addftinfo(1) General Commands Manual addftinfo(1) Name addftinfo - add font metrics to troff fonts for use with groff Synopsis addftinfo [-asc-height n] [-body-depth n] [-body-height n] [-cap-height n] [-comma-depth n] [-desc-depth n] [-fig-height n] [-x-height n] resolution unit‐width font addftinfo --help addftinfo -v addftinfo --version Description addftinfo reads an AT&T troff font description file font, adds addi‐ tional font metric information required by GNU troff(1), and writes the combined result to the standard output. The information added is de‐ rived from the font’s existing parameters and assumptions about tradi‐ tional troff names for characters. Among the font metrics added are the heights and depths of characters (how far each extends vertically above and below the baseline). The resolution and unit‐width arguments should be the same as the corresponding parameters in the DESC file. font is the name of the file describing the font; if font ends with “I”, the font is assumed to be oblique (or italic). Options --help displays a usage message, while -v and --version show version information; all exit afterward. All other options change parameters that are used to derive the heights and depths. Like the existing quantities in the font description file, each value n is in scaled points, inches/resolution for a font whose type size is unit‐width; see groff_font(5). -asc-height n height of characters with ascenders, such as “b”, “d”, or “l” -body-depth n depth of characters such as parentheses -body-height n height of characters such as parentheses -cap-height n height of uppercase letters such as “A” -comma-depth n depth of a comma -desc-depth n depth of characters with descenders, such as “p”, “q”, or “y” -fig-height height of figures (numerals) -x-height n height of lowercase letters without ascenders such as “x” addftinfo makes no attempt to use the specified parameters to infer un‐ specified parameters. If a parameter is not specified, the default will be used. The defaults are chosen to produce reasonable values for a Times font. See also groff_font(5), groff(1), groff_char(7) groff 1.23.0 29 August 2023 addftinfo(1) ─────────────────────────────────────────────────────────────────────────────── afmtodit(1) General Commands Manual afmtodit(1) Name afmtodit - adapt Adobe Font Metrics files for groff PostScript and PDF output Synopsis afmtodit [-ckmnsx] [-a slant] [-d device‐description‐file] [-e encoding‐file] [-f internal‐name] [-i italic‐correction‐ factor] [-o output‐file] [-w space‐width] afm‐file map‐file font‐description‐file afmtodit --help afmtodit -v afmtodit --version Description afmtodit adapts an Adobe Font Metric file, afm‐file, for use with the ps and pdf output devices of troff(1). map‐file associates a groff or‐ dinary or special character name with a PostScript glyph name. Output is written in groff_font(5) format to font‐description‐file, a file named for the intended groff font name (but see the -o option). map‐file should contain a sequence of lines of the form ps‐glyph groff‐char where ps‐glyph is the PostScript glyph name and groff‐char is a groff ordinary (if of unit length) or special (if longer) character identi‐ fier. The same ps‐glyph can occur multiple times in the file; each groff‐char must occur at most once. Lines starting with “#” and blank lines are ignored. If the file isn’t found in the current directory, it is sought in the devps/generate subdirectory of the default font di‐ rectory. If a PostScript glyph is not mentioned in map‐file, and a groff charac‐ ter name can’t be deduced using the Adobe Glyph List (AGL, built into afmtodit), then afmtodit puts the PostScript glyph into the groff font description file as an unnamed glyph which can only be accessed by the “\N” escape sequence in a roff document. In particular, this is true for glyph variants named in the form “foo.bar”; all glyph names con‐ taining one or more periods are mapped to unnamed entities. Unless -e is specified, the encoding defined in the AFM file (i.e., entries with non‐negative codes) is used. Refer to section “Using Symbols” in Groff: The GNU Implementation of troff, the groff Texinfo manual, or groff_char(7), which describe how groff character identifiers are con‐ structed. Glyphs not encoded in the AFM file (i.e., entries indexed as “-1”) are still available in groff; they get glyph index values greater than 255 (or greater than the biggest code used in the AFM file in the unlikely case that it is greater than 255) in the groff font description file. Unencoded glyph indices don’t have a specific order; it is best to ac‐ cess them only via special character identifiers. If the font file proper (not just its metrics) is available, listing it in the files /usr/local/share/groff/1.23.0/font/devps/download and /usr/local/share/groff/1.23.0/font/devpdf/download enables it to be em‐ bedded in the output produced by grops(1) and gropdf(1), respectively. If the -i option is used, afmtodit automatically generates an italic correction, a left italic correction, and a subscript correction for each glyph (the significance of these is explained in groff_font(5)); they can be specified for individual glyphs by adding to the afm‐file lines of the form: italicCorrection ps‐glyph n leftItalicCorrection ps‐glyph n subscriptCorrection ps‐glyph n where ps‐glyph is the PostScript glyph name, and n is the desired value of the corresponding parameter in thousandths of an em. Such parame‐ ters are normally needed only for italic (or oblique) fonts. The -s option should be given if the font is “special”, meaning that groff should search it whenever a glyph is not found in the current font. In that case, font‐description‐file should be listed as an argu‐ ment to the fonts directive in the output device’s DESC file; if it is not special, there is no need to do so, since troff(1) will automati‐ cally mount it when it is first used. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -a slant Use slant as the slant (“angle”) parameter in the font descrip‐ tion file; this is used by groff in the positioning of accents. By default afmtodit uses the negative of the ItalicAngle speci‐ fied in the AFM file; with true italic fonts it is sometimes de‐ sirable to use a slant that is less than this. If you find that an italic font places accents over base glyphs too far to the right, use -a to give it a smaller slant. -c Include comments in the font description file identifying the PostScript font. -d device‐description‐file The device description file is desc‐file rather than the default DESC. If not found in the current directory, the devps subdi‐ rectory of the default font directory is searched (this is true for both the default device description file and a file given with option -d). -e encoding‐file The PostScript font should be reencoded to use the encoding de‐ scribed in enc‐file. The format of enc‐file is described in grops(1). If not found in the current directory, the devps sub‐ directory of the default font directory is searched. -f internal‐name The internal name of the groff font is set to name. -i italic‐correction‐factor Generate an italic correction for each glyph so that its width plus its italic correction is equal to italic‐correction‐factor thousandths of an em plus the amount by which the right edge of the glyph’s bounding box is to the right of its origin. If this would result in a negative italic correction, use a zero italic correction instead. Also generate a subscript correction equal to the product of the tangent of the slant of the font and four fifths of the x‐height of the font. If this would result in a subscript correction greater than the italic correction, use a subscript correction equal to the italic correction instead. Also generate a left italic correction for each glyph equal to italic‐correction‐factor thousandths of an em plus the amount by which the left edge of the glyph’s bounding box is to the left of its origin. The left italic correction may be negative un‐ less option -m is given. This option is normally needed only with italic (or oblique) fonts. The font description files distributed with groff were created using an option of -i50 for italic fonts. -o output‐file Write to output‐file instead of font‐description‐file. -k Omit any kerning data from the groff font; use only for mono‐ spaced (constant‐width) fonts. -m Prevent negative left italic correction values. Font descrip‐ tion files for roman styles distributed with groff were created with “-i0 -m” to improve spacing with eqn(1). -n Don’t output a ligatures command for this font; use with mono‐ spaced (constant‐width) fonts. -s Add the special directive to the font description file. -w space‐width Use space‐width as the with of inter‐word spaces. -x Don’t use the built‐in Adobe Glyph List. Files /usr/local/share/groff/1.23.0/font/devps/DESC describes the ps output device. /usr/local/share/groff/1.23.0/font/devps/F describes the font known as F on device ps. /usr/local/share/groff/1.23.0/font/devps/download lists fonts available for embedding within the PostScript docu‐ ment (or download to the device). /usr/local/share/groff/1.23.0/font/devps/generate/dingbats.map /usr/local/share/groff/1.23.0/font/devps/generate/dingbats-reversed.map /usr/local/share/groff/1.23.0/font/devps/generate/slanted-symbol.map /usr/local/share/groff/1.23.0/font/devps/generate/symbol.map /usr/local/share/groff/1.23.0/font/devps/generate/text.map map names in the Adobe Glyph List to groff special character identifiers for Zapf Dingbats (ZD), reversed Zapf Dingbats (ZDR), slanted symbol (SS), symbol (S), and text fonts, respec‐ tively. These map‐files are used to produce the font descrip‐ tion files provided with groff for the grops output driver. Diagnostics AGL name 'x' already mapped to groff name 'y'; ignoring AGL name 'uniXXXX' You can disregard these if they’re in the form shown, where the ignored AGL name contains four hexadecimal digits XXXX. The Adobe Glyph List (AGL) has its own names for glyphs; they are often different from groff’s special character names. afmtodit is constructing a mapping from groff special character names to AGL names; this can be a one‐to‐one or many‐to‐one mapping, but one‐to‐many will not work, so afmtodit discards the excess map‐ pings. For example, if x is *D, y is Delta, and z is uni0394, afmtodit is telling you that the groff font description that it is writing cannot map the groff special character \[*D] to AGL glyphs Delta and uni0394 at the same time. If you get a message like this but are unhappy with which map‐ ping is ignored, a remedy is to craft an alternative map‐file and re‐run afmtodit using it. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. Section “Using Symbols” may be of particular note. You can browse it interactively with “info '(groff)Using Symbols'”. groff(1), gropdf(1), grops(1), groff_font(5) groff 1.23.0 29 August 2023 afmtodit(1) ─────────────────────────────────────────────────────────────────────────────── chem(1) General Commands Manual chem(1) Name chem - embed chemical structure diagrams in groff documents Synopsis chem [--] [file ...] chem -h chem --help chem -v chem --version Description chem produces chemical structure diagrams. Today’s version is best suited for organic chemistry (bonds, rings). The chem program is a groff preprocessor like eqn, pic, tbl, etc. It generates pic output such that all chem parts are translated into diagrams of the pic lan‐ guage. If no operands are given, or if file is “-”, chem reads the standard input stream. -h and --help display a usage message, whereas -v and --version display version information; all exit. The program chem originates from the Perl source file chem.pl. It tells pic to include a copy of the macro file chem.pic. Moreover the groff source file pic.tmac is loaded. In a style reminiscent of eqn and pic, the chem diagrams are written in a special language. A set of chem lines looks like this .cstart chem data .cend Lines containing the keywords .cstart and .cend start and end the input for chem, respectively. In pic context, i.e., after the call of .PS, chem input can optionally be started by the line begin chem and ended by the line with the single word end instead. Anything outside these initialization lines is copied through without modification; all data between the initialization lines is converted into pic commands to draw the diagram. As an example, .cstart CH3 bond CH3 .cend prints two CH3 groups with a bond between them. If you want to create just groff output, you must run chem followed by groff with the option -p for the activation of pic: chem [file ...] | groff -p ... Language The chem input language is rather small. It provides rings of several styles and a way to glue them together as desired, bonds of several styles, moieties (e.g., C, NH3, ..., and strings. Setting variables There are some variables that can be set by commands. Such commands have two possible forms, either variable value or variable = value This sets the given variable to the argument value. If more arguments are given only the last argument is taken, all other arguments are ig‐ nored. There are only a few variables to be set by these commands: textht arg Set the height of the text to arg; default is 0.16. cwid arg Set the character width to arg; default is 0.12. db arg Set the bond length to arg; default is 0.2. size arg Scale the diagram to make it look plausible at point size arg; default is 10 point. Bonds This bond [direction] [length n] [from Name|picstuff] draws a single bond in direction from nearest corner of Name. bond can also be double bond, front bond, back bond, etc. (We will get back to Name soon.) direction is the angle in degrees (0 up, positive clockwise) or a di‐ rection word like up, down, sw (= southwest), etc. If no direction is specified, the bond goes in the current direction (usually that of the last bond). Normally the bond begins at the last object placed; this can be changed by naming a from place. For instance, to make a simple alkyl chain: CH3 bond (this one goes right from the CH3) C (at the right end of the bond) double bond up (from the C) O (at the end of the double bond) bond right from C CH3 A length in inches may be specified to override the default length. Other pic commands can be tacked on to the end of a bond command, to created dotted or dashed bonds or to specify a to place. Rings There are lots of rings, but only five‐ and six‐sided rings get much support. ring by itself is a six‐sided ring; benzene is the benzene ring with a circle inside. aromatic puts a circle into any kind of ring. ring [pointing (up|right|left|down)] [aromatic] [put Mol at n] [double i,j k,l ... [picstuff] The vertices of a ring are numbered 1, 2, ... from the vertex that points in the natural compass direction. So for a hexagonal ring with the point at the top, the top vertex is 1, while if the ring has a point at the east side, that is vertex 1. This is expressed as R1: ring pointing up R2: ring pointing right The ring vertices are named .V1, ..., .Vn, with .V1 in the pointing di‐ rection. So the corners of R1 are R1.V1 (the top), R1.V2, R1.V3, R1.V4 (the bottom), etc., whereas for R2, R2.V1 is the rightmost vertex and R2.V4 the leftmost. These vertex names are used for connecting bonds or other rings. For example, R1: benzene pointing right R2: benzene pointing right with .V6 at R1.V2 creates two benzene rings connected along a side. Interior double bonds are specified as double n1,n2 n3,n4 ...; each number pair adds an interior bond. So the alternate form of a benzene ring is ring double 1,2 3,4 5,6 Heterocycles (rings with something other than carbon at a vertex) are written as put X at V, as in R: ring put N at 1 put O at 2 In this heterocycle, R.N and R.O become synonyms for R.V1 and R.V2. There are two five‐sided rings. ring5 is pentagonal with a side that matches the six‐sided ring; it has four natural directions. A flatring is a five‐sided ring created by chopping one corner of a six‐sided ring so that it exactly matches the six‐sided rings. The description of a ring has to fit on a single line. Moieties and strings A moiety is a string of characters beginning with a capital letter, such as N(C2H5)2. Numbers are converted to subscripts (unless they ap‐ pear to be fractional values, as in N2.5H). The name of a moiety is determined from the moiety after special characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52. Moieties can be specified in two kinds. Normally a moiety is placed right after the last thing mentioned, separated by a semicolon sur‐ rounded by spaces, e.g., B1: bond ; OH Here the moiety is OH; it is set after a bond. As the second kind a moiety can be positioned as the first word in a pic‐like command, e.g., CH3 at C + (0.5,0.5) Here the moiety is CH3. It is placed at a position relative to C, a moiety used earlier in the chemical structure. So moiety names can be specified as chem positions everywhere in the chem code. Beneath their printing moieties are names for places. The moiety BP is special. It is not printed but just serves as a mark to be referred to in later chem commands. For example, bond ; BP sets a mark at the end of the bond. This can be used then for specify‐ ing a place. The name BP is derived from branch point (i.e., line crossing). A string within double quotes " is interpreted as a part of a chem com‐ mand. It represents a string that should be printed (without the quotes). Text within quotes "..." is treated more or less like a moi‐ ety except that no changes are made to the quoted part. Names In the alkyl chain above, notice that the carbon atom C was used both to draw something and as the name for a place. A moiety always defines a name for a place; you can use your own names for places instead, and indeed, for rings you will have to. A name is just Name: ... Name is often the name of a moiety like CH3, but it need not to be. Any name that begins with a capital letter and which contains only let‐ ters and numbers is valid: First: bond bond 30 from First Miscellaneous The specific construction bond ... ; moiety is equivalent to bond moiety Otherwise, each item has to be on a separate line (and only one line). Note that there must be whitespace after the semicolon which separates the commands. A period character . or a single quote ' in the first column of a line signals a troff command, which is copied through as‐is. A line whose first non‐blank character is a hash character (#) is treated as a comment and thus ignored. However, hash characters within a word are kept. A line whose first word is pic is copied through as‐is after the word pic has been removed. The command size n scales the diagram to make it look plausible at point size n (default is 10 point). Anything else is assumed to be pic code, which is copied through with a label. Since chem is a pic preprocessor, it is possible to include pic state‐ ments in the middle of a diagram to draw things not provided for by chem itself. Such pic statements should be included in chem code by adding pic as the first word of this line for clarity. The following pic commands are accepted as chem commands, so no pic command word is needed: define Start the definition of pic macro within chem. [ Start a block composite. ] End a block composite. { Start a macro definition block. } End a macro definition block. The macro names from define statements are stored and their call is ac‐ cepted as a chem command as well. Wish list This TODO list was collected by Brian Kernighan. Error checking is minimal; errors are usually detected and reported in an oblique fashion by pic. There is no library or file inclusion mechanism, and there is no short‐ hand for repetitive structures. The extension mechanism is to create pic macros, but these are tricky to get right and don’t have all the properties of built‐in objects. There is no in‐line chemistry yet (e.g., analogous to the $...$ con‐ struct of eqn). There is no way to control entry point for bonds on groups. Normally a bond connects to the carbon atom if entering from the top or bottom and otherwise to the nearest corner. Bonds from substituted atoms on heterocycles do not join at the proper place without adding a bit of pic. There is no decent primitive for brackets. Text (quoted strings) doesn’t work very well. A squiggle bond is needed. Files /usr/local/share/groff/1.23.0/pic/chem.pic A collection of pic macros needed by chem. /usr/local/share/groff/1.23.0/tmac/pic.tmac A macro file which redefines .PS, .PE, and .PF to center pic di‐ agrams. /usr/local/share/doc/groff-1.23.0/examples/chem/*.chem Example files for chem. /usr/local/share/doc/groff-1.23.0/examples/chem/122/*.chem Example files from the chem article by its authors, “CHEM—A Pro‐ gram for Typesetting Chemical Structure Diagrams: User Manual” (CSTR #122). Authors The GNU version of chem was written by Bernd Warken ⟨groff-bernd .warken-72@web.de⟩. It is based on the documentation of Brian Kernighan’s original awk version of chem. See also “CHEM—A Program for Typesetting Chemical Diagrams: User Manual” by Jon L. Bentley, Lynn W. Jelinski, and Brian W. Kernighan, 1992, AT&T Bell Laboratories Computing Science Technical Report No. 122 groff(1), pic(1) groff 1.23.0 29 August 2023 chem(1) ─────────────────────────────────────────────────────────────────────────────── eqn(1) General Commands Manual eqn(1) Name eqn - format mathematics (equations) for groff or MathML Synopsis eqn [-CNrR] [-d xy] [-f F] [-m n] [-M dir] [-p n] [-s n] [-T dev] [file ...] eqn --help eqn -v eqn --version Description The GNU implementation of eqn is part of the groff(7) document format‐ ting system. eqn is a troff(1) preprocessor that translates expres‐ sions in its own language, embedded in roff(7) input files, into mathe‐ matical notation typeset by troff(1). It copies each file’s contents to the standard output stream, translating each equation between lines starting with .EQ and .EN, or within a pair of user‐specified delim‐ iters. Normally, eqn is not executed directly by the user, but invoked by specifying the -e option to groff(1). While GNU eqn’s input syntax is highly compatible with AT&T eqn, the output eqn produces cannot be processed by AT&T troff; GNU troff (or a troff implementing relevant GNU extensions) must be used. If no file operands are given on the command line, or if file is “-”, eqn reads the standard input stream. Unless the -R option is used, eqn searches for the file eqnrc in the directories given with the -M option first, then in /usr/local/share/ groff/site-tmac, and finally in the standard macro directory /usr/ local/share/groff/1.23.0/tmac. If it exists and is readable, eqn processes it before any input files. This man page primarily discusses the differences between GNU eqn and AT&T eqn. Most of the new features of the GNU eqn input language are based on TeX. There are some references to the differences between TeX and GNU eqn below; these may safely be ignored if you do not know TeX. Three points are worth special note. • GNU eqn emits Presentation MathML output when invoked with the “-T MathML” option. • GNU eqn does not support terminal devices well, though it may suffice for simple inputs. • GNU eqn sets the input token “...” as an ellipsis on the text base‐ line, not the three centered dots of AT&T eqn. Set an ellipsis on the math axis with the GNU extension macro cdots. Anatomy of an equation eqn input consists of tokens. Consider a form of Newton’s second law of motion. The input .EQ F = m a .EN becomes F=ma. Each of F, =, m, and a is a token. Spaces and newlines are interchangeable; they separate tokens but do not break lines or produce space in the output. The following input characters not only separate tokens, but manage their grouping and spacing as well. { } Braces perform grouping. Whereas “e sup a b” expresses “(e to the a) times b”, “e sup { a b }” means “e to the (a times b)”. When immediately preceded by a “left” or “right” primitive, a brace loses its special meaning. ^ ~ are the half space and full space, respectively. Use them to tune the appearance of the output. Tab and leader characters separate tokens as well as advancing the drawing position to the next tab stop, but are seldom used in eqn in‐ put. When they occur, they must appear at the outermost lexical scope. This roughly means that they can’t appear within braces that are neces‐ sary to disambiguate the input; eqn will diagnose an error in this event. (See subsection “Macros” below for additional token separation rules.) Other tokens are primitives, macros, an argument to either of the fore‐ going, or components of an equation. Primitives are fundamental keywords of the eqn language. They can con‐ figure an aspect of the preprocessor’s state, as when setting a “global” font selection or type size (gfont and gsize), or declaring or deleting macros (“define” and undef); these are termed commands. Other primitives perform formatting operations on the tokens after them (as with fat, over, sqrt, or up). Equation components include mathematical variables, constants, numeric literals, and operators. eqn remaps some input character sequences to groff special character escape sequences for economy in equation entry and to ensure that glyphs from an unstyled font are used; see groff_char(7). + \[pl] ' \[fm] ‐ \[mi] <= \[<=] = \[eq] >= \[>=] Macros permit primitives, components, and other macros to be collected and referred to by a single token. Predefined macros make convenient the preparation of eqn input in a form resembling its spoken expres‐ sion; for example, consider cos, hat, inf, and lim. Spacing and typeface GNU eqn imputes types to the components of an equation, adjusting the spacing between them accordingly. Recognized types are as follows; most affect spacing only, whereas the “letter” subtype of “ordinary” also assigns a style. ordinary character such as “1”, “a”, or “!” letter character to be italicized by default digit n/a operator large operator such as “Σ” binary binary operator such as “+” relation relational operator such as “=” opening opening bracket such as “(” closing closing bracket such as “)” punctuation punctuation character such as “,” inner sub‐formula contained within brackets suppress component to which automatic spacing is not applied Two primitives apply types to equation components. type t e Apply type t to expression e. chartype t text Assign each character in (unquoted) text type t, persistently. eqn sets up spacings and styles as if by the following commands. chartype "letter" abcdefghiklmnopqrstuvwxyz chartype "letter" ABCDEFGHIKLMNOPQRSTUVWXYZ chartype "letter" \[*a]\[*b]\[*g]\[*d]\[*e]\[*z] chartype "letter" \[*y]\[*h]\[*i]\[*k]\[*l]\[*m] chartype "letter" \[*n]\[*c]\[*o]\[*p]\[*r]\[*s] chartype "letter" \[*t]\[*u]\[*f]\[*x]\[*q]\[*w] chartype "binary" *\[pl]\[mi] chartype "relation" <>\[eq]\[<=]\[>=] chartype "opening" {([ chartype "closing" })] chartype "punctuation" ,;:. chartype "suppress" ^~ eqn assigns all other ordinary and special roff characters, including numerals 0–9, the “ordinary” type. (The “digit” type is not used, but is available for customization.) In keeping with common practice in mathematical typesetting, lowercase, but not uppercase, Greek letters are assigned the “letter” type to style them in italics. The macros for producing ellipses, “...”, cdots, and ldots, use the “inner” type. Primitives eqn supports without alteration the AT&T eqn primitives above, back, bar, bold, define, down, fat, font, from, fwd, gfont, gsize, italic, left, lineup, mark, matrix, ndefine, over, right, roman, size, sqrt, sub, sup, tdefine, to, under, and up. New primitives The GNU extension primitives “type” and chartype are discussed in sub‐ section “Spacing and typeface” above; “set” in subsection “Customiza‐ tion” below; and grfont and gbfont in subsection “Fonts” below. In the following synopses, X can be any character not appearing in the parame‐ ter thus bracketed. e1 accent e2 Set e2 as an accent over e1. e2 is assumed to be at the appro‐ priate height for a lowercase letter without an ascender; eqn vertically shifts it depending on e1’s height. For example, hat is defined as follows. accent { "^" } dotdot, dot, tilde, vec, and dyad are also defined using the accent primitive. big e Enlarge the expression e; semantics like those of CSS “large” are intended. In troff output, the type size is increased by 5 scaled points. MathML output emits the following. copy file include file Interpolate the contents of file, omitting lines beginning with .EQ or .EN. If a relative path name, file is sought relative to the current working directory. ifdef name X anything X If name is defined as a primitive or macro, interpret anything. nosplit text As "text", but since text is not quoted it is subject to macro expansion; it is not split up and the spacing between characters not adjusted per subsection “Spacing and typeface” above. e opprime As prime, but set the prime symbol as an operator on e. In the input “A opprime sub 1”, the “1” is tucked under the prime as a subscript to the “A” (as is conventional in mathematical type‐ setting), whereas when prime is used, the “1” is a subscript to the prime character. The precedence of opprime is the same as that of bar and “under”, and higher than that of other primi‐ tives except accent and uaccent. In unquoted text, a neutral apostrophe (') that is not the first character on the input line is treated like opprime. sdefine name X anything X As “define”, but name is not recognized as a macro if called with arguments. e1 smallover e2 As over, but reduces the type size of e1 and e2, and puts less vertical space between e1 and e2 and the fraction bar. The over primitive corresponds to the TeX \over primitive in displayed equation styles; smallover corresponds to \over in non‐display (“inline”) styles. space n Set extra vertical spacing around the equation, replacing the default values, where n is an integer in hundredths of an em. If positive, n increases vertical spacing before the equation; if negative, it does so after the equation. This primitive pro‐ vides an interface to groff’s \x escape sequence, but with the opposite sign convention. It has no effect if the equation is part of a pic(1) picture. special troff‐macro e Construct an object by calling troff‐macro on e. The troff string 0s contains the eqn output for e, and the registers 0w, 0h, 0d, 0skern, and 0skew the width, height, depth, subscript kern, and skew of e, respectively. (The subscript kern of an object indicates how much a subscript on that object should be “tucked in”, or placed to the left relative to a non‐subscripted glyph of the same size. The skew of an object is how far to the right of the center of the object an accent over it should be placed.) The macro must modify 0s so that it outputs the de‐ sired result, returns the drawing position to the text baseline at the beginning of e, and updates the foregoing registers to correspond to the new dimensions of the result. Suppose you want a construct that “cancels” an expression by drawing a diagonal line through it. .de Ca . ds 0s \ \Z'\\*(0s'\ \v'\\n(0du'\ \D'l \\n(0wu -\\n(0hu-\\n(0du'\ \v'\\n(0hu' .. .EQ special Ca "x \[mi] 3 \[pl] x" ~ 3 .EN We use the \[mi] and \[pl] special characters instead of + and - because they are part of the argument to a troff macro, so eqn does not transform them to mathematical glyphs for us. Here’s a more complicated construct that draws a box around an expres‐ sion; the bottom of the box rests on the text baseline. We de‐ fine the eqn macro box to wrap the call of the troff macro Bx. .de Bx .ds 0s \ \Z'\\h'1n'\\*[0s]'\ \v'\\n(0du+1n'\ \D'l \\n(0wu+2n 0'\ \D'l 0 -\\n(0hu-\\n(0du-2n'\ \D'l -\\n(0wu-2n 0'\ \D'l 0 \\n(0hu+\\n(0du+2n'\ \h'\\n(0wu+2n' .nr 0w +2n .nr 0d +1n .nr 0h +1n .. .EQ define box ' special Bx $1 ' box(foo) ~ "bar" .EN split "text" As text, but since text is quoted, it is not subject to macro expansion; it is split up and the spacing between characters ad‐ justed per subsection “Spacing and typeface” above. e1 uaccent e2 Set e2 as an accent under e1. e2 is assumed to be at the appro‐ priate height for a letter without a descender; eqn vertically shifts it depending on whether e1 has a descender. utilde is predefined using uaccent as a tilde accent below the baseline. undef name Remove definition of macro or primitive name, making it unde‐ fined. vcenter e Vertically center e about the math axis, a horizontal line upon which fraction bars and characters such as “+” and “−” are aligned. MathML already behaves this way, so eqn ignores this primitive when producing that output format. The built‐in sum macro is defined as if by the following. define sum ! { type "operator" vcenter size +5 \(*S } ! Extended primitives GNU eqn extends the syntax of some AT&T eqn primitives, introducing one deliberate incompatibility. delim on eqn recognizes an “on” argument to the delim primitive spe‐ cially, restoring any delimiters previously disabled with “delim off”. If delimiters haven’t been specified, neither command has effect. Few eqn documents are expected to use “o” and “n” as left and right delimiters, respectively. If yours does, con‐ sider swapping them, or select others. col n { ... } ccol n { ... } lcol n { ... } rcol n { ... } pile n { ... } cpile n { ... } lpile n { ... } rpile n { ... } The integer value n (in hundredths of an em) increases the ver‐ tical spacing between rows, using groff’s \x escape sequence (the value has no effect in MathML mode). Negative values are accepted but have no effect. If more than one n occurs in a ma‐ trix or pile, the largest is used. Customization When eqn generates troff input, the appearance of equations is con‐ trolled by a large number of parameters. They have no effect when gen‐ erating MathML, which delegates typesetting to a MathML rendering en‐ gine. Configure these parameters with the set primitive. set p n assigns parameter p the integer value n; n is interpreted in units of hundredths of an em unless otherwise stated. For exam‐ ple, set x_height 45 says that eqn should assume that the font’s x‐height is 0.45 ems. Available parameters are as follows; defaults are shown in parentheses. We intend these descriptions to be expository rather than rigorous. minimum_size sets a floor for the type size (in scaled points) at which equations are set (5). fat_offset The fat primitive emboldens an equation by overprinting two copies of the equation hori‐ zontally offset by this amount (4). In MathML mode, components to which fat_offset applies instead use the following. over_hang A fraction bar is longer by twice this amount than the maximum of the widths of the numerator and denominator; in other words, it overhangs the numerator and denominator by at least this amount (0). accent_width When bar or under is applied to a single char‐ acter, the line is this long (31). Normally, bar or under produces a line whose length is the width of the object to which it applies; in the case of a single character, this tends to produce a line that looks too long. delimiter_factor Extensible delimiters produced with the left and right primitives have a combined height and depth of at least this many thousandths of twice the maximum amount by which the sub‐equa‐ tion that the delimiters enclose extends away from the axis (900). delimiter_shortfall Extensible delimiters produced with the left and right primitives have a combined height and depth not less than the difference of twice the maximum amount by which the sub‐equation that the delimiters enclose extends away from the axis and this amount (50). null_delimiter_space This much horizontal space is inserted on each side of a fraction (12). script_space The width of subscripts and superscripts is in‐ creased by this amount (5). thin_space This amount of space is automatically inserted after punctuation characters. It also config‐ ures the width of the space produced by the ^ token (17). medium_space This amount of space is automatically inserted on either side of binary operators (22). thick_space This amount of space is automatically inserted on either side of relations. It also config‐ ures the width of the space produced by the ~ token (28). x_height The height of lowercase letters without ascen‐ ders such as “x” (45). axis_height The height above the baseline of the center of characters such as “+” and “−” (26). It is im‐ portant that this value is correct for the font you are using. default_rule_thickness This should be set to the thickness of the \[ru] character, or the thickness of horizontal lines produced with the \D escape sequence (4). num1 The over primitive shifts up the numerator by at least this amount (70). num2 The smallover primitive shifts up the numerator by at least this amount (36). denom1 The over primitive shifts down the denominator by at least this amount (70). denom2 The smallover primitive shifts down the denomi‐ nator by at least this amount (36). sup1 Normally superscripts are shifted up by at least this amount (42). sup2 Superscripts within superscripts or upper lim‐ its or numerators of smallover fractions are shifted up by at least this amount (37). Con‐ ventionally, this is less than sup1. sup3 Superscripts within denominators or square roots or subscripts or lower limits are shifted up by at least this amount (28). Convention‐ ally, this is less than sup2. sub1 Subscripts are normally shifted down by at least this amount (20). sub2 When there is both a subscript and a super‐ script, the subscript is shifted down by at least this amount (23). sup_drop The baseline of a superscript is no more than this much below the top of the object on which the superscript is set (38). sub_drop The baseline of a subscript is at least this much below the bottom of the object on which the subscript is set (5). big_op_spacing1 The baseline of an upper limit is at least this much above the top of the object on which the limit is set (11). big_op_spacing2 The baseline of a lower limit is at least this much below the bottom of the object on which the limit is set (17). big_op_spacing3 The bottom of an upper limit is at least this much above the top of the object on which the limit is set (20). big_op_spacing4 The top of a lower limit is at least this much below the bottom of the object on which the limit is set (60). big_op_spacing5 This much vertical space is added above and be‐ low limits (10). baseline_sep The baselines of the rows in a pile or matrix are normally this far apart (140). Usually equal to the sum of num1 and denom1. shift_down The midpoint between the top baseline and the bottom baseline in a matrix or pile is shifted down by this much from the axis (26). Usually equal to axis_height. column_sep This much space is added between columns in a matrix (100). matrix_side_sep This much space is added at each side of a ma‐ trix (17). draw_lines If non‐zero, eqn draws lines using the troff \D escape sequence, rather than the \l escape se‐ quence and the \[ru] special character. The eqnrc file sets the default: 1 on ps, html, and the X11 devices, otherwise 0. body_height is the presumed height of an equation above the text baseline; eqn adds any excess as extra pre‐vertical line spacing with troff’s \x es‐ cape sequence (85). body_depth is the presumed depth of an equation below the text baseline; eqn adds any excess as extra post‐vertical line spacing with troff’s \x es‐ cape sequence (35). nroff If non‐zero, then ndefine behaves like define and tdefine is ignored, otherwise tdefine be‐ haves like define and ndefine is ignored. The eqnrc file sets the default: 1 on ascii, latin1, utf8, and cp1047 devices, otherwise 0. Macros In GNU eqn, macros can take arguments. A word defined by any of the define, ndefine, or tdefine primitives followed immediately by a left parenthesis is treated as a parameterized macro call: subsequent tokens up to a matching right parenthesis are treated as comma‐separated argu‐ ments. In this context only, commas and parentheses also serve as to‐ ken separators. A macro argument is not terminated by a comma inside parentheses nested within it. In a macro definition, $n, where n is between 1 and 9 inclusive, is replaced by the nth argument; if there are fewer than n arguments, it is replaced by nothing. Predefined macros GNU eqn supports the predefined macros offered by AT&T eqn: and, approx, arc, cos, cosh, del, det, dot, dotdot, dyad, exp, for, grad, half, hat, if, inter, Im, inf, int, lim, ln, log, max, min, nothing, partial, prime, prod, Re, sin, sinh, sum, tan, tanh, tilde, times, union, vec, ==, !=, +=, ->, <-, <<, >>, and “...”. The lowercase clas‐ sical Greek letters are available as alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, upsilon, xi, and zeta. Spell them with an ini‐ tial capital letter (Alpha) or in full capitals (ALPHA) to obtain up‐ percase forms. GNU eqn further defines the macros cdot, cdots, and utilde (all dis‐ cussed above), dollar, which sets a dollar sign, and ldots, which sets an ellipsis on the text baseline. Fonts eqn uses up to three typefaces to set an equation: italic (oblique), roman (upright), and bold. Assign each a groff typeface with the prim‐ itives gfont, grfont, and gbfont. The defaults are the styles I, R, and B (applied to the current font family). The chartype primitive (see above) sets a character’s type, which determines the face used to set it. The “letter” type is set in italics; others are set in roman. Use the bold primitive to select an (upright) bold style. gbfont f Select f as the bold font. This is a GNU extension. gfont f Select f as the italic font. grfont f Select f as the roman font. This is a GNU extension. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -C Recognize .EQ and .EN even when followed by a character other than space or newline. -d xy Specify delimiters x for left and y for right ends of equations not bracketed by .EQ/.EN. x and y need not be distinct. Any “delim xy” statements in the source file override this option. -f F is equivalent to “gfont F”. -m n is equivalent to “set minimum_size n”. -M dir Search dir for eqnrc before those listed in section “Descrip‐ tion” above. -N Prohibit newlines within delimiters. This option allows eqn to recover better from missing closing delimiters. -p n Set sub‐ and superscripts n points smaller than the surrounding text. This option is deprecated. eqn normally sets sub‐ and superscripts at 70% of the type size of the surrounding text. -r Reduce the type size of subscripts at most once relative to the base type size for the equation. -R Don’t load eqnrc. -s n is equivalent to “gsize n”. This option is deprecated. -T dev Prepare output for the device dev. In most cases, the effect of this is to define a macro dev with a value of 1; eqnrc uses this to provide definitions appropriate for the device. However, if the specified driver is “MathML”, the output is MathML markup rather than troff input, and eqnrc is not loaded at all. The default output device is ps. Files /usr/local/share/groff/1.23.0/tmac/eqnrc Initialization file. MathML mode limitations MathML is designed on the assumption that it cannot know the exact physical characteristics of the media and devices on which it will be rendered. It does not support control of motions and sizes to the same degree troff does. • eqn customization parameters have no effect on generated MathML. • The special, up, down, fwd, and back primitives cannot be imple‐ mented, and yield a MathML “” message instead. • The vcenter primitive is silently ignored, as centering on the math axis is the MathML default. • Characters that eqn sets extra large in troff mode—notably the inte‐ gral sign—may appear too small and need to have their “” wrappers adjusted by hand. As in its troff mode, eqn in MathML mode leaves the .EQ and .EN tokens in place, but emits nothing corresponding to delim delimiters. They can, however, be recognized as character sequences that begin with “”, end with “”, and do not cross line boundaries. Caveats Tokens must be double‐quoted in eqn input if they are not to be recog‐ nized as names of macros or primitives, or if they are to be inter‐ preted by troff. In particular, short ones, like “pi” and “PI”, can collide with troff identifiers. For instance, the eqn command “gfont PI” does not select groff’s Palatino italic font for the global italic face; you must use “gfont "PI"” instead. Delimited equations are set at the type size current at the beginning of the input line, not necessarily that immediately preceding the open‐ ing delimiter. Unlike TeX, eqn does not inherently distinguish displayed and inline equation styles; see the smallover primitive above. However, macro packages frequently define EQ and EN macros such that the equation within is displayed. These macros may accept arguments permitting the equation to be labeled or captioned; see the package’s documentation. Bugs eqn abuses terminology—its “equations” can be inequalities, bare ex‐ pressions, or unintelligible gibberish. But there’s no changing it now. In nroff mode, lowercase Greek letters are rendered in roman instead of italic style. In MathML mode, the mark and lineup features don’t work. These could, in theory, be implemented with “” elements. In MathML mode, each digit of a numeric literal gets a separate “ ” pair, and decimal points are tagged with “”. This is allowed by the specification, but inefficient. Examples We first illustrate eqn usage with a trigonometric identity. .EQ sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta .EN It can be convenient to set up delimiters if mathematical content will appear frequently in running text. .EQ delim $$ .EN Having cached a table of logarithms, the property $ln ( x y ) = ln x + ln y$ sped calculations. The quadratic formula illustrates use of fractions and radicals, and affords an opportunity to use the full space token ~. .EQ x = { - b ~ \[+-] ~ sqrt { b sup 2 - 4 a c } } over { 2 a } .EN Alternatively, we could define the plus‐minus sign as a binary opera‐ tor. Automatic spacing puts 0.06 em less space on either side of the plus‐minus than ~ does, this being the difference between the widths of the medium_space parameter used by binary operators and that of the full space. Independently, we can define a macro “frac” for setting fractions. .EQ chartype "binary" \[+-] define frac ! { $1 } over { $2 } ! x = frac(- b \[+-] sqrt { b sup 2 - 4 a c }, 2 a) .EN See also “Typesetting Mathematics—User’s Guide” (2nd edition), by Brian W. Kernighan and Lorinda L. Cherry, 1978, AT&T Bell Laboratories Computing Science Technical Report No. 17. The TeXbook, by Donald E. Knuth, 1984, Addison‐Wesley Professional. Appendix G discusses many of the parameters from section “Customiza‐ tion” above in greater detail. groff_char(7), particularly subsections “Logical symbols”, “Mathemati‐ cal symbols”, and “Greek glyphs”, documents a variety of special char‐ acter escape sequences useful in mathematical typesetting. groff(1), troff(1), pic(1), groff_font(5) groff 1.23.0 29 August 2023 eqn(1) ─────────────────────────────────────────────────────────────────────────────── eqn2graph(1) General Commands Manual eqn2graph(1) Name eqn2graph - convert an eqn equation into a cropped image Synopsis eqn2graph [-format output‐format] [convert‐argument ...] eqn2graph --help eqn2graph -v eqn2graph --version Description eqn2graph reads a one‐line eqn(1) equation from the standard input and writes an image file, by default in Portable Network Graphics (PNG) format, to the standard output. The input EQN code should not be preceded by the .EQ macro that nor‐ mally precedes it within groff(1) macros; nor do you need to have dol‐ lar‐sign or other delimiters around the equation. Arguments not recognized by eqn2graph are passed to the ImageMagick or GraphicsMagick program convert(1). By specifying these, you can give your image a border, set the image’s pixel density, or perform other useful transformations. The output image is clipped using convert’s -trim option to the small‐ est possible bounding box that contains all the black pixels. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -format output‐format Write the image in output‐format, which must be understood by convert; the default is PNG. Environment GROFF_TMPDIR TMPDIR TMP TEMP These environment variables are searched in the given order to determine the directory where temporary files will be created. If none are set, /tmp is used. Authors eqn2graph was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a recipe for pic2graph(1), by W. Richard Stevens. See also pic2graph(1), grap2graph(1), eqn(1), groff(1), convert(1) groff 1.23.0 29 August 2023 eqn2graph(1) ─────────────────────────────────────────────────────────────────────────────── gdiffmk(1) General Commands Manual gdiffmk(1) Name gdiffmk - mark differences between groff/nroff/troff files Synopsis gdiffmk [-a add‐mark] [-c change‐mark] [-d delete‐mark] [-x diff‐ command] [-D [-B] [-M mark1 mark2]] [--] file1 file2 [output] gdiffmk --help gdiffmk --version Description gdiffmk compares two roff(7) documents, file1 and file2, and creates a roff document consisting of file2 with added margin character (.mc) re‐ quests indicating output lines that differ from file1. If the file1 or file2 argument is “-”, gdiffmk reads the standard input stream for that input. If the output operand is present, gdiffmk writes output to a file of that name. If it is “-” or absent, gdiffmk writes output to the standard output stream. “-” cannot be both an input and output operand. Options --help displays a usage message and --version shows version informa‐ tion; both exit afterward. -a add‐mark Use add‐mark for source lines not in file1 but present in file2. Default: “+”. -B By default, the deleted texts marked by the -D option end with an added roff break request, .br, to ensure that the deletions are marked properly. This is the only way to guarantee that deletions and small changes get flagged. This option directs the program not to insert these breaks; it makes no sense to use it without -D. -c change‐mark Use change‐mark for changed source lines. Default: “|”. -d delete‐mark Use the delete‐mark for deleted source lines. Default: “*”. -D Show the deleted portions from changed and deleted text. -M mark1 mark2 Change the delimiting marks for the -D option. It makes no sense to use this option without -D. Default delimiting marks: “[[” ... “]]”. -x diff‐command Use the diff‐command command to perform the comparison of file1 and file2. In particular, diff‐command should accept the GNU diff(1) -D option. Default: diff. -- Treat all subsequent arguments as file names, even if they begin with “-”. Bugs The output is not necessarily compatible with all macro packages and all preprocessors. A workaround that often overcomes preprocessor problems is to run gdiffmk on the output of all the preprocessors in‐ stead of the input source. gdiffmk relies on the -D option of GNU diff to make a merged “#ifdef” output format. Busybox diff is known to not support it. Also see the -x diff‐command option. Authors gdiffmk was written by Mike Bianchi ⟨MBianchi@Foveal.com⟩, now retired. It is maintained by the groff developers. See also groff(1), nroff(1), gtroff(1), roff(7), diff(1) groff 1.23.0 29 August 2023 gdiffmk(1) ─────────────────────────────────────────────────────────────────────────────── glilypond(1) General Commands Manual glilypond(1) Name glilypond - embed LilyPond musical notation in groff documents Synopsis glilypond [-k] [{--ly2eps|--pdf2eps}] [-e directory] [-o output‐file] [-p filename‐prefix] [-t tdir] [{-v|-V}] [--] [file ...] glilypond [{--ly2eps|--pdf2eps}] [--eps_dir directory] [--keep_all] [--output output‐file] [--prefix filename‐prefix] [--temp_dir tdir] [--verbose] [--] [file ...] glilypond -? glilypond -h glilypond --help glilypond --usage glilypond -l glilypond --license glilypond --version Description glilypond is a groff(7) preprocessor that enables the embedding of LilyPond music scores in groff documents. If no operands are given, or if file is “-”, glilypond reads the standard input stream. A double‐ dash argument (“--”) causes all subsequent arguments to be interpreted as file operands, even if their names start with a dash. Usage At present, glilypond works with the groff ps, dvi, html, and xhtml de‐ vices. The lbp and lj4 devices are untested. Unfortunately, the pdf device does not yet work. Option overview -?|-h|--help|--usage Display usage information and exit. --version Display version information and exit. -l|--license Display copyright license information and exit. Options for building EPS files --ly2eps Direct lilypond(1) to create Encapsulated PostScript (EPS) files. This is the default. --pdf2eps The program glilypond generates a PDF file using lilypond. Then the EPS file is generated by pdf2ps and ps2eps. Directories and files -e|--eps_dir directory_name Normally all EPS files are sent to the temporary directory. With this option, you can generate your own directory, in which all useful EPS files are send. So at last, the temporary direc‐ tory can be removed. -p|--prefix begin_of_name Normally all temporary files get names that start with the ly... prefix. With this option, you can freely change this prefix. -k|--keep_all Normally all temporary files without the eps files are deleted. With this option, all generated files either by the lilypond program or other format transposers are kept. -t|--temp_dir dir With this option, you call a directory that is the base for the temporary directory. This directory name is used as is without any extensions. If this directory does not exist it is be cre‐ ated. The temporary directory is created by Perl’s security op‐ erations directly under this directory. In this temporary di‐ rectory, the temporary files are stored. Output -o|--output file_name Normally all groff output of this program is sent to STDOUT. With this option, that can be changed, such that the output is stored into a file named in the option argument file_name. -v|-V|--verbose A lot more of information is sent to STDERR. Short option collections The argument handling of options Short options are arguments that start with a single dash -. Such an argument can consist of arbitrary many options without option argument, composed as a collection of option characters following the single dash. Such a collection can be terminated by an option character that expects an option argument. If this option character is not the last character of the argument, the following final part of the argument is the option argument. If it is the last character of the argument, the next argu‐ ment is taken as the option argument. This is the standard for POSIX and GNU option management. For example, -kVe some_dir is a collection of the short options -k and -V without option argument, followed by the short option -e with option argument that is the following part of the argument some_dir. So this argument could also be written as several arguments -k -V -e some_dir. Handling of long options Arguments that start with a double dash -- are so‐called long options R . Each double dash argument can only have a single long option. Long options have or have not an option argument. An option argument can be the next argument or can be appended with an equal sign = to the same argument as the long option. --help is a long option without an option argument. --eps_dir some_dir --eps_dir=some_dir is the long option --eps_dir with the option argument some_dir. Moreover the program allows abbreviations of long options, as much as possible. The long option --keep_all can be abbreviated from --keep_al up to --k because the program does not have another long option whose name starts with the character k. On the other hand, the option --version cannot be abbreviated further than --vers because there is also the long option --verbose that can be abbreviated up to --verb. An option argument can also be appended to an abbreviation. So is --e=some_dir the same as --eps_dir some_dir. Moreover the program allows an arbitrary usage of upper and lower case in the option name. This is Perl style. For example, the long option --keep_all can as well be written as --Keep_All or even as an abbreviation like --KeE. LilyPond regions in roff input Integrated LilyPond code A lilypond part within a structure written in the groff language is the whole part between the marks .lilypond start and .lilypond end A groff input can have several of these lilypond parts. When processing such a lilypond part between .lilypond start and .lily‐ pond end we say that the glilypond program is in lilypond mode. These lilypond parts are sent into temporary lilypond files with the file name extension .ly. These files are transformed later on into EPS files. Inclusion of .ly files An additional command line for file inclusion of lilypond files is given by .lilypond include file_name in groff input. For each such include command, one file of lilypond code can be included into the groff code. Arbitrarily many of these commands can be included in the groff input. These include commands can only be used outside the lilypond parts. Within the lilypond mode, this inclusion is not possible. So .lilypond include may not be used in lilypond mode, i.e. between .lilypond start and .lilypond end. These included ly‐files are also transformed into EPS files. Generated files By the transformation process of lilypond parts into EPS files, there are many files generated. By default, these files are regarded as tem‐ porary files and as such stored in a temporary directory. This process can be changed by command‐line options. Command‐line options for directories The temporary directory for this program is either created automati‐ cally or can be named by the option -t|--temp_dir dir. Moreover, the EPS files that are later on referred by .PSPIC command in the final groff output can be stored in a different directory that can be set by the command‐line option -e|--eps_dir directory_name. With this option, the temporary directory can be removed completely at the end of the program. The beginning of the names of the temporary files can be set by the command‐line options -p or --prefix. All of the temporary files except the EPS files are deleted finally. This can be changed by setting the command‐line options -k or --keep_files. With this, all temporary files and directories are kept, not deleted. These EPS files are stored in a temporary or EPS directory. But they cannot be deleted by the transformation process because they are needed for the display which can take a long time. Transformation processes for generating EPS files Mode pdf2eps This mode is the actual default and can also be chosen by the option --pdf2eps. In this mode, the .ly files are transformed by the lilypond(1) program into PDF files, using lilypond --pdf --output=file‐name for each .ly file. The file‐name must be provided without the exten‐ sion .pdf. By this process, a file file‐name.pdf is generated. The next step is to transform these PDF files into a PS file. This is done by the pdf2ps(1) program using $ pdf2ps file‐name.pdf file‐name.pds The next step creates an EPS file from the PS file. This is done by the ps2eps(1) program using $ ps2eps file‐name.ps By that, a file file‐name.eps is created for each lilypond part in the groff file or standard input. The last step to be done is replacing all lilypond parts by the groff command .PSPIC file‐name.eps Mode ly2eps In earlier time, this mode was the default. But now it does not work any more, so accept the new default pdf2eps. For testing, this mode can also be chosen by the glilypond option --ly2eps. In this mode, the .ly files are transformed by the lilypond program into many files of different formats, including eps files, using $ lilypond --ps -dbackend=eps -dgs-load-fonts --output=file‐name for each .ly file. The output file-name must be provided without an extension, its directory is temporary. There are many EPS files created. One having the complete transformed ly file, named file-name.eps. Moreover there are EPS files for each page, named file-name-digit.eps. The last step to be done is replacing all lilypond parts by the collec‐ tion of the corresponding EPS page files. This is done by groff com‐ mands .PSPIC file‐name-digit.eps Generated groff output The new groff(7) structure generated by glilypond is either 1) sent to standard output and can there be saved into a file or piped into groff(1) or 2) stored into a file by given the option -o | --output file_name Authors glilypond was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also groff(1) describes the usage of the groff command and contains pointers to further documentation of the groff system. groff_tmac(5) describes the .PSPIC request. lilypond(1) briefly describes the lilypond command and contains pointers to further documentation. pdf2ps(1) transforms a PDF file into a PostScript format. ps2eps(1) transforms a PS file into an EPS format. groff 1.23.0 29 August 2023 glilypond(1) ─────────────────────────────────────────────────────────────────────────────── gperl(1) General Commands Manual gperl(1) Name gperl - execute Perl commands in groff documents Synopsis gperl [file ...] gperl -h gperl --help gperl -v gperl --version Description This is a preprocessor for groff(1). It allows the use of perl(7) code in groff(7) files. The result of a Perl part can be stored in groff strings or numerical registers based on the arguments at a final line of a Perl part. If no operands are given, or if file is “-”, gperl reads the standard input stream. A double‐dash argument (“--”) causes all subsequent ar‐ guments to be interpreted as file operands, even if their names start with a dash. -h and --help display a usage message, whereas -v and --version display version information; all exit afterward. Perl regions Perl parts in groff files are enclosed by two .Perl requests with dif‐ ferent arguments, a starting and an ending command. Starting Perl mode The starting Perl request can either be without arguments, or by a re‐ quest that has the term start as its only argument. • .Perl • .Perl start Ending Perl mode without storage A .Perl command line with an argument different from start finishes a running Perl part. Of course, it would be reasonable to add the argu‐ ment stop; that’s possible, but not necessary. • .Perl stop • .Perl other_than_start The argument other_than_start can additionally be used as a groff string variable name for storage — see next section. Ending Perl mode with storage A useful feature of gperl is to store one or more results from the Perl mode. The output of a Perl part can be got with backticks `...`. This program collects all printing to STDOUT (normal standard output) by the Perl print program. This pseudo‐printing output can have sev‐ eral lines, due to printed line breaks with \n. By that, the output of a Perl run should be stored into a Perl array, with a single line for each array member. This Perl array output can be stored by gperl in either groff strings by creating a groff command .ds groff register by creating a groff command .rn The storage modes can be determined by arguments of a final stopping .Perl command. Each argument .ds changes the mode into groff string and .nr changes the mode into groff register for all following output parts. By default, all output is saved as strings, so .ds is not really needed before the first .nr command. That suits to groff(7), because every output can be saved as groff string, but the registers can be very re‐ strictive. In string mode, gperl generates a groff string storage line .ds var_name content In register mode the following groff command is generated .nr var_name content We present argument collections in the following. You can add as first argument for all stop. We omit this additional element. .Perl .ds var_name This will store 1 output line into the groff string named var_name by the automatically created command .ds var_name output .Perl var_name If var_name is different from start this is equivalent to the former command, because the string mode is string with .ds com‐ mand. default. .Perl var_name1 var_name2 This will store 2 output lines into groff string names var_name1 and var_name2, because the default mode .ds is active, such that no .ds argument is needed. Of course, this is equivalent to .Perl .ds var_name1 var_name2 and .Perl .ds var_name1 .ds var_name2 .Perl .nr var_name1 varname2 stores both variables as register variables. gperl generates .nr var_name1 output_line1 .nr var_name2 output_line2 .Perl .nr var_name1 .ds var_name2 stores the 1st argument as register and the second as string by .nr var_name1 output_line1 .ds var_name2 output_line2 Example A possible Perl part in a roff file could look like that: before .Perl start my $result = 'some data'; print $result; .Perl stop .ds string_var after This stores the result ”some data” into the roff string called string_var, such that the following line is printed: .ds string_var some data by gperl as food for the coming groff run. A Perl part with several outputs is: .Perl start print ”first\n”; print ”second line\n”; print ”3\n”; .Perl var1 var2 .nr var3 This stores 3 printed lines into 3 groff strings. var1,var2,var3. So the following groff command lines are created: .ds var1 first .ds var2 second line .nr var3 3 Authors gperl was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also Man pages related to groff are groff(1), groff(7), and grog(1). Documents related to Perl are perl(1), perl(7). groff 1.23.0 29 August 2023 gperl(1) ─────────────────────────────────────────────────────────────────────────────── gpinyin(1) General Commands Manual gpinyin(1) Name gpinyin - use Hanyu Pinyin Chinese in groff documents Synopsis gpinyin [file ...] gpinyin -h gpinyin --help gpinyin -v gpinyin --version Description gpinyin is a preprocessor for groff(1) that facilitates use of Hanyu Pinyin in groff(7) files. Pinyin is a method for writing the Mandarin Chinese language with the Latin alphabet. Mandarin consists of more than four hundred base syllables, each spoken with one of five differ‐ ent tones. Changing the tone applied to the syllable generally alters the meaning of the word it forms. In Pinyin, a syllable is written in the Latin alphabet and a numeric tone indicator can be appended to each syllable. Each input‐file is a file name or the character “-” to indicate that the standard input stream should be read. As usual, the argument “--” can be used in order to force interpretation of all remaining arguments as file names, even if an input‐file argument begins with a “-”. -h and --help display a usage message, while -v and --version show version information; all exit afterward. Pinyin sections Pinyin sections in groff files are enclosed by two .pinyin requests with different arguments. The starting request is .pinyin start or .pinyin begin and the ending request is .pinyin stop or .pinyin end . Syllables In Pinyin, each syllable is represented by one to six letters drawn from the fifty‐two upper‐ and lowercase letters of the Unicode basic Latin character set, plus the letter “U” with dieresis (umlaut) in both cases—in other words, the members of the set “[a–zA–ZüÜ]”. In groff input, all basic Latin letters are written as themselves. The “u with dieresis” can be written as “\[:u]” in lowercase or “\[:U]” in uppercase. Within .pinyin sections, gpinyin supports the form “ue” for lowercase and the forms “Ue” and “UE” for uppercase. Tones Each syllable has exactly one of five tones. The fifth tone is not ex‐ plicitly written at all, but each of the first through fourth tones is indicated with a diacritic above a specific vowel within the syllable. In a gpinyin source file, these tones are written by adding a numeral in the range 0 to 5 after the syllable. The tone numbers 1 to 4 are transformed into accents above vowels in the output. The tone numbers 0 and 5 are synonymous. The tones are written as follows. Tone Description Diacritic Example Input Example Output ───────────────────────────────────────────────────────────────────── first flat ¯ ma1 mā second rising ´ ma2 má third falling‐rising ˇ ma3 mǎ fourth falling ` ma4 mà fifth neutral (none) ma0 ma ma5 The neutral tone number can be omitted from a word‐final syllable, but not otherwise. Authors gpinyin was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also Useful documents on the World Wide Web related to Pinyin include Pinyin to Unicode ⟨http://www.foolsworkshop.com/ptou/index.html⟩, On‐line Chinese Tools ⟨http://www.mandarintools.com/⟩, Pinyin.info: a guide to the writing of Mandarin Chinese in roman‐ ization ⟨http://www.pinyin.info/index.html⟩, “Where do the tone marks go?” ⟨http://www.pinyin.info/rules/ where.html⟩, pinyin.txt from the CJK macro package for TeX ⟨http://git.savannah .gnu.org/gitweb/?p=cjk.git;a=blob_plain;f=doc/pinyin.txt;hb=HEAD⟩, and pinyin.sty from the CJK macro package for TeX ⟨http://git.savannah .gnu.org/gitweb/?p=cjk.git;a=blob_plain;f=texinput/pinyin.sty ;hb=HEAD⟩. groff(1) and grog(1) explain how to view roff documents. groff(7) and groff_char(7) are comprehensive references covering the language elements of GNU troff and the available glyph repertoire, re‐ spectively. groff 1.23.0 29 August 2023 gpinyin(1) ─────────────────────────────────────────────────────────────────────────────── grap2graph(1) General Commands Manual grap2graph(1) Name grap2graph - convert a grap diagram into a cropped image Synopsis grap2graph [-unsafe] [-format output‐format] [convert‐argument ...] grap2graph --help grap2graph -v grap2graph --version Description grap2graph reads a grap(1) program from the standard input and writes an image file, by default in Portable Network Graphics (PNG) format, to the standard output. The input GRAP code should not be wrapped with the .G1 and .G2 macros that normally guard it within groff(1) documents. Arguments not recognized by grap2graph are passed to the ImageMagick or GraphicsMagick program convert(1). By specifying these, you can give your image a border, set the image’s pixel density, or perform other useful transformations. The output image is clipped using convert’s -trim option to the small‐ est possible bounding box that contains all the black pixels. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -format output‐format Write the image in output‐format, which must be understood by convert; the default is PNG. -unsafe Run groff in unsafe mode, enabling the PIC command sh to execute arbitrary Unix shell commands. The groff default is to forbid this. Environment GROFF_TMPDIR TMPDIR TMP TEMP These environment variables are searched in the given order to determine the directory where temporary files will be created. If none are set, /tmp is used. Authors grap2graph was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a recipe for pic2graph(1), by W. Richard Stevens. See also pic2graph(1), eqn2graph(1), grap(1), pic(1), groff(1), convert(1) groff 1.23.0 29 August 2023 grap2graph(1) ─────────────────────────────────────────────────────────────────────────────── grn(1) General Commands Manual grn(1) Name grn - embed Gremlin images in groff documents Synopsis grn [-C] [-T dev] [-M dir] [-F dir] [file ...] grn -? grn --help grn -v grn --version Description grn is a preprocessor for including gremlin pictures in troff(1) input. grn writes to standard output, processing only input lines between two that start with .GS and .GE. Those lines must contain grn commands (see below). These macros request a gremlin file; the picture in that file is converted and placed in the troff input stream. .GS may be called with a C, L, or R argument to center, left‐, or right‐justify the whole gremlin picture (the default is to center). If no file is mentioned, the standard input is read. At the end of the picture, the position on the page is the bottom of the gremlin picture. If the grn entry is ended with .GF instead of .GE, the position is left at the top of the picture. Currently only the me macro package has support for .GS, .GE, and .GF. grn produces drawing escape sequences that use groff’s color scheme ex‐ tension (\D'F ...'), and thus may not work with other troffs. grn commands Each input line between .GS and .GE may have one grn command. Commands consist of one or two strings separated by white space, the first string being the command and the second its operand. Commands may be upper‐ or lowercase and abbreviated down to one character. Commands that affect a picture’s environment (those listed before “default”, see below) are only in effect for the current picture: the environment is reinitialized to the defaults at the start of the next picture. The commands are as follows. 1 N 2 N 3 N 4 N Set gremlin’s text size number 1 (2, 3, or 4) to N points. The default is 12 (16, 24, and 36, respectively). roman f italics f bold f special f Set the roman (italics, bold, or special) font to troff’s font f (either a name or number). The default is R (I, B, and S, re‐ spectively). l f stipple f Set the stipple font to troff’s stipple font f (name or number). The command stipple may be abbreviated down as far as “st” (to avoid confusion with “special”). There is no default for stip‐ ples (unless one is set by the “default” command), and it is in‐ valid to include a gremlin picture with polygons without speci‐ fying a stipple font. x N scale N Magnify the picture (in addition to any default magnification) by N, a floating‐point number larger than zero. The command scale may be abbreviated down to “sc”. narrow N medium N thick N Set the thickness of gremlin’s narrow (medium and thick, respec‐ tively) lines to N times 0.15pt (this value can be changed at compile time). The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt (0.45pt and 0.75pt, respectively). A thickness value of zero selects the smallest available line thickness. Negative values cause the line thickness to be pro‐ portional to the current point size. pointscale [off|on] Scale text to match the picture. Gremlin text is usually printed in the point size specified with the commands 1, 2, 3, or 4, regardless of any scaling factors in the picture. Setting pointscale will cause the point sizes to scale with the picture (within troff’s limitations, of course). An operand of anything but off will turn text scaling on. default Reset the picture environment defaults to the settings in the current picture. This is meant to be used as a global parameter setting mechanism at the beginning of the troff input file, but can be used at any time to reset the default settings. width N Force the picture to be N inches wide. This overrides any scal‐ ing factors present in the same picture. “width 0” is ignored. height N Force the picture to be N inches high, overriding other scaling factors. If both width and height are specified, the tighter constraint will determine the scale of the picture. height and width commands are not saved with a “default” command. They will, however, affect point size scaling if that option is set. file name Get picture from gremlin file name located the current directory (or in the library directory; see the -M option above). If mul‐ tiple file commands are given, the last one controls. If name doesn’t exist, an error message is reported and processing con‐ tinues from the .GE line. Usage with groff Since grn is a preprocessor, it has no access to elements of formatter state, such as indentation, line length, type size, or register values. Consequently, no troff input can be placed between the .GS and .GE macros. However, gremlin text elements are subsequently processed by troff, so anything valid in a single line of troff input is valid in a line of gremlin text (barring the dot control character “.” at the be‐ ginning of a line). Thus, it is possible to have equations within a gremlin figure by including in the gremlin file eqn expressions en‐ closed by previously defined delimiters (e.g., “$$”). When using grn along with other preprocessors, it is best to run tbl(1) before grn, pic(1), and/or ideal to avoid overworking tbl. eqn(1) should always be run last. groff(1) will automatically run preproces‐ sors in the correct order. A picture is considered an entity, but that doesn’t stop troff from trying to break it up if it falls off the end of a page. Placing the picture between “keeps” in the me macros will ensure proper placement. grn uses troff’s registers g1 through g9 and sets registers g1 and g2 to the width and height of the gremlin figure (in device units) before entering the .GS macro (this is for those who want to rewrite these macros). Gremlin file format There exist two distinct gremlin file formats: the original format for AED graphic terminals, and the Sun or X11 version. An extension used by the Sun/X11 version allowing reference points with negative coordi‐ nates is not compatible with the AED version. As long as a gremlin file does not contain negative coordinates, either format will be read correctly by either version of gremlin or grn. The other difference in Sun/X11 format is the use of names for picture objects (e.g., POLYGON, CURVE) instead of numbers. Files representing the same picture are shown below. sungremlinfile gremlinfile 0 240.00 128.00 0 240.00 128.00 CENTCENT 2 240.00 128.00 240.00 128.00 185.00 120.00 185.00 120.00 240.00 120.00 240.00 120.00 296.00 120.00 296.00 120.00 * -1.00 -1.00 2 3 2 3 10 A Triangle 10 A Triangle POLYGON 6 224.00 416.00 224.00 416.00 96.00 160.00 96.00 160.00 384.00 160.00 384.00 160.00 * -1.00 -1.00 5 1 5 1 0 0 -1 -1 • The first line of each gremlin file contains either the string “grem‐ linfile” (AED) or “sungremlinfile” (Sun/X11). • The second line of the file contains an orientation and x and y val‐ ues for a positioning point, separated by spaces. The orientation, either 0 or 1, is ignored by the Sun/X11 version. 0 means that grem‐ lin will display things in horizontal format (a drawing area wider than it is tall, with a menu across the top). 1 means that gremlin will display things in vertical format (a drawing area taller than it is wide, with a menu on the left side). x and y are floating‐point values giving a positioning point to be used when this file is read into another file. The stuff on this line really isn’t all that im‐ portant; a value of “1 0.00 0.00” is suggested. • The rest of the file consists of zero or more element specifications. After the last element specification is a line containing the string “-1”. • Lines longer than 127 characters are truncated to that length. Element specifications • The first line of each element contains a single decimal number giv‐ ing the type of the element (AED) or its name (Sun/X11). gremlin File Format: Object Type Specification ───────────────────────────────────────────────────────── AED Number Sun/X11 Name Description 0 BOTLEFT bottom‐left‐justified text 1 BOTRIGHT bottom‐right‐justified text 2 CENTCENT center‐justified text 3 VECTOR vector 4 ARC arc 5 CURVE curve 6 POLYGON polygon 7 BSPLINE b‐spline 8 BEZIER Bézier 10 TOPLEFT top‐left‐justified text 11 TOPCENT top‐center‐justified text 12 TOPRIGHT top‐right‐justified text 13 CENTLEFT left‐center‐justified text 14 CENTRIGHT right‐center‐justified text 15 BOTCENT bottom‐center‐justified text • After the object type comes a variable number of lines, each specify‐ ing a point used to display the element. Each line contains an x‐co‐ ordinate and a y‐coordinate in floating‐point format, separated by spaces. The list of points is terminated by a line containing the string “-1.0 -1.0” (AED) or a single asterisk, “*” (Sun/X11). • After the points comes a line containing two decimal values, giving the brush and size for the element. The brush determines the style in which things are drawn. For vectors, arcs, and curves there are six valid brush values. 1 thin dotted lines 2 thin dot‐dashed lines 3 thick solid lines 4 thin dashed lines 5 thin solid lines 6 medium solid lines For polygons, one more value, 0, is valid. It specifies a polygon with an invisible border. For text, the brush selects a font as fol‐ lows. 1 roman (R font in troff) 2 italics (I font in troff) 3 bold (B font in troff) 4 special (S font in troff) If you’re using grn to run your pictures through groff, the font is really just a starting font. The text string can contain formatting sequences like “\fI” or “\d” which may change the font (as well as do many other things). For text, the size field is a decimal value be‐ tween 1 and 4. It selects the size of the font in which the text will be drawn. For polygons, this size field is interpreted as a stipple number to fill the polygon with. The number is used to index into a stipple font at print time. • The last line of each element contains a decimal number and a string of characters, separated by a single space. The number is a count of the number of characters in the string. This information is used only for text elements, and contains the text string. There can be spaces inside the text. For arcs, curves, and vectors, the character count is zero (0), followed by exactly one space before the newline. Coordinates gremlin was designed for AED terminals, and its coordinates reflect the AED coordinate space. For vertical pictures, x values range 116 to 511, and y values from 0 to 483. For horizontal pictures, x values range from 0 to 511, and y values from 0 to 367. Although you needn’t absolutely stick to this range, you’ll get better results if you at least stay in this vicinity. Also, point lists are terminated by a point of (-1, -1), so you shouldn’t ever use negative coordinates. gremlin writes out coordinates using the printf(3) format “%f1.2”; it’s probably a good idea to use the same format if you want to modify the grn code. Sun/X11 coordinates There is no restriction on the range of coordinates used to create ob‐ jects in the Sun/X11 version of gremlin. However, files with negative coordinates will cause problems if displayed on the AED. Options -? and --help display a usage message, while -v and --version show ver‐ sion information; all exit afterward. -C Recognize .GS and .GE (and .GF) even when followed by a charac‐ ter other than space or newline. -F dir Search dir for subdirectories devname (name is the name of the output driver) for the DESC file before the default font direc‐ tories /usr/local/share/groff/site-font, /usr/local/share/groff/ 1.23.0/font, and /usr/lib/font. -M dir Prepend dir to the search path for gremlin files. The default search path is the current directory, the home directory, /usr/ local/share/groff/site-tmac, and /usr/local/share/groff/1.23.0/ tmac, in that order. -T dev Prepare device output using output driver dev. The default is ps. See groff(1) for a list of valid devices. Files /usr/local/share/groff/1.23.0/font/devname/DESC describes the output device name. Authors David Slattengren and Barry Roitblat wrote the original Berkeley grn. Daniel Senderowicz and Werner Lemberg modified it for groff. See also gremlin(1), groff(1), pic(1), ideal(1) groff 1.23.0 29 August 2023 grn(1) ─────────────────────────────────────────────────────────────────────────────── grodvi(1) General Commands Manual grodvi(1) Name grodvi - groff output driver for TeX DVI format Synopsis grodvi [-dl] [-F dir] [-p paper‐format] [-w n] [file ...] grodvi --help grodvi -v grodvi --version Description The GNU roff DVI output driver translates the output of troff(1) into TeX DVI format. Normally, grodvi is invoked by groff(1) when the lat‐ ter is given the “-T dvi” option. (In this installation, ps is the de‐ fault output device.) Use groff’s -P option to pass any options shown above to grodvi. If no file arguments are given, or if file is “-”, grodvi reads the standard input stream. Output is written to the stan‐ dard output stream. The DVI file generated by grodvi can interpreted by any correctly writ‐ ten DVI driver. troff drawing primitives are implemented using tpic version 2 specials. If the driver does not support these, \D escape sequences will not produce any output. Encapsulated PostScript (EPS) files can be easily included; use the PSPIC macro. pspic.tmac is loaded automatically by dvi.tmac. See groff_tmac(5). The default color used by the \m and \M escape sequences is black. Currently, the stroke color for \D drawing escape sequences is black; fill color values are translated to gray. In groff, as in AT&T troff, the \N escape sequence can be used to ac‐ cess any glyph in the current font by its position in the corresponding TFM file. By design, the DVI format doesn’t care about the physical dimensions of the output medium. Instead, grodvi emits the equivalent to TeX’s \special{papersize=width,length} on the first page; dvips (or another DVI driver) then sets the page size accordingly. If either the page width or length is not positive, no papersize special is output. A device control escape sequence \X'anything' is translated to the same DVI file instructions as would be produced by \special{anything} in TeX; anything cannot contain a newline. Typefaces grodvi supports the standard four styles: R (roman), I (italic), B (bold), and BI (bold‐italic). Fonts are grouped into families T and H having members in each style. “CM” abbreviates “Computer Modern”. TR CM Roman (cmr10) TI CM Text Italic (cmti10) TB CM Bold Extended Roman (cmbx10) TBI CM Bold Extended Text Italic (cmbxti10) HR CM Sans Serif (cmss10) HI CM Slanted Sans Serif (cmssi10) HB CM Sans Serif Bold Extended (cmssbx10) HBI CM Slanted Sans Serif Bold Extended (cmssbxo10) The following fonts are not members of a family. CW CM Typewriter Text (cmtt10) CWI CM Italic Typewriter Text (cmitt10) Special fonts include MI (cmmi10), S (cmsy10), EX (cmex10), SC (cm‐ tex10, only for CW), and, perhaps surprisingly, TR, TI, and CW, because TeX places some glyphs in text fonts that troff generally does not. For italic fonts, CWI is used instead of CW. Finally, the symbol fonts of the American Mathematical Society are available as special fonts SA (msam10) and SB (msbm10). They are are not mounted by default. The troff option -mec loads the ec.tmac macro file, employing the EC and TC fonts instead of CM. These are designed similarly to the Com‐ puter Modern fonts; further, they provide Euro \[Eu] and per mille \[%0] glyphs. ec.tmac must be loaded before any language‐specific macro files because it does not set up the codes necessary for auto‐ matic hyphenation. Font description files Use tfmtodit(1) to create groff font description files from TFM (TeX font metrics) files. The font description file should contain the fol‐ lowing additional directives, which tfmtodit generates automatically. internalname name The name of the TFM file (without the .tfm extension) is name. checksum n The checksum in the TFM file is n. designsize n The design size in the TFM file is n. Drawing commands grodvi supports an additional drawing command. \D'R dh dv' Draw a rule (solid black rectangle) with one corner at the draw‐ ing position, and the diagonally opposite corner at the drawing position +(dh,dv), which becomes the new drawing position after‐ ward. This command produces a rule in the DVI file and so can be printed even with a driver that does not support tpic spe‐ cials, unlike the other \D commands. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -d Do not use tpic specials to implement drawing commands. Hori‐ zontal and vertical lines are implemented by rules. Other draw‐ ing commands are ignored. -F dir Prepend directory dir/devname to the search path for font and device description files; name is the name of the device, usu‐ ally dvi. -l Use landscape orientation rather than portrait. -p paper‐format Set physical dimensions of output medium, overriding the papersize, paperlength, and paperwidth directives in the DESC file. paper‐format can be any argument accepted by the papersize directive; see groff_font(5). -w n Draw rules (lines) with a thickness of n thousandths of an em. The default thickness is 40 (0.04 em). Environment GROFF_FONT_PATH lists directories in which to search for devdvi, grodvi’s direc‐ tory of device and font description files. See troff(1) and groff_font(5). Files /usr/local/share/groff/1.23.0/font/devdvi/DESC describes the dvi output device. /usr/local/share/groff/1.23.0/font/devdvi/F describes the font known as F on device dvi. /usr/local/share/groff/1.23.0/tmac/dvi.tmac defines font mappings, special characters, and colors for use with the dvi output device. It is automatically loaded by troffrc when the dvi output device is selected. /usr/local/share/groff/1.23.0/tmac/ec.tmac configures the dvi output device to use the EC and TC font fami‐ lies instead of CM (Computer Modern). Bugs DVI files produced by grodvi use a different resolution (57,816 units per inch) from those produced by TeX. Incorrectly written drivers which assume the resolution used by TeX, rather than using the resolu‐ tion specified in the DVI file, will not work with grodvi. When using the -d option with boxed tables, vertical and horizontal lines can sometimes protrude by one pixel. This is a consequence of the way TeX requires that the heights and widths of rules be rounded. See also “What are the EC fonts?” ⟨https://texfaq.org/FAQ-ECfonts⟩; TeX FAQ: Frequently Asked Question List for TeX tfmtodit(1), groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7), groff_tmac(5) groff 1.23.0 29 August 2023 grodvi(1) ─────────────────────────────────────────────────────────────────────────────── groff(1) General Commands Manual groff(1) Name groff - front end to the GNU roff document formatting system Synopsis groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback‐encoding] [-f font‐family] [-F font‐directory] [-I inclusion‐directory] [-K input‐encoding] [-L spooler‐ argument] [-m macro‐package] [-M macro‐directory] [-n page‐ number] [-o page‐list] [-P postprocessor‐argument] [-r cnumeric‐ expression] [-r register=numeric‐expression] [-T output‐device] [-w warning‐category] [-W warning‐category] [file ...] groff -h groff --help groff -v [option ...] [file ...] groff --version [option ...] [file ...] Description groff is the primary front end to the GNU roff document formatting sys‐ tem. GNU roff is a typesetting system that reads plain text input files that include formatting commands to produce output in PostScript, PDF, HTML, DVI, or other formats, or for display to a terminal. For‐ matting commands can be low‐level typesetting primitives, macros from a supplied package, or user‐defined macros. All three approaches can be combined. If no file operands are specified, or if file is “-”, groff reads the standard input stream. A reimplementation and extension of the typesetter from AT&T Unix, groff is present on most POSIX systems owing to its long association with Unix manuals (including man pages). It and its predecessor are notable for their production of several best‐selling software engineer‐ ing texts. groff is capable of producing typographically sophisticated documents while consuming minimal system resources. The groff command orchestrates the execution of preprocessors, the transformation of input documents into a device‐independent page de‐ scription language, and the production of output from that language. Options -h and --help display a usage message and exit. Because groff is intended to subsume most users’ direct invocations of the troff(1) formatter, the two programs share a set of options. How‐ ever, groff has some options that troff does not share, and others which groff interprets differently. At the same time, not all valid troff options can be given to groff. groff‐specific options The following options either do not exist in GNU troff or are inter‐ preted differently by groff. -D enc Set fallback input encoding used by preconv(1) to enc; implies -k. -e Run eqn(1) preprocessor. -g Run grn(1) preprocessor. -G Run grap(1) preprocessor; implies -p. -I dir Works as troff’s option (see below), but also implies -g and -s. It is passed to soelim(1) and the output driver, and grn is passed an -M option with dir as its argument. -j Run chem(1) preprocessor; implies -p. -k Run preconv(1) preprocessor. Refer to its man page for its be‐ havior if neither of groff’s -K or -D options is also specified. -K enc Set input encoding used by preconv(1) to enc; implies -k. -l Send the output to a spooler program for printing. The “print” directive in the device description file specifies the default command to be used; see groff_font(5). If no such directive is present for the output device, output is piped to lpr(1). See options -L and -X. -L arg Pass arg to the print spooler program. If multiple args are re‐ quired, pass each with a separate -L option. groff does not prefix an option dash to arg before passing it to the spooler program. -M Works as troff’s option (see below), but is also passed to eqn(1), grap(1), and grn(1). -N Prohibit newlines between eqn delimiters: pass -N to eqn(1). -p Run pic(1) preprocessor. -P arg Pass arg to the postprocessor. If multiple args are required, pass each with a separate -P option. groff does not prefix an option dash to arg before passing it to the postprocessor. -R Run refer(1) preprocessor. No mechanism is provided for passing arguments to refer because most refer options have equivalent language elements that can be specified within the document. -s Run soelim(1) preprocessor. -S Operate in “safer” mode; see -U below for its opposite. For se‐ curity reasons, safer mode is enabled by default. -t Run tbl(1) preprocessor. -T dev Direct troff to format the input for the output device dev. groff then calls an output driver to convert troff’s output to a form appropriate for dev; see subsection “Output devices” below. -U Operate in unsafe mode: pass the -U option to pic and troff. -v --version Write version information for groff and all programs run by it to the standard output stream; that is, the given command line is processed in the usual way, passing -v to the formatter and any pre‐ or postprocessors invoked. -V Output the pipeline that groff would run to the standard output stream, but do not execute it. If given more than once, groff both writes and runs the pipeline. -X Use gxditview(1) instead of the usual postprocessor to (pre)view a document on an X11 display. Combining this option with -Tps uses the font metrics of the PostScript device, whereas the -TX75 and -TX100 options use the metrics of X11 fonts. -Z Disable postprocessing. troff output will appear on the stan‐ dard output stream (unless suppressed with -z); see groff_out(5) for a description of this format. Transparent options The following options are passed as‐is to the formatter program troff(1) and described in more detail in its man page. -a Generate a plain text approximation of the typeset output. -b Write a backtrace to the standard error stream on each error or warning. -c Start with color output disabled. -C Enable AT&T troff compatibility mode; implies -c. -d cs -d name=string Define string. -E Inhibit troff error messages; implies -Ww. -f fam Set default font family. -F dir Search in directory dir for the selected output device’s direc‐ tory of device and font description files. -i Process standard input after the specified input files. -I dir Search dir for input files. -m name Process name.tmac before input files. -M dir Search directory dir for macro files. -n num Number the first page num. -o list Output only pages in list. -r cnumeric‐expression -r register=numeric‐expression Define register. -w name -W name Enable (-w) or inhibit (-W) emission of warnings in category name. -z Suppress formatted device‐independent output of troff. Usage The architecture of the GNU roff system follows that of other device‐ independent roff implementations, comprising preprocessors, macro pack‐ ages, output drivers (or “postprocessors”), a suite of utilities, and the formatter troff at its heart. See roff(7) for a survey of how a roff system works. The front end programs available in the GNU roff system make it easier to use than traditional roffs that required the construction of pipelines or use of temporary files to carry a source document from maintainable form to device‐ready output. The discussion below summa‐ rizes the constituent parts of the GNU roff system. It complements roff(7) with groff‐specific information. Getting started Those who prefer to learn by experimenting or are desirous of rapid feedback from the system may wish to start with a “Hello, world!” docu‐ ment. $ echo "Hello, world!" | groff -Tascii | sed '/^$/d' Hello, world! We used a sed command only to eliminate the 65 blank lines that would otherwise flood the terminal screen. (roff systems were developed in the days of paper‐based terminals with 66 lines to a page.) Today’s users may prefer output to a UTF‐8‐capable terminal. $ echo "Hello, world!" | groff -Tutf8 | sed '/^$/d' Producing PDF, HTML, or TeX’s DVI is also straightforward. The hard part may be selecting a viewer program for the output. $ echo "Hello, world!" | groff -Tpdf > hello.pdf $ evince hello.pdf $ echo "Hello, world!" | groff -Thtml > hello.html $ firefox hello.html $ echo "Hello, world!" | groff -Tdvi > hello.dvi $ xdvi hello.html Using groff as a REPL Those with a programmer’s bent may be pleased to know that they can use groff in a read‐evaluate‐print loop (REPL). Doing so can be handy to verify one’s understanding of the formatter’s behavior and/or the syn‐ tax it accepts. Turning on all warnings with -ww can aid this goal. $ groff -ww -Tutf8 \# This is a comment. Let's define a register. .nr a 1 \# Do integer arithmetic with operators evaluated left‐to‐right. .nr b \n[a]+5/2 \# Let's get the result on the standard error stream. .tm \n[b] 3 \# Now we'll define a string. .ds name Leslie\" This is another form of comment. .nr b (\n[a] + (7/2)) \# Center the next two text input lines. .ce 2 Hi, \*[name]. Your secret number is \n[b]. \# We will see that the division rounded toward zero. It is \# Here's an if‐else control structure. .ie (\n[b] % 2) odd. .el even. \# This trick sets the page length to the current vertical \# position, so that blank lines don't spew when we're done. .pl \n[nl]u  Hi, Leslie. Your secret number is 4. It is even. Paper format In GNU roff, the page dimensions for the formatter troff and for output devices are handled separately. In the formatter, requests are used to set the page length (.pl), page offset (or left margin, .po), and line length (.ll). The right margin is not explicitly configured; the com‐ bination of page offset and line length provides the information neces‐ sary to derive it. The papersize macro package, automatically loaded by troff, provides an interface for configuring page dimensions by con‐ venient names, like “letter” or “A4”; see groff_tmac(5). The format‐ ter’s default in this installation is “letter”. It is up to each macro package to respect the page dimensions config‐ ured in this way. Some offer alternative mechanisms. For each output device, the size of the output medium can be set in its DESC file. Most output drivers also recognize a command‐line option -p to override the default dimensions and an option -l to use landscape orientation. See groff_font(5) for a description of the papersize di‐ rective, which takes an argument of the same form as -p. The output driver’s man page, such as grops(1), may also be helpful. groff uses the command‐line option -P to pass options to output devices; for exam‐ ple, use the following for PostScript output on A4 paper in landscape orientation. groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps Front end The groff program is a wrapper around the troff(1) program. It allows one to specify preprocessors via command‐line options and automatically runs the appropriate postprocessor for the selected output device. Do‐ ing so, the manual construction of pipelines or management of temporary files required of users of traditional roff(7) systems can be avoided. Use the grog(1) program to infer an appropriate groff command line to format a document. Language Input to a roff system is in plain text interleaved with control lines and escape sequences. The combination constitutes a document in one of a family of languages we also call roff; see roff(7) for background. An overview of GNU roff language syntax and features, including lists of all supported escape sequences, requests, and predefined registers, can be found in groff(7). GNU roff extensions to the AT&T troff lan‐ guage, a common subset of roff dialects extant today, are detailed in groff_diff(7). Preprocessors A preprocessor interprets a domain‐specific language that produces roff language output. Frequently, such input is confined to sections or re‐ gions of a roff input file (bracketed with macro calls specific to each preprocessor), which it replaces. Preprocessors therefore often inter‐ pret a subset of roff syntax along with their own language. GNU roff provides reimplementations of most preprocessors familiar to users of AT&T troff; these routinely have extended features and/or require GNU troff to format their output. tbl lays out tables; eqn typesets mathematics; pic draws diagrams; refer processes bibliographic references; soelim preprocesses “sourced” input files; grn renders gremlin(1) diagrams; chem draws chemical structural formulæ using pic; gperl populates groff registers and strings using perl(1); glilypond embeds LilyPond sheet music; and gpinyin eases Mandarin Chinese input using Hanyu Pinyin. A preprocessor unique to GNU roff is preconv(1), which converts various input encodings to something GNU troff can understand. When used, it is run before any other preprocessors. Most preprocessors enclose content between a pair of characteristic to‐ kens. Such a token must occur at the beginning of an input line and use the dot control character. Spaces and tabs must not follow the control character or precede the end of the input line. Deviating from these rules defeats a token’s recognition by the preprocessor. Tokens are generally preserved in preprocessor output and interpreted as macro calls subsequently by troff. The ideal preprocessor is not yet avail‐ able in groff. ┌──────────────┬─────────────────┬────────────────┐ │ preprocessor │ starting token │ ending token │ ├──────────────┼─────────────────┼────────────────┤ │ chem │ .cstart │ .cend │ │ eqn │ .EQ │ .EN │ │ grap │ .G1 │ .G2 │ │ grn │ .GS │ .GE │ │ ideal │ .IS │ .IE │ │ │ │ .IF │ │ pic │ .PS │ .PE │ │ │ │ .PF │ │ │ │ .PY │ │ refer │ .R1 │ .R2 │ │ tbl │ .TS │ .TE │ ├──────────────┼─────────────────┼────────────────┤ │ glilypond │ .lilypond start │ .lilypond stop │ │ gperl │ .Perl start │ .Perl stop │ │ gpinyin │ .pinyin start │ .pinyin stop │ └──────────────┴─────────────────┴────────────────┘ Macro packages Macro files are roff input files designed to produce no output them‐ selves but instead ease the preparation of other roff documents. When a macro file is installed at a standard location and suitable for use by a general audience, it is termed a macro package. Macro packages can be loaded prior to any roff input documents with the -m option. The GNU roff system implements most well‐known macro pack‐ ages for AT&T troff in a compatible way and extends them. These have one‐ or two‐letter names arising from intense practices of naming econ‐ omy in early Unix culture, a laconic approach that led to many of the packages being identified in general usage with the nroff and troff op‐ tion letter used to invoke them, sometimes to punning effect, as with “man” (short for “manual”), and even with the option dash, as in the case of the s package, much better known as ms or even -ms. Macro packages serve a variety of purposes. Some are “full‐service” packages, adopting responsibility for page layout among other fundamen‐ tal tasks, and defining their own lexicon of macros for document compo‐ sition; each such package stands alone and a given document can use at most one. an is used to compose man pages in the format originating in Ver‐ sion 7 Unix (1979); see groff_man(7). It can be specified on the command line as -man. doc is used to compose man pages in the format originating in 4.3BSD‐Reno (1990); see groff_mdoc(7). It can be specified on the command line as -mdoc. e is the Berkeley general‐purpose macro suite, developed as an al‐ ternative to AT&T’s s; see groff_me(7). It can be specified on the command line as -me. m implements the format used by the second‐generation AT&T macro suite for general documents, a successor to s; see groff_mm(7). It can be specified on the command line as -mm. om (invariably called “mom”) is a modern package written by Peter Schaffter specifically for GNU roff. Consult the mom HTML man‐ ual ⟨file:///usr/local/share/doc/groff-1.23.0/html/mom/toc.html⟩ for extensive documentation. She—for mom takes the female pro‐ noun—can be specified on the command line as -mom. s is the original AT&T general‐purpose document format; see groff_ms(7). It can be specified on the command line as -ms. Others are supplemental. For instance, andoc is a wrapper package spe‐ cific to GNU roff that recognizes whether a document uses man or mdoc format and loads the corresponding macro package. It can be specified on the command line as -mandoc. A man(1) librarian program may use this macro file to delegate loading of the correct macro package; it is thus unnecessary for man itself to scan the contents of a document to decide the issue. Many macro files augment the function of the full‐service packages, or of roff documents that do not employ such a package—the latter are sometimes characterized as “raw”. These auxiliary packages are de‐ scribed, along with details of macro file naming and placement, in groff_tmac(5). Formatters The formatter, the program that interprets roff language input, is troff(1). It provides the features of the AT&T troff and nroff pro‐ grams as well as many extensions. The command‐line option -C switches troff into compatibility mode, which tries to emulate AT&T troff as closely as is practical to enable the formatting of documents written for the older system. A shell script, nroff(1), emulates the behavior of AT&T nroff. It at‐ tempts to correctly encode the output based on the locale, relieving the user of the need to specify an output device with the -T option and is therefore convenient for use with terminal output devices, described in the next subsection. GNU troff generates output in a device‐independent, but not device‐ag‐ nostic, page description language detailed in groff_out(5). Output devices troff output is formatted for a particular output device, typically specified by the -T option to the formatter or a front end. If neither this option nor the GROFF_TYPESETTER environment variable is used, the default output device is ps. An output device may be any of the fol‐ lowing. ascii for terminals using the ISO 646 1991:IRV character set and en‐ coding, also known as US‐ASCII. cp1047 for terminals using the IBM code page 1047 character set and encoding. dvi for TeX DVI format. html xhtml for HTML and XHTML output, respectively. latin1 for terminals using the ISO Latin‐1 (ISO 8859‐1) character set and encoding. lbp for Canon CaPSL printers (LBP‐4 and LBP‐8 series laser print‐ ers). lj4 for HP LaserJet4‐compatible (or other PCL5‐compatible) print‐ ers. pdf for PDF output. ps for PostScript output. utf8 for terminals using the ISO 10646 (“Unicode”) character set in UTF‐8 encoding. X75 for previewing with gxditview using 75 dpi resolution and a 10‐point base type size. X75-12 for previewing with gxditview using 75 dpi resolution and a 12‐point base type size. X100 for previewing with gxditview using 100 dpi resolution and a 10‐point base type size. X100-12 for previewing with gxditview using 100 dpi resolution and a 12‐point base type size. Postprocessors Any program that interprets the output of GNU troff is a postprocessor. The postprocessors provided by GNU roff are output drivers, which pre‐ pare a document for viewing or printing. Postprocessors for other pur‐ poses, such as page resequencing or statistical measurement of a docu‐ ment, are conceivable. An output driver supports one or more output devices, each with its own device description file. A device determines its postprocessor with the postpro directive in its device description file; see groff_font(5). The -X option overrides this selection, causing gxditview to serve as the output driver. grodvi(1) provides dvi. grohtml(1) provides html and xhtml. grolbp(1) provides lbp. grolj4(1) provides lj4. gropdf(1) provides pdf. grops(1) provides ps. grotty(1) provides ascii, cp1047, latin1, and utf8. gxditview(1) provides X75, X75-12, X100, and X100-12, and additionally can preview ps. Utilities GNU roff includes a suite of utilities. gdiffmk(1) marks differences between a pair of roff input files. grog(1) infers the groff command a document requires. Several utilities prepare descriptions of fonts, enabling the formatter to use them when producing output for a given device. addftinfo(1) adds information to AT&T troff font description files to enable their use with GNU troff. afmtodit(1) creates font description files for PostScript Type 1 fonts. pfbtops(1) translates a PostScript Type 1 font in PFB (Printer Font Binary) format to PFA (Printer Font ASCII), which can then be inter‐ preted by afmtodit. hpftodit(1) creates font description files for the HP LaserJet 4 family of printers. tfmtodit(1) creates font description files for the TeX DVI device. xtotroff(1) creates font description files for X Window System core fonts. A trio of tools transform material constructed using roff preprocessor languages into graphical image files. eqn2graph(1) converts an eqn equation into a cropped image. grap2graph(1) converts a grap diagram into a cropped image. pic2graph(1) converts a pic diagram into a cropped image. Another set of programs works with the bibliographic data files used by the refer(1) preprocessor. indxbib(1) makes inverted indices for bibliographic databases, speeding lookup operations on them. lkbib(1) searches the databases. lookbib(1) interactively searches the databases. Exit status groff exits with a failure status if there was a problem parsing its arguments and a successful status if either of the options -h or --help was specified. Otherwise, groff runs a pipeline to process its input; if all commands within the pipeline exit successfully, groff does like‐ wise. If not, groff’s exit status encodes a summary of problems en‐ countered, setting bit 0 if a command exited with a failure status, bit 1 if a command was terminated with a signal, and bit 2 if a command could not be executed. (Thus, if all three misfortunes befell one’s pipeline, groff would exit with status 2^0 + 2^1 + 2^2 = 1+2+4 = 7.) To troubleshoot pipeline problems, you may wish to re‐run the groff command with the -V option and break the reported pipeline down into separate stages, inspecting the exit status of and diagnostic messages emitted by each command. Environment Normally, the path separator in environment variables ending with PATH is the colon; this may vary depending on the operating system. For ex‐ ample, Windows uses a semicolon instead. GROFF_BIN_PATH This search path, followed by PATH, is used to locate commands executed by groff. If it is not set, the installation directory of the GNU roff executables, /usr/local/bin, is searched before PATH. GROFF_COMMAND_PREFIX GNU roff can be configured at compile time to apply a prefix to the names of the programs it provides that had a counterpart in AT&T troff, so that name collisions are avoided at run time. The default prefix is empty. When used, this prefix is conventionally the letter “g”. For example, GNU troff would be installed as gtroff. Besides troff, the prefix applies to the formatter nroff; the preprocessors eqn, grn, pic, refer, tbl, and soelim; and the utilities indxbib and lookbib. GROFF_ENCODING The value of this variable is passed to the preconv(1) pre‐ processor’s -e option to select the character encoding of input files. This variable’s existence implies the groff option -k. If set but empty, groff calls preconv without an -e option. groff’s -K option overrides GROFF_ENCODING. GROFF_FONT_PATH Seek the selected output device’s directory of device and font description files in this list of directories. See troff(1) and groff_font(5). GROFF_TMAC_PATH Seek macro files in this list of directories. See troff(1) and groff_tmac(5). GROFF_TMPDIR Create temporary files in this directory. If not set, but the environment variable TMPDIR is set, temporary files are created there instead. On Windows systems, if neither of the foregoing are set, the environment variables TMP and TEMP (in that order) are checked also. Otherwise, temporary files are created in /tmp. The refer(1), grohtml(1), and grops(1) commands use tem‐ porary files. GROFF_TYPESETTER Set the default output device. If empty or not set, ps is used. The -T option overrides GROFF_TYPESETTER. SOURCE_DATE_EPOCH A time stamp (expressed as seconds since the Unix epoch) to use as the output creation time stamp in place of the current time. The time is converted to human‐readable form using localtime(3) when the formatter starts up and stored in registers usable by documents and macro packages. TZ The time zone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human‐readable form; see tzset(3). Examples roff systems are best known for formatting man pages. Once a man(1) librarian program has located a man page, it may execute a groff com‐ mand much like the following. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 The librarian will also pipe the output through a pager, which might not interpret the SGR terminal escape sequences groff emits for bold‐ face, underlining, or italics; see section “Limitations” below. To process a roff input file using the preprocessors tbl and pic and the me macro package in the way to which AT&T troff users were accus‐ tomed, one would type (or script) a pipeline. pic foo.me | tbl | troff -me -Tutf8 | grotty Using groff, this pipe can be shortened to an equivalent command. groff -p -t -me -T utf8 foo.me An even easier way to do this is to use grog(1) to guess the preproces‐ sor and macro options and execute the result by using the command sub‐ stitution feature of the shell. $(grog -Tutf8 foo.me) Each command‐line option to a postprocessor must be specified with any required leading dashes “-” because groff passes the arguments as‐is to the postprocessor; this permits arbitrary arguments to be transmitted. For example, to pass a title to the gxditview postprocessor, the shell commands groff -X -P -title -P 'trial run' mydoc.t and groff -X -Z mydoc.t | gxditview -title 'trial run' - are equivalent. Limitations When paging output for the ascii, cp1047, latin1, and utf8 devices, programs like more(1) and less(1) may require command‐line options to correctly handle some terminal escape sequences; see grotty(1). On EBCDIC hosts such as OS/390 Unix, the output devices ascii and latin1 aren’t available. Conversely, the output device cp1047 is not available on systems based on the ISO 646 or ISO 8859 character encod‐ ing standards. Installation directories GNU roff installs files in varying locations depending on its compile‐ time configuration. On this installation, the following locations are used. /usr/local/lib/X11/app-defaults Application defaults directory for gxditview(1). /usr/local/bin Directory containing groff’s executable commands. /usr/local/share/groff/1.23.0/eign List of common words for indxbib(1). /usr/local/share/groff/1.23.0 Directory for data files. /usr/dict/papers/Ind Default index for lkbib(1) and refer(1). /usr/local/share/doc/groff-1.23.0 Documentation directory. /usr/local/share/doc/groff-1.23.0/examples Example directory. /usr/local/share/groff/1.23.0/font Font directory. /usr/local/share/doc/groff-1.23.0/html HTML documentation directory. /usr/lib/font Legacy font directory. /usr/local/share/groff/site-font Local font directory. /usr/local/share/groff/site-tmac Local macro package (tmac file) directory. /usr/local/share/groff/1.23.0/tmac Macro package (tmac file) directory. /usr/local/share/groff/1.23.0/oldfont Font directory for compatibility with old versions of groff; see grops(1). /usr/local/share/doc/groff-1.23.0/pdf PDF documentation directory. groff macro directory Most macro files supplied with GNU roff are stored in /usr/local/share/ groff/1.23.0/tmac for the installation corresponding to this document. As a rule, multiple directories are searched for macro files; see troff(1). For a catalog of macro files GNU roff provides, see groff_tmac(5). groff device and font description directory Device and font description files supplied with GNU roff are stored in /usr/local/share/groff/1.23.0/font for the installation corresponding to this document. As a rule, multiple directories are searched for de‐ vice and font description files; see troff(1). For the formats of these files, see groff_font(5). Availability Obtain links to groff releases for download, its source repository, discussion mailing lists, a support ticket tracker, and further infor‐ mation from the groff page of the GNU website ⟨http://www.gnu.org/ software/groff⟩. A free implementation of the grap preprocessor, written by Ted Faber ⟨faber@lunabase.org⟩, can be found at the grap website ⟨http://www .lunabase.org/~faber/Vault/software/grap/⟩. groff supports only this grap. Authors groff (both the front‐end command and the overall system) was primarily written by James Clark ⟨jjc@jclark.com⟩. Contributors to this document include Clark, Trent A. Fisher, Werner Lemberg ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web.de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. Introduction, history, and further reading: roff(7) Viewer for groff (and AT&T device‐independent troff) documents: gxditview(1) Preprocessors: chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1), refer(1), soelim(1), tbl(1) Macro packages and package‐specific utilities: groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7), mmroff(1), groff_mom(7), pdfmom(1), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7) Bibliographic database management tools: indxbib(1), lkbib(1), lookbib(1) Language, conventions, and GNU extensions: groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5) Intermediate output language: groff_out(5) Formatter program: troff(1) Formatter wrappers: nroff(1), pdfroff(1) Postprocessors for output devices: grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1) Font support utilities: addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1) Graphics conversion utilities: eqn2graph(1), grap2graph(1), pic2graph(1) Difference‐marking utility: gdiffmk(1) “groff guess” utility: grog(1) groff 1.23.0 29 August 2023 groff(1) ─────────────────────────────────────────────────────────────────────────────── grog(1) General Commands Manual grog(1) Name grog - “groff guess”—infer the groff command a document requires Synopsis grog [--run] [--ligatures] [groff‐option ...] [--] [file ...] grog -h grog --help grog -v grog --version Description grog reads its input and guesses which groff(1) options are needed to render it. If no operands are given, or if file is “-”, grog reads the standard input stream. The corresponding groff command is normally written to the standard output stream. With the option --run, the in‐ ferred command is written to the standard error stream and then exe‐ cuted. Options -h and --help display a usage message, whereas -v and --version display version information; all exit afterward. --ligatures includes the arguments -P-y -PU in the inferred groff command. These are supported only by the pdf output device. --run writes the inferred command to the standard error stream and then executes it. All other specified short options (that is, arguments beginning with a minus sign “-” followed by a letter) are interpreted as groff options or option clusters with or without an option argument. Such options are included in the constructed groff command line. Details grog reads each file operand, pattern‐matching strings that are statis‐ tically likely to be characteristic of roff(7) documents. It tries to guess which of the following groff options are required to correctly render the input: -e, -g, -G, -j, -p, -R, -t (preprocessors); and -man, -mdoc, -mdoc-old, -me, -mm, -mom, and -ms (macro packages). The in‐ ferred groff command including these options and any file parameters is written to the standard output stream. It is possible to specify arbitrary groff options on the command line. These are included in the inferred command without change. Choices of groff options include -C to enable AT&T troff compatibility mode and -T to select a non‐default output device. If the input is not encoded in US‐ASCII, ISO 8859‐1, or IBM code page 1047, specification of a groff option to run the preconv(1) preprocessor is advised; see the -D, -k, and -K options of groff(1). For UTF‐8 input, -k is a good choice. groff may issue diagnostic messages when an inappropriate -m option, or multiple conflicting ones, are specified. Consequently, it is best to specify no -m options to grog unless it cannot correctly infer all of the -m arguments a document requires. A roff document can also be written without recourse to any macro package. In such cases, grog will infer a groff command without an -m option. Limitations grog presumes that the input does not change the escape, control, or no‐break control characters. grog does not parse roff input line con‐ tinuation or control structures (brace escape sequences and the “if”, “ie”, and “el” requests) nor groff’s “while”. Thus the input .if \ t .NH 1 .if n .SH Introduction will conceal the use of the ms macros NH and SH from grog. Such con‐ structions are regarded by grog’s implementors as insufficiently common to cause many inference problems. Preprocessors can be even stricter when matching macro calls that bracket the regions of an input file they replace. pic, for example, requires PS, PE, and PF calls to imme‐ diately follow the default control character at the beginning of a line. Detection of the -s option (the soelim(1) preprocessor) is tricky; to correctly infer its necessity would require grog to recursively open all files given as arguments to the .so request under the same condi‐ tions that soelim itself does so; see its man page. Recall that soelim is necessary only if sourced files need to be preprocessed. Therefore, as a workaround, you may want to run the input through soelim manually, piping it to grog, and compare the output to running grog on the input directly. If the “soelim”ed input causes grog to infer additional pre‐ processor options, then -s is likely necessary. $ printf ".TS\nl.\nI'm a table.\n.TE\n" > 3.roff $ printf ".so 3.roff\n" > 2.roff $ printf ".XP\n.so 2.roff\n" > 1.roff $ grog 1.roff groff -ms 1.roff $ soelim 1.roff | grog groff -t -ms - In the foregoing example, we see that this procedure enabled grog to detect tbl(1) macros, so we would add -s as well as the detected -t op‐ tion to a revised grog or groff command. $ grog -st 1.roff groff -st -ms 1.roff Exit status grog exits with error status 1 if a macro package appears to be in use by the input document, but grog was unable to infer which one, or 2 if there were problems handling an option or operand. It otherwise exits with status 0. (If the --run option is specified, groff’s exit status is discarded.) Inferring no preprocessors or macro packages is not an error condition; a valid roff document need not use either. Even plain text is valid input, if one is mindful of the syntax of the control and escape characters. Examples Running grog /usr/local/share/doc/groff-1.23.0/meintro.me at the command line results in groff -me /usr/local/share/doc/groff-1.23.0/meintro.me because grog recognizes that the file meintro.me is written using macros from the me package. The command grog /usr/local/share/doc/groff-1.23.0/pic.ms outputs groff -e -p -t -ms /usr/local/share/doc/groff-1.23.0/pic.ms on the other hand. Besides discerning the ms macro package, grog rec‐ ognizes that the file pic.ms additionally needs the combination of -t for tbl, -e for eqn, and -p for pic. Consider a file doc/grnexampl.me, which uses the grn preprocessor to include a gremlin(1) picture file in an me document. Let’s say we want to suppress color output, produce a DVI file, and get backtraces for any errors that troff encounters. The command grog -bc -Idoc -Tdvi doc/grnexmpl.me is processed by grog into groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me where we can see that grog has inferred the me macro package along with the eqn and grn preprocessors. (The input file is located in /usr/ local/share/doc/groff-1.23.0 if you’d like to try this example your‐ self.) Authors grog was originally written in Bourne shell by James Clark. The cur‐ rent implementation in Perl was written by Bernd Warken ⟨groff-bernd .warken-72@web.de⟩ and heavily revised by G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also groff(1) groff 1.23.0 29 August 2023 grog(1) ─────────────────────────────────────────────────────────────────────────────── grohtml(1) General Commands Manual grohtml(1) Name grohtml, post-grohtml, pre-grohtml - groff output driver for HTML Synopsis pre-grohtml [-epV] [-a anti‐aliasing‐text‐bits] [-D image‐directory] [-F font‐directory] [-g anti‐aliasing‐graphic‐bits] [-i resolution] [-I image‐stem] [-o image‐vertical‐offset] [-x html‐dialect] troff‐command troff‐argument ... pre-grohtml --help pre-grohtml -v pre-grohtml --version post-grohtml [-bCGhlnrVy] [-F font‐directory] [-j output‐stem] [-s base‐point‐size] [-S heading‐level] [-x html‐dialect] [file ...] post-grohtml --help post-grohtml -v post-grohtml --version Description The GNU roff system’s HTML support consists of a preprocessor, pre-grohtml, and an output driver, post-grohtml; together, they trans‐ late roff(7) documents to HTML. Because a preprocessor is (uniquely) required for this output driver, users should invoke grohtml via the groff(1) command with the -Thtml or -Txhtml options. (In this instal‐ lation, ps is the default output device.) Use groff’s -P option to pass any options shown above to grohtml. If no operands are given, or if file is “-”, grohtml reads the standard input stream. Output is written to the standard output stream. grohtml invokes groff twice. In the first pass, the preprocessor pre-grohtml renders pictures, equations, and tables as images in Post‐ Script format using the ps output device. In the second pass, the out‐ put driver post-grohtml translates the output of troff(1) to HTML. grohtml writes output encoded in UTF‐8 and has built‐in HTML entities for all non‐composite Unicode characters. In spite of this, groff may issue warnings about unknown special characters if they can’t be found during the first pass. Such warnings can be safely ignored unless the special characters appear inside a table or equation. Typefaces grohtml supports the standard four styles: R (roman), I (italic), B (bold), and BI (bold‐italic). Fonts are grouped into families T and C having members in each style. TR Times roman TI Times italic TB Times bold TBI Times bold‐italic CR Courier roman CI Courier italic CB Courier bold CBI Courier bold‐italic A special font, S, is also provided to accommodate roff documents that expect it to always be available. Font description files The font description files used with grohtml expose the same glyph repertoire in their charset sections. See groff_font(5). Dependencies pre-grohtml generates an image whenever an eqn equation, tbl table, or pic picture is encountered in the input. grohtml therefore may run several commands as part of its operation. These include the Netpbm tools pnmcrop, pnmcut, and pnmtopng; Ghostscript (gs); and the PSUtils tool psselect. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -a anti‐aliasing‐text‐bits Number of bits of antialiasing information to be used by text when generating PNG images. The default is 4 but 0, 1, and 2 are also valid. Your system’s version of gs must support the -dTextAlphaBits option in order to exploit antialiasing. A value of 0 stops grohtml from issuing antialiasing commands to gs. -b Initialize the background color to white. -C Suppress output of “CreationDate:” HTML comment. -D image‐directory Instruct grohtml to place all image files into directory image‐ directory. -e Direct eqn to produce MathML. This option should not be manually specified; it is synthesized by groff depending on whether it was given the -Thtml or -Txhtml option. -F font‐directory Prepend directory font‐directory/devname to the search path for font and device description files; name is the name of the de‐ vice, usually html. -g anti‐aliasing‐graphic‐bits Number of bits of antialiasing information to be used by graph‐ ics when generating PNG images. The default is 4 but 0, 1, and 2 are also valid. Your system’s version of gs must support the -dGraphicAlphaBits option in order to exploit antialiasing. A value of 0 stops grohtml from issuing antialiasing commands to gs. -G Suppress output of “Creator:” HTML comment. -h Generate section headings by using HTML B elements and increas‐ ing the font size, rather than HTML H elements. -i resolution Set the image resolution in pixels per inch; the default is 100. -I image‐stem Determine the image file name stem. If omitted, grohtml uses grohtml-XXXXX (where XXXXX is the process ID). A dash is ap‐ pended to the stem to separate it from the following image num‐ ber. -j output‐stem Instruct grohtml to split the HTML output into multiple files. Output is written to a new file at each section heading (but see option -S below) named output‐stem-n.html. -l Turn off the production of automatic section links at the top of the document. -n Generate simple heading anchors whenever a section/number head‐ ing is found. Without the option the anchor value is the tex‐ tual heading. This can cause problems when a heading contains a “?” on older versions of some browsers. This feature is auto‐ matically enabled if a heading contains an image. -o image‐vertical‐offset Specify the vertical offset of images in points. -p Display page rendering progress to the standard error stream. grohtml displays a page number only when an image is required. -r Turn off the automatic header and footer line (HTML rule). -s base‐type‐size Set the document’s base type size in points. When this size is used in the source, it corresponds to the HTML base type size. Every increase of two points in the source will produce a “big” element, and conversely when a decrease of two points is seen, a “small” element is emitted. -S heading‐level When splitting HTML output (see option -j above), split at each nested heading level defined by heading‐level, or higher). The default is 1. -V Create an XHTML or HTML validator button at the bottom of each page of the document. -x html‐dialect Select HTML dialect. Currently, html‐dialect should be either the digit 4 or the letter x, which indicates whether grohtml should generate HTML 4 or XHTML, respectively. This option should not be manually specified; it is synthesized by groff depending on whether it was given the -Thtml or -Txhtml option. -y Produce a right‐aligned groff signature at the end of the docu‐ ment (only if -V is also specified). Environment GROFF_FONT_PATH lists directories in which to search for devhtml, grohtml’s di‐ rectory of device and font description files. See troff(1) and groff_font(5). SOURCE_DATE_EPOCH A timestamp (expressed as seconds since the Unix epoch) to use as the output creation timestamp in place of the current time. The time is converted to human‐readable form using ctime(3) and recorded in an HTML comment. TZ The time zone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human‐readable form; see tzset(3). Files /usr/local/share/groff/1.23.0/font/devhtml/DESC describes the html output device. /usr/local/share/groff/1.23.0/font/devhtml/F describes the font known as F on device html. /usr/local/share/groff/1.23.0/tmac/html.tmac defines font mappings, special characters, and colors for use with the html output device. It is automatically loaded by troffrc when either of the html or xhtml output devices is se‐ lected. /usr/local/share/groff/1.23.0/tmac/html-end.tmac finalizes setup of the html output device. It is automatically loaded by troffrc-end when either of the html or xhtml output devices is selected. grohtml uses temporary files. See groff(1) for details about where such files are created. Bugs grohtml is still beta code. grohtml does not truly support hyphenation, but you can fool it into hyphenating long input lines, which can appear in HTML output with a hyphenated word followed by a space but no line break. See also groff(1), troff(1), groff_font(5) groff 1.23.0 29 August 2023 grohtml(1) ─────────────────────────────────────────────────────────────────────────────── grolbp(1) General Commands Manual grolbp(1) Name grolbp - groff output driver for Canon CaPSL printers Synopsis grolbp [-l] [-c num‐copies] [-F font‐directory] [-o orientation] [-p paper‐format] [-w width] [file ...] grolbp [--copies=num‐copies] [--fontdir=font‐directory] [--landscape] [--linewidth=width] [--orientation=orientation] [--papersize=paper‐format] [file ...] grolbp -h grolbp --help grolbp -v grolbp --version Description This GNU roff output driver translates the output of troff(1) into a CaPSL and VDM format suitable for Canon LBP‐4 and LBP‐8 printers. Nor‐ mally, grolbp is invoked by groff(1) when the latter is given the “-T lbp” option. (In this installation, ps is the default output de‐ vice.) Use groff’s -P option to pass any options shown above to grolbp. If no file arguments are given, or if file is “-”, grolbp reads the standard input stream. Output is written to the standard output stream. Typefaces The driver supports the Dutch, Swiss, and Swiss‐Narrow scalable type‐ faces, each in the regular, bold, italic, and bold‐italic styles. Ad‐ ditionally, the bitmapped, monospaced Courier and Elite typefaces are available in regular, bold, and italic styles; Courier at 8 and 12 points, Elite at 8 and 10 points. The following chart summarizes the groff font names used to access them. ┌───────────────┬─────────┬────────┬──────────┬──────────────┐ │ Typeface │ Roman │ Bold │ Italic │ Bold‐Italic │ ├───────────────┼─────────┼────────┼──────────┼──────────────┤ │ Dutch │ TR │ TB │ TI │ TBI │ ├───────────────┼─────────┼────────┼──────────┼──────────────┤ │ Swiss │ HR │ HB │ HI │ HBI │ ├───────────────┼─────────┼────────┼──────────┼──────────────┤ │ Swiss Narrow │ HNR │ HNB │ HNI │ HNBI │ ├───────────────┼─────────┼────────┼──────────┼──────────────┤ │ Courier │ CR │ CB │ CI │ │ ├───────────────┼─────────┼────────┼──────────┼──────────────┤ │ Elite │ ER │ EB │ EI │ │ └───────────────┴─────────┴────────┴──────────┴──────────────┘ Paper format, orientation, and device description file grolbp supports paper formats “A4”, “letter”, “legal”, and “executive”. These are matched case‐insensitively. The -p, --papersize option over‐ rides any setting in the device description file DESC. If neither specifies a paper format, A4 is assumed. In its DESC file, grolbp (case‐insensitively) recognizes an orientation directive accepting one mandatory argument, portrait or landscape. The first valid orientation directive encountered controls. The -l, -o, and --orientation command‐line options override any setting in DESC. If none of the foregoing specify the orientation, portrait is assumed. Font description files In addition to the font description file directives documented in groff_font(5), grolbp recognizes lbpname, which maps the groff font name to the font name used internally by the printer. Its syntax is as follows. lbpname printer‐font‐name lbpname’s argument is case‐sensitive. The printer’s font names are en‐ coded as follows. For bitmapped fonts, printer‐font_name has the form N⟨base‐font‐name⟩⟨font‐style⟩ base‐font‐name is the font name as it appears in the printer’s font listings without the first letter, up to (but not including) the font size. font‐style can be one of the letters R, I, or B, indicating the roman, italic, and bold styles, respectively. For instance, if the printer’s “font listing A” shows “Nelite12I.ISO_USA”, the corresponding entry in the groff font description file is lbpname NeliteI You may need to modify grolbp to add support for new bitmapped fonts, since the available font names and font sizes of bitmapped fonts (as documented above) are hard‐coded into the program. For scalable fonts, printer‐font‐name is identical to the font name as it appears in the printer’s “font listing A”. For instance, to select the “Swiss” font in bold‐italic style, which appears in the font list‐ ing as “Swiss-BoldOblique”, lbpname Swiss-BoldOblique is the required directive, and this is what we find in the groff font description file HBI for the lbp device. Drawing commands For compatibility with grolj4(1), an additional drawing command is available. \D'R dh dv' Draw a rule (solid black rectangle) with one corner at the draw‐ ing position, and the diagonally opposite corner at the drawing position +(dh,dv). Options -h and --help display a usage message, while -v and --version show ver‐ sion information; all exit afterward. -c num‐copies --copies=num‐copies Produce num‐copies copies of each page. -F font‐directory --fontdir=font‐directory Prepend directory font‐directory/devname to the search path for font and device description files; name is the name of the de‐ vice, usually lbp. -l --landscape Format the document in landscape orientation. -o orientation --orientation=orientation Format the document in the given orientation, which must be “portrait” or “landscape”. -p paper‐format --papersize=paper‐format Set the paper format to paper‐format, which must be a valid pa‐ per format as described above. -w width --linewidth=width Set the default line thickness to width thousandths of an em; the default is 40 (0.04 em). Environment GROFF_FONT_PATH lists directories in which to seek the selected output device’s directory of device and font description files. See troff(1) and groff_font(5). Files /usr/local/share/groff/1.23.0/font/devlbp/DESC describes the lbp output device. /usr/local/share/groff/1.23.0/font/devlbp/F describes the font known as F on device lbp. /usr/local/share/groff/1.23.0/tmac/lbp.tmac defines macros for use with the lbp output device. It is auto‐ matically loaded by troffrc when the lbp output device is se‐ lected. See also groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7) groff 1.23.0 29 August 2023 grolbp(1) ─────────────────────────────────────────────────────────────────────────────── grolj4(1) General Commands Manual grolj4(1) Name grolj4 - groff output driver for HP LaserJet 4 and compatible printers Synopsis grolj4 [-l] [-c num‐copies] [-d [n]] [-F font‐directory] [-p paper‐ format] [-w line‐width] [file ...] grolj4 --help grolj4 -v grolj4 --version Description This GNU roff output driver translates the output of troff(1) into a PCL5 format suitable for an HP LaserJet 4 printer. Normally, grolj4 is invoked by groff(1) when the latter is given the “-T lj4” option. (In this installation, ps is the default output device.) Use groff’s -P option to pass any options shown above to grolj4. If no file arguments are given, or if file is “-”, grolj4 reads the standard input stream. Output is written to the standard output stream. Typefaces grolj4 supports the standard four styles: R (roman), I (italic), B (bold), and BI (bold‐italic). Fonts are grouped into families A, C, G, O, T, TN, U, and UC having members in each style. AB Arial Bold ABI Arial Bold Italic AI Arial Italic AR Arial Roman CB Courier Bold CBI Courier Bold Italic CI Courier Italic CR Courier Roman GB Garamond Halbfett GBI Garamond Kursiv Halbfett GI Garamond Kursiv GR Garamond Antiqua OB CG Omega Bold OBI CG Omega Bold Italic OI CG Omega Italic OR CG Omega Roman OB CG Omega Bold OBI CG Omega Bold Italic OI CG Omega Italic OR CG Omega Roman TB CG Times Bold TBI CG Times Bold Italic TI CG Times Italic TR CG Times Roman TNRB M Times Bold TNRBI M Times Bold Italic TNRI M Times Italic TNRR M Times Roman UB Univers Bold UBI Univers Bold Italic UI Univers Medium Italic UR Univers Medium UCB Univers Condensed Bold UCBI Univers Condensed Bold Italic UCI Univers Condensed Medium Italic UCR Univers Condensed Medium The following fonts are not members of a family. ALBB Albertus Extra Bold ALBR Albertus Medium AOB Antique Olive Bold AOI Antique Olive Italic AOR Antique Olive Roman CLARENDON Clarendon CORONET Coronet LGB Letter Gothic Bold LGI Letter Gothic Italic LGR Letter Gothic Roman MARIGOLD Marigold The special font is S (PostScript Symbol); SYMBOL (M Symbol), and WINGDINGS (Wingdings) are also available but not mounted by default. Paper format and device description file grolj4 supports paper formats “A4”, “B5”, “C5”, “com10”, “DL”, “executive”, “legal”, “letter”, and “monarch”. These are matched case‐ insensitively. The -p option overrides any setting in the device de‐ scription file DESC. If neither specifies a paper format, “letter” is assumed. Font description files grolj4 recognizes four font description file directives in addition to those documented in groff_font(5). pclweight n Set the stroke weight to n, an integer in the range -7 to +7; the default is 0. pclstyle n Set the style to n, an integer in the range 0 to 32767; the de‐ fault is 0. pclproportional n Set the proportional spacing Boolean flag to n, which can be ei‐ ther 0 or 1; the default is 0. pcltypeface n Set the typeface family to n, an integer in the range 0 to 65535; the default is 0. Drawing commands An additional drawing command is recognized as an extension to those documented in groff(7). \D'R dh dv' Draw a rule (solid black rectangle) with one corner at the draw‐ ing position, and the diagonally opposite corner at the drawing position +(dh,dv), at which the drawing position will be after‐ ward. This generates a PCL fill rectangle command, and so will work on printers that do not support HP‐GL/2, unlike the other \D commands. Fonts Nominally, all Hewlett‐Packard LaserJet 4‐series and newer printers have the same internal fonts: 45 scalable fonts and one bitmapped Lineprinter font. The scalable fonts are available in sizes between 0.25 points and 999.75 points, in 0.25‐point increments; the Lineprinter font is available only in 8.5‐point size. The LaserJet font files included with groff assume that all printers since the LaserJet 4 are identical. There are some differences between fonts in the earlier and more recent printers, however. The LaserJet 4 printer used Agfa Intellifont technology for 35 of the internal scal‐ able fonts; the remaining 10 scalable fonts were TrueType. Beginning with the LaserJet 4000‐series printers introduced in 1997, all scalable internal fonts have been TrueType. The number of printable glyphs dif‐ fers slightly between Intellifont and TrueType fonts (generally, the TrueType fonts include more glyphs), and there are some minor differ‐ ences in glyph metrics. Differences among printer models are described in the PCL 5 Comparison Guide and the PCL 5 Comparison Guide Addendum (for printers introduced since approximately 2001). LaserJet printers reference a glyph by a combination of a 256‐glyph symbol set and an index within that symbol set. Many glyphs appear in more than one symbol set; all combinations of symbol set and index that reference the same glyph are equivalent. For each glyph, hpftodit(1) searches a list of symbol sets, and selects the first set that contains the glyph. The printing code generated by hpftodit is an integer that encodes a numerical value for the symbol set in the high byte(s), and the index in the low byte. See groff_font(5) for a complete descrip‐ tion of the font file format; symbol sets are described in greater de‐ tail in the PCL 5 Printer Language Technical Reference Manual. Two of the scalable fonts, Symbol and Wingdings, are bound to 256‐glyph symbol sets; the remaining scalable fonts, as well as the Lineprinter font, support numerous symbol sets, sufficient to enable printing of more than 600 glyphs. The metrics generated by hpftodit assume that the DESC file contains values of 1200 for res and 6350 for unitwidth, or any combination (e.g., 2400 and 3175) for which res × unitwidth = 7620000. Although HP PCL 5 LaserJet printers support an internal resolution of 7200 units per inch, they use a 16‐bit signed integer for positioning; if devlj4 is to support U.S. ledger paper (11 in × 17 in; in = inch), the maximum usable resolution is 32767 ÷ 17, or 1927 units per inch, which rounds down to 1200 units per inch. If the largest required paper dimension is less (e.g., 8.5 in × 11 in, or A5), a greater res (and lesser unitwidth) can be specified. Font metrics for Intellifont fonts were provided by Tagged Font Metric (TFM) files originally developed by Agfa/Compugraphic. The TFM files provided for these fonts supported 600+ glyphs and contained extensive lists of kerning pairs. To accommodate developers who had become accustomed to TFM files, HP also provided TFM files for the 10 TrueType fonts included in the LaserJet 4. The TFM files for TrueType fonts generally included less information than the Intellifont TFMs, supporting fewer glyphs, and in most cases, providing no kerning information. By the time the Laser‐ Jet 4000 printer was introduced, most developers had migrated to other means of obtaining font metrics, and support for new TFM files was very limited. The TFM files provided for the TrueType fonts in the Laser‐ Jet 4000 support only the Latin 2 (ISO 8859‐2) symbol set, and include no kerning information; consequently, they are of little value for any but the most rudimentary documents. Because the Intellifont TFM files contain considerably more informa‐ tion, they generally are preferable to the TrueType TFM files even for use with the TrueType fonts in the newer printers. The metrics for the TrueType fonts are very close, though not identical, to those for the earlier Intellifont fonts of the same names. Although most output us‐ ing the Intellifont metrics with the newer printers is quite accept‐ able, a few glyphs may fail to print as expected. The differences in glyph metrics may be particularly noticeable with composite parenthe‐ ses, brackets, and braces used by eqn(1). A script, located in /usr/ local/share/groff/1.23.0/font/devlj4/generate, can be used to adjust the metrics for these glyphs in the special font “S” for use with printers that have all TrueType fonts. At the time HP last supported TFM files, only version 1.0 of the Uni‐ code standard was available. Consequently, many glyphs lacking as‐ signed code points were assigned by HP to the Private Use Area (PUA). Later versions of the Unicode standard included code points outside the PUA for many of these glyphs. The HP‐supplied TrueType TFM files use the PUA assignments; TFM files generated from more recent TrueType font files require the later Unicode values to access the same glyphs. Con‐ sequently, two different mapping files may be required: one for the HP‐ supplied TFM files, and one for more recent TFM files. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -c num‐copies Format num‐copies copies of each page. -d [n] Use duplex mode n: 1 is long‐side binding (default), and 2 is short‐side binding. -F font‐directory Prepend directory font‐directory/devname to the search path for font and device description files; name is the name of the de‐ vice, usually lj4. -l Format the document in landscape orientation. -p paper‐format Set the paper format to paper‐format, which must be a valid pa‐ per format as described above. -w line‐width Set the default line thickness to line‐width thousandths of an em; the default is 40 (0.04 em). Environment GROFF_FONT_PATH lists directories in which to seek the selected output device’s directory of device and font description files. See troff(1) and groff_font(5). Files /usr/local/share/groff/1.23.0/font/devlj4/DESC describes the lj4 output device. /usr/local/share/groff/1.23.0/font/devlj4/F describes the font known as F on device lj4. /usr/local/share/groff/1.23.0/tmac/lj4.tmac defines macros for use with the lj4 output device. It is auto‐ matically loaded by troffrc when the lj4 output device is se‐ lected. Bugs Small dots. See also HP PCL/PJL Reference: PCL 5 Printer Language Technical Reference Man‐ ual, Part I ⟨http://www.hp.com/ctg/Manual/bpl13210.pdf⟩ hpftodit(1), groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7) groff 1.23.0 29 August 2023 grolj4(1) ─────────────────────────────────────────────────────────────────────────────── gropdf(1) General Commands Manual gropdf(1) Name gropdf - groff output driver for Portable Document Format Synopsis gropdf [-dels] [-F font‐directory] [-I inclusion‐directory] [-p paper‐ format] [-u [cmap‐file]] [-y foundry] [file ...] gropdf --help gropdf -v gropdf --version Description The GNU roff PDF output driver translates the output of troff(1) into Portable Document Format. Normally, gropdf is invoked by groff(1) when the latter is given the “-T pdf” option. (In this installation, ps is the default output device.) Use groff’s -P option to pass any options shown above to gropdf. If no file arguments are given, or if file is “-”, gropdf reads the standard input stream. Output is written to the standard output stream. See section “Font installation” below for a guide to installing fonts for gropdf. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -d Include debug information as comments within the PDF. Also pro‐ duces an uncompressed PDF. -e Forces gropdf to embed all fonts (even the 14 base PDF fonts). -F dir Prepend directory dir/devname to the search path for font, and device description files; name is the name of the device, usu‐ ally pdf. -I dir Search the directory dir for files named in \X'pdf: pdfpic' de‐ vice control commands. -I may be specified more than once; each dir is searched in the given order. To search the current work‐ ing directory before others, add “-I .” at the desired place; it is otherwise searched last. -l Orient the document in landscape format. -p paper‐format Set the physical dimensions of the output medium. This over‐ rides the papersize, paperlength, and paperwidth directives in the DESC file; it accepts the same arguments as the papersize directive. See groff_font(5) for details. -s Append a comment line to end of PDF showing statistics, i.e. number of pages in document. Ghostscript’s ps2pdf complains about this line if it is included, but works anyway. -u [cmap‐file] gropdf normally includes a ToUnicode CMap with any font created using text.enc as the encoding file, this makes it easier to search for words which contain ligatures. You can include your own CMap by specifying a cmap‐file or have no CMap at all by omitting the argument. -y foundry Set the foundry to use for selecting fonts of the same name. Usage The input to gropdf must be in the format output by troff(1). This is described in groff_out(5). In addition, the device and font descrip‐ tion files for the device used must meet certain requirements: The res‐ olution must be an integer multiple of 72 times the sizescale. The pdf device uses a resolution of 72000 and a sizescale of 1000. The device description file must contain a valid paper format; see groff_font(5). gropdf uses the same Type 1 Adobe PostScript fonts as the grops device driver. Although the PDF Standard allows the use of other font types (like TrueType) this implementation only accepts the Type 1 PostScript font. Fewer Type 1 fonts are supported natively in PDF documents than the standard 35 fonts supported by grops and all PostScript printers, but all the fonts are available since any which aren’t supported natively are automatically embedded in the PDF. gropdf supports the concept of foundries, that is different versions of basically the same font. During install a Foundry file controls where fonts are found and builds groff fonts from the files it discovers on your system. Each font description file must contain a command internalname psname which says that the PostScript name of the font is psname. Lines starting with # and blank lines are ignored. The code for each charac‐ ter given in the font file must correspond to the code in the default encoding for the font. This code can be used with the \N escape se‐ quence in troff to select the character, even if the character does not have a groff name. Every character in the font file must exist in the PostScript font, and the widths given in the font file must match the widths used in the PostScript font. Note that gropdf is currently only able to display the first 256 glyphs in any font. This restriction will be lifted in a later version. gropdf can automatically include the downloadable fonts necessary to print the document. Fonts may be in PFA or PFB format. Any downloadable fonts which should, when required, be included by gropdf must be listed in the file /usr/local/share/groff/1.23.0/font/ devpdf/download; this should consist of lines of the form foundry font filename where foundry is the foundry name or blank for the default foundry. font is the PostScript name of the font, and filename is the name of the file containing the font; lines beginning with # and blank lines are ignored; fields must be separated by tabs (spaces are not allowed); filename is searched for using the same mechanism that is used for groff font metric files. The download file itself is also sought using this mechanism. Foundry names are usually a single character (such as ‘U’ for the URW foundry) or empty for the default foundry. This de‐ fault uses the same fonts as ghostscript uses when it embeds fonts in a PDF file. In the default setup there are styles called R, I, B, and BI mounted at font positions 1 to 4. The fonts are grouped into families A, BM, C, H, HN, N, P, and T having members in each of these styles: AR AvantGarde‐Book AI AvantGarde‐BookOblique AB AvantGarde‐Demi ABI AvantGarde‐DemiOblique BMR Bookman‐Light BMI Bookman‐LightItalic BMB Bookman‐Demi BMBI Bookman‐DemiItalic CR Courier CI Courier‐Oblique CB Courier‐Bold CBI Courier‐BoldOblique HR Helvetica HI Helvetica‐Oblique HB Helvetica‐Bold HBI Helvetica‐BoldOblique HNR Helvetica‐Narrow HNI Helvetica‐Narrow‐Oblique HNB Helvetica‐Narrow‐Bold HNBI Helvetica‐Narrow‐BoldOblique NR NewCenturySchlbk‐Roman NI NewCenturySchlbk‐Italic NB NewCenturySchlbk‐Bold NBI NewCenturySchlbk‐BoldItalic PR Palatino‐Roman PI Palatino‐Italic PB Palatino‐Bold PBI Palatino‐BoldItalic TR Times‐Roman TI Times‐Italic TB Times‐Bold TBI Times‐BoldItalic There is also the following font which is not a member of a family: ZCMI ZapfChancery‐MediumItalic There are also some special fonts called S for the PS Symbol font. The lower case greek characters are automatically slanted (to match the SymbolSlanted font (SS) available to PostScript). Zapf Dingbats is available as ZD; the “hand pointing left” glyph (\[lh]) is available since it has been defined using the \X'pdf: xrev' device control com‐ mand, which reverses the direction of letters within words. The default color for \m and \M is black. gropdf understands some of the device control commands supported by grops(1). \X'ps: invis' Suppress output. \X'ps: endinvis' Stop suppressing output. \X'ps: exec gsave currentpoint 2 copy translate n rotate neg exch neg exch translate' where n is the angle of rotation. This is to support the align command in pic(1). \X'ps: exec grestore' Used by pic(1) to restore state after rotation. \X'ps: exec n setlinejoin' where n can be one of the following values. 0 = Miter join 1 = Round join 2 = Bevel join \X'ps: exec n setlinecap' where n can be one of the following values. 0 = Butt cap 1 = Round cap, and 2 = Projecting square cap \X'ps: ... pdfmark' All the pdfmark macros installed by using -m pdfmark or -m mspdf (see documentation in pdfmark.pdf). A subset of these macros are installed automatically when you use -Tpdf so you should not need to use “-m pdfmark” to access most PDF functionality. gropdf also supports a subset of the commands introduced in present.tmac. Specifically it supports:‐ PAUSE BLOCKS BLOCKE Which allows you to create presentation type PDFs. Many of the other commands are already available in other macro packages. These commands are implemented with groff X commands:‐ \X'ps: exec %%%%PAUSE' The section before this is treated as a block and is introduced using the current BLOCK transition setting (see “\X'pdf: transi‐ tion'” below). Equivalently, .pdfpause is available as a macro. \X'ps: exec %%%%BEGINONCE' Any text following this command (up to %%%%ENDONCE) is shown only once, the next %%%%PAUSE will remove it. If producing a non‐presentation PDF, i.e. ignoring the pauses, see GROPDF_NOSLIDE below, this text is ignored. \X'ps: exec %%%%ENDONCE' This terminates the block defined by %%%%BEGINONCE. This pair of commands is what implements the .BLOCKS Once/.BLOCKE commands in present.tmac. The mom macro package already integrates these extensions, so you can build slides with mom. If you use present.tmac with gropdf there is no need to run the program presentps(1) since the output will already be a presentation PDF. All other ps: tags are silently ignored. One \X device control command used by the DVI driver is also recog‐ nised. \X'papersize=paper‐format' where the paper‐format parameter is the same as that to the pa‐ persize directive. See groff_font(5). This means that you can alter the page size at will within the PDF file being created by gropdf. If you do want to change the paper format, it must be done before you start creating the page. gropdf supports several more device control features using the pdf: tag. Some have counterpart convenience macros that take the same argu‐ ments and behave equivalently. \X'pdf: pdfpic file alignment width height line‐length' Place an image of the specified width containing the PDF drawing from file file of desired width and height (if height is missing or zero then it is scaled proportionally). If alignment is -L the drawing is left‐aligned. If it is -C or -R a line‐length greater than the width of the drawing is required as well. If width is specified as zero then the width is scaled in propor‐ tion to the height. \X'pdf: xrev' Toggle the reversal of glyph direction. This feature works “letter by letter”, that is, each letter in a word is reversed left‐to‐right, not the entire word. One application is the re‐ versal of glyphs in the Zapf Dingbats font. To restore the nor‐ mal glyph orientation, repeat the command. \X'pdf: markstart /ANN‐definition' \X'pdf: markend' Macros that support PDF bookmarks use these calls internally to start and stop (respectively) the placement of the bookmark’s hot spot; the user will have called “.pdfhref L” with the text of the hot spot. Normally, these are never used except from within the pdfmark macros. \X'pdf: marksuspend' \X'pdf: markrestart' If you use a page location trap to produce a header or footer, or otherwise interrupt a document’s text, you need to use these commands if a PDF hot spot crosses a trap boundary; otherwise any text output by the trap will be marked as part of the hot spot. To prevent this error, place these device control com‐ mands or their corresponding convenience macros .pdfmarksuspend and .pdfmarkrestart at the start and end of the trap macro, re‐ spectively. \X'pdf: pagename name' Assign the current page a name. All documents bear two default names, ‘top’ and ‘bottom’. The convenience macro for this com‐ mand is .pdfpagename. \X’pdf: switchtopage when name' Normally each new page is appended to the end of the document, this command allows following pages to be inserted at a ‘named’ position within the document (see pagename command above). ‘when’ can be either ‘after’ or ‘before’. If it is omitted it defaults to ‘before’. It should be used at the end of the page before you want the switch to happen. This allows pages such as a TOC to be moved to elsewhere in the document, but more eso‐ teric uses are possible. The convenience macro for this command is .pdfswitchtopage. \X'pdf: transition feature mode duration dimension motion direction scale bool' where feature can be either SLIDE or BLOCK. When it is SLIDE the transition is used when a new slide is introduced to the screen, if BLOCK then this transition is used for the individual blocks which make up the slide. mode is the transition type between slides:‐ Split ‐ Two lines sweep across the screen, revealing the new page. The lines may be either horizontal or vertical and may move inward from the edges of the page or outward from the center, as specified by the dimension and motion entries, respectively. Blinds ‐ Multiple lines, evenly spaced across the screen, synchronously sweep in the same direction to reveal the new page. The lines may be either horizontal or verti‐ cal, as specified by the dimension entry. Horizontal lines move downward; vertical lines move to the right. Box ‐ A rectangular box sweeps inward from the edges of the page or outward from the center, as specified by the motion entry, revealing the new page. Wipe ‐ A single line sweeps across the screen from one edge to the other in the direction specified by the di‐ rection entry, revealing the new page. Dissolve ‐ The old page dissolves gradually to reveal the new one. Glitter ‐ Similar to Dissolve, except that the effect sweeps across the page in a wide band moving from one side of the screen to the other in the direction speci‐ fied by the direction entry. R ‐ The new page simply replaces the old one with no spe‐ cial transition effect; the direction entry shall be ig‐ nored. Fly ‐ (PDF 1.5) Changes are flown out or in (as specified by motion), in the direction specified by direction, to or from a location that is offscreen except when direc‐ tion is None. Push ‐ (PDF 1.5) The old page slides off the screen while the new page slides in, pushing the old page out in the direction specified by direction. Cover ‐ (PDF 1.5) The new page slides on to the screen in the direction specified by direction, covering the old page. Uncover ‐ (PDF 1.5) The old page slides off the screen in the direction specified by direction, uncovering the new page in the direction specified by direction. Fade ‐ (PDF 1.5) The new page gradually becomes visible through the old one. duration is the length of the transition in seconds (default 1). dimension (Optional; Split and Blinds transition styles only) The dimension in which the specified transition effect shall oc‐ cur: H Horizontal, or V Vertical. motion (Optional; Split, Box and Fly transition styles only) The direction of motion for the specified transition effect: I In‐ ward from the edges of the page, or O Outward from the center of the page. direction (Optional; Wipe, Glitter, Fly, Cover, Uncover and Push transition styles only) The direction in which the specified transition effect shall moves, expressed in degrees counter‐ clockwise starting from a left‐to‐right direction. If the value is a number, it shall be one of: 0 = Left to right, 90 = Bottom to top (Wipe only), 180 = Right to left (Wipe only), 270 = Top to bottom, 315 = Top‐left to bottom‐right (Glitter only) The value can be None, which is relevant only for the Fly transition when the value of scale is not 1.0. scale (Optional; PDF 1.5; Fly transition style only) The start‐ ing or ending scale at which the changes shall be drawn. If mo‐ tion specifies an inward transition, the scale of the changes drawn shall progress from scale to 1.0 over the course of the transition. If motion specifies an outward transition, the scale of the changes drawn shall progress from 1.0 to scale over the course of the transition bool (Optional; PDF 1.5; Fly transition style only) If true, the area that shall be flown in is rectangular and opaque. This command can be used by calling the macro .pdftransition us‐ ing the parameters described above. Any of the parameters may be replaced with a "." which signifies the parameter retains its previous value, also any trailing missing parameters are ig‐ nored. Note: not all PDF Readers support any or all these transitions. \X'pdf: background cmd left top right bottom weight' \X'pdf: background off' \X'pdf: background footnote bottom' produces a background rectangle on the page, where cmd is the command, which can be any of “page|fill|box” in combination. Thus, “pagefill” would draw a rectangle which covers the whole current page size (in which case the rest of the parameters can be omitted because the box dimensions are taken from the current media size). “box‐ fill”, on the other hand, requires the given dimensions to place the box. Including “fill” in the command will paint the rectangle with the current fill colour (as with \M[]) and including “box” will give the rectangle a bor‐ der in the current stroke colour (as with \m[]). cmd may also be “off” on its own, which will terminate drawing the current box. If you have specified a page colour with “pagefill”, it is always the first box in the stack, and if you specify it again, it will replace the first entry. Be aware that the “pagefill” box renders the page opaque, so tools that “watermark” PDF pages are unlikely to be successful. To return the background to transparent, issue an “off” command with no other boxes open. Finally, cmd may be “footnote” followed by a new value for bottom, which will be used for all open boxes on the current page. This is to allow room for footnote areas that grow while a page is processed (to accommodate mul‐ tiple footnotes, for instance). (If the value is nega‐ tive, it is used as an offset from the bottom of the page.) left top right bottom are the coordinates of the box. The top and bottom coor‐ dinates are the minimum and maximum for the box, since the actual start of the box is groff’s drawing position when you issue the command, and the bottom of the box is the point where you turn the box “off”. The top and bot‐ tom coordinates are used only if the box drawing extends onto the next page; ordinarily, they would be set to the header and footer margins. weight provides the line width for the border if “box” is in‐ cluded in the command. The convenience macro for this escape sequence is .pdfback‐ ground. An sboxes macro file is also available; see groff_tmac(5). Macros gropdf’s support macros in pdf.tmac define the convenience macros de‐ scribed above. Some features have no direct device control command counterpart. .pdfinfo /field content ... Define PDF metadata. field may be be one of Title, Author, Sub‐ ject, Keywords, or another datum supported by the PDF standard or your reader. field must be prefixed with a slash. Importing graphics gropdf supports only the inclusion of other PDF files for inline im‐ ages. Such a PDF file may, however, contain any of the graphic formats supported by the PDF standard, such as JPEG/JFIF, PNG, and GIF. Any application that outputs PDF can thus be used to prepare files for em‐ bedding in documents processed by groff and gropdf. The PDF file you wish to insert must be a single page and the drawing must just fit inside the media size of the PDF file. In inkscape(1) or gimp(1), for example, make sure the canvas size just fits the image. The PDF parser gropdf implements has not been rigorously tested with all applications that produce PDF. If you find a single‐page PDF which fails to import properly, try processing it with the pdftk(1) program. pdftk existing‐file output new‐file You may find that new‐file imports successfully. TrueType and other font formats gropdf does not yet support any font formats besides Adobe Type 1 (PFA or PFB). Font installation The following is a step‐by‐step font installation guide for gropdf. • Convert your font to something groff understands. This is a Post‐ Script Type 1 font in PFA or PFB format, together with an AFM file. A PFA file begins as follows. %!PS-AdobeFont-1.0: A PFB file contains this string as well, preceded by some non‐print‐ ing bytes. In the following steps, we will consider the use of CTAN’s BrushScriptX‐Italic ⟨https://ctan.org/tex-archive/fonts/ brushscr⟩ font in PFA format. • Convert the AFM file to a groff font description file with the afmtodit(1) program. For instance, $ afmtodit BrushScriptX-Italic.afm text.map BSI converts the Adobe Font Metric file BrushScriptX-Italic.afm to the groff font description file BSI. If you have a font family which provides regular upright (roman), bold, italic, and bold‐italic styles, (where “italic” may be “oblique” or “slanted”), we recommend using R, B, I, and BI, respec‐ tively, as suffixes to the groff font family name to enable groff’s font family and style selection features. An example is groff’s built‐in support for Times: the font family name is abbreviated as T, and the groff font names are therefore TR, TB, TI, and TBI. In our example, however, the BrushScriptX font is available in a single style only, italic. • Install the groff font description file(s) in a devpdf subdirectory in the search path that groff uses for device and font file descrip‐ tions. See the GROFF_FONT_PATH entry in section “Environment” of troff(1) for the current value of the font search path. While groff doesn’t directly use AFM files, it is a good idea to store them alongside its font description files. • Register fonts in the devpdf/download file so they can be located for embedding in PDF files gropdf generates. Only the first download file encountered in the font search path is read. If in doubt, copy the default download file (see section “Files” below) to the first directory in the font search path and add your fonts there. The PostScript font name used by gropdf is stored in the internalname field in the groff font description file. (This name does not neces‐ sarily resemble the font’s file name.) If the font in our example had originated from a foundry named Z, we would add the following line to download. Z→BrushScriptX-Italic→BrushScriptX-Italic.pfa A tab character, depicted as →, separates the fields. The default foundry has no name: its field is empty and entries corresponding to it start with a tab character, as will the one in our example. • Test the selection and embedding of the new font. printf "\\f[BSI]Hello, world!\n" | groff -T pdf -P -e >hello.pdf see hello.pdf Environment GROFF_FONT_PATH A list of directories in which to seek the selected output de‐ vice’s directory of device and font description files. If, in the download file, the font file has been specified with a full path, no directories are searched. See troff(1) and groff_font(5). GROPDF_NOSLIDE If set and evaluates to a true value (to Perl), gropdf ignores commands specific to presentation PDFs, producing a normal PDF instead. SOURCE_DATE_EPOCH A timestamp (expressed as seconds since the Unix epoch) to use as the output creation timestamp in place of the current time. The time is converted to human‐readable form using Perl’s localtime() function and recorded in a PDF comment. TZ The time zone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human‐readable form; see tzset(3). Files /usr/local/share/groff/1.23.0/font/devpdf/DESC describes the pdf output device. /usr/local/share/groff/1.23.0/font/devpdf/F describes the font known as F on device pdf. /usr/local/share/groff/1.23.0/font/devpdf/U-F describes the font from the URW foundry (versus the Adobe de‐ fault) known as F on device pdf. /usr/local/share/groff/1.23.0/font/devpdf/download lists fonts available for embedding within the PDF document (by analogy to the ps device’s downloadable font support). /usr/local/share/groff/1.23.0/font/devpdf/Foundry is a data file used by the groff build system to locate Post‐ Script Type 1 fonts. /usr/local/share/groff/1.23.0/font/devpdf/enc/text.enc describes the encoding scheme used by most PostScript Type 1 fonts; the encoding directive of font description files for the pdf device refers to it. /usr/local/share/groff/1.23.0/tmac/pdf.tmac defines macros for use with the pdf output device. It is auto‐ matically loaded by troffrc when the pdf output device is se‐ lected. /usr/local/share/groff/1.23.0/tmac/pdfpic.tmac defines the PDFPIC macro for embedding images in a document; see groff_tmac(5). It is automatically loaded by troffrc. Authors gropdf was written and is maintained by Deri James ⟨deri@chuzzlewit .myzen.co.uk⟩. See also /usr/local/share/doc/groff-1.23.0/sboxes/msboxes.ms /usr/local/share/doc/groff-1.23.0/sboxes/msboxes.pdf “Using PDF boxes with groff and the ms macros”, by Deri James. present.tmac is part of gpresent ⟨https://bob.diertens.org/corner/useful/ gpresent/⟩, a software package by Bob Diertens that works with groff to produce presentations (“foils”, or “slide decks”). afmtodit(1), groff(1), troff(1), groff_font(5), groff_out(5) groff 1.23.0 29 August 2023 gropdf(1) ─────────────────────────────────────────────────────────────────────────────── grops(1) General Commands Manual grops(1) Name grops - groff output driver for PostScript Synopsis grops [-glm] [-b brokenness‐flags] [-c num‐copies] [-F font‐directory] [-I inclusion‐directory] [-p paper‐format] [-P prologue‐file] [-w rule‐thickness] [file ...] grops --help grops -v grops --version Description The GNU roff PostScript output driver translates the output of troff(1) into PostScript. Normally, grops is invoked by groff(1) when the lat‐ ter is given the “-T ps” option. (In this installation, ps is the de‐ fault output device.) Use groff’s -P option to pass any options shown above to grops. If no file arguments are given, or if file is “-”, grotty reads the standard input stream. Output is written to the stan‐ dard output stream. When called with multiple file arguments, grops doesn’t produce a valid document structure (one conforming to the Document Structuring Conven‐ tions). To print such concatenated output, it is necessary to deacti‐ vate DSC handling in the printing program or previewer. See section “Font installation” below for a guide to installing fonts for grops. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -b n Work around problems with spoolers, previewers, and older print‐ ers. Normally, grops produces output at PostScript LanguageLevel 2 that conforms to version 3.0 of the Document Structuring Conventions. Some software and devices can’t handle such a data stream. The value of n determines what grops does to make its output acceptable to such consumers. If n is 0, grops employs no workarounds, which is the default; it can be changed by modifying the broken directive in grops’s DESC file. Add 1 to suppress generation of %%BeginDocumentSetup and %%End‐ DocumentSetup comments; this is needed for early versions of TranScript that get confused by anything between the %%EndProlog comment and the first %%Page comment. Add 2 to omit lines in included files beginning with %!, which confuse Sun’s pageview previewer. Add 4 to omit lines in included files beginning with %%Page, %%Trailer and %%EndProlog; this is needed for spoolers that don’t understand %%BeginDocument and %%EndDocument comments. Add 8 to write %!PS-Adobe-2.0 rather than %!PS-Adobe-3.0 as the first line of the PostScript output; this is needed when using Sun’s Newsprint with a printer that requires page reversal. Add 16 to omit media size information (that is, output neither a %%DocumentMedia comment nor the setpagedevice PostScript com‐ mand). This was the behavior of groff 1.18.1 and earlier; it is needed for older printers that don’t understand PostScript LanguageLevel 2, and is also necessary if the output is further processed to produce an EPS file; see subsection “Escapsulated PostScript” below. -c n Output n copies of each page. -F dir Prepend directory dir/devname to the search path for font and device description and PostScript prologue files; name is the name of the device, usually ps. -g Generate PostScript code to guess the page length. The guess is correct only if the imageable area is vertically centered on the page. This option allows you to generate documents that can be printed on both U.S. letter and A4 paper formats without change. -I dir Search the directory dir for files named in \X'ps: file' and \X'ps: import' escape sequences. -I may be specified more than once; each dir is searched in the given order. To search the current working directory before others, add “-I .” at the de‐ sired place; it is otherwise searched last. -l Use landscape orientation rather than portrait. -m Turn on manual feed for the document. -p fmt Set physical dimensions of output medium, overriding the papersize, paperlength, and paperwidth directives in the DESC file. fmt can be any argument accepted by the papersize direc‐ tive; see groff_font(5). -P prologue Use the file prologue, sought in the groff font search path, as the PostScript prologue, overriding the default (see section “Files” below) and the environment variable GROPS_PROLOGUE. -w n Draw rules (lines) with a thickness of n thousandths of an em. The default thickness is 40 (0.04 em). Usage The input to grops must be in the format output by troff(1), described in groff_out(5). In addition, the device and font description files for the device used must meet certain requirements. The device resolu‐ tion must be an integer multiple of 72 times the sizescale. The device description file must contain a valid paper format; see groff_font(5). Each font description file must contain a directive internalname psname which says that the PostScript name of the font is psname. A font description file may also contain a directive encoding enc‐file which says that the PostScript font should be reencoded using the en‐ coding described in enc‐file; this file should consist of a sequence of lines of the form pschar code where pschar is the PostScript name of the character, and code is its position in the encoding expressed as a decimal integer; valid values are in the range 0 to 255. Lines starting with # and blank lines are ignored. The code for each character given in the font description file must correspond to the code for the character in encoding file, or to the code in the default encoding for the font if the PostScript font is not to be reencoded. This code can be used with the \N escape se‐ quence in troff to select the character, even if it does not have a groff glyph name. Every character in the font description file must exist in the PostScript font, and the widths given in the font descrip‐ tion file must match the widths used in the PostScript font. grops as‐ sumes that a character with a groff name of space is blank (makes no marks on the page); it can make use of such a character to generate more efficient and compact PostScript output. grops is able to display all glyphs in a PostScript font; it is not limited to 256 of them. enc‐file (or the default encoding if no encod‐ ing file is specified) just defines the order of glyphs for the first 256 characters; all other glyphs are accessed with additional encoding vectors which grops produces on the fly. grops can embed fonts in a document that are necessary to render it; this is called “downloading”. Such fonts must be in PFA format. Use pfbtops(1) to convert a Type 1 font in PFB format. Downloadable fonts must be listed a download file containing lines of the form psname file where psname is the PostScript name of the font, and file is the name of the file containing it; lines beginning with # and blank lines are ignored; fields may be separated by tabs or spaces. file is sought us‐ ing the same mechanism as that for groff font description files. The download file itself is also sought using this mechanism; currently, only the first matching file found in the device and font description search path is used. If the file containing a downloadable font or imported document con‐ forms to the Adobe Document Structuring Conventions, then grops inter‐ prets any comments in the files sufficiently to ensure that its own output is conforming. It also supplies any needed font resources that are listed in the download file as well as any needed file resources. It is also able to handle inter‐resource dependencies. For example, suppose that you have a downloadable font called Garamond, and also a downloadable font called Garamond‐Outline which depends on Garamond (typically it would be defined to copy Garamond’s font dictionary, and change the PaintType), then it is necessary for Garamond to appear be‐ fore Garamond‐Outline in the PostScript document. grops handles this automatically provided that the downloadable font file for Garamond‐ Outline indicates its dependence on Garamond by means of the Document Structuring Conventions, for example by beginning with the following lines. %!PS-Adobe-3.0 Resource-Font %%DocumentNeededResources: font Garamond %%EndComments %%IncludeResource: font Garamond In this case, both Garamond and Garamond‐Outline would need to be listed in the download file. A downloadable font should not include its own name in a %%DocumentSuppliedResources comment. grops does not interpret %%DocumentFonts comments. The %%Document‐ NeededResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginResource, and %%EndResource comments (or possibly the old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%Begin‐ Font, and %%EndFont comments) should be used. The default stroke and fill color is black. For colors defined in the “rgb” color space, setrgbcolor is used; for “cmy” and “cmyk”, setcmyk‐ color; and for “gray”, setgray. setcmykcolor is a PostScript LanguageLevel 2 command and thus not available on some older printers. Typefaces Styles called R, I, B, and BI mounted at font positions 1 to 4. Text fonts are grouped into families A, BM, C, H, HN, N, P, and T, each hav‐ ing members in each of these styles. AR AvantGarde‐Book AI AvantGarde‐BookOblique AB AvantGarde‐Demi ABI AvantGarde‐DemiOblique BMR Bookman‐Light BMI Bookman‐LightItalic BMB Bookman‐Demi BMBI Bookman‐DemiItalic CR Courier CI Courier‐Oblique CB Courier‐Bold CBI Courier‐BoldOblique HR Helvetica HI Helvetica‐Oblique HB Helvetica‐Bold HBI Helvetica‐BoldOblique HNR Helvetica‐Narrow HNI Helvetica‐Narrow‐Oblique HNB Helvetica‐Narrow‐Bold HNBI Helvetica‐Narrow‐BoldOblique NR NewCenturySchlbk‐Roman NI NewCenturySchlbk‐Italic NB NewCenturySchlbk‐Bold NBI NewCenturySchlbk‐BoldItalic PR Palatino‐Roman PI Palatino‐Italic PB Palatino‐Bold PBI Palatino‐BoldItalic TR Times‐Roman TI Times‐Italic TB Times‐Bold TBI Times‐BoldItalic Another text font is not a member of a family. ZCMI ZapfChancery‐MediumItalic Special fonts include S, the PostScript Symbol font; ZD, Zapf Dingbats; SS (slanted symbol), which contains oblique forms of lowercase Greek letters derived from Symbol; EURO, which offers a Euro glyph for use with old devices lacking it; and ZDR, a reversed version of ZapfDing‐ bats (with symbols flipped about the vertical axis). Most glyphs in these fonts are unnamed and must be accessed using \N. The last three are not standard PostScript fonts, but supplied by groff and therefore included in the default download file. Device control commands grops recognizes device control commands produced by the \X escape se‐ quence, but interprets only those that begin with a “ps:” tag. \X'ps: exec code' Execute the arbitrary PostScript commands code. The PostScript currentpoint is set to the groff drawing position when the \X escape sequence is interpreted before executing code. The ori‐ gin is at the top left corner of the page; x coordinates in‐ crease to the right, and y coordinates down the page. A proce‐ dure u is defined that converts groff basic units to the coordi‐ nate system in effect (provided the user doesn’t change the scale). For example, .nr x 1i \X'ps: exec \nx u 0 rlineto stroke' draws a horizontal line one inch long. code may make changes to the graphics state, but any changes persist only to the end of the page. A dictionary containing the definitions specified by the def and mdef commands is on top of the dictionary stack. If your code adds definitions to this dictionary, you should allo‐ cate space for them using “\X'ps: mdef n'”. Any definitions persist only until the end of the page. If you use the \Y es‐ cape sequence with an argument that names a macro, code can ex‐ tend over multiple lines. For example, .nr x 1i .de y ps: exec \nx u 0 rlineto stroke .. \Yy is another way to draw a horizontal line one inch long. The single backslash before “nx”—the only reason to use a register while defining the macro “y”—is to convert a user‐specified di‐ mension “1i” to groff basic units which are in turn converted to PostScript units with the u procedure. grops wraps user‐specified PostScript code into a dictionary, nothing more. In particular, it doesn’t start and end the in‐ serted code with save and restore, respectively. This must be supplied by the user, if necessary. \X'ps: file name' This is the same as the exec command except that the PostScript code is read from file name. \X'ps: def code' Place a PostScript definition contained in code in the prologue. There should be at most one definition per \X command. Long de‐ finitions can be split over several \X commands; all the code arguments are simply joined together separated by newlines. The definitions are placed in a dictionary which is automatically pushed on the dictionary stack when an exec command is executed. If you use the \Y escape sequence with an argument that names a macro, code can extend over multiple lines. \X'ps: mdef n code' Like def, except that code may contain up to n definitions. grops needs to know how many definitions code contains so that it can create an appropriately sized PostScript dictionary to contain them. \X'ps: import file llx lly urx ury width [height]' Import a PostScript graphic from file. The arguments llx, lly, urx, and ury give the bounding box of the graphic in the default PostScript coordinate system. They should all be integers: llx and lly are the x and y coordinates of the lower left corner of the graphic; urx and ury are the x and y coordinates of the up‐ per right corner of the graphic; width and height are integers that give the desired width and height in groff basic units of the graphic. The graphic is scaled so that it has this width and height and translated so that the lower left corner of the graphic is lo‐ cated at the position associated with \X command. If the height argument is omitted it is scaled uniformly in the x and y axes so that it has the specified width. The contents of the \X command are not interpreted by troff, so vertical space for the graphic is not automatically added, and the width and height arguments are not allowed to have attached scaling indicators. If the PostScript file complies with the Adobe Document Struc‐ turing Conventions and contains a %%BoundingBox comment, then the bounding box can be automatically extracted from within groff input by using the psbb request. See groff_tmac(5) for a description of the PSPIC macro which provides a convenient high‐level interface for inclusion of PostScript graphics. \X'ps: invis' \X'ps: endinvis' No output is generated for text and drawing commands that are bracketed with these \X commands. These commands are intended for use when output from troff is previewed before being processed with grops; if the previewer is unable to display cer‐ tain characters or other constructs, then other substitute char‐ acters or constructs can be used for previewing by bracketing them with these \X commands. For example, gxditview is not able to display a proper \[em] character because the standard X11 fonts do not provide it; this problem can be overcome by executing the following request .char \[em] \X'ps: invis'\ \Z'\v'‐.25m'\h'.05m'\D'l .9m 0'\h'.05m''\ \X'ps: endinvis'\[em] In this case, gxditview is unable to display the \[em] character and draws the line, whereas grops prints the \[em] character and ignores the line (this code is already in file Xps.tmac, which is loaded if a document intended for grops is previewed with gxditview). If a PostScript procedure BPhook has been defined via a “ps: def” or “ps: mdef” device control command, it is executed at the beginning of every page (before anything is drawn or written by groff). For exam‐ ple, to underlay the page contents with the word “DRAFT” in light gray, you might use .de XX ps: def /BPhook { gsave .9 setgray clippath pathbbox exch 2 copy .5 mul exch .5 mul translate atan rotate pop pop /NewCenturySchlbk‐Roman findfont 200 scalefont setfont (DRAFT) dup stringwidth pop -.5 mul -70 moveto show grestore } def .. .devicem XX Or, to cause lines and polygons to be drawn with square linecaps and mitered linejoins instead of the round linecaps and linejoins normally used by grops, use .de XX ps: def /BPhook { 2 setlinecap 0 setlinejoin } def .. .devicem XX (square linecaps, as opposed to butt linecaps (“0 setlinecap”), give true corners in boxed tables even though the lines are drawn uncon‐ nected). Encapsulated PostScript grops itself doesn’t emit bounding box information. The following script, groff2eps, produces an EPS file. #! /bin/sh groff -P-b16 "$1" > "$1".ps gs -dNOPAUSE -sDEVICE=bbox -- "$1".ps 2> "$1".bbox sed -e "/^%%Orientation/r $1.bbox" \ -e "/^%!PS-Adobe-3.0/s/$/ EPSF-3.0/" "$1".ps > "$1".eps rm "$1".ps "$1".bbox You can then use “groff2eps foo” to convert file foo to foo.eps. TrueType and other font formats TrueType fonts can be used with grops if converted first to Type 42 format, a PostScript wrapper equivalent to the PFA format described in pfbtops(1). Several methods exist to generate a Type 42 wrapper; some of them involve the use of a PostScript interpreter such as Ghost‐ script—see gs(1). One approach is to use FontForge ⟨https://fontforge.org/⟩, a font edi‐ tor that can convert most outline font formats. Here’s an example of using the Roboto Slab Serif font with groff. Several variables are used so that you can more easily adapt it into your own script. MAP=/usr/local/share/groff/1.23.0/font/devps/generate/text.map TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab-Regular.ttf BASE=$(basename "$TTF") INT=${BASE%.ttf} PFA=$INT.pfa AFM=$INT.afm GFN=RSR DIR=$HOME/.local/groff/font mkdir -p "$DIR"/devps fontforge -lang=ff -c "Open(\"$TTF\");\ Generate(\"$DIR/devps/$PFA\");" afmtodit "$DIR/devps/$AFM" "$MAP" "$DIR/devps/$GFN" printf "$BASE\t$PFA\n" >> "$DIR/devps/download" fontforge and afmtodit may generate warnings depending on the attrib‐ utes of the font. The test procedure is simple. printf ".ft RSR\nHello, world!\n" | groff -F "$DIR" > hello.ps Once you’re satisfied that the font works, you may want to generate any available related styles (for instance, Roboto Slab also has “Bold”, “Light”, and “Thin” styles) and set up GROFF_FONT_PATH in your environ‐ ment to include the directory you keep the generated fonts in so that you don’t have to use the -F option. Font installation The following is a step‐by‐step font installation guide for grops. • Convert your font to something groff understands. This is a Post‐ Script Type 1 font in PFA format or a PostScript Type 42 font, to‐ gether with an AFM file. A PFA file begins as follows. %!PS-AdobeFont-1.0: A PFB file contains this string as well, preceded by some non‐print‐ ing bytes. If your font is in PFB format, use groff’s pfbtops(1) program to convert it to PFA. For TrueType and other font formats, we recommend fontforge, which can convert most outline font formats. A Type 42 font file begins as follows. %!PS-TrueTypeFont This is a wrapper format for TrueType fonts. Old PostScript printers might not support them (that is, they might not have a built‐in True‐ Type font interpreter). In the following steps, we will consider the use of CTAN’s BrushScriptX‐Italic ⟨https://ctan.org/tex-archive/ fonts/brushscr⟩ font in PFA format. • Convert the AFM file to a groff font description file with the afmtodit(1) program. For instance, $ afmtodit BrushScriptX-Italic.afm text.map BSI converts the Adobe Font Metric file BrushScriptX-Italic.afm to the groff font description file BSI. If you have a font family which provides regular upright (roman), bold, italic, and bold‐italic styles (where “italic” may be “oblique” or “slanted”), we recommend using the letters R, B, I, and BI, re‐ spectively, as suffixes to the groff font family name to enable groff’s font family and style selection features. An example is groff’s built‐in support for Times: the font family name is abbrevi‐ ated as T, and the groff font names are therefore TR, TB, TI, and TBI. In our example, however, the BrushScriptX font is available in a single style only, italic. • Install the groff font description file(s) in a devps subdirectory in the search path that groff uses for device and font file descrip‐ tions. See the GROFF_FONT_PATH entry in section “Environment” of troff(1) for the current value of the font search path. While groff doesn’t directly use AFM files, it is a good idea to store them alongside its font description files. • Register fonts in the devps/download file so they can be located for embedding in PostScript files grops generates. Only the first down‐ load file encountered in the font search path is read. If in doubt, copy the default download file (see section “Files” below) to the first directory in the font search path and add your fonts there. The PostScript font name used by grops is stored in the internalname field in the groff font description file. (This name does not neces‐ sarily resemble the font’s file name.) We add the following line to download. BrushScriptX-Italic→BrushScriptX-Italic.pfa A tab character, depicted as →, separates the fields. • Test the selection and embedding of the new font. printf "\\f[BSI]Hello, world!\n" | groff -T ps -P -e >hello.ps see hello.pdf Old fonts groff versions 1.19.2 and earlier contained descriptions of a slightly different set of the base 35 PostScript level 2 fonts defined by Adobe. The older set has 229 glyphs and a larger set of kerning pairs; the newer one has 314 glyphs and includes the Euro glyph. For backwards compatibility, these old font descriptions are also installed in the /usr/local/share/groff/1.23.0/oldfont/devps directory. To use them, make sure that grops finds the fonts before the default system fonts (with the same names): either give grops the -F command‐ line option, $ groff -Tps -P-F -P/usr/local/share/groff/1.23.0/oldfont ... or add the directory to groff’s font and device description search path environment variable, $ GROFF_FONT_PATH=/usr/local/share/groff/1.23.0/oldfont \ groff -Tps ... when the command runs. Environment GROFF_FONT_PATH A list of directories in which to seek the selected output de‐ vice’s directory of device and font description files. See troff(1) and groff_font(5). GROPS_PROLOGUE If this is set to foo, then grops uses the file foo (in the font path) instead of the default prologue file prologue. The option -P overrides this environment variable. SOURCE_DATE_EPOCH A timestamp (expressed as seconds since the Unix epoch) to use as the output creation timestamp in place of the current time. The time is converted to human‐readable form using ctime(3) and recorded in a PostScript comment. TZ The time zone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human‐readable form; see tzset(3). Files /usr/local/share/groff/1.23.0/font/devps/DESC describes the ps output device. /usr/local/share/groff/1.23.0/font/devps/F describes the font known as F on device ps. /usr/local/share/groff/1.23.0/font/devps/download lists fonts available for embedding within the PostScript docu‐ ment (or download to the device). /usr/local/share/groff/1.23.0/font/devps/prologue is the default PostScript prologue prefixed to every output file. /usr/local/share/groff/1.23.0/font/devps/text.enc describes the encoding scheme used by most PostScript Type 1 fonts; the encoding directive of font description files for the ps device refers to it. /usr/local/share/groff/1.23.0/tmac/ps.tmac defines macros for use with the ps output device. It is auto‐ matically loaded by troffrc when the ps output device is se‐ lected. /usr/local/share/groff/1.23.0/tmac/pspic.tmac defines the PSPIC macro for embedding images in a document; see groff_tmac(5). It is automatically loaded by troffrc. /usr/local/share/groff/1.23.0/tmac/psold.tmac provides replacement glyphs for text fonts that lack complete coverage of the ISO Latin‐1 character set; using it, groff can produce glyphs like eth (ð) and thorn (þ) that older PostScript printers do not natively support. grops creates temporary files using the template “gropsXXXXXX”; see groff(1) for details on their storage location. See also PostScript Language Document Structuring Conventions Specification ⟨http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf⟩ afmtodit(1), groff(1), troff(1), pfbtops(1), groff_char(7), groff_font(5), groff_out(5), groff_tmac(5) groff 1.23.0 29 August 2023 grops(1) ─────────────────────────────────────────────────────────────────────────────── grotty(1) General Commands Manual grotty(1) Name grotty - groff output driver for typewriter‐like (terminal) devices Synopsis grotty [-dfho] [-i|-r] [-F dir] [file ...] grotty -c [-bBdfhouU] [-F dir] [file ...] grotty --help grotty -v grotty --version Description The GNU roff TTY (“Teletype”) output driver translates the output of troff(1) into a form suitable for typewriter‐like devices, including terminal emulators. Normally, grotty is invoked by groff(1) when the latter is given one of the “-T ascii”, “-T latin1”, -Tlatin1, or “-T utf8” options on systems using ISO character encoding standards, or with “-T cp1047” or “-T utf8” on EBCDIC‐based hosts. (In this instal‐ lation, ps is the default output device.) Use groff’s -P option to pass any options shown above to grotty. If no file arguments are given, or if file is “-”, grotty reads the standard input stream. Out‐ put is written to the standard output stream. By default, grotty emits SGR escape sequences (from ISO 6429, popularly called “ANSI escapes”) to change text attributes (bold, italic, under‐ line, reverse video [“negative image”] and colors). Devices supporting the appropriate sequences can view roff documents using eight different background and foreground colors. Following ISO 6429, the following colors are defined in tty.tmac: black, white, red, green, blue, yellow, magenta, and cyan. Unrecognized colors are mapped to the default color, which is dependent on the settings of the terminal. OSC 8 hy‐ perlinks are produced for these devices. In keeping with long‐standing practice and the rarity of terminals (and emulators) that support oblique or italic fonts, italicized text is represented with underlining by default—but see the -i option below. SGR and OSC support in pagers When paging grotty’s output with less(1), the latter program must be instructed to pass SGR and OSC sequences through to the device; its -R option is one way to achieve this (less version 566 or later is re‐ quired for OSC 8 support). Consequently, programs like man(1) that page roff documents with less must call it with an appropriate option. Legacy output format The -c option tells grotty to use an output format compatible with pa‐ per terminals, like the Teletype machines for which roff and nroff were first developed but which are no longer in wide use. SGR escape se‐ quences are not emitted; bold, italic, and underlining character at‐ tributes are thus not manipulated. Instead, grotty overstrikes, repre‐ senting a bold character c with the sequence “c BACKSPACE c”, an italic character c with the sequence “_ BACKSPACE c”, and bold italics with “_ BACKSPACE c BACKSPACE c”. This rendering is inherently ambiguous when the character c is itself the underscore. The legacy output format can be rendered on a video terminal (or emula‐ tor) by piping grotty’s output through ul(1), which may render bold italics as reverse video. Some implementations of more(1) are also able to display these sequences; you may wish to experiment with that command’s -b option. less renders legacy bold and italics without re‐ quiring options. In contrast to the terminal output drivers of some other roff implementations, grotty never outputs reverse line feeds. There is therefore no need to filter its output through col(1). Device control commands grotty understands one device control function produced by the roff \X escape sequence in a document. \X'tty: link [uri [key=value] ...]' Embed a hyperlink using the OSC 8 terminal escape sequence. Specifying uri starts hyperlinked text, and omitting it ends the hyperlink. When uri is present, any number of additional key/value pairs can be specified; their interpretation is the responsibility of the pager or terminal. Spaces or tabs cannot appear literally in uri, key, or value; they must be represented in an alternate form. Device description files If the DESC file for the character encoding contains the “unicode” di‐ rective, grotty emits Unicode characters in UTF‐8 encoding. Otherwise, it emits characters in a single‐byte encoding depending on the data in the font description files. See groff_font(5). A font description file may contain a directive “internalname n” where n is a decimal integer. If the 01 bit in n is set, then the font is treated as an italic font; if the 02 bit is set, then it is treated as a bold font. Typefaces grotty supports the standard four styles: R (roman), I (italic), B (bold), and BI (bold‐italic). Because the output driver operates in nroff mode, attempts to set or change the font family or type size are ignored. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -b Suppress the use of overstriking for bold characters in legacy output format. -B Use only overstriking for bold‐italic characters in legacy out‐ put format. -c Use grotty’s legacy output format (see subsection “Legacy output format” above). SGR and OSC escape sequences are not emitted. -d Ignore all \D drawing escape sequences in the input. By de‐ fault, grotty renders \D'l...' escape sequences that have at least one zero argument (and so are either horizontal or verti‐ cal) using Unicode box drawing characters (for the utf8 device) or the -, |, and + characters (for all other devices). grotty handles \D'p...' escape sequences that consist entirely of hori‐ zontal and vertical lines similarly. -f Emit a form feed at the end of each page having no output on its last line. -F dir Prepend directory dir/devname to the search path for font and device description files; name describes the output device’s character encoding, one of ascii, latin1, utf8, or cp1047. -h Use literal horizontal tab characters in the output. Tabs are assumed to be set every 8 columns. -i Render oblique‐styled fonts (I and BI) with the SGR attribute for italic text rather than underlined text. Many terminals don’t support this attribute; however, xterm(1), since patch #314 (2014‐12‐28), does. Ignored if -c is also specified. -o Suppress overstriking (other than for bold and/or underlined characters when the legacy output format is in use). -r Render oblique‐styled fonts (I and BI) with the SGR attribute for reverse video text rather than underlined text. Ignored if -c or -i is also specified. -u Suppress the use of underlining for italic characters in legacy output format. -U Use only underlining for bold‐italic characters in legacy output format. Environment GROFF_FONT_PATH A list of directories in which to seek the selected output de‐ vice’s directory of device and font description files. See troff(1) and groff_font(5). GROFF_NO_SGR If set, grotty’s legacy output format is used just as if the -c option were specified; see subsection “Legacy output format” above. Files /usr/local/share/groff/1.23.0/font/devascii/DESC describes the ascii output device. /usr/local/share/groff/1.23.0/font/devascii/F describes the font known as F on device ascii. /usr/local/share/groff/1.23.0/font/devcp1047/DESC describes the cp1047 output device. /usr/local/share/groff/1.23.0/font/devcp1047/F describes the font known as F on device cp1047. /usr/local/share/groff/1.23.0/font/devlatin1/DESC describes the latin1 output device. /usr/local/share/groff/1.23.0/font/devlatin1/F describes the font known as F on device latin1. /usr/local/share/groff/1.23.0/font/devutf8/DESC describes the utf8 output device. /usr/local/share/groff/1.23.0/font/devutf8/F describes the font known as F on device utf8. /usr/local/share/groff/1.23.0/tmac/tty.tmac defines macros for use with the ascii, cp1047, latin1, and utf8 output devices. It is automatically loaded by troffrc when any of those output devices is selected. /usr/local/share/groff/1.23.0/tmac/tty-char.tmac defines fallback characters for use with grotty. See nroff(1). Limitations grotty is intended only for simple documents. • There is no support for fractional horizontal or vertical motions. • roff \D escape sequences producing anything other than horizontal and vertical lines are not supported. • Characters above the first line (that is, with a vertical drawing po‐ sition of 0) cannot be rendered. • Color handling differs from other output drivers. The groff requests and escape sequences that set the stroke and fill colors instead set the foreground and background character cell colors, respectively. Examples The following groff document exercises several features for which out‐ put device support varies: (1) bold style; (2) italic (underline) style; (3) bold‐italic style; (4) character composition by overstriking (“coöperate”); (5) foreground color; (6) background color; and (7) hor‐ izontal and vertical line‐drawing. You might see \f[B]bold\f[] and \f[I]italic\f[]. Some people see \f[BI]both\f[]. If the output device does (not) co\z\[ad]operate, you might see \m[red]red\m[]. Black on cyan can have a \M[cyan]\m[black]prominent\m[]\M[] \D'l 1i 0'\D'l 0 2i'\D'l 1i 0' look. .\" If in nroff mode, end page now. .if n .pl \n[nl]u Given the foregoing input, compare and contrast the output of the fol‐ lowing. $ groff -T ascii file $ groff -T utf8 -P -i file $ groff -T utf8 -P -c file | ul See also “Control Functions for Coded Character Sets” (ECMA‐48) 5th edition, Ecma International, June 1991. A gratis version of ISO 6429, this doc‐ ument includes a normative description of SGR escape sequences. Avail‐ able at ⟨http://www.ecma-international.org/publications/files/ECMA-ST/ Ecma-048.pdf⟩. “Hyperlinks in Terminal Emulators” ⟨https://gist.github.com/egmontkob/ eb114294efbcd5adb1944c9f3cb5feda⟩, Egmont Koblinger. groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7), ul(1), more(1), less(1), man(1) groff 1.23.0 29 August 2023 grotty(1) ─────────────────────────────────────────────────────────────────────────────── gxditview(1) General Commands Manual gxditview(1) Name gxditview - display groff intermediate output files in X11 Synopsis gxditview [X‐toolkit‐option ...] [-backingStore backing‐store‐type] [-filename file] [-page page‐number] [-printCommand command] [-resolution resolution] file gxditview -help gxditview --help gxditview -version gxditview --version Description gxditview interprets and displays the intermediate output format of groff(1) on an X11 display. It uses the standard X11 fonts, so it does not require access to the server machine for font loading. There are several ways to use gxditview. The intermediate output format of groff, documented in groff_out(5), is produced by troff or the -Z option to groff. It can be viewed by ex‐ plicitly calling “gxditview file”. If the file operand is “-”, gxditview will read the standard input stream; file cannot be omitted. The intermediate output format of groff is device‐independent but not device‐agnostic. gxditview can view it for all typesetter devices, but the quality is device‐dependent. gxditview will not display output for terminal (nroff) devices. The best results are achieved with the X* devices for groff’s -T op‐ tion, of which there are four: -TX75, -TX75-12, -TX100, and -TX100-12. They differ by the X resolution (75 or 100 dots per inch) and the base point size (10 or 12 points). They are especially built for gxditview. When using one of these, groff generates the intermediate output for this device and calls gxditview automatically for viewing. -X produces good results only with -Tps, -TX75, -TX75-12, -TX100, and -TX100-12. The default resolution for previewing -Tps output is 75dpi; this can be changed with the -resolution option. While gxditview is running, the left mouse button brings up a menu with several entries. Next Page Display the next page. Previous Page Display the previous page. Select Page Select a particular numbered page specified by a dialog box. Print Print the groff intermediate output using a command speci‐ fied by a dialog box. The default command initially dis‐ played is controlled by the printCommand application re‐ source, and by the -printCommand option. Open Open for display a new file specified by a dialog box. The file should contain groff intermediate output. If the filename starts with a bar or pipe symbol, “|” it will be interpreted as a command from which to read. Quit Exit from gxditview. The menu entries correspond to actions with similar but not identical names, which can also be accessed with keyboard accelerators. The n, Space, Return, and Next (PgDn) keys are bound to the NextPage action. The p, b, BackSpace, Delete, and Prior (PgUp) keys are bound to the PreviousPage action. The g key is bound to the SelectPage action. The o key is bound to the OpenFile action. The q key is bound to the Quit action. The r key is bound to a Rerasterize action which rereads the current file, and redisplays the current page; if the current file is a command, the command will be re‐executed. Vertical scrolling can be done with the k and j keys; horizontal scrolling is bound to the h and l keys. The arrow keys (up, down, left, and right) are also bound to the obvious scrolling actions. The paperlength and paperwidth commands in the DESC file describing a groff output device specify the length and width in machine units of the virtual page displayed by gxditview; see groff_font(5). X defaults This program uses the Dvi widget from the X Toolkit. It understands all of the core resource names and classes as well as: width (class Width) Specifies the width of the window. height (class Height) Specifies the height of the window. foreground (class Foreground) Specifies the default foreground color. font (class Font) Specifies the font to be used for error messages. fontMap (class FontMap) Specifies the mapping from groff font names to X font names. This must be a string containing a sequence of lines. Each line contains two whitespace‐separated fields: firstly the groff font name, and secondly the XLFD (X Logical Font Description). The default is shown in subsection “Default font map” below. Default font map XLFDs are long and unwieldy, so some lines are shown broken and in‐ dented below. TR -adobe-times-medium-r-normal--*-100-*-*-*-*-iso8859-1\n\ TI -adobe-times-medium-i-normal--*-100-*-*-*-*-iso8859-1\n\ TB -adobe-times-bold-r-normal--*-100-*-*-*-*-iso8859-1\n\ TBI -adobe-times-bold-i-normal--*-100-*-*-*-*-iso8859-1\n\ CR -adobe-courier-medium-r-normal--*-100 -*-*-*-*-iso8859-1\n\ CI -adobe-courier-medium-o-normal --*-100-*-*-*-*-iso8859-1\n\ CB -adobe-courier-bold-r-normal--*-100-*-*-*-*-iso8859-1\n\ CBI -adobe-courier-bold-o-normal--*-100-*-*-*-*-iso8859-1\n\ HR -adobe-helvetica-medium-r-normal --*-100-*-*-*-*-iso8859-1\n\ HI -adobe-helvetica-medium-o-normal --*-100-*-*-*-*-iso8859-1\n\ HB -adobe-helvetica-bold-r-normal --*-100-*-*-*-*-iso8859-1\n\ HBI -adobe-helvetica-bold-o-normal --*-100-*-*-*-*-iso8859-1\n\ NR -adobe-new century schoolbook-medium-r-normal--*-100 -*-*-*-*-iso8859-1\n\ NI -adobe-new century schoolbook-medium-i-normal--*-100 -*-*-*-*-iso8859-1\n\ NB -adobe-new century schoolbook-bold-r-normal--*-100 -*-*-*-*-iso8859-1\n\ NBI -adobe-new century schoolbook-bold-i-normal--*-100 -*-*-*-*-iso8859-1\n\ S -adobe-symbol-medium-r-normal--*-100 -*-*-*-*-adobe-fontspecific\n\ SS -adobe-symbol-medium-r-normal--*-100 -*-*-*-*-adobe-fontspecific\n\ Options -help and --help display a usage message, while -version and --version show version information; all exit afterward. gxditview accepts all of the standard X Toolkit command‐line options along with the additional options listed below. -page This option specifies the page number of the document to be dis‐ played. -backingStore backing‐store‐type Because redisplay of the groff intermediate output window can take a perceiptible amount of time, this option causes the server to save the window contents so that when it is scrolled around the viewport, the window is painted from contents saved in backing store. backing‐store‐type can be one of Always, WhenMapped or NotUseful. -printCommand command The default command displayed in the dialog box for the Print menu entry will be command. -resolution res The groff intermediate output file will be displayed at a reso‐ lution of res dots per inch, unless the DESC file contains the X11 command, in which case the device resolution will be used. This corresponds to the Dvi widget’s resolution resource. The default is 75. -filename string The default filename displayed in the dialog box for the Open menu entry will be string. This can be either a filename, or a command starting with “|”. The following standard X Toolkit command‐line arguments are commonly used with gxditview. -bg color This option specifies the color to use for the background of the window. The default is “white”. -bd color This option specifies the color to use for the border of the window. The default is “black”. -bw number This option specifies the width in pixels of the border sur‐ rounding the window. -fg color This option specifies the color to use for displaying text. The default is “black”. -fn font This option specifies the font to be used for displaying widget text. The default is “fixed”. -rv This option indicates that reverse video should be simulated by swapping the foreground and background colors. -geometry geometry This option specifies the preferred size and position of the window. -display host:display This option specifies the X server to contact. -xrm resourcestring This option specifies a resource string to be used. Environment GROFF_FONT_PATH A list of directories in which to seek the selected output de‐ vice’s directory of device and font description files. See troff(1) and groff_font(5). Files /usr/local/lib/X11/app-defaults/GXditview /usr/local/lib/X11/app-defaults/GXditview-color define X application defaults for gxditview. Users can override these values in the .Xdefaults file, normally located in the user’s home directory. See appres(1) and xrdb(1). /usr/local/share/groff/1.23.0/font/devX100/DESC describes the X100 output device. /usr/local/share/groff/1.23.0/font/devX100/F describes the font known as F on device X100. /usr/local/share/groff/1.23.0/font/devX100-12/DESC describes the X100-12 output device. /usr/local/share/groff/1.23.0/font/devX100-12/F describes the font known as F on device X100-12. /usr/local/share/groff/1.23.0/font/devX75/DESC describes the X75 output device. /usr/local/share/groff/1.23.0/font/devX75/F describes the font known as F on device X75. /usr/local/share/groff/1.23.0/font/devX75-12/DESC describes the X75-12 output device. /usr/local/share/groff/1.23.0/font/devX75-12/F describes the font known as F on device X75-12. /usr/local/share/groff/1.23.0/tmac/X.tmac defines macros for use with the X100, X100-12, X75, and X75-12 output devices. It is automatically loaded by troffrc when any of those output devices is selected. /usr/local/share/groff/1.23.0/tmac/Xps.tmac sets up troff to use gxditview as a previewer for device‐inde‐ pendent output targeting the ps output device. It is automati‐ cally loaded by troffrc when troff is given the options -X and -Tps. Examples The following command views this man page with a base point size of 12. groff -TX100-12 -man gxditview.1 The quality of the result depends mainly on the chosen point size and display resolution; for rapid previewing, however, something like groff -X -P-resolution -P100 document yields acceptable results. Authors gxditview and its predecessor xditview were written by Keith Packard (MIT X Consortium), Richard L. Hyde (Purdue), David Slattengren (Berke‐ ley), Malcolm Slaney (Schlumberger Palo Alto Research), Mark Moraes (University of Toronto), and James Clark. This program is derived from xditview; portions of xditview originated in xtroff, which was derived from suntroff. See also “X Logical Font Description Conventions” ⟨https://www.x.org/releases/ X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html⟩, by Jim Flowers and Stephen Gildea. X(7), xrdb(1), xditview(1), groff(1), groff_out(5) groff 1.23.0 29 August 2023 gxditview(1) ─────────────────────────────────────────────────────────────────────────────── hpftodit(1) General Commands Manual hpftodit(1) Name hpftodit - create font description files for use with groff and grolj4 Synopsis hpftodit [-aqs] [-i n] tfm‐file map‐file font‐description hpftodit -d tfm‐file [map‐file] hpftodit --help hpftodit -v hpftodit --version Description hpftodit creates a font description file for use with a Hewlett‐Packard LaserJet 4‐series (or newer) printer with the grolj4(1) output driver of groff(1), using data from an HP tagged font metric (TFM) file. tfm‐ file is the name of the font’s TFM file; Intellifont and TrueType TFM files are supported, but symbol set TFM files are not. map‐file is a file giving the groff special character identifiers for glyphs in the font; this file should consist of a sequence of lines of the form m u c1 c2 ... [# comment] where m is a decimal integer giving the glyph’s MSL (Master Symbol List) number, u is a hexadecimal integer giving its Unicode character code, and c1, c2, ... are its groff glyph names (see groff_char(7) for a list). The values can be separated by any number of spaces and/or tabs. The Unicode value must use uppercase hexadecimal digits A–F, and must lack a leading “0x”, “u”, or “U+”. Unicode values corresponding to composite glyphs are decomposed; that is “u00C0” becomes “u0041_0300”. A glyph without a groff special character identifier may be named uXXXX if the glyph corresponds to a Unicode value, or as an unnamed glyph “---”. If the given Unicode value is in the Private Use Area (PUA) (0xE000–0xF8FF), the glyph is included as an unnamed glyph. Refer to groff_diff(1) for additional information about unnamed glyphs and how to access them. Blank lines and lines beginning with “#” are ignored. A “#” following one or more groff names begins a comment. Because “#” is a valid groff name, it must appear first in a list of groff names if a comment is in‐ cluded, as in 3 0023 # # number sign or 3 0023 # sh # number sign whereas in 3 0023 sh # # number sign the first “#” is interpreted as the beginning of the comment. Output is written in groff_font(5) format to font‐description, a file named for the intended groff font name; if this operand is “-”, the font description is written to the standard output stream. If the -i option is used, hpftodit automatically will generate an italic correction, a left italic correction, and a subscript correction for each glyph (the significance of these parameters is explained in groff_font(5)). Options --help displays a usage message, while -v and --version show version information; all exit afterward. -a Include glyphs in the TFM file that are not included in map‐ file. A glyph with corresponding Unicode value is given the name uXXXX; a glyph without a Unicode value is included as an unnamed glyph “---”. A glyph with a Unicode value in the Pri‐ vate Use Area (0xE000–0xF8FF) is also included as an unnamed glyph. This option provides a simple means of adding Unicode‐named and unnamed glyphs to a font without including them in the map file, but it affords little control over which glyphs are placed in a regular font and which are placed in a special font. The pres‐ ence or absence of the -s option has some effect on which glyphs are included: without it, only the “text” symbol sets are searched for matching glyphs; with it, only the “mathematical” symbol sets are searched. Nonetheless, restricting the symbol sets searched isn’t very selective—many glyphs are placed in both regular and special fonts. Normally, -a should be used only as a last resort. -d Dump information about the TFM file to the standard output stream; use this to ensure that a TFM file is a proper match for a font, and that its contents are suitable. The information in‐ cludes the values of important TFM tags and a listing (by MSL number for Intellifont TFM files or by Unicode value for True‐ Type TFM files) of the glyphs included in the TFM file. The unit of measure “DU” for some tags indicates design units; there are 8782 design units per em for Intellifont fonts, and 2048 de‐ sign units per em for TrueType fonts. Note that the accessibil‐ ity of a glyph depends on its inclusion in a symbol set; some TFM files list many glyphs but only a few symbol sets. The glyph listing includes the glyph index within the TFM file, the MSL or Unicode value, and the symbol set and character code that will be used to print the glyph. If map‐file is given, groff names are given for matching glyphs. If only the glyph index and MSL or Unicode value are given, the glyph does not ap‐ pear in any supported symbol set and cannot be printed. With the -d option, map‐file is optional, and output‐font is ig‐ nored if given. -i n Generate an italic correction for each glyph so that its width plus its italic correction is equal to n thousandths of an em plus the amount by which the right edge of the glyphs’s bounding box is to the right of its origin. If a negative italic correc‐ tion would result, use a zero italic correction instead. Also generate a subscript correction equal to the product of the tangent of the slant of the font and four fifths of the x‐height of the font. If a subscript correction greater than the italic correction would result, use a subscript correction equal to the italic correction instead. Also generate a left italic correction for each glyph equal to n thousandths of an em plus the amount by which the left edge of the glyphs’s bounding box is to the left of its origin. The left italic correction may be negative. This option normally is needed only with italic or oblique fonts; a value of 50 (0.05 em) usually is a reasonable choice. -q Suppress warnings about glyphs in the map file that were not found in the TFM file. Warnings never are given for unnamed glyphs or by glyphs named by their Unicode values. This option is useful when sending the output of hpftodit to the standard output stream. -s Add the special directive to the font description file, affect‐ ing the order in which HP symbol sets are searched for each glyph. Without this option, the “text” sets are searched before the “mathematical” symbol sets. With it, the search order is reversed. Files /usr/local/share/groff/1.23.0/font/devlj4/DESC describes the lj4 output device. /usr/local/share/groff/1.23.0/font/devlj4/F describes the font known as F on device lj4. /usr/local/share/groff/1.23.0/font/devlj4/generate/Makefile is a make(1) script that uses hpftodit(1) to prepare the groff font description files above from HP TFM data; in can be used to regenerate them in the event the TFM files are updated. /usr/local/share/groff/1.23.0/font/devlj4/generate/special.awk is an awk(1) script that corrects the Intellifont‐based height metrics for several glyphs in the S (special) font for TrueType CG Times used in the HP LaserJet 4000 and later. /usr/local/share/groff/1.23.0/font/devlj4/generate/special.map /usr/local/share/groff/1.23.0/font/devlj4/generate/symbol.map /usr/local/share/groff/1.23.0/font/devlj4/generate/text.map /usr/local/share/groff/1.23.0/font/devlj4/generate/wingdings.map map MSL indices and HP Unicode PUA assignments to groff special character identifiers. See also groff(1), groff_diff(1), grolj4(1), groff_font(5) groff 1.23.0 29 August 2023 hpftodit(1) ─────────────────────────────────────────────────────────────────────────────── indxbib(1) General Commands Manual indxbib(1) Name indxbib - make inverted index for bibliographic databases Synopsis indxbib [-w] [-c common‐words‐file] [-d dir] [-f list‐file] [-h min‐hash‐table‐size] [-i excluded‐fields] [-k max‐keys‐per‐record] [-l min‐key‐length] [-n threshold] [-o file] [-t max‐key‐length] [file ...] indxbib --help indxbib -v indxbib --version Description indxbib makes an inverted index for the bibliographic databases in each file for use with refer(1), lookbib(1), and lkbib(1). Each created in‐ dex is named file.i; writing is done to a temporary file which is then renamed to this. If no file operands are given on the command line be‐ cause the -f option has been used, and no -o option is given, the index will be named Ind.i. Bibliographic databases are divided into records by blank lines. Within a record, each field starts with a % character at the beginning of a line. Fields have a one letter name that follows the % character. The values set by the -c, -l, -n, and -t options are stored in the in‐ dex: when the index is searched, keys will be discarded and truncated in a manner appropriate to these options; the original keys will be used for verifying that any record found using the index actually con‐ tains the keys. This means that a user of an index need not know whether these options were used in the creation of the index, provided that not all the keys to be searched for would have been discarded dur‐ ing indexing and that the user supplies at least the part of each key that would have remained after being truncated during indexing. The value set by the -i option is also stored in the index and will be used in verifying records found using the index. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -c common‐words‐file Read the list of common words from common‐words‐file instead of /usr/local/share/groff/1.23.0/eign. -d dir Use dir as the name of the directory to store in the index, in‐ stead of that returned by getcwd(2). Typically, dir will be a symbolic link whose target is the current working directory. -f list‐file Read the files to be indexed from list‐file. If list‐file is -, files will be read from the standard input stream. The -f op‐ tion can be given at most once. -h min‐hash‐table‐size Use the first prime number greater than or equal to the argument for the size of the hash table. Larger values will usually make searching faster, but will make the index file larger and cause indxbib to use more memory. The default hash table size is 997. -i excluded‐fields Don’t index the contents of fields whose names are in excluded‐ fields. Field names are one character each. If this option is not present, indxbib excludes fields X, Y, and Z. -k max‐keys‐per‐record Use no more keys per input record than specified in the argu‐ ment. If this option is not present, the maximum is 100. -l min‐key‐length Discard any key whose length in characters is shorter than the value of the argument. If this option is not present, the mini‐ mum key length is 3. -n threshold Discard the threshold most common words from the common words file. If this option is not present, the 100 most common words are discarded. -o basename Name the index basename.i. -t max‐key‐length Truncate keys to max‐key‐length in characters. If this option is not present, keys are truncated to 6 characters. -w Index whole files. Each file is a separate record. Files file.i index for file Ind.i default index name /usr/local/share/groff/1.23.0/eign contains the list of common words. The traditional name, “eign”, is an abbreviation of “English ignored [word list]”. indxbibXXXXXX temporary file See also “Some Applications of Inverted Indexes on the Unix System”, by M. E. Lesk, 1978, AT&T Bell Laboratories Computing Science Technical Report No. 69. refer(1), lkbib(1), lookbib(1) groff 1.23.0 29 August 2023 indxbib(1) ─────────────────────────────────────────────────────────────────────────────── lkbib(1) General Commands Manual lkbib(1) Name lkbib - search bibliographic databases Synopsis lkbib [-n] [-i fields] [-p file] ... [-t n] key ... lkbib --help lkbib -v lkbib --version Description lkbib searches bibliographic databases for references containing key‐ words key and writes any references found to the standard output stream. It reads databases given by -p options and then (unless -n is given) a default database. The default database is taken from the REFER environment variable if it is set, otherwise it is /usr/dict/ papers/Ind. For each database file to be searched, if an index file.i created by indxbib(1) exists, then it will be searched instead; each index can cover multiple databases. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -i string When searching files for which no index exists, ignore the con‐ tents of fields whose names are in string. -n Suppress search of default database. -p file Search file. Multiple -p options can be used. -t n Require only the first n characters of keys to be given. The default is 6. Environment REFER Default database. Files /usr/dict/papers/Ind Default database to be used if the REFER environment variable is not set. file.i Index files. See also “Some Applications of Inverted Indexes on the Unix System”, by M. E. Lesk, 1978, AT&T Bell Laboratories Computing Science Technical Report No. 69. refer(1), lookbib(1), indxbib(1) groff 1.23.0 29 August 2023 lkbib(1) ─────────────────────────────────────────────────────────────────────────────── lookbib(1) General Commands Manual lookbib(1) Name lookbib - search bibliographic databases Synopsis lookbib [-i string] [-t n] file ... lookbib --help lookbib -v lookbib --version Description lookbib writes a prompt to the standard error stream (unless the stan‐ dard input stream is not a terminal), reads from the standard input a line containing a set of keywords, searches each bibliographic database file for references containing those keywords, writes any references found to the standard output stream, and repeats this process until the end of input. For each database file to be searched, if an index file.i created by indxbib(1) exists, then it will be searched instead; each index can cover multiple databases. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -i string When searching files for which no index exists, ignore the con‐ tents of fields whose names are in string. -t n Require only the first n characters of keys to be given. The default is 6. Files file.i Index files. See also “Some Applications of Inverted Indexes on the Unix System”, by M. E. Lesk, 1978, AT&T Bell Laboratories Computing Science Technical Report No. 69. refer(1), lkbib(1), indxbib(1) groff 1.23.0 29 August 2023 lookbib(1) ─────────────────────────────────────────────────────────────────────────────── mmroff(1) General Commands Manual mmroff(1) Name mmroff - cross‐referencing front end for GNU roff mm macro package Synopsis mmroff [-x] groff‐argument ... mmroff --help mmroff --version Description mmroff is a simple wrapper for groff, used to expand cross references in mm; see groff_mm(7). It runs groff with the -mm option twice, first with -z and -rRef=1 to populate cross‐reference and index files with their corresponding entries, and then again to produce the document. It also handles the inclusion of PostScript images with the PIC macro. Documents that do not use these features of groff mm (the INITI, IND, INDP, INITR, SETR, GETHN, GETPN, GETR, GETST, and PIC macros) do not require mmroff. Options --help displays a usage message, while --version shows version informa‐ tion; both exit afterward. -x Create or update the cross‐reference file and exit. Authors mmroff was written by Jörgen Hägg ⟨jh@axis.se⟩ of Lund, Sweden. See also groff_mm(7), groff_mmse(7), groff(1), troff(1), tbl(1), pic(1), eqn(1) groff 1.23.0 29 August 2023 mmroff(1) ─────────────────────────────────────────────────────────────────────────────── neqn(1) General Commands Manual neqn(1) Name neqn - format equations for character‐cell terminal output Synopsis neqn [eqn‐argument ...] Description neqn invokes the eqn(1) command with the ascii output device. eqn does not support low‐resolution, typewriter‐like devices, although it may work adequately for very simple input. See also eqn(1) groff 1.23.0 29 August 2023 neqn(1) ─────────────────────────────────────────────────────────────────────────────── nroff(1) General Commands Manual nroff(1) Name nroff - format documents with groff for TTY (terminal) devices Synopsis nroff [-bcCEhikpRStUVz] [-d ctext] [-d string=text] [-K fallback‐ encoding] [-m macro‐package] [-M macro‐directory] [-n page‐ number] [-o page‐list] [-P postprocessor‐argument] [-r cnumeric‐ expression] [-r register=numeric‐expression] [-T output‐device] [-w warning‐category] [-W warning‐category] [file ...] nroff --help nroff -v nroff --version Description nroff formats documents written in the groff(7) language for type‐ writer‐like devices such as terminal emulators. GNU nroff emulates the AT&T nroff command using groff(1). nroff generates output via grotty(1), groff’s terminal output driver, which needs to know the character encoding scheme used by the device. Consequently, acceptable arguments to the -T option are ascii, latin1, utf8, and cp1047; any others are ignored. If neither the GROFF_TYPESETTER environment vari‐ able nor the -T command‐line option (which overrides the environment variable) specifies a (valid) device, nroff consults the locale to se‐ lect an appropriate output device. It first tries the locale(1) pro‐ gram, then checks several locale‐related environment variables; see section “Environment” below. If all of the foregoing fail, -Tascii is implied. The -b, -c, -C, -d, -E, -i, -m, -M, -n, -o, -r, -U, -w, -W, and -z op‐ tions have the effects described in troff(1). -c and -h imply “-P-c” and “-P-h”, respectively; -c is also interpreted directly by troff. In addition, this implementation ignores the AT&T nroff options -e, -q, and -s (which are not implemented in groff). The options -k, -K, -p, -P, -R, -t, and -S are documented in groff(1). -V causes nroff to dis‐ play the constructed groff command on the standard output stream, but does not execute it. -v and --version show version information about nroff and the programs it runs, while --help displays a usage message; all exit afterward. Exit status nroff exits with error status 2 if there was a problem parsing its ar‐ guments, with status 0 if any of the options -V, -v, --version, or --help were specified, and with the status of groff otherwise. Environment Normally, the path separator in environment variables ending with PATH is the colon; this may vary depending on the operating system. For ex‐ ample, Windows uses a semicolon instead. GROFF_BIN_PATH is a colon‐separated list of directories in which to search for the groff executable before searching in PATH. If unset, /usr/ local/bin is used. GROFF_TYPESETTER specifies the default output device for groff. LC_ALL LC_CTYPE LANG LESSCHARSET are pattern‐matched in this order for contents matching standard character encodings supported by groff in the event no -T option is given and GROFF_TYPESETTER is unset, or the values specified are invalid. Files /usr/local/share/groff/1.23.0/tmac/tty-char.tmac defines fallback definitions of roff special characters. These definitions more poorly optically approximate typeset output than those of tty.tmac in favor of communicating semantic infor‐ mation. nroff loads it automatically. Notes Pager programs like more(1) and less(1) may require command‐line op‐ tions to correctly handle some output sequences; see grotty(1). See also groff(1), troff(1), grotty(1), locale(1), roff(7) groff 1.23.0 29 August 2023 nroff(1) ─────────────────────────────────────────────────────────────────────────────── pdfmom(1) General Commands Manual pdfmom(1) Name pdfmom - produce PDF documents using the mom macro package for groff Synopsis pdfmom [-Tpdf] [groff‐options] [file ...] pdfmom -Tps [pdfroff‐options] [groff‐options] [file ...] pdfmom -v pdfmom --version Description pdfmom is a wrapper around groff(1) that facilitates the production of PDF documents from files formatted with the mom macros. pdfmom prints to the standard output, so output must usually be redi‐ rected to a destination file. The size of the final PDF can be reduced by piping the output through ps2pdf(1). If called with the -Tpdf option (which is the default), pdfmom processes files using groff’s native PDF driver, gropdf(1). If -Tps is given, processing is passed over to pdfroff, which uses groff’s Post‐ Script driver. In either case, multiple runs of the source file are performed in order to satisfy any forward references in the document. pdfmom accepts all the same options as groff. If -Tps is given, the options associated with pdfroff are accepted as well. When pdfmom calls pdfroff, the options “-mpdfmark -mom --no-toc” options are im‐ plied and should not be given on the command line. Equally, it is not necessary to supply the -mom or -m mom options when -Tps is absent. PDF integration with the mom macros is discussed in full in the manual “Producing PDFs with groff and mom”, which was itself produced with pdfmom. If called with the -v or --version options, pdfmom displays its version information and exits. Authors pdfmom was written by Deri James ⟨deri@chuzzlewit.myzen.co.uk⟩ and Pe‐ ter Schaffter ⟨peter@schaffter.ca⟩, and is maintained by James. See also /usr/local/share/doc/groff-1.23.0/pdf/mom-pdf.pdf “Producing PDFs with groff and mom”, by Deri James and Peter Schaffter. This file, together with its source, mom-pdf.mom, is part of the groff distribution. groff(1), gropdf(1), pdfroff(1), ps2pdf(1) groff 1.23.0 29 August 2023 pdfmom(1) ─────────────────────────────────────────────────────────────────────────────── pdfroff(1) General Commands Manual pdfroff(1) Name pdfroff - construct files in Portable Document Format using groff Synopsis pdfroff [groff‐option] [--emit-ps] [--no-toc-relocation] [--no-kill-null-pages] [--stylesheet=name] [--no-pdf-output] [--pdf-output=name] [--no-reference-dictionary] [--reference-dictionary=name] [--report-progress] [--keep-temporary-files] [file ...] pdfroff -h pdfroff --help pdfroff -v [groff‐option ...] pdfroff --version [groff‐option ...] groff‐option is any short option supported by groff(1) except for -h, -T, and -v; see section “Usage” below. Description pdfroff is a wrapper program for the GNU text processing system, groff. It transparently handles the mechanics of multiple pass groff process‐ ing, when applied to suitably marked up groff source files, such that tables of contents and body text are formatted separately, and are sub‐ sequently combined in the correct order, for final publication as a single PDF document. A further optional “style sheet” capability is provided; this allows for the definition of content which is required to precede the table of contents, in the published document. For each invocation of pdfroff, the ultimate groff output stream is post‐processed by the Ghostscript gs(1) interpreter to produce a fin‐ ished PDF document. pdfroff makes no assumptions about, and imposes no restrictions on, the use of any groff macro packages which the user may choose to employ, in order to achieve a desired document format; however, it does include specific built in support for the pdfmark macro package, should the user choose to employ it. Specifically, if the pdfhref macro, defined in the pdfmark.tmac package, is used to define public reference marks, or dynamic links to such reference marks, then pdfroff performs as many preformatting groff passes as required, up to a maximum limit of four, in order to compile a document reference dictionary, to resolve refer‐ ences, and to expand the dynamically defined content of links. Usage The command line is parsed in accordance with normal GNU conventions, but with one exception—when specifying any short form option (i.e., a single character option introduced by a single hyphen), and if that op‐ tion expects an argument, then it must be specified independently (i.e., it may not be appended to any group of other single character short form options). Long form option names (i.e., those introduced by a double hyphen) may be abbreviated to their minimum length unambiguous initial substring. Otherwise, pdfroff usage closely mirrors that of groff itself. Indeed, with the exception of the -h, -v, and -T dev short form options, and all long form options, which are parsed internally by pdfroff, all op‐ tions and file name arguments specified on the command line are passed on to groff, to control the formatting of the PDF document. Conse‐ quently, pdfroff accepts all options and arguments, as specified in groff(1), which may also be considered as the definitive reference for all standard pdfroff options and argument usage. Options pdfroff accepts all of the short form options (i.e., those introduced by a single hyphen), which are available with groff itself. In most cases, these are simply passed transparently to groff; the following, however, are handled specially by pdfroff. -h Same as --help; see below. -i Process standard input, after all other specified input files. This is passed transparently to groff, but, if grouped with other options, it must be the first in the group. Hiding it within a group breaks standard input processing, in the multi‐ ple‐pass groff processing context of pdfroff. -T dev Only -T ps is supported by pdfroff. Attempting to specify any other device causes pdfroff to abort. -v Same as --version; see below. See groff(1) for a description of all other short form options, which are transparently passed through pdfroff to groff. All long form options (i.e., those introduced by a double hyphen) are interpreted locally by pdfroff; they are not passed on to groff, unless otherwise stated below. --help Causes pdfroff to display a summary of the its usage syntax, and supported options, and then exit. --emit-ps Suppresses the final output conversion step, causing pdfroff to emit PostScript output instead of PDF. This may be useful to capture intermediate PostScript output when using a specialised postprocessor, such as gpresent for example, in place of the de‐ fault Ghostscript PDF writer. --keep-temporary-files Suppresses the deletion of temporary files, which normally oc‐ curs after pdfroff has completed PDF document formatting; this may be useful when debugging formatting problems. See section “Files” below for a description of the temporary files used by pdfroff. --no-pdf-output May be used with the --reference-dictionary=name option (de‐ scribed below) to eliminate the overhead of PDF formatting when running pdfroff to create a reference dictionary for use in a different document. --no-reference-dictionary May be used to eliminate the overhead of creating a reference dictionary, when it is known that the target PDF document con‐ tains no public references, created by the pdfhref macro. --no-toc-relocation May be used to eliminate the extra groff processing pass, which is required to generate a table of contents, and relocate it to the start of the PDF document, when processing any document which lacks an automatically generated table of contents. --no-kill-null-pages While preparing for simulation of the manual collation step, which is traditionally required to relocate a table of contents to the start of a document, pdfroff accumulates a number of empty page descriptions into the intermediate PostScript output stream. During the final collation step, these empty pages are normally discarded from the finished document; this option forces pdfroff to leave them in place. --pdf-output=name Specifies the name to be used for the resultant PDF document; if unspecified, the PDF output is written to standard output. A future version of pdfroff may use this option, to encode the document name in a generated reference dictionary. --reference-dictionary=name Specifies the name to be used for the generated reference dic‐ tionary file; if unspecified, the reference dictionary is cre‐ ated in a temporary file, which is deleted when pdfroff com‐ pletes processing of the current document. This option must be specified, if it is desired to save the reference dictionary, for use in references placed in other PDF documents. --report-progress Causes pdfroff to display an informational message on standard error, at the start of each groff processing pass. --stylesheet=name Specifies the name of an input file, to be used as a style sheet for formatting of content, which is to be placed before the ta‐ ble of contents, in the formatted PDF document. --version Causes pdfroff to display a version identification message. The entire command line is then passed transparently to groff, in a one pass operation only, in order to display the associated groff version information, before exiting. Environment The following environment variables may be set, and exported, to modify the behaviour of pdfroff. PDFROFF_COLLATE Specifies the program to be used for collation of the finished PDF document. This collation step may be required to move tables of contents to the start of the finished PDF document, when formatting with traditional macro packages, which print them at the end. How‐ ever, users should not normally need to specify PDFROFF_COLLATE, (and indeed, are not encouraged to do so). If unspecified, pdfroff uses sed(1) by default, which normally suffices. If PDFROFF_COLLATE is specified, then it must act as a filter, accepting a list of file name arguments, and write its output to the standard output stream, whence it is piped to the PDFROFF_POSTPROCESSOR_COMMAND, to produce the finished PDF out‐ put. When specifying PDFROFF_COLLATE, it is normally necessary to also specify PDFROFF_KILL_NULL_PAGES. PDFROFF_COLLATE is ignored, if pdfroff is invoked with the --no-kill-null-pages option. PDFROFF_KILL_NULL_PAGES Specifies options to be passed to the PDFROFF_COLLATE program. It should not normally be necessary to specify PDFROFF_KILL_NULL_PAGES. The internal default is a sed(1) script, which is intended to remove completely blank pages from the collated output stream, and which should be appropriate in most applications of pdfroff. However, if any alternative to sed(1) is specified for PDFROFF_COLLATE, then it is likely that a corresponding alternative specification for PDFROFF_KILL_NULL_PAGES is required. As in the case of PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES is ignored, if pdfroff is invoked with the --no-kill-null-pages op‐ tion. PDFROFF_POSTPROCESSOR_COMMAND Specifies the command to be used for the final document conver‐ sion from PostScript intermediate output to PDF. It must behave as a filter, writing its output to the standard output stream, and must accept an arbitrary number of files ... arguments, with the special case of “-” representing the standard input stream. If unspecified, PDFROFF_POSTPROCESSOR_COMMAND defaults to gs -dBATCH -dQUIET -dNOPAUSE -dSAFER -sDEVICE=pdfwrite \ -sOutputFile=- GROFF_TMPDIR Identifies the directory in which pdfroff should create tempo‐ rary files. If GROFF_TMPDIR is not specified, then the vari‐ ables TMPDIR, TMP and TEMP are considered in turn as possible temporary file repositories. If none of these are set, then temporary files are created in the current directory. GROFF_GHOSTSCRIPT_INTERPRETER Specifies the program to be invoked when pdfroff converts groff PostScript output to PDF. If PDFROFF_POSTPROCESSOR_COMMAND is specified, then the command name it specifies is implicitly as‐ signed to GROFF_GHOSTSCRIPT_INTERPRETER, overriding any explicit setting specified in the environment. If GROFF_GHOSTSCRIPT_INTERPRETER is not specified, then pdfroff searches the process PATH, looking for a program with any of the well known names for the Ghostscript interpreter; if no Ghost‐ script interpreter can be found, pdfroff aborts. GROFF_AWK_INTERPRETER Specifies the program to be invoked when pdfroff is extracting reference dictionary entries from a groff intermediate message stream. If GROFF_AWK_INTERPRETER is not specified, then pdfroff searches the process PATH, looking for any of the preferred pro‐ grams, gawk, mawk, nawk, and awk, in that order; if none of these are found, pdfroff issues a warning message, and continue processing; however, in this case, no reference dictionary is created. OSTYPE Typically defined automatically by the operating system, OSTYPE is used on Microsoft Win32/MS‐DOS platforms only, to infer the default PATH_SEPARATOR character, which is used when parsing the process PATH to search for external helper programs. PATH_SEPARATOR If set, PATH_SEPARATOR overrides the default separator charac‐ ter, (‘:’ on POSIX/Unix systems, inferred from OSTYPE on Mi‐ crosoft Win32/MS‐DOS), which is used when parsing the process PATH to search for external helper programs. SHOW_PROGRESS If this is set to a non‐empty value, then pdfroff always behaves as if the --report-progress option is specified on the command line. Files Input and output files for pdfroff may be named according to any con‐ vention of the user’s choice. Typically, input files may be named ac‐ cording to the choice of the principal normatting macro package, e.g., file.ms might be an input file for formatting using the ms macros (s.tmac); normally, the final output file should be named file.pdf. Temporary files created by pdfroff are placed in the file system hier‐ archy, in or below the directory specified by environment variables (see section “Environment” above). If mktemp(1) is available, it is invoked to create a private subdirectory of the nominated temporary files directory, (with subdirectory name derived from the template pdfroff-XXXXXXXXXX); if this subdirectory is successfully created, the temporary files will be placed within it, otherwise they will be placed directly in the directory nominated in the environment. All temporary files themselves are named according to the convention pdf$$.*, where $$ is the standard shell variable representing the process identifier of the pdfroff process itself, and * represents any of the extensions used by pdfroff to identify the following temporary and intermediate files. pdf$$.tmp A scratch pad file, used to capture reference data emitted by groff, during the reference dictionary compilation phase. pdf$$.ref The reference dictionary, as compiled in the last but one pass of the reference dictionary compilation phase; (at the start of the first pass, this file is created empty; in successive passes, it contains the reference dictionary entries, as col‐ lected in the preceding pass). If the --reference-dictionary=name option is specified, this in‐ termediate file becomes permanent, and is named name, rather than pdf$$.ref. pdf$$.cmp Used to collect reference dictionary entries during the active pass of the reference dictionary compilation phase. At the end of any pass, when the content of pdf$$.cmp compares as identical to pdf$$.ref, (or the corresponding file named by the --reference-dictionary=name option), then reference dictionary compilation is terminated, and the document reference map is ap‐ pended to this intermediate file, for inclusion in the final formatting passes. pdf$$.tc An intermediate PostScript file, in which “Table of Contents” entries are collected, to facilitate relocation before the body text, on ultimate output to the Ghostscript postprocessor. pdf$$.ps An intermediate PostScript file, in which the body text is col‐ lected prior to ultimate output to the Ghostscript postproces‐ sor, in the proper sequence, after pdf$$.tc. Authors pdfroff was written by Keith Marshall ⟨keith.d.marshall@ntlworld.com⟩, who maintains it at his groff‐pdfmark OSDN site ⟨https://osdn.net/ users/keith/pf/groff‐pdfmark/wiki/FrontPage⟩. groff’s version may be withdrawn in a future release. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. Since pdfroff provides a superset of all groff capabilities, the above manual, or its terser reference page, groff(7) may also be considered definitive references to all standard capabilities of pdfroff, with this document providing the reference to pdfroff’s extended features. While pdfroff imposes neither any restriction on, nor any requirement for, the use of any specific groff macro package, a number of supplied macro packages, and in particular those associated with the package pdfmark.tmac, are best suited for use with pdfroff as the preferred formatter. /usr/local/share/doc/groff-1.23.0/pdf/pdfmark.pdf “Portable Document Format Publishing with GNU Troff”, by Keith Marshall, offers detailed documentation on the use of these packages. This file, together with its source, pdfmark.ms, is part of the groff distribution. groff 1.23.0 29 August 2023 pdfroff(1) ─────────────────────────────────────────────────────────────────────────────── pfbtops(1) General Commands Manual pfbtops(1) Name pfbtops - translate PostScript Printer Font Binary files to Printer Font ASCII Synopsis pfbtops [pfb‐file] pfbtops --help pfbtops -v pfbtops --version Description pfbtops translates a PostScript Type 1 font in Printer Font Binary (PFB) format to Printer Font ASCII (PFA) format, splitting overlong lines in text packets into smaller chunks. If pfb‐file is omitted, the PFB file will be read from the standard input stream. The PFA font will be written on the standard output stream. PostScript fonts for MS‐DOS were historically supplied in PFB format. Use of a PostScript Type 1 font with groff requires conversion of its metrics (AFM file) to a groff font description file; see afmtodit(1). The --help option displays a usage message, while -v and --version show version information; all exit afterward. See also grops(1), gropdf(1) groff 1.23.0 29 August 2023 pfbtops(1) ─────────────────────────────────────────────────────────────────────────────── pic(1) General Commands Manual pic(1) Name pic - compile pictures for troff or TeX Synopsis pic [-CnSU] [file ...] pic -t [-cCSUz] [file ...] pic --help pic -v pic --version Description The GNU implementation of pic is part of the groff(1) document format‐ ting system. pic is a troff(1) preprocessor that translates descrip‐ tions of diagrammatic pictures embedded in roff(7) or TeX input files into the language understood by TeX or troff. It copies the contents of each file to the standard output stream, except that lines between .PS and any of .PE, .PF, or .PY are interpreted as picture descriptions in the pic language. End a pic picture with .PE to leave the drawing position at the bottom of the picture, and with .PF or .PY to leave it at the top. Normally, pic is not executed directly by the user, but invoked by specifying the -p option to groff(1). If no file operands are given on the command line, or if file is “-”, the standard input stream is read. It is the user’s responsibility to provide appropriate definitions of the PS, PE, and one or both of the PF and PY macros. When a macro package does not supply these, obtain simple definitions with the groff option -mpic; these will center each picture. GNU pic supports PY as a synonym of PF to work around a name space col‐ lision with the mm macro package, which defines PF as a page footer management macro. Use PF preferentially unless a similar problem faces your document. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -c Be more compatible with tpic; implies -t. Lines beginning with \ are not passed through transparently. Lines beginning with . are passed through with the initial . changed to \. A line be‐ ginning with .ps is given special treatment: it takes an op‐ tional integer argument specifying the line thickness (pen size) in milliinches; a missing argument restores the previous line thickness; the default line thickness is 8 milliinches. The line thickness thus specified takes effect only when a non‐nega‐ tive line thickness has not been specified by use of the thickness attribute or by setting the linethick variable. -C Recognize .PS, .PE, .PF, and .PY even when followed by a charac‐ ter other than space or newline. -n Don’t use groff extensions to the troff drawing commands. Spec‐ ify this option if a postprocessor you’re using doesn’t support these extensions, described in groff_out(5). This option also causes pic not to use zero‐length lines to draw dots in troff mode. -S Operate in safer mode; sh commands are ignored. This mode, en‐ abled by default, can be useful when operating on untrustworthy input. -t Produce TeX output. -U Operate in unsafe mode; sh commands are interpreted. -z In TeX mode, draw dots using zero‐length lines. The following options supported by other versions of pic are ignored. -D Draw all lines using the \D escape sequence. GNU pic always does this. -T dev Generate output for the troff device dev. This is unnecessary because the troff output generated by GNU pic is device‐indepen‐ dent. Usage This section primarily discusses the differences between GNU pic and the Eighth Edition Research Unix version of AT&T pic (1985). Many of these differences also apply to later versions of AT&T pic. TeX mode TeX‐compatible output is produced when the -t option is specified. You must use a TeX driver that supports tpic version 2 specials. (tpic was a fork of AT&T pic by Tim Morgan of the University of California at Irvine that diverged from its source around 1984. It is best known to‐ day for lending its name to a group of \special commands it produced for TeX.) Lines beginning with \ are passed through transparently; a % is added to the end of the line to avoid unwanted spaces. You can safely use this feature to change fonts or the value of \baselineskip. Anything else may well produce undesirable results; use at your own risk. By default, lines beginning with a dot are not treated specially—but see the -c option. In TeX mode, pic will define a vbox called \graph for each picture. Use GNU pic’s figname command to change the name of the vbox. You must print that vbox yourself using the command \centerline{\box\graph} for instance. Since the vbox has a height of zero (it is defined with \vtop) this will produce slightly more vertical space above the picture than below it; \centerline{\raise 1em\box\graph} would avoid this. To give the vbox a positive height and a depth of zero (as used by LaTeX’s graphics.sty, for example) define the follow‐ ing macro in your document. \def\gpicbox#1{% \vbox{\unvbox\csname #1\endcsname\kern 0pt}} You can then simply say \gpicbox{graph} instead of \box\graph. Commands Several commands new to GNU pic accept delimiters, shown in their syn‐ opses as braces { }. Nesting of braces is supported. Any other char‐ acters (except a space, tab, or newline) may be used as alternative de‐ limiters, in which case the members of a given pair must be identical. Strings are recognized within delimiters of either kind; they may con‐ tain the delimiter character or unbalanced braces. for variable = expr1 to expr2 [by [*]expr3] do X body X Set variable to expr1. While the value of variable is less than or equal to expr2, do body and increment variable by expr3; if by is not given, increment variable by 1. If expr3 is prefixed by * then variable will instead be multiplied by expr3. The value of expr3 can be negative for the additive case; variable is then tested whether it is greater than or equal to expr2. For the multiplicative case, expr3 must be greater than zero. If the constraints aren’t met, the loop isn’t executed. X can be any character not occurring in body. if expr then X if‐true X [else Y if‐false Y] Evaluate expr; if it is non‐zero then do if‐true, otherwise do if‐false. X can be any character not occurring in if‐true. Y can be any character not occurring in if‐false. print arg ... Concatenate and write arguments to the standard error stream followed by a newline. Each arg must be an expression, a posi‐ tion, or text. This is useful for debugging. command arg ... Concatenate arguments and pass them as a line to troff or TeX. Each arg must be an expression, a position, or text. command allows the values of pic variables to be passed to the format‐ ter. For example, .PS x = 14 command ".ds string x is " x "." .PE \*[string] produces x is 14. when formatted with troff. sh X command X Pass command to a shell. copy "filename" Include filename at this point in the file. copy ["filename"] thru X body X [until "word"] copy ["filename"] thru macro [until "word"] This construct does body once for each line of filename; the line is split into blank‐delimited words, and occurrences of $i in body, for i between 1 and 9, are replaced by the i‐th word of the line. If filename is not given, lines are taken from the current input up to .PE. If an until clause is specified, lines will be read only until a line the first word of which is word; that line will then be discarded. X can be any character not occurring in body. For example, .PS copy thru % circle at ($1,$2) % until "END" 1 2 3 4 5 6 END box .PE and .PS circle at (1,2) circle at (3,4) circle at (5,6) box .PE are equivalent. The commands to be performed for each line can also be taken from a macro defined earlier by giving the name of the macro as the argument to thru. The argument after thru is looked up as a macro name first; if not defined, its first char‐ acter is interpreted as a delimiter. reset reset pvar1[,] pvar2 ... Reset predefined variables pvar1, pvar2 ... to their default values; if no arguments are given, reset all predefined vari‐ ables to their default values. Variable names may be separated by commas, spaces, or both. Assigning a value to scale also causes all predefined variables that control dimensions to be reset to their default values times the new value of scale. plot expr ["text"] This is a text object which is constructed by using text as a format string for sprintf with an argument of expr. If text is omitted a format string of "%g" is used. Attributes can be specified in the same way as for a normal text object. Be very careful that you specify an appropriate format string; pic does only very limited checking of the string. This is deprecated in favour of sprintf. var := expr This syntax resembles variable assignment with = except that var must already be defined, and expr will be assigned to var with‐ out creating a variable local to the current block. (By con‐ trast, = defines var in the current block if it is not already defined there, and then changes the value in the current block only.) For example, .PS x = 3 y = 3 [ x := 5 y = 5 ] print x y .PE writes 5 3 to the standard error stream. Expressions The syntax for expressions has been significantly extended. x ^ y (exponentiation) sin(x) cos(x) atan2(y, x) log(x) (base 10) exp(x) (base 10, i.e. 10^x) sqrt(x) int(x) rand() (return a random number between 0 and 1) rand(x) (return a random number between 1 and x; deprecated) srand(x) (set the random number seed) max(e1, e2) min(e1, e2) !e e1 && e2 e1 || e2 e1 == e2 e1 != e2 e1 >= e2 e1 > e2 e1 <= e2 e1 < e2 "str1" == "str2" "str1" != "str2" String comparison expressions must be parenthesised in some contexts to avoid ambiguity. Other changes A bare expression, expr, is acceptable as an attribute; it is equiva‐ lent to dir expr, where dir is the current direction. For example line 2i means draw a line 2 inches long in the current direction. The ‘i’ (or ‘I’) character is ignored; to use another measurement unit, set the scale variable to an appropriate value. The maximum width and height of the picture are taken from the vari‐ ables maxpswid and maxpsht. Initially, these have values 8.5 and 11. Scientific notation is allowed for numbers. For example x = 5e-2 Text attributes can be compounded. For example, "foo" above ljust is valid. There is no limit to the depth to which blocks can be examined. For example, [A: [B: [C: box ]]] with .A.B.C.sw at 1,2 circle at last [].A.B.C is acceptable. Arcs now have compass points determined by the circle of which the arc is a part. Circles, ellipses, and arcs can be dotted or dashed. In TeX mode splines can be dotted or dashed also. Boxes can have rounded corners. The rad attribute specifies the radius of the quarter‐circles at each corner. If no rad or diam attribute is given, a radius of boxrad is used. Initially, boxrad has a value of 0. A box with rounded corners can be dotted or dashed. Boxes can have slanted sides. This effectively changes the shape of a box from a rectangle to an arbitrary parallelogram. The xslanted and yslanted attributes specify the x and y offset of the box’s upper right corner from its default position. The .PS line can have a second argument specifying a maximum height for the picture. If the width of zero is specified the width will be ig‐ nored in computing the scaling factor for the picture. GNU pic will always scale a picture by the same amount vertically as well as hori‐ zontally. This is different from DWB 2.0 pic which may scale a picture by a different amount vertically than horizontally if a height is spec‐ ified. Each text object has an invisible box associated with it. The compass points of a text object are determined by this box. The implicit mo‐ tion associated with the object is also determined by this box. The dimensions of this box are taken from the width and height attributes; if the width attribute is not supplied then the width will be taken to be textwid; if the height attribute is not supplied then the height will be taken to be the number of text strings associated with the ob‐ ject times textht. Initially, textwid and textht have a value of 0. In (almost all) places where a quoted text string can be used, an ex‐ pression of the form sprintf("format", arg, ...) can also be used; this will produce the arguments formatted according to format, which should be a string as described in printf(3) appropri‐ ate for the number of arguments supplied. Only the modifiers “#”, “-”, “+”, and “ ” [space]), a minimum field width, an optional precision, and the conversion specifiers %e, %E, %f, %g, %G, and %% are supported. The thickness of the lines used to draw objects is controlled by the linethick variable. This gives the thickness of lines in points. A negative value means use the default thickness: in TeX output mode, this means use a thickness of 8 milliinches; in TeX output mode with the -c option, this means use the line thickness specified by .ps lines; in troff output mode, this means use a thickness proportional to the pointsize. A zero value means draw the thinnest possible line sup‐ ported by the output device. Initially, it has a value of -1. There is also a thick[ness] attribute. For example, circle thickness 1.5 would draw a circle using a line with a thickness of 1.5 points. The thickness of lines is not affected by the value of the scale variable, nor by the width or height given in the .PS line. Boxes (including boxes with rounded corners or slanted sides), circles and ellipses can be filled by giving them an attribute of fill[ed]. This takes an optional argument of an expression with a value between 0 and 1; 0 will fill it with white, 1 with black, values in between with a proportionally gray shade. A value greater than 1 can also be used: this means fill with the shade of gray that is currently being used for text and lines. Normally this will be black, but output devices may provide a mechanism for changing this. Without an argument, then the value of the variable fillval will be used. Initially, this has a value of 0.5. The invisible attribute does not affect the filling of objects. Any text associated with a filled object will be added after the object has been filled, so that the text will not be obscured by the filling. Additional modifiers are available to draw colored objects: outline[d] sets the color of the outline, shaded the fill color, and colo[u]r[ed] sets both. All expect a subsequent string argument specifying the color. circle shaded "green" outline "black" Color is not yet supported in TeX mode. Device macro files like ps.tmac declare color names; you can define additional ones with the defcolor request (see groff(7)). To change the name of the vbox in TeX mode, set the pseudo‐variable figname (which is actually a specially parsed command) within a pic‐ ture. Example: .PS figname = foobar; ... .PE The picture is then available in the box \foobar. pic assumes that at the beginning of a picture both glyph and fill color are set to the default value. Arrow heads will be drawn as solid triangles if the variable arrowhead is non‐zero and either TeX mode is enabled or the -n option has not been given. Initially, arrowhead has a value of 1. Solid arrow heads are always filled with the current outline color. The troff output of pic is device‐independent. The -T option is there‐ fore redundant. All numbers are taken to be in inches; numbers are never interpreted to be in troff machine units. Objects can have an aligned attribute. This will only work if the postprocessor is grops(1) or gropdf(1). Any text associated with an object having the aligned attribute will be rotated about the center of the object so that it is aligned in the direction from the start point to the end point of the object. This attribute will have no effect on objects whose start and end points are coincident. In places where nth is allowed, 'expr'th is also allowed. “'th“ is a single token: no space is allowed between the apostrophe and the “th”. For example, for i = 1 to 4 do { line from 'i'th box.nw to 'i+1'th box.se } Conversion To obtain a stand‐alone picture from a pic file, enclose your pic code with .PS and .PE requests; roff configuration commands may be added at the beginning of the file, but no roff text. It is necessary to feed this file into groff without adding any page information, so you must check which .PS and .PE requests are actually called. For example, the mm macro package adds a page number, which is very annoying. At the moment, calling standard groff without any macro package works. Alternatively, you can define your own requests, e.g., to do nothing: .de PS .. .de PE .. groff itself does not provide direct conversion into other graphics file formats. But there are lots of possibilities if you first trans‐ form your picture into PostScript® format using the groff option -Tps. Since this ps‐file lacks BoundingBox information it is not very useful by itself, but it may be fed into other conversion programs, usually named ps2other or pstoother or the like. Moreover, the PostScript in‐ terpreter Ghostscript (gs(1)) has built‐in graphics conversion devices that are called with the option gs -sDEVICE= Call gs --help for a list of the available devices. An alternative may be to use the -Tpdf option to convert your picture directly into PDF format. The MediaBox of the file produced can be controlled by passing a -P-p papersize to groff. As the Encapsulated PostScript File Format EPS is getting more and more important, and the conversion wasn’t regarded trivial in the past you might be interested to know that there is a conversion tool named ps2eps which does the right job. It is much better than the tool ps2epsi packaged with gs. For bitmapped graphic formats, you should use pstopnm; the resulting (intermediate) pnm(5) file can be then converted to virtually any graphics format using the tools of the netpbm package. Files /usr/local/share/groff/1.23.0/tmac/pic.tmac offers simple definitions of the PS, PE, PF, and PY macros. Bugs Characters that are invalid as input to GNU troff (see the groff Tex‐ info manual or groff_char(7) for a list) are rejected even in TeX mode. The interpretation of fillval is incompatible with the pic in Tenth Edition Research Unix, which interprets 0 as black and 1 as white. See also /usr/local/share/doc/groff-1.23.0/pic.ps “Making Pictures with GNU pic”, by Eric S. Raymond. This file, together with its source, pic.ms, is part of the groff distribu‐ tion. “PIC—A Graphics Language for Typesetting: User Manual”, by Brian W. Kernighan, 1984 (revised 1991), AT&T Bell Laboratories Computing Sci‐ ence Technical Report No. 116 ps2eps is available from CTAN mirrors, e.g., ⟨ftp://ftp.dante.de/ tex-archive/support/ps2eps/⟩ W. Richard Stevens, Turning PIC into HTML ⟨http://www.kohala.com/start/ troff/pic2html.html⟩ W. Richard Stevens, Examples of pic Macros ⟨http://www.kohala.com/ start/troff/pic.examples.ps⟩ troff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1), ps2epsi(1), pnm(5) groff 1.23.0 29 August 2023 pic(1) ─────────────────────────────────────────────────────────────────────────────── pic2graph(1) General Commands Manual pic2graph(1) Name pic2graph - convert a pic diagram into a cropped image Synopsis pic2graph [-unsafe] [-format output‐format] [-eqn delimiters] [convert‐ argument ...] pic2graph --help pic2graph -v pic2graph --version Description pic2graph reads a pic(1) program from the standard input and writes an image file, by default in Portable Network Graphics (PNG) format, to the standard output. It furthermore translates eqn(1) constructs, so it can be used for generating images of mathematical formulae. The input PIC code should not be wrapped with the .PS and .PE/.PF macros that normally guard it within groff(1) documents. Arguments not recognized by pic2graph are passed to the ImageMagick or GraphicsMagick program convert(1). By specifying these, you can give your image a border, set the image’s pixel density, or perform other useful transformations. The output image is clipped using convert’s -trim option to the small‐ est possible bounding box that contains all the black pixels. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -eqn delimiters Use delimiters as the opening and closing characters that de‐ limit eqn directives; the default is “$$”. The option argument delimiters should be a two‐character string, but an empty string ("") is accepted as a directive to disable eqn processing. -format output‐format Write the image in output‐format, which must be understood by convert; the default is PNG. -unsafe Run groff in unsafe mode, enabling the PIC command sh to execute arbitrary Unix shell commands. The groff default is to forbid this. Environment GROFF_TMPDIR TMPDIR TMP TEMP These environment variables are searched in the given order to determine the directory where temporary files will be created. If none are set, /tmp is used. Authors pic2graph was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a recipe by W. Richard Stevens. See also W. Richard Stevens, Turning PIC into HTML ⟨http://www.kohala.com/start/ troff/pic2html.html⟩ eqn2graph(1), grap2graph(1), pic(1), eqn(1), groff(1), convert(1) groff 1.23.0 29 August 2023 pic2graph(1) ─────────────────────────────────────────────────────────────────────────────── preconv(1) General Commands Manual preconv(1) Name preconv - prepare files for typesetting with groff Synopsis preconv [-dr] [-D fallback‐encoding] [-e encoding] [file ...] preconv -h preconv --help preconv -v preconv --version Description preconv reads each file, converts its encoded characters to a form troff(1) can interpret, and sends the result to the standard output stream. Currently, this means that code points in the range 0–127 (in US‐ASCII, ISO 8859, or Unicode) remain as‐is and the remainder are con‐ verted to the groff special character form “\[uXXXX]”, where XXXX is a hexadecimal number of four to six digits corresponding to a Unicode code point. By default, preconv also inserts a roff .lf request at the beginning of each file, identifying it for the benefit of later pro‐ cessing (including diagnostic messages); the -r option suppresses this behavior. In typical usage scenarios, preconv need not be run directly; instead it should be invoked with the -k or -K options of groff. If no file operands are given on the command line, or if file is “-”, the standard input stream is read. preconv tries to find the input encoding with the following algorithm, stopping at the first success. 1. If the input encoding has been explicitly specified with option -e, use it. 2. If the input starts with a Unicode Byte Order Mark, determine the encoding as UTF‐8, UTF‐16, or UTF‐32 accordingly. 3. If the input stream is seekable, check the first and second input lines for a recognized GNU Emacs file‐local variable identifying the character encoding, here referred to as the “coding tag” for brevity. If found, use it. 4. If the input stream is seekable, and if the uchardet library is available on the system, use it to try to infer the encoding of the file. 5. If the -D option specifies an encoding, use it. 6. Use the encoding specified by the current locale (LC_CTYPE), unless the locale is “C”, “POSIX”, or empty, in which case assume Latin‐1 (ISO 8859‐1). The coding tag and uchardet methods in the above procedure rely upon a seekable input stream; when preconv reads from a pipe, the stream is not seekable, and these detection methods are skipped. If character encoding detection of your input files is unreliable, arrange for one of the other methods to succeed by using preconv’s -D or -e options, or by configuring your locale appropriately. groff also supports a GROFF_ENCODING environment variable, which can be overridden by its -K option. Valid values for (or parameters to) all of these are enumer‐ ated in the lists of recognized coding tags in the next subsection, and are further influenced by iconv library support. Coding tags Text editors that support more than a single character encoding need tags within the input files to mark the file’s encoding. While it is possible to guess the right input encoding with the help of heuristics that are reliable for a preponderance of natural language texts, they are not absolutely reliable. Heuristics can fail on inputs that are too short or don’t represent a natural language. Consequently, preconv supports the coding tag convention used by GNU Emacs (with some restrictions). This notation appears in specially marked regions of an input file designated for “file‐local variables”. preconv interprets the following syntax if it occurs in a roff comment in the first or second line of the input file. Both “\"” and “\#” com‐ ment forms are recognized, but the control (or no‐break control) char‐ acter must be the default and must begin the line. Similarly, the es‐ cape character must be the default. -*- [...;] coding: encoding[; ...] -*- The only variable preconv interprets is “coding”, which can take the values listed below. The following list comprises all MIME “charset” parameter values recog‐ nized, case‐insensitively, by preconv. big5, cp1047, euc-jp, euc-kr, gb2312, iso-8859-1, iso-8859-2, iso-8859-5, iso-8859-7, iso-8859-9, iso-8859-13, iso-8859-15, koi8-r, us-ascii, utf-8, utf-16, utf-16be, utf-16le In addition, the following list of other coding tags is recognized, each of which is mapped to an appropriate value from the list above. ascii, chinese-big5, chinese-euc, chinese-iso-8bit, cn-big5, cn-gb, cn-gb-2312, cp878, csascii, csisolatin1, cyrillic-iso-8bit, cyrillic-koi8, euc-china, euc-cn, euc-japan, euc-japan-1990, euc-korea, greek-iso-8bit, iso-10646/utf8, iso-10646/utf-8, iso-latin-1, iso-latin-2, iso-latin-5, iso-latin-7, iso-latin-9, japanese-euc, japanese-iso-8bit, jis8, koi8, korean-euc, korean-iso-8bit, latin-0, latin1, latin-1, latin-2, latin-5, latin-7, latin-9, mule-utf-8, mule-utf-16, mule-utf-16be, mule-utf-16-be, mule-utf-16be-with-signature, mule-utf-16le, mule-utf-16-le, mule-utf-16le-with-signature, utf8, utf-16-be, utf-16-be-with-signature, utf-16be-with-signature, utf-16-le, utf-16-le-with-signature, utf-16le-with-signature Trailing “-dos”, “-unix”, and “-mac” suffixes on coding tags (which in‐ dicate the end‐of‐line convention used in the file) are disregarded for the purpose of comparison with the above tags. iconv support While preconv recognizes all of the coding tags listed above, it is ca‐ pable on its own of interpreting only three encodings: Latin‐1, code page 1047, and UTF‐8. If iconv support is configured at compile time and available at run time, all others are passed to iconv library func‐ tions, which may recognize many additional encoding strings. The com‐ mand “preconv -v” discloses whether iconv support is configured. The use of iconv means that characters in the input that encode invalid code points for that encoding may be dropped from the output stream or mapped to the Unicode replacement character (U+FFFD). Compare the fol‐ lowing examples using the input “café” (note the “e” with an acute ac‐ cent), which due to its short length challenges inference of the encod‐ ing used. printf 'caf\351\n' | LC_ALL=en_US.UTF-8 preconv printf 'caf\351\n' | preconv -e us-ascii printf 'caf\351\n' | preconv -e latin-1 The fate of the accented “e” differs in each case. In the first, uchardet fails to detect an encoding (though the library on your system may behave differently) and preconv falls back to the locale settings, where octal 351 starts an incomplete UTF‐8 sequence and results in the Unicode replacement character. In the second, it is not a repre‐ sentable character in the declared input encoding of US‐ASCII and is discarded by iconv. In the last, it is correctly detected and mapped. Limitations preconv cannot perform any transformation on input that it cannot see. Examples include files that are interpolated by preprocessors that run subsequently, including soelim(1); files included by troff itself through “so” and similar requests; and string definitions passed to troff through its -d command‐line option. preconv assumes that its input uses the default escape character, a backslash \, and writes special character escape sequences accordingly. Options -h and --help display a usage message, while -v and --version show ver‐ sion information; all exit afterward. -d Emit debugging messages to the standard error stream. -D fallback‐encoding Report fallback‐encoding if all detection methods fail. -e encoding Skip detection and assume encoding; see groff’s -K option. -r Write files “raw”; do not add .lf requests. See also groff(1), iconv(3), locale(7) groff 1.23.0 29 August 2023 preconv(1) ─────────────────────────────────────────────────────────────────────────────── refer(1) General Commands Manual refer(1) Name refer - process bibliographic references for groff Synopsis refer [-bCenPRS] [-a n] [-B field.macro] [-c fields] [-f n] [-i fields] [-k field] [-l range‐expression] [-p database‐file] [-s fields] [-t n] [file ...] refer --help refer -v refer --version Description The GNU implementation of refer is part of the groff(1) document for‐ matting system. refer is a troff(1) preprocessor that prepares bibilo‐ graphic citations by looking up keywords specified in a roff(7) input document, obviating the need to type such annotations, and permitting the citation style in formatted output to be altered independently and systematically. It copies the contents of each file to the standard output stream, except that it interprets lines between .[ and .] as ci‐ tations to be translated into groff input, and lines between .R1 and .R2 as instructions regarding how citations are to be processed. Nor‐ mally, refer is not executed directly by the user, but invoked by spec‐ ifying the -R option to groff(1). If no file operands are given on the command line, or if file is “-”, the standard input stream is read. Each citation specifies a reference. The citation can specify a refer‐ ence that is contained in a bibliographic database by giving a set of keywords that only that reference contains. Alternatively it can spec‐ ify a reference by supplying a database record in the citation. A com‐ bination of these alternatives is also possible. For each citation, refer can produce a mark in the text. This mark consists of some label which can be separated from the text and from other labels in various ways. For each reference it also outputs groff(7) language commands that can be used by a macro package to pro‐ duce a formatted reference for each citation. The output of refer must therefore be processed using a suitable macro package, such as me, mm, mom, or ms. The commands to format a citation’s reference can be out‐ put immediately after the citation, or the references may be accumu‐ lated, and the commands output at some later point. If the references are accumulated, then multiple citations of the same reference will produce a single formatted reference. The interpretation of lines between .R1 and .R2 as prepreocessor com‐ mands is a feature of GNU refer. Documents making use of this feature can still be processed by AT&T refer just by adding the lines .de R1 .ig R2 .. to the beginning of the document. This will cause troff(1) to ignore everything between .R1 and .R2. The effect of some commands can also be achieved by options. These options are supported mainly for compat‐ ibility with AT&T refer. It is usually more convenient to use com‐ mands. refer generates .lf requests so that file names and line numbers in messages produced by commands that read refer output will be correct; it also interprets lines beginning with .lf so that file names and line numbers in the messages and .lf lines that it produces will be accurate even if the input has been preprocessed by a command such as soelim(1). Bibliographic databases The bibliographic database is a text file consisting of records sepa‐ rated by one or more blank lines. Within each record fields start with a % at the beginning of a line. Each field has a one character name that immediately follows the %. It is best to use only upper and lower case letters for the names of fields. The name of the field should be followed by exactly one space, and then by the contents of the field. Empty fields are ignored. The conventional meaning of each field is as follows: %A The name of an author. If the name contains a suffix such as “Jr.”, it should be separated from the last name by a comma. There can be multiple occurrences of the %A field. The order is significant. It is a good idea always to supply an %A field or a %Q field. %B For an article that is part of a book, the title of the book. %C The place (city) of publication. %D The date of publication. The year should be specified in full. If the month is specified, the name rather than the number of the month should be used, but only the first three letters are required. It is a good idea always to supply a %D field; if the date is unknown, a value such as in press or unknown can be used. %E For an article that is part of a book, the name of an editor of the book. Where the work has editors and no authors, the names of the editors should be given as %A fields and “, (ed.)” or “, (eds.)” should be appended to the last author. %G U.S. government ordering number. %I The publisher (issuer). %J For an article in a journal, the name of the journal. %K Keywords to be used for searching. %L Label. %N Journal issue number. %O Other information. This is usually printed at the end of the reference. %P Page number. A range of pages can be specified as m-n. %Q The name of the author, if the author is not a person. This will only be used if there are no %A fields. There can only be one %Q field. %R Technical report number. %S Series name. %T Title. For an article in a book or journal, this should be the title of the article. %V Volume number of the journal or book. %X Annotation. For all fields except %A and %E, if there is more than one occurrence of a particular field in a record, only the last such field will be used. If accent strings are used, they should follow the character to be ac‐ cented. This means that an ms document must call the .AM macro when it initializes. Accent strings should not be quoted: use one \ rather than two. Accent strings are an obsolescent feature of the me and ms macro packages; modern documents should use groff special character es‐ cape sequences instead; see groff_char(7). Citations Citations have a characteristic format. .[opening‐text flags keywords fields .]closing‐text The opening‐text, closing‐text, and flags components are optional. Only one of the keywords and fields components need be specified. The keywords component says to search the bibliographic databases for a reference that contains all the words in keywords. It is an error if more than one reference is found. The fields components specifies additional fields to replace or supple‐ ment those specified in the reference. When references are being accu‐ mulated and the keywords component is non‐empty, then additional fields should be specified only on the first occasion that a particular refer‐ ence is cited, and will apply to all citations of that reference. The opening‐text and closing‐text components specify strings to be used to bracket the label instead of those in the bracket-label command. If either of these components is non‐empty, the strings specified in the bracket-label command will not be used; this behavior can be altered using the [ and ] flags. Leading and trailing spaces are significant for these components. The flags component is a list of non‐alphanumeric characters each of which modifies the treatment of this particular citation. AT&T refer will treat these flags as part of the keywords and so will ignore them since they are non‐alphanumeric. The following flags are currently recognized. # Use the label specified by the short-label command, instead of that specified by the label command. If no short label has been specified, the normal label will be used. Typically the short label is used with author‐date labels and consists of only the date and possibly a disambiguating letter; the “#” is supposed to be suggestive of a numeric type of label. [ Precede opening‐text with the first string specified in the bracket-label command. ] Follow closing‐text with the second string specified in the bracket-label command. An advantage of using the [ and ] flags rather than including the brackets in opening‐text and closing‐text is that you can change the style of bracket used in the document just by changing the bracket-label command. Another is that sorting and merging of cita‐ tions will not necessarily be inhibited if the flags are used. If a label is to be inserted into the text, it will be attached to the line preceding the .[ line. If there is no such line, then an extra line will be inserted before the .[ line and a warning will be given. There is no special notation for making a citation to multiple refer‐ ences. Just use a sequence of citations, one for each reference. Don’t put anything between the citations. The labels for all the cita‐ tions will be attached to the line preceding the first citation. The labels may also be sorted or merged. See the description of the <> la‐ bel expression, and of the sort-adjacent-labels and abbreviate-label-ranges commands. A label will not be merged if its citation has a non‐empty opening‐text or closing‐text. However, the labels for a citation using the ] flag and without any closing‐text im‐ mediately followed by a citation using the [ flag and without any open‐ ing‐text may be sorted and merged even though the first citation’s opening‐text or the second citation’s closing‐text is non‐empty. (If you wish to prevent this, use the dummy character escape sequence \& as the first citation’s closing‐text.) Commands Commands are contained between lines starting with .R1 and .R2. Recog‐ nition of these lines can be prevented by the -R option. When a .R1 line is recognized any accumulated references are flushed out. Neither .R1 nor .R2 lines, nor anything between them, is output. Commands are separated by newlines or semicolons. A number sign (#) introduces a comment that extends to the end of the line, but does not conceal the newline. Each command is broken up into words. Words are separated by spaces or tabs. A word that begins with a (neutral) dou‐ ble quote (") extends to the next double quote that is not followed by another double quote. If there is no such double quote, the word ex‐ tends to the end of the line. Pairs of double quotes in a word begin‐ ning with a double quote collapse to one double quote. Neither a num‐ ber sign nor a semicolon is recognized inside double quotes. A line can be continued by ending it with a backslash “\”; this works every‐ where except after a number sign. Each command name that is marked with * has an associated negative com‐ mand no-name that undoes the effect of name. For example, the no-sort command specifies that references should not be sorted. The negative commands take no arguments. In the following description each argument must be a single word; field is used for a single upper or lower case letter naming a field; fields is used for a sequence of such letters; m and n are used for a non‐neg‐ ative numbers; string is used for an arbitrary string; file is used for the name of a file. abbreviate* fields string1 string2 string3 string4 Abbreviate the first names of fields. An initial letter will be separated from another initial letter by string1, from the last name by string2, and from anything else (such as “von” or “de”) by string3. These default to a period followed by a space. In a hyphenated first name, the initial of the first part of the name will be separated from the hyphen by string4; this defaults to a period. No attempt is made to handle any ambiguities that might result from abbreviation. Names are abbreviated before sorting and before label construction. abbreviate-label-ranges* string Three or more adjacent labels that refer to consecutive refer‐ ences will be abbreviated to a label consisting of the first la‐ bel, followed by string, followed by the last label. This is mainly useful with numeric labels. If string is omitted, it de‐ faults to “-”. accumulate* Accumulate references instead of writing out each reference as it is encountered. Accumulated references will be written out whenever a reference of the form .[ $LIST$ .] is encountered, after all input files have been processed, and whenever a .R1 line is recognized. annotate* field string field is an annotation; print it at the end of the reference as a paragraph preceded by the line .string If string is omitted, it will default to AP; if field is also omitted it will default to X. Only one field can be an annota‐ tion. articles string ... Each string is a definite or indefinite article, and should be ignored at the beginning of T fields when sorting. Initially, “a”, “an”, and “the” are recognized as articles. bibliography file ... Write out all the references contained in each bibliographic database file. This command should come last in an .R1/.R2 block. bracket-label string1 string2 string3 In the text, bracket each label with string1 and string2. An occurrence of string2 immediately followed by string1 will be turned into string3. The default behavior is as follows. bracket-label \*([. \*(.] ", " capitalize fields Convert fields to caps and small caps. compatible* Recognize .R1 and .R2 even when followed by a character other than space or newline. database file ... Search each bibliographic database file. For each file, if an index file.i created by indxbib(1) exists, then it will be searched instead; each index can cover multiple databases. date-as-label* string string is a label expression that specifies a string with which to replace the D field after constructing the label. See sub‐ section “Label expressions” below for a description of label ex‐ pressions. This command is useful if you do not want explicit labels in the reference list, but instead want to handle any necessary disambiguation by qualifying the date in some way. The label used in the text would typically be some combination of the author and date. In most cases you should also use the no-label-in-reference command. For example, date-as-label D.+yD.y%a*D.-y would attach a disambiguating letter to the year part of the D field in the reference. default-database* The default database should be searched. This is the default behavior, so the negative version of this command is more use‐ ful. refer determines whether the default database should be searched on the first occasion that it needs to do a search. Thus a no-default-database command must be given before then, in order to be effective. discard* fields When the reference is read, fields should be discarded; no string definitions for fields will be output. Initially, fields are XYZ. et-al* string m n Control use of et al. in the evaluation of @ expressions in la‐ bel expressions. If the number of authors needed to make the author sequence unambiguous is u and the total number of authors is t then the last t-u authors will be replaced by string pro‐ vided that t-u is not less than m and t is not less than n. The default behavior is as follows. et-al " et al" 2 3 Note the absence of a dot from the end of the abbreviation, which is arguably not correct. (Et al[.] is short for et alli, as etc. is short for et cetera.) include file Include file and interpret the contents as commands. join-authors string1 string2 string3 Join multiple authors together with strings. When there are ex‐ actly two authors, they will be joined with string1. When there are more than two authors, all but the last two will be joined with string2, and the last two authors will be joined with string3. If string3 is omitted, it will default to string1; if string2 is also omitted it will also default to string1. For example, join-authors " and " ", " ", and " will restore the default method for joining authors. label-in-reference* When outputting the reference, define the string [F to be the reference’s label. This is the default behavior, so the nega‐ tive version of this command is more useful. label-in-text* For each reference output a label in the text. The label will be separated from the surrounding text as described in the bracket-label command. This is the default behavior, so the negative version of this command is more useful. label string string is a label expression describing how to label each refer‐ ence. separate-label-second-parts string When merging two‐part labels, separate the second part of the second label from the first label with string. See the descrip‐ tion of the <> label expression. move-punctuation* In the text, move any punctuation at the end of line past the label. It is usually a good idea to give this command unless you are using superscripted numbers as labels. reverse* string Reverse the fields whose names are in string. Each field name can be followed by a number which says how many such fields should be reversed. If no number is given for a field, all such fields will be reversed. search-ignore* fields While searching for keys in databases for which no index exists, ignore the contents of fields. Initially, fields XYZ are ig‐ nored. search-truncate* n Only require the first n characters of keys to be given. In ef‐ fect when searching for a given key words in the database are truncated to the maximum of n and the length of the key. Ini‐ tially, n is 6. short-label* string string is a label expression that specifies an alternative (usu‐ ally shorter) style of label. This is used when the # flag is given in the citation. When using author‐date style labels, the identity of the author or authors is sometimes clear from the context, and so it may be desirable to omit the author or au‐ thors from the label. The short-label command will typically be used to specify a label containing just a date and possibly a disambiguating letter. sort* string Sort references according to string. References will automati‐ cally be accumulated. string should be a list of field names, each followed by a number, indicating how many fields with the name should be used for sorting. “+” can be used to indicate that all the fields with the name should be used. Also . can be used to indicate the references should be sorted using the (ten‐ tative) label. (Subsection “Label expressions” below describes the concept of a tentative label.) sort-adjacent-labels* Sort labels that are adjacent in the text according to their po‐ sition in the reference list. This command should usually be given if the abbreviate-label-ranges command has been given, or if the label expression contains a <> expression. This will have no effect unless references are being accumulated. Label expressions Label expressions can be evaluated both normally and tentatively. The result of normal evaluation is used for output. The result of tenta‐ tive evaluation, called the tentative label, is used to gather the in‐ formation that normal evaluation needs to disambiguate the label. La‐ bel expressions specified by the date-as-label and short-label commands are not evaluated tentatively. Normal and tentative evaluation are the same for all types of expression other than @, *, and % expressions. The description below applies to normal evaluation, except where other‐ wise specified. field field n The n‐th part of field. If n is omitted, it defaults to 1. 'string' The characters in string literally. @ All the authors joined as specified by the join-authors command. The whole of each author’s name will be used. However, if the references are sorted by author (that is, the sort specification starts with “A+”), then authors’ last names will be used in‐ stead, provided that this does not introduce ambiguity, and also an initial subsequence of the authors may be used instead of all the authors, again provided that this does not introduce ambigu‐ ity. The use of only the last name for the i‐th author of some reference is considered to be ambiguous if there is some other reference, such that the first i-1 authors of the references are the same, the i‐th authors are not the same, but the i‐th au‐ thors last names are the same. A proper initial subsequence of the sequence of authors for some reference is considered to be ambiguous if there is a reference with some other sequence of authors which also has that subsequence as a proper initial sub‐ sequence. When an initial subsequence of authors is used, the remaining authors are replaced by the string specified by the et-al command; this command may also specify additional require‐ ments that must be met before an initial subsequence can be used. @ tentatively evaluates to a canonical representation of the authors, such that authors that compare equally for sorting purpose will have the same representation. %n %a %A %i %I The serial number of the reference formatted according to the character following the %. The serial number of a reference is 1 plus the number of earlier references with same tentative label as this reference. These expressions tentatively evaluate to an empty string. expr* If there is another reference with the same tentative label as this reference, then expr, otherwise an empty string. It tenta‐ tively evaluates to an empty string. expr+n expr-n The first (+) or last (-) n upper or lower case letters or dig‐ its of expr. roff special characters (such as \('a) count as a single letter. Accent strings are retained but do not count to‐ wards the total. expr.l expr converted to lowercase. expr.u expr converted to uppercase. expr.c expr converted to caps and small caps. expr.r expr reversed so that the last name is first. expr.a expr with first names abbreviated. Fields specified in the abbreviate command are abbreviated before any labels are evalu‐ ated. Thus .a is useful only when you want a field to be abbre‐ viated in a label but not in a reference. expr.y The year part of expr. expr.+y The part of expr before the year, or the whole of expr if it does not contain a year. expr.-y The part of expr after the year, or an empty string if expr does not contain a year. expr.n The last name part of expr. expr1~expr2 expr1 except that if the last character of expr1 is - then it will be replaced by expr2. expr1 expr2 The concatenation of expr1 and expr2. expr1|expr2 If expr1 is non‐empty then expr1 otherwise expr2. expr1&expr2 If expr1 is non‐empty then expr2 otherwise an empty string. expr1?expr2:expr3 If expr1 is non‐empty then expr2 otherwise expr3. <expr> The label is in two parts, which are separated by expr. Two ad‐ jacent two‐part labels which have the same first part will be merged by appending the second part of the second label onto the first label separated by the string specified in the separate-label-second-parts command (initially, a comma followed by a space); the resulting label will also be a two‐part label with the same first part as before merging, and so additional labels can be merged into it. It is permissible for the first part to be empty; this may be desirable for expressions used in the short-label command. (expr) The same as expr. Used for grouping. The above expressions are listed in order of precedence (highest first); & and | have the same precedence. Macro interface Each reference starts with a call to the macro ]-. The string [F will be defined to be the label for this reference, unless the no-label-in-reference command has been given. There then follows a se‐ ries of string definitions, one for each field: string [X corresponds to field X. The register [P is set to 1 if the P field contains a range of pages. The [T, [A and [O registers are set to 1 according as the T, A and O fields end with any of .?! (an end‐of‐sentence charac‐ ter). The [E register will be set to 1 if the [E string contains more than one name. The reference is followed by a call to the ][ macro. The first argument to this macro gives a number representing the type of the reference. If a reference contains a J field, it will be clas‐ sified as type 1, otherwise if it contains a B field, it will be type 3, otherwise if it contains a G or R field it will be type 4, oth‐ erwise if it contains an I field it will be type 2, otherwise it will be type 0. The second argument is a symbolic name for the type: other, journal-article, book, article-in-book, or tech-report. Groups of ref‐ erences that have been accumulated or are produced by the bibliography command are preceded by a call to the ]< macro and followed by a call to the ]> macro. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -R Don’t recognize lines beginning with .R1/.R2. Other options are equivalent to refer commands. -a n reverse An -b no-label-in-text; no-label-in-reference -B See below. -c fields capitalize fields -C compatible -e accumulate -f n label %n -i fields search-ignore fields -k label L~%a -k field label field~%a -l label A.nD.y%a -l m label A.n+mD.y%a -l ,n label A.nD.y-n%a -l m,n label A.n+mD.y-n%a -n no-default-database -p db‐file database db‐file -P move-punctuation -s spec sort spec -S label "(A.n|Q) ', ' (D.y|D)"; bracket‐label " (" ) "; " -t n search-truncate n The B option has command equivalents with the addition that the file names specified on the command line are processed as if they were argu‐ ments to the bibliography command instead of in the normal way. -B annotate X AP; no-label-in-reference -B field.macro annotate field macro; no-label-in-reference Environment REFER If set, overrides the default database. Files /usr/dict/papers/Ind Default database. file.i Index files. /usr/local/share/groff/1.23.0/tmac/refer.tmac defines macros and strings facilitating integration with macro packages that wish to support refer. refer uses temporary files. See the groff(1) man page for details of where such files are created. Bugs In label expressions, <> expressions are ignored inside .char expres‐ sions. Examples We can illustrate the operation of refer with a sample bibliographic database containing one entry and a simple roff document to cite that entry. $ cat > my-db-file %A Daniel P.\& Friedman %A Matthias Felleisen %C Cambridge, Massachusetts %D 1996 %I The MIT Press %T The Little Schemer, Fourth Edition $ refer ‐p my-db-file Read the book .[ friedman .] on your summer vacation.  .lf 1 - Read the book\*([.1\*(.] .ds [F 1 .]- .ds [A Daniel P. Friedman and Matthias Felleisen .ds [C Cambridge, Massachusetts .ds [D 1996 .ds [I The MIT Press .ds [T The Little Schemer, Fourth Edition .nr [T 0 .nr [A 0 .][ 2 book .lf 5 - on your summer vacation. The foregoing shows us that refer (a) produces a label “1”; (b) brack‐ ets that label with interpolations of the “[.” and “.]” strings; (c) calls a macro “]-”; (d) defines strings and registers containing the label and bibliographic data for the reference; (e) calls a macro “][”; and (f) uses the lf request to restore the line numbers of the original input. As discussed in subsection “Macro interface” above, it is up to the document or a macro package to employ and format this information usefully. Let us see how we might turn groff_ms(7) to this task. $ REFER=my-db-file groff -R -ms .LP Read the book .[ friedman .] on your summer vacation. Commentary is available.\*{*\*} .FS \*{*\*} Space reserved for penetrating insight. .FE ms’s automatic footnote numbering mechanism is not aware of refer’s la‐ bel numbering, so we have manually specified a (superscripted) symbolic footnote for our non‐bibliographic aside. See also “Some Applications of Inverted Indexes on the Unix System”, by M. E. Lesk, 1978, AT&T Bell Laboratories Computing Science Technical Report No. 69. indxbib(1), lookbib(1), lkbib(1) groff 1.23.0 29 August 2023 refer(1) ─────────────────────────────────────────────────────────────────────────────── soelim(1) General Commands Manual soelim(1) Name soelim - recursively interpolate source requests in roff or other text files Synopsis soelim [-Crt] [-I dir] [input‐file ...] soelim --help soelim -v soelim --version Description GNU soelim is a preprocessor for the groff(7) document formatting sys‐ tem. soelim works as a filter to eliminate source requests in roff(7) input files; that is, it replaces lines of the form “.so included‐file” within each text input‐file with the contents of included‐file, recur‐ sively. By default, it writes lf requests as well to record the name and line number of each input‐file and included‐file, so that any diag‐ nostics produced by later processing can be accurately traced to the original input. Options allow this information to be suppressed (-r) or supplied in TeX comments instead (-t). In the absence of input‐file arguments, soelim reads the standard input stream. Output is written to the standard output stream. If the name of a macro‐file contains a backslash, use \\ or \e to embed it. To embed a space, write “\ ” (backslash followed by a space). Any other escape sequence in macro‐file, including “\[rs]”, prevents soelim from replacing the source request. The dot must be at the beginning of a line and must be followed by “so” without intervening spaces or tabs for soelim to handle it. This con‐ vention allows source requests to be “protected” from processing by soelim, for instance as part of macro definitions or “if” requests. There must also be at least one space between “so” and its macro‐file argument. The -C option overrides this requirement. The foregoing is the limit of soelim’s understanding of the roff lan‐ guage; it does not, for example, replace the input line .if 1 .so otherfile with the contents of otherfile. With its -r option, therefore, soelim can be used to process text files in general, to flatten a tree of in‐ put documents. soelim was designed to handle situations where the target of a roff source request requires a preprocessor such as eqn(1), pic(1), refer(1), or tbl(1). The usual processing sequence of groff(1) is as follows. input sourced file file ⎪ ⎪ ↓ ↓ preprocessor ⎯→ troff ⎯→ postprocessor ⎪ ↓ output file That is, files sourced with “so” are normally read only by the format‐ ter, troff. soelim is not required for troff to source files. If a file to be sourced should also be preprocessed, it must already be read before the input file passes through the preprocessor. soelim, normally invoked via groff’s -s option, handles this. input file ⎪ ↓ soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor ↑ ⎪ ⎪ ↓ sourced output file file Options --help displays a usage message, while -v and --version show version information; all exit afterward. -C Recognize an input line starting with .so even if a character other than a space or newline follows. -I dir Search the directory dir path for input‐ and included‐files. -I may be specified more than once; each dir is searched in the given order. To search the current working directory before others, add “-I .” at the desired place; it is otherwise searched last. -r Write files “raw”; do not add lf requests. -t Emit TeX comment lines starting with “%” indicating the current file and line number, rather than lf requests for the same pur‐ pose. If both -r and -t are given, the last one specified controls. See also groff(1) groff 1.23.0 29 August 2023 soelim(1) ─────────────────────────────────────────────────────────────────────────────── tbl(1) General Commands Manual tbl(1) Name tbl - prepare tables for groff documents Synopsis tbl [-C] [file ...] tbl --help tbl -v tbl --version Description The GNU implementation of tbl is part of the groff(1) document format‐ ting system. tbl is a troff(1) preprocessor that translates descrip‐ tions of tables embedded in roff(7) input files into the language un‐ derstood by troff. It copies the contents of each file to the standard output stream, except that lines between .TS and .TE are interpreted as table descriptions. While GNU tbl’s input syntax is highly compatible with AT&T tbl, the output GNU tbl produces cannot be processed by AT&T troff; GNU troff (or a troff implementing any GNU extensions employed) must be used. Normally, tbl is not executed directly by the user, but invoked by specifying the -t option to groff(1). If no file operands are given on the command line, or if file is “-”, tbl reads the stan‐ dard input stream. Overview tbl expects to find table descriptions between input lines that begin with .TS (table start) and .TE (table end). Each such table region en‐ closes one or more table descriptions. Within a table region, table descriptions beyond the first must each be preceded by an input line beginning with .T&. This mechanism does not start a new table region; all table descriptions are treated as part of their .TS/.TE enclosure, even if they are boxed or have column headings that repeat on subse‐ quent pages (see below). (Experienced roff users should observe that tbl is not a roff language interpreter: the default control character must be used, and no spaces or tabs are permitted between the control character and the macro name. These tbl input tokens remain as‐is in the output, where they become ordinary macro calls. Macro packages often define TS, T&, and TE macros to handle issues of table placement on the page. tbl produces groff code to define these macros as empty if their definitions do not exist when the formatter encounters a table region.) Each table region may begin with region options, and must contain one or more table definitions; each table definition contains a format specification followed by one or more input lines (rows) of entries. These entries comprise the table data. Region options The line immediately following the .TS token may specify region op‐ tions, keywords that influence the interpretation or rendering of the region as a whole or all table entries within it indiscriminately. They must be separated by commas, spaces, or tabs. Those that require a parenthesized argument permit spaces and tabs between the option’s name and the opening parenthesis. Options accumulate and cannot be un‐ set within a region once declared; if an option that takes a parameter is repeated, the last occurrence controls. If present, the set of re‐ gion options must be terminated with a semicolon (;). Any of the allbox, box, doublebox, frame, and doubleframe region op‐ tions makes a table “boxed” for the purpose of later discussion. allbox Enclose each table entry in a box; implies box. box Enclose the entire table region in a box. As a GNU extension, the alternative option name frame is also recognized. center Center the table region with respect to the current indentation and line length; the default is to left‐align it. As a GNU ex‐ tension, the alternative option name centre is also recognized. decimalpoint(c) Recognize character c as the decimal separator in columns using the N (numeric) classifier (see subsection “Column classifiers” below). This is a GNU extension. delim(xy) Recognize characters x and y as start and end delimiters, re‐ spectively, for eqn(1) input, and ignore input between them. x and y need not be distinct. doublebox Enclose the entire table region in a double box; implies box. As a GNU extension, the alternative option name doubleframe is also recognized. expand Spread the table horizontally to fill the available space (line length minus indentation) by increasing column separation. Or‐ dinarily, a table is made only as wide as necessary to accommo‐ date the widths of its entries and its column separations (whether specified or default). When expand applies to a table that exceeds the available horizontal space, column separation is reduced as far as necessary (even to zero). tbl produces groff input that issues a diagnostic if such compression occurs. The column modifier x (see below) overrides this option. linesize(n) Draw lines or rules (e.g., from box) with a thickness of n points. The default is the current type size when the region begins. This option is ignored on terminal devices. nokeep Don’t use roff diversions to manage page breaks. Normally, tbl employs them to avoid breaking a page within a table row. This usage can sometimes interact badly with macro packages’ own use of diversions—when footnotes, for example, are employed. This is a GNU extension. nospaces Ignore leading and trailing spaces in table entries. This is a GNU extension. nowarn Suppress diagnostic messages produced at document formatting time when the line or page lengths are inadequate to contain a table row. This is a GNU extension. tab(c) Use the character c instead of a tab to separate entries in a row of table data. Table format specification The table format specification is mandatory: it determines the number of columns in the table and directs how the entries within it are to be typeset. The format specification is a series of column descriptors. Each descriptor encodes a classifier followed by zero or more modi‐ fiers. Classifiers are letters (recognized case‐insensitively) or punctuation symbols; modifiers consist of or begin with letters or nu‐ merals. Spaces, tabs, newlines, and commas separate descriptors. New‐ lines and commas are special; they apply the descriptors following them to a subsequent row of the table. (This enables column headings to be centered or emboldened while the table entries for the data are not, for instance.) We term the resulting group of column descriptors a row definition. Within a row definition, separation between column de‐ scriptors (by spaces or tabs) is often optional; only some modifiers, described below, make separation necessary. Each column descriptor begins with a mandatory classifier, a character that selects from one of several arrangements. Some determine the po‐ sitioning of table entries within a rectangular cell: centered, left‐ aligned, numeric (aligned to a configurable decimal separator), and so on. Others perform special operations like drawing lines or spanning entries from adjacent cells in the table. Except for “|”, any classi‐ fier can be followed by one or more modifiers; some of these accept an argument, which in GNU tbl can be parenthesized. Modifiers select fonts, set the type size, and perform other tasks described below. The format specification can occupy multiple input lines, but must con‐ clude with a dot “.” followed by a newline. Each row definition is ap‐ plied in turn to one row of the table. The last row definition is ap‐ plied to rows of table data in excess of the row definitions. For clarity in this document’s examples, we shall write classifiers in uppercase and modifiers in lowercase. Thus, “CbCb,LR.” defines two rows of two columns. The first row’s entries are centered and bold‐ faced; the second and any further rows’ first and second columns are left‐ and right‐aligned, respectively. The row definition with the most column descriptors determines the num‐ ber of columns in the table; any row definition with fewer is implic‐ itly extended on the right‐hand side with L classifiers as many times as necessary to make the table rectangular. Column classifiers The L, R, and C classifiers are the easiest to understand and use. A, a Center longest entry in this column, left‐align remaining en‐ tries in the column with respect to the centered entry, then in‐ dent all entries by one en. Such “alphabetic” entries (hence the name of the classifier) can be used in the same column as L‐ classified entries, as in “LL,AR.”. The A entries are often termed “sub‐columns” due to their indentation. C, c Center entry within the column. L, l Left‐align entry within the column. N, n Numerically align entry in the column. tbl aligns columns of numbers vertically at the units place. If multiple decimal sep‐ arators are adjacent to a digit, it uses the rightmost one for vertical alignment. If there is no decimal separator, the rightmost digit is used for vertical alignment; otherwise, tbl centers the entry within the column. The roff dummy character \& in an entry marks the glyph preceding it (if any) as the units place; if multiple instances occur in the data, the left‐ most is used for alignment. If N‐classified entries share a column with L or R entries, tbl centers the widest N entry with respect to the widest L or R en‐ try, preserving the alignment of N entries with respect to each other. The appearance of eqn equations within N‐classified columns can be troublesome due to the foregoing textual scan for a decimal separator. Use the delim region option to make tbl ignore the data within eqn delimiters for that purpose. R, r Right‐align entry within the column. S, s Span previous entry on the left into this column. ^ Span entry in the same column from the previous row into this row. _, - Replace table entry with a horizontal rule. An empty table en‐ try is expected to correspond to this classifier; if data are found there, tbl issues a diagnostic message. = Replace table entry with a double horizontal rule. An empty ta‐ ble entry is expected to correspond to this classifier; if data are found there, tbl issues a diagnostic message. | Place a vertical rule (line) on the corresponding row of the ta‐ ble (if two of these are adjacent, a double vertical rule). This classifier does not contribute to the column count and no table entries correspond to it. A | to the left of the first column descriptor or to the right of the last one produces a vertical rule at the edge of the table; these are redundant (and ignored) in boxed tables. To change the table format within a tbl region, use the .T& token at the start of a line. It is followed by a format specification and ta‐ ble data, but not region options. The quantity of columns in a new ta‐ ble format thus introduced cannot increase relative to the previous ta‐ ble format; in that case, you must end the table region and start an‐ other. If that will not serve because the region uses box options or the columns align in an undesirable manner, you must design the initial table format specification to include the maximum quantity of columns required, and use the S horizontal spanning classifier where necessary to achieve the desired columnar alignment. Attempting to horizontally span in the first column or vertically span on the first row is an error. Non‐rectangular span areas are also not supported. Column modifiers Any number of modifiers can follow a column classifier. Arguments to modifiers, where accepted, are case‐sensitive. If the same modifier is applied to a column specifier more than once, or if conflicting modi‐ fiers are applied, only the last occurrence has effect. The modifier x is mutually exclusive with e and w, but e is not mutually exclusive with w; if these are used in combination, x unsets both e and w, while either e or w overrides x. b, B Typeset entry in boldface, abbreviating f(B). d, D Align a vertically spanned table entry to the bottom (“down”), instead of the center, of its range. This is a GNU extension. e, E Equalize the widths of columns with this modifier. The column with the largest width controls. This modifier sets the default line length used in a text block. f, F Select the typeface for the table entry. This modifier must be followed by a font or style name (one or two characters not starting with a digit), font mounting position (a single digit), or a name or mounting position of any length in parentheses. The last form is a GNU extension. (The parameter corresponds to that accepted by the troff ft request.) A one‐character argu‐ ment not in parentheses must be separated by one or more spaces or tabs from what follows. i, I Typeset entry in an oblique or italic face, abbreviating f(I). m, M Call a groff macro before typesetting a text block (see subsec‐ tion “Text blocks” below). This is a GNU extension. This modi‐ fier must be followed by a macro name of one or two characters or a name of any length in parentheses. A one‐character macro name not in parentheses must be separated by one or more spaces or tabs from what follows. The named macro must be defined be‐ fore the table region containing this column modifier is encoun‐ tered. The macro should contain only simple groff requests to change text formatting, like adjustment or hyphenation. The macro is called after the column modifiers b, f, i, p, and v take effect; it can thus override other column modifiers. p, P Set the type size for the table entry. This modifier must be followed by an integer n with an optional leading sign. If un‐ signed, the type size is set to n scaled points. Otherwise, the type size is incremented or decremented per the sign by n scaled points. The use of a signed multi‐digit number is a GNU exten‐ sion. (The parameter corresponds to that accepted by the troff ps request.) If a type size modifier is followed by a column separation modifier (see below), they must be separated by at least one space or tab. t, T Align a vertically spanned table entry to the top, instead of the center, of its range. u, U Move the column up one half‐line, “staggering” the rows. This is a GNU extension. v, V Set the vertical spacing to be used in a text block. This modi‐ fier must be followed by an integer n with an optional leading sign. If unsigned, the vertical spacing is set to n points. Otherwise, the vertical spacing is incremented or decremented per the sign by n points. The use of a signed multi‐digit num‐ ber is a GNU extension. (This parameter corresponds to that ac‐ cepted by the troff vs request.) If a vertical spacing modifier is followed by a column separation modifier (see below), they must be separated by at least one space or tab. w, W Set the column’s minimum width. This modifier must be followed by a number, which is either a unitless integer, or a roff hori‐ zontal measurement in parentheses. Parentheses are required if the width is to be followed immediately by an explicit column separation (alternatively, follow the width with one or more spaces or tabs). If no unit is specified, ens are assumed. This modifier sets the default line length used in a text block. x, X Expand the column. After computing the column widths, distrib‐ ute any remaining line length evenly over all columns bearing this modifier. Applying the x modifier to more than one column is a GNU extension. This modifier sets the default line length used in a text block. z, Z Ignore the table entries corresponding to this column for width calculation purposes; that is, compute the column’s width using only the information in its descriptor. n A numeric suffix on a column descriptor sets the separation dis‐ tance (in ens) from the succeeding column; the default separa‐ tion is 3n. This separation is proportionally multiplied if the expand region option is in effect; in the case of tables wider than the output line length, this separation might be zero. A negative separation cannot be specified. A separation amount after the last column in a row is nonsensical and provokes a di‐ agnostic from tbl. Table data The table data come after the format specification. Each input line corresponds to a table row, except that a backslash at the end of a line of table data continues an entry on the next input line. (Text blocks, discussed below, also spread table entries across multiple in‐ put lines.) Table entries within a row are separated in the input by a tab character by default; see the tab region option above. Excess en‐ tries in a row of table data (those that have no corresponding column descriptor, not even an implicit one arising from rectangularization of the table) are discarded with a diagnostic message. roff control lines are accepted between rows of table data and within text blocks. If you wish to visibly mark an empty table entry in the document source, popu‐ late it with the \& roff dummy character. The table data are inter‐ rupted by a line consisting of the .T& input token, and conclude with the line .TE. Ordinarily, a table entry is typeset rigidly. It is not filled, bro‐ ken, hyphenated, adjusted, or populated with additional inter‐sentence space. tbl instructs the formatter to measure each table entry as it occurs in the input, updating the width required by its corresponding column. If the z modifier applies to the column, this measurement is ignored; if w applies and its argument is larger than this width, that argument is used instead. In contrast to conventional roff input (within a paragraph, say), changes to text formatting, such as font se‐ lection or vertical spacing, do not persist between entries. Several forms of table entry are interpreted specially. • If a table row contains only an underscore or equals sign (_ or =), a single or double horizontal rule (line), respectively, is drawn across the table at that point. • A table entry containing only _ or = on an otherwise populated row is replaced by a single or double horizontal rule, respectively, joining its neighbors. • Prefixing a lone underscore or equals sign with a backslash also has meaning. If a table entry consists only of \_ or \= on an otherwise populated row, it is replaced by a single or double horizontal rule, respectively, that does not (quite) join its neighbors. • A table entry consisting of \Rx, where x is any roff ordinary or spe‐ cial character, is replaced by enough repetitions of the glyph corre‐ sponding to x to fill the column, albeit without joining its neigh‐ bors. • On any row but the first, a table entry of \^ causes the entry above it to span down into the current one. On occasion, these special tokens may be required as literal table data. To use either _ or = literally and alone in an entry, prefix or suffix it with the roff dummy character \&. To express \_, \=, or \R, use a roff escape sequence to interpolate the backslash (\e or \[rs]). A reliable way to emplace the \^ glyph sequence within a table entry is to use a pair of groff special character escape sequences (\[rs]\[ha]). Rows of table entries can be interleaved with groff control lines; these do not count as table data. On such lines the default control character (.) must be used (and not changed); the no‐break control character is not recognized. To start the first table entry in a row with a dot, precede it with the roff dummy character \&. Text blocks An ordinary table entry’s contents can make a column, and therefore the table, excessively wide; the table then exceeds the line length of the page, and becomes ugly or is exposed to truncation by the output de‐ vice. When a table entry requires more conventional typesetting, breaking across more than one output line (and thereby increasing the height of its row), it can be placed within a text block. tbl interprets a table entry beginning with “T{” at the end of an input line not as table data, but as a token starting a text block. Simi‐ larly, “T}” at the start of an input line ends a text block; it must also end the table entry. Text block tokens can share an input line with other table data (preceding T{ and following T}). Input lines be‐ tween these tokens are formatted in a diversion by troff. Text blocks cannot be nested. Multiple text blocks can occur in a table row. Text blocks are formatted as was the text prior to the table, modified by applicable column descriptors. Specifically, the classifiers A, C, L, N, R, and S determine a text block’s alignment within its cell, but not its adjustment. Add na or ad requests to the beginning of a text block to alter its adjustment distinctly from other text in the docu‐ ment. As with other table entries, when a text block ends, any alter‐ ations to formatting parameters are discarded. They do not affect sub‐ sequent table entries, not even other text blocks. If w or x modifiers are not specified for all columns of a text block’s span, the default length of the text block (more precisely, the line length used to process the text block diversion) is computed as L×C/(N+1), where L is the current line length, C the number of columns spanned by the text block, and N the number of columns in the table. If necessary, you can also control a text block’s width by including an ll (line length) request in it prior to any text to be formatted. Be‐ cause a diversion is used to format the text block, its height and width are subsequently available in the registers dn and dl, respec‐ tively. roff interface The register TW stores the width of the table region in basic units; it can’t be used within the region itself, but is defined before the .TE token is output so that a groff macro named TE can make use of it. T. is a Boolean‐valued register indicating whether the bottom of the table is being processed. The #T register marks the top of the table. Avoid using these names for any other purpose. tbl also defines a macro T# to produce the bottom and side lines of a boxed table. While tbl itself arranges for the output to include a call of this macro at the end of such a table, it can also be used by macro packages to create boxes for multi‐page tables by calling it from a page footer macro that is itself called by a trap planted near the bottom of the page. See section “Limitations” below for more on multi‐ page tables. GNU tbl internally employs register, string, macro, and diversion names beginning with the numeral 3. A document to be preprocessed with GNU tbl should not use any such identifiers. Interaction with eqn tbl should always be called before eqn(1). (groff(1) automatically arranges preprocessors in the correct order.) Don’t call the EQ and EN macros within tables; instead, set up delimiters in your eqn input and use the delim region option so that tbl will recognize them. GNU tbl enhancements In addition to extensions noted above, GNU tbl removes constraints en‐ dured by users of AT&T tbl. • Region options can be specified in any lettercase. • There is no limit on the number of columns in a table, regardless of their classification, nor any limit on the number of text blocks. • All table rows are considered when deciding column widths, not just those occurring in the first 200 input lines of a region. Similarly, table continuation (.T&) tokens are recognized outside a region’s first 200 input lines. • Numeric and alphabetic entries may appear in the same column. • Numeric and alphabetic entries may span horizontally. Using GNU tbl within macros You can embed a table region inside a macro definition. However, since tbl writes its own macro definitions at the beginning of each table re‐ gion, it is necessary to call end macros instead of ending macro defin‐ itions with “..”. Additionally, the escape character must be disabled. Not all tbl features can be exercised from such macros because tbl is a roff preprocessor: it sees the input earlier than troff does. For ex‐ ample, vertically aligning decimal separators fails if the numbers con‐ taining them occur as macro or string parameters; the alignment is per‐ formed by tbl itself, which sees only \$1, \$2, and so on, and there‐ fore can’t recognize a decimal separator that only appears later when troff interpolates a macro or string definition. Using tbl macros within conditional input (that is, contingent upon an if, ie, el, or while request) can result in misleading line numbers in subsequent diagnostics. tbl unconditionally injects its output into the source document, but the conditional branch containing it may not be taken, and if it is not, the lf requests that tbl injects to restore the source line number cannot take effect. Consider copying the input line counter register c. and restoring its value at a convenient loca‐ tion after applicable arithmetic. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -C Enable AT&T compatibility mode: recognize .TS and .TE even when followed by a character other than space or newline. Further‐ more, interpret the uninterpreted leader escape sequence \a. Limitations Multi‐page tables, if boxed and/or if you want their column headings repeated after page breaks, require support at the time the document is formatted. A convention for such support has arisen in macro packages such as ms, mm, and me. To use it, follow the .TS token with a space and then “H”; this will be interpreted by the formatter as a TS macro call with an H argument. Then, within the table data, call the TH macro; this informs the macro package where the headings end. If your table has no such heading rows, or you do not desire their repetition, call TH immediately after the table format specification. If a multi‐ page table is boxed or has repeating column headings, do not enclose it with keep/release macros, or divert it in any other way. Further, the bp request will not cause a page break in a “TS H” table. Define a macro to wrap bp: invoke it normally if there is no current diversion. Otherwise, pass the macro call to the enclosing diversion using the transparent line escape sequence \!; this will “bubble up” the page break to the output device. See section “Examples” below for a demon‐ stration. Double horizontal rules are not supported by grotty(1); single rules are used instead. grotty also ignores half‐line motions, so the u col‐ umn modifier has no effect. On terminal devices (“nroff mode”), hori‐ zontal rules and box borders occupy a full vee of space; this amount is doubled for doublebox tables. Tables using these features thus require more vertical space in nroff mode than in troff mode: write ne requests accordingly. Vertical rules between columns are drawn in the space be‐ tween columns in nroff mode; using double vertical rules and/or reduc‐ ing the column separation below the default can make them ugly or over‐ strike them with table data. A text block within a table must be able to fit on one page. Using \a to put leaders in table entries does not work in GNU tbl, ex‐ cept in compatibility mode. This is correct behavior: \a is an unin‐ terpreted leader. You can still use the roff leader character (Con‐ trol+A) or define a string to use \a as it was designed: to be inter‐ preted only in copy mode. .ds a \a .TS box center tab(;); Lw(2i)0 L. Population\*a;6,327,119 .TE ┌───────────────────────────────┐ │ Population..........6,327,119 │ └───────────────────────────────┘ A leading and/or trailing | in a format specification, such as “|LCR|.”, produces an en space between the vertical rules and the con‐ tent of the adjacent columns. If no such space is desired (so that the rule abuts the content), you can introduce “dummy” columns with zero separation and empty corresponding table entries before and/or after. .TS center tab(#); R0|L C R0|L. _ #levulose#glucose#dextrose# _ .TE These dummy columns have zero width and are therefore invisible; unfor‐ tunately they usually don’t work as intended on terminal devices. Examples It can be easier to acquire the language of tbl through examples than formal description, especially at first. .TS box center tab(#); Cb Cb L L. Ability#Application Strength#crushes a tomato Dexterity#dodges a thrown tomato Constitution#eats a month‐old tomato without becoming ill Intelligence#knows that a tomato is a fruit Wisdom#chooses \f[I]not\f[] to put tomato in a fruit salad Charisma#sells obligate carnivores tomato‐based fruit salads .TE ┌────────────────────────────────────────────────────────────────────┐ │ Ability Application │ │ Strength crushes a tomato │ │ Dexterity dodges a thrown tomato │ │ Constitution eats a month‐old tomato without becoming ill │ │ Intelligence knows that a tomato is a fruit │ │ Wisdom chooses not to put tomato in a fruit salad │ │ Charisma sells obligate carnivores tomato‐based fruit salads │ └────────────────────────────────────────────────────────────────────┘ The A and N column classifiers can be easier to grasp in visual render‐ ing than in description. .TS center tab(;); CbS,LN,AN. Daily energy intake (in MJ) Macronutrients .\" assume 3 significant figures of precision Carbohydrates;4.5 Fats;2.25 Protein;3 .T& LN,AN. Mineral Pu-239;14.6 _ .T& LN. Total;\[ti]24.4 .TE Daily energy intake (in MJ) Macronutrients Carbohydrates 4.5 Fats 2.25 Protein 3 Mineral Pu‐239 14.6 ──────────────────────────── Total ~24.4 Next, we’ll lightly adapt a compact presentation of spanning, vertical alignment, and zero‐width column modifiers from the mandoc reference for its tbl interpreter. It rewards close study. .TS box center tab(:); Lz S | Rt Ld| Cb| ^ ^ | Rz S. left:r l:center: :right .TE ┌────────────┬───┐ │ le│ft │ r │ │ │ center │ │ │ l │ right │ └───┴────────────┘ Row staggering is not visually achievable on terminal devices, but a table using it can remain comprehensible nonetheless. .TS center tab(|); Cf(BI) Cf(BI) Cf(B), C C Cu. n|n\f[B]\[tmu]\f[]n|difference 1|1 2|4|3 3|9|5 4|16|7 5|25|9 6|36|11 .TE n n×n difference 1 1 2 4 3 3 9 5 4 16 7 5 25 9 6 36 11 Some tbl features cannot be illustrated in the limited environment of a portable man page. We can define a macro outside of a tbl region that we can call from within it to cause a page break inside a multi‐page boxed table. You can choose a different name; be sure to change both occurrences of “BP”. .de BP . ie '\\n(.z'' .bp \\$1 . el \!.BP \\$1 .. See also “Tbl—A Program to Format Tables”, by M. E. Lesk, 1976 (revised 16 Janu‐ ary 1979), AT&T Bell Laboratories Computing Science Technical Report No. 49. The spanning example above was taken from mandoc’s man page for its tbl implementation ⟨https://man.openbsd.org/tbl.7⟩. groff(1), troff(1) groff 1.23.0 29 August 2023 tbl(1) ─────────────────────────────────────────────────────────────────────────────── tfmtodit(1) General Commands Manual tfmtodit(1) Name tfmtodit - adapt TeX Font Metrics files for use with groff and grodvi Synopsis tfmtodit [-s] [-g gf‐file] [-k skew‐char] tfm‐file map‐file font‐ description tfmtodit --help tfmtodit -v tfmtodit --version Description tfmtodit creates a font description file for use with groff(1)’s dvi output device. tfm‐file is the name of the TeX font metric file for the font. map‐file assigns groff ordinary or special character identi‐ fiers to glyph indices in the font; it should consist of a sequence of lines of the form i c1 ... cn where i is a position of the glyph in the font in decimal, and c1 through cn are glyph identifiers in the form used by groff font de‐ scriptions. If a glyph has no groff names but exists in tfm‐file, it is put in the groff font description file as an unnamed glyph. Output is written in groff_font(5) format to font‐description, a file named for the intended groff font name. If the font is “special”, meaning that groff should search it whenever a glyph is not found in the current font, use the -s option and name font‐description in the fonts directive in the output device’s DESC file. To do a good job of math typesetting, groff requires font metric infor‐ mation not present in tfm‐file. This is because TeX has separate math italic fonts, whereas groff uses normal italic fonts for math. The ad‐ ditional information required by groff is given by the two arguments to the math_fit macro in the Metafont programs for the Computer Modern fonts. In a text font (a font for which math_fit is false), Metafont normally ignores these two arguments. Metafont can be made to put this information into the GF (“generic font”) files it produces by loading the following definition after cmbase when creating cm.base. def ignore_math_fit(expr left_adjustment,right_adjustment) = special "adjustment"; numspecial left_adjustment*16/designsize; numspecial right_adjustment*16/designsize; enddef; For the EC font family, load the following definition after exbase; consider patching exbase.mf locally. def ignore_math_fit(expr left_adjustment,right_adjustment) = ori_special "adjustment"; ori_numspecial left_adjustment*16/designsize; ori_numspecial right_adjustment*16/designsize; enddef; The only difference from the previous example is the “ori_” prefix to “special” and “numspecial”. The GF file created using this modified cm.base or exbase.mf should be specified with the -g option, which should not be given for a font for which math_fit is true. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -g gf‐file Use the gf‐file produced by Metafont containing “special” and “numspecial” commands to obtain additional font metric informa‐ tion. -k skew‐char The skew character of this font is at position skew‐char. skew‐ char should be an integer; it may be given in decimal, with a leading 0 in octal, or with a leading 0x in hexadecimal. Any kerns whose second component is skew‐char are ignored. -s Add the special directive to the font description file. Files /usr/local/share/groff/1.23.0/font/devdvi/DESC describes the dvi output device. /usr/local/share/groff/1.23.0/font/devdvi/F describes the font known as F on device dvi. /usr/local/share/groff/1.23.0/font/devdvi/generate/ec.map /usr/local/share/groff/1.23.0/font/devdvi/generate/msam.map /usr/local/share/groff/1.23.0/font/devdvi/generate/msbm.map /usr/local/share/groff/1.23.0/font/devdvi/generate/tc.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texb.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texex.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texi.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texitt.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texmi.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texr.map /usr/local/share/groff/1.23.0/font/devdvi/generate/texsy.map /usr/local/share/groff/1.23.0/font/devdvi/generate/textex.map /usr/local/share/groff/1.23.0/font/devdvi/generate/textt.map map glyph indices in TeX fonts to groff ordinary and special character identifiers. ec.map is used for TREC, TIEC, TBEC, TBIEC, HREC, HIEC, HBEC, HBIEC, CWEC, and CWIEC; msam.map for SA; msbm.map for SB; tc.map for TRTC, TITC, TBTC, TBITC, HRTC, HITC, HBTC, HBITC, CWTC, and CWITC; texb.map for TB, HR, HI, HB, and HBI; texex.map for EX; texi.map for TI and TBI; texitt.map for CWI; texmi.map for MI; texr.map for TR; texsy.map for S; textex.map for SC; and textt.map for CW. See also groff(1), grodvi(1), groff_font(5) groff 1.23.0 29 August 2023 tfmtodit(1) ─────────────────────────────────────────────────────────────────────────────── troff(1) General Commands Manual troff(1) Name troff - GNU roff typesetter and document formatter Synopsis troff [-abcCEiRUz] [-d ctext] [-d string=text] [-f font‐family] [-F font‐directory] [-I inclusion‐directory] [-m macro‐package] [-M macro‐directory] [-n page‐number] [-o page‐list] [-r cnumeric‐expression] [-r register=numeric‐expression] [-T output‐device] [-w warning‐category] [-W warning‐category] [file ...] troff --help troff -v troff --version Description GNU troff transforms groff(7) language input into the device‐indepen‐ dent output format described in groff_out(5); troff is thus the heart of the GNU roff document formatting system. If no file operands are given on the command line, or if file is “-”, the standard input stream is read. GNU troff is functionally compatible with the AT&T troff typesetter and features numerous extensions. Many people prefer to use the groff(1) command, a front end which also runs preprocessors and output drivers in the appropriate order and with appropriate options. Options -h and --help display a usage message, while -v and --version show ver‐ sion information; all exit afterward. -a Generate a plain text approximation of the typeset output. The read‐only register .A is set to 1. This option produces a sort of abstract preview of the formatted output. • Page breaks are marked by a phrase in angle brackets; for ex‐ ample, “”. • Lines are broken where they would be in the formatted output. • A horizontal motion of any size is represented as one space. Adjacent horizontal motions are not combined. Inter‐sentence space nodes (those arising from the second argument to the .ss request) are not represented. • Vertical motions are not represented. • Special characters are rendered in angle brackets; for exam‐ ple, the default soft hyphen character appears as “”. The above description should not be considered a specification; the details of -a output are subject to change. -b Write a backtrace reporting the state of troff’s input parser to the standard error stream with each diagnostic message. The line numbers given in the backtrace might not always be correct, because troff’s idea of line numbers can be confused by requests that append to macros. -c Start with color output disabled. -C Enable AT&T troff compatibility mode; implies -c. See groff_diff(7). -d ctext -d string=text Define roff string c or string as text. c must be one charac‐ ter; string can be of arbitrary length. Such string assignments happen before any macro file is loaded, including the startup file. Due to getopt_long(3) limitations, c cannot be, and string cannot contain, an equals sign, even though that is a valid character in a roff identifier. -E Inhibit troff error messages; implies -Ww. This option does not suppress messages sent to the standard error stream by documents or macro packages using tm or related requests. -f fam Use fam as the default font family. -F dir Search in directory dir for the selected output device’s direc‐ tory of device and font description files. See the description of GROFF_FONT_PATH in section “Environment” below for the de‐ fault search locations and ordering. -i Read the standard input stream after all named input files have been processed. -I dir Search the directory dir for files (those named on the command line; in psbb, so, and soquiet requests; and in “\X'ps: im‐ port'”, “\X'ps: file'”, and “\X'pdf: pdfpic'” device control es‐ cape sequences). -I may be specified more than once; each dir is searched in the given order. To search the current working directory before others, add “-I .” at the desired place; it is otherwise searched last. -I works similarly to, and is named for, the “include” option of Unix C compilers. -m name Process the file name.tmac prior to any input files. If not found, tmac.name is attempted. name (in both arrangements) is presumed to be a macro file; see the description of GROFF_TMAC_PATH in section “Environment” below for the default search locations and ordering. -M dir Search directory dir for macro files. See the description of GROFF_TMAC_PATH in section “Environment” below for the default search locations and ordering. -n num Begin numbering pages at num. The default is 1. -o list Output only pages in list, which is a comma‐separated list of inclusive page ranges; n means page n, m-n means every page be‐ tween m and n, -n means every page up to n, and n- means every page from n on. troff stops processing and exits after format‐ ting the last page enumerated in list. -r cnumeric‐expression -r register=numeric‐expression Define roff register c or register as numeric‐expression. c must be a one‐character name; register can be of arbitrary length. Such register assignments happen before any macro file is loaded, including the startup file. Due to getopt_long(3) limitations, c cannot be, and register cannot contain, an equals sign, even though that is a valid character in a roff identi‐ fier. -R Don’t load troffrc and troffrc-end. -T dev Prepare output for device dev. The default is ps; see groff(1). -U Operate in unsafe mode, enabling the open, opena, pi, pso, and sy requests, which are disabled by default because they allow an untrusted input document to write to arbitrary file names and run arbitrary commands. This option also adds the current di‐ rectory to the macro package search path; see the -m and -M op‐ tions above. -w name -W name Enable (-w) or inhibit (-W) warnings in category name. See sec‐ tion “Warnings” below. -z Suppress formatted output. Warnings Warning diagnostics emitted by troff are divided into named, numbered categories. The name associated with each warning category is used by the -w and -W options. Each category is also assigned a power of two; the sum of enabled category codes is used by the warn request and the .warn register. Warnings of each category are produced under the fol‐ lowing circumstances. ┌───────────────────────┬─────────────────────────────┐ │ Bit Code Category │ Bit Code Category │ ├───────────────────────┼─────────────────────────────┤ │ 0 1 char │ 10 1024 reg │ │ 1 2 number │ 11 2048 tab │ │ 2 4 break │ 12 4096 right-brace │ │ 3 8 delim │ 13 8192 missing │ │ 4 16 el │ 14 16384 input │ │ 5 32 scale │ 15 32768 escape │ │ 6 64 range │ 16 65536 space │ │ 7 128 syntax │ 17 131072 font │ │ 8 256 di │ 18 262144 ig │ │ 9 512 mac │ 19 524288 color │ │ │ 20 1048576 file │ └───────────────────────┴─────────────────────────────┘ break 4 A filled output line could not be broken such that its length was less than the output line length \n[.l]. This category is enabled by default. char 1 No mounted font defines a glyph for the requested character. This category is enabled by default. color 524288 An undefined color name was selected, an attempt was made to define a color using an unrecognized color space, an invalid component in a color defin‐ ition was encountered, or an attempt was made to redefine a default color. delim 8 The closing delimiter in an escape sequence was missing or mismatched. di 256 A di, da, box, or boxa request was invoked without an argument when there was no current diversion. el 16 The el request was encountered with no prior corre‐ sponding ie request. escape 32768 An unsupported escape sequence was encountered. file 1048576 An attempt was made to load a file that does not exist. This category is enabled by default. font 131072 A non‐existent font was selected, or the selection was ignored because a font selection escape se‐ quence was used after the output line continuation escape sequence on an input line. This category is enabled by default. ig 262144 An invalid escape sequence occurred in input ig‐ nored using the ig request. This warning category diagnoses a condition that is an error when it oc‐ curs in non‐ignored input. input 16384 An invalid character occurred on the input stream. mac 512 An undefined string, macro, or diversion was used. When such an object is dereferenced, an empty one of that name is automatically created. So, unless it is later deleted, at most one warning is given for each. This warning is also emitted upon an attempt to move an unplanted trap macro. In such cases, the unplanted macro is not dereferenced, so it is not created if it does not exist. missing 8192 A request was invoked with a mandatory argument ab‐ sent. number 2 An invalid numeric expression was encountered. This category is enabled by default. range 64 A numeric expression was out of range for its con‐ text. reg 1024 An undefined register was used. When an undefined register is dereferenced, it is automatically de‐ fined with a value of 0. So, unless it is later deleted, at most one warning is given for each. right-brace 4096 A right brace escape sequence \} was encountered where a number was expected. scale 32 A scaling unit inappropriate to its context was used in a numeric expression. space 65536 A space was missing between a request or macro and its argument. This warning is produced when an un‐ defined name longer than two characters is encoun‐ tered and the first two characters of the name con‐ stitute a defined name. No request is invoked, no macro called, and an empty macro is not defined. This category is enabled by default. It never oc‐ curs in compatibility mode. syntax 128 A self‐contradictory hyphenation mode was re‐ quested; an empty or incomplete numeric expression was encountered; an operand to a numeric operator was missing; an attempt was made to define a recur‐ sive, empty, or nonsensical character class; or a groff extension conditional expression operator was used while in compatibility mode. tab 2048 A tab character was encountered where a number was expected, or appeared in an unquoted macro argu‐ ment. Two warning names group other warning categories for convenience. all All warning categories except di, mac, and reg. This shorthand is intended to produce all warnings that are useful with macro packages and documents written for AT&T troff and its descen‐ dants, which have less fastidious diagnostics than GNU troff. w All warning categories. Authors of documents and macro packages targeting groff are encouraged to use this setting. Environment GROFF_FONT_PATH and GROFF_TMAC_PATH each accept a search path of direc‐ tories; that is, a list of directory names separated by the system’s path component separator character. On Unix systems, this character is a colon (:); on Windows systems, it is a semicolon (;). GROFF_FONT_PATH A list of directories in which to seek the selected output de‐ vice’s directory of device and font description files. troff will scan directories given as arguments to any specified -F op‐ tions before these, then in a site‐specific directory (/usr/ local/share/groff/site-font), a standard location (/usr/local/ share/groff/1.23.0/font), and a compatibility directory (/usr/ lib/font) after them. GROFF_TMAC_PATH A list of directories in which to search for macro files. troff will scan directories given as arguments to any specified -M op‐ tions before these, then the current directory (only if in un‐ safe mode), the user’s home directory, a site‐specific directory (/usr/local/share/groff/site-tmac), and a standard location (/usr/local/share/groff/1.23.0/tmac) after them. GROFF_TYPESETTER Set the default output device. If empty or not set, ps is used. The -T option overrides GROFF_TYPESETTER. SOURCE_DATE_EPOCH A timestamp (expressed as seconds since the Unix epoch) to use as the output creation timestamp in place of the current time. The time is converted to human‐readable form using localtime(3) when the formatter starts up and stored in registers usable by documents and macro packages. TZ The timezone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human‐readable form; see tzset(3). Files /usr/local/share/groff/1.23.0/tmac/troffrc is an initialization macro file loaded before any macro packages specified with -m options. /usr/local/share/groff/1.23.0/tmac/troffrc-end is an initialization macro file loaded after all macro packages specified with -m options. /usr/local/share/groff/1.23.0/tmac/name.tmac are macro files distributed with groff. /usr/local/share/groff/1.23.0/font/devname/DESC describes the output device name. /usr/local/share/groff/1.23.0/font/devname/F describes the font F of device name. troffrc and troffrc-end are sought neither in the current nor the home directory by default for security reasons, even if the -U option is specified. Use the -M command‐line option or the GROFF_TMAC_PATH envi‐ ronment variable to add these directories to the search path if neces‐ sary. Authors The GNU version of troff was originally written by James Clark; he also wrote the original version of this document, which was updated by Werner Lemberg ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web .de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. groff(1) offers an overview of the GNU roff system and describes its front end executable. groff(7) details the groff language, including a short but complete ref‐ erence of all predefined requests, registers, and escape se‐ quences. groff_char(7) explains the syntax of groff special character escape sequences, and lists all special characters predefined by the language. groff_diff(7) enumerates the differences between AT&T device‐independent troff and groff. groff_font(5) covers the format of groff device and font description files. groff_out(5) describes the format of troff’s output. groff_tmac(5) includes information about macro files that ship with groff. roff(7) supplies background on roff systems in general, including point‐ ers to further related documentation. groff 1.23.0 29 August 2023 troff(1) ─────────────────────────────────────────────────────────────────────────────── xtotroff(1) General Commands Manual xtotroff(1) Name xtotroff - convert X font metrics into groff font metrics Synopsis xtotroff [-d destination‐directory] [-r resolution] [-s type‐size] font‐map xtotroff --help xtotroff -v xtotroff --version Description xtotroff uses font‐map to create groff(1) font description files from X11 fonts. Each line in font‐map consists of a series of lines of paired groff font names and X font names as X Logical Font Description (XLFD) patterns, with the pair members separated by spaces and/or tabs. For example, an input font‐map file consisting of the line TB -adobe-times-bold-r-normal--*-*-*-*-p-*-iso8859-1 maps the XLFD on the right to the groff font name TB, conventionally “Times bold”. xtotroff opens a connection to the running X server to query its font catalog, and aborts if it cannot. If necessary, the wildcards in the XLFD patterns are populated with the arguments to the -r and -s op‐ tions. If a font name is still ambiguous, xtotroff aborts. For each successful mapping, xtotroff creates a groff font description file in the current working directory (or that specified by the ‐d option) named for each groff font, and reports the mapping to the standard out‐ put stream. Options --help displays a usage message, while -v and --version show version information; all exit afterward. -d destination‐directory Write font descriptions to destination‐directory rather than the current working directory. -r resolution Set the resolution for all font patterns in font‐map. The value is used for both the horizontal and vertical motion quanta. If not specified, a resolution of 75dpi is assumed. -s type‐size Set the type size in points for all font patterns in font‐map. If not specified, a size of 10 points is assumed. Files /usr/local/share/groff/1.23.0/font/FontMap-X11 is the font mapping file used to produce the pre‐generated font description files, supplied with groff, of X11 core fonts corre‐ sponding to the 13 base Type 1 fonts for PostScript level 1. Bugs The only supported font encodings are “iso8859-1” and “adobe- fontspecific”. See also “X Logical Font Description Conventions” ⟨https://www.x.org/releases/ X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html⟩, by Jim Flowers and Stephen Gildea. X(7), groff(1), gxditview(1), troff(1), groff_font(5) groff 1.23.0 29 August 2023 xtotroff(1) ─────────────────────────────────────────────────────────────────────────────── groff_font(5) File Formats Manual groff_font(5) Name groff_font - GNU roff device and font description files Description The groff font and output device description formats are slight exten‐ sions of those used by AT&T device‐independent troff. In distinction to the AT&T implementation, groff lacks a binary format; all files are text files. (Plan 9 troff has also abandoned the binary format.) The device and font description files for a device name are stored in a de‐ vname directory. The device description file is called DESC, and, for each font supported by the device, a font description file is called f, where f is usually an abbreviation of a font’s name and/or style. For example, the ps (PostScript) device has groff font description files for Times roman (TR) and Zapf Chancery Medium italic (ZCMI), among many others, while the utf8 device (for terminal emulators) has only font descriptions for the roman, italic, bold, and bold‐italic styles (R, I, B, and BI, respectively). Device and font description files are read by the formatter, troff, and by output drivers. The programs typically delegate these files’ pro‐ cessing to an internal library, libgroff, ensuring their consistent in‐ terpretation. DESC file format The DESC file contains a series of directives; each begins a line. Their order is not important, with two exceptions: (1) the res direc‐ tive must precede any papersize directive; and (2) the charset direc‐ tive must come last (if at all). If a directive name is repeated, later entries in the file override previous ones (except that the paper dimensions are computed based on the res directive last seen when papersize is encountered). Spaces and/or tabs separate words and are ignored at line boundaries. Comments start with the “#” character and extend to the end of a line. Empty lines are ignored. family fam The default font family is fam. fonts n F1 ... Fn Fonts F1, ..., Fn are mounted at font positions m+1, ..., m+n where m is the number of styles (see below). This directive may extend over more than one line. A font name of 0 causes no font to be mounted at the corresponding position. hor n The horizontal motion quantum is n basic units. Horizontal quantities are rounded to multiples of n. image_generator program Use program to generate PNG images from PostScript input. Under GNU/Linux, this is usually gs(1), but under other systems (no‐ tably Cygwin) it might be set to another name. The grohtml(1) driver uses this directive. paperlength n The vertical dimension of the output medium is n basic units (deprecated: use papersize instead). papersize format‐or‐dimension‐pair‐or‐file‐name ... The dimensions of the output medium are as according to the ar‐ gument, which is either a standard paper format, a pair of di‐ mensions, or the name of a plain text file containing either of the foregoing. Recognized paper formats are the ISO and DIN formats A0–A7, B0–B7, C0–C7, and D0–D7; the U.S. formats letter, legal, tabloid, ledger, statement, and executive; and the enve‐ lope formats com10, monarch, and DL. Matching is performed without regard for lettercase. Alternatively, the argument can be a custom paper format length,width (with no spaces before or after the comma). Both length and width must have a unit appended; valid units are “i” for inches, “c” for centimeters, “p” for points, and “P” for pi‐ cas. Example: “12c,235p”. An argument that starts with a digit is always treated as a custom paper format. Finally, the argument can be a file name (e.g., /etc/papersize); if the file can be opened, the first line is read and a match attempted against each other form. No comment syntax is sup‐ ported. More than one argument can be specified; each is scanned in turn and the first valid paper specification used. paperwidth n The horizontal dimension of the output medium is n basic units (deprecated: use papersize instead). pass_filenames Direct troff to emit the name of the source file being processed. This is achieved with the intermediate output com‐ mand “x F”, which grohtml interprets. postpro program Use program as the postprocessor. prepro program Use program as a preprocessor. The html and xhtml output de‐ vices use this directive. print program Use program as the print spooler. If omitted, groff’s -l and -L options are ignored. res n The device resolution is n basic units per inch. sizes s1 ... sn 0 The device has fonts at s1, ..., sn scaled points (see below). The list of sizes must be terminated by a 0. Each si can also be a range of sizes m–n. The list can extend over more than one line. sizescale n A typographical point is subdivided into n scaled points. The default is 1. styles S1 ... Sm The first m font mounting positions are associated with styles S1, ..., Sm. tcommand The postprocessor can handle the t and u intermediate output commands. unicode The output device supports the complete Unicode repertoire. This directive is useful only for devices which produce charac‐ ter entities instead of glyphs. If unicode is present, no charset section is required in the font description files since the Unicode handling built into groff is used. However, if there are entries in a font descrip‐ tion file’s charset section, they either override the default mappings for those particular characters or add new mappings (normally for composite characters). The utf8, html, and xhtml output devices use this directive. unitwidth n Quantities in the font description files are in basic units for fonts whose type size is n scaled points. unscaled_charwidths Make the font handling module always return unscaled glyph widths. The grohtml driver uses this directive. use_charnames_in_special troff should encode named glyphs inside device control commands. The grohtml driver uses this directive. vert n The vertical motion quantum is n basic units. Vertical quanti‐ ties are rounded to multiples of n. charset This directive and the rest of the file are ignored. It is rec‐ ognized for compatibility with other troff implementations. In GNU troff, character set repertoire is described on a per‐font basis. troff recognizes but ignores the directives spare1, spare2, and biggestfont. The res, unitwidth, fonts, and sizes lines are mandatory. Directives not listed above are ignored by troff but may be used by postprocessors to obtain further information about the device. Font description file format On typesetting output devices, each font is typically available at mul‐ tiple sizes. While paper measurements in the device description file are in absolute units, measurements applicable to fonts must be propor‐ tional to the type size. groff achieves this using the precedent set by AT&T device‐independent troff: one font size is chosen as a norm, and all others are scaled linearly relative to that basis. The “unit width” is the number of basic units per point when the font is rendered at this nominal size. For instance, groff’s lbp device uses a unitwidth of 800. Its Times roman font (“TR”) has a spacewidth of 833; this is also the width of its comma, period, centered period, and mathematical asterisk, while its “M” is 2,963 basic units. Thus, an “M” on the lbp device is 2,963 basic units wide at a notional type size of 800 points. (800‐point type is not practical for most purposes, but using it enables the quan‐ tities in the font description files to be expressed as integers.) A font description file has two sections. The first is a sequence of directives, and is parsed similarly to the DESC file described above. Except for the directive names that begin the second section, their or‐ dering is immaterial. Later directives of the same name override ear‐ lier ones, spaces and tabs are handled in the same way, and the same comment syntax is supported. Empty lines are ignored throughout. name F The name of the font is F. “DESC” is an invalid font name. Simple integers are valid, but their use is discouraged. (groff requests and escape sequences interpret non‐negative font names as mounting positions instead. Further, a font named “0” cannot be automatically mounted by the fonts directive of a DESC file.) spacewidth n The width of an unadjusted inter‐word space is n basic units. The directives above must appear in the first section; those below are optional. slant n The font’s glyphs have a slant of n degrees; a positive n slants in the direction of text flow. ligatures lig1 ... lign [0] Glyphs lig1, ..., lign are ligatures; possible ligatures are ff, fi, fl, ffi, and ffl. For compatibility with other troff imple‐ mentations, the list of ligatures may be terminated with a 0. The list of ligatures must not extend over more than one line. special The font is special: when a glyph is requested that is not present in the current font, it is sought in any mounted fonts that bear this property. Other directives in this section are ignored by troff, but may be used by postprocessors to obtain further information about the font. The second section contains one or two subsections. These can appear in either order; the first one encountered commences the second sec‐ tion. Each starts with a directive on a line by itself. A charset subsection is mandatory unless the associated DESC file contains the unicode directive. Another subsection, kernpairs, is optional. The directive charset starts the character set subsection. (For type‐ setter devices, this directive is misnamed since it starts a list of glyphs, not characters.) It precedes a series of glyph descriptions, one per line. Each such glyph description comprises a set of fields separated by spaces or tabs and organized as follows. name metrics type code [entity‐name] [-- comment] name identifies the glyph: if name is a printable character c, it cor‐ responds to the troff ordinary character c. If name is a multi‐charac‐ ter sequence not beginning with \, it corresponds to the GNU troff spe‐ cial character escape sequence “\[name]”. A name consisting of three minus signs, “---”, indicates that the glyph is unnamed: such glyphs can be accessed only by the \N escape sequence in troff. A special character named “---” can still be defined using .char and similar re‐ quests. The name “\-” defines the minus sign glyph. Finally, name can be the horizontal motion escape sequences, \| and \^ (“thin” and “hair” spaces, respectively), in which case only the width metric described below is applied; a font can thus customize the widths of these spaces. The form of the metrics field is as follows (on one line; it may be broken here for readability). width[,[height[,[depth[,[italic‐correction[,[ left‐italic‐correction[,[subscript‐correction]]]]]]]]]] There must not be any spaces, tabs, or newlines between these sub‐ fields, which are in basic units expressed as decimal integers. Un‐ specified subfields default to 0. Since there is no associated binary format, these values are not required to fit into the C language data type char as they are in AT&T device‐independent troff. The width subfield gives the width of the glyph. The height subfield gives the height of the glyph (upwards is positive); if a glyph does not extend above the baseline, it should be given a zero height, rather than a negative height. The depth subfield gives the depth of the glyph, that is, the distance below the baseline to which the glyph ex‐ tends (downwards is positive); if a glyph does not extend below the baseline, it should be given a zero depth, rather than a negative depth. Italic corrections are relevant to glyphs in italic or oblique styles. The italic‐correction is the amount of space that should be added after an oblique glyph to be followed immediately by an upright glyph. The left‐italic‐correction is the amount of space that should be added before an oblique glyph to be preceded immediately by an up‐ right glyph. The subscript‐correction is the amount of space that should be added after an oblique glyph to be followed by a subscript; it should be less than the italic correction. For fonts used with typesetting devices, the type field gives a feat‐ ural description of the glyph: it is a bit mask recording whether the glyph is an ascender, descender, both, or neither. When a \w escape sequence is interpolated, these values are bitwise or‐ed together for each glyph and stored in the ct register. In font descriptions for terminal devices, all glyphs might have a type of zero, regardless of their appearance. 0 means the glyph lies entirely between the baseline and a hori‐ zontal line at the “x‐height” of the font, as with “a”, “c”, and “x”; 1 means the glyph descends below the baseline, like “p”; 2 means the glyph ascends above the font’s x‐height, like “A” or “b”); and 3 means the glyph is both an ascender and a descender—this is true of parentheses in some fonts. The code field gives a numeric identifier that the postprocessor uses to render the glyph. The glyph can be specified to troff using this code by means of the \N escape sequence. The code can be any integer (that is, any integer parsable by the C standard library’s strtol(3) function). The entity‐name field defines an identifier for the glyph that the postprocessor uses to print the troff glyph name. This field is op‐ tional; it was introduced so that the grohtml output driver could en‐ code its character set. For example, the glyph \[Po] is represented by “£” in HTML 4.0. For efficiency, these data are now compiled di‐ rectly into grohtml. grops uses the field to build sub‐encoding arrays for PostScript fonts containing more than 256 glyphs. Anything on the line after the entity‐name field or “--” is ignored. A line in the charset section can also have the form name " identifying name as another name for the glyph mentioned in the preced‐ ing line. Such aliases can be chained. The directive kernpairs starts a list of kerning adjustments to be made to adjacent glyph pairs from this font. It contains a sequence of lines formatted as follows. g1 g2 n The foregoing means that when glyph g1 is typeset immediately before g2, the space between them should be increased by n. Most kerning pairs should have a negative value for n. Files /usr/local/share/groff/1.23.0/font/devname/DESC describes the output device name. /usr/local/share/groff/1.23.0/font/devname/F describes the font known as F on device name. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. “Troff User’s Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report No. 54, widely called simply “CSTR #54”, documents the language, device and font description file formats, and device‐independent output format referred to collectively in groff documentation as “AT&T troff”. “A Typesetter‐independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science Technical Report No. 97, provides addi‐ tional insights into the device and font description file formats and device‐independent output format. groff(1), subsection “Utilities”, lists programs available for describ‐ ing fonts in a variety of formats such that groff output drivers can use them. troff(1) documents the default device and font description file search path. groff_out(5), addftinfo(1) groff 1.23.0 29 August 2023 groff_font(5) ─────────────────────────────────────────────────────────────────────────────── groff_out(5) File Formats Manual groff_out(5) Name groff_out - GNU roff intermediate output format Description The fundamental operation of the troff(1) formatter is the translation of the groff(7) input language into a series of instructions concerned primarily with placing glyphs or geometric objects at specific posi‐ tions on a rectangular page. In the following discussion, the term command refers to this intermediate output language, never to the groff(7) language intended for use by document authors. Intermediate output commands comprise several categories: glyph output; font, color, and text size selection; motion of the printing position; page advance‐ ment; drawing of geometric primitives; and device control commands, a catch‐all for other operations. The last includes directives to start and stop output, identify the intended output device, and embed URL hy‐ perlinks in supported output formats. Because the front‐end command groff(1) is a wrapper that normally runs the troff formatter to generate intermediate output and an output dri‐ ver (“postprocessor”) to consume it, users normally do not encounter this language. The groff program’s -Z option inhibits postprocessing such that this intermediate output is sent to the standard output stream as when troff is run manually. groff’s intermediate output facilitates the development of output dri‐ vers and other postprocessors by offering a common programming inter‐ face. It is an extension of the page description language developed by Brian Kernighan for AT&T device‐independent troff circa 1980. Where a distinction is necessary, we will say “troff output” to describe the output of GNU troff, and “intermediate output” to denote the language accepted by the parser implemented in groff’s internal C++ library used by most of its output drivers. Language concepts During the run of troff, the roff input is cracked down to the informa‐ tion on what has to be printed at what position on the intended device. So the language of the intermediate output format can be quite small. Its only elements are commands with or without arguments. In this doc‐ ument, the term “command” always refers to the intermediate output lan‐ guage, never to the roff language used for document formatting. There are commands for positioning and text writing, for drawing, and for de‐ vice controlling. Separation Classical troff output had strange requirements on whitespace. The groff output parser, however, is smart about whitespace by making it maximally optional. The whitespace characters, i.e., the tab, space, and newline characters, always have a syntactical meaning. They are never printable because spacing within the output is always done by po‐ sitioning commands. Any sequence of space or tab characters is treated as a single syntac‐ tical space. It separates commands and arguments, but is only required when there would occur a clashing between the command code and the ar‐ guments without the space. Most often, this happens when variable length command names, arguments, argument lists, or command clusters meet. Commands and arguments with a known, fixed length need not be separated by syntactical space. A line break is a syntactical element, too. Every command argument can be followed by whitespace, a comment, or a newline character. Thus a syntactical line break is defined to consist of optional syntactical space that is optionally followed by a comment, and a newline charac‐ ter. The normal commands, those for positioning and text, consist of a sin‐ gle letter taking a fixed number of arguments. For historical reasons, the parser allows stacking of such commands on the same line, but for‐ tunately, in groff intermediate output, every command with at least one argument is followed by a line break, thus providing excellent read‐ ability. The other commands — those for drawing and device controlling — have a more complicated structure; some recognize long command names, and some take a variable number of arguments. So all D and x commands were de‐ signed to request a syntactical line break after their last argument. Only one command, ‘x X’ has an argument that can stretch over several lines, all other commands must have all of their arguments on the same line as the command, i.e., the arguments may not be split by a line break. Lines containing only spaces and/or a comment are treated as empty and ignored. Argument units Some commands accept integer arguments that represent measurements, but the scaling units of the formatter’s language are never used. Most commands assume a scaling unit of “u” (basic units), and others use “z” (scaled points); These are defined by the parameters specified in the device’s DESC file; see groff_font(5) and, for more on scaling units, groff(7) and Groff: The GNU Implementation of troff, the groff Texinfo manual. Color‐related commands use dimensionless integers. Note that single characters can have the eighth bit set, as can the names of fonts and special characters (this is, glyphs). The names of glyphs and fonts can be of arbitrary length. A glyph that is to be printed will always be in the current font. A string argument is always terminated by the next whitespace character (space, tab, or newline); an embedded # character is regarded as part of the argument, not as the beginning of a comment command. An integer argument is already terminated by the next non‐digit character, which then is regarded as the first character of the next argument or com‐ mand. Document parts A correct intermediate output document consists of two parts, the pro‐ logue and the body. The task of the prologue is to set the general device parameters using three exactly specified commands. The groff prologue is guaranteed to consist of the following three lines (in that order): x T device x res n h v x init with the arguments set as outlined in subsection “Device Control Com‐ mands” below. However, the parser for the intermediate output format is able to swallow additional whitespace and comments as well. The body is the main section for processing the document data. Syntac‐ tically, it is a sequence of any commands different from the ones used in the prologue. Processing is terminated as soon as the first x stop command is encountered; the last line of any groff intermediate output always contains such a command. Semantically, the body is page oriented. A new page is started by a p command. Positioning, writing, and drawing commands are always done within the current page, so they cannot occur before the first p com‐ mand. Absolute positioning (by the H and V commands) is done relative to the current page, all other positioning is done relative to the cur‐ rent location within this page. Command reference This section describes all intermediate output commands, the classical commands as well as the groff extensions. Comment command #anything⟨line‐break⟩ A comment. Ignore any characters from the # character up to the next newline. Each comment can be preceded by arbitrary syntac‐ tical space; every command can be terminated by a comment. Simple commands The commands in this subsection have a command code consisting of a single character, taking a fixed number of arguments. Most of them are commands for positioning and text writing. These commands are smart about whitespace. Optionally, syntactical space can be inserted be‐ fore, after, and between the command letter and its arguments. All of these commands are stackable, i.e., they can be preceded by other sim‐ ple commands or followed by arbitrary other commands on the same line. A separating syntactical space is necessary only when two integer argu‐ ments would clash or if the preceding argument ends with a string argu‐ ment. C id⟨white‐space⟩ Typeset the glyph of the special character id. Trailing syntac‐ tical space is necessary to allow special character names of ar‐ bitrary length. The drawing position is not advanced. c c Typeset the glyph of the ordinary character character c. The drawing position is not advanced. f n Select the font mounted at position n. n cannot be negative. H n Horizontally move the drawing position to n basic units from the left edge of the page. n cannot be negative. h n Move the drawing position right n basic units. AT&T troff al‐ lowed negative n; GNU troff does not produce such values, but groff’s output driver library handles them. m scheme [component ...] Select the stroke color using the components in the color space scheme. Each component is an integer between 0 and 65536. The quantity of components and their meanings vary with each scheme. This command is a groff extension. mc cyan magenta yellow Use the CMY color scheme with components cyan, magenta, and yellow. md Use the default color (no components; black in most cases). mg gray Use a grayscale color scheme with a component ranging be‐ tween 0 (black) and 65536 (white). mk cyan magenta yellow black Use the CMYK color scheme with components cyan, magenta, yellow, and black. mr red green blue Use the RGB color scheme with components red, green, and blue. N n Typeset the glyph with index n in the current font. n is nor‐ mally a non‐negative integer. The drawing position is not ad‐ vanced. The html and xhtml devices use this command with nega‐ tive n to produce unbreakable space; the absolute value of n is taken and interpreted in basic units. n b a Indicate a break. No action is performed; the command is present to make the output more easily parsed. The integers b and a describe the vertical space amounts before and after the break, respectively. GNU troff issues this command but groff’s output driver library ignores it. See v and V. p n Begin a new page, setting its number to n. Each page is inde‐ pendent, even from those using the same number. The vertical drawing position is set to 0. All positioning, writing, and drawing commands are interpreted in the context of a page, so a p command must precede them. s n Set type size to n scaled points (unit z in GNU troff). AT&T troff used unscaled points (p) instead; see section “Compatibil‐ ity” below. t xyz...⟨white‐space⟩ t xyz... dummy‐arg⟨white‐space⟩ Typeset word xyz; that is, set a sequence of ordinary glyphs named x, y, z, ..., terminated by a space or newline; an op‐ tional second integer argument is ignored (this allows the for‐ matter to generate an even number of arguments). Each glyph is set at the current drawing position, and the position is then advanced horizontally by the glyph’s width. A glyph’s width is read from its metrics in the font description file, scaled to the current type size, and rounded to a multiple of the horizon‐ tal motion quantum. Use the C command to emplace glyphs of spe‐ cial characters. The t command is a groff extension and is out‐ put only for devices whose DESC file contains the tcommand di‐ rective; see groff_font(5). u n xyz... u xyz... dummy‐arg⟨white‐space⟩ Typeset word xyz with track kerning. As t, but after placing each glyph, the drawing position is further advanced horizon‐ tally by n basic units. The u command is a groff extension and is output only for devices whose DESC file contains the tcommand directive; see groff_font(5). V n Vertically move the drawing position to n basic units from the top edge of the page. n cannot be negative. v n Move the drawing position down n basic units. AT&T troff al‐ lowed negative n; GNU troff does not produce such values, but groff’s output driver library handles them. w Indicate an inter‐word space. No action is performed; the com‐ mand is present to make the output more easily parsed. Only ad‐ justable, breakable inter‐word spaces are thus described; those resulting from \~ or horizontal motion escape sequences are not. GNU troff issues this command but groff’s output driver library ignores it. See h and H. Graphics commands Each graphics or drawing command in the intermediate output starts with the letter D followed by one or two characters that specify a subcom‐ mand; this is followed by a fixed or variable number of integer argu‐ ments that are separated by a single space character. A D command may not be followed by another command on the same line (apart from a com‐ ment), so each D command is terminated by a syntactical line break. troff output follows the classical spacing rules (no space between com‐ mand and subcommand, all arguments are preceded by a single space char‐ acter), but the parser allows optional space between the command let‐ ters and makes the space before the first argument optional. As usual, each space can be any sequence of tab and space characters. Some graphics commands can take a variable number of arguments. In this case, they are integers representing a size measured in basic units u. The h arguments stand for horizontal distances where positive means right, negative left. The v arguments stand for vertical dis‐ tances where positive means down, negative up. All these distances are offsets relative to the current location. Unless indicated otherwise, each graphics command directly corresponds to a similar groff \D escape sequence; see groff(7). Unknown D commands are assumed to be device‐specific. Its arguments are parsed as strings; the whole information is then sent to the post‐ processor. In the following command reference, the syntax element ⟨line‐break⟩ means a syntactical line break as defined in subsection “Separation” above. D~ h1 v1 h2 v2 ... hn vn⟨line‐break⟩ Draw B‐spline from current position to offset (h1, v1), then to offset (h2, v2) if given, etc., up to (hn, vn). This command takes a variable number of argument pairs; the current position is moved to the terminal point of the drawn curve. Da h1 v1 h2 v2⟨line‐break⟩ Draw arc from current position to (h1, v1)+(h2, v2) with center at (h1, v1); then move the current position to the final point of the arc. DC d⟨line‐break⟩ DC d dummy‐arg⟨line‐break⟩ Draw a solid circle using the current fill color with diameter d (integer in basic units u) with leftmost point at the current position; then move the current position to the rightmost point of the circle. An optional second integer argument is ignored (this allows the formatter to generate an even number of argu‐ ments). This command is a groff extension. Dc d⟨line‐break⟩ Draw circle line with diameter d (integer in basic units u) with leftmost point at the current position; then move the current position to the rightmost point of the circle. DE h v⟨line‐break⟩ Draw a solid ellipse in the current fill color with a horizontal diameter of h and a vertical diameter of v (both integers in ba‐ sic units u) with the leftmost point at the current position; then move to the rightmost point of the ellipse. This command is a groff extension. De h v⟨line‐break⟩ Draw an outlined ellipse with a horizontal diameter of h and a vertical diameter of v (both integers in basic units u) with the leftmost point at current position; then move to the rightmost point of the ellipse. DF color‐scheme [component ...]⟨line‐break⟩ Set fill color for solid drawing objects using different color schemes; the analogous command for setting the color of text, line graphics, and the outline of graphic objects is m. The color components are specified as integer arguments between 0 and 65536. The number of color components and their meaning vary for the different color schemes. These commands are gener‐ ated by the groff escape sequences \D'F ...’ and \M (with no other corresponding graphics commands). This command is a groff extension. DFc cyan magenta yellow⟨line‐break⟩ Set fill color for solid drawing objects using the CMY color scheme, having the 3 color components cyan, ma‐ genta, and yellow. DFd ⟨line‐break⟩ Set fill color for solid drawing objects to the default fill color value (black in most cases). No component ar‐ guments. DFg gray⟨line‐break⟩ Set fill color for solid drawing objects to the shade of gray given by the argument, an integer between 0 (black) and 65536 (white). DFk cyan magenta yellow black⟨line‐break⟩ Set fill color for solid drawing objects using the CMYK color scheme, having the 4 color components cyan, ma‐ genta, yellow, and black. DFr red green blue⟨line‐break⟩ Set fill color for solid drawing objects using the RGB color scheme, having the 3 color components red, green, and blue. Df n⟨line‐break⟩ The argument n must be an integer in the range -32767 to 32767. 0≤n≤1000 Set the color for filling solid drawing objects to a shade of gray, where 0 corresponds to solid white, 1000 (the default) to solid black, and values in between to intermediate shades of gray; this is obsoleted by command DFg. n<0 or n>1000 Set the filling color to the color that is currently be‐ ing used for the text and the outline, see command m. For example, the command sequence mg 0 0 65536 Df -1 sets all colors to blue. This command is a groff extension. Dl h v⟨line‐break⟩ Draw line from current position to offset (h, v) (integers in basic units u); then set current position to the end of the drawn line. Dp h1 v1 h2 v2 ... hn vn⟨line‐break⟩ Draw a polygon line from current position to offset (h1, v1), from there to offset (h2, v2), etc., up to offset (hn, vn), and from there back to the starting position. For historical rea‐ sons, the position is changed by adding the sum of all arguments with odd index to the current horizontal position and the even ones to the vertical position. Although this doesn’t make sense it is kept for compatibility. This command is a groff exten‐ sion. DP h1 v1 h2 v2 ... hn vn⟨line‐break⟩ The same macro as the corresponding Dp command with the same ar‐ guments, but draws a solid polygon in the current fill color rather than an outlined polygon. The position is changed in the same way as with Dp. This command is a groff extension. Dt n⟨line‐break⟩ Set the current line thickness to n (an integer in basic units u) if n>0; if n=0 select the smallest available line thickness; otherwise, the line thickness is made proportional to the type size, which is the default. For historical reasons, the horizontal position is changed by adding the argument to the current horizontal position, while the vertical position is not changed. Although this doesn’t make sense, it is kept for com‐ patibility. This command is a groff extension. Device control commands Each device control command starts with the letter x followed by a space character (optional or arbitrary space/tab in groff) and a sub‐ command letter or word; each argument (if any) must be preceded by a syntactical space. All x commands are terminated by a syntactical line break; no device control command can be followed by another command on the same line (except a comment). The subcommand is basically a single letter, but to increase readabil‐ ity, it can be written as a word, i.e., an arbitrary sequence of char‐ acters terminated by the next tab, space, or newline character. All characters of the subcommand word but the first are simply ignored. For example, troff outputs the initialization command x i as x init and the resolution command x r as x res. But writings like x i_like_groff and x roff_is_groff are accepted as well to mean the same commands. In the following, the syntax element ⟨line‐break⟩ means a syntactical line break as defined in subsection “Separation” above. xF name⟨line‐break⟩ (Filename control command) Use name as the intended name for the current file in error re‐ ports. This is useful for remembering the original file name when groff uses an internal piping mechanism. The input file is not changed by this command. This command is a groff extension. xf n s⟨line‐break⟩ (font control command) Mount font position n (a non‐negative integer) with font named s (a text word); see groff_font(5). xH n⟨line‐break⟩ (Height control command) Set character height to n (a positive integer in scaled points z). Classical troff used the unit points (p) instead; see section “Compatibility” below. xi ⟨line‐break⟩ (init control command) Initialize device. This is the third command of the prologue. xp ⟨line‐break⟩ (pause control command) Parsed but ignored. The classical documentation reads pause de‐ vice, can be restarted. xr n h v⟨line‐break⟩ (resolution control command) Resolution is n, while h is the minimal horizontal motion, and v the minimal vertical motion possible with this device; all argu‐ ments are positive integers in basic units u per inch. This is the second command of the prologue. xS n⟨line‐break⟩ (Slant control command) Set slant to n degrees (an integer in basic units u). xs ⟨line‐break⟩ (stop control command) Terminates the processing of the current file; issued as the last command of any intermediate troff output. xt ⟨line‐break⟩ (trailer control command) Generate trailer information, if any. In groff, this is cur‐ rently ignored. xT xxx⟨line‐break⟩ (Typesetter control command) Set the name of the output driver to xxx, a sequence of non‐ whitespace characters terminated by whitespace. The possible names correspond to those of groff’s -T option. This is the first command of the prologue. xu n⟨line‐break⟩ (underline control command) Configure underlining of spaces. If n is 1, start underlining of spaces; if n is 0, stop underlining of spaces. This is needed for the cu request in nroff mode and is ignored other‐ wise. This command is a groff extension. xX anything⟨line‐break⟩ (X‐escape control command) Send string anything uninterpreted to the device. If the line following this command starts with a + character this line is interpreted as a continuation line in the following sense. The + is ignored, but a newline character is sent instead to the de‐ vice, the rest of the line is sent uninterpreted. The same ap‐ plies to all following lines until the first character of a line is not a + character. This command is generated by the groff escape sequence \X. The line‐continuing feature is a groff ex‐ tension. Obsolete command In classical troff output, emitting a single glyph was mostly done by a very strange command that combined a horizontal move and the printing of a glyph. It didn’t have a command code, but is represented by a 3‐character argument consisting of exactly 2 digits and a character. ddc Move right dd (exactly two decimal digits) basic units u, then print glyph with single‐letter name c. In groff, arbitrary syntactical space around and within this command is allowed to be added. Only when a preceding command on the same line ends with an argument of variable length a sep‐ arating space is obligatory. In classical troff, large clusters of these and other commands were used, mostly without spaces; this made such output almost unreadable. For modern high‐resolution devices, this command does not make sense because the width of the glyphs can become much larger than two decimal digits. In groff, it is used only for output to the X75, X75-12, X100, and X100-12 devices. For others, the commands t and u provide greater functionality and superior troubleshooting capacity. Postprocessing The roff postprocessors are programs that have the task to translate the intermediate output into actions that are sent to a device. A de‐ vice can be some piece of hardware such as a printer, or a software file format suitable for graphical or text processing. The groff sys‐ tem provides powerful means that make the programming of such post‐ processors an easy task. There is a library function that parses the intermediate output and sends the information obtained to the device via methods of a class with a common interface for each device. So a groff postprocessor must only redefine the methods of this class. For details, see the refer‐ ence in section “Files” below. Example This section presents the intermediate output generated from the same input for three different devices. The input is the sentence hell world fed into groff on the command line. • High‐resolution device ps shell> echo "hell world" | groff -Z -T ps x T ps x res 72000 1 1 x init p1 x font 5 TR f5 s10000 V12000 H72000 thell wh2500 tw H96620 torld n12000 0 x trailer V792000 x stop This output can be fed into the postprocessor grops(1) to get its rep‐ resentation as a PostScript file, or gropdf(1) to output directly to PDF. • Low‐resolution device latin1 This is similar to the high‐resolution device except that the posi‐ tioning is done at a minor scale. Some comments (lines starting with #) were added for clarification; they were not generated by the for‐ matter. shell> "hell world" | groff -Z -T latin1 # prologue x T latin1 x res 240 24 40 x init # begin a new page p1 # font setup x font 1 R f1 s10 # initial positioning on the page V40 H0 # write text 'hell' thell # inform about a space, and do it by a horizontal jump wh24 # write text 'world' tworld # announce line break, but do nothing because ... n40 0 # ... the end of the document has been reached x trailer V2640 x stop This output can be fed into the postprocessor grotty(1) to get a for‐ matted text document. • Classical style output As a computer monitor has a very low resolution compared to modern printers the intermediate output for the X devices can use the jump‐ and‐write command with its 2‐digit displacements. shell> "hell world" | groff -Z -T X100 x T X100 x res 100 1 1 x init p1 x font 5 TR f5 s10 V16 H100 # write text with old‐style jump‐and‐write command ch07e07l03lw06w11o07r05l03dh7 n16 0 x trailer V1100 x stop This output can be fed into the postprocessor xditview(1x) or gxditview(1) for displaying in X. Due to the obsolete jump‐and‐write command, the text clusters in the classical output are almost unreadable. Compatibility The intermediate output language of the classical troff was first docu‐ mented in [CSTR #97]. The groff intermediate output format is compati‐ ble with this specification except for the following features. • The classical quasi device independence is not yet implemented. • The old hardware was very different from what we use today. So the groff devices are also fundamentally different from the ones in clas‐ sical troff. For example, the classical PostScript device was called post and had a resolution of 720 units per inch, while groff’s ps de‐ vice has a resolution of 72000 units per inch. Maybe, by implement‐ ing some rescaling mechanism similar to the classical quasi device independence, these could be integrated into modern groff. • The B‐spline command D~ is correctly handled by the intermediate out‐ put parser, but the drawing routines aren’t implemented in some of the postprocessor programs. • The argument of the commands s and x H has the implicit unit scaled point z in groff, while classical troff had point (p). This isn’t an incompatibility, but a compatible extension, for both units coincide for all devices without a sizescale parameter, including all classi‐ cal and the groff text devices. The few groff devices with a sizescale parameter either did not exist, had a different name, or seem to have had a different resolution. So conflicts with classical devices are very unlikely. • The position changing after the commands Dp, DP, and Dt is illogical, but as old versions of groff used this feature it is kept for compat‐ ibility reasons. The differences between groff and classical troff are documented in groff_diff(7). Files /usr/local/share/groff/1.23.0/font/devname/DESC describes the output device name. Authors James Clark wrote an early version of this document, which described only the differences between AT&T device‐independent troff’s output format and that of GNU roff. The present version was completely rewritten in 2001 by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. “Troff User’s Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report No. 54, widely called simply “CSTR #54”, documents the language, device and font description file formats, and device‐independent output format referred to collectively in groff documentation as “AT&T troff”. “A Typesetter‐independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science Technical Report No. 97, provides addi‐ tional insights into the device and font description file formats and device‐independent output format. groff(1) documents the -Z option and contains pointers to further groff documentation. groff(7) describes the groff language, including its escape sequences and system of units. groff_font(5) details the device scaling parameters of device DESC files. troff(1) generates the device‐independent intermediate output documented here. roff(7) presents historical aspects and the general structure of roff systems. groff_diff(7) enumerates differences between the intermediate output produced by AT&T troff and that of groff. gxditview(1) is a viewer for intermediate output. Roff.js ⟨https://github.com/Alhadis/Roff.js/⟩ is a viewer for intermedi‐ ate output written in JavaScript. grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), and grotty(1) are groff postprocessors. groff 1.23.0 29 August 2023 groff_out(5) ─────────────────────────────────────────────────────────────────────────────── groff_tmac(5) File Formats Manual groff_tmac(5) Name groff_tmac - macro files in the GNU roff typesetting system Description Definitions of macros, strings, and registers for use in a roff(7) doc‐ ument can be collected into macro files, roff input files designed to produce no output themselves but instead ease the preparation of other roff documents. There is no syntactical difference between a macro file and any other roff document; only its purpose distinguishes it. When a macro file is installed at a standard location, named according to a certain convention, and suitable for use by a general audience, it is termed a macro package. Macro packages can be loaded by supplying the -m option to troff(1) or a groff front end. Each macro package stores its macro, string, and register definitions in one or more tmac files. This name originated in early Unix culture as an abbreviation of “troff macros”. A macro file must have a name in the form name.tmac (or tmac.name) and be placed in a “tmac directory” to be loadable with the -mname option. Section “Environment” of troff(1) lists these directories. Alterna‐ tively, a groff document requiring a macro file can load it with the mso (“macro source”) request. Like any other roff document, a macro file can use the “so” request (“source”) to load further files relative to its own location. Macro files are named for their most noteworthy application, but a macro file need not define any macros. It can restrict itself to defining registers and strings or invoking other groff requests. It can even be empty. Macro packages Macro packages come in two varieties; those which assume responsibility for page layout and other critical functions (“major” or “full‐ser‐ vice”) and those which do not (“supplemental” or “auxiliary”). GNU roff provides most major macro packages found in AT&T and BSD Unix sys‐ tems, an additional full‐service package, and many supplemental pack‐ ages. Multiple full‐service macro packages cannot be used by the same document. Auxiliary packages can generally be freely combined, though attention to their use of the groff language name spaces for identi‐ fiers (particularly registers, macros, strings, and diversions) should be paid. Name space management was a significant challenge in AT&T troff; groff’s support for arbitrarily long identifiers affords few ex‐ cuses for name collisions, apart from attempts at compatibility with the demands of historical documents. Man pages an man an is used to compose man pages in the format originating in Version 7 Unix (1979). It has a small macro interface and is widely used; see groff_man(7). doc mdoc doc is used to compose man pages in the format originating in 4.3BSD‐Reno (1990). It provides many more features than an, but is also larger, more complex, and not as widely adopted; see groff_mdoc(7). Because readers of man pages often do not know in advance which macros are used to format a given document, a wrapper is available. andoc mandoc This macro file, specific to groff, recognizes whether a docu‐ ment uses man or mdoc format and loads the corresponding macro package. Multiple man pages, in either format, can be handled; andoc reloads each macro package as necessary. Full‐service packages The packages in this section provide a complete set of macros for writ‐ ing documents of any kind, up to whole books. They are similar in functionality; it is a matter of taste which one to use. me The classical me macro package; see groff_me(7). mm The semi‐classical mm macro package; see groff_mm(7). mom The mom macro package, only available in groff. As this was not based on other packages, it was freely designed as quite a nice, modern macro package. See groff_mom(7). ms The classical ms macro package; see groff_ms(7). Localization packages For Western languages, the localization file sets the hyphenation mode and loads hyphenation patterns and exceptions. Localization files can also adjust the date format and provide translations of strings used by some of the full‐service macro packages; alter the input encoding (see the next section); and change the amount of additional inter‐sentence space. For Eastern languages, the localization file defines character classes and sets flags on them. By default, troffrc loads the local‐ ization file for English. trans loads localized strings used by various macro packages after their localized forms have been prepared by a localization macro file. groff provides the following localization files. cs Czech; localizes man, me, mm, mom, and ms. Sets the input en‐ coding to Latin‐2 by loading latin2.tmac. de den German; localizes man, me, mm, mom, and ms. Sets the input en‐ coding to Latin‐1 by loading latin1.tmac. de.tmac selects hyphenation patterns for traditional orthogra‐ phy, and den.tmac does the same for the new orthography (“Recht‐ schreibreform”). en English. fr French; localizes man, me, mm, mom, and ms. Sets the input en‐ coding to Latin‐9 by loading latin9.tmac. it Italian; localizes man, me, mm, mom, and ms. ja Japanese. sv Swedish; localizes man, me, mm, mom, and ms. Sets the input en‐ coding to Latin‐1 by loading latin1.tmac. Some of the localiza‐ tion of the mm package is handled separately; see groff_mmse(7). zh Chinese. Input encodings latin1 latin2 latin5 latin9 are various ISO 8859 input encodings supported by groff. On systems using ISO character encodings, groff loads latin1.tmac automatically at startup. A document that uses Latin‐2, Latin‐5, or Latin‐9 can specify one of these alternative encod‐ ings. cp1047 provides support for EBCDIC‐based systems. On those platforms, groff loads cp1047.tmac automatically at startup. Because different input character codes constitute valid GNU troff in‐ put on ISO and EBCDIC systems, the latin macro files cannot be used on EBCDIC systems, and cp1047 cannot be used on ISO systems. Auxiliary packages The macro packages in this section are not intended for stand‐alone use, but can add functionality to any other macro package or to plain (“raw”) groff documents. 62bit provides macros for addition, multiplication, and division of 62‐bit integers (allowing safe multiplication of signed 31‐bit integers, for example). hdtbl allows the generation of tables using a syntax similar to the HTML table model. This Heidelberger table macro package is not a preprocessor, which can be useful if the contents of table en‐ tries are determined by macro calls or string interpolations. Compare to tbl(1). It works only with the ps and pdf output de‐ vices. See groff_hdtbl(7). papersize enables the paper format to be set on the command line by giving a “-d paper=format” option to troff. Possible values for format are the ISO and DIN formats “A0–A6”, “B0–B6”, “C0–C6”, and “D0–D6”; the U.S. formats “letter”, “legal”, “tabloid”, “ledger”, “statement”, and “executive”; and the envelope formats “com10”, “monarch”, and “DL”. All formats, even those for en‐ velopes, are in portrait orientation: the length measurement is vertical. Appending “l” (ell) to any of these denotes landscape orientation instead. This macro file assumes one‐inch horizon‐ tal margins, and sets registers recognized by the groff man, mdoc, mm, mom, and ms packages to configure them accordingly. If you want different margins, you will need to use those pack‐ ages’ facilities, or troff ll and/or po requests to adjust them. An output device typically requires command‐line options -p and -l to override the paper dimensions and orientation, respec‐ tively, defined in its DESC file; see subsection “Paper format” of groff(1). This macro file is normally loaded at startup by the troffrc file when formatting for a typesetting device (but not a terminal). pdfpic provides a single macro, PDFPIC, to include a PDF graphic in a document using features of the pdf output driver. For other output devices, PDFPIC calls PSPIC, with which it shares an in‐ terface (see below). This macro file is normally loaded at startup by the troffrc file. pic supplies definitions of the macros PS, PE, and PF, usable with the pic(1) preprocessor. They center each picture. Use it if your document does not use a full‐service macro package, or that package does not supply working pic macro definitions. Except for man and mdoc, those provided with groff already do so (ex‐ ception: mm employs the name PF for a different purpose). pspic provides a macro, PSPIC, that includes a PostScript graphic in a document. The ps, dvi, html, and xhtml output devices support such inclusions; for all other drivers, the image is replaced with a rectangular border of the same size. pspic.tmac is loaded at startup by the troffrc file. Its syntax is as follows. .PSPIC [-L|-R|-C|-I n] file [width [height]] file is the name of the PostScript file; width and height give the desired width and height of the image. If neither a width nor a height argument is specified, the image’s natural width (as given in the file’s bounding box) or the current line length is used as the width, whatever is smaller. The width and height arguments may have scaling units attached; the default scaling unit is i. PSPIC scales the graphic uniformly in the horizontal and vertical directions so that it is no more than width wide and height high. Option -C centers the graphic horizontally; this is the default. -L and -R left‐ and right‐align the graphic, respectively. -I indents the graphic by n (with a de‐ fault scaling unit of m). To use PSPIC within a diversion, we recommend extending it with the following code, assuring that the diversion’s width com‐ pletely covers the image’s width. .am PSPIC . vpt 0 \h'(\\n[ps-offset]u + \\n[ps-deswid]u)' . sp -1 . vpt 1 .. Failure to load PSPIC’s image argument is not an error. (The psbb request does issue an error diagnostic.) To make such a failure fatal, append to the pspic*error-hook macro. .am pspic*error-hook . ab .. ptx provides a macro, xx, to format permuted index entries as pro‐ duced by the GNU ptx(1) program. If your formatting needs dif‐ fer, copy the macro into your document and adapt it to your needs. rfc1345 defines special character escape sequences named for the glyph mnemonics specified in RFC 1345 and the digraph table of the Vim text editor. See groff_rfc1345(7). sboxes offers an interface to the “pdf: background” device control com‐ mand supported by gropdf(1). Using this package, groff ms docu‐ ments can draw colored rectangles beneath any output. .BOXSTART SHADED color OUTLINED color INDENT size WEIGHT size begins a box, where the argument after SHADED gives the fill color and that after OUTLINED the border color. Omit the former to get a borderless filled box and the latter for a border with no fill. The specified WEIGHT is used if the box is OUTLINED. INDENT precedes a value which leaves a gap between the border and the contents inside the box. Each color must be a defined groff color name, and each size a valid groff numeric expression. The keyword/value pairs can be specified in any order. Boxes can be stacked, so you can start a box within another box; usually the later boxes would be smaller than the containing box, but this is not enforced. When using BOXSTART, the left position is the current indent minus the INDENT in the command, and the right position is the left position (calculated above) plus the current line length and twice the indent. .BOXSTOP takes no parameters. It closes the most recently started box at the current vertical position after adding its INDENT spacing. Your groff documents can conditionally exercise the sboxes macros. The register GSBOX is defined if the package is loaded, and interpolates a true value if the pdf output device is in use. sboxes furthermore hooks into the groff_ms(7) package to receive notifications when footnotes are growing, so that it can close boxes on a page before footnotes are printed. When that condi‐ tion obtains, sboxes will close open boxes two points above the footnote separator and re‐open them on the next page. (This amount probably will not match the box’s INDENT.) See “Using PDF boxes with groff and the ms macros” ⟨file:///usr/ local/share/doc/groff-1.23.0/msboxes.pdf⟩ for a demonstration. trace aids the debugging of groff documents by tracing macro calls. See groff_trace(7). www defines macros corresponding to HTML elements. See groff_www(7). Naming AT&T nroff and troff were implemented before the conventions of the modern C getopt(3) call evolved, and used a naming scheme for macro packages that looks odd to modern eyes. Macro packages were typically loaded using the -m option to the formatter; when directly followed by its argument without an intervening space, this looked like a long op‐ tion preceded by a single minus—a sensation in the computer stone age. Macro packages therefore came to be known by names that started with the letter “m”, which was omitted from the name of the macro file as stored on disk. For example, the manuscript macro package was stored as tmac.s and loaded with the option -ms. groff commands permit space between an option and its argument. The syntax “groff -m s” makes the macro file name more clear but may sur‐ prise users familiar with the original convention, unaware that the package’s “real” name was “s” all along. For such packages of long pedigree, groff accommodates different users’ expectations by supplying wrapper macro files that load the desired file with mso requests. Thus, all of “groff -m s”, “groff -m ms”, “groff -ms”, and “groff -mms” serve to load the manuscript macros. Wrappers are not provided for packages of more recent vintage, like www.tmac. As noted in passing above, AT&T troff named macro files in the form tmac.name. It has since become conventional in operating systems to use a suffixed file name extension to suggest a file type or format. Inclusion The traditional method of employing a macro package is to specify the -m package option to the formatter, which then reads package’s macro file prior to any input files. Historically, package was sought in a file named tmac.package (that is, with a “tmac.” prefix). GNU troff searches for package.tmac in the macro path; if not found, it looks for tmac.package instead, and vice versa. Alternatively, one could include a macro file by using the request “.so file‐name” in the document; file‐name is resolved relative to the loca‐ tion of the input document. GNU troff offers an improved feature in the similar request “mso package‐file‐name”, which searches the macro path for package‐file‐name. Because its argument is a file name, its “.tmac” component must be included for the file to be found; however, as a convenience, if opening it fails, mso strips any such suffix and tries again with a “tmac.” prefix, and vice versa. If a sourced file requires preprocessing, for example if it includes tbl tables or eqn equations, the preprocessor soelim(1) must be used. This can be achieved with a pipeline or, in groff, by specifying the -s option to the formatter (or front end). man(1) librarian programs gen‐ erally call soelim automatically. (Macro packages themselves generally do not require preprocessing.) Writing macros A roff(7) document is a text file that is enriched by predefined for‐ matting constructs, such as requests, escape sequences, strings, nu‐ meric registers, and macros from a macro package. These elements are described in roff(7). To give a document a personal style, it is most useful to extend the existing elements by defining some macros for repeating tasks; the best place for this is near the beginning of the document or in a separate file. Macros without arguments are just like strings. But the full power of macros occurs when arguments are passed with a macro call. Within the macro definition, the arguments are available as the escape sequences \$1, ..., \$9, \$[...], \$*, and \$@, the name under which the macro was called is in \$0, and the number of arguments is in register \n[.$]; see groff(7). Draft mode Writing groff macros is easy when the escaping mechanism is temporarily disabled. In groff, this is done by enclosing the macro definition(s) within a pair of .eo and .ec requests. Then the body in the macro def‐ inition is just like a normal part of the document — text enhanced by calls of requests, macros, strings, registers, etc. For example, the code above can be written in a simpler way by .eo .ds midpart was called with the following .de print_args \f[I]\$0\f[] \*[midpart] \n[.$] arguments: \$* .. .ec Unfortunately, draft mode cannot be used universally. Although it is good enough for defining normal macros, draft mode fails with advanced applications, such as indirectly defined strings, registers, etc. An optimal way is to define and test all macros in draft mode and then do the backslash doubling as a final step; do not forget to remove the .eo request. Tips for macro definitions • Start every line with a dot, for example, by using the groff re‐ quest .nop for text lines, or write your own macro that handles also text lines with a leading dot. .de Text . if (\\n[.$] == 0) \ . return . nop \)\\$*\) .. • Write a comment macro that works both for copy and draft modes; since the escape character is off in draft mode, trouble might occur when comment escape sequences are used. For example, the following macro just ignores its arguments, so it acts like a comment line: .de c .. .c This is like a comment line. • In long macro definitions, make ample use of comment lines or almost‐empty lines (this is, lines which have a leading dot and nothing else) for a better structuring. • To increase readability, use groff’s indentation facility for requests and macro calls (arbitrary whitespace after the leading dot). Diversions Diversions can be used to implement quite advanced programming con‐ structs. They are comparable to pointers to large data structures in the C programming language, but their usage is quite different. In their simplest form, diversions are multi‐line strings, but diver‐ sions get their power when used dynamically within macros. The (for‐ matted) information stored in a diversion can be retrieved by calling the diversion just like a macro. Most of the problems arising with diversions can be avoided if you re‐ member that diversions always store complete lines. Using diversions when the line buffer has not been flushed produces strange results; not knowing this, many people get desperate about diversions. To ensure that a diversion works, add line breaks at the right places. To be safe, enclose everything that has to do with diversions within a pair of line breaks; for example, by explicitly using .br requests. This rule should be applied to diversion definition, both inside and out‐ side, and to all calls of diversions. This is a bit of overkill, but it works nicely. (If you really need diversions which should ignore the current partial line, use environments to save the current partial line and/or use the .box request.) The most powerful feature using diversions is to start a diversion within a macro definition and end it within another macro. Then every‐ thing between each call of this macro pair is stored within the diver‐ sion and can be manipulated from within the macros. Authors This document was written by Bernd Warken ⟨groff-bernd.warken-72@web .de⟩, Werner Lemberg ⟨wl@gnu.org⟩, and G. Branden Robinson ⟨g.branden .robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. The Filesystem Hierarchy Standard ⟨https://wiki.linuxfoundation.org/ lsb/fhs⟩ is maintained by the Linux Foundation. groff(1) is an overview of the groff system. groff_man(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mom(7), groff_ms(7), groff_rfc1345(7), groff_trace(7), and groff_www(7) are groff macro packages. groff(7) summarizes the language recognized by GNU troff. troff(1) documents the default macro file search path. groff 1.23.0 29 August 2023 groff_tmac(5) ─────────────────────────────────────────────────────────────────────────────── groff(7) Miscellaneous Information Manual groff(7) Name groff - GNU roff language reference Description groff is short for GNU roff, a free reimplementation of the AT&T de‐ vice‐independent troff typesetting system. See roff(7) for a survey of and background on roff systems. This document is intended as a reference. The primary groff manual, Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is a better resource for learners, containing many examples and much discussion. It is written in Texinfo; you can browse it in‐ teractively with “info groff”. Additional formats, including plain text, HTML, DVI, and PDF, may be available in /usr/local/share/doc/ groff-1.23.0. groff is also a name for an extended dialect of the roff language. We use “roff” to denote features that are universal, or nearly so, among implementations of this family. We apply the term “groff” to the lan‐ guage documented here, the GNU implementation of the overall system, the project that develops that system, and the command of that name. GNU troff, installed on this system as troff(1), is the formatter: a program that reads device and font descriptions (groff_font(5)), inter‐ prets the groff language expressed in text input files, and translates that input into a device‐independent output format (groff_out(5)) that is usually then post‐processed by an output driver to produce Post‐ Script, PDF, HTML, DVI, or terminal output. Input format Input to GNU troff is organized into lines separated by the Unix new‐ line character (U+000A), and must be in one of two character encodings it can recognize: IBM code page 1047 on EBCDIC systems, and ISO Latin‐1 (8859‐1) otherwise. Use of ISO 646‐1991:IRV (“US‐ASCII”) or (equiva‐ lently) the “Basic Latin” subset of ISO 10646 (“Unicode”) is recom‐ mended; see groff_char(7). The preconv(1) preprocessor transforms other encodings, including UTF‐8, to satisfy troff’s requirements. Syntax characters Several input characters are syntactically significant to groff. . A dot at the beginning of an input line marks it as a control line. It can also follow the .el and .nop requests, and the condition in .if, .ie, and .while requests. The control character invokes re‐ quests and calls macros by the name that follows it. The .cc re‐ quest can change the control character. ' The neutral apostrophe is the no‐break control character, recog‐ nized where the control character is. It suppresses the (first) break implied by the .bp, .cf, .fi, .fl, .in, .nf, .rj, .sp, .ti, and .trf requests. The requested operation takes effect at the next break. It makes .br nilpotent. The no‐break control charac‐ ter can be changed with the .c2 request. When formatted, “'” may be typeset as a typographical quotation mark; use the \[aq] special character escape sequence to format a neutral apostrophe glyph. " The neutral double quote can be used to enclose arguments to macros and strings, and is required if those arguments contain space or tab characters. In the .ds, .ds1, .as, and .as1 requests, an ini‐ tial neutral double quote in the second argument is stripped off to allow embedding of leading spaces. To include a double quote in‐ side a quoted argument, use the \[dq] special character escape se‐ quence (which also serves to typeset the glyph in text). \ A backslash introduces an escape sequence. The escape character can be changed with the .ec request; .eo disables escape sequence recognition. Use the \[rs] special character escape sequence to format a backslash glyph, and \e to typeset the glyph of the cur‐ rent escape character. ( An opening parenthesis is special only in certain escape sequences; when recognized, it introduces an argument of exactly two charac‐ ters. groff offers the more flexible square bracket syntax. [ An opening bracket is special only in certain escape sequences; when recognized, it introduces an argument (list) of any length, not including a closing bracket. ] A closing bracket is special only when an escape sequence using an opening bracket as an argument delimiter is being interpreted. It ends the argument (list). Additionally, the Control+A character (U+0001) in text is interpreted as a leader (see below). Horizontal white space characters are significant to groff, but trail‐ ing spaces on text lines are ignored. space Space characters separate arguments in request invocations, macro calls, and string interpolations. In text, they separate words. Multiple adjacent space characters in text cause groff to attempt end‐of‐sentence detection on the preceding word (and trailing punctuation). The amount of space between words and sentences is controlled by the .ss request. When filling is enabled (the default), a line may be broken at a space. When adjustment is enabled (the default), inter‐word spaces are ex‐ panded until the output line reaches the configured length. An adjustable but non‐breaking space is available with \~. To get a space of fixed width, use one of the escape sequences ‘\ ’ (the escape character followed by a space), \0, \|, \^, or \h; see section “Escape sequences” below. newline In text, a newline puts an inter‐word space onto the output and, if filling is enabled, triggers end‐of‐sentence recogni‐ tion on the preceding text. See section “Line continuation” below. tab A tab character in text causes the drawing position to advance to the next defined tab stop. Tabs and leaders The formatter interprets input horizontal tab characters (“tabs”) and Control+A characters (“leaders”) into movements to the next tab stop. Tabs simply move to the next tab stop; leaders place enough periods to fill the space. Tab stops are by default located every half inch mea‐ sured from the drawing position corresponding to the beginning of the input line; see section “Page geometry” of roff(7). Tabs and leaders do not cause breaks and therefore do not interrupt filling. Tab stops can be configured with the ta request, and tab and leader glyphs with the tc and lc requests, respectively. Line continuation When filling is enabled, input and output line breaks generally do not correspond. The roff language therefore distinguishes input and output line continuation. A backslash \ immediately followed by a newline, sometimes discussed as \newline, suppresses the effects of that newline on the input. The next input line thus retains the classification of its predecessor as a control or text line. \newline is useful for managing line lengths in the input during document maintenance; you can break an input line in the middle of a request invocation, macro call, or escape sequence. Input line continuation is invisible to the formatter, with two excep‐ tions: the | operator recognizes the new input line, and the input line counter register .c is incremented. The \c escape sequence continues an output line. Nothing on the input line after it is formatted. In contrast to \newline, a line after \c is treated as a new input line, so a control character is recognized at its beginning. The visual results depend on whether filling is en‐ abled. An intervening control line that causes a break overrides \c, flushing out the pending output line in the usual way. The register .int contains a positive value if the last output line was continued with \c; this datum is associated with the environment. Colors groff supports color output with a variety of color spaces and up to 16 bits per channel. Some devices, particularly terminals, may be more limited. When color support is enabled, two colors are current at any given time: the stroke color, with which glyphs, rules (lines), and geometric objects like circles and polygons are drawn, and the fill color, which can be used to paint the interior of a closed geometric figure. The color, defcolor, gcolor, and fcolor requests; \m and \M escape sequences; and .color, .m, and .M registers exercise color sup‐ port. Each output device has a color named “default”, which cannot be rede‐ fined. A device’s default stroke and fill colors are not necessarily the same. For the dvi, html, pdf, ps, and xhtml output devices, troff automatically loads a macro file defining many color names at startup. By the same mechanism, the devices supported by grotty(1) recognize the eight standard ISO 6429/ECMA‐48 color names (also known vulgarly as “ANSI colors”). Measurements Numeric parameters that specify measurements are expressed as integers or decimal fractions with an optional scaling unit suffixed. A scaling unit is a letter that immediately follows the last digit of a number. Digits after the decimal point are optional. Measurements are scaled by the scaling unit and stored internally (with any fractional part discarded) in basic units. The device resolution can therefore be obtained by storing a value of “1i” to a register. The only constraint on the basic unit is that it is at least as small as any other unit. u Basic unit. i Inch; defined as 2.54 centimeters. c Centimeter. p Point; a typesetter’s unit used for measuring type size. There are 72 points to an inch. P Pica; another typesetter’s unit. There are 6 picas to an inch and 12 points to a pica. s, z Scaled points and multiplication by the output device’s sizescale parameter, respectively. f Multiplication by 65,536; scales decimal fractions in the inter‐ val [0, 1] to 16‐bit unsigned integers. The magnitudes of other scaling units depend on the text formatting pa‐ rameters in effect. m Em; an em is equal to the current type size in points. n En; an en is one‐half em. v Vee; distance between text baselines. M Hundredth of an em. Motion quanta An output device’s basic unit u is not necessarily its smallest ad‐ dressable length; u can be smaller to avoid problems with integer roundoff. The minimum distances that a device can work with in the horizontal and vertical directions are termed its motion quanta, stored in the .H and .V registers, respectively. Measurements are rounded to applicable motion quanta. Half‐quantum fractions round toward zero. Default units A general‐purpose register (one created or updated with the nr request; see section “Registers” below) is implicitly dimensionless, or reckoned in basic units if interpreted in a measurement context. But it is con‐ venient for many requests and escape sequences to infer a scaling unit for an argument if none is specified. An explicit scaling unit (not after a closing parenthesis) can override an undesirable default. Ef‐ fectively, the default unit is suffixed to the expression if a scaling unit is not already present. GNU troff’s use of integer arithmetic should also be kept in mind; see below. Numeric expressions A numeric expression evaluates to an integer. The following operators are recognized. + addition - subtraction * multiplication / truncating division % modulus ──────────────────────────────────────────── unary + assertion, motion, incrementation unary - negation, motion, decrementation ──────────────────────────────────────────── ; scaling >? maximum greater than <= less than or equal >= greater than or equal = equal == equal ──────────────────────────────────────────── & logical conjunction (“and”) : logical disjunction (“or”) ! logical complementation (“not”) ──────────────────────────────────────────── ( ) precedence ──────────────────────────────────────────── | boundary‐relative motion troff provides a set of mathematical and logical operators familiar to programmers—as well as some unusual ones—but supports only integer arithmetic. (Provision is made for interpreting and reporting decimal fractions in certain cases.) The internal data type used for computing results is usually a 32‐bit signed integer, which suffices to represent magnitudes within a range of ±2 billion. (If that’s not enough, see groff_tmac(5) for the 62bit.tmac macro package.) Arithmetic infix operators perform a function on the numeric expres‐ sions to their left and right; they are + (addition), - (subtraction), * (multiplication), / (truncating division), and % (modulus). Truncat‐ ing division rounds to the integer nearer to zero, no matter how large the fractional portion. Overflow and division (or modulus) by zero are errors and abort evaluation of a numeric expression. Arithmetic unary operators operate on the numeric expression to their right; they are - (negation) and + (assertion—for completeness; it does nothing). The unary minus must often be used with parentheses to avoid confusion with the decrementation operator, discussed below. The sign of the modulus of operands of mixed signs is determined by the sign of the first. Division and modulus operators satisfy the follow‐ ing property: given a dividend a and a divisor b, a quotient q formed by “(a / b)” and a remainder r by “(a % b)”, then qb + r = a. GNU troff’s scaling operator, used with parentheses as (c;e), evaluates a numeric expression e using c as the default scaling unit. If c is omitted, scaling units are ignored in the evaluation of e. GNU troff also provides a pair of operators to compute the extrema of two operands: >? (maximum) and  (greater than), <= (less than or equal), >= (greater than or equal), and = (equal). == is a synonym for =. When evaluated, a comparison is replaced with “0” if it is false and “1” if true. In the roff language, positive values are true, others false. We can operate on truth values with the logical operators & (logical conjunction or “and”) and : (logical disjunction or “or”). They evalu‐ ate as comparison operators do. A logical complementation (“not”) op‐ erator, !, works only within “if”, “ie”, and “while” requests. Fur‐ thermore, ! is recognized only at the beginning of a numeric expression not contained by another numeric expression. In other words, it must be the “outermost” operator. Including it elsewhere in the expression produces a warning in the “number” category (see troff(1)), and its ex‐ pression evaluates false. This unfortunate limitation maintains com‐ patibility with AT&T troff. Test a numeric expression for falsity by comparing it to a false value. The roff language has no operator precedence: expressions are evaluated strictly from left to right, in contrast to schoolhouse arithmetic. Use parentheses ( ) to impose a desired precedence upon subexpressions. For many requests and escape sequences that cause motion on the page, the unary operators + and - work differently when leading a numeric ex‐ pression. They then indicate a motion relative to the drawing posi‐ tion: positive is down in vertical contexts, right in horizontal ones. + and - are also treated differently by the following requests and es‐ cape sequences: bp, in, ll, pl, pn, po, ps, pvs, rt, ti, \H, \R, and \s. Here, leading plus and minus signs serve as incrementation and decrementation operators, respectively. To negate an expression, sub‐ tract it from zero or include the unary minus in parentheses with its argument. A leading | operator indicates a motion relative not to the drawing po‐ sition but to a boundary. For horizontal motions, the measurement specifies a distance relative to a drawing position corresponding to the beginning of the input line. By default, tab stops reckon move‐ ments in this way. Most escape sequences do not; | tells them to do so. For vertical motions, the | operator specifies a distance from the first text baseline on the page or in the current diversion, using the current vertical spacing. The \B escape sequence tests its argument for validity as a numeric ex‐ pression. A register interpolated as an operand in a numeric expression must have an Arabic format; luckily, this is the default. Due to the way arguments are parsed, spaces are not allowed in numeric expressions unless the (sub)expression containing them is surrounded by parentheses. Identifiers An identifier labels a GNU troff datum such as a register, name (macro, string, or diversion), typeface, color, special character, character class, environment, or stream. Valid identifiers consist of one or more ordinary characters. An ordinary character is an input character that is not the escape character, a leader, tab, newline, or invalid as GNU troff input. Invalid input characters are subset of control characters (from the sets “C0 Controls” and “C1 Controls” as Unicode describes them). When troff encounters one in an identifier, it produces a warning in cate‐ gory “input” (see section “Warnings” in troff(1)). They are removed during interpretation: an identifier “foo”, followed by an invalid character and then “bar”, is processed as “foobar”. On a machine using the ISO 646, 8859, or 10646 character encodings, in‐ valid input characters are 0x00, 0x08, 0x0B, 0x0D–0x1F, and 0x80–0x9F. On an EBCDIC host, they are 0x00–0x01, 0x08, 0x09, 0x0B, 0x0D–0x14, 0x17–0x1F, and 0x30–0x3F. Some of these code points are used by troff internally, making it non‐trivial to extend the program to accept UTF‐8 or other encodings that use characters from these ranges. An identifier with a closing bracket (“]”) in its name can’t be ac‐ cessed with bracket‐form escape sequences that expect an identifier as a parameter. Similarly, the identifier “(” can’t be interpolated ex‐ cept with bracket forms. If you begin a macro, string, or diversion name with either of the characters “[” or “]”, you foreclose use of the refer(1) preprocessor, which recognizes “.[” and “.]” as bibliographic reference delimiters. The escape sequence \A tests its argument for validity as an identi‐ fier. How GNU troff handles the interpretation of an undefined identifier de‐ pends on the context. There is no way to invoke an undefined request; such syntax is interpreted as a macro call instead. If the identifier is interpreted as a string, macro, or diversion, troff emits a warning in category “mac”, defines it as empty, and interpolates nothing. If the identifier is interpreted as a register, troff emits a warning in category “reg”, initializes it to zero, and interpolates that value. See section “Warnings” in troff(1), and subsection “Interpolating reg‐ isters” and section “Strings” below. Attempting to use an undefined typeface, style, special character, color, character class, environ‐ ment, or stream generally provokes an error diagnostic. Identifiers for requests, macros, strings, and diversions share one name space; special characters and character classes another. No other object types do. Control characters Control characters are recognized only at the beginning of an input line, or at the beginning of the branch of a control structure request; see section “Control structures” below. A few requests cause a break implicitly; use the no‐break control char‐ acter to prevent the break. Break suppression is its sole behavioral distinction. Employing the no‐break control character to invoke re‐ quests that don’t cause breaks is harmless but poor style. The control character “.” and the no‐break control character “'” can be changed with the cc and c2 requests, respectively. Within a macro def‐ inition, register .br indicates the control character used to call it. Invoking requests A control character is optionally followed by tabs and/or spaces and then an identifier naming a request or macro. The invocation of an un‐ recognized request is interpreted as a macro call. Defining a macro with the same name as a request replaces the request. Deleting a re‐ quest name with the rm request makes it unavailable. The als request can alias requests, permitting them to be wrapped or non‐destructively replaced. See section “Strings” below. There is no inherent limit on argument length or quantity. Most re‐ quests take one or more arguments, and ignore any they do not expect. A request may be separated from its arguments by tabs or spaces, but only spaces can separate an argument from its successor. Only one be‐ tween arguments is necessary; any excess is ignored. GNU troff does not allow tabs for argument separation. Generally, a space within a request argument is not relevant, not mean‐ ingful, or is supported by bespoke provisions, as with the tl request’s delimiters. Some requests, like ds, interpret the remainder of the control line as a single argument. See section “Strings” below. Spaces and tabs immediately after a control character are ignored. Commonly, authors structure the source of documents or macro files with them. Calling macros If a macro of the desired name does not exist when called, it is cre‐ ated, assigned an empty definition, and a warning in category “mac” is emitted. Calling an undefined macro does end a macro definition naming it as its end macro (see section “Writing macros” below). To embed spaces within a macro argument, enclose the argument in neu‐ tral double quotes ‘"’. Horizontal motion escape sequences are some‐ times a better choice for arguments to be formatted as text. The foregoing raises the question of how to embed neutral double quotes or backslashes in macro arguments when those characters are desired as literals. In GNU troff, the special character escape sequence \[rs] produces a backslash and \[dq] a neutral double quote. In GNU troff’s AT&T compatibility mode, these characters remain avail‐ able as \(rs and \(dq, respectively. AT&T troff did not consistently define these special characters, but its descendants can be made to support them. See groff_font(5). If even that is not feasible, see the “Calling Macros” section of the groff Texinfo manual for the com‐ plex macro argument quoting rules of AT&T troff. Using escape sequences Whereas requests must occur on control lines, escape sequences can oc‐ cur intermixed with text and may appear in arguments to requests, macros, and other escape sequences. An escape sequence is introduced by the escape character, a backslash \. The next character selects the escape’s function. Escape sequences vary in length. Some take an argument, and of those, some have different syntactical forms for a one‐character, two‐charac‐ ter, or arbitrary‐length argument. Others accept only an arbitrary‐ length argument. In the former scheme, a one‐character argument fol‐ lows the function character immediately, an opening parenthesis “(” in‐ troduces a two‐character argument (no closing parenthesis is used), and an argument of arbitrary length is enclosed in brackets “[]”. In the latter scheme, the user selects a delimiter character. A few escape sequences are idiosyncratic, and support both of the foregoing conven‐ tions (\s), designate their own termination sequence (\?), consume in‐ put until the next newline (\!, \", \#), or support an additional modi‐ fier character (\s again, and \n). If an escape character is followed by a character that does not iden‐ tify a defined operation, the escape character is ignored (producing a diagnostic of the “escape” warning category, which is not enabled by default) and the following character is processed normally. Escape sequence interpolation is of higher precedence than escape se‐ quence argument interpretation. This rule affords flexibility in using escape sequences to construct parameters to other escape sequences. The escape character can be interpolated (\e). Requests permit the es‐ cape mechanism to be deactivated (eo) and restored, or the escape char‐ acter changed (ec), and to save and restore it (ecs and ecr). Delimiters Some escape sequences that require parameters use delimiters. The neu‐ tral apostrophe ' is a popular choice and shown in this document. The neutral double quote " is also commonly seen. Letters, numerals, and leaders can be used. Punctuation characters are likely better choices, except for those defined as infix operators in numeric expressions; see below. The following escape sequences don’t take arguments and thus are al‐ lowed as delimiters: \space, \%, \|, \^, \{, \}, \', \`, \-, \_, \!, \?, \), \/, \,, \&, \:, \~, \0, \a, \c, \d, \e, \E, \p, \r, \t, and \u. However, using them this way is discouraged; they can make the input confusing to read. A few escape sequences, \A, \b, \o, \w, \X, and \Z, accept a newline as a delimiter. Newlines that serve as delimiters continue to be recog‐ nized as input line terminators. Use of newlines as delimiters in es‐ cape sequences is also discouraged. Finally, the escape sequences \D, \h, \H, \l, \L, \N, \R, \s, \S, \v, and \x prohibit many delimiters. • the numerals 0–9 and the decimal point “.” • the (single‐character) operators +-/*%<>=&:() • any escape sequences other than \%, \:, \{, \}, \', \`, \-, \_, \!, \/, \c, \e, and \p Delimiter syntax is complex and flexible primarily for historical rea‐ sons; the foregoing restrictions need be kept in mind mainly when using groff in AT&T compatibility mode. GNU troff keeps track of the nesting depth of escape sequence interpolations, so the only characters you need to avoid using as delimiters are those that appear in the argu‐ ments you input, not any that result from interpolation. Typically, ' works fine. See section “Implementation differences” in groff_diff(7). Dummy characters As discussed in roff(7), the first character on an input line is treated specially. Further, formatting a glyph has many consequences on formatter state (see section “Environments” below). Occasionally, we want to escape this context or embrace some of those consequences without actually rendering a glyph to the output. \& interpolates a dummy character, which is constitutive of output but invisible. Its presence alters the interpretation context of a subsequent input char‐ acter, and enjoys several applications: preventing the insertion of ex‐ tra space after an end‐of‐sentence character, preventing interpretation of a control character at the beginning of an input line, preventing kerning between two glyphs, and permitting the tr request to remap a character to “nothing”. \) works as \& does, except that it does not cancel a pending end‐of‐sentence state. Control structures groff has “if” and “while” control structures like other languages. However, the syntax for grouping multiple input lines in the branches or bodies of these structures is unusual. They have a common form: the request name is (except for .el “else”) followed by a conditional expression cond‐expr; the remainder of the line, anything, is interpreted as if it were an input line. Any quan‐ tity of spaces between arguments to requests serves only to separate them; leading spaces in anything are therefore not seen. anything ef‐ fectively cannot be omitted; if cond‐expr is true and anything is empty, the newline at the end of the control line is interpreted as a blank line (and therefore a blank text line). It is frequently desirable for a control structure to govern more than one request, macro call, or text line, or a combination of the forego‐ ing. The opening and closing brace escape sequences \{ and \} perform such grouping. Brace escape sequences outside of control structures have no meaning and produce no output. \{ should appear (after optional spaces and tabs) immediately subse‐ quent to the request’s conditional expression. \} should appear on a line with other occurrences of itself as necessary to match \{ se‐ quences. It can be preceded by a control character, spaces, and tabs. Input after any quantity of \} sequences on the same line is processed only if all the preceding conditions to which they correspond are true. Furthermore, a \} closing the body of a .while request must be the last such escape sequence on an input line. Conditional expressions The .if, .ie, and .while requests test the truth values of numeric ex‐ pressions. They also support several additional Boolean operators; the members of this expanded class are termed conditional expressions; their truth values are as shown below. cond‐expr... ...is true if... ──────────────────────────────────────────────────────────────────────── 's1's2' s1 produces the same formatted output as s2. c g a glyph g is available. d m a string, macro, diversion, or request m is defined. e the current page number is even. F f a font named f is available. m c a color named c is defined. n the formatter is in nroff mode. o the current page number is odd. r n a register named n is defined. S s a font style named s is available. t the formatter is in troff mode. v n/a (historical artifact; always false). If the first argument to an .if, .ie, or .while request begins with a non‐alphanumeric character apart from ! (see below); it performs an output comparison test. Shown first in the table above, the output comparison operator interpolates a true value if formatting its com‐ parands s1 and s2 produces the same output commands. Other delimiters can be used in place of the neutral apostrophes. troff formats s1 and s2 in separate environments; after the comparison, the resulting data are discarded. The resulting glyph properties, including font family, style, size, and slant, must match, but not necessarily the requests and/or escape sequences used to obtain them. Motions must match in orientation and magnitude to within the applicable horizontal or verti‐ cal motion quantum of the device, after rounding. Surround the comparands with \? to avoid formatting them; this causes them to be compared character by character, as with string comparisons in other programming languages. Since comparands protected with \? are read in copy mode, they need not even be valid groff syntax. The es‐ cape character is still lexically recognized, however, and consumes the next character. The above operators can’t be combined with most others, but a leading “!”, not followed immediately by spaces or tabs, complements an expres‐ sion. Spaces and tabs are optional immediately after the “c”, “d”, “F”, “m”, “r”, and “S” operators, but right after “!”, they end the predicate and the conditional evaluates true. (This bizarre behavior maintains compatibility with AT&T troff.) Syntax reference conventions In the following request and escape sequence specifications, most argu‐ ment names were chosen to be descriptive. A few denotations may re‐ quire introduction. c denotes a single input character. font a font either specified as a font name or a numeric mounting position. anything all characters up to the end of the line, to the end‐ ing delimiter for the escape sequence, or within \{ and \}. Escape sequences may generally be used freely in anything, except when it is read in copy mode. message is a character sequence to be emitted on the standard error stream. Special character escape sequences are not interpreted. n is a numeric expression that evaluates to a non‐nega‐ tive integer. npl is a numeric expression constituting a count of subse‐ quent productive input lines; that is, those that di‐ rectly produce formatted output. Text lines produce output, as do control lines containing requests like .tl or escape sequences like \D. Macro calls are not themselves productive, but their interpolated contents can be. ±N is a numeric expression with a meaning dependent on its sign. If a numeric expression presented as ±N starts with a ‘+’ sign, an in‐ crement in the amount of of N is applied to the value applicable to the request or escape sequence. If it starts with a ‘-’ sign, a decrement of magnitude N is applied instead. Without a sign, N replaces any ex‐ isting value. A leading minus sign in N is always interpreted as a decrementation operator, not an algebraic sign. To assign a register a negative value or the negated value of another register, enclose it with its operand in parentheses or subtract it from zero. If a prior value does not exist (the register was undefined), an increment or decrement is applied as if to 0. Request short reference Not all details of request behavior are outlined here. See the groff Texinfo manual or, for features new to GNU troff, groff_diff(7). .ab Abort processing; exit with failure status. .ab message Abort processing; write message to the standard error stream and exit with failure status. .ad Enable output line alignment and adjustment using the mode stored in \n[.j]. .ad c Enable output line alignment and adjustment in mode c (c=b,c,l,n,r). Sets \n[.j]. .af register c Assign format c to register, where c is “i”, “I”, “a”, “A”, or a sequence of decimal digits whose quantity denotes the minimum width in digits to be used when the register is in‐ terpolated. “i” and “a” indicate Roman numerals and basic Latin alphabetics, respectively, in the lettercase specified. The default is 0. .aln new old Create alias (additional name) new for existing register named old. .als new old Create alias (additional name) new for existing request, string, macro, or diversion old. .am macro Append to macro until .. is encountered. .am macro end Append to macro until .end is called. .am1 macro Same as .am but with compatibility mode switched off during macro expansion. .am1 macro end Same as .am but with compatibility mode switched off during macro expansion. .ami macro Append to a macro whose name is contained in the string macro until .. is encountered. .ami macro end Append to a macro indirectly. macro and end are strings whose contents are interpolated for the macro name and the end macro, respectively. .ami1 macro Same as .ami but with compatibility mode switched off during macro expansion. .ami1 macro end Same as .ami but with compatibility mode switched off during macro expansion. .as name Create string name with empty contents; no operation if name already exists. .as name contents Append contents to string name. .as1 string .as1 string contents As .as, but with compatibility mode disabled when contents interpolated. .asciify diversion Unformat ASCII characters, spaces, and some escape sequences in diversion. .backtrace Write the state of the input stack to the standard error stream. See the -b option of groff(1). .bd font Stop emboldening font font. .bd font n Embolden font by overstriking its glyphs offset by n-1 units. See register .b. .bd special‐font font Stop emboldening special‐font when font is selected. .bd special‐font font n Embolden special‐font, overstriking its glyphs offset by n-1 units when font is selected. See register .b. .blm Unset blank line macro (trap). Restore default handling of blank lines. .blm name Set blank line macro (trap) to name. .box Stop directing output to current diversion; any pending out‐ put line is discarded. .box name Direct output to diversion name, omitting a partially col‐ lected line. .boxa Stop appending output to current diversion; any pending out‐ put line is discarded. .boxa name Append output to diversion name, omitting a partially col‐ lected line. .bp Break page and start a new one. .bp ±N Break page, starting a new one numbered ±N. .br Break output line. .brp Break output line; adjust if applicable. .break Break out of a while loop. .c2 Reset no‐break control character to “'”. .c2 o Recognize ordinary character o as no‐break control character. .cc Reset control character to ‘.’. .cc o Recognize ordinary character o as the control character. .ce Break, center the output of the next productive input line without filling, and break again. .ce npl Break, center the output of the next npl productive input lines without filling, then break again. If npl ≤ 0, stop centering. .cf file Copy contents of file without formatting to the (top‐level) diversion. .cflags n c1 c2 ... Assign properties encoded by n to characters c1, c2, and so on. .ch name Unplant page location trap name. .ch name vpos Change page location trap name planted by .wh by moving its location to vpos (default scaling unit v). .char c contents Define ordinary or special character c as contents. .chop object Remove the last character from the macro, string, or diver‐ sion named object. .class name c1 c2 ... Define a (character) class name comprising the characters or range expressions c1, c2, and so on. .close stream Close the stream. .color Enable output of color‐related device‐independent output com‐ mands. .color n If n is zero, disable output of color‐related device‐indepen‐ dent output commands; otherwise, enable them. .composite from to Map glyph name from to glyph name to while constructing a composite glyph name. .continue Finish the current iteration of a while loop. .cp Enable compatibility mode. .cp n If n is zero, disable compatibility mode, otherwise enable it. .cs font n m Set constant character width mode for font to n/36 ems with em m. .cu Continuously underline the output of the next productive in‐ put line. .cu npl Continuously underline the output of the next npl productive input lines. If npl=0, stop continuously underlining. .da Stop appending output to current diversion. .da name Append output to diversion name. .de macro Define or redefine macro until “..” occurs at the start of a control line in the current conditional block. .de macro end Define or redefine macro until end is invoked or called at the start of a control line in the current conditional block. .de1 macro As .de, but disable compatibility mode during macro expan‐ sion. .de1 macro end As “.de macro end”, but disable compatibility mode during macro expansion. .defcolor ident scheme color‐component ... Define a color named ident. scheme identifies a color space and determines the number of required color‐components; it must be one of “rgb” (three components), “cmy” (three), “cmyk” (four), or “gray” (one). “grey” is accepted as a syn‐ onym of “gray”. The color components can be encoded as a single hexadecimal value starting with # or ##. The former indicates that each component is in the range 0–255 (0–FF), the latter the range 0–65,535 (0–FFFF). Alternatively, each color component can be specified as a decimal fraction in the range 0–1, interpreted using a default scaling unit of “f”, which multiplies its value by 65,536 (but clamps it at 65,535). Each output device has a color named “default”, which cannot be redefined. A device’s default stroke and fill colors are not necessarily the same. .dei macro Define macro indirectly. As .de, but use interpolation of string macro as the name of the defined macro. .dei macro end Define macro indirectly. As .de, but use interpolations of strings macro and end as the names of the defined and end macros. .dei1 macro As .dei, but disable compatibility mode during macro expan‐ sion. .dei1 macro end As .dei macro end, but disable compatibility mode during macro expansion. .device anything Write anything, read in copy mode, to troff output as a de‐ vice control command. An initial neutral double quote is stripped to allow embedding of leading spaces. .devicem name Write contents of macro or string name to troff output as a device control command. .di Stop directing output to current diversion. .di name Direct output to diversion name. .do name ... Interpret the string, request, diversion, or macro name (along with any arguments) with compatibility mode disabled. Compatibility mode is restored (only if it was active) when the expansion of name is interpreted. .ds name Create empty string name. .ds name contents Create a string name containing contents. .ds1 name .ds1 name contents As .ds, but with compatibility mode disabled when contents interpolated. .dt Clear diversion trap. .dt vertical‐position name Set the diversion trap to macro name at vertical‐position (default scaling unit v). .ec Recognize \ as the escape character. .ec o Recognize ordinary character o as the escape character. .ecr Restore escape character saved with .ecs. .ecs Save the escape character. .el anything Interpret anything as if it were an input line if the condi‐ tional expression of the corresponding .ie request was false. .em name Call macro name after the end of input. .eo Disable the escape mechanism in interpretation mode. .ev Pop environment stack, returning to previous one. .ev env Push current environment onto stack and switch to env. .evc env Copy environment env to the current one. .ex Exit with successful status. .fam Set default font family to previous value. .fam name Set default font family to name. .fc Disable field mechanism. .fc a Set field delimiter to a and pad glyph to space. .fc a b Set field delimiter to a and pad glyph to b. .fchar c contents Define fallback character (or glyph) c as contents. .fcolor Restore previous fill color. .fcolor c Set fill color to c. .fi Enable filling of output lines; a pending output line is bro‐ ken. Sets \n[.u]. .fl Flush output buffer. .fp pos id Mount font with font description file name id at non‐negative position n. .fp pos id font‐description‐file‐name Mount font with font‐description‐file‐name as name id at non‐ negative position n. .fschar f c anything Define fallback character (or glyph) c for font f as string anything. .fspecial font Reset list of special fonts for font to be empty. .fspecial font s1 s2 ... When the current font is font, then the fonts s1, s2, ... are special. .ft .ft P Select previous font mounting position (abstract style or font); same as \f[] or \fP. .ft font Select typeface font, which can be a mounting position, ab‐ stract style, or font name; same as \f[font] escape sequence. font cannot be P. .ftr font1 font2 Translate font1 to font2. .fzoom font .fzoom font 0 Stop magnifying font. .fzoom font z Set zoom factor for font to z (in thousandths; default: 1000). .gcolor Restore previous stroke color. .gcolor c Set stroke color to c. .hc Reset the hyphenation character to \% (the default). .hc char Change the hyphenation character to char. .hcode c1 code1 [c2 code2] ... Set the hyphenation code of character c1 to code1, that of c2 to code2, and so on. .hla lang Set the hyphenation language to lang. .hlm n Set the maximum quantity of consecutive hyphenated lines to n. .hpf pattern‐file Read hyphenation patterns from pattern‐file. .hpfa pattern‐file Append hyphenation patterns from pattern‐file. .hpfcode a b [c d] ... Define mappings for character codes in hyphenation pattern files read with .hpf and .hpfa. .hw word ... Define hyphenation overrides for each word; a hyphen “-” in‐ dicates a hyphenation point. .hy Set automatic hyphenation mode to 1. .hy 0 Disable automatic hyphenation; same as .nh. .hy mode Set automatic hyphenation mode to mode; see section “Hyphen‐ ation” below. .hym Set the (right) hyphenation margin to 0 (the default). .hym length Set the (right) hyphenation margin to length (default scaling unit m). .hys Set the hyphenation space to 0 (the default). .hys hyphenation‐space Suppress automatic hyphenation in adjustment modes “b” or “n” if the line can be justified with the addition of up to hy‐ phenation‐space to each inter‐word space (default scaling unit m). .ie cond‐expr anything If cond‐expr is true, interpret anything as if it were an in‐ put line, otherwise skip to a corresponding .el request. .if cond‐expr anything If cond‐expr is true, then interpret anything as if it were an input line. .ig Ignore input (except for side effects of \R on auto‐incre‐ menting registers) until “..” occurs at the start of a con‐ trol line in the current conditional block. .ig end Ignore input (except for side effects of \R on auto‐incre‐ menting registers) until .end is called at the start of a control line in the current conditional block. .in Set indentation amount to previous value. .in ±N Set indentation to ±N (default scaling unit m). .it Cancel any pending input line trap. .it npl name Set (or replace) an input line trap in the environment, call‐ ing macro name, after the next npl productive input lines have been read. Lines interrupted with the \c escape se‐ quence are counted separately. .itc Cancel any pending input line trap. .itc npl name As .it, except that input lines interrupted with the \c es‐ cape sequence are not counted. .kern Enable pairwise kerning. .kern n If n is zero, disable pairwise kerning, otherwise enable it. .lc Unset leader repetition character. .lc c Set leader repetition character to c (default: “.”). .length reg anything Compute the number of characters of anything and store the count in the register reg. .linetabs Enable line‐tabs mode (calculate tab positions relative to beginning of output line). .linetabs 0 Disable line‐tabs mode. .lf n Set number of next input line to n. .lf n file Set number of next input line to n and input file name to file. .lg m Set ligature mode to m (0 = disable, 1 = enable, 2 = enable for two‐letter ligatures only). .ll Set line length to previous value. Does not affect a pending output line. .ll ±N Set line length to ±N (default length 6.5i, default scaling unit m). Does not affect a pending output line. .lsm Unset the leading space macro (trap). Restore default han‐ dling of lines with leading spaces. .lsm name Set the leading space macro (trap) to name. .ls Change to the previous value of additional intra‐line skip. .ls n Set additional intra‐line skip value to n, i.e., n-1 blank lines are inserted after each text output line. .lt Set length of title lines to previous value. .lt ±N Set length of title lines (default length 6.5i, default scal‐ ing unit m). .mc Cease writing margin character. .mc c Begin writing margin character c to the right of each output line. .mc c d Begin writing margin character c on each output line at dis‐ tance d to the right of the right margin (default distance 10p, default scaling unit m). .mk Mark vertical drawing position in an internal register; see .rt. .mk register Mark vertical drawing position in register. .mso file As .so, except that file is sought in the tmac directories. .msoquiet file As .mso, but no warning is emitted if file does not exist. .na Disable output line adjustment. .ne Break page if distance to next page location trap is less than one vee. .ne d Break page if distance to next page location trap is less than distance d (default scaling unit v). .nf Disable filling of output lines; a pending output line is broken. Clears \n[.u]. .nh Disable automatic hyphenation; same as “.hy 0”. .nm Deactivate output line numbering. .nm ±N .nm ±N m .nm ±N m s .nm ±N m s i Activate output line numbering: number the next output line ±N, writing numbers every m lines, with s numeral widths (\0) between the line number and the output (default 1), and in‐ denting the line number by i numeral widths (default 0). .nn Suppress numbering of the next output line to be numbered with nm. .nn n Suppress numbering of the next n output lines to be numbered with nm. If n=0, cancel suppression. .nop anything Interpret anything as if it were an input line. .nr reg ±N Define or update register reg with value N. .nr reg ±N I Define or update register reg with value N and auto‐increment I. .nroff Make the conditional expressions n true and t false. .ns Enable no‐space mode, ignoring .sp requests until a glyph or \D primitive is output. See .rs. .nx Immediately jump to end of current file. .nx file Stop formatting current file and begin reading file. .open stream file Open file for writing and associate the stream named stream with it. Unsafe request; disabled by default. .opena stream file As .open, but append to file. Unsafe request; disabled by default. .os Output vertical distance that was saved by the .sv request. .output contents Emit contents directly to intermediate output, allowing lead‐ ing whitespace if string starts with " (which is stripped off). .pc Reset page number character to ‘%’. .pc c Page number character. .pev Report the state of the current environment followed by that of all other environments to the standard error stream. .pi program Pipe output to program (nroff only). Unsafe request; dis‐ abled by default. .pl Set page length to default 11i. The current page length is stored in register .p. .pl ±N Change page length to ±N (default scaling unit v). .pm Report, to the standard error stream, the names and sizes in bytes of defined macros, strings, and diversions. .pn ±N Next page number N. .pnr Write the names and contents of all defined registers to the standard error stream. .po Change to previous page offset. The current page offset is available in register .o. .po ±N Page offset N. .ps Return to previous type size. .ps ±N Set/increase/decrease the type size to/by N scaled points (a non‐positive resulting type size is set to 1 u); also see \s[±N]. .psbb file Retrieve the bounding box of the PostScript image found in file, which must conform to Adobe’s Document Structuring Con‐ ventions (DSC). See registers llx, lly, urx, ury. .pso command‐line Execute command‐line with popen(3) and interpolate its out‐ put. Unsafe request; disabled by default. .ptr Report names and positions of all page location traps to the standard error stream. .pvs Change to previous post‐vertical line spacing. .pvs ±N Change post‐vertical line spacing according to ±N (default scaling unit p). .rchar c1 c2 ... Remove definition of each ordinary or special character c1, c2, ... defined by a .char, .fchar, or .schar request. .rd prompt Read insertion. .return Return from a macro. .return anything Return twice, namely from the macro at the current level and from the macro one level higher. .rfschar f c1 c2 ... Remove the font‐specific definitions of glyphs c1, c2, ... for font f. .rj npl Break, right‐align the output of the next productive input line without filling, then break again. .rj npl Break, right‐align the output of the next npl productive in‐ put lines without filling, then break again. If npl ≤ 0, stop right‐aligning. .rm name Remove request, macro, diversion, or string name. .rn old new Rename request, macro, diversion, or string old to new. .rnn reg1 reg2 Rename register reg1 to reg2. .rr ident Remove register ident. .rs Restore spacing; disable no‐space mode. See .ns. .rt Return (upward only) to vertical position marked by .mk on the current page. .rt N Return (upward only) to vertical position N (default scaling unit v). .schar c contents Define global fallback character (or glyph) c as contents. .shc Reset the soft hyphen character to \[hy]. .shc c Set the soft hyphen character to c. .shift n In a macro definition, left‐shift arguments by n positions. .sizes s1 s2 ... sn [0] Set available type sizes similarly to the sizes directive in a DESC file. Each si is interpreted in units of scaled points (z). .so file Replace the request’s control line with the contents of file, “sourcing” it. .soquiet file As .so, but no warning is emitted if file does not exist. .sp Break and move the next text baseline down by one vee, or un‐ til springing a page location trap. .sp dist Break and move the next text baseline down by dist, or until springing a page location trap (default scaling unit v). A negative dist will not reduce the position of the text base‐ line below zero. Prefixing dist with the | operator moves to a position relative to the page top for positive N, and the bottom if N is negative; in all cases, one line height (vee) is added to dist. dist is ignored inside a diversion. .special Reset global list of special fonts to be empty. .special s1 s2 ... Fonts s1, s2, etc. are special and are searched for glyphs not in the current font. .spreadwarn Toggle the spread warning on and off (the default) without changing its value. .spreadwarn N Emit a break warning if the additional space inserted for each space between words in an adjusted output line is greater than or equal to N. A negative N is treated as 0. The default scaling unit is m. At startup, .spreadwarn is inactive and N is 3 m. .ss n Set minimal inter‐word spacing to n 12ths of current font’s space width. .ss n m As “.ss n”, and set additional inter‐sentence space to m 12ths of current font’s space width. .stringdown stringvar Replace each byte in the string named stringvar with its low‐ ercase version. .stringup stringvar Replace each byte in the string named stringvar with its up‐ percase version. .sty n style Associate abstract style with font position n. .substring str start [end] Replace the string named str with its substring bounded by the indices start and end, inclusive. Negative indices count backwards from the end of the string. .sv As .ne, but save 1 v for output with .os request. .sv d As .ne, but save distance d for later output with .os request (default scaling unit v). .sy command‐line Execute command‐line with system(3). Unsafe request; dis‐ abled by default. .ta n1 n2 ... nn T r1 r2 ... rn Set tabs at positions n1, n2, ..., nn, then set tabs at nn+m×rn+r1 through nn+m×rn+rn, where m increments from 0, 1, 2, ... to the output line length. Each n argument can be prefixed with a “+” to place the tab stop ni at a distance relative to the previous, n(i-1). Each argument ni or ri can be suffixed with a letter to align text within the tab column bounded by tab stops i and i+1; “L” for left‐aligned (the de‐ fault), “C” for centered, and “R” for right‐aligned. .tag .taga Reserved for internal use. .tc Unset tab repetition character. .tc c Set tab repetition character to c (default: none). .ti ±N Temporarily indent next output line (default scaling unit m). .tkf font s1 n1 s2 n2 Enable track kerning for font. .tl 'left'center'right' Format three‐part title. .tm message Write message, followed by a newline, to the standard error stream. .tm1 message As .tm, but an initial neutral double quote in message is re‐ moved, allowing it to contain leading spaces. .tmc message As .tm1, without emitting a newline. .tr abcd... Translate ordinary or special characters a to b, c to d, and so on prior to output. .trf file Transparently output the contents of file. Unlike .cf, in‐ valid input characters in file are rejected. .trin abcd... As .tr, except that .asciify ignores the translation when a diversion is interpolated. .trnt abcd... As .tr, except that translations are suppressed in the argu‐ ment to \!. .troff Make the conditional expressions t true and n false. .uf font Set underline font used by .ul to font. .ul Underline (italicize in troff mode) the output of the next productive input line. .ul npl Underline (italicize in troff mode) the output of the next npl productive input line. If npl=0, stop underlining. .unformat diversion Unformat space characters and tabs in diversion, preserving font information. .vpt Enable vertical position traps. .vpt 0 Disable vertical position traps. .vs Change to previous vertical spacing. .vs ±N Set vertical spacing to ±N (default scaling unit p). .warn Enable all warning categories. .warn 0 Disable all warning categories. .warn n Enable warnings in categories whose codes sum to n; see troff(1). .warnscale su Set scaling unit used in certain warnings to su (one of u, i, c, p, or P; default: i). .wh vpos Remove visible page location trap at vpos (default scaling unit v). .wh vpos name Plant macro name as page location trap at vpos (default scal‐ ing unit v), removing any visible trap already there. .while cond‐expr anything Repeatedly execute anything unless and until cond‐expr evalu‐ ates false. .write stream anything Write anything to the stream named stream. .writec stream anything Similar to .write without emitting a final newline. .writem stream xx Write contents of macro or string xx to the stream named stream. Escape sequence short reference The escape sequences \", \#, \$, \*, \?, \a, \e, \n, \t, \g, \V, and \newline are interpreted even in copy mode. \" Comment. Everything up to the end of the line is ignored. \# Comment. Everything up to and including the next newline is ig‐ nored. \*s Interpolate string with one‐character name s. \*(st Interpolate string with two‐character name st. \*[string] Interpolate string with name string (of arbitrary length). \*[string arg ...] Interpolate string with name string (of arbitrary length), tak‐ ing arg ... as arguments. \$0 Interpolate name by which currently executing macro was invoked. \$n Interpolate macro or string parameter numbered n (1≤n≤9). \$(nn Interpolate macro or string parameter numbered nn (01≤nn≤99). \$[nnn] Interpolate macro or string parameter numbered nnn (nnn≥1). \$* Interpolate concatenation of all macro or string parameters, separated by spaces. \$@ Interpolate concatenation of all macro or string parameters, with each surrounded by double quotes and separated by spaces. \$^ Interpolate concatenation of all macro or string parameters as if they were arguments to the .ds request. \' is a synonym for \[aa], the acute accent special character. \` is a synonym for \[ga], the grave accent special character. \- is a synonym for \[-], the minus sign special character. \_ is a synonym for \[ul], the underrule special character. \% Control hyphenation. \! Transparent line. The remainder of the input line is inter‐ preted (1) when the current diversion is read; or (2) if in the top‐level diversion, by the postprocessor (if any). \?anything\? Transparently embed anything, read in copy mode, in a diversion, or unformatted as an output comparand in a conditional expres‐ sion. \space Move right one word space. \~ Insert an unbreakable, adjustable space. \0 Move right by the width of a numeral in the current font. \| Move one‐sixth em to the right on typesetters. \^ Move one‐twelfth em to the right on typesetters. \& Interpolate a dummy character. \) Interpolate a dummy character that is transparent to end‐of‐sen‐ tence recognition. \/ Apply italic correction. Use between an immediately adjacent oblique glyph on the left and an upright glyph on the right. \, Apply left italic correction. Use between an immediately adja‐ cent upright glyph on the left and an oblique glyph on the right. \: Non‐printing break point (similar to \%, but never produces a hyphen glyph). \newline Continue current input line on the next. \{ Begin conditional input. \} End conditional input. \(gl Interpolate glyph with two‐character name gl. \[glyph] Interpolate glyph with name glyph (of arbitrary length). \[base‐char comp ...] Interpolate composite glyph constructed from base‐char and each component comp. \[charnnn] Interpolate glyph of eight‐bit encoded character nnn, where 0≤nnn≤255. \[unnnn[n[n]]] Interpolate glyph of Unicode character with code point nnnn[n[n]] in uppercase hexadecimal. \[ubase‐char[_combining‐component]...] Interpolate composite glyph from Unicode character base‐char and combining‐components. \a Interpolate a leader in copy mode. \A'anything' Interpolate 1 if anything is a valid identifier, and 0 other‐ wise. \b'string' Build bracket: pile a sequence of glyphs corresponding to each character in string vertically, and center it vertically on the output line. \B'anything' Interpolate 1 if anything is a valid numeric expression, and 0 otherwise. \c Continue output line at next input line. \C'glyph' As \[glyph], but compatible with other troff implementations. \d Move downward ½ em on typesetters. \D'drawing‐command' See subsection “Drawing commands” below. \e Interpolate the escape character. \E As \e, but not interpreted in copy mode. \fP Select previous font mounting position (abstract style or font); same as “.ft” or “.ft P”. \fF Select font mounting position, abstract style, or font with one‐ character name or one‐digit position F. F cannot be P. \f(ft Select font mounting position, abstract style, or font with two‐ character name or two‐digit position ft. \f[font] Select font mounting position, abstract style, or font with ar‐ bitrarily long name or position font. font cannot be P. \f[] Select previous font mounting position (abstract style or font). \Ff Set default font family to that with one‐character name f. \F(fm Set default font family to that with two‐character name fm. \F[fam] Set default font family to that with arbitrarily long name fam. \F[] Set default font family to previous value. \gr Interpolate format of register with one‐character name r. \g(rg Interpolate format of register with two‐character name rg. \g[reg] Interpolate format of register with arbitrarily long name reg. \h'N' Horizontally move the drawing position by N ems (or specified units); | may be used. Positive motion is rightward. \H'N' Set height of current font to N scaled points (or specified units). \kr Mark horizontal position in one‐character register name r. \k(rg Mark horizontal position in two‐character register name rg. \k[reg] Mark horizontal position in register with arbitrarily long name reg. \l'N[c]' Draw horizontal line of length N with character c (default: \[ru]; default scaling unit m). \L'N[c]' Draw vertical line of length N with character c (default: \[br]; default scaling unit v). \mc Set stroke color to that with one‐character name c. \m(cl Set stroke color to that with two‐character name cl. \m[color] Set stroke color to that with arbitrarily long name color. \m[] Restore previous stroke color. \Mc Set fill color to that with one‐character name c. \M(cl Set fill color to that with two‐character name cl. \M[color] Set fill color to that with arbitrarily long name color. \M[] Restore previous fill color. \nr Interpolate contents of register with one‐character name r. \n(rg Interpolate contents of register with two‐character name rg. \n[reg] Interpolate contents of register with arbitrarily long name reg. \N'n' Interpolate glyph with index n in the current font. \o'abc...' Overstrike centered glyphs of characters a, b, c, and so on. \O0 At the outermost suppression level, disable emission of glyphs and geometric objects to the output driver. \O1 At the outermost suppression level, enable emission of glyphs and geometric objects to the output driver. \O2 At the outermost suppression level, enable glyph and geometric primitive emission to the output driver and write to the stan‐ dard error stream the page number, four bounding box registers enclosing glyphs written since the previous \O escape sequence, the page offset, line length, image file name (if any), horizon‐ tal and vertical device motion quanta, and input file name. \O3 Begin a nested suppression level. \O4 End a nested suppression level. \O[5Pfile] At the outermost suppression level, write the name file to the standard error stream at position P, which must be one of l, r, c, or i. \p Break output line at next word boundary; adjust if applicable. \r Move “in reverse” (upward) 1 em. \R'name ±N' Set, increment, or decrement register name by N. \s±N Set/increase/decrease the type size to/by N scaled points. N must be a single digit; 0 restores the previous type size. (In compatibility mode only, a non‐zero N must be in the range 4–39.) Otherwise, as .ps request. \s(±N \s±(N Set/increase/decrease the type size to/by N scaled points; N is a two‐digit number ≥1. As .ps request. \s[±N] \s±[N] \s'±N' \s±'N' Set/increase/decrease the type size to/by N scaled points. As .ps request. \S'N' Slant output glyphs by N degrees; the direction of text flow is positive. \t Interpolate a tab in copy mode. \u Move upward ½ em on typesetters. \v'N' Vertically move the drawing position by N vees (or specified units); | may be used. Positive motion is downward. \Ve Interpolate contents of environment variable with one‐character name e. \V(ev Interpolate contents of environment variable with two‐character name ev. \V[env] Interpolate contents of environment variable with arbitrarily long name env. \w'anything' Interpolate width of anything, formatted in a dummy environment. \x'N' Increase vertical spacing of pending output line by N vees (or specified units; negative before, positive after). \X'anything' Write anything to troff output as a device control command. Within anything, the escape sequences \&, \), \%, and \: are ig‐ nored; \space and \~ are converted to single space characters; and \\ has its escape character stripped. So that the basic Latin subset of the Unicode character set can be reliably en‐ coded in anything, the special character escape sequences \-, \[aq], \[dq], \[ga], \[ha], \[rs], and \[ti] are mapped to basic Latin characters; see groff_char(7). For this transformation, character translations and special character definitions are ig‐ nored. \Yn Write contents of macro or string n to troff output as a device control command. \Y(nm Write contents of macro or string nm to troff output as a device control command. \Y[name] Write contents of macro or string name to troff output as a de‐ vice control command. \zc Format character c with zero width—without advancing the drawing position. \Z'anything' Save the drawing position, format anything, then restore it. Drawing commands Drawing commands direct the output device to render geometrical objects rather than glyphs. Specific devices may support only a subset, or may feature additional ones; consult the man page for the output driver in use. Terminal devices in particular implement almost none. Rendering starts at the drawing position; when finished, the drawing position is left at the rightmost point of the object, even for closed figures, except where noted. GNU troff draws stroked (outlined) ob‐ jects with the stroke color, and shades filled ones with the fill color. See section “Colors” above. Coordinates h and v are horizontal and vertical motions relative to the drawing position or previous point in the command. The default scaling unit for horizontal measurements (and diameters of circles) is m; for vertical ones, v. Circles, ellipses, and polygons can be drawn stroked or filled. These are independent properties; if you want a filled, stroked figure, you must draw the same figure twice using each drawing command. A filled figure is always smaller than an outlined one because the former is drawn only within its defined area, whereas strokes have a line thick‐ ness (set with \D't'). \D'~ h1 v1 ... hn vn' Draw B‐spline to each point in sequence, leaving drawing posi‐ tion at (hn, vn). \D'a hc vc h v' Draw circular arc centered at (hc, vc) counterclockwise from the drawing position to a point (h, v) relative to the center. (hc, vc) is adjusted to the point nearest the perpendicular bi‐ sector of the arc’s chord. \D'c d' Draw circle of diameter d with its leftmost point at the drawing position. \D'C d' As \D'C', but the circle is filled. \D'e h v' Draw ellipse of width h and height v with its leftmost point at the drawing position. \D'E h v' As \D'e', but the ellipse is filled. \D'l h v' Draw line from the drawing position to (h, v). \D'p h1 v1 ... hn vn' Draw polygon with vertices at drawing position and each point in sequence. GNU troff closes the polygon by drawing a line from (hn, vn) back to the initial drawing position. Afterward, the drawing position is left at (hn, vn). \D'P h1 v1 ... hn vn' As \D'p', but the polygon is filled. \D't n' Set stroke thickness of geometric objects to to n basic units. A zero n selects the minimal supported thickness. A negative n selects a thickness proportional to the type size; this is the default. Device control commands The .device and .devicem requests, and \X and \Y escape sequences, en‐ able documents to pass information directly to a postprocessor. These are useful for exercising device‐specific capabilities that the groff language does not abstract or generalize; such functions include the embedding of hyperlinks and image files. Device‐specific functions are documented in each output driver’s man page. Strings groff supports strings primarily for user convenience. Conventionally, if one would define a macro only to interpolate a small amount of text, without invoking requests or calling any other macros, one defines a string instead. Only one string is predefined by the language. \*[.T] Contains the name of the output device (for example, “utf8” or “pdf”). The .ds request creates a string with a specified name and contents. If the identifier named by .ds already exists as an alias, the target of the alias is redefined. If .ds is called with only one argument, the named string becomes empty. Otherwise, troff stores the remainder of the control line in copy mode; see subsection “Copy mode” below. The \* escape sequence dereferences a string’s name, interpolating its contents. If the name does not exist, it is defined as empty, nothing is interpolated, and a warning in category “mac” is emitted. See sec‐ tion “Warnings” in troff(1). The bracketed interpolation form accepts arguments that are handled as macro arguments are; see section “Calling macros” above. In contrast to macro calls, however, if a closing bracket ] occurs in a string argument, that argument must be enclosed in double quotes. \* is interpreted even in copy mode. When defining strings, argument interpolations must be escaped if they are to refer‐ ence parameters from the calling context; see section “Parameters” be‐ low. An initial neutral double quote " in the string contents is stripped to allow embedding of leading spaces. Any other " is interpreted liter‐ ally, but it is wise to use the special character escape sequence \[dq] instead if the string might be interpolated as part of a macro argu‐ ment; see section “Calling macros” above. Strings are not limited to a single input line of text. \newline works just as it does elsewhere. The resulting string is stored without the newlines. Care is therefore required when interpolating strings while filling is disabled. It is not possible to embed a newline in a string that will be interpreted as such when the string is interpolated. To achieve that effect, use \* to interpolate a macro instead. The .as request is similar to .ds but appends to a string instead of redefining it. If .as is called with only one argument, no operation is performed (beyond dereferencing the string). Because strings are similar to macros, they too can be defined to sup‐ press AT&T troff compatibility mode enablement when interpolated; see section “Compatibility mode” below. The .ds1 request defines a string that suspends compatibility mode when the string is later interpolated. .as1 is likewise similar to .as, with compatibility mode suspended when the appended portion of the string is later interpolated. Caution: Unlike other requests, the second argument to these requests consumes the remainder of the input line, including trailing spaces. Ending string definitions (and appendments) with a comment, even an empty one, prevents unwanted space from creeping into them during source document maintenance. Several requests exist to perform rudimentary string operations. Strings can be queried (.length) and modified (.chop, .substring, .stringup, .stringdown), and their names can be manipulated through re‐ naming, removal, and aliasing (.rn, .rm, .als). When a request, macro, string, or diversion is aliased, redefinitions and appendments “write through” alias names. To replace an alias with a separately defined object, you must use the rm request on its name first. Registers In the roff language, numbers can be stored in registers. Many built‐ in registers exist, supplying anything from the date to details of for‐ matting parameters. You can also define your own. See section “Iden‐ tifiers” above for information on constructing a valid name for a reg‐ ister. Define registers and update their values with the nr request or the \R escape sequence. Registers can also be incremented or decremented by a configured amount at the time they are interpolated. The value of the increment is spec‐ ified with a third argument to the .nr request, and a special interpo‐ lation syntax, \n± is used to alter and then retrieve the register’s value. Together, these features are called auto‐increment. (A nega‐ tive auto‐increment can be considered an “auto‐decrement”.) Many predefined registers are available. In the following presenta‐ tion, the register interpolation syntax \n[name] is used to refer to a register name to clearly distinguish it from a string or request name. The register name space is separate from that used for requests, macros, strings, and diversions. Bear in mind that the symbols \n[] are not part of the register name. Read‐only registers Predefined registers whose identifiers start with a dot are read‐only. Many are Boolean‐valued. Some are string‐valued, meaning that they in‐ terpolate text. A register name (without the dot) is often associated with a request of the same name; exceptions are noted. \n[.$] Count of arguments passed to currently interpolated macro or string. \n[.a] Amount of extra post‐vertical line space; see \x. \n[.A] Approximate output is being formatted (Boolean‐valued); see troff -a option. \n[.b] Font emboldening offset; see .bd. \n[.br] The normal control character was used to call the cur‐ rently interpolated macro (Boolean‐valued). \n[.c] Input line number; see .lf and register “c.”. \n[.C] Compatibility mode is enabled (Boolean‐valued); see .cp. Always false when processing .do; see register .cp. \n[.cdp] Depth of last glyph formatted in the environment; posi‐ tive if glyph extends below the baseline. \n[.ce] Count of output lines remaining to be centered. \n[.cht] Height of last glyph formatted in the environment; posi‐ tive if glyph extends above the baseline. \n[.color] Color output is enabled (Boolean‐valued). \n[.cp] Within .do, the saved value of compatibility mode; see register .C. \n[.csk] Skew of the last glyph formatted in the environment; skew is how far to the right of the center of a glyph the center of an accent over that glyph should be placed. \n[.d] Vertical drawing position in diversion. \n[.ev] Name of environment (string‐valued). \n[.f] Mounting position of selected font; see .ft and \f. \n[.F] Name of input file (string‐valued); see .lf. \n[.fam] Name of default font family (string‐valued). \n[.fn] Resolved name of selected font (string‐valued); see .ft and \f. \n[.fp] Next non‐zero free font mounting position index. \n[.g] Always true in GNU troff (Boolean‐valued). \n[.h] Text baseline high‐water mark on page or in diversion. \n[.H] Horizontal motion quantum of output device in basic units. \n[.height] Font height; see \H. \n[.hla] Hyphenation language in environment (string‐valued). \n[.hlc] Count of immediately preceding consecutive hyphenated lines in environment. \n[.hlm] Maximum quantity of consecutive hyphenated lines allowed in environment. \n[.hy] Automatic hyphenation mode in environment. \n[.hym] Hyphenation margin in environment. \n[.hys] Hyphenation space adjustment threshold in environment. \n[.i] Indentation amount; see .in. \n[.in] Indentation amount applicable to the pending output line; see .ti. \n[.int] Previous output line was “interrupted” or continued with \c (Boolean‐valued). \n[.j] Adjustment mode encoded as an integer; see .ad and .na. Do not interpret or perform arithmetic on its value. \n[.k] Horizontal drawing position relative to indentation. \n[.kern] Pairwise kerning is enabled (Boolean‐valued). \n[.l] Line length; see .ll. \n[.L] Line spacing; see .ls. \n[.lg] Ligature mode. \n[.linetabs] Line‐tabs mode is enabled (Boolean‐valued). \n[.ll] Line length applicable to the pending output line. \n[.lt] Title length. \n[.m] Stroke color (string‐valued); see .gcolor and \m. Empty if the stroke color is the default. \n[.M] Fill color (string‐valued); see .fcolor and \M. Empty if the fill color is the default. \n[.n] Length of formatted output on previous output line. \n[.ne] Amount of vertical space required by last .ne that caused a trap to be sprung; also see register .trunc. \n[.nm] Output line numbering is enabled (Boolean‐valued). \n[.nn] Count of output lines remaining to have numbering sup‐ pressed. \n[.ns] No‐space mode is enabled (Boolean‐valued). \n[.o] Page offset; see .po. \n[.O] Output suppression nesting level; see \O. \n[.p] Page length; see .pl. \n[.P] The page is selected for output (Boolean‐valued); see troff -o option. \n[.pe] Page ejection is in progress (Boolean‐valued). \n[.pn] Number of the next page. \n[.ps] Type size in scaled points. \n[.psr] Most recently requested type size in scaled points; see .ps and \s. \n[.pvs] Post‐vertical line spacing. \n[.R] Count of available unused registers; always 10,000 in GNU troff. \n[.rj] Count of lines remaining to be right‐aligned. \n[.s] Type size in points as a decimal fraction (string‐val‐ ued); see .ps and \s. \n[.slant] Slant of font in degrees; see \S. \n[.sr] Most recently requested type size in points as a decimal fraction (string‐valued); see .ps and \s. \n[.ss] Size of minimal inter‐word space in twelfths of the space width of the selected font. \n[.sss] Size of additional inter‐sentence space in twelfths of the space width of the selected font. \n[.sty] Selected abstract style (string‐valued); see .ft and \f. \n[.t] Distance to next vertical position trap; see .wh and .ch. \n[.T] An output device was explicitly selected (Boolean‐val‐ ued); see troff -T option. \n[.tabs] Representation of tab settings suitable for use as argu‐ ment to .ta (string‐valued). \n[.trunc] Amount of vertical space truncated by the most recently sprung vertical position trap, or, if the trap was sprung by an .ne, minus the amount of vertical motion produced by .ne; also see register .ne. \n[.u] Filling is enabled (Boolean‐valued); see .fi and .nf. \n[.U] Unsafe mode is enabled (Boolean‐valued); see troff -U option. \n[.v] Vertical line spacing; see .vs. \n[.V] Vertical motion quantum of the output device in basic units. \n[.vpt] Vertical position traps are enabled (Boolean‐valued). \n[.w] Width of previous glyph formatted in the environment. \n[.warn] Sum of the numeric codes of enabled warning categories. \n[.x] Major version number of the running troff formatter. \n[.y] Minor version number of the running troff formatter. \n[.Y] Revision number of the running troff formatter. \n[.z] Name of diversion (string‐valued). Empty if output is directed to the top‐level diversion. \n[.zoom] Zoom multiplier of current font (in thousandths; zero if no magnification); see .fzoom. Writable predefined registers Several registers are predefined but also modifiable; some are updated upon interpretation of certain requests or escape sequences. Date‐ and time‐related registers are set to the local time as determined by localtime(3) when the formatter launches. This initialization can be overridden by SOURCE_DATE_EPOCH and TZ; see section “Environment” of groff(1). \n[$$] Process ID of troff. \n[%] Page number. \n[c.] Input line number. \n[ct] Union of character types of each glyph rendered into dummy environment by \w. \n[dl] Width of last closed diversion. \n[dn] Height of last closed diversion. \n[dw] Day of the week (1–7; 1 is Sunday). \n[dy] Day of the month (1–31). \n[hours] Count of hours elapsed since midnight (0–23). \n[hp] Horizontal drawing position relative to start of input line. \n[llx] Lower‐left x coordinate (in PostScript units) of Post‐ Script image; see .psbb. \n[lly] Lower‐left y coordinate (in PostScript units) of Post‐ Script image; see .psbb. \n[ln] Output line number; see .nm. \n[lsn] Count of leading spaces on input line. \n[lss] Amount of horizontal space corresponding to leading spaces on input line. \n[minutes] Count of minutes elapsed in the hour (0–59). \n[mo] Month of the year (1–12). \n[nl] Vertical drawing position. \n[opmaxx] \n[opmaxy] \n[opminx] \n[opminy] These four registers mark the top left‐ and bottom right‐hand corners of a rectangle encompassing all for‐ matted output on the page. They are reset to -1 by \O0 or \O1. \n[rsb] As register sb, adding maximum glyph height to measure‐ ment. \n[rst] As register st, adding maximum glyph depth to measure‐ ment. \n[sb] Maximum displacement of text baseline below its original position after rendering into dummy environment by \w. \n[seconds] Count of seconds elapsed in the minute (0–60). \n[skw] Skew of last glyph rendered into dummy environment by \w. \n[slimit] The maximum depth of troff’s internal input stack. If ≤0, there is no limit: recursion can continue until available memory is exhausted. The default is 1,000. \n[ssc] Subscript correction of last glyph rendered into dummy environment by \w. \n[st] Maximum displacement of text baseline above its original position after rendering into dummy environment by \w. \n[systat] Return value of system() function; see .sy. \n[urx] Upper‐right x coordinate (in PostScript units) of Post‐ Script image; see .psbb. \n[ury] Upper‐right y coordinate (in PostScript units) of Post‐ Script image; see .psbb. \n[year] Gregorian year. \n[yr] Gregorian year minus 1900. Using fonts In digital typography, a font is a collection of characters in a spe‐ cific typeface that a device can render as glyphs at a desired size. (Terminals and some output devices have fonts that render at only one or two sizes. As examples of the latter, take the groff lj4 device’s Lineprinter, and lbp’s Courier and Elite faces.) A roff formatter can change typefaces at any point in the text. The basic faces are a set of styles combining upright and slanted shapes with normal and heavy stroke weights: “R”, “I”, “B”, and “BI”—these stand for roman, bold, italic, and bold‐italic. For linguistic text, GNU troff groups type‐ faces into families containing each of these styles. (Font designers prepare families such that the styles share esthetic properties.) A text font is thus often a family combined with a style, but it need not be: consider the ps and pdf devices’ ZCMI (Zapf Chancery Medium italic)—often, no other style of Zapf Chancery Medium is provided. On typesetting devices, at least one special font is available, comprising unstyled glyphs for mathematical operators and other purposes. Like AT&T troff, GNU troff does not itself load or manipulate a digital font file; instead it works with a font description file that charac‐ terizes it, including its glyph repertoire and the metrics (dimensions) of each glyph. This information permits the formatter to accurately place glyphs with respect to each other. Before using a font descrip‐ tion, the formatter associates it with a mounting position, a place in an ordered list of available typefaces. So that a document need not be strongly coupled to a specific font family, in GNU troff an output de‐ vice can associate a style in the abstract sense with a mounting posi‐ tion. Thus the default family can be combined with a style dynami‐ cally, producing a resolved font name. Fonts often have trademarked names, and even Free Software fonts can require renaming upon modification. groff maintains a convention that a device’s serif font family is given the name T (“Times”), its sans‐ serif family H (“Helvetica”), and its monospaced family C (“Courier”). Historical inertia has driven groff’s font identifiers to short upper‐ case abbreviations of font names, as with TR, TB, TI, TBI, and a spe‐ cial font S. The default family used with abstract styles can be changed at any time; initially, it is T. Typically, abstract styles are arranged in the first four mounting positions in the order shown above. The de‐ fault mounting position, and therefore style, is always 1 (R). By is‐ suing appropriate formatter instructions, you can override these de‐ faults before your document writes its first glyph. Terminal output devices cannot change font families and lack special fonts. They support style changes by overstriking, or by altering ISO 6429/ECMA‐48 graphic renditions (character cell attributes). Hyphenation When filling, groff hyphenates words as needed at user‐specified and automatically determined hyphenation points. Explicitly hyphenated words such as “mother‐in‐law” are always eligible for breaking after each of their hyphens. The hyphenation character \% and non‐printing break point \: escape sequences may be used to control the hyphenation and breaking of individual words. The .hw request sets user‐defined hyphenation points for specified words at any subsequent occurrence. Otherwise, groff determines hyphenation points automatically by de‐ fault. Several requests influence automatic hyphenation. Because conventions vary, a variety of hyphenation modes is available to the .hy request; these determine whether hyphenation will apply to a word prior to breaking a line at the end of a page (more or less; see below for de‐ tails), and at which positions within that word automatically deter‐ mined hyphenation points are permissible. The default is “1” for his‐ torical reasons, but this is not an appropriate value for the English hyphenation patterns used by groff; localization macro files loaded by troffrc and macro packages often override it. 0 disables hyphenation. 1 enables hyphenation except after the first and before the last character of a word. The remaining values “imply” 1; that is, they enable hyphenation under the same conditions as “.hy 1”, and then apply or lift restrictions relative to that basis. 2 disables hyphenation of the last word on a page. (Hyphenation is prevented if the next page location trap is closer to the vertical drawing position than the next text baseline would be. See section “Traps” below.) 4 disables hyphenation before the last two characters of a word. 8 disables hyphenation after the first two characters of a word. 16 enables hyphenation before the last character of a word. 32 enables hyphenation after the first character of a word. Apart from value 2, restrictions imposed by the hyphenation mode are not respected for words whose hyphenations have been specified with the hyphenation character (“\%” by default) or the .hw request. Nonzero values are additive. For example, mode 12 causes groff to hy‐ phenate neither the last two nor the first two characters of a word. Some values cannot be used together because they contradict; for in‐ stance, values 4 and 16, and values 8 and 32. As noted, it is super‐ fluous to add 1 to any non‐zero even mode. The places within a word that are eligible for hyphenation are deter‐ mined by language‐specific data (.hla, .hpf, and .hpfa) and lettercase relationships (.hcode and .hpfcode). Furthermore, hyphenation of a word might be suppressed due to a limit on consecutive hyphenated lines (.hlm), a minimum line length threshold (.hym), or because the line can instead be adjusted with additional inter‐word space (.hys). Localization The set of hyphenation patterns is associated with the hyphenation lan‐ guage set by the .hla request. The .hpf request is usually invoked by a localization file loaded by the troffrc file. groff provides local‐ ization files for several languages; see groff_tmac(5). Writing macros The .de request defines a macro named for its argument. If that name already exists as an alias, the target of the alias is redefined; see section “Strings” above. troff enters “copy mode” (see below), storing subsequent input lines as the definition. If the optional second argu‐ ment is not specified, the definition ends with the control line “..” (two dots). Alternatively, a second argument names a macro whose call syntax ends the definition; this “end macro” is then called normally. Spaces or tabs are permitted after the first control character in the line containing this ending token, but a tab immediately after the to‐ ken prevents its recognition as the end of a macro definition. Macro definitions can be nested if they use distinct end macros or if their ending tokens are sufficiently escaped. An end macro need not be de‐ fined until it is called. This fact enables a nested macro definition to begin inside one macro and end inside another. Variants of .de disable compatibility mode and/or indirect the names of the macros specified for definition or termination: these are .de1, .dei, and .dei1. Append to macro definitions with .am, .am1, .ami, and .ami1. The .als, .rm, and .rn requests create an alias of, remove, and rename a macro, respectively. .return stops the execution of a macro immediately, returning to the enclosing context. Parameters Macro call and string interpolation parameters can be accessed using escape sequences starting with “\$”. The \n[.$] read‐only register stores the count of parameters available to a macro or string; its value can be changed by the .shift request, which dequeues parameters from the current list. The \$0 escape sequence interpolates the name by which a macro was called. Applying string interpolation to a macro does not change this name. Copy mode When troff processes certain requests, most importantly those which de‐ fine or append to a macro or string, it does so in copy mode: it copies the characters of the definition into a dedicated storage region, in‐ terpolating the escape sequences \n, \g, \$, \*, \V, and \? normally; interpreting \newline immediately; discarding comments \" and \#; in‐ terpolating the current leader, escape, or tab character with \a, \e, and \t, respectively; and storing all other escape sequences in an en‐ coded form. The complement of copy mode—a roff formatter’s behavior when not defining or appending to a macro, string, or diversion—where all macros are interpolated, requests invoked, and valid escape se‐ quences processed immediately upon recognition, can be termed interpre‐ tation mode. The escape character, \ by default, can escape itself. This enables you to control whether a given \n, \g, \$, \*, \V, or \? escape se‐ quence is interpreted at the time the macro containing it is defined, or later when the macro is called. You can think of \\ as a “delayed” backslash; it is the escape charac‐ ter followed by a backslash from which the escape character has removed its special meaning. Consequently, \\ is not an escape sequence in the usual sense. In any escape sequence \X that troff does not recognize, the escape character is ignored and X is output. An unrecognized es‐ cape sequence causes a warning in category “escape”, with two excep‐ tions, \\ being one. The other is \., which escapes the control char‐ acter. It is used to permit nested macro definitions to end without a named macro call to conclude them. Without a syntax for escaping the control character, this would not be possible. roff documents should not use the \\ or \. character sequences outside of copy mode; they serve only to obfuscate the input. Use \e to represent the escape character, \[rs] to obtain a backslash glyph, and \& before . and ' where troff expects them as control characters if you mean to use them literally. Macro definitions can be nested to arbitrary depth. In “\\”, each es‐ cape character is interpreted twice—once in copy mode, when the macro is defined, and once in interpretation mode, when the macro is called. This fact leads to exponential growth in the quantity of escape charac‐ ters required to delay interpolation of \n, \g, \$, \*, \V, and \? at each nesting level. An alternative is to use \E, which represents an escape character that is not interpreted in copy mode. Because \. is not a true escape sequence, we can’t use \E to keep “..” from ending a macro definition prematurely. If the multiplicity of backslashes com‐ plicates maintenance, use end macros. Traps Traps are locations in the output, or conditions on the input that, when reached or fulfilled, call a specified macro. A vertical position trap calls a macro when the formatter’s vertical drawing position reaches or passes, in the downward direction, a certain location on the output page or in a diversion. Its applications include setting page headers and footers, body text in multiple columns, and footnotes. These traps can occur at a given location on the page (.wh, .ch); at a given location in the current diversion (.dt)—together, these are known as vertical position traps, which can be disabled and re‐enabled (.vpt). A diversion is not formatted in the context of a page, so it lacks page location traps; instead it can have a diversion trap. There can exist at most one such vertical position trap per diversion. Other kinds of trap can be planted at a blank line (.blm); at a line with leading space characters (.lsm); after a certain number of produc‐ tive input lines (.it, .itc); or at the end of input (.em). Macros called by traps are passed no arguments. Setting a trap is also called planting one. It is said that a trap is sprung if its condition is fulfilled. Registers associated with trap management include vertical position trap enablement status (\n[.vpt]), distance to the next trap (\n[.t]), amount of needed (.ne‐requested) space that caused the most recent ver‐ tical position trap to be sprung (\n[.ne]), amount of needed space truncated from the amount requested (\n[.trunc]), page ejection status (\n[.pe]), and leading space count (\n[.lsn]) with its corresponding amount of motion (\n[.lss]). Page location traps A page location trap is a vertical position trap that applies to the page; that is, to undiverted output. Many can be present; manage them with the wh and ch requests. Non‐negative page locations given to these requests set the trap relative to the top of the page; negative values set the trap relative to the bottom of the page. It is not pos‐ sible to plant a trap less than one basic unit from the page bottom: a location of “-0” is interpreted as “0”, the top of the page. An exist‐ ing visible trap (see below) at the same location is removed; this is .wh’s sole function if its second argument is missing. A trap is sprung only if it is visible, meaning that its location is reachable on the page and it is not hidden by another trap at the same location already planted there. (A trap planted at “20i” or “-30i” will not be sprung on a page of length “11i”.) A trap above the top or at or below the bottom of the page can be made visible by either moving it into the page area or increasing the page length so that the trap is on the page. Negative trap values always use the current page length; they are not converted to an absolute ver‐ tical position. Use .ptr to dump page location traps to the standard error stream; their positions are reported in basic units. The implicit page trap An implicit page trap always exists in the top‐level diversion; it works like a trap in some ways but not others. Its purpose is to eject the current page and start the next one. It has no name, so it cannot be moved or deleted with wh or ch requests. You cannot hide it by placing another trap at its location, and can move it only by redefin‐ ing the page length with .pl. Its operation is suppressed when verti‐ cal page traps are disabled with the vpt request. Diversions In roff systems it is possible to format text as if for output, but in‐ stead of writing it immediately, one can divert the formatted text into a named storage area. It is retrieved later by specifying its name af‐ ter a control character. The same name space is used for such diver‐ sions as for strings and macros; see section “Identifiers” above. Such text is sometimes said to be “stored in a macro”, but this coinage ob‐ scures the important distinction between macros and strings on one hand and diversions on the other; the former store unformatted input text, and the latter capture formatted output. Diversions also do not inter‐ pret arguments. Applications of diversions include “keeps” (preventing a page break from occurring at an inconvenient place by forcing a set of output lines to be set as a group), footnotes, tables of contents, and indices. For orthogonality it is said that GNU troff is in the top‐level diversion if no diversion is active (that is, formatted out‐ put is being “diverted” immediately to the output device. Dereferencing an undefined diversion will create an empty one of that name and cause a warning in category mac to be emitted. (see section “Warnings” in troff(1)). A diversion does not exist for the purpose of testing with the d conditional operator until its initial definition ends (see subsection “Conditional expressions” above). The di request creates a diversion, including any partially collected line. da appends to a diversion, creating one if it does not already exist. If the diversion’s name already exists as an alias, the target of the alias is replaced or appended to; see section “Strings” above. box and boxa works similarly, but ignore partially collected lines. Call any of these macros again without an argument to end the diver‐ sion. Diversions can be nested. The registers .d, .z, dn, and dl report in‐ formation about the current (or last closed) diversion. .h is meaning‐ ful in diversions, including the top level. The \! and \? escape sequences and output request escape from a di‐ version, the first two to the enclosing level and the last to the top level. This facility is termed transparent embedding. The asciify and unformat requests reprocess diversions. Punning names Macros, strings, and diversions share a name space; see section “Iden‐ tifiers” above. Internally, the same mechanism is used to store them. You can thus call a macro with string interpolation syntax and vice versa. Interpolating a string does not hide existing macro arguments. The sequence \\ can be placed at the end of a line in a macro defini‐ tion or, within a macro definition, immediately after the interpolation of a macro as a string to suppress the effect of a newline. Environments Environments store most of the parameters that control text processing. A default environment named “0” exists when troff starts up; it is mod‐ ified by formatting‐related requests and escape sequences. You can create new environments and switch among them. Only one is current at any given time. Active environments are managed using a stack, a data structure supporting “push” and “pop” operations. The current environment is at the top of the stack. The same environment name can be pushed onto the stack multiple times, possibly interleaved with others. Popping the environment stack does not destroy the cur‐ rent environment; it remains accessible by name and can be made current again by pushing it at any time. Environments cannot be renamed or deleted, and can only be modified when current. To inspect the envi‐ ronment stack, use the pev request; see section “Debugging” below. Environments store the following information. • a partially collected line, if any • data about the most recently output glyph and line (registers .cdp, .cht, .csk, .n, .w) • typeface parameters (size, family, style, height and slant, inter‐ word and inter‐sentence space sizes) • page parameters (line length, title length, vertical spacing, line spacing, indentation, line numbering, centering, right‐alignment, un‐ derlining, hyphenation parameters) • filling enablement; adjustment enablement and mode • tab stops; tab, leader, escape, control, no‐break control, hyphen‐ ation, and margin characters • input line traps • stroke and fill colors The ev request pushes to and pops from the environment stack, while evc copies a named environment’s contents to the current one. Underlining In RUNOFF (see roff(7)), underlining, even of lengthy passages, was straightforward because only fixed‐pitch printing devices were tar‐ geted. Typesetter output posed a greater challenge. There exists a groff request .ul (see above) that underlines subsequent source lines on terminal devices, but on typesetters, it selects an italic font style instead. The ms macro package (see groff_ms(7)) offers a macro .UL, but it too produces the desired effect only on typesetters, and has other limitations. One could adapt ms’s approach to the construction of a macro as fol‐ lows. .de UNDERLINE . ie n \\$1\f[I]\\$2\f[P]\\$3 . el \\$1\Z'\\$2'\v'.25m'\D'l \w'\\$2'u 0'\v'-.25m'\\$3 .. If doclifter(1) makes trouble, change the macro name UNDERLINE into some 2‐letter word, like Ul. Moreover, change the form of the font se‐ lection escape sequence from \f[P] to \fP. Underlining without macro definitions If one does not want to use macro definitions, e.g., when doclifter gets lost, use the following. .ds u1 before .ds u2 in .ds u3 after .ie n \*[u1]\f[I]\*[u2]\f[P]\*[u3] .el \*[u1]\Z'\*[u2]'\v'.25m'\D'l \w'\*[u2]'u 0'\v'-.25m'\*[u3] When using doclifter, it might be necessary to change syntax forms such as \[xy] and \*[xy] to those supported by AT&T troff: \*(xy and \(xy, and so on. Then these lines could look like .ds u1 before .ds u2 in .ds u3 after .ie n \*[u1]\fI\*(u2\fP\*(u3 .el \*(u1\Z'\*(u2'\v'.25m'\D'l \w'\*(u2'u 0'\v'-.25m'\*(u3 The result looks like before _i_n after Underlining by overstriking with \(ul The \z escape sequence writes a glyph without advancing the drawing po‐ sition, enabling overstriking. Thus, \zc\(ul formats c with an under‐ rule glyph on top of it. Video terminals implement the underrule by setting a character cell’s underline attribute, so this technique works in both nroff and troff modes. Long words may then look intimidating in the input; a clarifying ap‐ proach might be to use the input line continuation escape sequence \newline to place each underlined character on its own input line. Thus, .nf \&\fB: ${\fIvar\fR\c \zo\(ul\ \zp\(ul\c \&\fIvalue\fB} .fi produces : ${varo_p_value} as output. Compatibility mode The differences between the roff language recognized by GNU troff and that of AT&T troff, as well as the device, font, and device‐independent intermediate output formats described by CSTR #54 are documented in groff_diff(7). groff provides an AT&T compatibility mode. The .cp re‐ quest and registers .C and .cp set and test the enablement of this mode. Debugging Preprocessors use the .lf request to preserve the identities of line numbers and names of input files. groff emits a variety of error diag‐ nostics and supports several categories of warning; the output of these can be selectively suppressed with .warn (and see the -E, -w, and -W options of troff(1)). A trace of the formatter’s input processing stack can be emitted when errors or warnings occur by means of troff(1)’s -b option, or produced on demand with the .backtrace re‐ quest. .tm, .tmc, and .tm1 can be used to emit customized diagnostic messages or for instrumentation while troubleshooting. .ex and .ab cause early termination with successful and error exit codes respec‐ tively, to halt further processing when continuing would be fruitless. Examine the state of the formatter with requests that write lists of defined names—macros, strings, and diversions—(.pm); environments (.pev), registers (.pnr), and page location traps (.ptr) to the stan‐ dard error stream. Authors This document was written by by Trent A. Fisher, Werner Lemberg, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. Section “Underlining” was primarily written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. “Troff User’s Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report No. 54, widely called simply “CSTR #54”, documents the language, device and font description file formats, and device‐independent output format referred to collectively in groff documentation as “AT&T troff”. “A Typesetter‐independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science Technical Report No. 97 (CSTR #97), pro‐ vides additional insights into the device and font description file formats and device‐independent output format. groff(1) is the preferred interface to the groff system; it manages the pipeline that carries a source document through preprocessors, the troff formatter, and an output driver to viewable or print‐ able form. It also exhaustively lists the man pages provided with the GNU roff system. groff_char(7) discusses character encoding issues, escape sequences that pro‐ duce glyphs, and enumerates groff’s predefined special character escape sequences. groff_diff(7) covers differences between the GNU troff formatter, its device and font description file formats, its device‐independent output format, and those of AT&T troff, whose design it reimplements. groff_font(5) describes the formats of the files that describe devices (DESC) and fonts. groff_tmac(5) surveys macro packages provided with groff, describes how docu‐ ments can take advantage of them, offers guidance on writing macro packages and using diversions, and includes historical in‐ formation on macro package naming conventions. roff(7) presents a detailed history of roff systems and summarizes con‐ cepts common to them. groff 1.23.0 29 August 2023 groff(7) ─────────────────────────────────────────────────────────────────────────────── groff_char(7) Miscellaneous Information Manual groff_char(7) Name groff_char - GNU roff special character and glyph repertoire Description The GNU roff typesetting system has a large glyph repertoire suitable for production of varied literary, professional, technical, and mathe‐ matical documents. groff works with characters; an output device ren‐ ders glyphs. groff’s input character set is restricted to that defined by the standards ISO Latin‐1 (ISO 8859‐1) and CCSID “code page” 1047 (an EBCDIC arrangement of Latin‐1). For ease of document maintenance in UTF‐8 environments, it is advisable to use only the Unicode basic Latin code points, a subset of all of the foregoing historically re‐ ferred to as US‐ASCII, which has only 94 visible, printable code points. In groff, these are termed ordinary characters. Often, many more are desired in output. AT&T troff in the 1970s faced a similar problem: the available typeset‐ ter’s glyph repertoire differed from that of the computers that con‐ trolled it. troff’s solution was a form of escape sequence known as a special character to access several dozen additional glyphs available in the fonts prepared for mounting in the phototypesetter. These glyphs were mapped onto a two‐character name space for a degree of mnemonic convenience; for example, the escape sequence \(aa encoded an acute accent and \(sc a section sign. groff has lifted historical roff limitations on special character name lengths, but recognizes and retains compatibility with the historical names. groff expands the lexicon of glyphs available by name and per‐ mits users to define their own special character escape sequences with the char request. Special character names are groff identifiers; see section “Identifiers” in groff(7). Our discussion uses the terms “glyph name” and “special character name” interchangeably; we assume no character translations or redefinitions. This document lists all of the glyph names predefined by groff’s font description files and presents the systematic notation by which it en‐ ables access to arbitrary Unicode code points and construction of com‐ posite glyphs. Glyphs listed may be unavailable, or may vary in ap‐ pearance, depending on the output device and font chosen when the page was formatted. This page was rendered for device utf8 using font R. A few escape sequences that are not groff special characters also pro‐ duce glyphs; these exist for syntactical or historical reasons. \', \`, \-, and \_ are translated on input to the special character escape sequences \[aa], \[ga], \[-], and \[ul], respectively. Others include \\, \. (backslash‐dot), and \e; see groff(7). A small number of spe‐ cial characters represent glyphs that are not encoded in Unicode; exam‐ ples include the baseline rule \[ru] and the Bell System logo \[bs]. In groff, you can test output device support for any character (ordi‐ nary or special) with the conditional expression operator “c”. .ie c \[bs] \{Welcome to the \[bs] Bell System; did you get the Wehrmacht helmet or the Death Star?\} .el No Bell System logo. For brevity in the remainder of this document, we shall refer to sys‐ tems conforming to the ISO 646:1991 IRV, ISO 8859, or ISO 10646 (“Uni‐ code”) character encoding standards as “ISO” systems, and those employ‐ ing IBM code page 1047 as “EBCDIC” systems. That said, EBCDIC systems that support groff are known to also support UTF‐8. While groff accepts eight‐bit encoded input, not all such code points are valid as input. On ISO platforms, character codes 0, 11, 13–31, and 128–159 are invalid. (This is all C0 and C1 controls except for SOH through LF [Control+A to Control+J], and FF [Control+L].) On EBCDIC platforms, 0, 8–9, 11, 13–20, 23–31, and 48–63 are invalid. Some of these code points are used by groff for internal purposes, which is one reason it does not support UTF‐8 natively. Fundamental character set The ordinary characters catalogued above, plus the space, tab, newline, and leader (Control+A), form the fundamental character set for groff input; anything in the language, even over one million code points in Unicode, can be expressed using it. On ISO systems, code points in the range 33–126 comprise a common set of printable glyphs in all of the aforementioned ISO character encoding standards. It is this character set and (with some noteworthy exceptions) the corresponding glyph repertoire for which AT&T troff was implemented. On EBCDIC systems, printable characters are in the range 66–201 and 203–254; those without counterparts in the ISO range 33–126 are discussed in the next subsec‐ tion. All of the following characters map to glyphs as you would expect. ┌───────────────────────────────────────────────────────────┐ │ ! # $ % & ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ │ │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] _ │ │ a b c d e f g h i j k l m n o p q r s t u v w x y z { | } │ └───────────────────────────────────────────────────────────┘ The remaining ordinary characters surprise computing professionals and others intimately familiar with the ISO character encodings. The de‐ velopers of AT&T troff chose mappings for them that would be useful for typesetting technical literature in a broad range of scientific disci‐ plines: Bell Labs used the system for preparation of AT&T’s patent fil‐ ings with the U.S. government. Further, the prevailing character en‐ coding standard in the 1970s, USAS X3.4‐1968 (“ASCII”), deliberately supported semantic ambiguity at some code points, and outright substi‐ tution at several others, to suit the localization demands of various national standards bodies. The table below presents the seven exceptional code points with their typical keycap engravings, their glyph mappings and semantics in roff systems, and the escape sequences producing the Unicode basic Latin character they replace. The first, the neutral double quote, is a par‐ tial exception because it does represent itself, but since the roff language also uses it to quote macro arguments, groff supports a spe‐ cial character escape sequence as an alternative form so that the glyph can be easily included in macro arguments without requiring the user to master the quoting rules that AT&T troff required in that context. (Some requests, like ds, also treat " non‐literally.) Furthermore, not all of the special character escape sequences are portable to AT&T troff and all of its descendants; these groff extensions are presented using its special character form \[], whereas portable special charac‐ ter escape sequences are shown in the traditional \( form. \- and \e are portable to all known troffs. \e means “the glyph of the current escape character”; it therefore can produce unexpected output if the ec request is used. On devices with a limited glyph repertoire, glyphs in the “keycap” and “appearance” columns on the same row of the table may look identical; except for the neutral double quote, this will not be the case on more‐capable devices. Review your document using as many different output devices as possible. ┌───────────────────────────────────────────────────────────────────┐ │ Keycap Appearance and meaning Special character and meaning │ ├───────────────────────────────────────────────────────────────────┤ │ " " neutral double quote \[dq] neutral double quote │ │ ' ’ closing single quote \[aq] neutral apostrophe │ │ - ‐ hyphen \- or \[-] minus sign/Unix dash │ │ \ (escape character) \e or \[rs] reverse solidus │ │ ^ ˆ modifier circumflex \(ha circumflex/caret/“hat” │ │ ` ‘ opening single quote \(ga grave accent │ │ ~ ˜ modifier tilde \(ti tilde │ └───────────────────────────────────────────────────────────────────┘ The hyphen‐minus is a particularly unfortunate case of overloading. Its awkward name in ISO 8859 and later standards reflects the many dis‐ tinguishable purposes to which it had already been put by the 1980s, including a hyphen, a minus sign, and (alone or in repetition) dashes of varying widths. For best results in roff systems, use the “-” char‐ acter in input outside an escape sequence only to mean a hyphen, as in the phrase “long‐term”. For a minus sign in running text or a Unix command‐line option dash, use \- (or \[-] in groff if you find it helps the clarity of the source document). (Another minus sign, for use in mathematical equations, is available as \[mi]). AT&T troff supported em‐dashes as \(em, as does groff. The special character escape sequence for the apostrophe as a neutral single quote is typically needed only in technical content; typing words like “can’t” and “Anne’s” in a natural way will render correctly, because in ordinary prose an apostrophe is typeset either as a closing single quotation mark or as a neutral single quote, depending on the capabilities of the output device. By contrast, special character es‐ cape sequences should be used for quotation marks unless portability to limited or historical troff implementations is necessary; on those sys‐ tems, the input convention is to pair the grave accent with the apos‐ trophe for single quotes, and to double both characters for double quotes. AT&T troff defined no special characters for quotation marks or the apostrophe. Repeated single quotes (‘‘thus’’) will be visually distinguishable from double quotes (“thus”) on terminal devices, and perhaps on others (depending on the font selected). ┌─────────────────────────────────────────────────────────────────┐ │ AT&T troff input recommended groff input │ ├─────────────────────────────────────────────────────────────────┤ │ A Winter's Tale A Winter's Tale │ │ `U.K. outer quotes' \[oq]U.K. outer quotes\[cq] │ │ `U.K. ``inner'' quotes' \[oq]U.K. \[lq]inner\[rq] quotes\[cq] │ │ ``U.S. outer quotes'' \[lq]U.S. outer quotes\[rq] │ │ ``U.S. `inner' quotes'' \[lq]U.S. \[oq]inner\[cq] quotes\[rq] │ └─────────────────────────────────────────────────────────────────┘ If you frequently require quotation marks in your document, see if the macro package you’re using supplies strings or macros to facilitate quotation, or define them yourself (except in man pages). Using Unicode basic Latin characters to compose boxes and lines is ill‐ advised. roff systems have special characters for drawing horizontal and vertical lines; see subsection “Rules and lines” below. Preproces‐ sors like tbl(1) and pic(1) draw boxes and will produce the best possi‐ ble output for the device, falling back to basic Latin glyphs only when necessary. Eight‐bit encodings and Latin‐1 supplement ISO 646 is a seven‐bit code encoding 128 code points; eight‐bit codes are twice the size. ISO 8859‐1 and code page 1047 allocated the addi‐ tional space to what Unicode calls “C1 controls” (control characters) and the “Latin‐1 supplement”. The C1 controls are neither printable nor usable as groff input. Two Latin‐1 supplement characters are handled specially on input. troff never produces them as output. NBSP encodes a no‐break space; it is mapped to \~, the adjustable non‐breaking space escape sequence. SHY encodes a soft hyphen; it is mapped to \%, the hyphenation con‐ trol escape sequence. The remaining characters in the Latin‐1 supplement represent them‐ selves. Although they can be specified directly with the keyboard on systems configured to use Latin‐1 as the character encoding, it is more portable, both to other roff systems and to UTF‐8 environments, to use their special character escape sequences, shown below. The glyph de‐ scriptions we use are non‐standard in some cases, for brevity. ¡ \[r!] inverted exclamation mark Ñ \[~N] N tilde ¢ \[ct] cent sign Ò \[`O] O grave £ \[Po] pound sign Ó \['O] O acute ¤ \[Cs] currency sign Ô \[^O] O circumflex ¥ \[Ye] yen sign Õ \[~O] O tilde ¦ \[bb] broken bar Ö \[:O] O dieresis § \[sc] section sign × \[mu] multiplication sign ¨ \[ad] dieresis accent Ø \[/O] O slash © \[co] copyright sign Ù \[`U] U grave ª \[Of] feminine ordinal indicator Ú \['U] U acute « \[Fo] left double chevron Û \[^U] U circumflex ¬ \[no] logical not Ü \[:U] U dieresis ® \[rg] registered sign Ý \['Y] Y acute ¯ \[a-] macron accent Þ \[TP] uppercase thorn ° \[de] degree sign ß \[ss] lowercase sharp s ± \[+-] plus‐minus à \[`a] a grave ² \[S2] superscript two á \['a] a acute ³ \[S3] superscript three â \[^a] a circumflex ´ \[aa] acute accent ã \[~a] a tilde µ \[mc] micro sign ä \[:a] a dieresis ¶ \[ps] pilcrow sign å \[oa] a ring · \[pc] centered period æ \[ae] ae ligature ¸ \[ac] cedilla accent ç \[,c] c cedilla ¹ \[S1] superscript one è \[`e] e grave º \[Om] masculine ordinal indicator é \['e] e acute » \[Fc] right double chevron ê \[^e] e circumflex ¼ \[14] one quarter symbol ë \[:e] e dieresis ½ \[12] one half symbol ì \[`i] i grave ¾ \[34] three quarters symbol í \['i] e acute ¿ \[r?] inverted question mark î \[^i] i circumflex À \[`A] A grave ï \[:i] i dieresis Á \['A] A acute ð \[Sd] lowercase eth  \[^A] A circumflex ñ \[~n] n tilde à \[~A] A tilde ò \[`o] o grave Ä \[:A] A dieresis ó \['o] o acute Å \[oA] A ring ô \[^o] o circumflex Æ \[AE] AE ligature õ \[~o] o tilde Ç \[,C] C cedilla ö \[:o] o dieresis È \[`E] E grave ÷ \[di] division sign É \['E] E acute ø \[/o] o slash Ê \[^E] E circumflex ù \[`u] u grave Ë \[:E] E dieresis ú \['u] u acute Ì \[`I] I grave û \[^u] u circumflex Í \['I] I acute ü \[:u] u dieresis Î \[^I] I circumflex ý \['y] y acute Ï \[:I] I dieresis þ \[Tp] lowercase thorn Ð \[-D] uppercase eth ÿ \[:y] y dieresis Special character escape forms Glyphs that lack a character code in the basic Latin repertoire to di‐ rectly represent them are entered by one of several special character escape forms. Such glyphs can be simple or composite, and accessed ei‐ ther by name or numerically by code point. Code points and combining properties are determined by character encoding standards, whereas glyph names as used here originated in AT&T troff special character es‐ cape sequences. Predefined glyph names use only characters in the ba‐ sic Latin repertoire. \(gl is a special character escape sequence for the glyph with the two‐character name gl. This is the original syntax form sup‐ ported by AT&T troff. The acute accent, \(aa, is an example. \C'glyph‐name' is a special character escape sequence for glyph‐name, which can be of arbitrary length. The delimiter, shown here as a neutral apostrophe, can be any character not occurring in glyph‐name. This syntax form was introduced in later versions of AT&T de‐ vice‐independent troff. The foregoing acute accent example can be expressed as \C'aa'. \[glyph‐name] is a special character escape sequence for glyph‐name, which can be of arbitrary length but must not contain a closing square bracket “]”. (No glyph names predefined by groff employ “]”.) The foregoing acute accent example can be expressed in groff as \[aa]. \C'c' and \[c] are not synonyms for the ordinary character “c”, but re‐ quest the special character named “\c”. For example, “\[a]” is not “a”, but rather a special character with the internal glyph name (used in font description files and diagnostic messages) \a, which is typi‐ cally undefined. The only such glyph name groff predefines is the mi‐ nus sign, which can therefore be accessed as \C'-' or \[-]. \[base‐char composite‐1 composite‐2 ... composite‐n] is a composite glyph. Glyphs like a lowercase “e” with an acute accent, as in the word “café”, can be expressed as \[e aa]. See subsection “Accents” below for a table of combining glyph names. Unicode encodes far more characters than groff has glyph names for; special character escape forms based on numerical code points enable access to any of them. Frequently used glyphs or glyph combinations can be stored in strings, and new glyph names can be created ad hoc with the char request; see groff(7). \[unnnn[n[n]]] is a Unicode numeric special character escape sequence. Any Unicode code point can be accessed with four to six hexadecimal digits, with hexadecimal letters accepted in uppercase form only. Thus, \[u02DA] accesses the (spacing) ring accent, pro‐ ducing “˚”. Unicode code points can be composed as well; when they are, GNU troff requires NFD (Normalization Form D), where all Unicode glyphs are maxi‐ mally decomposed. (Exception: precomposed characters in the Latin‐1 supplement described above are also accepted. Do not count on this ex‐ ception remaining in a future GNU troff that accepts UTF‐8 input di‐ rectly.) Thus, GNU troff accepts “caf\['e]”, “caf\[e aa]”, and “caf\[u0065_0301]”, as ways to input “café”. (Due to its legacy 8‐bit encoding compatibility, at present it also accepts “caf\[u00E9]” on ISO Latin‐1 systems.) \[ubase‐char[_combining‐component]...] constructs a composite glyph from Unicode numeric special char‐ acter escape sequences. The code points of the base glyph and the combining components are each expressed in hexadecimal, with an underscore (_) separating each component. Thus, \[u006E_0303] produces “ñ”. \[charnnn] expresses an eight‐bit code point where nnn is the code point of the character, a decimal number between 0 and 255 without lead‐ ing zeroes. This legacy numeric special character escape se‐ quence is used to map characters onto glyphs via the trin re‐ quest in macro files loaded by grotty(1). Glyph tables In this section, groff’s glyph name repertoire is presented in tabular form. The meanings of the columns are as follows. Output shows the glyph as it appears on the device used to render this document; although it can have a notably different shape on other devices (and is subject to user‐directed translation and replacement), groff attempts reasonable equivalency on all out‐ put devices. Input shows the groff character (ordinary or special) that normally produces the glyph. Some code points have multiple glyph names. Unicode is the code point notation for the glyph or combining glyph se‐ quence as described in subsection “Special character escape forms” above. It corresponds to the standard notation for Uni‐ code short identifiers such that groff’s unnnn is equivalent to Unicode’s U+nnnn. Notes describes the glyph, elucidating the mnemonic value of the glyph name where possible. A plus sign “+” indicates that the glyph name appears in the AT&T troff user’s manual, CSTR #54 (1992 revision). When using the AT&T special character syntax \(xx, widespread portability can be expected from such names. Entries marked with “***” denote glyphs used for mathematical purposes. On typesetting devices, such glyphs are typically drawn from a special font (see groff_font(5)). Often, such glyphs lack bold or italic style forms or have metrics that look incongruous in ordinary prose. A few which are not uncom‐ mon in running text have “text variants”, which should work better in that context. Conversely, a handful of glyphs that are normally drawn from a text font may be required in mathe‐ matical equations. Both sets of exceptions are noted in the tables where they appear (“Logical symbols” and “Mathematical symbols”). Basic Latin Apart from basic Latin characters with special mappings, described in subsection “Fundamental character set” above, a few others in that range have special character glyph names. These were defined for ease of input on non‐U.S. keyboards lacking keycaps for them, or for symme‐ try with other special character glyph names serving a similar purpose. The vertical bar is overloaded; the \[ba] and \[or] escape sequences may render differently. See subsection “Mathematical symbols” below for special variants of the plus, minus, and equals signs normally drawn from this range. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── " \[dq] u0022 neutral double quote # \[sh] u0023 number sign $ \[Do] u0024 dollar sign ' \[aq] u0027 apostrophe, neutral single quote / \[sl] u002F slash, solidus + @ \[at] u0040 at sign [ \[lB] u005B left square bracket \ \[rs] u005C reverse solidus ] \[rB] u005D right square bracket ^ \[ha] u005E circumflex, caret, “hat” { \[lC] u007B left brace | | u007C bar | \[ba] u007C bar | \[or] u007C bitwise or + } \[rC] u007D right brace ~ \[ti] u007E tilde Supplementary Latin letters Historically, \[ss] could be considered a ligature of “sz”. An upper‐ case form is available as \[u1E9E], but in the German language it is of specialized use; ß does not normally uppercase‐transform to it, but rather to “SS”. “Lowercase f with hook” is also used as a function symbol; see subsection “Mathematical symbols” below. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── Ð \[-D] u00D0 uppercase eth ð \[Sd] u00F0 lowercase eth Þ \[TP] u00DE uppercase thorn þ \[Tp] u00FE lowercase thorn ß \[ss] u00DF lowercase sharp s ı \[.i] u0131 i without tittle ȷ \[.j] u0237 j without tittle ƒ \[Fn] u0192 lowercase f with hook, function Ł \[/L] u0141 L with stroke ł \[/l] u0142 l with stroke Ø \[/O] u00D8 O with stroke ø \[/o] u00F8 o with stroke Ligatures and digraphs Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ff \[ff] u0066_0066 ff ligature + fi \[fi] u0066_0069 fi ligature + fl \[fl] u0066_006C fl ligature + ffi \[Fi] u0066_0066_0069 ffi ligature + ffl \[Fl] u0066_0066_006C ffl ligature + Æ \[AE] u00C6 AE ligature æ \[ae] u00E6 ae ligature Œ \[OE] u0152 OE ligature œ \[oe] u0153 oe ligature IJ \[IJ] u0132 IJ digraph ij \[ij] u0133 ij digraph Accents Normally, the formatting of a special character advances the drawing position as an ordinary character does. groff’s composite request des‐ ignates a special character as combining. The composite.tmac macro file, loaded automatically by the default troffrc, maps the following special characters to the combining characters shown below. The non‐ combining code point in parentheses is used when the special character occurs in isolation (compare “caf\[e aa]” and “caf\[aa]e”). Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ˝ \[a"] u030B (u02DD) double acute accent ¯ \[a-] u0304 (u00AF) macron accent ˙ \[a.] u0307 (u02D9) dot accent ^ \[a^] u0302 (u005E) circumflex accent ´ \[aa] u0301 (u00B4) acute accent + ` \[ga] u0300 (u0060) grave accent + ˘ \[ab] u0306 (u02D8) breve accent ¸ \[ac] u0327 (u00B8) cedilla accent ¨ \[ad] u0308 (u00A8) dieresis accent ˇ \[ah] u030C (u02C7) caron accent ˚ \[ao] u030A (u02DA) ring accent ~ \[a~] u0303 (u007E) tilde accent ˛ \[ho] u0328 (u02DB) hook accent Accented characters All of these glyphs can be composed using combining glyph names as de‐ scribed in subsection “Special character escape forms” above; the names below are short aliases for convenience. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── Á \['A] u0041_0301 A acute Ć \['C] u0043_0301 C acute É \['E] u0045_0301 E acute Í \['I] u0049_0301 I acute Ó \['O] u004F_0301 O acute Ú \['U] u0055_0301 U acute Ý \['Y] u0059_0301 Y acute á \['a] u0061_0301 a acute ć \['c] u0063_0301 c acute é \['e] u0065_0301 e acute í \['i] u0069_0301 i acute ó \['o] u006F_0301 o acute ú \['u] u0075_0301 u acute ý \['y] u0079_0301 y acute Ä \[:A] u0041_0308 A dieresis Ë \[:E] u0045_0308 E dieresis Ï \[:I] u0049_0308 I dieresis Ö \[:O] u004F_0308 O dieresis Ü \[:U] u0055_0308 U dieresis Ÿ \[:Y] u0059_0308 Y dieresis ä \[:a] u0061_0308 a dieresis ë \[:e] u0065_0308 e dieresis ï \[:i] u0069_0308 i dieresis ö \[:o] u006F_0308 o dieresis ü \[:u] u0075_0308 u dieresis ÿ \[:y] u0079_0308 y dieresis  \[^A] u0041_0302 A circumflex Ê \[^E] u0045_0302 E circumflex Î \[^I] u0049_0302 I circumflex Ô \[^O] u004F_0302 O circumflex Û \[^U] u0055_0302 U circumflex â \[^a] u0061_0302 a circumflex ê \[^e] u0065_0302 e circumflex î \[^i] u0069_0302 i circumflex ô \[^o] u006F_0302 o circumflex û \[^u] u0075_0302 u circumflex À \[`A] u0041_0300 A grave È \[`E] u0045_0300 E grave Ì \[`I] u0049_0300 I grave Ò \[`O] u004F_0300 O grave Ù \[`U] u0055_0300 U grave à \[`a] u0061_0300 a grave è \[`e] u0065_0300 e grave ì \[`i] u0069_0300 i grave ò \[`o] u006F_0300 o grave ù \[`u] u0075_0300 u grave à \[~A] u0041_0303 A tilde Ñ \[~N] u004E_0303 N tilde Õ \[~O] u004F_0303 O tilde ã \[~a] u0061_0303 a tilde ñ \[~n] u006E_0303 n tilde õ \[~o] u006F_0303 o tilde Š \[vS] u0053_030C S caron š \[vs] u0073_030C s caron Ž \[vZ] u005A_030C Z caron ž \[vz] u007A_030C z caron Ç \[,C] u0043_0327 C cedilla ç \[,c] u0063_0327 c cedilla Å \[oA] u0041_030A A ring å \[oa] u0061_030A a ring Quotation marks The neutral double quote, often useful when documenting programming languages, is also available as a special character for convenient em‐ bedding in macro arguments; see subsection “Fundamental character set” above. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── „ \[Bq] u201E low double comma quote ‚ \[bq] u201A low single comma quote “ \[lq] u201C left double quote ” \[rq] u201D right double quote ‘ \[oq] u2018 single opening (left) quote ’ \[cq] u2019 single closing (right) quote ' \[aq] u0027 apostrophe, neutral single quote " " u0022 neutral double quote " \[dq] u0022 neutral double quote « \[Fo] u00AB left double chevron » \[Fc] u00BB right double chevron ‹ \[fo] u2039 left single chevron › \[fc] u203A right single chevron Punctuation The Unicode name for U+00B7 is “middle dot”, which is unfortunately confusable with the groff mnemonic for the visually similar but seman‐ tically distinct multiplication dot; see subsection “Mathematical sym‐ bols” below. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ¡ \[r!] u00A1 inverted exclamation mark ¿ \[r?] u00BF inverted question mark · \[pc] u00B7 centered period — \[em] u2014 em‐dash + – \[en] u2013 en‐dash ‐ \[hy] u2010 hyphen + Brackets On typesetting devices, the bracket extensions are font‐invariant glyphs; that is, they are rendered the same way regardless of font (with a drawing escape sequence). On terminals, they are not font‐in‐ variant; groff maps them rather arbitrarily to U+23AA (“curly bracket extension”). In AT&T troff, only one glyph was available to vertically extend brackets, braces, and parentheses: \(bv. Not all devices supply bracket pieces that can be piled up with \b due to the restrictions of the escape’s piling algorithm. A general solu‐ tion to build brackets out of pieces is the following macro: .\" Make a pile centered vertically 0.5em above the baseline. .\" The first argument is placed at the top. .\" The pile is returned in string 'pile'. .eo .de pile-make . nr pile-wd 0 . nr pile-ht 0 . ds pile-args . . nr pile-# \n[.$] . while \n[pile-#] \{\ . nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]') . nr pile-ht +(\n[rst] - \n[rsb]) . as pile-args \v'\n[rsb]u'\" . as pile-args \Z'\$[\n[pile-#]]'\" . as pile-args \v'-\n[rst]u'\" . nr pile-# -1 . \} . . ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\" . as pile \*[pile-args]\" . as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\" . as pile \h'\n[pile-wd]u'\" .. .ec Another complication is the fact that some glyphs which represent bracket pieces in AT&T troff can be used for other mathematical symbols as well, for example \(lf and \(rf, which provide the floor operator. Some output devices, such as dvi, don’t unify such glyphs. For this reason, the glyphs \[lf], \[rf], \[lc], and \[rc] are not unified with similar‐looking bracket pieces. In groff, only glyphs with long names are guaranteed to pile up correctly for all devices—provided those glyphs are available. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── [ [ u005B left square bracket [ \[lB] u005B left square bracket ] ] u005D right square bracket ] \[rB] u005D right square bracket { { u007B left brace { \[lC] u007B left brace } } u007D right brace } \[rC] u007D right brace ⟨ \[la] u27E8 left angle bracket ⟩ \[ra] u27E9 right angle bracket ⎪ \[bv] u23AA brace vertical extension + *** ⎪ \[braceex] u23AA brace vertical extension ⎡ \[bracketlefttp] u23A1 left square bracket top ⎢ \[bracketleftex] u23A2 left square bracket extension ⎣ \[bracketleftbt] u23A3 left square bracket bottom ⎤ \[bracketrighttp] u23A4 right square bracket top ⎥ \[bracketrightex] u23A5 right square bracket extension ⎦ \[bracketrightbt] u23A6 right square bracket bottom ⎧ \[lt] u23A7 left brace top + ⎨ \[lk] u23A8 left brace middle + ⎩ \[lb] u23A9 left brace bottom + ⎧ \[bracelefttp] u23A7 left brace top ⎨ \[braceleftmid] u23A8 left brace middle ⎩ \[braceleftbt] u23A9 left brace bottom ⎪ \[braceleftex] u23AA left brace extension ⎫ \[rt] u23AB right brace top + ⎬ \[rk] u23AC right brace middle + ⎭ \[rb] u23AD right brace bottom + ⎫ \[bracerighttp] u23AB right brace top ⎬ \[bracerightmid] u23AC right brace middle ⎭ \[bracerightbt] u23AD right brace bottom ⎪ \[bracerightex] u23AA right brace extension ⎛ \[parenlefttp] u239B left parenthesis top ⎜ \[parenleftex] u239C left parenthesis extension ⎝ \[parenleftbt] u239D left parenthesis bottom ⎞ \[parenrighttp] u239E right parenthesis top ⎟ \[parenrightex] u239F right parenthesis extension ⎠ \[parenrightbt] u23A0 right parenthesis bottom Arrows Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ← \[<-] u2190 horizontal arrow left + → \[->] u2192 horizontal arrow right + ↔ \[<>] u2194 bidirectional horizontal arrow ↓ \[da] u2193 vertical arrow down + ↑ \[ua] u2191 vertical arrow up + ↕ \[va] u2195 bidirectional vertical arrow ⇐ \[lA] u21D0 horizontal double arrow left ⇒ \[rA] u21D2 horizontal double arrow right ⇔ \[hA] u21D4 bidirectional horizontal double arrow ⇓ \[dA] u21D3 vertical double arrow down ⇑ \[uA] u21D1 vertical double arrow up ⇕ \[vA] u21D5 bidirectional vertical double arrow ⎯ \[an] u23AF horizontal arrow extension Rules and lines On typesetting devices, the font‐invariant glyphs (see subsection “Brackets” above) \[br], \[ul], and \[rn] form corners when adjacent; they can be used to build boxes. On terminal devices, they are mapped as shown in the table. The Unicode‐derived names of these three glyphs are approximations. The input character _ always accesses the underscore glyph in a font; \[ul], by contrast, may be font‐invariant on typesetting devices. The baseline rule \[ru] is a font‐invariant glyph, namely a rule of one‐half em. In AT&T troff, \[rn] also served as a one en extension of the square root symbol. groff favors \[radicalex] for this purpose; see subsec‐ tion “Mathematical symbols” below. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── | | u007C bar | \[ba] u007C bar │ \[br] u2502 box rule + _ _ u005F underscore, low line + _ \[ul] ‐‐‐ underrule + ‾ \[rn] u203E overline + _ \[ru] ‐‐‐ baseline rule + ¦ \[bb] u00A6 broken bar / / u002F slash, solidus + / \[sl] u002F slash, solidus + \ \[rs] u005C reverse solidus Text markers Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ○ \[ci] u25CB circle + • \[bu] u2022 bullet + † \[dg] u2020 dagger + ‡ \[dd] u2021 double dagger + ◊ \[lz] u25CA lozenge, diamond □ \[sq] u25A1 square + ¶ \[ps] u00B6 pilcrow sign § \[sc] u00A7 section sign + ☜ \[lh] u261C hand pointing left + ☞ \[rh] u261E hand pointing right + @ @ u0040 at sign @ \[at] u0040 at sign # # u0023 number sign # \[sh] u0023 number sign ↵ \[CR] u21B5 carriage return ✓ \[OK] u2713 check mark Legal symbols The Bell System logo is not supported in groff. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── © \[co] u00A9 copyright sign + ® \[rg] u00AE registered sign + ™ \[tm] u2122 trade mark sign \[bs] ‐‐‐ Bell System logo + Currency symbols Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── $ $ u0024 dollar sign $ \[Do] u0024 dollar sign ¢ \[ct] u00A2 cent sign + € \[eu] u20AC Euro sign € \[Eu] u20AC variant Euro sign ¥ \[Ye] u00A5 yen sign £ \[Po] u00A3 pound sign ¤ \[Cs] u00A4 currency sign Units Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ° \[de] u00B0 degree sign + ‰ \[%0] u2030 per thousand, per mille sign ′ \[fm] u2032 arc minute sign, foot mark + ″ \[sd] u2033 arc second sign µ \[mc] u00B5 micro sign ª \[Of] u00AA feminine ordinal indicator º \[Om] u00BA masculine ordinal indicator Logical symbols The variants of the not sign may differ in appearance or spacing de‐ pending on the device and font selected. Unicode does not encode a discrete “bitwise or” sign: on typesetting devices, it is drawn shorter than the bar, about the same height as a capital letter. Terminal de‐ vices unify \[ba] and \[or]. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ∧ \[AN] u2227 logical and ∨ \[OR] u2228 logical or ¬ \[no] u00AC logical not + *** ¬ \[tno] u00AC text variant of \[no] ∃ \[te] u2203 there exists ∀ \[fa] u2200 for all ∋ \[st] u220B such that ∴ \[3d] u2234 therefore ∴ \[tf] u2234 therefore | | u007C bar | \[or] u007C bitwise or + Mathematical symbols \[Fn] also appears in subsection “Supplementary Latin letters” above. Observe the two varieties of the plus‐minus, multiplication, and divi‐ sion signs; \[+-], \[mu], and \[di] are normally drawn from the special font, but have text font variants. Also be aware of three glyphs available in special font variants that are normally drawn from text fonts: the plus, minus, and equals signs. These variants may differ in appearance or spacing depending on the device and font selected. In AT&T troff, \(rn (“root en extender”) served as the horizontal ex‐ tension of the radical (square root) sign, \(sr, and was drawn at the maximum height of the typeface’s bounding box; this enabled the special character to double as an overline (see subsection “Rules and lines” above). A contemporary font’s radical sign might not ascend to such an extreme. In groff, you can instead use \[radicalex] to continue the radical sign \[sr]; these special characters are intended for use with text fonts. \[sqrt] and \[sqrtex] are their counterparts with mathe‐ matical spacing. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ½ \[12] u00BD one half symbol + ¼ \[14] u00BC one quarter symbol + ¾ \[34] u00BE three quarters symbol + ⅛ \[18] u215B one eighth symbol ⅜ \[38] u215C three eighths symbol ⅝ \[58] u215D five eighths symbol ⅞ \[78] u215E seven eighths symbol ¹ \[S1] u00B9 superscript one ² \[S2] u00B2 superscript two ³ \[S3] u00B3 superscript three + + u002B plus + \[pl] u002B special variant of plus + *** - \[-] u002D minus − \[mi] u2212 special variant of minus + *** ∓ \[-+] u2213 minus‐plus ± \[+-] u00B1 plus‐minus + *** ± \[t+-] u00B1 text variant of \[+-] ⋅ \[md] u22C5 multiplication dot × \[mu] u00D7 multiplication sign + *** × \[tmu] u00D7 text variant of \[mu] ⊗ \[c*] u2297 circled times ⊕ \[c+] u2295 circled plus ÷ \[di] u00F7 division sign + *** ÷ \[tdi] u00F7 text variant of \[di] ⁄ \[f/] u2044 fraction slash * * u002A asterisk ∗ \[**] u2217 mathematical asterisk + ≤ \[<=] u2264 less than or equal to + ≥ \[>=] u2265 greater than or equal to + ≪ \[<<] u226A much less than ≫ \[>>] u226B much greater than = = u003D equals = \[eq] u003D special variant of equals + *** ≠ \[!=] u003D_0338 not equals + ≡ \[==] u2261 equivalent + ≢ \[ne] u2261_0338 not equivalent ≅ \[=~] u2245 approximately equal to ≃ \[|=] u2243 asymptotically equal to + ~ \[ti] u007E tilde + ∼ \[ap] u223C similar to, tilde operator + ≈ \[~~] u2248 almost equal to ≈ \[~=] u2248 almost equal to ∝ \[pt] u221D proportional to + ∅ \[es] u2205 empty set + ∈ \[mo] u2208 element of a set + ∉ \[nm] u2208_0338 not element of set ⊂ \[sb] u2282 proper subset + ⊄ \[nb] u2282_0338 not subset ⊃ \[sp] u2283 proper superset + ⊅ \[nc] u2283_0338 not superset ⊆ \[ib] u2286 subset or equal + ⊇ \[ip] u2287 superset or equal + ∩ \[ca] u2229 intersection, cap + ∪ \[cu] u222A union, cup + ∠ \[/_] u2220 angle ⊥ \[pp] u22A5 perpendicular ∫ \[is] u222B integral + ∫ \[integral] u222B integral *** ∑ \[sum] u2211 summation *** ∏ \[product] u220F product *** ∐ \[coproduct] u2210 coproduct *** ∇ \[gr] u2207 gradient + √ \[sr] u221A radical sign, square root + ‾ \[rn] u203E overline + ‾ \[radicalex] ‐‐‐ radical extension √ \[sqrt] u221A radical sign, square root *** ‾ \[sqrtex] ‐‐‐ radical extension *** ⌈ \[lc] u2308 left ceiling + ⌉ \[rc] u2309 right ceiling + ⌊ \[lf] u230A left floor + ⌋ \[rf] u230B right floor + ∞ \[if] u221E infinity + ℵ \[Ah] u2135 aleph symbol ƒ \[Fn] u0192 lowercase f with hook, function ℑ \[Im] u2111 blackletter I, imaginary part ℜ \[Re] u211C blackletter R, real part ℘ \[wp] u2118 Weierstrass p ∂ \[pd] u2202 partial differential ℏ \[-h] u210F h bar ℏ \[hbar] u210F h bar Greek glyphs These glyphs are intended for technical use, not for typesetting Greek language text; normally, the uppercase letters have upright shape, and the lowercase ones are slanted. Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── Α \[*A] u0391 uppercase alpha + Β \[*B] u0392 uppercase beta + Γ \[*G] u0393 uppercase gamma + Δ \[*D] u0394 uppercase delta + Ε \[*E] u0395 uppercase epsilon + Ζ \[*Z] u0396 uppercase zeta + Η \[*Y] u0397 uppercase eta + Θ \[*H] u0398 uppercase theta + Ι \[*I] u0399 uppercase iota + Κ \[*K] u039A uppercase kappa + Λ \[*L] u039B uppercase lambda + Μ \[*M] u039C uppercase mu + Ν \[*N] u039D uppercase nu + Ξ \[*C] u039E uppercase xi + Ο \[*O] u039F uppercase omicron + Π \[*P] u03A0 uppercase pi + Ρ \[*R] u03A1 uppercase rho + Σ \[*S] u03A3 uppercase sigma + Τ \[*T] u03A4 uppercase tau + Υ \[*U] u03A5 uppercase upsilon + Φ \[*F] u03A6 uppercase phi + Χ \[*X] u03A7 uppercase chi + Ψ \[*Q] u03A8 uppercase psi + Ω \[*W] u03A9 uppercase omega + α \[*a] u03B1 lowercase alpha + β \[*b] u03B2 lowercase beta + γ \[*g] u03B3 lowercase gamma + δ \[*d] u03B4 lowercase delta + ε \[*e] u03B5 lowercase epsilon + ζ \[*z] u03B6 lowercase zeta + η \[*y] u03B7 lowercase eta + θ \[*h] u03B8 lowercase theta + ι \[*i] u03B9 lowercase iota + κ \[*k] u03BA lowercase kappa + λ \[*l] u03BB lowercase lambda + μ \[*m] u03BC lowercase mu + ν \[*n] u03BD lowercase nu + ξ \[*c] u03BE lowercase xi + ο \[*o] u03BF lowercase omicron + π \[*p] u03C0 lowercase pi + ρ \[*r] u03C1 lowercase rho + σ \[*s] u03C3 lowercase sigma + τ \[*t] u03C4 lowercase tau + υ \[*u] u03C5 lowercase upsilon + ϕ \[*f] u03D5 lowercase phi + χ \[*x] u03C7 lowercase chi + ψ \[*q] u03C8 lowercase psi + ω \[*w] u03C9 lowercase omega + ϵ \[+e] u03F5 variant epsilon (lunate) ϑ \[+h] u03D1 variant theta (cursive form) ϖ \[+p] u03D6 variant pi (similar to omega) φ \[+f] u03C6 variant phi (curly shape) ς \[ts] u03C2 terminal lowercase sigma + Playing card symbols Output Input Unicode Notes ──────────────────────────────────────────────────────────────────────── ♣ \[CL] u2663 solid club suit ♠ \[SP] u2660 solid spade suit ♥ \[HE] u2665 solid heart suit ♦ \[DI] u2666 solid diamond suit History A consideration of the typefaces originally available to AT&T nroff and troff illuminates many conventions that one might regard as idiosyn‐ cratic fifty years afterward. (See section “History” of roff(7) for more context.) The face used by the Teletype Model 37 terminals of the Murray Hill Unix Room was based on ASCII, but assigned multiple mean‐ ings to several code points, as suggested by that standard. Decimal 34 (") served as a dieresis accent and neutral double quotation mark; dec‐ imal 39 (') as an acute accent, apostrophe, and closing (right) single quotation mark; decimal 45 (-) as a hyphen and a minus sign; decimal 94 (^) as a circumflex accent and caret; decimal 96 (`) as a grave accent and opening (left) single quotation mark; and decimal 126 (~) as a tilde accent and (with a half‐line motion) swung dash. The Model 37 bore an optional extended character set offering upright Greek letters and several mathematical symbols; these were documented as early as the kbd(VII) man page of the (First Edition) Unix Programmer’s Manual. At the time Graphic Systems delivered the C/A/T phototypesetter to AT&T, the ASCII character set was not considered a standard basis for a glyph repertoire by traditional typographers. In the stock Times ro‐ man, italic, and bold styles available, several ASCII characters were not present at all, nor was most of the Teletype’s extended character set. AT&T commissioned a “special” font to ensure no loss of reper‐ toire. A representation of the coverage of the C/A/T’s text fonts follows. The glyph resembling an underscore is a baseline rule, and that resem‐ bling a vertical line is a box rule. In italics, the box rule was not slanted. We also observe that the hyphen and minus sign were already “de‐unified” by the fonts provided; a decision whither to map an input “-” therefore had to be taken. ┌─────────────────────────────────────────────────────┐ │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z │ │ a b c d e f g h i j k l m n o p q r s t u v w x y z │ │ 0 1 2 3 4 5 6 7 8 9 fi fl ffi ffl │ │ ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] │ │ │ • □ — ‐ _ ¼ ½ ¾ ° † ′ ¢ ® © │ └─────────────────────────────────────────────────────┘ The special font supplied the missing ASCII and Teletype extended glyphs, among several others. The plus, minus, and equals signs ap‐ peared in the special font despite availability in text fonts “to insu‐ late the appearance of equations from the choice of standard [read: text] fonts”—a priority since troff was turned to the task of mathemat‐ ical typesetting as soon as it was developed. We note that AT&T took the opportunity to de‐unify the apostrophe/right single quotation mark from the acute accent (a choice ISO later dupli‐ cated in its 8859 series of standards). A slash intended to be mirror‐ symmetric with the backslash was also included, as was the Bell System logo; we do not attempt to depict the latter. ┌───────────────────────────────────────────────────────────┐ │ α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ σ ς τ υ ϕ χ ψ ω │ │ Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω │ │ " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗ │ │ ≥ ≤ ≡ ≈ ∼ ≠ ↑ ↓ ← → × ÷ ± ∞ ∂ ∇ ¬ ∫ ∝ √ ‾ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∅ ∈ │ │ § ‡ ☜ ☞ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉ │ └───────────────────────────────────────────────────────────┘ One ASCII character as rendered by the Model 37 was apparently aban‐ doned. That device printed decimal 124 (|) as a broken vertical line, like Unicode U+00A6 (¦). No equivalent was available on the C/A/T; the box rule \[br], brace vertical extension \[bv], and “or” operator \[or] were used as contextually appropriate. Devices supported by AT&T device‐independent troff exhibited some dif‐ ferences in glyph detail. For example, on the Autologic APS‐5 photo‐ typesetter, the square \(sq became filled in the Times bold face. Files The files below are loaded automatically by the default troffrc. /usr/local/share/groff/1.23.0/tmac/composite.tmac assigns alternate mappings for identifiers after the first in a composite special character escape sequence. See subsection “Accents” above. /usr/local/share/groff/1.23.0/tmac/fallbacks.tmac defines fallback mappings for Unicode code points such as the increment sign (U+2206) and upper‐ and lowercase Roman numerals. Authors This document was written by James Clark ⟨jjc@jclark.com⟩, with addi‐ tions by Werner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd .warken-72@web.de⟩, revised to use tbl(1) by Eric S. Raymond ⟨esr@ thyrsus.com⟩, and largely rewritten by G. Branden Robinson ⟨g.branden .robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. Section “Using Symbols” may be of particular note. You can browse it interactively with “info '(groff) Using Symbols'”. “An extension to the troff character set for Europe”, E.G. Keizer, K.J. Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, No. 2, Summer 1989 The Unicode Standard ⟨http://www.unicode.org⟩ “7‐bit Character Sets” ⟨https://www.aivosto.com/articles/charsets-7bit .html⟩ by Tuomas Salste documents the inherent ambiguity and config‐ urable code points of the ASCII encoding standard. “Nroff/Troff User’s Manual” by Joseph F. Ossanna, 1976, AT&T Bell Labo‐ ratories Computing Science Technical Report No. 54, features two tables that throw light on the glyph repertoire available to “typesetter roff” when it was first written. Be careful of re‐typeset versions of this document that can be found on the Internet. Some do not accurately represent the original document: several glyphs are obviously missing. More subtly, lowercase Greek letters are rendered upright, not slanted as they appeared in the C/A/T’s special font and as expected by troff users. groff_rfc1345(7) describes an alternative set of special character glyph names, which extends and in some cases overrides the definitions listed above. groff(1), troff(1), groff(7) groff 1.23.0 29 August 2023 groff_char(7) ─────────────────────────────────────────────────────────────────────────────── groff_diff(7) Miscellaneous Information Manual groff_diff(7) Name groff_diff - differences between GNU roff and AT&T troff Description The GNU roff text processing system, groff, is an extension of AT&T troff, the typesetting system originating in Unix systems of the 1970s. groff removes many arbitrary limitations and adds features, both to the input language and to the page description language output by the troff formatter. Differences arising from groff’s implementation of AT&T troff features are also noted. See roff(7) for background. Language GNU troff features identifiers of arbitrary length; supports color out‐ put, non‐integral type sizes, and user‐defined characters; adds more conditional expression operators; recognizes additional scaling units and numeric operators; enables general file I/O (in “unsafe mode” only); and exposes more formatter state. Long names GNU troff introduces many new requests; with three exceptions (cp, do, rj), they have names longer than two characters. The names of regis‐ ters, fonts, strings/macros/diversions, environments, special charac‐ ters, streams, and colors can be of any length. Anywhere AT&T troff supports a parameterized escape sequence that uses an opening parenthe‐ sis “(” to introduce a two‐character argument, groff supports a square‐ bracketed form “[]” where the argument within can be of arbitrary length. Font families, abstract styles, and translation GNU troff can group text typefaces into families containing each of the styles “R”, “I”, “B”, and “BI”. So that a document need not be coupled to a specific font family, an output device can associate a style in the abstract sense with a mounting position. Thus the default family can be combined with a style dynamically, producing a resolved font name. A document can translate, or remap, fonts with the ftr request. Applying the requests cs, bd, tkf, uf, or fspecial to an abstract style affects the member of the default family corresponding to that style. The default family can be set with the fam request or -f command‐line option. The styles directive in the output device’s DESC file controls which mounting positions (if any) are initially associated with ab‐ stract styles rather than fonts, and the sty request can update this association. Colors groff supports color output with a variety of color spaces and up to 16 bits per channel. Some devices, particularly terminals, may be more limited. When color support is enabled, two colors are current at any given time: the stroke color, with which glyphs, rules (lines), and geometric figures are drawn, and the fill color, which paints the inte‐ rior of filled geometric figures. The color, defcolor, gcolor, and fcolor requests; \m and \M escape sequences; and .color, .m, and .M registers exercise color support. Fractional type sizes and new scaling units AT&T troff interpreted all type size measurements in points. Combined with integer arithmetic, this design choice made it impossible to sup‐ port, for instance, ten and a half‐point type. In GNU troff, an output device can select a scaling factor that subdivides a point into “scaled points”. A type size expressed in scaled points can thus represent a non‐integral type size. A scaled point is equal to 1/sizescale points, where sizescale is spec‐ ified in the device description file, DESC, and defaults to 1; see groff_font(5). Requests and escape sequences in GNU troff interpret arguments that represent a type size in points, which the formatter multiplies by sizescale and converts to an integer. Arguments treated in this way comprise those to the escape sequences \H and \s, to the request ps, the third argument to the cs request, and the second and fourth arguments to the tkf request. Scaled points may be specified explicitly with the z scaling unit. In GNU troff, the register \n[.s] can interpolate a non‐integral type size. The register \n[.ps] inter‐ polates the type size in scaled points. For example, if sizescale is 1000, then a scaled point is one thou‐ sandth of a point. Consequently, “.ps 10.5” is synonymous with “.ps 10.5z”; both set the type size to 10,500 scaled points, or 10.5 points. It makes no sense to use the “z” scaling unit in a numeric expression whose default scaling unit is neither “u” nor “z”, so GNU troff disal‐ lows this. Similarly, it is nonsensical to use a scaling unit other than “z” or “u” in a numeric expression whose default scaling unit is “z”, so GNU troff disallows this as well. Another new scaling unit, “s”, multiplies by the number of basic units in a scaled point. Thus, “\n[.ps]s” is equal to “1m” by definition. Do not confuse the “s” and “z” scaling units. Output devices may be limited in the type sizes they can employ. The .s and .ps registers represent the type size as selected by the output driver as it understands a device’s capability. The last requested type size is interpolated in scaled points by the read‐only register .psr and in points as a decimal fraction by the read‐only string‐valued register .sr. Both are associated with the environment. For example, if a type size of 10.95 points is requested, and the nearest size per‐ mitted by a sizes request (or by the sizes or sizescale directives in the device’s DESC file) is 11 points, the output driver uses the latter value. A further two new measurement units available in groff are “M”, which indicates hundredths of an em, and “f”, which multiplies by 65,536. The latter provides convenient fractions for color definitions with the defcolor request. For example, 0.5f equals 32768u. Numeric expressions GNU troff permits spaces in a numeric expression within parentheses, and offers three new operators. e1>?e2 Interpolate the greater of e1 and e2. e1 } .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] The class “[prepunctx]” thus contains the contents of the class “[prepunct]” and characters in the range U+2013–U+2016. If you want to include “-” in a class, it must be the first character value in the argument list, otherwise it gets misin‐ terpreted as part of the range syntax. It is not possible to use class names as end points of range de‐ finitions. A typical use of the class request is to control line‐breaking and hyphenation rules as defined by the cflags request. For ex‐ ample, to inhibit line breaks before the characters belonging to the “[prepunctx]” class defined in the previous example, you can write the following. .cflags 2 \C'[prepunctx]' .close stream Close the stream named stream, invalidating it as an argument to the write request. See open. .composite c1 c2 Map character name c1 to character name c2 when c1 is a combin‐ ing component in a composite glyph. Typically, this remaps a spacing glyph to a combining one. .continue Skip the remainder of a “while” loop’s body, immediately start‐ ing the next iteration. See break. .color n If n is non‐zero or missing, enable colors (the default), other‐ wise disable them. .cp n If n is non‐zero or missing, enable compatibility mode, other‐ wise disable it. In compatibility mode, long names are not rec‐ ognized, and the incompatibilities they cause do not arise. .defcolor ident scheme color‐component ... Define a color named ident. scheme identifies a color space and determines the number of required color‐components; it must be one of “rgb” (three components), “cmy” (three components), “cmyk” (four components), or “gray” (one component). “grey” is accepted as a synonym of “gray”. The color components can be encoded as a hexadecimal value starting with # or ##. The for‐ mer indicates that each component is in the range 0–255 (0–FF), the latter the range 0–65535 (0–FFFF). Alternatively, each color component can be specified as a decimal fraction in the range 0–1, interpreted using a default scaling unit of “f”, which multiplies its value by 65,536 (but clamps it at 65,535). Each output device has a color named “default”, which cannot be redefined. A device’s default stroke and fill colors are not necessarily the same. .de1 name [end‐name] Define a macro to be interpreted with compatibility mode dis‐ abled. When name is called, compatibility mode enablement sta‐ tus is saved; it is restored when the call completes. .dei name [end‐name] Define macro indirectly, with the name of the macro to be de‐ fined in string name and the name of the end macro terminating its definition in string end‐name. .dei1 name [end‐name] As dei, but compatibility mode is disabled while the definition of the macro named in string name is interpreted. .device anything Write anything, read in copy mode, to troff output as a device control command. An initial neutral double quote is stripped to allow the embedding of leading spaces. .devicem name Write contents of macro or string name to troff output as a de‐ vice control command. .do name [arg ...] Interpret the string, request, diversion, or macro name (along with any arguments) with compatibility mode disabled. Compati‐ bility mode is restored (only if it was active) when the expan‐ sion of name is interpreted; that is, the restored compatibility state applies to the contents of the macro, string, or diversion name as well as data read from files or pipes if name is any of the so, soquiet, mso, msoquiet, or pso requests. For example, .de mac1 FOO .. .de1 mac2 groff .mac1 .. .de mac3 compatibility .mac1 .. .de ma \\$1 .. .cp 1 .do mac1 .do mac2 \" mac2, defined with .de1, calls "mac1" .do mac3 \" mac3 calls "ma" with argument "c1" .do mac3 \[ti] \" groff syntax accepted in .do arguments results in FOO groff FOO compatibility c1 ~ as output. .ds1 name contents As ds, but compatibility mode is disabled while name is inter‐ preted: a “compatibility save” token is inserted at the begin‐ ning of contents, and a “compatibility restore” token after it. .ecr Restore the escape character saved with ecs, or set escape char‐ acter to “\” if none has been saved. .ecs Save the current escape character. .evc env Copy the properties of environment env to the current environ‐ ment, except for the following data. • a partially collected line, if present; • the interruption status of the previous input line (due to use of the \c escape sequence); • the count of remaining lines to center, to right‐justify, or to underline (with or without underlined spaces)—these are set to zero; • the activation status of temporary indentation; • input traps and their associated data; • the activation status of line numbering (which can be reacti‐ vated with “.nm +0”); and • the count of consecutive hyphenated lines (set to zero). .fam [family] Set default font family to family. If no argument is given, the previous font family is selected, or the formatter’s default family if there is none. The formatter’s default font family is “T” (Times), but it can be overridden by the output device—see groff_font(5). The default font family is associated with the environment. See \F. .fchar c contents Define fallback character c as contents. The syntax of this re‐ quest is the same as the char request; the difference is that a character defined with char hides a glyph with the same name in the selected font, whereas characters defined with fchar are checked only if c isn’t found in the selected font. This test happens before special fonts are searched. .fcolor color Set the fill color to color. Without an argument, the previous fill color is selected. .fschar f c contents Define fallback special character c for font f as contents. A character defined by fschar is located after the list of fonts declared with fspecial is searched but before those declared with the “special” request. .fspecial f s1 s2 ... When font f is selected, fonts s1, s2, ... are treated as spe‐ cial; that is, they are searched for glyphs not found in f. Any fonts specified in the “special” request are searched after s1, s2, and so on. Without s arguments, fspecial clears the list of fonts treated as special when f is selected. .ftr f g Translate font f to g. Whenever a font named f is referred to in an \f escape sequence, in the F and S conditional expression operators, or in the ft, ul, bd, cs, tkf, special, fspecial, fp, or sty requests, font g is used. If g is missing or identical to f, then font f is not translated. .fzoom f zoom Set zoom factor zoom for font f. zoom must a non‐negative inte‐ ger multiple of 1/1000th. If it is missing or is equal to zero, it means the same as 1000, namely no magnification. f must be a resolved font name, not an abstract style. .gcolor color Set the stroke color to color. Without an argument, the previ‐ ous stroke color is selected. .hcode c1 code1 [c2 code2] ... Set the hyphenation code of character c1 to code1, that of c2 to code2, and so on. A hyphenation code must be an ordinary char‐ acter (not a special character escape sequence) other than a digit. The request is ignored if given no arguments. For hyphenation to work, hyphenation codes must be set up. At startup, groff assigns hyphenation codes to the letters “a–z” (mapped to themselves), to the letters “A–Z” (mapped to “a–z”), and zero to all other characters. Normally, hyphenation pat‐ terns contain only lowercase letters which should be applied re‐ gardless of case. In other words, they assume that the words “ABBOT” and “Abbot” should be hyphenated exactly as “abbot” is. hcode extends this principle to letters outside the Unicode ba‐ sic Latin alphabet; without it, words containing such letters won’t be hyphenated properly even if the corresponding hyphen‐ ation patterns contain them. .hla lang Set the hyphenation language to lang. Hyphenation exceptions specified with the hw request and hyphenation patterns and ex‐ ceptions specified with the hpf and hpfa requests are associated with the hyphenation language. The hla request is usually in‐ voked by a localization file, which is in turn loaded by the troffrc or troffrc-end file; see the hpf request below. The hy‐ phenation language is associated with the environment. .hlm [n] Set the maximum number of consecutive hyphenated lines to n. If n is negative, there is no maximum. If omitted, n is -1. This value is associated with the environment. Only lines output from a given environment count towards the maximum associated with that environment. Hyphens resulting from \% are counted; explicit hyphens are not. .hpf pattern‐file Read hyphenation patterns from pattern‐file. This file is sought in the same way that macro files are with the mso request or the -mname command‐line option to groff(1) and troff(1). The pattern‐file should have the same format as (simple) TeX pattern files. The following scanning rules are implemented. • A percent sign starts a comment (up to the end of the line) even if preceded by a backslash. • “Digraphs” like \$ are not supported. • “^^xx” (where each x is 0–9 or a–f) and ^^c (character c in the code point range 0–127 decimal) are recognized; other uses of ^ cause an error. • No macro expansion is performed. • hpf checks for the expression \patterns{...} (possibly with whitespace before or after the braces). Everything between the braces is taken as hyphenation patterns. Consequently, “{” and “}” are not allowed in patterns. • Similarly, \hyphenation{...} gives a list of hyphenation ex‐ ceptions. • \endinput is recognized also. • For backwards compatibility, if \patterns is missing, the whole file is treated as a list of hyphenation patterns (but the “%” character is still recognized as the start of a com‐ ment). Use the hpfcode request (see below) to map the encoding used in hyphenation pattern files to groff’s input encoding. The set of hyphenation patterns is associated with the hyphen‐ ation language set by the hla request. The hpf request is usu‐ ally invoked by a localization file loaded by the troffrc file. By default, troffrc loads the localization file for English. (As of groff 1.23.0, localization files for Czech (cs), German (de), English (en), French (fr), Japanese (ja), Swedish (sv), and Chinese (zh) exist.) For Western languages, the localiza‐ tion file sets the hyphenation mode and loads hyphenation pat‐ terns and exceptions. A second call to hpf (for the same language) replaces the old patterns with the new ones. Invoking hpf causes an error if there is no hyphenation lan‐ guage. If no hpf request is specified (either in the document, in a file loaded at startup, or in a macro package), GNU troff won’t automatically hyphenate at all. .hpfa pattern‐file As hpf, except that the hyphenation patterns and exceptions from pattern‐file are appended to the patterns already applied to the hyphenation language of the environment. .hpfcode a b [c d] ... Define mapping values for character codes in pattern files. This is an older mechanism no longer used by groff’s own macro files; for its successor, see hcode above. hpf or hpfa apply the mapping after reading or appending to the active list of patterns. Its arguments are pairs of character codes—integers from 0 to 255. The request maps character code a to code b, code c to code d, and so on. Character codes that would other‐ wise be invalid in groff can be used. By default, every code maps to itself except those for letters “A” to “Z”, which map to those for “a” to “z”. .hym [length] Set the (right) hyphenation margin to length. If the adjustment mode is not “b” or “n”, the line is not hyphenated if it is shorter than length. Without an argument, the default hyphen‐ ation margin is reset to its default value, 0. The default scaling unit is “m”. The hyphenation margin is associated with the environment. A negative argument resets the hyphenation margin to zero, emitting a warning in category “range”. .hys [hyphenation‐space] Suppress hyphenation of the line in adjustment modes “b” or “n”, if it can be justified by adding no more than hyphenation‐space extra space to each inter‐word space. Without an argument, the hyphenation space adjustment threshold is set to its default value, 0. The default scaling unit is “m”. The hyphenation space adjustment threshold is associated with the current envi‐ ronment. A negative argument resets the hyphenation space ad‐ justment threshold to zero, emitting a warning in category “range”. .itc n name As “it”, but lines interrupted with the \c escape sequence are not applied to the line count. .kern n If n is non‐zero or missing, enable pairwise kerning (the de‐ fault), otherwise disable it. .length reg anything Compute the number of characters in anything and return the count in the register reg. If reg doesn’t exist, it is created. anything is read in copy mode. .ds xxx abcd\h'3i'efgh .length yyy \*[xxx] \n[yyy] 14 .linetabs n If n is non‐zero or missing, enable line‐tabs mode, otherwise disable it (the default). In this mode, tab stops are computed relative to the start of the pending output line, instead of the drawing position corresponding to the start of the input line. Line‐tabs mode is a property of the environment. For example, the following .ds x a\t\c .ds y b\t\c .ds z c .ta 1i 3i \*x \*y \*z yields a b c whereas in line‐tabs mode, the same input gives a b c instead. .lsm [name] Set the leading space macro (trap) to name. If there are lead‐ ing space characters on an input line, name is invoked in lieu of the usual roff behavior; the leading spaces are removed. The count of leading spaces on an input line is stored in \n[lsn], and the amount of corresponding horizontal motion in \n[lss], irrespective of whether a leading space trap is set. When it is, the leading spaces are removed from the input line, and no motion is produced before calling name. If no argument is sup‐ plied, the default leading space behavior is (re‐)established. .mso file As “so”, except that file is sought in the same directories as arguments to the groff(1) and troff(1) -m command‐line option are (the “tmac path”). If the file name to be interpolated has the form name.tmac and it isn’t found, mso tries to include tmac.name instead and vice versa. If file does not exist, a warning in category “file” is emitted and the request has no other effect. .msoquiet file As mso, but no warning is emitted if file does not exist. .nop anything Interpret anything as if it were an input line. nop resembles “.if 1”; it puts a break on the output if anything is empty. Unlike “if”, it cannot govern conditional blocks. Its applica‐ tion is to maintain consistent indentation within macro defini‐ tions even when producing text lines. .nroff Make the n conditional expression evaluate true and t false. See troff. .open stream file Open file for writing and associate stream with it. See write and close. .opena stream file As open, but if file exists, append to it instead of truncating it. .output contents Emit contents, which are read in copy mode, to the formatter output; this is similar to \! used in the top‐level diversion. An initial neutral double quote in contents is stripped to allow the embedding of leading spaces. .pev Report the state of the current environment followed by that of all other environments to the standard error stream. .pnr Write the names and values of all currently defined registers to the standard error stream. .psbb file Get the bounding box of a PostScript image file. This file must conform to Adobe’s Document Structuring Conventions; the request attempts to extract the bounding box values from a %%BoundingBox comment. After invocation, the x and y coordinates (in Post‐ Script units) of the lower left and upper right corners can be found in the registers \n[llx], \n[lly], \n[urx], and \n[ury], respectively. If an error occurs, these four registers are set to zero. .pso command As “so”, except that input comes from the standard output stream of command. .ptr Report the names and vertical positions of all page location traps to the standard error stream. Empty slots in the list are shown as well, because they can affect the visibility of subse‐ quently planted traps. .pvs ±n Set the post‐vertical line spacing to n; default scaling unit is “p”. With no argument, the post‐vertical line space is set to its previous value. In GNU troff, the distance between text baselines consists of the extra pre‐vertical line spacing set by the most negative \x argument on the pending output line, the vertical spacing (vs), the extra post‐vertical line spacing set by the most positive \x argument on the pending output line, and the post‐vertical line spacing set by this request. .rchar c ... Remove definition of each ordinary or special character c, undo‐ ing the effect of a char, fchar, or schar request. Glyphs, which are defined by font description files, cannot be removed. Spaces and tabs may separate c arguments. .return Within a macro, return immediately. If called with an argument, return twice, namely from the current macro and from the macro one level higher. No effect otherwise. .rfschar f c ... Remove each fallback special character c for font f. Spaces and tabs may separate c arguments. See fschar. .rj [n] Right‐align the next n input lines. Without an argument, right‐ align the next input line. rj implies “.ce 0”, and ce implies “.rj 0”. .rnn r1 r2 Rename register r1 to r2. If r1 doesn’t exist, the request is ignored. .schar c contents Define global fallback character c as contents. See char; the distinction is that a character defined with schar is located after the list of fonts declared with the special request but before any mounted special fonts. .shc [c] Set the soft hyphen character, inserted when a word is hyphen‐ ated automatically or at a hyphenation character, to c. If c is omitted, the soft hyphen character is set to the default, \[hy]. If the selected glyph does not exist in the font in use at a po‐ tential hyphenation point, then the line is not broken at that point. Neither character definitions (char and similar) nor translations (tr and similar) are considered when assigning the soft hyphen character. .shift n In a macro, shift the arguments by n positions: argument i be‐ comes argument i-n; arguments 1 to n are no longer available. If n is missing, arguments are shifted by 1. No effect other‐ wise. .sizes s1 s2 ... sn [0] Set the available type sizes to s1, s2, ... sn scaled points. The list of sizes can be terminated by an optional “0”. Each si can also be a range m–n. In contrast to the device description file directive of the same name (see groff_font(5)), the argu‐ ment list can’t extend over more than one line. .soquiet file As “so”, but no warning is emitted if file does not exist. .special f ... Declare each font f as special, searching it for glyphs not found in the selected font. Without arguments, this list of special fonts is made empty. .spreadwarn [limit] Emit a break warning if the additional space inserted for each space between words in an output line adjusted to both margins with “.ad b” is larger than or equal to limit. A negative value is treated as zero; an absent argument toggles the warning on and off without changing limit. The default scaling unit is m. At startup, spreadwarn is inactive and limit is 3 m. For example, “.spreadwarn 0.2m” causes a warning if break warn‐ ings are not suppressed and troff must add 0.2 m or more for each inter‐word space in a line. .stringdown str .stringup str Alter the string named str by replacing each of its bytes with its lowercase (down) or uppercase (up) version (if one exists). Special characters (see groff_char(7)) will often transform in the expected way due to the regular naming convention for ac‐ cented characters. When they do not, use substrings and/or catenation. .ds resume R\['e]sum\['e]\" \*[resume] .stringdown resume \*[resume] .stringup resume \*[resume] Résumé résumé RÉSUMÉ .sty n s Associate abstract style s with font mounting position n. .substring string start [end] Replace the string named string with its substring bounded by the indices start and end, inclusively. The first character in the string has index 0. If end is omitted, it is implicitly set to the largest valid value (the string length minus one). Nega‐ tive indices count backwards from the end of the string: the last character has index -1, the character before the last has index -2, and so on. .ds xxx abcdefgh .substring xxx 1 -4 \*[xxx] bcde .substring xxx 2 \*[xxx] de .tkf f s1 n1 s2 n2 Enable track kerning for font f. When the current font is f the width of every glyph is increased by an amount between n1 and n2; when the current type size is less than or equal to s1 the width is increased by n1; when it is greater than or equal to s2 the width is increased by n2; when the type size is greater than or equal to s1 and less than or equal to s2 the increase in width is a linear function of the type size. .tm1 message As tm request, but strips a leading neutral double quote from message to allow the embedding of leading spaces. .tmc message As tm1 request, but does not append a newline. .trf file Transparently output the contents of file file. Each line is output as if preceded by \!; however, the lines are not subject to copy‐mode interpretation. If the file does not end with a newline, then a newline is added. Unlike cf, file cannot con‐ tain characters that are invalid as input to GNU troff. For example, you can define a macro x containing the contents of file f, using .di x .trf f .di .trin abcd This is the same as the tr request except that the asciify re‐ quest uses the character code (if any) before the character translation. Example: .trin ax .di xxx a .br .di .xxx .trin aa .asciify xxx .xxx The result is “x a”. Using tr, the result would be “x x”. .trnt abcd This is the same as the tr request except that the translations do not apply to text that is transparently throughput into a di‐ version with \!. For example, .tr ab .di x \!.tm a .di .x prints b; if trnt is used instead of tr it prints a. .troff Make the t conditional expression evaluate true and n false. See nroff. .unformat div Unformat the diversion div. Unlike asciify, unformat handles only tabs and spaces between words, the latter usually arising from spaces or newlines in the input. Tabs are treated as input tokens, and spaces become adjustable again. The vertical sizes of lines are not preserved, but glyph information (font, type size, space width, and so on) is retained. .vpt n If n is non‐zero or missing, enable vertical position traps (the default), otherwise disable them. Vertical position traps are those set by the ch, wh, and dt requests. .warn [n] Select the categories, or “types”, of reported warnings. n is the sum of the numeric codes associated with each warning cate‐ gory that is to be enabled; all other categories are disabled. The categories and their associated codes are listed in section “Warnings” of troff(1). For example, “.warn 0” disables all warnings, and “.warn 1” disables all warnings except those about missing glyphs. If no argument is given, all warning categories are enabled. .warnscale si Set the scaling unit used in warnings to si. Valid values for si are u, i (the default), c, p, and P. .while cond‐expr anything Evaluate the conditional expression cond‐expr, and repeatedly execute anything unless and until cond‐expr evaluates false. anything, which is often a conditional block, is referred to as the while request’s body. troff treats the body of a while request similarly to that of a de request (albeit one not read in copy mode), but stores it un‐ der an internal name and deletes it when the loop finishes. The operation of a macro containing a while request can slow signif‐ icantly if the while body is large. Each time the macro is exe‐ cuted, the while body is parsed and stored again. An often bet‐ ter solution—and one that is more portable, since AT&T troff lacked the while request—is to instead write a recursive macro. It will be parsed only once (unless you redefine it). To pre‐ vent infinite loops, the default number of available recursion levels is 1,000 or somewhat less (because things other than macro calls can be on the input stack). You can disable this protective measure, or raise the limit, by setting the slimit register. See section “Debugging” below. If a while body begins with a conditional block, its closing brace must end an input line. The break and continue requests alter a while loop’s flow of control. .write stream anything Write anything to stream, which must previously have been the subject of an open request, followed by a newline. anything is read in copy mode. An initial neutral double quote in anything is stripped to allow the embedding of leading spaces. .writec stream anything As write, but without a trailing newline. .writem stream name Write the contents of the macro or string name to stream, which must previously have been the subject of an open request. name is read in copy mode. Extended requests .cf file In a diversion, embed an object which, when reread, will cause the contents of file to be copied verbatim to the output. In AT&T troff, the contents of file are immediately copied to the output regardless of whether a diversion is being written to; this behavior is so anomalous that it must be considered a bug. .de name [end‐name] .am name [end‐name] .ds name [contents] .as name [contents] In compatibility mode, these requests behave similarly to de1, am1, ds1, and as1, respectively: a “compatibility save” token is inserted at the beginning, and a “compatibility restore” token at the end, with compatibility mode switched on during execu‐ tion. .hy n New values 16 and 32 are available; the former enables hyphen‐ ation before the last character in a word, and the latter en‐ ables hyphenation after the first character in a word. .ss word‐space‐size [additional‐sentence‐space‐size] A second argument sets the amount of additional space separating sentences on the same output line. If omitted, this amount is set to word‐space‐size. Both arguments are in twelfths of cur‐ rent font’s space width (typically one‐fourth to one‐third em for Western scripts; see groff_font(5)). The default for both parameters is 12. Negative values are erroneous. .ta [[n1 n2 ... nn ]T r1 r2 ... rn] groff supports an extended syntax to specify repeating tab stops after the “T” mark. These values are always taken as relative distances from the previous tab stop. This is the idiomatic way to specify tab stops at equal intervals in groff. The syntax summary above instructs groff to set tabs at posi‐ tions n1, n2, ..., nn, then at nn+r1, nn+r2, ..., nn+rn, then at nn+rn+r1, nn+rn+r2, ..., nn+rn+rn, and so on. New registers GNU troff exposes more formatter state via many new read‐only regis‐ ters. Their names often correspond to the requests that affect them. \n[.br] Within a macro call, interpolate 1 if the macro is called with the “normal” control character (“.” by default), and 0 otherwise. This facility allows the reliable modification of requests. Using this register outside of a macro defin‐ ition makes no sense. .als bp*orig bp .de bp .tm before bp .ie \\n[.br] .bp*orig .el 'bp*orig .tm after bp .. \n[.C] Interpolate 1 if compatibility mode is in effect, 0 other‐ wise. See cp. \n[.cdp] Interpolate depth of last glyph added to the environment. It is positive if the glyph extends below the baseline. \n[.ce] Interpolate number of input lines remaining to be centered. \n[.cht] Interpolate height of last glyph added to the environment. It is positive if the glyph extends above the baseline. \n[.color] Interpolate 1 if colors are enabled, 0 otherwise. \n[.cp] Within a “do” request, interpolate the saved value of com‐ patibility mode (see \n[.C] above). \n[.csk] Interpolate skew of last glyph added to the environment. The skew of a glyph is how far to the right of the center of a glyph the center of an accent over that glyph should be placed. \n[.ev] Interpolate name of current environment. This is a string‐ valued register. \n[.fam] Interpolate name of default font family. This is a string‐ valued register. \n[.fn] Interpolate resolved name of the selected font. This is a string‐valued register. \n[.fp] Interpolate next free font mounting position. \n[.g] Interpolate 1. Test with “if” or ie to check whether GNU troff is the formatter. \n[.height] Interpolate font height. See \H. \n[.hla] Interpolate hyphenation language of the environment. This is a string‐valued register. \n[.hlc] Interpolate count of immediately preceding consecutive hy‐ phenated lines in the environment. \n[.hlm] Interpolate maximum number of consecutive hyphenated lines allowed in the environment. \n[.hy] Interpolate hyphenation mode of the environment. \n[.hym] Inteprolate hyphenation margin of the environment. \n[.hys] Interpolate hyphenation space adjustment threshold of the environment. \n[.in] Interpolate indentation amount applicable to the pending output line. \n[.int] Interpolate 1 if the previous output line was interrupted (ended with \c), 0 otherwise. \n[.kern] Interpolate 1 if pairwise kerning is enabled, 0 otherwise. \n[.lg] Interpolate ligature mode. \n[.linetabs] Interpolate 1 if line‐tabs mode is enabled, 0 otherwise. \n[.ll] Interpolate line length applicable to the pending output line. \n[.lt] Interpolate title line length. \n[.m] Interpolate name of the selected stroke color. This is a string‐valued register. \n[.M] Interpolate name of the selected fill color. This is a string‐valued register. \n[.ne] Interpolate amount of space demanded by the most recent ne request that caused a page location trap to be sprung. See \n[.trunc]. \n[.nm] Interpolate 1 if output line numbering is enabled (even if temporarily suppressed), 0 otherwise. \n[.ns] Interpolate 1 if no‐space mode is enabled, 0 otherwise. \n[.O] Interpolate output suppression level. See \O. \n[.P] Interpolate 1 if the current page is selected for output. See -o command‐line option to troff(1). \n[.pe] Interpolate 1 during page ejection, 0 otherwise. \n[.pn] Interpolate next page number (either that set by pn, or that of the current page plus 1). \n[.ps] Interpolate type size in scaled points. \n[.psr] Interpolate most recently requested type size in scaled points. \n[.pvs] Interpolate post‐vertical line spacing amount. \n[.rj] Interpolate number of input lines remaining to be right‐ aligned. \n[.slant] Interpolate font slant. See \S. \n[.sr] Interpolate most recently requested type size in points as a decimal fraction. This is a string‐valued register. \n[.ss] \n[.sss] Interpolate values of minimal inter‐word space and addi‐ tional inter‐sentence space, respectively, in twelfths of the space width of the selected font. \n[.sty] Interpolate selected abstract font style, if any. This is a string‐valued register. \n[.tabs] Interpolate representation of the tab stop settings in a form suitable for passage to the ta request. \n[.trunc] Interpolate amount of vertical space truncated by the most recently sprung page location trap, or, if the trap was sprung by an ne request, minus the amount of vertical mo‐ tion produced by the ne request. In other words, at the point a trap is sprung, \n[.trunc] represents the differ‐ ence of what the vertical position would have been but for the trap, and what the vertical position actually is. See \n[.ne]. \n[.U] Interpolate 1 if in unsafe mode, 0 otherwise. See -U com‐ mand‐line option to troff(1). \n[.vpt] Interpolate 1 if vertical position traps are enabled, 0 otherwise. \n[.warn] Interpolate warning mode. See section “Warnings” of troff(1). \n[.x] Interpolate major version number of the running troff for‐ matter. For example, if the version number is 1.23.0, then \n[.x] contains 1. \n[.y] Interpolate minor version number of the running troff for‐ matter. For example, if the version number is 1.23.0, then \n[.y] contains 23. \n[.Y] Interpolate revision number of the running troff formatter. For example, if the version number is 1.23.0, then \n[.Y] contains 0. \n[.zoom] Interpolate magnification of font, in thousandths, or 0 if magnification unused. See fzoom. The following (writable) registers are set by the psbb request. \n[llx] \n[lly] \n[urx] \n[ury] Interpolate the (upper, lower, left, right) bounding box values (in PostScript units) of the most recently processed PostScript image. The following (writable) registers are set by the \w escape sequence. \n[rst] \n[rsb] Like \n[st] and \n[sb], but taking account of the heights and depths of glyphs. In other words, these registers store the highest and lowest vertical positions attained by the argument formatted by the \w escape sequence, doing what AT&T troff doc‐ umented \n[st] and \n[sb] as doing. \n[ssc] The amount of horizontal space (possibly negative) that should be added to the last glyph before a subscript. \n[skw] How far to right of the center of the last glyph in the \w ar‐ gument, the center of an accent from a roman font should be placed over that glyph. Other writable registers are as follows. Those relating to date and time are initialized using localtime(3) at formatter startup. \n[c.] Interpolate input line number. \n[.c] is a read‐only alias of this register. \n[hours] Interpolate number of hours elapsed since midnight. \n[hp] Interpolate horizontal position relative to that at the start of the input line. \n[lsn] \n[lss] Interpolate count of leading spaces on input line and amount of corresponding horizontal motion, respectively. \n[minutes] Interpolate number of minutes elapsed in the hour. \n[seconds] Interpolate number of seconds elapsed in the minute. \n[systat] Interpolate return value of system(3) function executed by most recent sy request. \n[slimit] Interpolates maximum quantity of objects on troff’s inter‐ nal input stack (default: 1000). If non‐positive, there is no limit: recursion can continue until program memory is exhausted. \n[year] Interpolate Gregorian year. AT&T troff’s \[yr] interpo‐ lates the Gregorian year minus 1900. Miscellaneous GNU troff predefines one string, .T, containing the argument given to the -T command‐line option, namely the output device (for example, pdf or utf8). The (read‐only) register .T interpolates 1 if GNU troff is run with the -T command‐line option, and 0 otherwise. A font not listed in the output device’s DESC file’s fonts directive is automatically mounted at the next available font position when it is selected. If you mount a font explicitly with the fp request, you should do so on the first unused position, which can be found in the .fp register. Unparameterized string interpolation does not conceal the arguments to a macro being interpreted. Thus, in a macro definition, the call of another macro with the existing argument list, .xx \\$@ is more efficiently done with \\*[xx]\\ (that is, with string interpolation). The trailing backslashes prevent the final newline in the macro definition from being interpolated, po‐ tentially putting an unwanted blank line on the output. See section “Punning Names” in groff(7). If a font description file contains pairwise kerning information, glyphs from that font are kerned. Kerning between two glyphs can be inhibited by placing a dummy character \& between them. GNU troff keeps track of the nesting depth of escape sequence interpo‐ lations and other uses of delimiters, as in the tl request and the out‐ put comparison operator (that is, input like 'foo'bar' as a conditional expression), so the only characters you need to avoid using as delim‐ iters are those that appear in the arguments you input, not any that result from interpolation. Typically, ' works fine. Use visible char‐ acters as delimiters in GNU troff, not “ASCII” controls like BEL (Con‐ trol+G). The implementation of \$@ ensures that the double quotes sur‐ rounding an argument appear at an interpolation depth different from that of the arguments themselves. Similarly, in bracket‐form escape sequences like \f[ZCMI], a right bracket ] does not end the sequence unless it occurs at the same interpolation depth as the opening [, so input like \f[\*[my‐family]\*[my‐style]] works as desired. In compatibility mode, no attention is paid to the interpolation depth. In GNU troff, the tr request can map characters to the unbreakable space escape sequence \~ as a special case (tr normally operates only on characters). This feature replaces the odd‐parity tr mapping trick used in AT&T troff documents, where a character, often ~, was “sacri‐ ficed” by mapping it to “nothing”, drafting it into use as an unad‐ justable, unbreakable space. (This feature was gratuitous even in early AT&T troff, which supported the \space escape sequence by 1976.) Often, it makes more sense to use GNU troff’s \~ escape sequence in‐ stead, which has been adopted by every other active troff implementa‐ tion except that of Illumos, as well as by the non‐troff mandoc. Translation of a character to \~ is unnecessary. GNU troff permits tabs and spaces after the first dot on a control line that ends a macro definition. .if t \{\ . de bar . nop Hello, I'm 'bar'. . . .\} Formatter output The page description language output by GNU troff is modeled after that used by AT&T troff once the latter adopted a device‐independent ap‐ proach in the early 1980s. Only the differences are documented here. For a fuller discussion, see groff_out(5). Glyph and font names can be of arbitrary length; postprocessors should not assume that they are at most two characters. A glyph to be format‐ ted is always drawn from the current font; in contrast to AT&T device‐ independent troff, drivers need not search special fonts to find a glyph. Units The argument to the s command is in scaled points (units of points/n, where n is the argument to the sizescale command in the DESC file). The argument to the “x H” command is also in scaled points. Simple commands If the tcommand directive is present in the output device’s DESC file, GNU troff employs the following two commands. t xyz... Typeset word xyz; that is, set a sequence of ordinary glyphs named x, y, z, ..., terminated by a space or newline; an op‐ tional second integer argument is ignored (this allows the for‐ matter to generate an even number of arguments). Each glyph is set at the current drawing position, and the position is then advanced horizontally by the glyph’s width. A glyph’s width is read from its metrics in the font description file, scaled to the current type size, and rounded to a multiple of the horizon‐ tal motion quantum. Use the C command to emplace glyphs of spe‐ cial characters. u n xyz... Typeset word xyz with track kerning. As t, but after placing each glyph, the drawing position is further advanced horizon‐ tally by n basic units. New commands implement color support. mc cyan magenta yellow md mg gray mk cyan magenta yellow black mr red green blue Set the components of the stroke color with respect to various color spaces. md resets the stroke color to the default value. The arguments are integers in the range 0 to 65535. A new device control subcommand is available. x u n If n is 1, start underlining of spaces. If n is 0, stop under‐ lining of spaces. This facility is needed for the cu request in nroff mode and is ignored otherwise. Extended drawing commands GNU pic does not produce troff escape sequences employing these exten‐ sions if its -n option is given. Df n Set the shade of gray used to fill geometric objects to n, which must be an integer. 0 corresponds to white and 1000 to black. A grayscale ramp spans the two. A value outside this range uses the stroke color as the fill color. The fill color is opaque. Normally the default is black, but some drivers may provide a way of changing this. Df is obsolete since 2002, superseded by DFg below. The corresponding \D'f' escape sequence should not be used: its argument is rounded to an integer multiple of the horizontal mo‐ tion quantum, which can limit the precision of n. DC d Draw a filled circle of diameter d with its leftmost point at the drawing position. DE h v Draw a filled ellipse, of horizontal axis h and vertical axis v, with its leftmost point at the drawing position. Dp dx1dy1...dxndyn Draw a polygon with, for i=1,...,n+1, its ith vertex at the drawing position +ij−=Σ11(dxj,dyj). groff output drivers automati‐ cally close polygons, drawing a line from (dxn,dyn) back to (dx1,dy1). The drawing position is left at the last specified vertex, but this may change in a future version of GNU troff. Heirloom Doctools troff, like DWB troff, by default does not close the polygon. In its groff compatibility mode, Heirloom closes the polygon but leaves the drawing position unchanged— that is, at the polygon’s initial drawing position. At the moment, GNU pic uses this command only to generate trian‐ gles and rectangles. DP dx1dy1...dxndyn As Dp, but draw a filled rather than a stroked polygon. Dt n Set the line thickness to n basic units. AT&T troff output dri‐ vers use a thickness proportional to the type size; this is the GNU troff default. A negative n requests this explicitly. An n of zero selects the smallest available line thickness. A difficulty arises in how the drawing position should be changed after the execution of these commands. This has little importance to most users, since the output of GNU grn and pic does not depend on it. Given a drawing command of the form Dz x1y1...xnyn, where z is not c or e, AT&T troff treats each xi as a horizontal motion, each yi as a ver‐ tical one, and therefore assumes that the width of the drawn object is in=Σ1xi, and its height is in=Σ1yi. (Verify its assumption about height by examining the st and sb registers after using such a drawing command in a \w escape sequence). For the sake of compatibility, GNU troff also follows this rule, even though it frustrates extensions to the D com‐ mand that set drawing parameters rather than rendering objects, produc‐ ing ugly results in the case of Dt and Df, or otherwise don’t parame‐ terize objects as a series of vertices, as with GNU troff’s filled el‐ lipse, DE. Thus after executing a D command of the form Dz x1y1...xnyn, the drawing position should be increased by (in=Σ1xi,in=Σ1yi). In a future release, GNU troff and its output drivers may abandon the application of this assumption to drawing commands not explicitly spec‐ ified in the AT&T “Troff User’s Manual”. Fill color selection is implemented with another set of extensions. DFc cyan magenta yellow DFd DFg gray DFk cyan magenta yellow black DFr red green blue Set the components of the fill color as described under the \M escape sequence above. DFd restores the device’s default fill color. The drawing position is not updated, in contrast to Df. Device control syntax extension GNU troff introduces a line continuation convention, permitting the ar‐ gument to the x X command to contain newlines. A newline in the input is transformed to the sequence “newline+”. When interpreting an x X command, a postprocessor should therefore be prepared for a plus sign after a newline; if it occurs, preserve the newline, discard the plus sign, and continue to collect the input into the argument of the x X command. A newline not followed by a plus sign terminates the x X com‐ mand. An application of this feature is the embedding of PostScript or PDF language command streams into troff output. GNU troff guarantees that the first three output commands it emits are as follows. x T device x res n h v x init Debugging In addition to AT&T troff’s debugging features, GNU troff emits more error diagnostics when syntactical or semantic nonsense is encountered and supports several warning categories; the output of these can be se‐ lected with warn. Also see the -E, -w, and -W options of troff(1). Backtraces can be automatically produced when errors or warnings occur (the -b option of troff(1)) or generated on demand (backtrace). groff also adds more flexible diagnostic output requests (tmc and tm1). More aspects of formatter state can be examined with requests that write lists of defined registers (pnr), environments (pev), and page location traps (ptr) to the standard error stream. Implementation differences GNU troff’s features sometimes cause incompatibilities with documents written assuming old implementations of troff. Some GNU extensions to troff are supported by other implementations. When adjusting to both margins, AT&T troff at first adjusts spaces starting from the right; GNU troff begins from the left. Both imple‐ mentations adjust spaces from opposite ends on alternating output lines to prevent “rivers” in the text. GNU troff does not always hyphenate words as AT&T troff does. The AT&T implementation uses a set of hard‐coded rules specific to U.S. English, while GNU troff uses language‐specific hyphenation pattern files de‐ rived from TeX. In some versions of troff there was limited space to store hyphenation exceptions (arguments to the hw request); GNU troff has no such restriction. Long names may be GNU troff’s most obvious innovation. AT&T troff in‐ terprets “.dsabcd” as defining a string “ab” with contents “cd”. Nor‐ mally, GNU troff interprets this as a call of a macro named “dsabcd”. AT&T troff also interprets \*[ and \n[ as an interpolation of a string or register, respectively, called “[”. In GNU troff, however, the “[” is normally interpreted as beginning the enclosure of a long identi‐ fier. In compatibility mode, GNU troff interprets names in the tradi‐ tional way, which means that they are limited to one or two characters. See the -C option in troff(1) and, above, the .C and .cp registers, and cp and “do” requests, for more on compatibility mode. The register \n[.cp] is specialized and may require a statement of ra‐ tionale. When writing macro packages or documents that use GNU troff features and which may be mixed with other packages or documents that do not—common scenarios include serial processing of man pages or use of the “so” or mso requests—you may desire correct operation regardless of compatibility mode enablement in the surrounding context. It may occur to you to save the existing value of \n(.C into a register, say, _C, at the beginning of your file, turn compatibility mode off with “.cp 0”, then restore it from that register at the end with “.cp \n(_C”. At the same time, a modular design of a document or macro package may lead you to multiple layers of inclusion. You cannot use the same register name everywhere lest you “clobber” the value from a preceding or enclosing context. The two‐character register name space of AT&T troff is confining and mnemonically challenging; you may wish to use GNU troff’s more capacious name space. However, attempting “.nr _my_saved_C \n(.C” will not work in compatibility mode; the register name is too long. “This is exactly what .do is for,” you think, “.do nr _my_saved_C \n(.C”. The foregoing will always save zero to your register, because “do” turns compatibility mode off while it interprets its argument list. What you need is: .do nr _my_saved_C \n[.cp] .cp 0 at the beginning of your file, followed by .cp \n[_my_saved_C] .do rr _my_saved_C at the end. As in the C language, we all have to share one big name space, so choose a register name that is unlikely to collide with other uses. The existence of the .T string is a common feature of post‐CSTR #54 troffs—DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 troff all sup‐ port it—but valid values are specific to each implementation. The be‐ havior of the .T register in GNU troff differs from AT&T troff, which interpolated 1 only if nroff was the formatter and was called with -T. The lf request sets the number of the current input line in AT&T troff, and the next in GNU troff. AT&T troff had only environments named “0”, “1”, and “2”. In GNU troff, any number of environments may exist, using any valid identi‐ fiers for their names. GNU troff normally tracks the interpolation depth of escape sequence parameters and other delimited structures, but not in compatibility mode. See section “Miscellaneous” above. In compatibility mode, the escape sequences \f, \H, \m, \M, \R, \s, and \S are transparent at the beginning of an input line for the purpose of recognizing a control character, because they modify formatter state (\R) or properties of the environment (the rest) and therefore do not create output nodes. For example, this code produces bold output in both cases, but the text differs, .de xx ' Hello! .. \fB.xx\fP formatting “.xx” normally and “Hello!” in compatibility mode. GNU troff request names unrecognized by other troff implementations will likely be ignored; escape sequences that are GNU troff extensions are liable to format their function selector character. For example, the adjustable, non‐breaking space escape sequence \~ is also supported by Heirloom Doctools troff 050915 (September 2005), mandoc 1.9.5 (2009‐09‐21), neatroff (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User Space troff (commit 93f8143600, 2022‐08‐12), but not by So‐ laris/Illumos troffs, which will render it as ~. GNU troff does not allow the use of the escape sequences \|, \^, \&, \{, \}, \space, \', \`, \-, \_, \!, \%, or \c in identifiers; AT&T troff does. The \A escape sequence (see subsection “Escape sequences” above) may be helpful in avoiding their use. Normally, the syntax form \sn accepts only a single character (a digit) for n, consistently with other forms that originated in AT&T troff, like \*, \$, \f, \g, \k, \n, and \z. In compatibility mode only, a non‐zero n must be in the range 4–39. Legacy documents relying upon this quirk of parsing should be migrated to another \s form. [Back‐ ground: The Graphic Systems C/A/T phototypesetter (the original device target for AT&T troff) supported only a few discrete type sizes in the range 6–36 points, so Ossanna contrived a special case in the parser to do what the user must have meant. Kernighan warned of this in the 1992 revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it as a “living fossil”.] Fractional type sizes cause one noteworthy incompatibility. In AT&T troff the ps request ignores scaling units and thus “.ps 10u” sets the type size to 10 points, whereas in GNU troff it sets the type size to 10 scaled points, which may be a much smaller measurement. See subsec‐ tion “Fractional type sizes and new scaling units” above. The ab request differs from AT&T troff: GNU troff writes no message to the standard error stream if no arguments are given, and it exits with a failure status instead of a successful one. The bp request differs from AT&T troff: GNU troff does not accept a scaling unit on the argument, a page number; the former (somewhat use‐ lessly) does. In AT&T troff the pm request reports macro, string, and diversion sizes in units of 128‐byte blocks, and an argument reduces the report to a sum of the above in the same units. GNU troff ignores any arguments and reports the sizes in bytes. Unlike AT&T troff, GNU troff does not ignore the ss request if the out‐ put is a terminal device; instead, the values of minimum inter‐word and additional inter‐sentence space are each rounded down to the nearest multiple of 12. In GNU troff there is a fundamental difference between (unformatted) characters and (formatted) glyphs. Everything that affects how a glyph is output is stored with the glyph node; once a glyph node has been constructed, it is unaffected by any subsequent requests that are exe‐ cuted, including bd, cs, tkf, tr, or fp requests. Normally, glyphs are constructed from characters immediately before the glyph is added to an output line. Macros, diversions, and strings are all, in fact, the same type of object; they contain a sequence of intermixed character and glyph nodes. Special characters transform from one to the other: before being added to the output, they behave as characters; afterward, they are glyphs. A glyph node does not behave like a character node when it is processed by a macro: it does not inherit any of the special properties that the character from which it was constructed might have had. For example, the input .di x \\\\ .br .di .x produces “\\” in GNU troff. Each pair of backslashes becomes one back‐ slash glyph; the resulting backslashes are thus not interpreted as es‐ cape characters when they are reread as the diversion is output. AT&T troff would interpret them as escape characters when rereading them and end up printing one “\”. One way to format a backslash in most documents is with the \e escape sequence; this formats the glyph of the current escape character, re‐ gardless of whether it is used in a diversion; it also works in both GNU troff and AT&T troff. (Naturally, if you’ve changed the escape character, you need to prefix the “e” with whatever it is—and you’ll likely get something other than a backslash in the output.) The other correct way, appropriate in contexts independent of the back‐ slash’s common use as a roff escape character—perhaps in discussion of character sets or other programming languages—is the character escape \(rs or \[rs], for “reverse solidus”, from its name in the ECMA‐6 (ISO/IEC 646) standard. [This escape sequence is not portable to AT&T troff, but is to its lineal descendant, Heirloom Doctools troff, as of its 060716 release (July 2006).] To store an escape sequence in a diversion that is interpreted when the diversion is reread, either use the traditional \! transparent output facility, or, if this is unsuitable, the new \? escape sequence. See subsection “Escape sequences” above and sections “Diversions” and “gtroff Internals” in Groff: The GNU Implementation of troff, the groff Texinfo manual. In the somewhat pathological case where a diversion exists containing a partially collected line and a partially collected line at the top‐ level diversion has never existed, AT&T troff will output the partially collected line at the end of input; GNU troff will not. Formatter output incompatibilities Its extensions notwithstanding, the groff intermediate output format has some incompatibilities with that of AT&T troff, but better compati‐ bility is sought; problem reports and patches are welcome. The follow‐ ing incompatibilities are known. • The drawing position after rendering polygons is inconsistent with AT&T troff practice. Other implementations have diverged on this point as well. • The output cannot be easily rescaled to other devices as AT&T troff’s could. Authors This document was written by James Clark ⟨jjc@jclark.com⟩, Werner Lem‐ berg ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web.de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. “Troff User’s Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report No. 54, widely called simply “CSTR #54”, documents the language, device and font description file formats, and output format referred to collectively in groff documentation as AT&T troff. “A Typesetter‐independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science Technical Report No. 97, provides addi‐ tional insights into the device and font description file formats and output format. groff(1), groff(7), roff(7) groff 1.23.0 29 August 2023 groff_diff(7) ─────────────────────────────────────────────────────────────────────────────── groff_hdtbl(7) Miscellaneous Information Manual groff_hdtbl(7) Name groff_hdtbl - Heidelberger table macros for GNU roff Description The hdtbl macros consist of four base and three optional macros, con‐ trolled by about twenty arguments. The syntax is simple and similar to the HTML table model and nearly as flexible: you can write sequences of tokens (macro calls with their arguments and content data), separated by blanks and beginning with a macro call, into the same line to get compact and cleanly arrranged input. An advantage of hdtbl is that the tables are constructed without calling a preprocessor; this means that groff(7)’s full macro capabilities are available. On the other hand, table processing with hdtbl is much slower than using the tbl(1) pre‐ processor. A further advantage is that the HTML‐like syntax of hdtbl will be easily converted to HTML; this is not implemented yet. Usage In this and the next section, we present examples to help users under‐ stand the basic workflow of hdtbl. First of all, you must load the hdtbl.tmac file. As with nearly all other groff macro packages, there are two possibilities to do so: Either add the line .mso hdtbl.tmac to your roff file before using any macros of the hdtbl package, or add the option -m hdtbl to the command line of groff (before the document file which contains hdtbl macros). Then you can include on or more tables in your docu‐ ment, where each one must be started and ended with the .TBL and .ETB macros, respectively. In this man page, we approximate the result of each example as terminal output to be as generic as possible since hdtbl currently only supports the ps and pdf output drivers. The simplest well‐formed table consists of just single calls to the four base table macros in the right order. Here we construct a table with only one cell. .TBL .TR .TD contents of the table cell .ETB A terminal representation is +------------------------------------------------------+ | contents-of-the-table-cell | +------------------------------------------------------+ Equivalent to the above is the following notation. .TBL .TR .TD "contents of the table cell" .ETB By default, the formatted table is inserted into the surrounding text at the place of its definition. If the vertical space isn’t suffi‐ cient, it is placed at the top of the next page. Tables can also be stored for later insertion. Using ‘row‐number*column‐number’ as the data for the table cells, a ta‐ ble with two rows and two columns can be written as .TBL cols=2 . TR .TD 1*1 .TD 1*2 . TR .TD 2*1 .TD 2*2 .ETB A terminal representation is +--------------------------+---------------------------+ | 1*1 | 1*2 | +--------------------------+---------------------------+ | 2*1 | 2*2 | +--------------------------+---------------------------+ Here we see a difference from HTML tables: The number of columns must be explicitly specified using the ‘cols=m’ argument (or indirectly via the ‘width’ argument, see below). The contents of a table cell is arbitrary; for example, it can be an‐ other table, without restriction to the nesting depth. A given table layout can be either constructed with suitably nested tables or with proper arguments to .TD and .TH, controlling column and row spanning. Note, however, that this table .TBL . TR . TD . nop 1*1 1*2 . TR . TD . TBL cols=2 border= . TR . TD . nop 2*1 . TD . nop 2*2 . ETB .ETB and this table .TBL cols=2 . TR . TD colspan=2 . nop 1*1 1*2 . TR . TD . nop 2*1 . TD . nop 2*2 .ETB are similar but not identical (the use of .nop is purely cosmetic to get proper indentation). The first table looks like +------------------------------------------------------+ | 1*1 1*2 | +------------------------------------------------------+ | | | 2*1 2*2 | | | +------------------------------------------------------+ and the second one like +------------------------------------------------------+ | 1*1 1*2 | +---------------------------+--------------------------+ | 2*1 | 2*2 | +---------------------------+--------------------------+ Here is the latter table in a more compact form. .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2 . TR .TD 2*1 .TD 2*2 .ETB If a macro has one or more arguments (see below), and it is not start‐ ing a line, everything belonging to this macro including the macro it‐ self must be enclosed in double quotes. Macros and arguments The order of macro calls and other tokens follows the HTML model. In the following list, valid predecessors and successors of all hdtbl macros are given, together with the possible arguments. Macro arguments are separated by blanks. The order of arguments is ar‐ bitrary; they are of the form key=value or key='value1 [value2 [...]]' with the only exception of the optional argument of the macro .ETB, which is the string ‘hold’. Another possible form is "key=value1 [value2 [...]]" However, this is limited to the case where the macro is the first one in the line and not already enclosed in double quotes. Argument values specified below as c are colors predefined by groff or colors defined by the user with the .defcolor request. Argument val‐ ues d are decimal numbers with or without decimal point. Argument val‐ ues m are natural numbers. Argument values n are numerical values with the usual groff scaling indicators. Some of the arguments are specific to one or two macros, but most of them can be specified with .TBL, .TR, .TD, and .TH. These common arguments are explained in the next subsec‐ tion. Most of the argument default values can be changed by the user by set‐ ting corresponding default registers or strings, as listed below. .TBL [args] Begin a new table. predecessor: .TD, .TH, .ETB, cell contents successor: .CPTN, .TR arguments: border=[n] Thickness of the surrounding box border. ‘border=’ (no value) means neither a surrounding box border nor any horizontal or vertical separa‐ tor lines between the table rows and cells. ‘border=0’ suppresses the surrounding box border, but still allows separator lines between cells and rows. Default: ‘border=.1n’ (register ‘t*b’). bc=c Border color. Default: ‘bc=red4’ (string ‘t*bc’). cols=m Number of table columns. This argument is neces‐ sary if more than one column is in the table and no ‘width’ arguments are present. Default: ‘cols=1’ (register ‘t*cols’). cpd=n Cell padding, i.e., the extra space between the cell space border and the cell contents. Default: ‘cpd=.5n’ (register ‘t*cpd’). csp=n Cell spacing, i.e., the extra space between the table border or vertical or horizontal lines be‐ tween cells and the cellspace. Default: ‘csp=.5n’ (register ‘t*csp’). tal=l|c|r Horizontal alignment of the table, if it is smaller than the line width. ‘tal=l’: left align‐ ment. ‘tal=c’: centered alignment. ‘tal=r’: right alignment. Default: ‘tal=l’ (register ‘t*tal’). width='w1 [w2 [...]]' Widths of table cells. w1, w2, ... are either numbers of type n or natural numbers with the pseudo‐scaling indicator ‘%’, with the meaning “percent of the actual line length (or column length for inner tables, respectively)”. If there are less width values than table columns, the last width value is used for the remaining cells. The argument width='1.5i 10%' for example indicates that the first column is 1.5 inches wide; the remaining columns take 1/10 of the column length each. Default: The table width equals the outer line length or column length; the columns have equal widths. height=n Height of the table. If the table with its con‐ tents is lower than n, the last row is stretched to this value. .CPTN [args] Text of caption. The (optionally numbered) table caption. .CPTN is optional. predecessor: .TBL successor: .TR arguments: val=t|b Vertical alignment of the table caption. ‘val=t’: The caption is placed above the table. ‘val=b’: The caption is placed below the table. Default: ‘val=t’ (string ‘t*cptn’). .TR [args] Begin a new table row. predecessor: .TBL, .CPTN, .TD, .TH, .ETB, cell contents successor: .TD, .TH arguments: height=n The height of the row. If a cell in the row is higher than n, this value is ignored; otherwise the row height is stretched to n. .TD [args [cell contents]] Begin a table data cell. .TH [args [cell contents]] Begin a table header cell. Arguments and cell contents can be mixed. The macro .TH is not really necessary and differs from .TD only in three default set‐ tings, similar to the and HTML tags: The contents of .TH is horizontally and vertically centered and typeset in bold‐ face. predecessor: .TR, .TD, .TH, .ETB, cell contents successor: .TD, .TH, .TR, .ETB, cell contents arguments: colspan=m The width of this cell is the sum of the widths of the m cells above and below this row. rowspan=m The height of this cell is the sum of the heights of the m cells left and right of this column. Remark: Overlapping of column and row spanning, as in the following table fragment (the overlapping happens in the second cell in the second row), is invalid and causes incorrect results. .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3 .TR ".TD 2*1 colspan=2" .TD 2*3 A working example for headers and cells with colspan is .TBL cols=3 . TR ".TH colspan=2" header1+2 .TH header3 . TR .TD 1*1 .TD 1*2 .TD 1*3 . TR .TD 2*1 ".TD colspan=2" 2*2+3 .ETB This looks like +------------------------------+---------------+ | header1+2 | header3 | +--------------+---------------+---------------+ | 1*1 | 1*2 | 1*3 | +--------------+---------------+---------------+ | 2*1 | 2*2+3 | +--------------+-------------------------------+ A working example with rowspan is .TBL cols=3 . TR . TD 1*1 . TD rowspan=2 1+2*2 . TD 1*3 . . TR . TD 2*1 . TD 2*3 .ETB which looks like +--------------+---------------+---------------+ | 1*1 | 1+2*2 | 1*3 | +--------------+ +---------------+ | 2*1 | | 2*3 | +--------------+---------------+---------------+ .ETB [hold] End of the table. This macro finishes a table. It causes one of the following ac‐ tions. • If the argument ‘hold’ is given, the table is held until it is freed by calling the macro .t*free, which in turn prints the table immediately, either at the current position or at the top of the next page if its height is larger than the re‐ maining space on the page. • Otherwise, if the table is higher than the remaining space on the page, it is printed at the top of the next page. • If neither of the two above constraints hold, the table is printed immediately at the place of its definition. predecessor: .TD, .TH, .ETB, cell contents successor: .TBL, .TR, .TD, .TH, .ETB, cell contents arguments: hold Prevent the table from being printed until it is freed by calling the macro .t*free. This argument is ignored for inner (nested) tables. .t*free [n] Free the next held table or n held tables. Call this utility macro to print tables which are held by using the ‘hold’ argu‐ ment of the .ETB macro. Arguments common to .TBL, .TR, .TD, and .TH The arguments described in this section can be specified with the .TBL and .TR macros, but they are eventually passed on to the table cells. If omitted, the defaults take place, which the user can change by set‐ ting the corresponding default registers or strings, as documented be‐ low. Setting an argument with the .TBL macro has the same effect as setting it for all rows in the table. Setting an argument with a .TR macro has the same effect as setting it for all the .TH or .TD macro in this row. bgc=[c] The background color of the table cells. This includes the area specified with the ‘csp’ argument. The argument ‘bgc=’ (no value) suppresses a background color; this makes the background transparent. Default: ‘bgc=bisque’ (string ‘t*bgc’). fgc=c The foreground color of the cell contents. Default: ‘fgc=red4’ (string ‘t*fgc’). ff=name The font family for the table. name is a groff font family identifier, such as A for Avant Garde or HN for Helvetica Nar‐ row. Default: The font family found before the table (string ‘t*ff’). fst=style The font style for the table. One of R, B, I, or BI for roman, bold, italic, or bold italic, respectively. As with roff’s .ft request, the ‘fst’ argument can be used to specify the font fam‐ ily and font style together, for example ‘fst=HNBI’ instead of ‘ff=HN’ and ‘fst=BI’. Default: The font style in use right before the table (string ‘t*fst’). fsz='d1 [d2]' A decimal or fractional factor d1, by which the point size for the table is changed, and d2, by which the vertical line spacing is changed. If d2 is omitted, value d1 is taken for both. Default: ‘fsz='1.0 1.0'’ (string ‘t*fsz’). hal=l|c|b|r Horizontal alignment of the cell contents in the table. ‘hal=l’: left alignment. ‘hal=c’: centered alignment. ‘hal=b’: both (left and right) alignment. ‘hal=r’: right alignment. Default: ‘hal=b’ (string ‘t*hal’). val=t|m|b Vertical alignment of the cell contents in the table for cells lower than the current row. ‘val=t’: alignment below the top of the cell. ‘val=m’: alignment in the middle of the cell. ‘val=b’: alignment above the cell bottom. Default: ‘val=t’ (string ‘t*val’). hl=[s|d] Horizontal line between the rows. If specified with .TD or .TH this is a separator line to the cell below. ‘hl=’ (no value): no separator line. ‘hl=s’: a single separator line between the rows. ‘hl=d’: a double separator line. The thickness of the separator lines is the half of the border thickness, but at least 0.1 inches. The distance between the double lines is equal to the line thickness. Remark: Together with ‘border=0’ for proper formatting the value of ‘csp’ must be at least .05 inches for single separator lines and .15 inches for double separator lines. Default: ‘hl=s’ (string ‘t*hl’). vl=[s|d] Vertical separator line between the cells. If specified with .TD or .TH this is a separator line to the cell on the right. ‘vl=s’: a single separator line between the cells. ‘vl=d’: a double separator line. ‘vl=’ (no value): no vertical cell sepa‐ rator lines. For more information see the documentation of the ‘hl’ argument above. Default: ‘vl=s’ (string ‘t*vl’). hdtbl customization Before creating the first table, you should configure default values to minimize the markup needed in each table. The following example sets up defaults suitable for typical papers: .ds t*bgc white\" background color .ds t*fgc black\" foreground color .ds t*bc black\" border color .nr t*cpd 0.1n\" cell padding The file /usr/local/share/doc/groff-1.23.0/examples/hdtbl/common.roff provides another example setup in the “minimal Page setup” section. A table which does not fit on a partially filled page is printed auto‐ matically on the top of the next page if you append the little utility macro t*hm to the page header macro of your document’s main macro pack‐ age. For example, say .am pg@top . t*hm .. if you use the ms macro package. The macro t*EM checks for held or kept tables, and for missing ETB macros (table not closed). You can call this macro by appending it the to end‐of‐input macro of the main, or “full‐service”, macro package your document uses. For example, try .am pg@end-text . t*EM .. if you use the ms package. Bugs and suggestions Please send your comments to the groff mailing list ⟨groff@gnu.org⟩ or directly to the author. Authors The hdtbl macro package was written by Joachim Walsdorff ⟨Joachim .Walsdorff@urz.uni-heidelberg.de⟩. See also groff(1) provides an overview of GNU roff and details how to invoke groff at the command line. groff(7) summarizes the roff language and GNU extensions to it. tbl(1) describes the traditional roff preprocessor for tables. groff 1.23.0 29 August 2023 groff_hdtbl(7) ─────────────────────────────────────────────────────────────────────────────── groff_man(7) Miscellaneous Information Manual groff_man(7) Name groff_man - compose manual pages with GNU roff Synopsis groff -man [option ...] [file ...] groff -m man [option ...] [file ...] Description The GNU implementation of the man macro package is part of the groff document formatting system. It is used to produce manual pages (“man pages”) like the one you are reading. This document presents the macros thematically; for those needing only a quick reference, the following table lists them alphabetically, with cross references to appropriate subsections below. Man page authors and maintainers who are not already experienced groff users should consult groff_man_style(7), an expanded version of this document, for additional explanations and advice. It covers only those concepts required for man page document maintenance, and not the full breadth of the groff typesetting system. Macro Meaning Subsection ─────────────────────────────────────────────────────────────── .B Bold Font style macros .BI Bold, italic alternating Font style macros .BR Bold, roman alternating Font style macros .EE Example end Document structure macros .EX Example begin Document structure macros .I Italic Font style macros .IB Italic, bold alternating Font style macros .IP Indented paragraph Paragraphing macros .IR Italic, roman alternating Font style macros .LP Begin paragraph Paragraphing macros .ME Mail‐to end Hyperlink macros .MR Man page cross reference Hyperlink macros .MT Mail‐to start Hyperlink macros .P Begin paragraph Paragraphing macros .PP Begin paragraph Paragraphing macros .RB Roman, bold alternating Font style macros .RE Relative inset end Document structure macros .RI Roman, italic alternating Font style macros .RS Relative inset start Document structure macros .SB Small bold Font style macros .SH Section heading Document structure macros .SM Small Font style macros .SS Subsection heading Document structure macros .SY Synopsis start Command synopsis macros .TH Title heading Document structure macros .TP Tagged paragraph Paragraphing macros .TQ Supplemental paragraph tag Paragraphing macros .UE URI end Hyperlink macros .UR URI start Hyperlink macros .YS Synopsis end Command synopsis macros We discuss other macros (.AT, .DT, .HP, .OP, .PD, and .UC) in subsec‐ tion “Deprecated features” below. Throughout Unix documentation, a manual entry is referred to simply as a “man page”, regardless of its length, without gendered implication, and irrespective of the macro package selected for its composition. Macro reference preliminaries A tagged paragraph describes each macro. We present coupled pairs to‐ gether, as with .EX and .EE. An empty macro argument can be specified with a pair of double‐quotes (""), but the man package is designed such that this should seldom be necessary. Most macro arguments will be formatted as text in the out‐ put; exceptions are noted. Document structure macros Document structure macros organize a man page’s content. All of them break the output line. .TH (title heading) identifies the document as a man page and configures the page headers and footers. Section head‐ ings (.SH), one of which is mandatory and many of which are convention‐ ally expected, facilitate location of material by the reader and aid the man page writer to discuss all essential aspects of the topic. Subsection headings (.SS) are optional and permit sections that grow long to develop in a controlled way. Many technical discussions bene‐ fit from examples; lengthy ones, especially those reflecting multiple lines of input to or output from the system, are usefully bracketed by .EX and .EE. When none of the foregoing meets a structural demand, use .RS/.RE to inset a region within a (sub)section. .TH topic section [footer‐middle] [footer‐inside] [header‐middle] Determine the contents of the page header and footer. The sub‐ ject of the man page is topic and the section of the manual to which it belongs is section. See man(1) or intro(1) for the manual sectioning applicable to your system. topic and section are positioned together at the left and right in the header (with section in parentheses immediately appended to topic). footer‐middle is centered in the footer. The arrangement of the rest of the footer depends on whether double‐sided layout is en‐ abled with the option -rD1. When disabled (the default), footer‐inside is positioned at the bottom left. Otherwise, footer‐inside appears at the bottom left on recto (odd‐numbered) pages, and at the bottom right on verso (even‐numbered) pages. The outside footer is the page number, except in the continuous‐ rendering mode enabled by the option -rcR=1, in which case it is the topic and section, as in the header. header‐middle is cen‐ tered in the header. If section is an integer between 1 and 9 (inclusive), there is no need to specify header‐middle; an.tmac will supply text for it. The macro package may also abbreviate topic and footer‐inside with ellipses if they would overrun the space available in the header and footer, respectively. For HTML output, headers and footers are suppressed. Additionally, this macro breaks the page, resetting the number to 1 (unless the -rC1 option is given). This feature is in‐ tended only for formatting multiple man documents in sequence. A valid man document calls .TH once, early in the file, prior to any other macro calls. .SH [heading‐text] Set heading‐text as a section heading. If no argument is given, a one‐line input trap is planted; text on the next line becomes heading‐text. The left margin is reset to zero to set the head‐ ing text in bold (or the font specified by the string HF), and, on typesetting devices, slightly larger than the base type size. If the heading font \*[HF] is bold, use of an italic style in heading‐text is mapped to the bold‐italic style if available in the font family. The inset level is reset to 1, setting the left margin to the value of the IN register. Text after head‐ ing‐text is set as an ordinary paragraph (.P). The content of heading‐text and ordering of sections follows a set of common practices, as has much of the layout of material within sections. For example, a section called “Name” or “NAME” must exist, must be the first section after the .TH call, and must contain only text of the form topic[, another‐topic]... \- summary‐description for a man page to be properly indexed. See groff_man_style(7) for suggestions and man(7) for the conventions prevailing on your system. .SS [subheading‐text] Set subheading‐text as a subsection heading indented between a section heading and an ordinary paragraph (.P). If no argument is given, a one‐line input trap is planted; text on the next line becomes subheading‐text. The left margin is reset to the value of the SN register to set the heading text in bold (or the font specified by the string HF). If the heading font \*[HF] is bold, use of an italic style in subheading‐text is mapped to the bold‐italic style if available in the font family. The inset level is reset to 1, setting the left margin to the value of the IN register. Text after subheading‐text is set as an ordinary paragraph (.P). .EX .EE Begin and end example. After .EX, filling is disabled and a constant‐width (monospaced) font is selected. Calling .EE en‐ ables filling and restores the previous font. These macros are extensions introduced in Ninth Edition Research Unix. Systems running that troff, or those from Documenter’s Workbench, Heirloom Doctools, or Plan 9 troff support them. To be certain your page will be portable to systems that do not, copy their definitions from the an-ext.tmac file of a groff in‐ stallation. .RS [inset‐amount] Start a new relative inset level. The position of the left mar‐ gin is saved, then moved right by inset‐amount, if specified, and by the amount of the IN register otherwise. Calls to .RS can be nested; each increments by 1 the inset level used by .RE. The level prior to any .RS calls is 1. .RE [level] End a relative inset. The left margin corresponding to inset level level is restored. If no argument is given, the inset level is reduced by 1. Paragraphing macros An ordinary paragraph (.P) is set without a first‐line indentation at the current left margin. In man pages and other technical literature, definition lists are frequently encountered; these can be set as “tagged paragraphs”, which have one (.TP) or more (.TQ) leading tags followed by a paragraph that has an additional indentation. The in‐ dented paragraph (.IP) macro is useful to continue the indented content of a narrative started with .TP, or to present an itemized or ordered list. All of these macros break the output line. If another paragraph macro has occurred since the previous .SH or .SS, they (except for .TQ) follow the break with a default amount of vertical space, which can be changed by the deprecated .PD macro; see subsection “Horizontal and vertical spacing” below. They also reset the type size and font style to defaults (.TQ again excepted); see subsection “Font style macros” below. .P .LP .PP Begin a new paragraph; these macros are synonymous. The inden‐ tation is reset to the default value; the left margin, as af‐ fected by .RS and .RE, is not. .TP [indentation] Set a paragraph with a leading tag, and the remainder of the paragraph indented. A one‐line input trap is planted; text on the next line, which can be formatted with a macro, becomes the tag, which is placed at the current left margin. The tag can be extended with the \c escape sequence. Subsequent text is in‐ dented by indentation, if specified, and by the amount of the IN register otherwise. If the tag is not as wide as the indenta‐ tion, the paragraph starts on the same line as the tag, at the applicable indentation, and continues on the following lines. Otherwise, the descriptive part of the paragraph begins on the line following the tag. .TQ Set an additional tag for a paragraph tagged with .TP. An input trap is planted as with .TP. This macro is a GNU extension not defined on systems running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. .IP [tag] [indentation] Set an indented paragraph with an optional tag. The tag and in‐ dentation arguments, if present, are handled as with .TP, with the exception that the tag argument to .IP cannot include a macro call. Command synopsis macros .SY and .YS aid you to construct a command synopsis that has the clas‐ sical Unix appearance. They break the output line. These macros are GNU extensions not defined on systems running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. .SY command Begin synopsis. A new paragraph begins at the left margin un‐ less .SY has already been called without a corresponding .YS, in which case only a break is performed. Adjustment and automatic hyphenation are disabled. command is set in bold. If a break is required, lines after the first are indented by the width of command plus a space. .YS End synopsis. Indentation, adjustment, and hyphenation are re‐ stored to their previous states. Hyperlink macros Man page cross references are best presented with .MR. Text may be hy‐ perlinked to email addresses with .MT/.ME or other URIs with .UR/.UE. Hyperlinked text is supported on HTML and terminal output devices; ter‐ minals and pager programs must support ECMA‐48 OSC 8 escape sequences (see grotty(1)). When device support is unavailable or disabled with the U register (see section “Options” below), .MT and .UR URIs are ren‐ dered between angle brackets after the linked text. .MT, .ME, .UR, and .UE are GNU extensions not defined on systems run‐ ning AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. Plan 9 from User Space’s troff implements .MR. The arguments to .MR, .MT, and .UR should be prepared for typesetting since they can appear in the output. Use special character escape se‐ quences to encode Unicode basic Latin characters where necessary, par‐ ticularly the hyphen‐minus. The formatter removes \: escape sequences from hyperlinks when supplying device control commands to output dri‐ vers. .MR topic manual‐section [trailing‐text] (since groff 1.23) Set a man page cross reference as “topic(man‐ ual‐section)”. If trailing‐text (typically punctuation) is specified, it follows the closing parenthesis without interven‐ ing space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. The cross reference hyperlinks to a URI of the form “man:topic(man‐ ual‐section)”. .MT address .ME [trailing‐text] Identify address as an RFC 6068 addr‐spec for a “mailto:” URI with the text between the two macro calls as the link text. An argument to .ME is placed after the link text without interven‐ ing space. address may not be visible in the rendered document if hyperlinks are enabled and supported by the output driver. If they are not, address is set in angle brackets after the link text and before trailing‐text. If hyperlinking is enabled but there is no link text, address is formatted and hyperlinked without angle brackets. .UR uri .UE [trailing‐text] Identify uri as an RFC 3986 URI hyperlink with the text between the two macro calls as the link text. An argument to .UE is placed after the link text without intervening space. uri may not be visible in the rendered document if hyperlinks are en‐ abled and supported by the output driver. If they are not, uri is set in angle brackets after the link text and before trail‐ ing‐text. If hyperlinking is enabled but there is no link text, uri is formatted and hyperlinked without angle brackets. The hyperlinking of .TP paragraph tags with .UR/.UE and .MT/.ME is not yet supported; if attempted, the hyperlink will be typeset at the be‐ ginning of the indented paragraph even on hyperlink‐supporting devices. Font style macros The man macro package is limited in its font styling options, offering only bold (.B), italic (.I), and roman. Italic text is usually set un‐ derscored instead on terminal devices. The .SM and .SB macros set text in roman or bold, respectively, at a smaller type size; these differ visually from regular‐sized roman or bold text only on typesetting de‐ vices. It is often necessary to set text in different styles without intervening space. The macros .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R” indicate bold, italic, and roman, respectively, set their odd‐ and even‐numbered arguments in alternating styles, with no space separating them. The default type size and family for typesetting devices is 10‐point Times, except on the X75-12 and X100-12 devices where the type size is 12 points. The default style is roman. .B [text] Set text in bold. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further formatted with a macro, is set in bold. .I [text] Set text in an italic or oblique face. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further formatted with a macro, is set in an italic or oblique face. .SM [text] Set text one point smaller than the default type size on type‐ setting devices. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further format‐ ted with a macro, is set smaller. .SB [text] Set text in bold and (on typesetting devices) one point smaller than the default type size. If no argument is given, a one‐line input trap is planted; text on the next line, which can be fur‐ ther formatted with a macro, is set smaller and in bold. This macro is an extension introduced in SunOS 4.0. Unlike the above font style macros, the font style alternation macros below set no input traps; they must be given arguments to have effect. Italic corrections are applied as appropriate. .BI bold‐text italic‐text ... Set each argument in bold and italics, alternately. .BR bold‐text roman‐text ... Set each argument in bold and roman, alternately. .IB italic‐text bold‐text ... Set each argument in italics and bold, alternately. .IR italic‐text roman‐text ... Set each argument in italics and roman, alternately. .RB roman‐text bold‐text ... Set each argument in roman and bold, alternately. .RI roman‐text italic‐text ... Set each argument in roman and italics, alternately. Horizontal and vertical spacing The indentation argument accepted by .IP, .TP, and the deprecated .HP is a number plus an optional scaling unit, as is .RS’s inset‐amount. If no scaling unit is given, the man package assumes “n”. An indenta‐ tion specified in a call to .IP, .TP, or the deprecated .HP persists until (1) another of these macros is called with an indentation argu‐ ment, or (2) .SH, .SS, or .P or its synonyms is called; these clear the indentation entirely. The left margin used by ordinary paragraphs set with .P (and its syn‐ onyms) not within an .RS/.RE relative inset is 7.2n for typesetting de‐ vices and 7n for terminal devices (but see the -rIN option). Headers, footers (both set with .TH), and section headings (.SH) are set at the page offset (see groff(7)) and subsection headings (.SS) indented from it by 3n (but see the -rSN option). Several macros insert vertical space: .SH, .SS, .TP, .P (and its syn‐ onyms), .IP, and the deprecated .HP. The default inter‐section and in‐ ter‐paragraph spacing is is 1v for terminal devices and 0.4v for type‐ setting devices. (The deprecated macro .PD can change this vertical spacing, but its use is discouraged.) Between .EX and .EE calls, the inter‐paragraph spacing is 1v regardless of output device. Registers Registers are described in section “Options” below. They can be set not only on the command line but in the site man.local file as well; see section “Files” below. Strings The following strings are defined for use in man pages. None of these is necessary in a contemporary man page; see groff_man_style(7). Oth‐ ers are supported for configuration of rendering parameters; see sec‐ tion “Options” below. \*R interpolates a special character escape sequence for the “regis‐ tered sign” glyph, \(rg, if available, and “(Reg.)” otherwise. \*S interpolates an escape sequence setting the type size to the document default. \*(lq \*(rq interpolate special character escape sequences for left and right double‐quotation marks, \(lq and \(rq, respectively. \*(Tm interpolates a special character escape sequence for the “trade mark sign” glyph, \(tm, if available, and “(TM)” otherwise. Hooks Two macros, both GNU extensions, are called internally by the groff man package to format page headers and footers and can be redefined by the administrator in a site’s man.local file (see section “Files” below). The presentation of .TH above describes the default headers and foot‐ ers. Because these macros are hooks for groff man internals, man pages have no reason to call them. Such hook definitions will likely consist of “.sp” and “.tl” requests. They must also increase the page length with “.pl” requests in continuous rendering mode; .PT furthermore has the responsibility of emitting a PDF bookmark after writing the first page header in a document. Consult the existing implementations in an.tmac when drafting replacements. .BT Set the page footer text (“bottom trap”). .PT Set the page header text (“page trap”). To remove a page header or footer entirely, define the appropriate macro as empty rather than deleting it. Deprecated features Use of the following in man pages for public distribution is discour‐ aged. .AT [system [release]] Alter the footer for use with legacy AT&T man pages, overriding any definition of the footer‐inside argument to .TH. This macro exists only to render man pages from historical systems. system can be any of the following. 3 7th edition (default) 4 System III 5 System V The optional release argument specifies the release number, as in “System V Release 3”. .DT Reset tab stops to the default (every 0.5i). Use of this presentation‐oriented macro is deprecated. It translates poorly to HTML, under which exact space control and tabulation are not readily available. Thus, information or dis‐ tinctions that you use tab stops to express are likely to be lost. If you feel tempted to change the tab stops such that calling this macro later is desirable to restore them, you should probably be composing a table using tbl(1) instead. .HP [indentation] Set up a paragraph with a hanging left indentation. The inden‐ tation argument, if present, is handled as with .TP. Use of this presentation‐oriented macro is deprecated. A hang‐ ing indentation cannot be expressed naturally under HTML, and non‐roff‐based man page interpreters may treat .HP as an ordi‐ nary paragraph. Thus, information or distinctions you mean to express with indentation may be lost. .OP option‐name [option‐argument] Indicate an optional command parameter called option‐name, which is set in bold. If the option takes an argument, specify op‐ tion‐argument using a noun, abbreviation, or hyphenated noun phrase. If present, option‐argument is preceded by a space and set in italics. Square brackets in roman surround both argu‐ ments. Use of this quasi‐semantic macro, an extension originating in Documenter’s Workbench troff, is deprecated. It cannot easily be used to annotate options that take optional arguments or op‐ tions whose arguments have internal structure (such as a mixture of literal and variable components). One could work around these limitations with font selection escape sequences, but it is preferable to use font style alternation macros, which afford greater flexibility. .PD [vertical‐space] Define the vertical space between paragraphs or (sub)sections. The optional argument vertical‐space specifies the amount; the default scaling unit is “v”. Without an argument, the spacing is reset to its default value; see subsection “Horizontal and vertical spacing” above. Use of this presentation‐oriented macro is deprecated. It translates poorly to HTML, under which exact control of inter‐ paragraph spacing is not readily available. Thus, information or distinctions that you use .PD to express are likely to be lost. .UC [version] Alter the footer for use with legacy BSD man pages, overriding any definition of the footer‐inside argument to .TH. This macro exists only to render man pages from historical systems. version can be any of the following. 3 3rd Berkeley Distribution (default) 4 4th Berkeley Distribution 5 4.2 Berkeley Distribution 6 4.3 Berkeley Distribution 7 4.4 Berkeley Distribution History M. Douglas McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed, imple‐ mented, and documented the AT&T man macros for Unix Version 7 (1979) and employed them to edit the first volume of its Programmer’s Manual, a compilation of all man pages supplied by the system. That man sup‐ ported the macros listed in this page not described as extensions, ex‐ cept .P and the deprecated .AT and .UC. The only strings defined were R and S; no registers were documented. .UC appeared in 3BSD (1980). Unix System III (1980) introduced .P and exposed the registers IN and LL, which had been internal to Seventh Edition Unix man. PWB/UNIX 2.0 (1980) added the Tm string. 4BSD (1980) added lq and rq strings. SunOS 2.0 (1985) recognized C, D, P, and X registers. 4.3BSD (1986) added .AT and .P. Ninth Edition Re‐ search Unix (1986) introduced .EX and .EE. SunOS 4.0 (1988) added .SB. The foregoing features were what James Clark implemented in early ver‐ sions of groff. Later, groff 1.20 (2009) originated .SY/.YS, .TQ, .MT/.ME, and .UR/.UE. Plan 9 from User Space’s troff introduced .MR in 2020. Options The following groff options set registers (with -r) and strings (with -d) recognized and used by the man macro package. To ensure rendering consistent with output device capabilities and reader preferences, man pages should never manipulate them. -dAD=adjustment‐mode Set line adjustment to adjustment‐mode, which is typically “b” for adjustment to both margins (the default), or “l” for left alignment (ragged right margin). Any valid argument to groff’s “.ad” request may be used. See groff(7) for less‐common choices. -rcR=1 Enable continuous rendering. Output is not paginated; instead, one (potentially very long) page is produced. This is the de‐ fault for terminal and HTML devices. Use -rcR=0 to disable it on terminal devices; on HTML devices, it cannot be disabled. -rC1 Number output pages consecutively, in strictly increasing se‐ quence, rather than resetting the page number to 1 (or the value of register P) with each new man document. -rCS=1 Set section headings (the argument(s) to .SH) in full capitals. This transformation is off by default because it discards case distinction information. -rCT=1 Set the man page topic (the first argument to .TH) in full capi‐ tals in headers and footers. This transformation is off by de‐ fault because it discards case distinction information. -rD1 Enable double‐sided layout, formatting footers for even and odd pages differently; see the description of .TH in subsection “Document structure macros” above. -rFT=footer‐distance Set distance of the footer relative to the bottom of the page to footer‐distance; this amount is always negative. At one half‐ inch above this location, the page text is broken before writing the footer. Ignored if continuous rendering is enabled. The default is -0.5i. -dHF=heading‐font Set the font used for section and subsection headings; the de‐ fault is “B” (bold style of the default family). Any valid ar‐ gument to groff’s “.ft” request may be used. See groff(7). -rHY=0 Disable automatic hyphenation. Normally, it is enabled (1). The hyphenation mode is determined by the groff locale; see sec‐ tion “Localization“ of groff(7). -rIN=standard‐indentation Set the amount of indentation used for ordinary paragraphs (.P and its synonyms) and the default indentation amount used by .IP, .RS, .TP, and the deprecated .HP. See subsection “Horizon‐ tal and vertical spacing” above for the default. For terminal devices, standard‐indentation should always be an integer multi‐ ple of unit “n” to get consistent indentation. -rLL=line‐length Set line length; the default is 78n for terminal devices and 6.5i for typesetting devices. -rLT=title‐length Set the line length for titles. By default, it is set to the line length (see -rLL above). -dMF=man‐page‐topic‐font Set the font used for man page topics named in .TH and .MR calls; the default is “I” (italic style of the default family). Any valid argument to groff’s “.ft” request may be used. If the MF string ends in “I”, it is assumed to be an oblique typeface, and italic corrections are applied before and after man page topics. -rPn Start enumeration of pages at n. The default is 1. -rStype‐size Use type‐size for the document’s body text; acceptable values are 10, 11, or 12 points. See subsection “Font style macros” above for the default. -rSN=subsection‐indentation Set indentation of subsection headings to subsection‐indenta‐ tion. See subsection “Horizontal and vertical spacing” above for the default. -rU1 Enable generation of URI hyperlinks in the grohtml and grotty output drivers. grohtml enables them by default; grotty does not, pending more widespread pager support for OSC 8 escape se‐ quences. Use -rU0 to disable hyperlinks; this will make the ar‐ guments to MT and UR calls visible in the document text produced by link‐capable drivers. -rXp Number successors of page p as pa, pb, pc, and so forth. The register tracking the suffixed page letter uses format “a” (see the “.af” request in groff(7)). Files /usr/local/share/groff/1.23.0/tmac/an.tmac Most man macros are defined in this file. It also loads exten‐ sions from an-ext.tmac (see below). /usr/local/share/groff/1.23.0/tmac/andoc.tmac This brief groff program detects whether the man or mdoc macro package is being used by a document and loads the correct macro definitions, taking advantage of the fact that pages using them must call .TH or .Dd, respectively, before any other macros. A man program or user typing, for example, “groff -mandoc page.1”, need not know which package the file page.1 uses. Multiple man pages, in either format, can be handled; andoc reloads each macro package as necessary. /usr/local/share/groff/1.23.0/tmac/an-ext.tmac Except for .SB, definitions of macros described above as exten‐ sions are contained in this file; in some cases, they are sim‐ pler versions of definitions appearing in an.tmac, and are ig‐ nored if the formatter is GNU troff. They are written to be compatible with AT&T troff and permissively licensed—not copy‐ lefted. To reduce the risk of name space collisions, string and register names begin only with “m”. We encourage man page au‐ thors who are concerned about portability to legacy Unix systems to copy these definitions into their pages, and maintainers of troff implementations or work‐alike systems that format man pages to re‐use them. The definitions for these macros are read after a page calls .TH, so they will replace any macros of the same names preceding it in your file. If you use your own implementations of these macros, they must be defined after .TH is called to have any ef‐ fect. Furthermore, it is wise to define such page‐local macros (if at all) after the “Name” section to accommodate timid make‐ whatis or mandb implementations that may give up their scan for indexing material early. /usr/local/share/groff/1.23.0/tmac/man.tmac This is a wrapper that loads an.tmac. /usr/local/share/groff/1.23.0/tmac/mandoc.tmac This is a wrapper that loads andoc.tmac. /usr/local/share/groff/site-tmac/man.local Put site‐local changes and customizations into this file. Authors The initial GNU implementation of the man macro package was written by James Clark. Later, Werner Lemberg ⟨wl@gnu.org⟩ supplied the S, LT, and cR registers, the last a 4.3BSD‐Reno mdoc(7) feature. Larry Kollar ⟨kollar@alltel.net⟩ added the FT, HY, and SN registers; the HF string; and the PT and BT macros. G. Branden Robinson ⟨g.branden.robinson@ gmail.com⟩ implemented the AD and MF strings; CS, CT, and U registers; and the MR macro. Except for .SB, the extension macros were written by Lemberg, Eric S. Raymond ⟨esr@thyrsus.com⟩, and Robinson. This document was originally written for the Debian GNU/Linux system by Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by Lemberg and Robinson. The extension macros were documented by Raymond and Robinson. See also tbl(1), eqn(1), and refer(1) are preprocessors used with man pages. man(1) describes the man page librarian on your system. groff_mdoc(7) details the groff version of the BSD‐originated alternative macro pack‐ age for man pages. groff_man_style(7), groff(7), groff_char(7), man(7) groff 1.23.0 29 August 2023 groff_man(7) ─────────────────────────────────────────────────────────────────────────────── groff_man_style(7) Miscellaneous Information Manual groff_man_style(7) Name groff_man_style - GNU roff man page tutorial and style guide Synopsis groff -man [option ...] [file ...] groff -m man [option ...] [file ...] Description The GNU implementation of the man macro package is part of the groff document formatting system. It is used to produce manual pages (“man pages”) like the one you are reading. This document presents the macros thematically; for those needing only a quick reference, the following table lists them alphabetically, with cross references to appropriate subsections below. Macro Meaning Subsection ─────────────────────────────────────────────────────────────── .B Bold Font style macros .BI Bold, italic alternating Font style macros .BR Bold, roman alternating Font style macros .EE Example end Document structure macros .EX Example begin Document structure macros .I Italic Font style macros .IB Italic, bold alternating Font style macros .IP Indented paragraph Paragraphing macros .IR Italic, roman alternating Font style macros .LP Begin paragraph Paragraphing macros .ME Mail‐to end Hyperlink macros .MR Man page cross reference Hyperlink macros .MT Mail‐to start Hyperlink macros .P Begin paragraph Paragraphing macros .PP Begin paragraph Paragraphing macros .RB Roman, bold alternating Font style macros .RE Relative inset end Document structure macros .RI Roman, italic alternating Font style macros .RS Relative inset start Document structure macros .SB Small bold Font style macros .SH Section heading Document structure macros .SM Small Font style macros .SS Subsection heading Document structure macros .SY Synopsis start Command synopsis macros .TH Title heading Document structure macros .TP Tagged paragraph Paragraphing macros .TQ Supplemental paragraph tag Paragraphing macros .UE URI end Hyperlink macros .UR URI start Hyperlink macros .YS Synopsis end Command synopsis macros We discuss other macros (.AT, .DT, .HP, .OP, .PD, and .UC) in subsec‐ tion “Deprecated features” below. Throughout Unix documentation, a manual entry is referred to simply as a “man page”, regardless of its length, without gendered implication, and irrespective of the macro package selected for its composition. Man pages should be encoded using Unicode basic Latin code points ex‐ clusively, and employ the Unix line‐ending convention (U+000A only). Fundamental concepts groff is a programming system for typesetting: we thus often use the verb “to set” in the sense “to typeset”. The formatter troff(1) col‐ lects words from the input and fills output lines with as many as will fit. Words are separated by spaces and newlines. A transition to a new output line is called a break. When formatted, a word may be bro‐ ken at hyphens, at \% or \: escape sequences (see subsection “Portabil‐ ity” below), or at predetermined locations if automatic hyphenation is enabled (see the -rHY option in section “Options” below). An output line may be supplemented with inter‐sentence space, and then optionally adjusted with more space to a consistent line length (see the -dAD op‐ tion). roff(7) details these processes. An input line that starts with a dot (.) or neutral apostrophe (') is a control line. To call a macro, put its name after a dot on a control line. We refer to macros in this document using this leading dot. Some macros interpret arguments, words that follow the macro name. A newline, unless escaped (see subsection “Portability” below), marks the end of the macro call. An input line consisting of a dot followed by a newline is called the empty request; it does nothing. Text lines are input lines that are not control lines. We describe below several man macros that plant one‐line input traps: the next input line that directly produces formatted output is treated specially. For man documents that follow the advice in section “Porta‐ bility” below, this means that control lines using the empty request and uncommented input lines ending with an escaped newline do not spring the trap; anything else does (but see the .TP macro descrip‐ tion). Macro reference preliminaries A tagged paragraph describes each macro. We present coupled pairs to‐ gether, as with .EX and .EE. Optional macro arguments are indicated by surrounding them with square brackets. If a macro accepts multiple arguments, those containing space characters must be double‐quoted to be interpreted correctly. An empty macro argument can be specified with a pair of double‐quotes (""), but the man package is designed such that this should seldom be necessary. See section “Notes” below for examples of cases where bet‐ ter alternatives to empty arguments in macro calls are available. Most macro arguments will be formatted as text in the output; exceptions are noted. Document structure macros Document structure macros organize a man page’s content. All of them break the output line. .TH (title heading) identifies the document as a man page and configures the page headers and footers. Section head‐ ings (.SH), one of which is mandatory and many of which are convention‐ ally expected, facilitate location of material by the reader and aid the man page writer to discuss all essential aspects of the topic. Subsection headings (.SS) are optional and permit sections that grow long to develop in a controlled way. Many technical discussions bene‐ fit from examples; lengthy ones, especially those reflecting multiple lines of input to or output from the system, are usefully bracketed by .EX and .EE. When none of the foregoing meets a structural demand, use .RS/.RE to inset a region within a (sub)section. .TH topic section [footer‐middle] [footer‐inside] [header‐middle] Determine the contents of the page header and footer. roff sys‐ tems refer to these collectively as “titles”. The subject of the man page is topic and the section of the manual to which it belongs is section. This use of “section” has nothing to do with the section headings otherwise discussed in this page; it arises from the organizational scheme of printed and bound Unix manuals. See man(1) or intro(1) for the manual sectioning ap‐ plicable to your system. topic and section are positioned to‐ gether at the left and right in the header (with section in parentheses immediately appended to topic). footer‐middle is centered in the footer. The arrangement of the rest of the footer depends on whether double‐sided layout is enabled with the option -rD1. When disabled (the default), footer‐inside is positioned at the bottom left. Otherwise, footer‐inside appears at the bottom left on recto (odd‐numbered) pages, and at the bottom right on verso (even‐numbered) pages. The outside footer is the page number, except in the continuous‐rendering mode en‐ abled by the option -rcR=1, in which case it is the topic and section, as in the header. header‐middle is centered in the header. If section is an integer between 1 and 9 (inclusive), there is no need to specify header‐middle; an.tmac will supply text for it. The macro package may also abbreviate topic and footer‐inside with ellipses (...) if they would overrun the space available in the header and footer, respectively. For HTML output, headers and footers are suppressed. Additionally, this macro breaks the page, resetting the number to 1 (unless the -rC1 option is given). This feature is in‐ tended only for formatting multiple man documents in sequence. A valid man document calls .TH once, early in the file, prior to any other macro calls. By convention, footer‐middle is the date of the most recent mod‐ ification to the man page source document, and footer‐inside is the name and version or release of the project providing it. .SH [heading‐text] Set heading‐text as a section heading. If no argument is given, a one‐line input trap is planted; text on the next line becomes heading‐text. The left margin is reset to zero to set the head‐ ing text in bold (or the font specified by the string HF), and, on typesetting devices, slightly larger than the base type size. If the heading font \*[HF] is bold, use of an italic style in heading‐text is mapped to the bold‐italic style if available in the font family. The inset level is reset to 1, setting the left margin to the value of the IN register. Text after head‐ ing‐text is set as an ordinary paragraph (.P). The content of heading‐text and ordering of sections follows a set of common practices, as has much of the layout of material within sections. For example, a section called “Name” or “NAME” must exist, must be the first section after the .TH call, and must contain only text of the form topic[, another‐topic]... \- summary‐description for a man page to be properly indexed. See man(7) for the con‐ ventions prevailing on your system. .SS [subheading‐text] Set subheading‐text as a subsection heading indented between a section heading and an ordinary paragraph (.P). If no argument is given, a one‐line input trap is planted; text on the next line becomes subheading‐text. The left margin is reset to the value of the SN register to set the heading text in bold (or the font specified by the string HF). If the heading font \*[HF] is bold, use of an italic style in subheading‐text is mapped to the bold‐italic style if available in the font family. The inset level is reset to 1, setting the left margin to the value of the IN register. Text after subheading‐text is set as an ordinary paragraph (.P). .EX .EE Begin and end example. After .EX, filling is disabled and a constant‐width (monospaced) font is selected. Calling .EE en‐ ables filling and restores the previous font. Example regions are useful for formatting code, shell sessions, and text file contents. An example region is not a “literal mode” of any sort: special character escape sequences must still be used to produce correct glyphs for ', -, \, ^, `, and ~, and sentence endings are still detected and additional inter‐sen‐ tence space applied. If the amount of additional inter‐sentence spacing is altered, the rendering of, for instance, regular ex‐ pressions using . or ? followed by multiple spaces can change. Use the dummy character escape sequence \& before the spaces. These macros are extensions introduced in Ninth Edition Research Unix. Systems running that troff, or those from Documenter’s Workbench, Heirloom Doctools, or Plan 9 troff support them. To be certain your page will be portable to systems that do not, copy their definitions from the an-ext.tmac file of a groff in‐ stallation. .RS [inset‐amount] Start a new relative inset level. The position of the left mar‐ gin is saved, then moved right by inset‐amount, if specified, and by the amount of the IN register otherwise. Calls to .RS can be nested; each increments by 1 the inset level used by .RE. The level prior to any .RS calls is 1. .RE [level] End a relative inset. The left margin corresponding to inset level level is restored. If no argument is given, the inset level is reduced by 1. Paragraphing macros An ordinary paragraph (.P) like this one is set without a first‐line indentation at the current left margin. In man pages and other techni‐ cal literature, definition lists are frequently encountered; these can be set as “tagged paragraphs”, which have one (.TP) or more (.TQ) lead‐ ing tags followed by a paragraph that has an additional indentation. The indented paragraph (.IP) macro is useful to continue the indented content of a narrative started with .TP, or to present an itemized or ordered list. All of these macros break the output line. If another paragraph macro has occurred since the previous .SH or .SS, they (ex‐ cept for .TQ) follow the break with a default amount of vertical space, which can be changed by the deprecated .PD macro; see subsection “Hori‐ zontal and vertical spacing” below. They also reset the type size and font style to defaults (.TQ again excepted); see subsection “Font style macros” below. .P .LP .PP Begin a new paragraph; these macros are synonymous. The inden‐ tation is reset to the default value; the left margin, as af‐ fected by .RS and .RE, is not. .TP [indentation] Set a paragraph with a leading tag, and the remainder of the paragraph indented. A one‐line input trap is planted; text on the next line, which can be formatted with a macro, becomes the tag, which is placed at the current left margin. The tag can be extended with the \c escape sequence. Subsequent text is in‐ dented by indentation, if specified, and by the amount of the IN register otherwise. If the tag is not as wide as the indenta‐ tion, the paragraph starts on the same line as the tag, at the applicable indentation, and continues on the following lines. Otherwise, the descriptive part of the paragraph begins on the line following the tag. The line containing the tag can include a macro call, for in‐ stance to set the tag in bold with .B. .TP was used to write the first paragraph of this description of .TP, and .IP the sub‐ sequent one. .TQ Set an additional tag for a paragraph tagged with .TP. An input trap is planted as with .TP. This macro is a GNU extension not defined on systems running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. The descriptions of .P, .LP, and .PP above were written using .TP and .TQ. .IP [tag] [indentation] Set an indented paragraph with an optional tag. The tag and in‐ dentation arguments, if present, are handled as with .TP, with the exception that the tag argument to .IP cannot include a macro call. Two convenient uses for .IP are (1) to start a new paragraph with the same indentation as an immediately preceding .IP or .TP paragraph, if no inden‐ tation argument is given; and (2) to set a paragraph with a short tag that is not semanti‐ cally important, such as a bullet (•)—obtained with the \(bu special character escape sequence—or list enumera‐ tor, as seen in this very paragraph. Command synopsis macros .SY and .YS aid you to construct a command synopsis that has the clas‐ sical Unix appearance. They break the output line. These macros are GNU extensions not defined on systems running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. .SY command Begin synopsis. A new paragraph begins at the left margin (as with .P) unless .SY has already been called without a corre‐ sponding .YS, in which case only a break is performed. Adjust‐ ment and automatic hyphenation are disabled. command is set in bold. If a break is required, lines after the first are in‐ dented by the width of command plus a space. .YS End synopsis. Indentation, adjustment, and hyphenation are re‐ stored to their previous states. Multiple .SY/.YS blocks can be specified, for instance to distinguish differing modes of operation of a complex command like tar(1); each will be vertically separated as paragraphs are. .SY can be repeated before .YS to indicate synonymous ways of invoking a particular mode of operation. groff’s own command‐line interface serves to illustrate most of the specimens of synopsis syntax one is likely to encounter. .SY groff .RB [ \‐abcCeEgGijklNpRsStUVXzZ ] .RB [ \‐d\~\c .IR cs ] .RB [ \‐d\~\c .IB name =\c .IR string ] .RB [ \‐D\~\c .IR enc ] (and so on similarly) .RI [ file\~ .\|.\|.] .YS . . .SY groff .B \‐h . .SY groff .B \‐\‐help .YS . . .SY groff .B \‐v .RI [ option\~ .\|.\|.\&] .RI [ file\~ .\|.\|.] . .SY groff .B \‐\‐version .RI [ option\~ .\|.\|.\&] .RI [ file\~ .\|.\|.] .YS produces the following output. groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-d name=string] [-D enc] [-f fam] [-F dir] [-I dir] [-K enc] [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn] [-r reg=expr] [-T dev] [-w name] [-W name] [file ...] groff -h groff --help groff -v [option ...] [file ...] groff --version [option ...] [file ...] Several features of the above example are of note. • The empty request (.), which does nothing, is used to vertically space the input file for readability by the document maintainer. Do not put blank (empty) lines in a man page source document. • Command and option names are presented in bold to cue the user that they should be input literally. • Option dashes are specified with the \- escape sequence; this is an important practice to make them clearly visible and to facilitate copy‐and‐paste from the rendered man page to a shell prompt or text file. • Option arguments and command operands are presented in italics (but see subsection “Font style macros” below regarding terminals) to cue the user that they must be replaced with appropriate text. • Symbols that are neither to be typed literally nor replaced at the user’s discretion appear in the roman style; brackets surround op‐ tional arguments, and an ellipsis indicates that the previous syntac‐ tical element may be repeated arbitrarily. • The non‐breaking adjustable space escape sequence \~ is used to pre‐ vent the output line from being broken within the option brackets; see subsection “Portability” below. • The output line continuation escape sequence \c is used with font style alternation macros to allow all three font styles to be set without (breakable) space among them; see subsection “Portability” below. • The dummy character escape sequence \& follows the ellipsis when fur‐ ther text will follow after space on the output line, keeping its last period from being interpreted as the end of a sentence and caus‐ ing additional inter‐sentence space to be placed after it. See sub‐ section “Portability” below. Hyperlink macros Man page cross references like ls(1) are best presented with .MR. Text may be hyperlinked to email addresses with .MT/.ME or other URIs with .UR/.UE. Hyperlinked text is supported on HTML and terminal output de‐ vices; terminals and pager programs must support ECMA‐48 OSC 8 escape sequences (see grotty(1)). When device support is unavailable or dis‐ abled with the U register (see section “Options” below), .MT and .UR URIs are rendered between angle brackets after the linked text. .MT, .ME, .UR, and .UE are GNU extensions not defined on systems run‐ ning AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. Plan 9 from User Space’s troff implements .MR. The arguments to .MR, .MT, and .UR should be prepared for typesetting since they can appear in the output. Use special character escape se‐ quences to encode Unicode basic Latin characters where necessary, par‐ ticularly the hyphen‐minus. (See section “Portability” below.) URIs can be lengthy; rendering them can result in jarring adjustment or variations in line length, or troff warnings when a hyperlink is longer than an output line. The application of non‐printing break point es‐ cape sequences \: after each slash (or series thereof), and before each dot (or series thereof) is recommended as a rule of thumb. The former practice avoids forcing a trailing slash in a URI onto a separate out‐ put line, and the latter helps the reader to avoid mistakenly inter‐ preting a dot at the end of a line as a period (or multiple dots as an ellipsis). Thus, .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc has several potential break points in the URI shown. Consider adding break points before or after at signs in email addresses, and question marks, ampersands, and number signs in HTTP(S) URIs. The formatter re‐ moves \: escape sequences from hyperlinks when supplying device control commands to output drivers. .MR topic manual‐section [trailing‐text] (since groff 1.23) Set a man page cross reference as “topic(man‐ ual‐section)”. If trailing‐text (typically punctuation) is specified, it follows the closing parenthesis without interven‐ ing space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. The cross reference hyperlinks to a URI of the form “man:topic(man‐ ual‐section)”. The output driver .MR grops 1 produces PostScript from .I troff output. . The Ghostscript program (\c .MR gs 1 ) interprets PostScript and PDF. .MT address .ME [trailing‐text] Identify address as an RFC 6068 addr‐spec for a “mailto:” URI with the text between the two macro calls as the link text. An argument to .ME is placed after the link text without interven‐ ing space. address may not be visible in the rendered document if hyperlinks are enabled and supported by the output driver. If they are not, address is set in angle brackets after the link text and before trailing‐text. If hyperlinking is enabled but there is no link text, address is formatted and hyperlinked without angle brackets. When rendered by groff to a PostScript device, Contact .MT fred\:.foonly@\:fubar\:.net Fred Foonly .ME for more information. displays as “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for more information.”. .UR uri .UE [trailing‐text] Identify uri as an RFC 3986 URI hyperlink with the text between the two macro calls as the link text. An argument to .UE is placed after the link text without intervening space. uri may not be visible in the rendered document if hyperlinks are en‐ abled and supported by the output driver. If they are not, uri is set in angle brackets after the link text and before trail‐ ing‐text. If hyperlinking is enabled but there is no link text, uri is formatted and hyperlinked without angle brackets. When rendered by groff to a PostScript device, The GNU Project of the Free Software Foundation hosts the .UR https://\:www\:.gnu\:.org/\:software/\:groff/ .I groff home page .UE . displays as “The GNU Project of the Free Software Foundation hosts the groff home page ⟨https://www.gnu.org/software/ groff/⟩.”. The hyperlinking of .TP paragraph tags with .UR/.UE and .MT/.ME is not yet supported; if attempted, the hyperlink will be typeset at the be‐ ginning of the indented paragraph even on hyperlink‐supporting devices. Font style macros The man macro package is limited in its font styling options, offering only bold (.B), italic (.I), and roman. Italic text is usually set un‐ derscored instead on terminal devices. The .SM and .SB macros set text in roman or bold, respectively, at a smaller type size; these differ visually from regular‐sized roman or bold text only on typesetting de‐ vices. It is often necessary to set text in different styles without intervening space. The macros .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R” indicate bold, italic, and roman, respectively, set their odd‐ and even‐numbered arguments in alternating styles, with no space separating them. Because font styles are presentational rather than semantic, conflict‐ ing traditions have arisen regarding which font styles should be used to mark file or path names, environment variables, and inlined liter‐ als. The default type size and family for typesetting devices is 10‐point Times, except on the X75-12 and X100-12 devices where the type size is 12 points. The default style is roman. .B [text] Set text in bold. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further formatted with a macro, is set in bold. Use bold for literal portions of syntax synopses, for command‐ line options in running text, and for literals that are major topics of the subject under discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold. .I [text] Set text in an italic or oblique face. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further formatted with a macro, is set in an italic or oblique face. Use italics for file and path names, for environment variables, for C data types, for enumeration or preprocessor constants in C, for variant (user‐replaceable) portions of syntax synopses, for the first occurrence (only) of a technical concept being in‐ troduced, for names of journals and of literary works longer than an article, and anywhere a parameter requiring replacement by the user is encountered. An exception involves variant text in a context already typeset in italics, such as file or path names with replaceable components; in such cases, follow the convention of mathematical typography: set the file or path name in italics as usual but use roman for the variant part (see .IR and .RI below), and italics again in running roman text when re‐ ferring to the variant material. .SM [text] Set text one point smaller than the default type size on type‐ setting devices. If no argument is given, a one‐line input trap is planted; text on the next line, which can be further format‐ ted with a macro, is set smaller. Note: terminals will render text at normal size instead. Do not rely upon .SM to communicate semantic information distinct from using roman style at normal size; it will be hidden from readers using such devices. .SB [text] Set text in bold and (on typesetting devices) one point smaller than the default type size. If no argument is given, a one‐line input trap is planted; text on the next line, which can be fur‐ ther formatted with a macro, is set smaller and in bold. This macro is an extension introduced in SunOS 4.0. Note: terminals will render text in bold at the normal size in‐ stead. Do not rely upon .SB to communicate semantic information distinct from using bold style at normal size; it will be hidden from readers using such devices. Observe what is not prescribed for setting in bold or italics above: elements of “synopsis language” such as ellipses and brackets around options; proper names and adjectives; titles of anything other than ma‐ jor works of literature; identifiers for standards documents or techni‐ cal reports such as CSTR #54, RFC 1918, Unicode 13.0, or POSIX.1‐2017; acronyms; and occurrences after the first of a technical term. Be frugal with italics for emphasis, and particularly with bold. Arti‐ cle titles and brief runs of literal text, such as references to indi‐ vidual characters or short strings, including section and subsection headings of man pages, are suitable objects for quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in subsection “Portability” below. Unlike the above font style macros, the font style alternation macros below set no input traps; they must be given arguments to have effect. Italic corrections are applied as appropriate. If a space is required within an argument, first consider whether the same result could be achieved with as much clarity by using single‐style macros on separate input lines. When it cannot, double‐quote an argument containing em‐ bedded space characters. Setting all three different styles within a word presents challenges; it is possible with the \c and/or \f escape sequences. See subsection “Portability” below for approaches. .BI bold‐text italic‐text ... Set each argument in bold and italics, alternately. .BI -r register = numeric‐expression .BR bold‐text roman‐text ... Set each argument in bold and roman, alternately. After .B .NH is called, .IB italic‐text bold‐text ... Set each argument in italics and bold, alternately. In places where .IB n th is allowed, .IR italic‐text roman‐text ... Set each argument in italics and roman, alternately. Use GNU .IR pic 's .B figname command to change the name of the vbox. .RB roman‐text bold‐text ... Set each argument in roman and bold, alternately. if .I file is .RB \[lq] \- \[rq], the standard input stream is read. .RI roman‐text italic‐text ... Set each argument in roman and italics, alternately. .RI ( tpic was a fork of AT&T .I pic by Tim Morgan of the University of California at Irvine Horizontal and vertical spacing The indentation argument accepted by .IP, .TP, and the deprecated .HP is a number plus an optional scaling unit, as is .RS’s inset‐amount. If no scaling unit is given, the man package assumes “n”; that is, the width of a letter “n” in the font current when the macro is called (see section “Measurements” in groff(7)). An indentation specified in a call to .IP, .TP, or the deprecated .HP persists until (1) another of these macros is called with an indentation argument, or (2) .SH, .SS, or .P or its synonyms is called; these clear the indentation entirely. The left margin used by ordinary paragraphs set with .P (and its syn‐ onyms) not within an .RS/.RE relative inset is 7.2n for typesetting de‐ vices and 7n for terminal devices (but see the -rIN option). Headers, footers (both set with .TH), and section headings (.SH) are set at the page offset (see groff(7)) and subsection headings (.SS) indented from it by 3n (but see the -rSN option). It may be helpful to think of the left margin and indentation as re‐ lated but distinct concepts; groff’s implementation of the man macro package tracks them separately. The left margin is manipulated by .RS and .RE (and by .SH and .SS, which reset it to the default). Indenta‐ tion is controlled by the paragraphing macros (though, again, .SH and .SS reset it); it is imposed by the .TP, .IP, and deprecated .HP macros, and cancelled by .P and its synonyms. An extensive example follows. This ordinary (.P) paragraph is not in a relative inset nor does it possess an indentation. Now we have created a relative inset (in other words, moved the left margin) with .RS and started another ordinary paragraph with .P. tag This tagged paragraph, set with .TP, is still within the .RS region, but lines after the first have a supplemen‐ tary indentation that the tag lacks. A paragraph like this one, set with .IP, will appear to the reader as also associated with the tag above, because .IP re‐uses the previous paragraph’s indentation unless given an argument to change it. This paragraph is af‐ fected both by the moved left margin (.RS) and indenta‐ tion (.IP). ┌──────────────────────────────────┐ │ This table is affected both by │ │ the left margin and indentation. │ └──────────────────────────────────┘ • This indented paragraph has a bullet for a tag, making it more obvious that the left margin and indentation are distinct; only the former affects the tag, but both af‐ fect the text of the paragraph. This ordinary (.P) paragraph resets the indentation, but the left margin is still inset. ┌─────────────────────────────┐ │ This table is affected only │ │ by the left margin. │ └─────────────────────────────┘ Finally, we have ended the relative inset by using .RE, which (because we used only one .RS/.RE pair) has reset the left margin to the de‐ fault. This is an ordinary .P paragraph. Resist the temptation to mock up tabular or multi‐column output with tab characters or the indentation arguments to .IP, .TP, .RS, or the deprecated .HP; the result may not render comprehensibly on an output device you fail to check, or which is developed in the future. The ta‐ ble preprocessor tbl(1) can likely meet your needs. Several macros insert vertical space: .SH, .SS, .TP, .P (and its syn‐ onyms), .IP, and the deprecated .HP. The default inter‐section and in‐ ter‐paragraph spacing is is 1v for terminal devices and 0.4v for type‐ setting devices (“v” is a unit of vertical distance, where 1v is the distance between adjacent text baselines in a single‐spaced document). (The deprecated macro .PD can change this vertical spacing, but its use is discouraged.) Between .EX and .EE calls, the inter‐paragraph spac‐ ing is 1v regardless of output device. Registers Registers are described in section “Options” below. They can be set not only on the command line but in the site man.local file as well; see section “Files” below. Strings The following strings are defined for use in man pages. Others are supported for configuration of rendering parameters; see section “Op‐ tions” below. \*R interpolates a special character escape sequence for the “regis‐ tered sign” glyph, \(rg, if available, and “(Reg.)” otherwise. \*S interpolates an escape sequence setting the type size to the document default. \*(lq \*(rq interpolate special character escape sequences for left and right double‐quotation marks, \(lq and \(rq, respectively. \*(Tm interpolates a special character escape sequence for the “trade mark sign” glyph, \(tm, if available, and “(TM)” otherwise. None of the above is necessary in a contemporary man page. \*S is su‐ perfluous, since type size changes are invisible on terminal devices and macros that change it restore its original value afterward. Better alternatives exist for the rest; simply use the \(rg, \(lq, \(rq, and \(tm special character escape sequences directly. Unless a man page author is aiming for a pathological level of portability, such as the composition of pages for consumption on simulators of 1980s Unix sys‐ tems (or Solaris troff, though even it supports \(rg), the above strings should be avoided. Portability It is wise to quote multi‐word section and subsection headings; the .SH and .SS macros of man(7) implementations descended from Seventh Edition Unix supported six arguments at most. A similar restriction applied to the .B, .I, .SM, and font style alternation macros. The two major syntactical categories for formatting control in the roff language are requests and escape sequences. Since the man macros are implemented in terms of groff requests and escape sequences, one can, in principle, supplement the functionality of man with these lower‐ level elements where necessary. However, using raw groff requests (apart from the empty request “.”) is likely to make your page render poorly when processed by other tools; many of these attempt to interpret page sources directly for conversion to HTML. Some requests make implicit assumptions about things like character and page sizes that may not hold in an HTML environment; also, many of these viewers don’t interpret the full groff vocabulary, a problem that can lead to portions of your text being omitted or pre‐ sented incomprehensibly. For portability to modern viewers, it is best to write your page solely with the macros described in this page (except for the ones identified as deprecated, which should be avoided). The macros we have described as extensions (.EX/.EE, .SY/.YS, .TQ, .UR/.UE, .MT/.ME, .MR, and .SB) should be used with caution, as they may not be built in to some viewer that is important to your audience. See an-ext.tmac in section “Files” below. Similar caveats apply to escape sequences. Some escape sequences are however required for correct typesetting even in man pages and usually do not cause portability problems. Several of these render glyphs cor‐ responding to punctuation code points in the Unicode basic Latin range (U+0000–U+007F) that are handled specially in roff input; the escape sequences below must be used to render them correctly and portably when documenting material that uses them syntactically—namely, any of the set ' - \ ^ ` ~ (apostrophe, dash or minus, backslash, caret, grave ac‐ cent, tilde). \" Comment. Everything after the double‐quote to the end of the input line is ignored. Whole‐line comments should be placed im‐ mediately after the empty request (“.”). \newline Join the next input line to the current one. Except for the up‐ date of the input line counter (used for diagnostic messages and related purposes), a series of lines ending in backslash‐newline appears to groff as a single input line. Use this escape se‐ quence to split excessively long input lines for document main‐ tenance. \% Control hyphenation. The location of this escape sequence within a word marks a hyphenation point, supplementing groff’s automatic hyphenation patterns. At the beginning of a word, it suppresses any hyphenation breaks within except those specified with \%. \: Insert a non‐printing break point. A word can break at such a point, but a hyphen glyph is not written to the output if it does. This escape sequence is an input word boundary, so the remainder of the word is subject to hyphenation as normal. You can use \: and \% in combination to control breaking of a file name or URI or to permit hyphenation only after certain explicit hyphens within a word. See subsection “Hyperlink macros” above for an example. This escape sequence is a groff extension also supported by Heirloom Doctools troff 050915 (September 2005), mandoc 1.14.5 (2019‐03‐10), and neatroff (commit 399a4936, 2014‐02‐17), but not by Plan 9, Solaris, or Documenter’s Workbench troffs. \~ Adjustable non‐breaking space. Use this escape sequence to pre‐ vent a break inside a short phrase or between a numerical quan‐ tity and its corresponding unit(s). Before starting the motor, set the output speed to\~1. There are 1,024\~bytes in 1\~KiB. CSTR\~#8 documents the B\~language. This escape sequence is a groff extension also supported by Heirloom Doctools troff 050915 (September 2005), mandoc 1.9.5 (2009‐09‐21), neatroff (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User Space troff (commit 93f8143600, 2022‐08‐12), but not by Solaris or Documenter’s Workbench troffs. \& Dummy character. Insert at the beginning of an input line to prevent a dot or apostrophe from being interpreted as beginning a roff control line. Append to an end‐of‐sentence punctuation sequence to keep it from being recognized as such. \| Thin space (one‐sixth em on typesetters, zero‐width on termi‐ nals); a non‐breaking space. Used primarily in ellipses (“.\|.\|.”) to space the dots more pleasantly on typesetting devices like dvi, pdf, and ps. \c End a text line without inserting space or attempting a break. Normally, if filling is enabled, the end of a text line is treated like a space; an output line may be broken there (if not, an adjustable space is inserted); if filling is disabled, the line will be broken there, as in .EX/.EE examples. The next line is interpreted as usual and can include a macro call (con‐ trast with \newline). \c is useful when three font styles are needed in a single word, as in a command synopsis. .RB [ \-\-stylesheet=\c .IR name ] It also helps when changing font styles in .EX/.EE examples, since they are not filled. .EX $ \c .B groff \-T utf8 \-Z \c .I file \c .B | grotty \-i .EE Alternatively, and perhaps with better portability, the \f font selection escape sequence can be used; see below. Using \c to continue a .TP paragraph tag across multiple input lines will render incorrectly with groff 1.22.3, mandoc 1.14.1, older ver‐ sions of these programs, and perhaps with some other formatters. \e Format the current escape character on the output; widely used in man pages to render a backslash glyph. It works reliably as long as the “.ec” request is not used, which should never happen in man pages, and it is slightly more portable than the more ex‐ plicit \(rs (“reverse solidus”) special character escape se‐ quence. \fB, \fI, \fR, \fP Switch to bold, italic, roman, or back to the previous style, respectively. Either \f or \c is needed when three different font styles are required in a word. .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ] .RB [ \-\-reference\-dictionary=\c .IR name ] Style escape sequences may be more portable than \c. As shown above, it is up to you to account for italic corrections with “\/” and “\,”, which are themselves GNU extensions, if desired and if supported by your implementation. \fP reliably returns to the style in use immediately preceding the previous \f escape sequence only if no sectioning, para‐ graph, or style macro calls have intervened. As long as at most two styles are needed in a word, style macros like .B and .BI usually result in more readable roff source than \f escape sequences do. Several special characters are also widely portable. Except for \-, \(em, and \(ga, AT&T troff did not consistently define the characters listed below, but its descendants, like Plan 9 or Solaris troff, can be made to support them by defining them in font description files, making them aliases of existing glyphs if necessary; see groff_font(5). \- Minus sign or basic Latin hyphen‐minus. This escape sequence produces the Unix command‐line option dash in the output. “-” is a hyphen in the roff language; some output devices replace it with U+2010 (hyphen) or similar. \(aq Basic Latin neutral apostrophe. Some output devices format “'” as a right single quotation mark. \(oq \(cq Opening (left) and closing (right) single quotation marks. Use these for paired directional single quotes, ‘like this’. \(dq Basic Latin quotation mark (double quote). Use in macro calls to prevent ‘"” from being interpreted as beginning a quoted ar‐ gument, or simply for readability. .TP .BI "split \(dq" text \(dq \(lq \(rq Left and right double quotation marks. Use these for paired di‐ rectional double quotes, “like this”. \(em Em‐dash. Use for an interruption—such as this one—in a sen‐ tence. \(en En‐dash. Use to separate the ends of a range, particularly be‐ tween numbers; for example, “the digits 1–9”. \(ga Basic Latin grave accent. Some output devices format “`” as a left single quotation mark. \(ha Basic Latin circumflex accent (“hat”). Some output devices for‐ mat “^” as U+02C6 (modifier letter circumflex accent) or simi‐ lar. \(rs Reverse solidus (backslash). The backslash is the default es‐ cape character in the roff language, so it does not represent itself in output. Also see \e above. \(ti Basic Latin tilde. Some output devices format “~” as U+02DC (small tilde) or similar. For maximum portability, escape sequences and special characters not listed above are better avoided in man pages. Hooks Two macros, both GNU extensions, are called internally by the groff man package to format page headers and footers and can be redefined by the administrator in a site’s man.local file (see section “Files” below). The presentation of .TH above describes the default headers and foot‐ ers. Because these macros are hooks for groff man internals, man pages have no reason to call them. Such hook definitions will likely consist of “.sp” and “.tl” requests. They must also increase the page length with “.pl” requests in continuous rendering mode; .PT furthermore has the responsibility of emitting a PDF bookmark after writing the first page header in a document. Consult the existing implementations in an.tmac when drafting replacements. .BT Set the page footer text (“bottom trap”). .PT Set the page header text (“page trap”). To remove a page header or footer entirely, define the appropriate macro as empty rather than deleting it. Deprecated features Use of the following in man pages for public distribution is discour‐ aged. .AT [system [release]] Alter the footer for use with legacy AT&T man pages, overriding any definition of the footer‐inside argument to .TH. This macro exists only to render man pages from historical systems. system can be any of the following. 3 7th edition (default) 4 System III 5 System V The optional release argument specifies the release number, as in “System V Release 3”. .DT Reset tab stops to the default (every 0.5i [inches]). Use of this presentation‐oriented macro is deprecated. It translates poorly to HTML, under which exact space control and tabulation are not readily available. Thus, information or dis‐ tinctions that you use tab stops to express are likely to be lost. If you feel tempted to change the tab stops such that calling this macro later is desirable to restore them, you should probably be composing a table using tbl(1) instead. .HP [indentation] Set up a paragraph with a hanging left indentation. The inden‐ tation argument, if present, is handled as with .TP. Use of this presentation‐oriented macro is deprecated. A hang‐ ing indentation cannot be expressed naturally under HTML, and non‐roff‐based man page interpreters may treat .HP as an ordi‐ nary paragraph. Thus, information or distinctions you mean to express with indentation may be lost. .OP option‐name [option‐argument] Indicate an optional command parameter called option‐name, which is set in bold. If the option takes an argument, specify op‐ tion‐argument using a noun, abbreviation, or hyphenated noun phrase. If present, option‐argument is preceded by a space and set in italics. Square brackets in roman surround both argu‐ ments. Use of this quasi‐semantic macro, an extension originating in Documenter’s Workbench troff, is deprecated. It cannot easily be used to annotate options that take optional arguments or op‐ tions whose arguments have internal structure (such as a mixture of literal and variable components). One could work around these limitations with font selection escape sequences, but it is preferable to use font style alternation macros, which afford greater flexibility. .PD [vertical‐space] Define the vertical space between paragraphs or (sub)sections. The optional argument vertical‐space specifies the amount; the default scaling unit is “v”. Without an argument, the spacing is reset to its default value; see subsection “Horizontal and vertical spacing” above. Use of this presentation‐oriented macro is deprecated. It translates poorly to HTML, under which exact control of inter‐ paragraph spacing is not readily available. Thus, information or distinctions that you use .PD to express are likely to be lost. .UC [version] Alter the footer for use with legacy BSD man pages, overriding any definition of the footer‐inside argument to .TH. This macro exists only to render man pages from historical systems. version can be any of the following. 3 3rd Berkeley Distribution (default) 4 4th Berkeley Distribution 5 4.2 Berkeley Distribution 6 4.3 Berkeley Distribution 7 4.4 Berkeley Distribution History M. Douglas McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed, imple‐ mented, and documented the AT&T man macros for Unix Version 7 (1979) and employed them to edit the first volume of its Programmer’s Manual, a compilation of all man pages supplied by the system. That man sup‐ ported the macros listed in this page not described as extensions, ex‐ cept .P and the deprecated .AT and .UC. The only strings defined were R and S; no registers were documented. .UC appeared in 3BSD (1980). Unix System III (1980) introduced .P and exposed the registers IN and LL, which had been internal to Seventh Edition Unix man. PWB/UNIX 2.0 (1980) added the Tm string. 4BSD (1980) added lq and rq strings. SunOS 2.0 (1985) recognized C, D, P, and X registers. 4.3BSD (1986) added .AT and .P. Ninth Edition Re‐ search Unix (1986) introduced .EX and .EE. SunOS 4.0 (1988) added .SB. The foregoing features were what James Clark implemented in early ver‐ sions of groff. Later, groff 1.20 (2009) originated .SY/.YS, .TQ, .MT/.ME, and .UR/.UE. Plan 9 from User Space’s troff introduced .MR in 2020. Options The following groff options set registers (with -r) and strings (with -d) recognized and used by the man macro package. To ensure rendering consistent with output device capabilities and reader preferences, man pages should never manipulate them. -dAD=adjustment‐mode Set line adjustment to adjustment‐mode, which is typically “b” for adjustment to both margins (the default), or “l” for left alignment (ragged right margin). Any valid argument to groff’s “.ad” request may be used. See groff(7) for less‐common choices. -rcR=1 Enable continuous rendering. Output is not paginated; instead, one (potentially very long) page is produced. This is the de‐ fault for terminal and HTML devices. Use -rcR=0 to disable it on terminal devices; on HTML devices, it cannot be disabled. -rC1 Number output pages consecutively, in strictly increasing se‐ quence, rather than resetting the page number to 1 (or the value of register P) with each new man document. -rCS=1 Set section headings (the argument(s) to .SH) in full capitals. This transformation is off by default because it discards case distinction information. -rCT=1 Set the man page topic (the first argument to .TH) in full capi‐ tals in headers and footers. This transformation is off by de‐ fault because it discards case distinction information. -rD1 Enable double‐sided layout, formatting footers for even and odd pages differently; see the description of .TH in subsection “Document structure macros” above. -rFT=footer‐distance Set distance of the footer relative to the bottom of the page to footer‐distance; this amount is always negative. At one half‐ inch above this location, the page text is broken before writing the footer. Ignored if continuous rendering is enabled. The default is -0.5i. -dHF=heading‐font Set the font used for section and subsection headings; the de‐ fault is “B” (bold style of the default family). Any valid ar‐ gument to groff’s “.ft” request may be used. See groff(7). -rHY=0 Disable automatic hyphenation. Normally, it is enabled (1). The hyphenation mode is determined by the groff locale; see sec‐ tion “Localization“ of groff(7). -rIN=standard‐indentation Set the amount of indentation used for ordinary paragraphs (.P and its synonyms) and the default indentation amount used by .IP, .RS, .TP, and the deprecated .HP. See subsection “Horizon‐ tal and vertical spacing” above for the default. For terminal devices, standard‐indentation should always be an integer multi‐ ple of unit “n” to get consistent indentation. -rLL=line‐length Set line length; the default is 78n for terminal devices and 6.5i for typesetting devices. -rLT=title‐length Set the line length for titles. (“Titles” is the roff term for headers and footers.) By default, it is set to the line length (see -rLL above). -dMF=man‐page‐topic‐font Set the font used for man page topics named in .TH and .MR calls; the default is “I” (italic style of the default family). Any valid argument to groff’s “.ft” request may be used. If the MF string ends in “I”, it is assumed to be an oblique typeface, and italic corrections are applied before and after man page topics. -rPn Start enumeration of pages at n. The default is 1. -rStype‐size Use type‐size for the document’s body text; acceptable values are 10, 11, or 12 points. See subsection “Font style macros” above for the default. -rSN=subsection‐indentation Set indentation of subsection headings to subsection‐indenta‐ tion. See subsection “Horizontal and vertical spacing” above for the default. -rU1 Enable generation of URI hyperlinks in the grohtml and grotty output drivers. grohtml enables them by default; grotty does not, pending more widespread pager support for OSC 8 escape se‐ quences. Use -rU0 to disable hyperlinks; this will make the ar‐ guments to MT and UR calls visible in the document text produced by link‐capable drivers. -rXp Number successors of page p as pa, pb, pc, and so forth. The register tracking the suffixed page letter uses format “a” (see the “.af” request in groff(7)). For example, the option -rX2 produces the following page numbers: 1, 2, 2a, 2b, ..., 2aa, 2ab, and so on. Files /usr/local/share/groff/1.23.0/tmac/an.tmac Most man macros are defined in this file. It also loads exten‐ sions from an-ext.tmac (see below). /usr/local/share/groff/1.23.0/tmac/andoc.tmac This brief groff program detects whether the man or mdoc macro package is being used by a document and loads the correct macro definitions, taking advantage of the fact that pages using them must call .TH or .Dd, respectively, before any other macros. A man program or user typing, for example, “groff -mandoc page.1”, need not know which package the file page.1 uses. Multiple man pages, in either format, can be handled; andoc reloads each macro package as necessary. /usr/local/share/groff/1.23.0/tmac/an-ext.tmac Except for .SB, definitions of macros described above as exten‐ sions are contained in this file; in some cases, they are sim‐ pler versions of definitions appearing in an.tmac, and are ig‐ nored if the formatter is GNU troff. They are written to be compatible with AT&T troff and permissively licensed—not copy‐ lefted. To reduce the risk of name space collisions, string and register names begin only with “m”. We encourage man page au‐ thors who are concerned about portability to legacy Unix systems to copy these definitions into their pages, and maintainers of troff implementations or work‐alike systems that format man pages to re‐use them. The definitions for these macros are read after a page calls .TH, so they will replace any macros of the same names preceding it in your file. If you use your own implementations of these macros, they must be defined after .TH is called to have any ef‐ fect. Furthermore, it is wise to define such page‐local macros (if at all) after the “Name” section to accommodate timid make‐ whatis or mandb implementations that may give up their scan for indexing material early. /usr/local/share/groff/1.23.0/tmac/man.tmac This is a wrapper that loads an.tmac. /usr/local/share/groff/1.23.0/tmac/mandoc.tmac This is a wrapper that loads andoc.tmac. /usr/local/share/groff/site-tmac/man.local Put site‐local changes and customizations into this file. .\" Use narrower indentation on terminals and similar. .if n .nr IN 4n .\" Put only one space after the end of a sentence. .ss 12 0 \" See groff(7). .\" Keep pages narrow even on wide terminals. .if n .if \n[LL]>78n .nr LL 78n .\" Ensure hyperlinks are enabled for terminals. .nr U 1 On multi‐user systems, it is more considerate to users whose preferences may differ from the administrator’s to be less ag‐ gressive with such settings, or to permit their override with a user‐specific man.local file. Place the requests below at the end of the site‐local file to manifest courtesy. .soquiet \V[XDG_CONFIG_HOME]/man.local .soquiet \V[HOME]/.man.local However, a security‐sandboxed man(1) program may lack permission to open such files. Notes Some tips on troubleshooting your man pages follow. • Some ASCII characters look funny or copy and paste wrong. On devices with large glyph repertoires, like UTF‐8‐capable ter‐ minals and PDF, several keyboard glyphs are mapped to code points outside the Unicode basic Latin range because that usu‐ ally results in better typography in the general case. When documenting GNU/Linux command or C language syntax, however, this translation is sometimes not desirable. To get a “literal”... ...should be input. ──────────────────────────────────────────── ' \(aq - \- \ \(rs ^ \(ha ` \(ga ~ \(ti ──────────────────────────────────────────── Additionally, if a neutral double quote (") is needed in a macro argument, you can use \(dq to get it. You should not use \(aq for an ordinary apostrophe (as in “can’t”) or \- for an ordinary hyphen (as in “word‐aligned”). Review subsection “Portability” above. • Do I ever need to use an empty macro argument ("")? Probably not. When this seems necessary, often a shorter or clearer alternative is available. Instead of... ...should be considered. ──────────────────────────────────────────────────────────────── .TP "" .TP ──────────────────────────────────────────────────────────────── .BI "" italic‐text bold‐text .IB italic‐text bold‐text ──────────────────────────────────────────────────────────────── .TH foo 1 "" "foo 1.2.3" .TH foo 1 yyyy‐mm‐dd "foo 1.2.3" ──────────────────────────────────────────────────────────────── .IP "" 4n .IP ──────────────────────────────────────────────────────────────── .IP "" 4n .RS 4n paragraph .P ... paragraph ... .RE ──────────────────────────────────────────────────────────────── .B one two "" three .B one two three In the title heading (.TH), the date of the page’s last revision is more important than packaging information; it should not be omitted. Ideally, a page maintainer will keep both up to date. .IP is sometimes ill‐understood and misused, especially when no marker argument is supplied—an indentation argument is not re‐ quired. By setting an explicit indentation, you may be overrid‐ ing the reader’s preference as set with the -rIN option. If your page renders adequately without one, use the simpler form. If you need to indent multiple (unmarked) paragraphs, consider setting an inset region with .RS and .RE instead. In the last example, the empty argument does have a subtly dif‐ ferent effect than its suggested replacement: the empty argument causes an additional space character to be interpolated between the arguments “two” and “three”—but it is a regular breaking space, so it can be discarded at the end of an output line. It is better not to be subtle, particularly with space, which can be overlooked in source and rendered forms. • .RS doesn’t indent relative to my indented paragraph. The .RS macro sets the left margin; that is, the position at which an ordinary paragraph (.P and its synonyms) will be set. .IP, .TP, and the deprecated .HP use the same default indenta‐ tion. If not given an argument, .RS moves the left margin by this same amount. To create an inset relative to an indented paragraph, call .RS repeatedly until an acceptable indentation is achieved, or give .RS an indentation argument that is at least as much as the paragraph’s indentation amount relative to an adjacent .P paragraph. See subsection “Horizontal and verti‐ cal spacing” above for the values. Another approach you can use with tagged paragraphs is to place an .RS call immediately after the paragraph tag; this will also force a break regardless of the width of the tag, which some au‐ thors prefer. Follow‐up paragraphs under the tag can then be set with .P instead of .IP. Remember to use .RE to end the in‐ dented region before starting the next tagged paragraph (at the appropriate nesting level). • .RE doesn’t move the inset back to the expected level. • warning: scaling unit invalid in context • warning: register 'an-saved-marginn' not defined • warning: register 'an-saved-prevailing-indentn' not defined The .RS macro takes an indentation amount as an argument; the .RE macro’s argument is a specific inset level. .RE 1 goes to the level before any .RS macros were called, .RE 2 goes to the level of the first .RS call you made, and so forth. If you de‐ sire symmetry in your macro calls, simply issue one .RE without an argument for each .RS that precedes it. After calls to the .SH and .SS sectioning macros, all relative insets are cleared and calls to .RE have no effect until .RS is used again. • Do I need to keep typing the indentation in a series of .IP calls? Not if you don’t want to change it. Review subsection “Horizon‐ tal and vertical spacing” above. Instead of... ...should be considered. ───────────────────────────────────────────── .IP \(bu 4n .IP \(bu 4n paragraph paragraph .IP \(bu 4n .IP \(bu another‐paragraph another‐paragraph ───────────────────────────────────────────── • Why doesn’t the package provide a string to insert an ellipsis? Examples of ellipsis usage are shown above, in subsection “Com‐ mand synopsis macros”. The idiomatic roff ellipsis is three dots (periods) with thin space escape sequences \| internally separating them. Since dots both begin control lines and are candidate end‐of‐sentence characters, however, it is sometimes necessary to prefix and/or suffix an ellipsis with the dummy character escape sequence \&. That fact stands even if a string is defined to contain the sequence; further, if the string ends with \&, end‐of‐sentence detection is defeated when you use the string at the end of an actual sentence. (Ending a sentence with an ellipsis is often poor style, but not always.) A hypo‐ thetical string EL that contained an ellipsis, but not the trailing dummy character \&, would then need to be suffixed with the latter when not ending a sentence. Instead of... ...do this. ────────────────────────────────────────────────── .ds EL \&.\|.\|. Arguments are Arguments are .IR src‐file\~ .\|.\|.\& .IR src‐file\~ \*(EL\& .IR dest‐dir . .IR dest‐dir . ────────────────────────────────────────────────── The first column practices a false economy; the savings in typ‐ ing is offset by the cost of obscuring even the suggestion of an ellipsis to a casual reader of the source document, and reduced portability to non‐roff man page formatters that cannot handle string definitions. There is an ellipsis code point in Unicode, and some fonts have an ellipsis glyph, which some man pages have accessed in a non‐ portable way with the font‐dependent \N escape sequence. We discourage the use of these; on terminals, they may crowd the dots into a half‐width character cell, and will not render at all if the output device doesn’t have the glyph. In syntax syn‐ opses, missing ellipses can cause great confusion. Dots and space are universally supported. Authors The initial GNU implementation of the man macro package was written by James Clark. Later, Werner Lemberg ⟨wl@gnu.org⟩ supplied the S, LT, and cR registers, the last a 4.3BSD‐Reno mdoc(7) feature. Larry Kollar ⟨kollar@alltel.net⟩ added the FT, HY, and SN registers; the HF string; and the PT and BT macros. G. Branden Robinson ⟨g.branden.robinson@ gmail.com⟩ implemented the AD and MF strings; CS, CT, and U registers; and the MR macro. Except for .SB, the extension macros were written by Lemberg, Eric S. Raymond ⟨esr@thyrsus.com⟩, and Robinson. This document was originally written for the Debian GNU/Linux system by Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by Lemberg and Robinson. The extension macros were documented by Raymond and Robinson. Raymond also originated the portability section, to which Ingo Schwarze ⟨schwarze@usta.de⟩ contributed most of the material on escape sequences. See also tbl(1), eqn(1), and refer(1) are preprocessors used with man pages. man(1) describes the man page librarian on your system. groff_mdoc(7) details the groff version of the BSD‐originated alternative macro pack‐ age for man pages. groff_man(7), groff(7), groff_char(7), man(7) groff 1.23.0 29 August 2023 groff_man_style(7) ─────────────────────────────────────────────────────────────────────────────── groff_mdoc(7) Miscellaneous Information Manual groff_mdoc(7) Name groff_mdoc — compose BSD‐style manual (man) pages with GNU roff Synopsis groff -mdoc file ... Description The GNU implementation of the mdoc macro package is part of the groff(1) document formatting system. mdoc is a structurally‐ and se‐ mantically‐oriented package for writing Unix manual pages with troff(1). Its predecessor, the man(7) package, primarily addressed page layout and presentational concerns, leaving the selection of fonts and other typesetting details to the individual author. This discre‐ tion has led to divergent styling practices among authors using it. mdoc organizes its macros into domains. The page structure domain lays out the page and comprises titles, section headings, displays, and lists. The general text domain supplies macros to quote or style text, or to interpolate common noun phrases. The manual domain offers seman‐ tic macros corresponding to the terminology used by practitioners in discussion of Unix commands, routines, and files. Manual domain macros distinguish command‐line arguments and options, function names, func‐ tion parameters, pathnames, variables, cross references to other manual pages, and so on. These terms are meaningful both to the author and the readers of a manual page. It is hoped that the resulting increased consistency of the man page corpus will enable easier translation to future documentation tools. Throughout Unix documentation, a manual entry is referred to simply as a “man page”, regardless of its length, without gendered implication, and irrespective of the macro package selected for its composition. Getting started The mdoc package attempts to simplify man page authorship and mainte‐ nance without requiring mastery of the roff language. This document presents only essential facts about roff. For further background, in‐ cluding a discussion of basic typographical concepts like “breaking”, “filling”, and “adjustment”, see roff(7). Specialized units of mea‐ surement also arise, namely ens, vees, inches, and points, abbreviated “n”, “v”, “i”, and “p”, respectively; see section “Measurements” of groff(7). For brief examples, we employ an arrow notation illustrating a trans‐ formation of input on the left to rendered output on the right. Con‐ sider the .Dq macro, which double‐quotes its arguments. .Dq man page → “man page” Usage An mdoc macro is called by placing the roff control character, ‘.’ (dot) at the beginning of a line followed by its name. In this docu‐ ment, we often discuss a macro name with this leading dot to identify it clearly, but the dot is not part of its name. Space or tab charac‐ ters can separate the dot from the macro name. Arguments may follow, separated from the macro name and each other by spaces, but not tabs. The dot at the beginning of the line prepares the formatter to expect a macro name. A dot followed immediately by a newline is ignored; this is called the empty request. To begin an input line with a dot (or a neutral apostrophe ‘'’) in some context other than a macro call, pre‐ cede it with the ‘\&’ escape sequence; this is a dummy character, not formatted for output. The backslash is the roff escape character; it can appear anywhere and it always followed by at least one more charac‐ ter. If followed by a newline, the backslash escapes the input line break; you can thus keep input lines to a reasonable length without af‐ fecting their interpretation. Macros in GNU troff accept an unlimited number of arguments, in con‐ trast to other troffs that often can’t handle more than nine. In lim‐ ited cases, arguments may be continued or extended on the next input line without resort to the ‘\newline’ escape sequence; see subsection “Extended arguments” below. Neutral double quotes " can be used to group multiple words into an argument; see subsection “Passing space characters in an argument” below. Most of mdoc’s general text and manual domain macros parse their argu‐ ment lists for callable macro names. This means that an argument in the list matching a general text or manual domain macro name (and de‐ fined to be callable) will be called with the remaining arguments when it is encountered. In such cases, the argument, although the name of a macro, is not preceded by a dot. Macro calls can thus be nested. This approach to macro argument processing is a unique characteristic of the mdoc package, not a general feature of roff syntax. For example, the option macro, .Op, may call the flag and argument macros, .Fl and .Ar, to specify an optional flag with an argument. .Op Fl s Ar bytes → [-s bytes] To prevent a word from being interpreted as a macro name, precede it with the dummy character. .Op \&Fl s \&Ar bytes → [Fl s Ar bytes] In this document, macros whose argument lists are parsed for callable arguments are referred to as parsed, and those that may be called from an argument list are referred to as callable. This usage is a techni‐ cal faux pas, since all mdoc macros are in fact interpreted (unless prevented with ‘\&’), but as it is cumbersome to constantly refer to macros as “being able to call other macros”, we employ the term “parsed” instead. Except where explicitly stated, all mdoc macros are parsed and callable. In the following, we term an mdoc macro that starts a line (with a leading dot) a command if a distinction from those appearing as argu‐ ments of other macros is necessary. Passing space characters in an argument Sometimes it is desirable to give a macro an argument containing one or more space characters, for instance to specify a particular arrangement of arguments demanded by the macro. Additionally, quoting multi‐word arguments that are to be treated the same makes mdoc work faster; macros that parse arguments do so once (at most) for each. For exam‐ ple, the function command .Fn expects its first argument to be the name of a function and any remaining arguments to be function parameters. Because C language standards mandate the inclusion of types and identi‐ fiers in the parameter lists of function definitions, each ‘Fn’ parame‐ ter after the first will be at least two words in length, as in “int foo”. There are a few ways to embed a space in a macro argument. One is to use the unadjustable space escape sequence \space. The formatter treats this escape sequence as if it were any other printable charac‐ ter, and will not break a line there as it would a word space when the output line is full. This method is useful for macro arguments that are not expected to straddle an output line boundary, but has a draw‐ back: this space does not adjust as others do when the output line is formatted. An alternative is to use the unbreakable space escape se‐ quence, ‘\~’, which cannot break but does adjust. This groff extension is widely but not perfectly portable. Another method is to enclose the string in double quotes. .Fn fetch char\ *str → fetch(char *str) .Fn fetch char\~*str → fetch(char *str) .Fn fetch "char *str" → fetch(char *str) If the ‘\’ before the space in the first example or the double quotes in the third example were omitted, ‘.Fn’ would see three arguments, and the result would contain an undesired comma. .Fn fetch char *str → fetch(char, *str) Trailing space characters It is wise to remove trailing spaces from the ends of input lines. Should the need arise to put a formattable space at the end of a line, do so with the unadjustable or unbreakable space escape sequences. Formatting the backslash glyph When you need the roff escape character ‘\’ to appear in the output, use ‘\e’ or ‘\(rs’ instead. Technically, ‘\e’ formats the current es‐ cape character; it works reliably as long as no roff request is used to change it, which should never happen in man pages. ‘\(rs’ is a groff special character escape sequence that explicitly formats the “reverse solidus” (backslash) glyph. Other possible pitfalls groff mdoc warns when an empty input line is found outside of a display, a topic presented in subsection “Examples and displays” below. Use empty requests to space the source document for maintenance. Leading spaces cause a break and are formatted. Avoid this behaviour if possible. Similarly, do not put more than one space between words in an ordinary text line; they are not “normalized” to a single space as other text formatters might do. Don’t try to use the neutral double quote character ‘"’ to represent itself in an argument. Use the special character escape sequence ‘\(dq’ to format it. Further, this glyph should not be used for con‐ ventional quotation; mdoc offers several quotation macros. See subsec‐ tion “Enclosure and quoting macros” below. The formatter attempts to detect the ends of sentences and by default puts the equivalent of two spaces between sentences on the same output line; see roff(7). To defeat this detection in a parsed list of macro arguments, put ‘\&’ before the punctuation mark. Thus, The .Ql . character. .Pp The .Ql \&. character. .Pp .No test . test .Pp .No test. test gives The ‘’. character The ‘.’ character. test. test test. test as output. As can be seen in the first and third output lines, mdoc handles punctuation characters specially in macro arguments. This will be explained in section “General syntax” below. A comment in the source file of a man page can begin with ‘.\"’ at the start of an input line, ‘\"’ after other input, or ‘\#’ anywhere (the last is a groff extension); the remainder of any such line is ignored. A man page template Use mdoc to construct a man page from the following template. .\" The following three macro calls are required. .Dd date .Dt topic [section‐identifier [section‐keyword‐or‐title]] .Os [package‐or‐operating system [version‐or‐release]] .Sh Name .Nm topic .Nd summary‐description .\" The next heading is used in sections 2 and 3. .\" .Sh Library .\" The next heading is used in sections 1‐4, 6, 8, and 9. .Sh Synopsis .Sh Description .\" Uncomment and populate the following sections as needed. .\" .Sh "Implementation notes" .\" The next heading is used in sections 2, 3, and 9. .\" .Sh "Return values" .\" The next heading is used in sections 1, 3, 6, and 8. .\" .Sh Environment .\" .Sh Files .\" The next heading is used in sections 1, 6, and 8. .\" .Sh "Exit status" .\" .Sh Examples .\" The next heading is used in sections 1, 4, 6, 8, and 9. .\" .Sh Diagnostics .\" .Sh Compatibility .\" The next heading is used in sections 2, 3, 4, and 9. .\" .Sh Errors .\" .Sh "See also" .\" .Sh Standards .\" .Sh History .\" .Sh Authors .\" .Sh Caveats .\" .Sh Bugs The first items in the template are the commands .Dd, .Dt, and .Os. They identify the page and are discussed below in section “Title macros”. The remaining items in the template are section headings (.Sh); of which “Name” and “Description” are mandatory. These headings are dis‐ cussed in section “Page structure domain”, which follows section “Manual domain”. Familiarize yourself with manual domain macros first; we use them to illustrate the use of page structure domain macros. Conventions In the descriptions of macros below, square brackets surround optional arguments. An ellipsis (‘...’) represents repetition of the preceding argument zero or more times. Alternative values of a parameter are separated with ‘|’. If a mandatory parameter can take one of several alternative values, use braces to enclose the set, with spaces and ‘|’ separating the items. ztar {c | x} [-w [-y | -z]] [-f archive] member ... An alternative to using braces is to separately synopsize distinct op‐ eration modes, particularly if the list of valid optional arguments is dependent on the user’s choice of a mandatory parameter. ztar c [-w [-y | -z]] [-f archive] member ... ztar x [-w [-y | -z]] [-f archive] member ... Most macros affect subsequent arguments until another macro or a new‐ line is encountered. For example, ‘.Li ls Bq Ar file’ doesn’t produce ‘ls [file]’, but ‘ls [file]’. Consequently, a warning message is emit‐ ted for many commands if the first argument is itself a macro, since it cancels the effect of the preceding one. On rare occasions, you might want to format a word along with surrounding brackets as a literal. .Li "ls [file]" → ls [file] # list any files named e, f, i, or l Many macros possess an implicit width, used when they are contained in lists and displays. If you avoid relying on these default measure‐ ments, you escape potential conflicts with site‐local modifications of the mdoc package. Explicit -width and -offset arguments to the .Bl and .Bd macros are preferable. Title macros We present the mandatory title macros first due to their importance even though they formally belong to the page structure domain macros. They designate the topic, date of last revision, and the operating sys‐ tem or software project associated with the page. Call each once at the beginning of the document. They populate the page headers and footers, which are in roff parlance termed “titles”. .Dd date This first macro of any mdoc manual records the last modifica‐ tion date of the document source. Arguments are concatenated and separated with space characters. Historically, date was written in U.S. traditional format, “Month day , year” where Month is the full month name in Eng‐ lish, day an integer without a leading zero, and year the four‐ digit year. This localism is not enforced, however. You may prefer ISO 8601 format, YYYY‐MM‐DD. A date of the form ‘$Mdocdate: September 1 2023 $’ is also recognized. It is used in OpenBSD manuals to automatically insert the current date when committing. This macro is neither callable nor parsed. .Dt topic [section‐identifier [section‐keyword‐or‐title]] topic is the subject of the man page. A section‐identifier that begins with an integer in the range 1–9 or is one of the words ‘unass’, ‘draft’, or ‘paper’ selects a predefined section title. This use of “section” has nothing to do with the sec‐ tion headings otherwise discussed in this page; it arises from the organizational scheme of printed and bound Unix manuals. In this implementation, the following titles are defined for integral section numbers. 1 General Commands Manual 2 System Calls Manual 3 Library Functions Manual 4 Kernel Interfaces Manual 5 File Formats Manual 6 Games Manual 7 Miscellaneous Information Manual 8 System Manager’s Manual 9 Kernel Developer’s Manual A section title may be arbitrary or one of the following abbre‐ viations. USD User’s Supplementary Documents PS1 Programmer’s Supplementary Documents AMD Ancestral Manual Documents SMM System Manager’s Manual URM User’s Reference Manual PRM Programmer’s Manual KM Kernel Manual IND Manual Master Index LOCAL Local Manual CON Contributed Software Manual For compatibility, ‘MMI’ can be used for ‘IND’, and ‘LOC’ for ‘LOCAL’. Values from the previous table will specify a new section title. If section‐keyword‐or‐title designates a com‐ puter architecture recognized by groff mdoc, its value is prepended to the default section title as specified by the sec‐ ond parameter. By default, the following architecture keywords are defined. acorn26, acorn32, algor, alpha, amd64, amiga, amigappc, arc, arm, arm26, arm32, armish, atari, aviion, beagle, bebox, cats, cesfic, cobalt, dreamcast, emips, evbarm, evbmips, evbppc, evbsh3, ews4800mips, hp300, hp700, hpcarm, hpcmips, hpcsh, hppa, hppa64, i386, ia64, ibmnws, iyonix, landisk, loongson, luna68k, luna88k, m68k, mac68k, macppc, mips, mips64, mipsco, mmeye, mvme68k, mvme88k, mvmeppc, netwinder, news68k, newsmips, next68k, ofppc, palm, pc532, playstation2, pmax, pmppc, powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips, sh3, shark, socppc, solbourne, sparc, sparc64, sun2, sun3, tahoe, vax, x68k, x86_64, xen, zaurus If a section title is not determined after the above matches have been attempted, section‐keyword‐or‐title is used. The effects of varying ‘.Dt’ arguments on the page header con‐ tent are shown below. Observe how ‘\&’ prevents the numeral 2 from being used to look up a predefined section title. .Dt foo 2 → foo(2) System Calls Manual foo(2) .Dt foo 2 m68k → foo(2) m68k System Calls Manual foo(2) .Dt foo 2 baz → foo(2) System Calls Manual foo(2) .Dt foo \&2 baz → foo(2) baz foo(2) .Dt foo "" baz → foo baz foo .Dt foo M Z80 → foo(M) Z80 foo(M) roff strings define section titles and architecture identi‐ fiers. Site‐specific additions might be found in the file mdoc.local; see section “Files” below. This macro is neither callable nor parsed. .Os [operating‐system‐or‐package‐name [version‐or‐release]] This macro associates the document with a software distribu‐ tion. When composing a man page to be included in the base in‐ stallation of an operating system, do not provide an argument; mdoc will supply it. In this implementation, that default is “GNU”. It may be overridden in the site configuration file, mdoc.local; see section “Files” below. A portable software package maintaining its own man pages can supply its name and version number or release identifier as optional arguments. A version‐or‐release argument should use the standard nomencla‐ ture for the software specified. In the following table, rec‐ ognized version‐or‐release arguments for some predefined oper‐ ating systems are listed. As with .Dt, site additions might be defined in mdoc.local. ATT 7th, 7, III, 3, V, V.2, V.3, V.4 BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4 NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.6, 1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 3.0, 3.0.1, 3.0.2, 3.0.3, 3.1, 3.1.1, 4.0, 4.0.1, 5.0, 5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3, 5.1.4, 5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1, 7.0.2, 7.1, 7.1.1, 7.1.2, 7.2, 8.0, 8.1 FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8, 4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3, 5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 9.0, 9.1, 9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0, 12.1 OpenBSD 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6 DragonFly 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.8.1, 1.9, 1.10, 1.11, 1.12, 1.12.2, 1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2, 3.2.1, 3.2.2, 3.3, 3.4, 3.4.1, 3.4.2, 3.4.3, 3.5, 3.6, 3.6.1, 3.6.2, 3.7, 3.8, 3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4, 4.0.5, 4.0.6, 4.1, 4.2, 4.2.1, 4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1, 4.4.2, 4.4.3, 4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1, 5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2, 5.4.3, 5.5, 5.6, 5.6.1, 5.6.2 Darwin 8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0, 8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0, 9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0, 9.7.0, 9.8.0, 10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0, 10.5.0, 10.6.0, 10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0, 11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0, 12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0, 14.0.0, 14.1.0, 14.2.0, 14.3.0, 14.4.0, 14.5.0, 15.0.0, 15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0, 15.6.0, 16.0.0, 16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0, 16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0, 17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0, 18.2.0, 18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0 Historically, the first argument used with .Dt was BSD or ATT. An unrecognized version argument after ATT is replaced with “Unix”; for other predefined abbreviations, it is ignored and a warning diagnostic emitted. Otherwise, unrecognized arguments are displayed verbatim in the page footer. For instance, this page uses “.Os groff 1.23.0” whereas a locally produced page might employ “.Os "UXYZ CS Department"”, omitting versioning. This macro is neither callable nor parsed. Introduction to manual and general text domains What’s in a Name... The manual domain macro names are derived from the day to day informal language used to describe commands, subroutines and related files. Slightly different variations of this language are used to describe the three different aspects of writing a man page. First, there is the de‐ scription of mdoc macro command usage. Second is the description of a Unix command with mdoc macros, and third, the description of a command to a user in the verbal sense; that is, discussion of a command in the text of a man page. In the first case, troff macros are themselves a type of command; the general syntax for a troff command is: .Xx argument1 argument2 ... ‘.Xx’ is a macro command, and anything following it are arguments to be processed. In the second case, the description of a Unix command using the manual domain macros is a bit more involved; a typical “Synopsis” command line might be displayed as: filter [-flag] ⟨infile⟩ ⟨outfile⟩ Here, filter is the command name and the bracketed string -flag is a flag argument designated as optional by the option brackets. In mdoc terms, ⟨infile⟩ and ⟨outfile⟩ are called meta arguments; in this exam‐ ple, the user has to replace the meta expressions given in angle brack‐ ets with real file names. Note that in this document meta arguments are used to describe mdoc commands; in most man pages, meta variables are not specifically written with angle brackets. The macros that for‐ matted the above example: .Nm filter .Op Fl flag .Ao Ar infile Ac Ao Ar outfile Ac In the third case, discussion of commands and command syntax includes both examples above, but may add more detail. The arguments ⟨infile⟩ and ⟨outfile⟩ from the example above might be referred to as operands or file arguments. Some command‐line argument lists are quite long: make [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I directory] [-j max_jobs] [variable=value] [target ...] Here one might talk about the command make and qualify the argument, makefile, as an argument to the flag, -f, or discuss the optional file operand target. In the verbal context, such detail can prevent confu‐ sion, however the mdoc package does not have a macro for an argument to a flag. Instead the ‘Ar’ argument macro is used for an operand or file argument like target as well as an argument to a flag like variable. The make command line was produced from: .Nm make .Op Fl eiknqrstv .Op Fl D Ar variable .Op Fl d Ar flags .Op Fl f Ar makefile .Op Fl I Ar directory .Op Fl j Ar max_jobs .Op Ar variable Ns = Ns Ar value .Bk .Op Ar target ... .Ek The ‘.Bk’ and ‘.Ek’ macros are explained in “Keeps”. General Syntax The manual domain and general text domain macros share a similar syntax with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’ differ only when called without arguments; and ‘.Fn’ and ‘.Xr’ impose an order on their argument lists. All manual domain macros are capable of recognizing and properly handling punctuation, provided each punctuation character is separated by a leading space. If a command is given: .Ar sptr, ptr), The result is: sptr, ptr), The punctuation is not recognized and all is output in the font used by ‘.Ar’. If the punctuation is separated by a leading white space: .Ar sptr , ptr ) , The result is: sptr, ptr), The punctuation is now recognized and output in the default font dis‐ tinguishing it from the argument strings. To remove the special mean‐ ing from a punctuation character, escape it with ‘\&’. The following punctuation characters are recognized by mdoc: . , : ; ( ) [ ] ? ! troff is limited as a macro language, and has difficulty when presented with a string containing certain mathematical, logical, or quotation character sequences: {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"} The problem is that troff may assume it is supposed to actually perform the operation or evaluation suggested by the characters. To prevent the accidental evaluation of these characters, escape them with ‘\&’. Typical syntax is shown in the first manual domain macro displayed be‐ low, ‘.Ad’. Manual domain Addresses The address macro identifies an address construct. Usage: .Ad ⟨address⟩ ... .Ad addr1 addr1 .Ad addr1 . addr1. .Ad addr1 , file2 addr1, file2 .Ad f1 , f2 , f3 : f1, f2, f3: .Ad addr ) ) , addr)), The default width is 12n. Author Name The ‘.An’ macro is used to specify the name of the author of the item being documented, or the name of the author of the actual manual page. Usage: .An ⟨author name⟩ ... .An "Joe Author" Joe Author .An "Joe Author" , Joe Author, .An "Joe Author" Aq nobody@FreeBSD.org Joe Author .An "Joe Author" ) ) , Joe Author)), The default width is 12n. In a section titled “Authors”, ‘An’ causes a break, allowing each new name to appear on its own line. If this is not desirable, .An -nosplit call will turn this off. To turn splitting back on, write .An -split Arguments The .Ar argument macro may be used whenever an argument is referenced. If called without arguments, ‘file ...’ is output. This places the el‐ lipsis in italics, which is ugly and incorrect, and will be noticed on terminals that underline text instead of using an oblique typeface. We recommend using ‘.Ar file No ...’ instead. Usage: .Ar [⟨argument⟩] ... .Ar file ... .Ar file No ... file ... .Ar file1 file1 .Ar file1 . file1. .Ar file1 file2 file1 file2 .Ar f1 f2 f3 : f1 f2 f3: .Ar file ) ) , file)), The default width is 12n. Configuration Declaration (Section Four Only) The ‘.Cd’ macro is used to demonstrate a config(8) declaration for a device interface in a section four manual. Usage: .Cd ⟨argument⟩ ... .Cd "device le0 at scode?" device le0 at scode? In a section titled “Synopsis”, ‘Cd’ causes a break before and after its arguments. The default width is 12n. Command Modifiers The command modifier is identical to the ‘.Fl’ (flag) command with the exception that the ‘.Cm’ macro does not assert a dash in front of every argument. Traditionally flags are marked by the preceding dash, how‐ ever, some commands or subsets of commands do not use them. Command modifiers may also be specified in conjunction with interactive com‐ mands such as editor commands. See “Flags”. The default width is 10n. Defined Variables A variable (or constant) that is defined in an include file is speci‐ fied by the macro ‘.Dv’. Usage: .Dv ⟨defined‐variable⟩ ... .Dv MAXHOSTNAMELEN MAXHOSTNAMELEN .Dv TIOCGPGRP ) TIOCGPGRP) The default width is 12n. Errnos The ‘.Er’ errno macro specifies the error return value for section 2, 3, and 9 library routines. The second example below shows ‘.Er’ used with the ‘.Bq’ general text domain macro, as it would be used in a sec‐ tion two manual page. Usage: .Er ⟨errno type⟩ ... .Er ENOENT ENOENT .Er ENOENT ) ; ENOENT); .Bq Er ENOTDIR [ENOTDIR] The default width is 17n. Environment Variables The ‘.Ev’ macro specifies an environment variable. Usage: .Ev ⟨argument⟩ ... .Ev DISPLAY DISPLAY .Ev PATH . PATH. .Ev PRINTER ) ) , PRINTER)), The default width is 15n. Flags The ‘.Fl’ macro handles command‐line flags. It prepends a dash, ‘-’, to the flag. For interactive command flags that are not prepended with a dash, the ‘.Cm’ (command modifier) macro is identical, but without the dash. Usage: .Fl ⟨argument⟩ ... .Fl - .Fl cfv -cfv .Fl cfv . -cfv. .Cm cfv . cfv. .Fl s v t -s -v -t .Fl - , --, .Fl xyz ) , -xyz), .Fl | - | The ‘.Fl’ macro without any arguments results in a dash representing stdin/stdout. Note that giving ‘.Fl’ a single dash will result in two dashes. The default width is 12n. Function Declarations The ‘.Fd’ macro is used in the “Synopsis” section with section two or three functions. It is neither callable nor parsed. Usage: .Fd ⟨argument⟩ ... .Fd "#include " #include  In a section titled “Synopsis”, ‘Fd’ causes a break if a function has already been presented and a break has not occurred, leaving vertical space between one function declaration and the next. In a section titled “Synopsis”, the ‘In’ macro represents the #include statement, and is the short form of the above example. It specifies the C header file as being included in a C program. It also causes a break. While not in the “Synopsis” section, it represents the header file en‐ closed in angle brackets. Usage: .In ⟨header file⟩ .In stdio.h <stdio.h> .In stdio.h <stdio.h> Function Types This macro is intended for the “Synopsis” section. It may be used any‐ where else in the man page without problems, but its main purpose is to present the function type (in BSD kernel normal form) for the “Synopsis” of sections two and three. (It causes a break, allowing the function name to appear on the next line.) Usage: .Ft ⟨type⟩ ... .Ft struct stat struct stat Functions (Library Routines) The ‘.Fn’ macro is modeled on ANSI C conventions. Usage: .Fn ⟨function⟩ [⟨parameter⟩] ... .Fn getchar getchar() .Fn strlen ) , strlen()), .Fn align "char *ptr" , align(char *ptr), Note that any call to another macro signals the end of the ‘.Fn’ call (it will insert a closing parenthesis at that point). For functions with many parameters (which is rare), the macros ‘.Fo’ (function open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (function argument). Example: .Ft int .Fo res_mkquery .Fa "int op" .Fa "char *dname" .Fa "int class" .Fa "int type" .Fa "char *data" .Fa "int datalen" .Fa "struct rrec *newrr" .Fa "char *buf" .Fa "int buflen" .Fc Produces: int res_mkquery(int op, char *dname, int class, int type, char *data, int datalen, struct rrec *newrr, char *buf, int buflen) Typically, in a “Synopsis” section, the function delcaration will begin the line. If more than one function is presented in the “Synopsis” section and a function type has not been given, a break will occur, leaving vertical space between the current and prior function names. The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respec‐ tively. Function Arguments The ‘.Fa’ macro is used to refer to function arguments (parameters) outside of the “Synopsis” section of the manual or inside the “Synopsis” section if the enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used. ‘.Fa’ may also be used to refer to structure members. Usage: .Fa ⟨function argument⟩ ... .Fa d_namlen ) ) , d_namlen)), .Fa iov_len iov_len The default width is 12n. Return Values The ‘.Rv’ macro generates text for use in the “Return values” section. Usage: .Rv [-std] [⟨function⟩ ...] For example, ‘.Rv -std atexit’ produces: The atexit() function returns the value 0 if successful; other‐ wise the value -1 is returned and the global variable errno is set to indicate the error. The -std option is valid only for manual page sections 2 and 3. Cur‐ rently, this macro does nothing if used without the -std flag. Exit Status The ‘.Ex’ macro generates text for use in the “Diagnostics” section. Usage: .Ex [-std] [⟨utility⟩ ...] For example, ‘.Ex -std cat’ produces: The cat utility exits 0 on success, and >0 if an error occurs. The -std option is valid only for manual page sections 1, 6 and 8. Currently, this macro does nothing if used without the -std flag. Interactive Commands The ‘.Ic’ macro designates an interactive or internal command. Usage: .Ic ⟨argument⟩ ... .Ic :wq :wq .Ic "do while {...}" do while {...} .Ic setenv , unsetenv setenv, unsetenv The default width is 12n. Library Names The ‘.Lb’ macro is used to specify the library where a particular func‐ tion is compiled in. Usage: .Lb ⟨argument⟩ ... Available arguments to ‘.Lb’ and their results are: libarchive Reading and Writing Streaming Archives Library (libarchive, -larchive) libarm ARM Architecture Library (libarm, -larm) libarm32 ARM32 Architecture Library (libarm32, -larm32) libbluetooth Bluetooth Library (libbluetooth, -lbluetooth) libbsm Basic Security Module Library (libbsm, -lbsm) libc Standard C Library (libc, -lc) libc_r Reentrant C Library (libc_r, -lc_r) libcalendar Calendar Arithmetic Library (libcalendar, -lcalendar) libcam Common Access Method User Library (libcam, -lcam) libcdk Curses Development Kit Library (libcdk, -lcdk) libcipher FreeSec Crypt Library (libcipher, -lcipher) libcompat Compatibility Library (libcompat, -lcompat) libcrypt Crypt Library (libcrypt, -lcrypt) libcurses Curses Library (libcurses, -lcurses) libdevinfo Device and Resource Information Utility Library (libdevinfo, -ldevinfo) libdevstat Device Statistics Library (libdevstat, -ldevstat) libdisk Interface to Slice and Partition Labels Library (libdisk, -ldisk) libdwarf DWARF Access Library (libdwarf, -ldwarf) libedit Command Line Editor Library (libedit, -ledit) libelf ELF Access Library (libelf, -lelf) libevent Event Notification Library (libevent, -levent) libfetch File Transfer Library for URLs (libfetch, -lfetch) libform Curses Form Library (libform, -lform) libgeom Userland API Library for kernel GEOM subsystem (libgeom, -lgeom) libgpib General‐Purpose Instrument Bus (GPIB) library (libgpib, -lgpib) libi386 i386 Architecture Library (libi386, -li386) libintl Internationalized Message Handling Library (libintl, -lintl) libipsec IPsec Policy Control Library (libipsec, -lipsec) libipx IPX Address Conversion Support Library (libipx, -lipx) libiscsi iSCSI protocol library (libiscsi, -liscsi) libjail Jail Library (libjail, -ljail) libkiconv Kernel side iconv library (libkiconv, -lkiconv) libkse N:M Threading Library (libkse, -lkse) libkvm Kernel Data Access Library (libkvm, -lkvm) libm Math Library (libm, -lm) libm68k m68k Architecture Library (libm68k, -lm68k) libmagic Magic Number Recognition Library (libmagic, -lmagic) libmd Message Digest (MD4, MD5, etc.) Support Library (libmd, -lmd) libmemstat Kernel Memory Allocator Statistics Library (libmemstat, -lmemstat) libmenu Curses Menu Library (libmenu, -lmenu) libnetgraph Netgraph User Library (libnetgraph, -lnetgraph) libnetpgp Netpgp signing, verification, encryption and decryption (libnetpgp, -lnetpgp) libossaudio OSS Audio Emulation Library (libossaudio, -lossaudio) libpam Pluggable Authentication Module Library (libpam, -lpam) libpcap Packet Capture Library (libpcap, -lpcap) libpci PCI Bus Access Library (libpci, -lpci) libpmc Performance Counters Library (libpmc, -lpmc) libposix POSIX Compatibility Library (libposix, -lposix) libprop Property Container Object Library (libprop, -lprop) libpthread POSIX Threads Library (libpthread, -lpthread) libpuffs puffs Convenience Library (libpuffs, -lpuffs) librefuse File System in Userspace Convenience Library (librefuse, -lrefuse) libresolv DNS Resolver Library (libresolv, -lresolv) librpcsec_gss RPC GSS‐API Authentication Library (librpcsec_gss, -lrpcsec_gss) librpcsvc RPC Service Library (librpcsvc, -lrpcsvc) librt POSIX Real‐time Library (librt, -lrt) libsdp Bluetooth Service Discovery Protocol User Library (libsdp, -lsdp) libssp Buffer Overflow Protection Library (libssp, -lssp) libSystem System Library (libSystem, -lSystem) libtermcap Termcap Access Library (libtermcap, -ltermcap) libterminfo Terminal Information Library (libterminfo, -lterminfo) libthr 1:1 Threading Library (libthr, -lthr) libufs UFS File System Access Library (libufs, -lufs) libugidfw File System Firewall Interface Library (libugidfw, -lugidfw) libulog User Login Record Library (libulog, -lulog) libusbhid USB Human Interface Devices Library (libusbhid, -lusbhid) libutil System Utilities Library (libutil, -lutil) libvgl Video Graphics Library (libvgl, -lvgl) libx86_64 x86_64 Architecture Library (libx86_64, -lx86_64) libz Compression Library (libz, -lz) Site‐specific additions might be found in the file mdoc.local; see sec‐ tion “Files” below. In a section titled “Library”, ‘Lb’ causes a break before and after its arguments. Literals The ‘Li’ literal macro may be used for special characters, symbolic constants, and other syntactical items that should be typed exactly as displayed. Usage: .Li ⟨argument⟩ ... .Li \en \n .Li M1 M2 M3 ; M1 M2 M3; .Li cntrl-D ) , cntrl‐D), .Li 1024 ... 1024 ... The default width is 16n. Names The ‘Nm’ macro is used for the document title or page topic. Upon its first call, it has the peculiarity of remembering its argument, which should always be the topic of the man page. When subsequently called without arguments, ‘Nm’ regurgitates this initial name for the sole purpose of making less work for the author. Use of ‘Nm’ is also appro‐ priate when presenting a command synopsis for the topic of a man page in section 1, 6, or 8. Its behavior changes when presented with argu‐ ments of various forms. .Nm groff_mdoc groff_mdoc .Nm groff_mdoc .Nm \-mdoc -mdoc .Nm foo ) ) , foo)), .Nm : groff_mdoc: By default, the topic is set in boldface to reflect its prime impor‐ tance in the discussion. Cross references to other man page topics should use ‘Xr’; including a second argument for the section number en‐ ables them to be hyperlinked. By default, cross‐referenced topics are set in italics to avoid cluttering the page with boldface. The default width is 10n. Options The ‘.Op’ macro places option brackets around any remaining arguments on the command line, and places any trailing punctuation outside the brackets. The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a closing option bracket, respectively) may be used across one or more lines or to specify the exact position of the closing parenthesis. Usage: .Op [⟨option⟩] ... .Op [] .Op Fl k [-k] .Op Fl k ) . [-k]). .Op Fl k Ar kookfile [-k kookfile] .Op Fl k Ar kookfile , [-k kookfile], .Op Ar objfil Op Ar corfil [objfil [corfil]] .Op Fl c Ar objfil Op Ar corfil , [-c objfil [corfil]], .Op word1 word2 [word1 word2] .Li .Op Oo Ao option Ac Oc ... .Op [⟨option⟩] ... Here a typical example of the ‘.Oo’ and ‘.Oc’ macros: .Oo .Op Fl k Ar kilobytes .Op Fl i Ar interval .Op Fl c Ar count .Oc Produces: [[-k kilobytes] [-i interval] [-c count]] The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respec‐ tively. Pathnames The ‘.Pa’ macro formats file specifications. If called without argu‐ ments, ‘~’ (recognized by many shells) is output, representing the user’s home directory. Usage: .Pa [⟨pathname⟩] ... .Pa ~ .Pa /usr/share /usr/share .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX). The default width is 32n. Standards The ‘.St’ macro replaces standard abbreviations with their formal names. Usage: .St ⟨abbreviation⟩ ... Available pairs for “Abbreviation/Formal Name” are: ANSI/ISO C -ansiC ANSI X3.159‐1989 (“ANSI C89”) -ansiC-89 ANSI X3.159‐1989 (“ANSI C89”) -isoC ISO/IEC 9899:1990 (“ISO C90”) -isoC-90 ISO/IEC 9899:1990 (“ISO C90”) -isoC-99 ISO/IEC 9899:1999 (“ISO C99”) -isoC-2011 ISO/IEC 9899:2011 (“ISO C11”) POSIX Part 1: System API -iso9945-1-90 ISO/IEC 9945‐1:1990 (“POSIX.1”) -iso9945-1-96 ISO/IEC 9945‐1:1996 (“POSIX.1”) -p1003.1 IEEE Std 1003.1 (“POSIX.1”) -p1003.1-88 IEEE Std 1003.1‐1988 (“POSIX.1”) -p1003.1-90 ISO/IEC 9945‐1:1990 (“POSIX.1”) -p1003.1-96 ISO/IEC 9945‐1:1996 (“POSIX.1”) -p1003.1b-93 IEEE Std 1003.1b‐1993 (“POSIX.1”) -p1003.1c-95 IEEE Std 1003.1c‐1995 (“POSIX.1”) -p1003.1g-2000 IEEE Std 1003.1g‐2000 (“POSIX.1”) -p1003.1i-95 IEEE Std 1003.1i‐1995 (“POSIX.1”) -p1003.1-2001 IEEE Std 1003.1‐2001 (“POSIX.1”) -p1003.1-2004 IEEE Std 1003.1‐2004 (“POSIX.1”) -p1003.1-2008 IEEE Std 1003.1‐2008 (“POSIX.1”) POSIX Part 2: Shell and Utilities -iso9945-2-93 ISO/IEC 9945‐2:1993 (“POSIX.2”) -p1003.2 IEEE Std 1003.2 (“POSIX.2”) -p1003.2-92 IEEE Std 1003.2‐1992 (“POSIX.2”) -p1003.2a-92 IEEE Std 1003.2a‐1992 (“POSIX.2”) X/Open -susv1 Version 1 of the Single UNIX Specification (“SUSv1”) -susv2 Version 2 of the Single UNIX Specification (“SUSv2”) -susv3 Version 3 of the Single UNIX Specification (“SUSv3”) -susv4 Version 4 of the Single UNIX Specification (“SUSv4”) -svid4 System V Interface Definition, Fourth Edition (“SVID4”) -xbd5 X/Open Base Definitions Issue 5 (“XBD5”) -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”) -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”) -xns5 X/Open Networking Services Issue 5 (“XNS5”) -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”) -xpg3 X/Open Portability Guide Issue 3 (“XPG3”) -xpg4 X/Open Portability Guide Issue 4 (“XPG4”) -xpg4.2 X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”) -xsh5 X/Open System Interfaces and Headers Issue 5 (“XSH5”) Miscellaneous -ieee754 IEEE Std 754‐1985 -iso8601 ISO 8601 -iso8802-3 ISO/IEC 8802‐3:1989 Variable Types The ‘.Vt’ macro may be used whenever a type is referenced. In a sec‐ tion titled “Synopsis”, ‘Vt’ causes a break (useful for old‐style C variable declarations). Usage: .Vt ⟨type⟩ ... .Vt extern char *optarg ; extern char *optarg; .Vt FILE * FILE * Variables Generic variable reference. Usage: .Va ⟨variable⟩ ... .Va count count .Va settimer , settimer, .Va "int *prt" ) : int *prt): .Va "char s" ] ) ) , char s])), The default width is 12n. Manual Page Cross References The ‘.Xr’ macro expects the first argument to be a manual page name. The optional second argument, if a string (defining the manual sec‐ tion), is put into parentheses. Usage: .Xr ⟨man page name⟩ [⟨section⟩] ... .Xr mdoc mdoc .Xr mdoc , mdoc, .Xr mdoc 7 mdoc(7) .Xr xinit 1x ; xinit(1x); The default width is 10n. General text domain AT&T Macro Usage: .At [⟨version⟩] ... .At AT&T UNIX .At v6 . Version 6 AT&T UNIX. The following values for ⟨version⟩ are possible: 32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4 BSD Macro Usage: .Bx {-alpha | -beta | -devel} ... .Bx [⟨version⟩ [⟨release⟩]] ... .Bx BSD .Bx 4.3 . 4.3BSD. .Bx -devel BSD (currently under development) ⟨version⟩ will be prepended to the string ‘BSD’. The following values for ⟨release⟩ are possible: Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2 NetBSD Macro Usage: .Nx [⟨version⟩] ... .Nx NetBSD .Nx 1.4 . NetBSD 1.4. For possible values of ⟨version⟩ see the description of the ‘.Os’ com‐ mand above in section “Title macros”. FreeBSD Macro Usage: .Fx [⟨version⟩] ... .Fx FreeBSD .Fx 2.2 . FreeBSD 2.2. For possible values of ⟨version⟩ see the description of the ‘.Os’ com‐ mand above in section “Title macros”. DragonFly Macro Usage: .Dx [⟨version⟩] ... .Dx DragonFly .Dx 1.4 . DragonFly 1.4. For possible values of ⟨version⟩ see the description of the ‘.Os’ com‐ mand above in section “Title macros”. OpenBSD Macro Usage: .Ox [⟨version⟩] ... .Ox 1.0 OpenBSD 1.0 BSD/OS Macro Usage: .Bsx [⟨version⟩] ... .Bsx 1.0 BSD/OS 1.0 Unix Macro Usage: .Ux ... .Ux Unix Emphasis Macro Text may be stressed or emphasized with the ‘.Em’ macro. The usual font for emphasis is italic. Usage: .Em ⟨argument⟩ ... .Em does not does not .Em exceed 1024 . exceed 1024. .Em vide infra ) ) , vide infra)), The default width is 10n. Font Mode The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes no arguments). Font modes may be nested within other font modes. ‘.Bf’ has the following syntax: .Bf ⟨font mode⟩ ⟨font mode⟩ must be one of the following three types: Em | -emphasis Same as if the ‘.Em’ macro was used for the en‐ tire block of text. Li | -literal Same as if the ‘.Li’ macro was used for the en‐ tire block of text. Sy | -symbolic Same as if the ‘.Sy’ macro was used for the en‐ tire block of text. Both macros are neither callable nor parsed. Enclosure and Quoting Macros The concept of enclosure is similar to quoting. The object being to enclose one or more strings between a pair of characters like quotes or parentheses. The terms quoting and enclosure are used interchangeably throughout this document. Most of the one‐line enclosure macros end in small letter ‘q’ to give a hint of quoting, but there are a few irregu‐ larities. For each enclosure macro, there is a pair of opening and closing macros that end with the lowercase letters ‘o’ and ‘c’ respec‐ tively. Quote Open Close Function Result .Aq .Ao .Ac Angle Bracket Enclosure .Bq .Bo .Bc Bracket Enclosure [string] .Brq .Bro .Brc Brace Enclosure {string} .Dq .Do .Dc Double Quote “string” .Eq .Eo .Ec Enclose String (in XY) XstringY .Pq .Po .Pc Parenthesis Enclosure (string) .Ql Quoted Literal “string” or string .Qq .Qo .Qc Straight Double Quote "string" .Sq .So .Sc Single Quote ‘string’ All macros ending with ‘q’ and ‘o’ have a default width value of 12n. .Eo, .Ec These macros expect the first argument to be the opening and closing strings, respectively. .Es, .En To work around the nine‐argument limit in the original troff program, mdoc supports two other macros that are now obso‐ lete. ‘.Es’ uses its first and second parameters as opening and closing marks which are then used to enclose the argu‐ ments of ‘.En’. The default width value is 12n for both macros. .Eq The first and second arguments of this macro are the opening and closing strings respectively, followed by the arguments to be enclosed. .Ql The quoted literal macro behaves differently in troff and nroff modes. If formatted with nroff(1), a quoted literal is always quoted. If formatted with troff, an item is only quoted if the width of the item is less than three constant‐ width characters. This is to make short strings more visible where the font change to literal (constant‐width) is less no‐ ticeable. The default width is 16n. .Pf The prefix macro suppresses the whitespace between its first and second argument: .Pf ( Fa name2 (name2 The default width is 12n. The ‘.Ns’ macro (see below) performs the analogous suffix function. .Ap The ‘.Ap’ macro inserts an apostrophe and exits any special text modes, continuing in ‘.No’ mode. Examples of quoting: .Aq ⟨⟩ .Aq Pa ctype.h ) , ⟨ctype.h⟩), .Bq [] .Bq Em Greek , French . [Greek, French]. .Dq “” .Dq string abc . “string abc”. .Dq '\[ha][A-Z]' “’^[A‐Z]’” .Ql man mdoc ‘man mdoc’ .Qq "" .Qq string ) , "string"), .Qq string Ns ), "string)," .Sq ‘’ .Sq string ‘string’ .Em or Ap ing or’ing For a good example of nested enclosure macros, see the ‘.Op’ option macro. It was created from the same underlying enclosure macros as those presented in the list above. The ‘.Xo’ and ‘.Xc’ extended argu‐ ment list macros are discussed below. Normal text macro ‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’ and similar. Parsing is not suppressed, so you must prefix words like ‘No’ with ‘\&’ to avoid their interpretation as mdoc macros. Usage: .No argument ... .Em Use caution No here . → Use caution here. .Em No dogs allowed . → No dogs allowed. .Em \&No dogs allowed . → No dogs allowed. The default width is 12n. No‐Space Macro The ‘.Ns’ macro suppresses insertion of a space between the current po‐ sition and its first parameter. For example, it is useful for old style argument lists where there is no space between the flag and argu‐ ment: Usage: ... ⟨argument⟩ Ns [⟨argument⟩] ... .Ns ⟨argument⟩ ... .Op Fl I Ns Ar directory [-Idirectory] Note: The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating the space unless another macro name follows it. If used as a command (i.e., the second form above in the ‘Usage’ line), ‘.Ns’ is identical to ‘.No’. (Sub)section cross references Use the ‘.Sx’ macro to cite a (sub)section heading within the given document. Usage: .Sx ⟨section‐reference⟩ ... .Sx Files → “Files” The default width is 16n. Symbolics The symbolic emphasis macro is generally a boldface macro in either the symbolic sense or the traditional English usage. Usage: .Sy ⟨symbol⟩ ... .Sy Important Notice → Important Notice The default width is 6n. Mathematical Symbols Use this macro for mathematical symbols and similar things. Usage: .Ms ⟨math symbol⟩ ... .Ms sigma → sigma The default width is 6n. References and Citations The following macros make a modest attempt to handle references. At best, the macros make it convenient to manually drop in a subset of refer(1) style references. .Rs Reference start (does not take arguments). In a section titled “See also”, it causes a break and begins collec‐ tion of reference information until the reference end macro is read. .Re Reference end (does not take arguments). The reference is printed. .%A Reference author name; one name per invocation. .%B Book title. .%C City/place. .%D Date. .%I Issuer/publisher name. .%J Journal name. .%N Issue number. .%O Optional information. .%P Page number. .%Q Corporate or foreign author. .%R Report name. .%T Title of article. .%U Optional hypertext reference. .%V Volume. Macros beginning with ‘%’ are not callable but accept multiple argu‐ ments in the usual way. Only the ‘.Tn’ macro is handled properly as a parameter; other macros will cause strange output. ‘.%B’ and ‘.%T’ can be used outside of the ‘.Rs/.Re’ environment. Example: .Rs .%A "Matthew Bar" .%A "John Foo" .%T "Implementation Notes on foobar(1)" .%R "Technical Report ABC-DE-12-345" .%Q "Drofnats College" .%C "Nowhere" .%D "April 1991" .Re produces Matthew Bar and John Foo, Implementation Notes on foobar(1), Technical Report ABC‐DE‐12‐345, Drofnats College, Nowhere, April 1991. Trade Names or Acronyms The trade name macro prints its arguments at a smaller type size. It is intended to imitate a small caps fonts for fully capitalized acronyms. Usage: .Tn ⟨symbol⟩ ... .Tn DEC DEC .Tn ASCII ASCII The default width is 10n. Extended Arguments The .Xo and .Xc macros allow one to extend an argument list on a macro boundary for the ‘.It’ macro (see below). Note that .Xo and .Xc are implemented similarly to all other macros opening and closing an enclo‐ sure (without inserting characters, of course). This means that the following is true for those macros also. Here is an example of ‘.Xo’ using the space mode macro to turn spacing off: .Bd -literal -offset indent .Sm off .It Xo Sy I Ar operation .No \en Ar count No \en .Xc .Sm on .Ed produces Ioperation\ncount\n Another one: .Bd -literal -offset indent .Sm off .It Cm S No / Ar old_pattern Xo .No / Ar new_pattern .No / Op Cm g .Xc .Sm on .Ed produces S/old_pattern/new_pattern/[g] Another example of ‘.Xo’ and enclosure macros: Test the value of a variable. .Bd -literal -offset indent .It Xo .Ic .ifndef .Oo \&! Oc Ns Ar variable Oo .Ar operator variable No ... .Oc Xc .Ed produces .ifndef [!]variable [operator variable ...] Page structure domain Section headings The following ‘.Sh’ section heading macros are required in every man page. The remaining section headings are recommended at the discretion of the author writing the manual page. The ‘.Sh’ macro is parsed but not generally callable. It can be used as an argument in a call to ‘.Sh’ only; it then reactivates the default font for ‘.Sh’. The default width is 8n. .Sh Name The ‘.Sh Name’ macro is mandatory. If not speci‐ fied, headers, footers, and page layout defaults will not be set and things will be rather unpleas‐ ant. The Name section consists of at least three items. The first is the ‘.Nm’ name macro naming the subject of the man page. The second is the name de‐ scription macro, ‘.Nd’, which separates the subject name from the third item, which is the description. The description should be the most terse and lucid possible, as the space available is small. ‘.Nd’ first prints ‘-’, then all its arguments. .Sh Library This section is for section two and three function calls. It should consist of a single ‘.Lb’ macro call; see “Library Names”. .Sh Synopsis The “Synopsis” section describes the typical usage of the subject of a man page. The macros required are either ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’, ‘.Fc’, ‘.Fd’, and ‘.Ft’). The function name macro ‘.Fn’ is required for manual page sections 2 and 3; the command and general name macro ‘.Nm’ is required for sections 1, 5, 6, 7, and 8. Section 4 manuals require a ‘.Nm’, ‘.Fd’ or a ‘.Cd’ configura‐ tion device usage macro. Several other macros may be necessary to produce the synopsis line as shown below: cat [-benstuv] [-] file ... The following macros were used: .Nm cat .Op Fl benstuv .Op Fl .Ar file No ... .Sh Description In most cases the first text in the “Description” section is a brief paragraph on the command, func‐ tion or file, followed by a lexical list of options and respective explanations. To create such a list, the ‘.Bl’ (begin list), ‘.It’ (list item) and ‘.El’ (end list) macros are used (see “Lists and Columns” below). .Sh Implementation notes Implementation specific information should be placed here. .Sh Return values Sections 2, 3 and 9 function return values should go here. The ‘.Rv’ macro may be used to generate text for use in the “Return values” section for most sec‐ tion 2 and 3 library functions; see “Return Values”. The following ‘.Sh’ section headings are part of the preferred manual page layout and must be used appropriately to maintain consistency. They are listed in the order in which they would be used. .Sh Environment The Environment section should reveal any related environment variables and clues to their behavior and/or usage. .Sh Files Files which are used or created by the man page sub‐ ject should be listed via the ‘.Pa’ macro in the “Files” section. .Sh Examples There are several ways to create examples. See sub‐ section “Examples and Displays” below for details. .Sh Diagnostics Diagnostic messages from a command should be placed in this section. The ‘.Ex’ macro may be used to generate text for use in the “Diagnostics” section for most section 1, 6 and 8 commands; see “Exit Status”. .Sh Compatibility Known compatibility issues (e.g. deprecated options or parameters) should be listed here. .Sh Errors Specific error handling, especially from library functions (man page sections 2, 3, and 9) should go here. The ‘.Er’ macro is used to specify an error (errno). .Sh See also References to other material on the man page topic and cross references to other relevant man pages should be placed in the “See also” section. Cross references are specified using the ‘.Xr’ macro. Currently refer(1) style references are not accommo‐ dated. It is recommended that the cross references be sorted by section number, then alphabetically by name within each section, then separated by commas. Example: ls(1), ps(1), group(5), passwd(5) .Sh Standards If the command, library function, or file adheres to a specific implementation such as IEEE Std 1003.2 (“POSIX.2”) or ANSI X3.159‐1989 (“ANSI C89”) this should be noted here. If the command does not ad‐ here to any standard, its history should be noted in the History section. .Sh History Any command which does not adhere to any specific standards should be outlined historically in this section. .Sh Authors Credits should be placed here. Use the ‘.An’ macro for names and the ‘.Aq’ macro for email addresses within optional contact information. Explicitly in‐ dicate whether the person authored the initial man‐ ual page or the software or whatever the person is being credited for. .Sh Bugs Blatant problems with the topic go here. User‐specified ‘.Sh’ sections may be added; for example, this section was set with: .Sh "Page structure domain" Subsection headings Subsection headings have exactly the same syntax as section headings: ‘.Ss’ is parsed but not generally callable. It can be used as an argu‐ ment in a call to ‘.Ss’ only; it then reactivates the default font for ‘.Ss’. The default width is 8n. Paragraphs and Line Spacing .Pp The ‘.Pp’ paragraph command may be used to specify a line space where necessary. The macro is not necessary after a ‘.Sh’ or ‘.Ss’ macro or before a ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical distance unless the -compact flag is given). The macro is neither callable nor parsed and takes no arguments; an alternative name is ‘.Lp’. Keeps The only keep that is implemented at this time is for words. The macros are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep). The only option that ‘.Bk’ currently accepts is -words (also the default); this pre‐ vents breaks in the middle of options. In the example for make com‐ mand‐line arguments (see “What’s in a Name”), the keep prevents nroff from placing the flag and the argument on separate lines. Neither macro is callable or parsed. More work needs to be done on the keep macros; specifically, a -line option should be added. Examples and Displays There are seven types of displays. .D1 (This is D‐one.) Display one line of indented text. This macro is parsed but not callable. -ldghfstru The above was produced by: .D1 Fl ldghfstru. .Dl (This is D‐ell.) Display one line of indented literal text. The ‘.Dl’ example macro has been used throughout this file. It allows the indentation (display) of one line of text. Its default font is set to constant width (literal). ‘.Dl’ is parsed but not callable. % ls -ldg /usr/local/bin The above was produced by: .Dl % ls \-ldg /usr/local/bin. .Bd Begin display. The ‘.Bd’ display must be ended with the ‘.Ed’ macro. It has the following syntax: .Bd {-literal | -filled | -unfilled | -ragged | -centered} [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact] -ragged Fill, but do not adjust the right margin (only left‐justify). -centered Center lines between the current left and right margin. Note that each single line is cen‐ tered. -unfilled Do not fill; break lines where their input lines are broken. This can produce overlong lines without warning messages. -filled Display a filled block. The block of text is formatted (i.e., the text is justified on both the left and right side). -literal Display block with literal font (usually fixed‐ width). Useful for source code or simple tabbed or spaced text. -file ⟨file name⟩ The file whose name follows the -file flag is read and displayed before any data enclosed with ‘.Bd’ and ‘.Ed’, using the selected dis‐ play type. Any troff/mdoc commands in the file will be processed. -offset ⟨string⟩ If -offset is specified with one of the follow‐ ing strings, the string is interpreted to indi‐ cate the level of indentation for the forthcom‐ ing block of text: left Align block on the current left margin; this is the default mode of ‘.Bd’. center Supposedly center the block. At this time unfortunately, the block merely gets left aligned about an imaginary center margin. indent Indent by one default indent value or tab. The default indent value is also used for the ‘.D1’ and ‘.Dl’ macros, so one is guaranteed the two types of displays will line up. The indentation value is nor‐ mally set to 6n or about two thirds of an inch (six constant width characters). indent-two Indent two times the default indent value. right This left aligns the block about two inches from the right side of the page. This macro needs work and perhaps may never do the right thing within troff. If ⟨string⟩ is a valid numeric expression in‐ stead (with a scaling indicator other than ‘u’), use that value for indentation. The most useful scaling indicators are ‘m’ and ‘n’, specifying the so‐called Em and En square. This is approximately the width of the letters ‘m’ and ‘n’ respectively of the current font (for nroff output, both scaling indicators give the same values). If ⟨string⟩ isn’t a numeric expression, it is tested whether it is an mdoc macro name, and the default offset value asso‐ ciated with this macro is used. Finally, if all tests fail, the width of ⟨string⟩ (typeset with a fixed‐width font) is taken as the off‐ set. -compact Suppress insertion of vertical space before be‐ gin of display. .Ed End display (takes no arguments). Lists and Columns There are several types of lists which may be initiated with the ‘.Bl’ begin‐list macro. Items within the list are specified with the ‘.It’ item macro, and each list must end with the ‘.El’ macro. Lists may be nested within themselves and within displays. The use of columns in‐ side of lists or lists inside of columns is untested. In addition, several list attributes may be specified such as the width of a tag, the list offset, and compactness (blank lines between items allowed or disallowed). Most of this document has been formatted with a tag style list (-tag). It has the following syntax forms: .Bl {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩] [-offset ⟨string⟩] [-compact] .Bl -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ... .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset ⟨string⟩] [-compact] And now a detailed description of the list types. -bullet A bullet list. .Bl -bullet -offset indent -compact .It Bullet one goes here. .It Bullet two here. .El Produces: • Bullet one goes here. • Bullet two here. -dash (or -hyphen) A dash list. .Bl -dash -offset indent -compact .It Dash one goes here. .It Dash two here. .El Produces: - Dash one goes here. - Dash two here. -enum An enumerated list. .Bl -enum -offset indent -compact .It Item one goes here. .It And item two here. .El The result: 1. Item one goes here. 2. And item two here. If you want to nest enumerated lists, use the -nested flag (starting with the second‐level list): .Bl -enum -offset indent -compact .It Item one goes here .Bl -enum -nested -compact .It Item two goes here. .It And item three here. .El .It And item four here. .El Result: 1. Item one goes here. 1.1. Item two goes here. 1.2. And item three here. 2. And item four here. -item A list of type -item without list markers. .Bl -item -offset indent .It Item one goes here. Item one goes here. Item one goes here. .It Item two here. Item two here. Item two here. .El Produces: Item one goes here. Item one goes here. Item one goes here. Item two here. Item two here. Item two here. -tag A list with tags. Use -width to specify the tag width. SL sleep time of the process (seconds blocked) PAGEIN number of disk I/O operations resulting from ref‐ erences by the process to pages not loaded in core. UID numerical user‐id of process owner PPID numerical id of parent of process priority (non‐ positive when in non‐interruptible wait) The raw text: .Bl -tag -width "PPID" -compact -offset indent .It SL sleep time of the process (seconds blocked) .It PAGEIN number of disk I/O operations resulting from references by the process to pages not loaded in core. .It UID numerical user-id of process owner .It PPID numerical id of parent of process priority (non-positive when in non-interruptible wait) .El -diag Diag lists create section four diagnostic lists and are simi‐ lar to inset lists except callable macros are ignored. The -width flag is not meaningful in this context. Example: .Bl -diag .It You can’t use Sy here. The message says all. .El produces You can’t use Sy here. The message says all. -hang A list with hanging tags. Hanged labels appear similar to tagged lists when the label is smaller than the label width. Longer hanged list labels blend into the paragraph un‐ like tagged paragraph labels. And the unformatted text which created it: .Bl -hang -offset indent .It Em Hanged labels appear similar to tagged lists when the label is smaller than the label width. .It Em Longer hanged list labels blend into the paragraph unlike tagged paragraph labels. .El -ohang Lists with overhanging tags do not use indentation for the items; tags are written to a separate line. SL sleep time of the process (seconds blocked) PAGEIN number of disk I/O operations resulting from references by the process to pages not loaded in core. UID numerical user‐id of process owner PPID numerical id of parent of process priority (non‐positive when in non‐interruptible wait) The raw text: .Bl -ohang -offset indent .It Sy SL sleep time of the process (seconds blocked) .It Sy PAGEIN number of disk I/O operations resulting from references by the process to pages not loaded in core. .It Sy UID numerical user-id of process owner .It Sy PPID numerical id of parent of process priority (non-positive when in non-interruptible wait) .El -inset Here is an example of inset labels: Tag The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manu‐ als. Use a -width attribute as described below. Diag Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored. Hang Hanged labels are a matter of taste. Ohang Overhanging labels are nice when space is con‐ strained. Inset Inset labels are useful for controlling blocks of paragraphs and are valuable for converting mdoc manuals to other formats. Here is the source text which produced the above example: .Bl -inset -offset indent .It Em Tag The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manuals. .It Em Diag Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored. .It Em Hang Hanged labels are a matter of taste. .It Em Ohang Overhanging labels are nice when space is constrained. .It Em Inset Inset labels are useful for controlling blocks of paragraphs and are valuable for converting .Xr mdoc manuals to other formats. .El -column This list type generates multiple columns. The number of columns and the width of each column is determined by the ar‐ guments to the -column list, ⟨string1⟩, ⟨string2⟩, etc. If ⟨stringN⟩ starts with a ‘.’ (dot) immediately followed by a valid mdoc macro name, interpret ⟨stringN⟩ and use the width of the result. Otherwise, the width of ⟨stringN⟩ (typeset with a fixed‐width font) is taken as the Nth column width. Each ‘.It’ argument is parsed to make a row, each column within the row is a separate argument separated by a tab or the ‘.Ta’ macro. The table: String Nroff Troff <= <= ≤ >= >= ≥ was produced by: .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff" .It Sy String Ta Sy Nroff Ta Sy Troff .It Li <= Ta <= Ta \*(<= .It Li >= Ta >= Ta \*(>= .El Don’t abuse this list type! For more complicated cases it might be far better and easier to use tbl(1), the table pre‐ processor. Other keywords: -width ⟨string⟩ If ⟨string⟩ starts with a ‘.’ (dot) immediately fol‐ lowed by a valid mdoc macro name, interpret ⟨string⟩ and use the width of the result. Almost all lists in this document use this option. Example: .Bl -tag -width ".Fl test Ao Ar string Ac" .It Fl test Ao Ar string Ac This is a longer sentence to show how the .Fl width flag works in combination with a tag list. .El gives: -test ⟨string⟩ This is a longer sentence to show how the -width flag works in combination with a tag list. (Note that the current state of mdoc is saved before ⟨string⟩ is interpreted; afterwards, all variables are restored again. However, boxes (used for enclo‐ sures) can’t be saved in GNU troff(1); as a conse‐ quence, arguments must always be balanced to avoid nasty errors. For example, do not write ‘.Ao Ar string’ but ‘.Ao Ar string Xc’ instead if you really need only an opening angle bracket.) Otherwise, if ⟨string⟩ is a valid numeric expression (with a scaling indicator other than ‘u’), use that value for indentation. The most useful scaling indi‐ cators are ‘m’ and ‘n’, specifying the so‐called Em and En square. This is approximately the width of the letters ‘m’ and ‘n’ respectively of the current font (for nroff output, both scaling indicators give the same values). If ⟨string⟩ isn’t a numeric ex‐ pression, it is tested whether it is an mdoc macro name, and the default width value associated with this macro is used. Finally, if all tests fail, the width of ⟨string⟩ (typeset with a fixed‐width font) is taken as the width. If a width is not specified for the tag list type, ‘6n’ is used. -offset ⟨string⟩ If ⟨string⟩ is indent, a default indent value (nor‐ mally set to 6n, similar to the value used in ‘.Dl’ or ‘.Bd’) is used. If ⟨string⟩ is a valid numeric expression instead (with a scaling indicator other than ‘u’), use that value for indentation. The most useful scaling indicators are ‘m’ and ‘n’, specifying the so‐called Em and En square. This is approxi‐ mately the width of the letters ‘m’ and ‘n’ respec‐ tively of the current font (for nroff output, both scaling indicators give the same values). If ⟨string⟩ isn’t a numeric expression, it is tested whether it is an mdoc macro name, and the default offset value associated with this macro is used. Fi‐ nally, if all tests fail, the width of ⟨string⟩ (typeset with a fixed‐width font) is taken as the offset. -compact Suppress insertion of vertical space before the list and between list items. Miscellaneous macros A double handful of macros fit only uncomfortably into one of the above sections. Of these, we couldn’t find attested examples for ‘Me’ or ‘Ot’. They are documented here for completeness—if you know their proper usage, please send a mail to groff@gnu.org and include a speci‐ men with its provenance. .Bt formats boilerplate text. .Bt → is currently in beta test. It is neither callable nor parsed and takes no arguments. Its de‐ fault width is 6n. .Fr is an obsolete means of specifying a function return value. Usage: .Fr return‐value ... ‘Fr’ allows a break right before the return value (usually a sin‐ gle digit) which is bad typographical behaviour. Instead, set the return value with the rest of the code, using ‘\~’ to tie the re‐ turn value to the previous word. Its default width is 12n. .Hf Inlines the contents of a (header) file into the document. Usage: .Hf file It first prints ‘File:’ followed by the file name, then the con‐ tents of file. It is neither callable nor parsed. .Lk Embed hyperlink. Usage: .Lk uri [link‐text] Its default width is 6n. .Me Usage unknown. The mdoc sources describe it as a macro for “menu entries”. Its default width is 6n. .Mt Embed email address. Usage: .Mt email‐address Its default width is 6n. .Ot Usage unknown. The mdoc sources describe it as “old function type (fortran)”. .Sm Manipulate or toggle argument‐spacing mode. Usage: .Sm [on | off] ... If argument‐spacing mode is off, no spaces between macro arguments are inserted. If called without a parameter (or if the next para‐ meter is neither ‘on’ nor ‘off’), ‘Sm’ toggles argument‐spacing mode. Its default width is 8n. .Ud formats boilerplate text. .Ud → currently under development. It is neither callable nor parsed and takes no arguments. Its de‐ fault width is 8n. Predefined strings The following strings are predefined for compatibility with legacy mdoc documents. Contemporary ones should use the alternatives shown in the “Prefer” column below. See groff_char(7) for a full discussion of these special character escape sequences. String 7‐bit 8‐bit UCS Prefer Meaning \*(<= <= <= ≤ \(<= less than or equal to \*(>= >= >= ≥ \(>= greater than or equal to \*(Rq " " ” \(rq right double quote \*(Lq " " “ \(lq left double quote \*(ua ^ ^ ↑ \(ua vertical arrow up \*(aa ' ´ ´ \(aa acute accent \*(ga ` ` ` \(ga grave accent \*(q " " " \(dq neutral double quote \*(Pi pi pi π \(*p lowercase pi \*(Ne != != ≠ \(!= not equals \*(Le <= <= ≤ \(<= less than or equal to \*(Ge >= >= ≥ \(>= greater than or equal to \*(Lt < < < < less than \*(Gt > > > > greater than \*(Pm +- ± ± \(+- plus or minus \*(If infinity infinity ∞ \(if infinity \*(Am & & & & ampersand \*(Na NaN NaN NaN NaN not a number \*(Ba | | | | bar Some column headings are shorthand for standardized character encod‐ ings; “7‐bit” for ISO 646:1991 IRV (US‐ASCII), “8‐bit” for ISO 8859‐1 (Latin‐1) and IBM code page 1047, and “UCS” for ISO 10646 (Unicode character set). Historically, mdoc configured the string definitions to fit the capabilities expected of the output device. Old typesetters lacked directional double quotes, producing repeated directional single quotes ‘‘like this’’; early versions of mdoc in fact defined the ‘Lq’ and ‘Rq’ strings this way. Nowadays, output drivers take on the re‐ sponsibility of glyph substitution, as they possess relevant knowledge of their available repertoires. Diagnostics The debugging macro ‘.Db’ offered by previous versions of mdoc is un‐ available in GNU troff(1) since the latter provides better facilities to check parameters; additionally, groff mdoc implements many error and warning messages, making the package more robust and more verbose. The remaining debugging macro is ‘.Rd’, which dumps the package’s global register and string contents to the standard error stream. A normal user will never need it. Options The following groff options set registers (with -r) and strings (with -d) recognized and used by the mdoc macro package. To ensure rendering consistent with output device capabilities and reader preferences, man pages should never manipulate them. Setting string ‘AD’ configures the adjustment mode for most formatted text. Typical values are ‘b’ for adjustment to both margins (the de‐ fault), or ‘l’ for left alignment (ragged right margin). Any valid ar‐ gument to groff’s ‘ad’ request may be used. See groff(7) for less‐com‐ mon choices. groff -Tutf8 -dAD=l -mdoc groff_mdoc.7 | less -R Setting register ‘C’ to 1 numbers output pages consecutively, rather than resetting the page number to 1 (or the value of register ‘P’) with each new mdoc document. By default, the package inhibits page breaks, headers, and footers in the midst of the document text if it is being displayed with a terminal device such as ‘latin1’ or ‘utf8’, to enable more efficient viewing of the page. This behavior can be changed to format the page as if for 66‐line Teletype output by setting the continuous rendering register ‘cR’ to zero while calling groff(1). groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt On HTML devices, it cannot be disabled. Section headings (defined with ‘.Sh’) and page titles in headers (de‐ fined with ‘.Dt’) can be presented in full capitals by setting the reg‐ isters ‘CS’ and ‘CT’, respectively, to 1. These transformations are off by default because they discard case distinction information. Setting register ‘D’ to 1 enables double‐sided page layout, which is only distinct when not continuously rendering. It places the page num‐ ber at the bottom right on odd‐numbered (recto) pages, and at the bot‐ tom left on even‐numbered (verso) pages, swapping places with the argu‐ ments to ‘.Os’. groff -Tps -rD1 -mdoc foo.man > foo.ps The value of the ‘FT’ register determines the footer’s distance from the page bottom; this amount is always negative and should specify a scaling unit. At one half‐inch above this location, the page text is broken before writing the footer. It is ignored if continuous render‐ ing is enabled. The default is -0.5i. The ‘HF’ string sets the font used for section and subsection headings; the default is ‘B’ (bold style of the default family). Any valid argu‐ ment to groff’s ‘ft’ request may be used. Normally, automatic hyphenation is enabled using a mode appropriate to the groff locale; see section “Localization“ of groff(7). It can be disabled by setting the ‘HY’ register to zero. groff -Tutf8 -rHY=0 -mdoc foo.man | less -R The paragraph and subsection heading indentation amounts can be changed by setting the registers ‘IN’ and ‘SN’. groff -Tutf8 -rIN=5n -rSN=2n -mdoc foo.man | less -R The default paragraph indentation is 7.2n on typesetters and 7n on ter‐ minals. The default subsection heading indentation amount is 3n; sec‐ tion headings are set with an indentation of zero. The line and title lengths can be changed by setting the registers ‘LL’ and ‘LT’, respectively: groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less -R If not set, both registers default to 78n for terminal devices and 6.5i otherwise. Setting the ‘P’ register starts enumeration of pages at its value. The default is 1. To change the document font size to 11p or 12p, set register ‘S’ ac‐ cordingly: groff -Tdvi -rS11 -mdoc foo.man > foo.dvi Register ‘S’ is ignored when formatting for terminal devices. Setting the ‘X’ register to a page number p numbers its successors as pa, pb, pc, and so forth. The register tracking the suffixed page let‐ ter uses format ‘a’ (see the ‘af’ request in groff(7)). Files /usr/local/share/groff/1.23.0/tmac/andoc.tmac This brief groff program detects whether the man or mdoc macro package is being used by a document and loads the correct macro definitions, taking advantage of the fact that pages using them must call TH or Dd, respectively, before any other macros. A user typing, for example, groff -mandoc page.1 need not know which package the file page.1 uses. Multiple man pages, in either format, can be handled; andoc.tmac reloads each macro package as necessary. /usr/local/share/groff/1.23.0/tmac/doc.tmac implements the bulk of the groff mdoc package and loads further components as needed from the mdoc subdirectory. /usr/local/share/groff/1.23.0/tmac/mdoc.tmac is a wrapper that loads doc.tmac. /usr/local/share/groff/1.23.0/tmac/mdoc/doc-common defines macros, registers, and strings concerned with the pro‐ duction of formatted output. It includes strings of the form ‘doc-volume-ds-X’ and ‘doc-volume-as-X’ for manual section ti‐ tles and architecture identifiers, respectively, where X is an argument recognized by .Dt. /usr/local/share/groff/1.23.0/tmac/mdoc/doc-nroff defines parameters appropriate for rendering to terminal de‐ vices. /usr/local/share/groff/1.23.0/tmac/mdoc/doc-ditroff defines parameters appropriate for rendering to typesetter de‐ vices. /usr/local/share/groff/1.23.0/tmac/mdoc/doc-syms defines many strings and macros that interpolate formatted text, such as names of operating system releases, *BSD li‐ braries, and standards documents. The string names are of the form ‘doc-str-O-V’, ‘doc-str-St--S-I’ (observe the double dashes), or ‘doc-str-Lb-L’, where O is one of the operating system macros from section “General text domain” above, V is an encoding of an operating system release (sometimes omitted along with the ‘-’ preceding it), S an identifier for a stan‐ dards body or committee, I one for an issue of a standard pro‐ mulgated by S, and L a keyword identifying a *BSD library. /usr/local/share/groff/site-tmac/mdoc.local This file houses local additions and customizations to the package. It can be empty. See also The mandoc: https://mandoc.bsd.lv/ project maintains an independent im‐ plementation of the mdoc language and a renderer that directly parses its markup as well as that of man. groff(1), man(1), troff(1), groff_man(7), mdoc(7) Bugs Section 3f has not been added to the header routines. ‘.Fn’ needs to have a check to prevent splitting up the line if its length is too short. Occasionally it separates the last parenthesis, and sometimes looks ridiculous if output lines are being filled. The list and display macros do not do any keeps and certainly should be able to. As of groff 1.23, ‘Tn’ no longer changes the type size; this function‐ ality may return in the next release. groff 1.23.0 29 August 2023 groff_mdoc(7) ─────────────────────────────────────────────────────────────────────────────── groff_me(7) Miscellaneous Information Manual groff_me(7) Name groff_me - “me” macro package for formatting roff documents Synopsis groff -me [option ...] [file ...] groff -m me [option ...] [file ...] Description The GNU implementation of the me macro package is part of the groff document formatting system. The me package of macro definitions for the roff language provides a convenient facility for preparing techni‐ cal papers in various formats. This version is based on the me dis‐ tributed with 4.4BSD and can be used with the GNU troff formatter as well as those descended from AT&T troff. Some formatter requests affect page layout unpredictably when used in conjunction with this package; however, the following may be used with impunity after the first call to a paragraphing macro like lp or pp. Some arguments are optional; see groff(7) for details, particularly of requests whose argument list is designated with an ellipsis. An aster‐ isk * marks groff extensions. ad c set text adjustment mode to c af r f assign format f to register r am m e append to macro m until e called as s t append rest of line t to string s bp n begin new page numbered n br break output line ce n center next n output lines cp n en‐/disable AT&T troff compatibility mode* de m e define macro m until e called do t interpret input t with compatibility mode off* ds s t define rest of line t as string s el t interpret t if corresponding ie false fc c d set field delimiter c and padding glyph d fi enable filling hc c set hyphenation character to c hy m set automatic hyphenation mode to m ie p t as if, but enable interpretation of later el if p t if condition p, interpret rest of line t in h set indentation to distance h lc c set leader repetition glyph to c ls n set line spacing to n mc c h set (right) margin glyph to c at distance h mk r mark vertical position in register r na disable adjustment of text ne v need vertical space of distance v nf disable filling nh disable automatic hyphenation nr r n i assign register r value n with auto‐increment i ns begin no‐space mode pl v set page length to v pn n set next page number to n po h set page offset to h rj n right‐align next n output lines* rm m remove macro, string, or request m rn m n rename macro, string, or request m to n rr r remove register r rs resume spacing (end no‐space mode) rt v return to vertical position set by mk, or v so f source (interpolate) input file f sp n insert n lines of vertical space ta ... set tab stops tc c set tab repetition glyph to c ti h set temporary indentation (next line only) to h tl ... output three‐part title tr ... translate characters ul n underline next n output lines Except on title pages (produced by calling tp), me suppresses the out‐ put of vertical space at the tops of pages (after the output of any page header); the sp request will thus not work there. You can instead call bl or enclose the desired spacing request in a diversion, for in‐ stance by calling (b and )b. me also intercepts the ll request; see the “me Reference Manual” for details. Name space Objects in me follow a rigid naming convention. To avoid conflict, any user‐defined register, string, or macro names should be single numerals or uppercase letters, or any longer sequence of letters and numerals with at least one uppercase letter. (For portability between BSD and groff me, limit names to two characters, and avoid the name [ (left square bracket).) The names employed by any preprocessors in use should also not be repurposed. Macros $0 post‐section heading hook $1 pre‐section depth 1 hook $2 pre‐section depth 2 hook $3 pre‐section depth 3 hook $4 pre‐section depth 4 hook $5 pre‐section depth 5 hook $6 pre‐section depth 6 hook $C post‐chapter title hook $H page/column heading hook $c output chapter number and title $f output footer $h output header $p output section heading $s output footnote area separator (b begin block (c begin centered block (d begin delayed text (f begin footnote (l begin list (q begin long quotation (x begin index entry (z begin floating keep )b end block )c end centered block )d end delayed text )f end footnote )l end list )q end long quotation )x end index entry )z end floating keep ++ set document segment type +c begin chapter 1c end multi‐column layout 2c begin multi‐column layout EN end eqn equation EQ begin eqn equation GE end grn picture with drawing position at bottom GF end grn picture with drawing position at top GS start grn picture IE end ideal picture with drawing position at bottom IF end ideal picture with drawing position at top IS start ideal picture PE end pic picture with drawing position at bottom PF end pic picture with drawing position at top PS start pic picture TE end tbl table TH end heading for multi‐page tbl table TS start tbl table b embolden argument ba set base indentation bc begin new column bi embolden and italicize argument bx box argument ef set even‐numbered page footer eh set even‐numbered page header ep end page fo set footer he set header hl draw horizontal line hx suppress next page’s headers/footers i italicize argument ip begin indented paragraph ld reset localization and date registers and strings* ll set line length lp begin fully left‐aligned paragraph np begin numbered paragraph of set odd‐numbered page footer oh set odd‐numbered page header pd output delayed text pp begin first‐line indented paragraph q quote argument r set argument in roman re reset tab stops sh begin numbered section sm set argument at smaller type size sx change section depth sz set type size and vertical spacing tp begin title page u underline argument uh begin unnumbered section xl set line length (local) xp output index Some macros are provided for “old” roff(1) compatibility. The “me Ref‐ erence Manual” describes alternatives for modern documents. ar use Arabic numerals for page numbers bl insert space (even at page top; cf. sp) ix set indentation without break m1 set page top to header distance m2 set header to text distance m3 set text to footer distance m4 set footer to page bottom distance n1 begin output line numbering n2 end or alter output line numbering pa begin page ro use Roman numerals for page numbers sk skip next page Registers $0 section depth $1 first section number component $2 second section number component $3 third section number component $4 fourth section number component $5 fifth section number component $6 sixth section number component $c current column number $d delayed text number $f footnote number $i paragraph base indentation $l column width $m number of available columns $p numbered paragraph number $s column spacing (indentation) bi display (block) indentation bm distance from text area to page bottom bs display (block) pre/post space bt block threshold for keeps ch current chapter number df display font dv vertical spacing of displayed text (as percentage)* es equation pre/post space ff footnote font fi footnote indentation (first line only) fm footer margin fp footnote type size in points fs footnote prespace fu footnote undent (right indentation) hm header margin ii indented paragraph indentation no line numbering offset* pf paragraph font pi paragraph indentation po page offset pp paragraph type size in points ps paragraph prespace qi long quotation left/right indentation qp long quotation type size in points qs long quotation pre/post space sf section title font si section indentation per level of depth so additional section title offset sp section title type size in points ss section prespace sx super/subscript line height increase* tf title font tm distance from page top to text area tp title type size in points tv vertical spacing of text (as percentage)* xs index entry prespace xu index undent (right indentation) y2 year of the century* y4 year* yr year minus 1900 zs floating keep pre/post space Strings # delayed text marker $n concatenated section number * footnote marker - em dash < begin subscripting > end subscripting dw weekday name lq left double quotation mark mo month name rq right double quotation mark td date wa term for “appendix” used by .$c* wc term for “chapter” used by .$c* { begin superscripting } end superscripting Files /usr/local/share/groff/1.23.0/tmac/e.tmac implements the package. /usr/local/share/groff/1.23.0/tmac/refer-me.tmac implements refer(1) support for me. /usr/local/share/groff/1.23.0/tmac/me.tmac is a wrapper enabling the package to be loaded with “groff -m me”. Notes Early roff macro packages often limited their names to a single letter, which followed the formatter’s m flag letter, resulting in mm, ms, mv, mn, and so on. The “e” in “me” stands for “Eric P. Allman”, who wrote the macro package and the original technical papers documenting it while an undergraduate at the University of California. See also Two manuals are available in source and rendered form. On your system, they may be compressed and/or available in additional formats. /usr/local/share/doc/groff-1.23.0/meintro.me /usr/local/share/doc/groff-1.23.0/meintro.ps is “Writing Papers with Groff Using -me”, by Eric P. Allman, adapted for groff by James Clark. /usr/local/share/doc/groff-1.23.0/meref.me /usr/local/share/doc/groff-1.23.0/meref.ps is the “me Reference Manual”, by Eric P. Allman, adapted for groff by James Clark and G. Branden Robinson. Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. For preprocessors supported by me, see eqn(1), grn(1), pic(1), refer(1), and tbl(1). groff(1), troff(1), groff(7) groff 1.23.0 29 August 2023 groff_me(7) ─────────────────────────────────────────────────────────────────────────────── groff_mm(7) Miscellaneous Information Manual groff_mm(7) Name groff_mm - memorandum macros for GNU roff Synopsis groff -mm [option ...] [file ...] groff -m mm [option ...] [file ...] Description The GNU implementation of the mm macro package is part of the groff document formatting system. The mm package is suitable for the compo‐ sition of letters, memoranda, reports, and books. Call an mm macro at the beginning of a document to initialize the pack‐ age. A simple mm document might use only P for paragraphing. Set num‐ bered and unnumbered section headings with H and HU, respectively. Change the style of the typeface with B, I, and R; you can alternate styles with BI, BR, IB, IR, RB, and RI. Several nestable list types are available via AL, BL, BVL, DL, ML, RL, and VL; each of these begins a list, to which LI adds an item and LE ends the (nested) list. Cus‐ tomized list arrangements are supported by LB. DS and DF start static and floating displays, respectively; either is terminated with DE. groff mm is intended to be compatible with the mm implementation found in the AT&T Documenter’s Workbench (DWB), with the following limita‐ tions. • Omitted features include the logo and company name strings, }Z and ]S, respectively; the encoded company site location addresses recog‐ nized as the third argument to the AU macro; the Pv (“private” head‐ ing) register; and the OK (other keywords), and PM (proprietary mark‐ ings) macros. • The CS (output cover sheet) macro is implemented only for memorandum type 4. • The grap preprocessor is not explicitly supported; no G1 and G2 macros are defined. • The registers A, C, E, T, and U, typically set from the troff or nroff command lines with DWB mm, are not recognized. • When setting the registers L or W from the command line, use an ex‐ plicit scaling unit to avoid surprises. • DWB mm’s nP macro indented the second line of a paragraph to align it with the start of the text of the first (after the paragraph number); groff mm’s does not. • Cut marks are not supported. DWB mm supported only seven levels of heading. As a compatible exten‐ sion, groff mm supports fourteen, introducing new registers H8 through H14, and affecting the interpretation of the HF and HP strings. Macro, register, and string descriptions in this page frequently men‐ tion each other; most cross references are to macros. Where a register or string is referenced, its type is explicitly identified. mm’s macro names are usually in full capitals; registers and strings tend to have mixed‐case names. Document styles groff mm offers three different frameworks for document organization. COVER/COVEND is a flexible means of preparing any document requiring a cover page. LT/LO aids preparation of typical Anglophone correspon‐ dence (business letters, for example). The MT memorandum type mecha‐ nism implements a group of formal styles historically used by AT&T Bell Laboratories. Your document can select at most one of these ap‐ proaches; when used, each disables the others. Localization groff mm is designed to be easily localized. For languages other than English, strings that can appear in output are collected in the file /usr/local/share/groff/1.23.0/tmac/xx.tmac, where xx is an ISO 639 two‐ letter language identifier. Localization packages should be loaded af‐ ter mm; for example, you might format a Swedish mm document with the command “groff -mm -msv”. This package can also be localized by site or territory; for example, /usr/local/share/groff/1.23.0/tmac/mse.tmac illustrates how to adapt the output to a national standard using its ISO 3166 territory code. Such a package can define a string that causes a macro file /usr/local/ share/groff/1.23.0/tmac/mm/territory_locale to be loaded at package initialization. If this mechanism is not used, /usr/local/share/groff/ 1.23.0/tmac/mm/locale is loaded instead. No diagnostic is produced if these files do not exist. Registers and strings Much mm behavior can be configured by registers and strings. A regis‐ ter is assigned with the nr request. .nr ident [±]n [i] ident is the name of the register, and n is the value to be assigned. n can be prefixed with a plus or minus sign if incrementation or decre‐ mentation (respectively) of the register’s existing value by n is de‐ sired. If assignment of a (possibly) negative n is required, further prefix it with a zero or enclose it in parentheses. If i is specified, the register is automatically modified by i prior to interpolation if a plus or minus sign is included in the escape sequence as follows. \n[±][ident] i can be negative; it combines algebraically with the sign in the in‐ terpolation escape sequence. Strings are defined with the ds request. .ds ident contents contents consumes everything up to the end of the line, including trailing spaces. It is a good practice to end contents with a comment escape sequence (\") so that extraneous spaces do not intrude during document maintenance. To include leading spaces in contents, prefix it with a double quote. Strings are interpolated with the \* escape se‐ quence. \*[ident] Register and string name spaces are distinct, but strings and macros share a name space. Defining a string with the same name as an mm macro is not supported and may cause incorrect rendering, the emission of diagnostic messages, and an error exit status from troff. Register format A register is interpolated using Arabic numerals if no other format has been assigned to it. Assign a format to a register with the af re‐ quest. .af R c R is the name of the register, and c is the format. If c is a sequence of Arabic numerals, their quantity defines a zero‐padded minimum width for the interpolated register value. Form Sequence 1 0, 1, 2, 3, ..., 10, ... 001 000, 001, 002, 003, ..., 1000, ... i 0, i, ii, iii, iv, ... I 0, I, II, III, IV, ... a 0, a, b, c, ..., z, aa, ab, ... A 0, A, B, C, ..., Z, AA, AB, ... Fonts In groff mm, the fonts (or rather, font styles) R (roman), I (italic), and B (bold) are mounted at font positions 1, 2, and 3, respectively. Internally, font positions are used for backward compatibility. From a practical point of view, it doesn’t make a big difference—a different font family can still be selected by invoking groff’s fam request or using its -f command‐line option. On the other hand, if you want to replace just, for example, font I with Zapf Chancery Medium italic (available on groff’s pdf and ps output devices), you have to use the fp request, replacing the font at position 2 with “.fp 2 ZCMI”). Be‐ cause the cover sheet, memorandum type, and refer(1) integration macros explicitly request fonts named B, I, and R, you will also need to remap these font names with the ftr request, for instance with “.ftr I ZCMI”. Macros An explicitly empty argument may be specified with a pair of double quotes; to call a macro XX with an empty second argument but non‐empty first and third ones, you could input the following. .XX foo "" baz Macro names longer than two characters are GNU extensions; some shorter names were not part of DWB mm’s published interface but are documented aspects of groff mm. )E level text Add heading text text to the table of contents with level, which is either 0 or in the range 1 to 7. See also H. This undocu‐ mented DWB mm macro is exposed by groff mm to enable customized tables of contents. 1C [1] Format page text in one column. The page is broken. A 1 argu‐ ment suppresses this break; its use may cause body text and a pending footnote to overprint. See 2C, MC, and NCOL. 2C Begin two‐column formatting. This is a special case of MC. See 1C and NCOL. AE Abstract end; stop collecting abstract text. See AS. AF [firm‐name] Specify firm associated with the document. At most one can be declared; the firm name is used by memorandum types and avail‐ able to cover sheets. AF terminates a document title started with TL, and can be called without an argument for that purpose. See MT and COVER. AL [type [text‐indent [1]]] Begin an auto‐incrementing numbered list. Item numbers start at one. The type argument assigns the register format (see above) of the list item enumerators. The default is 1. An explicitly empty type also indicates the default. A text‐indent argument overrides register Li. A third argument suppresses the blank line that normally precedes each list item. Use LI to declare list items, and LE to end the list. APP [id [title]] Begin an appendix. If the identifier id is omitted, it is in‐ cremented (or initialized, if necessary). The register format used for id is “A”. The page is broken. The register Aph de‐ termines whether an appendix heading is then formatted. This heading uses the string App followed by id. Appendices appear in any table of contents (see TC). The string Apptxt is set to title if the latter is present, and made empty otherwise. APPSK id n [title] As APP, but increment the page number by n. Use this macro to “skip pages” when diagrams or other materials not formatted by troff are included in appendices. AS [placement [indentation]] Abstract start; begin collecting abstract. Input up to the next AE call is included in the abstract. placement influences the location of the abstract on the cover sheet of a memorandum (see MT). COVER, by contrast, ignores placement by default, but can be customized to interpret it. placement Effect 0 The abstract appears on page 1 and cover sheet if the document is a “released paper” memorandum (“.MT 4”); otherwise, it appears on page 1 without a cover sheet. 1 The abstract appears only on the cover sheet (“.MT 4” only). An abstract does not appear at all in external letters (“.MT 5”). A placement of 2 was supported by DWB mm but is not by groff mm. A second argument increases the indentation by indentation and reduces the line length by twice this amount. A scaling unit of ens is assumed. The default is 0. AST [caption] Set the caption above the abstract to caption, or clear it if there is no argument. The default is “ABSTRACT”. AT title ... Specify author’s title(s). If present, AT must appear just af‐ ter the corresponding author’s AU. Each title occupies an out‐ put line beneath the author’s name in the signature block used by LT letters (see SG) and in MT memoranda. The ms cover sheet style also uses it. AU [name [initials [loc [dept [ext [room [arg1 [arg2 [arg3]]]]]]]]] Specify author. AU terminates a document title started with TL, and can be called without arguments for that purpose. Author information is used by cover sheets, MT memoranda, and SG. Fur‐ ther arguments comprise initials, location, department, tele‐ phone extension, room number or name, and up to three additional items. Repeat AU to identify multiple authors. Use WA/WE instead to identify the author for documents employing LT. AV [name [1]] Format approval lines for a handwritten signature and date. Two horizontal rules are drawn, with the specified name and the text of the string Letdate beneath them. Above these rules, the text in the string Letapp is formatted; a second argument replaces this text with a blank line. See LT. AVL [name] As AV, but the date, date rule, and approval notation Letapp are omitted. B [bold‐text [previous‐font‐text]] ... Join bold‐text in boldface with previous‐font‐text in the previ‐ ous font, without space between the arguments. If no arguments, switch font to bold style. B1 Begin boxed, kept display. The text is indented one character, and the right margin is one character shorter. This is a GNU extension. B2 End boxed, kept display. This is a GNU extension. BE End bottom block; see BS. BI [bold‐text [italic‐text]] ... Join bold‐text in boldface with italic‐text in italics, without space between the arguments. BL [text‐indent [1]] Begin bulleted list. Items are prefixed with a bullet and a space. A text‐indent argument overrides register Pi. A second argument suppresses blank lines between items. Use LI to de‐ clare list items, and LE to end the list. BR [bold‐text [roman‐text]] ... Join bold‐text in boldface with roman‐text in roman style, with‐ out space between the arguments. BS Begin bottom block. Input is collected until BE is called, and output between the footnote area and footer of each page. BVL [text‐indent [mark‐indent [1]]] Begin broken variable‐item (or “tagged”) list. Each item is ex‐ pected to supply its own mark. The line is always broken after the mark; contrast VL. text‐indent sets the indentation of the text, and mark‐indent the distance from the current list inden‐ tation to the mark. A third argument suppresses the blank line that normally precedes each list item. Use LI to declare list items, and LE to end the list. COVER [style] Begin a cover page description. COVER must appear before the body text (or main matter) of a document. The argument style is used to construct the file name /usr/local/share/groff/1.23.0/ tmac/mm/style.cov and load it with the mso request. The default style is ms; the ms.cov file prepares a cover page resembling those of the ms package. A .cov file must define a COVEND macro, which a document must call at the end of the cover de‐ scription. Use cover description macros in the following order; only TL and AU are required. .COVER .TL .AF .AU .AT .AS .AE .COVEND COVEND End the cover description. DE End static or floating display begun with DS or DF. DF [format [fill [right‐indentation]]] Begin floating display. A floating display is saved in a queue and output in the order entered. Arguments are handled as in DS. Floating displays cannot be nested. Placement of floating displays is controlled by the registers De and Df. DL [text‐indent [1]] Begin dashed list. Items are prefixed with an em dash and a space. A text‐indent argument overrides register Pi. A second argument suppresses blank lines between items. Use LI to de‐ clare list items, and LE to end the list. DS [format [fill [right‐indentation]]] Begin static display. Input until DE is called is collected into a display. The display is output on a single page unless it is taller than the height of the page. DS can be nested (contrast with DF). format Effect none Do not indent the display. L Do not indent the display. I Indent text by \n[Si]. C Center each line. CB Center the whole display as a block. R Right‐adjust the lines. RB Right‐adjust the whole display as a block. The values “L”, “I”, “C”, and “CB” can also be specified as “0”, “1”, “2”, and “3”, respectively, for compatibility with DWB mm. fill Effect none Disable filling. N Disable filling. F Enable filling. “N” and “F” can also be specified as “0” and “1”, respectively, for compatibility with DWB mm. A third argument reduces the line length by right‐indentation. mm normally places blank lines before and after the display. Set register Ds to 0 to suppress these. EC [title [override [flag [refname]]]] Caption an equation. The caption consists of the string Liec followed by an automatically incrementing counter stored in the register Ec, punctuation configured by the register Of, then ti‐ tle (if any). Use the af request to configure Ec’s number for‐ mat. override and flag alter the equation number as follows. Omitting flag and specifying 0 in its place are equivalent. flag Effect 0 Prefix number with override. 1 Suffix number with override. 2 Replace number with override. Equation captions are centered irrespective of the alignment of any enclosing display. refname stores the equation number using SETR; it can be re‐ treived with “.GETST refname”. This argument is a GNU exten‐ sion. Captioned equations are listed in a table of contents (see TC) if the Boolean register Le is true. Such a list uses the string Le as a heading. EF ["'left'center'right'"] Define the even‐page footer, which is formatted just above the normal page footer on even‐numbered pages. See PF. EF defines the string EOPef. EH ["'left'center'right'"] Define the even‐page header, which is formatted just below the normal page header on even‐numbered pages. See PH. EH defines the string TPeh. EN End equation input preprocessed by eqn(1); see EQ. EOP If defined, this macro is called in lieu of normal page footer layout. Headers and footers are formatted in a separate envi‐ ronment. See TP. Strings available to EOP ───────────────────────── EOPf argument to PF EOPef argument to EF EOPof argument to OF EPIC [-L] width height [name] Draw a box with the given width and height. It also prints the text name or a default string if name is not specified. This is used to include external pictures; just give the size of the picture. -L left‐aligns the picture; the default is to center. See PIC. EQ [label] Start equation input preprocessed by eqn(1). EQ and EN macro calls bracket an equation region. Such regions must be con‐ tained in displays (DS/DE), except when the region is used only to configure eqn and not to produce output. If present, label appears aligned to the right and centered vertically within the display; see register Eq. If multiple eqn regions occur within a display, only the last label (if any) is used. EX [title [override [flag [refname]]]] Caption an exhibit. Arguments are handled analogously to EC. The register Ex is the exhibit counter. The string Liex pre‐ cedes the exhibit number and any title. Exhibit captions are centered irrespective of the alignment of any enclosing display. Captioned exhibits are listed in a table of contents (see TC) if the Boolean register Lx is true. Such a list uses the string Lx as a heading. FC [closing‐text] Output the string Letfc, or the specified closing‐text, as the formal closing of a letter. FD [arg [1]] Configure display of footnotes. The first argument encodes en‐ ablement of automatic hyphenation, adjustment to the right mar‐ gin, indentation of footnote text, and left‐ vs. right‐alignment of the footnote label within the space allocated for it. arg Hyphenate? Adjust? Indent? Label alignment 0 no yes yes left 1 yes yes yes left 2 no no yes left 3 yes no yes left 4 no yes no left 5 yes yes no left 6 no no no left 7 yes no no left 8 no yes yes right 9 yes yes yes right 10 no no yes right 11 yes no yes right An arg greater than 11 is treated as 0. mm’s default is 0. If a second argument, conventionally 1, is given, footnote num‐ bering is reset when a first‐level heading is encountered. See FS. FE End footnote; see FS. FG [title [override [flag [refname]]]] Caption a figure. Arguments are handled analogously to EC. The register Fg is the figure counter. The string Lifg precedes the figure number and any title. Figure captions are centered irre‐ spective of the alignment of any enclosing display. Captioned figures are listed in a table of contents (see TC) if the Boolean register Lf is true. Such a list uses the string Lf as a heading. FS [label] Start footnote. Input until FE is called is collected into a footnote. By default, footnotes are automatically numbered starting at 1; the number is available in register :p and, with a trailing period, in string F. This string precedes the foot‐ note text at the bottom of the column or page. Footnotes are vertically separated by the product of registers Fs and Lsp. In groff mm, footnotes may be used in displays. A label argument replaces the contents of the string F; it need not be numeric. In this event, the footnote marker in the body text must be explicitly written. GETHN refname [varname] Include the heading number where the corresponding “.SETR ref‐ name” was placed. This is displayed as “X.X.X.” in pass 1. See INITR. If varname is used, GETHN sets the string varname to the heading number. GETPN refname [varname] Include the page number where the corresponding “.SETR refname” was placed. This is displayed as “9999” in pass 1. See INITR. If varname is used, GETPN sets the string varname to the page number. GETR refname Combine GETHN and GETPN with the text “chapter” and “, page”. The string Qrf contains the text for the cross reference: .ds Qrf See chapter \\*[Qrfh], page \\*[Qrfp]. Qrf may be changed to support other languages. Strings Qrfh and Qrfp are set by GETR and contain the page and heading number, respectively. GETST refname [varname] Include the string saved with the second argument to .SETR. This is a dummy string in pass 1. If varname is used, GETST sets it to the saved string. See INITR. H level [title [suffix]] Set a numbered section heading at level. mm produces numbered heading marks of the form a.b.c..., with up to fourteen levels of nesting. Each level’s number increases automatically with each H call and is reset to zero when a more significant level is specified. “1” is the most significant or coarsest division of the document. Text after an H call is formatted as a para‐ graph; calling P is unnecessary. title specifies an optional title; it must be double‐quoted if it contains spaces. mm appends suffix to title in the body of the document, but omits it from any table of contents (see TC). This facility can be used to annotate the heading title with a footnote. suffix should not interpolate the F string; specify a footnote mark explicitly. See FS. Heading behavior is highly configurable. Several registers set a threshold, where heading levels at or below the threshold value are handled in one way, and those above it another. For example, a heading level within the threshold of register Cl is included in the table of contents (see TC). Heading layout. Register Ej sets a threshold for page breaking (ejection) prior to a heading. If not preceded by a page break, a heading level below the threshold in register Hps is preceded by the amount of vertical space in register Hps1, and by the amount in Hps2 otherwise. The Hb register sets a threshold be‐ low which a break occurs after the heading, and register Hs sets a threshold below which vertical space follows it. If the head‐ ing level is not less than both of these, a run‐in heading is produced; paragraph text follows on the same output line. Oth‐ erwise, register Hi configures the indentation of text after headings. Threshold register Hc enables the centering of head‐ ings; a heading level below both of the Hb and Hc thresholds is centered. Heading typeface and size. The fonts used for heading numbers and titles at each level are configured by the HF string. The string HP likewise assigns a type size to each heading level. The vertical spacing used by headings may be controlled by the user‐definable macros HX and/or HZ. Heading number format. Registers named H1 through H14 store counters for each heading level. Their values are printed using Arabic numerals by default; see HM. The heading levels are catenated with dots for formatting; to typeset only the deepest, set the Ht register. Heading numbers are not suffixed with a trailing dot except when only the first level is output; to omit a dot in this case as well, clear the H1dot register. Customizing heading behavior. mm calls hook macros to enable further customization of headings. (DWB mm called these “ex‐ its”.) They can be used to change the heading’s mark (the num‐ bered portion before any heading title), its vertical spacing, and its vertical space requirements (for instance, to require a minimum quantity of subsequent output lines). Define hook macros in expectation of the following parameters. The argument declared‐level is the level argument to H, or 0 for unnumbered headings (see HU). actual‐level is the same as declared‐level for numbered headings, and the value of register Hu for unnum‐ bered headings. title is the corresponding argument to H or HU. HX declared‐level actual‐level title mm calls HX before setting the heading. Your definition may alter }0, }2, and ;3. }0 (string) contains the heading mark plus two spaces if de‐ clared‐level is non‐zero, and otherwise is empty. ;0 (register) encodes a position for the text after the heading. 0 means that the heading is to be run in, 1 means that a break is to occur before the text, and 2 means that vertical space is to separate heading and text. }2 (string) is the suffix that separates a run‐in heading from the text. It contains two spaces if register ;0 is 0, and otherwise is empty. ;3 (register) contains the vertical space required for the head‐ ing to be typeset. If that amount is not avail‐ able, the page is broken prior to the heading. The default is 2v. HY declared‐level actual‐level title mm calls HY after determing the heading typeface and size. It could be used to change indentation. HZ declared‐level actual‐level title mm calls HZ after formatting the heading, just before H or HU returns. It could be used to change the page header to include a section heading. HC [hyphenation‐character] Set hyphenation character. Default value is “\%”. Resets to the default if called without argument. Hyphenation can be turned off by setting register Hy to 0 at the beginning of the file. HM [arg1 [arg2 [... [arg14]]]] Set the heading mark style. Each argument assigns the specified register format (see above) to the corresponding heading level. The default is 1 for all levels. An explicitly empty argument also indicates the default. HU heading‐text Set an unnumbered section heading. Except for a heading number, it is treated as a numbered heading of the level stored in reg‐ ister Hu; see H. I [italic‐text [previous‐font‐text]] ... Join italic‐text in italics with previous‐font‐text in the pre‐ vious font, without space between the arguments. If no argu‐ ments, switch font to italic style. IA [recipient‐name [title]] Specify the inside address in a letter. Input is collected into the inside address until IE is called, and then output. You can specify multiple recipients with empty IA/IE pairs; only the last address is used. The arguments give each recipient a name and title. See LT. IB [italic‐text [bold‐text]] ... Join italic‐text in italics with bold‐text in boldface, without space between the arguments. IE End the inside address begun with IA. IND argument ... If the Boolean register Ref is true, write an index entry as a specially prepared roff comment to the standard error stream, with each argument separated from its predecessor by a tab char‐ acter. The entry’s location information is arranged as config‐ ured by the most recent INITI call. INDP Output the index set up by INITI and populated by IND calls. By default, INDP calls SK and writes a centered caption interpolat‐ ing the string Index. It then disables filling and calls 2C; afterward, it restores filling and calls 1C. Define macros to customize this behavior. INDP calls TXIND be‐ fore the caption, TYIND instead of writing the caption, and TZIND after formatting the index. INITI location‐type file‐name [macro] Initialize groff mm’s indexing system. Argument location‐type selects how the location of each index entry is reported. file‐ name populates an internal string used later by INDP. location‐type Entry format N page number H heading mark B page number, tab character, heading mark If macro is specified, it is called for each index entry with the arguments given to IND. INITR id Initialize the cross reference macros. Cross references are written to the standard error stream, which should be redirected into a file named id.qrf. mmroff(1) handles this and the two formatting passes it requires. The first pass identifies cross references, and the second one includes them. See SETR, GETPN, and GETHN. IR [italic‐text [roman‐text]] ... Join italic‐text in italics with roman‐text in roman style, without space between the arguments. ISODATE [0] Use ISO 8601 format for the date string DT used by some cover sheet and memorandum types; that is, YYYY‐MM‐DD. Must be called before ND to be effective. If given an argument of 0, the tra‐ ditional date format for the groff locale is used; this is also the default. LB text‐indent mark‐indent pad type [mark [pre‐item‐space [pre‐list‐ space]]] Begin list. The macros AL, BL, BVL, DL, ML, RL, and VL call LB in various ways; they are simpler to use and may be preferred if they suit the desired purpose. The nesting level of lists is tracked by mm; the outermost level is 0. The text of each list item is indented by text‐indent; the default is taken from the Li register (in ens). Each item’s mark is indented by mark‐indent; the default is 0n. The mark is normally left‐aligned. If pad is greater than zero, mark‐indent is overridden such that pad ens of space follow the mark. type selects one of six possible ways to display the mark. type Output for a mark “x” 1 x. 2 x) 3 (x) 4 [x] 5 6 {x} If type is 0 and mark is unspecified, the items are set with a hanging indent. Otherwise, mark is interpreted as a string defining the mark. If type is greater than zero, items are au‐ tomatically numbered; mark is interpreted as a register format. The default type is 0. The last two arguments manage vertical space. Unless a list’s nesting level is greater than the value of register Ls, its items are preceded by pre‐item‐space multiplied by the register Lsp; the default is 1. LB precedes the list by pre‐list‐space multiplied by the register Lsp; the default is 0. LC [list‐level] Clear list state. Active lists are terminated as if with LE, either all (the default) or only those from the current level down to list‐level if specified. H calls LC automatically. LE [1] End list. The current list is terminated. An argument of 1 causes vertical space in the amount of register Lsp to follow the list. LI [mark [item‐mark‐mode]] Begin a list item. Input is collected into a list item until the current list is terminated or LI is called again. By de‐ fault, the item’s text is preceded by any mark configured by the current list. If only mark is specified, it replaces the con‐ figured mark. A second argument prefixes mark to the configured mark; an item‐mark‐mode value of 1 places an unbreakable space after mark, while a value of 2 does not (rendering the two adja‐ cent). Also see register Limsp. LO option [value] Specify letter options; see LT. Standard options are as fol‐ lows. See IA regarding the inside address and string DT regard‐ ing the date. option Effect AT Attention; put contents of string LetAT and value left‐ aligned after the inside address. CN Confidential; put value, or contents of string LetCN, left‐aligned after the date. RN Reference; put contents of string LetRN and value after the confidental notation (if any) and the date, aligned with the latter. SA Salutation; put value, or contents of string LetSA, left‐aligned after the inside address and the confiden‐ tal notation (if any). SJ Subject; put contents of string LetSJ and value left‐ aligned after the inside address and the attention and salutation notations (if any). In letter type “SP”, LetSJ is ignored and value is set in full capitals. LT [style] Format a letter in the designated style, defaulting to BL (see below). A letter begins with the writer’s address (WA/WE), fol‐ lowed by the date (ND), the inside address (IA/IE), the body of the letter (P and other general‐purpose mm macros), the formal closing (FC), the signature (SG), and notations (NS/NE). Any of these may be omitted. Letter options specified with LO add fur‐ ther annotations, which are extensible; see section “Internals” below. style Description BL Blocked: the writer’s address, date, formal closing, and signature are indented to the center of the line. Everything else is left‐aligned. SB Semi‐blocked: as BL, but the first line of each para‐ graph is indented by 5m. FB Fully blocked: everything begins at the left margin. SP Simplified: as FB, but a formal closing is omitted, and the signature is set in full capitals. MC column‐width [gutter‐width] Begin multi‐column layout. groff mm creates as many columns of column‐width as the line length will permit. gutter‐width is the interior spacing between columns. It defaults to column‐ width/15. 1C returns to single‐column layout. MC is a GNU ex‐ tension. See MULB for an alternative. ML mark [text‐indent [1]] Start a list with the mark argument preceding each list item. text‐indent overrides the default indentation of the list items set by register Li. If a third argument, conventionally 1, is given, the blank line that normally precedes each list item is suppressed. Use LI to declare list items, and LE to end the list. MT [type [addressee]] Select memorandum type. These correspond to formats used by AT&T Bell Laboratories, where the mm package was initially de‐ veloped, affecting the document layout. Some of these included a cover page with a caption categorizing the document. groff mm uses type to construct the file name /usr/local/share/groff/ 1.23.0/tmac/mm/type.MT and load it with the mso request. Memo‐ randum types 0 to 5 are supported; any other value of type is mapped to type 6. If type is omitted, 0 is implied. addressee sets a string analogous to one used by AT&T cover sheet macros that are not implemented in groff mm. type Description 0 normal memorandum; no caption 1 captioned “MEMORANDUM FOR FILE” 2 captioned “PROGRAMMER’S NOTES” 3 captioned “ENGINEER’S NOTES” 4 released paper 5 external letter See COVER for a more flexible cover sheet mechanism. MOVE y‐pos [x‐pos [line‐length]] Move to a position, setting page offset to x‐pos. If line‐ length is not given, the difference between current and new page offset is used. Use PGFORM without arguments to return to nor‐ mal. MULB cw1 space1 [cw2 space2] ... cwn Begin alternative multi‐column mode. All column widths must be specified, as must the amount of space between each column pair. The arguments’ default scaling unit is n. MULB uses a diversion and operates in a separate environment. MULN Begin next column in alternative column mode. MULE End alternative multi‐column mode and emit the columns. NCOL Move to the start of the next column (only when using 2C or MC). Contrast with MULN. ND [arg] Set the document’s date. mm does not interpret arg; it can be a revision identifier (or empty). NE End notation begun with NS; filling is enabled. nP [type] Begin a numbered paragraph at heading level two. See P. NS [code [1]] Declare notations, typically for letters or memoranda, of the type specified by code. The text corresponding to code is out‐ put, and filling is disabled until NE is called. Typically, a list of names or attachments lies within NS/NE. If code is ab‐ sent or does not match one of the values listed under the Letns string description below, each line of notations is formatted as “Copy (line) to”. If a second argument, conventionally 1, is given, code becomes the entire notation and NE is not necessary. In groff mm, you can set up further notations to be recognized by NS; see the strings Letns and Letnsdef below. OF ["'left'center'right'"] Define the odd‐page footer, which is formatted just above the normal page footer on odd‐numbered pages. See PF. OF defines the string EOPof. OH ["'left'center'right'"] Define the odd‐page header, which is formatted just below the normal page header on odd‐numbered pages. See PH. OH defines the string TPoh. OP Make sure that the following text is printed at the top of an odd‐numbered page. Does not output an empty page if currently at the top of an odd page. P [type] Begin new paragraph. If type is missing or 0, P sets the para‐ graph fully left-aligned. A type of 1 idents the first line by \[Pi] ens. Set the register Pt to select a default paragraph indentation style. The register Ps controls the vertical spac‐ ing between paragraphs. PE Picture end; see pic(1). PF ["'left'center'right'"] Define the page footer. The footer is formatted at the bottom of each page; the argument is otherwise as described in PH. PF defines the string EOPf. See EF, OF, and EOP. PGFORM [linelength [pagelength [pageoffset [1]]]] Set line length, page length, and/or page offset. This macro can be used for letterheads and similar. It is normally the first macro call in a file, though it is not necessary. PGFORM can be used without arguments to reset everything after a MOVE call. A line break is done unless the fourth argument is given. This can be used to avoid the page number on the first page while setting new width and length. (It seems as if this macro sometimes doesn’t work too well. Use the command‐line arguments to change line length, page length, and page offset instead.) PGNH Suppress header on the next page. This macro must be called be‐ fore any macros that produce output to affect the layout of the first page. PH ["'left'center'right'"] Define the page header, formatted at the top of each page, as the argument, where left, center, and right are aligned to the respective locations on the line. A “%” character in arg is re‐ placed by the page number. If the argument is absent, no page header is set. The default page header is "''- % -''" which centers the page number between hyphens and formats noth‐ ing at the upper left and right. Header macros call PX (if de‐ fined) after formatting the header. PH defines the string TPh. See EH, OH, and TP. PIC [-B] [-C|-I n|-L|-R] file [width [height]] Include PostScript document file. The optional -B argument draws a box around the picture. The optional -L, -C, -R, and -I n arguments align the picture or indent it by n (assuming a scaling unit of m). By default, the picture is left‐aligned. Optional width and height arguments resize the picture. Use of this macro requires two‐pass processing; see INITR and mmroff(1). PS Picture start; see pic(1). PY Picture end with flyback. Ends a pic(1) picture, returning the vertical position to where it was prior to the picture. This is a GNU extension. R [roman‐text [previous‐font‐text]] ... Join roman‐text in roman style with previous‐font‐text in the previous font, without space between the arguments. If no argu‐ ments, switch font to roman style. RB [roman‐text [bold‐text]] ... Join roman‐text in roman style with bold‐text in boldface, with‐ out space between the arguments. RD [prompt [diversion [string]]] Read from standard input to diversion and/or string. The text is saved in a diversion named diversion. Recall the text by writing the name of the diversion after a dot on an empty line. A string is also defined if string is given. Diversion and/or prompt can be empty (""). RF Reference end. Ends a reference definition and returns to nor‐ mal processing. See RS. RI [roman‐text [italic‐text]] ... Join roman‐text in roman style with italic‐text in italics, without space between the arguments. RL [text‐indent [1]] Begin reference list. Each item is preceded by an automatically incremented number between square brackets; compare AL. text‐ indent changes the default indentation. Use LI to declare list items, and LE to end the list. A second argument, convention‐ ally 1, suppresses the blank line that normally precedes each list item. RP [suppress‐counter‐reset [page‐ejection‐policy]] Format a reference page, listing items accumulated within RS/RF pairs. The reference counter is reset unless the first argument is 1. Normally, page breaks occur before and after the refer‐ ences are output; the register Rpe configures this behavior, and a second argument overrides its value. TC calls RP automati‐ cally if references have accumulated. References are list items, and thus are vertically separated (see LB). Setting register Ls to 0 suppresses this spacing. The string Rp contains the reference page caption. RS [reference‐string] Begin an automatically numbered reference definition. By de‐ fault, references are numbered starting at 1; the number is available in register :R. Interpolate the string Rf where the reference mark should be and write the reference between RS/RF on an input line after the reference mark. If reference‐string is specified, groff ms also stores the reference mark in a string of that name, which can be interpolated as \*[reference‐ string] subsequently. S [type‐size [vertical‐spacing]] Set type size and vertical spacing. Each argument is a groff measurement, using an appropriate scaling unit and an optional + or - prefix to increment or decrement the current value. An ar‐ gument of P restores the previous value, C indicates the current value, and D requests the default. An empty or omitted argument is treated as P. SA [mode] Set or restore the default enablement of adjustment. Specify 0 or 1 as mode to set a document’s default explicitly; 1 is as‐ sumed by mm. Adjustment can be temporarily suspended with the na request. When the H or HU macros are used to format a head‐ ing, or when SA is called without a mode argument, the default adjustment is restored. SETR refname [string] Remember the current heading and page numbers as refname. Saves string if string is defined. string is retrieved with GETST. See INITR. SG [arg [1]] Signature line. Prints the authors name(s) after the formal closing. The argument is appended to the reference data, printed at either the first or last author. The reference data is the location, department, and initials specified with AU. It is printed at the first author if the second argument is given, otherwise at the last. No reference data is printed if the au‐ thor(s) is specified through WA/WE. See section “Internals” be‐ low. SK [n] Skip n pages. If n is 0 or omitted, the page is broken unless the drawing position is already at the top of a page. Other‐ wise, n pages, blank except for any headers and footers, are printed. SM text [post] SM pre text post Format text at a smaller type size, joined with any specified pre and post at normal size. SP [lines] Space vertically. lines can have any scaling factor, like “3i” or “8v”. Several SP calls in a line only produces the maximum number of lines, not the sum. SP is ignored also until the first text line in a page. Add \& before a call to SP to avoid this. TAB Reset tab stops to every 5 ens. TB [title [override [flag [refname]]]] Caption a table. Arguments are handled analogously to EC. The register Tb is the table counter. The string Litb precedes the table number and any title. Table captions are centered irre‐ spective of the alignment of any enclosing display. Captioned tables are listed in a table of contents (see TC) if the Boolean register Lt is true. Such a list uses the string Lt as a heading. TC [slevel [spacing [tlevel [tab [h1 [h2 [h3 [h4 [h5]]]]]]]]] Output table of contents. This macro is normally the last called in the document. It flushes any pending displays and, if any references are pending (see RS), calls RP. It then begins a new page with the contents caption, stored in the string Licon, centered at the top. The entries follow after three vees of space. Each entry is a saved section (number and) heading title (see the Cl register), along with its associated page number. By default, an entry is indented by an amount corresponding to its heading level and the maximum heading length encountered at that heading level; if defined, the string Ci overrides these indentations. Entries at heading levels up to and including slevel are preceded by spacing vees of space. Entries at head‐ ing levels up to and including tlevel are followed by a leader and a right‐aligned page number. If the Boolean‐valued tab ar‐ gument is true, the leader is replaced with horizontal motion in the same amount. For entries above heading level tlevel, the page number follows the heading text after a word space. Each argument h1...h5 appears in order on its own line, centered, above the contents caption. Page numbering restarts at 1, in register format “i”. If the Oc register is true, numbering of these pages is suppressed. If TC is called with at most four arguments, it calls the user‐ defined macro TX (if defined) prior to formatting the contents caption, and TY (if defined) instead of formatting the contents caption. Analogous handling of lists of figures, tables, equations, and exhibits is achieved by defining TXxx and TYxx macros, where xx is “FG”, “TB”, “EC”, or “EX”, respectively. Similarly, the strings Lifg, Litb, Liex, and Liec determine captions for their respective lists. TE Table end. See TS. TH End table heading. It is repeated after page breaks within a table. See TS. The N argument supported by DWB mm is not im‐ plemented by groff mm. TL [charging‐case‐number [filing‐case‐number]] Begin document title. Input is collected into the title until AF or AU is called, and output as directed by the cover page. charging‐case‐number and filing‐case‐number are saved for use in memorandum types 0 and 5. See MT. TM number ... Declare technical memorandum number(s) used by MT. TP If defined, this macro is called in lieu of normal page header layout. Headers and footers are formatted in a separate envi‐ ronment. See EOP. Strings available to TP ──────────────────────── TPh argument to PH TPeh argument to EH TPoh argument to OH TS [H] Table start. Argument “H” tells mm that the table has a head‐ ing. See TE, TH, and tbl(1). VERBON [format [type‐size [font]]] Begin verbatim display, where characters have equal width. for‐ mat controls several parameters. Add up the values of desired features; the default is 0. On typesetting devices, further ar‐ guments configure the type‐size in scaled points, and the face (font); the default is CR (Courier roman). Value Effect 1 Disable the formatter’s escape character (\). 2 Vertically space before the display. 4 Vertically space after the display. 8 Number output lines; call formatter’s nm request with arguments in string Verbnm. 16 Indent by the amount stored in register Verbin. VERBOFF End verbatim display. VL [text‐indent [mark‐indent [1]]] Begin variable‐item (or “tagged”) list. Each item should supply its own mark, or tag. If the mark is wider than mark‐indent, one space separates it from subsequent text; contrast BVL. text‐indent sets the indentation of the text, and mark‐indent the distance from the current list indentation to the mark. A third argument suppresses the blank line that normally precedes each list item. Use LI to declare list items, and LE to end the list. VM [-T] [top [bottom]] Vertical margin. Increase the top and bottom margin by top and bottom, respectively. If option -T is specified, set those mar‐ gins to top and bottom. If no argument is given, reset the mar‐ gin to zero, or to the default (“7v 5v”) if -T is used. It is highly recommended that macros TP and/or EOP are defined if us‐ ing -T and setting top and/or bottom margin to less than the de‐ fault. This undocumented DWB mm macro is exposed by groff mm to increase user control of page layout. WA [writer’s‐name [title]] Specify the writer(s) of an LT letter. Input is collected into the writer’s address until WA is called, and then output. You can specify multiple writers with empty WA/WE pairs; only the last address is used. The arguments give each writer a name and title. WC [format ...] Control width of footnotes and displays. format Effect N equivalent to “-WF -FF -WD” (default) WF set footnotes at full line length, even in two‐column mode -WF set footnotes using column line length FF apply width of first footnote to encountered to subse‐ quent ones -FF footnote width determined by WF and -WF WD set displays at full line length, even in two‐column mode -WD set displays using column line length WE End the writer’s address begun with WA. Strings Many mm strings interpolate predefined, localizable text. These are presented in quotation marks. App “APPENDIX” Apptxt stores the title argument to the last APP call. BU interpolates a bullet (see BL). Ci is a list of indentation amounts to use for table of contents heading levels, overriding their automatic computation. Each word must be a horizontal measurement (like “1i”) and is mapped one‐to‐one to heading levels 1, 2, and so on. DT The date; set by the ND macro (defaults to the date the document is formatted). The format is the conventional one for the groff locale, but see the ISODATE macro and Iso register. EM interpolates an em dash. F interpolates an automatically numbered footnote marker; the num‐ ber is used by the next FS call without an argument. In troff mode, the marker is superscripted; in nroff mode, it is sur‐ rounded by square brackets. H1txt Updated by .H and .HU to the current heading text. Also updated in table of contents & friends. HF assigns font identifiers, separated by spaces, to heading levels in one‐to‐one correspondence. Each identifier may be a font mounting position, font name, or style name. Omitted values are assumed to be 1. The default is “2 2 2 2 2 2 2 2 2 2 2 2 2 2”, which places all headings in italics. DWB mm’s default was “3 3 2 2 2 2 2”. HP assigns type sizes, separated by spaces, to heading levels in one‐to‐one correspondence. Each size is interpreted in scaled points; zero values are translated to 10. Omitted values are assumed to be 0 (and are translated accordingly). The default is “0 0 0 0 0 0 0 0 0 0 0 0 0 0”. Index “INDEX” Le “LIST OF EQUATIONS” Letfc “Yours very truly,” (see FC) Letapp “APPROVED:” (see AV) LetAT “ATTENTION:” (see LO) LetCN “CONFIDENTIAL” (see LO) Letdate “Date” (see AV) Letns is a group of strings structuring the notations produced by NS. If the code argument to NS has no corresponding string, the no‐ tation is included between parentheses, prefixed with Letns!copy, and suffixed with Letns!to. Observe the spaces af‐ ter “Copy” and before “to”. NS code String Contents 0 Letns!0 Copy to 1 Letns!1 Copy (with att.) to 2 Letns!2 Copy (without att.) to 3 Letns!3 Att. 4 Letns!4 Atts. 5 Letns!5 Enc. 6 Letns!6 Encs. 7 Letns!7 Under separate cover 8 Letns!8 Letter to 9 Letns!9 Memorandum to 10 Letns!10 Copy (with atts.) to 11 Letns!11 Copy (without atts.) to 12 Letns!12 Abstract Only to 13 Letns!13 Complete Memorandum to 14 Letns!14 CC — Letns!copy Copy (with trailing space) — Letns!to to (note leading space) Letnsdef Select the notation format used by NS when it is given no argu‐ ment. The default is “0”. LetRN “In reference to:” (see LO) LetSA “To Whom It May Concern:” (see LO) LetSJ “SUBJECT:” (see LO) Lf “LIST OF FIGURES” Licon “CONTENTS” Liec “Equation” Liex “Exhibit” Lifg “Figure” Litb “TABLE” Lt “LIST OF TABLES” Lx “LIST OF EXHIBITS” MO1...MO12 “January” through “December” Qrf “See chapter \\*[Qrfh], page \\n[Qrfp].” Rf interpolates an automatically numbered reference mark; the num‐ ber is used by the next RS call. In troff mode, the marker is superscripted; in nroff mode, it is surrounded by square brack‐ ets. Rp “REFERENCES” Sm interpolates ℠, the service mark sign. Tcst interpolates an indicator of the TC macro’s processing status. If TC is not operating, it is empty. User‐defined TP or EOP macros might condition page headers or footers on its contents. Value Meaning co Table of contents fg List of figures tb List of tables ec List of equations ex List of exhibits ap Appendix Tm interpolates ™, the trade mark sign. Verbnm supplies argument(s) to the nm request employed by the VERBON macro. The default is “1”. Registers Default register values, where meaningful, are shown in parentheses. Many are also marked as Boolean‐valued, meaning that they are consid‐ ered “true” (on, enabled) when they have a positive value, and “false” (off, disabled) otherwise. .mgm indicates that groff mm is in use (Boolean‐valued; 1). :p is an auto‐incrementing footnote counter; see FS. :R is an auto‐incrementing reference counter; see RS. Aph formats an appendix heading (and title, if supplied); see APP (Boolean‐valued; 1). Au includes supplemental author information (the third and subse‐ quent arguments to AU) in memorandum “from” information; see COVER and MT (Boolean‐valued; 1). Cl sets the threshold for inclusion of headings in a table of con‐ tents. Headings at levels above this value are excluded; see H and TC (2). The Cl register controls whether a heading is saved for output in the table of contents at the time H or HU is called; if you change Cl’s value immediately prior to calling TC, you are unlikely to get the result you want. Cp suppresses page breaks before lists of captioned equations, ex‐ hibits, figures, and tables, and before an index; see EC, EX, FG, TB, and INDP (Boolean‐valued; 0). D produces debugging information for the mm package on the stan‐ dard error stream. A value of 0 outputs nothing; 1 reports for‐ matting progress. Higher values communicate internal state in‐ formation of increasing verbosity (0). De causes a page break after a floating display is output; see DF (Boolean‐valued; 0). Df configures the behavior of DF. The following values are recog‐ nized; 4 and 5 do not override the De register (5). Value Effect 0 Flush pending displays at the end of each section when section‐page numbering is active, otherwise at the end of the document. 1 Flush a pending display on the current page or column if there is enough space, otherwise at the end of the docu‐ ment. 2 Flush one pending display at the top of each page or column. 3 Flush a pending display on the current page or column if there is enough space, otherwise at the top of the next. 4 Flush as many pending displays as possible in a new page or column. 5 Fill columns or pages with flushed displays until none remain. Ds puts vertical space in the amount of register Dsp (if defined) or Lsp before and after each static display; see DS (Boolean‐ valued; 1). Dsp configures the amount of vertical space placed before and after static displays; see DS and register Ds (undefined). Ec is an auto‐incrementing equation counter; see EC. Ej sets the threshold for page breaks (ejection) prior to the for‐ mat of headings. Headings at levels above this value are set on the same page and column if possible; see H (0). Eq aligns an equation label to the left of a display instead of the right (Boolean‐valued; 0). Ex is an auto‐incrementing exhibit counter; see EX. Fg is an auto‐incrementing figure counter; see FG. Fs is multiplied by register Lsp to vertically separate footnotes; see FS (1). H1...H14 are auto‐incrementing counters corresponding to each heading level; see H. H1dot appends a period to the number of a level one heading; see H (Boolean‐valued; 1). H1h is a copy of A copy of register register H1, but it is incre‐ mented just before a page break. This can be useful in user‐de‐ fined macros; see H and HX. Hb sets the threshold for breaking the line after formatting a heading. Text after headings at levels above this value are set on the same output line if possible; see H (2). Hc sets the threshold for centering a heading. Headings at levels above this value use the prevailing alignment (that is, they are not centered); see H (0). Hi configures the indentation of text after headings. It does not affect “run‐in” headings. The following values are recognized; see H and P (1). Value Effect 0 no indentation 1 indent per the paragraph type 2 indent to align with heading title Hps sets the heading level threshold for application of preceding vertical space; see H. Headings at levels above the value in register Hps use the amount of space in register Hps1; otherwise that in Hps2. The value of Hps should be strictly greater than that of Ej (1). Hps1 configures the amount of vertical space preceding a heading above the Hps threshold; see H (troff devices: 0.5v; nroff de‐ vices: 1v). Hps2 configures the amount of vertical space preceding a heading at or below the Hps threshold; see H (troff devices: 1v; nroff de‐ vices: 2v). Hs sets the heading level threshold for application of succeeding vertical space. If the heading level is greater than Hs, the heading is followed by vertical space in the amount of regis‐ ter Hss; see H (2). Hss is multiplied by register Lsp to produce vertical space after headings above the threshold in register Hs; see H (1). Ht suppresses output of heading level counters above the lowest when the heading is formatted; see H (Boolean‐valued; 0). Hu sets the heading level used by unnumbered headings; see HU (2). Hy enables automatic hyphenation of words (Boolean‐valued; 0). Iso configures the use of ISO 8601 date format if specified (with any value) on the command line; see ISODATE. The default is de‐ termined by localization files. L defines the page length for the document, and must be set from the command line. A scaling unit should be appended. The de‐ fault is that of the selected groff output device. Le Lf Lt Lx configure the report of lists of equation, figure, table, and exhibit captions, respectively, after a table of contents; see TC (Boolean‐valued; Le: 0; Lf, Lt, Lx: 1). Letwam sets the maximum number of input lines permitted in a writer’s address; see WA and WE (14). Li configures the amount of indentation in ens applied to list items; see LI (6). Limsp inserts a space between the prefix and the mark in automatically numbered lists; see AL (Boolean‐valued; 1). Ls sets a threshold for placement of vertical space before list items. If the list nesting level is greater than this value, no such spacing occurs; see LI (99). Lsp configures the base amount of vertical space used for separation in the document. mm applies this spacing to many contexts, sometimes with multipliers; see DS, FS, H, LI, and P (troff de‐ vices: 0.5v; nroff devices: 1v). N configures the header and footer placements used by PH. The de‐ fault footer is empty. If “section‐page” numbering is selected, the default header becomes empty and the default footer becomes “x‐y”, where x is is the section number (the number of the cur‐ rent first‐level heading) and y the page number within the sec‐ tion. The following values are recognized; for finer control, see PH, PF, EH, EF, OH, and OF, and registers Sectf and Sectp. Value 5 is a GNU extension (0). Value Effect 0 Set header on all pages. 1 Move header to footer on page 1. 2 Omit header on page 1. 3 Use “section‐page” numbering style on all pages. 4 Omit header on all pages. 5 Use “section‐page” and “section‐figure” numbering style on all pages. Np causes paragraphs after first‐level headings (only) to be num‐ bered in the format s.p, where s is is the section number (the number of the current first‐level heading) and p is the para‐ graph number, starting at 1; see H and P (Boolean‐valued; 0). O defines the page offset of the document, and must be set from the command line. A scaling unit should be appended. The de‐ fault is .75i on terminal devices. On typesetters, it is .963i or set to 1i by the papersize.tmac package; see groff_tmac(5). Oc suppresses the appearance of page numbers in the table of con‐ tents; see TC (Boolean‐valued; 0). Of selects a separator format within equation, exhibit, figure, and table captions; see EC, EX, FG, and TB. The following values are recognized; the spaces shown are unpaddable (0). Value Effect 0 ". " 1 " — " P interpolates the current page number; it is the same as regis‐ ter % except when “section‐page” numbering is enabled. Pi configures the amount of indentation in ens applied to the first line of a paragraph; see P (5). Pgps causes the type size and vertical spacing set by S to apply to headers and footers, overriding the HP string. If not set, S calls affect headers and footers only when followed by PH, PF, OH, EH, OF, or OE calls (Boolean‐valued; 1). Ps is multiplied by register Lsp to vertically separate paragraphs; see P (1). Pt determines when a first‐line indentation is applied to a para‐ graph; see P (0). Value Effect 0 never 1 always 2 always, except immediately after H, DE, or LE Ref is used internally to control mmroff(1)’s two‐pass approach to index and reference management; see INITI and RS (Boolean‐val‐ ued; 0). Rpe configures the default page ejection policy for reference pages; see RP (0). Value Effect 0 Break the page before and after the list of references. 1 Suppress page break after the list. 2 Suppress page break before the list. 3 Suppress page breaks before and after the list. S defines the type size for the document, and must be set from the command line. A scaling unit should be appended; p is typical (10p). Sectf selects the “section‐figure” numbering style. Its default is 0 unless register N is set to 5 at the command line (Boolean‐val‐ ued). Sectp selects the “section‐page” numbering style. Its default is 0 unless register N is set to 3 or 5 at the command line (Boolean‐ valued). Si configures the amount of display indentation in ens; see DS (5). Tb is an auto‐incrementing table counter; see TB. V defines the vertical spacing for the document, and must be set from the command line. A scaling unit should be appended; p is typical. The default vertical spacing is 120% of the type size. Verbin configures the amount of indentation for verbatim displays when indentation is selected; see VERBON (5n). W defines the “width” of the document (that is, the length of an output line with no indentation); it must be set from the com‐ mand line. A scaling unit should be appended. The default is 6i or assigned by the papersize.tmac package; see groff_tmac(5). Internals The LT letter macros call further macros depending on the letter type, with which they are suffixed. It is therefore possible to define addi‐ tional letter types, either in the territory‐specific macro file, or as local additions. LT sets the registers Pt and Pi to 0 and 5, respec‐ tively. The following macros must be defined to support a new letter type. let@init_type LT calls this macro to initialize any registers and other data needed by the letter type. let@head_type formats the letterhead; it is called instead of the usual page header macro. Its definition should remove the alias let@header unless the letterhead is desired on subsequent pages. let@sg_type name title n is‐final [SG‐arg ...] SG calls this macro only for letters; MT memoranda have their own signature processing. name and title are specified through WA/WE. n is the index of the nth writer, and is‐final is true for the last writer to be listed. Further SG arguments are ap‐ pended to the signature line. let@fc_type closing This macro is called by FC, and has the formal closing as the argument. LO implements letter options. It requires that a string named Lettype be defined, where type is the letter type. LO then assigns its second argument (value) to the string let*lo-type. Files /usr/local/share/groff/1.23.0/tmac/m.tmac is the groff implementation of the memorandum macros. /usr/local/share/groff/1.23.0/tmac/mm.tmac is wrapper to load m.tmac. /usr/local/share/groff/1.23.0/tmac/refer-mm.tmac implements refer(1) support for mm. /usr/local/share/groff/1.23.0/tmac/mm/ms.cov implements an ms‐like cover sheet. /usr/local/share/groff/1.23.0/tmac/mm/0.MT implements memorandum types 0–3 and 6. /usr/local/share/groff/1.23.0/tmac/mm/4.MT implements memorandum type 4. /usr/local/share/groff/1.23.0/tmac/mm/5.MT implements memorandum type 5. /usr/local/share/groff/1.23.0/tmac/mm/locale performs any (further) desired necessary localization; empty by default. Authors The GNU version of the mm macro package was written by Jörgen Hägg ⟨jh@ axis.se⟩ of Lund, Sweden. See also MM - A Macro Package for Generating Documents ⟨https://tkurtbond.github .io/troff/mm-all.pdf⟩, the DWB 3.3 mm manual, introduces the package but does not document GNU extensions. Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1), groff_mmse(7) groff 1.23.0 29 August 2023 groff_mm(7) ─────────────────────────────────────────────────────────────────────────────── groff_mmse(7) Handbok för diverse information groff_mmse(7) Namn groff_mmse - svenska ”memorandum” makro för GNU roff Syntax groff -mmse [flaggor ...] [filer ...] groff -m mmse [flaggor ...] [filer ...] Beskrivning mmse är en svensk variant av mm. Alla texter är översatta. En A4 sida får text som är 13 cm bred, 3,5 cm indragning samt är 28,5 cm hög. Det finns stöd för brevuppställning enligt svensk standard för vänster och högerjusterad text. COVER kan använda se_ms som argument. Detta ger ett svenskt försätts‐ blad. Se groff_mm(7) för övriga detaljer. Brev Tillgängliga brevtyper: .LT SVV Vänsterställd löptext med adressat i position T0 (vänster‐ ställt). .LT SVH Högerställd löptext med adressat i position T4 (passar fönster‐ kuvert). Följande extra LO‐variabler används. .LO DNAMN namn Anger dokumentets namn. .LO MDAT datum Mottagarens datum, anges under Ert datum: (LetMDAT). .LO BIL sträng Anger bilaga, nummer eller sträng med Bilaga (LetBIL) som pre‐ fix. .LO KOMP text Anger kompletteringsuppgift. .LO DBET beteckning Anger dokumentbeteckning eller dokumentnummer. .LO BET beteckning Anger beteckning (ärendebeteckning i form av diarienummer eller liknande). .LO SIDOR antal Anger totala antalet sidor och skrivs ut efter sidnumret inom parenteser. Om makrot .TP är definierat anropas det efter utskrift av brevhuvudet. Där lägger man lämpligen in postadress och annat som brevfot. Skrivet av Jörgen Hägg, Lund, Sweden Filer /usr/local/share/groff/1.23.0/tmac/mse.tmac /usr/local/share/groff/1.23.0/tmac/mm/se_*.cov Se också groff_mm(7) groff 1.23.0 29 August 2023 groff_mmse(7) ─────────────────────────────────────────────────────────────────────────────── groff_mom(7) Miscellaneous Information Manual groff_mom(7) Name groff_mom - modern macros for document composition with GNU roff Synopsis groff -mom [option ...] [file ...] groff -m mom [option ...] [file ...] Description mom is a macro set for groff, designed primarily to prepare documents for PDF and PostScript output. mom provides macros in two categories: typesetting and document processing. The former provide access to groff’s typesetting capabilities in ways that are simpler to master than groff’s requests and escape sequences. The latter provide highly customizable markup tags that allow the user to design and output pro‐ fessional‐looking documents with a minimum of typesetting intervention. Files processed with pdfmom(1) produce PDF documents. The documents include a PDF outline that appears in the navigation pane panel of doc‐ ument viewers, and may contain clickable internal and external links. Normally. groff’s native PDF driver, gropdf(1), is used to generate the output. When pdfmom is given the “-T ps” option, it still produces PDF, but processing is delegated to pdfroff, which uses groff’s Post‐ Script driver, grops(1). Not all PDF features are available when -T ps is given; its primary use is to allow processing of files with embedded PostScript images. Files processed with groff -mom (or -m mom) format for the device spec‐ ified with the -T option. (In this installation, ps is the default output device.) mom comes with her own comprehensive documentation in HTML. A PDF man‐ ual, “Producing PDFs with groff and mom”, discusses preparation of PDF documents with mom in detail. Files /usr/local/share/groff/1.23.0/tmac/mom.tmac is a wrapper enabling the package to be loaded with “groff -m mom”. /usr/local/share/groff/1.23.0/tmac/om.tmac implements the package. /usr/local/share/doc/groff-1.23.0/html/mom/toc.html is the entry point to the HTML documentation. /usr/local/share/doc/groff-1.23.0/pdf/mom-pdf.pdf is “Producing PDFs with groff and mom”, by Deri James and Peter Schaffter. /usr/local/share/doc/groff-1.23.0/examples/mom/*.mom are examples of mom usage. Reference Escape sequences \*[] begin using an initialized colour inline \*[BCK n] move backward in a line \*[BOLDER] invoke pseudo bold inline (related to macro .SETBOLDER) \*[BOLDERX] off pseudo bold inline (related to macro .SETBOLDER) \*[BU n] move characters pairs closer together inline (related to macro .KERN) \*[COND] invoke pseudo condensing inline (related to macro .CONDENSE) \*[CONDX] off pseudo condensing inline (related to macro .CONDENSE) \*[CONDSUP]...\*[CONDSUPX] pseudo‐condensed superscript \*[DOWN n] temporarily move downward in a line \*[EN-MARK] mark initial line of a range of line numbers (for use with line numbered endnotes) \*[EXT] invoke pseudo extending inline (related to macro .EXTEND) \*[EXTX] off pseudo condensing inline (related to macro .EXTEND) \*[EXTSUP]...\*[EXTSUPX] pseudo extended superscript \*[FU n] move characters pairs further apart inline (related to macro .KERN) \*[FWD n] move forward in a line \*[LEADER] insert leaders at the end of a line \*[RULE] draw a full measure rule \*[SIZE n] change the point size inline (related to macro .PT_SIZE) \*[SLANT] invoke pseudo italic inline (related to macro .SETSLANT) \*[SLANTX] off pseudo italic inline (related to macro .SETSLANT) \*[ST]...\*[STX] string tabs (mark tab positions inline) \*[SUP]...\*[SUPX] superscript \*[TB+] inline escape for .TN (Tab Next) \*[UL]...\*[ULX] invoke underlining inline (fixed width fonts only) \*[UP n] temporarily move upward in a line Macros .AUTOLEAD set the linespacing relative to the point size .B_MARGIN set a bottom margin .BR break a justified line .CENTER set line‐by‐line quad centre .CONDENSE set the amount to pseudo condense .EL break a line without advancing on the page .EXTEND set the amount to pseudo extend .FALLBACK_FONT establish a fallback font (for missing fonts) .FAM alias to .FAMILY .FAMILY  set the family type .FT set the font style (roman, italic, etc.) .HI [  ] hanging indent .HY automatic hyphenation on/off .HY_SET set automatic hyphenation parameters .IB [   ] indent both .IBX [ CLEAR ] exit indent both .IL [  ] indent left .ILX [ CLEAR ] exit indent left .IQ [ CLEAR ] quit any/all indents .IR [  ] indent right .IRX [ CLEAR ] exit indent right .JUSTIFY justify text to both margins .KERN automatic character pair kerning on/off .L_MARGIN set a left margin (page offset) .LEFT set line‐by‐line quad left .LL set a line length .LS set a linespacing (leading) .PAGE set explicit page dimensions and margins .PAGEWIDTH set a custom page width .PAGELENGTH set a custom page length .PAPER  set common paper sizes (letter, A4, etc) .PT_SIZE set the point size .QUAD "justify" text left, centre, or right .R_MARGIN set a right margin .RIGHT set line‐by‐line quad right .SETBOLDER set the amount of emboldening .SETSLANT set the degree of slant .SPREAD force justify a line .SS set the sentence space size .T_MARGIN set a top margin .TI [  ] temporary left indent .WS set the minimum word space size Documentation of details Details of inline escape sequences in alphabetical order \*[] begin using an initialized colour inline \*[BCK n] move backward in a line \*[BOLDER] \*[BOLDERX] Emboldening on/off \*[BOLDER] begins emboldening type. \*[BOLDERX] turns the fea‐ ture off. Both are inline escape sequences; therefore, they should not appear as separate lines, but rather be embedded in text lines, like this: Not \*[BOLDER]everything\*[BOLDERX] is as it seems. Alternatively, if you wanted the whole line emboldened, you should do \*[BOLDER]Not everything is as it seems.\*[BOLDERX] Once \*[BOLDER] is invoked, it remains in effect until turned off. Note: If you’re using the document processing macros with .PRINTSTYLE TYPEWRITE, mom ignores \*[BOLDER] requests. \*[BU n] move characters pairs closer together inline (related to macro .KERN) \*[COND] \*[CONDX] Pseudo‐condensing on/off \*[COND] begins pseudo‐condensing type. \*[CONDX] turns the feature off. Both are inline escape sequences; therefore, they should not appear as separate lines, but rather be embedded in text lines, like this: \*[COND]Not everything is as it seems.\*[CONDX] \*[COND] remains in effect until you turn it off with \*[CONDX]. IMPORTANT: You must turn \*[COND] off before making any changes to the point size of your type, either via the .PT_SIZE macro or with the \s inline escape sequence. If you wish the new point size to be pseudo‐condensed, simply reinvoke \*[COND] afterward. Equally, \*[COND] must be turned off before changing the con‐ dense percentage with .CONDENSE. Note: If you’re using the document processing macros with .PRINTSTYLE TYPEWRITE, mom ignores \*[COND] requests. \*[CONDSUP]...\*[CONDSUPX] pseudo‐condensed superscript \*[DOWN n] temporarily move downward in a line \*[EN-MARK] mark initial line of a range of line numbers (for use with line numbered endnotes) \*[EXT] \*[EXTX] Pseudo‐extending on/off \*[EXT] begins pseudo‐extending type. \*[EXTX] turns the fea‐ ture off. Both are inline escape sequences; therefore, they should not appear as separate lines, but rather be embedded in text lines, like this: \*[EXT]Not everything is as it seems.\*[EXTX] \*[EXT] remains in effect until you turn it off with \*[EXTX]. IMPORTANT: You must turn \*[EXT] off before making any changes to the point size of your type, either via the .PT_SIZE macro or with the \s inline escape sequence. If you wish the new point size to be pseudo‐extended, simply reinvoke \*[EXT] afterward. Equally, \*[EXT] must be turned off before changing the extend percentage with .EXTEND. Note: If you are using the document processing macros with .PRINTSTYLE TYPEWRITE, mom ignores \*[EXT] requests. \*[EXTSUP]...\*[EXTSUPX] pseudo extended superscript \*[FU n] move characters pairs further apart inline (related to macro .KERN) \*[FWD n] move forward in a line \*[LEADER] insert leaders at the end of a line \*[RULE] draw a full measure rule \*[SIZE n] change the point size inline (related to macro .PT_SIZE) \*[SLANT] \*[SLANTX] Pseudo italic on/off \*[SLANT] begins pseudo‐italicizing type. \*[SLANTX] turns the feature off. Both are inline escape sequences; therefore, they should not appear as separate lines, but rather be embedded in text lines, like this: Not \*[SLANT]everything\*[SLANTX] is as it seems. Alternatively, if you wanted the whole line pseudo‐italicized, you’d do \*[SLANT]Not everything is as it seems.\*[SLANTX] Once \*[SLANT] is invoked, it remains in effect until turned off. Note: If you’re using the document processing macros with .PRINTSTYLE TYPEWRITE, mom underlines pseudo‐italics by default. To change this behaviour, use the special macro .SLANT_MEANS_SLANT. \*[ST]...\*[STX] Mark positions of string tabs The quad direction must be LEFT or JUSTIFY (see .QUAD and .JUSTIFY) or the no‐fill mode set to LEFT in order for these in‐ lines to function properly. Please see IMPORTANT, below. String tabs need to be marked off with inline escape sequences before being set up with the .ST macro. Any input line may con‐ tain string tab markers. , above, means the numeric identifier of the tab. The following shows a sample input line with string tab markers. \*[ST1]De minimus\*[ST1X]non curat\*[ST2]lex\*[ST2X]. String tab 1 begins at the start of the line and ends after the word time. String tab 2 starts at good and ends after men. In‐ line escape sequences (e.g., font or point size changes, or hor‐ izontal movements, including padding) are taken into account when mom determines the position and length of string tabs. Up to nineteen string tabs may be marked (not necessarily all on the same line, of course), and they must be numbered between 1 and 19. Once string tabs have been marked in input lines, they have to be set with .ST, after which they may be called, by number, with .TAB. Note: Lines with string tabs marked off in them are normal input lines, i.e. they get printed, just like any input line. If you want to set up string tabs without the line printing, use the .SILENT macro. IMPORTANT: Owing to the way groff processes input lines and turns them into output lines, it is not possible for mom to guess the correct starting position of string tabs marked off in lines that are centered or set flush right. Equally, she cannot guess the starting position if a line is fully justified and broken with .SPREAD. In other words, in order to use string tabs, LEFT must be ac‐ tive, or, if .QUAD LEFT or JUSTIFY are active, the line on which the string tabs are marked must be broken manually with .BR (but not .SPREAD). To circumvent this behaviour, I recommend using the PAD to set up string tabs in centered or flush right lines. Say, for exam‐ ple, you want to use a string tab to underscore the text of a centered line with a rule. Rather than this, .CENTER \*[ST1]A line of text\*[ST1X]\c .EL .ST 1 .TAB 1 .PT_SIZE 24 .ALD 3p \*[RULE] .RLD 3p .TQ you should do: .QUAD CENTER .PAD "#\*[ST1]A line of text\*[ST1X]#" .EL .ST 1 .TAB 1 .PT_SIZE 24 .ALD 3p \" You can't use \*[UP] or \*[DOWN] with \*[RULE]. .RLD 3p .TQ \*[SUP]...\*[SUPX] superscript \*[TB+] Inline escape for .TN (Tab Next) \*[UL]...\*[ULX] invoke underlining inline (fixed width fonts only) \*[UP n] temporarily move upward in a line Details of macros in alphabetical order .AUTOLEAD set the linespacing relative to the point size .B_MARGIN  Bottom Margin Requires a unit of measure .B_MARGIN sets a nominal position at the bottom of the page be‐ yond which you don’t want your type to go. When the bottom mar‐ gin is reached, mom starts a new page. .B_MARGIN requires a unit of measure. Decimal fractions are allowed. To set a nomi‐ nal bottom margin of 3/4 inch, enter .B_MARGIN .75i Obviously, if you haven’t spaced the type on your pages so that the last lines fall perfectly at the bottom margin, the margin will vary from page to page. Usually, but not always, the last line of type that fits on a page before the bottom margin causes mom to start a new page. Occasionally, owing to a peculiarity in groff, an extra line will fall below the nominal bottom margin. If you’re using the document processing macros, this is unlikely to happen; the doc‐ ument processing macros are very hard‐nosed about aligning bot‐ tom margins. Note: The meaning of .B_MARGIN is slightly different when you’re using the document processing macros. .FALLBACK_FONT  [ ABORT | WARN ] Fallback Font In the event that you pass an invalid argument to .FAMILY (i.e. a non‐existent family), mom, by default, uses the fallback font, Courier Medium Roman (CR), in order to continue processing your file. If you’d prefer another fallback font, pass .FALLBACK_FONT the full family+font name of the font you’d like. For example, if you’d rather the fallback font were Times Roman Medium Roman, .FALLBACK_FONT TR would do the trick. Mom issues a warning whenever a font style set with .FT does not exist, either because you haven’t registered the style or be‐ cause the font style does not exist in the current family set with .FAMILY. By default, mom then aborts, which allows you to correct the problem. If you’d prefer that mom not abort on non‐existent fonts, but rather continue processing using a fallback font, you can pass .FALLBACK_FONT the argument WARN, either by itself, or in con‐ junction with your chosen fallback font. Some examples of invoking .FALLBACK_FONT: .FALLBACK_FONT WARN mom will issue a warning whenever you try to access a non‐existent font but will continue processing your file with the default fallback font, Courier Medium Roman. .FALLBACK_FONT TR WARN mom will issue a warning whenever you try to access a non‐existent font but will continue processing your file with a fallback font of Times Roman Medium Roman; addi‐ tionally, TR will be the fallback font whenever you try to access a family that does not exist. .FALLBACK_FONT TR ABORT mom will abort whenever you try to access a non‐existent font, and will use the fallback font TR whenever you try to access a family that does not exist. If, for some reason, you want to revert to ABORT, just enter ".FALLBACK_FONT ABORT" and mom will once again abort on font errors. .FAM  Type Family, alias of .FAMILY .FAMILY  Type Family, alias of .FAM .FAMILY takes one argument: the name of the family you want. Groff comes with a small set of basic families, each identified by a 1‐, 2‐ or 3‐letter mnemonic. The standard families are: A = Avant Garde BM = Bookman H = Helvetica HN = Helvetica Narrow N = New Century Schoolbook P = Palatino T = Times Roman ZCM = Zapf Chancery The argument you pass to .FAMILY is the identifier at left, above. For example, if you want Helvetica, enter .FAMILY H Note: The font macro (.FT) lets you specify both the type family and the desired font with a single macro. While this saves a few keystrokes, I recommend using .FAMILY for family, and .FT for font, except where doing so is genuinely inconvenient. ZCM, for example, only exists in one style: Italic (I). Therefore, .FT ZCMI makes more sense than setting the family to ZCM, then setting the font to I. Additional note: If you are running a groff version prior to 1.19.2, you must follow all .FAMILY requests with a .FT request, otherwise mom will set all type up to the next .FT request in the fallback font. If you are running groff 1.19.2 or later, when you invoke the .FAMILY macro, mom remembers the font style (Roman, Italic, etc) currently in use (if the font style exists in the new family) and will continue to use the same font style in the new family. For example: .FAMILY BM \" Bookman family .FT I \" Medium Italic  \" Bookman Medium Italic .FAMILY H \" Helvetica family  \" Helvetica Medium Italic However, if the font style does not exist in the new family, mom will set all subsequent type in the fallback font (by default, Courier Medium Roman) until she encounters a .FT request that’s valid for the family. For example, assuming you don’t have the font Medium Condensed Roman (mom extension CD) in the Helvetica family: .FAMILY UN \" Univers family .FT CD \" Medium Condensed  \" Univers Medium Condensed .FAMILY H \" Helvetica family  \" Courier Medium Roman! In the above example, you must follow .FAMILY H with a .FT re‐ quest that’s valid for Helvetica. Please see the Appendices, Adding fonts to groff, for informa‐ tion on adding fonts and families to groff,aswellasto see a list of the extensions mom provides to groff’s basic R, I, B, BI styles. Suggestion: When adding families to groff, I recommend following the established standard for the naming families and fonts. For example, if you add the Garamond family, name the font files GARAMONDR GARAMONDI GARAMONDB GARAMONDBI GARAMOND then becomes a valid family name you can pass to .FAMI‐ LY. (You could, of course, shorten GARAMOND to just G, or GD.) R, I, B, and BI after GARAMOND are the roman, italic, bold and bold‐italic fonts respectively. .FONT R | B | BI |  Alias to .FT .FT R | B | BI |  Set font By default, groff permits .FT to take one of four possible argu‐ ments specifying the desired font: R = (Medium) Roman I = (Medium) Italic B = Bold (Roman) BI = Bold Italic For example, if your family is Helvetica, entering .FT B will give you the Helvetica bold font. If your family were Palatino, you’d get the Palatino bold font. Mom considerably extends the range of arguments you can pass to .FT, making it more convenient to add and access fonts of dif‐ fering weights and shapes within the same family. Have a look here for a list of the weight/style arguments mom allows. Be aware, though, that you must have the fonts, cor‐ rectly installed and named, in order to use the arguments. (See Adding fonts to groff for instructions and information.) Please also read the ADDITIONAL NOTE found in the description of the .FAMILY macro. How mom reacts to an invalid argument to .FT depends on which version of groff you’re using. If your groff version is 1.19.2 or later, mom will issue a warning and, depending on how you’ve set up the fallback font, either continue processing using the fallback font, or abort (allowing you to correct the problem). In earlier versions, mom will silently continue processing, us‐ ing either the fallback font or the font that was in effect pri‐ or to the invalid .FT call. .FT will also accept, as an argument, a full family and font name. For example, .FT HB will set subsequent type in Helvetica Bold. However, I strongly recommend keeping family and font separate except where doing so is genuinely inconvenient. For inline control of fonts, see Inline Escapes, font control. .HI [  ] Hanging indent — the optional argument requires a unit of mea‐ sure. A hanging indent looks like this: The thousand injuries of Fortunato I had borne as best I could, but when he ventured upon insult, I vowed revenge. You who so well know the nature of my soul will not suppose, however, that I gave utterance to a threat, at length I would be avenged... The first line of text hangs outside the left margin. In order to use hanging indents, you must first have a left in‐ dent active (set with either .IL or .IB). Mom will not hang text outside the left margin set with .L_MARGIN or outside the left margin of a tab. The first time you invoke .HI, you must give it a measure. If you want the first line of a paragraph to hang by, say, 1 pica, do .IL 1P .HI 1P Subsequent invocations of .HI do not require you to supply a measure; mom keeps track of the last measure you gave it. Generally speaking, you should invoke .HI immediately prior to the line you want hung (i.e. without any intervening control lines). And because hanging indents affect only one line, there’s no need to turn them off. IMPORTANT: Unlike IL, IR and IB, measures given to .HI are NOT additive. Each time you pass a measure to .HI, the measure is treated literally. Recipe: A numbered list using hanging in‐ dents Note: mom has macros for setting lists. This recipe exists to demonstrate the use of hanging indents only. .PAGE 8.5i 11i 1i 1i 1i 1i .FAMILY T .FT R .PT_SIZE 12 .LS 14 .JUSTIFY .KERN .SS 0 .IL \w'\0\0.' .HI \w'\0\0.' 1.\0The most important point to be considered is whether the answer to the meaning of Life, the Universe, and Everything really is 42. We have no one's word on the subject except Mr. Adams's. .HI 2.\0If the answer to the meaning of Life, the Universe, and Everything is indeed 42, what impact does this have on the politics of representation? 42 is, after all not a prime number. Are we to infer that prime numbers don't deserve equal rights and equal access in the universe? .HI 3.\0If 42 is deemed non‐exclusionary, how do we present it as the answer and, at the same time, forestall debate on its exclusionary implications? First, we invoke a left indent with a measure equal to the width of 2 figures spaces plus a period (using the \w inline escape). At this point, the left indent is active; text afterward would normally be indented. However, we invoke a hanging indent of exactly the same width, which hangs the first line (and first line only!) to the left of the indent by the same distance (in this case, that means “out to the left margin”). Because we be‐ gin the first line with a number, a period, and a figure space, the actual text (The most important point...) starts at exactly the same spot as the indented lines that follow. Notice that subsequent invocations of .HI don’t require a mea‐ sure to be given. Paste the example above into a file and preview it with pdfmom filename.mom | ps2pdf - filename.pdf to see hanging indents in action. .IB [   ] Indent both — the optional argument requires a unit of measure .IB allows you to set or invoke a left and a right indent at the same time. At its first invocation, you must supply a measure for both in‐ dents; at subsequent invocations when you wish to supply a mea‐ sure, both must be given again. As with .IL and .IR, the mea‐ sures are added to the values previously passed to the macro. Hence, if you wish to change just one of the values, you must give an argument of zero to the other. A word of advice: If you need to manipulate left and right in‐ dents separately, use a combination of .IL and .IR instead of .IB. You’ll save yourself a lot of grief. A minus sign may be prepended to the arguments to subtract from their current values. The \w inline escape may be used to spec‐ ify text‐dependent measures, in which case no unit of measure is required. For example, .IB \w'margarine' \w'jello' left indents text by the width of the word margarine and right indents by the width of jello. Like .IL and .IR, .IB with no argument indents by its last ac‐ tive values. See the brief explanation of how mom handles in‐ dents for more details. Note: Calling a tab (with .TAB ) automatically cancels any active indents. Additional note: Invoking .IB automatically turns off .IL and .IR. .IL [  ] Indent left — the optional argument requires a unit of measure .IL indents text from the left margin of the page, or if you’re in a tab, from the left edge of the tab. Once IL is on, the left indent is applied uniformly to every subsequent line of text, even if you change the line length. The first time you invoke .IL, you must give it a measure. Sub‐ sequent invocations with a measure add to the previous measure. A minus sign may be prepended to the argument to subtract from the current measure. The \w inline escape may be used to speci‐ fy a text‐dependent measure, in which case no unit of measure is required. For example, .IL \w'margarine' indents text by the width of the word margarine. With no argument, .IL indents by its last active value. See the brief explanation of how mom handles indents for more details. Note: Calling a tab (with .TAB ) automatically cancels any active indents. Additional note: Invoking .IL automatically turns off IB. .IQ [  ] IQ — quit any/all indents IMPORTANT NOTE: The original macro for quitting all indents was .IX. This usage has been deprecated in favour of IQ. .IX will continue to behave as before, but mom will issue a warning to stderr indicating that you should update your documents. As a consequence of this change, .ILX, .IRX and .IBX may now al‐ so be invoked as .ILQ, .IRQ and .IBQ. Both forms are accept‐ able. Without an argument, the macros to quit indents merely restore your original margins and line length. The measures stored in the indent macros themselves are saved so you can call them again without having to supply a measure. If you pass these macros the optional argument CLEAR, they not only restore your original left margin and line length, but also clear any values associated with a particular indent style. The next time you need an indent of the same style, you have to sup‐ ply a measure again. .IQ CLEAR, as you’d suspect, quits and clears the values for all indent styles at once. .IR [  ] Indent right — the optional argument requires a unit of measure .IR indents text from the right margin of the page, or if you’re in a tab, from the end of the tab. The first time you invoke .IR, you must give it a measure. Sub‐ sequent invocations with a measure add to the previous indent measure. A minus sign may be prepended to the argument to sub‐ tract from the current indent measure. The \w inline escape may be used to specify a text‐dependent measure, in which case no unit of measure is required. For example, .IR \w'jello' indents text by the width of the word jello. With no argument, .IR indents by its last active value. See the brief explanation of how mom handles indents for more details. Note: Calling a tab (with .TAB ) automatically cancels any active indents. Additional note: Invoking .IR automatically turns off IB. .L_MARGIN  Left Margin L_MARGIN establishes the distance from the left edge of the printer sheet at which you want your type to start. It may be used any time, and remains in effect until you enter a new val‐ ue. Left indents and tabs are calculated from the value you pass to .L_MARGIN, hence it’s always a good idea to invoke it before starting any serious typesetting. A unit of measure is re‐ quired. Decimal fractions are allowed. Therefore, to set the left margin at 3 picas (1/2 inch), you’d enter either .L_MARGIN 3P or .L_MARGIN .5i If you use the macros .PAGE, .PAGEWIDTH or .PAPER without invok‐ ing .L_MARGIN (either before or afterward), mom automatically sets .L_MARGIN to 1 inch. Note: .L_MARGIN behaves in a special way when you’re using the document processing macros. .MCO Begin multi‐column setting. .MCO (Multi‐Column On) is the macro you use to begin multi‐col‐ umn setting. It marks the current baseline as the top of your columns, for use later with .MCR. See the introduction to columns for an explanation of multi‐columns and some sample in‐ put. Note: Do not confuse .MCO with the .COLUMNS macro in the docu‐ ment processing macros. .MCR Once you’ve turned multi‐columns on (with .MCO), .MCR, at any time, returns you to the top of your columns. .MCX [  ] Optional argument requires a unit of measure. Exit multi‐columns. .MCX takes you out of any tab you were in (by silently invoking .TQ) and advances to the bottom of the longest column. Without an argument, .MCX advances 1 linespace below the longest column. Linespace, in this instance, is the leading in effect at the mo‐ ment .MCX is invoked. If you pass the  argument to .MCX, it advances 1 line‐ space below the longest column (see above) PLUS the distance specified by the argument. The argument requires a unit of mea‐ sure; therefore, to advance an extra 6 points below where .MCX would normally place you, you’d enter .MCX 6p Note: If you wish to advance a precise distance below the base‐ line of the longest column, use .MCX with an argument of 0 (ze‐ ro; no unit of measure required) in conjunction with the .ALD macro, like this: .MCX 0 .ALD 24p The above advances to precisely 24 points below the baseline of the longest column. .NEWPAGE Whenever you want to start a new page, use .NEWPAGE, by itself with no argument. Mom will finish up processing the current page and move you to the top of a new one (subject to the top margin set with .T_MARGIN). .PAGE  [  [  [  [  [  ] ] ] ] ] All arguments require a unit of measure IMPORTANT: If you’re using the document processing macros, .PAGE must come after .START. Otherwise, it should go at the top of a document, prior to any text. And remember, when you’re using the document processing macros, top margin and bottom margin mean something slightly different than when you’re using just the typesetting macros (see Top and bottom margins in document processing). .PAGE lets you establish paper dimensions and page margins with a single macro. The only required argument is page width. The rest are optional, but they must appear in order and you can’t skip over any. , ,  and  refer to the left, right, top and bottom margins respectively. Assuming your page dimensions are 11 inches by 17 inches, and that’s all you want to set, enter .PAGE 11i 17i If you want to set the left margin as well, say, at 1 inch, PAGE would look like this: .PAGE 11i 17i 1i Now suppose you also want to set the top margin, say, at 1–1/2 inches.  comes after  in the optional arguments, but you can’t skip over any arguments, therefore to set the top mar‐ gin, you must also give a right margin. The .PAGE macro would look like this: .PAGE 11i 17i 1i 1i 1.5i | | required right---+ +---top margin margin Clearly, .PAGE is best used when you want a convenient way to tell mom just the dimensions of your printer sheet (width and length), or when you want to tell her everything about the page (dimensions and all the margins), for example .PAGE 8.5i 11i 45p 45p 45p 45p This sets up an 8½ by 11 inch page with margins of 45 points (5/8‐inch) all around. Additionally, if you invoke .PAGE with a top margin argument, any macros you invoke after .PAGE will almost certainly move the baseline of the first line of text down by one linespace. To compensate, do .RLD 1v immediately before entering any text, or, if it’s feasible, make .PAGE the last macro you invoke prior to entering text. Please read the Important note on page dimensions and papersize for information on ensuring groff respects your .PAGE dimensions and margins. .PAGELENGTH  tells mom how long your printer sheet is. It works just like .PAGEWIDTH. Therefore, to tell mom your printer sheet is 11 inches long, you enter .PAGELENGTH 11i Please read the important note on page dimensions and papersize for information on ensuring groff respects your PAGELENGTH. .PAGEWIDTH  The argument to .PAGEWIDTH is the width of your printer sheet. .PAGEWIDTH requires a unit of measure. Decimal fractions are allowed. Hence, to tell mom that the width of your printer sheet is 8½ inches, you enter .PAGEWIDTH 8.5i Please read the Important note on page dimensions and papersize for information on ensuring groff respects your PAGEWIDTH. .PAPER  provides a convenient way to set the page dimensions for some common printer sheet sizes. The argument  can be one of: LETTER, LEGAL, STATEMENT, TABLOID, LEDGER, FOLIO, QUAR‐ TO, EXECUTIVE, 10x14, A3, A4, A5, B4, B5. .PRINTSTYLE .PT_SIZE  Point size of type, does not require a unit of measure. .PT_SIZE (Point Size) takes one argument: the size of type in points. Unlike most other macros that establish the size or measure of something, .PT_SIZE does not require that you supply a unit of measure since it’s a near universal convention that type size is measured in points. Therefore, to change the type size to, say, 11 points, enter .PT_SIZE 11 Point sizes may be fractional (e.g., 10.25 or 12.5). You can prepend a plus or a minus sign to the argument to .PT_SIZE, in which case the point size will be changed by + or - the original value. For example, if the point size is 12, and you want 14, you can do .PT_SIZE +2 then later reset it to 12 with .PT_SIZE -2 The size of type can also be changed inline. Note: It is unfortunate that the pic preprocessor has already taken the name, PS, and thus mom’s macro for setting point sizes can’t use it. However, if you aren’t using pic, you might want to alias .PT_SIZE as .PS, since there’d be no conflict. For ex‐ ample .ALIAS PS PT_SIZE would allow you to set point sizes with .PS. .R_MARGIN  Right Margin Requires a unit of measure. IMPORTANT: .R_MARGIN, if used, must come after .PAPER, .PAGEWIDTH, .L_MARGIN, and/or .PAGE (if a right margin isn’t given to PAGE). The reason is that .R_MARGIN calculates line length from the overall page dimensions and the left margin. Obviously, it can’t make the calculation if it doesn’t know the page width and the left margin. .R_MARGIN establishes the amount of space you want between the end of typeset lines and the right hand edge of the printer sheet. In other words, it sets the line length. .R_MARGIN re‐ quires a unit of measure. Decimal fractions are allowed. The line length macro (LL) can be used in place of .R_MARGIN. In either case, the last one invoked sets the line length. The choice of which to use is up to you. In some instances, you may find it easier to think of a section of type as having a right margin. In others, giving a line length may make more sense. For example, if you’re setting a page of type you know should have 6‐pica margins left and right, it makes sense to enter a left and right margin, like this: .L_MARGIN 6P .R_MARGIN 6P That way, you don’t have to worry about calculating the line length. On the other hand, if you know the line length for a patch of type should be 17 picas and 3 points, entering the line length with LL is much easier than calculating the right margin, e.g., .LL 17P+3p If you use the macros .PAGE, .PAGEWIDTH or PAPER without invok‐ ing .R_MARGIN afterward, mom automatically sets .R_MARGIN to 1 inch. If you set a line length after these macros (with .LL), the line length calculated by .R_MARGIN is, of course, overrid‐ den. Note: .R_MARGIN behaves in a special way when you’re using the document processing macros. .ST  L | R | C | J [ QUAD ] After string tabs have been marked off on an input line (see \*[ST]...\*[STX]), you need to set them by giving them a direc‐ tion and, optionally, the QUAD argument. In this respect, .ST is like .TAB_SET except that you don’t have to give .ST an indent or a line length (that’s already taken care of, inline, by \*[ST]...\*[STX]). If you want string tab 1 to be left, enter .ST 1 L If you want it to be left and filled, enter .ST 1 L QUAD If you want it to be justified, enter .ST 1 J .TAB  After tabs have been defined (either with .TAB_SET or .ST), .TAB moves to whatever tab number you pass it as an argument. For example, .TAB 3 moves you to tab 3. Note: .TAB breaks the line preceding it and advances 1 line‐ space. Hence, .TAB 1 A line of text in tab 1. .TAB 2 A line of text in tab 2. produces, on output A line of text in tab 1. A line of text in tab 2. If you want the tabs to line up, use .TN (“Tab Next”) or, more conveniently, the inline escape sequence \*[TB+]: .TAB 1 A line of text in tab 1.\*[TB+] A line of text in tab 2. which produces A line of text in tab 1. A line of text in tab 2. If the text in your tabs runs to several lines, and you want the first lines of each tab to align, you must use the multi‐column macros. Additional note: Any indents in effect prior to calling a tab are automatically turned off by TAB. If you were happily zip‐ ping down the page with a left indent of 2 picas turned on, and you call a tab whose indent from the left margin is 6 picas, your new distance from the left margin will be 6 picas, not I 6 picas plus the 2 pica indent. Tabs are not by nature columnar, which is to say that if the text inside a tab runs to several lines, calling another tab does not automatically move to the baseline of the first line in the previous tab. To demonstrate: TAB 1 Carrots Potatoes Broccoli .TAB 2 $1.99/5 lbs $0.25/lb $0.99/bunch produces, on output Carrots Potatoes Broccoli $1.99/5 lbs $0.25/lb $0.99/bunch .TB  Alias to .TAB .TI [  ] Temporary left indent — the optional argument requires a unit of measure A temporary indent is one that applies only to the first line of text that comes after it. Its chief use is indenting the first line of paragraphs. (Mom’s .PP macro, for example, uses a tem‐ porary indent.) The first time you invoke .TI, you must give it a measure. If you want to indent the first line of a paragraph by, say, 2 ems, do .TI 2m Subsequent invocations of .TI do not require you to supply a measure; mom keeps track of the last measure you gave it. Because temporary indents are temporary, there’s no need to turn them off. IMPORTANT: Unlike .IL, .IR and IB, measures given to .TI are NOT additive. In the following example, the second ".TI 2P" is ex‐ actly 2 picas. .TI 1P The beginning of a paragraph... .TI 2P The beginning of another paragraph... .TN Tab Next Inline escape \*[TB+] TN moves over to the next tab in numeric sequence (tab n+1) without advancing on the page. See the NOTE in the description of the .TAB macro for an example of how TN works. In tabs that aren’t given the QUAD argument when they’re set up with .TAB_SET or ST, you must terminate the line preceding .TN with the \c inline escape sequence. Conversely, if you did give a QUAD argument to .TAB_SET or ST, the \c must not be used. If you find remembering whether to put in the \c bothersome, you may prefer to use the inline escape alternative to .TN, \*[TB+], which works consistently regardless of the fill mode. Note: You must put text in the input line immediately after .TN. Stacking of .TN’s is not allowed. In other words, you cannot do .TAB 1 Some text\c .TN Some more text\c .TN .TN Yet more text The above example, assuming tabs numbered from 1 to 4, should be entered .TAB 1 Some text\c .TN Some more text\c .TN \&\c .TN Yet more text \& is a zero‐width, non‐printing character that groff recognizes as valid input, hence meets the requirement for input text fol‐ lowing .TN. .TQ TQ takes you out of whatever tab you were in, advances 1 line‐ space, and restores the left margin, line length, quad direction and fill mode that were in effect prior to invoking any tabs. .T_MARGIN  Top margin Requires a unit of measure .T_MARGIN establishes the distance from the top of the printer sheet at which you want your type to start. It requires a unit of measure, and decimal fractions are allowed. To set a top margin of 2½ centimetres, you’d enter .T_MARGIN 2.5c .T_MARGIN calculates the vertical position of the first line of type on a page by treating the top edge of the printer sheet as a baseline. Therefore, .T_MARGIN 1.5i puts the baseline of the first line of type 1½ inches beneath the top of the page. Note: .T_MARGIN means something slightly different when you’re using the document processing macros. See Top and bottom mar‐ gins in document processing for an explanation. IMPORTANT: .T_MARGIN does two things: it establishes the top margin for pages that come after it and it moves to that posi‐ tion on the current page. Therefore, .T_MARGIN should only be used at the top of a file (prior to entering text) or after NEW‐ PAGE, like this: .NEWPAGE .T_MARGIN 6P  Authors mom was written by Peter Schaffter ⟨peter@schaffter.ca⟩. PDF support was provided by Deri James ⟨deri@chuzzlewit.myzen.co.uk⟩. This manual page was written by Bernd Warken. See also /usr/local/share/doc/groff-1.23.0/html/mom/toc.html entry point to the HTML documentation ⟨http://www.schaffter.ca/mom/momdoc/toc.html⟩ HTML documentation online ⟨http://www.schaffter.ca/mom/⟩ the mom macros homepage Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. pdfmom(1), groff(1), troff(1) groff 1.23.0 29 August 2023 groff_mom(7) ─────────────────────────────────────────────────────────────────────────────── groff_ms(7) Miscellaneous Information Manual groff_ms(7) Name groff_ms - GNU roff manuscript macro package for formatting documents Synopsis groff -ms [option ...] [file ...] groff -m ms [option ...] [file ...] Description The GNU implementation of the ms macro package is part of the groff document formatting system. The ms package is suitable for the compo‐ sition of letters, memoranda, reports, and books. These groff macros support cover page and table of contents generation, automatically numbered headings, several paragraph styles, a variety of text styling options, footnotes, and multi‐column page layouts. ms supports the tbl(1), eqn(1), pic(1), and refer(1) preprocessors for in‐ clusion of tables, mathematical equations, diagrams, and standardized bibliographic citations. This implementation is mostly compatible with the documented interface and behavior of AT&T Unix Version 7 ms. Many extensions from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been recreated. Usage The ms macro package expects a certain amount of structure: a well‐ formed document contains at least one paragraphing or heading macro call. To compose a simple document from scratch, begin it by calling .LP or .PP. Longer documents have a structure as follows. Document type Calling the RP macro at the beginning of your document puts the document description (see below) on a cover page. Otherwise, ms places this information on the first page, followed immediately by the body text. Some document types found in other ms imple‐ mentations are specific to AT&T or Berkeley, and are not sup‐ ported in groff ms. Format and layout By setting registers and strings, you can configure your docu‐ ment’s typeface, margins, spacing, headers and footers, and footnote arrangement. See subsection “Document control set‐ tings” below. Document description A document description consists of any of: a title, one or more authors’ names and affiliated institutions, an abstract, and a date or other identifier. See subsection “Document description macros” below. Body text The main matter of your document follows its description (if any). ms supports highly structured text consisting of para‐ graphs interspersed with multi‐level headings (chapters, sec‐ tions, subsections, and so forth) and augmented by lists, foot‐ notes, tables, diagrams, and similar material. The preponder‐ ance of subsections below covers these matters. Table of contents Macros enable the collection of entries for a table of contents (or index) as the material they discuss appears in the document. You then call a macro to emit the table of contents at the end of your document. The table of contents must necessarily follow the rest of the text since GNU troff is a single‐pass formatter; it thus cannot determine the page number of a division of the text until it has been set and output. Since ms output was de‐ signed for the production of hard copy, the traditional proce‐ dure was to manually relocate the pages containing the table of contents between the cover page and the body text. Today, page resequencing is more often done in the digital domain. An index works similarly, but because it typically needs to be sorted af‐ ter collection, its preparation requires separate processing. Document control settings The following tables list the document control registers, strings, and special characters. For any parameter whose default is unsatisfactory, define it before calling any ms macro other than RP. Margin settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[PO] Page offset (left margin) next page 1i (0) \n[LL] Line length next paragraph 6.5i (65n) \n[LT] Title line length next paragraph 6.5i (65n) \n[HM] Top (header) margin next page 1i \n[FM] Bottom (footer) margin next page 1i ──────────────────────────────────────────────────────────────────────── Titles (headers, footers) Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \*[LH] Left header text next header empty \*[CH] Center header text next header -\n[%]- \*[RH] Right header text next header empty \*[LF] Left footer text next footer empty \*[CF] Center footer text next footer empty \*[RF] Right footer text next footer empty ──────────────────────────────────────────────────────────────────────── Text settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[PS] Point size next paragraph 10p \n[VS] Vertical spacing (leading) next paragraph 12p \n[HY] Hyphenation mode next paragraph 6 \*[FAM] Font family next paragraph T ──────────────────────────────────────────────────────────────────────── Paragraph settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[PI] Indentation next paragraph 5n \n[PD] Paragraph distance (spacing) next paragraph 0.3v (1v) \n[QI] Quotation indentation next paragraph 5n \n[PORPHANS] # of initial lines kept next paragraph 1 ──────────────────────────────────────────────────────────────────────── Heading settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[PSINCR] Point size increment next heading 1p \n[GROWPS] Size increase depth limit next heading 0 \n[HORPHANS] # of following lines kept next heading 1 \*[SN-STYLE] Numbering style (alias) next heading \*[SN-DOT] ──────────────────────────────────────────────────────────────────────── \*[SN-STYLE] can alternatively be made an alias of \*[SN-NO-DOT] with the als request. Footnote settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[FI] Indentation next footnote 2n \n[FF] Format next footnote 0 \n[FPS] Point size next footnote \n[PS]-2p \n[FVS] Vertical spacing (leading) next footnote \n[FPS]+2p \n[FPD] Paragraph distance (spacing) next footnote \n[PD]/2 \*[FR] Line length ratio special 11/12 ──────────────────────────────────────────────────────────────────────── Display settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[DD] Display distance (spacing) special 0.5v (1v) \n[DI] Display indentation special 0.5i ──────────────────────────────────────────────────────────────────────── Other settings Parameter Definition Effective Default ──────────────────────────────────────────────────────────────────────── \n[MINGW] Minimum gutter width next page 2n \n[TC-MARGIN] TOC page number margin width next PX call \w'000' \[TC-LEADER] TOC leader character next PX call .\h'1m' ──────────────────────────────────────────────────────────────────────── For entries marked “special” in the “Effective” column, see the discus‐ sion in the applicable section below. The PO, LL, and LT register de‐ faults vary by output device and paper format; the values shown are for typesetters using U.S. letter paper, and then terminals. See section “Paper format” of groff(1). The PD and DD registers use the larger value if the vertical motion quantum of the output device is too coarse for the smaller one; usually, this is the case only for output to ter‐ minals and emulators thereof. The “gutter” affected by \n[MINGW] is the gap between columns in multiple‐column page arrangements. The TC-MARGIN register and TC-LEADER special character affect the format‐ ting of tables of contents assembled by the XS, XA, and XE macros. Document description macros Define information describing the document by calling the macros below in the order shown; .DA or .ND can be called to set the document date (or other identifier) at any time before (a) the abstract, if present, or (b) its information is required in a header or footer. Use of these macros is optional, except that .TL is mandatory if any of .RP, .AU, .AI, or .AB is called, and .AE is mandatory if .AB is called. .RP [no-repeat-info] [no-renumber] Use the “report” (AT&T: “released paper”) format for your docu‐ ment, creating a separate cover page. The default arrangement is to place most of the document description (title, author names and institutions, and abstract, but not the date) at the top of the first page. If the optional no-repeat-info argument is given, ms produces a cover page but does not repeat any of its information on subsequently (but see the DA macro below re‐ garding the date). Normally, .RP sets the page number following the cover page to 1. Specifying the optional no-renumber argu‐ ment suppresses this alteration. Optional arguments can occur in any order. “no” is recognized as a synonym of no-repeat-info for AT&T compatibility. .TL Specify the document title. ms collects text on input lines following this call into the title until reaching .AU, .AB, or a heading or paragraphing macro call. .AU Specify an author’s name. ms collects text on input lines fol‐ lowing this call into the author’s name until reaching .AI, .AB, another .AU, or a heading or paragraphing macro call. Call it repeatedly to specify multiple authors. .AI Specify the preceding author’s institution. An .AU call is use‐ fully followed by at most one .AI call; if there are more, the last .AI call controls. ms collects text on input lines follow‐ ing this call into the author’s institution until reaching .AU, .AB, or a heading or paragraphing macro call. .DA [x ...] Typeset the current date, or any arguments x, in the center footer, and, if .RP is also called, left‐aligned at the end of the document description on the cover page. .ND [x ...] Typeset the current date, or any arguments x, if .RP is also called, left‐aligned at the end of the document description on the cover page. This is groff ms’s default. .AB [no] Begin the abstract. ms collects text on input lines following this call into the abstract until reaching an .AE call. By de‐ fault, ms places the word “ABSTRACT” centered and in italics above the text of the abstract. The optional argument “no” sup‐ presses this heading. .AE End the abstract. Text settings The FAM string, a GNU extension, sets the font family for body text; the default is “T”. The PS and VS registers set the type size and ver‐ tical spacing (distance between text baselines), respectively. The font family and type size are ignored on terminal devices. Setting these parameters before the first call of a heading, paragraphing, or (non‐date) document description macro also applies them to headers, footers, and (for FAM) footnotes. The HY register defines the automatic hyphenation mode used with the hy request. Setting \n[HY] to 0 is equivalent to using the nh request. This is a Tenth Edition Research Unix extension. Typographical symbols ms provides a few strings to obtain typographical symbols not easily entered with the keyboard. These and many others are available as spe‐ cial character escape sequences—see groff_char(7). \*[-] Interpolate an em dash. \*[Q] \*[U] Interpolate typographer’s quotation marks where available, and neutral double quotes otherwise. \*[Q] is the left quote and \*[U] the right. Paragraphs Paragraphing macros break, or terminate, any pending output line so that a new paragraph can begin. Several paragraph types are available, differing in how indentation applies to them: to left, right, or both margins; to the first output line of the paragraph, all output lines, or all but the first. All paragraphing macro calls cause the insertion of vertical space in the amount stored in the PD register, except at page or column breaks, or adjacent to displays. The PORPHANS register defines the minimum number of initial lines of any paragraph that must be kept together to avoid isolated lines at the bottom of a page. If a new paragraph is started close to the bottom of a page, and there is insufficient space to accommodate \n[PORPHANS] lines before an automatic page break, then a page break is forced be‐ fore the start of the paragraph. This is a GNU extension. .LP Set a paragraph without any (additional) indentation. .PP Set a paragraph with a first‐line left indentation in the amount stored in the PI register. .IP [marker [width]] Set a paragraph with a left indentation. The optional marker is not indented and is empty by default. width overrides the in‐ dentation amount in \n[PI]; its default unit is “n”. Once spec‐ ified, width applies to further .IP calls until specified again or a heading or different paragraphing macro is called. .QP Set a paragraph indented from both left and right margins by \n[QI]. .QS .QE Begin (QS) and end (QE) a region where each paragraph is in‐ dented from both margins by \n[QI]. The text between .QS and .QE can be structured further by use of other paragraphing macros. .XP Set an “exdented” paragraph—one with a left indentation of \n[PI] on every line except the first (also known as a hanging indent). This is a Berkeley extension. Headings Use headings to create a hierarchical structure for your document. The ms macros print headings in bold using the same font family and, by de‐ fault, type size as the body text. Headings are available with and without automatic numbering. Text on input lines following the macro call becomes the heading’s title. Call a paragraphing macro to end the heading text and start the section’s content. .NH [depth] Set an automatically numbered heading. ms produces a numbered heading in the form a.b.c..., to any level desired, with the numbering of each depth increasing automatically and being reset to zero when a more significant depth is increased. “1” is the most significant or coarsest division of the document. Only non‐zero values are output. If depth is omitted, it is taken to be 1. If you specify depth such that an ascending gap occurs relative to the previous NH call—that is, you “skip a depth”, as by “.NH 1” and then “.NH 3”, groff ms emits a warning on the standard error stream. .NH S heading‐depth‐index ... Alternatively, you can give NH a first argument of “S”, followed by integers to number the heading depths explicitly. Further automatic numbering, if used, resumes using the specified in‐ dices as their predecessors. This feature is a Berkeley exten‐ sion. After .NH is called, the assigned number is made available in the strings SN-DOT (as it appears in a printed heading with default format‐ ting, followed by a terminating period) and SN-NO-DOT (with the termi‐ nating period omitted). These are GNU extensions. You can control the style used to print numbered headings by defining an appropriate alias for the string SN-STYLE. By default, \*[SN-STYLE] is aliased to \*[SN-DOT]. If you prefer to omit the terminating period from numbers appearing in numbered headings, you may alias it to \*[SN-NO-DOT]. Any such change in numbering style becomes effective from the next use of .NH following redefinition of the alias for \*[SN-STYLE]. The formatted number of the current heading is available in \*[SN] (a feature first documented by Berkeley); this string facili‐ tates its inclusion in, for example, table captions, equation labels, and .XS/.XA/.XE table of contents entries. .SH [depth] Set an unnumbered heading. The optional depth argument is a GNU extension indicating the heading depth corresponding to the depth argument of .NH. It matches the type size at which the heading is set to that of a numbered heading at the same depth when the \n[GROWPS] and \n[PSINCR] heading size adjustment mech‐ anism is in effect. The PSINCR register defines an increment in type size to be applied to a heading at a lesser depth than that specified in \n[GROWPS]. The value of \n[PSINCR] should be specified in points with the “p” scaling unit and may include a fractional component. The GROWPS register defines the heading depth above which the type size increment set by \n[PSINCR] becomes effective. For each heading depth less than the value of \n[GROWPS], the type size is increased by \n[PSINCR]. Setting \n[GROWPS] to a value less than 2 disables the in‐ cremental heading size feature. In other words, if the value of GROWPS register is greater than the depth argument to a .NH or .SH call, the type size of a heading pro‐ duced by these macros increases by \n[PSINCR] units over \n[PS] multi‐ plied by the difference of \n[GROWPS] and depth. The \n[HORPHANS] register operates in conjunction with the NH and SH macros to inhibit the printing of isolated headings at the bottom of a page; it specifies the minimum number of lines of the subsequent para‐ graph that must be kept on the same page as the heading. If insuffi‐ cient space remains on the current page to accommodate the heading and this number of lines of paragraph text, a page break is forced before the heading is printed. Any display macro call or tbl, pic, or eqn re‐ gion between the heading and the subsequent paragraph suppresses this grouping. Typeface and decoration The ms macros provide a variety of ways to style text. Attend closely to the ordering of arguments labeled pre and post, which is not intu‐ itive. Support for pre arguments is a GNU extension. .B [text [post [pre]]] Style text in bold, followed by post in the previous font style without intervening space, and preceded by pre similarly. With‐ out arguments, ms styles subsequent text in bold until the next paragraphing, heading, or no‐argument typeface macro call. .R [text [post [pre]]] As .B, but use the roman style (upright text of normal weight) instead of bold. Argument recognition is a GNU extension. .I [text [post [pre]]] As .B, but use an italic or oblique style instead of bold. .BI [text [post [pre]]] As .B, but use a bold italic or bold oblique style instead of upright bold. This is a Tenth Edition Research Unix extension. .CW [text [post [pre]]] As .B, but use a constant‐width (monospaced) roman typeface in‐ stead of bold. This is a Tenth Edition Research Unix extension. .BX [text] Typeset text and draw a box around it. On terminal devices, re‐ verse video is used instead. If you want text to contain space, use unbreakable space or horizontal motion escape sequences (\~, \space, \^, \|, \0, or \h). .UL [text [post]] Typeset text with an underline. post, if present, is set after text with no intervening space. .LG Set subsequent text in larger type (2 points larger than the current size) until the next type size, paragraphing, or heading macro call. You can specify this macro multiple times to en‐ large the type size as needed. .SM Set subsequent text in smaller type (2 points smaller than the current size) until the next type size, paragraphing, or heading macro call. You can specify this macro multiple times to reduce the type size as needed. .NL Set subsequent text at the normal type size (\n[PS]). When pre is used, a hyphenation control escape sequence \% that would ordinarily start text must start pre instead. groff ms also offers strings to begin and end super‐ and subscripting. These are GNU extensions. \*{ \*} Begin and end superscripting, respectively. \*< \*> Begin and end subscripting, respectively. Indented regions You may need to indent a region of text while otherwise formatting it normally. Indented regions can be nested. .RS Begin a region where headings, paragraphs, and displays are in‐ dented (further) by \n[PI]. .RE End the (next) most recent indented region. Keeps, boxed keeps, and displays On occasion, you may want to keep several lines of text, or a region of a document, together on a single page, preventing an automatic page break within certain boundaries. This can cause a page break to occur earlier than it normally would. You can alternatively specify a floating keep: if a keep cannot fit on the current page, ms holds its contents and allows text following the keep (in the source document) to fill in the remainder of the current page. When the page breaks, whether by reaching the end or bp request, ms puts the floating keep at the beginning of the next page. .KS Begin a keep. .KF Begin a floating keep. .KE End (floating) keep. As an alternative to the keep mechanism, the ne request forces a page break if there is not at least the amount of vertical space specified in its argument remaining on the page. A boxed keep has a frame drawn around it. .B1 Begin a keep with a box drawn around it. .B2 End boxed keep. Boxed keep macros cause breaks; if you need to box a word or phrase within a line, see the BX macro in section “Highlighting” above. Box lines are drawn as close as possible to the text they enclose so that they are usable within paragraphs. If you wish to place one or more paragraphs in a boxed keep, you may improve their appearance by calling .B1 after the first paragraphing macro, and by adding a small amount of vertical space before calling .B2. If you want a boxed keep to float, you will need to enclose the .B1 and .B2 calls within a pair of .KF and .KE calls. Displays turn off filling; lines of verse or program code are shown with their lines broken as in the source document without requiring br requests between lines. Displays can be kept on a single page or al‐ lowed to break across pages. The DS macro begins a kept display of the layout specified in its first argument; non‐kept displays are begun with dedicated macros corresponding to their layout. .DS L .LD Begin (DS: kept) left‐aligned display. .DS [I [indent]] .ID [indent] Begin (DS: kept) display indented by indent if specified, \n[DI] otherwise. .DS B .BD Begin (DS: kept) block display: the entire display is left‐ aligned, but indented such that the longest line in the display is centered on the page. .DS C .CD Begin (DS: kept) centered display: each line in the display is centered. .DS R .RD Begin (DS: kept) right‐aligned display. This is a GNU exten‐ sion. .DE End any display. The distance stored in \n[DD] is inserted before and after each pair of display macros; this is a Berkeley extension. In groff ms, this dis‐ tance replaces any adjacent inter‐paragraph distance or subsequent spacing prior to a section heading. The DI register is a GNU exten‐ sion; its value is an indentation applied to displays created with .DS and .ID without arguments, to “.DS I” without an indentation argument, and to equations set with “.EQ I”. Changes to either register take ef‐ fect at the next display boundary. Tables, figures, equations, and references The ms package is often used with the tbl, pic, eqn, and refer pre‐ processors. The \n[DD] distance is also applied to regions of the doc‐ ument preprocessed with eqn, pic, and tbl. Mark text meant for pre‐ processors by enclosing it in pairs of tokens as follows, with nothing between the dot and the macro name. The preprocessors match these to‐ kens only at the start of an input line. .TS [H] .TE Demarcate a table to be processed by the tbl preprocessor. The optional H argument instructs ms to repeat table rows (often column headings) at the top of each new page the table spans, if applicable; calling the TH macro marks the end of such rows. tbl(1) provides a comprehensive reference to the preprocessor and offers examples of its use. .PS .PE .PF .PS begins a picture to be processed by the pic preprocessor; either of .PE or .PF ends it, the latter with “flyback” to the vertical position at its top. .EQ [align [label]] .EN Demarcate an equation to be processed by the eqn preprocessor. The equation is centered by default; align can be C, L, or I to (explicitly) center, left‐align, or indent it by \n[DI], respec‐ tively. If specified, label is set right‐aligned. .[ .] Demarcate a bibliographic citation to be processed by the refer preprocessor. refer(1) provides a comprehensive reference to the preprocessor and the format of its bibliographic database. When refer emits collected references (as might be done on a “Works Cited” page), it interpolates the string \*[REFERENCES] as an unnum‐ bered heading (.SH). Attempting to place a multi‐page table inside a keep can lead to un‐ pleasant results, particularly if the tbl “allbox” option is used. Footnotes A footnote is typically anchored to a place in the text with a marker, which is a small integer, a symbol, or arbitrary user‐specified text. \** Place an automatic number, an automatically generated numeric footnote marker, in the text. Each time this string is interpo‐ lated, the number it produces increments by one. Automatic num‐ bers start at 1. This is a Berkeley extension. Enclose the footnote text in FS and FE macro calls to set it at the nearest available “foot”, or bottom, of a text column or page. .FS [marker] Begin a footnote. The .FS-MARK hook (see below) is called with any supplied marker argument, which is then also placed at the beginning of the footnote text. If marker is omitted, the next pending automatic number enqueued by interpolation of the * string is used, and if none exists, nothing is prefixed. .FE End footnote text. groff ms provides a hook macro, FS-MARK, for user‐determined operations to be performed when the FS macro is called. It is passed the same ar‐ guments as .FS itself. By default, this macro has an empty definition. .FS-MARK is a GNU extension. Footnote text is formatted as paragraphs are, using analogous parame‐ ters. The registers FI, FPD, FPS, and FVS correspond to PI, PD, PS, and VS, respectively; FPD, FPS, and FVS are GNU extensions. The FF register controls the formatting of automatically numbered foot‐ note paragraphs, and those for which .FS is given a marker argument, at the bottom of a column or page as follows. 0 Set an automatic number, or a specified FS marker argu‐ ment, as a superscript (on typesetter devices) or sur‐ rounded by square brackets (on terminals). The footnote paragraph is indented as with .PP if there is an .FS ar‐ gument or an automatic number, and as with .LP otherwise. This is the default. 1 As 0, but set the marker as regular text, and follow an automatic number with a period. 2 As 1, but without indentation (like .LP). 3 As 1, but set the footnote paragraph with the marker hanging (like .IP). Language and localization groff ms provides several strings that you can customize for your own purposes, or redefine to adapt the macro package to languages other than English. It is already localized for Czech, German, French, Ital‐ ian, and Swedish. Load the desired localization macro package after ms; see groff_tmac(5). String Default ─────────────────────────────────── \*[REFERENCES] References \*[ABSTRACT] \f[I]ABSTRACT\f[] \*[TOC] Table of Contents \*[MONTH1] January \*[MONTH2] February \*[MONTH3] March \*[MONTH4] April \*[MONTH5] May \*[MONTH6] June \*[MONTH7] July \*[MONTH8] August \*[MONTH9] September \*[MONTH10] October \*[MONTH11] November \*[MONTH12] December ─────────────────────────────────── The default for ABSTRACT includes font selection escape sequences to set the word in italics. Headers and footers There are multiple ways to produce headers and footers. One is to de‐ fine the strings LH, CH, and RH to set the left, center, and right headers, respectively; and LF, CF, and RF to set the left, center, and right footers. This approach suffices for documents that do not dis‐ tinguish odd‐ and even‐numbered pages. Another method is to call macros that set headers or footers for odd‐ or even‐numbered pages. Each such macro takes a delimited argument separating the left, center, and right header or footer texts from each other. You can replace the neutral apostrophes (') shown below with any character not appearing in the header or footer text. These macros are Berkeley extensions. .OH 'left'center'right' .OF 'left'center'right' .EH 'left'center'right' .EF 'left'center'right' The OH and EH macros define headers for odd‐ (recto) and even‐ numbered (verso) pages, respectively; the OF and EF macros de‐ fine footers for them. With either method, a percent sign % in header or footer text is re‐ placed by the current page number. By default, ms places no header on a page numbered “1” (regardless of its number format). .P1 Typeset the header even on page 1. To be effective, this macro must be called before the header trap is sprung on any page num‐ bered “1”. This is a Berkeley extension. For even greater flexibility, ms permits redefinition of the macros called when the page header and footer traps are sprung. PT (“page trap”) is called by ms when the header is to be written, and BT (“bot‐ tom trap”) when the footer is to be. The groff page location trap that ms sets up to format the header also calls the (normally undefined) HD macro after .PT; you can define .HD if you need additional processing after setting the header. The HD hook is a Berkeley extension. Any such macros you (re)define must implement any desired specialization for odd‐, even‐, or first numbered pages. Tab stops Use the ta request to set tab stops as needed. .TA Reset the tab stops to the ms default (every 5 ens). Redefine this macro to create a different set of default tab stops. Margins Control margins using the registers summarized in the “Margins” portion of the table in section “Document control settings” above. There is no setting for the right margin; the combination of page offset \n[PO] and line length \n[LL] determines it. Multiple columns ms can set text in as many columns as reasonably fit on the page. The following macros force a page break if a multi‐column layout is active when they are called. \n[MINGW] is the default minimum gutter width; it is a GNU extension. When multiple columns are in use, keeps and the HORPHANS and PORPHANS registers work with respect to column breaks in‐ stead of page breaks. .1C Arrange page text in a single column (the default). .2C Arrange page text in two columns. .MC [column‐width [gutter‐width]] Arrange page text in multiple columns. If you specify no argu‐ ments, it is equivalent to the 2C macro. Otherwise, column‐ width is the width of each column and gutter‐width is the mini‐ mum distance between columns. Creating a table of contents Define an entry to appear in the table of contents by bracketing its text between calls to the XS and XE macros. A typical application is to call them immediately after NH or SH and repeat the heading text within them. The XA macro, used within .XS/.XE pairs, supplements an entry—for instance, when it requires multiple output lines, whether be‐ cause a heading is too long to fit or because style dictates that page numbers not be repeated. You may wish to indent the text thus wrapped to correspond to its heading depth; this can be done in the entry text by prefixing it with tabs or horizontal motion escape sequences, or by providing a second argument to the XA macro. .XS and .XA automatically associate the page number where they are called with the text following them, but they accept arguments to override this behavior. At the end of the document, call TC or PX to emit the table of contents; .TC re‐ sets the page number to i (Roman numeral one), and then calls PX. All of these macros are Berkeley extensions. .XS [page‐number] .XA [page‐number [indentation]] .XE Begin, supplement, and end a table of contents entry. Each en‐ try is associated with page‐number (otherwise the current page number); a page‐number of “no” prevents a leader and page number from being emitted for that entry. Use of .XA within .XS/.XE is optional; it can be repeated. If indentation is present, a sup‐ plemental entry is indented by that amount; ens are assumed if no unit is indicated. Text on input lines between .XS and .XE is stored for later recall by .PX. .PX [no] Switch to single‐column layout. Unless “no” is specified, cen‐ ter and interpolate \*[TOC] in bold and two points larger than the body text. Emit the table of contents entries. .TC [no] Set the page number to 1, the page number format to lowercase Roman numerals, and call PX (with a “no” argument, if present). The remaining features in this subsection are GNU extensions. groff ms obviates the need to repeat heading text after .XS calls. Call .XN and .XH after .NH and .SH, respectively. Text to be appended to the for‐ matted section heading, but not to appear in the table of contents en‐ try, can follow these calls. .XN heading‐text Format heading‐text and create a corresponding table of contents entry; the indentation is computed from the depth argument of the preceding NH call. .XH depth heading‐text As .XN, but use depth to determine the indentation. groff ms encourages customization of table of contents entry produc‐ tion. (Re‐)define any of the following macros as desired. .XN-REPLACEMENT heading‐text .XH-REPLACEMENT depth heading‐text These hook macros implement .XN and .XH, and call XN-INIT and XH-INIT, respectively, then call XH-UPDATE-TOC with the argu‐ ments given them. .XH-INIT .XN-INIT These hook macros do nothing by default. .XH-UPDATE-TOC depth heading‐text Bracket heading‐text with XS and XE calls, indenting it by 2 ens per level of depth beyond the first. You can customize the style of the leader that bridges each table of contents entry with its page number; define the TC-LEADER special char‐ acter by using the char request. A typical leader combines the dot glyph “.” with a horizontal motion escape sequence to spread the dots. The width of the page number field is stored in the TC-MARGIN register. Differences from AT&T ms The groff ms macros are an independent reimplementation, using no AT&T code. Since they take advantage of the extended features of groff, they cannot be used with AT&T troff. groff ms supports features de‐ scribed above as Berkeley and Tenth Edition Research Unix extensions, and adds several of its own. • The internals of groff ms differ from the internals of AT&T ms. Documents that depend upon implementation details of AT&T ms may not format properly with groff ms. Such details include macros whose function was not documented in the AT&T ms manual (“Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff”, M. E. Lesk, Bell Laboratories, 1978). • The error‐handling policy of groff ms is to detect and report er‐ rors, rather than to ignore them silently. • Tenth Edition Research Unix supported P1/P2 macros to bracket code examples; groff ms does not. • groff ms does not work in GNU troff’s AT&T compatibility mode. If loaded when that mode is enabled, it aborts processing with a diag‐ nostic message. • Multiple line spacing is not supported. Use a larger vertical spac‐ ing instead. • groff ms uses the same header and footer defaults in both nroff and troff modes as AT&T ms does in troff mode; AT&T’s default in nroff mode is to put the date, in U.S. traditional format (e.g., “January 1, 2021”), in the center footer (the CF string). • Many groff ms macros, including those for paragraphs, headings, and displays, cause a reset of paragraph rendering parameters, and may change the indentation; they do so not by incrementing or decrement‐ ing it, but by setting it absolutely. This can cause problems for documents that define additional macros of their own that try to ma‐ nipulate indentation. Use .RS and .RE instead of the in request. • AT&T ms interpreted the values of the registers PS and VS in points, and did not support the use of scaling units with them. groff ms interprets values of the registers PS, VS, FPS, and FVS, equal to or larger than 1,000 (one thousand) as decimal fractions multiplied by 1,000. (Register values are converted to and stored as basic units. See “Measurements” in the groff Texinfo manual or in groff(7)). This threshold makes use of a scaling unit with these parameters practical for high‐resolution devices while preserving backward compatibility. It also permits expression of non‐integral type sizes. For example, “groff -rPS=10.5p” at the shell prompt is equivalent to placing “.nr PS 10.5p” at the beginning of the docu‐ ment. • AT&T ms’s AU macro supported arguments used with some document types; groff ms does not. • Right‐aligned displays are available. The AT&T ms manual observes that “it is tempting to assume that “.DS R” will right adjust lines, but it doesn’t work”. In groff ms, it does. • To make groff ms use the default page offset (which also specifies the left margin), the PO register must stay undefined until the first ms macro is called. This implies that \n[PO] should not be used early in the document, unless it is changed also: accessing an undefined register automatically defines it. • groff ms supports the PN register, but it is not necessary; you can access the page number via the usual % register and invoke the af request to assign a different format to it if desired. (If you re‐ define the ms PT macro and desire special treatment of certain page numbers—like “1”—you may need to handle a non‐Arabic page number format, as groff ms’s .PT does; see the macro package source. groff ms aliases the PN register to %.) • The AT&T ms manual documents registers CW and GW as setting the de‐ fault column width and “intercolumn gap”, respectively, and which applied when .MC was called with fewer than two arguments. groff ms instead treats .MC without arguments as synonymous with .2C; there is thus no occasion for a default column width register. Further, the MINGW register and the second argument to .MC specify a minimum space between columns, not the fixed gutter width of AT&T ms. • The AT&T ms manual did not document the QI register; Berkeley and groff ms do. • The register GS is set to 1 by the groff ms macros, but is not used by the AT&T ms package. Documents that need to determine whether they are being formatted with groff ms or another implementation should test this register. Unix Version 7 macros not implemented by groff ms Several macros described in the Unix Version 7 ms documentation are unimplemented by groff ms because they are specific to the requirements of documents produced internally by Bell Laboratories, some of which also require a glyph for the Bell System logo that groff does not sup‐ port. These macros implemented several document type formats (EG, IM, MF, MR, TM, TR), were meaningful only in conjunction with the use of certain document types (AT, CS, CT, OK, SG), stored the postal ad‐ dresses of Bell Labs sites (HO, IH, MH, PY, WH), or lacked a stable de‐ finition over time (UX). Legacy features groff ms retains some legacy features solely to support formatting of historical documents; contemporary ones should not use them because they can render poorly. See groff_char(7) instead. AT&T ms accent mark strings AT&T ms defined accent mark strings as follows. String Description ────────────────────────────────────────────────────── \*['] Apply acute accent to subsequent glyph. \*[`] Apply grave accent to subsequent glyph. \*[:] Apply dieresis (umlaut) to subsequent glyph. \*[^] Apply circumflex accent to subsequent glyph. \*[~] Apply tilde accent to subsequent glyph. \*[C] Apply caron to subsequent glyph. \*[,] Apply cedilla to subsequent glyph. Berkeley ms accent mark and glyph strings Berkeley ms offered an AM macro; calling it redefined the AT&T accent mark strings (except for \*C), applied them to the preceding glyph, and defined additional strings, some for spacing glyphs. .AM Enable alternative accent mark and glyph‐producing strings. String Description ─────────────────────────────────────────────────────────────── \*['] Apply acute accent to preceding glyph. \*[`] Apply grave accent to preceding glyph. \*[:] Apply dieresis (umlaut) to preceding glyph. \*[^] Apply circumflex accent to preceding glyph. \*[~] Apply tilde accent to preceding glyph. \*[,] Apply cedilla to preceding glyph. \*[/] Apply stroke (slash) to preceding glyph. \*[v] Apply caron to preceding glyph. \*[_] Apply macron to preceding glyph. \*[.] Apply underdot to preceding glyph. \*[o] Apply ring accent to preceding glyph. ─────────────────────────────────────────────────────────────── \*[?] Interpolate inverted question mark. \*[!] Interpolate inverted exclamation mark. \*[8] Interpolate small letter sharp s. \*[q] Interpolate small letter o with hook accent (ogonek). \*[3] Interpolate small letter yogh. \*[d‐] Interpolate small letter eth. \*[D‐] Interpolate capital letter eth. \*[th] Interpolate small letter thorn. \*[TH] Interpolate capital letter thorn. \*[ae] Interpolate small ae ligature. \*[AE] Interpolate capital ae ligature. \*[oe] Interpolate small oe ligature. \*[OE] Interpolate capital oe ligature. Naming conventions The following conventions are used for names of macros, strings, and registers. External names available to documents that use the groff ms macros contain only uppercase letters and digits. Internally, the macros are divided into modules. Conventions for iden‐ tifier names are as follows. • Names used only within one module are of the form module*name. • Names used outside the module in which they are defined are of the form module@name. • Names associated with a particular environment are of the form environment:name; these are used only within the par module. • name does not have a module prefix. • Constructed names used to implement arrays are of the form array!index. Thus the groff ms macros reserve the following names: • Names containing the characters *, @, and :. • Names containing only uppercase letters and digits. Files /usr/local/share/groff/1.23.0/tmac/s.tmac implements the package. /usr/local/share/groff/1.23.0/tmac/refer-ms.tmac implements refer(1) support for ms. /usr/local/share/groff/1.23.0/tmac/ms.tmac is a wrapper enabling the package to be loaded with “groff -m ms”. Authors The GNU version of the ms macro package was written by James Clark and contributors. This document was written by Clark, Larry Kollar ⟨lkollar@despammed.com⟩, and G. Branden Robinson ⟨g.branden.robinson@ gmail.com⟩. See also A manual is available in source and rendered form. On your system, it may be compressed and/or available in additional formats. /usr/local/share/doc/groff-1.23.0/ms.ms /usr/local/share/doc/groff-1.23.0/ms.ps “Using groff with the ms Macro Package”; Larry Kollar and G. Branden Robinson. /usr/local/share/doc/groff-1.23.0/msboxes.ms /usr/local/share/doc/groff-1.23.0/msboxes.pdf “Using PDF boxes with groff and the ms macros”; Deri James. BOXSTART and BOXSTOP macros are available via the sboxes exten‐ sion package, enabling colored, bordered boxes when the pdf out‐ put device is used. Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1) groff 1.23.0 29 August 2023 groff_ms(7) ─────────────────────────────────────────────────────────────────────────────── groff_rfc1345(7) Miscellaneous Information Manual groff_rfc1345(7) Name groff_rfc1345 - special character names from RFC 1345 and Vim digraphs Description The file rfc1345.tmac defines special character escape sequences for groff(7) based on the glyph mnemonics specified in RFC 1345 and the di‐ graph table of the text editor Vim. Each escape sequence translates to a Unicode code point, and will render correctly if the underlying font is a Unicode font that covers the code point. For example, “\[Rx]” is the “recipe” or “prescription take” symbol, and maps to the code point U+211E. groff lets you write it as “\[u211E]”, but “\[Rx]” is more mnemonic. For a list of the glyph names provided, please see the file rfc1345.tmac, which contains definitions of the form .char \[Rx] \[u211E] \" PRESCRIPTION TAKE where .char’s first argument defines a groff special character escape sequence with a mnemonic glyph name, its second argument is a special character escape sequence based on the code point, and the comment de‐ scribes the glyph defined. The RFC 1345 glyph names cover a wide range of Unicode code points, in‐ cluding supplemental Latin, Greek, Cyrillic, Hebrew, Arabic, Hiragana, Katakana, and Bopomofo letters, punctuation, math notation, currency symbols, industrial and entertainment icons, and box‐drawing symbols. The Vim digraph table is practically a subset of RFC 1345 (being lim‐ ited to two‐character mnemonics), but, as a newer implementation, adds four mnemonics not specified in the RFC (the horizontal ellipsis, the Euro sign, and two mappings for the rouble sign). These have also been added to rfc1345.tmac. rfc1345.tmac contains a total of 1,696 glyph names. It is not an error to load rfc1345.tmac if your font does not have all the glyphs, as long as it contains the glyphs that you actually use in your document. The RFC 1345 mnemonics are not identical in every case to the mappings for special character glyph names that are built in to groff; for exam‐ ple, “\[<<]” means the “much less than” sign (U+226A) when rfc1345.tmac is not loaded and this special character is not otherwise defined by a document or macro package. rfc1345.tmac redefines “\[<<]” to the “left‐pointing double angle quotation mark” (U+00AB). See groff_char(7) for the full list of predefined special character escape sequences. Usage Load the rfc1345.tmac file. This can be done by either adding “.mso rfc1345.tmac” to your document before the first use of any of the glyph names the macro file defines, or by using the troff(1) option “-m rfc1345” from the shell. Bugs As the groff Texinfo manual notes, “[o]nly the current font is checked for ligatures and kerns; neither special fonts nor entities defined with the char request (and its siblings) are taken into account.” Many of the characters defined in rfc1345.tmac are accented Latin letters, and will be affected by this deficiency, producing subpar typography ⟨https://savannah.gnu.org/bugs/?59932⟩. Files /usr/local/share/groff/1.23.0/tmac/rfc1345.tmac implements the character mappings. Authors rfc1345.tmac was contributed by Dorai Sitaram ⟨ds26gte@yahoo.com⟩. See also RFC 1345 ⟨https://tools.ietf.org/html/rfc1345⟩, by Keld Simonsen, June 1992. The Vim digraph table can be listed using the vim(1) command “:help digraph-table”. groff_char(7) groff 1.23.0 29 August 2023 groff_rfc1345(7) ─────────────────────────────────────────────────────────────────────────────── groff_trace(7) Miscellaneous Information Manual groff_trace(7) Name groff_trace - macros for debugging GNU roff documents Synopsis groff -m trace [option ...] [file ...] Description trace is a macro package for the groff(7) document formatting system, designed as an aid for debugging documents written in its language. It issues a message to the standard error stream upon entry to and exit from each macro call. This can ease the process of isolating errors in macro definitions. Activate the package by specifying the command‐line option “-m trace” to the formatter program (often groff(1)). You can achieve finer con‐ trol by including the macro file within the document; invoke the mso request, as in “.mso trace.tmac”. Only macros that are defined after this invocation are traced. If the trace-full register is set to a true value, as with the command‐line option “-r trace-full=1”, register and string assignments, along with some other requests, are traced also. If another macro package should be traced as well, specify it after “-m trace” on the command line. The macro file trace.tmac is unusual because it does not contain any macros to be called by a user. Instead, groff’s macro definition and alteration facilities are wrapped such that they display diagnostic messages. Limitations Because trace.tmac wraps the de request (and its cousins), macro argu‐ ments are expanded one level more. This causes problems if an argument uses four or more backslashes to delay interpretation of an escape se‐ quence. For example, the macro call .foo \\\\n[bar] normally passes “\\n[bar]” to macro “foo”, but with de redefined, it passes “\n[bar]” instead. The solution to this problem is to use groff’s \E escape sequence, an escape character that is not interpreted in copy mode. .foo \En[bar] Examples We will illustrate trace.tmac using the shell’s “here document” feature to supply groff with a document on the standard input stream. Since we are interested only in diagnostic messages appearing on the standard error stream, we discard the formatted output by redirecting the stan‐ dard output stream to /dev/null. Observing nested macro calls Macro calls can be nested, even with themselves. Tracing recurses along with them; this feature can help to detangle complex call stacks. $ cat < /dev/null .de countdown . nop \\$1 . nr count (\\$1 ‐ 1) . if \\n[count] .countdown \\n[count] .. .countdown 3 blastoff EOF *** .de countdown *** de trace enter: .countdown "3" *** de trace enter: .countdown "2" *** de trace enter: .countdown "1" *** trace exit: .countdown "1" *** trace exit: .countdown "2" *** trace exit: .countdown "3" Tracing with the mso request Now let us activate tracing within the document, not with a command‐ line option. We might do this when using a macro package like ms or mom, where we may not want to be distracted by traces of macros we didn’t write. $ cat < /dev/null .LP This is my introductory paragraph. .mso trace.tmac .de Mymac .. .Mymac .PP Let us review the existing literature. EOF *** .de Mymac *** de trace enter: .Mymac *** trace exit: .Mymac As tracing was not yet active when the macros “LP” and “PP” were de‐ fined (by s.tmac), their calls were not traced; contrast with the macro “Mymac”. Files /usr/local/share/groff/1.23.0/tmac/trace.tmac implements the package. Authors trace.tmac was written by James Clark. This document was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩ and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”. groff(1) gives an overview of the groff document formatting system. troff(1) supplies details of the -m command‐line option. groff_tmac(5) offers a survey of groff macro packages. groff(7) is a reference manual for the groff language. groff 1.23.0 29 August 2023 groff_trace(7) ─────────────────────────────────────────────────────────────────────────────── groff_www(7) Miscellaneous Information Manual groff_www(7) Name groff_www - GNU roff macros for authoring web pages Synopsis groff -m www [option ...] [file ...] Description This manual page describes the GNU www macro package, which is part of the groff(7) document formatting system. This macro file is automati‐ cally loaded by the default troffrc file when the formatter (usually groff(1)) is called with either of the options -Thtml or -Txhtml. To see hyperlinks in action, format this man page using one of those op‐ tions. This document is a basic guide; the HTML output driver (grohtml) re‐ mains in an alpha state. It has been included with the distribution to encourage testing. Here is a summary of the functions found in this macro set. .JOBNAME split output into multiple files .HX automatic heading level cut off .BCL specify colours on a web page .BGIMG specify background image .URL create a URL using two parameters .FTP create an FTP reference .MTO create an HTML email address .TAG generate an HTML name .IMG include an image file .PIMG include PNG image .MPIMG place PNG on the margin and wrap text around it .HnS begin heading .HnE end heading .LK emit automatically collected links. .HR produce a horizontal rule .NHR suppress automatic generation of rules. .HTL only generate HTML title .HEAD add data to block .ULS unorder list begin .ULE unorder list end .OLS ordered list begin .OLE ordered list end .DLS definition list begin .DLE definition list end .LI insert a list item .DC generate a drop capital .HTML pass an HTML raw request to the device driver .CDS code example begin .CDE code example end .ALN place links on left of main text. .LNS start a new two‐column table with links in the left. .LNE end the two‐column table. .LINKSTYLE initialize default URL attributes. Macros .JOBNAME filename Split output into multiple HTML files. A file is split whenever a .SH or .NH 1 is encountered. Its argument is the file stem name for future output files. This option is equivalent to grohtml’s -j option. .HX n Specify the cut off depth when generating links from section headings. For example, a parameter of 2 would cause grohtml to generate a list of links for .NH 1 and .NH 2 but not for .NH 3. Whereas .HX 0 tells grohtml that no heading links should be created at all. Another method for turning automatic headings off is by issuing the command‐line switch -P-l to groff. .BCL foreground background active not‐visited visited This macro takes five parameters: foreground, background, active hypertext link, hypertext link not yet visited, and visited hy‐ pertext link colour. .BGIMG imagefile the only parameter to this macro is the background image file. .URL url [description] [after] generates a URL using either one, two, or three arguments. The first parameter is the actual URL, the second is the name of the link, and the third is optional stuff to be printed immediately afterwards. If description and after are absent then the URL becomes the anchor text. Hyphenation is disabled while printing the actual URL; explicit breakpoints should be inserted with the \: escape sequence. Here is how to encode foo ⟨http://foo .org/⟩: .URL http://\:foo\:.org/ foo : If this is processed by a device other than -Thtml or -Txhtml it appears as: foo ⟨http://foo.org⟩: The URL macro can be of any type; for example, we can reference Eric Raymond’s pic guide ⟨pic.html⟩ by: .URL pic\:.html "Eric Raymond's pic guide" .MTO address [description] [after] Generate an email HTML reference. The first argument is manda‐ tory as the email address. The optional second argument is the text you see in your browser. If an empty argument is given, address is used instead. An optional third argument is stuff printed immediately afterwards. Hyphenation is disabled while printing the actual email address. For example, Joe User ⟨joe@ user.org⟩ can be achieved by the following macro: .MTO joe@user.org "Joe User" All URLs currently are treated as consuming no textual space in groff. This could be considered as a bug since it causes some problems. To circumvent this, www.tmac inserts a zero‐width character which expands to a harmless space (only if run with -Thtml or -Txhtml). .FTP url [description] [after] indicates that data can be obtained via FTP. The first argument is the URL and the second is the browser text. A third argu‐ ment, similar to the macros above, is intended for stuff printed immediately afterwards. The second and the third parameter are optional. Hyphenation is disabled while printing the actual URL. As an example, here is the location of the GNU FTP server ⟨ftp://ftp.gnu.org/⟩. The macro example above can be specified as: .FTP ftp://\:ftp\:.gnu\:.org/ "GNU FTP server" . .TAG name Generates an HTML name tag from its argument. This can then be referenced using the URL ⟨#URL⟩ macro. As you can see, you must precede the tag name with # since it is a local reference. This link was achieved via placing a TAG in the URL description above; the source looks like this: .TP .B URL generates .TAG URL a URL using either two or three arguments. ... .IMG [-R|-L|-C] filename [width] [height] Include a picture into the document. The first argument is the horizontal location: right, left, or center (-R, -L, or -C). Alignment is centered by default (-C). The second argument is the filename. The optional third and fourth arguments are the width and height. If the width is absent it defaults to 1 inch. If the height is absent it defaults to the width. This maps onto an HTML img tag. If you are including a PNG image then it is advisable to use the PIMG macro. .PIMG [-R|-L|-C] filename [width [height]] Include an image in PNG format. This macro takes exactly the same parameters as the IMG macro; it has the advantage of work‐ ing with PostScript and HTML devices also since it can automati‐ cally convert the image into the EPS format, using the following programs of the netpbm package: pngtopnm, pnmcrop, and pnmtops. If the document isn’t processed with -Thtml or -Txhtml it is necessary to use the -U option of groff. .MPIMG [-R|-L] [-G gap] filename [width [height]] Place a PNG image on the margin and wrap text around it. The first parameters are optional. The alignment: left or right (-L or -R) specifies the margin where the picture is placed at. The default alignment is left (-L). Optionally, -G gap can be used to arrange a gap between the picture and the text that wraps around it. The default gap width is zero. The first non‐optional argument is the filename. The optional following arguments are the width and height. If the width is absent it defaults to 1 inch. If the height is absent it de‐ faults to the width. Example: .MPIMG -L -G 2c foo.png 3c 1.5c The height and width may also be given as percentages. The PostScript device calculates the width from the .l register and the height from the .p register. For example: .MPIMG -L -G 2c foo.png 15% .HnS n Begin heading. The numeric heading level n is specified by the first parameter. Use this macro if your headings contain URL, FTP or MTO macros. Example: .HnS 1 .HR GNU Troff .URL https://\:www\:.gnu\:.org/\:software/\:groff/ \[em]a .URL http://www\:.gnu\:.org/ GNU project. .HR .HnE In this case you might wish to disable automatic links to head‐ ings. This can be done via -P-l from the command line. .HnE End heading. .LK Force grohtml to place the automatically generated links at this position. .HR Generate a full‐width horizontal rule for -Thtml and -Txhtml. No effect for all other devices. .NHR Suppress generation of the top and bottom rules which grohtml emits by default. .HTL Generate an HTML title only. This differs from the TL macro of the ms macro package which generates both an HTML title and an

heading. Use it to provide an HTML title as search engine fodder but a graphic title in the document. The macro termi‐ nates when a space or break is seen (.sp, .br). .HEAD Add arbitrary HTML data to the block. Ignored if not processed with -Thtml or -Txhtml. Example: .HEAD "" .HTML All text after this macro is treated as raw HTML. If the docu‐ ment is processed without -Thtml or -Txhtml then the macro is ignored. Internally, this macro is used as a building block for other higher‐level macros. For example, the BGIMG macro is defined as .de BGIMG . HTML .. .DC l text [color] Produce a drop capital. The first parameter is the letter to be dropped and enlarged, the second parameter text is the adjoining text whose height the first letter should not exceed. The op‐ tional third parameter is the color of the dropped letter. It defaults to black. .CDS Start displaying a code section in constant width font. .CDE End code display .ALN [color] [percentage] Place section heading links automatically to the left of the main text. The color argument is optional and if present indi‐ cates which HTML background color is to be used under the links. The optional percentage indicates the amount of width to devote to displaying the links. The default values are #eeeeee and 30 for color and percentage width, respectively. This macro should only be called once at the beginning of the document. After calling this macro each section heading emits an HTML table con‐ sisting of the links in the left and the section text on the right. .LNS Start a new two‐column table with links in the left column. This can be called if the document has text before the first .SH and if .ALN is used. Typically this is called just before the first paragraph and after the main title as it indicates that text after this point should be positioned to the right of the left‐hand navigational links. .LNE End a two‐column table. This should be called at the end of the document if .ALN was used. .LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ] Initialize default URL attributes to be used if this macro set is not used with the HTML device. The macro set initializes it‐ self with the following call .LINKSTYLE blue CR \[la] \[ra] but these values will be superseded by a user call to LINKSTYLE. Section heading links By default grohtml generates links to all section headings and places these at the top of the HTML document. (See LINKS ⟨#LK⟩ for details of how to switch this off or alter the position). Limitations of grohtml tbl(1) tables are rendered as PNG images. Paul DuBois’s approach with tblcvt(1), part of the troffcvt distribution ⟨http://www.snake.net/ software/troffcvt/⟩, should be explored. Files /usr/local/share/groff/1.23.0/tmac/www.tmac Authors The www macro package was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩, with additions by Werner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@web.de⟩. See also groff(1), troff(1), grohtml(1), netpbm(1) groff 1.23.0 29 August 2023 groff_www(7) ─────────────────────────────────────────────────────────────────────────────── roff(7) Miscellaneous Information Manual roff(7) Name roff - concepts and history of roff typesetting Description The term roff denotes a family of document formatting systems known by names like troff, nroff, and ditroff. A roff system consists of an in‐ terpreter for an extensible text formatting language and a set of pro‐ grams for preparing output for various devices and file formats. Unix‐ like operating systems often distribute a roff system. The manual pages on Unix systems (“man pages”) and bestselling books on software engineering, including Brian Kernighan and Dennis Ritchie’s The C Pro‐ gramming Language and W. Richard Stevens’s Advanced Programming in the Unix Environment have been written using roff systems. GNU roff—groff— is arguably the most widespread roff implementation. Below we present typographical concepts that form the background of all roff implementations, narrate the development history of some roff sys‐ tems, detail the command pipeline managed by groff(1), survey the for‐ matting language, suggest tips for editing roff input, and recommend further reading materials. Concepts roff input files contain text interspersed with instructions to control the formatter. Even in the absence of such instructions, a roff for‐ matter still processes its input in several ways, by filling, hyphenat‐ ing, breaking, and adjusting it, and supplementing it with inter‐sen‐ tence space. These processes are basic to typesetting, and can be con‐ trolled at the input document’s discretion. When a device‐independent roff formatter starts up, it obtains informa‐ tion about the device for which it is preparing output from the lat‐ ter’s description file (see groff_font(5)). An essential property is the length of the output line, such as “6.5 inches”. The formatter interprets plain text files employing the Unix line‐end‐ ing convention. It reads input a character at a time, collecting words as it goes, and fits as many words together on an output line as it can—this is known as filling. To a roff system, a word is any sequence of one or more characters that aren’t spaces or newlines. The excep‐ tions separate words. A roff formatter attempts to detect boundaries between sentences, and supplies additional inter‐sentence space between them. It flags cer‐ tain characters (normally “!”, “?”, and “.”) as potentially ending a sentence. When the formatter encounters one of these end‐of‐sentence characters at the end of an input line, or one of them is followed by two (unescaped) spaces on the same input line, it appends an inter‐word space followed by an inter‐sentence space in the output. The dummy character escape sequence \& can be used after an end‐of‐sentence char‐ acter to defeat end‐of‐sentence detection on a per‐instance basis. Normally, the occurrence of a visible non‐end‐of‐sentence character (as opposed to a space or tab) immediately after an end‐of‐sentence charac‐ ter cancels detection of the end of a sentence. However, several char‐ acters are treated transparently after the occurrence of an end‐of‐sen‐ tence character. That is, a roff does not cancel end‐of‐sentence de‐ tection when it processes them. This is because such characters are often used as footnote markers or to close quotations and parentheti‐ cals. The default set is ", ', ), ], *, \[dg], \[dd], \[rq], and \[cq]. The last four are examples of special characters, escape se‐ quences whose purpose is to obtain glyphs that are not easily typed at the keyboard, or which have special meaning to the formatter (like \). When an output line is nearly full, it is uncommon for the next word collected from the input to exactly fill it—typically, there is room left over only for part of the next word. The process of splitting a word so that it appears partially on one line (with a hyphen to indi‐ cate to the reader that the word has been broken) with its remainder on the next is hyphenation. Hyphenation points can be manually specified; groff also uses a hyphenation algorithm and language‐specific pattern files to decide which words can be hyphenated and where. Hyphenation does not always occur even when the hyphenation rules for a word allow it; it can be disabled, and when not disabled there are several parame‐ ters that can prevent it in certain circumstances. Once an output line is full, the next word (or remainder of a hyphen‐ ated one) is placed on a different output line; this is called a break. In this document and in roff discussions generally, a “break” if not further qualified always refers to the termination of an output line. When the formatter is filling text, it introduces breaks automatically to keep output lines from exceeding the configured line length. After an automatic break, a roff formatter adjusts the line if applicable (see below), and then resumes collecting and filling text on the next output line. Sometimes, a line cannot be broken automatically. This usually does not happen with natural language text unless the output line length has been manipulated to be extremely short, but it can with specialized text like program source code. groff provides a means of telling the formatter where the line may be broken without hyphens. This is done with the non‐printing break point escape sequence \:. There are several ways to cause a break at a predictable location. A blank input line not only causes a break, but by default it also out‐ puts a one‐line vertical space (effectively a blank output line). Macro packages may discourage or disable this “blank line method” of paragraphing in favor of their own macros. A line that begins with one or more spaces causes a break. The spaces are output at the beginning of the next line without being adjusted (see below). Again, macro packages may provide other methods of producing indented paragraphs. Trailing spaces on text lines (see below) are discarded. The end of input causes a break. After the formatter performs an automatic break, it may then adjust the line, widening inter‐word spaces until the text reaches the right mar‐ gin. Extra spaces between words are preserved. Leading and trailing spaces are handled as noted above. Text can be aligned to the left or right margin only, or centered, using requests. A roff formatter translates horizontal tab characters, also called sim‐ ply “tabs”, in the input into movements to the next tab stop. These tab stops are by default located every half inch measured from the cur‐ rent position on the input line. With them, simple tables can be made. However, this method can be deceptive, as the appearance (and width) of the text in an editor and the results from the formatter can vary greatly, particularly when proportional typefaces are used. A tab character does not cause a break and therefore does not interrupt fill‐ ing. The formatter provides facilities for sophisticated table compo‐ sition; there are many details to track when using the “tab” and “field” low‐level features, so most users turn to the tbl(1) preproces‐ sor to lay out tables. Requests and macros A request is an instruction to the formatter that occurs after a con‐ trol character, which is recognized at the beginning of an input line. The regular control character is a dot “.”. Its counterpart, the no‐ break control character, a neutral apostrophe “'”, suppresses the break implied by some requests. These characters were chosen because it is uncommon for lines of text in natural languages to begin with them. If you require a formatted period or apostrophe (closing single quotation mark) where the formatter is expecting a control character, prefix the dot or neutral apostrophe with the dummy character escape sequence, “\&”. An input line beginning with a control character is called a control line. Every line of input that is not a control line is a text line. Requests often take arguments, words (separated from the request name and each other by spaces) that specify details of the action the for‐ matter is expected to perform. If a request is meaningless without ar‐ guments, it is typically ignored. Of key importance are the requests that define macros. Macros are invoked like requests, enabling the re‐ quest repertoire to be extended or overridden. A macro can be thought of as an abbreviation you can define for a col‐ lection of control and text lines. When the macro is called by giving its name after a control character, it is replaced with what it stands for. The process of textual replacement is known as interpolation. Interpolations are handled as soon as they are recognized, and once performed, a roff formatter scans the replacement for further requests, macro calls, and escape sequences. In roff systems, the “de” request defines a macro. Page geometry roff systems format text under certain assumptions about the size of the output medium, or page. For the formatter to correctly break a line it is filling, it must know the line length, which it derives from the page width. For it to decide whether to write an output line to the current page or wait until the next one, it must know the page length. A device’s resolution converts practical units like inches or centimeters to basic units, a convenient length measure for the output device or file format. The formatter and output driver use basic units to reckon page measurements. The device description file defines its resolution and page dimensions (see groff_font(5)). A page is a two‐dimensional structure upon which a roff system imposes a rectangular coordinate system with its upper left corner as the ori‐ gin. Coordinate values are in basic units and increase down and to the right. Useful ones are therefore always positive and within numeric ranges corresponding to the page boundaries. While the formatter (and, later, output driver) is processing a page, it keeps track of its drawing position, which is the location at which the next glyph will be written, from which the next motion will be mea‐ sured, or where a geometric object will commence rendering. Notion‐ ally, glyphs are drawn from the text baseline upward and to the right. (groff does not yet support right‐to‐left scripts.) The text baseline is a (usually invisible) line upon which the glyphs of a typeface are aligned. A glyph therefore “starts” at its bottom‐left corner. If drawn at the origin, a typical letter glyph would lie partially or wholly off the page, depending on whether, like “g”, it features a de‐ scender below the baseline. Such a situation is nearly always undesirable. It is furthermore con‐ ventional not to write or draw at the extreme edges of the page. Therefore the initial drawing position of a roff formatter is not at the origin, but below and to the right of it. This rightward shift from the left edge is known as the page offset. (groff’s terminal out‐ put devices have page offsets of zero.) The downward shift leaves room for a text output line. Text is arranged on a one‐dimensional lattice of text baselines from the top to the bottom of the page. Vertical spacing is the distance between adjacent text baselines. Typographic tradition sets this quan‐ tity to 120% of the type size. The initial vertical drawing position is one unit of vertical spacing below the page top. Typographers term this unit a vee. Vertical spacing has an impact on page‐breaking decisions. Generally, when a break occurs, the formatter moves the drawing position to the next text baseline automatically. If the formatter were already writ‐ ing to the last line that would fit on the page, advancing by one vee would place the next text baseline off the page. Rather than let that happen, roff formatters instruct the output driver to eject the page, start a new one, and again set the drawing position to one vee below the page top; this is a page break. When the last line of input text corresponds to the last output line that fits on the page, the break caused by the end of input will also break the page, producing a useless blank one. Macro packages keep users from having to confront this difficulty by setting “traps”; more‐ over, all but the simplest page layouts tend to have headers and foot‐ ers, or at least bear vertical margins larger than one vee. Other language elements Escape sequences start with the escape character, a backslash \, and are followed by at least one additional character. They can appear anywhere in the input. With requests, the escape and control characters can be changed; fur‐ ther, escape sequence recognition can be turned off and back on. Strings store character sequences. In groff, they can be parameterized as macros can. Registers store numerical values, including measurements. The latter are generally in basic units; scaling units can be appended to numeric expressions to clarify their meaning when stored or interpolated. Some read‐only predefined registers interpolate text. Fonts are identified either by a name or by a mounting position (a non‐ negative number). Four styles are available on all devices. R is “ro‐ man”: normal, upright text. B is bold, an upright typeface with a heavier weight. I is italic, a face that is oblique on typesetter out‐ put devices and usually underlined instead on terminal devices. BI is bold‐italic, combining both of the foregoing style variations. Type‐ setting devices group these four styles into families of text fonts; they also typically offer one or more special fonts that provide un‐ styled glyphs; see groff_char(7). groff supports named colors for glyph rendering and drawing of geomet‐ ric objects. Stroke and fill colors are distinct; the stroke color is used for glyphs. Glyphs are visual representation forms of characters. In groff, the distinction between those two elements is not always obvious (and a full discussion is beyond our scope). In brief, “A” is a character when we consider it in the abstract: to make it a glyph, we must select a typeface with which to render it, and determine its type size and color. The formatting process turns input characters into output glyphs. A few characters commonly seen on keyboards are treated spe‐ cially by the roff language and may not look correct in output if used unthinkingly; they are the (double) quotation mark ("), the neutral apostrophe ('), the minus sign (-), the backslash (\), the caret or circumflex accent (^), the grave accent (`), and the tilde (~). All of these and more can be produced with special character escape sequences; see groff_char(7). groff offers streams, identifiers for writable files, but for security reasons this feature is disabled by default. A further few language elements arise as page layouts become more so‐ phisticated and demanding. Environments collect formatting parameters like line length and typeface. A diversion stores formatted output for later use. A trap is a condition on the input or output, tested auto‐ matically by the formatter, that is associated with a macro, calling it when that condition is fulfilled. Footnote support often exercises all three of the foregoing features. A simple implementation might work as follows. A pair of macros is de‐ fined: one starts a footnote and the other ends it. The author calls the first macro where a footnote marker is desired. The macro estab‐ lishes a diversion so that the footnote text is collected at the place in the body text where its corresponding marker appears. An environ‐ ment is created for the footnote so that it is set at a smaller type‐ face. The footnote text is formatted in the diversion using that envi‐ ronment, but it does not yet appear in the output. The document author calls the footnote end macro, which returns to the previous environment and ends the diversion. Later, after much more body text in the docu‐ ment, a trap, set a small distance above the page bottom, is sprung. The macro called by the trap draws a line across the page and emits the stored diversion. Thus, the footnote is rendered. History Computer‐driven document formatting dates back to the 1960s. The roff system is intimately connected with Unix, but its origins lie with the earlier operating systems CTSS, GECOS, and Multics. The predecessor—RUNOFF roff’s ancestor RUNOFF was written in the MAD language by Jerry Saltzer to prepare his Ph.D. thesis on the Compatible Time Sharing System (CTSS), a project of the Massachusetts Institute of Technology (MIT). This program is referred to in full capitals, both to distinguish it from its many descendants, and because bits were expensive in those days; five‐ and six‐bit character encodings were still in widespread usage, and mixed‐case alphabetics in file names seen as a luxury. RUNOFF introduced a syntax of inlining formatting directives amid docu‐ ment text, by beginning a line with a period (an unlikely occurrence in human‐readable material) followed by a “control word”. Control words with obvious meaning like “.line length n” were supported as well as an abbreviation system; the latter came to overwhelm the former in popular usage and later derivatives of the program. A sample of control words from a RUNOFF manual of December 1966 ⟨http://web.mit.edu/Saltzer/www/ publications/ctss/AH.9.01.html⟩ was documented as follows (with the pa‐ rameter notation slightly altered). The abbreviations will be familiar to roff veterans. Abbreviation Control word .ad .adjust .bp .begin page .br .break .ce .center .in .indent n .ll .line length n .nf .nofill .pl .paper length n .sp .space [n] In 1965, MIT’s Project MAC teamed with Bell Telephone Laboratories and General Electric (GE) to inaugurate the Multics ⟨http://www.multicians .org⟩ project. After a few years, Bell Labs discontinued its partici‐ pation in Multics, famously prompting the development of Unix. Mean‐ while, Saltzer’s RUNOFF proved influential, seeing many ports and de‐ rivations elsewhere. In 1969, Doug McIlroy wrote one such reimplementation, adding exten‐ sions, in the BCPL language for a GE 645 running GECOS at the Bell Labs location in Murray Hill, New Jersey. In its manual, the control com‐ mands were termed “requests”, their two‐letter names were canonical, and the control character was configurable with a .cc request. Other familiar requests emerged at this time; no‐adjust (.na), need (.ne), page offset (.po), tab configuration (.ta, though it worked differ‐ ently), temporary indent (.ti), character translation (.tr), and auto‐ matic underlining (.ul; on RUNOFF you had to backspace and underscore in the input yourself). .fi to enable filling of output lines got the name it retains to this day. McIlroy’s program also featured a heuris‐ tic system for automatically placing hyphenation points, designed and implemented by Molly Wagner. It furthermore introduced numeric vari‐ ables, termed registers. By 1971, this program had been ported to Mul‐ tics and was known as roff, a name McIlroy attributes to Bob Morris, to distinguish it from CTSS RUNOFF. Unix and roff McIlroy’s roff was one of the first Unix programs. In Ritchie’s term, it was “transliterated” from BCPL to DEC PDP‐7 assembly language for the fledgling Unix operating system. Automatic hyphenation was managed with .hc and .hy requests, line spacing control was generalized with the .ls request, and what later roffs would call diversions were avail‐ able via “footnote” requests. This roff indirectly funded operating systems research at Murray Hill; AT&T prepared patent applications to the U.S. government with it. This arrangement enabled the group to ac‐ quire a PDP‐11; roff promptly proved equal to the task of formatting the manual for what would become known as “First Edition Unix”, dated November 1971. Output from all of the foregoing programs was limited to line printers and paper terminals such as the IBM 2471 (based on the Selectric line of typewriters) and the Teletype Corporation Model 37. Proportionally spaced type was unavailable. New roff and Typesetter roff The first years of Unix were spent in rapid evolution. The practicali‐ ties of preparing standardized documents like patent applications (and Unix manual pages), combined with McIlroy’s enthusiasm for macro lan‐ guages, perhaps created an irresistible pressure to make roff extensi‐ ble. Joe Ossanna’s nroff, literally a “new roff”, was the outlet for this pressure. By the time of Unix Version 3 (February 1973)—and still in PDP‐11 assembly language—it sported a swath of features now consid‐ ered essential to roff systems: definition of macros (.de), diversion of text thither (.di), and removal thereof (.rm); trap planting (.wh; “when”) and relocation (.ch; “change”); conditional processing (.if); and environments (.ev). Incremental improvements included assignment of the next page number (.pn); no‐space mode (.ns) and restoration of vertical spacing (.rs); the saving (.sv) and output (.os) of vertical space; specification of replacement characters for tabs (.tc) and lead‐ ers (.lc); configuration of the no‐break control character (.c2); shorthand to disable automatic hyphenation (.nh); a condensation of what were formerly six different requests for configuration of page “titles” (headers and footers) into one (.tl) with a length controlled separately from the line length (.lt); automatic line numbering (.nm); interactive input (.rd), which necessitated buffer‐flushing (.fl), and was made convenient with early program cessation (.ex); source file in‐ clusion in its modern form (.so; though RUNOFF had an “.append” control word for a similar purpose) and early advance to the next file argument (.nx); ignorable content (.ig); and programmable abort (.ab). Third Edition Unix also brought the pipe(2) system call, the explosive growth of a componentized system based around it, and a “filter model” that remains perceptible today. Equally importantly, the Bell Labs site in Murray Hill acquired a Graphic Systems C/A/T phototypesetter, and with it came the necessity of expanding the capabilities of a roff system to cope with a variety of proportionally spaced typefaces at multiple sizes. Ossanna wrote a parallel implementation of nroff for the C/A/T, dubbing it troff (for “typesetter roff”). Unfortunately, surviving documentation does not illustrate what requests were imple‐ mented at this time for C/A/T support; the troff(1) man page in Fourth Edition Unix (November 1973) does not feature a request list, unlike nroff(1). Apart from typesetter‐driven features, Unix Version 4 roffs added string definitions (.ds); made the escape character configurable (.ec); and enabled the user to write diagnostics to the standard error stream (.tm). Around 1974, empowered with multiple type sizes, ital‐ ics, and a symbol font specially commissioned by Bell Labs from Graphic Systems, Kernighan and Lorinda Cherry implemented eqn for typesetting mathematics. In the same year, for Fifth Edition Unix, Ossanna com‐ bined and reimplemented the two roffs in C, using that language’s pre‐ processor to generate both from a single source tree. Ossanna documented the syntax of the input language to the nroff and troff programs in the “Troff User’s Manual”, first published in 1976, with further revisions as late as 1992 by Kernighan. (The original version was entitled “Nroff/Troff User’s Manual”, which may partially explain why roff practitioners have tended to refer to it by its AT&T document identifier, “CSTR #54”.) Its final revision serves as the de facto specification of AT&T troff, and all subsequent implementors of roff systems have done so in its shadow. A small and simple set of roff macros was first used for the manual pages of Unix Version 4 and persisted for two further releases, but the first macro package to be formally described and installed was ms by Michael Lesk in Version 6. He also wrote a manual, “Typing Documents on the Unix System”, describing ms and basic nroff/troff usage, updat‐ ing it as the package accrued features. Sixth Edition additionally saw the debut of the tbl preprocessor for formatting tables, also by Lesk. For Unix Version 7 (January 1979), McIlroy designed, implemented, and documented the man macro package, introducing most of the macros de‐ scribed in groff_man(7) today, and edited volume 1 of the Version 7 manual using it. Documents composed using ms featured in volume 2, edited by Kernighan. Meanwhile, troff proved popular even at Unix sites that lacked a C/A/T device. Tom Ferrin of the University of California at San Francisco combined it with Allen Hershey’s popular vector fonts to produce vtroff, which translated troff’s output to the command language used by Versatec and Benson‐Varian plotters. Ossanna had passed away unexpectedly in 1977, and after the release of Version 7, with the C/A/T typesetter becoming supplanted by alternative devices such as the Mergenthaler Linotron 202, Kernighan undertook a revision and rewrite of troff to generalize its design. To implement this revised architecture, he developed the font and device description file formats and the page description language that remain in use to‐ day. He described these novelties in the article “A Typesetter‐inde‐ pendent TROFF”, last revised in 1982, and like the troff manual itself, it is widely known by a shorthand, “CSTR #97”. Kernighan’s innovations prepared troff well for the introduction of the Adobe PostScript language in 1982 and a vibrant market in laser print‐ ers with built‐in interpreters for it. An output driver for Post‐ Script, dpost, was swiftly developed. However, AT&T’s software licens‐ ing practices kept Ossanna’s troff, with its tight coupling to the C/A/T’s capabilities, in parallel distribution with device‐independent troff throughout the 1980s. Today, however, all actively maintained troffs follow Kernighan’s device‐independent design. groff—a free roff from GNU The most important free roff project historically has been groff, the GNU implementation of troff, developed by James Clark starting in 1989 and distributed under copyleft ⟨http://www.gnu.org/copyleft⟩ licenses, ensuring to all the availability of source code and the freedom to mod‐ ify and redistribute it, properties unprecedented in roff systems to that point. groff rapidly attracted contributors, and has served as a replacement for almost all applications of AT&T troff (exceptions in‐ clude mv, a macro package for preparation of viewgraphs and slides, and the ideal preprocessor, which produces diagrams from mathematical con‐ straints). Beyond that, it has added numerous features; see groff_diff(7). Since its inception and for at least the following three decades, it has been used by practically all GNU/Linux and BSD operating systems. groff continues to be developed, is available for almost all operating systems in common use (along with several obscure ones), and is free. These factors make groff the de facto roff standard today. Other free roffs In 2007, Caldera/SCO and Sun Microsystems, having acquired rights to AT&T Documenter’s Workbench (DWB) troff (a descendant of the Bell Labs code), released it under a free but GPL‐incompatible license. This im‐ plementation ⟨https://github.com/n-t-roff/DWB3.3⟩ was made portable to modern POSIX systems, and adopted and enhanced first by Gunnar Ritter and then Carsten Kunze to produce Heirloom Doctools troff ⟨https://github.com/n‐t‐roff/heirloom‐doctools⟩. In July 2013, Ali Gholami Rudi announced neatroff ⟨https://github.com/ aligrudi/neatroff⟩, a permissively licensed new implementation. Another descendant of DWB troff is part of Plan 9 from User Space ⟨https://9fans.github.io/plan9port/⟩. Since 2021, this troff has been available under permissive terms. Using roff When you read a man page, often a roff is the program rendering it. Some roff implementations provide wrapper programs that make it easy to use the roff system from the shell’s command line. These can be spe‐ cific to a macro package, like mmroff(1), or more general. groff(1) provides command‐line options sparing the user from constructing the long, order‐dependent pipelines familiar to AT&T troff users. Further, a heuristic program, grog(1), is available to infer from a document’s contents which groff arguments should be used to process it. The roff pipeline A typical roff document is prepared by running one or more processors in series, followed by a a formatter program and then an output driver (or “device postprocessor”). Commonly, these programs are structured into a pipeline; that is, each is run in sequence such that the output of one is taken as the input to the next, without passing through sec‐ ondary storage. (On non‐Unix systems, pipelines may have to be simu‐ lated with temporary files.) $ preproc1 < input‐file | preproc2 | ... | troff [option] ... \ | output‐driver Once all preprocessors have run, they deliver pure roff language input to the formatter, which in turn generates a document in a page descrip‐ tion language that is then interpreted by a postprocessor for viewing, printing, or further processing. Each program interprets input in a language that is independent of the others; some are purely descriptive, as with tbl(1) and roff output, and some permit the definition of macros, as with eqn(1) and roff in‐ put. Most roff input files employ the macros of a document formatting package, intermixed with instructions for one or more preprocessors, and seasoned with escape sequences and requests from the roff language. Some documents are simpler still, since their formatting packages dis‐ courage direct use of roff requests; man pages are a prominent example. Many features of the roff language are seldom needed by users; only au‐ thors of macro packages require a substantial command of them. Preprocessors A roff preprocessor is a program that, directly or ultimately, gener‐ ates output in the roff language. Typically, each preprocessor defines a language of its own that transforms its input into that for roff or another preprocessor. As an example of the latter, chem produces pic input. Preprocessors must consequently be run in an appropriate order; groff(1) handles this automatically for all preprocessors supplied by the GNU roff system. Portions of the document written in preprocessor languages are usually bracketed by tokens that look like roff macro calls. roff preprocessor programs transform only the regions of the document intended for them. When a preprocessor language is used by a document, its corresponding program must process it before the input is seen by the formatter, or incorrect rendering is almost guaranteed. GNU roff provides several preprocessors, including eqn, grn, pic, tbl, refer, and soelim. See groff(1) for a complete list. Other preproces‐ sors for roff systems are known. dformat depicts data structures; grap constructs statistical charts; and ideal draws diagrams using a constraint‐based language. Formatter programs A roff formatter transforms roff language input into a single file in a page description language, described in groff_out(5), intended for pro‐ cessing by a selected device. This page description language is spe‐ cialized in its parameters, but not its syntax, for the selected de‐ vice; the format is device‐independent, but not device‐agnostic. The parameters the formatter uses to arrange the document are stored in de‐ vice and font description files; see groff_font(5). AT&T Unix had two formatters—nroff for terminals, and troff for type‐ setters. Often, the name troff is used loosely to refer to both. When generalizing thus, groff documentation prefers the term “roff”. In GNU roff, the formatter program is always troff(1). Devices and output drivers To a roff system, a device is a hardware interface like a printer, a text or graphical terminal, or a standardized file format that unre‐ lated software can interpret. An output driver is a program that parses the output of troff and produces instructions specific to the device or file format it supports. An output driver might support mul‐ tiple devices, particularly if they are similar. The names of the devices and their driver programs are not standard‐ ized. Technological fashions evolve; the devices used for document preparation when AT&T troff was first written in the 1970s are no longer used in production environments. Device capabilities have tended to increase, improving resolution and font repertoire, and adding color output and hyperlinking. Further, to reduce file size and processing time, AT&T troff’s page description language placed low lim‐ its on the magnitudes of some quantities it could represent. Its Post‐ Script output driver, dpost(1), had a resolution of 720 units per inch; groff’s grops(1) uses 72,000. roff programming Documents using roff are normal text files interleaved with roff for‐ matting elements. The roff language is powerful enough to support ar‐ bitrary computation and it supplies facilities that encourage exten‐ sion. The primary such facility is macro definition; with this fea‐ ture, macro packages have been developed that are tailored for particu‐ lar applications. Macro packages Macro packages can have a much smaller vocabulary than roff itself; this trait combined with their domain‐specific nature can make them easy to acquire and master. The macro definitions of a package are typically kept in a file called name.tmac (historically, tmac.name). Find details on the naming and placement of macro packages in groff_tmac(5). A macro package anticipated for use in a document can be declared to the formatter by the command‐line option -m; see troff(1). It can al‐ ternatively be specified within a document using the mso request of the groff language; see groff(7). Well‐known macro packages include man for traditional man pages and mdoc for BSD‐style manual pages. Macro packages for typesetting books, articles, and letters include ms (from “manuscript macros”), me (named by a system administrator from the first name of its creator, Eric All‐ man), mm (from “memorandum macros”), and mom, a punningly named package exercising many groff extensions. See groff_tmac(5) for more. The roff formatting language The roff language provides requests, escape sequences, macro definition facilities, string variables, registers for storage of numbers or di‐ mensions, and control of execution flow. The theoretically minded will observe that a roff is not a mere markup language, but Turing‐complete. It has storage (registers), it can perform tests (as in conditional ex‐ pressions like “(\n[i] >= 1)”), its “if” and related requests alter the flow of control, and macro definition permits unbounded recursion. Requests and escape sequences are instructions, predefined parts of the language, that perform formatting operations, interpolate stored mater‐ ial, or otherwise change the state of the parser. The user can define their own request‐like elements by composing together text, requests, and escape sequences ad libitum. A document writer will not (usually) note any difference in usage for requests or macros; both are found on control lines. However, there is a distinction; requests take either a fixed number of arguments (sometimes zero), silently ignoring any ex‐ cess, or consume the rest of the input line, whereas macros can take a variable number of arguments. Since arguments are separated by spaces, macros require a means of embedding a space in an argument; in other words, of quoting it. This then demands a mechanism of embedding the quoting character itself, in case it is needed literally in a macro ar‐ gument. AT&T troff had complex rules involving the placement and repe‐ tition of the double quote to achieve both aims. groff cuts this knot by supporting a special character escape sequence for the neutral dou‐ ble quote, “\[dq]”, which never performs quoting in the typesetting language, but is simply a glyph, ‘"’. Escape sequences start with a backslash, “\”. They can appear almost anywhere, even in the midst of text on a line, and implement various features, including the insertion of special characters with “\(xx” or “\[xxx]”, break suppression at input line endings with “\c”, font changes with “\f”, type size changes with “\s”, in‐line comments with “\"”, and many others. Strings store text. They are populated with the ds request and inter‐ polated using the \* escape sequence. Registers store numbers and measurements. A register can be set with the request nr and its value can be retrieved by the escape sequence \n. File naming conventions The structure or content of a file name, beyond its location in the file system, is not significant to roff tools. roff documents employ‐ ing “full‐service” macro packages (see groff_tmac(5)) tend to be named with a suffix identifying the package; we thus see file names ending in .man, .ms, .me, .mm, and .mom, for instance. When installed, man pages tend to be named with the manual’s section number as the suffix. For example, the file name for this document is roff.7. Practice for “raw” roff documents is less consistent; they are sometimes seen with a .t suffix. Input conventions Since troff fills text automatically, it is common practice in the roff language to avoid visual composition of text in input files: the es‐ thetic appeal of the formatted output is what matters. Therefore, roff input should be arranged such that it is easy for authors and maintain‐ ers to compose and develop the document, understand the syntax of roff requests, macro calls, and preprocessor languages used, and predict the behavior of the formatter. Several traditions have accrued in service of these goals. • Follow sentence endings in the input with newlines to ease their recognition. It is frequently convenient to end text lines after colons and semicolons as well, as these typically precede independent clauses. Consider doing so after commas; they often occur in lists that become easy to scan when itemized by line, or constitute supple‐ ments to the sentence that are added, deleted, or updated to clarify it. Parenthetical and quoted phrases are also good candidates for placement on text lines by themselves. • Set your text editor’s line length to 72 characters or fewer; see the subsections below. This limit, combined with the previous item of advice, makes it less common that an input line will wrap in your text editor, and thus will help you perceive excessively long con‐ structions in your text. Recall that natural languages originate in speech, not writing, and that punctuation is correlated with pauses for breathing and changes in prosody. • Use \& after “!”, “?”, and “.” if they are followed by space, tab, or newline characters and don’t end a sentence. • In filled text lines, use \& before “.” and “'” if they are preceded by space, so that reflowing the input doesn’t turn them into control lines. • Do not use spaces to perform indentation or align columns of a table. Leading spaces are reliable when text is not being filled. • Comment your document. It is never too soon to apply comments to record information of use to future document maintainers (including your future self). The \" escape sequence causes troff to ignore the remainder of the input line. • Use the empty request—a control character followed immediately by a newline—to visually manage separation of material in input files. Many of the groff project’s own documents use an empty request be‐ tween sentences, after macro definitions, and where a break is ex‐ pected, and two empty requests between paragraphs or other requests or macro calls that will introduce vertical space into the document. You can combine the empty request with the comment escape sequence to include whole‐line comments in your document, and even “comment out” sections of it. An example sufficiently long to illustrate most of the above sugges‐ tions in practice follows. An arrow → indicates a tab character. .\" nroff this_file.roff | less .\" groff -T ps this_file.roff > this_file.ps →The theory of relativity is intimately connected with the theory of space and time. . I shall therefore begin with a brief investigation of the origin of our ideas of space and time, although in doing so I know that I introduce a controversial subject. \" remainder of paragraph elided . . →The experiences of an individual appear to us arranged in a series of events; in this series the single events which we remember appear to be ordered according to the criterion of \[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped which cannot be analysed further. . There exists, therefore, for the individual, an I-time, or subjective time. . This itself is not measurable. . I can, indeed, associate numbers with the events, in such a way that the greater number is associated with the later event than with an earlier one; but the nature of this association may be quite arbitrary. . This association I can define by means of a clock by comparing the order of events furnished by the clock with the order of a given series of events. . We understand by a clock something which provides a series of events which can be counted, and which has other properties of which we shall speak later. .\" Albert Einstein, _The Meaning of Relativity_, 1922 Editing with Emacs Official GNU doctrine holds that the best program for editing a roff document is Emacs; see emacs(1). It provides an nroff major mode that is suitable for all kinds of roff dialects. This mode can be activated by the following methods. When editing a file within Emacs the mode can be changed by typing “M‐x nroff-mode”, where M‐x means to hold down the meta key (often labelled “Alt”) while pressing and releasing the “x” key. It is also possible to have the mode automatically selected when a roff file is loaded into the editor. • The most general method is to include file‐local variables at the end of the file; we can also configure the fill column this way. .\" Local Variables: .\" fill-column: 72 .\" mode: nroff .\" End: • Certain file name extensions, such as those commonly used by man pages, trigger the automatic activation of the nroff mode. • Technically, having the sequence .\" -*- nroff -*- in the first line of a file will cause Emacs to enter the nroff major mode when it is loaded into the buffer. Unfortunately, some imple‐ mentations of the man(1) program are confused by this practice, so we discourage it. Editing with Vim Other editors provide support for roff‐style files too, such as vim(1), an extension of the vi(1) program. Vim’s highlighting can be made to recognize roff files by setting the filetype option in a Vim modeline. For this feature to work, your copy of vim must be built with support for, and configured to enable, several features; consult the editor’s online help topics “auto-setting”, “filetype”, and “syntax”. Then put the following at the end of your roff files, after any Emacs configura‐ tion: .\" vim: set filetype=groff textwidth=72: Replace “groff” in the above with “nroff” if you want highlighting that does not recognize many of the GNU extensions to roff, such as request, register, and string names longer than two characters. Authors This document was written by Bernd Warken ⟨groff-bernd.warken-72@web .de⟩ and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩. See also Much roff documentation is available. The Bell Labs papers describing AT&T troff remain available, and groff is documented comprehensively. Internet sites Unix Text Processing ⟨https://github.com/larrykollar/ Unix-Text-Processing⟩, by Dale Dougherty and Tim O’Reilly, 1987, Hayden Books. This well‐regarded text brings the reader from a state of no knowledge of Unix or text editing (if necessary) to sophisticated com‐ puter‐aided typesetting. It has been placed under a free software li‐ cense by its authors and updated by a team of groff contributors and enthusiasts. “History of Unix Manpages” ⟨http://manpages.bsd.lv/history.html⟩, an online article maintained by the mdocml project, provides an overview of roff development from Saltzer’s RUNOFF to 2008, with links to origi‐ nal documentation and recollections of the authors and their contempo‐ raries. troff.org ⟨http://www.troff.org/⟩, Ralph Corderoy’s troff site, pro‐ vides an overview and pointers to much historical roff information. Multicians ⟨http://www.multicians.org/⟩, a site by Multics enthusiasts, contains a lot of information on the MIT projects CTSS and Multics, in‐ cluding RUNOFF; it is especially useful for its glossary and the many links to historical documents. The Unix Archive ⟨http://www.tuhs.org/Archive/⟩, curated by the Unix Heritage Society, provides the source code and some binaries of histor‐ ical Unices (including the source code of some versions of troff and its documentation) contributed by their copyright holders. Jerry Saltzer’s home page ⟨http://web.mit.edu/Saltzer/www/publications/ pubs.html⟩ stores some documents using the original RUNOFF formatting language. groff ⟨http://www.gnu.org/software/groff⟩, GNU roff’s web site, pro‐ vides convenient access to groff’s source code repository, bug tracker, and mailing lists (including archives and the subscription interface). Historical roff documentation Many AT&T troff documents are available online, and can be found at Ralph Corderoy’s site (see above) or via Internet search. Of foremost significance are two mentioned in section “History” above, describing the language and its device‐independent implementation, re‐ spectively. “Troff User’s Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report No. 54. “A Typesetter‐independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science Technical Report No. 97. You can obtain many relevant Bell Labs papers in PDF from Bernd Warken’s “roff classical” GitHub repository ⟨https://github.com/ bwarken/roff_classical.git⟩. Manual pages As a system of multiple components, a roff system potentially has many man pages, each describing an aspect of it. Unfortunately, there is no consistent naming scheme for these pages among the different roff im‐ plementations. For GNU roff, the groff(1) man page enumerates all man pages distrib‐ uted with the system, and individual pages frequently refer to external resources as well as manuals distributed with groff on a variety of topics. With other roffs, you are on your own, but troff(1) might be a good starting point. groff 1.23.0 29 August 2023 roff(7)