variablelist element is used to present a sequence of terms and their descriptions. Generally, the terms appear on the left, and the descriptions are indented relative to the terms. The amount of indent is the key feature when formatting these lists. The handling of multiple
term elements and the methods for print and HTML formatting are described in the next sections.
varlistentry element can contain more than one
term element. That's useful when several terms have the same descriptive paragraph. There are two presentation styles to choose from: comma separated terms and stacked terms.
If you want multiple
term elements to be set inline and separated by commas, then do nothing because that is the default. The comma and space are actually defined in a stylesheet parameter named
variablelist.term.separator. You could customize that parameter if you want to use some other punctuation instead.
If you instead want multiple
term elements to stack vertically, then set the stylesheet parameter
variablelist.term.break.after to 1 instead of its default value of zero. When set to 1, the stylesheet adds a line break after each
term. Unless you want the commas to still show, you should also set the
variablelist.term.separator to blank. These parameters apply to both print and HTML output.
Variable lists present a challenge for formatting because the
term hanging out to the left can be of any width. There are several methods for setting the term width, which is effectively the indent width of the
listitem paragraphs. Here is the list of methods, with highest priority first.
variablelist.as.blocks stylesheet parameter set to nonzero.
dbfo list-presentation="blocks" processing instruction in the list.
dbfo term-width processing instruction in the list.
termlength attribute in the
The widths of the
term elements themselves.
The first two methods put each
varlistentry into a pair of
fo:blocks with the term block preceding the list item block. This has the effect of stacking the term above the paragraph, permitting the term to be of any length. The paragraph is indented a small fixed amount. The use of the
variablelist.as.blocks parameter turns this behavior on globally for all
variablelists. The processing instruction turns it
on for one list. The following is an example.
<variablelist> <?dbfo list-presentation="blocks"?> <varlistentry> <term>Left button</term> <listitem><para>Blah blah</para></listitem> </varlistentry> ... </variablelist>
variablelist.as.blocks parameter is a global setting, you can override it for
individual lists with a
list-presentation="list"?> processing instruction. Then
you can also specify a term width.
If the list is not formatted as blocks, then the list is formatted using a
fo:list-block, which puts the list item text side-by-side with the term. Then the term width can be set by either a processing instruction or an attribute value. Following is an example of that processing instruction.
<variablelist> <?dbfo term-width=".75in"?> <varlistentry> <term>Left button</term> <listitem><para>Blah blah</para></listitem> </varlistentry> ... </variablelist>
term-width value can be a plain number also, in which case it is assumed to be in
em units. The
termlength attribute of
variablelist can be set in a similar manner if the processing instruction is not used.
If you do not set a term width with any of the above methods, then the XSL-FO stylesheet counts the characters in all the
term elements and uses the largest, up to some maximum value. Starting with version 1.62 of the stylesheets, the maximum indent width is controlled by the
variablelist.max.termlength stylesheet parameter. The default value is
24, roughly 24 character widths. Enter a different integer to
change the maximum indent. Any terms that are longer will line wrap.
If this default behavior does not produce satisfactory results in a
given list, then adjust the indent with one of the methods described
Variable lists present a challenge for formatting in HTML because the standard
DL list in HTML does not let set the indent width. The DocBook XSL stylesheets support a set of processing instructions (PIs) to enable you to control how a given
variablelist is formatted in HTML. For HTML output, the list can be put into a two-column HTML
TABLE element to control formatting. Following is an annotated example:
<variablelist> <?dbhtml list-presentation="table"?> <?dbhtml term-width="15%" list-width="85%" ?> <?dbhtml term-presentation="bold" ?> <?dbhtml term-separator=":" ?> <?dbhtml table-summary="mouse buttons described" ?> <varlistentry> <term>Left button</term> <listitem><para>Blah blah</para></listitem> </varlistentry> ... </variablelist>
Put the processing instructions somewhere inside the
This PI enables the formatting PIs to work. It tells the stylesheet to use an HTML
This PI sets the table left column width (
This PI lets you change the font style for all the terms in a
This PI lets you add some punctuation or any other text after every term in the list. In this example, each term will be followed by a colon.
You can supply a text string that is put into the HTML table's
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises