• DevCenter
• Projects
• Inserting shortdesc below child topic links

Inserting <shortdesc> below child topic links

Background

We use DITA source to generate WebWorks Help output in ePublisher Express 2011.3 for certain deliverables. We have other deliverables that use DITA source but we generate Eclipse Help output. We like how Eclipse Help displays the <shortdesc> element on the line directly below the links to child topics. See ietools-79_eclipse_help_comparison.png.

Requirement

We want to mimic this feature of Eclipse Help in the WebWorks Help output. Using the attached dita files, we get by default this output IETOOLS-79-current-wwhoutput.png. We want something like this output instead IETOOLS-79-preferred-wwhoutput.png.

Questions

• What WebWorks xsl files should be modified to produce the preferred output?

We have experience in customizing xsl. We understand that the solution would involve modifying the preprocessing xsl files that WebWorks uses before content is assembled into xhtml.

• In the DITA-OT, this processing happens in these files:

  • xsl\xsl\preprocess\maplinkImpl.xsl

  • xsl\preprocess\mappullImpl.xsl

  • xsl\preprocess\topicpullImpl.xsl

  • xsl\xslhtml\rel-links.xsl

DITA source

Sample dita files for a project that uses <shortdesc>.

test-IETOOLS-79.ditamap

<?xml version="1.0"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd" [
]>
<map>
        <topicref href="test-IETOOLS-79.dita" type="concept" format="dita">
                <topicref href="test-IETOOLS-79-child-concept.dita" type="concept" format="dita"></topicref>
                <topicref href="test-IETOOLS-79-child-reference.dita" type="reference" format="dita"></topicref>
        </topicref>
</map>

test-IETOOLS-79.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" [
]>
<concept id="testietools79">
        <title>Test IETOOLS 79</title>
        <shortdesc>This short description is used for the parent topic in the map.</shortdesc>
        <conbody>
                <p>This is the parent topic in the map.</p>
        </conbody>
</concept>

test-IETOOLS-79-child-concept.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" [
]>
<concept id="testIETOOLS79childconcept">
        <title>Test IETOOLS 79 Child Concept</title>
<shortdesc>This short description is used for the child <i>concept</i> topic in the map.</shortdesc>
<conbody>
        <p>This is a child concept topic in the map.</p>
</conbody>
</concept>

test-IETOOLS-79-child-reference.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" [
]>
<reference id="testietools79childreference">
        <title>Test IETOOLS 79 Child Reference</title>
<shortdesc>This short description is used for the child <i>reference</i> topic in the map.</shortdesc>
<refbody>
        <section>
                <title>First Section</title>
                <p>This is a child reference topic in the map.</p>
        </section>
</refbody>
</reference>

Update (8/29/12)

I attached an implementation of this item here. It includes an override for extracting the summary text from a WIF marker and emitting a paragraph. To style the summary, add class description for "short_description" to webworks.css. The XSL override to content.xsl occurs at the bottom of the ParagraphNormal XSL call template. I've included it inline here:

  <!-- Begin: HACK WEBWORKS -->
  <!--                      -->
  <xsl:if test="$ParamParagraph/@stylename = 'Child Topic' or $ParamParagraph/@stylename = 'Parent Topic'">
    <xsl:variable name="VarShortDescMarker" select="$ParamParagraph/descendant::wwdoc:Marker[@name = 'Child Link Description' or @name = 'Parent Link Description'][1]" /> 

    <xsl:if test="count($VarShortDescMarker) = 1">
      <html:div class="short_description">
        <xsl:for-each select="$VarShortDescMarker/wwdoc:TextRun">
          <xsl:for-each select="wwdoc:Text">
            <xsl:value-of select="@value" />
          </xsl:for-each>
        </xsl:for-each>
      </html:div>
    </xsl:if>
  </xsl:if>
  <!-- End: HACK WEBWORKS -->
  <!--                    -->

Update (8/31/12)

This solution works beautifully. Thank you, Jesse. If anyone implements this, make sure you merge Targets\WebWorks Help\Transforms\content.xsl (if it exists) with Formats\WebWorks Help\Transforms\content.xsl to avoid the Target contents.xsl from overriding the Formats contents.xsl Leave the value of the Marker Style for Child Link Description and Parent Link Description as Ignore.

Tip! (11/16/12)

I wanted to do so something similar, but instead of emitting the paragraph below the related link, I wanted the text to be in the box that appears when one hovers over the related link. After spending several hours attempting this customization, which does work, I realized I didn't need to do any of it. All I needed to do was change the behavior for the 'Child Link Description' and 'Parent Link Description' marker types to "Link Title." This gives me exactly what I want, and no changes necessary to content.xsl or webworks.css.