MirOS Manual: 17.msmacros(USD)


            Typing Documents on the UNIX System:
         Using the -ms Macros with Troff and Nroff

                         M. E. Lesk

                          ABSTRACT

          This document describes a set of  easy-to-use
     macros for preparing documents on the UNIX system.
     Documents may be produced  on  either  the  photo-
     typesetter  or  on  a  computer  terminal, without
     changing the input.

          The macros provide facilities for paragraphs,
     sections  (optionally  with  automatic numbering),
     page titles, footnotes,  equations,  tables,  two-
     column format, and cover pages for papers.

          This memo includes, as an appendix, the  text
     of  the  ``Guide to Preparing Documents with -ms''
     which contains additional examples of features  of
     -ms.

          This manual is a revision of,  and  replaces,
     ``Typing  Documents  on UNIX,'' dated November 22,
     1974.

     Introduction. This memorandum describes  a  package  of
commands to produce papers using the troff and nroff format-
ting programs on the UNIX system. As with other roff-derived
programs, text is prepared interspersed with formatting com-
mands. However, this package, which  itself  is  written  in
troff  commands,  provides  higher-level commands than those
provided with the basic troff program. The  commands  avail-
able in this package are listed in Appendix A.

     Text. Type normally, except that instead  of  indenting
for  paragraphs,  place  a  line reading ``.PP'' before each
paragraph. This will produce indenting and extra space.

Alternatively, the command .LP that was used here will  pro-
duce a left-aligned (block) paragraph. The paragraph spacing
can be changed: see below under ``Registers.''

     Beginning. For  a  document  with  a  paper-type  cover
sheet, the input should start as follows:

                        July 4, 2014

USD:17-2           Using the -ms Macros with Troff and Nroff

        [optional overall format .RP - see below]
        .TL
        Title of document (one or more lines)
        .AU
        Author(s) (may also be several lines)
        .AI
        Author's institution(s)
        .AB
        Abstract; to be placed on the cover sheet of a paper.
        Line length is 5/6 of normal; use .ll here to change.
        .AE  (abstract end)
        text ... (begins with .PP, which see)

To omit some of the standard headings (e.g. no abstract,  or
no  author's institution) just omit the corresponding fields
and command lines. The word ABSTRACT can  be  suppressed  by
writing ``.AB no'' for ``.AB''. Several interspersed .AU and
.AI lines can be used for multiple authors. The headings are
not compulsory: beginning with a .PP command is perfectly OK
and will just start printing an ordinary paragraph. Warning:
You  can't  just  begin a document with a line of text. Some
-ms command must precede any text input.  When in doubt, use
.LP  to  get proper initialization, although any of the com-
mands .PP, .LP, .TL, .SH, .NH is good enough. Figure 1 shows
the  legal  arrangement  of commands at the start of a docu-
ment.

     Cover Sheets and First Pages. The first line of a docu-
ment  signals  the general format of the first page. In par-
ticular, if it  is  ".RP"  a  cover  sheet  with  title  and
abstract is prepared. The default format is useful for scan-
ning drafts.

     In general -ms is arranged so that only one form  of  a
document  need  be  stored, containing all information;  the
first command gives the format, and  unnecessary  items  for
that format are ignored.

     Warning: don't put extraneous material between the  .TL
and  .AE  commands.  Processing of the titling items is spe-
cial, and other data placed in them may not  behave  as  you
expect.  Don't forget that some -ms command must precede any
input text.

     Page headings. The -ms macros, by default, will print a
page heading containing a page number (if greater than 1). A
default page footer is provided only  in  nroff,  where  the
date  is  used.  The  user can make minor adjustments to the
page headings/footings by redefining the strings LH, CH, and
RH which are the left, center and right portions of the page
headings, respectively; and the  strings  LF,  CF,  and  RF,
which  are  the  left, center and right portions of the page
footer. For more complex formats, the user can redefine  the

                        July 4, 2014

Using the -ms Macros with Troff and Nroff           USD:17-3

macros  PT and BT, which are invoked respectively at the top
and bottom of each page. The margins (taken  from  registers
HM  and  FM  for the top and bottom margin respectively) are
normally 1 inch; the page header/footer are in the middle of
that  space.  The  user who redefines these macros should be
careful not to change parameters such as point size or  font
without resetting them to default values.

     Multi-column formats. If you place the command  ``.2C''
in  your  document,  the  document will be printed in double
column format beginning at that point.  This feature is  not
too  useful in computer terminal output, but is often desir-
able on the typesetter. The command ``.1C'' will go back  to
one-column  format  and also skip to a new page. The ``.2C''
command is actually a special case of the command

        .MC [column width [gutter width]]

which makes multiple columns with the specified  column  and
gutter  width;  as  many columns as will fit across the page
are used. Thus triple, quadruple, ... column  pages  can  be
printed.  Whenever  the number of columns is changed (except
going from full width to some larger number  of  columns)  a
new page is started.

     Headings. To produce a special heading, there  are  two
commands. If you type

        .NH
        type section heading here
        may be several lines

you will get automatically numbered section headings (1,  2,
3, ...), in boldface. For example,

    .NH
    Care and Feeding of Department Heads

produces

1. Care and Feeding of Department Heads

     Alternatively,

        .SH
        Care and Feeding of Directors

will print the heading with no number added:

Care and Feeding of Directors

     Every section heading, of either type, should  be  fol-
lowed  by  a paragraph beginning with .PP or .LP, indicating
the end of the heading. Headings may contain more  than  one

                        July 4, 2014

USD:17-4           Using the -ms Macros with Troff and Nroff

line of text.

     The .NH command also supports  more  complex  numbering
schemes. If a numerical argument is given, it is taken to be
a ``level'' number and an appropriate sub-section number  is
generated.   Larger   level  numbers  indicate  deeper  sub-
sections, as in this example:

        .NH
        Erie-Lackawanna
        .NH 2
        Morris and Essex Division
        .NH 3
        Gladstone Branch
        .NH 3
        Montclair Branch
        .NH 2
        Boonton Line

generates:

2. Erie-Lackawanna

2.1. Morris and Essex Division

2.1.1. Gladstone Branch

2.1.2. Montclair Branch

2.2. Boonton Line

     An explicit ``.NH 0'' will reset the numbering of level
1 to one, as here:

        .NH 0
        Penn Central

1.  Penn Central

     Indented paragraphs. (Paragraphs with hanging  numbers,
e.g. references.) The sequence

        .IP [1]
        Text for first paragraph, typed
        normally for as long as you would
        like on as many lines as needed.
        .IP [2]
        Text for second paragraph, ...

produces

[1]  Text for first paragraph, typed normally for as long as
     you would like on as many lines as needed.

                        July 4, 2014

Using the -ms Macros with Troff and Nroff           USD:17-5

[2]  Text for second paragraph, ...

A series of indented paragraphs may be followed by an  ordi-
nary  paragraph  beginning  with  .PP  or  .LP, depending on
whether you wish indenting or not. The command .LP was  used
here.

     More sophisticated uses of .IP are  also  possible.  If
the  label  is omitted, for example, a plain block indent is
produced.

        .IP
        This material will
        just be turned into a
        block indent suitable for quotations or
        such matter.
        .LP

will produce

     This material will just be turned into a  block  indent
     suitable for quotations or such matter.

If a non-standard amount of indenting is required, it may be
specified  after the label (in character positions) and will
remain in effect until the next .PP or .LP. Thus,  the  gen-
eral form of the .IP command contains two additional fields:
the label and the indenting length.  For example,

        .IP first: 9
        Notice the longer label, requiring larger
        indenting for these paragraphs.
        .IP second:
        And so forth.
        .LP

produces this:

first:   Notice the longer label, requiring larger indenting
         for these paragraphs.

second:  And so forth.

It is also possible to produce multiple nested indents;  the
command  .RS  indicates  that  the  next .IP starts from the
current indentation level. Each .RE will eat up one level of
indenting  so  you  should balance .RS and .RE commands. The
.RS command should be thought of as ``move right''  and  the
.RE command as ``move left''. As an example

                        July 4, 2014

USD:17-6           Using the -ms Macros with Troff and Nroff

        .IP 1.
        Bell Laboratories
        .RS
        .IP 1.1
        Murray Hill
        .IP 1.2
        Holmdel
        .IP 1.3
        Whippany
        .RS
        .IP 1.3.1
        Madison
        .RE
        .IP 1.4
        Chester
        .RE
        .LP

will result in

1.   Bell Laboratories

     1.1  Murray Hill

     1.2  Holmdel

     1.3  Whippany

          1.3.1Madison

     1.4  Chester

All of these  variations  on  .LP  leave  the  right  margin
untouched.   Sometimes,  for  purposes such as setting off a
quotation, a paragraph indented on both right  and  left  is
required.

     A  single  paragraph  like  this  is  obtained  by
     preceding  it  with .QP. More complicated material
     (several paragraphs) should be bracketed with  .QS
     and .QE.

Emphasis. To get italics (on the typesetter) or  underlining
(on the terminal) say

        .I
        as much text as you want
        can be typed here
        .R

as was done for these three words. The .R  command  restores
the  normal  (usually Roman) font. If only one word is to be
italicized, it may be just given on the  line  with  the  .I

                        July 4, 2014

Using the -ms Macros with Troff and Nroff           USD:17-7

command,

                .I word

and in this case no .R is needed  to  restore  the  previous
font. Boldface can be produced by

        .B
        Text to be set in boldface
        goes here
        .R

and also will be underlined on the terminal or line printer.
As with .I, a single word can be placed in boldface by plac-
ing it on the same line as the .B command.

     A few size changes can be specified similarly with  the
commands  .LG  (make  larger),  .SM  (make smaller), and .NL
(return to normal size). The size change is two points;  the
commands  may be repeated for increased effect (here one .NL
canceled two .SM commands).

     If actual underlining  as  opposed  to  italicizing  is
required on the typesetter, the command

                .UL word

will underline a word.  There is no way to underline  multi-
ple words on the typesetter.

     Footnotes. Material placed between lines with the  com-
mands  .FS  (footnote)  and  .FE (footnote end) will be col-
lected, remembered, and finally placed at the bottom of  the
current  page*. By default, footnotes are 11/12th the length
of normal text, but this can be changed using the FL  regis-
ter (see below).

     Displays and Tables. To prepare displays of lines, such
as  tables,  in  which  the lines should not be re-arranged,
enclose them in the commands .DS and .DE

        .DS
        table lines, like the
        examples here, are placed
        between .DS and .DE
        .DE

By default, lines between  .DS  and  .DE  are  indented  and
left-adjusted. You can also center lines, or retain the left
margin. Lines bracketed by .DS C and .DE commands  are  cen-
tered  (and  not  re-arranged); lines bracketed by .DS L and
_________________________
* Like this.

                        July 4, 2014

USD:17-8           Using the -ms Macros with Troff and Nroff

.DE are left-adjusted, not indented, and not re-arranged.  A
plain  .DS  is  equivalent to .DS I, which indents and left-
adjusts.  Thus,

                 these lines were preceded
                  by .DS C and followed by
                       a .DE command;

whereas

these lines were preceded
by .DS L and followed by
a .DE command.

Note that .DS C centers each line; there is a variant .DS  B
that  makes  the display into a left-adjusted block of text,
and then centers that entire block. Normally  a  display  is
kept  together,  on  one  page.  If  you wish to have a long
display which may be split across page boundaries, use  .CD,
.LD,  or .ID in place of the commands .DS C, .DS L, or .DS I
respectively. An extra argument to the .DS I or .DS  command
is  taken  as  an  amount to indent. Note: it is tempting to
assume that .DS R will right adjust lines,  but  it  doesn't
work.

     Boxing words or lines. To draw rectangular boxes around
words the command

        .BX word
            ____
will print |_o__d_|as shown. The boxes will not be neat  on  a
terminal,  and  this  should not be used as a substitute for
italics.
 Longer pieces of text may be boxed by  enclosing  them  with
file, you can print it on a terminal with the command*

   nroff -ms file

and you can print it on the typesetter with the command

   troff -ms file

(many options are possible). In each case, if your  document
is  stored  in  several  files,  just list all the filenames
where we have used ``file''.  If  equations  or  tables  are
used, eqn and/or tbl must be invoked as preprocessors.

     References and further study. If you have to  do  Greek
or mathematics, see eqn [1] for equation setting. To aid eqn
users,  -ms  provides  definitions  of  .EQ  and  .EN  which
_________________________
* If .2C was used, pipe the nroff output  through  col;
make the first line of the input ``.pi /usr/bin/col.''

                        July 4, 2014

Using the -ms Macros with Troff and Nroff           USD:17-9

normally center the equation and set  it  off  slightly.  An
argument on .EQ is taken to be an equation number and placed
in the right margin near the equation.  In  addition,  there
are  three  special arguments to EQ: the letters C, I, and L
indicate centered (default),  indented,  and  left  adjusted
equations,  respectively. If there is both a format argument
and an equation number, give the format argument  first,  as
in

                .EQ L (1.3a)

for a left-adjusted equation numbered (1.3a).

     Similarly, the  macros  .TS  and  .TE  are  defined  to
separate  tables  (see [2]) from text with a little space. A
very long table with a heading may be broken across pages by
beginning it with .TS H instead of .TS, and placing the line
.TH in the table data after the heading.  If the  table  has
no heading repeated from page to page, just use the ordinary
.TS and .TE macros.

     To learn more about troff see [3] for a general  intro-
duction, and [4] for the full details (experts only). Infor-
mation on related UNIX commands is in [5]. For jobs that  do
not seem well-adapted to -ms, consider other macro packages.
It is often far easier to write a  specific  macro  packages
for  such tasks as imitating particular journals than to try
to adapt -ms.

     Acknowledgment. Many thanks are due to Brian  Kernighan
for  his help in the design and implementation of this pack-
age, and for his assistance in preparing this manual.

                         References

[1]  B. W. Kernighan and L. L. Cherry, Typesetting Mathemat-
     ics - Users Guide (2nd edition), Bell Laboratories Com-
     puting Science Report no. 17.

[2]  M. E. Lesk, Tbl - A  Program  to  Format  Tables,  Bell
     Laboratories Computing Science Report no. 45.

[3]  B. W. Kernighan, A Troff Tutorial,  Bell  Laboratories,
     1976.

[4]  J.  F.  Ossanna,  Nroff/Troff  Reference  Manual,  Bell
     Laboratories Computing Science Report no. 51.

[5]  K.  Thompson  and  D.  M.  Ritchie,  UNIX  Programmer's
     Manual, Bell Laboratories, 1978.

                        July 4, 2014

USD:17-10          Using the -ms Macros with Troff and Nroff

                         Appendix A
                      List of Commands

1CReturn to single column format. LGIncrease type size.
2CStart double column format.     LPLeft aligned block paragraph.
ABBegin abstract.
AEEnd abstract.
AISpecify author's institution.
AUSpecify author.                 NDChange or cancel date.
B Begin boldface.                 NHSpecify numbered heading.
DAProvide the date on each page.  NLReturn to normal type size.
DEEnd display.                    PPBegin paragraph.
DSStart display (also CD, LD, ID).
ENEnd equation.                   R Return to regular font (usually Roman).
EQBegin equation.                 REEnd one level of relative indenting.
FEEnd footnote.                   RPUse released paper format.
FSBegin footnote.                 RSRelative indent increased one level.
I Begin italics.                  SHSpecify section heading.
                                  SMChange to smaller type size.
IPBegin indented paragraph.       TLSpecify title.
KERelease keep.
KFBegin floating keep.            ULUnderline one word.
KSStart keep.

                       Register Names

     The following register names are  used  by  -ms  inter-
nally.  Independent  use  of these names in one's own macros
may produce  incorrect  output.  Note  that  no  lower  case
letters are used in any -ms internal name.

               Number registers used in -ms
:    DW    GW    HM   IQ    LL    NA   OJ    PO    T.   TV
#T   EF    H1    HT   IR    LT    NC   PD    PQ    TB   VS
.T   FC    H2    IF   IT    MF    ND   PE    PS    TC   WF
1T   FL    H3    IK   KI    MM    NF   PF    PX    TD   YE
AV   FM    H4    IM   L1    MN    NS   PI    RO    TN   YY
CW   FP    H5    IP   LE    MO    OI   PN    ST    TQ   ZN

               String registers used in -ms
'    A5    CB    DW   EZ    I     KF   MR    R1    RT   TL
`    AB    CC    DY   FA    I1    KQ   ND    R2    S0   TM
^    AE    CD    E1   FE    I2    KS   NH    R3    S1   TQ
~    AI    CF    E2   FJ    I3    LB   NL    R4    S2   TS
:    AU    CH    E3   FK    I4    LD   NP    R5    SG   TT
,    B     CM    E4   FN    I5    LG   OD    RC    SH   UL
1C   BG    CS    E5   FO    ID    LP   OK    RE    SM   WB
2C   BT    CT    EE   FQ    IE    ME   PP    RF    SN   WH
A1   C     D     EL   FS    IM    MF   PT    RH    SY   WT
A2   C1    DA    EM   FV    IP    MH   PY    RP    TA   XD
A3   C2    DE    EN   FY    IZ    MN   QF    RQ    TE   XF

                        July 4, 2014

Using the -ms Macros with Troff and Nroff          USD:17-11

A4   CA    DS    EQ   HO    KE    MO   R     RS    TH   XK

           Figure 1:  Order of Commands in Input
                              line   from   5.612,3.388   to
                              5.612,2.888      line     from
                              4.237,4.888 to 4.237,4.763  to
                              5.612,4.763      line     from
                              3.175,5.700 to 3.175,5.513  to
                              5.612,5.513      line     from
                              3.237,9.700 to 3.237,9.512  to
                              2.425,9.512      line     from
                              4.237,6.825   to   4.237,5.138
                              line   from   4.212,5.237   to
                              4.237,5.138   to   4.263,5.237
                              line   from   2.425,6.950   to
                              2.425,6.825 to 5.612,6.825  to
                              5.612,4.638      line     from
                              5.587,4.737 to 5.612,4.638  to
                              5.638,4.737      line     from
                              2.425,9.387 to 3.175,9.387  to
                              3.175,6.700      line     from
                              3.150,6.800 to 3.175,6.700  to
                              3.200,6.800      line     from
                              2.425,10.200  to  3.237,10.200
                              to   3.237,9.950   line   from
                              3.212,10.050 to 3.237,9.950 to
                              3.262,10.050     line     from
                              5.612,4.388   to   5.612,3.575
                              line   from   5.587,3.675   to
                              5.612,3.575   to   5.638,3.675
                              line   from   3.175,6.388   to
                              3.175,5.825     line      from
                              3.150,5.925  to 3.175,5.825 to
                              3.200,5.925     line      from
                              2.425,7.950   to   2.425,7.200
                              line   from   2.400,7.300   to
                              2.425,7.200   to   2.450,7.300
                              line   from   2.425,8.950   to
                              2.425,8.137      line     from
                              2.400,8.237 to 2.425,8.137  to
                              2.450,8.237      line     from
                              2.425,10.387  to   2.425,9.200
                              line   from   2.400,9.300   to
                              2.425,9.200   to   2.450,9.300
                              "RP"   at   3.175,9.796  ljust
                              "text..." at 5.487,3.483 ljust
                              "PP,  LP" at 5.425,4.483 ljust
                              "NH, SH" at 3.987,4.983  ljust
                              "AE" at 3.112,5.733 ljust "AB"
                              at 3.112,6.546 ljust  "AI"  at
                              2.362,7.046   ljust   "AU"  at
                              2.362,7.983  ljust   "TL"   at
                              2.362,9.046 ljust

                        July 4, 2014

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.