SysIII/usr/src/man/docs/mm_man/s03envir

.H 1 "FORMATTING CONCEPTS"
.H 2 "Basic Terms"
The normal action of the formatters is to
.I fill
output lines from one or more input lines.
The output lines may be
.I justified
so that both the left and right margins are aligned.
As the lines are being filled,
words 
may also be
hyphenated {3.4} as necessary.
It is possible to turn any of these modes on and off
(see \f3.\fPSA {12.2},
.I Hy
{3.4},
and the formatter \f3.\fPnf and \f3.\fPf\&i requests\*(II).
Turning off fill mode also turns off justification and hyphenation.
.P
Certain formatting commands (requests and macros) cause the filling of the current output line to cease, 
the line (of whatever length) to be printed,
and the subsequent text to begin a new output line.
This printing of a partially filled output line is known as a
.I break.
A few formatter 
requests
and most of the
\*(PM macros cause a break.
.P
While formatter requests can be used with
\*(PM,
one must fully understand the consequences and side-effects that
each such request might have.
Actually, there is little need to use formatter requests;
the macros described here
should be used in most cases because:
.DL 
.LI
it is much easier to control
(and change at any later point in time)
the overall style of the document.
.LI
complicated facilities 
(such as footnotes or tables of contents)
can be obtained with ease.
.LI
the user is insulated from the peculiarities of
the formatter language.
.LE
.P
A good rule is to use formatter requests only when absolutely necessary {3.10}.
.P
In order to make it easy to revise the input text at a later time,
input lines should be kept short
and should be broken at the end of clauses;
each new full
.I sentence
.I must
begin on a new line.
.H 2 "Arguments and Double Quotes"
For any macro call, a
.I "null argument"
is an argument whose width is zero.
Such an argument often has a special meaning;
the preferred form for a null argument is "\^".
Note that
.I omitting
an argument is
.I not
the same as supplying a
.I "null argument"
(for example, see the \f3.\fPMT macro in {6.6}).
Furthermore, omitted arguments can occur only at the end of an argument list,
while null arguments can occur anywhere.
.P
Any macro argument containing ordinary (paddable) spaces
.I must 
be enclosed in double
quotes\ (").\*F\ 
.FS
A double quote (\^"\^) is a
.I single
character that must not be confused
with two apostrophes or acute accents (\^\'\^\'\^), or with two grave
accents (\^\`\^\`\^).
.FE
Otherwise, it will be treated as several separate
arguments.
.P
Double quotes\ (") are
.I not 
permitted as part of the value of 
a macro argument
or of a string that is to be used as a macro argument.
If you must, use
two grave accents (\^\`\^\`\^) and/or two acute accents (\^\'\^\'\^)
instead.
This restriction is necessary because many macro arguments are processed (interpreted) 
a variable number of times;
for example, headings are first printed in the text and may be (re)printed in the table of contents.
.H 2 "Unpaddable Spaces"
When output lines are
.I justified
to give an even right margin,
existing spaces in a line may have additional spaces appended to them.
This may harm the desired alignment of text.
To avoid this problem,
it is necessary to be able to specify a space that cannot be expanded
during justification, i.e., an
.I "unpaddable space" .
There are several ways to accomplish this.
.P
First, one may type a backslash followed by a space (``\\\|\ '').
This pair of characters directly generates an
.I "unpaddable space" .
Second, one may sacrifice some seldom-used character to be translated
into a space upon output.
Because this translation occurs after justification,
the chosen character may be used anywhere an
unpaddable space is desired.
.tr ~~
The tilde (\^~\^) is often used for this purpose.
To use it in this way, insert the following at the beginning of the document:
.Es 1
\&\f3.\fPtr ~
.Ee
.P
If a tilde must actually appear in the output,
it can be temporarily ``recovered'' by inserting:
.Es 1
\&\f3.\fPtr ~\^~
.Ee1
before the place where it is needed.
Its previous usage is restored by repeating the ``\f3.\fPtr\ \|~\^'',
but only after a break or after the line containing the tilde has
been forced out.
Note that the use of the tilde in this fashion is
.I not
recommended for documents in which the tilde
is used within equations.
.tr ~~
.H 2 "Hyphenation"
The formatters do not perform hyphenation unless the user requests it.
Hyphenation can be turned on in the body of the text by
specifying:
.Es 1
\&\f3.\fPnr Hy 1
.Ee 1
.I once
at the beginning of the document.
For hyphenation control within footnote text
and across pages,
see {8.3}.
.P
If hyphenation is requested, the formatters
will automatically hyphenate words, if need be.
However, the user may specify the hyphenation points for 
a specific occurrence of any word
by the use of a special character known as a hyphenation indicator,
or may specify
hyphenation points for
a small list of words (about 128 characters).
.P 
If the
.I "hyphenation indicator" 
(initially, the two-character sequence ``\\%'')
appears at the beginning of a word,
the word is
.I not 
hyphenated.
Alternatively, it can be used to indicate legal hyphenation point(s)
inside a word.
In any case,
.I all
occurrences of the hyphenation indicator disappear on output.
.P
The user may specify a different hyphenation indicator:
.Es 1
\&\f3.\fPHC [hyphenation-indicator]
.Ee
.P
.hc
The circumflex (\^\*^\^) is often used for this purpose;
this is done by inserting
the following at the beginning of a document:
.HC
.Es 1
\&\f3.\fPHC \*^
.Ee 1
.HC ^
.tr ``
.hc ^
.P
Note that any word containing hyphens
or
dashes\*(EMalso known as 
.I em 
dashes\*(EM\c
will be hyphenated immediately after a
hyphen 
or
dash
if
it is necessary to hyphenate the word,
.I
even if
the formatter hyphenation function is turned off.
.R
.P
The user may supply, via the \f3.\fPhw request,
a small list of words with the proper hyphenation points indicated.
For example, to indicate the proper hyphenation of the word \%``printout,''
one may specify:
.Es 1
\&\f3.\fPhw print-out
.Ee
.H 2 "Tabs"
The macros \f3.\fPMT {6.6}, \f3.\fPTC {10.1},
and \f3.\fPCS {10.2} use the formatter \f3.\fPta request
to set tab stops,
and then restore the
.I default
values\*F
.FS
Every eight characters in
.I nroff;
every \(12 inch in
.I troff.
.FE
of tab settings.
Thus, setting tabs
to other than the default values
is the user's responsibility.
.P
Note that a tab character is always interpreted with respect to
its position on the
.I "input line"  ,
rather than its position on the output line.
In general, tab characters should appear only on lines processed in
``no-fill'' mode {3.1}.
.P
Also note that
.I tbl  \^(1)
{7.3} changes tab stops,
but does
.I not 
restore the default tab settings.
.H 2 "Special Use of the BEL Character"
The non-printing character BEL is used as a delimiter in many macros where it
is necessary to compute the width of an argument
or to delimit arbitrary text, e.g., in
headers and footers {9}, headings {4},
and list marks {5}.
Users who include BEL characters in their input text
(especially in arguments to macros)
will receive mangled output.
.H 2 "Bullets
A bullet (\*(BU) is often obtained on a typewriter terminal by
using an ``o'' overstruck by a ``+''.
For compatibility with
.I troff ,
a bullet string
is provided by
\*(PM.
Rather than overstriking,
use the sequence:
.DS 1
\&\\\\\(**(BU
.DE1
wherever a bullet is desired.
Note that the bullet list (\f3.\fPBL) macros {5.3.3.2} use this
string to automatically generate the bullets for the list items.
.H 2 "Dashes, Minus Signs, and Hyphens"
.I Troff
has distinct graphics for a dash,
a minus sign, and a hyphen,
while
.I nroff
does not.
Those who intend to use
.I nroff
only may use the minus sign (``-'') for all three.
.P
Those who wish mainly to use
.I troff
should follow the escape conventions of the
.I "N\s-1ROFF\s0/T\s-1ROFF\s0 User's Manual"\c
\^\*(II.
.P
Those who want to use both formatters must take care during
text preparation.
Unfortunately, these characters cannot
be represented in a way that is both compatible and convenient.
We suggest the following approach:
.VL 10
.LI Dash
Type \e*(EM for each text dash for both
.I nroff
and
.I troff .
This string generates an em dash (\*(EM) in
.I troff
and generates ``--'' in
.I nroff .
Note that the dash list (\f3.\fPDL) macros {5.3.3.3} automatically
generate the
em dashes for the list items.
.LI Hyphen
Type ``-'' and use as is for both formatters.
.I Nroff
will print it as is, and
.I troff
will print a true hyphen.
.LI Minus
Type ``\\-'' for a true minus sign,
regardless of formatter.
.I Nroff
will effectively ignore the ``\\'', while
.I troff
will print a true minus sign.
.LE
.H 2 "Trademark String"
A trademark string \e\(**(Tm is now available with \*(PM.
This places the letters ``TM'' one-half line above the
text that it follows.
.P
For example:
.Es 1
The UNIX\e*(Tm User's Manual is available from the library.
.Ee 
yields:
.Es 1
The UNIX\*(Tm User's Manual is available from the library.
.Ee
.H 2 "Use of Formatter Requests"
Most formatter requests\*(II should
.I not
be used with \*(PM because \*(PM provides the corresponding formatting functions
in a much more user-oriented and surprise-free fashion
than do the basic formatter requests {3.1}.
However, some formatter requests
.I are
useful with \*(PM, namely:
.DS 1
.ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i 7i
\&\f3.\fPaf	\f3.\fPbr	\f3.\fPce	\f3.\fPde	\f3.\fPds	\f3.\fPf\&i	\f3.\fPhw	\f3.\fPls	\f3.\fPnf	\f3.\fPnr	\f3.\fP!
\&\f3.\fPnx	\f3.\fPrm	\f3.\fPrr	\f3.\fPrs	\f3.\fPso	\f3.\fPsp	\f3.\fPta	\f3.\fPti	\f3.\fPtl	\f3.\fPtr
.DE
.P
The
\&\f3.\fPfp, \f3.\fPlg, and \f3.\fPss
requests are also sometimes useful for
.I troff.
Use of other requests without fully understanding their
implications very often leads to disaster.