NROFF/TROFF User's Manual USD:24-3 SUMMARY OF REQUESTS AND OUTLINE OF THIS MANUAL Request Initial If No Form Value* Argument Notes#Explanation 1. General Explanation 2. Font and Character Size Control .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 FNM 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, xx, or 1-4. Also \fx,\f(xx,\fN. .fp N F R,I,B,S ignored - Font named F mounted on physical position 10. NROFF/TROFF User's Manual USD:24-5 Request Initial If No Form Value Argument NotesExplanation .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 abcd.... none - O Translate a to b, etc. on output. 11. Local Horizontal and Vertical Motions, and the Width Func- tion 12. Overstrike, Bracket, Line-drawing, and Zero-width Functions 13. Hyphenation. .nh hyphenate - E No hyphenation. .hy N hyphenate hyphenateEHyphenate; N = mode. .hc c \% \% E Hyphenation indicator character c. .hw word1 ... ignored-Exception words. 14. Three Part Titles. .tl 'left'center'right' - - Three part title. .pc c % off - Page number character. .lt _N 6.5in previous E,mLength of title. 15. Output Line Numbering. .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. 16. Conditional Acceptance of Input .if c anything - - If condition c true, accept anything as input, for multi-line use \{anything\}. .if !c anything - - If condition c false, accept any- thing. .if N anything - u If expression N > 0, accept any- thing. .if !N anything - u If expression N < 0, accept any- thing. .if 'string1'string2' anything -If string1 identical to string2, accept anything. .if !'string1'string2' anything-If string1 not identical to string2, accept anything. .ie c anything - u If portion of if-else; all above forms (like if). .el anything - - Else portion of if-else. 17. Environment Switching. .ev N N=0 previous - Environment switched (push down). USD:24-6 NROFF/TROFF User's Manual Request Initial If No Form Value Argument NotesExplanation 18. Insertions from the Standard Input .rd prompt - prompt=BELRead insertion. .ex - - - Exit from NROFF/TROFF. 19. Input/Output File Switching .so filename - - Switch source file (push down). .nx filename end-of-file-Next file. .pi program - - Pipe output to program (NROFF only). 20. Miscellaneous .mc c N - off E,m Set margin character c and separa- tion N. .tm string - newline-Print string on terminal (UNIX standard error output). .ig yy - .yy=.. - Ignore till call of yy. .pm t - all - Print macro names and sizes; if t present, print only total of sizes. .ab string - - - Print a message and abort. .fl - - B Flush output buffer. 21. Output and Error Messages _________________________________________________________________ Notes- 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 ignored. Alphabetical Request and Section Number Cross Reference a20 c10 di7 e18 h13 l10 ne3 os5 r18 ss2 u10 ad4 c10 ds7 fc9 h13 l10 nf4 p14 rm7 sv5 u10 af8 ce4 dt7 fi4 i16 ll6 n13 p19 rn7 ta9 vs5 am7 ch7 e10 f20 i16 ls5 n15 pl3 rr8 tc9 wh7 as7 cs2 e16 fp2 i20 l14 n15 p20 rs5 ti6 bd2 c10 em7 ft2 in6 m20 nr8 pn3 rt3 t14 bp3 da7 e10 fz2 it7 mk3 ns5 po3 s19 t20 br4 de7 e17 h13 lc9 na4 n19 ps2 sp5 t10 NROFF/TROFF User's Manual USD:24-7 Escape Sequences for Characters, Indicators, and Functions Section Escape Reference Sequence Meaning 10.1 \\ \ (to prevent or delay the interpretation of \) 10.1 \e Printable version of the current escape character. 2.1 \' ' (acute accent); equivalent to \(aa 2.1 \` ` (grave accent); equivalent to \(ga 2.1 \- - Minus sign in the current 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 (->) 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. All 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. The absolute position 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 diversion (f7.4) to the vertical place N. For all other requests and functions, |N becomes the distance from the current horizontal place on the input line to the horizontal place N. For example, .sp |3.2c will space in the required direction to 3.2 centimeters from the top of the page. 22.4.Numerical expressions. 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 initial + or - is stripped and interpreted as an increment or decrement indicator respectively. In the presence of default scaling, the desired scale indicator must be attached to every 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 .ll (4.25i+\nxP+3)/2u will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 points. 22.5.Notation. 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 not an increment indicator, but merely the sign of N. Gen- erally, unreasonable numerical input is either ignored or trun- cated to a reasonable value. For example, most requests expect to set parameters to non-negative values; exceptions are sp, wh, ch, nr, and if. The requests ps, ft, po, vs, ls, ll, in, and lt restore the previous parameter value in the absence of an argu- ment. USD:24-10 NROFF/TROFF User's Manual 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. 23. Font and Character Size Control 23.1.Character set. 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 \(xx where xx is a two-character name given in the Appendix Table II. The three ASCII exceptions are mapped as follows: ____________________________________________________ | ASCII Input | Printed by TROFF | |Character Name | Character Name | |_________________________|_________________________| | ' acute accent | ' close quote | | ` grave accent | ` open quote | |_________________________|_________________________| 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. 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. 23.2.Fonts. 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 current 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 \fx, \f(xx, or \fN where x and xx are the name of a mounted font and N is a numerical font position. It is not 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 ignored. 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. NROFF understands font control and normally underlines Italic characters (see f10.5). NROFF/TROFF User's Manual USD:24-11 23.3.Character size. 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 \sN at the desired point to set the size to N, or a \s_N (11, there is the risk that a trap interpolated macro may provide text lines within the span; environment switching can prevent this. USD:24-26 NROFF/TROFF User's Manual .cu N off N=1 E A variant of ul that causes every character to be underlined in NROFF. Identical to ul in TROFF. .uf F Italic Italic - Underline font set to F. In NROFF, F may not be on position 1 (ini- tially Times Roman). 31.4.Control characters. Both the control character . and the no-break 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. Request Initial If No Form Value Argument NotesExplanation .cc c . . E The basic control character is set to c, or reset to ".". .c2 c ' ' E The nobreak control character is set to c, or reset to "'". 31.5.Output translation. 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). Request Initial If No Form Value Argument NotesExplanation .tr abcd.... 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 input to output time. 31.6.Transparent throughput. An input line beginning with a \! is read in copy mode and transparently 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. 31.7.Comments and concealed newlines. 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 always ignored-except in a comment. Comments may be imbedded at the end 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 .\". NROFF/TROFF User's Manual USD:24-27 32. Local Horizontal and Vertical Motions, and the Width Func- tion 32.1.Local Motions. The functions \v'N' and \h'N' can be used for local vertical and horizontal motion respectively. The dis- tance N may be negative; the positive directions are rightward and downward. A local motion is one contained within a line. To avoid unexpected vertical dislocations, it is necessary that the net 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. __________________________________________________________________________________________ | Vertical | Effect in ||Horizontal | Effect in | |_____________|___________________________||____________|_________________________________| | | || | | |_____________|___________________________|| \h'N' |Move distance N | | | | || \(space) |Unpaddable space-size space | | \u |1/2 em up |1/2 line up ||____________|_________________________________| | \d |1/2 em down |1/2 line down || | | | | \r |1 em up |1 line up || \| |1/6 em space |ignored | | | | || \^ |1/12 em space |ignored | |_____________|____________|______________||____________|___________________|_____________| 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. 32.2.Width Function. The width function \w'string' generates the numerical width of string (in basic units). Size and font changes may be safely imbedded in string, 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. ". The width function also sets three number registers. The regis- ters st and sb are set respectively to the highest and lowest extent of string relative to the baseline; then, for example, the total height 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 string 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. 32.3.Mark horizontal place. The escape sequence \kx will cause the current horizontal position in the input line to be stored in register x. As an example, the construction \kxword\h'|\nxu+2u'word will embolden word by backing up to almost its beginning and overprinting it, resulting in word. 33. Overstrike, Bracket, Line-drawing, and Zero-width Functions 33.1.Overstriking. Automatically centered overstriking of up to nine characters is provided by the overstrike function \o'string'. The characters in string are overprinted with USD:24-28 NROFF/TROFF User's Manual centers aligned; the total width is that of the widest character. string should not contain local vertical motion. As examples, \o'e\'' produces ', and \o'\(mo\(sl' produces /. 33.2.Zero-width characters. The function \zc will output c without spacing over it, and can be used to produce left-aligned overstruck combinations. As examples, \z\(ci\(pl will produce +, and \(br\z\(rn\(ul\(br will produce the smallest possible con- structed box |_|. 33.3.Large Brackets. The Special Mathematical Font contains a number of bracket construction pieces ((())|||||||) that can be combined into various bracket styles. The function \b'string' may be used to pile up vertically the characters in string (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 |E|. | | 33.4.Line drawing. The function \l'Nc' 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 before 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 less 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 .de us \\$1\l'|0\(ul' .. or one to draw a box around a string .de bx \(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul' .. such that .us "underlined words" and .bx "words in a box" yield ________________ and ________________. The function \L'Nc' 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 box rule | (\(br); the other suitable character is the bold vertical | (\(bv). The line is begun without any initial motion relative to NROFF/TROFF User's Manual USD:24-29 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 no compensating motions are made; the instantaneous b__________________________________________________________________ |he horizontal and vertical line drawing functions may be used in | |ombination to produce large boxes. The zero-width box-rule and | |he 1/2-em wide underrule were designed to form corners when | |sing 1-em vertical spacings. For example the macro | | | | .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 | | .. | |ill draw a box around some text whose beginning vertical place | |as saved in number register a (e. g. using .mk a) as done for | ____________________________________________________________________ 34. Hyphenation. The automatic hyphenation may be switched off and on. When switched on with hy, several variants may be set. A hyphenation indicator 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. 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 always subject to splitting after those characters, whether or not automatic hyphenation is on or off. Request Initial If No Form Value Argument NotesExplanation .nh hyphenate - E Automatic hyphenation is turned off. .hyN on,N=1 on,N=1 E Automatic hyphenation is turned on for N>1, or off for N=0. If N=2, last 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. .hc c \% \% E Hyphenation indicator character is set to c or to the default \%. The indicator does not appear in the output. .hw word1 ... ignored-Specify hyphenation points in words with imbedded minus signs. USD:24-30 NROFF/TROFF User's Manual Versions of a word with terminal s are implied; i. e. dig-it implies dig-its. This list is examined ini- tially and after each suffix strip- ping. The space available is small-about 128 characters. 35. Three Part Titles. 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. Request Initial If No Form Value Argument NotesExplanation .tl 'left'center'right' - - The strings left, center, and right 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. .pc c % off - The page number character is set to c, or removed. The page-number register remains %. .lt _N 6.5in previous E,mLength of title set to _N. The line-length and the title-length are independent. Indents do not apply to titles; page-offsets do. 36. Output Line Numbering. 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 not 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). NROFF/TROFF User's Manual USD:24-31 Request Initial If No Form Value Argument NotesExplanation .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. .nn N - N=1 E The next N text output lines are not numbered. 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. 37. Conditional Acceptance of Input In the following, c is a one-character, built-in condition name, ! signifies not, N is a numerical expression, string1 and string2 are strings delimited by any non-blank, non-numeric character not in the strings, and anything represents what is conditionally accepted. Request Initial If No Form Value Argument NotesExplanation .if c anything - - If condition c true, accept anything as input; in multi-line case use \{anything\}. .if !c anything - - If condition c false, accept any- thing. .if N anything - u If expression N > 0, accept any- thing. .if !N anything - u If expression N < 0, accept any- thing. .if 'string1'string2' anything -If string1 identical to string2, accept anything. .if !'string1'string2' anything-If string1 not identical to string2, accept anything. .ie c anything - u If portion of if-else; all above forms (like if). USD:24-32 NROFF/TROFF User's Manual .el anything - - Else portion of if-else. The built-in condition names are: ________________________________________ |Condition | | |__________|____________________________| | o |Current page number is odd | | e |Current page number is even | | t |Formatter is TROFF | | n |Formatter is NROFF | |__________|____________________________| If the condition c is true, or if the number N is greater than zero, or if the strings compare identically (including motions and character size and font), anything is accepted as input. If a ! precedes the condition, number, or string comparison, the sense of the acceptance is reversed. Any spaces between the condition and the beginning of anything are skipped over. The anything 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 \}. 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. Some examples are: .if e .tl 'Even Page %''' which outputs a title if the page number is even; and .ie \n%>1 \{\ 'sp 0.5i .tl 'Page %''' 'sp |1.2i \} .el .sp |2.5i which treats page 1 differently from other pages. 38. Environment Switching. A number of the parameters that control the text processing are gathered together into an environment, which can be switched by the user. The environment parameters are those associated with requests noting E in their Notes 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. NROFF/TROFF User's Manual USD:24-33 Request Initial If No Form Value Argument NotesExplanation .ev N N=0 previous - Environment switched to environ- ment 0