Customize your transformation scenario to show redlining in the table of contents

When using redlining, topics that were added to, modified in, or removed from a map can now be highlighted in the table of contents.

The DITA CMS Redline feature uses the DeltaXML DITA Compare product to highlight changes between two DITA files. The output of this product is a DITA document that uses therevandstatusattributes to identify the changes in the documentation. For example, the following code shows the output of a comparison between two DITA maps:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ixiamap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN"                  
        "../../system/dtd/ixia/IxiaMap.dtd">
<ixiamap id="mymap" xml:lang="en_US">    
   <title>Product A Installation Guide</title>
   <enhancedtopicmeta/>    
   <topicref href="topic1.xml" rev="deltaxml-changed" status="changed"/>    
   <topicref href="topic2.xml" rev="deltaxml-add" status="new"/>    
   <topicref href="topic3.xml" rev="deltaxml-delete" status="deleted"/>    
   <topicref href="topic4.xml" rev="deltaxml-unchanged" status="unchanged"/> 
</ixiamap>
Note: For more information about DeltaXML DITA Compare, see the following URL: http://docs.deltaxml.com/dita/current/docs/user-guide.html#dita-markup

If you want your output format to display the revision changes in the table of contents, you need to customize your transformation scenarios.

This section shows how to customize the org.dita.pdf2 plug-in in the DITA Open Toolkit (version 1.8) to display revision changes. You can use this example as a template to customize your own scenarios.

Important: The Redline ditaval file provided by the DITA CMS (i.e., redline.ditaval) does not apply to the styling of the table of contents.

To enable redlining in your TOC, you copy the following two files to the com.ixiasoft.pdf.review plug-in and then modify them:

  • commons.xsl
  • toc.xsl

This procedure is described below.

Important: The procedure below was tested on DITA OT 1.6.2.
  1. Copy the commons.xsl and toc.xsl files from the following directory:
    %OutputGenDir%\data\%OT_Dir%\plugins\org.dita.pdf2\xsl\fo
    To the following directory:
    %OutputGenDir%\data\%OT_Dir%\plugins\com.ixiasoft.pdf.review\cfg.map\fo\xsl

    This ensures that you do not modify the org.dita.pdf2 plug-in directly.

  2. Open the commons.xsl file with a text editor.
    Make sure to open the file that is located in the following directory:
    %OutputGenDir%\data\%OT_Dir%\plugins\com.ixiasoft.pdf.review\cfg.map\fo\xsl
  3. To add a variable that will contain the revision status created with the DeltaXML DITA Compare:
    1. Search for the following string in the commons.xml file:
      <xsl:template name="getNavTitle">
      For example:
      ...
      <xsl:template name="getNavTitle">
         ...
      </xsl:template>
    2. Just after the closing</xsl:template>statement, enter the following lines:
      <!-- REDLINE: NEW TEMPLATE -->
      <xsl:template name="getNavTitleWithRev">
         <xsl:call-template name="getNavTitle"/>
         <xsl:variable name="topicref" select="key('map-id', @id)"/>
         <!-- REDLINE: created a new variable "redlineStatus" to hold rev attribute created by deltaxml -->
         <xsl:variable name="redlineStatus" select="$topicref/@rev"/>
         <!-- REDLINE: adding the value of deltaxml attribute in this particular case -->
         <xsl:value-of select="$redlineStatus"/>	
      </xsl:template>
      <!-- REDLINE: FINISHED -->

      These lines declare a new template that will define a variable called redlineStatus, which contains the value of the@revattribute from the map file created by the DeltaXML compare feature.

  4. Save and close the commons.xsl file.
  5. Open the toc.xsl file with a text editor.
    Make sure to open the file that is located in the following directory:
    %OutputGenDir%\data\%OT_Dir%\plugins\com.ixiasoft.pdf.review\cfg.map\fo\xsl
    1. Search for the following string in the toc.xsl file:
      <xsl:if test="$topicLevel &lt; $tocMaximumLevel">
      For example:
      ...
      <xsl:if test="$topicLevel &lt; $tocMaximumLevel">
         <xsl:variable name="mapTopicref" select="key('map-id', @id)[1]"/>
         <xsl:choose>
    2. Just before the<xsl:choose>statement, enter the following lines:
      <!-- 
         REDLINE: added this section to get topic's navtitle plus deltaxml rev attribute 
         value. This will help determine that topic being processed falls in which one 
         of the three categories: 
            1) has topic been modified in authoring version of the map(deltaxml-changed)
            2) has topic been deleted in authoring version of the map(deltaxml-delete)
            3) has topic been added to authoring version of the map(deltaxml-add)
      -->
      <xsl:variable name="topicTitleWithStatus">
         <xsl:call-template name="getNavTitleWithRev"/>
       </xsl:variable>
      
      <xsl:variable name="tocColor">
         <xsl:choose >
            <xsl:when test=" matches($topicTitleWithStatus, 'deltaxml-changed') ">
               <xsl:value-of select="'#0000FF'"/> <!-- blue -->
            </xsl:when>
            <xsl:when test="matches($topicTitleWithStatus, 'deltaxml-delete')">
               <xsl:value-of select="'#DF0101'"/> <!-- mustard -->
            </xsl:when>
            <xsl:when test="matches($topicTitleWithStatus, 'deltaxml-add')"> 
               <xsl:value-of select="'#21610B'"/> <!-- green -->
            </xsl:when>
            <xsl:otherwise>
               <xsl:value-of select="'#000000'"/> <!-- black -->
            </xsl:otherwise>
         </xsl:choose>
      </xsl:variable>
      			
      <xsl:variable name="topicTitle">
         <xsl:value-of select="substring-before($topicTitleWithStatus, 'deltaxml')"/>
      </xsl:variable>

      These lines configure how the changes will be highlighted in the table of contents. Customize these lines as required for your deployment.

    3. Search for the following string, which is inside the<xsl:choose>statement, just a few lines below:
      <fo:inline xsl:use-attribute-sets="__toc__title">
      For example:
      ...
      <xsl:apply-templates select="$mapTopicref" mode="tocPrefix"/>
      <fo:inline xsl:use-attribute-sets="__toc__title">
         <xsl:call-template name="getNavTitle" />
      </fo:inline>
      <fo:inline xsl:use-attribute-sets="__toc__page-number">
      ...
    4. Comment out the code for this<fo:inline>statement.

      For example:

         ...
      <xsl:apply-templates select="$mapTopicref" mode="tocPrefix"/>
      <!-- Commenting out for the REDLINE feature -->
      <!-- <fo:inline xsl:use-attribute-sets="__toc__title">
         <xsl:call-template name="getNavTitle" />
      </fo:inline>  -->
      ...	
    5. Under the commented code, add the following lines:
      ...
      <!-- REDLINE: for adding color to toc-->
      <xsl:attribute name="color">
         <xsl:value-of select="$tocColor"/>
      </xsl:attribute>
      
      <!-- REDLINE: modified how topic title is generated. -->
      <xsl:value-of select="concat($topicTitle,' ')"/>
  6. Save and close the toc.xsl file.
  7. In the same directory, edit the custom.xsl file.
  8. Add the following two lines before the closing</xsl:stylesheet>element.
    <xsl:import href="toc.xsl"/>
    <xsl:import href="commons.xsl"/>
  9. In the %OutputGenDir%/data/%OT_Dir%/ directory, double-click startcmd.bat (Windows) or run startcmd.sh (Linux).
  10. At the command prompt, enter:
    ant -f integrator.xml
    The integration build runs and you should soon see BUILD SUCCESSFUL.
    Note:If a message similar to the following is displayed, you can safely ignore it:
    Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre6\lib\tools.jar
  11. Close the command window.
  12. Restart the Output Generator service.
The next time that you use redlining, changes made in the map will be highlighted in the table of contents.