NROFF/TROFF User's Manual _J_o_s_e_p_h _F. _O_s_s_a_n_n_a (_u_p_d_a_t_e_d _f_o_r _4._3_B_S_D _b_y _M_a_r_k _S_e_i_d_e_n) Bell Laboratories Murray Hill, New Jersey 07974 Introduction 9NROFF and TROFF are text processors under the UNIX Time-Sharing System that format text for typewriter-like terminals and for a Graphic Systems phototypesetter, respectively. (Device- independent TROFF, part of the Documenter's Workbench, supports additional output devices.) They accept lines of text inter- spersed with lines of format control information and format the text into a printable, paginated document having a user-designed style. NROFF and TROFF offer unusual freedom in document styl- ing, including: arbitrary style headers and footers; arbitrary style footnotes; multiple automatic sequence numbering for para- graphs, 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 -i Read standard input after the input files are exhausted. 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 -n_N Number first generated page _N. 9 -o_l_i_s_t Print only pages whose page numbers appear in _l_i_s_t, 9 9 USD:24-2 NROFF/TROFF User's Manual 9 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 -q Invoke the simultaneous input-output mode of the rd request. 9 -r_a_N Number register _a (one-character) is set to _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 -z Efficiently suppress formatted output. Only produce output to standard error (from tm requests or diag- nostics). _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. 9 -h On output, use tabs during horizontal spacing to increase speed. Device tabs setting are assumed to be (and input tabs are initially set to) every 8 character widths. _T_R_O_F_F _O_n_l_y 9 -a Send a printable (ASCII) approximation of the results to the standard output. 9 -b TROFF will report whether the phototypesetter is busy or available. No text processing is done. 9 -f Refrain from feeding out paper and stopping photo- typesetter at the end of the run. 9 -t Direct output to the standard output instead of the phototypesetter. 9 -w Wait until phototypesetter is available, if currently busy. 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 requests formatting of pages 4, 8, 9, and 10 of a document 9 NROFF/TROFF User's Manual USD:24-3 9 contained in the files named _f_i_l_e_1 and _f_i_l_e_2, specifies the out- put 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 EQN1 (for NROFF and TROFF respectively), and the table- construction preprocessor TBL2. A reverse-line postprocessor COL3 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. TK3 is a 37 Teletype simulator postprocessor for printing NROFF output on a Tektronix 4014. TC5 is a 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 | tc 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 TC. 9 The remainder of this manual consists of: a Summary and outline; a Reference Manual keyed to the outline; and a set of Tutorial Examples. Another tutorial is [5]. 99 References 9 [1]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. 9 [2]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 [3]Internal on-line documentation (_m_a_n pages) on UNIX. 9 [4]B. W. Kernighan, _A _T_R_O_F_F _T_u_t_o_r_i_a_l, Bell Laboratories. 9 [5]Your site may have similar programs for more modern displays. 9 9 USD:24-4 NROFF/TROFF User's Manual 9 9 NROFF/TROFF User's Manual USD:24-3 9 SUMMARY OF REQUESTS AND OUTLINE OF THIS MANUAL 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.|- .fz _F +__N off - E font _F to point size +__N. .fz S _F +__N off - E Special Font characters to point size +__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 __________ 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 USD:24-4 NROFF/TROFF User's Manual 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 output line. .sp _N - _N=1_V B,v Space vertical distance _N _i_n _e_i_t_h_e_r _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. 9 NROFF/TROFF User's Manual USD:24-5 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 .ul _N off _N=1 E Underline (italicize in TROFF) _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 USD:24-6 NROFF/TROFF User's Manual 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 18. Insertions from the Standard Input 9 .rd _p_r_o_m_p_t - _p_r_o_m_p_t=BELRead 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 error 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. .ab _s_t_r_i_n_g - - - Print a message and abort. .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 ab20 ad4 af8 am7 as7 bd2 bp3 br4 77777777 c210 cc10 ce4 ch7 cs2 cu10 da7 de7 77777777 di7 ds7 dt7 ec10 el16 em7 eo10 ev17 77777777 ex18 fc9 fi4 fl20 fp2 ft2 fz2 hc13 77777777 hw13 hy13 ie16 if16 ig20 in6 it7 lc9 77777777 lg10 li10 ll6 ls5 lt14 mc20 mk3 na4 77777777 ne3 nf4 nh13 nm15 nn15 nr8 ns5 nx19 77777777 os5 pc14 pi19 pl3 pm20 pn3 po3 ps2 77777777 rd18 rm7 rn7 rr8 rs5 rt3 so19 sp5 77777777 ss2 sv5 ta9 tc9 ti6 tl14 tm20 tr10 77777777 uf10 ul10 vs5 wh7 7777 9 9 9 NROFF/TROFF User's Manual USD:24-7 9 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 9 9 USD:24-8 NROFF/TROFF User's Manual 9 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. 19 c. Number of _l_i_n_e_s read from current input file. 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 (not in ditroff) 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. 5.3 .L Set to current _l_i_n_e-_s_p_a_c_i_n_g (ls) parameter - .P Set to 1 if the current page is being printed; otherwise 0. - .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'. 19 .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. 4.2 .j Current adjustment mode and type. 4.1 .k Length of text portion on current partial output line. 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 9 9 NROFF/TROFF User's Manual USD:24-9 9 9 USD:24-8 NROFF/TROFF User's Manual 9 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 sthetic reasons. Names must be followed by either space or newline. Control lines with unrecognized 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 (insertion in place) 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, (for historical reasons, corresponding to the Graphic Systems phototypesetter which had a horizontal resolution of 1/432 inch and a vertical resolution of 1/144 inch.) NROFF inter- nally uses 240 units/inch, corresponding to the least common mul- tiple of the horizontal and vertical resolutions of various typewriter-like output devices. TROFF rounds horizontal/vertical numerical parameter input to its own internal horizontal/vertical resolution. 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 scale indicator suffixes 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. 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| 9 9 9 NROFF/TROFF User's Manual USD:24-9 9 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 prefixed 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 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.2 centimeters 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 .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 9 9 USD:24-10 NROFF/TROFF User's Manual 9 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 a typesetter-dependent basic character set plus a Special Mathemat- ical Font character set-each having 102 characters. An example of these character sets is shown in the Appendix Table I. All printable ASCII characters are included, with some on the Special Font. With three exceptions, these ASCII characters are input as themselves, and non-ASCII characters are input in the form \(_x_x where _x_x is a two-character name given in the Appendix 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) 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 9 9 NROFF/TROFF User's Manual USD:24-11 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 are typesetter dependent, but often include 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 .fz _F +__N off - E The characters in font _F will be adjusted to be in size +__N. Charac- ters in the Special Font encountered during the use of font _F will have the same size modification. (Use the .fz S request if different treatment of Special Font characters is required). .fz must follow any .fp request for the position. 9 .fz S _F +__N off - E The characters in the Special Font will be in size +__N independent of previous .fz requests. 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 affected characters are centered in this space, including those with an __________ 9 *Notes are explained at the end of the Summary and Index above. 9 USD:24-12 NROFF/TROFF User's Manual 9 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 _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 NROFF/TROFF User's Manual USD:24-13 9 The usable page width on the Graphic Systems phototypesetter was about 7.54 inches, beginning about 1/27 inch from the left edge of the 8 inch wide, continuous roll paper, but these characteris- tics are typesetter- dependent. The physical limitations 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 affect 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 _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 __________ 9 *The use of " ' " as control character (instead of ".") suppresses the break function. 9 |-Values separated by ";" are for NROFF and TROFF respectively. 9 9 USD:24-14 NROFF/TROFF User's Manual 9 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 to hyphenate the word 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 charac- ter 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; however, 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 posi- tion 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. The .k register (read-only) contains the hor- izontal size of the text portion (without indent) of the current partially-collected output line (if any) in the current environ- ment. 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 (10.4) can be made to not look like a control line by preceding 9 NROFF/TROFF User's Manual USD:24-15 9 it by 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. The type indicator can also be a value saved from the read-only .j number register, which is set to contain the current adjustment mode and type. 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. 9 USD:24-16 NROFF/TROFF User's Manual 9 The adjustment type for ad is not changed. Output line filling still occurs if fill mode is on. 9 .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. The (read-only) number register .L is set to contain the current line-spacing value. Appended blank lines are omitted, if 9 NROFF/TROFF User's Manual USD:24-17 9 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 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 outputs a blank line just 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 9 9 USD:24-18 NROFF/TROFF User's Manual 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. 9 .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 9 9 NROFF/TROFF User's Manual USD:24-19 9 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 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- 9 9 USD:24-20 NROFF/TROFF User's Manual 9 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). 9 _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 the it request 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 9 9 NROFF/TROFF User's Manual USD:24-21 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 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 9 USD:24-22 NROFF/TROFF User's Manual 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 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: 9 9 9 NROFF/TROFF User's Manual USD:24-23 98 ____________________________________________ 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 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, 9 USD:24-24 NROFF/TROFF User's Manual 9 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 ^, #^_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 ... 8n; 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 8 character widths. 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_h_a_r_a_c_t_e_r _t_r_a_n_s_l_a_t_i_o_n_s. Ways of inputting the graphic character set were discussed in 2.1. The ASCII control charac- ters horizontal tab (9.1), SOH (9.1), and backspace (10.3) are discussed elsewhere. The newline delimits input lines. In addi- tion, STX, ETX, ENQ, ACK, and BEL are accepted, and may be used as delimiters or translated into a graphic with tr (10.5). _A_l_l others are ignored. 9 The _e_s_c_a_p_e character \ introduces _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s-causes the following character to mean another character, or to indicate some function. A complete list of such sequences is given in the Summary and Index on page 6. \ should not be confused with the ASCII control character ESC of the same name. The escape charac- ter \ can be input with the sequence \\. The escape character can be changed with ec, and all that has been said about the default \ becomes true for the new escape character. \e can be 9 9 NROFF/TROFF User's Manual USD:24-25 9 used to print whatever the current escape character is. If necessary or convenient, the escape mechanism may be turned off with eo, and restored with ec. 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 .ec _c \ \ - Set escape character to \, or to _c, if given. 9 .eo on - - Turn escape mechanism off. 9 _1_0._2._L_i_g_a_t_u_r_e_s. Five ligatures are available in the current TROFF character set - fi, fl, ff, ffi, and ffl. They may be input (even in NROFF) by \(fi, \(fl, \(ff, \(Fi, and \(Fl respec- tively. The ligature mode is normally on in TROFF, and _a_u_t_o_m_a_t_i_- _c_a_l_l_y invokes ligatures during input. 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 .lg _N off; on on - Ligature mode is turned on if _N is absent or non-zero, and turned off if _N=0. If _N=2, only the two- character ligatures are automati- cally invoked. Ligature mode is inhibited for request, macro, string, register, or file names, and in _c_o_p_y _m_o_d_e. No effect in NROFF. 9 _1_0._3._B_a_c_k_s_p_a_c_i_n_g, _u_n_d_e_r_l_i_n_i_n_g, _o_v_e_r_s_t_r_i_k_i_n_g, _e_t_c. Unless in _c_o_p_y _m_o_d_e, the ASCII backspace character is replaced by a backward horizontal motion having the width of the space character. Underlining as a form of line-drawing is discussed in 12.4. A generalized overstriking function is described in 12.1. 9 NROFF automatically underlines characters in the _u_n_d_e_r_l_i_n_e font, specifiable with uf, normally Times Italic on font position 2 (see 2.2). In addition to ft and \f_F, the underline font may be selected by ul and cu. Underlining is restricted to an output- device-dependent subset of _r_e_a_s_o_n_a_b_l_e characters. 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 .ul _N off _N=1 E Underline in NROFF (italicize in TROFF) the next _N input text lines. Actually, switch to _u_n_d_e_r_l_i_n_e font, saving the current font for later restoration; _o_t_h_e_r font changes within the span of a ul will take effect, but the restoration will undo the last change. Output gen- erated by tl (14) _i_s affected by the font change, but does _n_o_t decrement _N. If _N>1, there is the risk that a trap interpolated macro may provide text lines within the span; environ- ment switching can prevent this. 9 9 9 USD:24-26 NROFF/TROFF User's Manual 9 .cu _N off _N=1 E A variant of ul that causes _e_v_e_r_y character to be underlined in NROFF. Identical to ul in TROFF. 9 .uf _F Italic Italic - Underline font set to _F. In NROFF, _F may _n_o_t be on position 1 (ini- tially Times Roman). 9 _1_0._4._C_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r_s. Both the control character . and the _n_o-_b_r_e_a_k control character ' may be changed, if desired. Such a change must be compatible with the design of any macros used in the span of the change, and particularly of any trap-invoked mac- ros. 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 .cc _c . . E The basic control character is set to _c, or reset to ".". 9 .c2 _c ' ' E The _n_o_b_r_e_a_k control character is set to _c, or reset to "'". 9 _1_0._5._O_u_t_p_u_t _t_r_a_n_s_l_a_t_i_o_n. One character can be made a stand-in for another character using tr. All text processing (e. g. char- acter comparisons) takes place with the input (stand-in) charac- ter which appears to have the width of the final character. The graphic translation occurs at the moment of output (including diversion). 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 .tr _a_b_c_d.... none - O Translate _a into _b, _c into _d, etc. If an odd number of characters is given, the last one will be mapped into the space character. To be consistent, a particular translation must stay in effect from _i_n_p_u_t to _o_u_t_p_u_t time. 9 _1_0._6._T_r_a_n_s_p_a_r_e_n_t _t_h_r_o_u_g_h_p_u_t. An input line beginning with a \! is read in _c_o_p_y _m_o_d_e and _t_r_a_n_s_p_a_r_e_n_t_l_y output (without the ini- tial \!); the text processor is otherwise unaware of the line's presence. This mechanism may be used to pass control information to a post-processor or to imbed control lines in a macro created by a diversion. 9 _1_0._7._C_o_m_m_e_n_t_s _a_n_d _c_o_n_c_e_a_l_e_d _n_e_w_l_i_n_e_s. An uncomfortably long input line that must stay one line (e. g. a string definition, or nofilled text) can be split into many physical lines by ending all but the last one with the escape \. The sequence \(newline) is _a_l_w_a_y_s ignored-except in a comment. Comments may be imbedded at the _e_n_d of any line by prefacing them with \". The newline at the end of a comment cannot be concealed. A line beginning with \" will appear as a blank line and behave like .sp 1; a comment can be on a line by itself by beginning the line with .\". 9 9 9 NROFF/TROFF User's Manual USD:24-27 9 11. Local Horizontal and Vertical Motions, and the Width Func- tion 9 _1_1._1._L_o_c_a_l _M_o_t_i_o_n_s. The functions \v'_N' and \h'_N' can be used for _l_o_c_a_l vertical and horizontal motion respectively. The dis- tance _N may be negative; the _p_o_s_i_t_i_v_e directions are _r_i_g_h_t_w_a_r_d and _d_o_w_n_w_a_r_d. A _l_o_c_a_l motion is one contained _w_i_t_h_i_n a line. To avoid unexpected vertical dislocations, it is necessary that the _n_e_t vertical local motion within a word in filled text and other- wise within a line balance to zero. The above and certain other escape sequences providing local motion are summarized in the following table. 8 _____________________________________________________________________________________ Vertical Effect in Horizontal Effect in Local Motion TROFF NROFF Local Motion TROFF NROFF 8 _____________________________________________________________________________________ 9 \v'_N' Move distance _N \h'_N' Move distance _N 8 __________________________________________9 \(space) Unpaddable space-size space \u 1/2 em up 1/2 line up \0 Digit-size space \d 1/2 em down 1/2 line down8 ___________________________________________ 9 \r 1 em up 1 line up \| 1/6 em space ignored \^ 1/12 em space ignored 98 _____________________________________________________________________________________ 7 |7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7| |8|7|7|7|7| 9 |7|7|7|7|7|7|7|7|7|999999999999999999|7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7| |8|7|7| 9 |7|7|7|7|7|7|7|7|7| As an example, E2 could be generated by the sequence E\s-2\v'-0.4m'2\v'0.4m'\s+2; it should be noted in this example that the 0.4 em vertical motions are at the smaller size. 9 _1_1._2._W_i_d_t_h _F_u_n_c_t_i_o_n. The _w_i_d_t_h function \w'_s_t_r_i_n_g' generates the numerical width of _s_t_r_i_n_g (in basic units). Size and font changes may be safely imbedded in _s_t_r_i_n_g, and will not affect the current environment. For example, .ti -\w'1. 'u could be used to temporarily indent leftward a distance equal to the size of the string "1. ". 9 The width function also sets three number registers. The regis- ters st and sb are set respectively to the highest and lowest extent of _s_t_r_i_n_g relative to the baseline; then, for example, the total _h_e_i_g_h_t of the string is \n(stu-\n(sbu. In TROFF the number register ct is set to a value between 0 and 3: 0 means that all of the characters in _s_t_r_i_n_g were short lower case characters without descenders (like e); 1 means that at least one character has a descender (like y); 2 means that at least one character is tall (like H); and 3 means that both tall characters and charac- ters with descenders are present. 9 _1_1._3._M_a_r_k _h_o_r_i_z_o_n_t_a_l _p_l_a_c_e. The escape sequence \k_x will cause the _c_u_r_r_e_n_t horizontal position in the _i_n_p_u_t _l_i_n_e to be stored in register _x. As an example, the construction \kx_w_o_r_d\h'|\nxu+2u'_w_o_r_d will embolden _w_o_r_d by backing up to almost its beginning and overprinting it, resulting in _w_o_r_d_w_o_r_d. 9 12. Overstrike, Bracket, Line-drawing, and Zero-width Functions 9 _1_2._1._O_v_e_r_s_t_r_i_k_i_n_g. Automatically centered overstriking of up to nine characters is provided by the _o_v_e_r_s_t_r_i_k_e function \o'_s_t_r_i_n_g'. The characters in _s_t_r_i_n_g are overprinted with 9 9 USD:24-28 NROFF/TROFF User's Manual 9 centers aligned; the total width is that of the widest character. _s_t_r_i_n_g should _n_o_t contain local vertical motion. As examples, \o'e\'' produces e', and \o'\(mo\(sl' produces /. 9 _1_2._2._Z_e_r_o-_w_i_d_t_h _c_h_a_r_a_c_t_e_r_s. The function \z_c will output _c without spacing over it, and can be used to produce left-aligned overstruck combinations. As examples, \z\(ci\(pl will produce O+, and \(br\z\(rn\(ul\(br will produce the smallest possible con- structed box |_|. 9 _1_2._3._L_a_r_g_e _B_r_a_c_k_e_t_s. The Special Mathematical Font contains a number of bracket construction pieces (|||||||||||) that can be combined into various bracket styles. The function \b'_s_t_r_i_n_g' may be used to pile up vertically the characters in _s_t_r_i_n_g (the first character on top and the last at the bottom); the charac- ters are vertically separated by 1 em and the total pile is cen- tered 1/2em above the current baseline (1/2 line in NROFF). For example, \b'\(lc\(lf'E\|\b'\(rc\(rf'\x'-0.5m'\x'0.5m' produces 98 |99|8E8|99|8. _1_2._4._L_i_n_e _d_r_a_w_i_n_g. The function \l'_N_c' will draw a string of repeated _c's towards the right for a distance _N. (\l is \(lower case L). If _c looks like a continuation of an expression for _N, it may insulated from _N with a \&. If _c is not specified, the _ (baseline rule) is used (underline character in NROFF). If _N is negative, a backward horizontal motion of size _N is made _b_e_f_o_r_e drawing the string. Any space resulting from _N/(size of _c) hav- ing a remainder is put at the beginning (left end) of the string. In the case of characters that are designed to be connected such as baseline-rule _, underrule _, and root-en , the remainder space is covered by over-lapping. If _N is _l_e_s_s than the width of _c, a single _c is centered on a distance _N. As an example, a macro to underscore a string can be written 9 .de us \\$1\l'|0\(ul' .. 9 or one to draw a box around a string 9 .de bx \(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul' .. 9 such that 9 .us "underlined words" 9 and 9 .bx "words in a box" 9 yield underlined words________________ and |words in a box|________________. 9 The function \L'_N_c' will draw a vertical line consisting of the (optional) character _c stacked vertically apart 1em (1 line in NROFF), with the first two characters overlapped, if necessary, to form a continuous line. The default character is the _b_o_x _r_u_l_e | (\(br); the other suitable character is the _b_o_l_d _v_e_r_t_i_c_a_l | (\(bv). The line is begun without any initial motion relative to 9 NROFF/TROFF User's Manual USD:24-29 9 the current base line. A positive _N specifies a line drawn down- ward and a negative _N specifies a line drawn upward. After the line is drawn _n_o compensating motions are made; the instantaneous baseline is at the _e_n_d of the line. 9 The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The zero-width _b_o_x-_r_u_l_e and the 1/2-em wide _u_n_d_e_r_r_u_l_e were _d_e_s_i_g_n_e_d to form corners when using 1-em vertical spacings. For example the macro 9 .de eb .sp -1 \"compensate for next automatic base-line spacing .nf \"avoid possibly overflowing word buffer \h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(ul' \"draw box .fi .. 9 will draw a box around some text whose beginning vertical place was saved in number register _a (e. g. using .mk a) as done for this paragraph. 7 |7|7|7|7|7|7|7|7|7|7|7|7|7|7__________________________________________________________________99|99|99|99|99|99|99|99|99|99|99|99|99|99|____________________________________________________________________ 9 13. Hyphenation. 9 The automatic hyphenation may be switched off and on. When switched on with hy, several variants may be set. A _h_y_p_h_e_n_a_t_i_o_n _i_n_d_i_c_a_t_o_r character may be imbedded in a word to specify desired hyphenation points, or may be prepended to suppress hyphenation. In addition, the user may specify a small exception word list. 9 Only words that consist of a central alphabetic string surrounded by (usually null) non-alphabetic strings are considered candi- dates for automatic hyphenation. Words that were input contain- ing hyphens (minus), em-dashes (\(em), or hyphenation indicator characters-such as mother-in-law-are _a_l_w_a_y_s subject to splitting after those characters, whether or not automatic hyphenation is on or off. 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 .nh hyphenate - E Automatic hyphenation is turned off. 9 .hy_N on,_N=1 on,_N=1 E Automatic hyphenation is turned on for _N>_1, or off for _N=0. If _N=2, _l_a_s_t lines (ones that will cause a trap) are not hyphenated. For _N=4 and 8, the last and first two char- acters respectively of a word are not split off. These values are additive; i. e. _N=14 will invoke all three restrictions. 9 .hc _c \% \% E Hyphenation indicator character is set to _c or to the default \%. The indicator does not appear in the output. 9 .hw _w_o_r_d_1 ... ignored-Specify hyphenation points in words with imbedded minus signs. 9 9 USD:24-30 NROFF/TROFF User's Manual 9 Versions of a word with terminal _s are implied; i. e. _d_i_g-_i_t implies _d_i_g-_i_t_s. This list is examined ini- tially _a_n_d after each suffix strip- ping. The space available is small-about 128 characters. 9 14. Three Part Titles. 9 The titling function tl provides for automatic placement of three fields at the left, center, and right of a line with a title- length specifiable with lt. tl may be used anywhere, and is independent of the normal text collecting process. A common use is in header and footer macros. 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 .tl '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t' - - The strings _l_e_f_t, _c_e_n_t_e_r, and _r_i_g_h_t are respectively left- adjusted, centered, and right- adjusted in the current title- length. Any of the strings may be empty, and overlapping is permitted. If the page-number character (ini- tially %) is found within any of the fields it is replaced by the current page number having the format assigned to register %. Any charac- ter may be used as the string delim- iter. 9 .pc _c % off - The page number character is set to _c, or removed. The page-number register remains %. 9 .lt +__N 6.5in previous E,mLength of title set to +__N. The line-length and the title-length are _i_n_d_e_p_e_n_d_e_n_t. Indents do not apply to titles; page-offsets do. 9 15. Output Line Numbering. 9 Automatic sequence numbering of output lines may be requested with nm. When in effect, a three-digit, arabic number plus a 3 digit-space is prepended to output text lines. The text lines are thus offset by four digit-spaces, and otherwise retain their line length; a reduction in line length may be 6 desired to keep the right margin aligned with an earlier mar- gin. Blank lines, other vertical spaces, and lines generated by tl are _n_o_t numbered. Numbering can be temporarily 9 suspended with nn, or with an .nm followed by a later .nm +0. In addition, a line number indent _I, and the number-text separation _S may be specified in digit-spaces. Further, it 12 can be specified that only those line numbers that are multi- ples of some number _M are to be printed (the others will appear as blank number fields). 9 9 9 NROFF/TROFF User's Manual USD:24-31 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 .nm +__N _M _S _I off E Line number mode. If +__N is given, line numbering is turned on, and the next output line numbered is num- bered +__N. Default values are _M=1, _S=1, and _I=0. Parameters corresponding to missing arguments are unaffected; a non-numeric argu- ment is considered missing. In the absence of all arguments, numbering is turned off; the next line number is preserved for possible further use in number register ln. 9 .nn _N - _N=1 E The next _N text output lines are not numbered. 9 15 As an example, the paragraph portions of this section are numbered with _M=3: .nm 1 3 was placed at the beginning; .nm was placed at the end of the first paragraph; and .nm +0 was 18 placed in front of this paragraph; and .nm finally placed at the end. Line lengths were also changed (by \w'0000'u) to keep the right side aligned. Another example is .nm +5 5 x 3 21 which turns on numbering with the line number of the next line to be 5 greater than the last numbered line, with _M=5, with spacing _S untouched, and with the indent _I set to 3. 9 16. Conditional Acceptance of Input 9 In the following, _c is a one-character, built-in _c_o_n_d_i_t_i_o_n name, ! signifies _n_o_t, _N is a numerical expression, _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2 are strings delimited by any non-blank, non-numeric character _n_o_t in the strings, and _a_n_y_t_h_i_n_g represents what is conditionally accepted. 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 .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; in multi-line case use _\{_a_n_y_t_h_i_n_g_\}. 9 .if !_c _a_n_y_t_h_i_n_g - - If condition _c false, accept _a_n_y_- _t_h_i_n_g. 9 .if _N _a_n_y_t_h_i_n_g - u If expression _N > 0, accept _a_n_y_- _t_h_i_n_g. 9 .if !_N _a_n_y_t_h_i_n_g - u If expression _N <_ 0, accept _a_n_y_- _t_h_i_n_g. 9 .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. 9 .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. 9 .ie _c _a_n_y_t_h_i_n_g - u If portion of if-else; all above forms (like if). 9 9 USD:24-32 NROFF/TROFF User's Manual 9 .el _a_n_y_t_h_i_n_g - - Else portion of if-else. 9 The built-in condition names are: 8 ________________________________________ Condition Name True If 8 ________________________________________ o Current page number is odd e Current page number is even t Formatter is TROFF n Formatter is NROFF 8 ________________________________________ 7 |7|7|7|7|7|7| |7|7|7|7|7|7| |7|7|7|7|7|7| If the condition _c is _t_r_u_e, or if the number _N is greater than zero, or if the strings compare identically (including motions and character size and font), _a_n_y_t_h_i_n_g is accepted as input. If a ! precedes the condition, number, or string comparison, the sense of the acceptance is reversed. 9 Any spaces between the condition and the beginning of _a_n_y_t_h_i_n_g are skipped over. The _a_n_y_t_h_i_n_g can be either a single input line (text, macro, or whatever) or a number of input lines. In the multi-line case, the first line must begin with a left delimiter \{ and the last line must end with a right delimiter \}. 9 The request ie (if-else) is identical to if except that the acceptance state is remembered. A subsequent and matching el (else) request then uses the reverse sense of that state. ie - el pairs may be nested. 9 Some examples are: 9 .if e .tl 'Even Page %''' 9 which outputs a title if the page number is even; and 9 .ie \n%>1 \{\ 'sp 0.5i .tl 'Page %''' 'sp |1.2i \} .el .sp |2.5i 9 which treats page 1 differently from other pages. 9 17. Environment Switching. 9 A number of the parameters that control the text processing are gathered together into an _e_n_v_i_r_o_n_m_e_n_t, which can be switched by the user. The environment parameters are those associated with requests noting E in their _N_o_t_e_s column; in addition, partially collected lines and words are in the environment. Everything else is global; examples are page-oriented parameters, diversion-oriented parameters, number registers, and macro and string definitions. All environments are initialized with default parameter values. 9 9 9 9 NROFF/TROFF User's Manual USD:24-33 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 .ev _N _N=0 previous - Environment switched to environ- ment 0<__N<_2. Switching is done in push-down fashion so that restoring a previous environment _m_u_s_t be done with .ev rather than specific refer- ence. 9 18. Insertions from the Standard Input 9 The input can be temporarily switched to the system _s_t_a_n_d_a_r_d _i_n_p_u_t with rd, which will switch back when _t_w_o newlines in a row are found (the _e_x_t_r_a blank line is not used). This mechanism is intended for insertions in form-letter-like documentation. On UNIX, the _s_t_a_n_d_a_r_d _i_n_p_u_t can be the user's keyboard, a _p_i_p_e, or a _f_i_l_e. 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 .rd _p_r_o_m_p_t - _p_r_o_m_p_t=BELRead insertion from the stan- dard input until two newlines in a row are found. If the standard input is the user's keyboard, _p_r_o_m_p_t (or a BEL) is written onto the user's terminal. rd behaves like a macro, and arguments may be placed after _p_r_o_m_p_t. 9 .ex - - - Exit from NROFF/TROFF. Text pro- cessing is terminated exactly as if all input had ended. 9 If insertions are to be taken from the terminal keyboard _w_h_i_l_e output is being printed on the terminal, the command line option -q will turn off the echoing of keyboard input and prompt only with BEL. The regular input and insertion input _c_a_n_n_o_t simul- taneously come from the standard input. 9 As an example, multiple copies of a form letter may be prepared by entering the insertions for all the copies in one file to be used as the standard input, and causing the file containing the letter to reinvoke itself using nx (19); the process would ulti- mately be ended by an ex in the insertion file. 9 19. Input/Output File Switching 9 The (read-only) number register .c contains the input line number in the current input file. The number register c. is a general register serving the same purpose. 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 .so _f_i_l_e_n_a_m_e - - Switch source file. The top input (file reading) level is switched to _f_i_l_e_n_a_m_e. The effect of an so encountered in a macro occurs immediately. When the new file 9 USD:24-34 NROFF/TROFF User's Manual 9 ends, input is again taken from the original file. so's may be nested. 9 .nx _f_i_l_e_n_a_m_e end-of-file-Next file is _f_i_l_e_n_a_m_e. The current file is considered ended, and the input is immediately switched to _f_i_l_e_n_a_m_e. 9 .pi _p_r_o_g_r_a_m - - Pipe output to _p_r_o_g_r_a_m (NROFF only). This request must occur _b_e_f_o_r_e any printing occurs. No arguments are transmitted to _p_r_o_- _g_r_a_m. 9 20. Miscellaneous 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 9 .mc _c _N - off E,m Specifies that a _m_a_r_g_i_n character _c | appear a distance _N to the right of | the right margin after each non- | empty text line (except those pro- | duced by tl). If the output line is | too-long (as can happen in nofill | mode) the character will be appended | to the line. If _N is not given, the | previous _N is used; the initial _N is | 0.2 inches in NROFF and 1em in | TROFF. The margin character used | with this paragraph was a 12-point | box-rule. | 9 .tm _s_t_r_i_n_g - newline-After skipping initial blanks, _s_t_r_i_n_g (rest of the line) is read in _c_o_p_y _m_o_d_e and written on the user's terminal. (see 21). 9 .ig _y_y - ._y_y=.. - Ignore input lines. ig behaves exactly like de (7) except that the input is discarded. The input is read in _c_o_p_y _m_o_d_e, and any auto- incremented registers will be affected. 9 .pm _t - all - Print macros. The names and sizes of all of the defined macros and strings are printed on the user's terminal; if _t is given, only the total of the sizes is printed. The sizes is given in _b_l_o_c_k_s of 128 characters. 9 .ab _s_t_r_i_n_g - - - Print _s_t_r_i_n_g on standard error and terminate immediately. The default _s_t_r_i_n_g is "User Abort". Does not cause a break. Only output preced- ing the last break is written. 9 9 9 NROFF/TROFF User's Manual USD:24-35 9 .fl - - B Flush output buffer. Used in interactive debugging to force out- put. 9 21. Output and Error Messages. 9 The output from tm, pm, ab and the prompt from rd, as well as various _e_r_r_o_r messages are written onto UNIX's _s_t_a_n_d_a_r_d _e_r_r_o_r output. The latter is different from the _s_t_a_n_d_a_r_d _o_u_t_p_u_t, where NROFF formatted output goes. By default, both are written onto the user's terminal, but they can be independently redirected. 9 Various _e_r_r_o_r conditions may occur during the operation of NROFF and TROFF. Certain less serious errors having only local impact do not cause processing to terminate. Two examples are _w_o_r_d _o_v_e_r_f_l_o_w, caused by a word that is too large to fit into the word buffer (in fill mode), and _l_i_n_e _o_v_e_r_f_l_o_w, caused by an output line that grew too large to fit in the line buffer; in both cases, a message is printed, the offending excess is discarded, and the affected word or line is marked at the point of trunca- tion with a * in NROFF and a <= in TROFF. The philosophy is to continue processing, if possible, on the grounds that output use- ful for debugging may be produced. If a serious error occurs, processing terminates, and an appropriate message is printed. Examples are the inability to create, read, or write files, and the exceeding of certain internal limits that make future output unlikely to be useful. 9 9 USD:24-36 NROFF/TROFF User's Manual 9 9 USD:24-28 NROFF/TROFF User's Manual 9 TUTORIAL EXAMPLES T1. Introduction 9Although NROFF and TROFF have by design a syntax reminiscent of earlier text processors* with the intent of easing their use, it is almost always neces- sary to prepare at least a small set of macro definitions to describe most documents. Such common formatting needs as page margins and footnotes are deliberately not built into NROFF and TROFF. Instead, the macro and string definition, number register, diversion, environment switching, page- position trap, and conditional input mechanisms provide the basis for user-defined imple- mentations. 9The examples to be discussed are intended to be useful and somewhat realistic, but won't necessarily cover all relevant contingencies. Explicit numer- ical parameters are used in the examples to make them easier to read and to illustrate typical values. In many cases, number registers would really be used to reduce the number of places where numerical information is kept, and to concentrate condi- tional parameter initialization like that which depends on whether TROFF or NROFF is being used. 9T2. Page Margins 9As discussed in 3, _h_e_a_d_e_r and __________ 9*For example: P. A. Crisman, Ed., _T_h_e _C_o_m_p_a_t_i_b_l_e _T_i_m_e- _S_h_a_r_i_n_g _S_y_s_t_e_m, MIT Press, 1965, Section AH9.01 (Descrip- tion of RUNOFF program on MIT's CTSS system). 7777777777777777777777777777777777777777777777778 _f_o_o_t_e_r macros are usually defined to describe the top and bottom page margin areas respectively. A trap is planted at page position 0 for the header, and at -_N (_N from the page bottom) for the footer. The simplest such definitions might be 9 .de hd \"define header 'sp 1i .. \"end definition .de fo \"define footer 'bp .. \"end definition .wh 0 hd .wh -1i fo 9 which provide blank 1 inch top and bottom margins. The header will occur on the _f_i_r_s_t page, only if the definition and trap exist prior to the initial pseudo-page transition (3). In fill mode, the output line that springs the footer trap was typically forced out because some part or whole word didn't fit on it. If anything in the footer and header that follows causes a _b_r_e_a_k, that word or part word will be forced out. In this and other examples, requests like bp and sp that normally cause breaks are invoked using the _n_o-_b_r_e_a_k con- trol character ' to avoid this. When the header/footer design contains material requiring independent text processing, the environment may be switched, avoiding most interaction with the running text. 9 A more realistic example would be 9 9 9 9 NROFF/TROFF User's Manual USD:24-29 9 .de hd \"header .if t .tl '\(rn''\(rn' \"troff cut mark .if \\n%>1 \{\ 'sp |0.5i-1\"tl base at 0.5i .tl ''- % -''\"centered page number .ps \"restore size .ft \"restore font .vs \} \"restore vs 'sp |1.0i \"space to 1.0i .ns \"turn on no-space mode .. .de fo \"footer .ps 10 \"set footer/header size .ft R \"set font .vs 12p \"set base-line spacing .if \\n%=1 \{\ 'sp |\\n(.pu-0.5i-1 \"tl base 0.5i up .tl ''- % -'' \} \"first page number 'bp .. .wh 0 hd .wh -1i fo 9 which sets the size, font, and base-line spacing for the header/footer material, and ultimately restores them. The material in this case is a page number at the bottom of the first page and at the top of the remaining pages. If TROFF is used, a _c_u_t _m_a_r_k is drawn in the form of _r_o_o_t-_e_n's at each margin. The sp's refer to absolute positions to avoid dependence on the base-line spacing. Another reason for this in the footer is that the footer is invoked by printing a line whose vertical spacing swept past the trap position by possibly as much as the base- line spacing. The _n_o-_s_p_a_c_e mode is turned on at the end of hd to render ineffective accidental occurrences of sp at the top of the running text. 9 The above method of restoring size, font, etc. presupposes that such requests (that set _p_r_e_v_i_o_u_s value) are _n_o_t used in the running text. A better scheme is save and restore both the current _a_n_d previous values as shown for size in the 7777777777777777777777777777777777777777777777777777777 following: 9 .de fo .nr s1 \\n(.s\"current size .ps .nr s2 \\n(.s\"previous size . --- \"rest of footer .. .de hd . --- \"header stuff .ps \\n(s2\"restore previous size .ps \\n(s1\"restore current size .. 9 Page numbers may be printed in the bottom margin by a separate macro triggered during the footer's page ejection: 9 .de bn \"bottom number .tl ''- % -''\"centered page number .. .wh -0.5i-1v bn \"tl base 0.5i up 99 T3. Paragraphs and Headings 9 The housekeeping associated with starting a new paragraph should be collected in a para- graph macro that, for example, does the desired preparagraph spacing, forces the correct font, size, base-line spacing, and indent, checks that enough space remains for _m_o_r_e _t_h_a_n _o_n_e line, and requests a temporary indent. 9 .de pg \"paragraph .br \"break .ft R \"force font, .ps 10 \"size, .vs 12p \"spacing, .in 0 \"and indent .sp 0.4 \"prespace .ne 1+\\n(.Vu\"want more than 1 line .ti 0.2i \"temp indent .. 9 The first break in pg will force out any previous partial lines, and must occur before the vs. The forcing of font, etc. is partly a defense against prior error and partly to permit things like section heading macros to set parame- ters only once. The prespacing 9 USD:24-30 NROFF/TROFF User's Manual 9 parameter is suitable for TROFF; a larger space, at least as big as the output device vertical resolution, would be more suitable in NROFF. The choice of remaining space to test for in the ne is the smal- lest amount greater than one line (the .V is the available vertical resolution). 9 A macro to automatically number section headings might look like: 9 .de sc \"section . --- \"force font, etc. .sp 0.4 \"prespace .ne 2.4+\\n(.Vu \"want 2.4+ lines .fi \\n+S. .. .nr S 0 1 \"init S 9 The usage is .sc, followed by the section heading text, fol- lowed by .pg. The ne test value includes one line of heading, 0.4 line in the fol- lowing pg, and one line of the paragraph text. A word con- sisting of the next section number and a period is produced to begin the heading line. The format of the number may be set by af (8). 9 Another common form is the labeled, indented paragraph, where the label protrudes left into the indent space. 9 .de lp \"labeled paragraph .pg .in 0.5i \"paragraph indent .ta 0.2i 0.5i\"label, paragraph .ti 0 \t\\$1\t\c\"flow into paragraph .. 9 The intended usage is ".lp _l_a_b_e_l"; _l_a_b_e_l will begin at 0.2inch, and cannot exceed a length of 0.3inch without intruding into the paragraph. The label could be right adjusted against 0.4inch by setting the tabs instead with 7777777777777777777777777777777777777777777777777777777 .ta 0.4iR 0.5i. The last line of lp ends with \c so that it will become a part of the first line of the text that follows. 9 T4. Multiple Column Output 9 The production of multiple column pages requires the footer macro to decide whether it was invoked by other than the last column, so that it will begin a new column rather than produce the bottom margin. The header can initialize a column register that the footer will increment and test. The following is arranged for two columns, but is easily modified for more. 9 .de hd \"header . --- .nr cl 0 1\"init column count .mk \"mark top of text .. .de fo \"footer .ie \\n+(cl<2 \{\ .po +3.4i \"next column; 3.1+0.3 .rt \"back to mark .ns \} \"no-space mode .el \{\ .po \\nMu \"restore left margin . --- 'bp \} .. .ll 3.1i \"column width .nr M \\n(.o\"save left margin 9 Typically a portion of the top of the first page contains full width text; the request for the narrower line length, as well as another .mk would be made where the two column output was to begin. 9 T5. Footnote Processing 9 The footnote mechanism to be described is used by imbedding the footnotes in the input text at the point of reference, demarcated by an initial .fn and a terminal .ef: 9 .fn _F_o_o_t_n_o_t_e _t_e_x_t _a_n_d _c_o_n_t_r_o_l _l_i_n_e_s... 9 9 NROFF/TROFF User's Manual USD:24-31 9 .ef 9 In the following, footnotes are processed in a separate environment and diverted for later printing in the space immediately prior to the bottom margin. There is provision for the case where the last col- lected footnote doesn't com- pletely fit in the available space. 9 .de hd \"header . --- .nr x 0 1 \"init footnote count .nr y 0-\\nb\"current footer place .ch fo -\\nbu\"reset footer trap .if \\n(dn .fz\"leftover footnote .. .de fo \"footer .nr dn 0 \"zero last diversion size .if \\nx \{\ .ev 1 \"expand footnotes in ev1 .nf \"retain vertical size .FN \"footnotes .rm FN \"delete it .if "\\n(.z"fy" .di \"end overflow diversion .nr x 0 \"disable fx .ev \} \"pop environment . --- 'bp .. .de fx \"process footnote overflow .if \\nx .di fy\"divert overflow .. .de fn \"start footnote .da FN \"divert (append) footnote .ev 1 \"in environment 1 .if \\n+x=1 .fs \"if first, include separator .fi \"fill mode .. .de ef \"end footnote .br \"finish output .nr z \\n(.v\"save spacing .ev \"pop ev .di \"end diversion .nr y -\\n(dn\"new footer position, .if \\nx=1 .nr y -(\\n(.v-\\nz) \ \"uncertainty correction .ch fo \\nyu\"y is negative .if (\\n(nl+1v)>(\\n(.p+\\ny) \ .ch fo \\n(nlu+1v \"it didn't fit .. .de fs \"separator \l'1i' \"1 inch rule 7777777777777777777777777777777777777777777777777777777 .br .. .de fz \"get leftover footnote .fn .nf \"retain vertical size .fy \"where fx put it .ef .. .nr b 1.0i\"bottom margin size .wh 0 hd \"header trap .wh 12i fo\"footer trap, temp position .wh -\\nbu fx\"fx at footer position .ch fo -\\nbu\"conceal fx with fo 9 The header hd initializes a footnote count register x, and sets both the current footer trap position register y and the footer trap itself to a nominal position specified in register b. In addition, if the register dn indicates a leftover footnote, fz is invoked to reprocess it. The footnote start macro fn begins a diversion (append) in environment 1, and increments the count x; if the count is one, the footnote separator fs is interpolated. The separator is kept in a separate macro to permit user redefinition. The footnote end macro ef restores the previous environment and ends the diversion after saving the spacing size in register z. y is then decremented by the size of the footnote, available in dn; then on the first foot- note, y is further decremented by the difference in vertical base-line spacings of the two environments, to prevent the late triggering the footer trap from causing the last line of the combined footnotes to over- flow. The footer trap is then set to the lower (on the page) of y or the current page posi- tion (nl) plus one line, to allow for printing the refer- ence line. If indicated by x, the footer fo rereads the foot- notes from FN in nofill mode in environment 1, and deletes FN. 9 9 USD:24-32 NROFF/TROFF User's Manual 9 If the footnotes were too large to fit, the macro fx will be trap-invoked to redivert the overflow into fy, and the register dn will later indicate to the header whether fy is empty. Both fo and fx are planted in the nominal footer trap position in an order that causes fx to be concealed unless the fo trap is moved. The footer then terminates the overflow diversion, if neces- sary, and zeros x to disable fx, because the uncertainty correction together with a not-too-late triggering of the footer can result in the foot- note rereading finishing before reaching the fx trap. 9 A good exercise for the student is to combine the multiple- column and footnote mechanisms. 9 T6. The Last Page 9 After the last input file has ended, NROFF and TROFF invoke the _e_n_d _m_a_c_r_o (7), if any, and when it finishes, eject the remainder of the page. During the eject, any traps encoun- tered are processed normally. At the _e_n_d of this last page, processing terminates _u_n_l_e_s_s a partial line, word, or partial word remains. If it is desired that another page be started, the end-macro 9 .de en \"end-macro \c 'bp .. .em en 9 will deposit a null partial word, and effect another last page. 7777777777777777777777777777777777777777777777777777778 9 9 9 NROFF/TROFF User's Manual USD:24-33 9 79 9 9 USD:24-32 NROFF/TROFF User's Manual 9 Table I Font Style Examples The following fonts are printed in 12-point, with a vertical spacing of 14-point, and with non-alphanumeric characters separated by 1/4em space (all measurements on 8.5 x 11 inch paper prior to photoreduction). This font sample is printed on an APS-5 phototypesetter at University of California, Berkeley. Times Roman 9abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 1234567890 ! $ % & ( ) ` ' * + - . , / : ; = ? [ ] | o+ [] - - _ 1/4 1/2 3/4 fi fl ff ffi ffl 8o9 |- ' c/ 8r9 8c9 _T_i_m_e_s _I_t_a_l_i_c 9_a_b_c_d_e_f_g_h_i_j_k_l_m_n_o_p_q_r_s_t_u_v_w_x_y_z _A_B_C_D_E_F_G_H_I_J_K_L_M_N_O_P_Q_R_S_T_U_V_W_X_Y_Z _1_2_3_4_5_6_7_8_9_0 ! $ % & ( ) ` ' * + - . , / : ; = ? [ ] | o+ [] - - _ 1/4 1/2 3/4 __fi __fl __ff ___ffi ___ffl 8o9 |- ' c/ 8r9 8c9 Times Bold 9abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 1234567890 ! $ % & ( ) ` ' * + - . , / : ; = ? [ ] | o+ [] - - _ 1/4 1/2 3/4 fi fl ff ffi ffl 8o9 |- ' c/ 8r9 8c9 Special Mathematical Font 9" ' \ ^ _ ` ~ / < > { } # @ + - = * A B \ D S Q N O i k L M @ X o J K Y I v U x V C G W T E P R Y F H Z >_ <_ =_ 9~8 =~ =/ -> <- |^ x / +_ U oo ] [ _ ^ |= => <= | O | | | | | | | | | | | | 9 9 9 NROFF/TROFF User's Manual USD:24-33 9 9 NROFF/TROFF User's Manual USD:24-33 9 Table II Input Naming Conventions for ', `, and - and for Non-ASCII Special Characters Non-ASCII characters and _m_i_n_u_s on the standard fonts. _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e ' ' close quote ` ` open quote - \(em 3/4 Em dash - - hyphen or - \(hy hyphen - \- current font minus o+ \(bu bullet [] \(sq square _ \(ru rule 1/4 \(14 1/4 1/2 \(12 1/2 3/4 \(34 3/4 777777777777 fi \(fi fi fl \(fl fl ff \(ff ff ffi \(Fi ffi ffl \(Fl ffl 8o9 \(de degree |- \(dg dagger ' \(fm foot mark c/ \(ct cent sign 8r9 \(rg registered 8c9 \(co copyright 9 Non-ASCII characters and ', `, _, +, -, =, and * on the special font. 9 The ASCII characters @, #, ", ', `, <, >, \, {, }, ~, ^, and _ exist _o_n_l_y on the special font and are printed as a 1-em space if that font is not mounted. The following characters exist only on the special font except for the upper case Greek letter names followed by |- which are mapped into upper case English letters in whatever font is mounted on font position one (default Times Roman). The special math plus, minus, and equals are provided to insulate the appearance of equations from the choice of standard fonts. _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e + \(pl math plus - \(mi math minus = \(eq math equals * \(** math star \(sc section ' \(aa acute accent ` \(ga grave accent _ \(ul underrule / \(sl slash (matching backslash) A \(*a alpha B \(*b beta \ \(*g gamma D \(*d delta S \(*e epsilon Q \(*z zeta 777777777777777 N \(*y eta O \(*h theta i \(*i iota k \(*k kappa L \(*l lambda M \(*m mu @ \(*n nu X \(*c xi o \(*o omicron J \(*p pi K \(*r rho Y \(*s sigma \(ts terminal sigma I \(*t tau v \(*u upsilon 9 9 9 USD:24-34 NROFF/TROFF User's Manual 9 _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e _r U \(*f phi x \(*x chi V \(*q psi C \(*w omega A \(*A Alpha|- B \(*B Beta|- G \(*G Gamma W \(*D Delta E \(*E Epsilon|- Z \(*Z Zeta|- H \(*Y Eta|- T \(*H Theta I \(*I Iota|- K \(*K Kappa|- E \(*L Lambda M \(*M Mu|- N \(*N Nu|- \(*C Xi O \(*O Omicron|- P \(*P Pi P \(*R Rho|- R \(*S Sigma T \(*T Tau|- Y \(*U Upsilon F \(*F Phi X \(*X Chi|- H \(*Q Psi Z \(*W Omega \(sr square root \(rn root en extender >_ \(>= >= <_ \(<= <= =_ \(== identically equal =~ \(~= approx = 9~8 \(ap approximates =/ \(!= not equal -> \(-> right arrow <- \(<- left arrow |^ \(ua up arrow \(da down arrow x \(mu multiply / \(di divide +_ \(+- plus-minus U \(cu cup (union) \(ca cap (intersection) \(sb subset of \(sp superset of \(ib improper subset \(ip improper superset oo \(if infinity ] \(pd partial derivative [ \(gr gradient 7777777777777777777777777777777777777777777777777777 _ \(no not ^ \(is integral sign \(pt proportional to \(es empty set \(mo member of | \(br box vertical rule |= \(dd double dagger => \(rh right hand <= \(lh left hand \(bs Bell System logo (typesetter-dependent) | \(or or O \(ci circle | \(lt left top of big curly bracket | \(lb left bottom | \(rt right top | \(rb right bot | \(lk left center of big curly bracket | \(rk right center of big curly bracket | \(bv bold vertical | \(lf left floor (left bottom of big square bracket) | \(rf right floor (right bottom) | \(lc left ceiling (left top) | \(rc right ceiling (right top) 9 9 9 NROFF/TROFF User's Manual USD:24-35 9 _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e 9 NROFF/TROFF User's Manual USD:24-33 9 Table II Input Naming Conventions for ', `, and - and for Non-ASCII Special Characters Non-ASCII characters and _m_i_n_u_s on the standard fonts. _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e ' ' close quote ` ` open quote - \(em 3/4 Em dash - - hyphen or - \(hy hyphen - \- current font minus o+ \(bu bullet [] \(sq square _ \(ru rule 1/4 \(14 1/4 1/2 \(12 1/2 3/4 \(34 3/4 777777777777 fi \(fi fi fl \(fl fl ff \(ff ff ffi \(Fi ffi ffl \(Fl ffl 8o9 \(de degree |- \(dg dagger ' \(fm foot mark c/ \(ct cent sign 8r9 \(rg registered 8c9 \(co copyright 9 Non-ASCII characters and ', `, _, +, -, =, and * on the special font. 9 The ASCII characters @, #, ", ', `, <, >, \, {, }, ~, ^, and _ exist _o_n_l_y on the special font and are printed as a 1-em space if that font is not mounted. The following characters exist only on the special font except for the upper case Greek letter names followed by |- which are mapped into upper case English letters in whatever font is mounted on font position one (default Times Roman). The special math plus, minus, and equals are provided to insulate the appearance of equations from the choice of standard fonts. _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e + \(pl math plus - \(mi math minus = \(eq math equals * \(** math star \(sc section ' \(aa acute accent ` \(ga grave accent _ \(ul underrule / \(sl slash (matching backslash) A \(*a alpha B \(*b beta \ \(*g gamma D \(*d delta S \(*e epsilon Q \(*z zeta 777777777777777 N \(*y eta O \(*h theta i \(*i iota k \(*k kappa L \(*l lambda M \(*m mu @ \(*n nu X \(*c xi o \(*o omicron J \(*p pi K \(*r rho Y \(*s sigma \(ts terminal sigma I \(*t tau v \(*u upsilon 9 9 9 USD:24-34 NROFF/TROFF User's Manual 9 _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e _r U \(*f phi x \(*x chi V \(*q psi C \(*w omega A \(*A Alpha|- B \(*B Beta|- G \(*G Gamma W \(*D Delta E \(*E Epsilon|- Z \(*Z Zeta|- H \(*Y Eta|- T \(*H Theta I \(*I Iota|- K \(*K Kappa|- E \(*L Lambda M \(*M Mu|- N \(*N Nu|- \(*C Xi O \(*O Omicron|- P \(*P Pi P \(*R Rho|- R \(*S Sigma T \(*T Tau|- Y \(*U Upsilon F \(*F Phi X \(*X Chi|- H \(*Q Psi Z \(*W Omega \(sr square root \(rn root en extender >_ \(>= >= <_ \(<= <= =_ \(== identically equal =~ \(~= approx = 9~8 \(ap approximates =/ \(!= not equal -> \(-> right arrow <- \(<- left arrow |^ \(ua up arrow \(da down arrow x \(mu multiply / \(di divide +_ \(+- plus-minus U \(cu cup (union) \(ca cap (intersection) \(sb subset of \(sp superset of \(ib improper subset \(ip improper superset oo \(if infinity ] \(pd partial derivative [ \(gr gradient 7777777777777777777777777777777777777777777777777777 _ \(no not ^ \(is integral sign \(pt proportional to \(es empty set \(mo member of | \(br box vertical rule |= \(dd double dagger => \(rh right hand <= \(lh left hand \(bs Bell System logo (typesetter-dependent) | \(or or O \(ci circle | \(lt left top of big curly bracket | \(lb left bottom | \(rt right top | \(rb right bot | \(lk left center of big curly bracket | \(rk right center of big curly bracket | \(bv bold vertical | \(lf left floor (left bottom of big square bracket) | \(rf right floor (right bottom) | \(lc left ceiling (left top) | \(rc right ceiling (right top) 9 9 9 NROFF/TROFF User's Manual USD:24-35 9 _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e_N_a_m_e 9