SysIII/usr/src/man/docs/mm_man/s09hdfo

.tr `\\
.H 1 "PAGE HEADERS AND FOOTERS"
Text that occurs at the top of each page is known as the
.I "page header" .
Text printed at the bottom of each page is called the
.I "page footer" .
There can be up to
three lines of text
associated with the header:
every page, even page only, and odd page only.
Thus the page header may have
up to
two lines of text:  
the line that occurs at the top of every page
and the line for the even- or odd-numbered page.
The same is true for the page footer.
.P
This section first describes the default 
appearance of page headers and page footers, and
then the ways of changing them.
We use
the term
.I header
.I (not
qualified by 
.I even
or
.I odd)
to mean the line of the page header that occurs on every page,
and similarly for the term
.I footer.
.H 2 "Default Headers and Footers
By default, each page has a centered page number as the header {9.2}.
There is no default footer and no even/odd default headers or footers,
except as specified in {9.9}.
.P
In a memorandum or a 
released paper,
the page header on the first page is automatically suppressed
.I provided
a break does 
.I not 
occur before \f3.\fPMT is called.
The macros and text of {6.9}
and of {9}
as well as \f3.\fPnr and \f3.\fPds requests
do
.I not
cause a break and
are permitted
before the \f3.\fPMT macro call.
.H 2 "Page Header
.Es1
\&\f3.\fPPH [arg]
.Ee
.P
For this and for the \f3.\fPEH, \f3.\fPOH, \f3.\fPPF, \f3.\fPEF, \f3.\fPOF macros,
the argument is of the form:
.Es1
\&"\^\'\^left-part\^\'\^center-part\^\'\^right-part\^\'\^"
.Ee1
If it is inconvenient 
to use the apostrophe (\^\'\^) as the delimiter
(i.e., because it occurs within one of the parts),
it may be replaced
.I uniformly
by
.I any 
other character.
On output, the parts are left-justified, centered, and right-justified, respectively.
See {9.11} for examples.
.P
The \f3.\fPPH macro specifies the 
header that is to appear at the top
of every page.
The initial value (as stated in {9.1}) is the default centered page number
enclosed by hyphens.
The page number contained in the
.I P
register is an Arabic number.  The format of the number may be
changed by the \f3.\fPaf request.
.P
If
.I "debug mode"
is set using the flag -rD1 on the command line {2.4},
additional information, printed at the top left of each page,
is included in the default header.
This consists of the SCCS\*(Rf
.RS JJ
Bonanni, L. E. and Salemi, C. A.
.I
The Source Code Control System User's Guide.
.R
Bell Laboratories,
April 1979.
.RF
Release and Level of
\*(PM 
(thus identifying the current version {12.3}),
followed by the current line number within the current input file.
.H 2 "Even-Page Header
.Es1
\&\f3.\fPEH [arg]
.Ee
.P
The \f3.\fPEH macro supplies a line to be printed
at the top of each even-numbered page,
immediately
.I following
the header.
The initial value is a blank line.
.H 2 "Odd-Page Header
.Es1
\&\f3.\fPOH [arg]
.Ee
.P
This macro is the same as \f3.\fPEH, except that it applies to odd-numbered pages.
.H 2 "Page Footer
.Es1
\&\f3.\fPPF [arg]
.Ee
.P
The \f3.\fPPF macro specifies the line that is to appear
at the bottom of each page.
Its initial value is a blank line.
If the -rC\f2n\fP flag is specified
on the command line {2.4},
the type of copy
.I follows
the footer on a separate line.
In particular, if -rC3 or -rC4 (DRAFT) is specified,
then, in addition,
the footer is initialized to contain the
date {6.7.1}, instead of being a blank line.
.H 2 "Even-Page Footer
.Es1
\&\f3.\fPEF [arg]
.Ee
.P
The \f3.\fPEF macro supplies a line to be printed at the bottom of
each even-numbered page,
immediately
.I preceding
the footer.
The initial value is a blank line.
.H 2 "Odd-Page Footer
.Es1
\&\f3.\fPOF [arg]
.Ee
.P
This macro is the same as \f3.\fPEF, except that it applies to odd-numbered pages.
.H 2 "Footer on the First Page"
By default,
the footer is a blank line.
If, in the input text, one specifies \f3.\fPPF and/or \f3.\fPOF before the
end of the first page of the document,
then these lines will appear at the bottom of the first page.
.P
The header (whatever its contents)
.I replaces
the footer
.I
on the first page only
.R
if the -rN1 flag is specified on the command line {2.4}.
.tr ``
.H 2 "Default Header and Footer with ``Section-Page'' Numbering
Pages can be numbered sequentially within sections
{4.5}.
To obtain this numbering style,
specify -rN3 or -rN5 on the command line.
In this case, the default
.I footer 
is a centered
\&``section-page'' number, e.g.\ 7-2,
and the default page header is blank.
.H 2 "Use of Strings and Registers in Header and Footer Macros \*(BU
String and register names may be placed in the arguments
to the header and footer macros.
If the value of the string or register is to be computed
.I
when the respective header or footer is printed,
.R
the invocation must be escaped by four (4) backslashes.
This is because the string or register invocation will be processed
three times:
.BL "" 1
.LI
as the argument to the header or footer macro;
.LI
in a formatting request within the header or footer macro;
.LI
in a
\&\f3.\fPtl
request during
header or footer processing.
.LE
.P
For example, the page number
register
.I P
must be escaped with four backslashes
in order to specify a header
in which the page number is to be printed at the right margin, e.g.:
.Es1
\&\f3.\fPPH "\^\'\^\'\^\'\^Page ````nP\^\'\^"
.tr `\\
.Ee1
.tr ``
creates a right-justified header containing the word
.tr ``
``Page'' followed by the page number.
Similarly, to specify a footer with the ``section-page'' style,
one specifies
(see {4.2.2.5} for meaning of
.I H1 \^):
.br
.tr `\\
.Es 1
\&\f3.\fPPF "\^\'\^\'\^\'- ````````n(H1-````````nP -\^\'\^"
.Ee
.P
.tr `\\
As another example,
suppose that the user arranges for the string
.I a]
to contain the current section heading
which is to be printed at the bottom of each page.
The \f3.\fPPF macro call would then be:
.Es1
\&\f3.\fPPF "\^\'\^\'````````\(**(a]\^\'\^\'\^"
.Ee
.tr ``
.P
If only one or two backslashes were used,
the footer would print a constant value for
.I a],
namely, its value 
when the \f3.\fPPF appeared in the input text.
.H 2 "Header and Footer Example \*(BU
The following sequence specifies
blank lines for the header and footer lines,
page numbers on the outside edge of each page
(i.e., top left margin of even pages
and top right margin of odd pages),
and ``Revision\ 3'' on the top inside margin of each page:
.br
.tr `\\
.Es1
\&\f3.\fPPH "\^"
\&\f3.\fPPF "\^"
\&\f3.\fPEH "\^\'\^````````nP\^\'\^\^\'\^Revision 3\^\'\^"
\&\f3.\fPOH "\^\'\^Revision 3\^\'\^\^\'\^````````nP\^\'\^"
.Ee
.tr ``
.H 2 "Generalized Top-of-Page Processing \*(BU"
.VL 4\"WARNING
.LI "\ \(rh"
.I
This section is intended only for users accustomed to writing
formatter macros.
.R
.LE
.P
During header processing,
\*(PM
invokes two user-definable macros.
One, the \f3.\fPTP macro,
is invoked in the environment (see \f3.\fPev request\*(II) of the header;
the other, \f3.\fPPX, is a user-exit macro that is invoked (without arguments)
when the normal environment has been restored, and with
``no-space'' mode already in effect.
.P
The effective
initial definition of \f3.\fPTP (after the first page of a document) is:
.Es1
.tr ``
\&\f3.\fPde TP
\&\f3.\fPsp 3
\&\f3.\fPtl ``\(**(\^}t
\&\f3.\fPif e \'tl ``\(**(\^}e
\&\f3.\fPif o \'tl ``\(**(\^}o
\&\f3.\fPsp 2
\&\f3.\|.\fP
.tr `\\
.Ee1
.tr ``
The string
.I  }t 
contains the header,
the string
.I  }e 
contains the even-page header,
and the string
.I  }o 
contains the odd-page header,
as defined by the \f3.\fPPH, \f3.\fPEH, and \f3.\fPOH macros, respectively.
To obtain more specialized page titles,
the user may redefine the \f3.\fPTP macro
to cause any desired header processing {12.5}.
Note that formatting done within the \f3.\fPTP macro
is processed in an environment different
from that of the body.
.P
For example,
to obtain a page header that includes three centered lines
of data, say, a document's number, issue date,
and revision date,
one could define \f3.\fPTP as follows:
.Es 1
\&\f3.\fPde TP
\&\f3.\fPsp
\&\f3.\fPce 3
777-888-999
Iss\f3.\fP 2, AUG 1977
Rev\f3.\fP 7, SEP 1977
\&\f3.\fPsp
\&\f3.\|.\fP
.Ee
.P
The \f3.\fPPX macro may be used to provide text that is to appear at the top
of each page after the normal header
and that may have tab stops to align it with columns
of text in the body of the document.
.H 2 "Generalized Bottom-of-Page Processing 
.Es 1
\&\f3.\fPBS
zero or more lines of text
\&\f3.\fPBE
.Ee
.P
Lines of text that are
specified between the \f3.\fPBS (bottom-block start)
and \f3.\fPBE (bottom-block end) macros
will be printed at the bottom of each page,\*F
.FS
The bottom block will appear on the table of contents pages and the
cover sheet for Memorandum for File, but
.I not
on the Technical Memorandum or Released Paper cover sheets.
.FE
after the footnotes (if any), but before the page footer.
This block of text is removed by specifying an empty
block, i.e.:
.Es 1
\&\f3.\fPBS
\&\f3.\fPBE
.Ee
.H 2 "Top and Bottom Margins"
.Es 1
\&\f3.\fPVM [top] [bottom]
.Ee
.P
\&\f3.\fPVM (Vertical Margin) allows the user to specify extra
space at the top and bottom of the page.
This space precedes the page header and
follows the page footer.
\&\f3.\fPVM takes two unscaled arguments that are treated as v's.
For example:
.Es 1
\&\f3.\fPVM 10 15
.Ee
adds 10 blank lines to the default top of page
margin, and 15 blank lines to the default bottom
of page margin.
Both
arguments must be positive (default
spacing at the top of the page may be decreased by
re-defining \f3.\fPTP).
.H 2 "Proprietary Markings"
.Es 1
\&\f3.\fPPM [code]
.Ee
.P
\&\f3.\fPPM, for Proprietary Marking, appends
to the page footer a PRIVATE, NOTICE,
BELL LABORATORIES PROPRIETARY, or
BELL LABORATORIES RESTRICTED
disclaimer.
The
.I code
may be:
.! tbl tbl-9.15
.P
The disclaimers are in a form approved for use
by the Bell System.
.H 2 "Private Documents"
.Es 1
\&\f3.\fPnr Pv value
.Ee
.P
The word
``PRIVATE'' may be printed
centered and underlined on the second line of a document
(preceding the page header).
This is done by setting the
.I Pv
register:
.! tbl tbl-9.16
.P
If
.I Pv
is 2, the user definable \f3.\fPTP may not be used
because
\&\f3.\fPTP is used by \*(PM to print PRIVATE on all pages
except the first page of a memorandum on which \f3.\fPTP is not invoked.
.tr ``