------------------------------- Page    i -------------------------------

                        Nroff/Troff User's Manual




                                                 Joseph F. Ossanna



                                                 Edited for UTS

------------------------------- Page   ii -------------------------------

                            TABLE OF CONTENTS


Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   1

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   1

1.    General Explanation . . . . . . . . . . . . . . . . . . . . . .   3

1.1      Form of input  . . . . . . . . . . . . . . . . . . . . . . .   3
1.2      Formatter and device resolution  . . . . . . . . . . . . . .   3
1.3      Numerical parameter input  . . . . . . . . . . . . . . . . .   4
1.4      Numerical expressions  . . . . . . . . . . . . . . . . . . .   5
1.5      Notation . . . . . . . . . . . . . . . . . . . . . . . . . .   5

2.    Font and Character Size Control . . . . . . . . . . . . . . . .   6

2.1      Character set  . . . . . . . . . . . . . . . . . . . . . . .   6
2.2      Fonts  . . . . . . . . . . . . . . . . . . . . . . . . . . .   6
2.3      Character size . . . . . . . . . . . . . . . . . . . . . . .   7

3.    Page control  . . . . . . . . . . . . . . . . . . . . . . . . .   9

4.    Text Filling, Adjusting, and Centering  . . . . . . . . . . . .  10

4.1      Filling and adjusting  . . . . . . . . . . . . . . . . . . .  10
4.2      Interrupted text . . . . . . . . . . . . . . . . . . . . . .  11

5.    Vertical Spacing  . . . . . . . . . . . . . . . . . . . . . . .  12

5.1      Base-line spacing  . . . . . . . . . . . . . . . . . . . . .  12
5.2      Extra line space . . . . . . . . . . . . . . . . . . . . . .  12
5.3      Blocks of vertical space . . . . . . . . . . . . . . . . . .  13

6.    Line Length and Indenting . . . . . . . . . . . . . . . . . . .  14

7.    Macros, Strings, Diversion, and Position Traps  . . . . . . . .  15

7.1      Macros and strings . . . . . . . . . . . . . . . . . . . . .  15
7.2      Copy mode input interpretation . . . . . . . . . . . . . . .  15
7.3      Arguments  . . . . . . . . . . . . . . . . . . . . . . . . .  15
7.4      Diversions . . . . . . . . . . . . . . . . . . . . . . . . .  16
7.5      Traps  . . . . . . . . . . . . . . . . . . . . . . . . . . .  17

8.    Number Registers  . . . . . . . . . . . . . . . . . . . . . . .  19

9.    Tabs, Leaders, and Fields . . . . . . . . . . . . . . . . . . .  20

------------------------------- Page  iii -------------------------------

9.1      Tabs and leaders . . . . . . . . . . . . . . . . . . . . . .  20
9.2      Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .  21

10.   Input and Output Conventions and Character Translations . . . .  21

10.1     Input character translations . . . . . . . . . . . . . . . .  21
10.2     Ligatures  . . . . . . . . . . . . . . . . . . . . . . . . .  22
10.3     Backspacing, underlining, overstriking, etc  . . . . . . . .  22
10.4     Control characters . . . . . . . . . . . . . . . . . . . . .  23
10.5     Output translation . . . . . . . . . . . . . . . . . . . . .  23
10.6     Transparent throughput . . . . . . . . . . . . . . . . . . .  24
10.7     Comments and concealed new-lines . . . . . . . . . . . . . .  24

11.   Local Horizontal and Vertical Motions, and the Width Function .  24

11.1     Local Motions  . . . . . . . . . . . . . . . . . . . . . . .  24
11.2     Width Function . . . . . . . . . . . . . . . . . . . . . . .  25
11.3     Mark horizontal place  . . . . . . . . . . . . . . . . . . .  25

12.   Overstrike, Bracket, Line Drawing, and Zero Width Functions . .  26

12.1     Overstriking . . . . . . . . . . . . . . . . . . . . . . . .  26
12.2     Zero Width characters  . . . . . . . . . . . . . . . . . . .  26
12.3     Large Brackets . . . . . . . . . . . . . . . . . . . . . . .  26
12.4     Line drawing . . . . . . . . . . . . . . . . . . . . . . . .  26

13.   Hyphenation . . . . . . . . . . . . . . . . . . . . . . . . . .  27

14.   Three Part Titles . . . . . . . . . . . . . . . . . . . . . . .  28

15.   Output Line Numbering . . . . . . . . . . . . . . . . . . . . .  29

16.   Conditional Acceptance of Input . . . . . . . . . . . . . . . .  30

17.   Environment Switching . . . . . . . . . . . . . . . . . . . . .  31

18.   Insertions from the Standard Input  . . . . . . . . . . . . . .  32

19.   Input/Output File Switching . . . . . . . . . . . . . . . . . .  32

20.   Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . .  33

21.   Output and Error Messages . . . . . . . . . . . . . . . . . . .  34

Tutorial Examples . . . . . . . . . . . . . . . . . . . . . . . . . .  34

1.    Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .  34

2.    Page Margins  . . . . . . . . . . . . . . . . . . . . . . . . .  35

------------------------------- Page   iv -------------------------------

3.    Paragraphs and Headings . . . . . . . . . . . . . . . . . . . .  37

4.    Multiple Column Output  . . . . . . . . . . . . . . . . . . . .  38

5.    Footnote Processing . . . . . . . . . . . . . . . . . . . . . .  39

6.    The Last Page . . . . . . . . . . . . . . . . . . . . . . . . .  41

References  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  41

Appendix A.    Escape Sequences for Characters, Indicators, and
               Functions  . . . . . . . . . . . . . . . . . . . . . .  42

Appendix B.    Predefined Number Registers  . . . . . . . . . . . . .  43

Appendix C.    Command Summary  . . . . . . . . . . . . . . . . . . .  45


                                                            Last Page  49

-------------------------------- Page  1 --------------------------------

INTRODUCTION

Nroff  is  a  text  processor  under  UTS  [1]  that  formats  text   for
typewriter-like terminals.  Troff is a text processor for a Graphic  Sys-
tems phototypesetter, that is not supported under UTS.  They accept lines
of text interspersed with lines of format control information and  format
the text  into a  printable, paginated  document having  a  user-designed
style.  Nroff  and  troff  offer  unusual freedom  in  document  styling,
including: arbitrary  style headers  and footers;  arbitrary style  foot-
notes; multiple  automatic sequence numbering  for paragraphs,  sections,
etc; multiple column output; dynamic  font and point size control;  arbi-
trary horizontal and vertical local motions at any point; and a family of
automatic overstriking, bracket construction, and line drawing functions.

Nroff and troff are highly  compatible with each other  and it is  almost
always possible to prepare  input acceptable to both.  Conditional  input
is provided that enables the user  to embed input expressly destined  for
either program.  Nroff can prepare output directly for a variety  of ter-
minal types and is capable of using the full resolution of each terminal.




USAGE

The general form for invoking nroff (or troff) at command level is

     nroff [option ...] [file ...]
     troff [option ...] [file ...]

where option  represents  any  of several  optional  arguments  and  file
represents each file containing the  document to be formatted.  An  argu-
ment consisting  of  a single  minus  (-) is  taken  to be  a  file  name
corresponding to the standard input.  If no file names are given input is
taken from the  standard input.   The options,  which may  appear in  any
order so long as they appear before the files, are:

Option  Effect

-olist  Print only pages whose  page numbers appear  in list, which  con-
        sists of  comma-separated numbers  and number  ranges.  A  number
        range has the form N-M and means pages N through M; a initial  -N
        means from the beginning to  page N; and a final N- means from  N
        to the end.

-nN     Number first generated page N.

-sN     Stop every  N  pages.   Nroff  will halt  before  every  N  pages

-------------------------------- Page  2 --------------------------------

        (default N=1) to allow paper loading or changing, and will resume
        on receipt of a  new-line.  Troff will  stop the  phototypesetter
        every N pages, produce a trailer to allow changing cassettes, and
        will resume after the phototypesetter START button is pressed.

-mname  Prepends the macro file /usr/lib/tmac.name to the input files.

-raN    Register a (one character) is set to N.

-i      Read standard input after the input files are exhausted.

-q      Invoke the simultaneous input/output mode of the rd request.

-z      Efficiently suppresses  formatted output.   Only  message  output
        will occur (from tm's and diagnostics).

             nroff only

-Tname  Prepare output for the specified terminal, using the device table
        found in /usr/lib/term/tabname.  Known names are coi for the  COI
        3270 terminals, mem for the Memorex 1377 terminals, q12 (or  q10)
        for the Qume printer with  12 (or 10) characters per inch,  q3270
        for a Qume (q12) simulation viewable on  a 3270, e1pr for the  E1
        building line printer, tn  for the TN  train line printer,  qline
        for a Qume (q12) simulation viewable  on a line printer, com  for
        the COMp 80  microfiche device,  and ascii for  a standard  ascii
        terminal.  The default table  is either coi  or mem depending  on
        the current stty(1) setting.

-e      Produce equally spaced words in adjusted lines, using full termi-
        nal resolution.

-h      Output tabs used  during horizontal  spacing to  speed output  as
        well as reduce output byte count.  Device tab settings assumed to
        be every 8  nominal character  widths.  The  default settings  of
        input (logical) tabs is also initialized to every 8 nominal char-
        acter widths.

             troff only

-f      Refrain from feeding  out paper and  stopping phototypesetter  at
        the end of the run.

-a      Send a  printable (ASCII)  approximation of  the results  to  the
        standard output.

-pN     Print  all  characters  in  point  size  N  while  retaining  all
        prescribed  spacings  and  motions,  to  reduce   phototypesetter
        elapsed time.

-------------------------------- Page  3 --------------------------------

Each option is invoked as a separate argument; for example,

     nroff -o4,8-10 -Tq12 -mabc file1 file2

requests formatting of pages 4, 8, 9, and  10 of a document contained  in
the files named  file1 and  file2, specifies the  output terminal as  the
Qume, and invokes the macro package abc.

Various pre-  and postprocessors  are available  for use  with nroff  and
troff, including the  table construction  preprocessor tbl [3].   Reverse
line postprocessors (tprf,  qprf, and  oprf) are  available for  multiple
column nroff output on terminals without reverse line ability.

The remainder of this  manual consists of  a reference manual,  a set  of
tutorial examples, and several appendices, including a command summary.




1.    GENERAL EXPLANATION


1.1      FORM OF INPUT

Input consists of text lines,  which are destined  to be printed,  inter-
spersed with  control lines,  which set parameters  or otherwise  control
later processing.  Control lines begin with a control character--normally
. (period) or ' (acute  accent)--followed by a one or two character  name
that specifies  a basic  request or  the substitution  of a  user-defined
macro in place of the  control line.  The control character '  suppresses
the break function--the forced output of a partially filled  line--caused
by certain requests.   The control  character may be  separated from  the
request/macro name by white space (spaces and tabs) for esthetic reasons.
Names must be followed by  either space or new-line.  Control lines  with
unrecognized names are ignored.

Various special functions may be  introduced anywhere in the input  using
an escape character, normally  \.  For example,  the function \nR  causes
the interpolation of the contents  of the number register  R in place  of
the function; here R  is either a single character  name as in \nx, or  a
left parenthesis introduced, two character name, as in \n(xx.


1.2      FORMATTER AND DEVICE RESOLUTION

Troff internally uses 432 units/inch,  corresponding to the Graphic  Sys-
tems phototypesetter that has a horizontal resolution of 1/432 inch and a
vertical resolution of 1/144 inch.  Nroff internally uses 240 units/inch,

-------------------------------- Page  4 --------------------------------

corresponding to the least common multiple of the horizontal and vertical
resolutions of  various  typewriter-like output  devices.   Troff  rounds
horizontal/vertical numerical parameter input to the  horizontal/vertical
resolution of  the Graphic  Systems typesetter.   Nroff similarly  rounds
numerical input to the resolution  of the output device specified by  the
-T option.


1.3      NUMERICAL PARAMETER INPUT

Both nroff and troff accept numerical input with the appended scale indi-
cators shown in the following table, where S is the  current type size in
points, V is the current vertical line spacing in basic units, and C is a
nominal character width in basic units.

     ______________________________________________________________
    |   Scale   |                     | Number of basic units     |
    |_indicator_|_______meaning_______|_troff________nroff________|
    |     i     | inch                | 432        | 240          |
    |     c     | centimeter          | 432*50/127 | 240*50/127   |
    |     P     | Pica = 1/6 inch     | 72         | 240/6        |
    |     m     | em = S points       | 6*S        | C            |
    |     n     | en = Em/2           | 3*S        | C, same as em|
    |     p     | point = 1/72 inch   | 6          | 240/72       |
    |     u     | basic unit          | 1          | 1            |
    |     v     | vertical line space | V          | V            |
    |____none___|_default,_see_below__|____________|______________|

In nroff, both the em and the en are taken to be equal to the C, which is
dependent on the  output device;  common values are  1/10 and 1/12  inch.
The width of  characters in  nroff need  not be  all the  same, and  con-
structed characters such as -> (\(ra) are often extra wide.   The default
scaling is ems for the  horizontally-oriented requests and functions  ll,
in, ti,  ta, lt,  po, mc,  \h, and  \l; V's  for the  vertically-oriented
requests and functions pl, wh, ch, dt, sp, sv, ne, rt, \v, \x, and \L;  p
for the vs request;  and u for  the requests nr,  if, and ie.  All  other
requests ignore any scale indicators.  When a number register  containing
an already appropriately scaled number is interpolated to provide numeri-
cal input, the unit scale indicator u may need to be appended to  prevent
an additional  inappropriate  default scaling.   The  number, N,  may  be
specified in decimal fraction  form but the  parameter finally stored  is
rounded to an integer number of basic units.

The absolute position indicator | may be prepended to a number N to  gen-
erate  the  distance  to  the  vertical  or  horizontal  place  N.    For
vertically-oriented requests and  functions, |N becomes  the distance  in
basic units from the current vertical place on the page or in a diversion
(#7.4) to the the  vertical place N.   For all other  requests and  func-
tions, |N becomes the distance  from the current horizontal place on  the
input line to the horizontal place N.  For example,

-------------------------------- Page  5 --------------------------------

     .sp  |3.2c

will space in the required direction to  3.2 centimeters from the top  of
the page.


1.4      NUMERICAL EXPRESSIONS

Wherever numerical input is expected an expression involving parentheses,
the arithmetic operators +, -,  /, *, % (mod), and the logical  operators
<, >, <=, >=, = (or ==), . (and), : (or) may be used.  Except where  con-
trolled by parentheses, evaluation of expressions is left-to-right; there
is no operator precedence.  For  certain requests, an initial  + or -  is
stripped and interpreted as  an increment or decrement indicator  respec-
tively.  In the presence of default scaling, the desired scale  indicator
must be attached to every  number in an expression for which the  desired
and default scaling differ.  For example,  if the number register x  con-
tains 2 and the current point size is 10, then

     .ll  (4.25i+\nxP+3)/2u

will set the line length to  half the sum of 4.25  inches + 2 picas +  30
points.


1.5      NOTATION

Numerical parameters are shown in this manual in two ways.  +N means that
the argument may take the  forms N, +N, or -N and that the  corresponding
effect is to set the affected parameter to N, to increment it by N, or to
decrement it by N respectively.  Plain N means that an  initial algebraic
sign is not an increment indicator, but merely the sign of N.  Generally,
unreasonable numerical input is either ignored or truncated to a  reason-
able value.  For example, most requests expect to set parameters to  non-
negative values; exceptions are sp, wh, ch, nr, and if.  The requests ps,
ft, po, vs, ls, ll,  in, and lt restore the  previous parameter value  in
the absence of an argument.

Single character arguments  are shown  by single lower  case letters  and
one/two character arguments are  shown by a  pair of lower case  letters.
Character string arguments are shown by multicharacter mnemonics.

-------------------------------- Page  6 --------------------------------

2.    FONT AND CHARACTER SIZE CONTROL


2.1      CHARACTER SET

The troff character set  consists of the  Graphics Systems Commercial  II
character set plus a Special Mathematical Font character set--each having
102 characters.  The attached  Table I shows  these character sets.   All
ASCII characters are included, with some on the Special Font.  With three
exceptions, the ASCII characters are  input as themselves, and  non-ASCII
characters are input in  the form \(xx where  xx is a two character  name
given in the attached Table II.  The three ASCII exceptions are mapped as
follows:

          ____________________________________________________
         |        ASCII input       |     printed by troff   |
         |_character_______name_____|_character_______name___|
         |     '       acute accent |     '       close quote|
         |     `       grave accent |     '       open quote |
         |_____-_______minus________|_____-_______hyphen_____|

The characters ', `, and - may be input by \', \`, and \- respectively or
by their names (Table II).  The ASCII characters @, #,  ", ', ', <, >, \,
{, }, ~, ^, and _ exist only on the  Special Font and are printed as a  1
em space if that Font is not mounted.

Nroff understands  the entire  troff character  set, but  can in  general
print only ASCII characters, additional characters as may be available on
the output device, such characters  as may be able to  be built by  over-
striking or other combination,  and those that  can reasonably be  mapped
into other printable characters.  The  exact behavior is determined by  a
driving table prepared for each device.  The characters ', `, and - print
as themselves.


2.2      FONTS

The default mounted fonts are  Times Roman (R),  Times Italic (I),  Times
Bold (B), and the  Special Mathematical Font  (S) on physical  typesetter
positions 1, 2,  3, and  4 respectively.  These  fonts are  used in  this
document.  The current font, initially  Roman, may be changed (among  the
mounted fonts) by use of the ft request,  or by imbedding at any  desired
point either  \fx, \f(xx,  or \fN,  where x  and xx  are the  names of  a
mounted font and N is a numerical font position.  It is not necessary  to
change to the  Special font;  characters on that  font are  automatically
handled.  A request for a named but  not mounted font is ignored.   Troff
can be informed  that any  particular font is  mounted by  use of the  fp
request.  The list of known fonts is installation dependent.  In the dis-
cussion below of font-related requests, F represents either a one  or two
character font name  or the  numerical font position,  1-4.  The  current

-------------------------------- Page  7 --------------------------------

register .f.

Nroff understands font control and normally underlines Italic  characters
(see #10.5).


2.3      CHARACTER SIZE

Character point sizes available on the Graphic Systems typesetter are  6,
7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36.  This is a range
of 1/12 inch to 1/2 inch.  The ps request can change or restore the point
size.  Alternatively the point size may be changed between any  two char-
acters by imbedding a \sN at the desired point to set the size to N, or a
\s+N (1<N<9) to increment/decrement the size by N; \s0 restores  the pre-
vious size.  Requested point size values that are between two valid sizes
yield the larger  of the two.  The  current size is  available in the  .s
read-only register.  Nroff ignores type size control.

.ps +N
The point size (initially 10)  in the current environment  is set to  +N.
With no  argument, the  previous point size  is restored.   Alternatively
imbed \sN or \s+N.  Any positive size value may be requested; if invalid,
the next larger valid size  will result, with a maximum of 36.  A  paired
sequence +N,-N will  work because  the previous requested  value is  also
remembered.  Ignored in nroff.

.ss N
The space character size (initially 12/36 em) in the current  environment
is set to N/36  ems.  This size is  the minimum word spacing in  adjusted
text.  Ignored in nroff.

.cs F N M
Constant character space (width) mode (initially off) is set on for  font
F (if mounted);  the width of every  character will be  taken to be  N/36
ems.  If M is absent, the em is that of the character's point size; if  M
is given, the em  is M-points.  All  affected characters are centered  in
this space, including those having a width larger than this space.   Spe-
cial Font characters occurring  while the current  font is F are also  so
treated.  If N is absent, the mode is turned off.  The mode must be still
or again in effect when  the characters are physically printed.   Ignored
in nroff.

.bd F N
The characters in font F will be artificially emboldened by printing each
one twice, separated by N-1  basic units.  A reasonable value for N is  3
when the character size is near 10 points.  If N is missing the  embolden
mode is turned off.   The column heads above  were printed with .bd I  3.
The mode must be still or again in effect when the characters are  physi-
cally printed.  Ignored in nroff.

-------------------------------- Page  8 --------------------------------

.bd S F N
The characters  in  the Special  Font  will be  emboldened  whenever  the
current font is F.   This manual was  printed with .bd  S B 3.  The  mode
must be  still or  again in  effect when  the characters  are  physically
printed.  Ignored in nroff.

.ft F
The font (initially Roman) in  the current environment  is changed to  F.
Alternatively, imbed \fF.   With no  argument, or with  font name P,  the
previous font is restored.

.fp N F
Font position.  This is  a statement that  a font named  F is mounted  on
position N (1-4).  It  is a fatal  error if F  is not known.  The  photo-
typesetter has four fonts  physically mounted.  Each  font consists of  a
film strip that can  be mounted on a  numbered quadrant of a wheel.   The
default mounting sequence assumed by troff is R, I, B, and S on positions
1, 2, 3 and 4.

.fz F N
This forces font 'F' to be  in size 'N'.  N may  have the form N, +N,  or
-N.  For example,

     .fz 3 -2

will cause  an  implicit  \s-2  every time  font  3  is  entered,  and  a
corresponding \s+2 when  it is left.   Special font characters  occurring
during the reign of font  F will have the same  size change.  If  special
characters are to be treated differently,

     .fz S F N

may specify the size treatment of special characters during font F.   For
example,

     .fz 3 -3
     .fz S 3 -0

will cause automatic reduction of  font 3 by 3  points while the  special
characters would not be  affected.  Any fp  request specifying a font  on
some position must precede fz requests relating to that position.

-------------------------------- Page  9 --------------------------------

3.    PAGE CONTROL

Top and bottom margins are not automatically provided; it is conventional
to define two macros  and to set traps  for them at vertical positions  0
(top) and -N (N from the bottom).  See  #7 and Tutorial Examples #T2.   A
pseudopage transition onto the  first page occurs  either when the  first
break occurs  or  when  the first  nondiverted  text  processing  occurs.
Arrangements for a trap  to occur at  the top of  the first page must  be
completed before this transition.   In the following,  references to  the
current diversion (#7.4)  mean that the  mechanism being described  works
during both ordinary and  diverted output (the  former considered as  the
top diversion level).

The usable page  width on  the Graphic Systems  phototypesetter is  about
7.54 inches, beginning about 1/27  inch from the left edge of the 8  inch
wide, continuous roll paper.   The physical limitations  on nroff  output
are output device dependent.

.pl +N
Page length (initially 11 inches)  is set to +N  V's.  With no  argument,
the default value of 11 inches is used.  The internal limitation is about
75 inches  in troff  and about  136 inches  in nroff.   The current  page
length is available in the .p read-only register.

.bp +N
Begin page.  The current page is ejected and a new page is begun.  If  +N
is given, the new page number will be +N.  Use 'bp to suppress the break.
Also see request ns.

.pn +N
Page number.  The next page  (when it occurs) will  have the page  number
+N.  A pn must occur  before the initial pseudopage transition to  effect
the page number of the first page.  The current  page number is in the  %
general register.

.po +N
Page offset.  The current left margin is set  to +N ems.  The nroff  ini-
tial value is 0; the  troff initial value of 26/27 inch provides about  1
inch of paper  margin including  the physical typesetter  margin of  1/27
inch.  In troff the  maximum line length  plus page offset is about  7.54
inches.  See #6.  With no argument, the previous page offset is restored.
The current page offset is available in the .o read-only register.

.ne N
Need N V's of vertical space.  With no  argument, the default value of  1
is used.  If  the distance, D, to  the next trap  position (see #7.5)  is
less than N, a forward vertical space of size D occurs, which will spring
the trap.  If there are no remaining traps on the page, D is the distance
to the bottom of the  page.  If D<V, another line  could still be  output
and spring the trap.  In a diversion, D is the  distance to the diversion

-------------------------------- Page 10 --------------------------------

trap, if any, or is very large.

.mk R
Mark the current vertical place in an internal register (both  associated
with the current diversion  level), or in  register R, if given.  See  rt
request.

.rt +N
Return upward only to a marked  vertical place in the current  diversion.
If +N (with respect to  the current place) is given, the place is +N  V's
from the top of  the page or  diversion, or if  N is absent,  to a  place
marked by  a previous  mk.   The sp  request (#5.3)  may  always be  used
instead of  rt by  spacing to  the absolute  place stored  in a  explicit
register; for example, using the sequence .mk R ... .sp |\nRu.




4.    TEXT FILLING, ADJUSTING, AND CENTERING


4.1      FILLING AND ADJUSTING

Normally, words are collected from input text lines and assembled into  a
output text line until  some word doesn't  fit.  An attempt is then  made
the hyphenate the word  in an effort to  assemble a part  of it into  the
output line.  The spaces  between the words  on the output line are  then
increased to spread the line to the current line length minus any current
indent.  A word is any string of characters delimited by  the space char-
acter or the beginning/end of the input line.  Any adjacent pair of words
that must be kept together (neither split across output lines  nor spread
apart in the adjustment process) can be tied together by separating  them
with the unpaddable space character "\ " (backslash space).  The adjusted
word spacings are uniform in troff and the minimum interword spacing  can
be controlled  with the  ss request  (#2).  In nroff,  they are  normally
nonuniform because of  quantization to  character-sized spaces;  however,
the command line option -e causes uniform spacing with full output device
resolution.  Filling,  adjustment,  and  hyphenation  (#13)  can  all  be
prevented or  controlled.  The  text length  on the last  line output  is
available in the .n  read-only register, and  text base-line position  on
the page for this line is in the nl general register.  The text base-line
high-water mark (lowest place) on the current page is in the .h read-only
register.  The .k  read-only register  holds the horizontal  size of  the
text portion (without indent) of  the current partially collected  output
line, if any, in the current environment.

An input text line ending  with ., ?, or !  is taken to be  the end of  a
sentence, and  an additional  space character  is automatically  provided

-------------------------------- Page 11 --------------------------------

during filling.  Multiple interword space  characters found in the  input
are retained, except  for trailing  spaces; initial spaces  also cause  a
break.

When filling is in effect, a \p may be imbedded or attached to a word  to
cause a break at the  end of the word and have the resulting output  line
spread out to fill the current line length.

A text input line that happens to begin  with a control character can  be
made to not look like  a control line by prefacing it with the  nonprint-
ing, zero width filler  character \&.   Still another way  is to  specify
output translation of some convenient character into the control  charac-
ter using tr (#10.5).


4.2      INTERRUPTED TEXT

The copying of an input line in nofill (nonfill) mode can be  interrupted
by ending the partial  line with a  \c.  The next encountered input  text
line will be considered to  be a continuation of the  same line of  input
text.  Similarly, a word within filled text may be interrupted  by ending
the word (and line) with \c; the next encountered text will be taken as a
continuation of the interrupted  word.  If the intervening control  lines
cause a break, any partial line will be forced out along with any partial
word.

.br
Break.  The filling of the line currently being collected is stopped  and
the line is output without  adjustment.  Text lines beginning with  space
characters and empty text lines (blank  lines) also cause a break.   When
used as 'br, it has no effect.

.fi
Fill output lines in the current environment.  The read-only register  .u
is 1 in fill mode and 0 in nofill mode.   Fill mode is initially on.  Use
'fi to suppress the break.

.nf
Nofill.  Output lines in the  current environment are neither filled  nor
adjusted.  Input text lines are  copied directly to output lines  without
regard for the current line length.  Use 'nf to suppress the break.

.ad c
Line adjustment (initially on) in  the current environment is begun.   If
fill mode is not on, adjustment will be deferred until  fill mode is back
on.  The following table  shows how the  adjustment type (initially  both
left and right) is changed, if the type indicator c is present.

-------------------------------- Page 12 --------------------------------

                 ______________________________________
                |_Indicator_|________Adjust_Type______|
                |     l     | adjust left margin only |
                |     r     | adjust right margin only|
                |     c     | center                  |
                |   b or n  | adjust both margins     |
                |___absent__|_unchanged_______________|

The adjustment type indicator c may also be a number previously  obtained
from the  .j register.   The .j  read-only number  register contains  the
current adjustment mode and type  in a form that may  be given to the  ad
request.

.na
No adjust.   Adjustment is  turned off  in the  current environment;  the
right margin will be ragged.  The adjustment type for ad  is not changed.
Output line filling still occurs if fill mode is on.

.ce N
Center the next N input text lines in the current environment within  the
current (line length minus indent).  With no argument, the default  value
of 1 is used.   If N=0, any  residual count is  cleared.  A break  occurs
after each of the N input lines.  Use 'ce to  suppress the initial break.
If the input line is too long, it will be left adjusted.




5.    VERTICAL SPACING


5.1      BASE-LINE SPACING

The vertical  spacing (V)  between the  base-lines of  successive  output
lines can be set using  the vs request with a resolution of 1/144 inch  =
1/2 point in troff, and to the output device resolution in nroff.  V must
be large enough to accommodate the character sizes on the affected output
lines.  For the common type sizes (9-12 points), usual typesetting  prac-
tice is to set V  to 2 points greater than the point size; troff  default
is 10 point type on  a 12 point spacing.  The  current V is available  in
the .v  read-only register.   Multiple V  line separation  (as in  double
spacing) may be requested with ls.


5.2      EXTRA LINE SPACE

If a word contains a vertically tall construct requiring the output  line
containing it to have extra vertical space before or after  it (or both),

-------------------------------- Page 13 --------------------------------

that word.   In this  and  other functions  having a  pair of  delimiters
around their  parameter (here  '),  the delimiter  choice  is  arbitrary,
except that it can't  look like the  continuation of a number  expression
for N.  If N  is negative, the  output line containing  the word will  be
preceded by N  extra vertical space;  if N is  positive, the output  line
containing the word will be followed by N extra vertical space.  If  suc-
cessive requests  for extra  space apply  to the same  line, the  maximum
values are used.  The  most recently  used postline extra  line space  is
available in the .a read-only register.


5.3      BLOCKS OF VERTICAL SPACE

A block of vertical space is ordinarily requested using sp, which  honors
the no space  mode and which does  not space past  a trap.  A  contiguous
block of vertical space may be reserved using sv.

.vs N
Set vertical base-line spacing  size V  in the current  environment to  N
points.  This size is initially  12 points (1/6 inch in nroff).  With  no
argument, the previous spacing size is restored.  Transient extra  verti-
cal space available with \x'N' (see above).

.ls N
Line spacing (initially 1) in the current environment is set to +N.  With
no argument, the previous line spacing size is restored.  N-1  V's (blank
lines) are appended to each output  text line.  Appended blank lines  are
omitted, if the text or previous appended blank line reached a trap posi-
tion.

.sp N
Space vertically  N  V's in  either  direction.  With  no  argument,  the
default value of 1 V  is used.  If N is negative, the motion is  backward
(upward) and is limited to the distance to the top of the page.   Forward
(downward) motion is truncated to  the distance to the nearest trap.   If
the no space mode is on, no spacing occurs  (see ns, and rs below).   Use
'sp to suppress the break.

.sv N
Save a contiguous vertical block  of size N V's.   With no argument,  the
default value  of 1  V is  used.  If  the distance  to the  next trap  is
greater than N, N vertical space is output.  No space mode has no effect.
If this distance is less than N, no vertical space is immediately output,
but N is remembered for  later output (see os).   Later sv requests  will
overwrite any still remembered N.

.os
Output saved vertical space.  No space mode has no effect.  This  outputs
a block of vertical space requested by an earlier sv request.

-------------------------------- Page 14 --------------------------------

.ns
No space mode  (initially off)  in the  current diversion  is turned  on.
When on, the no space mode inhibits sp requests and bp requests without a
next page number.  The no space mode is turned off when a line of  output
occurs, or with rs.

.rs
Restore spacing in the current  diversion.  The no  space mode is  turned
off.

(blank text line)
Causes a break and output of a blank line exactly like sp 1.




6.    LINE LENGTH AND INDENTING

The maximum line length for fill mode may be set with ll.  The indent may
be set with in; an indent applicable to only the  next output line may be
set with ti.  The line length includes  indent space but not page  offset
space.  The line length minus the indent is the basis  for centering with
ce.  The effect of  ll, in, or  ti is delayed,  if a partially  collected
line exists, until after that line is output.  In fill mode the length of
text on an output line is less than or equal to the line length minus the
indent.  The current line  length and indent  are available in  read-only
registers .l and .i respectively.  The  length of three part titles  pro-
duced by tl (see #14) is independently set by lt.

.ll +N
Line length (initially 6.5 inches) in  the current environment is set  to
+N ems.   With no  argument, the  previous line length  is restored.   In
troff the maximum line length plus page offset is about 7.54 inches.

.in +N
The indent (initially 0)  in the current  environment is set  to +N  ems.
With no argument, the  previous indentation is  restored.  The indent  is
prepended to each output line.  Use 'in to suppress the break.

.ti +N
Temporary indent.  The next output  text line in the current  environment
will be indented a distance +N ems from the current  indent.  The result-
ing total indent may not be negative.  The current indent is not changed.
Use 'ti to suppress the break.

-------------------------------- Page 15 --------------------------------

7.    MACROS, STRINGS, DIVERSION, AND POSITION TRAPS


7.1      MACROS AND STRINGS

A macro is a named set of arbitrary lines that may be invoked by name  or
with a trap.  A string  is a named string of characters, not including  a
new-line character,  that  may be  interpolated  by name  at  any  point.
Request, macro, and  string names  share the same  name list.  Macro  and
string names may be one or two  characters long and may usurp  previously
defined request, macro, or  string names.  Any  of these entities may  be
renamed with rn or removed with rm.  Macros are created by de and di, and
appended to by am and da; di and da cause normal output to be stored in a
macro.  Strings are  created by ds  and appended  to by as.   A macro  is
invoked in the same way  as a request; a control line beginning .xx  will
interpolate the contents of macro xx.  The remainder of the line may con-
tain up to nine arguments.  The strings x and xx  are interpolated at any
desired point with  \*x and  \*(xx respectively.   String references  and
macro invocations may be nested.


7.2      COPY MODE INPUT INTERPRETATION

During the definition and extension of strings and macros (not by  diver-
sion) the  input is  read  in copy  mode.  The  input  is copied  without
interpretation except that:

  *  The contents of number registers specified by \n are interpolated.
  *  Strings specified by \* are interpolated.
  *  Arguments specified by \$ are interpolated.
  *  Concealed new-lines specified by \(new-line) are eliminated.
  *  Comments specified by \" are eliminated.
  *  \t and \a are interpreted  as ASCII horizontal  tab and SOH  respec-
     tively (#9).
  *  \\ is interpreted as \.
  *  \. is interpreted as ".".

These interpretations can be suppressed by prepending a \.  For  example,
since \\ maps into a \, \\n will copy as \n, which will be interpreted as
a number register indicator when the macro or string is reread.


7.3      ARGUMENTS

When a macro is invoked  by name, the remainder of  the line is taken  to
contain up to nine arguments.  The argument separator is the  space char-
acter, and arguments may be surrounded by double quotes to permit  imbed-
ded space characters.  Pairs of  double quotes may be imbedded in  double
quoted arguments  to represent  a single  double quote.   If the  desired
arguments won't  fit on  a  line, a  concealed new-line  may  be used  to

-------------------------------- Page 16 --------------------------------

continue on the next line.

When a macro is invoked the input level is pushed down and any  arguments
available at the  previous level  become unavailable until  the macro  is
completely read and the previous level is restored.  A macro's own  argu-
ments can be interpolated at  any point within the macro with \$N,  which
interpolates the N'th argument (1<N<9).   If an invoked argument  doesn't
exist, a null string results.   For example, the macro xx may be  defined
by

     .de xx     \" begin definition
     Today is \\$1 the \\$2.
     ..         \" end definition

and called by

     .xx Monday 14th

to produce the text

     Today is Monday the 14th.

The \$ was concealed in the definition with a prepended \.  The number of
currently available arguments is in the .$ read-only register.

No arguments are available at the top (nonmacro) level in this  implemen-
tation.  Because string referencing is implemented as an input-level push
down, no arguments are available from within a string.  No arguments  are
available within a trap-invoked macro.

Arguments are copied in copy mode onto  a stack where they are  available
for reference.  The  mechanism does  not allow an  argument to contain  a
direct reference to a long string (interpolated  at copy time) and it  is
advisable to conceal string references (with an extra \) to  delay inter-
polation until argument reference time.


7.4      DIVERSIONS

Processed output may be diverted into a macro for purposes such as  foot-
note processing  (see Tutorial  #T5)  or determining  the horizontal  and
vertical size of some text for conditional changing of pages or  columns.
A single diversion trap may be set at a specified vertical position.  The
general number registers dn and dl respectively contain the vertical  and
horizontal size  of the  most recently ended  diversion.  Processed  text
that is diverted into a  macro retains the vertical size  of each of  its
lines when reread in nofill mode regardless of the current  V.  Constant-
spaced (cs)  or emboldened  (bd)  text that  is diverted  can  be  reread
correctly only  if these modes  are again  or still in  effect at  reread
time.  One way to do this is to imbed in the diversion the appropriate cs

-------------------------------- Page 17 --------------------------------

or bd requests with the transparent mechanism described in #10.6.

Diversions may be nested and certain parameters and registers are associ-
ated with the current diversion level (the top nondiversion level  may be
thought of as the 0th diversion level).  These are the diversion trap and
associated macro, no space mode,  the internally saved marked place  (see
mk and rt), the current vertical  place (.d register), the current  high-
water text base-line (.h  register), and the  current diversion name  (.z
register).


7.5      TRAPS

Three types of  trap mechanisms  are available--page  traps, a  diversion
trap, and  an  input line  count  trap.  Macro  invocation traps  may  be
planted using wh at any page position including the top.  This trap posi-
tion may be changed using  ch.  Trap positions at or below the bottom  of
the page have no effect unless or until moved to within the page or  ren-
dered effective by an increase in page length.  Two traps  may be planted
at the same position only by  first planting them at different  positions
and then  moving one;  the  first planted  trap will  conceal the  second
unless and until the first one is moved (see Tutorial Examples #T5).   If
the first  one is moved  back, it  again conceals the  second trap.   The
macro associated with a page trap is automatically invoked when a line of
text is output whose vertical size reaches or sweeps past  the trap posi-
tion.  Reaching the bottom  of a page  springs the top  of page trap,  if
any, provided there is a next page.  The distance to  the next trap posi-
tion is available in  the .t read-only  register; if there  are no  traps
between the current  position and  the bottom of  the page, the  distance
returned is the distance to the page bottom.

A macro invocation trap effective in the current diversion may be planted
using dt.  The .t read-only register works in a diversion; if there is no
later trap a large distance is returned.  For a description of input line
count traps, see it below.

.de xx yy
Define or redefine the macro xx.  The contents of the macro begin on  the
next input line.  Input lines  are copied in copy mode until the  defini-
tion is ended by  a line beginning  with .yy, whereupon  the macro yy  is
called.  In the absence of  yy, the definition is ended by a line  begin-
ning with "..".  A macro may contain de requests provided the ending mac-
ros differ or the contained definition terminator is concealed.  ".." can
be concealed as \\.., which will copy as \.. and be reread as "..".

.am xx yy
Append to macro (append version of de).

.ds xx string
Define a string xx containing string.  Any initial double quote in string

-------------------------------- Page 18 --------------------------------

is stripped off to permit initial blanks.

.as xx string
Append string to string xx (append version of ds).

.rm xx
Remove request, macro, or string.  The name  xx is removed from the  name
list and any related storage space is freed.  Later references  will have
no effect.

.rn xx yy
Rename request, macro, or  string xx to  yy.  If yy  exists, it is  first
removed.

.di xx
Divert output to macro xx.   Normal text processing occurs during  diver-
sion except that page  offsetting is not  done.  The diversion ends  when
the request  di or  da  is encountered  without an  argument;  extraneous
requests of this type should not appear when nested diversions  are being
used.

.da xx
Divert, appending to xx (append version of di).

.wh N xx
Install a trap to  invoke xx at page  position N (in  V's); a negative  N
will be interpreted relative  to the page  bottom.  Any macro  previously
planted at N is replaced by  xx.  A zero N refers  to the top of a  page.
In the absence of xx, the first found trap at N, if any, is removed.

.ch xx N
Change the trap position for macro xx to be  N (in V's).  In the  absence
of N, the trap, if any, is removed.

.dt N xx
Install a diversion trap in the current diversion at position N (in  V's)
to invoke macro xx.  Another dt will redefine the diversion  trap.  If no
arguments are given, the diversion trap is removed.

.it N xx
Set an input line  count trap in  the current environment  to invoke  the
macro xx after N lines  of text input have been read (control or  request
lines don't count).  The text may be inline text or text interpolated  by
inline or trap-invoked macros.  If no arguments are given, the input line
count trap is removed.

.em xx
The macro xx will be invoked when all input has ended.  The effect is the
same as if the contents of  xx had been at the end of the last file  pro-
cessed.

-------------------------------- Page 19 --------------------------------

8.    NUMBER REGISTERS

A variety of parameters are  available to the  user as predefined,  named
number registers  (see Predefined  Number Registers).   In addition,  the
user may define his own named registers.   Register names are one or  two
characters long and do not conflict with request, macro, or string names.
Except for certain predefined read-only registers, a number register  can
be read, written, automatically incremented or decremented, and  interpo-
lated into the input in  a variety of formats.  One  common use of  user-
defined registers is to automatically number sections, paragraphs, lines,
etc.  A number register may be used any time numerical input is  expected
or desired and may be used in numerical expressions (#1.4).

Number registers are created and  modified using nr, which specifies  the
name, numerical value,  and the autoincrement  size.  Registers are  also
modified, if accessed with an  autoincrementing sequence.  If the  regis-
ters x and xx both contain N and have the  autoincrement size M, the fol-
lowing access sequences have the effect shown:

             ______________________________________________
            |         |      Effect on     |     Value    |
            |_Sequence|_______Register_____|_Interpolated_|
            | \nx     |         none       |       N      |
            | \n(xx   |         none       |       N      |
            | \n+x    | x incremented by M |      N+M     |
            | \n-x    | x decremented by M |      N-M     |
            | \n+(xx  | xx incremented by M|      N+M     |
            |_\n-(xx__|_xx_decremented_by_M|______N-M_____|

When interpolated, a number register  is converted to decimal  (default),
decimal with leading  zeros, lower-case  Roman, upper-case Roman,  lower-
case sequential alphabetic, or upper-case sequential alphabetic according
to the format specified by af.

.nr R +N M
The number register R is assigned the  value +N relative to the  previous
value, if any.  The increment for autoincrementing is set to M.

.af R c
Assign format c (initially Arabic) to register R.  The available  formats
are:
              ____________________________________________
             |       |              Numbering            |
             |_Format|______________Sequence_____________|
             |    1  | 0,1,2,3,4,5,...                   |
             |   001 | 000,001,002,003,004,005,...       |
             |    i  | 0,i,ii,iii,iv,v,...               |
             |    I  | 0,I,II,III,IV,V,...               |
             |    a  | 0,a,b,c,...,z,aa,ab,...,zz,aaa,...|
             |____A__|_0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,...|

-------------------------------- Page 20 --------------------------------

An Arabic format  having N  digits specifies a  field width  of N  digits
(example 2  above).   The  read-only  registers and  the  width  function
(#11.2) are always Arabic.

.rr R
Remove register R.  If many  registers are being created dynamically,  it
may become  necessary to  remove no  longer used  registers to  recapture
internal storage space for newer registers.




9.    TABS, LEADERS, AND FIELDS


9.1      TABS AND LEADERS

The ASCII horizontal tab character and the ASCII SOH (hereafter known  as
the leader character)  can both  generate either horizontal  motion or  a
string of repeated  characters.  The  length of the  generated entity  is
governed by internal tab stops specifiable with ta.  The default  differ-
ence is  that tabs  generate  motion and  leaders generate  a  string  of
periods; tc  and lc  offer the  choice of repeated  character or  motion.
There are  three  types  of internal  tab  stops--left  adjusting,  right
adjusting, and centering.  In the following table: D is the distance from
the current position on the input line (where a tab or leader was  found)
to the next tab stop;  next-string consists of the input characters  fol-
lowing the tab (or leader) up to the next tab (or leader) or end of line;
and W is the width of next-string.

       ___________________________________________________________
      |   Tab   | Length of motion or|        Location of        |
      |___type__|_repeated_characters|________next-string________|
      |   Left  |          D         | Following D               |
      |  Right  |         D-W        | Right adjusted within D   |
      |_Centered|________D-W/2_______|_Centered_on_right_end_of_D|

The length  of generated  motion is  allowed to  be negative,  that of  a
repeated character string cannot be.  Repeated character strings  contain
an integer number of characters,  and any residual distance is  prepended
as motion.  Tabs or  leaders found after  the last tab stop are  ignored,
but may be used as next-string terminators.

Tabs and leaders are not interpreted in copy mode.  \t and \a always gen-
erate a noninterpreted tab and leader respectively, and are equivalent to
tabs and leaders in copy mode.

-------------------------------- Page 21 --------------------------------

9.2      FIELDS

A field is contained between  a pair of  field delimiter characters,  and
consists of substrings  separated by  padding indicator characters.   The
field length is the distance  on the input line  from the position  where
the field begins to the next tab stop.  The difference  between the total
length of all the substrings and the field length is incorporated as hor-
izontal padding space that is divided among the indicated padding places.
The incorporated padding is allowed to be negative.  For example, if  the
field delimiter is # and the padding indicator is ^,  #^xxx^right# speci-
fies a  right-adjusted  string with  the  string 'xxx'  centered  in  the
remaining space.

.ta Nt ...
Set tab stops and  types in the  current environment at  positions N  (in
ems).  t=R, right  adjusting; t=C, centering;  t absent, left  adjusting.
Nroff tab stops are  preset every 0.8  inch; troff every  0.5 inch.   The
stop values are separated by spaces, and a value preceded by + is treated
as an increment to the previous stop  value.  With no arguments, all  tab
stops are removed.

.tc c
The tab repetition character (initially a space) in the current  environ-
ment becomes c, or is removed (reset to a space) specifying motion.

.lc c
The leader repetition character (initially  '.') in the current  environ-
ment becomes c, or is removed specifying motion.

.fc a b
The field delimiter  is set to  a; the  padding indicator is  set to  the
space character or to b, if given.  In the absence of arguments the field
mechanism is turned off.




10.   INPUT AND OUTPUT CONVENTIONS AND CHARACTER TRANSLATIONS


10.1     INPUT CHARACTER TRANSLATIONS

Ways of inputting the graphic character set were discussed in #2.1.   The
ASCII control characters horizontal tab (#9.1), SOH (#9.1), and backspace
(#10.3) are discussed elsewhere.  The new-line delimits input lines.   In
addition, STX, ETX, ENQ,  ACK, and BEL are  accepted, and may be used  as
delimiters or translated into a graphic with tr (#10.5).  All others  are
ignored.

-------------------------------- Page 22 --------------------------------

The escape character \ introduces escape sequences--causes the  following
character to mean another character or some function.  A complete list of
such sequences is given in Appendix A.  \ should not be confused with the
ASCII control character ESC of the same name.  The escape character \ can
be input with the sequence \\.  The escape character can be changed  with
ec, and all that has  been said about the default \ becomes true for  the
new escape character.  \e will print whatever the current escape  charac-
ter is.  If necessary or  convenient, the escape mechanism may be  turned
off with eo, and restored with ec.

.ec c
Set escape character (initially '\') to c, or reset to '\', if omitted.

.eo
Turn escape mechanism off.


10.2     LIGATURES

Five ligatures are available in the current troff character set--fi,  fl,
ff, ffi, and ffl.  They may be input (even in nroff) by \(fi, \(fl, \(ff,
\(Fi, and \(Fl respectively.  The ligature mode is normally on in  troff,
and automatically invokes ligatures during input.

.lg N
Ligature mode (initially  on in troff)  is turned  on if N  is absent  or
nonzero, and turned off if N=0.  If N=2, only the two character ligatures
are automatically  invoked.   Ligature mode  is  inhibited  for  request,
macro, string, register, or  file names, and  in copy mode.  This has  no
effect in nroff.


10.3     BACKSPACING, UNDERLINING, OVERSTRIKING, ETC

Unless in copy mode, the ASCII backspace character is replaced by a back-
ward horizontal motion having the  width of the space character.   Under-
lining as a form of  line drawing is discussed  in #12.4.  A  generalized
overstriking function is described in #12.1.

Nroff automatically underlines characters in the underline font, specifi-
able with uf, normally  that on font  position 2 (normally Times  Italic,
see #2.2).  In addition to ft and \fF, the underline font may be selected
by ul and cu.   Underlining is restricted  to an output device  dependent
subset of reasonable characters.

.ul N
Underline in nroff (italicize in  troff) the next N  input text lines  in
the current environment.   This causes  a switch to  the underline  font,
saving the current font for later restoration; other font changes  within
the span of a ul will take effect, but the restoration will undo the last

-------------------------------- Page 23 --------------------------------

change.  Output generated by tl (#14) is affected by the font change, but
does not decrement N.  With no argument, the default value  of 1 is used.
If N>1, there is the risk that a trap interpolated macro may provide text
lines within the span; environment switching can prevent this.

.cu N
A variant of ul that  causes every character to  be underlined in  nroff.
Identical to ul in troff.

.uf F
Underline font (initially Italic)  is set  to F.  With  no argument,  the
default Italic font is  restored.  In nroff, F  may not be on position  1
(initially Times Roman).

.up N
Upper-case the next N input text  lines in the current environment.   All
lower-case alphabetics in those lines are converted to upper-case.


10.4     CONTROL CHARACTERS

Both the control character . and the no break control character ' may  be
changed, if desired.  Such a change must be compatible with the design of
any macros used in the span of the change, and particularly of any  trap-
invoked macros.

.cc c
The basic control character (initially ".") in the current environment is
set to c, or reset to "." if no argument is provided.

.c2 c
The no break control character (initially "'") in the current environment
is set to c, or reset to "'" if no argument is provided.


10.5     OUTPUT TRANSLATION

One character can be made a stand-in for another character using tr.  All
text processing  (such as  character  comparisons) takes  place with  the
input (stand-in) character that appears  to have the  width of the  final
character.  The  graphic  translation  occurs  at the  moment  of  output
(including diversion).

.tr abcd....
Translate a into b,  c into d, etc.   If an odd  number of characters  is
given, the last one will be mapped into the space  character.  To be con-
sistent, a particular translation must stay in effect from input to  out-
put time.

-------------------------------- Page 24 --------------------------------

10.6     TRANSPARENT THROUGHPUT

An input line beginning with a \! is read in copy mode and  transparently
output (without the initial \!); the text processor is otherwise  unaware
of the line's presence.  This mechanism may pass control information to a
postprocessor or imbed control lines in a macro created by a diversion.


10.7     COMMENTS AND CONCEALED NEW-LINES

An uncomfortably  long input  line that  must stay  one line  (such as  a
string definition or nofilled text) can be split into many physical lines
by ending all but the  last one with the escape  \.  The sequence  \(new-
line) is always ignored--except in  a comment.  Comments may be  imbedded
at the end of any  line by prefacing them with  \".  The new-line at  the
end of  a comment cannot  be concealed.   A line beginning  with \"  will
appear as a blank line and behave like .sp 1; a comment can be on a  line
by itself by beginning the line with .\".




11.   LOCAL HORIZONTAL AND VERTICAL MOTIONS, AND THE WIDTH FUNCTION


11.1     LOCAL MOTIONS

The functions \v'N' and \h'N' can be used for local vertical and horizon-
tal motion respectively.  The  distance N may  be negative; the  positive
directions are rightward and downward.   A local motion is one  contained
within a line.  To avoid  unexpected vertical dislocations, it is  neces-
sary that the net vertical local motion within a word in filled text  and
otherwise within a  line balance  to zero.  The  above and certain  other
escape sequences providing local motion  are summarized in the  following
table.

-------------------------------- Page 25 --------------------------------

             |_____________|______________________________|
             |   vertical  |           effect in          |
             |_local_motion|______troff__________nroff____|
             |___\v'N'_____|__move_distance_N_____________|
             |   \u        |  12 em up     |  12 line up  |
             |   \d        |  12 em down   |  12 line down|
             |___\r________|__1_em_up______|__1_line_up___|
             |  horizontal |           effect in          |
             |_local_motion|______troff__________nroff____|
             |   \h'N'     |  move distance N             |
             |   \(space)  |  unpaddable space            |
             |___\0________|__digit-sized_space___________|
             |   \|        |  1/6 em space |  ignored     |
             |___\^________|__1/12_em_space|__ignored_____|

As  an  example,  E2  could  be  generated  by  the  sequence   E\s-2\v'-
0.4m'2\v'0.4m'\s+2; it should be  noted in this  example that the 0.4  em
vertical motions are at the smaller size.


11.2     WIDTH FUNCTION

The width function \w'string' generates the numerical width of string (in
basic units).  Size and  font changes may  be safely imbedded in  string,
and will not affect the current environment.  For example,  .ti -\w'1. 'u
would temporarily indent  leftward a  distance equal to  the size of  the
string "1. ".

The width function also sets three number registers.  The general  regis-
ters st and sb are  set respectively to the highest and lowest extent  of
string relative to the base line; then, for example, the total height  of
the string is \n(stu-\n(sbu.  In troff the general number register  ct is
set to a value between 0 and 3: 0 means that all the characters in string
were short  lower-case characters  without descenders (like  e); 1  means
that at least one  character has a  descender (like y);  2 means that  at
least one character is tall (like H); and 3 means  that both tall charac-
ters and characters with descenders are present.


11.3     MARK HORIZONTAL PLACE

The escape sequence \kx will cause the current horizontal position in the
input line to be stored  in register x.  As an example, the  construction
\kxword\h'|\nxu+2u'word will embolden word  by backing up  to almost  its
beginning and overprinting it, resulting in word.

-------------------------------- Page 26 --------------------------------

12.   OVERSTRIKE, BRACKET, LINE DRAWING, AND ZERO WIDTH FUNCTIONS


12.1     OVERSTRIKING

Automatically centered overstriking of up to nine characters is  provided
by the overstrike  function \o'string'.  The  characters in string  over-
printed with centers aligned; the total width is that of the widest char-
acter.  string should  not contain local  vertical motion.  As  examples,
\o'e\'' produces e, and \o'\(mo/' produces /.


12.2     ZERO WIDTH CHARACTERS

The function \zc will output c without  spacing over it, and can  produce
left-aligned overstruck combinations.  As examples, \zo+ will produce  o,
and \(br\z\(rn\(ul\(br will produce the smallest possible constructed box
|_|.


12.3     LARGE BRACKETS

The Special  Mathematical  Font  contains  several  bracket  construction
pieces (||||<>|||||) that  can be combined  into various bracket  styles.
The function \b'string' piles up vertically the characters in string (the
first character on top  and the last  at the bottom); the characters  are
vertically separated by 1 em and the total  pile is centered 12 em  above
the   current   base   line   (12   line   in   nroff).    For   example,
                                                      | |
\b'\(lc\(lf'E\|\b'\(rc\(rf'\x'-0.5m'\x'0.5m' produces |E|.


12.4     LINE DRAWING

The function \l'Nc' will draw a string of repeated c's towards the  right
for a distance N.  (\l is \lower case L).  If c looks like a continuation
of an expression for N, it  may be insulated from N  with a \&.  If c  is
not specified, the  _ (base  line rule) is  used (underline character  in
nroff).  If N is negative, a backward horizontal motion of size N is made
before drawing the string.  Any space resulting from N/(size of c) having
a remainder is put at the beginning (left end) of the string.  For  char-
acters that  are designed  to  be connected,  such as  base line  rule _,
underrule _ and root en _, the remainder space is covered by overlapping.
If N is less than the width of c, a single c is centered on a distance N.
As an example, a macro to underscore a string can be written

     .de US
     \\$1\l'|0\(ul'
     ..

-------------------------------- Page 27 --------------------------------

     .de BX
     \(br\\$1\(br\l'|0\(rn'\l'|0\(ul'
     ..

such that

     .US "underlined words"

and

     .BX "words in a box"

yield underlined_words and |words_in_a_box|


The  function  \L'Nc'  will  draw  a  vertical  line  consisting  of  the
(optional) character c stacked vertically  apart 1 em (1 line in  nroff),
with the first two characters  overlapped, if necessary,  to form a  con-
tinuous line.  The default character is the box rule |  (\(br); the other
suitable character is  the bold  vertical |  (\(bv).  The  line is  begun
without any initial motion relative to the current base line.  A positive
N specifies a line drawn downward and a negative N specifies a line drawn
upward.  After the line  is drawn no  compensating motions are made;  the
instantaneous base line is at the end of the line.
__________________________________________________________________________
The horizontal and  vertical line  drawing functions may  be combined  to |
produce large boxes.  The zero  width box rule and the 12-em wide  under- |
rule were designed to  form corners  when using 1  em vertical  spacings. |
For example the macro                                                     |
                                                                          |
     .de EB                                                               |
     .sp -1   \" compensate for next automatic base-line spacing          |
     .nf      \" avoid possibly overflowing word buffer                   |
     \h'-.5n'\L'|\\nZu-1'\l'\\n(.lu+1n\(ul'\L'-|\\nZu+1'\l'|0u-.5n\(ul'   |
     .fi                                                                  |
     ..                                                                   |
                                                                          |
will draw a box around some text whose beginning vertical place was saved |
in_number_register_Z_(such_as_using_.mk_Z)_as_done_for_this_paragraph.____|




13.   HYPHENATION

The automatic hyphenation may be switched  off and on.  When switched  on
with hy, several variants may be set.  A hyphenation indicator  character
may be imbedded in a word to  specify desired hyphenation points, or  may

-------------------------------- Page 28 --------------------------------

be prepended to suppress hyphenation.  In addition, the user may  specify
a small exception word list.

Only words  that consist  of a  central alphabetic  string surrounded  by
(usually  null)  nonalphabetic  strings  are  considered  candidates  for
automatic hyphenation.  Words that were input containing hyphens (minus),
em dashes (\(em),  or hyphenation  indicator characters--such as  mother-
in-law--are always subject to splitting  after those characters,  whether
automatic hyphenation is on or off.

.nh
Automatic hyphenation (initially on) in the current environment is turned
off.

.hyN
Automatic hyphenation in the current environment is turned on for N>1, or
off for N=0.  If  N=2, last lines (ones that  will cause a trap) are  not
hyphenated.  For N=4 and  8, the  last and first  two characters  respec-
tively of a word are not split off.  These values are additive; for exam-
ple, N=14 will invoke all three restrictions.  With no argument, the ini-
tial value of 1 is reset.

.hc c
The hyphenation indicator character in the current environment is set  to
c or to the default \%.  The indicator does not appear in the output.

.hw word1 ...
Specify hyphenation points in words with imbedded minus signs.   Versions
of a word with terminal  s are implied; for example, dig-it implies  dig-
its.  This list is  examined initially and  after each suffix  stripping.
The space available is small--about 128 characters.




14.   THREE PART TITLES

The titling function tl provides for automatic placement of three  fields
at the left, center, and right of a line with  a title length specifiable
with lt.  tl may be used anywhere, and is independent of the normal  text
collecting process.  A common use is in header and footer macros.

.tl 'l'c'r'
The strings l,  c, and  r are respectively  left-adjusted, centered,  and
right-adjusted in the current  title length.  Any  of the strings may  be
empty, and overlapping is permitted.  If the page number character  (ini-
tially %)  is found  within  any of  the fields,  it is  replaced by  the
current page number  having the  format assigned to  general register  %.

-------------------------------- Page 29 --------------------------------

Any character may be used as the string delimiter.

.pc c
The page number  character (initially  '%') is set  to c,  or removed  if
omitted.  The page number register remains %.

.lt +N
Length of titles (initially 6.5 inches) in the current environment is set
to +N ems.  With no argument, the previous title length is restored.  The
line length and the title length  are independent.  Indents do not  apply
to titles; page offsets do.




15.   OUTPUT LINE NUMBERING

    Automatic sequence numbering of  output lines may  be requested  with
    nm.  When in effect, a three digit, Arabic number plus  a digit space
  3 is prepended to output text lines.  The text lines are thus offset by
    four digit spaces, and otherwise  retain their line length; a  reduc-
    tion in line length may be desired  to keep the right margin  aligned
  6 with an  earlier margin.   Blank  lines, other  vertical spaces,  and
    lines generated by tl are not numbered.  Numbering can be temporarily
    suspended with nn,  or with an .nm  followed by a  later .nm +0.   In
  9 addition, a line number  indent I, and  the number-text separation  S
    may be specified in digit spaces.  Further, it can be  specified that
    only those line numbers that are multiples of some number M are to be
 12 printed (the others will appear as blank number fields).

.nm +N M S I
Set the line number  mode in the  current environment.  If  +N is  given,
line numbering is turned  on, and the  next output line numbered is  num-
bered +N.  Default values are M=1, S=1, and I=0.  Parameters  correspond-
ing to missing arguments  are unaffected; a  nonnumeric argument is  con-
sidered missing.  In the  absence of all  arguments, numbering is  turned
off; the next line number  is preserved for possible further use in  gen-
eral number register ln.

.nn N
The next N text output lines in the current environment are not numbered.
With no argument, the default value of 1 is used.

    As an example, the  paragraph portions of  this section are  numbered
    with M=3: .nm 1 3 was placed at the beginning;  .nm was placed at the
 15 end of the first paragraph;  and .nm +0 was placed  in front of  this
    paragraph; and .nm finally placed at the end.  Line lengths were also
    changed (by  \w'0000'u) to  keep  the right  side  aligned.   Another

-------------------------------- Page 30 --------------------------------

 18 example is  .nm +5  5 x  3, which  turns on numbering  with the  line
    number of the next line to be 5 greater than the last numbered  line,
    with M=5, with spacing S untouched, and with the indent I set to 3.




16.   CONDITIONAL ACCEPTANCE OF INPUT

In the following, c is a one character, built-in condition name, ! signi-
fies not, N is  a numerical expression,  string1 and string2 are  strings
delimited by any nonblank, nonnumeric  character not in the strings,  and
anything represents what is conditionally accepted.

.if c anything
If condition c  true, accept  anything as  input; in  multiline case  use
\{anything\}.

.if !c anything
If condition c false, accept anything.

.if N anything
If expression N>0, accept anything.

.if !N anything
If expression N<0, accept anything.

.if 'string1'string2' anything
If string1 identical to string2, accept anything.

.if !'string1'string2' anything
If string1 not identical to string2, accept anything.

.ie c anything
If portion of if/else; all above forms (like if).

.el anything
Else portion of if/else.

The built-in condition names are:
                _________________________________________
               | Condition|                             |
               |   Name   |           True If           |
               |__________|_____________________________|
               |     n    | Formatter is nroff          |
               |     t    | Formatter is troff          |
               |     o    | Current page number is odd  |
               |_____e____|_Current_page_number_is_even_|

-------------------------------- Page 31 --------------------------------

If the condition c is true, or if the number  N is greater than zero,  or
if the strings compare identically (including motions and character  size
and font), anything is accepted as input.  If a ! precedes the condition,
number, or string comparison, the sense of the acceptance is reversed.

Any spaces  between  the condition  and  the beginning  of  anything  are
skipped over.   The anything  can be  either a single  input line  (text,
macro, or whatever) or several input  lines.  In the multiline case,  the
first line must begin with a left delimiter \{ and the last line must end
with a right delimiter \}.

The request ie (if/else) is  identical to if  except that the  acceptance
state is remembered.  A  later and matching  el (else) request then  uses
the reverse sense of that state.  ie/el pairs may be nested.

Some examples are:

     .ne 1
     .if e .tl 'Even Page %'''

which outputs a title if the page number is even; and

     .ie \n%>1 \{\
     'sp 0.5i
     .tl 'Page %'''
     'sp |1.2i \}
     .el .sp |2.5i

which treats page 1 differently from other pages.




17.   ENVIRONMENT SWITCHING

Many of  the parameters  that control  the text  processing are  gathered
together into an  environment, which  can be switched  by the user.   The
environment parameters are  those associated  with requests  noting E  in
their Notes column; in addition, partially collected lines and words  are
in the  environment.   Everything  else is  global;  examples  are  page-
oriented parameters, diversion-oriented parameters, number registers, and
macro and string definitions.  All environments are entered with  default
parameter values.

.ev N
The environment (initially 0) is switched to environment 0<N<2.  With  no
argument, the  previous environment  is restored.  Switching  is done  in
push-down fashion so that restoring  a previous environment must be  done

-------------------------------- Page 32 --------------------------------

with .ev rather than specific reference.




18.   INSERTIONS FROM THE STANDARD INPUT

The input can be temporarily switched  to the system standard input  with
rd, which will  switch back when two  new-lines in a  row are found  (the
extra blank line is not used).  This mechanism is intended for insertions
in form-letter-like documentation.  The standard input can be the  user's
keyboard, a pipe, or a file.

.rd prompt
Read insertion from the standard input until  two new-lines in a row  are
found.  If the standard input is the user's keyboard, prompt (or a BEL if
omitted) is written onto the user's  terminal.  rd behaves like a  macro,
and arguments may be placed after prompt.

.ex
Exit from nroff/troff.  Text processing is halted exactly as if all input
had ended.

If insertions are to be taken from the terminal keyboard while output  is
being printed on the terminal,  the command line option -q will turn  off
the echoing of  keyboard input  and prompt  only with  BEL.  The  regular
input and insertion  input cannot simultaneously  come from the  standard
input.

As an example, multiple copies of a form letter may be prepared by enter-
ing the insertions for all the copies in one file to be used as the stan-
dard input, and causing the file containing the letter to reinvoke itself
using nx (#19); the process would finally be ended by an ex in the inser-
tion file.




19.   INPUT/OUTPUT FILE SWITCHING


.so file
Switch source file.  The top  input (file reading)  level is switched  to
file.  The contents of file  will be interpolated at the point the so  is
encountered.  When the new file ends, input is again taken from the  ori-
ginal file.  The so requests may be nested.

-------------------------------- Page 33 --------------------------------

.nx file
Next file is file.  The current file  is considered ended, and the  input
is immediately  switched to  file.  With  no argument  processing of  the
current file is ended.

.pi program
Pipe output to program (nroff only).  This request must occur before  any
printing occurs.  No arguments are transmitted to program.




20.   MISCELLANEOUS


.mc c N                                                                    |
Specifies that a margin character c appear a distance N ems to the  right  |
of the right margin after each nonempty text line (except  those produced  |
by tl) in the current  environment.  If the output line  is too long  (as  |
can happen in nofill  mode) the character  will be appended to the  line.  |
With no arguments the margin character is turned off.  If N is not given,  |
the previous N is used; the initial N is 0.2  inches in nroff and 1 em in  |
troff.  The margin character used with this paragraph was a 12 point  box  |
rule.                                                                      |

.tm string
After skipping initial blanks, string (rest of the line) is read in  copy
mode and written on the user's terminal.

.ab string
Prints string on the standard error output and halts without further pro-
cessing.  If string is missing, 'User Abort.' is printed.  Does not cause
a break.  The output buffer is flushed.

.ig yy
Ignore input lines.   ig behaves  exactly like  de (#7)  except that  the
input is discarded.  The input  is read in copy mode, and any  autoincre-
mented registers will be affected.

.pm t
Print macros.  The names and sizes of all defined macros and strings  are
printed on the  user's terminal;  if t is  given, only  the total of  the
sizes is printed.  The sizes are given in blocks of 128 characters.

.fl
Flush output buffer.  Used in interactive debugging to force output.  Use
'fl to suppress the break.

-------------------------------- Page 34 --------------------------------

21.   OUTPUT AND ERROR MESSAGES

The output from tm, pm, and the prompt from rd, as well as various  error
messages are written  onto the  standard message output.   The latter  is
different from the standard  output, where nroff  formatted output  goes.
By default, both are  written onto the  user's terminal, but they can  be
independently redirected.

Various error  conditions may  occur during  the operation  of nroff  and
troff.  Certain less serious errors having only local effect do not cause
processing to halt.  Two  examples are  word overflow, caused  by a  word
that is too large  to fit into the word  buffer (in fill mode), and  line
overflow, caused by an output line that grew too large to fit in the line
buffer; in both cases, a message is printed, the offending excess is dis-
carded, and the affected word or line is  marked at the point of  trunca-
tion with a '*' in nroff and a <= (\(lh)  in troff.  The philosophy is to
continue processing, if possible, because output useful for debugging may
be produced.   If  a  serious  error occurs,  processing  halts,  and  an
appropriate message is printed.   Examples are the  inability to  create,
read, or write files, and  the exceeding of certain internal limits  that
make future output unlikely to be useful.




TUTORIAL EXAMPLES




1.    INTRODUCTION

Although nroff and troff have by  design a syntax reminiscent of  earlier
text processors [6]  with the intent  of easing their  use, it is  almost
always necessary to prepare at least a small set of macro definitions  to
describe most documents.   Such common formatting  needs as page  margins
and footnotes are deliberately not built into nroff and troff.   Instead,
the macro and string definition, number register, diversion,  environment
switching, page position trap, and  conditional input mechanisms  provide
the basis for user-defined implementations.

The examples to be discussed are intended to be useful and somewhat real-
istic, but won't necessarily cover all relevant contingencies.   Explicit
numerical parameters are used in the examples to make them easier to read
and to illustrate  typical values.  Using  number registers would  reduce
the number  of places  where  numerical information  is kept,  and  would

-------------------------------- Page 35 --------------------------------

concentrate conditional parameter initialization like that which  depends
on whether troff or nroff is being used.




2.    PAGE MARGINS

As discussed  in #3,  header and  footer macros  are usually  defined  to
describe the top and  bottom page margin  areas respectively.  A trap  is
planted at page position  0 for the header,  and at -N  (N from the  page
bottom) for the footer.  The simplest such definitions might be

     .de ph  \" define page header
     'sp 1i
     ..      \" end definition
     .de pf  \" define page footer
     'bp
     ..      \" end definition
     .wh 0 ph
     .wh -1i pf

which provide blank 1 inch top and bottom margins.  The header will occur
on the first page, only if the definition and trap  exist before the ini-
tial pseudopage  transition (#3).   In fill  mode, the  output line  that
springs the footer  trap was  typically forced out  because some part  or
whole word didn't fit on it.  If anything  in the footer and header  that
follows causes a break,  that word or part  word will be forced out.   In
this and other  examples, requests  like bp  and sp  that normally  cause
breaks are invoked using the no break control character '  to avoid this.
When the  header/footer design  contains material  requiring  independent
text processing, the environment may be switched, avoiding most  interac-
tion with the running text.

A more realistic example would be

     .de ph  \" header
     .if t .tl '\(rn''\(rn'  \" troff cut mark
     .if \\n%>1 \{\
     'sp |0.5i-1        \" tl base at 0.5i
     .tl ''- % -''      \" centered page number
     .ps                \" restore size
     .ft                \" restore font
     .vs  \}            \" restore vs
     'sp |1.0i          \" space to 1.0i
     .ns                \" turn on no space mode
     ..
     .de pf             \" footer

-------------------------------- Page 36 --------------------------------

     .ps 10             \" set footer/header size
     .ft R              \" set font
     .vs 12p            \" set base-line spacing
     .if \\n%=1 \{\
     'sp |\\n(.pu-0.5i-1   \" tl base 0.5i up
     .tl ''- % -'' \}      \" first page number
     'bp
     ..
     .wh 0 ph
     .wh -1i pf

which sets the size,  font, and base-line  spacing for the  header/footer
material, and finally restores them.  This material has a page  number at
the bottom of the first page and at the  top of the remaining pages.   If
troff is used, a  cut mark is drawn with  root en's at each margin.   The
sp's refer to  absolute positions  to avoid dependence  on the  base-line
spacing.  Another reason  for this in  the footer is  that the footer  is
invoked by printing a  line whose  vertical spacing swept  past the  trap
position by possibly as much as the base-line spacing.  The no space mode
is  turned  on  at  the  end  of  ph  to  render  ineffective  accidental
occurrences of sp at the top of the running text.

The above method  of restoring  size, font, etc.,  presupposes that  such
requests (that set previous value)  are not used in the running text.   A
better scheme is save and restore both the current and previous values as
shown for size in the following:

     .de pf
     .nr s1 \\n(.s      \" current size
     .ps
     .nr s2 \\n(.s      \" previous size
     .  ---             \" rest of footer
     ..
     .de ph
     .  ---             \" header stuff
     .ps \\n(s2         \" restore previous size
     .ps \\n(s1         \" restore current size
     ..

Page numbers may  be printed  in the bottom  margin by  a separate  macro
triggered during the footer's page ejection:

     .de bn            \" bottom number
     .tl ''- % -''     \" centered page number
     ..
     .wh -0.5i-1v bn   \" tl base 0.5i up

-------------------------------- Page 37 --------------------------------

3.    PARAGRAPHS AND HEADINGS

The housekeeping associated with starting a new paragraph should be  col-
lected in a paragraph macro that, for example, does the  desired prepara-
graph spacing,  forces the  correct font,  size, base-line  spacing,  and
indent, checks  that enough  space remains  for more than  one line,  and
requests a temporary indent.

     .de pp           \" paragraph
     .br              \" break
     .ft R            \" force font,
     .ps 10           \" size,
     .vs 12p          \" spacing,
     .in 0            \" and indent
     .sp 0.4          \" prespace
     .ne 1+\\n(.Vu    \" want more than 1 line
     .ti 0.2i         \" temp indent
     ..

The first break in pp will force out any previous partial lines, and must
occur before  the vs.   The forcing  of font,  etc. is  partly a  defense
against prior error and partly to permit things like section heading mac-
ros to set parameters  only once.  The  prespacing parameter is  suitable
for troff; a larger space, at least as big as the output device  vertical
resolution, would be  more suitable  in nroff.  The  choice of  remaining
space to test for in the ne is the smallest amount greater than one  line
(the .V is the available vertical resolution).

A macro to automatically number section headings might look like:

     .de sc     \" section
     .  ---     \" force font, etc.
     .sp 0.4    \" prespace
     .ne 2.4+\\n(.Vu \" want 2.4+ lines
     .fi
     \\n+S.
     ..
     .nr S 0 1  \" init S

The usage is .sc, followed by the section heading text, followed by  .pp.
The ne test value includes one line of heading, 0.4 line in the following
pp, and a line of paragraph text.  A word consisting of the next  section
number and a period is produced to begin the heading line.  The format of
the number may be set by af (#8).

Another common form is the  labeled, indented paragraph, where the  label
protrudes left into the indent space.

     .de lp         \" labeled paragraph
     .pp

-------------------------------- Page 38 --------------------------------

     .in 0.5i       \" paragraph indent
     .ta 0.2i 0.5i  \" label, paragraph
     .ti 0
     \t\\$1\t\c\" flow into paragraph
     ..

The intended usage is ".lp label"; label will begin at 0.2 inch, and can-
not exceed a  length of  0.3 inch without  intruding into the  paragraph.
The label could be right  adjusted against 0.4 inch  by setting the  tabs
instead with .ta 0.4iR 0.5i.  The last line of lp ends with \c so that it
will become a part of the first line of text that follows.




4.    MULTIPLE COLUMN OUTPUT

The production  of multiple  column pages  requires the  footer macro  to
decide whether it was invoked  by other than the last column, so that  it
will begin  a new  column rather  than produce  the bottom  margin.   The
header can initialize a  column register that  the footer will  increment
and test.  The following is arranged for two columns, but is easily modi-
fied for more.

     .de ph       \" header
     .  ---
     .nr cl 0 1   \" init column count
     .mk          \" mark top of text
     ..
     .de pf       \" footer
     .ie \\n+(cl<2 \{\
     .po +3.4i    \" next column; 3.1+0.3
     .rt          \" back to mark
     .ns \}       \" no space mode
     .el \{\
     .po \\nMu    \" restore left margin
     .  ---
     'bp \}
     ..
     .ll 3.1i     \" column width
     .nr M \\n(.o \" save left margin

Typically a portion  of the  top of the  first page  contains full  width
text; the request for  the narrower line  length, as well as another  .mk
would be made where the two column output was to begin.

-------------------------------- Page 39 --------------------------------

5.    FOOTNOTE PROCESSING

The footnote mechanism to be described is used by imbedding the footnotes
in the input text at the point of reference, demarcated by an initial .fs
and a terminal .fe:

     .fs
     Footnote text and control lines ...
     .fe

In the following, footnotes are  processed in a separate environment  and
diverted for later printing  in the space  immediately before the  bottom
margin.  There is provision for the  case where the last collected  foot-
note doesn't completely fit in the available space.

     .de ph              \" header
     .  ---
     .nr x 0 1           \" init footnote count
     .nr y 0-\\nb        \" current footer place
     .ch pf -\\nbu       \" reset footer trap
     .if \\n(dn .fz      \" leftover footnote
     ..
     .de pf     \" footer
     .nr dn 0   \" zero last diversion size
     .if \\nx \{\
     .ev 1      \" expand footnotes in ev1
     .nf        \" retain vertical size
     .FN        \" footnotes
     .rm FN     \" delete it
     .if "\\n(.z"fy" .di       \" end overflow diversion
     .nr x 0    \" disable fx
     .ev  \}    \" pop environment
     .  ---
     'bp
     ..
     .de fx     \" process footnote overflow
     .if \\nx .di fy  \" divert overflow
     ..
     .de fs     \" footnote start
     .da FN     \" divert (append) footnote
     .ev 1      \" in environment 1
     .if \\n+x=1 .fs   \" if first, include separator
     .fi        \" fill mode
     ..
     .de fe     \" footnote end
     .br        \" finish output
     .nr z \\n(.v     \" save spacing
     .ev        \" pop ev
     .di        \" end diversion
     .nr y -\\n(dn   \" new footer position,

-------------------------------- Page 40 --------------------------------

     .if \\nx=1 .nr y -(\\n(.v-\\nz) \
                \" uncertainty correction
     .ch pf \\nyu  \" y is negative
     .if (\\n(nl+1v)>(\\n(.p+\\ny) \
     .ch pf \\n(nlu+1v      \" it didn't fit
     ..
     .de fs     \" separator
     \l'1i'     \" 1 inch rule
     .br
     ..
     .de fz          \" get leftover footnote
     .fs
     .nf             \" retain vertical size
     .fy             \" where fx put it
     .fe
     ..
     .nr b 1.0i      \" bottom margin size
     .wh 0 ph        \" header trap
     .wh 12i pf      \" footer trap, temp position
     .wh -\\nbu fx   \" fx at footer position
     .ch pf -\\nbu   \" conceal fx with pf

The header ph initializes a footnote count register x, and sets both  the
current footer trap position register  y and the footer trap itself to  a
nominal position specified in register b.  In addition, if the dn  regis-
ter indicates a leftover  footnote, fz is  invoked to reprocess it.   The
footnote start macro fs begins a diversion (append) in environment 1, and
increments the count x; if the count is one, the footnote separator fs is
interpolated.  The separator is kept in  a separate macro to permit  user
redefinition.  The footnote end  macro fe restores the previous  environ-
ment and ends the diversion after saving the spacing size in register  z.
y is then decremented by the size of the footnote,  available in dn; then
on the first  footnote, y  is further  decremented by  the difference  in
vertical base-line spacings of the two environments, to prevent the  late
triggering the footer trap  from causing  the last line  of the  combined
footnotes to overflow.  The footer trap is then set to  the lower (on the
page) of y or the current page position (nl) plus one line, to allow  for
printing the reference line.   If suggested by  x, the footer pf  rereads
the footnotes from FN in  nofill mode in environment  1, and deletes  FN.
If the footnotes were too large to fit, the macro fx will be trap-invoked
to redivert the overflow into fy, and the register dn will later  suggest
to the header whether  fy is empty.   Both pf and  fx are planted in  the
nominal footer trap position in an order  that causes fx to be  concealed
unless the pf trap  is moved.  The  footer then ends the overflow  diver-
sion, if necessary, and zeros  x to disable  fx, because the  uncertainty
correction together  with a  not too  late triggering of  the footer  can
result in the footnote rereading finishing before reaching the fx trap.

A good exercise for  the student is  to combine the  multiple column  and
footnote mechanisms.

-------------------------------- Page 41 --------------------------------

6.    THE LAST PAGE

After the last input file has ended, nroff and troff invoke the end macro
(#7), if  any, and when  it finishes,  eject the remainder  of the  page.
During the eject, any traps  encountered are processed normally.  At  the
end of this last page,  processing halts unless a partial line, word,  or
partial word remains.  If it is desired that another page be started, the
end macro

     .de en     \" end macro
     \c
     'bp
     ..
     .em en

will deposit a null partial word, and effect another last page.




REFERENCES

 [1]  UTS Programmer's Manual

 [2]  B. W.  Kernighan,  L. L.  Cherry,  Typesetting  Mathematics--User's
      Guide

 [3]  M. E. Lesk, Formatting Tables on UTS

 [4]  On-line UTS documentation

 [5]  B. W. Kernighan, A Troff Tutorial

 [6]  P. A. Crisman, Ed., The Compatible Time Sharing System, MIT  Press,
      1965, Section AH9.01 (description  of RUNOFF program on MIT's  CTSS
      system)

-------------------------------- Page 42 --------------------------------

APPENDIX A.    ESCAPE SEQUENCES FOR CHARACTERS, INDICATORS, AND FUNCTIONS

        Escape
Section Sequence      Meaning
 10.1   \\            \ (to prevent or delay the interpretation of \)
 10.1   \e            Printable version of the current escape character.
  2.1   \'            ' (acute accent); equivalent to \(aa
  2.1   \`            ` (grave accent); equivalent to \(ga
  2.1   \-            - Minus sign in the current font
  7     \.            Period (dot) (see de)
 11.1   \(space)      Unpaddable space size space character
 11.1   \0            Digit width space
 11.1   \|            1
 11.1   \^            12 em half-narrow space (zero width in nroff)
  4.1   \&            Nonprinting, zero width character
 10.6   \!            Transparent line indicator
 10.7   \"            Beginning of comment
  7.3   \$N           Interpolate argument 1<N<9
 13     \%            Default optional hyphenation character
  2.1   \(xx          Character named xx
  7.1   \*x, \*(xx    Interpolate string x or xx
  9.1   \a            Noninterpreted leader character
 12.3   \b'abc...'    Bracket building function
  4.2   \c            Interrupt text processing
 11.1   \d            Downward 12 em vertical motion (12 line in nroff)
  2.2   \fx,\f(xx,\fN Change to font named x or xx, or position N
 11.1   \h'N'         Local horizontal motion; move right N (<0 left)
 11.3   \kx           Mark horizontal input place in register x
 12.4   \l'Nc'        Horizontal line drawing function (with optional c)
 12.4   \L'Nc'        Vertical line drawing function (with optional c)
  8     \nx,\n(xx     Interpolate number register x or xx
 12.1   \o'abc...'    Overstrike characters a, b, c, ...
  4.1   \p            Break and spread output line
 11.1   \r            Reverse em vertical motion (reverse line in nroff)
  2.3   \sN,\s+N      Point size change function
  9.1   \t            Noninterpreted horizontal tab
 11.1   \u            Upward 12 em vertical motion (12 line in nroff)
 11.1   \v'N'         Local vertical motion; move down N (<0 up)
 11.2   \w'string'    Interpolate width of string
  5.2   \x'N'         Extra line space function (<0 before, >0 after)
 12.2   \zc           Print c with zero width (without spacing)
 16     \{            Begin conditional input
 16     \}            End conditional input
 10.7   \(new-line)   Concealed (ignored) new-line
        \X            X, any character not listed above

The escape sequences \\, \., \", \$, \*, \a, \n, \t, and \(new-line)  are
interpreted in copy mode (#7.2).

-------------------------------- Page 43 --------------------------------

APPENDIX B.    PREDEFINED NUMBER REGISTERS

                      General Number Registers
Section  Name  Description
  3      %     Current page number.
         c.    Number of lines read from current input file.
 11.2    ct    Character type (set by width function).
  7.4    dl    Width (maximum) of last completed diversion.
  7.4    dn    Height (vertical size) of last completed diversion.
         dw    Current day of the week (1-7).
         dy    Current day of the month (1-31).
 11.3    hp    Current horizontal place on input line.
         hr    Current hour of the day (0-23).
         jd    Julian date; current day of the year (1-366).
 15      ln    Output line number.
         mn    Current minute of the hour (0-59).
         mo    Current month (1-12).
  4.1    nl    Vertical position of last printed text base-line.
 11.2    sb    Depth below base line (generated by width function).
         sc    Current second of the minute (0-59).
 11.2    st    Height above base line (generated by width function).
         yr    Last two digits of current year.

                       Read-Only Number Registers
Section  Name  Description
  7.3    .$    Number of arguments available at the current macro level.
         .A    Set to 1 in troff, if -a option used; always 1 in nroff.
 11.1    .H    Available horizontal resolution in basic units.
         .L    Current line spacing parameter from ls request.
         .P    Set to 1 if the current page is being printed; else 0.
         .T    Set to 1 in nroff, if -T option used; always 0 in troff.
 11.1    .V    Available vertical resolution in basic units.
  5.2    .a    Postline extra line space most recently caused by \x'N'.
         .c    Number of lines read from current input file.
  7.4    .d    Current vertical place in current diversion;
                  equal to nl, if no diversion.
  2.2    .f    Current font as physical quadrant (1-4).
  4      .h    Base-line high-water mark on current page or diversion.
  6      .i    Current indent.
  4.1    .j    Current adjustment mode and type.
         .k    Horizontal size of current line.
  6      .l    Current line length.
  4      .n    Length of text portion on previous output line.
  3      .o    Current page offset.
  3      .p    Current page length.
  2.3    .s    Current point size.
  7.5    .t    Distance to the next trap.
  4.1    .u    Equal to 1 in fill mode and 0 in nofill mode.
  5.1    .v    Current vertical line spacing.
 11.2    .w    Width of previous character.

-------------------------------- Page 44 --------------------------------

         .x    Reserved version-dependent register.
         .y    Reserved version-dependent register.
  7.4    .z    Name of current diversion.

-------------------------------- Page 45 --------------------------------

APPENDIX C.    COMMAND SUMMARY

Notes

B         .xx causes a break; 'xx suppresses the break.
D         Mode or relevant parameters associated with current diversion.
E         Relevant parameters are a part of the current environment.
T         has effect in troff only
v,p,m,u   Default scale indicator; if not specified, scale is ignored.



1.  General Explanation


2.  Font and Character Size Control

.ps +N          Point size; also \s+N. (E,T)
.ss N           Space character size set to N/36 em. (E,T)
.cs F N M       Constant character space (width) mode (font F). (T)
.bd F N         Embolden font F by N-1 units. (T)
.bd S F N       Embolden Special Font when current font is F. (T)
.ft F           Change to font F = x, xx, or 1-4. (E)
.fp N F         Font named F mounted on physical position 1<N<4.
.fz F N         This forces font 'F' to be in size 'N'.


3.  Page Control

.pl +N          Page length. (v)
.bp +N          Eject current page; next page number N. (B,v)
.pn +N          Next page number N.
.po +N          Page offset. (v)
.ne N           Need N vertical space (V = vertical spacing). (D,v)
.mk R           Mark current vertical place in register R. (D)
.rt +N          Return (upward only) to marked vertical place. (D,v)


4.  Text Filling, Adjusting, and Centering

.br             Break. (B)
.fi             Fill output lines. (B,E)
.nf             No filling or adjusting of output lines. (B,E)
.ad c           Adjust output lines with mode c. (E)
.na             No output line adjusting. (E)
.ce N           Center following N input text lines. (B,E)

-------------------------------- Page 46 --------------------------------

5.  Vertical Spacing

.vs N           Vertical base line spacing. (E,p)
.ls N           Output N-1 V's after each text output line. (E)
.sp N           Space vertical distance N in either direction. (B,v)
.sv N           Save vertical distance N. (v)
.os             Output saved vertical distance.
.ns             Turn no space mode on. (D)
.rs             Restore spacing; turn no space mode off. (D)
(blank text line)   Same as .sp 1


6.  Line Length and Indenting

.ll +N          Line length. (E,m)
.in +N          Indent. (B,E,m)
.ti +N          Temporary indent. (B,E,m)


7.  Macros, Strings, Diversion, and Position Traps

.de xx yy       Define or redefine macro xx; end at call of yy.
.am xx yy       Append to a macro.
.ds xx string   Define a string xx containing string.
.as xx string   Append string to string xx.
.rm xx          Remove request, macro, or string.
.rn xx yy       Rename request, macro, or string xx to yy.
.di xx          Divert output to macro xx. (D)
.da xx          Divert and append to xx. (D)
.wh N xx        Set location trap; negative is w.r.t. page bottom. (v)
.ch xx N        Change trap location. (v)
.dt N xx        Set a diversion trap. (D,v)
.it N xx        Set an input line count trap. (E)
.em xx          End macro is xx.


8.  Number Registers

.nr R +N M      Define and set number register R; autoincrement by M. (u)
.af R c         Assign format to register R (c=1, i, I, a, A).
.rr R           Remove register R.


9.  Tabs, Leaders, and Fields

.ta Nt ...      Tab settings; left type, unless t=R or C. (E,m)
.tc c           Tab repetition character. (E)
.lc c           Leader repetition character. (E)
.fc a b         Set field delimiter a and pad character b.

-------------------------------- Page 47 --------------------------------

10.  Input and Output Conventions and Character Translations

.ec c           Set escape character.
.eo             Turn off escape character mechanism.
.lg N           Ligature mode on if N>0.
.ul N           Underline (italicize in troff) N input lines. (E)
.cu N           Continuous underline in nroff; like ul in troff. (E)
.uf F           Underline font set to F (to be switched to by ul).
.up N           Upper-case the next N input text lines.
.cc c           Set control character to c. (E)
.c2 c           Set the no break control character to c. (E)
.tr abcd....    Translate a to b, etc., on output.


11.  Local Horizontal and Vertical Motions, and the Width Function


12.  Overstrike, Bracket, Line Drawing, and Zero Width Functions


13.  Hyphenation

.nh             No hyphenation. (E)
.hy N           Hyphenate; N = mode. (E)
.hc c           Hyphenation indicator character c. (E)
.hw word1 ...   Exception words.


14.  Three Part Titles

.tl 'l'c'r'     Three part title.
.pc c           Page number character.
.lt +N          Length of title. (E,m)


15.  Output Line Numbering

.nm +N M S I    Number mode on or off, set parameters. (E)
.nn N           Do not number next N lines. (E)

-------------------------------- Page 48 --------------------------------

16.  Conditional Acceptance of Input

.if c cmd       If condition c true, accept cmd as input;
.if !c cmd      If condition c false, accept cmd.
.if N cmd       If expression N>0, accept cmd. (u)
.if !N cmd      If expression N<0, accept cmd. (u)
.if 's't' cmd   If s identical to t, accept cmd.
.if !'s't' cmd  If s not identical to t, accept cmd.
.ie c cmd       If portion of if/else; in all above forms. (u)
.el cmd         Else portion of if/else.


17.  Environment Switching

.ev N           Environment switched (push down).


18.  Insertions from the Standard Input

.rd prompt      Read insertion.
.ex             Exit from nroff/troff.


19.  Input/Output File Switching

.so file        Switch source file (push down).
.nx file        Next file.
.pi program     Pipe output to program (nroff only).


20.  Miscellaneous

.mc c N         Set margin character c and separation N. (E,m)
.tm string      Print string on terminal (standard error output).
.ab string      Print string on standard error and halt.
.ig yy          Ignore till call of yy.
.pm t           Print macro names and sizes; with t show only total size.
.fl             Flush output buffer. (B)


21.  Output and Error Messages

-------------------------------- Page 49 --------------------------------

Alphabetical Request and Section Number Cross Reference

ab  20        ds   7        ie  16        nm  15        rs   5
ad   4        dt   7        if  16        nn  15        rt   3
af   8        ec  10        ig  20        nr   8        so  19
am   7        el  16        in   6        ns   5        sp   5
as   7        em   7        it   7        nx  19        ss   2
bd   2        eo  10        lc   9        os   5        sv   5
bp   3        ev  17        lg  10        pc  14        ta   9
br   4        ex  18        li  10        pi  19        tc   9
c2  10        fc   9        ll   6        pl   3        ti   6
cc  10        fi   4        ls   5        pm  20        tl  14
ce   4        fl  20        lt  14        pn   3        tm  20
ch   7        fp   2        mc  20        po   3        tr  10
cs   2        ft   2        mk   3        ps   2        uf  10
cu  10        fz   2        na   4        rd  18        ul  10
da   7        hc  13        ne   3        rm   7        up  10
de   7        hw  13        nf   4        rn   7        vs   5
di   7        hy  13        nh  13        rr   8        wh   7
