variablelist options

variablelist options
	Chapter 21. Lists

The 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.

Multiple term elements

A 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 list formatting in print

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 variablelist element.
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>

Although the variablelist.as.blocks parameter is a global setting, you can override it for individual lists with a <?dbfo 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>

The 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 above.

Variable list formatting in HTML

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 `variablelist` element. You can put them all into one PI, or make separate PIs for each.
	This PI enables the formatting PIs to work. It tells the stylesheet to use an HTML `TABLE` instead of a `DL` list for this variable list. If you want to always output tables for variablelists, then you can instead set the stylesheet parameter `variablelist.as.table` to 1. Then you can omit this PI, except when you want to force a particular list to use `DL`, in which case you use `<?dbhtml list-presentation="list" ?>`.
	This PI sets the table left column width (`term-width`) and the overall table width (`list-width`). Use percentages for the values. If you omit both, you get the default HTML table formatting.
	This PI lets you change the font style for all the terms in a `variablelist`. The choices are `bold`, `italic`, `bold-italic`. In general, such formats should be applied with a CSS stylesheet, but this can be useful for a list that needs different formatting.
	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 `summary` attribute.


orderedlist options		simplelist options