10.3.1. Specifying a header or a footer

The header or the footer of a generated PDF, RTF, DOCX, 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 this variable comes from the meta element having any of the following name attributes: "dc.date", "dcterms.issued", "dcterms.modified", "dcterms.created", if found in the head element of the ebook specification. If the ebook specification does not contain such meta elements then the current date is used.

The value of the content attribute of the meta element is expected be something like YYYY-MM-DD, because it is parsed and then formatted according to the xml:lang of the ebook specification. For example, if content="2017-02-23", with xml:lang="en", it gives: "February 02, 2017" and with xml:lang="fr", it gives: "02 février 2017".

{{chapter-title}}

The title of the current part, chapter, appendices or appendix.

{{section1-title}}

The title of the current part, chapter, appendices or appendix or section 1.

{{division-title}}

The title of the current document divisions. All the document divisions are guaranteed to have a corresponding {{division-title}}. Even automatically generated divisions such as <toc/> or <index/> have a corresponding {{division-title}}.

{{page-number}}

Current page number within the current document part (front matter, body matter or back matter) .

{{page-count}}

Total number of pages of the current document part (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 . Lets the author 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}};; index:: 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;; index:: Index;; {{document-title}}'.

Let's remember that variable {{division-title}} is substituted with the title of the current document division, including automatically generated document divisions such as toc and index.

Therefore our conditional value is better expressed as: 'toc:: index:: {{division-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||index:: {{division-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 --> "title" |
                  "toc" |
                  "booklist" |
                  "frontmatter" |
                  "body" |
                  "backmatter" |
                  "index"

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 index. 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 body:: ;; toc||index:: {{division-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, has an odd page number or has 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"

When the document has one side, the only possible page side is odd. The other values, first and even, are not supported. For example, something like 'one-side body even:: {{chapter-title}};;' cannot generate any text.

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

Therefore 'first body:: ;; toc||index:: {{division-title}};; {{document-title}}' reads as follows:

1. Use the empty string for the first page of a part, appendices, chapter or appendix.
2. Use the document division title for the pages containing the Table of Contents. This title is "Table of Contents", but localized according to the main language of the book.
3. Use the document division title title for the pages containing the Index. This title is "Index", but localized according to the main language of the book.
4. For any other page, use the title of the book.

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".