Typography

A few of the typographical specs used by the DocBook XSL stylesheets can be changed with individual parameters on the command line. Because there are so many possible specs, however, most are contained in XSL attribute-set elements that bundle together many specs. Changing such specs requires a customization layer.

The following is an example of several typography changes using parameters:

xsltproc  --output myfile.fo  \
  --stringparam  body.font.family  Helvetica \
  --stringparam  body.font.master  11 \
  --stringparam  title.font.family  "Times Roman" \
  --stringparam  footnote.font.size 9 \
 fo/docbook.xsl  myfile.xml

Body and title font families

To change the font family for the body text, use the body.font.family parameter. The default value is serif, which most FO processors render as Times Roman. Although you can specify any font name in the parameter, there is no guarantee that the XSL-FO processor can produce that font. You need to consult the documentation of the current version of the processor to see what fonts it supports. As installed, FOP supports only Times Roman, Helvetica, and Courier. These are the fonts supported by the Adobe PDF files. To configure a new font into your FO processor, see the section “Adding a font”.

The font used for the title page and chapter and section titles can be changed with the title.font.family parameter. It is set to sans-serif by default, which maps to Helvetica in most FO processors.

For elements such as literal and programlisting that require a monospace font, the monospace.font.family parameter provides the font family name. By default it is monospace, which maps to Courier in most FO processors.

Font sizes

To change the body font size, use the body.font.master parameter. That parameter is a pure number representing point size, but specified without units. That parameter is then used to compute the actual font size values relative to the master size. So you need not set the body.font.size parameter, because it is computed from the body.font.master value.

You can also change the footnote font size using the footnote.font.size parameter. By default, the footnote size is 80% of the size of the body master size. You could set it to 8pt for example.

The title font sizes cannot be set with parameter values, and must be set using a customization file. See the section “Title fonts and sizes”.

Using renderas to style section titles

The DocBook DTD defines a strict hierarchy of section elements. Unlike HTML, you cannot put a level 3 heading directly under a level 1 heading. However, sometimes the content does not fit well into this strict hierarchy when being formatted. For example, you may have a level 1 section that has a great many short level 2 sections. When formatted, the level 2 section titles may appear too large relative to their small section content. If you were writing in HTML, you might just break the hierarchy and resort to h3 titles to reduce their size.

The creators of DocBook recognized this problem, and provided a solution in the renderas (“render as”) attribute. Its value can be sect1, sect2, etc. You can use the renderas attribute to tell the stylesheet to render a particular section title as if it were a different section level.

For example:

<sect1>
  <title>Options</title>
  <para>This section describes a lot of options</para>
  <sect2 renderas="sect3">
    <title>The A option</title
    ...
  

The section level 2 element has a renderas="sect3" attribute. The stylesheet will then format the title “The A option” in the type size and style of a level 3 section. If you have several such sect2 sections, you have to add the attribute to each to keep the headings consistent. The attribute has no other effect on how the section in handled. It is still numbered as a level 2 section, and it appears as a level 2 section in the table of contents.