Page 238
DESCRIPTION
This manual page describes the GNU version of troff, which is part of the groff document formatting system. It is highly compatible with UNIX troff. Usually, it should be invoked using the groff command, which will also run preprocessors and postprocessors in the appropriate order and with the appropriate options.
OPTIONS
| _a | Generate an ASCII approximation of the typeset output. |
| _b | Print a backtrace with each warning or error message. This backtrace should help track down the cause of the error. The line numbers given in the backtrace may not always correct: troff's idea of line numbers gets confused by as or am requests. |
| _i | Read the standard input after all the named input files have been processed. |
| _v | Print the version number. |
| _wname |
Enable warning name. Available warnings are described in the "Warnings" subsection as follows. Multiple _w options are allowed. |
| _Wname | Inhibit warning name. Multiple _W options are allowed. |
| _E | Inhibit all error messages. |
| _z | Suppress formatted output. |
| _C | Enable compatibility mode. |
| _dcs, _dname=s | Define c or name to be a string s; c must be a one-letter name. |
| _ffam | Use fam as the default font family. |
| _mname | Read in the file tmac.name. Normally, this will be searched for in /usr/lib/groff/tmac. |
| _R | Don't load troffrc. |
| _nnum | Number the first page num. |
| _olist | Output only pages in list, which is a comma-separated list of page ranges; n means print page n, m_n means print every page between m and n, _n means print every page up to n, n_ means print every page from n. Troff will exit after printing the last page in the list. |
| _rcn, _rname=n | Set number register c or name to n; c must be a one-character name; n can be any troff numeric expression. |
| _Tname | Prepare output for device name, rather than the default ps. |
| _Fdir | Search dir for subdirectories devname (name is the name of the device) for the DESC file and font files before the normal /usr/lib/groff/font. |
| _Mdir | Search directory dir for macro files before the normal /usr/lib/groff/tmac. |
USAGE
Only the features not in UNIX troff are described here.
LONG NAMES
The names of number registers, fonts, strings/macros/diversions, special characters can be of any length. In escape sequences, where you can use (xx for a two-character name, you can use [xxx] for a name of arbitrary length:
| \[xxx] | Print the special character called xxx. |
| \f[xxx] | Set font xxx. |
| \*[xxx] | Interpolate string xxx. |
| \n[xxx] | Interpolate number register xxx. |
A scaled point is equal to 1/sizescale points, where sizescale is specified in the DESC file (1 by default.) There is a new scale indicator z that has the effect of multiplying by sizescale. Requests and escape sequences in troff interpret arguments that represent a point size as being in units of scaled points, but they evaluate each such argument using a default scale indicator
Page 239
of z. Arguments treated in this way are the argument to the ps request, the third argument to the cs request, the second and fourth arguments to the tkf request, the argument to the \H escape sequence, and those variants of the \s escape sequence that take a numeric expression as their argument.
For example, suppose sizescale is 1,000; then a scaled point will be equivalent to a millipoint; the request .ps 10.25 is equivalent to .ps 10.25z, and so sets the point size to 10,250 scaled points, which is equal to 10.25 points.
The number register \n(.s returns the point size in points as decimal fraction. There is also a new number register \n[.ps] that returns the point size in scaled points.
It would make no sense to use the z scale indicator in a numeric expression whose default scale indicator was neither u nor z, and so troff disallows this. Similarly, it would make no sense to use a scaling indicator other than z or u in a numeric expression whose default scale indicator was z, and so troff disallows this as well.
There is also new scale indicator s that multiplies by the number of units in a scaled point. So, for example, \n[.ps]s is equal to 1m. Be sure not to confuse the s and z scale indicators.
NUMERIC ESPRESSIONS
Spaces are permitted in a number expression within parentheses.
M indicates a scale of hundredths of an em.
NEW ESCAPE SEQUENCES
| \A'anything' | This expands to 1 or 0 according to whether anything is or is not acceptable as the name of a string, macro, diversion, number register, environment, or font. It will return 0 if anything is empty. This is useful if you want to look up user input in some sort of associative table. |
| \C'xxx' | Typeset character named xxx. Normally it is more convenient to use \[xxx]. But \C has the advantage that it is compatible with recent versions of UNIX and is available in compatibility mode. |
| \E |
This is equivalent to an escape character, but it's not interpreted in copy mode. For
example, strings to start and end superscripting could be defined like this:
.ds { \v'_.3m'\s'\En[.s]*6u/10u'
.ds { \s0\v'.3m'
|
The use of \E ensures that these definitions will work even if \*f gets interpreted in copy-mode (for example, by being used in a macro argument).
| \N'n' | Typeset the character with code n in the current font. n can be any integer. Most devices only have characters with codes between 0 and 255. If the current font does not contain a character with that code, special fonts will not be searched. The \N escape sequence can be conveniently used on conjunction with the char request: |
| .char \[phone] \f(ZDnN'37' | |
| The code of each character is given in the fourth column in the font description file after the charset command. It is possible to include unnamed characters in the font description file by using a name of —; the \N escape sequence is the only way to use these. | |
| \R'namen' | This has the same effect as .nrnamen |
| \s(nn | Set the point size to nn points; nn must be exactly two digits. |
| \s[n], \s'n' | Set the point size to n scaled points; n is a numeric expression with a default scale indicator of z. |
| \Vx\V(xx \V[xxx] | Interpolate the contents of the environment variable xxx, as returned by getenv(3). \V is interpreted in copy-mode. |
Page 240
| \Yx\Y(xx \Y[xxx] | This is approximately equivalent to \X'\*[xxx]'. However, the contents of the string or macro xxx are not interpreted; also, it is permitted for xxx to have been defined as a macro and thus contain newlines (it is not permitted for the argument to \X to contain newlines). The inclusion of newlines requires an extension to the UNIX troff output format and will confuse drivers that do not know about this extension. |
| \Z'anything' | Print anything and then restore the horizontal and vertical position; anything may not contain tabs or leaders. |
| \$0 | The name by which the current macro was invoked. The als request can make a macro have more than one name. |
| \$* | In a macro, the concatenation of all the arguments separated by spaces. |
| \$@ | In a macro, the concatenation of all the arguments with each surrounded by double quotes, and separated by spaces. |
| \$( nn, \$[ nnn ] | In a macro, this gives the nnth or nnnth argument. Macros can have an unlimited number of arguments. |
| \?anything\? |
When used in a diversion, this will transparently embed
anything in the diversion. anything is read in copy mode. When the diversion is reread,
anything will be interpreted. anything may not
contain newlines; use \! if you want to embed newlines in a diversion. The escape sequence
\? is also recognized in copy mode and turned into a single internal code; it is this code that
terminates anything. Thus
.nr x 1 .nf .di d \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? .di .nr x 2 .di e .d .di .nr x 3 .di f .e .di .nr x 4 .f |
| will print 4. | |
| \/ | This increases the width of the preceding character so that the spacing between that character and the following character will be correct if the following character is a Roman character. For example, if an italic f is immediately followed by a Roman right parenthesis, then in many fonts the top right portion of the f will overlap the top left of the right parenthesis, producing f), which is ugly. Inserting \/ produces and avoids this problem. It is a good idea to use this escape sequence whenever an italic character is immediately followed by a Roman character without any intervening space. |
| \, | This modifies the spacing of the following character so that the spacing between that character and the preceding character will correct if the preceding character is a Roman character. For example, inserting \, between the parenthesis and the f changes to (f. It is a good idea to use this escape sequence whenever a Roman character is immediately followed by an italic character without any intervening space. |
| \) | Like \& except that it behaves like a character declared with the cflags request to be transparent for the purposes of end-of-sentence recognition. |
| \~ | This produces an unbreakable space that stretches like a normal interword space when a line is adjusted. |
| \# | Everything up to and including the next newline is ignored. This is interpreted in copy mode. This is like \% except that \% does not ignore the terminating newline. |
Page 241
NEW REQUESTS
| .alnxxyy | Create an alias xx for number register object named yy. The new name and the old name will be exactly equivalent. If yy is undefined, a warning of type reg will be generated, and the request will be ignored. |
| .alsxxyy | Create an alias xx for request, string, macro, or diversion object named yy. The new name and the old name will be exactly equivalent (it is similar to a hard rather than a soft link). If yy is undefined, a warning of type mac will be generated, and the request will be ignored. The de, am, di, da, ds, and as requests only create a new object if the name of the macro, diversion, or string diversion is currently undefined or if it is defined to be a request; normally, they modify the value of an existing object. |
| .asciifyxx |
This request only exists in order to make it possible to make certain gross hacks work with
GNU troff. It unformats the diversion xx in such a way that ASCII characters that were formatted
and diverted into xx will be treated like ordinary input characters when
xx is reread. For example, this:
.tr @. .di x @nr\n\1 .br .di .tr @@ .asciify x .x |
| will set register n to 1. | |
| .backtrace | Print a backtrace of the input stack on stderr. |
| .break | Break out of a while loop. See also the while and continue requests. Be sure not to confuse this with the br request. |
| .cflagsnc1c2... | Characters c1, c2, ... have properties determined by n, which is ORed from the following. |
| 1 | The character ends sentences. (Initially, characters .?! have this property.) |
| 2 | Lines can be broken before the character (initially, no characters have this property); a line will not be broken at a character with this property unless the characters on each side both have nonzero hyphenation codes. |
| 4 | Lines can be broken after the character (initially, characters _\(hy\(em have this property); a line will not be broken at a character with this property unless the characters on each side both have nonzero hyphenation codes. |
| 8 | The character overlaps horizontally (initially, characters \(ul\(rn\(ru have this property). |
| 16 | The character overlaps vertically (initially, character \(br has this property). |
| 32 | An end-of-sentence character followed by any number of characters with this property will be treated as the end of a sentence if followed by a newline or two spaces; in other words, the character is transparent for the purposes of end-of-sentence recognition; this is the same as having a zero space factor in TeX (initially, characters `)]*\(dg\(rq have this property). |
| .charcstring | Define character c to be string. Every time character c needs to be printed, string will be processed in a temporary environment and the result will be wrapped up into a single object. Compatibility mode will be turned off and the escape character will be set to \ while string is being processed. Any emboldening, constant spacing, or track kerning will be applied to this object rather than to individual characters in string. A character defined by this request can be used just like a normal character provided by the output device. In particular, other characters can be translated to it with the tr request; it can be made the leader character by the lc request; repeated patterns can be drawn with the character by using the \l and \L escape sequences; words containing the character can be hyphenated correctly, if the hcode request is used to give the character a hyphenation code. There is a special antirecursion feature: Use of character within the character's definition will be handled like normal characters not defined with char. A character definition can be removed with the rchar request. |