SysIII/usr/src/man/docs/mm_man/s01intro

.H 1 INTRODUCTION
.H 2 Purpose
This memorandum
is the user's guide and
reference manual for
the Memorandum Macros
(\*(PM),
a general-purpose package of text formatting macros for use with the
\*(UX\(dg
.FS \(dg
UNIX is a Trademark of Bell Laboratories.
.FE
text formatters
.I nroff
and
.I troff .
The purpose of
\*(PM
is to provide
a unified, consistent, and flexible tool for producing
many common types of documents.
Although the \*(Ux Time-Sharing System
provides other macro packages for various 
.I specialized
formats,
\*(PM
has become the standard, general-purpose macro package for most documents.
.P
\*(Pm
can be used to produce:
.BL "" 1
.LI
Letters.
.LI
Reports.
.LI
Technical Memoranda.
.LI
Released Papers.
.LI
Manuals.
.LI
Books.
.LI
etc.
.LE
.P
The uses of \*(PM range from
single-page letters to documents of several hundred pages in length,
such as user guides, design proposals, etc.
.H 2 Conventions
Each section of this memorandum explains a single facility of
\*(PM.
In general, the earlier a section occurs,
the more necessary it is for most users.
Some of the later sections can be completely ignored 
if \*(PM defaults are acceptable.
Likewise, each section progresses from normal-case to special-case
facilities.
We recommend reading a section in detail only until there is enough information
to obtain the desired format,
then skimming the rest of it,
because some details may be of use to just a few people.
.P
Numbers enclosed in curly brackets (\^{\|}\^) refer to
section numbers within this document.
For example, this is {1.2}.
.P
Sections that require knowledge of 
the formatters {1.4}
have a bullet (\*(BU) at the end of the
section heading.
.P
In the synopses of macro calls,
square brackets (\^[\|]\^)
surrounding an argument indicate that it is optional.
Ellipses (\|\f3.\|.\|.\fP\|) show that the preceding argument may 
appear more than once.
.P
A reference of the form
.I name (N)
points to page
.I name
in section
.I N
of the 
.I "\*(Pu User's Manual"\c
\^\*(Rf.
.RS AA
.I
U\s-1NIX\s0 User's Manual\(emRelease\ 3.0.
.R
Bell Laboratories, April 1980.
.RF
.P
The examples of
.I output
in this manual
are as produced by
.I troff;
.I nroff
output would, of course, look somewhat different
(Appendix\ C shows
.I both
the
.I nroff
and 
.I troff
output for a simple letter).
In those
cases in which
the behavior of the two formatters is truly different,
the
.I nroff
.if t .ne4
action is described first, with the
.I troff
action following in parentheses.
For example:
.DS 1
The title is underlined (italic).
.DE1
means that the title is underlined in
.I nroff
and italic in
.I troff.
.H 2 "Overall Structure of a Document
The input for a document that is to be formatted with
\*(PM
possesses four major segments,
any of which may be omitted;
if present, they
.I must 
occur in the following order:
.BL
.LI
.I "Parameter-setting\*(EM" \c
This segment sets the general style and appearance of a document.
The user can control page width, margin justification,
numbering styles for headings and lists,
page headers and footers {9}, and many other properties of the document.
Also, the user can add macros or redefine existing ones.
This segment can be omitted entirely if one is satisfied with default values;
it produces no actual output,
but only performs the setup for the rest of the document.
.LI
.I "Beginning\*(EM" \c
This segment includes those items that occur only once,
at the beginning of a document,
e.g., title, author's name, date.
.LI
.I "Body\*(EM" \c
This segment is the actual text of the document.
It may be as small as a single paragraph, or as large as hundreds of pages.
It may have a hierarchy of
.I headings
up to seven levels deep {4}.
Headings are automatically numbered (if desired)
and can be saved to generate the table of contents.
Five additional levels of subordination are provided by a set of
.I list 
macros for
automatic numbering, alphabetic sequencing, and ``marking'' of list items {5}.
The body may also contain various types of displays, tables, figures,
references, and footnotes {7, 8, 11}.
.LI
.I "Ending\*(EM" \c
This segment contains those items
that occur once only, at the end of a document.
Included here are signature(s)
and
lists of notations (e.g., ``copy to'' lists) {6.11}.
Certain macros may be invoked here to print information that is wholly or partially
derived from the rest of the document,
such as the table of contents or 
the cover sheet for a document {10}.
.LE
.P
The existence and size of these four segments varies widely among
different document types.
Although a specific item (such as date, title,
author name(s), etc.) may be printed in several different ways depending on the document type,
there is a uniform way of typing it in.
.H 2 "Definitions"
The term
.I formatter
refers to either of the text-formatting programs
.I nroff
and
.I troff .
.P
.I Requests
are built-in commands recognized by the formatters.
Although one seldom needs to use these
requests
directly {3.10}, this document contains references to some of them.
Full details are given in the 
.I "N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual"\c
\^\*(Rf.
.RS II
Ossanna, J. F.
.I
N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual.
.R
Bell Laboratories,
October 1976.
.RF
For example, the request:
.Es 1
\&\f3.\fPsp
.Ee 1
inserts a blank line in the output.
.P
.I Macros
are named collections of requests.
Each
macro
is an abbreviation for a collection of requests that would
otherwise require repetition.
\*(Pm
supplies many macros,
and the user can define additional ones.
Macros
and
requests
share the same set of names
and are used in the same way.
.P
.I Strings
provide character variables,
each of which names a string of characters.
Strings are often used in page headers, page footers,
and lists.
They share the pool of names used by
.I requests
and
.I macros.
A string can be given a value via the
\&\f3.\fPds
(define string) request,
and its value can be obtained by referencing its name,
preceded by ``\\\(**'' (for 1-character names) or ``\\\(**('' (for 2-character names).
For instance, the string 
.I DT
in
\*(PM
normally contains the current date,
so that the
.I input 
line:
.Es  1
Today is \\\\\(**(DT.
.Ee 1
may result in the following
.I output:
.DS 1
Today is \*(DT.
.DE
.P
The current date can be replaced, e.g.:
.Es 1
\&\f3.\fPds DT 01/01/79
.Ee 1
or by invoking a macro designed for that purpose {6.7.1}.
.P
.I "Number registers"
fill the role of integer variables.
They
are used for flags, for arithmetic, and for automatic numbering.
A
register
can be given a value using a
\&\f3.\fPnr
request,
and be referenced by preceding its name by ``\\n'' (for 1-character names) or
``\\n('' (for 2-character names).
For example, the following sets the value of the register
.I d
to 1 more than that of the register
.I dd \^:
.Es 1
\&\f3.\fPnr d 1+\\\\n(dd
.Ee 1
See {14.1} regarding naming conventions for requests, macros, strings,
and number registers.
.H 2 "Prerequisites and Further Reading"
.H 3 Prerequisites
We assume familiarity with \*(UX at the level given in
.I "U\s-1NIX\s0 for Beginners"\c
\^\*(Rf
.RS CC
Kernighan, B. W.
.I
U\s-1NIX\s0 for Beginners.
.R
Bell Laboratories, October 1974.
.RF
and
.I "A Tutorial Introduction to the U\s-1NIX\s0 Text Editor"\c
\^\*(Rf.
.RS DD
Kernighan, B. W.
.I
A Tutorial Introduction to the U\s-1NIX\s0 Text Editor.
.R
Bell Laboratories,
October 1974.
.RF
Some familiarity with the request summary in the
.I "N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual"\c
\^\*(II is helpful.
.H 3 "Further Reading"
.I "N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual"\c
\^\*(II
provides detailed descriptions of
formatter capabilities,
while
.I "A T\s-1ROFF\s0 Tutorial"\c
\^\*(Rf
.RS EE
Kernighan, B. W.
.I
A T\s-1ROFF\s0 Tutorial.
.R
Bell Laboratories,
August 1976.
.RF
provides a general overview.
See the
.I "Typesetting Mathematics\(emUser's Guide"\c
\^\*(Rf
.RS FF
Kernighan, B. W. and Cherry, L. L.
.I
Typesetting Mathematics\(emUser's Guide (Second Edition).
.R
Bell Laboratories,
June 1976.
.RF
(and possibly also
.I "New Graphic Symbols for E\s-1QN\s0 and N\s-1EQN\s0"\c
\^\*(Rf)
.RS GG
Scrocca, C.
.I
New Graphic Symbols for E\s-1QN\s0 and N\s-1EQN\s0.
.R
Bell Laboratories,
September 1976.
.RF
for instructions on formatting mathematical expressions.
See
.I tbl  \^(1)
and
.I "Tbl\(emA Program to Format Tables"\c
\^\*(Rf
.RS KK
Lesk, M.
.I
Tbl\(emA Program to Format Tables.
.R
Bell Laboratories,
September 1977.
.RF
for instructions on formatting tabular data.
.P
Examples of formatted documents and of their respective input,
as well as a quick reference to the material in this manual
are given in
.I "Typing Documents with \*(PM"\c
\^\*(Rf.
.RS HH
Smith, D. W. and Piskorik, E. M.
.I
Typing Documents with \*(PM.
.R
Bell Laboratories,
April 1980.
.RF