Print title pages

The customization of titles was covered in the previous sections. But title pages include more than just titles. They can include information about authors, publishers, copyright, legal notice, and even a revision history. Title pages are one part of printed output that often demands customization, for example, to match a corporate style.

The overall process for customizing title page specifications is covered in Chapter 10, Title page customization. For print output, some additional options are available. There are four approaches to customizing the title pages produced by DocBook XSL. They are listed here from lowest to highest precedence:

Which method you use depends on what you are trying to accomplish with your customization. The following table should help guide you.

Table 12.2. Title page customization guide

To accomplish this:You need to do this:
Change page margins for title pages only.Create a custom page-master for title pages. See the section “Custom page design”.
Set common properties on title pages.Customize parameters and attribute-set values. See the section “Title page attribute-sets”.
Add or rearrange elements to a title page.Customize titlepage spec file and generate custom stylesheet module. See the section “Title page spec file”.
Customize an element on a title pageAdd a new element template. See the section “Title page element templates”.
Add sub elements to a title page.Customize an element template. See the section “Title page element templates”.
Customize layout of title page.Create your own titlepage templates. See the section “Custom title page layout”.

Title page processing in DocBook XSL involves a large number of templates and many opportunities for intervention for customization purposes. At some point you may want to better understand the inner workings. See the section “Template sequence for book title pages” for a description of the sequence of templates executed for a book's title pages. Title pages for other elements are handled in a similar manner.

Title page attribute-sets

The stylesheets are set up to use attribute-sets to specify many characteristics of title pages. To the degree that properties are parameterized with attribute-sets, you can customize them without having to modify any XSL templates. Attribute-sets of the same name are merged, so you don't have to repeat all properties in your customization. See the section “Attribute sets” for general information on how attribute-sets work.

The main feature for controlling the overall title page style is a collection of attribute-sets. These are defined and used for each kind of title page, as for example the book.titlepage.recto.style attribute set, which would be used for the front (recto) side of book title pages. Dozens of these attribute sets are defined in fo/titlepage.xsl and can be overridden in your customization layer. The following example shows the default properties for a book's front title page:

Example 12.1. Title page attribute set (default)

<xsl:attribute-set name="book.titlepage.recto.style">
  <xsl:attribute name="font-family">
    <xsl:value-of select="$title.font.family"/>
  </xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
  <xsl:attribute name="font-size">12pt</xsl:attribute>
  <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>

These attributes form the base properties for the title page. Unless otherwise specified by one of the other customization methods, each element that appears on the title page will have these properties. Here is an example.

Example 12.2. Customized title page attribute set

<xsl:attribute-set name="book.titlepage.recto.style">
  <xsl:attribute name="font-family">Garamond</xsl:attribute>
  <xsl:attribute name="text-align">right</xsl:attribute>
  <xsl:attribute name="color">#E0E0E0</xsl:attribute>
</xsl:attribute-set>

This customized version overrides the font-family and text-align values from the original attribute-set in fo/titlepage.xsl, and adds a color attribute. The font-weight and font-size properties remain as originally defined.

You can override these base properties for specific elements on the title page by customizing the title page spec file, or by adding title page element templates, as described in the next sections.

Title page spec file

The title page spec file provides a means to add FO properties to each element you list for the title page sides (recto and verso). Those properties might include font family and size, or color, spacing, or alignment.

The general process for customizing title pages is described in Chapter 10, Title page customization, summarized in these steps:

  1. Create a customized title page specification file.

  2. Process the spec file with the special stylesheet template/titlepage.xsl that generates a title page stylesheet file.

  3. Include the generated title page stylesheet file in your customization layer.

In HTML, title pages are a single virtual page without specific boundaries. In print, title pages have recto and verso pages, or front side and back side of double-sided output. So some thought must be given to which information appears on which printed page. You can also apply specific style properties to any elements on the title pages. Here is what the book element's default title page spec looks like in fo/titlepage.templates.xml.

Example 12.3. Print title page spec file

<t:titlepage t:element="book" t:wrapper="fo:block">  1
    <t:titlepage-content t:side="recto">  2
      <title 3 
             t:named-template="division.title"  4
             param:node="ancestor-or-self::book[1]"  5
             text-align="center"  6
             font-size="&hsize5;"  7
             space-before="&hsize5space;"
             font-weight="bold"
             font-family="{$title.font.family}"/>
      <subtitle
             text-align="center"
             font-size="&hsize4;"
             space-before="&hsize4space;"
             font-family="{$title.font.family}"/>
      <corpauthor
             font-size="&hsize3;"
             keep-with-next="always"
             space-before="2in"/>
      <authorgroup space-before="2in"/>
      <author font-size="&hsize3;"
              space-before="&hsize2space;"
              keep-with-next="always"/>
    </t:titlepage-content>
1

Start of title page specs for book element. Note that all elements and attributes used to control the templates use the t: name space, such as t:titlepage and t:element. The t:wrapper attribute indicates that the whole title page is to be wrapped in an fo:block element.

2

Start the content for the recto (front) side of the title page.

3

First element on page should be the book title. DocBook elements do not use the t: namespace.

4

Use the named template division.title to process the title within the wrapper fo:block.

5

Call the named template with a parameter named node and value ancestor-or-self::book[1]. In the division.title template, the node parameter is expected to contain the node of the element containing the title. This is an XPath expression that selects the book element itself.

6

Add a text-align property to the block containing the title. Attributes not in a namespace are copied through to the wrapper element.

7

Add a font-size property to the block containing the title. This uses as its value an entity reference to one of the entities declared in the spec file itself. Following this are several other properties for title, and other elements in the order in which they should appear on the title page.

This default title page spec results in the generated title page stylesheet template that looks like this:

Example 12.4. Generated template for title on book title page

<xsl:template match="title" mode="book.titlepage.recto.auto.mode"> 
  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" 
            xsl:use-attribute-sets="book.titlepage.recto.style"
            text-align="center" 
            font-size="24.8832pt" 
            space-before="18.6624pt" 
            font-weight="bold" 
            font-family="{$title.font.family}">
    <xsl:call-template name="division.title">
      <xsl:with-param name="node" select="ancestor-or-self::book[1]"/>
    </xsl:call-template>
  </fo:block>
</xsl:template>

You can see that most of the property attributes in the fo:block element come from the spec file. But an additional set comes from xsl:use-attribute-sets="book.titlepage.recto.style", which is automatically inserted by the template-generating stylesheet. This attribute-set is defined in fo/titlepage.xsl to declare default characteristics for all elements on this title page. See Example 12.1, “Title page attribute set (default)” for a listing of the attributes.

Notice that the attribute-set includes attributes such as font-size that are also specified in the spec file (and hence the book.titlepage.recto.auto.mode template). It is a feature of attribute sets that an explicit instance of an attribute will override the same attribute from the attribute-set. That allows the attribute-set to supply a default set of values that apply to all elements on the title page, yet gives you the freedom to specify values for particular elements. That lets you specify most of the attributes once, and then add only the changes for specific elements.

The resulting FO output includes properties from the attribute set (default or customized), from explicit properties on each element as listed in the spec file, and from the template used to format the title, which is division.title in this case. Any parameter or entity variables are resolved as well. The following shows the resulting FO output:

Example 12.5. FO output for title on book title page

<fo:block font-family="sans-serif"
          color="#E0E0E0" 
          font-weight="bold" 
          font-size="24.8832pt" 
          text-align="center" 
          space-before="18.6624pt">
   <fo:block keep-with-next.within-column="always" 
             hyphenate="false">
      Using the DocBook XSL Stylesheets
   </fo:block>
</fo:block>

In this case, all of the properties in the attribute set except color were explicitly overridden by the spec file. The inner fo:block with its keep and hyphenate properties come from the division.title template.

Adding title page elements

You can add elements to your title pages by expanding the list of elements declared in the title page spec file. With print output you generally have two pages to work with, recto and verso. You need to decide which page to put new elements on, and in what order. Then you need to decide what properties you want to apply to each element. For example, if you want to add revhistory to a book's verso title page, then add a line to the spec file as follows:

Example 12.6. Adding an element to a title page

  <t:titlepage-content t:side="verso">
      <title
             t:named-template="book.verso.title"
             font-size="&hsize2;"
             font-weight="bold"
             font-family="{$title.font.family}"/>
      <corpauthor/>
      <authorgroup t:named-template="verso.authorgroup"/>
      <author/>
      <othercredit/>
      <pubdate space-before="1em"/>
      <revhistory/>        Add this line
      <copyright/>
      <abstract/>
      <legalnotice font-size="8pt"/>
  </t:titlepage-content>

When this spec file is processed into the titlepage templates module, it adds a template in the right mode for outputting the revision text at that point on the title page.

Styling title page elements

The spec file can include any FO properties you want to apply to a given element on a given title page. For example, if the added revhistory element in the preceding example needs some styling:

<revhistory
    font-weight="normal"
    font-style="italic"
    color="green"/>

The revhistory element has revision children, each of which has child elements. In this example, all those descendant elements would have those properties. For structured elements such as this, you might want to supply your own custom XSL template for formatting all the descendants. That can simplify the spec file considerably. For example:

<revhistory
   t:named-template="book.verso.revhistory"/>

You could write the book.verso.revhistory XSL template to create a fo:table to format all of its ancestors in an orderly fashion. The template could also apply properties to specific elements as needed.

Adding title page graphics

Many companies want to put a logo graphic on each title page. This is easily done with the spec file:

  <t:titlepage-content t:side="recto">
      <mediaobject/>
      <title
             t:named-template="book.verso.title"
             font-size="&hsize2;"
             font-weight="bold"
             font-family="{$title.font.family}"/>
      <corpauthor/>
      ...
  </t:titlepage-content>

The <mediaobject/> entry in the spec file will generate a template on bookinfo/mediaobject in your custom titlepage XSL module. You then just need to put a mediaobject element in your bookinfo element to specify the actual graphic file, and that template will process it onto the titlepage, located above the title in this case.

Title page element templates

The title page machinery provides a means to insert XSL templates to customize how individual elements are handled.

You can do this in two ways. You can list in the spec file a named-template attribute on an element, as was done for the title element in Example 12.3, “Print title page spec file”. Then you add the named template to your customization layer. Or if you don't want to modify the titlepage spec file and generate a new titlepage stylesheet module, then you can use the built-in mechanism. If the template has a match on the element name and uses the proper mode name, it will be automatically applied by the stylesheets.

You can use the built-in mechanism if all of the following are true:

  • An element is already included in the title page spec file.

  • The spec file doesn't specify a named-template attribute for that element.

  • You don't want to bother generating your own custom title page stylesheet module.

An example best illustrates how to declare such a template in your customization layer:

Example 12.7. Custom title page element template

<xsl:template match="corpauthor" mode="book.titlepage.recto.mode">
  <fo:external-graphic>
    <xsl:attribute name="src" select="$my.corporate.logo"/>
  </fo:external-graphic>
  <fo:inline color="blue">
    <xsl:apply-templates mode="titlepage.mode"/>
  </fo:inline>
</xsl:template>

This template is automatically applied to any corpauthor elements that appear on the recto title page of a book (if it is so specified in the title page spec file). If you want to apply it on a verso title page of a set element, then you would change the mode to mode="set.titlepage.verso.mode" instead.

The action of this example template is to insert a corporate logo graphic (defined with a parameter) before the corporate author name, and then wrap that name in a fo:inline element to apply a blue color.

In this example, any children of corpauthor are then processed using templates with mode="titlepage.mode". These are defined in the stylesheet module fo/titlepage.xsl. This is the fallback mode when a specific titlepage mode is not defined for an element. If you wanted to apply the mode="titlepage.mode" templates to the corpauthor element itself, then you need to add a select attribute:

<xsl:apply-templates  select="."  mode="titlepage.mode"/>

The template processing takes place within the fo:block that holds the properties from the spec file. That means you don't have to specify those properties in your custom template. But it also means those property values will be inherited by any output generated by your template. Also, before using mode="titlepage.mode" this way, you should check in fo/titlepage.xsl for the template that uses this mode for your customized element to make sure it is compatible. For example, some of them output their own fo:block element, which would not be permitted inside an fo:inline as in this example.

Custom title page layout

If you need to customize the layout of a title page, then you will find that difficult to do using the title page spec file and generated stylesheet module. The spec file is best at adding, sequencing, and formatting elements that are included on a title page, but not any layout relationships they have have with each other.

You can completely control the layout of a title page by using a fo:table element to locate content on the page in table cells. This is similar to the process used to lay out HTML pages. Within a given table cell you apply templates to the elements you want to appear in that cell. This is usually done in a mode such as titlepage.mode to ensure proper handling in the title page context.

Your custom page layout is activated by giving it the appropriate template name to override the default title page processing. For example, if your customization layer includes a template named book.titlepage.recto, then it will be used instead of the template generated from the title page spec file. The following example uses a layout table to position content on the page:

Example 12.8. Table-based title page layout

<xsl:template name="book.titlepage.recto">
  <fo:block>
    <fo:table inline-progression-dimension="100%" table-layout="fixed">
      <fo:table-column column-width="50%"/>
      <fo:table-column column-width="50%"/>
      <fo:table-body>
        <fo:table-row >
          <fo:table-cell number-columns-spanned="2">
            <fo:block text-align="center">
              <xsl:choose>
                <xsl:when test="bookinfo/title">
                  <xsl:apply-templates 
                         mode="book.titlepage.recto.auto.mode" 
                         select="bookinfo/title"/>
                </xsl:when>
                <xsl:when test="title">
                  <xsl:apply-templates 
                         mode="book.titlepage.recto.auto.mode" 
                         select="title"/>
                </xsl:when>
              </xsl:choose>
            </fo:block>
          </fo:table-cell>
        </fo:table-row>
        <fo:table-row>
          <fo:table-cell>
            <fo:block>
              <xsl:apply-templates 
                     mode="book.titlepage.recto.mode" 
                     select="bookinfo/corpauthor"/>
            </fo:block>
          </fo:table-cell>
          <fo:table-cell>
            <fo:block>
              <xsl:apply-templates 
                     mode="book.titlepage.recto.mode" 
                     select="bookinfo/edition"/>
            </fo:block>
          </fo:table-cell> 
        </fo:table-row >  
      </fo:table-body> 
    </fo:table>
  </fo:block>
</xsl:template>

This rather trivial example outputs the book title, the corpauthor, and the edition. The layout is a two-column table. The title spans both columns and is centered in them. In the second row, the corpauthor appears in the left table cell and the edition in the right table cell. A real example would include more properties on the fo:table-cell elements to control how each element is placed in its cell.

Template sequence for book title pages

This section summarizes the sequence of templates used to generate title pages for a book. A similar sequence is used for other elements that might have title pages, including article, chapter, reference, etc. Use this as a guide for figuring out where to intervene for customization.

  1. Template with match="book" in fo/division.xsl starts the book processing.

  2. That template calls the named template book.titlepage in fo/titlepage.templates.xsl (the stylesheet module generated from titlepage.templates.xml). It passes it the book element to process.

  3. That template calls these named templates on the book element in sequence:

    book.titlepage.before.recto (null)
    book.titlepage.recto
    book.titlepage.before.verso
    book.titlepage.verso
    book.titlepage.separator
    

    By default, the first template does nothing, but could be customized to do something. The book.titlepage.separator and book.titlepage.before.verso templates just output a page break. That leaves the two main templates to process the recto and verso sides of the title page.

  4. The book.titlepage.recto template is in fo/titlepage.templates.xsl (the generated file). It processes the title page elements in the order in which they appear in the spec file (fo/titlepage.templates.xml).

  5. It does an apply-templates mode="book.titlepage.recto.auto.mode" on the first element in the list, which is title. Since the title could reside inside or outside the bookinfo container, it first tries to select bookinfo/title. If that fails, then it tries title.

  6. There is a template with match="title" mode="book.titlepage.recto.auto.mode" in the generated file fo/titlepage.templates.xsl. It does the following:

    1. It starts an fo:block.

    2. It adds a use-attribute-set name="book.titlepage.recto.style". This provides the properties that are common to all elements on that page.

    3. It adds the property attributes assigned to book title (recto) from the spec file.

    4. It calls the template named division.title on the title element to output the title text. It calls that template because the spec file assigned it to the title element on book recto title pages. That template resides in fo/division.xsl, and it does the following:

      1. If passivetex.extensions is turned on, it outputs a fotex:bookmark element, which is used to generate PDF bookmarks.

      2. It starts a nested fo:block with a couple more properties.

      3. Then it outputs the title text.

      4. Then it closes the inner fo:block.

    5. It closes the outer fo:block element to complete the title element.

  7. Then the book.titlepage.recto template processes the next element in the sequence, which is subtitle. Its processing is similar, but not the same. It does an apply-templates mode="book.titlepage.recto.auto.mode" on the subtitle element.

  8. There is a template with match="subtitle" mode="book.titlepage.recto.auto.mode" in the generated file fo/titlepage.templates.xsl. It does the following:

    1. It starts an fo:block.

    2. It adds the property attributes assigned to book subtitle (recto) from the spec file.

    3. It adds a use-attribute-set name="book.titlepage.recto.style". This the properties that are common to all elements on that page.

    4. Since subtitle does not have a call-template attribute in the spec file to assign it a special template, it uses the default behavior. It executes an apply-templates mode="book.titlepage.recto.mode" on the subtitle element. Any element that doesn't have a specific template assigned to it in the spec file gets the same treatment.

      1. In the stock stylesheets, there is no template with match="subtitle" mode="book.titlepage.recto.mode". This is an opportunity for a customization layer to intercept processing by supplying a template with those attributes.

      2. If no such custom template exists, then instead the template with match="*" mode="book.titlepage.recto.mode" in fo/titlepage.templates.xsl is used.

      3. This default template does apply-templates mode="titlepage.mode" on the matching element, which is subtitle in this case.

      4. There is a template with match="subtitle" mode="titlepage.mode" in fo/titlepage.xsl. This stylesheet module is not generated. It contains templates for each element to handle its default processing on title pages. That template processes its children in the same mode to ensure the generated text is appropriate for title page output.

    5. It closes the fo:block element to complete the title element.

  9. The book.titlepage.recto template processes the rest of the elements listed in the spec file for the recto page in a similar manner.

  10. Then the book.titlepage template calls the book.titlepage.verso template, which processes all the elements listed in the spec file for the verso title page.

  11. Then the book.titlepage template calls the book.titlepage.separator template, which just outputs a page break. That completes the book title page processing.

If a given element that you want to appear on a title page does not have any titlepage template, then it won't appear. An element can be output with any of these:

  • A call to a specific template named in the spec file. See the section “Chapter titles” for an example.

  • A match on the element with a template in book.titlepage.recto.mode (or whichever title page you need).

  • A match on the element with a template in titlepage.mode.