





     


                 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 phototype-
          setter 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 format-
     ting commands.  However, this package, which itself is writ-
     ten in troff commands, provides higher-level  commands  than
     those  provided  with the basic troff program.  The commands
     available 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 spac-
     ing can be changed: see below under ``Registers.''

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









     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 head-
     ings are not compulsory: beginning with  a  .PP  command  is
     perfectly  OK and will just start printing an ordinary para-
     graph.  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 commands .PP, .LP, .TL, .SH, .NH is good
     enough.  Figure 1 shows the legal arrangement of commands at
     the start of a document.

          Cover Sheets and First Pages.  The first line of a doc-
     ument 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
     scanning 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
     macros  PT and BT, which are invoked respectively at the top









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


     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
     line of text.









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


          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-sec-
     tions, 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.











     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 cur-
     rent  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














     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.1
                    Madison

          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 pre-
          ceding 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









     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
     .DE are left-adjusted, not indented, and not re-arranged.  A
     -----------
     * Like this.









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


     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 dis-
     play 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 word-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|
     |.B1 and .B2:                                              |
     |                                                          |
     |     .B1                                                  |
     |     text...                                              |
     |     .B2                                                  |
     |                                                          |
     |as has been done here.                                    |
     +----------------------------------------------------------+

          Keeping  blocks  together.  If you wish to keep a table
     or other block of lines together on a page, there are ``keep
     -  release''  commands.  If a block of lines preceded by .KS
     and followed by .KE does not fit on  the  remainder  of  the
     current  page, it will begin on a new page.  Lines bracketed
     by .DS and .DE commands are automatically kept together this
     way.   There  is  also  a  ``keep floating'' command: if the
     block to be kept together is preceded by .KF instead of  .KS
     and  does not fit on the current page, it will be moved down
     through the text until the top of the next page.   Thus,  no
     large blank space will be introduced in the document.









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


          Nroff/Troff  commands.   Among the useful commands from
     the basic formatting programs are the following.   They  all
     work with both typesetter and computer terminal output:

          .bp - begin new page.
          .br - ``break'', stop running text
                    from line to line.
          .sp n - insert n blank lines.
          .na - don't adjust right margins.


          Date.   By default, documents produced on computer ter-
     minals have the date at the bottom of each  page;  documents
     produced  on  the  typesetter don't.  To force the date, say
     ``.DA''.  To force no date, say ``.ND''.  To lie  about  the
     date, say ``.DA July 4, 1776'' which puts the specified date
     at the bottom of each page.  The command

          .ND May 8, 1945

     in ".RP" format places the specified date on the cover sheet
     and nowhere else.  Place this line before the title.

          Registers.  Certain of the registers used by -ms can be
     altered to change default settings.  They should be  changed
     with .nr commands, as with

               .nr PS 9

     to  make  the  default point size 9 point.  If the effect is
     needed immediately, the normal troff command should be  used
     in addition to changing the number register.

     Register    Defines         Takes      Default
                                 effect
      PO     page offset       next page    1''
      LL     line length       next para.   6''
      LT     title length      next para.   6''
      HM     top margin        next page    1''
      FM     bottom margin     next page    1''
      PS     point size        next para.   10 pts
      VS     line spacing      next para.   12 pts
      PI     para. indent      next para.   5 ens
      PD     para. spacing     next para.   0.3 VS
      QI     quote para ind    next para.   5 ens
      FL     footnote length   next FS      *5/6 LL
      FI     footnote indent   next FS      *5/6 LL
      FF     footnote format   next FS      *5/6 LL
      MINGW  min. column wid   next page    2 ens

     You  may also alter the strings LH, CH, and RH which are the
     left, center, and right headings respectively; and similarly
     LF,  CF,  and  RF which are strings in the page footer.  The
     page number on output is taken from register PN,  to  permit









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


     changing its output style.  For more complicated headers and
     footers the macros PT and BT can be redefined, as  explained
     earlier.

          Accents.   To  simplify  typing  certain foreign words,
     strings representing common accent marks are defined.   They
     precede  the  letter over which the mark is to appear.  Here
     are the strings:

                  Input   Output      Input   Output
                  \*'e      e         \*~a      a
                  \*`e      e         \*Ce      e
                  \*:u      u         \*,c      c
                  \*^e      e


          Use.  After your document is prepared and stored  on  a
     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
     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  sepa-
     rate 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
     -----------
     *  If  .2C was used, pipe the nroff output through
     col; make  the  first  line  of  the  input  ``.pi
     /usr/bin/col.''









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


     .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).
     Information 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
          Computing 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 Labo-
          ratories Computing Science Report no. 51.

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



                              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.










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


     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  let-
     ters 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
     A4    CA   DS    EQ    HO   KE    MO    R    RS    TH    XK

                Figure 1:  Order of Commands in Input





















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


                    |
                    +-------+
                    |      ||
                    |
                    |      RP
                    +--------
                   |+------+
                    |      |
                   TL      |
                    |      |
                    |      |
                    |      |
                    |      |
                   ||      |
                    |      |
                   AU      |
                    |      |
                    |      |
                   ||      |
                    |      |
                   AI      |
                    +------+----------+------------+-
                           |          |            |
                          AB          |            |
                           |          |            |
                           |          |            |
                           |          |            |
                           |          |            |
                          AE          |            |
                           -----------+------------+
                                      |            |
                                     ||            |
                                                   |
                                   NH,|SH          |
                                      -------------+-

                                                  PP, LP
                                                   |
                                                   |
                                                   |
                                                   |
                                                   |
                                                  text...
                                                   |
                                                   |
                                                   |














