





     


                   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 phototypesetter
          or on a computer terminal, without changing the  input.

               The macros provide facilities for paragraphs, sec-
          tions  (optionally  with  automatic  numbering),   page
          titles,  footnotes,  equations, tables, two-column for-
          mat, 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, ``Typ-
          ing Documents on UNIX,'' dated November 22, 1974.


          Introduction.   This  memorandum describes a package of com-
     mands to produce papers using the troff and nroff formatting pro-
     grams  on  the UNIX system.  As with other roff-derived programs,
     text is prepared interspersed with formatting commands.  However,
     this package, which itself is written 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 produce  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:












     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 com-
     mand 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 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  document
     signals  the general format of the first page.  In particular, 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 docu-
     ment need be stored, containing all information;  the first  com-
     mand  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 special, 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  head-
     ings/footings  by redefining the strings LH, CH, and RH which are
     the left, center and right portions of the page headings, respec-
     tively;  and the strings LF, CF, and RF, which are the left, cen-
     ter and right portions of the page footer.  For more complex for-
     mats,  the  user  can  redefine  the  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









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


     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 for-
     mat  beginning  at that point.  This feature is not too useful in
     computer terminal output, but is often desirable on the  typeset-
     ter.   The  command ``.1C'' will go back to one-column format and
     also skip to a new page.  The ``.2C'' command is actually a  spe-
     cial 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.  When-
     ever 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 com-
     mands.  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 followed by
     a paragraph beginning with .PP or .LP, indicating the end of  the
     heading.  Headings may contain more than one 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 gener-
     ated.  Larger level numbers indicate deeper sub-sections,  as  in
     this example:









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


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

     [2]  Text for second paragraph, ...

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











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


          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  suit-
          able 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 general
     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  com-
     mand  .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






















     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  para-
     graph indented on both right and left is required.

          A  single  paragraph like this is obtained by preceding
          it with .QP.  More complicated material (several  para-
          graphs) 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 itali-
     cized, it may be just given on the line with the .I command,











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


               .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 placing it on
     the same line as the .B command.

          A  few size changes can be specified similarly with the com-
     mands .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 com-
     mands).

          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  multiple
     words on the typesetter.

          Footnotes.   Material placed between lines with the commands
     .FS (footnote) and .FE (footnote end) will be  collected,  remem-
     bered, 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 register (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 centered (and not
     re-arranged); lines bracketed by .DS L and .DE are left-adjusted,
     not  indented, and not re-arranged.  A plain .DS is equivalent to
     .DS I, which indents and left-adjusts.  Thus,


     -----------
     * Like this.









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


                         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 argu-
     ment 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 termi-
     nal, 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 fol-
     lowed 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 com-
     mands 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.

          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:










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


          .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 terminals
     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 changing  its  output
     style.   For  more  complicated headers and footers the macros PT
     and BT can be redefined, as explained earlier.











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


          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 separate
     tables (see [2]) from text with a little space.  A very long  ta-
     ble  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  introduc-
     tion,  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
     -----------
     *  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


     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  package,  and
     for his assistance in preparing this manual.


                                References


     [1]  B. W. Kernighan and L. L. Cherry, Typesetting Mathematics --
          Users Guide (2nd edition), Bell Laboratories Computing  Sci-
          ence Report no. 17.

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

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

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

     [5]  K. Thompson and D. M.  Ritchie,  UNIX  Programmer's  Manual,
          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.
     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









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


          The  following  register  names  are used by -ms internally.
     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
     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...
                                                     |
                                                     |
                                                     |














