Chapter 11. Title page customization

Chapter 11. Title page customization
	Part III. Customizing DocBook XSL

Table of Contents

HTML titlepage specs
Special titlepages

The design of title pages is one area where customization is often needed. You may want to customize both the content and the format of your book, article, chapter, or section title pages. DocBook provides a wide range of metadata elements that can be entered in *info elements such as bookinfo or chapterinfo. You may want to output some metadata elements such as author, but not display others such as revhistory. Also, a title page for a book would likely contain different information from the title page for an article.

Note

A “title page” in DocBook may not be a separate page. The stylesheets use the term “titlepage” to mean the presentation of an element's title and other info element content, such as author and copyright. The “titlepage” mechanism in the stylesheets is designed to be very general, so that it handles many different output styles. Page breaking after the title and info is just one possible feature. Sometimes it generates separate title pages, as in the FO output for a book, and sometimes it just prints the title and info elements without a page break, as in HTML output.

The DocBook XSL stylesheets provide a complete subsystem for customizing title pages. This chapter describes the overall process. Specific details for HTML or FO titlepages are covered in subsequent chapters. Also covered later are certain attribute-sets that can override the properties for some titles.

With the titlepage mechanism described here, you can:

Add or remove information elements on a titlepage.
Change the order that elements appear on a titlepage.
Add formatting attributes to titlepage elements.
Assign a custom template for processing a titlepage element.

The steps for customizing titlepages are listed here, and are further described in the sections that follow.

Create or modify a title page specification file, which is written in XML with its own special element names.
Run a special XSL stylesheet on the spec file to generate your customized title page XSL templates. That's right, you use XSL to generate XSL.
Include the generated templates in your stylesheet customization layer.
Modify templates in mode="titlepage.mode" and more specific modes to customize how individual elements are handled.

Create a titlepage spec file

To create your title page spec file for FO output, you can copy fo/titlepage.templates.xml from the XSL stylesheet distribution. An annotated version of the top of that file follows. To modify title pages for HTML output, you would copy the html/titlepage.templates.xml instead.

Example 11.1. Title page specification file for FO output

<!DOCTYPE t:templates [
<!ENTITY hsize0 "10pt">   
<!ENTITY hsize1 "12pt">
<!ENTITY hsize2 "14.4pt">
<!ENTITY hsize3 "17.28pt">
<!ENTITY hsize4 "20.736pt">
<!ENTITY hsize5 "24.8832pt">
<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
]>
<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"  
             xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
             xmlns:fo="http://www.w3.org/1999/XSL/Format"
             xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- =============================================================== -->

<t:titlepage t:element="article" t:wrapper="fo:block"
             font-family="{$title.fontset}" >

  <t:titlepage-content t:side="recto"
             text-align="center">

    <title 
           t:named-template="component.title" 
           param:node="ancestor-or-self::article[1]" 
           font-size="&hsize5;" 
           font-weight="bold"
           keep-with-next="always" />

    <subtitle/>

    <corpauthor space-before="0.5em"
                font-size="&hsize2;"/>
    <authorgroup space-before="0.5em"
                 font-size="&hsize2;"/>
    <author space-before="0.5em"
            font-size="&hsize2;"/>
    ...
  </t:titlepage-content>

  <t:titlepage-content t:side="verso"> 
  </t:titlepage-content>

  <t:titlepage-before t:side="recto"> 
  </t:titlepage-before>

  <t:titlepage-before t:side="verso">
  </t:titlepage-before>

  <t:titlepage-separator> 
  </t:titlepage-separator>
</t:titlepage>

	The DOCTYPE is used to declare a set of XML entities. These entities are used in the spec file to set font-sizes and such. They let you use the same number for more than one element for consistency. Then if you need to change them all, you just change the entity declaration.
	The specification's root element is `t:templates`, which declares the name spaces and contains all the other elements.All elements and attributes that control the processing are in the `t:` (template) namespace. Intermixed are DocBook element names that not in the template namespace. That enables the spec file to clearly designate which are controlling elements and which are actual DocBook content elements.
	A `t:titlepage` element contains the specs for one element type, in this example `article`. There is one of these for each of `book`, `chapter`, `appendix`, and any other division and component element.
	A `t:wrapper` attribute indicates the output element to wrap the whole title page in. In this case, it is an `fo:block` element.
	This `font-family` attribute is not in the `t:` namespace and so will be passed through. It will add a `font-family` attribute to the `fo:block` wrapper. The attribute value comes from the `title.fontset` parameter (an internal parameter that includes the title font and symbol fonts).
	A `t:titlepage-content` element lists the actual content for one side of the title page, in this case `recto` (front side).
	Inside the `t:titlepage-content` element you see a list of DocBook element names, posed as empty elements. These are placeholders, for the content that comes from your DocBook documents. The order in which DocBook element names appear in the spec file is the order they will appear in the output title page. In this example, the `title` element is first on the page. You can add, move, or remove elements as needed to meet your title page requirements. If instead you want to force the output order to match the order of those elements in your documents, add a `order="document"` attribute to the `t:titlepage-content` element.
	You can assign a named template to process an element. The `component.title` template exists in the stylesheet and is used for chapter, appendix, glossary, and other component-level titles. You can also write your own customized templates and assign them with this mechanism.
	You can pass parameters to the named template you assigned to the element in the previous spec. In this case, the parameter name is `node`, and the value is an XPath expression for the ancestor element of the title element being processed.
	You can also set properties to format the element. In this case, it is setting the `font-size` of the article title to the value of the `&hsize5;` entity, which was declared to be `24.8832pt` at the top of the spec file. This is the nominal size, and can be overridden by a named template such as `component.title`. For HTML output, formatting properties are usually applied from a separate CSS stylesheet instead of the titlepage spec file.
	Another `t:titlepage-content` element, this time with `t:side="verso"`, is used to list the content for the `verso` (back) side of the title page. By default, only a `book` element has a two-page titlepage. For all other elements, the `verso` titlepage is empty because there is no second titlepage. See the specs for `book` if you want to create a two-page titlepage.
	Three other elements inside a `t:titlepage` can be used to declare templates for the transitions before and after each title page side. A `<t:titlepage-before t:side="recto">` element lets you define processing to take place just before the recto side. In print, this could be used to generate a page break. Any empty elements have no effect, as in this example. Here is a list of all three transition elements, shown in the order in which they are presented in the output: t:titlepage-before t:side="recto" t:titlepage-content t:side="recto" t:titlepage-before t:side="verso" t:titlepage-content t:side="verso" t:titlepage-separator For a `book`, the `t:titlepage-before` element for `verso` is used to specify a page break, to ensure that the verso content is on its own page.
	A `t:titlepage-separator` element defines what happens between the title pages and the rest of the element's content. In print, this could be a page break if you want your table of contents on its own page. In HTML it could output a rule line separator.

HTML titlepage specs

The titlepage specifcation file for HTML output is similar to the one for FO output. It uses the same element names in the t: namespace, and you can add, remove, or move information elements for any of the titlepages.

These are some of the main differences for the HTML spec file:

Formatting properties are generally left out of the HTML spec file. That's because an external CSS stylesheet is the preferred method for formatting HTML.
To assist in applying CSS styles, each element's titlepage gets a class attribute so that CSS class selectors can be used. The value is titlepage by default, but can be changed to be more specific.
The terms recto and verso are meaningless in a pageless presentation like HTML. So all content is specified on the recto titlepage.

Special titlepages

The titlepage spec files include a few special titlepage elements that do not correspond to actual DocBook elements. For example:

<t:titlepage t:element="table.of.contents" t:wrapper="fo:block">

This set of specs handles the formatting for the title in the table of contents. Since that title is generated by the stylesheets, it does not actually come from a DocBook element. But the stylesheet lets you add properties to control its formatting.


Person names		Generate custom XSL templates