Customization of the DocBook XSL Stylesheets for the TCC

This section contains parameter settings that affect the overall PDF page format. To make changes here, you need to understand a number of XSL-FO concepts such as regions, blocks and inlines, block and inline progression directions, and such. Dave Pawson's book XSL-FO is absolutely indispensable for this background information; see Section 2, “Skills you will need”.

First, we turn on double-sided formatting, which places the “outer” margin on the left of even pages and the right of odd pages, and the “inner” margin in the opposite positions.

<xsl:param name="double.sided">1</xsl:param>

The margins are defined next. For double-sided formatting, the default inner margin is 1.25" and the outer 0.75". To save paper, we set the inner margin to 1".

<xsl:param name="page.margin.outer">0.75in</xsl:param>
<xsl:param name="page.margin.inner">1in</xsl:param>

In the stock style, the xref element does not include a page number. We want internal cross-references to use the page number.

<xsl:param name="insert.xref.page.number">1</xsl:param>

The next parameter is a bit obscure. The stock style defaults to “draft mode”, which overlays each page with a user-supplied image named draft.png. We do not support draft mode, and would prefer not to see a bunch of messages about how it can't find draft.png.

<xsl:param name="draft.mode">no</xsl:param>

Because the current style has no running header, we reclaim most of the space allocated to the header, but leave 0.25" so that the FO processor won't complain about inadequate space for the (empty) content that goes there. The area occupied by the header is called the “region before”, and its size paramater is region.before.extent.

<xsl:param name="region.before.extent">0.25in</xsl:param>

The next few sections set up the vertical spacing used in page makeup. Each of these is an xsl:attribute-set that contain attributes that define the minimum, optimum, and maximum spacing before or after a given element.

The values we use here were determined by trying various values to see how they look. This is a trade-off: smaller spacing saves paper, and tends to put more on a page, reducing the number of cases where blocks of related content are divided across page breaks. On the other hand, larger spaces can make the document more readable.

First, the normal.para.spacing attribute set defines the spacing around paragraphs. The stock (minimum, optimal, maximum) spaces are (0.8em, 1em, 1.2em), but those are rather generous. To save paper we scrunch them down a bunch. (The “em” is the usual printer's measure—the point size of the font, so in a 12-point font, 0.5em is 6 points.)

<xsl:attribute-set name="normal.para.spacing">
  <xsl:attribute name="space-before.minimum">0.50em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">0.60em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">0.70em</xsl:attribute>
</xsl:attribute-set>

Next we set up the spacing for itemizedlist and similar elements. The list.block.spacing attribute set describes the space before and after the entire list. The default spacing is (0.8em, 1.0em, 1.2em) before and after.

<xsl:attribute-set name="list.block.spacing">
  <xsl:attribute name="space-before.minimum">0.70em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">0.75em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">0.80em</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.70em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">0.75em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">0.80em</xsl:attribute>
</xsl:attribute-set>

The list.item.spacing attribute set describes the space around individual items in the list. The default values are also (0.8em, 1.0em, 1.2em).

<xsl:attribute-set name="list.item.spacing">
  <xsl:attribute name="space-before.minimum">0.50em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">0.60em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">0.70em</xsl:attribute>
</xsl:attribute-set>

Finally, the verbatim.properties attribute set defines the vertical spacing around the various verbatim-type elements (programlisting, literallayout, and screen).

<xsl:attribute-set name="verbatim.properties">
  <xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">0.6em</xsl:attribute>

We add a very thin black border (0.1mm) around verbatim elements. This has the advantage of showing clearly when a verbatim element is broken across a page boundary: the side facing the break will have no border. The default border style is none, so we must set the style to solid.

  <xsl:attribute name="border-width">0.1mm</xsl:attribute>
  <xsl:attribute name="border-style">solid</xsl:attribute>

The padding attribute insures that the content does not actually touch the border.

  <xsl:attribute name="padding">1mm</xsl:attribute>
</xsl:attribute-set>