Page headers and footers

Specifying a header or a footer

The header or the footer of a generated PDF, RTF, etc, page has 3 columns.

The width of these columns may be specified using the header-left-width, header-center-width, header-right-width parameters for the header and the footer-left-width, footer-center-width, footer-right-width parameters for the footer.

The width of a column is specified as an integer which is larger than or equal to 1. This value is the proportional width of the column. For example, if the left column has a width equal to 2 and the right column has a width equal to 4, this simply means that the right column is twice (4/2 = 2) as wide as the left column.

The contents of these columns may be specified using the header-left, header-center, header-right parameters for the header and the footer-left, footer-center, footer-right parameters for the footer.

When header-left, header-center, header-right are all specified as the empty string, no header is generated. When footer-left, footer-center, footer-right are all specified as the empty string, no footer is generated.

The content of a column is basically a mix of text and variables. Example: "Page {{page-number}} of {{page-count}}".

Supported variables are:

{{document-title}}: The title of the document.
{{document-date}}: The publication date of the document.
The value of the variable comes from the last created or revised element found in the topicmeta/critdates or bookmeta/critdates element of the map. More precisely, it comes the value of attribute golive, modified or date, considered in that order. The value of this attribute must be something like YYYY-MM-DD, because it is parsed and then formatted according to the xml:lang of the map. For example, if golive="2014-02-23", with xml:lang="en", it gives: "February 02, 2014" and with xml:lang="fr", it gives: "02 Février 2014". If the map has no critdates element, then the current date is used. If the value of attribute golive, modified or date is not specified as YYYY-MM-DD, then this value is used as is.
{{chapter-title}}: The title of the current part, chapter, appendices or appendix . Empty if the map being converted is not a bookmap.
{{section1-title}}: The title of the current part, chapter, appendices or appendix or section 1 . A section 1 is specified by a non-typed topicref (that is, not a part, chapter, preface, appendix, dedication, etc) which is a direct child of a map or bookmap.
{{topic-title}}: The title of the current topic. All topics are guaranteed to have a corresponding {{topic-title}}. Even automatically generated topics such as toc or indexlist have a corresponding {{topic-title}}⁽¹⁾.
{{page-number}}: Current page number within the current document division (front matter, body matter or back matter) .
{{page-count}}: Total number of pages of the current document division (front matter, body matter or back matter).
{{break}}: A line break.
{{image(URI)}}: An image having specified URI. A relative URI is resolved against the current working directory. Example: "{{image(artwork/logo.svg)}}".
{{page-sequence}}: Not for production use. Inserts in the header/footer the name of the current page sequence . This allows to learn which name to use in a conditional header or footer. See below.

Conditional headers and footers

The default value of header-center is '{{document-title}}'. This means that each page of the generated PDF, RTF, etc, file will have the document title centered on its top. But what if you want the pages containing the Table of Contents have a "Contents" header? Is there a way to specify: use "Contents" for the pages containing the Table of Contents and use the title of the document for any other page?

This is done by specifying the following conditional value for parameter header-center: 'toc:: Contents;; {{document-title}}'.

A conditional value may contain one or more cases separated by ";;". Each case is tested against the page being generated. The first case which matches the page being generated is the one which is selected.

conditional_value --> case [ ";;" case ]*

case --> [ condition "::" ]* value

condition --> [ test_page_sequence ]?
                     & [ S test_page_layout ]?
                     & [ S test_page_side ]?

Let's suppose you also want the the pages containing the Index have a "Index" header. Specifying 'toc:: Contents;; {{document-title}};; indexList:: Index' won't work as expected because the second case (having no condition at all) matches any page, including the Index pages. You need to specify: 'toc:: Contents;; indexlist:: Index;; {{document-title}}'.

Let's remember that variable {{topic-title}} is substituted with the title of the current topic, including automatically generated topics such toc and indexlist.

Therefore our conditional value is better expressed as: 'toc:: indexlist:: {{topic-title}};; {{document-title}}'. Notice how a case may have several conditions. Suffice for any of these conditions to match the page being generated for the case to be selected.

Even better, specify 'toc||indexlist:: {{topic-title}};; {{document-title}}'. String "||" may be used to separate alternative values to be tested against the page being generated.

test_page_sequence --> page_sequence [ "||" page_sequence ]*

page_sequence --> "abbrevlist" | "amendments" | "appendices" | "appendix"
                              | "backmattersection" | "bibliolist" | "bookabstract" | "booklist" 
                              | "chapter" | "colophon" | "dedication" | "draftintro" 
                              | "figurelist" | "glossarylist" | "indexlist" | "notices" 
                              | "part" | "preface" | "section1" | "tablelist" 
                              | "toc" | "trademarklist"

Tip

It's not difficult to guess that the name of the page sequence corresponding to the Table of Contents is toc and that the name of the page sequence corresponding to the Index is indexlist. However the simplest way to learn what is the name of the page sequence being generated is to reference variable {{page-sequence}} in the specification of a header or a footer.

Now let's suppose that we want to suppress the document title on the first page of a part, chapter or appendix. This is specified as follows: 'first part||chapter||appendix:: ;; toc||indexlist:: {{topic-title}};; {{document-title}}'.

For now, we have only described a condition about the page sequence being generated: TOC, Index, etc. In fact, a condition may test up to 3 facets of the page being generated:

The page sequence to which belongs the page being generated.
Whether the page being generated is part of a one-sided or a two-sided document.
Whether the page being generated is the first page of its sequence. When the the page being generated is not the first page of its sequence, if the page being generated has an odd or an even page number.

test_page_layout --> page_layout [ "||" page_layout ]*

page_layout --> "two-sides" | "one-side"

test_page_side --> page_side [ "||" page_side ]*

page_side --> "first" | "odd" | "even"

Remember

When the document has one side, there is no difference between even and odd. That is, even, odd, even||odd all simply mean: other than first.

The order of the tests is not significant. For example, 'first part||chapter||appendix' is equivalent to 'part||chapter||appendix first'.

Therefore 'first part||chapter||appendix:: ;; toc||indexlist:: {{topic-title}};; {{document-title}}' reads as follows:

Use the empty string for the first page of a part, chapter or appendix.
Use the topic title for the pages containing the Table of Contents. This title is "Table of Contents", but localized according to the main language of the DITA document being converted.
Use the topic title for the pages containing the Index. This title is "Index", but localized according to the main language of the DITA document being converted.
For any other page, use the title of the DITA document.

Note

Everything explained in this section applies not only to the contents of a column of a header or footer, but also to the proportional width of a column of a header or footer. Example: -p footer-right-width "first||odd:: 4;; even:: 1".

⁽¹⁾	The {{topic-title}} of a toc is "Table of Contents", properly localized. The {{topic-title}} of a indexlist is "Index", properly localized.