SysIII/usr/src/man/docs/mm_man/s02invok

.H 1 "INVOKING THE MACROS"
This section tells how to access
\*(PM,
shows \*(PU command lines appropriate for
various output devices,
and describes command-line flags for
\*(PM.
.H 2 "The mm Command"
The
.I mm \^(1)
command can be used to print documents using
.I nroff
and \*(PM;
this command invokes
.I nroff
with the -cm flag {2.2}.
It has options to specify
preprocessing by 
.I tbl \^(1)
and/or by
.I neqn \^(1),
and for postprocessing by various output filters.
Any arguments or flags
that are not recognized by
.I mm \^(1),
e.g. -rC3, are passed
to
.I nroff
or to \*(PM, as appropriate.
The options, which can occur in any order
but
.I must 
appear before the file names, are:
.VL 17 5 1
.LI -e
.I neqn \^(1)
is to be invoked.
.LI -t
.I tbl \^(1)
is to be invoked.
.LI -c
.I col \^(1)
is to be invoked.
.LI -E
the ``-e'' option of \f2nroff\f1 is to be invoked.
.LI -y
-mm (uncompacted macros) is to be used instead of -cm.
.LI -12
12-pitch mode is to be used.
Be sure that the pitch switch on the terminal
is set to 12.
.LI -T450
output is to a DASI450.
This is the
.I default
terminal type (unless $TERM is set).
It is also equivalent to -T1620.
.LI -T450-12
output is to a DASI450 in 12-pitch mode.
.LI -T300
output is to a DASI300 terminal.
.LI -T300-12
output is to a DASI300 in 12-pitch mode.
.LI -T300S
output is to a DASI300S.
.LI -T300S-12
output is to a DASI300S in 12-pitch mode.
.LI -T4014
output is to a Tektronix 4014.
.LI -T37
output is to a 
\s-2TELETYPE\s0\(rg Model 37.
.LI -T382
output is to a DTC-382.
.LI -T4000A
output is to a Trendata 4000A.
.LI -TX
output is prepared for an EBCDIC lineprinter.
.LI -Thp
output is to a HP264x (implies -c).
.LI -T43
output is to a \s-2TELETYPE\s0\(rg Model 43 (implies -c).
.LI -T40/4
output is to a \s-2TELETYPE\s0\(rg Model 40/4 (implies -c).
.LI -T745
output is to a Texas Instrument 700 series terminal (implies -c).
.LI -T2631
output is prepared for a HP2631 printer (where -T2631-e and -T2631-c
may be used for expanded and compressed modes, respectively) (implies -c).
.LI -Tlp
output is to a device with no reverse or partial line motions or other
special features (implies -c).
.LE
.P
Any other -T option given does not produce an error; it is equivalent to
-Tlp.
.P
A similar command is available for use with
.I troff
(see
.I mmt \^(1)).
.H 2 "The -cm or -mm Flag"
The
\*(PM
package can also be invoked by including the 
.BR -cm " or " -mm
flag as an argument to
the formatter.
The -cm flag causes the pre-compacted version of the macros to be loaded.
The -mm flag causes the file ^/usr/lib/tmac/tmac.m to be read
and processed before 
any other files.
This action defines
the
\*(PM
macros,
sets default values for various parameters,
and initializes the formatter to be ready to process
the files of input text.
.H 2 "Typical Command Lines"
The prototype command lines are as follows
(with the various options explained in {2.4} and in the
.I "N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual"\c
\^\*(II).
.ds QQ filename \f3.\|.\|.\fP
.ds PP \f2or\fP
.tr ~
.BL
.LI
Text without tables or equations:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B mm
[options]
\*(QQ
.LI \*(PP
.B nroff 
[options]
.B  -cm
\*(QQ
.LI ~
.B mmt
[options]
\*(QQ
.LI \*(PP
.B troff
[options]
.B -cm
\*(QQ
.LE
.Ee
.LI
Text with
tables:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -t"
[options]
\*(QQ
.LI \*(PP
.B tbl
\*(QQ \(bv
.B nroff
[options]
.B -cm
.LI ~
.B "mmt -t"
[options]
\*(QQ
.LI \*(PP
.B tbl
\*(QQ \(bv
.B troff
[options]
.B -cm
.LE
.Ee
.LI
Text with equations:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -e"
[options]
\*(QQ
.LI \*(PP
.B neqn
\*(QQ \(bv
.B nroff
[options]
.B -cm
.LI ~
.B "mmt -e"
[options]
\*(QQ
.LI \*(PP
.B eqn
\*(QQ \(bv
.B troff
[options]
.B -cm
.LE
.Ee
.LI
Text with both tables and equations:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -t -e"
[options]
\*(QQ
.LI \*(PP
.B tbl
\*(QQ \(bv
.B "neqn \(bv nroff"
[options]
.B -cm
.LI ~
.B "mmt -t -e"
[options]
\*(QQ
.LI \*(PP
.B tbl
\*(QQ \(bv
.B "eqn \(bv troff"
[options]
.B -cm
.LE
.Ee
.LE
.P
When formatting a document with
.I nroff ,
the
output should normally be processed
for a specific type of terminal, because
the output may require
some features that are specific to a given terminal, e.g.,
reverse paper motion
or half-line paper motion in both directions.
Some commonly-used terminal types and the
command lines appropriate for them are given below.
See {2.4} as well as
.I 300 \^(1),
.I 450 \^(1),
.I 4014 \^(1),
.I hp \^(1),
.I col \^(1),
and
.I terminals \^(7)
for further information.
.BL
.LI
DASI450 in 10-pitch, 6 lines/inch mode, with .75 inch offset, and a
line length of 6.0 inches (60 characters) where this is the default terminal
type so no -T option is needed (unless $TERM is set to another value):
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B mm
\*(QQ
.LI \*(PP
.B "nroff -T450 -h -cm"
filename \f3.\|.\|.\fP
.br
.LE
.Ee
.LI
DASI450 in 12-pitch, 6 lines/inch mode, with .75 inch offset,
and a line length of
6.0 inches (72 characters):
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -12"
\*(QQ
.LI \*(PP
.B "nroff -T450-12 -h -cm"
filename \f3.\|.\|.\fP
.br
.LE
.Ee 1
or, to increase the line length to 80 characters and decrease the offset
to 3 characters:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -12 -rW80 -rO3"
\*(QQ
.LI \*(PP
.B "nroff -T450-12 -rW80 -rO3 -h -cm"
filename \f3.\|.\|.\fP
.br
.LE
.Ee 
.LI
Hewlett-Packard HP264x CRT family:
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -Thp"
\*(QQ
.LI \*(PP
.B "nroff -cm"
filename \f3.\|.\|.\fP
.B "\(bv col \(bv hp"
.br
.LE
.Ee
.LI
Any terminal incapable of reverse paper motion and also lacking hardware
tab stops
(Texas Instruments 700 series, etc.):
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.B "mm -T745"
\*(QQ
.LI \*(PP
.B "nroff -cm"
filename \f3.\|.\|.\fP
.B "\(bv col -x"
.br
.LE
.Ee
.LI
Versatec printer (see
.I vp \^(1)
for additional details):
.Es 0 1
.LB 5 0 2 x 0 0
.LI ~
.tr Q"
.B vp
[vp-options]
.B "Qmm -rT2 -c"
filename \f3.\|.\|.\fP\^Q
.LI \*(PP
.B vp
[vp-options]
.B "Qnroff -rT2 -cm"
filename \f3.\|.\|.\fP
.B "\(bv colQ"
.br
.LE
.Ee
.tr QQ
.LE
.rm QQ
.rm PP
.P
Of course, 
.I tbl \^(1)
and
.I eqn \^(1)/\c
.I neqn \^(1),
if needed,
must be invoked as shown 
in the command line prototypes at the
beginning of this section.
.P
If two-column processing {12.4} is used with
.I nroff,
either the -c option 
must be specified to
.I mm \^(1),\*F
.FS
Note that
.I mm \^(1)
uses
.I col \^(1)
automatically for many of the terminal types {2.1}.
.FE
or the
.I nroff
output must be postprocessed by
.I col \^(1).
In the latter case,
the -T37 terminal type must be specified to
.I nroff,
the -h option must
.I not
be specified, and
the output of
.I col \^(1)
must be processed by the appropriate terminal filter (e.g.,
.I 450 \^(1));
.I mm \^(1)
with the -c option
handles all this automatically.
.H 2 "Parameters that Can Be Set from the Command Line"
.I "Number registers"
are commonly used within
\*(PM
to hold parameter values that control various aspects of output style.
Many of these can be changed within the text files via
\&\f3.\fPnr
requests.
In addition, some of these registers can be set from the command line itself,
a useful feature for those parameters that should
.I not
be permanently
embedded within the input text itself.
If used, these
registers (with the possible exception
of the register
.I P \*(EM\c
see below)
.I must 
be set on the command line (or
before the \*(PM macro definitions are processed)
and their meanings
are:
.VL 6
.LI -rAn
for
.I n
= 1
has the effect of invoking the \f3.\fPAF macro without an argument {6.7.2}.
If
.I n
= 2 allows for usage of the Bell Logo, if available, on a printing
device (currently available for the Xerox 9700 only).
.LI -rC\f2n\fP
.I n
sets the type of copy
(e.g., DRAFT) to be printed
at the bottom of each page.
See {9.5}.
.br
n = 1 for OFFICIAL FILE COPY.
.br
n = 2 for DATE FILE COPY.
.br
n = 3 for DRAFT with single-spacing and default paragraph style.
.br
n = 4 for DRAFT with double-spacing and 10 space paragraph indent.
.LI -rD1
sets
.I "debug mode" .
This flag requests the formatter to attempt to continue processing
even if \*(PM detects errors
that would otherwise cause termination.
It also includes some debugging information
in the default page header
{9.2, 12.3}.
.LI -rE\f2n\fP
controls the font of the Subject/Date/From fields.  If
.I n
is 0 then these fields are bold (default for
.I troff )
and if
.I n
is 1 then these fields are regular text (default for
.I nroff ).
.LI -rL\f2k\fP
sets the length of the physical page to
.I k
lines.\*F\ 
.FS 
For
.I nroff,
.I k
is an
.I unscaled
number representing lines
or character positions;
for
.I troff,
.I k
must be
.I scaled.
.FE
The default value is 66 lines per page.
This parameter is used, for example,
when
directing output to a Versatec printer.
.LI -rN\f2n\fP
specifies the page numbering style.
When
.I n
is 0 (default),
all pages get the (prevailing) header {9.2}.
When
.I n
is 1,
the page header
replaces the footer on page\ 1 only.
When
.I n
is 2, the page header is omitted from page\ 1.
When
.I n
is 3, ``section-page'' numbering {4.5} occurs (see \f3.\fPFD {8.3} and \f3.\fPRP {11.4} for
footnote and reference numbering in sections).
When
.I n
is 4, the \f2default\f1 page header is suppressed;
however a user-specified header is not affected.
When
.I n
is 5, ``section-page'' and ``section-figure''
numbering occurs.
.! tbl tbl-2.3
.P
The contents of the prevailing header and footer  
do
.I not
depend on
the value of
the number register
.I N;
.I N
only controls whether and
where the header (and, for
.I N \^=3 
or 5,
the footer) is printed, as well as the page numbering style.
In particular, if the header and footer are null {9.2, 9.5},
the value of
.I N
is irrelevant.
.LI -rO\f2k\fP
offsets output
.I k
.nr :p -1
spaces to the right.\*F\ 
'''.FS 
'''For
'''.I nroff,
'''these values are
'''.I unscaled
'''numbers representing lines
'''or character positions.
'''For
'''.I troff ,
'''these values must be
'''.I scaled.
'''.FE
It is helpful for adjusting output positioning on some terminals.
The default offset if this register is not set on the command line is
\&.75 inches.
NOTE: The register name is the capital letter
``O'',
.I not
the digit zero (0).
.LI -rP\f2n\fP
specifies that the pages of the document are to 
be numbered starting with
.I n.
This register may also be set via a \f3.\fPnr request
in the input text.
.LI -rS\f2n\fP
sets the point size and vertical spacing for the document.
The default
.I n
is 10,
i.e., 10-point type on 12-point leading
(vertical spacing), giving 6 lines per inch
{12.9}.
This parameter applies to
.I troff
only.
.LI -rT\f2n\fP
provides register settings
for certain devices.
If
.I n
is 1,
then the line length and page offset are
set
to 80 and 3, respectively.
Setting
.I n
to 2
changes the page length
to 84 lines per page
and inhibits underlining;
it is meant for output
sent to the Versatec printer.
The default value for
.I n
is 0.
This parameter applies to
.I nroff
only.
.LI -rU1
controls underlining of section headings.
This flag causes only letters and digits to be underlined.
Otherwise, all characters (including spaces) are underlined
{4.2.2.4.2}.
This parameter applies to
.I nroff
only.
.LI -rW\f2k\fP
page width (i.e., line length and title length) is
set to
.nr :p -1
.I k. \*F\ 
'''.FS 
'''For
'''.I nroff,
'''.I k
'''is an
'''.I unscaled
'''number representing lines
'''or character positions;
'''for
'''.I troff,
'''.I k
'''must be
'''.I scaled.
'''.FE
This can be used to change the page width from the default value of 
6.0 inches (60 characters in 10 pitch or 72 characters in 12 pitch).
.LE
.H 2 "Omission of -cm or -mm"
If a large
number of arguments is required on the command line,
it may be convenient to set up the
first (or only) input file of a document as follows:
.DS1
zero or more initializations of registers listed in {2.4}
.ss 18
\!.ss 18
\&\f3.\fPso /usr/lib/tmac/tmac\f3.\fPm
.ss 12
\!.ss 12
remainder of text
.DE
.P
In this case, one must
.I not 
use the 
.BR -cm " or " -mm 
flag
(nor the
.IR mm "\^(1) or " mmt \^(1)
command);
the \&\f3.\fPso
request has the equivalent effect, but
the registers in {2.4}
must be initialized
.I before
the
\&\f3.\fPso
request, because their values are meaningful only if set
before the macro definitions are processed.
When using this method, it is best to ``lock''
into the input file only those parameters that are seldom changed.
For example:
.Es 1
\&\f3.\fPnr W 80
\&\f3.\fPnr O 10
\&\f3.\fPnr N 3
\&\f3.\fPso /usr/lib/tmac/tmac\f3.\fPm
\&\f3.\fPH 1 "\^INTRODUCTION\^"
.if t .sp -.5v
\&\h'.25i'\f3.\fP
.if t .sp -.5v
\&\h'.25i'\f3.\fP
.if t .sp -.5v
\&\h'.25i'\f3.\fP
.Ee 1
specifies, for
.I nroff,
a line length of 80,
a page offset of 10, and
``section-page'' numbering.