groff_man(7) Miscellaneous Information Manual groff_man(7)
groff_man - GNU roff macro package for formatting man pages
groff -man [option ...] [input-file ...] groff -m man [option ...] [input-file ...]
The man macro package for groff 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 Paragraph macros .IR Italic, roman alternating Font style macros .LP (Left) paragraph Paragraph macros .ME Mail-to end Hyperlink and email macros .MT Mail-to start Hyperlink and email macros .OP (Command-line) option Command synopsis macros .P Paragraph Paragraph macros .PP Paragraph Paragraph macros .RB Roman, bold alternating Font style macros .RE Relative-indent end Document structure macros .RI Roman, italic alternating Font style macros .RS Relative-indent 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 Paragraph macros .TQ Supplemental paragraph tag Paragraph macros .UE URL end Hyperlink and email macros .UR URL start Hyperlink and email macros .YS Synopsis end Command synopsis macros Macros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC) are described in subsection “Deprecated features” below. Macro reference preliminaries Each macro is described in a tagged paragraph. Closely-related macros, such as .EX and .EE, are grouped together. A macro call begins on a line starting with a dot (“.”), followed by zero or more spaces and then the macro name. Some macros accept arguments; each such argument is separated from the macro name and any subsequent arguments by one or more spaces. A newline, unless escaped (see subsection “Portability” below), terminates the macro call. Optional macro arguments are indicated by surrounding them with square brackets. If a macro accepts multiple arguments, those containing space or horizontal tab 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. Unused macro arguments are more often simply omitted, or good style suggests that a more appropriate macro be chosen, that earlier arguments are more important than later ones, or that arguments have identical significance such that skipping any is superfluous. Most macro arguments are strings that will be output as text; exceptions are noted. Bear in mind that groff is fundamentally a programming system for typesetting. Consequently, the verb “to set” is frequently used below in the sense “to typeset”. Document structure macros The highest level of organization of a man page is determined by this group of macros. .TH (title heading) identifies the document as a man page and defines information enabling its indexing by mandb(8) or a similar tool. Sections (.SH), one of which is mandatory and many of which are standardized, facilitate quick location of relevant material by the reader and aid the man page writer to discuss all essential aspects of the topic. Subsections (.SS) are optional and permit sections that grow long to develop in a controlled way. Many technical discussions require 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, a region within a (sub)section can be manually indented within .RS and .RE macros. .TH title section [footer-middle] [footer-inside] [header-middle] Define the title of the man page as title and the section as section. See man(1) for details on the section numbers and suffixes applicable to your system. title and section are positioned together at the left and right in the header line (with section in parentheses immediately appended to title). footer-middle is centered in the footer line. The arragement 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 odd- numbered (recto) pages, and at the bottom right on even- numbered (verso) 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 title and section, as in the header. header-middle is centered in the header line. If section is a simple integer between 1 and 9 (inclusive), or is exactly “3p”, there is no need to specify header-middle; the macro package will supply text for it. For HTML output, headers and footers are completely suppressed. Additionally, this macro starts a new page; the page number is reset to 1 (unless the -rC1 option is given on the command line). This feature is intended only for formatting multiple man pages. A man page should contain exactly one .TH call at or near the beginning of the file, prior to any other macro calls. By convention, footer-middle is the most recent modification date of 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 flush left. The text following .SH up to the end of the line, or the text on the next input line if .SH is given no arguments, is set in bold (or the font specified by the string HF) and, on typesetter devices, slightly larger than the base point size. Additionally, the left margin and indentation affecting subsequent text are reset to their default values. Text on input lines after heading-text is set as a normal paragraph (.PP). The content of heading-text and ordering of sections has been standardized by common practice, 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 a line of the form topic[, another-topic]... \- summary-description for a man page to be properly indexed. See man(7) for the conventions prevailing on your system. .SS [ subheading-text] Set subheading-text as a subsection heading indented partway between a section heading and a normally- indented paragraph (.PP). See subsection “Horizontal and vertical spacing” below for the precise indentation amount. The text following .SS up to the end of the line, or the text on the next input line if .SS is given no arguments, is set in bold (or the font specified by the string HF). Additionally, the left margin and indentation affecting subsequent text are reset to their default values. Text on input lines after subheading-text is set as a normal paragraph (.PP). .EX .EE Begin and end example. After .EX, filling and hyphenation are disabled and a constant-width (monospaced) font is selected. Calling .EE enables filling and restores the previous font and initial hyphenation mode. Example regions are useful for formatting code, shell sessions, and text file contents. These macros are extensions, introduced in Version 9 Unix, to the original man package. Many systems running AT&T, 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 installation. .RS [ indent] Move the left margin to the right by the value indent, if specified, and by a default amount otherwise; see subsection “Horizontal and vertical spacing” below. Calls to .RS can be nested; each call increments by 1 the indentation level used by .RE. The indentation level prior to any .RS calls is 1. .RE [ level] Move the left margin back to that corresponding to indentation level level. If no argument is given, move the left margin one level back. Paragraph macros An ordinary paragraph (.PP) like this one is set without a first-line indent at the current left margin, which by default is indented from the leftmost position of the output device. In man pages and other technical literature, definition lists are frequently encountered; these can be set as “tagged paragraphs” (.TP and .TQ), which have one or more leading tags followed by a paragraph that has an additional left indent. 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 paragraph macros break the output line at the current position. 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 point size and font style to defaults (.TQ again excepted); see subsection “Font style macros” below. .LP .PP .P Begin a new paragraph; these macros are synonymous. The left margin and indentation are reset to default values. .TP [ indent] Set a tagged, indented paragraph. The input line following this macro, known as the tag, is printed at the current left margin. Subsequent text is indented by indent, if specified, and by a default amount otherwise; see subsection “Horizontal and vertical spacing” below. If the tag is not as wide as the indentation, 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, entirely indented. The line containing the tag can include a macro call, for instance to set the tag in bold with .B. .TP was used to write the first paragraph of this description of .TP, and .IP the subsequent ones. .TQ Set an additional tag for a paragraph tagged with .TP. The pending output line is broken. The tag on the input line following this macro and subsequent lines are handled as with .TP. This macro is not defined on systems running AT&T or Plan 9 troff. To be certain your page will be portable to those systems, copy its definition from the an-ext.tmac file of a groff installation. The descriptions of .LP, .PP, and .P above were written using .TP and .TQ. .IP [ tag] [indent] Set an indented paragraph with an optional tag. The tag and indent arguments, if present, are handled as with .TP, with the exception that the tag argument to .IP cannot include a macro call. Two convenient use cases for .IP are (1) to start a new paragraph with the same indentation as an immediately preceding .IP or .TP paragraph, if no indent argument is given; and (2) to set a paragraph with a short tag that is not semantically important, such as a bullet (·)—obtained with the \(bu special character escape—or list enumerator, as seen in this very paragraph. Command synopsis macros Command synopses are a staple of section 1 and 8 man pages. These macros aid you to construct one that has the classical Unix appearance. A command synopsis is wrapped in .SY/.YS calls, with command-line options of some formats indicated by .OP. These macros are not defined on systems running AT&T or Plan 9 troff. To be certain your page will be portable to those systems, copy their definitions from the an-ext.tmac file of a groff installation. .SY command Begin synopsis. Hyphenation is turned off. The command argument is set in bold. The output line is filled as normal, but if a break is required, subsequent output lines are indented by the width of command plus a space. .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 option-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 arguments. .YS End synopsis. Restore previous indentation amount and initial hyphenation mode. 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 separated by a paragraph space. .SY can also be repeated multiple times before a closing .YS, which is useful to indicate synonymous ways of invoking a particular mode of operation. For example, .SY groff .OP \-abcegiklpstzCEGNRSUVXZ .OP \-d cs .OP \-f fam .OP \-F dir .OP \-I dir .OP \-K arg .OP \-L arg .OP \-m name .OP \-M dir .OP \-n num .OP \-o list .OP \-P arg .OP \-r cn .OP \-T dev .OP \-w name .OP \-W name .RI [ file \&.\|.\|.\&] .YS . .SY groff .B \-h .SY groff .B \-\-help .YS produces the following output. groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name] [file ...] groff -h groff --help Several features of the above example are of note. · The empty request (.), which does nothing, is used for verti‐ cal spacing in the input file for readability by the document maintainer. Do not put blank (i.e., empty) lines in a roff source document. · The 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 cut-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 termi‐ nals) to cue the user that they must be replaced with appro‐ priate text. · Symbols that are neither to be typed literally nor simply replaced appear in the roman style; brackets surround optional arguments, and an ellipsis indicates that the previous syntac‐ tical element may be repeated arbitrarily. Authors of man pages should note the use of the zero-width space escape sequence \& preceding the ellipsis, which pre‐ vents it from being misinterpreted as an invalid control line, and after it, which prevents it from being misinterpreted as the end of a sentence. See subsection “Portability” below. Hyperlink and email macros Email addresses are bracketed with .MT/.ME and URL hyperlinks with .UR/.UE. These macros are not defined on systems running AT&T or Plan 9 troff. To be certain your page will be portable to those systems, copy their definitions from the an-ext.tmac file of a groff installation. .MT address .ME [ punctuation] Identify address as an RFC 6068 addr-spec for a “mailto:” URI with the text between the two macro calls as the link text. A punctuation argument to .ME is placed at the end of the link text without intervening space. Note that address may not be visible in the output text, particularly if the man page is being viewed as HTML. On a device that is not a browser, address is set in angle brackets after the link text and before punctuation. When rendered by groff to a terminal or PostScript device, Contact .MT fred.foonly@\:fubar.net Fred Foonly .ME for more information. displays as “Contact Fred Foonly ⟨firstname.lastname@example.org⟩ for more information.”. The use of \: to insert hyphenless discretionary breaks is a GNU extension and can be omitted. .UR URL .UE [ punctuation] Identify URL as an RFC 3986 URI hyperlink with the text between the two macro calls as the link text. A punctuation argument to .UE is placed at the end of the link text without intervening space. Note that URL may not be vis‐ ible in the output text, particularly if the man page is being viewed as HTML. On a device that is not a browser, URL is set in angle brackets after the link text and before punctuation. When rendered by groff to a terminal or PostScript device, The GNU Project of the Free Software Foundation hosts the .UR https://\:www.gnu.org/\:software/\:groff/ groff home page .UE . displays as “The GNU Project of the Free Software Foundation hosts the groff home page ⟨https://www.gnu.org/soft‐ ware/groff/⟩.”. The use of \: to insert hyphenless discretionary breaks is a GNU extension and can be omitted. Font style macros The man macro package is limited in its font styling options, offer‐ ing only bold (.B), italic (.I), and roman. Italic text is usually set underscored instead on terminal devices. The .SM and .SB macros set text in roman or bold, respectively, at a smaller point size; these differ visually from regular-sized roman or bold text only on typesetter devices. 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, con‐ flicting traditions have arisen regarding which font styles should be used to mark file or path names, environment variables, in-line lit‐ erals, and man page cross-references. The default point size and family (for typesetter devices) is 10-point Times. The default style is roman. .B [ text] Set text in bold. If the macro is given no arguments, the text of the next input line 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 .EX/.EE examples of interactive I/O (such as a shell session), set only user input in bold. .I [ text] Set text in italics. If the macro is given no argu‐ ments, the text of the next input line is set in italics. Use italics for file and path names, for environment vari‐ ables, for enumeration or preprocessor constants in C, for variable (user-determined) portions of syntax synopses, for the first occurrence (only) of a technical concept being introduced, for names of works of software (including commands and functions, but excluding names of operating systems or their kernels), and anywhere a parameter requiring replacement by the user is encountered. An exception involves variable text in a context that is already marked up in italics, such as file or path names with variable 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 vari‐ able part (see .IR and .RI below), and italics again in run‐ ning roman text when referring to the variable material. .SM [ text] Set text one point smaller than the default point size. If the macro is given no arguments, the text of the next input line 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, one point smaller than the default point size. If the macro is given no arguments, the text of the next input line is set smaller and in bold. Note: terminals will render text in bold at the normal size instead. Do not rely upon .SB to communicate semantic infor‐ mation distinct from using bold style at normal size; it will be hidden from readers using such devices. Note 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 works of literature or software; identifiers for standards documents or technical reports such as CSTR #54, RFC 1918, Unicode 11.0, or POSIX.1-2017; acronyms; and occurrences after the first of a techni‐ cal term or piece of jargon. Again, the names of operating systems and their kernels are, by practically universal convention, set in roman. Be frugal with the use of italics for emphasis, and particularly with the use of bold. Brief runs of literal text, such as references to individual characters or short strings, including section and subsec‐ tion headings of man pages, are suitable objects for quotation; see the \(lq, \(rq, \(oq, and \(cq escapes in subsection “Portability” below. Unlike the above font style macros, the font style alternation macros below accept only arguments on the same line as the macro call. If space is required within one of the arguments, first consider whether the same result could be achieved with as much clarity by using the single-style macros on separate input lines. When it cannot, double- quote an argument containing embedded space characters. Setting all three different styles within a word presents challenges; it is pos‐ sible with the \c and/or \f escapes, but see subsection “Portability” below for caveats. .BI bold-text italic-text ... Set each argument in bold and italics, alternately. .BI \-r name = n .BR bold-text roman-text ... Set each argument in bold and roman, alternately. Any such change becomes effective with the first use of .BR .NH , .I after the new alias is defined. .IB italic-text bold-text ... Set each argument in italics and bold, alternately. All macro package files must be named .IB name .tmac to fully use the .I tmac mechanism. .IR italic-text roman-text ... Set each argument in italics and roman, alternately. This is the first command of the .IR prologue . .RB roman-text bold-text ... Set each argument in roman and bold, alternately. Also, the statement .RB \(oq "delim on" \(cq is not handled specially. .RI roman-text italic-text ... Set each argument in roman and italics, alternately. .RI [ file \&.\|.\|.\&] Horizontal and vertical spacing The indent argument accepted by .RS, .IP, .TP, and the deprecated .HP is a number plus an optional scaling indicator. If no scaling indi‐ cator 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 “Numerical Expressions” in groff(7)). An indent specified in a call to .IP, .TP, or the deprecated .HP persists until (1) another of these macros is called with an explicit indent argument, or (2) .SH, .SS, or .PP or its synonyms is called; these clear the indent entirely. Indents set by .RS move the left margin and persist until .RS, .RE, .SH, or .SS is called. The default indentation, exhibited by ordi‐ nary .PP paragraphs not within an .RS/.RE relative indent, is 7.2n for typesetter devices and 7n for terminal devices. The HTML output device is an exception; it ignores indentation completely. This same indentation is used again (additively) for the defaults of .IP, .TP, .RS, and the deprecated .HP. Headers, footers (both set with .TH), and section headings (.SH) are set flush left and subsection headings (.SS) are indented 3n (but see the -rSN option). Resist the temptation to mock up tabular or multi-column output with horizontal 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 table preprocessor tbl(1) can likely meet your needs. The following macros break the output line and insert vertical space: .SH, .SS, .TP, .PP (and its synonyms), .IP, and the deprecated .HP. The default inter-section and inter-paragraph spacing is is 1v for terminal devices and 0.4v for typesetter devices (“v” is a unit of vertical distance, where 1v is the distance between adjacent text baselines in a single-spaced document). In .EX/.EE sections, the inter-paragraph spacing is 1v regardless of output device. (The dep‐ recated macro .PD can change this vertical spacing, but its use is discouraged.) The macros .RS, .RE, .EX, .EE, and .TQ also cause a break but no insertion of vertical space. Number registers Number registers are described in section “Options” below. Strings The following strings are defined. \*R expands to the special character escape for the “registered sign” glyph, \(rg, if available, and “(Reg.)” otherwise. \*S expands to an escape setting the point size to the document default. \*(HF expands to the font identifier used to print headings and sub‐ headings. The default is “B”. This string is a GNU exten‐ sion. \*(lq \*(rq expand to the special character escapes for left and right double-quotation marks, \(lq and \(rq, respectively. \*(Tm expands to the special character escape for the “trade mark sign” glyph, \(tm, if available, and “(TM)” otherwise. Interaction with preprocessors When a preprocessor like tbl or eqn is needed, a hint can be given to the man page formatter by making the first line of a man page look like this: '\" word Note that the line starts with an apostrophe ('), not a dot, and that a single space character follows the double quote. The word consists of one letter for each needed preprocessor: “e” for eqn, “r” for refer, and “t” for tbl. Modern implementations of the man program interpret this first line and automatically call the right preproces‐ sor(s). The usual tbl and eqn macros for table and equation inclusion, .TS, .T&, .TE, .EQ, and .EN, may be used freely. Note that terminal devices are extremely limited in presentation of mathematical equa‐ tions. Portability The two major syntactical categories of roff languages are requests and escapes. Since the man macros are implemented in terms of groff requests and escapes, one can, in principle, supplement the function‐ ality of man with these lower-level elements where necessary. Note, however, that 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 assump‐ tions 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 presented incomprehensibly. For portability to modern viewers, it is best to write your page entirely 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/.OP/.YS, .UR/.UE, and .MT/.ME) should be used with caution, as they may not yet be built in to some viewer that is important to your audience. If in doubt, copy the implementation into your page—after the .TH call and the “Name” section, to accommodate timid mandb implementations. Similar caveats apply to escapes. 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 corre‐ sponding to punctuation characters in the Unicode basic Latin range (U+0000–U+007F) that are handled specially in roff input; the escapes below must be used to render them correctly and portably when docu‐ menting material that uses them syntactically—namely, any of the set ' - ^ ` ~ (apostrophe, dash, caret, grave accent, tilde). \" Comment. Everything after the double-quote to the end of the input line is ignored. Whole-line comments are frequently placed immediately after the empty request “.”). \newline Join the next input line to the current one. Except for the update 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 to break excessively long input lines for document maintenance. \% Control hyphenation. If hyphenation is enabled, the location of this escape within a word marks a hyphenation point, over‐ riding groff's hyphenation patterns. Use at the beginning of a word to suppress its hyphenation entirely. \~ Adjustable, non-breaking space character. Use this escape to prevent a break inside a short phrase or between a numerical quantity 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. \& Zero-width non-breaking space. Insert at the beginning of an input line to prevent a dot or apostrophe from being inter‐ preted as the beginning of a roff request. Append to an end- of-sentence punctuation sequence to keep it from being recog‐ nized as such. \| Narrow (one-sixth em on typesetters, zero-width on terminals) non-breaking space. Used primarily in ellipses (“.\|.\|.”) to achieve more pleasant spacing on typesetter devices like PostScript and PDF. \- Minus sign or basic Latin hyphen-minus. “-” is a hyphen to roff; some output devices replace it with U+2010 (hyphen) or similar. \(aq Basic Latin apostrophe. Some output devices replace “'” with a right single quotation mark. \(oq Opening single quotation mark. \(cq Closing single quotation mark. Use these for paired directional single quotes, ‘like this’. \(dq Basic Latin double-quote. Use in macro calls to prevent ‘"” from being interpreted as beginning a quoted argument. .BI split\~\(dq text \(dq \(lq Left double quotation mark. \(rq Right double quotation mark. Use these for paired directional 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 between numbers; for example, “the digits 1–9”. \(ga Basic Latin grave accent. Some output devices replace “`” with a left single quotation mark. \(ha Basic Latin circumflex accent (“hat”). Some output devices replace “^” with U+02C6 (modifier letter circumflex accent) or similar. \(ti Basic Latin tilde. Some output devices replace “~” with U+02DC (small tilde) or similar. \c Suppress break at the end of the input line. Normally, the end of an input line is treated like a space; an output line may be broken there and will be in .EX/.EE examples. Anything after \c on the input line is discarded. The next line, including macro calls, is interpreted as usual (contrast with \newline). This is occasionally useful when three different fonts are needed in a single word. Normally, the final output file should be named .IB file .pdf\c \&. Note that when using this trick with the .BI or .RI macros, you will need to manually add an italic correction escape “\/”, a GNU extension, before the \c due to way macros expand their arguments—if you value the improved typesetter output quality over the potential reduction in document portability. Files processed with .B groff \-mom (or .BI "\-m " mom\/\c ) produce PostScript output by default. Alternatively, and perhaps with better portability, the \f font style escape sequence can be used; see below. Using \c to include the output from more than one input line into the next-line argument of a .TP macro will render incorrectly with groff 1.22.3, mandoc 1.14.1, older versions of these programs, and perhaps with some other formatters. \e Widely used in man pages to represent a backslash output 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 exact \(rs (“reverse solidus”) special character escape sequence. \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 escapes 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. Note that \fP reliably returns to the style in use immediately preceding the previous \f escape 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 escapes do. For maximum portability, escape sequences and special characters not listed above are better avoided in man pages. 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 for compatibility, to render man pages from historical systems. The first argument system can be: 3 7th edition (default) 4 System III 5 System V The optional second argument release specifies the release number, such as in “System V Release 3”. .BT Set the page footer. By redefining this macro (a GNU exten‐ sion) in a man.local file (see section “Files” below), an adminsitrator can customize the footer for a site. .DT Set tab stops every 0.5 inches. Since this macro is always called during a .TH macro, it makes sense to call it only if the tab stops have been changed. Use of this presentation-level macro is deprecated. It trans‐ lates poorly to HTML, under which exact space control and tab‐ ulation are not readily available. Thus, information or dis‐ tinctions that you use .DT to express are likely to be lost. If you feel tempted to use it, you should probably be compos‐ ing a table using tbl(1) markup instead. .HP [ indent] Set up a paragraph with a hanging left indentation. The indent argument, if present, is handled as with .TP. Use of this presentation-level macro is deprecated. While it is universally portable to legacy Unix systems, a hanging indentation cannot be expressed naturally under HTML, and HTML-based man page processors may interpret it as starting a normal paragraph. Thus, any information or distinction you tried to express with the indentation may be lost. .PD [ vertical-space] Define the vertical space between paragraphs or (sub)sections. The optional argument vertical-space speci‐ fies the amount of space; the default scaling is ‘v’). With‐ out an argument, the spacing is reset to its default value; see subsection “Horizontal and vertical spacing” above. Use of this presentation-level macro is deprecated. It trans‐ lates poorly to HTML, under which exact control of inter-para‐ graph spacing is not readily available. Thus, information or distinctions that you use .PD to express are likely to be lost. .PT Set the page header. By redefining this macro (a GNU exten‐ sion) in a man.local file (see section “Files” below), an adminsitrator can customize the header for a site. .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 for compatibility, to render man pages from historical systems. The argument version can be: 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 Version 7 Unix (1979) introduced the man macro package and supported all of the macros described in this page not listed as extensions, except .P, .SB, and the deprecated .AT and .UC. The only strings defined were R and S; no number registers were documented. .UC appeared in 3BSD (1980) and .P in Unix System III (1980). 4BSD (1980) added lq and rq strings. 4.3BSD (1986) added .AT and .P. Version 9 Unix (1986) introduced .EX and .EE. Ultrix 11 (1988) added the Tm string. SunOS 4.0 (1988) may have been the first to support .SB.
The following groff options set number registers recognized and used by the man macro package. -rcR=1 Continuous rendering. Do not paginate the output; produce one (potentially very long) output page. This is the default for terminal and HTML devices. Use -rcR=0 to disable it. -rC1 Number output pages continuously. If multiple man pages are processed, number the output pages in strictly increasing sequence, rather than resetting the page number to 1 at each new man page. -rCS=1 Capitalize section headings. 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 Capitalize titles. Set the man page title (the first argument to .TH) in full capitals in headers and footers. This transformation is off by default because it discards case distinction information. -rD1 Enable double-sided layout. Format 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 if negative or top if positive, to footer-distance. The default is -0.5i. -rHY=mode Set hyphenation mode, as documented in section “Hyphenation” of groff(7). The default is 4 if continuous rendering is enabled (-rcR=1 above), and 6 otherwise. -rIN=indent Set the body text indentation (for normal paragraphs) to indent. See subsection “Horizontal and vertical spacing” above for the default indentation value. For terminal devices, indent should always be an integer multiple of unit ‘n’ to get consistent indentation. -rLL=line-length Set line length. If this option is not given, the line length is set to respect any value set by a prior “.ll” request (which must be in effect when the .TH macro is invoked), if this differs from the built-in default for the formatter; otherwise it defaults to 78n for terminal devices and 6.5i for typesetter devices. Note that the use of a “.ll” request to initialize the line length is supported for backward compatibility with some versions of the man program; direct initialization of the LL register should always be preferred to the use of such a request. In particular, note that a “.ll 65n” request does not preserve the default nroff line length (the man default initialization to 78n prevails), whereas the -rLL=65n option, or an equivalent “.nr LL 65n” request preceding the use of the .TH macro, does set a line length of 65n. -rLT=title-length Set title length, used for headers and footers. If this option is not given, the title length defaults to the line length. -rPn Start enumeration of pages at n rather than 1. -rSpoint-size Use point-size as the base document point size. Acceptable values are 10, 11, or 12. See subsection “Font style macros” above for the default. -rSN=subsection-indent Set subsection indentation to subsection-indent. See subsection “Horizontal and vertical spacing” above for the default indentation value. -rXp After page p, number pages as pa, pb, pc, and so forth. For example, the option -rX2 produces the following page numbers: 1, 2, 2a, 2b, 2c, and so on.
/usr/local/share/groff/1.22.4/tmac/man.tmac /usr/local/share/groff/1.22.4/tmac/an.tmac These are wrapper files to call andoc.tmac. /usr/local/share/groff/1.22.4/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, as their first macro. Because the wrappers above load this file, a man program or user typing, for example, “groff -man page.1”, need not know which package the file page.1 uses. Multiple man pages, in either format, can be handled. /usr/local/share/groff/1.22.4/tmac/an-old.tmac Most man macros are contained in this file. It also loads the extensions from an-ext.tmac (see below). /usr/local/share/groff/1.22.4/tmac/an-ext.tmac The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE, .UR/.UE, and .MT/.ME are contained in this file, which is written to be compatible with AT&T troff and permissively licensed—not copylefted. Man page authors concerned about portability to legacy Unix systems are encouraged to copy these definitions into their pages, and maintainers of troff implementations or work-alike systems that format man pages are encouraged to re-use them. Note that the definitions for these macros are read after the call of .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 calling .TH to have any effect. /usr/local/share/groff/site-tmac/man.local Local changes and customizations should be put into this file.
Some tips on troubleshooting your man pages follow. · .RS doesn't indent relative to my indented paragraph The .RS macro sets the indentation relative to that of a normal paragraph (.PP and its synonyms). .RS, .IP, .TP, and the deprecated .HP all use the same default indentation. To indent 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 .PP paragraph. See subsection “Horizontal and vertical spacing” above for the values. · .RE doesn't reset the indent to the expected level · warning: scale indicator invalid in this context · warning: number register 'an-saved-margin n' not defined · warning: number register 'an-saved-prevailing-indent n' not defined The .RS macro takes an indentation amount as an argument; the .RE macro's argument is a specific indentation 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 desire 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 indents are cleared and calls to .RE have no effect until .RS is used again.
The GNU version of the man macro package was written by James Clark and contributors. The extension macros were written by Werner Lemberg ⟨email@example.com⟩ and Eric S. Raymond ⟨firstname.lastname@example.org⟩. This document was originally written for the Debian GNU/Linux system by Susan G. Kleinmann ⟨email@example.com⟩. It was corrected and updated by Werner Lemberg and G. Branden Robinson. The extension macros were documented by Eric S. Raymond; he also originated the portability section, to which Ingo Schwarze contributed most of the material on escape sequences.
Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the main groff documentation. You can browse it interactively with “info groff”. tbl(1), eqn(1), and refer(1) are preprocessors used with man pages. man(1) describes the man page formatter on your system. groff_mdoc(7) describes the groff version of the BSD-originated alternative macro package for man pages. groff(7), groff_char(7), man(7)
This page is part of the groff (GNU troff) project. Information about the project can be found at ⟨http://www.gnu.org/software/groff/⟩. If you have a bug report for this manual page, see ⟨http://www.gnu.org/software/groff/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2020-07-14. (At that time, the date of the most recent commit that was found in the repos‐ itory was 2020-07-12.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which is not part of the original manual page), send a mail to firstname.lastname@example.org groff 18.104.22.168-3ba6 14 July 2020 groff_man(7)
Pages that refer to this page: groff(1), grotty(1), groff_tmac(5), man(7), man-pages(7)