COHERENT manpages
This page displays the COHERENT manpage for nroff [Text-formatting language].
List of available manpages
Index
nroff -- Command Text-formatting language nroff [option ...] [file ...] nroff is the COHERENT text-formatter and text-formatting language. By embedding commands within files of text, you can instruct nroff to format text, create paragraphs, subheadings, headers, footers, and in general perform all tasks required to format text for the printed page or for screen display. nroff is designed to be used with character-display terminals or monospace printers. The related program troff performs typeset-quality formatting, suitable for printing on the Hewlett-Packard LaserJet printer or any printer for which the PostScript language has been implemented. troff's formatting language is a superset of that used by nroff. Text that you have encoded for formatting by nroff will work with troff, but the reverse is not always true. See the Lexicon entry on troff for information that applies to troff alone. nroff Input nroff processes each file, or the standard input if none is specified, and prints the formatted result on the standard output. The input must contain formatting instructions as well as the text to be processed. Basic nroff commands provide for such things as setting line length, page length, and page offset, generating vertical and horizontal motions, indentation, filling and adjusting output lines, and centering. The great flexibility of nroff lies in its acceptance of user-defined macros to control almost all formatting. For example, the formation of paragraphs, header and footer areas, and footnotes must all be implemented by the user via macros. The following summarizes the commands and options that can be used with nroff. Four types of commands and options are described: (1) command line options; (2) nroff's basic commands (also called primitives); (3) escape sequences that can be used with nroff; and (4) nroff's dedicated number registers, and what information each one keeps. Command-line Options Command-line options may be listed in any order on the command line. They are as follows: -d Debug: print each request before execution. This options is extremely useful when you are writing new macros. -f name Write the temporary file in file name. -k Keep: do not erase the temporary file. -i Read from the standard input after reading the given files. -mname Include the macro file /usr/lib/tmac.name in the input stream. -nN Number the first page of output N. -raN Set number register a to the value N. -rabN Set number register ab to value N. For obvious reasons, ab cannot contain a digit. -v Return the number of your version. -x Do not eject to the bottom of the last page when text ends. Use this option when you wish to use nroff interactively. It, too, is useful when debugging macros. nroff appends the contents of the environmental variable NROFF to the beginning of the list of command-line arguments. This let you set commonly used options once in the environment, rather than retype them for each invocation of nroff. Primitives The following gives the basic commands, or primitives, that are built into nroff. These primitives can be assembled into macros, or can be written directly into the text of your document. Commands may begin either with a period `.' or with an apostrophe; the former causes a break (see .br, below), the latter does not. .ab msg Abort: print msg on the standard error and abort processing. .ad [bclr] Enter adjust mode: that is, insert white space between words to create right-justified output. b adjusts for both margins; this is the default. c adjusts and centers on the line. l adjusts, flush with the left margin. r adjusts, flush with the right margin. .af R X Assign format X to number register R. The assigned format may be one of the following: 1 Arabic numerals (default) i Lower-case Roman numerals I Upper-case Roman numerals a Lower-case alphabetic characters A Upper-case alphabetic characters .am XX Append the following to macro XX. Used like .de, below. .as XX Append the following to string XX. Used like .ds, below. .bp Begin a new page. .br Break; print any fraction of a line of text that is in the input buffer before reading new text. .c2 c Set the no-break control character to c. With no argument, reset it to the default character, which is the apostrophe. .cc c Set the normal control character to c. With no argument, reset it to the default character, which is the period. .ce N Center N lines of text (default, one). .ch XX N Change the location of the trap for macro XX to vertical position N on the page. Used like command .wh, below. .co endmark Copy input directly to the output until endmark is seen. If no endmark is given, copy until another .co is seen. .cu N Underline the next N lines. When used without an argument, one line is underlined. The instruction .cu 0 turns off underlining. Note that unlike the UNIX version of nroff, .cu does not perform continuous underlining -- it underlines words, but not spaces. .da X Divert and append the following text into macro X. A diversion is ended by a .da command that has no argument. .de X Define macro X. The macro definition is ended by a line that contains only two periods ``..''. .di X Divert the following text into macro X. Diversion is ended by a .di command that has no argument. .ds X value Define string X to have the given value. .ec c Set the escape characer to c. With no argument, reset it to the default backslash character `\'. .el action Execute action when the test in an .ie command fails. This command must be used with an .ie command. .em XX Execute macro XX when processing is completed. .eo Escape off: turn off special handling of all escape sequences. .ev N Change the environment. When followed by 0, 1, 2, the command pushes that environment; when used without an argument, the command pops the present environment and returns to the previous environment. .ex Exit from nroff without further ado. .fi Enter fill mode. .fl Flush; same as .br. .ft X Change the current font to X. nroff recognizes R, B, and I, for Roman, bold, and italic, respectively. .ie condition action This command tests to see if condition is true; if true, it then executes action; otherwise, it performs the action introduced by an .el primitive. This command must be used with the .el command. .if condition action This command tests to see if condition is true; if so, then action is executed; otherwise, action is ignored. The command .if o applies if the page number is odd, and the command .if e applies if the page number is even. The command .if n applies if the text is processed by nroff, and the command .if t applies if the text is processed by troff. The command .if l applies in landscape mode. The command .if p applies to troff PostScript mode. Note that the last two conditions are unique to the COHERENT implementation of nroff, and may not be portable to other implementations. .ig X Ignore all input until macro .X is called; if no argument is given, ignore input until two periods ``..''. .in NX Change the normal indentation to N units of X scale. X can be u or i, for machine units or inches, respectively. If N is used without X, nroff assumes the indentation to be given in number of character- widths (in picas, or tenths of an inch). Default indentation is zero. .it N XX Set an input trap to execute macro XX after N input lines (not counting request lines). .lc c Set the leader dot character to c. When nroff sees the escape sequence \a, it fills space to the next tab stop with the leader dot character. lc with no argument tells nroff to use spaces to fill leaders. .ll NX Set the line length. Used like the .in command, above. .ls X Leave spaces; insert X vertical spaces after each line of text. Default is zero. .lt NX Length of title. Used like the .in command, above. .na Enter no-adjust mode. Line lengths are not changed. .ne NX Confirm that at least N portions of X units of measure of vertical space are needed before the next trap. If this amount of space is not available, then move the text to the top of the next page. X can be i or v, for inches or vertical spaces, respectively. This command is used in display macros and in paragraph macros to help prevent widows and orphans. .nf Enter no-fill mode; no right justification is performed, although line lengths are changed to approximate uniform line length. .nh Turn off hyphenation. nroff hyphenates according to built-in algorithms that are correct most of the time, but not always. .nr X N1 N2 Set number register X to value N1; set its default increment/decrement to N2. For example, .nr X 2 3 sets number register X to 2, and sets its default increment to 3. The basic unit of measurement for nroff 1/120th of an inch; this is also called the machine unit. It is indicated by the suffix u to a measurement. Unless otherwise stated, all number registers that information about a page holds that information in nroff machine units. Other units of measure convert into nroff units as follows: inch: 1i = 120u vertical line space: 1v = 20u centimeter: 1c = 47u em: 1m = 12u en: 1n = 12u pica: 1P = 20u point: 1p = 1u .ns No-space mode. .nx file Terminate processing of the current input file and begin processing file instead. .pl NX Set the page length to N. The unit of measure X can be V or i, for vertical spaces (sixths of an inch) or inches, respectively. The default unit of measure is vertical spaces. .pn N Set the page number to N. .po NX Set the default page offset to N. The unit of measure X can be set to i, for inches. The default unit of measure is number of characters. .rb file Read binary: read the given file and copy it directly to the output without processing. .rd prompt Read an insertion from the standard input after issuing the given prompt. .rf XX YY Rename font XX as YY. For example, to have calls to font K remapped to Roman font, use the call: .rf K R .rm XX Remove macro or string XX. .rn XX YY Change the name of a macro or string from XX to YY. .rr X Remove register X. .rs Restore normal space mode. .so file Open file, read its contents, and process them. When the end of file is reached, resume processing the contents of the present file. .sp [|]NX Space down N. The unit of measure X can be i, for inches, with the default unit of measure being vertical spaces, or sixths of an inch. The optional vertical bar `|' indicates that N is an absolute value; for example, .sp |1.5i means to move to 1.5 inches below the top of the page, whereas .sp 1.5i means to move to 1.5 inches below the present position. .sy command Execute command under the shell. Please note that this primitive is non-standard. Macros that use it cannot be formatted under standard AT&T nroff. .ta NX ... Set the tab to N. The unit of measure X can be set to i, for inches; the default unit of measure is number of characters, or tenths of an inch. A tab setting, of course, is for an absolute, not a relative, value. If more than one tab setting is defined, the first defines the first tabulation character on a text line, the second defines the second tabulation character, etc. Any undefined tabulations are thrown away. .tc X N Fill any unused space within a tabulation field with the character X. If the optional N is present, it specifies a width for the character; for example, .tc . .1i fills tabs with dots spaced one-tenth of an inch apart. .ti NX Temporary indent; indent only the next line. Used like the .in command, above. .tl 'left'center'right' Set a three-part title, with left being set flush left, center being centered on the line, and right being set flush right. Note the use of the apostrophes to separate the fields; the apostrophes for an undefined field must still be present, or a syntax error will be generated. .tm message Print message on the standard error device. This is often used with .if or .ie commands to indicate an error condition. .tr xy Translate character x to y on output. .ul N This behaves the same as .cu. .vs Np Reset the normal vertical spacing to N points p. One point equals 1/72 of an inch. The default setting one pica, which equals is 12 points or 1/6 of an inch. .wh NX action Set a trap to perform action when point N is reached on every formatted page. If N is negative, it is measured up from the bottom of the page. The unit of measure X may be i or v, for inches or number of vertical lines, respectively; the default unit of measure is v. Escape Sequences The following lists nroff's escape sequences, or commands that suspend or work around the normal operation of nroff. Each escape sequences is introduced by the escape character, normally the backslash character `\': \(xx Print special character xx, as defined by a .dc request. nroff reads default special character definitions from file /usr/lib/roff/nroff/specials.r. For example, the escape sequence \(<= prints the less-than-or-equal-to symbol <=. \. Print a literal period. \' Print a literal apostrophe. This should be used in text that will be manipulated by the \w escape sequence or the .tl primitive. \\ Delay interpretation of a backslash character. This normally is used to defer the interpretation of a macro or string from the time it is processed to the time that it is called. \- Print a minus sign. \& Ignore what is normally a command string. \$N Call macro argument N. \'' Introduce a comment within your text. All text to the right of this escape sequence will be ignored by nroff. This sequence must read .\'' when used at the beginning of a line. \*S Call string S. \*(ST Call string ST. \a Fill the space to the next tab stop with leader dots (normally `.'). \d Move down by one-half em (troff) or one-half line (nroff). Normally used to do crude subscripting, or to undo the effect of the \u escape sequence. \e Print the escape character in the output text -- normally, a backslash. \fX Set font to X; this can be either R, I, B, or P, for Roman, italic, bold, or previous font, respectively. \h'[|]NX' Move horizontally by N units of X. If N is positive, move to the right; if negative, move to the left. The unit of measure X may be i, for inches; the default unit of measure is ems. (One em equals one pica, which is one-sixth of an inch). When the optional vertical bar `|' is used, move to an absolute position on the line. For example \h'|1.5i' moves to 1.5 inches to the right of the left margin, whereas \h'1.5i' moves 1.5 inches to the right of the current position. \kx Record the current vertical position into register x. \l'NX' Draw a horizontal line N units of X long. The unit of measure X may be i, for inches; the default unit of measure is character-widths. \L'NX' Draw a vertical line; used like \l, above. \nX Read the value of number register X. \n(XY Read the value of number register XY. \o'chars' Overstrike the given chars, centered on the widest. \sN Change the current size of the type to N points. \s+N Increment the current point size by N points. \s-N Decrement the current point size by N points. \t Print a tab. \u Move up by one-half em (troff) or one-half line (nroff). Normally used to do crude superscripting, or to reverse the effect of the \d escape sequence. \v'NX' Vertical motion; move N units of X vertically. If N is positive, move down; if negative, move up. The unit of measure X may be i or v, for inches or vertical spaces (sixths of an inch), respectively. The default unit of measure is v. \w'argument' Measure the width of argument. For example \w'stuff and nonsense' measures the width of the phrase stuff and nonsense; or \w'\$1' measures the width of the first argument passed to a macro, whatever that argument might happen to be. Therefore, the command .in \w'\$1' will indent a line by the width of argument 1. \Xdd Output the character with hexadecimal value dd, where dd are two hexadecimal digits. Users can use this option to encode characters that are not part of the English-language character set. The hexadecimal values to which characters map depend upon the character set that you (or your printer) use. Please note nroff reserves the following values for its internal use: <Ctrl-SP> X00Ignored <Ctrl-A> X01 Leader dots, same as ``\a'' <Ctrl-I> X09 Tab, same as ``\t'' <Ctrl-J> X10 Newline This escape sequence is unique to the COHERENT implementation of nroff and troff. Code that uses it will behave differently when ported to other implementations. \zc Print character c with zero width. \<newline> Ignore this <newline> character. \{ Begin conditional commands; used after an .if, an .ie, or an .el command. \{\ Begin conditional commands, and ignore the following carriage return. \} End conditional commands. Dedicated Number Registers The following lists the number registers that are predefined in nroff. You can read or reset these registers to suit the need of any special formats that you wish to devise. $$ Process identifier of the current nroff process. This usually is used with the primitive .sy to name temporary files. .$ Number of arguments passed to a macro. % Present page number. .c Number of lines read from the current input file. This can be used to help set an input-line trap. .d Current vertical position in the current diversion. If no diversion is opened, this register's contents equal those of the nl register, described below. dl Maximum width of last completed diversion. dn Height of last completed diversion. dw Day of the week (one through seven; one indicates Sunday). dy Day of the month, as set by COHERENT. .F Name of input file being read. This is very useful for printing error messages. This register applies only the COHERENT implementation of nroff. Code that uses it is not portable to other implementations. .h Vertical position of the current line's base-line. This number register gives you the best idea of your current vertical position on the page. hp Horizontal position on current input line. .i Present amount of indentation. .j Current type and mode of text adjustment. .l Present line length. ln Current line number in the output. mo Month, as set by COHERENT. .n Width of the text portion of the previously printed line. Useful for underlining, shading, or otherwise modifying the previous line of text. For example \l'\n(.nu' draws a line under the previously printed line of text. nl Vertical position of the base-line of the last printed line of text. .o Present page offset. .p Page length. .s Size of the type currently being printed, in points. sb Depth to which a string hangs below its base line. This is generated by the width function. st Height to which a string extends above its base line. This is generated by the width function. .t Distance to the next trap. Check this register to see if the object you wish to print on a page will fit. .v Size of a line, in points. This is set by the vs primitive. yr Last two digits of the year, as set by COHERENT. .z Name of the current diversion. Printer Configuration nroff reads several files in directory /usr/lib/roff/nroff to find printer- specific information. It reads special character definitions from file specials.r. If file fonts.r exists, nroff reads font information from it; nroff understands only Roman, bold and italic fonts, but .rf requests may define alternative font names. If file .pre exists, nroff copies it at the beginning of the output. If file .post exists, nroff copies it at the end of the output. In landscape mode, nroff looks for files .pre_land and .post_land instead. You can change these files as desired to include printer-specific commands in nroff output. Miscellaneous The -ms macro package is kept in file /usr/lib/tmac.s. The macros in this package are more than sufficient for most ordinary text processing. Beginners should work through this macro package rather than trying to deal at once with the basic program. The tutorial to nroff, which is included with this manual, provides a detailed introduction to nroff. Error messages for nroff appear in the appendix to this manual. Files /tmp/rof* -- Temporary files /usr/lib/tmac.* -- Standard macro packages /usr/lib/roff/nroff/ -- Support files directory /usr/lib/roff/nroff/.pre -- Output prefix /usr/lib/roff/nroff/.pre_land -- Output prefix, landscape mode /usr/lib/roff/nroff/.post -- Output suffix /usr/lib/roff/nroff/.post_land -- Output suffix, landscape mode /usr/lib/roff/nroff/fonts.r -- Alternative font name definitions /usr/lib/roff/nroff/specials.r -- Special character definitions See Also col, commands, deroff, man, ms, printer, troff nroff, The Text-Formatting Language, tutorial Diagnostics nroff returns the following error messages. Most are self-explanatory. -f option requires file argument (fatal) .bd not implemented yet .co: unexpected EOF before string (error) .dt not implemented yet .el without .ie (error) .fc not implemented yet .hc not implemented yet .hw not implemented yet .hy not implemented yet .ie nested more than N levels (error) The .ie/.el combination can be nested only 15 levels deep. .ie without matching .el (error) Every .ie must be followed by an .el. .lf: string, file ``string'' (error) troff could not load a font-width table from file string. .lf: ``string'' is not a PCL font width table (error) troff expects a PCL font-width table, but file string is not in the PCL font-width format. .lf: ``string'' is not a PostScript font width table (error) troff expects a PostScript font-width table, but file string is not in the PostScript font-width format. .lf: cannot load more than N fonts (error) troff has a static limit on the number of font-width tables that can be loaded at one time. .lf: cannot open file ``string'' (error) .lf: requires fontname and filename (error) .nm not implemented yet .nn not implemented yet .pi not implemented yet .rb: cannot open file string (error) .rb: no file specified (error) .rf: requires name and new name (error) \} without matching \{ (error) Every \} must be preceded by a \{. arguments too long (error) attempted zero divide (error) attempted zero modulus (error) bad adjustment type (error) bad argument reference (error) bad directive N (fatal) bad font N (fatal) bad font N at dev_font, nfonts=N (fatal) bad font N, nfonts=N (fatal) bad pattern (fatal) bad tab stop (error) bad tab stop (error) botch: fontname(N) (fatal) nroff cannot handle font N and must abort processing. botch: swdmul=N psz=N swddiv=N (fatal) An undefined error has occurred within nroff. The printed numbers give the value of nroff's internal registers. If such an error occurs regularly when you process a given piece of text, please send the text in question and a copy of the error message to Mark Williams technical support. bracket building not implemented yet cannot create temp file (fatal) cannot dehyphenate (fatal) cannot end diversion (error) You attempted to close a diversion without first opening one. cannot find current file (error) cannot find font XX (error) Font XX has not been opened; therefore [nt]roff cannot use it. To open a font, use the load-font primitive .lf. cannot find font N (error) cannot find register string (error) You attempted to read a number register without first loading a value into it. cannot open string (error) cannot open file ``string'' (error) cannot pop environment (error) You popped an environment without first pushing one. cannot read environment (fatal) cannot remove string (error) cannot reopen temp file (fatal) cannot write environment (fatal) delimiter argument too large (error) diversion buffer odd alignment (fatal) environment does not exist (error) environments stacked too deeply (error) field with too large (error) file ``string'' not found (error) flushd -- current diversion null (fatal) font position out of range (error) fonts.r not found (fatal) nroff and troff read the list of fonts to use from a file named fonts.r. If you do not have such a file in your current directory, nroff and troff read the one out of their home directories: /usr/lib/roff/nroff, /usr/lib/roff/troff_pcl, or /usr/lib/roff/troff_ps, depending which variety of output you have requested. This error message means that your current directory does not hold a file named fonts.r, and that [nt]roff cannot open the fonts.r file in its appropriate home directory. illegal hex digit (error) The escape sequence \XNN prints a character by its literal hexadecimal value. This should be used when processing characters that are not normally printable on the terminal screen. Digit N can be the numerals `0' through `9', the letters `a' through `f', or the letters `A' through `F'. All other characters will trigger this error. illegal option: string (fatal) incomplete macro in trap (fatal) A trap has jumped to a macro, but that macro does not terminate, for whatever reason. Usually this indicates that you have opened a diversion but failed to close it. line buffer overflow (fatal) no room for new font name XX (error) out of space - memory string (fatal) request 'string' not found (error) section N of title too large (error) special character XX not found (error) syntax error (error) This message any number of errors with your nroff source. Check the line number given in the message. temporary file write error (fatal) nroff cannot write a temporary file, for whatever reason. This usually indicates that you lack permission to write into the directory into which nroff is attempt to write its temporary files. too many tab stops (error) nroff allows a maximum of nine tab stops in one line. It ignores all tab stops that exceed that limit. unexpected end of file (fatal) This error indicates that nroff is in the middle of processing a macro when the file ends. This error usually occurs when you open a diversion and fail to close it. unknown macro/register type N (fatal) vertical line drawing not implemented yet (error) word buffer overflow (fatal)