Troff User's Manual

Point size set to ±N. Alternatively, embed or Any positive 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.

Space-character size (i.e., inter-word gap) is set to N/36 ems. This size is the minimum word spacing in adjusted text. Ignored in nroff.

Constant character space (width) mode is set on for font F (if mounted); the width of every character 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 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 in effect when the characters are physically printed. Ignored in nroff.

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 near 10 points. If N is missing the embolden mode is turned off. The emboldening value N is in the .b register.

This paragraph is printed with .bd R 3. The mode must be in effect when the characters are physically printed. Ignored in nroff.

The characters in the Special font will be emboldened whenever the current font is F. The mode must be in effect when the characters are physically printed. Ignored in nroff.

Font changed to F. Alternatively, embed The font name P is reserved to mean the previous font, and the name for the special font.

Font position. This is a statement that a font named F is associated with position N. It is a fatal error if F is not known. For fonts with names longer than two characters, L refers to the long name, and F becomes a synonym. There is generally a limit of about 10 mounted fonts.

3 Page control

Top and bottom margins are not automatically provided; it is conventional to define two macros and to set traps for them at vertical positions 0 (top) and -N (distance N up from the bottom). See §7 and Tutorial Examples §T2. A pseudo-page transition onto the first page occurs either when the first break occurs or when the first non-diverted 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 current diversion (§7.4) mean that the mechanism being described works during both ordinary and diverted output (the former considered as the top diversion level).

The limitations on troff and nroff output dimensions are device dependent.

Page length set to ±N. The current page length is available in the .p register.

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.

Page number. The next page (when it occurs) will have the page number ±N. A pn must occur before the initial pseudo-page transition to affect the page number of the first page. The current page number is in the % register.

Page offset. The current left margin is set to ±N. The troff initial value provides 1 inch of paper margin on a typical device. The current page offset is available in the .o register.

Need N vertical space. If the distance 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 bottom 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 diversion trap, if any, or is very large.

Mark the current vertical place in an internal register (both associated with the current diversion level), or in register R, if given. See rt request.

Return upward only to a marked vertical place in the current diversion. If ±N (with respect to 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. The sp request (§5.3) may be used instead of rt by spacing to the absolute place stored in a explicit register, e.g., using R ... this also works when the motion is downwards.

4 Text Filling, Adjusting, and Centering

An input text line ending with ., ?, or !, optionally followed by any number of or ¿, is taken to be the end of a sentence, and an additional space character is automatically provided during filling. To prevent this, add to the end of the input line. Multiple inter-word space characters found in the input are retained, except for trailing spaces; initial spaces also cause a break.

When filling is in effect, a \p may be embedded or attached to a word to cause a break at the end of the word and have the resulting output line spread out to fill the current line length.

A text input line that happens to begin with a control character can be made not to look like a control line by prefixing it with 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).

Break. The filling of the line currently being collected is stopped and the line is output without adjustment. Text lines beginning with space characters (but not tabs) and empty text lines (blank lines) also cause a break.

Fill subsequent output lines. The register .u is 1 in fill mode and 0 in nofill mode.

Nofill. Subsequent output lines are neither filled nor adjusted. Input text lines are copied directly to output lines without regard for the current line length.

Line 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 number register contains the current value of the setting; its value can be recorded and used subsequently to set adjustment.

Noadjust. Adjustment is turned off; the right margin will be ragged. The adjustment type for ad is not changed. Output line filling still occurs if fill mode is on.

Center the next N input text lines within the current available horizontal space (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.

5 Vertical Spacing

In and other functions having a pair of delimiters around their parameter, the delimiter choice (here is arbitrary, except that it can not look like the continuation of a number expression for N.

Set vertical baseline spacing size V. Transient extra vertical space is available with \x'N' (see above).

Line spacing set to ±N. N-1 Vs (blank lines) are appended to each output text line. Appended blank lines are omitted, if the text or previous appended blank line reached a trap position.

Space vertically in either direction. If N is negative, the motion is backward (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. (Recall the use of from §1.3.) If the no-space mode is on, no spacing occurs (see ns and rs below).

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 no effect. If this distance is less than N, no vertical space is immediately output, but N is remembered for later output (see os). Subsequent sv requests will overwrite any still remembered N.

Output saved vertical space. No-space mode has no effect. Used to finally output a block of vertical space requested by an earlier sv request.

No-space mode turned on. When on, no-space mode inhibits sp requests and bp requests without a next page number. No-space mode is turned off when a line of output occurs, or with rs.

Restore spacing. The no-space mode is turned off.

Causes a break and output of a blank line exactly like sp 1.

6 Line Length and Indenting

The maximum line length for fill mode may be set with ll. The indent may be set with in; an indent applicable to only the next output line may be set with ti. The line length includes indent space but not 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 three-part titles produced by tl (see §14) is independently set by lt.

Line length is set to ±N.

Indent is set to ±N. The indent is prefixed to each output line.

Temporary indent. The next output text line will be indented a distance ±N with respect to the current indent. The resulting total indent may not be negative. The current indent is not changed.

7 Macros, Strings, Diversion, and Position Traps

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. A macro is invoked in the same way as a request; a control line beginning .xx will interpolate the contents of macro xx. The remainder of the line may contain up to nine arguments.

Strings are created by ds and appended to by as. The strings x and xx are interpolated at any desired point with \*x and \*(xx respectively. String references and macro invocations may be nested.

^* The contents of number registers indicated by \n are interpolated.
^* Strings indicated by \* are interpolated.
^* Arguments indicated by \$ are interpolated.
^* Concealed newlines indicated by \newline are eliminated.
^* Comments indicated by \" are eliminated.
^* \t and \a are interpreted as ASCII horizontal tab and SOH respectively (§9).
^* \\ is interpreted as \.
^* \. is interpreted as ``.''.

When a macro is invoked the input level is pushed down 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 any point within the macro with which interpolates the Nth argument (1<=N<=9). If an invoked argument does not exist, a null string results. For example, the macro xx may be defined by

&de xx	\" begin definition
Today is \\$1 the \\$2.
&.	\" end definition

&xx Monday 14th

Today is Monday the 14th.

No arguments are available at the top (non-macro) level, within a string, or within a trap-invoked macro.

Arguments are copied in copy mode onto a stack where they are available for reference. It is advisable to conceal string references (with an extra \) to delay interpolation until argument reference time.

Diversions may be nested and certain parameters and registers are associated with the current diversion level (the top non-diversion level may be thought of as the 0th diversion level). These are the diversion trap and associated macro, no-space mode, the internally-saved marked place (see mk and rt), the current vertical place (.d register), the current high-water text baseline (.h register), and the current diversion name (.z register).

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 large distance is returned. For a description of input-line-count traps, see it below.

Define or redefine the macro xx. The contents of the macro begin on the next input line. Input lines are copied in copy mode until the definition is terminated by a line beginning with .yy, whereupon the macro yy is called. In the absence of yy, the definition is terminated by a line beginning with ``..''. A macro may contain de requests provided the terminating macros differ or the contained definition terminator is concealed. ``..'' can be concealed as \\.. which will copy as \.. and be reread as ``..''.

Append to macro xx (append version of de).

Define a string xx containing string. Any initial double quote in string is stripped off to permit initial blanks.

Append string to string xx (append version of ds).

Remove request, macro, or string. The name xx is removed from the name list and any related storage space is freed. Subsequent references will have no effect. If many macros and strings are being created dynamically, it may become necessary to remove unused ones to recapture internal storage space for newer registers.

Rename request, macro, or string xx to yy. If yy exists, it is first removed.

Divert output to macro xx. Normal text processing occurs during diversion 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.

Divert, appending to macro xx (append version of di).

Install a trap to invoke xx at page position N; a negative N will be interpreted as a distance from the page bottom. Any macro previously planted at N is replaced by xx. A zero N refers to the top of a page. In the absence of xx, the first trap found at N, if any, is removed.

Change the trap position for macro xx to be N. In the absence of N, the trap, if any, is removed.

Install a diversion trap at position N in the current diversion to invoke macro xx. Another dt will redefine the diversion trap. If no arguments are given, the diversion trap is removed.

Set an input-line-count trap to invoke the macro xx after N lines of text input have been read (control or request lines do not count). The text may be inline text or text interpolated by inline or trap-invoked macros.

The macro xx will be invoked when all input has ended. The effect is almost as if the contents of xx had been at the end of the last file processed, but all processing ceases at the next page eject.

8 Number Registers

A variety of parameters are available to the user as predefined number registers (see Summary, page 0u+7u). In addition, users may define their own registers. Register names are one or two characters long and do not 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, paragraphs, lines, etc. A number register may be used any time numerical input is expected or desired and may be used in numerical expressions (§1.4).

Number registers are created and modified using nr, which specifies 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 xx both contain N and have the auto-increment size M, the following access sequences have the effect shown:

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.

The number register R is assigned the value ±N with respect to the previous value, if any. The increment for auto-incrementing is set to M.

Assign format c to register R. The available formats are:

An arabic format having N digits specifies a field width of N digits (example 2 above). The read-only registers and the width function (§11.2) are always arabic. Warning: the value of a number register in a non-Arabic format is not numeric, and will not produce the expected results in expressions.

The function or returns the format of a number register in a form suitable for it returns nothing if the register has not been used.

Remove number register R. If many registers are being created dynamically, it may become necessary to remove unused registers to recapture internal storage space for newer registers. The register contains the number of number registers still available.

9 Tabs, Leaders, and Fields

Tabs and leaders are not interpreted in copy mode. \t and \a always generate a non-interpreted tab and leader respectively, and are equivalent to actual tabs and leaders in copy mode.

Set tab stops and types. t=R, right adjusting; t=C, centering; t absent, left adjusting. Troff tab stops are preset every 0.5in., nroff every 0.8in. The stop values are separated by spaces, and a value preceded by + is treated as an increment to the previous stop value.

The tab repetition character becomes c, or is removed, thus specifying motion.

The leader repetition character becomes c, or is removed, thus specifying motion.

The field delimiter is set to a; the padding indicator is set to the space character or to b, if given. In the absence of arguments the field mechanism is turned off.

10 Input and Output Conventions and Character Translations

The escape character \ introduces escape sequences, which cause the following character to mean another character, or to indicate some function. A complete list of such sequences is given in the Summary on page 0u+7u. The escape character \ should not be confused with the ASCII control character ESC. The escape character \ 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 used to print whatever the current escape character is. The escape mechanism may be turned off with eo, and restored with ec.

Set escape character to , or to c, if given.

Turn escape mechanism off.

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 automatically invoked. Ligature mode is inhibited for request, macro, string, register, or file names, and in copy mode. No effect in nroff.

Nroff automatically underlines characters in the underline font, specifiable with uf, normally that on font position 2. In addition to ft and the underline font may be selected by ul and cu. Underlining is restricted to an output-device-dependent subset of reasonable characters.

Italicize in troff (underline in nroff) the next N input text lines. Actually, switch to underline font, saving the current font for later restoration; other font changes within the span of a ul will take effect, but the restoration will undo the last change. Output generated by tl (§14) is affected by the font change, but does not decrement N. If N>1, there is the risk that a trap interpolated macro may provide text lines within the span; environment switching can prevent this.

Continuous underline. A variant of ul that causes every character to be underlined in nroff. Identical to ul in troff.

Underline font set to F. In nroff, F may not be on position 1.

The basic control character is set to c, or reset to ``.''.

The no-break control character is set to c, or reset to ``'''.

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.

11 Local Horizontal and Vertical Motions, and the Width Function

The width function also sets three number registers. The registers 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. The value 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 characters with descenders are present.

12 Overstrike, Bracket, Line-drawing, Graphics, and Zero-width Functions

\b'\(lc\(lf'E\b'\(rc\(rf'\x'-0.5m'\x'0.5m'

&de us
\\$1\l'|0\(ul'
&&

&de bx
\(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul'
&&

&ul "underlined words"

&bx "words in a box"

The function \L'Nc' draws 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 the current baseline. A positive N specifies a line drawn downward and a negative N specifies a line drawn upward. After the line is drawn no compensating motions are made; the instantaneous baseline is at the end of the line.

The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The zero-width box-rule and the ½-em wide under-rule were designed to form corners when using 1-em vertical spacings. For example the macro

.de eb
.sp -1	\"compensate for next automatic baseline spacing
.nf	\"avoid possibly overflowing word buffer
\h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(ul'
.fi
..

h'-.5n'L'|0+1u-1'
L'-|0+1u+1'

D'l dh dv'	draw line from current position by dh, dv
D'c d'	draw circle of diameter d with left side at current position
D'e d1d2'	draw ellipse of diameters d1 and d2
D'a dh1 dv1 dh2 dv2'	draw arc from current position to dh1+dh2, dv1+dv2,
	   with center at dh1, dv1 from current position
D'~ dh1dv1dh2dv2...'	draw B-spline from current position by dh1,dv1,
	   then by dh2,dv2, then by dh2,dv2, then ...

Numbers taken as horizontal (first, third, etc.) have default scaling of ems; vertical numbers (second, fourth, etc.) have default scaling of Vs (§1.3). The position after a graphical object has been drawn is at its end; for circles and ellipses, the ``end'' is at the right side.

13 Hyphenation.

Automatic hyphenation may be switched off and on. When switched on with hy, several variants may be set. A hyphenation indicator character may be embedded in a word to specify desired hyphenation points, or may be prefixed to suppress hyphenation. In addition, the user may specify a small list of exception words.

Only words that consist of a central alphabetic string surrounded by (usually null) non-alphabetic strings are candidates for automatic hyphenation. Words that contain hyphens (minus), em-dashes (\(em), or hyphenation indicator characters are always subject to splitting after those characters, whether automatic hyphenation is on or off.

Automatic hyphenation is turned off.

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 characters respectively of a word are not split off. These values are additive; i.e., N=14 will invoke all three restrictions.

Hyphenation indicator character is set to c or to the default . The indicator does not appear in the output.

Specify hyphenation points in words with embedded minus signs. Versions of a word with terminal s are implied; i.e., implies This list is examined initially and after each suffix stripping. The space available is small.

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

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 (initially %) is found within any of the fields it is replaced by the current page number in the format assigned to register %. Any character may be used in place of as the string delimiter.

The page number character is set to c, or removed. The page number register remains %.

Length of title is set to ±N. The line length and the title length are independent. Indents do not apply to titles; page offsets do.

15 Output Line Numbering.

Automatic sequence numbering of output lines may be requested with nm. When in effect, a three-digit, arabic number plus a digit-space is prefixed 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 desired to keep the right margin aligned with an earlier margin. Blank lines, other vertical spaces, and lines generated by tl are not numbered. Numbering can be temporarily 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 can be specified that only those line numbers that are multiples of some number M are to be printed (the others will appear as blank number fields).

Line number mode. If ±N is given, line numbering is turned on, and the next output line numbered is numbered ±N. Default values are M=1, S=1, and I=0. Parameters corresponding to missing arguments are unaffected; a non-numeric argument 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.

The next N text output lines are not numbered.

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

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

If condition c true, accept anything as input; in multi-line case use \{anything\}.

If condition c false, accept anything.

If expression N > 0, accept anything.

If expression N <= 0 [sic], accept anything.

If string1 identical to string2, accept anything.

If string1 not identical to string2, accept anything.

If portion of if-else; all of the forms for if above are valid.

Else portion of if-else.

The built-in condition names are:

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 %'''

&ie \n%>1 \{\
'	sp 0.5i
&	tl 'Page %'''
'	sp |1.2i \}
&el .sp |2.5i

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

Environment switched to environment 0<=N<=2. Switching is done in push-down fashion so that restoring a previous environment must be done with .ev rather than specific reference. Note that what is pushed down and restored is the environment number, not its contents.

18 Insertions from the Standard Input

The input can be temporarily switched to the system standard input with rd, which will switch back when two consecutive newlines are found (the extra blank line is not used). This mechanism is intended for insertions in form-letter-like documentation. The standard input can be the user's keyboard, a pipe, or a file.

Read insertion from the standard input until two newlines in a row are found. If the standard input is the user's keyboard, prompt (or a BEL) is written onto the standard output. rd behaves like a macro, and arguments may be placed after prompt.

Exit from nroff/troff. Text processing is terminated exactly as if all input had ended.

If insertions are to be taken from the terminal keyboard while 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 cannot simultaneously come from the standard input.

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 with nx (§19); the process would ultimately be ended by an ex in the insertion file.

19 Input/Output File Switching

Switch source file. The top input (file reading) level is switched to filename. When the new file ends, input is again taken from the original file. so's may be nested.

Next file is filename. The current file is considered ended, and the input is immediately switched to filename.

Execute program from string, which is the rest of the input line. The output is not collected automatically. The number register which contains the process id of the troff process, may be useful in generating unique filenames for output.

Pipe output to string, which is the rest of the input line. This request must occur before any printing occurs; typically it is the first line of input.

Copy contents of file filename to output, completely unprocessed. The file is assumed to contain something meaningful to subsequent processes.

20 Miscellaneous
that a margin character c appear a distance N to the right of the right margin after each non-empty text line (except those produced 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 1 em in troff. The margin character used with this paragraph was a 12-point box-rule.

After skipping initial blanks, string (rest of the line) is read in copy mode and written on the standard error.

After skipping initial blanks, string (rest of the line) is read in copy mode and written on the standard error. Troff or nroff then exit.

Ignore input lines. ig behaves exactly like de (§7) except that the input is discarded. The input is read in copy mode, and any auto-incremented registers will be affected.

Set line number to N and filename to filename for purposes of subsequent error messages, etc. The number register [sic] contains the name of the current input file, as set by command line argument, or The number register contains the number of input lines read from the current file, again perhaps as modified by

Print macros. The names and sizes of all of the defined macros and strings are printed on the standard error; if t is given, only the total of the sizes is printed. The sizes is given in blocks of 128 characters.

Flush output buffer. Force output, including any pending position information.

21 Output and Error Messages.

The output from tm, pm, and the prompt from rd, as well as various error messages, are written onto the standard error. The latter is different from the standard output, where formatted text goes. By default, both are written onto the user's terminal, but they can be independently redirected.

Various error 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 word overflow, caused by a word that is too large to fit into the word buffer (in fill mode), and line overflow, 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 truncation with a * in nroff and a <= in troff. Processing continues if possible, on the grounds that output useful for debugging may be produced. If a serious error occurs, processing terminates, and a message is printed, along with a list of the macro names currently active. Examples of serious errors include the inability to create, read, or write files, and the exceeding of certain internal limits that make future output unlikely to be useful.

22 Output Language

Troff produces its output in a language that is independent of any specific output device, except that the numbers in it have been computed on the basis of the resolution of the device, and the sizes, fonts, and characters that that device can print. Nevertheless it is quite possible to interpret that output on a different device, within the latter's capabilities.

sn	set point size to n
fn	set font to n
cc	print character c
Cname	print the character called name; terminate name by white space
Nn	print character n on current font
Hn	go to absolute horizontal position n (n>=0)
Vn	go to absolute vertical position n (n>=0, down is positive)
hn	go n units horizontally; n<0 is to the left
vn	go n units vertically; n<0 is up
nnc	move right nn, then print UTF character c;  nn must be exactly 2 digits
pn	new page n begins­set vertical position to 0
nb a	end of line (information only­no action);  b = space before line, a = after
w	paddable word space (information only­no action)
Dc ...0graphics function c; see below
x ...0device control functions; see below
# ...0comment

The device control and graphics commands are intended as open-ended families, to be expanded as needed. The graphics functions coincide directly with the sequences:

Dl dh dv	draw line from current position by dh, dv
Dc d	draw circle of diameter d with left side here
De dh1 dv2	draw ellipse of diameters dh1 and dv2
Da dh1 dv1 dh2 dv2	draw arc from current position to dh1+dh2, dv1+dv2,
		   center at dh1, dv1 from current position
D~ dh1 dv1 dh2 dv2 ...	draw B-spline from current position to dh1, dv1,
		   then to dh2, dv2, then to ...
Dz dh1 dv1 dh2 dv2 ...	for any other z is uninterpreted

The device control functions begin with then a command, then other parameters.

x T s	name of typesetter is s
x r n h v	resolution is n units/inch;
		h = minimum horizontal motion, v = minimum vertical
x i	initialize
x f n s	mount font s on font position n
x p	pause­can restart
x s	stop­done forever
x t	generate trailer information, if any
x H n	set character height to n
x S n	set slant to n
x X any	generated by the \X function
x any	to be ignored if not recognized

The commands and must occur first; fonts must be mounted before they can be used; comes last. There are no other order requirements.

The following is the output from for a typical printer, as described in §23:

x T utf
x res 720 1 1
x init
V0
p1

x font 1 R
x font 2 I
x font 3 B
x font 4 BI
x font 5 CW
x font 6 H
x font 7 HB
x font 8 HX
x font 9 S1
x font 10 S

s10
f1
H0
s10
f1
V0
H720
V120
ch
50e44l28l28o50,w58w72o50r33l28dn120 0
x trailer
V7920
x stop

Troff output is normally not redundant; size and font changes and position information are not included unless needed. Nevertheless, each page is self-contained, for the benefit of postprocessors that re-order pages or process only a subset.

23 Device and Font Description Files

The parameters that describe a output device name are read from the directory each time troff is invoked. The device name is provided by default, by the environment variable or by a command-line argument The default device name is for UTFencoded Unicode characters. The pre-defined string contains the name of the device. The command-line option may be used to change the default directory.

fonts n F1 F2 ... Fn
sizes s1 s2 ...0
res n
hor n
vert n
unitwidth n
charset
list of multi-character character names (optional)

Character widths for each font are assumed to be given in machine units at point size (In other words, a character with a width of n is n units wide at size All widths are integers at all sizes.

A list of valid character names may be introduced by the list of names is optional.

A line whose first non-blank character is is a comment. Except that must occur last, parameters may appear in any order.

Here is a subset of the file for a typical Postscript printer:

# Description file for Postscript printers.

fonts 10 R I B BI CW H HB HX S1 S
sizes 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
   24 25 26 27 28 29 30 31 32 33 34 35 36 38 40 44 48 54 60 72 0
res 720
hor 1
vert 1
unitwidth 10
charset
hy ct fi fl ff Fi Fl dg em 14 34 12 en aa
ga ru sc dd -> br Sl ps cs cy as os =. ld
rd le ge pp -+ ob vr
sq bx ci fa te ** pl mi eq ~= *A *B *X *D
*E *F *G *Y *I *K *L *M *N *O *P *R *H *S *T *U *W
*C *Q *Z ul rn *a *b *x *d *e *f *g *y *i *k
*l *m *n *o *p *h *r *s *t *u *w *c *q *z

name str	name of font is str
ligatures . . . 0	list of ligatures
spacewidth n	width of a space on this font
special	this is a special font
charset
list of character name, width, ascender/descender, code, tab separated

Each line following describes one character: its name, its width in units as described above, ascender/descender information, and a decimal, octal or hexadecimal value by which the output device knows it (the ``number'' of the character). The character name is arbitrary, except that signifies an unnamed character. If the width field contains the name is a synonym for the previous character. The ascender/descender field is 1 if the character has a descender (hangs below the baseline, like is 2 if it has an ascender (is tall, like is 3 if both, and is 0 if neither. The value is returned in the register, as computed by the function (§11.2).

Here are excerpts from a typical font description file for the same Postscript printer.

hy	33	0	45	hyphen \(hy
-	"			- is a synonym for \(hy

 

Q	72	3	81

 

a	44	0	97
b	50	2	98
c	44	0	99
d	50	2	100
y	50	1	121

 

em	100	0	208
---	44	2	220	Pound symbol £, \N'220'
---	36	0	221	centered dot \N'221'

Introduction

It is almost always necessary to prepare at least a small set of macro definitions to describe a document. 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 implementations.

For most uses, a standard package like or is the right choice. The next stage is to augment that, or to selectively replace macros from the standard package. The last stage, much harder, is to write one's own from scratch. This is not a task for the novice.

The examples discussed here are intended to be useful and somewhat realistic, but will not necessarily cover all relevant contingencies. Explicit numerical parameters are used in the examples to make them easier to read and to illustrate typical values. In many cases, number registers would be used to reduce the number of places where numerical information is kept, and to concentrate conditional parameter initialization like that which depends on whether troff or nroff is being used.

Page Margins

As discussed in §3, header and footer 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

&de hd	\"define header
'sp 1i
&&	\"end definition
&de fo	\"define footer
'bp
&&	\"end definition
&wh 0 hd
&wh -1i fo

A more realistic example would be

&de hd	\"header
&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 baseline 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

This method of restoring size, font, etc., presupposes that such requests (that set previous value) are not used in the running text. A better scheme is to save and restore both the current and previous values as shown for size in the following:

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

&de bn	\"bottom number
&tl ''- % -''	\"centered page number
&&
&wh -0.5i-1v bn	 \"tl base 0.5i up

Paragraphs and Headings

The housekeeping associated with starting a new paragraph should be collected in a paragraph macro that, for example, does the desired preparagraph spacing, forces the correct font, size, baseline spacing, and indent, checks that enough space remains for more than one line, and requests a temporary indent.

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

A macro to automatically number section headings might look like:

&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

Another common form is the labeled, indented paragraph, where the label protrudes left into the indent space.

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

Multiple Column Output

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.

&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

Footnotes

The footnote mechanism to be described is used by embedding the footnotes in the input text at the point of reference, demarcated by an initial .fn and a terminal .ef:

&fn
Footnote text and control lines...
&ef

&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 di
&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 1st, 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	 \"didn't fit
&&

&de fs	\"separator
\l'1i'	\"1 inch rule
&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 pos
&wh -\\nbu fx	\"fx at footer position
&ch fo -\\nbu	\"conceal fx with fo

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 footnote, y is further decremented by the difference in vertical baseline spacings of the two environments, to prevent the late triggering of the footer trap from causing the last line of the combined footnotes to overflow. The footer trap is then set to the lower (on the page) of y or the current page position (nl) plus one line, to allow for printing the reference line.

If indicated by x, the footer fo rereads the footnotes from FN in nofill mode in environment 1, and deletes FN. 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 necessary, and zeros x to disable fx, because the uncertainty correction together with a not-too-late triggering of the footer can result in the footnote rereading finishing before reaching the fx trap.

A good exercise for the student is to combine the multiple-column and footnote mechanisms.

The Last Page

After the last input file has ended, nroff and troff invoke the end macro (§7), if any, and when it finishes, eject the remainder of the page. During the eject, any traps encountered are processed normally. At the end of this last page, processing terminates unless a partial line, word, or partial word remains. If it is desired that another page be started, the end-macro

&de en	\"end-macro
\c
'bp
&&
&em en

The following table lists names for a set of characters, most of which have traditionally been provided by troff using the `special' or `symbol' font. Many of these sequences are old ways to get what are now Unicode characters; Lucida Sans, for example, has glyphs corresponding to many of these but does not have the special sequences. Therefore the troff sequence gives the character ¿ from the Times font instead of the character ¿ from the current font, in this case Lucida Sans. Not all sequences print on any particular device, including this one; Peter faces appear in their place.