Chapter 27. Q and A sets

Table of Contents

Q and A labeling
Q and A formatting
Q and A list of questions
Hiding the answers
Chunking Q and A

The Question and Answer feature of DocBook is often used to generate Frequently Asked Question (FAQ) documents. It consists of a set of qandaentry elements contained in a qandaset. The set can be further subdivided with qandadiv containers. The following short example shows how to create a Q&A in your document.

<qandaset>
  <title>Frequently Asked Questions (FAQ)</title>
  <qandadiv>
    <title>Questions about Networking</title>
    <qandaentry>
      <question>
        <para>How do I get an IP address?</para>
      </question>
      <answer>
        <para>Ask your system administrator.</para>
      </answer>
    </qandaentry>
    <qandaentry>
      ...
    </qandaentry>
    ...
  </qandadiv>
</qandaset>

The stylesheets let you control how the questions and answers are labeled, and how they are formatted.

Q and A labeling

By default, the questions in a qandaset are numbered, and the number will be prefixed with the chapter or section number:

1.1 First question in chapter 1.
    First answer.
1.2 Second question in chapter 1.
    Second answer.
...
2.1 First question in chapter 2.
    This answer.
2.2 Second question in chapter 2.
    That answer.

This behavior comes from the default values of the qanda.defaultlabel parameter, which is set to number by default, and the qanda.inherit.numeration parameter, which is set to 1 by default. Here inherit means the label inherits the chapter or section number as its prefix.

If you would rather have them all labeled with letters, then set the qanda.defaultlabel parameter to qanda. The results look like the following:

Q:  First question in chapter 1.
A:  First answer.
Q:  Second question in chapter 1.
A:  Second answer.

For other languages, it will use appropriate labels defined in the gentext files. You can also set the qanda.defaultlabel parameter to the literal none to get no labels at all.

If you want to number your questions without the chapter or section number prefix, then set the qanda.inherit.numeration parameter to zero. Then every chapter's questions will start over with numbering. The results look like this:

1.  First question in chapter 1.
    First answer.
2.  Second question in chapter 1.
    Second answer.
...
1.  First question in chapter 2.
    This answer.
2.  Second question in chapter 2.
    That answer.

If you want to override the label style for a particular qandaset element in your document, then add a defaultlabel attribute to that qandaset in your document. You can set it to any of the allowed values, which are number, qanda, or none. This attribute will override the global qanda.defaultlabel for that qandaset only. The following example shows how it is used:

<qandaset defaultlabel="qanda">
  <title>Frequently Asked Questions (FAQ)</title>
  ...
</qandaset>

You can also control the label on any or all individual questions or answers by including a label element in each question or answer element. For example:

<qandaentry>
  <question>
    <label>Important Question:</label>
    <para>What is the meaning of life?</para>
  </question>
  <answer>
    <label>Typical Answer:</label>
    <para>No one knows!</para>
  </answer>
</qandaentry>

The label element overrides any of the generated labels. The indent will be automatically adjusted to accommodate the label width.

If you want to do further customization of the labeling of QandA sets, then you'll probably need to customize a template. You should copy to your customization layer the template that starts with the following line, from common/labels.xsl :

<xsl:template match="question|answer" mode="label.markup">
...

The template generates whatever label is applied to questions and answers. By customizing it, you can alter how the label options are handled, or you can simplify it by removing most of the options and just enacting what your style is.

For example, if you wanted to number all of the questions throughout the document with Q1, Q2, Q3, etc., using consecutive numbers that don't restart at all, you could add this template to your customization layer to override the default template:

<xsl:template match="question" mode="label.markup">
    <xsl:text>Q</xsl:text>
    <xsl:number level="any" count="qandaentry" format="1"/>
</xsl:template>

The level="any" attribute causes the xsl:number counter to count all qandaentry elements at any level with one sequence of numbers.