A DocBook Cookbook

Jean-François Perrot

1. Motivation
2. Setting parameters
3. Adding fo-attributes through xsl-attribute-sets

1. Motivation

   DocBook is designed to support the detailed structure of large and complex books - even collections.
   The whole nomenclature - tags and attributes - is quite extensive, as testified by the size of the authoritative RNG grammar.
   In addition, the standard XSLT transforms introduce a substantial set of parameters, attributes and templates.
   On top of it, the results do not always conform to the documentation, (which by the way mostly relates to DocBook v.4, e.g. Dawson).
   In this complicated situation, one has to rely on past experience.
   
   This is particularly true for pdf rendering — for XHTML, an adequate CSS is of a great help.
   
   

2. Setting parameters

   The standard stylesheet uses many parameters (reference list) which receive default values.
   Explicitly setting the parameters will override those default values.
   
   Examples
   
   
   1. Setting paper size : paper.type
      Default is USletter.
      <xsl:param name="paper.type" select="'A4'"/>
      
      
   2. Choice of typeface for titles: title.font.family
      Default is sans-serif.
<xsl:param name="title.font.family" select="'serif'"/>
      
      Same for body.font.family (default is serif).
      
      
   3. Automatic numbering of sections (and subsections): section.autolabel
      Default is "0" (= false)
      <xsl:param name="section.autolabel" select="1"/>
      
      
   4. Printing the URL after the text of a link: ulink.show
      Default is "1" (= true).
      <xsl:param name="ulink.show" select="0"/> to suppress URLs (links are active anyway)
      In DocBook v.5, applies as soon as xlink:href apears with an external reference.
      
      Same for header.rule et footer.rule which govern the presence of a horizonal line below the header and above the footer of the page
      (default is "1" for both).
      
   
   

3. Adding fo-attributes through xsl-attribute-sets

   The standard stylesheet defines a number of attribute-sets, which are used by templates. [Review the way attribute-sets  work]
   Recall that when a template T uses an attribute-set A, every attribute a that is defined in A appears in the XML that is generated by the template.
   Adding an attribute x to A will result in injecting x into all the XML elements that will be generated by T.
   These attribute-sets are seen a properties belonging to the generated XML object (e.g. an fo:block).
   
   Examples
   
   
   1. section.level1.properties
      Default value is empty: inherits section.properties, which is also empy.
      
      
      Description
      The properties that apply to the containing block of a level-1 section, and therefore apply to the whole section.
      This includes sect1 elements and section elements at level 1.
      [doc]
      
      In order to obtain a page-break before each section1, add to the block the fo attribute
      <xsl:attribute name="break-before">page</xsl:attribute>
      N.B. since attributes are unqualified in XSL-FO, the namespace prefix does not appear. Nonetheless, this attributes is part and parcel of the XSL-FO language.
      
      This is achieved by incrementally adding this attribute to the attribute-set:
      <xsl:attribute-set name="section.level1.properties">
  <xsl:attribute name="break-before">page</xsl:attribute>
</xsl:attribute-set>

      
   2. section.title.level1.properties
      Defaut value :
      <xsl:attribute-set name="section.title.level1.properties">
  <xsl:attribute name="font-size">
    <xsl:value-of select="$body.font.master * 2.0736"></xsl:value-of>
    <xsl:text>pt</xsl:text>
  </xsl:attribute>
</xsl:attribute-set>
      
      That is to say, the only specified property is the font size (in points).
      One may add a choice of color: <xsl:attribute name="color">blue</xsl:attribute>

<xsl:attribute-set name="section.title.level1.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>
      
      
   3. xref.properties
      Default value is empty.
      
      Describes the typography of hypertext links.
      Let us try and imitate a time-honored tradition from HTML: blue and underlined.
      <xsl:attribute-set name="xref.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
  <xsl:attribute name="text-decoration">underline</xsl:attribute>
</xsl:attribute-set>