The document discusses implementing flagging and change tracking in DITA documents. It provides an overview of filtering and describes how to flag content based on attributes like product, audience and platform using a DITAVAL file. It also discusses using revision properties to flag changes and provides XML code samples.

1. Implementing Flagging and Change Tracking Aliza Merzel, Suite Solutions

2. Who are we? Our Mission To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes. Qualitative Advantage Content Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets. Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.

3. Clients and Partners Private and Confidential Suite Solutions©2009

4. Implementing Flagging and Change Tracking Overview of Filtering Implementing Flagging Implementing Track Changing

5. How to provide the ditaval file Ant parameter: dita.input.valfile <param name=“dita.input.valfile” value=“path to ditaval”/> Java command line: /filter: &quot;%JAVA_HOME%\bin\java&quot; -jar lib/dost.jar /id:&quot;%1&quot; /tempdir:&quot;%1/temp&quot; /i:&quot;%1/%2&quot; /outdir:&quot;%3&quot; /draft:&quot;no&quot; /filter:&quot;%1\context.ditaval&quot; /copycss:yes /transtype:&quot;%4&quot;

6. Filtering Output Using Ditaval Allows you to publish a subset of the documentation. Filtering (conditional processing) based on conditional attributes: product, audience, platform, otherprops The props attribute may be specialized to create additional conditional attributes Use ditaval XML file to set criteria By default, all topics and elements are included Ditaval file specifies which elements to exclude “ OR” operation within each attribute “AND” operation between attributes

7. Filtering Output Using Ditaval Example: <step product=“prodA prodB”> * As long as either is NOT excluded, the element remains in place Example: <step product=“prodA prodB” audience=“admin”> * If “admin” is excluded then the whole element is removed <?xml version='1.0' encoding='utf-8'?> <val> <prop att=' product ' val=‘ prodA ' action=' include ' /> <prop att=' product ' val=‘ prodB ' action=' exclude ' /> <prop att=' audience ' val=' admin ' action=' include ' /> </val>

8. Implementing Change Tracking and Flagging Overview of Filtering Implementing Flagging Implementng Track Changing

9. Flagging DITA allows you to flag different part of the document based on product, audience, platform, otherprops, rev, and specialized attributes from props

10. Sample DITAVAL file for Flagging < val > < style-conflict foreground-conflict-color = &quot; red &quot; background-conflict-color = &quot; lightgreen &quot; /> < prop att = ' platform ' val = ' xp ' action = &quot; flag &quot; color = &quot; purple &quot; backcolor = &quot; #CCFFFF &quot; style = &quot; underline &quot; > < startflag imageref = &quot; delta.gif &quot; /> < endflag imageref = &quot; deltaend.gif &quot; /> </ prop > < prop att = ' audience ' val = ' admin ' action = &quot; flag &quot; color = &quot; blue &quot; style = &quot; italics &quot; > < startflag >< alt-text > admin start </ alt-text ></ startflag > < endflag >< alt-text > admin end </ alt-text ></ endflag > </ prop > < revprop val = ' 1 ' action = &quot; flag &quot; color = &quot; green &quot; changebar = &quot; color:red;style:dotted;width:3pt;offset:5pt &quot; > < startflag >< alt-text > Start change </ alt-text > </ startflag > < endflag >< alt-text > End change </ alt-text ></ endflag > </ revprop > < revprop val = ' 2 ' action = &quot; flag &quot; color = &quot; green &quot; changebar = &quot; placement:end; color:blue; style:solid;width:2pt;offset:2pt &quot; / > </ val >

11. <prop> For flagging content based on product, audience, platform, otherprops attributes (and props attribute may be specialized to create additional conditional attributes) att Name of attribute to flag on val Value of attribute to flag on action exclude – remove content include – keep content flag - to flag elements passthrough – to preserve the attribute through subsequent processing color Text color style One of the following: Underline double-underline (treated as underline) italics overline bold line-through backcolor Background color

12. <revprop> For flagging based on rev attribute. You can not filter on the rev attribute. att Not included for revprop, since this is only used for the rev attribute val Value of attribute to flag on action flag - to flag elements passthrough – to preserve the attribute through subsequent processing color Text color style One of the following: Underline double-underline (treated as underline) italics overline bold line-through backcolor Background color

13. <revprop> changebar color offset placement= start | end | left | right | inside | outside | alternate style = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset width example: changebar=&quot;style:dotted;width:3pt;offset:5pt&quot;

14. <style-conflict> This declares color and background-color to be used when one or more flagging methods collide on a single content element. Change bars and style attributes will be be listed for all possible attributes foreground-conflict-color = color for confilict areas background-conflict-color = background color for confilict areas These attributes are only used when an element has conflicting attributes. < cmd > Move the < ph platform = &quot; xp &quot; audience = &quot; admin &quot; > car </ ph > onto the driveway. </ cmd >

15. Nested flagging: When an element is flagged with one color and an ancestor is flagged with a different color, the most deeply nested color will be applied. < section rev = &quot; 1 &quot; > < title > sectiontitle </ title > < p > some content </ p > < note platform = &quot; xp &quot; > here is a note </ note > < p > some more content </ p > < simpletable audience = &quot; admin &quot; > < strow > < stentry > st 1a </ stentry > < stentry > st 1b </ stentry > </ strow > < strow > < stentry > st 2a </ stentry > < stentry > st 2b </ stentry > </ strow > </ simpletable > </ section >

16. Nested flagging Example

17. You can also add an image or text before/after the flagged content < startflag imageref = &quot; delta.gif &quot; ></ startflag > < endflag imageref = &quot; deltaend.gif &quot; ></ endflag > To supply text < startflag >< alt-text > admin start </ alt-text ></ startflag > < endflag > < alt-text > admin end </ alt-text ></ endflag > You are responsible for providing all images. In HTML the images will be treated as relative to the ditamap. In PDF the images will be relative to the topic.fo file in the output directory

18. XSL Code for Flagging in HTML output Code is located in: DITA-OT1.5.1\xsl\xslhtml\flag.xsl For each element there are multiple lines of code. These lines of code are included in each element. If you customized code you will need to include these lines to maintain the flagging. 1. Add color/style attributes < xsl:call-template name = &quot; gen-style &quot; > < xsl:with-param name = &quot; conflictexist &quot; select = &quot; $conflictexist &quot; / > < xsl:with-param name = &quot; flagrules &quot; select = &quot; $flagrules &quot; /> </ xsl:call-template > 2. Add start image and/or alt-text < xsl:call-template name = &quot; start-flagit &quot; > < xsl:with-param name = &quot; flagrules &quot; select = &quot; $flagrules &quot; /> </ xsl:call-template >

19. HTML output 3. Output the content of the block < xsl:call-template name = &quot; revblock &quot; > < xsl:with-param name = &quot; flagrules &quot; select = &quot; $flagrules &quot; /> </ xsl:call-template > 4. Output the content of inline element < xsl:call-template name = &quot; revtext &quot; > < xsl:with-param name = &quot; flagrules &quot; select = &quot; $flagrules &quot; /> </ xsl:call-template > 5. Output end images and/or alt-text < xsl:call-template name = &quot; end-flagit &quot; > < xsl:with-param name = &quot; flagrules &quot; select = &quot; $flagrules &quot; /> </ xsl:call-template >

20. XSL Code for Flagging in PDF output It is slightly easier. The files are preprocessed to add the flagging information to the temp files. 1. <suitesol:flagging-inside> Defines the style information that should be applied to the parent element When creating custom templates, this element must be matched before any of the child elements. < xsl:apply-templates select = &quot; suitesol:flagging-inside &quot; /> And later < xsl:apply-templates select = &quot; node()[ not(name=’ suitesol:flagging-inside ’)] &quot; /> 2. <suitesol:flagging-outside> Defines a block level element that should be created to provide flagging styles. Will become an <fo:block> around the child. Used for: simpletable, dl, note (and all elements that are specialized from them)

21. XSL Code for Flagging in PDF output 3. <suitesol:changebar-start> Defines the starting change bar along with style information Will become <fo:change-bar-begin> 4. <suitesol:changebar-end> Defines where the changebar ends. Will become <fo:change-bar-end>

22. FO tags for change-bars < fo:change-bar-begin > - signifies start of change bar < fo:change-bar-end > - signifies end of change bar Placement in relation to content/page change-bar -placement start end left right change-bar-class Unique identifier, must have a <fo:change-bar-end> with same unique identifier change-bar-color Color of bar change-bar-offset Offset for the content inside outside Alternate

23. FO tags for change-bars Style of the bar: change-bar -style none hidden dotted dashed solid double groove ridge inset outset change-bar-width Width of bar

24. Implementing Change Tracking and Flagging Overview of Filtering Implementing Flagging Implementing Track Changing

25. Track changing Generally use this to create change-bars in pdf output. In any templates creating change bars, one would generally test for draft outputas whether or not to show change-bars. This can be done by setting “args.draft” or “/draft:” Use a combination of rev attribute and status. <section rev=”1” status=”new”> <section rev=”1” status=”deleted”> <section rev=”1” status=”changed”>

26. Track changing To use the flagging code as shown earlier you will need to combine those into the rev attribute as the flagging code tests only for rev. For example: <section rev=”1n”> <section rev=”1d”> <section rev=”1c”> A rev attribute can have more than one value in it, separated by spaces: <section rev=”1n 2c”> Meaning that this section was new in rev 1, changed in rev 2.

27. Track changing in Xmetal XMetal uses processing instruction added to the text to mark added or deleted content <? xm-deletion_mark author=&quot;Production&quot; time=&quot;20081007T101245-0800&quot; data=&quot;prerequisite.&quot; ?> <? xm-insertion_mark_start author=&quot;Production&quot; time=&quot;20081007T101246-0800&quot; ?> <? xm-insertion_mark_end ?> XSL-FO templates: < xsl:template match = &quot; processing-instruction('xm-insertion_mark_start') &quot; priority = &quot; 99 &quot; > < xsl:template match = &quot; processing-instruction('xm-insertion_mark_end') &quot; > < xsl:template match = &quot; processing-instruction('xm-deletion_mark') &quot; >

28. Track changing in Arbortext Arbortext uses special tags wrapped around content to mark changes, additions, deletions. < atict:add user = &quot; amerzel &quot; time = &quot; 1267736691 &quot; > < atict:del user = &quot; amerzel &quot; time = &quot; 1267736691 &quot; > XSL-FO templates: < xsl:template match = &quot; atict:add &quot; priority = &quot; 99 &quot; > < xsl:template match = &quot; atict:del &quot; priority = &quot; 99 &quot; > For more info: http://www.arbortext.com/namespace/atict/change-tracking-markup-spec.html

29. Implementing Flagging and Change Tracking Overview of Filtering Implementing Flagging Implementng Track Changing

30. Ditaval Utility Developed by Suite Solutions: available for free Displays all conditional attribute values used in any DITA files referenced by the chosen map Displays all topics in which a particular conditional value is used Choose attribute values to include using checkboxes Generate ditaval file based on chosen criteria Can be downloaded from: http://www.suite-sol.com/pages/resources/resources_ditaval_utility.html

32. End of Implementing Flagging and Change Tracking Be in touch! Aliza Merzel [email_address] Let us know how we can help you further… One-on-one support and training CMS