Q and A cross references

Cross referencing to Q and A elements is similar to other cross references. You put an id (or xml:id in DocBook 5) attribute on the element you want to reference, and then you use xref, link, or olink to cross reference to it. When referencing a specific question, reference the id on the qandaentry rather than the question element.

The generated text for a qandaset or qandadiv comes from the title element, so be sure your elements have a title (it is optional on those elements).

The generated text for a qandaentry depends on your parameter settings. The default behavior is to output a Q: and the question number. The following are some examples:

ParametersExample xref
<xsl:param name="qanda.defaultlabel">number</xsl:param>
<xsl:param name="qanda.inherit.numeration" select="1"/>
<xsl:param name="qandadiv.autolabel" select="1"/>
Q: 2.1.3

where the question has a number label of 2.1.2, with 2.1 from the division number and .3 from the third question in that division.

<xsl:param name="qanda.defaultlabel">number</xsl:param>
<xsl:param name="qandadiv.autolabel" select="0"/>
Q: 3

for the third question in any division.

<xsl:param name="qanda.defaultlabel">qanda</xsl:param>

In the second two examples, the information provided in the cross reference text is not particularly helpful. The links will work, but they do not provide the reader with much context. It is particularly bad when numbering is not used for questions, as in the last example.

You might be wondering why the stylesheet does not use the question text for the cross reference? A question element can be long and complex, because its schema content model permits tables, figures, lists, etc. Copying such text as cross reference text would be very confusing to the reader, so the stylesheet does not do that by default.

But if you can write your questions with cross references in mind, you can create a customization that could work with questions. The following customization uses the first para element for the cross reference text. Just keep the first para in all your question elements short.

<xsl:template match="question" mode="object.xref.markup">
  <xsl:call-template name="gentext">
    <xsl:with-param name="key" select="'question'"/>
  <xsl:text> </xsl:text>
  <xsl:call-template name="gentext.startquote"/>
  <xsl:apply-templates select="para[1]/node()"/>
  <xsl:call-template name="gentext.endquote"/>

Although your xref is referencing a qandaentry, the stylesheet generates the cross reference text by processing its question child element in mode="object.xref.markup". Normally that mode uses a gentext template for the current locale and fills in the question number.

In this customization, it instead outputs the Q: label for the current locale, and puts the text of the first para element in quotes. The select="para[1]/node()" selects the content of the para element, not the para itself, which would generate a block instead of an inline. If you want to change the Q: part, then customize the gentext template for question, as described in the section “Generated text”.

Another method to reference a question that does not require a stylesheet customization is to use an endterm attribute as described in the section “Use another element's text for an xref”.