SysIII/usr/src/man/docs/mm_man/s07ks

.H 1 "DISPLAYS"
Displays are blocks of text that are
to be kept together\*(EMnot split across pages.
\*(Pm
provides two styles of
displays:\*F
.FS
Displays are processed in an environment that is different from
that of the body of the text
(see the \f3.\fPev request\*(II).
.FE
a
.I static
(\f3.\fPDS) style and a
.I floating 
(\f3.\fPDF) style.
In the
.I static
style,
the display appears in the same relative position
in the output text as it does in the input text;
this may result in extra white space at the bottom of the page if the
display is too big to fit there.
In the
.I floating
style,
the display ``floats'' through the input text to the top of the next page
if there is not enough room for it on the current page;
thus the input text that 
.I follows
a floating display may
.I precede
it in the output text.
A queue of floating displays
is maintained so that their relative order is 
not
disturbed.
.P
By default,
a display is processed in no-fill mode, with single-spacing, and is
.I not
indented from the existing margins.
The user can specify indentation or centering, as well as
fill-mode processing.
.P
Displays and footnotes {8}
may
.I never
be nested, in any combination whatsoever.
Although lists {5} and paragraphs {4.1} are permitted,
no headings (\f3.\fPH or \f3.\fPHU) {4.2, 4.3} can occur within 
displays or footnotes.
.H 2 "Static Displays
.Es1
\&\f3.\fPDS [format] [fill] [rindent]
\&one or more lines of text
\&\f3.\fPDE 
.Ee
.P
A static display is started by the \f3.\fPDS macro
and terminated by the \f3.\fPDE macro.
With no arguments, 
\&\f3.\fPDS will accept the lines of text exactly as they are typed
(no-fill mode) and will
.I not
indent them from the prevailing left margin indentation or from the right
margin.  The
.I rindent
argument is the number of characters\*F
.FS
This number must be unscaled in
.I nroff
and is treated as
.I ens .
It may be scaled in
.I troff
or else defaults to
.I ems .
.FE
that the line length should be decreased, i.e., an indentation from the
right margin.
.P
The
.I format
argument to \f3.\fPDS is an integer or letter used to control the left
margin indentation and centering
with the following meanings:
.! tbl tbl-7.1.a
.P
The
.I fill
argument is also an integer or letter and can have the following meanings:
.! tbl tbl-7.1.b
.P
Omitted arguments are taken to be zero.
.P
The standard amount of indentation
is taken from the register
.I Si ,
which is initially 5.
Thus, by default, the text of an indented display aligns with
the first line of indented paragraphs,
whose indent is contained in the
.I Pi
register {4.1}.
Even though their initial values are the same,
these two registers are independent of one another.
.P
.P
The display format value 3 (CB) centers the
.I "entire display"
as a block (as opposed
to \f3.\fPDS\ \|2 and \f3.\fPDF\ \|2, which center each line
.I  individually \^).
That is,
all the collected lines are left-justified,
and then the display is centered, 
based on the width of the longest line.
This format
.I must
be used in order for the
.I eqn \^(1)/\c
.I neqn \^(1)
``mark'' and ``lineup'' feature to work with centered equations
(see section 7.4 below).
.P
By default, a blank line (\*(12) is placed before and after static and floating
displays.
These blank lines before and after
.I static 
displays 
can be inhibited by setting the register
.I Ds
to 0.
.P
The following example shows the usage of all
three arguments for displays.
This block of text will be filled and
indented 5 spaces from both the left and the
right margins
(i.e., centered).
.Es 1
\&\f3.\fPDS I F 5
``We the people of the United States, in order to form a more perfect union,
establish justice, ensure domestic tranquility, provide for the common defense,
and secure the blessings of liberty to ourselves and our posterity,
do ordain and establish this Constitution to the
United States of America.''
\&\f3.\fPDE
.Ee
.H 2 "Floating Displays"
.Es1
\&\f3.\fPDF [format] [fill] [rindent]
one or more lines of text
\&\f3.\fPDE 
.Ee
.P
.nr c- \n(dl
A floating display is started by the \f3.\fPDF macro
and terminated by the \f3.\fPDE macro.
The arguments have the same meanings as for \f3.\fPDS {7.1}, except that, for
floating displays, indent, no indent, and centering are always
calculated with respect to the initial left margin,
because the prevailing indent may change between the time
when the formatter first reads the floating display and the
time that the display is printed.
One blank line (\*(12)
.I always 
occurs both before and after a floating display.
.P
The user may exercise great control over the output
positioning of floating displays through the use of 
two number registers, \f2De\f1 and \f2Df\f1.
When a floating display is encountered by
.I nroff
or
.I troff ,
it is processed and placed onto a queue of displays waiting
to be output.
Displays are always removed from the queue and printed in the
order that they were entered on the queue, which is the
order that they appeared in the input file.
If a new floating display is encountered and the queue of displays is empty,
then the new display is a candidate for immediate output on the current
page.
Immediate output is governed by the size of the display and the
setting of the \f2Df\f1 register (see below).
The \f2De\f1 register (see below) controls whether or
not text will appear on the current page after
a floating display has been produced.
.P
As long as the queue contains one or more displays,
new displays will be automatically entered there, rather
than being output.
When a new page is started (or the top of the
second column when in two-column mode)
the next display from the queue becomes a candidate for
output if the \f2Df\f1 register has specified ``top-of-page''
output.
When a display is output it is also removed from the queue.
.P
When the end of a section (when using section-page numbering)
or the end of a document is reached, all displays are
automatically removed from the queue and output.
This will occur before a \f3.\fPSG, \f3.\fPCS, or \f3.\fPTC is processed.
.P
A display is said to ``fit on the current page'' if there is enough
room to contain the entire display on the page, or if the display
is longer than one page in length and less than half of the
current page has been used.
Also note that a wide (full page width) display will never
fit in the second column of a two-column document.
.P
The registers, their settings, and their effects are as follows:
.! tbl tbl-7.2.a
.! tbl tbl-7.2.b
.P
The \f3.\fPWC macro {12.4} may also be used to control handling of
displays in double-column mode and to control the break in the text
before floating displays.
.H 2 Tables
.Es1
\&\f3.\fPTS [H]
global options;
column descriptors.
title lines
[.TH [N]]
data within the table.
\&\f3.\fPTE
.Ee
.P
The \f3.\fPTS (table start) and \f3.\fPTE (table end)
macros make possible the use of the
.I tbl \^(1)
processor\*(KK.
They are used
to delimit the text to be
examined by
.I tbl \^(1)
as well as to set proper spacing around the table.
The display function and the
.I tbl \^(1)
delimiting function are independent of one another,
however, so in order to permit
one to keep together
blocks that
contain any mixture of tables, equations, filled and unfilled text,
and caption lines
the \f3.\fPTS-\f3.\fPTE block should be enclosed
within a display (\f3.\fPDS-\f3.\fPDE).
Floating tables may be enclosed inside floating displays (\f3.\fPDF-\f3.\fPDE).
.P
The macros \f3.\fPTS and \f3.\fPTE also
permit the processing of
tables that extend
over several pages.
If a table heading is needed for each page of a multi-page
table, specify the argument
``H'' to the \f3.\fPTS macro as above.
Following the options and format information,
the table heading is typed on as many lines as required
and followed by the \f3.\fPTH macro.
The \f3.\fPTH macro
.I must
occur when ``\f3.\fPTS\ \|H'' is used.
Note that this is 
.I not
a feature of 
.I tbl (1),
but of the macro definitions provided by \*(PM.
.P
The table header macro \f3.\fPTH may take as an argument the letter \f3N\fP.
This argument causes the table header to be printed only if it is the
first table header on the page.
This option is used when it is necessary to build
long tables from smaller \f3.\fPTS~H\^/\^\f3.\fPTE segments.
For example:
.Es
\&\f3.\fPTS H
global options;
column descriptors.
Title lines
\&\f3.\fPTH
data
\&\f3.\fPTE
\&\f3.\fPTS H
global options;
column descriptors.
Title lines
\&\f3.\fPTH N
data
\&\f3.\fPTE
.Ee
will cause the table heading to appear at the top of the first table segment,
and no heading to appear at the top of the second segment when both appear
on the same page.
However, the heading will still appear at the top of each page that
the table continues onto.
This feature is used when a single table
must be broken into segments because
of table complexity (for example, too many blocks of filled text).
If each segment had its own \f3.\fPTS~H\^/\^\f3.\fPTH sequence,
each segment would have its own header.
However, if each table segment after
the first uses \f3.\fPTS~H\^/\^\f3.\fPTH~N
then the table header will only appear
at the beginning of the table and the top
of each new page or column that the table continues onto.
.P
For
.I nroff ,
the -e option (-E for
.I mm \^(1)
{2.1}) may be used for terminals, such as the 450, that are capable of
finer printing resolution.  This will cause better alignment of features
such as the lines forming the corner of a box.  Note that -e is not
effective with
.I col \^(1).
.H 2 Equations
.Es1
\&\f3.\fPDS
\&\f3.\fPEQ [label]
equation(s)
\&\f3.\fPEN
\&\f3.\fPDE
.Ee
.P
The equation setters
.I eqn \^(1)
and
.I neqn \^(1)
\*(FF\^\*(GG
expect to use the \f3.\fPEQ (equation start) and \f3.\fPEN (equation end)
macros as delimiters in the same way that
.I tbl \^(1)
uses \f3.\fPTS and \f3.\fPTE;
however, \&\f3.\fPEQ and \f3.\fPEN
must occur inside a \f3.\fPDS-\f3.\fPDE pair.
.VL 4\"WARNING
.LI "\ \(rh"
.I
There is an exception to this rule:
if \f3.\fPEQ and \f3.\fPEN are used only to specify
the delimiters for in-line equations
or to specify
.R
eqn/neqn
.I
``defines,''
.I
\&\f3.\fPDS and \f3.\fPDE must 
.R
not
.I
be used;
otherwise extra blank lines will appear in the output.
.R
.LE
.P
The .EQ macro takes an argument that will be used
as a label for the equation.
By default, the label will appear at the right margin in the ``vertical center''
of the general equation.  The
.I Eq
register may be set to 1 to change the labeling to the left margin.
.P
The equation will be centered for centered displays; otherwise the equation
will be adjusted to the opposite margin from the label.
.if t .ne5
.H 2 "Figure, Table, Equation, and Exhibit Captions"
.Es1
.ta .4i
\&\f3.\fPFG	[title] [override] [flag]
\&\f3.\fPTB	[title] [override] [flag]
\&\f3.\fPEC	[title] [override] [flag]
\&\f3.\fPEX	[title] [override] [flag]
.Ee
.P
The \f3.\fPFG (Figure Title),
\&\f3.\fPTB (Table Title),
\&\f3.\fPEC (Equation Caption)
and \f3.\fPEX (Exhibit Caption)
macros are
normally used inside \f3.\fPDS-\f3.\fPDE
pairs to automatically number and title
figures, tables,
and equations.
They use registers
.I Fg,
.I Tb,
.I Ec,
and
.I Ex,
respectively (see {2.4} on -rN5 to reset counters in sections).
As an example, the call:
.Es 1
\&\f3.\fPFG "This is an illustration"
.Ee 1
yields:
.DS 1
.FG "This is an illustration"
.DE
.P
\&\f3.\fPTB replaces ``\f3Figure\fP'' by ``\f3TABLE\fP'';
\&\f3.\fPEC replaces ``\f3Figure\fP'' by ``\f3Equation\fP'',
and \f3.\fPEX replaces ``\f3Figure\fP'' by ``\f3Exhibit\fP''.
Output is centered if it can fit on a single line;
otherwise, all lines but the first are indented to line up
with the first character of the title.
The format of the numbers may be changed using the \f3.\fPaf request
of the formatter.  The format of the caption may be changed from
``Figure\ 1.\ Title'' to ``Figure\ 1\ -\ Title'' by setting
the
.I Of
register to 1.
.P
The
.I override
string is used to modify the normal numbering.
If
.I flag
is omitted or 0,
.I override
is used as a prefix to the number;
if
.I flag
is 1,
.I override 
is used as a suffix;
and if
.I flag
is 2,
.I override
replaces the number.
If -rN5 {2.4} is given, ``section-figure'' numbering is set
automatically and user-specified
.I override
string is ignored.
.P
As a matter of style, table headings 
are usually placed ahead of
the text of the tables,
while figure, equation, and exhibit captions usually occur
after the corresponding figures and equations.
.H 2 "List of Figures, Tables, Equations, and Exhibits"
A List of Figures, List of Tables, List of Exhibits, and
List of Equations may be obtained.
They will be printed after the Table of Contents is printed
if the number registers
.I Lf ,
.I Lt ,
.I Lx ,
and
.I Le
(respectively) are set to 1.
.I Lf ,
.I Lt ,
and
.I Lx
are 1 by default;
.I Le
is 0 by default.
.P
The titles of these Lists may be changed by redefining the following
strings which are shown here with their default values:
.Es 1
\&\f3.\fPds Lf LIST OF FIGURES
\&\f3.\fPds Lt LIST OF TABLES
\&\f3.\fPds Lx LIST OF EXHIBITS
\&\f3.\fPds Le LIST OF EQUATIONS
.Ee