The default content for running headers is as follows:

The default content for footers is as follows:

The content for running headers is defined in a stylesheet template named header.content. Likewise, the footers are defined in a template named footer.content. You see the default versions in fo/pagesetup.xsl. To customize the headers and footers, you redefine these templates in your customization layer.

The header.content template is called three times for each page-sequence, once each for left, center, and right header cells. It should select and return the appropriate text to fill each cell. The same is true for the footer.content template.

The header and footer content is considered static-content in FO, which means it is repeated in the same place on each page in a page sequence. However, the text itself can vary to show the current section title or page number. The static content is declared at the beginning of each different page sequence that is started during the processing of the document. Within a page sequence, FO supports variations for where a given page-master appears in the sequence, such as for odd- or even-numbered pages.

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

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

<xsl:apply-templates select="." 
  mode="object.title.markup"/>

<xsl:call-template name="datetime.format">
  <xsl:with-param ...

The header.content or footer.content template is called with the element that starts the page sequence as the context node. This means you can select elements to appear in the content using XPaths relative to that element. An example below adds corpauthor to a header.

The header.content or footer.content template is also called with several parameters that you can use in your logic for deciding what should appear in each position. There are also global parameters that can be included in the decision making. The parameters each template is called with include the following:

In addition to these passed parameters, you can use these global parameters to select header/footer content.

A customized version of the header.content template is typically a big xsl:choose structure where each xsl:when states its conditions for choosing the text for a particular header or footer cell. It only has to cover the cells that might have content. Here is a complete example.

<xsl:template name="header.content">  
  <xsl:param name="pageclass" select="''"/>
  <xsl:param name="sequence" select="''"/>
  <xsl:param name="position" select="''"/>
  <xsl:param name="gentext-key" select="''"/>

  <fo:block>  
    <!-- sequence can be odd, even, first, blank -->
    <!-- position can be left, center, right -->
    <xsl:choose>

      <xsl:when test="$sequence = 'odd' and $position = 'left'">  
        <fo:retrieve-marker retrieve-class-name="section.head.marker"  
                            retrieve-position="first-including-carryover"
                            retrieve-boundary="page-sequence"/>
      </xsl:when>

      <xsl:when test="$sequence = 'odd' and $position = 'center'">
        <xsl:call-template name="draft.text"/>  
      </xsl:when>

      <xsl:when test="$sequence = 'odd' and $position = 'right'">
        <fo:page-number/>  
      </xsl:when>

      <xsl:when test="$sequence = 'even' and $position = 'left'">  
        <fo:page-number/>
      </xsl:when>

      <xsl:when test="$sequence = 'even' and $position = 'center'">
        <xsl:call-template name="draft.text"/>
      </xsl:when>

      <xsl:when test="$sequence = 'even' and $position = 'right'">
        <xsl:apply-templates select="." mode="titleabbrev.markup"/>  
      </xsl:when>

      <xsl:when test="$sequence = 'first' and $position = 'left'"> 
      </xsl:when>

      <xsl:when test="$sequence = 'first' and $position = 'right'">  
      </xsl:when>

      <xsl:when test="$sequence = 'first' and $position = 'center'"> 
        <xsl:value-of 
               select="ancestor-or-self::book/bookinfo/corpauthor"/>  
      </xsl:when>

      <xsl:when test="$sequence = 'blank' and $position = 'left'">
        <fo:page-number/>
      </xsl:when>

      <xsl:when test="$sequence = 'blank' and $position = 'center'">
        <xsl:text>This page intentionally left blank</xsl:text>  
      </xsl:when>

      <xsl:when test="$sequence = 'blank' and $position = 'right'">
      </xsl:when>

    </xsl:choose>
  </fo:block>
</xsl:template>

As you can see from the example, there is quite a bit of flexibility in what can appear in a given header or footer location. You can use static text, or dynamic content. You can also include graphics.

Keep in mind that the sequence name odd does not include the sequence first, even though the first page may be an odd page. If you specify something for odd pages, you may also want to specify it for the first page too, as for example:

<xsl:when test="$double.sided != 0 
                and ($sequence = 'odd' or $sequence = 'first') 
                and $position='right'">

It is a common feature to put the current section title in the running header or footer. This is possible with XSL-FO, using the fo:marker and fo:retrieve-marker elements. The stylesheet automatically inserts the fo:marker elements, and you specify the fo:retrieve-marker element in your header or footer content.

You can control which levels of sections are included in the running section titles. Often only the first or second levels are important enough to warrant inclusion. The stylesheet parameter marker.section.level sets the maximum section level to be used. The default value is 2, so only sections at levels 1 and 2 are considered for the running titles. Set the parameter to 1 if you only want top-level sections, or set it to a higher number to include more levels. When the stylesheet processes your document, it inserts the following hidden marker for each section that meets the parameter condition:

<fo:marker marker-class-name="section.head.marker">
  My section title
</fo:marker>

The content of the element is the title to be displayed, if it is selected. The marker name section.head.marker is the same for all section levels by default. If you want to display both the first and second section levels on the same page, you would need to customize the stylesheet to output different marker names for the different levels.

When the pages are being laid out by the FO processor, each hidden marker is placed on the page within its section block. A section's block starts with the section title and extends as far as the section's content goes. That may be over more than one page. Then when the header or footer includes a fo:retrieve-marker, the processor looks for markers with the matching name. Which one it selects depends on the attributes on the fo:retrieve-marker element. The following example shows the typical attributes for running section titles:

<fo:retrieve-marker 
      retrieve-class-name="section.head.marker"
      retrieve-position="first-including-carryover"
      retrieve-boundary="page-sequence"/>

The retrieve-class-name attribute identifies the group of markers to select from. The retrieve-position="first-including-carryover" attribute picks up the first matching marker on the current page, or from a section carried over from a previous page if there is no marker on the current page. The retrieve-boundary="page-sequence" attribute sets the boundary for selecting a previous marker as the current page-sequence, as opposed to the whole document. That prevents carryover from the previous chapter.

Your page design may call for putting a graphical image in headers or footers. The overall process is the same as for other header or footer content. You just add the appropriate XSL-FO markup in the right place in your customized header.content or footer.content template, which are described in the section “Changing the header or footer text”.

The following is an example of the XSL-FO markup as it might appear in the template:

...
<xsl:when test="$position = 'center'">
  <fo:external-graphic content-height="1.2cm">
    <xsl:attribute name="src">
      <xsl:call-template name="fo-external-image">
        <xsl:with-param name="filename" select="$header.image.filename"/>
      </xsl:call-template>
    </xsl:attribute>
  </fo:external-graphic>
</xsl:when>
...

The fo:external-graphic element is used in XSL-FO to specify a graphical file to include in your output. The content-height attribute sets the height, to make sure it will fit within the allocated height for the header or footer. See the section “Allocating height for headers and footers” for details on adjusting the height to fit the graphic.

The image filename itself is specified here using a parameter value $header.image.filename. This is not a DocBook XSL parameter, but one that you could add to your stylesheet. A parameter that is specified at the top of the stylesheet makes it easier to change the filename without searching through code in your customization. But why does it call a template named fo-external-image instead of just adding a literal src attribute? Because different XSL-FO processors handle slightly different syntax for the file reference. That template handles generating the right syntax for each processor.

Some page designs cram more information into the headers or footers by stacking it onto multiple lines. For example, you could have the chapter title on the first line and the running section title on the second. There are two approaches to achieving this effect, using multiple blocks or customizing the layout table.

If you just need to stack two pieces of information into one location in the header or footer, then using two blocks is the easiest customization. In the appropriate xsl:when clause in your customization of the header.content or footer.content template, use two fo:block elements. The following example uses two stacked blocks:

...
<xsl:when test="$sequence = 'odd' and $position = 'left'">
  <fo:block>
    <xsl:apply-templates select="." mode="titleabbrev.markup"/>
  </fo:block>
  <fo:block> 
    <fo:retrieve-marker retrieve-class-name="section.head.marker"  
                        retrieve-position="first-including-carryover"
                        retrieve-boundary="page-sequence"/>
  </fo:block>
</xsl:when>
...

In this example, the first block would contain the chapter title, and the second block would contain the section title.

If your header or footer design uses stacked information in more than one position, then you may want to use the second method, which is customizing the layout table. Using multiple rows in a layout table ensures that the different information will align vertically.

The header.table template in fo/pagesetup.xsl lays out the table rows and cells in the page header. Likewise the footer.table lays out the footer area. You can customize either template to write a table to display whatever combination of rows and cells and spans you want, expressed in XSL-FO table elements.

As you will see in the original template, each fo:table-cell must have a call to the header.content template, and it must communicate that cell's location in the table using the position param. The original left, center, and right values are just strings that are matched in the default header.content template. You can add your own position values like row1col2, as long as you match it with a selection in your customized header.content template.

You can change the font family, size, style, and other attributes of the headers or footers such as borders and background color by customizing the default attribute-sets. You can put FO properties into the header.content.properties attribute set to change the running header style, or into the footer.content.properties attribute-set to change the running footer style. For example:

<xsl:attribute-set name="header.content.properties">
  <xsl:attribute name="font-family">Helvetica</xsl:attribute>
  <xsl:attribute name="font-size">9pt</xsl:attribute>
</xsl:attribute-set>

The rule lines in the headers and footers can be changed or turned off. If you want to change the style of the header rule line, you can customize the following template that is found in fo/pagesetup.xsl:

<xsl:template name="head.sep.rule">
  <xsl:param name="pageclass"/>
  <xsl:param name="sequence"/>
  <xsl:param name="gentext-key"/>

  <xsl:if test="$header.rule != 0">
    <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute>
    <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
    <xsl:attribute name="border-bottom-color">black</xsl:attribute>
  </xsl:if>
</xsl:template>

An identical template named foot.sep.rule lets you control footer rules. The template parameters let you customize which pages have rules or have different rule styles. These parameters are described in the section “Changing the header or footer text”. For example, if you wanted to turn off the header rule line for book title pages and the first page of chapters, you could use the following customization:

<xsl:template name="head.sep.rule">
  <xsl:param name="pageclass"/>
  <xsl:param name="sequence"/>
  <xsl:param name="gentext-key"/>

  <xsl:if test="$header.rule != 0">
    <xsl:choose>
      <xsl:when test="$pageclass = 'titlepage'">
        <!-- off -->
      </xsl:when>
      <xsl:when test="$pageclass = 'body' and $sequence = 'first'">
        <!-- off -->
      </xsl:when>
      <xsl:otherwise>
        <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute>
        <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
        <xsl:attribute name="border-bottom-color">black</xsl:attribute>
      </xsl:choose>
    </xsl:choose>
  </xsl:if>
</xsl:template>

If you want to turn off the header rule entirely, set the stylesheet parameter header.rule to zero. To turn off the footer rule, set footer.rule to zero.

You can use the header.table.properties attribute-set to apply properties to the table used to lay out the header content. Likewise there is a footer.table.properties attribute-set for footers (both becoming available in version 1.72 of the stylesheets). You can use these attribute-sets to draw a border or apply a background color. The following example does both:

<xsl:attribute-set name="header.table.properties">
  <xsl:attribute name="background-color">#DDDDDD</xsl:attribute>
  <xsl:attribute name="border">0.5pt solid black</xsl:attribute>
  <xsl:attribute name="padding-left">5pt</xsl:attribute>
  <xsl:attribute name="padding-right">5pt</xsl:attribute>
</xsl:attribute-set>

<xsl:param name="header.rule">0</xsl:param>

To improve the appearance, this example adds some padding to separate the text from the border, and turns off the normal header rule so it does not override the new border.

If you need more control, then you will need to customize the template files that create the tables that format the headers or footers. These templates are named header.table and footer.table, respectively, and they are located in fo/pagesetup.xsl. Customizing these templates gives you complete control over the handling of content in the headers and footers.

The header or footer is laid out using a single row three-cell table for the left, center, and right positions. Text in the left cell is left-aligned, text in the middle cell is centered, and text in the right cell is right-aligned. By default, all three cell positions are assigned the same width. But you may need to adjust the relative widths to fit your pattern of text. A page number requires very little space, while a long chapter title may need more than a third of the page width.

You can use the header.column.widths and footer.column.widths parameters to adjust the relative widths. Each parameter takes three numbers separated by white space. Each number represents its proportion of the sum of the three numbers. For example:

<xsl:param name="header.column.widths">1 2 1</xsl:param>

The first number represents the relative width of the left position, the second number the relative width of the middle position, and the third number the relative width of the right position. That is for single-sided output. For double-sided output, a mirrored design is assumed, so the first number represents the inside position, and the third number represents the outside position. So in this example, the middle position is twice as wide as either of the other two positions.

Here are some guidelines for setting these width values:

If you find the table layout used in headers and footer to be too restrictive, you can always replace the header or footer table with your own XSL-FO layout. You'll need to customize the template named header.table or footer.table from fo/pagesetup.xsl. You can keep the same template name and template parameters, but you can customize how the information is used within the header or footer space.

If you plan to put more in the headers or footers than just short bits of text, then you need to provide sufficient space. The header text is positioned within the top margin using three parameters, as described in the section “Top and bottom margins”, with similar parameters for the footer text in the bottom margin.

The parameter that sets the height of the header area is region.before.extent. It gets that name from the XSL-FO standard (enough said). The default height is 0.4 inches, which is about 29 points. Since the default line-height is 12 points, there is room for two lines of text. That's helpful when you carry running titles in the header, because some titles may be long enough to wrap to a second line.

If you increase the header font size and line height by setting attributes in the header.content.properties attribute-set, you may also need to increase the region.before.extent parameter. Remember that the header area has to fit within the top margin area, though, so you may also need to increase those two margin parameters as well, to give it more space and to adjust its position. If you are changing the footer size, then it is the region.after.extent and the bottom margin parameters that would need adjustment.

If you add a graphic to the header or footer content, be sure its content-height property fits within the appropriate region extent.

The DocBook XSL print stylesheet provides a pair of named templates, initial.page.number and format.page.number, that give you complete control over the page numbering style in your document. The default numbering style for a book uses lowercase roman numerals (i, ii, iii, etc.) for the front matter, and then restarts with arabic numeral 1 on the first chapter. But you may want a style that numbers consecutively in arabic numerals without restarting, or that starts with page 1 in the table of contents. instead of the title page.

<xsl:template name="initial.page.number">
  <xsl:param name="element" select="local-name(.)"/>  
  <xsl:param name="master-reference" select="''"/>  

  <xsl:choose>
    <!-- double-sided output -->
    <xsl:when test="$double.sided != 0">  
      <xsl:choose>
        <xsl:when test="$element = 'toc'">auto-odd</xsl:when>  
        <xsl:when test="$element = 'book'">1</xsl:when>  
        <xsl:when test="$element = 'part' and not(preceding::chapter)  
                        and not(preceding::part)">1</xsl:when>  
        ...

<xsl:template name="page.number.format">
  <xsl:param name="element" select="local-name(.)"/>
  <xsl:param name="master-reference" select="''"/>

  <xsl:choose>
    <xsl:when test="$element = 'toc' and self::book">i</xsl:when>
    <xsl:when test="$element = 'preface'">i</xsl:when>
    <xsl:when test="$element = 'dedication'">i</xsl:when>
    <xsl:otherwise>1</xsl:otherwise>
  </xsl:choose>
</xsl:template>

<xsl:template name="initial.page.number">auto-odd</xsl:template>
<xsl:template name="page.number.format">1</xsl:template>

<xsl:template match="book/index|part/index">
  ...
      <fo:block id="END-OF-DOCUMENT"/>
    </fo:flow>
  </fo:page-sequence>
 </xsl:if>
</xsl:template>

...
<xsl:when test="$double.sided = 0 and $position='center'">
  <xsl:text>Page </xsl:text>  
  <fo:page-number/>
  <xsl:text> of </xsl:text>
  <fo:page-number-citation ref-id="END-OF-DOCUMENT"/>
</xsl:when>
...

Add extension property to each fo:page-sequence element:
<xsl:template match="*" mode="running.head.mode">
  <xsl:param name="master-reference" select="'unknown'"/>
  <xsl:param name="gentext-key" select="name(.)"/>

  <xsl:if test="$axf.extensions != 0">
    <xsl:attribute name="axf:page-number-prefix">
      <xsl:apply-templates select="." mode="page-number-prefix"/>
    </xsl:attribute>
  </xsl:if>
  ...
</xsl:template>

Example custom template to generate the prefix text:
<!-- Also match on elements inside a chapter for index and xref targets -->
<xsl:template match="chapter|chapter//*" mode="page-number-prefix">
  <xsl:if test="$page.number.prefixes != 0">
    <xsl:number count="chapter" from="book" level="any"/>
    <xsl:value-of select="$page.number.prefix.separator"/>
  </xsl:if>
</xsl:template>

Restart page numbering in each page-sequence:
<xsl:template name="initial.page.number">1</xsl:template>

<xsl:template name="force.page.count">
  <xsl:param name="element" select="local-name(.)"/>
  <xsl:param name="master-reference" select="''"/>

  <xsl:choose>
    <!-- double-sided output -->
    <xsl:when test="$double.sided != 0">end-on-even</xsl:when>
    <!-- single-sided output -->
    <xsl:otherwise>no-force</xsl:otherwise>
  </xsl:choose>
</xsl:template>