Appendix 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.)

* Headings Introduced::         Conventions for using page headings.
* Heading Format::              Standard page heading formats.
* Heading Choice::              How to specify the type of page heading.
* Custom Headings::             How to create your own headings and footings.

Headings Introduced
-------------------
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.1 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.2 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.3 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.

@thischaptername
Expands to the name of the current chapter.

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


