Topic Specialization Step 4-4: Implement Specialization-Specific XSLT Processing

For the FAQ question, the new processing is relatively easy: just generate "Q. " before the title content:
<xsl:template match="*[contains(@class, ' faq-question/faq-question-statement ')]">
  <xsl:param name="headinglevel">
          <xsl:when test="count(ancestor::*[contains(@class,' topic/topic ')]) > 6">6</xsl:when>
          <xsl:otherwise><xsl:value-of select="count(ancestor::*[contains(@class,' topic/topic ')])"/></xsl:otherwise>
  <xsl:element name="h{$headinglevel}">
    <xsl:attribute name="class">topictitle<xsl:value-of select="$headinglevel"/></xsl:attribute>
    <xsl:call-template name="commonattributes"/>
    <div class="faq-question-statement" style="background-color: #FFFFA0">
    <span class="faq-question-statement-q">Q. </span>
  <xsl:value-of select="$newline"/>  <xsl:param name="headinglevel">

The <span> with the @class value isn't strictly necessary but it provides a handy hook for using CSS styles to further control the presentation of the question.

For the question answer, the solution is not quite so obvious. In order to produce the answer with the initial "A. " text such that it is immediately followed by the text of the first paragraph requires processing the first child paragraph of <faq-answer> specially and then processing the rest of the content. However, the base template provides processing for elements that would be presented before the first paragraph, such as the abstract and the short description.

This presents a dilemma and indicates that we haven't fully thought through the markup design or the presentation design. Clearly we were thinking of questions as just being a title with the question and answers as paragraphs. But DITA topics can be more sophisticated. The upshot is that we have to account for these elements in some way.

One way would be to simply eliminate them from the allowed content of <faq-question>. That would certainly simplify the problem but might make our FAQ question topics too simple. For example, there might be systems that depend on short descriptions or abstracts for some cool functionality.

The better thing would be to provide FAQ-specific processing for these elements that ensures the correct presentation. In addition, there might be ways to integrate these elements with the FAQ to make them more useful.

In particular, it probably makes sense to refine the model for <faq-question> to require<shortdesc> to be the first paragraph of the answer, with the body as the rest of the answer. This would enable, for example, an FAQ presentation that shows just the question and short description with the topic body hidden until requested.

This point that we've come to is one of the reasons that it's so important to test new markup designs in the context of realistic processing as well as in the context of authoring. As you design new markup you should expect to go through several iterations of design/implement/rework. One advantage of using DITA as a base is that it makes it fairly inexpensive to do this iterative development because you can quickly extend the base functionality rather than having to first implement a large base of processing just to get to a point where you can see some output.

At this point, we put our XSLT work on hold for a moment and go back to the DTD declarations to refine the markup rules.