Related Links (DITA)

Download example implementation

This article details a strategy for emitting a title on related links tables in DITA. This strategy uses an attribute called markopen in the default.wwconfig file to specify the creation of an empty paragraph at the beginning of each linkpool in a related-links element. The attached project provides an example (Related Links.zip) of this implementation.

markopen and default.wwconfig

Following is the snippet that needs to be added to default.wwconfig:

  <!-- Begin Related Links Customization -->
  <!--                                   -->
  <Style match="//*[contains(@class, ' topic/linkpool ')]">
   <xsl:if test="contains(parent::*[1]/@class, ' topic/related-links ')">
    <xsl:variable name="VarLinkType">
     <xsl:choose>
      <xsl:when test="count(./*[contains(@class, ' topic/link ')][1]) = 1">
       <xsl:variable name="VarTypeAttribute" select="./*[contains(@class, ' topic/link ')][1]/@type" />
       <xsl:value-of select="translate(substring($VarTypeAttribute, 1, 1), 'trc', 'TRC')" />
       <xsl:value-of select="substring($VarTypeAttribute, 2)" />
      </xsl:when>
 
      <xsl:otherwise>
       <xsl:text>Link</xsl:text>
      </xsl:otherwise>
     </xsl:choose>
    </xsl:variable>
    
    <wwditaconfig:Head markopen="Related {$VarLinkType}s" />
   </xsl:if>
  </Style>
  <!-- End Related Links Customization -->
  <!--                                 -->

This snippet matches linkpool elements, verifies that it occurs within a related-links element, then synthesizes a name based on the type of link elements within the linkpool. It then uses this name in the markopen attribute of the wwditaconfig:Head element. This attribute indicates to the ePublisher WIF creation processing to create an empty paragraph with the given name, at the location of the linkpool.

Adding text and formatting

Once this change is implemented in default.wwconfig, scanning the *.ditamap will result in new Paragraph styles such as Related Concepts, Related Tasks, and so on. Using the Bullet Property panel in the ePublisher Style Designer, it is possible to specify the "numbering" text. In the field labeled Text, a user may enter: Related Concepts, for example. Formatting the paragraph is possible using the other ePublisher Property and Option panels.

Joining linkpools which are the same kind

One problem I ran into immediately was a related-links elements which had multiple linkpools of the same type. This resulted in several instances of the title Related Concepts on a given page. This problem may ultimately be solved in the XSL, but for this implementation, I opted to solve it using CSS selectors. Following is an addition to webworks.css which aims to suppress mutlple instances of the Related * title.

/* Related links customization */
/*                             */
div.Parent_Topic + div.Related_Concepts,  div.Parent_Topic + div.Related_Tasks, div.Parent_Topic + div.Related_References {
    display: none;
}

This solution may be ultimately inadequate, but I would like to see instances where this solution breaks down to better understand the limitations. Please share if you run into problems with this strategy.