Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff M. E. Lesk Bell Laboratories Murray Hill, New Jersey 07974 _A_B_S_T_R_A_C_T 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 a 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. The commands described here are also avail- able in packages that produce output formatted appropriately for several journals, including _S_o_f_t_w_a_r_e _P_r_a_c_t_i_c_e _a_n_d _E_x_p_e_r_i_e_n_c_e, _J_o_u_r_n_a_l _o_f _t_h_e _A_C_M, and _S_I_A_M _J_o_u_r_n_a_l _o_n _C_o_m_p_u_t_i_n_g. March, 1982 Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff M. E. Lesk Bell Laboratories Murray Hill, New Jersey 07974 _I_n_t_r_o_d_u_c_t_i_o_n. This memorandum describes a package of commands to produce papers using the _t_r_o_f_f and _n_r_o_f_f format- ting programs on the UNIX system. As with other _r_o_f_f- derived programs, text is prepared interspersed with format- ting commands. However, this package, which itself is writ- ten in _t_r_o_f_f commands, provides higher-level commands than those provided with the basic _t_r_o_f_f program. The commands available in this package are listed in Appendix A. _T_e_x_t. 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.'' _B_e_g_i_n_n_i_n_g. For a document with a paper-type cover sheet, the input should start as follows: [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 - 2 - paragraph. _W_a_r_n_i_n_g: 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. _C_o_v_e_r _S_h_e_e_t_s _a_n_d _F_i_r_s_t _P_a_g_e_s. 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 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. _P_a_g_e _h_e_a_d_i_n_g_s. 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 _n_r_o_f_f, 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 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. _M_u_l_t_i-_c_o_l_u_m_n _f_o_r_m_a_t_s. 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 use- ful 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. 7777777777777 The ``.2C'' command is actu- ally 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. - 3 - Whenever the number of columns is changed (except going from full width to some larger number of columns) a new page is started. _H_e_a_d_i_n_g_s. 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. _C_a_r_e _a_n_d _F_e_e_d_i_n_g _o_f _D_e_p_a_r_t_m_e_n_t _H_e_a_d_s Alternatively, .SH Care and Feeding of Directors will print the heading with no number added: _C_a_r_e _a_n_d _F_e_e_d_i_n_g _o_f _D_i_r_e_c_- _t_o_r_s 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 con- tain 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 777777777777777777777777777777777777777777777777777777 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. _E_r_i_e-_L_a_c_k_a_w_a_n_n_a _2._1. _M_o_r_r_i_s _a_n_d _E_s_s_e_x _D_i_v_i_- _s_i_o_n _2._1._1. _G_l_a_d_s_t_o_n_e _B_r_a_n_c_h _2._1._2. _M_o_n_t_c_l_a_i_r _B_r_a_n_c_h _2._2. _B_o_o_n_t_o_n _L_i_n_e An explicit ``.NH 0'' will reset the numbering of level 1 to one, as here: .NH 0 Penn Central _1. _P_e_n_n _C_e_n_t_r_a_l _I_n_d_e_n_t_e_d _p_a_r_a_g_r_a_p_h_s. (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 - 4 - [1] Text for first para- graph, typed normally for as long as you would like on as many lines as needed. [2] Text for second para- graph, ... A series of indented para- graphs may be followed by an ordinary paragraph beginning with .PP or .LP, depending on whether you wish indent- ing 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 posi- tions) 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, 777777777777777777777777777777777777777777777777777777 .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 para- graphs. second: And so forth. It is also possible to pro- duce 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 bal- ance .RS and .RE commands. The .RS command should be thought of as ``move right'' and the .RE command as ``move left''. As an exam- ple .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 - 5 - 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 compli- cated material (several para- graphs) should be bracketed with .QS and .QE. _E_m_p_h_a_s_i_s. To get italics (on the typesetter) or underlining (on the termi- nal) say .I as much text as you want can be typed here .R as was done for _t_h_e_s_e _t_h_r_e_e _w_o_r_d_s. 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 command, .I word and in this case no .R is needed to restore the previ- ous font. _B_o_l_d_f_a_c_e can be produced by 777777777777777777777777777777777777777777777777777777 .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 sin- gle word can be placed in boldface by placing it on the same line as the .B com- mand. 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 can- celed two .SM commands). If actual _u_n_d_e_r_l_i_n_i_n_g 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. _F_o_o_t_n_o_t_e_s. Material placed between lines with the commands .FS (footnote) and .FE (footnote end) will be collected, 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). _D_i_s_p_l_a_y_s _a_n_d _T_a_b_l_e_s. __________________________ * Like this. - 6 - 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 brack- eted by .DS C and .DE com- mands are centered (and not re-arranged); lines brack- eted 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, 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 777777777777777777777777777777777777777777777777777777 is tempting to assume that .DS R will right adjust lines, but it doesn't work. _B_o_x_i_n_g _w_o_r_d_s _o_r _l_i_n_e_s. To draw rectangular boxes around words the command .BX word will print |word|7____99____ as shown. The boxes will not be neat on a terminal, and this should not be used as a sub- stitute for italics. Longer pieces of text may be boxed by enclosing them with __________________________ * If .2C was used, pipe the _n_r_o_f_f output through _c_o_l; make the first line of the input ``.pi /usr/bin/col.'' 99