Custom page design

Custom page design
	Chapter 12. Print customizations

If you find that the stylesheet parameters used in the DocBook stylesheets are not sufficient for meeting your page design needs, you can create your own custom page masters and use them in your documents.

Default page masters

Before creating custom page masters, it helps to understand the set up of the default page masters so you can see how to fit your customizations in.

In DocBook XSL-FO, a standard set of FO simple-page-master elements are declared and used. The page masters are grouped into page classes, one for each specialized type of page such as title page or body. The six page classes are listed in the following table. Within each class, there are different page masters to handle the sequence of pages of that type, such as first, left, and right pages. There is a page-sequence-master element for each page class to set the conditions for sequencing the group of page masters. The following is a list of the built-in page masters.

Table 12.3. DocBook XSL-FO page master names

Page Class	Used by	simple-page-master name	Description
titlepage	Title pages for `set`, `part` and `book` elements.	titlepage-first	First title page
		titlepage-odd	Right-hand title pages
		titlepage-even	Left-hand title pages
lot	Lists of titles, including table of contents and lists of figures, tables, examples, or procedures.	lot-first	First page of table of contents or list of titles such as figures, tables, examples or procedures that appear at front of book.
		lot-odd	Right-hand list of titles
		lot-even	Left-hand list of titles
front	Used by these elements: dedication preface	front-first	First page of new page sequence in book front matter, used for dedication and preface.
		front-odd	Right-hand front matter page.
		front-even	Left-hand front matter page.
body	Used by these elements: chapter article reference refentry section (if root element) sect1 (if root element)	body-first	First page of new page sequence in body of document, such as chapters.
		body-odd	Right-hand body page.
		body-even	Left-hand body page.
back	Used by these elements: appendix bibliography colophon glossary	back-first	First page of new page sequence in book back matter, which includes appendix, glossary, bibliography, and colophon (but not index).
		back-odd	Right-hand back matter page.
		back-even	Left-hand back matter page.
index	Book or set index	index-first	First page of index.
		index-odd	Right-hand index page.
		index-even	Left-hand index page.
		blank	Blank page that may be automatically inserted at the end of a page sequence to even out the page count. It can be used in all page-sequence-masters.

Note

In each page class, there is a second set of page masters with the same names except the names all end in -draft, such as titlepage-first-draft. These are used when a document is processed in draft mode, which happens when you set the draft.mode parameter to one.

Each of the page-master-sequence and simple-page-master elements is defined in the fo/pagesetup.xsl stylesheet file. The page-master-sequence elements are used to set the conditions under which different page masters are selected, such as the first page or even page number. The simple-page-master elements define the margins of the page, using the stylesheet parameters. The following example shows a complete page master declaration:

Example 12.9. Page master declaration

<fo:simple-page-master master-name="titlepage-even" 
                       page-width="{$page.width}"  
                       page-height="{$page.height}"
                       margin-top="{$page.margin.top}"
                       margin-bottom="{$page.margin.bottom}"
                       margin-left="{$page.margin.inner}"
                       margin-right="{$page.margin.outer}">
    <fo:region-body margin-bottom="{$body.margin.bottom}"  
                    margin-top="{$body.margin.top}"
                    column-count="{$column.count.titlepage}">
    </fo:region-body>
    <fo:region-before region-name="xsl-region-before-even"  
                      extent="{$region.before.extent}"
                      display-align="before"/>
    <fo:region-after region-name="xsl-region-after-even"  
                     extent="{$region.after.extent}"
                     display-align="after"/>
</fo:simple-page-master>

	The `master-name` attribute indicates that this page master is for even-numbered title pages.
	The attributes set the page size and margins using stylesheet parameter values.
	The `region-body` child sets the margins for the body area on the page.
	The `region-before` child element sets the height of the header area. The `display-align` attribute puts the header text at the top of the header area.
	The `region-after` child element sets the height of the footer area, with the text aligned at the bottom of the footer area.

The DocBook FO stylesheets don't call the page masters directly, but instead call the page sequence masters, which then call the appropriate page masters as needed. Here is an example of a complete page sequence declaration:

Example 12.10. Page sequence declaration

<fo:page-sequence-master master-name="titlepage">  
    <fo:repeatable-page-master-alternatives>  
        <fo:conditional-page-master-reference 
                  master-reference="blank"  
                  blank-or-not-blank="blank"/>  
        <fo:conditional-page-master-reference 
                  master-reference="titlepage-first"  
                  page-position="first"/>  
        <fo:conditional-page-master-reference 
                  master-reference="titlepage-odd"
                  odd-or-even="odd"/>
        <fo:conditional-page-master-reference 
                  master-reference="titlepage-even"
                  odd-or-even="even"/>
    </fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>

	The stylesheet calls this master-name when setting up a page sequence for title pages.
	Wrapper element for a set of conditions that select a particular page master when its conditions are met.
	Calls the page master named `blank` when its conditions are met.
	The value of `blank` for this property indicates that this page master is to be used if a page must be generated but there is no content from the flow to put on it. This occurs when the page sequence properties are set to end on an even page number, but the last of content happens to be on an odd page number.
	Calls the page master named `titlepage-first` when its conditions are met.
	The value of `first` for the `page-position` property indicates that this page master is to be used for the first page of a new titlepage sequence. The other conditions follow a similar pattern for odd-numbered and even-numbered pages.

Declaring custom page masters

The FO stylesheets let you set up your own page masters while leaving the original default page masters in place. To do so, you create an XSL template named user.pagemasters in your customization layer. In it, you add as many fo:simple-page-master and fo:page-sequence-master elements as you need. The names must be different from the default names, which means each master-name attribute must be unique and different from those already declared. Then you add any page properties you need as attributes to the simple-page-master element. The user.pagemasters template is automatically called by the template that sets up the default page masters. So all you have to do is define it and your page masters will become part of your FO output files, ready to be used in page sequences.

The easiest way to make your own page masters is to cut and paste from the original fo/pagesetup.xsl stylesheet file to your customization, and then change the name and property attributes. You will most likely want to copy a page-sequence-master and its related simple-page-master elements so you can have proper handling of first, left, and right pages.

In your property attributes for your custom page masters, you can refer to any of the existing stylesheet parameter values, or define your own parameters in your customization layer. You can also use any of them in expressions, so you can adjust the regular value by increments. There are many simple-page-master property attributes that you can add as well. You will need a good FO reference or the XSL-FO specification to know what attribute names and values can be used. Keep in mind that not all property attributes are supported by all XSL-FO processors.

Using custom page masters

Declaring custom page masters just makes them available to be used, but does not employ them in page sequences. To do that, you have to add some logic to the stylesheets so your custom page masters are selected instead of the default page masters. That logic is put into a template named select.user.pagemaster that you add to your customization layer. The way this works is as follows:

The DocBook elements that start a page sequence call the template named select.pagemaster. It is supposed to return a master-name for a page-sequence-master such as titlepage or body. That template's first step is to select the appropriate default page master name for that element.
Then the select.pagemaster template automatically calls the select.user.pagemaster template, passing the selected default master name as a parameter.
The default version of the select.user.pagemaster template simply returns the default page master. But if you customize that template, then it can return the master name of one of your customized page-sequence-masters in place of the default.

Here is an example of a customized template that selects a new name if for titlepage, otherwise returns the default:

<xsl:template name="select.user.pagemaster">
  <xsl:param name="element"/>
  <xsl:param name="pageclass"/>
  <xsl:param name="default-pagemaster"/>

  <!-- Return my customized title page master name if for titlepage,
       otherwise return the default -->

  <xsl:choose>
    <xsl:when test="$default-pagemaster = 'titlepage'">
      <xsl:value-of select="'my-new-titlepage'" />
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="$default-pagemaster"/>
    </xsl:otherwise>
  </xsl:choose>
  </xsl:template>

You could also use the element name or the pageclass parameter value in the conditions for choosing a page master.