Table of Contents
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.
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.
DocBook XSL: The Complete Guide - 3rd Edition | PDF version available | Copyright © 2002-2005 Sagehill Enterprises |