SysIII/usr/src/man/docs/mm_man/s10toc

.H 1 "TABLE OF CONTENTS AND COVER SHEET
The table of contents and the
cover sheet for a document
are produced by 
invoking the \f3.\fPTC and \f3.\fPCS macros, respectively.
.VL 4\"WARNING
.LI "\ \(rh"
.I
This section will refer to cover sheets for Technical Memoranda
and Released Papers only.  The mechanism for producing a Memorandum
for File cover sheet was discussed earlier {6.4}.
.R
.LE
.P
These macros should normally appear only once at the
.I end 
of the document,
after the Signature Block {6.11.1} and Notations {6.11.2} macros.
They may occur in either order.
.P
The table of contents is produced at the end of the document
because the entire document must be processed before the
table of contents can be generated.
Similarly, the cover sheet is often not needed,
and is therefore produced at the end.
.H 2 "Table of Contents"
.Es1
\&\f3.\fPTC [slevel] [spacing] [tlevel] [tab] [head1] [head2] [head3] [head4] [head5]
.Ee
.P
The \f3.\fPTC macro generates a table of contents containing the headings
that were
saved for the table of contents
as determined by the value of the
.I Cl
register {4.4}.
The arguments to \f3.\fPTC control the spacing before each entry,
the placement of the associated page number,
and additional text on the first page
of the table of contents
before the word ``CONTENTS.''\ 
.P
Spacing before each entry is controlled by the first two arguments;
headings whose level is less than or equal to 
.I slevel
will have
.I spacing
blank lines (halves of a vertical space) before them.
Both
.I slevel
and
.I spacing
default to 1.
This means that first-level headings are preceded by one blank line
(\*(12).
Note that
.I slevel
does
.I not
control what levels of heading have been saved;
the saving of headings is the function of the
.I Cl
register {4.4}.
.P
The third
and fourth
arguments control the placement of the page number
for each heading.
The page numbers can be justified at the right margin with either blanks
or dots (``leaders'') separating the heading text from the page number,
or the page numbers can follow the heading text.
For headings whose level is less than or equal to
.I tlevel
(default 2),
the page numbers are justified at the right margin.
In this case,
the value of 
.I tab
determines the character used to separate the heading text from the page number.
If
.I tab
is 0 (the default value),
dots (i.e., leaders) are used;
if
.I tab
is greater than 0, spaces are used.
For headings whose level is greater than
.I tlevel,
the page numbers are separated from the heading text by
two spaces (i.e., they are ``ragged right'').
.P
All additional arguments
(e.g., 
.I head1 ,
.I head2 ,
etc.), if any,
are horizontally centered on the page, and precede the actual
table of contents itself.
.P
If the \f3.\fPTC macro is invoked with at most four arguments,
then the user-exit macro \f3.\fPTX
is invoked (without arguments) before the word ``CONTENTS'' is printed;
or the user-exit macro \f3.\fPTY is invoked and the word ``CONTENTS'' is
.I not
printed.
By defining \f3.\fPTX or \f3.\fPTY and invoking
\&\f3.\fPTC with at most four arguments, the user can specify
what needs to be done at the top of the (first) page of the table of contents.
For example,
the following input:
.Es 1
\&\f3.\fPde TX
\&\f3.\fPce 2
Special Application
Message Transmission
\&\f3.\fPsp 2
\&\f3.\fPin +10n
Approved: `l\^\'\^3i\^\'
\&\f3.\fPin
\&\f3.\fPsp
\&\f3.\|.\fP
\&\f3.\fPTC
.tr `\\
.Ee
.tr ``
.P
yields:
.DS
.ce 2
Special Application
Message Transmission
.sp2
.in +10n
Approved:\ \l'3i'
.in -10n
.sp
.ce99
CONTENTS
\&\f3.\fP
.sp -.5
\&\f3.\fP
.sp -.5
\&\f3.\fP
.ce0
.DE
.P
If this macro were defined as \f3.\fPTY rather than \f3.\fPTX,
the word ``CONTENTS'' would not appear.  Defining \f3.\fPTY as an
empty macro will suppress ``CONTENTS'' with no replacement:
.Es 1
\&\f3.\fPde TY
\&\f3.\|.\fP
.Ee
.P
By default, the first level headings will appear in the table of contents
at the left margin.  Subsequent levels will be aligned with the text of
headings at the preceding level.  These indentations may be changed by
defining the
.I Ci
string which takes a maximum of seven arguments corresponding to the
heading levels.  It must be given at least as many arguments as are set
by the
.I Cl
register.  The arguments must be scaled.  For example,
with
.I Cl =5,
.Es 1
\&\f3.\fPds Ci \f3.\fP25i \f3.\fP5i \f3.\fP75i 1i 1i
.Ee
or
.Es 1
\&\f3.\fPds Ci 0 2n 4n 6n 8n
.Ee
.P
Two other registers are available to modify the format of the table of
contents,
.I Oc " and " Cp .
By default,
table of contents pages will have lowercase Roman numeral page numbering.
If the
.I Oc
register
is set to 1,
the \f3.\fPTC macro will not print any page number but will instead
reset the
.I P
register to 1.  It is the user's responsibility to give an appropriate
page footer to place the page number.  Ordinarily the same \f3.\fPPF
used in the body of the document (e.g., OSDD style) will be
adequate.
.P
The List of Figures, Tables,
etc. pages will be produced separately unless
.I Cp
is set to 1 which causes these lists to appear on the same page as the
table of contents.
.H 2 "Cover Sheet
.Es1
\&\f3.\fPCS [pages] [other] [total] [figs] [tbls] [refs]
.Ee
.P
The \f3.\fPCS macro generates a cover sheet
in either the TM or released-paper style.
See {6.4} for details on the Memorandum for File style cover sheet.
All of the other information for the cover sheet
is obtained from the data given before the \f3.\fPMT macro call
{6.9}.
If a TM style is used, the \f3.\fPCS macro
generates the ``Cover Sheet for Technical Memorandum.''
The data that appears
in the lower left corner of the TM cover sheet\*(BB
(the number of pages of text,
the number of
other pages,
the total number of pages,
the number of figures,
the number of tables,
and the number of references)
is generated automatically.  These values may be changed by
supplying the appropriate arguments to the \f3.\fPCS macro.
Any values that are omitted will be calculated automatically
(0 is used for other pages).
If the released-paper style is used,
all arguments to \f3.\fPCS are ignored.