SysIII/usr/src/man/docs/mm_man/s04head

.hc ^
.tr ~
.tr ``
.H 1 "PARAGRAPHS AND HEADINGS
This section describes simple paragraphs and section headings.
Additional paragraph and list styles are covered in {5}.
.H 2 "Paragraphs
.Es1
\&\f3.\fPP [type]
one or more lines of text.
.Ee
.P
This macro is used to begin
two kinds of paragraphs.
In a
.I "left-justified"
paragraph,
the first line begins at the left margin,
while in an
.I "indented"
paragraph,
it is
indented five spaces (see below).
.P 
A document possesses a
.I "default paragraph style" 
obtained by specifying ``\f3.\fPP''
before each paragraph
that does
.I not
follow a heading {4.2}.
The default style
is controlled by the register
.I Pt .
The initial value of
.I Pt
is 0, which always provides
left-justified paragraphs.
All paragraphs
can be forced to be indented by inserting the following at the
beginning of the document:
.Es1
\&\f3.\fPnr Pt 1
.Ee
.P
All paragraphs will be indented except after headings, lists,
and displays if the following:
.Es1
\&\f3.\fPnr Pt 2
.Ee
is inserted at the beginning of the document.
.P
The amount a paragraph is indented is contained
in the register
.I Pi ,
whose default
value is 5.
To indent paragraphs by, say, 10 spaces, insert:
.Es1
\&\f3.\fPnr Pi 10
.Ee
at the beginning of the document.
Of course, both the
.I Pi
and
.I Pt
register values
must be greater than zero for any paragraphs to be indented.
.P
The number register
.I Ps
controls the amount of spacing between paragraphs.
By default,
.I Ps
is set to 1,
yielding one blank space (\(12 a vertical space).
.VL 4\"WARNING
.LI "\ \(rh"
.I
Values that specify indentation must be
.R
unscaled
.I
and are treated as ``character positions,''
i.e., as a number of
.R
ens.
.I In
troff,
.I an
en
.I
is the number of points (1 point = 1/72 of an inch)
equal to half the current point size.
In
.R
nroff,
.I an
en
.I
is equal to the width of a character.
.R
.LE
.P
Regardless of the value of
.I Pt,
an
.I individual 
paragraph can be forced to be left-justified or indented.
``\f3.\fPP\ \|0'' always forces left justification;
``\f3.\fPP\ \|1'' always causes indentation by the amount specified by the register
.I Pi.
.P 
If \f3.\fPP occurs inside a
.I list,
the indent (if any) of the paragraph is added to the
current list indent {5}.
.P
Numbered paragraphs may be produced by setting the register
.I Np
to 1.  This produces paragraphs numbered within first level headings, e.g.,
1.01, 1.02, 1.03, 2.01, etc.
.P
A different style of numbered paragraphs is obtained by using the
.Es 1
\&\f3.\fPnP
.Ee
macro rather than the \f3.\fPP macro for paragraphs.  This produces
paragraphs that are numbered within second level headings and contain
a ``double-line indent'' in which the text of the second line is indented
to be aligned with the text of the first line so that the number stands
out.  
.Es 1
\&\f3.\fPH 1 "FIRST HEADING"
\&\f3.\fPH 2 "Second Heading"
\&\f3.\fPnP
one or more lines of text
.Ee
.H 2 "Numbered Headings
.Es1
\&\f3.\fPH level [heading-text] [heading-suffix]
zero or more lines of text
.Ee
.P
The \f3.\fPH macro provides seven levels 
of numbered headings, as illustrated by this document.
Level 1 is the most major or highest; level 7 the lowest.
.P
The
.I heading-suffix
is appended to the
.I heading-text
and may be used for footnote marks which should not appear with
the heading text in the Table of Contents.
.VL 4\"WARNING
.LI "\ \(rh"
.I
There is no need for a \f3.\fPP macro after a \f3.\fPH
(or \f3.\fPHU
.R
{4.3}\c
.I
), because the
\&\f3.\fPH macro also performs the function of the \f3.\fPP macro.
In fact, if a \f3.\fPP follows a \f3.\fPH, the \f3.\fPP is ignored.
.R
{4.2.2.2}.
.LE
.H 3 "Normal Appearance
The normal appearance of headings is as shown in
this document.
The effect of \f3.\fPH varies according to the
.I level
argument.
First-level headings are
.I preceded 
by two blank lines (one vertical space);
all others are
.I  preceded 
by one blank line (\*(12).
.VL 20
.LI "\f3.\fPH\ \|1\ \|heading-text"
gives a bold heading
.I followed
by a single blank line (\*(12).
The following text begins 
on a new line and is indented according to the current paragraph type.
.if t .ne4
Full capital letters should normally be used 
to make the heading stand out.
.LI "\f3.\fPH\ \|2\ \|heading-text"
yields a bold heading
followed by a single blank line (\*(12).
The following text begins on a new line
and is indented according to the current paragraph type.
Normally, initial capitals are used.
.LI "\f3.\fPH\ \|\f2n\fP\ \|heading-text"
for 3\|\(<=\|\f2n\fP\|\(<=\|7,
produces an underlined (italic) heading followed
by two spaces.
The following text appears on the same line, i.e.,
these are
.I run-in
headings.
.LE
.P
Appropriate numbering and spacing (horizontal and vertical) occur 
even if the heading text is omitted from a \f3.\fPH macro call.
.P
Here are the first few \f3.\fPH calls of {4}:
.Es1
\&\f3.\fPH 1 "PARAGRAPHS AND HEADINGS"
\&\f3.\fPH 2 "Paragraphs"
\&\f3.\fPH 2 "Numbered Headings"
\&\f3.\fPH 3 "Normal Appearance."
\&\f3.\fPH 3 "Altering Appearance of Headings."
\&\f3.\fPH 4 "Pre-Spacing and Page Ejection."
\&\f3.\fPH 4 "Spacing After Headings."
\&\f3.\fPH 4 "Centered Headings."
\&\f3.\fPH 4 "Bold, Italic, and Underlined Headings."
\&\f3.\fPH 5 "Control by Level."
.Ee
.H 3 "Altering Appearance of Headings"
Users satisfied with the default appearance of
headings may skip to {4.3}.
One can modify the appearance of headings quite easily
by setting certain registers and strings at the beginning of the document.
This permits quick alteration of a document's style,
because this style-control information is concentrated in a few lines,
rather than being distributed throughout the document.
.H 4 "Pre-Spacing and Page Ejection"
A first-level heading normally has two blank lines (one vertical space) preceding it,
and all others have one blank line (\*(12).
If a multi-line heading were to be split across pages,
it is automatically moved to the top of the next page.
Every first-level heading may be forced to the top of a new page by inserting:
.Es1
\&\f3.\fPnr Ej 1
.Ee1
at the beginning of the document.
Long documents may be made more manageable if each section starts on a
new page.
Setting
.I Ej
to a higher value causes the same effect for headings up to that level,
i.e., a page eject occurs if the heading level is less than or equal to
.I Ej .
.H 4 "Spacing After Headings"
Three registers control the appearance of text immediately following a \f3.\fPH call.
They are
.I Hb
(heading break level),
.I Hs
(heading space level), and
.I Hi
(post-heading indent).
.P
If the heading level is less than or equal to
.I Hb ,
a break {3.1} occurs after the heading.
If the heading level is less than or equal to
.I Hs ,
a blank line (\*(12) is inserted after the heading.
Defaults for
.I Hb
and
.I Hs
are 2.
If a heading level is greater than
.I Hb
and also greater than
.I Hs ,
then the heading (if any) is run into the following text.
.if t .ne5
These registers permit headings to be separated from the text in a consistent
way throughout a document,
while allowing easy alteration of white space
and heading emphasis.
.P
For any
.I stand-alone
heading, i.e., a heading not run into the following text,
the alignment of the next line of output is controlled
by the register
.I Hi .
If
.I Hi
is 0, text is left-justified.
If
.I Hi
is 1 (the 
.I default 
value),
the text is indented according to the paragraph type 
as specified by the register
.I Pt
{4.1}.
Finally, if
.I Hi
is 2, text is indented to line up with the first word of the heading itself,
so that the heading number stands out more clearly.
.P
For example, to cause a blank line (\*(12) to appear after
the first three heading levels,
to have no run-in headings,
and to force the text following all headings to be left-justified
(regardless of the value of
.I Pt \^),
the following should appear at the top of the document:
.Es 1
.ta .5i
\&\f3.\fPnr Hs	3
\&\f3.\fPnr Hb	7
\&\f3.\fPnr Hi	0
.Ee
.H 4 "Centered Headings"
The register
.I Hc
can be used to obtain centered headings.
A heading is centered if its level
is less than or equal to
.I Hc ,
.I and
if it is also stand-alone {4.2.2.2}.
.I Hc
is 0 initially (no centered headings).
.H 4 "Bold, Italic, and Underlined Headings"
\&
.H 5 "Control by Level"
Any heading that is 
underlined by
.I nroff
is made italic by
.I troff.
The string
.I HF
(heading font) contains seven codes that specify the fonts for heading
levels 1-7.
The legal codes, their interpretations, and the defaults for
.I HF 
are:
.! tbl tbl-4.2.2.4
.P
Thus,
levels 1 and 2 are bold; levels 3 through 7 are underlined in
.I nroff
and italic in
.I troff .
The user may reset HF as desired.
Any value omitted from the
right end of the list is taken to be 1.
For example, the following
would result in five bold levels
and two non-underlined (roman) levels:
.Es 1
\&\f3.\fPds HF 3 3 3 3 3
.Ee
.H 5 "Nroff Underlining Style"
.I Nroff
can underline in two ways.
The normal style (\c
\&\f3.\fPul
request) is to underline only letters and digits.
The continuous style (\c
\&\f3.\fPcu
request) underlines all characters, including spaces.
By default,
\*(PM
attempts to use the
continuous style on any
heading that is to be underlined
and is short enough to fit on
a single line.
If a heading is to be underlined, but is too long,
it is underlined the normal way
(i.e., only letters and digits are underlined).
.P
All underlining of headings
can be forced to the normal way by using the -rU1 flag when invoking
.I nroff
{2.4}.
.H 5 "Heading Point Sizes."
The user may also specify the desired point size
for each heading level with the \f2HP\fP string
(for use with
.I troff
only).
.Es 1
\&\f3.\fPds HP [ps1] [ps2] [ps3] [ps4] [ps5] [ps6] [ps7]
.Ee
.P
By default,
the text of headings (\f3.\fPH and \f3.\fPHU)
is printed in the same point size as the body
.I except
that bold stand-alone headings are printed in a size one point smaller than the body.
The string
.I HP,
similar to the string
.I HF,
can be specified to contain up to seven values,
corresponding to the seven levels of headings.
For example:
.Es 1
\&\f3.\fPds HP 12 12 10 10 10 10 10
.Ee 1
specifies that the  first and second level headings are to be printed in 12-point type,
with the remainder printed in 10-point.
Note that the specified values may also be
.I relative
point-size changes, e.g.:
.Es 1
\&\f3.\fPds HP +2 +2 -1 -1
.Ee 1
If absolute point sizes are specified,
then those sizes will be used regardless of the point size
of the body of the document.
If relative point sizes are specified,
then the point sizes for the headings will be relative to the
point size of the body,
even if the latter is changed.
.P
Omitted or zero values
imply that the
.I default
point size will be used
for the corresponding heading level.
.VL 3\"WARNING
.ie t .LI "\ \(rh"
.el .LI =>
.I
Only the point size of the headings is affected.
Specifying a large point size without providing
increased vertical spacing (via \f3.\fPHX and/or \f3.\fPHZ)
may cause overprinting.
.R
.LE
.H 4 "Marking Styles\*(EMNumerals and Concatenation"
\&
.Es 1
\&\f3.\fPHM [arg1] \f3.\|.\|.\fP [arg7]
.Ee
.P
The registers named
.I H1
through
.I H7
are used as counters for the seven levels of headings.
Their values are normally printed using Arabic numerals.
The \f3.\fPHM macro (heading mark style) allows this choice to be overridden,
thus providing ``outline'' and other document styles.
This macro can have up to seven arguments;
each argument
is a string indicating the
type of marking to be used.
Legal values and their meanings are shown below;
omitted values are interpreted as 1, while illegal values
have no effect.
.! tbl tbl-4.2.2.5
.P
By default,
the complete heading mark for a given level is built by concatenating
the mark for that level to the right of all marks for all levels of higher
value.
To inhibit the concatenation of heading level marks,
i.e., to obtain just the current level mark
followed by a period,
set the register
.I Ht
(heading-mark type) to 1.
.P
For example, a commonly-used ``outline'' style is obtained by:
.Es 1
\&\f3.\fPHM I A 1 a i
\&\f3.\fPnr Ht 1
.Ee
.H 2 "Unnumbered Headings"
.Es1
\&\f3.\fPHU heading-text
.Ee
.P 
\&\f3.\fPHU is a special case of \f3.\fPH; it is handled in the same way
as \f3.\fPH,
except that no heading mark is printed.
In order to preserve the hierarchical structure of headings
when \f3.\fPH and \f3.\fPHU calls are intermixed,
each \f3.\fPHU heading is considered to exist at the level given by register
.I Hu ,
whose initial value is 2.
Thus, in the normal case, the only difference between:
.Es1
\&\f3.\fPHU heading-text
.ie t .sp .5
.el .sp
and
.ie t .sp .5
.el .sp
\&\f3.\fPH 2 heading-text
.Ee1
is the printing of the heading mark for the latter.
Both have the effect of incrementing the numbering counter for level 2,
and resetting to zero the counters for levels 3 through 7.
Typically, the value of
.I Hu
should be set to make unnumbered headings (if any) be the lowest-level
headings in a document.
.P
\&\f3.\fPHU can be especially helpful in setting up Appendices and other
sections that may not fit well into the numbering scheme
of the main body of a document
{14.2.1}.
.H 2 "Headings and the Table of Contents"
The text of headings and their corresponding page numbers
can be automatically collected for a table of contents.
This is accomplished by 
doing the following two things:
.BL "" 1
.LI
specifying in the register
.I Cl
what level headings
are to be saved
.LI
invoking the \f3.\fPTC macro {10.1}
at the end of the document
.LE
.P
Any heading whose level is less than or equal to
the value of the register
.I Cl
(contents level)
is saved and later displayed in the table of contents.
The default value for
.I Cl
is 2, i.e., the first two levels of headings are saved.
.P
Due to the way the headings are saved, it is possible to exceed
the formatter's storage capacity,
particularly when saving many levels of many headings, while also processing
displays {7} and footnotes {8}.
If this happens, the ``Out of temp file space'' diagnostic {Appendix\ D}
will be issued;
the only remedy is to save fewer levels and/or
to have fewer words in the heading text.
.H 2 "First-Level Headings and the Page Numbering Style"
By default, pages are numbered sequentially
at the top of the page.
For large documents, it may be desirable to use page numbering
of the form
``section-page,'' where
.I section 
is the number of the current first-level heading.
This page numbering style can be achieved by 
specifying the -rN3 or -rN5 flag on the command line
{9.9}.
As a side effect,
this also has the effect of setting
.I Ej
to 1, i.e., each section begins on a new page.
In this style, the page number is printed at the
.I bottom
of the page, so that the correct
section number is printed.
.H 2 "User Exit Macros \*(BU"
.VL 4\"WARNING
.LI "\ \(rh"
.I
This section is intended only for users who are accustomed to
writing formatter macros.
.R
.LE
.Es 1
\&\f3.\fPHX dlevel rlevel heading-text
\&\f3.\fPHY dlevel rlevel heading-text
\&\f3.\fPHZ dlevel rlevel heading-text
.Ee
.P
.P
The \&\f3.\fPHX, \f3.\fPHY, and \f3.\fPHZ macros
are the means by which the user obtains a
final level of control 
over the previously-described heading mechanism.
\*(Pm
does not define \f3.\fPHX, \f3.\fPHY, and \f3.\fPHZ;
they are intended to be defined by the user.
The
\&\f3.\fPH macro invokes \f3.\fPHX shortly before the actual heading text is printed;
it calls \f3.\fPHZ as its last action.
After \f3.\fPHX is invoked, the size of the heading is calculated.  This
processing causes certain features that may have been included in \f3.\fPHX,
such as \f3.\fPti for temporary indent, to be lost.  After the size
calculation, \f3.\fPHY is invoked so that the user may respecify these
features.
All the default actions occur if these macros are not defined.
If the \f3.\fPHX, \f3.\fPHY, or \f3.\fPHZ are defined by the user,
the user-supplied definition is interpreted at the appropriate point.
These macros can therefore influence the
handling of all headings, because the ^\f3.\fPHU macro is actually
a special case of the \f3.\fPH macro.
.P
If the user originally invoked the \f3.\fPH macro,
then the derived level (\c
.I dlevel \^)
and the real level (\c
.I rlevel \^)
are both equal to the level given in the \f3.\fPH invocation.
If the user originally invoked the \f3.\fPHU macro {4.3},
.I dlevel
is equal to the contents of register
.I Hu ,
and
.I rlevel
is 0.
In both cases,
.I heading-text
is the text of the original invocation.
.P
By the time \f3.\fPH calls \f3.\fPHX, it has already incremented the 
heading counter of the specified level {4.2.2.5},
produced blank line(s) (vertical space) to precede the heading {4.2.2.1},
and accumulated the ``heading mark'', i.e., the string of digits, letters,
and periods needed for a numbered heading.
When \f3.\fPHX is called, all user-accessible registers and strings can be referenced,
as well as the following:
.VL 15
.LI "string\ }0"
If
.I rlevel
is non-zero,
this string contains the
``heading mark.''\ 
Two unpaddable
spaces (to separate the
.I mark 
from the
.I heading \|)
have been appended to this string.
If
.I rlevel
is 0,
this string is null.
.LI "register\ ;0"
This register indicates the type of spacing that is to follow the heading
{4.2.2.2}.
A value of 0 means that the heading is run-in.
A value of
1 means a break (but no blank line) is to follow the heading.
A value of
2 means that a blank line (\*(12) is to follow the heading.
.LI "string\ }2"
If register ;0 is 0,
this string contains two unpaddable spaces that will be used to separate
the (run-in)
.I heading 
from the following
.I text.
If register ;0 is non-zero, this string is null.
.LI "register\ ;3"
This register contains 
an adjustment factor for a
\&\f3.\fPne
request issued before the heading is actually printed.
On entry to \f3.\fPHX, it has the value 3 if
.I dlevel
equals 1, and 1 otherwise.
The
\&\f3.\fPne
request is for the following number of lines:
the contents of the register ;0 taken as blank lines
(halves of vertical space)
plus
the contents of register ;3 as blank lines
(halves of vertical space)
plus
the number of lines of the heading.
.LE
.P
The user may alter the values of
.I }0 ,
.I }2 ,
and
.I ;3\|
within \f3.\fPHX
as desired.
The following are examples of actions that might be
performed by defining \f3.\fPHX to include the lines shown:
.tr `\\
.Es 1
Change first-level heading mark from format \f2n\fP\f3.\fP to \f2n\fP\f3.\fP0:
\&\f3.\fPif ````$1=1 \f3.\fPds }0 ````n(H1\f3.\fP0``\(sq``\(sq\c
.sp-1
.tl |||(\(sq stands for a space)|
.ie t .sp .5
.el .sp
Separate run-in heading from the text with a period and two unpaddable spaces:
\&\f3.\fPif ````n(\f3;\fP0=0 \f3.\fPds }2 \f3.\fP``\(sq``\(sq
.ie t .sp .5
.el .sp
Assure that at least 15 lines are left on the page before printing a first-level heading:
\&\f3.\fPif ````$1=1 \f3.\fPnr \f3;\fP3 15-````n(\f3;\fP0
.ie t .sp .5
.el .sp
Add 3 additional blank lines before each first-level heading:
\&\f3.\fPif ````$1=1 \f3.\fPsp 3
'	.sp
'	Make varying indent for outline style:
'	.in ````$1*2-2
.ie t .sp .5
.el .sp
Indent level 3 run-in headings by 5 spaces:
\&\f3.\fPif ````$1=3 \f3.\fPti 5n
.Ee
.tr ``
.P
If temporary string or macro names are used within \f3.\fPHX,
care must be taken in the choice of their names {14.1}.
.P
\&\f3.\fPHY is called after the .ne is issued.  Certain features
requested in \f3.\fPHX must be repeated.  For example:
.Es 1
\&\f3.\fPde HY
\&\f3.\fPif \e\e$1=3 \f3.\fPti 5n
\&\f3.\|.\fP
.Ee
.P
\&\f3.\fPHZ is called at the end of \f3.\fPH to permit user-controlled actions after
the heading is produced.
For example, in a large document, sections may correspond to chapters of
a book, and the user may want to
change a page header or footer.
For example:
.tr `\\
.Es 1
\&\f3.\fPde HZ
\&\f3.\fPif ````$1=1 \f3.\fPPF "\^\'\^\'\^Section ````$3\^\'\^\'\^"
\&\f3.\|.\fP
.Ee
.tr ``
.H 2 "Hints for Large Documents"
A large document is often organized for convenience into one file per section.
If the files are numbered,
it is wise to use enough digits in the names of these files for
the maximum number of sections,
i.e., use suffix numbers 01 through 20 rather than 1 through 9 and 10 through 20.
.P
Users often want to format individual sections of long documents.
To do this with the correct section numbers, it is necessary to set register
.I H1
to 1 less than the number of the
section just
.I before 
the corresponding ``\f3.\fPH 1'' call.
For example, at the beginning of section 5, insert:
.Es 1
\&\f3.\fPnr H1 4
.Ee
.tr ~~
.VL 4\"WARNING
.LI "\ \(rh"
.I
This is a dangerous practice:
it defeats the automatic (re)numbering of sections
when sections are added or deleted.
Remove such lines
as soon as possible.
.R
.LE