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:choose>
          <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:choose>
  </xsl:param>
  <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:apply-templates/>
    </div>
  </xsl:element>
  <xsl:value-of select="$newline"/>  <xsl:param name="headinglevel">
</xsl:template>
    

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 answer, the solution is not quite so obvious. To render the answer such that the initial "A. " text is immediately followed by the first paragraph (with no break) 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 contain other elements, and we have to account for them somehow.

One way would be to simply eliminate those elements from the allowed content of <faq-question>. That would certainly simplify the problem, but it 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 them 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 is why it's so important to test new markup designs in the context of realistic processing and 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 is fairly inexpensive to do this iterative development. With DITA, you can quickly extend the base functionality without 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.