E. Page Headings

Most printed manuals contain headings along the top of every page except the title and copyright pages. Some manuals also contain footings. (Headings and footings have no meaning to Info, which is not paginated.)

E.1 Headings Introduced

Texinfo provides standard page heading formats for manuals that are printed on one side of each sheet of paper and for manuals that are printed on both sides of the paper. Typically, you will use these formats, but you can specify your own format if you wish.

In addition, you can specify whether chapters should begin on a new page, or merely continue the same page as the previous chapter; and if chapters begin on new pages, you can specify whether they must be odd-numbered pages.

By convention, a book is printed on both sides of each sheet of paper. When you open a book, the right-hand page is odd-numbered, and chapters begin on right-hand pages—a preceding left-hand page is left blank if necessary. Reports, however, are often printed on just one side of paper, and chapters begin on a fresh page immediately following the end of the preceding chapter. In short or informal reports, chapters often do not begin on a new page at all, but are separated from the preceding text by a small amount of whitespace.

The @setchapternewpage command controls whether chapters begin on new pages, and whether one of the standard heading formats is used. In addition, Texinfo has several heading and footing commands that you can use to generate your own heading and footing formats.

In Texinfo, headings and footings are single lines at the tops and bottoms of pages; you cannot create multiline headings or footings. Each header or footer line is divided into three parts: a left part, a middle part, and a right part. Any part, or a whole line, may be left blank. Text for the left part of a header or footer line is set flushleft; text for the middle part is centered; and, text for the right part is set flushright.

E.2 Standard Heading Formats

Texinfo provides two standard heading formats, one for manuals printed on one side of each sheet of paper, and the other for manuals printed on both sides of the paper.

By default, nothing is specified for the footing of a Texinfo file, so the footing remains blank.

The standard format for single-sided printing consists of a header line in which the left-hand part contains the name of the chapter, the central part is blank, and the right-hand part contains the page number.

A single-sided page looks like this:

  _______________________
 |                       |
 | chapter   page number |
 |                       |
 | Start of text ...     |
 | ...                   |
 |                       |

The standard format for two-sided printing depends on whether the page number is even or odd. By convention, even-numbered pages are on the left- and odd-numbered pages are on the right. (TeX will adjust the widths of the left- and right-hand margins. Usually, widths are correct, but during double-sided printing, it is wise to check that pages will bind properly—sometimes a printer will produce output in which the even-numbered pages have a larger right-hand margin than the odd-numbered pages.)

In the standard double-sided format, the left part of the left-hand (even-numbered) page contains the page number, the central part is blank, and the right part contains the title (specified by the @settitle command). The left part of the right-hand (odd-numbered) page contains the name of the chapter, the central part is blank, and the right part contains the page number.

Two pages, side by side as in an open book, look like this:

  _______________________     _______________________
 |                       |   |                       |
 | page number     title |   | chapter   page number |
 |                       |   |                       |
 | Start of text ...     |   | More  text ...        |
 | ...                   |   | ...                   |
 |                       |   |                       |

The chapter name is preceded by the word “Chapter”, the chapter number and a colon. This makes it easier to keep track of where you are in the manual.

E.3 Specifying the Type of Heading

TeX does not begin to generate page headings for a standard Texinfo file until it reaches the @end titlepage command. Thus, the title and copyright pages are not numbered. The @end titlepage command causes TeX to begin to generate page headings according to a standard format specified by the @setchapternewpage command that precedes the @titlepage section.

There are four possibilities:

No @setchapternewpage command

Cause TeX to specify the single-sided heading format, with chapters on new pages. This is the same as @setchapternewpage on.

@setchapternewpage on

Specify the single-sided heading format, with chapters on new pages.

@setchapternewpage off

Cause TeX to start a new chapter on the same page as the last page of the preceding chapter, after skipping some vertical whitespace. Also cause TeX to typeset for single-sided printing. (You can override the headers format with the @headings double command; see The @headings Command.)

@setchapternewpage odd

Specify the double-sided heading format, with chapters on new pages.

Texinfo lacks an @setchapternewpage even command.

E.4 How to Make Your Own Headings

You can use the standard headings provided with Texinfo or specify your own. By default, Texinfo has no footers, so if you specify them, the available page size for the main text will be slightly reduced.

Texinfo provides six commands for specifying headings and footings:

• @everyheading @everyfooting generate page headers and footers that are the same for both even- and odd-numbered pages.
• @evenheading and @evenfooting command generate headers and footers for even-numbered (left-hand) pages.
• @oddheading and @oddfooting generate headers and footers for odd-numbered (right-hand) pages.

Write custom heading specifications in the Texinfo file immediately after the @end titlepage command. You must cancel the predefined heading commands with the @headings off command before defining your own specifications.

Here is how to tell TeX to place the chapter name at the left, the page number in the center, and the date at the right of every header for both even- and odd-numbered pages:

@headings off
@everyheading @thischapter @| @thispage @| @today{}

You need to divide the left part from the central part and the central part from the right part by inserting ‘@|’ between parts. Otherwise, the specification command will not be able to tell where the text for one part ends and the next part begins.

Each part can contain text or @-commands. The text is printed as if the part were within an ordinary paragraph in the body of the page. The @-commands replace themselves with the page number, date, chapter name, or whatever.

Here are the six heading and footing commands:

@everyheading left @| center @| right

@everyfooting left @| center @| right

The ‘every’ commands specify the format for both even- and odd-numbered pages. These commands are for documents that are printed on one side of each sheet of paper, or for documents in which you want symmetrical headers or footers.

@evenheading left @| center @| right

@oddheading left @| center @| right

@evenfooting left @| center @| right

@oddfooting left @| center @| right

The ‘even’ and ‘odd’ commands specify the format for even-numbered pages and odd-numbered pages. These commands are for books and manuals that are printed on both sides of each sheet of paper.

Use the ‘@this…’ series of @-commands to provide the names of chapters and sections and the page number. You can use the ‘@this…’ commands in the left, center, or right portions of headers and footers, or anywhere else in a Texinfo file so long as they are between @iftex and @end iftex commands.

Here are the ‘@this…’ commands:

@thispage

Expands to the current page number.

@thissectionname

Expands to the name of the current section.

@thissectionnum

Expands to the number of the current section.

@thissection

Expands to the number and name of the current section, in the format ‘Section 1: Title’.

@thischaptername

Expands to the name of the current chapter.

@thischapternum

Expands to the number of the current chapter, or letter of the current appendix.

@thischapter

Expands to the number and name of the current chapter, in the format ‘Chapter 1: Title’.

@thistitle

Expands to the name of the document, as specified by the @settitle command.

@thisfile

For @include files only: expands to the name of the current @include file. If the current Texinfo source file is not an @include file, this command has no effect. This command does not provide the name of the current Texinfo source file unless it is an @include file. (See section Include Files, for more information about @include files.)

You can also use the @today{} command, which expands to the current date, in ‘1 Jan 1900’ format.

Other @-commands and text are printed in a header or footer just as if they were in the body of a page. It is useful to incorporate text, particularly when you are writing drafts:

@headings off
@everyheading @emph{Draft!} @| @thispage @| @thischapter
@everyfooting @| @| Version: 0.27: @today{}

Beware of overlong titles: they may overlap another part of the header or footer and blot it out.

If you have very short chapters and/or sections, several of them can appear on a single page. You can specify which chapters and sections you want @thischapter, @thissection and other such macros to refer to on such pages as follows:

@everyheadingmarks ref

@everyfootingmarks ref

The ref argument can be either top (the @this... commands will refer to the chapter/section at the top of a page) or bottom (the commands will reflect the situation at the bottom of a page). These ‘@every...’ commands specify what to do on both even- and odd-numbered pages.

@evenheadingmarks ref

@oddheadingmarks ref

@evenfootingmarks ref

@oddfootingmarks ref

These ‘@even...’ and ‘@odd...’ commands specify what to do on only even- or odd-numbered pages, respectively. The ref argument is the same as with the ‘@every...’ commands.

Write these commands immediately after the @...contents commands, or after the @end titlepage command if you don’t have a table of contents or if it is printed at the end of your manual.

By default the @this... commands reflect the situation at the bottom of a page both in headings and in footings.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.