NROFF/TROFF User's Manual _J_o_s_e_p_h _F. _O_s_s_a_n_n_a Bell Laboratories Murray Hill, New Jersey 07974 Introduction 9NROFF and TROFF are text processors under the PDP-11 UNIX Time- Sharing System1 that format text for typewriter-like terminals and for a Graphic Systems phototypesetter, respectively. They accept lines of text interspersed with lines of format control information and format the text into a printable, paginated docu- ment having a user-designed style. NROFF and TROFF offer unusual freedom in document styling, including: arbitrary style headers and footers; arbitrary style footnotes; multiple automatic sequence numbering for paragraphs, sections, etc; multiple column output; dynamic font and point-size control; arbitrary horizontal and vertical local motions at any point; and a family of automatic overstriking, bracket construction, and line drawing functions. 9NROFF and TROFF are highly compatible with each other and it is almost always possible to prepare input acceptable to both. Con- ditional input is provided that enables the user to embed input expressly destined for either program. NROFF can prepare output directly for a variety of terminal types and is capable of util- izing the full resolution of each terminal. 9Usage 9The general form of invoking NROFF (or TROFF) at UNIX command level is 9 nroff _o_p_t_i_o_n_s _f_i_l_e_s(or troff _o_p_t_i_o_n_s _f_i_l_e_s) 9where _o_p_t_i_o_n_s represents any of a number of option arguments and _f_i_l_e_s represents the list of files containing the document to be formatted. An argument 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: _O_p_t_i_o_n _E_f_f_e_c_t 9 -o_l_i_s_t Print only pages whose page numbers appear in _l_i_s_t, which consists 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. 9 9 - 1 - 9 NROFF/TROFF User's Manual October 11, 1976 -n_N Number first generated page _N. 9 -s_N Stop every _N pages. NROFF will halt prior to every _N pages (default _N=1) to allow paper loading or changing, and will resume upon receipt of a newline. 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. 9 -m_n_a_m_e Prepends the macro file /usr/lib/tmac._n_a_m_e to the input _f_i_l_e_s. 9 -r_a_N Register _a (one-character) is set to _N. 9 -i Read standard input after the input files are exhausted. 9 -q Invoke the simultaneous input-output mode of the rd request. _N_R_O_F_F _O_n_l_y 9 -T_n_a_m_e Specifies the name of the output terminal type. Currently defined names are 37 for the (default) Model 37 Teletype8r9, tn300 for the GE TermiNet 300 (or any terminal without half-line capabilities), 300S for the DASI-300S, 300 for the DASI-300, and 450 for the DASI-450 (Diablo Hyterm). 9 -e Produce equally-spaced words in adjusted lines, using full terminal resolution. _T_R_O_F_F _O_n_l_y 9 -t Direct output to the standard output instead of the phototypesetter. 9 -f Refrain from feeding out paper and stopping photo- typesetter at the end of the run. 9 -w Wait until phototypesetter is available, if currently busy. 9 -b TROFF will report whether the phototypesetter is busy or available. No text processing is done. 9 -a Send a printable (ASCII) approximation of the results to the standard output. 9 -p_N Print all characters in point size _N while retaining all prescribed spacings and motions, to reduce pho- totypesetter elasped time. 9 -g Prepare output for the Murray Hill Computation Center phototypesetter and direct it to the standard output. 99 Each option is invoked as a separate argument; for example, 9 nroff -o_4,_8-_1_0 -T_3_0_0_S -m_a_b_c _f_i_l_e_1 _f_i_l_e_2 9 9 - 2 - 9 NROFF/TROFF User's Manual October 11, 1976 requests formatting of pages 4, 8, 9, and 10 of a document con- tained in the files named _f_i_l_e_1 and _f_i_l_e_2, specifies the output terminal as a DASI-300S, and invokes the macro package _a_b_c. 9 Various pre- and post-processors are available for use with NROFF and TROFF. These include the equation preprocessors NEQN and EQN2 (for NROFF and TROFF respectively), and the table- construction preprocessor TBL3. A reverse-line postprocessor COL4 is available for multiple-column NROFF output on terminals without reverse-line ability; COL expects the Model 37 Teletype escape sequences that NROFF produces by default. TK4 is a 37 Teletype simulator postprocessor for printing NROFF output on a Tektronix 4014. TCAT4 is phototypesetter-simulator postprocessor for TROFF that produces an approximation of phototypesetter out- put on a Tektronix 4014. For example, in 9 tbl _f_i_l_e_s | eqn | troff -t _o_p_t_i_o_n_s | tcat 9 the first | indicates the piping of TBL's output to EQN's input; the second the piping of EQN's output to TROFF's input; and the third indicates the piping of TROFF's output to TCAT. GCAT4 can be used to send TROFF (-g) output to the Murray Hill Computation Center. 9 The remainder of this manual consists of: a Summary and Index; a Reference Manual keyed to the index; and a set of Tutorial Exam- ples. Another tutorial is [5]. 9 Joseph F. Ossanna 99 References 9 [1]K. Thompson, D. M. Ritchie, _U_N_I_X _P_r_o_g_r_a_m_m_e_r'_s _M_a_n_u_a_l, Sixth Edition (May 1975). 9 [2]B. W. Kernighan, L. L. Cherry, _T_y_p_e_s_e_t_t_i_n_g _M_a_t_h_e_m_a_t_i_c_s - _U_s_e_r'_s _G_u_i_d_e (_S_e_c_o_n_d _E_d_i_t_i_o_n), Bell Laboratories internal memorandum. 9 [3]M. E. Lesk, _T_b_l - _A _P_r_o_g_r_a_m _t_o _F_o_r_m_a_t _T_a_b_l_e_s, Bell Labora- tories internal memorandum. 9 [4]Internal on-line documentation, on UNIX. 9 [5]B. W. Kernighan, _A _T_R_O_F_F _T_u_t_o_r_i_a_l, Bell Laboratories internal memorandum. 9 - 3 - 9 NROFF/TROFF User's Manual October 11, 1976 9 - 4 - 9 NROFF/TROFF User's Manual October 11, 1976 SUMMARY AND INDEX 99_R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e* _A_r_g_u_m_e_n_t _N_o_t_e_s#_E_x_p_l_a_n_a_t_i_o_n 91. General Explanation 92. Font and Character Size Control 9.ps+__N 10point previous E Point size; also \s+__N.|- .ss _N 12/36em ignored E Space-character size set to _N/36em.|- .cs_F_N_M off - P Constant character space (width) mode (font _F).|- .bd _F _N off - P Embolden font _F by _N-1 units.|- .bd S _F _N off - P Embolden Special Font when current font is _F.|- .ft _F Roman previous E Change to font _F = _x, _x_x, or 1-4. Also \f_x,\f(_x_x,\f_N. .fp _N _F R,I,B,S ignored - Font named _F mounted on physical position 1<__N<_4. 93. Page Control 9.pl+__N 11in 11in v Page length. .bp +__N _N=1 - B|=,v Eject current page; next page number _N. .pn +__N _N=1 ignored - Next page number _N. .po +__N 0; 26/27in previousvPage offset. .ne _N - _N=1_V D,v Need _N vertical space (_V = vertical spacing). .mk _R none internal D Mark current vertical place in register _R. .rt +__N none internal D,vReturn (_u_p_w_a_r_d _o_n_l_y) to marked vertical place. 94. Text Filling, Adjusting, and Centering 9.br - - B Break. .fi fill - B,E Fill output lines. .nf fill - B,E No filling or adjusting of output lines. .ad _c adj,both adjust EAdjust output lines with mode _c. .na adjust - E No output line adjusting. .ce _N off _N=1 B,E Center following _N input text lines. 95. Vertical Spacing 9.vs _N 1/6in;12pts previousE,pVertical base line spacing (_V). .ls _N _N=1 previous E Output _N-1 _Vs after each text out- put line. .sp _N - _N=1_V B,v Space vertical distance _N _i_n _e_i_t_h_e_r __________ 9*Values separated by ";" are for NROFF and TROFF respectively. #Notes are explained at the end of this Summary and Index |-No effect in NROFF. |=The use of " ' " as control character (instead of ".") suppresses the break function. 9 - 3 - 9 NROFF/TROFF User's Manual October 11, 1976 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n _d_i_r_e_c_t_i_o_n. .sv _N - _N=1_V v Save vertical distance _N. .os - - - Output saved vertical distance. .ns space - D Turn no-space mode on. .rs - - D Restore spacing; turn no-space mode off. 9 6. Line Length and Indenting 9 .ll +__N 6.5in previous E,mLine length. .in +__N _N=0 previous B,E,mIndent. .ti +__N - ignored B,E,m Temporary indent. 9 7. Macros, Strings, Diversion, and Position Traps 9 .de _x_x _y_y - ._y_y=.. -Define or redefine macro _x_x; end at call of _y_y. .am _x_x _y_y - ._y_y=.. -Append to a macro. .ds _x_x _s_t_r_i_n_g - ignored-Define a string _x_x containing _s_t_r_i_n_g. .as _x_x _s_t_r_i_n_g - ignored-Append _s_t_r_i_n_g to string _x_x. .rm _x_x - ignored - Remove request, macro, or string. .rn _x_x _y_y - ignored-Rename request, macro, or string _x_x to _y_y. .di _x_x - end D Divert output to macro _x_x. .da _x_x - end D Divert and append to _x_x. .wh _N _x_x - - v Set location trap; negative is w.r.t. page bottom. .ch _x_x _N - - v Change trap location. .dt _N _x_x - off D,vSet a diversion trap. .it _N _x_x - off E Set an input-line count trap. .em _x_x none none - End macro is _x_x. 9 8. Number Registers 9 .nr _R +__N _M - u Define and set number register _R; auto-increment by _M. .af _R _c arabic - - Assign format to register _R (_c=1, i, I, a, A). .rr _R - - - Remove register _R. 9 9. Tabs, Leaders, and Fields 9 .ta _N_t ... 0.8; 0.5in noneE,mTab settings; _l_e_f_t type, unless _t=R(right), C(centered). .tc _c none none E Tab repetition character. .lc _c . none E Leader repetition character. .fc _a _b off off - Set field delimiter _a and pad char- acter _b. 9 10. Input and Output Conventions and Character Translations 9 .ec _c \ \ - Set escape character. .eo on - - Turn off escape character mechanism. .lg _N -;on on - Ligature mode on if _N>0. .ul _N off _N=1 E Underline (italicize in TROFF) _N 9 - 4 - 9 NROFF/TROFF User's Manual October 11, 1976 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n input lines. .cu _N off _N=1 E Continuous underline in NROFF; like ul in TROFF. .uf _F Italic Italic - Underline font set to _F (to be switched to by ul). .cc _c . . E Set control character to _c. .c2 _c ' ' E Set nobreak control character to _c. .tr _a_b_c_d.... none - O Translate _a to _b, etc. on output. 9 11. Local Horizontal and Vertical Motions, and the Width Func- tion 9 12. Overstrike, Bracket, Line-drawing, and Zero-width Functions 9 13. Hyphenation. 9 .nh hyphenate - E No hyphenation. .hy _N hyphenate hyphenateEHyphenate; _N = mode. .hc _c \% \% E Hyphenation indicator character _c. .hw _w_o_r_d_1 ... ignored - Exception words. 9 14. Three Part Titles. 9 .tl '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t' - - Three part title. .pc _c % off - Page number character. .lt +__N 6.5in previous E,mLength of title. 9 15. Output Line Numbering. 9 .nm +__N _M _S _I off E Number mode on or off, set parame- ters. .nn _N - _N=1 E Do not number next _N lines. 9 16. Conditional Acceptance of Input 9 .if _c _a_n_y_t_h_i_n_g - - If condition _c true, accept _a_n_y_- _t_h_i_n_g as input, for multi-line use _\{_a_n_y_t_h_i_n_g_\}. .if !_c _a_n_y_t_h_i_n_g - - If condition _c false, accept _a_n_y_- _t_h_i_n_g. .if _N _a_n_y_t_h_i_n_g - u If expression _N > 0, accept _a_n_y_- _t_h_i_n_g. .if !_N _a_n_y_t_h_i_n_g - u If expression _N <_ 0, accept _a_n_y_- _t_h_i_n_g. .if '_s_t_r_i_n_g_1'_s_t_r_i_n_g_2' _a_n_y_t_h_i_n_g -If _s_t_r_i_n_g_1 identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. .if !'_s_t_r_i_n_g_1'_s_t_r_i_n_g_2' _a_n_y_t_h_i_n_g-If _s_t_r_i_n_g_1 not identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. .ie _c _a_n_y_t_h_i_n_g - u If portion of if-else; all above forms (like if). .el _a_n_y_t_h_i_n_g - - Else portion of if-else. 9 17. Environment Switching. 9 .ev _N _N=0 previous - Environment switched (_p_u_s_h _d_o_w_n). 9 9 9 - 5 - 9 NROFF/TROFF User's Manual October 11, 1976 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 18. Insertions from the Standard Input 9 .rd _p_r_o_m_p_t - _p_r_o_m_p_t=BEL-Read insertion. .ex - - - Exit from NROFF/TROFF. 9 19. Input/Output File Switching 9 .so _f_i_l_e_n_a_m_e - - Switch source file (_p_u_s_h _d_o_w_n). .nx _f_i_l_e_n_a_m_e end-of-file-Next file. .pi _p_r_o_g_r_a_m - - Pipe output to _p_r_o_g_r_a_m (NROFF only). 9 20. Miscellaneous 9 .mc _c _N - off E,m Set margin character _c and separa- tion _N. .tm _s_t_r_i_n_g - newline-Print _s_t_r_i_n_g on terminal (UNIX standard message output). .ig _y_y - ._y_y=.. - Ignore till call of _y_y. .pm _t - all - Print macro names and sizes; if _t present, print only total of sizes. .fl - - B Flush output buffer. 9 21. Output and Error Messages 9 _________________________________________________________________ 9 Notes- 9 B Request normally causes a break. D Mode or relevant parameters associated with current diversion level. E Relevant parameters are a part of the current environment. O Must stay in effect until logical output. P Mode must be still or again in effect at the time of physical output. v,p,m,uDefault scale indicator; if not specified, scale indicators are _i_g_n_o_r_e_d. Alphabetical Request and Section Number Cross Reference 9 ad4 af8 am7 as7 bd2 bp3 br4 c210 77777777 cc10 ce4 ch7 cs2 cu10 da7 de7 di7 77777777 ds7 dt7 ec10 el16 em7 eo10 ev17 ex18 77777777 fc9 fi4 fl20 fp2 ft2 hc13 hw13 hy13 77777777 ie16 if16 ig20 in6 it7 lc9 lg10 li10 77777777 ll6 ls5 lt14 mc20 mk3 na4 ne3 nf4 77777777 nh13 nm15 nn15 nr8 ns5 nx19 os5 pc14 77777777 pi19 pl3 pm20 pn3 po3 ps2 rd18 rm7 77777777 rn7 rr8 rs5 rt3 so19 sp5 ss2 sv5 77777777 ta9 tc9 ti6 tl14 tm20 tr10 uf10 ul10 77777777 vs5 wh7 77 9 9 9 - 6 - 9 NROFF/TROFF User's Manual October 11, 1976 Escape Sequences for Characters, Indicators, and Functions 9 _S_e_c_t_i_o_n _E_s_c_a_p_e _R_e_f_e_r_e_n_c_e _S_e_q_u_e_n_c_e _M_e_a_n_i_n_g 9 10.1 \\ \ (to prevent or delay the interpretation of \) 10.1 \e Printable version of the _c_u_r_r_e_n_t escape character. 2.1 \' ' (acute accent); equivalent to \(aa 2.1 \` ` (grave accent); equivalent to \(ga 2.1 \- - Minus sign in the _c_u_r_r_e_n_t font 7 \. Period (dot) (see de) 11.1 \(space) Unpaddable space-size space character 11.1 \0 Digit width space 11.1 \| 1/6em narrow space character (zero width in NROFF) 11.1 \^ 1/12em half-narrow space character (zero width in NROFF) 4.1 \& Non-printing, 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 \(_x_x Character named _x_x 7.1 \*_x, \*(_x_x Interpolate string _x or _x_x 9.1 \a Non-interpreted leader character 12.3 \b'_a_b_c...' Bracket building function 4.2 \c Interrupt text processing 11.1 \d Forward (down) 1/2em vertical motion (1/2 line in NROFF) 2.2 \f_x,\f(_x_x,\f_N Change to font named _x or _x_x, or position _N 11.1 \h'_N ' Local horizontal motion; move right _N (_n_e_g_a_t_i_v_e _l_e_f_t) 11.3 \k_x Mark horizontal _i_n_p_u_t place in register _x 12.4 \l'_N_c' Horizontal line drawing function (optionally with _c) 12.4 \L'_N_c' Vertical line drawing function (optionally with _c) 8 \n_x,\n(_x_x Interpolate number register _x or _x_x 12.1 \o'_a_b_c...' Overstrike characters _a, _b, _c, ... 4.1 \p Break and spread output line 11.1 \r Reverse 1em vertical motion (reverse line in NROFF) 2.3 \s_N,\s+__N Point-size change function 9.1 \t Non-interpreted horizontal tab 11.1 \u Reverse (up) 1/2em vertical motion (1/2 line in NROFF) 11.1 \v'_N' Local vertical motion; move down _N (_n_e_g_a_t_i_v_e _u_p) 11.2 \w'_s_t_r_i_n_g' Interpolate width of _s_t_r_i_n_g 5.2 \x'_N' Extra line-space function (_n_e_g_a_t_i_v_e _b_e_f_o_r_e, _p_o_s_i_t_i_v_e _a_f_t_e_r) 12.2 \z_c Print _c with zero width (without spacing) 16 \{ Begin conditional input 16 \} End conditional input 10.7 \(newline) Concealed (ignored) newline - \_X _X, any character _n_o_t listed above The escape sequences \\, \., \", \$, \*, \a, \n, \t, and \(new- line) are interpreted in _c_o_p_y _m_o_d_e (7.2). 9 - 7 - 9 NROFF/TROFF User's Manual October 11, 1976 Predefined General Number Registers _S_e_c_t_i_o_n _R_e_g_i_s_t_e_r _R_e_f_e_r_e_n_c_e _N_a_m_e _D_e_s_c_r_i_p_t_i_o_n 9 3 % Current page number. 11.2 ct Character type (set by _w_i_d_t_h 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 _i_n_p_u_t line. 15 ln Output line number. - mo Current month (1-12). 4.1 nl Vertical position of last printed text base-line. 11.2 sb Depth of string below base line (generated by _w_i_d_t_h function). 11.2 st Height of string above base line (generated by _w_i_d_t_h function). - yr Last two digits of current year. Predefined Read-Only Number Registers _S_e_c_t_i_o_n _R_e_g_i_s_t_e_r _R_e_f_e_r_e_n_c_e _N_a_m_e _D_e_s_c_r_i_p_t_i_o_n 9 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. - .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 Post-line extra line-space most recently utilized using \x'_N'. - .c Number of _l_i_n_e_s 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 Text base-line high-water mark on current page or diversion. 6 .i Current indent. 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. - .x Reserved version-dependent register. - .y Reserved version-dependent register. 7.4 .z Name of current diversion. 9 - 8 - 9 NROFF/TROFF User's Manual October 11, 1976 9 - 9 - 9 NROFF/TROFF User's Manual October 11, 1976 REFERENCE MANUAL 91. General Explanation 9_1._1._F_o_r_m _o_f _i_n_p_u_t. Input consists of _t_e_x_t _l_i_n_e_s, which are des- tined to be printed, interspersed with _c_o_n_t_r_o_l _l_i_n_e_s, which set parameters or otherwise control subsequent processing. Control lines begin with a _c_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r-normally . (period) or ' (acute accent)-followed by a one or two character name that specifies a basic _r_e_q_u_e_s_t or the substitution of a user-defined _m_a_c_r_o in place of the control line. The control character ' suppresses the _b_r_e_a_k 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/or tabs) for esthetic reasons. Names must be fol- lowed by either space or newline. Control lines with unrecog- nized names are ignored. 9Various special functions may be introduced anywhere in the input by means of an _e_s_c_a_p_e character, normally \. For example, the function \n_R causes the interpolation of the contents of the _n_u_m_b_e_r _r_e_g_i_s_t_e_r _R in place of the function; here _R is either a single character name as in \n_x, or left-parenthesis-introduced, two-character name as in \n(_x_x. 9_1._2._F_o_r_m_a_t_t_e_r _a_n_d _d_e_v_i_c_e _r_e_s_o_l_u_t_i_o_n. TROFF internally uses 432 units/inch, corresponding to the Graphic Systems phototypesetter which has a horizontal resolution of 1/432 inch and a vertical resolution of 1/144 inch. NROFF internally uses 240 units/inch, 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 actual horizontal/vertical resolution of the Graphic Systems typesetter. NROFF similarly rounds numerical input to the actual resolution of the output device indicated by the -T option (default Model 37 Teletype). 9_1._3._N_u_m_e_r_i_c_a_l _p_a_r_a_m_e_t_e_r _i_n_p_u_t. Both NROFF and TROFF accept numerical input with the appended scale indicators 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 _n_o_m_- _i_n_a_l _c_h_a_r_a_c_t_e_r _w_i_d_t_h in basic units. 9 9 - 8 - 9 NROFF/TROFF User's Manual October 11, 1976 8 ______________________________________________________________ Scale Number of basic units Indicator Meaning TROFF NROFF 8 ______________________________________________________________ i Inch 432 240 c Centimeter 432x50/127 240x50/127 P Pica = 1/6 inch 72 240/6 m Em = _S points 6x_S _C n En = Em/2 3x_S _C, _s_a_m_e _a_s _E_m p Point = 1/72 inch 6 240/72 u Basic unit 1 1 v Vertical line space _V _V none Default, see below 8 ______________________________________________________________ 7 |7|7|7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7|7|7| |8|7|7|7|7|7|7|7|7| 9 |7|7|7|7|7|7|7|7|7|7|7| In NROFF, _b_o_t_h the em and the en are taken to be equal to the _C, which is output-device dependent; common values are 1/10 and 1/12 inch. Actual character widths in NROFF need not be all the same and constructed characters such as -> (->) 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; _Vs 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. _A_l_l other requests ignore any scale indicators. When a number register containing an already appropriately scaled number is interpolated to provide numerical 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. 9 The _a_b_s_o_l_u_t_e _p_o_s_i_t_i_o_n indicator | may be prepended to a number _N to generate 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 _d_i_v_e_r_s_i_o_n (7.4) to the the vertical place _N. For _a_l_l other requests and functions, |_N becomes the distance from the current horizontal place on the _i_n_p_u_t line to the horizontal place _N. For example, 9 .sp |3.2c 9 will space _i_n _t_h_e _r_e_q_u_i_r_e_d _d_i_r_e_c_t_i_o_n to 3.2centimeters from the top of the page. 9 _1._4._N_u_m_e_r_i_c_a_l _e_x_p_r_e_s_s_i_o_n_s. 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 controlled by parentheses, evaluation of expressions is left-to-right; there is no operator precedence. In the case of certain requests, an ini- tial + or - is stripped and interpreted as an increment or decre- ment indicator respectively. In the presence of default scaling, the desired scale indicator must be attached to _e_v_e_r_y number in an expression for which the desired and default scaling differ. For example, if the number register x contains 2 and the current point size is 10, then 9 9 - 9 - 9 NROFF/TROFF User's Manual October 11, 1976 .ll (4.25i+\nxP+3)/2u 9 will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 points. 9 _1._5._N_o_t_a_t_i_o_n. Numerical parameters are indicated 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 _n_o_t an increment indicator, but merely the sign of _N. Gen- erally, unreasonable numerical input is either ignored or trun- cated to a reasonable 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 _p_r_e_v_i_o_u_s parameter value in the _a_b_s_e_n_c_e of an argu- ment. 9 Single character arguments are indicated by single lower case letters and one/two character arguments are indicated by a pair of lower case letters. Character string arguments are indicated by multi-character mnemonics. 9 2. Font and Character Size Control 9 _2._1._C_h_a_r_a_c_t_e_r _s_e_t. The TROFF character set consists of the Graphics Systems Commercial II character set plus a Special Mathematical Font character set-each having 102 characters. These character sets are shown in the attached Table I. All ASCII characters are included, with some on the Special Font. With three exceptions, the ASCII characters are input as them- selves, and non-ASCII characters are input in the form \(_x_x where _x_x is a two-character name given in the attached Table II. The three ASCII exceptions are mapped as follows: 8 ____________________________________________________ ASCII Input Printed by TROFF Character Name Character Name 8 ____________________________________________________ ' acute accent ' close quote ` grave accent ` open quote - minus - hyphen 8 ____________________________________________________ 7 |7|7|7|7|7| |7|7|7|7|7| |7|7|7|7|7| The characters ', `, and - may be input by \', \`, and \- respec- tively 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. 9 NROFF understands the entire TROFF character set, but can in gen- eral print only ASCII characters, additional characters as may be available on the output device, such characters as may be able to be constructed by overstriking 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. 9 _2._2._F_o_n_t_s. The default mounted fonts are Times Roman (R), Times Italic (I), Times Bold (B), and the Special Mathematical Font (S) 9 - 10 - 9 NROFF/TROFF User's Manual October 11, 1976 on physical typesetter positions 1, 2, 3, and 4 respectively. These fonts are used in this document. The _c_u_r_r_e_n_t font, ini- tially Roman, may be changed (among the mounted fonts) by use of the ft request, or by imbedding at any desired point either \f_x, \f(_x_x, or \f_N where _x and _x_x are the name of a mounted font and _N is a numerical font position. It is _n_o_t necessary to change to the Special font; characters on that font are automatically han- dled. A request for a named but not-mounted font is _i_g_n_o_r_e_d. 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 subsequent discussion of font-related requests, _F represents either a one/two-character font name or the numerical font position, 1-4. The current font is available (as numerical position) in the read-only number register .f. 9 NROFF understands font control and normally underlines Italic characters (see 10.5). 9 _2._3._C_h_a_r_a_c_t_e_r _s_i_z_e. 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 is used to change or restore the point size. Alternatively the point size may be changed between any two characters by imbedding a \s_N 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 _p_r_e_v_i_o_u_s 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 register. NROFF ignores type size control. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s*_E_x_p_l_a_n_a_t_i_o_n 9 .ps +__N 10point previous E Point size set to +__N. Alterna- tively imbed \s_N or \s+__N. Any posi- tive 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. 9 .ss _N 12/36em ignored E Space-character size is set to _N/36ems. This size is the minimum word spacing in adjusted text. Ignored in NROFF. 9 .cs_F_N_M off - P Constant character space (width) mode is set on for font _F (if mounted); the width of every charac- ter 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 __________ 9 *Notes are explained at the end of the Summary and Index above. - 11 - 9 NROFF/TROFF User's Manual October 11, 1976 affected characters are centered in this space, including those with an actual width larger than this space. Special 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. 9 .bd _F _N off - P 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 in the vicinity of 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 physically printed. Ignored in NROFF. 9 .bd S _F _N off - P The characters in the Special Font will be emboldened whenever the current font is _F. This manual was printed with .bdSB3. The mode must be still or again in effect when the characters are physically printed. 9 .ft _F Roman previous E Font changed to _F. Alternatively, imbed \f_F. The font name P is reserved to mean the previous font. 9 .fp _N _F R,I,B,S ignored - 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 which 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. 9 3. Page control 9 Top and bottom margins are _n_o_t automatically provided; it is con- ventional to define two _m_a_c_r_o_s and to set _t_r_a_p_s for them at vert- ical positions 0 (top) and -_N (_N from the bottom). See 7 and Tutorial Examples T2. A pseudo-page transition onto the _f_i_r_s_t page occurs either when the first _b_r_e_a_k occurs or when the first _n_o_n-_d_i_v_e_r_t_e_d 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 _c_u_r_r_e_n_t 9 - 12 - 9 NROFF/TROFF User's Manual October 11, 1976 _d_i_v_e_r_s_i_o_n (7.4) mean that the mechanism being described works during both ordinary and diverted output (the former considered as the top diversion level). 9 The useable 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 limita- tions on NROFF output are output-device dependent. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .pl +__N 11in 11in v Page length set to +__N. The internal limitation is about 75 inches in TROFF and about 136 inches in NROFF. The current page length is available in the .p register. 9 .bp +__N _N=1 - B*,v Begin page. The current page is ejected and a new page is begun. If +__N is given, the new page number will be +__N. Also see request ns. 9 .pn +__N _N=1 ignored - Page number. The next page (when it occurs) will have the page number +__N. A pn must occur before the ini- tial pseudo-page transition to effect the page number of the first page. The current page number is in the % register. 9 .po +__N 0; 26/27in|- previousvPage offset. The current _l_e_f_t _m_a_r_g_i_n is set to +__N. The TROFF ini- tial value provides about 1 inch of paper margin including the physical typesetter margin of 1/27 inch. In TROFF the maximum (line- length)+(page-offset) is about 7.54 inches. See 6. The current page offset is available in the .o regis- ter. 9 .ne _N - _N=1_V D,v Need _N vertical space. If the dis- tance, _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 bot- tom 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 _d_i_v_e_r_s_i_o_n __________ 9 *The use of " ' " as control character (instead of ".") suppresses the break function. 9 |-Values separated by ";" are for NROFF and TROFF respectively. - 13 - 9 NROFF/TROFF User's Manual October 11, 1976 _t_r_a_p, if any, or is very large. 9 .mk _R none internal D Mark the _c_u_r_r_e_n_t vertical place in an internal register (both associ- ated with the current diversion level), or in register _R, if given. See rt request. 9 .rt +__N none internal D,vReturn _u_p_w_a_r_d _o_n_l_y to a marked vertical place in the current diver- sion. If +__N (w.r.t. current place) is given, the place is +__N from the top of the page or diversion or, if _N is absent, to a place marked by a previous mk. Note that the sp request (5.3) may be used in all cases instead of rt by spacing to the absolute place stored in a explicit register; e. g. using the sequence .mk _R ... .sp |\n_Ru. 9 4. Text Filling, Adjusting, and Centering 9 _4._1._F_i_l_l_i_n_g _a_n_d _a_d_j_u_s_t_i_n_g. 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 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 out the line to the current _l_i_n_e _l_e_n_g_t_h minus any current _i_n_d_e_n_t. A _w_o_r_d is any string of characters delimited by the _s_p_a_c_e character 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 _u_n_p_a_d_d_a_b_l_e _s_p_a_c_e 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-size spaces; how- ever, 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 _t_e_x_t _l_e_n_g_t_h on the last line output is available in the .n register, and text base- line position on the page for this line is in the nl register. The text base-line high-water mark (lowest place) on the current page is in the .h register. 9 An input text line ending with ., ?, or ! is taken to be the end of a _s_e_n_t_e_n_c_e, and an additional space character is automatically provided during filling. Multiple inter-word space characters found in the input are retained, except for trailing spaces; ini- tial spaces also cause a _b_r_e_a_k. 9 When filling is in effect, a \p may be imbedded or attached to a word to cause a _b_r_e_a_k at the _e_n_d of the word and have the result- ing output line _s_p_r_e_a_d _o_u_t to fill the current line length. 9 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 - 14 - 9 NROFF/TROFF User's Manual October 11, 1976 the non-printing, zero-width filler character \&. Still another way is to specify output translation of some convenient character into the control character using tr (10.5). 9 _4._2._I_n_t_e_r_r_u_p_t_e_d _t_e_x_t. The copying of a input line in _n_o_f_i_l_l (non-fill) mode can be _i_n_t_e_r_r_u_p_t_e_d by terminating the partial line with a \c. The _n_e_x_t encountered input text line will be considered to be a continuation of the same line of input text. Similarly, a word within _f_i_l_l_e_d text may be interrupted by ter- minating 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. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .br - - B 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. 9 .fi fill on - B,E Fill subsequent output lines. The register .u is 1 in fill mode and 0 in nofill mode. 9 .nf fill on - B,E Nofill. Subsequent output lines are _n_e_i_t_h_e_r filled _n_o_r adjusted. Input text lines are copied directly to output lines _w_i_t_h_o_u_t _r_e_g_a_r_d for the current line length. 9 .ad _c adj,both adjust ELine adjustment is begun. If fill mode is not on, adjustment will be deferred until fill mode is back on. If the type indicator _c is present, the adjustment type is changed as shown in the following table. 8 ______________________________________ Indicator Adjust Type 8 ______________________________________ l adjust left margin only r adjust right margin only c center b or n adjust both margins absent unchanged 8 ______________________________________ 7 |7|7|7|7|7|7| |7|7|7|7|7|7| |7|7|7|7|7|7| 9 .na adjust - E Noadjust. Adjustment is turned off; the right margin will be ragged. The adjustment type for ad is not changed. Output line filling still occurs if fill mode is on. 9 - 15 - 9 NROFF/TROFF User's Manual October 11, 1976 .ce _N off _N=1 B,E Center the next _N input text lines within the current (line-length minus indent). If _N=0, any residual count is cleared. A break occurs after each of the _N input lines. If the input line is too long, it will be left adjusted. 9 5. Vertical Spacing 9 _5._1._B_a_s_e-_l_i_n_e _s_p_a_c_i_n_g. The vertical spacing (_V) between the base-lines of successive output lines can be set using the vs request with a resolution of 1/144inch=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 (as in this docu- ment). The current _V is available in the .v register. Multiple-_V line separation (e.g. double spacing) may be requested with ls. 9 _5._2._E_x_t_r_a _l_i_n_e-_s_p_a_c_e. If a word contains a vertically tall con- struct requiring the output line containing it to have extra vertical space before and/or after it, the _e_x_t_r_a-_l_i_n_e-_s_p_a_c_e func- tion \x'_N' can be imbedded in or attached to 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 vert- ical space. If successive requests for extra space apply to the same line, the maximum values are used. The most recently util- ized post-line extra line-space is available in the .a register. 9 _5._3._B_l_o_c_k_s _o_f _v_e_r_t_i_c_a_l _s_p_a_c_e. A block of vertical space is ordi- narily requested using sp, which honors the _n_o-_s_p_a_c_e mode and which does not space _p_a_s_t a trap. A contiguous block of vertical space may be reserved using sv. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .vs_N 1/6in;12pts previousE,pSet vertical base-line spacing size _V. Transient _e_x_t_r_a vertical space available with \x'_N' (see above). 9 .ls_N _N=1 previous E _L_i_n_e spacing set to +__N. _N-1 _Vs (_b_l_a_n_k _l_i_n_e_s) are appended to each output text line. Appended blank lines are omitted, if the text or previous appended blank line reached a trap position. 9 .sp _N - _N=1_V B,v Space vertically in _e_i_t_h_e_r direc- tion. If _N is negative, the motion 9 - 16 - 9 NROFF/TROFF User's Manual October 11, 1976 is _b_a_c_k_w_a_r_d (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). 9 .sv _N - _N=1_V v Save a contiguous vertical block of size _N. If the distance to the next trap is greater than _N, _N vertical space is output. No-space mode has _n_o effect. If this distance is less than _N, no vertical space is immedi- ately output, but _N is remembered for later output (see os). Subse- quent sv requests will overwrite any still remembered _N. 9 .os - - - Output saved vertical space. No- space mode has _n_o effect. Used to finally output a block of vertical space requested by an earlier sv request. 9 .ns space - D No-space mode turned on. When on, the no-space mode inhibits sp requests and bp requests _w_i_t_h_o_u_t a next page number. The no-space mode is turned off when a line of output occurs, or with rs. 9 .rs space - D Restore spacing. The no-space mode is turned off. 9 Blank text line. - B Causes a break and output of a blank line exactly like sp 1. 9 6. Line Length and Indenting 9 The maximum line length for fill mode may be set with ll. The indent may be set with in; an indent applicable to _o_n_l_y the _n_e_x_t output line may be set with ti. The line length includes indent space but _n_o_t 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 registers .l and .i respectively. The length of _t_h_r_e_e-_p_a_r_t _t_i_t_l_e_s produced by tl (see 14) is _i_n_d_e_p_e_n_d_e_n_t_l_y set by lt. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .ll +__N 6.5in previous E,mLine length is set to +__N. In TROFF the maximum (line- length)+(page-offset) is about 7.54 inches. - 17 - 9 NROFF/TROFF User's Manual October 11, 1976 .in +__N _N=0 previous B,E,mIndent is set to +__N. The indent is prepended to each output line. 9 .ti +__N - ignored B,E,m Temporary indent. The _n_e_x_t output text line will be indented a dis- tance +__N with respect to the current indent. The resulting total indent may not be negative. The current indent is not changed. 9 7. Macros, Strings, Diversion, and Position Traps 9 _7._1._M_a_c_r_o_s _a_n_d _s_t_r_i_n_g_s. A _m_a_c_r_o is a named set of arbitrary _l_i_n_e_s that may be invoked by name or with a _t_r_a_p. A _s_t_r_i_n_g is a named string of _c_h_a_r_a_c_t_e_r_s, _n_o_t including a newline character, that may be interpolated by name at any point. Request, macro, and string names share the _s_a_m_e 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 ._x_x will interpolate the con- tents of macro _x_x. The remainder of the line may contain up to nine _a_r_g_u_m_e_n_t_s. The strings _x and _x_x are interpolated at any desired point with \*_x and \*(_x_x respectively. String references and macro invocations may be nested. 9 _7._2._C_o_p_y _m_o_d_e _i_n_p_u_t _i_n_t_e_r_p_r_e_t_a_t_i_o_n. During the definition and extension of strings and macros (not by diversion) the input is read in _c_o_p_y _m_o_d_e. The input is copied without interpretation _e_x_c_e_p_t that: 9 o+ The contents of number registers indicated by \n are interpolated. o+ Strings indicated by \* are interpolated. o+ Arguments indicated by \$ are interpolated. o+ Concealed newlines indicated by \(newline) are eliminated. o+ Comments indicated by \" are eliminated. o+ \t and \a are interpreted as ASCII horizontal tab and SOH respectively (9). o+ \\ is interpreted as \. o+ \. is interpreted as ".". 9 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. 9 _7._3._A_r_g_u_m_e_n_t_s. 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 character, and arguments may be surrounded by double-quotes to permit imbedded 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 newline may be used to continue on the next line. 9 9 - 18 - 9 NROFF/TROFF User's Manual October 11, 1976 When a macro is invoked the _i_n_p_u_t _l_e_v_e_l is _p_u_s_h_e_d _d_o_w_n 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 arguments can be interpolated at _a_n_y point within the macro with \$_N, which interpolates the _Nth argu- ment (1<__N<_9). If an invoked argument doesn't exist, a null string results. For example, the macro _x_x may be defined by 9 .de xx \"begin definition Today is \\$1 the \\$2. .. \"end definition 9 and called by 9 .xx Monday 14th 9 to produce the text 9 Today is Monday the 14th. 9 Note that the \$ was concealed in the definition with a prepended \. The number of currently available arguments is in the .$ register. 9 No arguments are available at the top (non-macro) level in this implementation. Because string referencing is implemented as a input-level push down, no arguments are available from _w_i_t_h_i_n a string. No arguments are available within a trap-invoked macro. 9 Arguments are copied in _c_o_p_y _m_o_d_e onto a stack where they are available for reference. The mechanism does not allow an argu- ment to contain a direct reference to a _l_o_n_g string (interpolated at copy time) and it is advisable to conceal string references (with an extra \) to delay interpolation until argument reference time. 9 _7._4._D_i_v_e_r_s_i_o_n_s. Processed output may be diverted into a macro for purposes such as footnote 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 number registers dn and dl respectively contain the vertical and hor- izontal 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 _n_o_f_i_l_l 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 or bd requests with the _t_r_a_n_- _s_p_a_r_e_n_t mechanism described in 10.6. 9 Diversions may be nested and certain parameters and registers are associated with the current diversion level (the top non- diversion 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). 99 9 - 19 - 9 NROFF/TROFF User's Manual October 11, 1976 _7._5._T_r_a_p_s. 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 position 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 rendered effective by an increase in page length. Two traps may be planted at the _s_a_m_e position only by first planting them at different positions and then moving one of the traps; 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 verti- cal size _r_e_a_c_h_e_s or _s_w_e_e_p_s _p_a_s_t the trap position. 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 position is available in the .t 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. 9 A macro-invocation trap effective in the current diversion may be planted using dt. The .t register works in a diversion; if there is no subsequent trap a _l_a_r_g_e distance is returned. For a description of input-line-count traps, see it below. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .de _x_x _y_y - ._y_y=.. -Define or redefine the macro _x_x. The contents of the macro begin on the next input line. Input lines are copied in _c_o_p_y _m_o_d_e until the definition is terminated by a line beginning with ._y_y, whereupon the macro _y_y is called. In the absence of _y_y, the definition is terminated by a line beginning with "..". A macro may contain de requests pro- vided the terminating macros differ or the contained definition termina- tor is concealed. ".." can be con- cealed as \\.. which will copy as \.. and be reread as "..". 9 .am _x_x _y_y - ._y_y=.. -Append to macro (append version of de). 9 .ds _x_x _s_t_r_i_n_g - ignored-Define a string _x_x containing _s_t_r_i_n_g. Any initial double-quote in _s_t_r_i_n_g is stripped off to permit initial blanks. 9 .as _x_x _s_t_r_i_n_g - ignored-Append _s_t_r_i_n_g to string _x_x (append version of ds). 9 .rm _x_x - ignored - Remove request, macro, or string. The name _x_x is removed from the name list and any related storage space - 20 - 9 NROFF/TROFF User's Manual October 11, 1976 is freed. Subsequent references will have no effect. 9 .rn _x_x _y_y - ignored-Rename request, macro, or string _x_x to _y_y. If _y_y exists, it is first removed. 9 .di _x_x - end D Divert output to macro _x_x. 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. 9 .da _x_x - end D Divert, appending to _x_x (append ver- sion of di). 9 .wh _N _x_x - - v Install a trap to invoke _x_x at page position _N; a _n_e_g_a_t_i_v_e _N will be interpreted with respect to the page _b_o_t_t_o_m. Any macro previously planted at _N is replaced by _x_x. A zero _N refers to the _t_o_p of a page. In the absence of _x_x, the first found trap at _N, if any, is removed. 9 .ch _x_x _N - - v Change the trap position for macro _x_x to be _N. In the absence of _N, the trap, if any, is removed. 9 .dt _N _x_x - off D,vInstall a diversion trap at posi- tion _N in the _c_u_r_r_e_n_t diversion to invoke macro _x_x. Another dt will redefine the diversion trap. If no arguments are given, the diversion trap is removed. 9 .it _N _x_x - off E Set an input-line-count trap to invoke the macro _x_x after _N lines of _t_e_x_t input have been read (control or request lines don't count). The text may be in-line text or text interpolated by inline or trap- invoked macros. 9 .em _x_x none none - The macro _x_x will be invoked when all input has ended. The effect is the same as if the contents of _x_x had been at the end of the last file processed. 9 8. Number Registers 9 A variety of parameters are available to the user as predefined, named _n_u_m_b_e_r _r_e_g_i_s_t_e_r_s (see Summary and Index, page 7). In addi- tion, the user may define his own named registers. Register 9 - 21 - 9 NROFF/TROFF User's Manual October 11, 1976 names are one or two characters long and _d_o _n_o_t 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 interpolated into the input in a variety of formats. One common use of user- defined registers is to automatically number sections, para- graphs, lines, etc. A number register may be used any time numerical input is expected or desired and may be used in numeri- cal _e_x_p_r_e_s_s_i_o_n_s (1.4). 9 Number registers are created and modified using nr, which speci- fies the name, numerical value, and the auto-increment size. Registers are also modified, if accessed with an auto- incrementing sequence. If the registers _x and _x_x both contain _N and have the auto-increment size _M, the following access sequences have the effect shown: 8 _____________________________________________ Effect on Value Sequence Register Interpolated 8 _____________________________________________ \n_x none _N \n(_x_x none _N \n+_x _x incremented by _M _N+_M \n-_x _x decremented by _M _N-_M \n+(_x_x _x_x incremented by _M _N+_M \n-(_x_x _x_x decremented by _M _N-_M 8 _____________________________________________ 7 |7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7| 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. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .nr _R +__N _M - u The number register _R is assigned the value +__N with respect to the previous value, if any. The incre- ment for auto-incrementing is set to _M. 9 .af _R _c arabic - - Assign format _c to register _R. The available formats are: 8 ____________________________________________ Numbering Format Sequence 8 ____________________________________________ 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,... 8 ____________________________________________ 7 |7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7| An arabic format having _N digits 9 - 22 - 9 NROFF/TROFF User's Manual October 11, 1976 specifies a field width of _N digits (example 2 above). The read-only registers and the _w_i_d_t_h function (11.2) are always arabic. 9 .rr _R - ignored - Remove register _R. If many regis- ters are being created dynamically, it may become necessary to remove no longer used registers to recapture internal storage space for newer registers. 9 9. Tabs, Leaders, and Fields 9 _9._1._T_a_b_s _a_n_d _l_e_a_d_e_r_s. The ASCII horizontal tab character and the ASCII SOH (hereafter known as the _l_e_a_d_e_r character) can both be used to generate either horizontal motion or a string of repeated characters. The length of the generated entity is governed by internal _t_a_b _s_t_o_p_s specifiable with ta. The default difference 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-_l_e_f_t adjust- ing, _r_i_g_h_t adjusting, and _c_e_n_t_e_r_i_n_g. In the following table: _D is the distance from the current position on the _i_n_p_u_t line (where a tab or leader was found) to the next tab stop; _n_e_x_t- _s_t_r_i_n_g consists of the input characters following the tab (or leader) up to the next tab (or leader) or end of line; and _W is the width of _n_e_x_t-_s_t_r_i_n_g. 8 ___________________________________________________________ Tab Length of motion or Location of type repeated characters _n_e_x_t-_s_t_r_i_n_g 8 ___________________________________________________________ Left _D Following _D Right _D-_W Right adjusted within _D Centered _D-_W/2 Centered on right end of _D 8 ___________________________________________________________ 7 |7|7|7|7|7| |7|7|7|7|7| |7|7|7|7|7| |7|7|7|7|7| The length of generated motion is allowed to be negative, but that of a repeated character string cannot be. Repeated charac- ter 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 _n_e_x_t- _s_t_r_i_n_g terminators. 9 Tabs and leaders are not interpreted in _c_o_p_y _m_o_d_e. \t and \a always generate a non-interpreted tab and leader respectively, and are equivalent to actual tabs and leaders in _c_o_p_y _m_o_d_e. 9 _9._2._F_i_e_l_d_s. A _f_i_e_l_d is contained between a _p_a_i_r of _f_i_e_l_d _d_e_l_i_m_- _i_t_e_r characters, and consists of sub-strings separated by _p_a_d_d_i_n_g indicator characters. The field length is the distance on the _i_n_p_u_t line from the position where the field begins to the next tab stop. The difference between the total length of all the sub-strings and the field length is incorporated as horizontal 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 ^, 9 - 23 - 9 NROFF/TROFF User's Manual October 11, 1976 #^_x_x_x^_r_i_g_h_t# specifies a right-adjusted string with the string _x_x_x centered in the remaining space. 9 _R_e_q_u_e_s_t _I_n_i_t_i_a_l _I_f _N_o _F_o_r_m _V_a_l_u_e _A_r_g_u_m_e_n_t _N_o_t_e_s_E_x_p_l_a_n_a_t_i_o_n 9 .ta _N_t ... 0.8; 0.5in noneE,mSet tab stops and types. _t=R, right adjusting; _t=C, center- ing; _t absent, left adjusting. TROFF tab stops are preset every 0.5in.; NROFF every 0.8in. The stop values are separated by spaces, and a value preceded by + is treated as an increment to the previous stop value. 9 .tc _c none none E The tab repetition character becomes _c, or is removed specifying motion. 9 .lc _c . none E The leader repetition character becomes _c, or is removed specifying motion. 9 .fc _a _b off off - The field delimiter is set to _a; the padding indicator is set to the _s_p_a_c_e character or to _b, if given. In the absence of arguments the field mechanism is turned off. 9 10. Input and Output Conventions and Character Translations 9 _1_0._1._I_n_p_u_t _c