groff_man - GNU roff macro package for formatting man pages
groff -man |
[option ...] [input-file ...] man [option ...] [input-file ...] DESCRIPTIONThe man macro package for groff is used to produce manual pages (“man pages”) like the one you are reading. GNU roff’s implementation was written by James Clark. This document presents the macros thematically to aid learners; for those needing only a quick reference, the following table lists them alphabetically, with cross-references to appropriate subsections below. Macros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC) are described in subsection “Deprecated features”, below. Macro
reference preliminaries Optional macro arguments are indicated by surrounding them with square brackets. If a macro accepts multiple arguments, arguments containing whitespace must be double-quoted ("one two"), to be interpreted correctly. 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 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. footer-outside is positioned at the left in the footer line (or at the left on even pages and at the right on odd pages if double-sided printing is active). 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-outside 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 register HF) slightly larger than the base font 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 page-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 (by default) partway between a section heading and a normally-indented paragraph (.PP). 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 register HF) at the base font size. 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).
Example regions are useful for formatting code, shell sessions, and text file contents. These macros are defined on many (but not all) legacy Unix systems running classic 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. .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
.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.
This macro is not defined on legacy Unix systems running classic 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
Command
synopsis macros These macros
are not defined on legacy Unix systems running classic
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.
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.
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 produces the following output.
Several features of the above example are of note.
Some man pages use a brace-and-pipe notation such as “{--diff|--compare}” to indicate that one and only one of the ’|’-separated items within the braces must be input. If this braced construct is furthermore surrounded by square brackets, it means that at most one of the items is accepted. Authors of man pages should note the use of the zero-width space escape sequence ’\&’ on both sides of the ellipsis; this is a good practice to avoid surprises in the event the ellipsis gets refilled in your text editor. See “Portability”, below. The morbidly curious may consult groff(7) regarding the narrow-space escape sequence ’\|’. Hyperlink
and email macros These macros
are not defined on legacy Unix systems running classic
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.
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 TTY or PostScript output device, Contact displays as: “Contact Fred Foonly 〈 fred.foonly@fubar.net〉 for more information.”. The use of ’\:’ to insert hyphenless discretionary breaks is a groff extension and can be omitted. .UR URL 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 visible 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 TTY or PostScript output device, The GNU Project
of the Free Software Foundation hosts the displays as: “The GNU Project of the Free Software Foundation hosts the Groff home page 〈 https://www.gnu.org/software/ groff/〉 .”. The use of ’\:’ to insert hyphenless discretionary breaks is a groff extension and can be omitted. Font style
macros Because font styles are presentational rather than semantic, conflicting traditions have arisen regarding which font styles should be used to mark file or path names, environment variables, in-line literals, and even man page cross-references. The default
font size and family (for troff output devices) is
10-point Times. The default style is roman. 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 and register names. In .EX/.EE examples of interactive I/O (such as a shell session), set only the user-typed input in bold. .I [text] Set text in italics. If the macro is given no arguments, the text of the next input line is set in italics. Use italics for file and path names, for environment variables, 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 (see .IR below), but use roman for the variable part, and italics again in running roman text when referring to the variable material. .SM [text] Set text one point size smaller than the default size. If the macro is given no arguments, the text of the next input line is set smaller. Note: nroff-style output devices, such as terminals, will render text at the normal font size instead. Do not rely upon .SM to communicate semantic information distinct from using roman style at the normal size; it will be hidden from readers using such devices. .SB [text] Set text in bold, one point size smaller than the default size. If the macro is given no arguments, the text of the next input line is set smaller and in bold. Note: nroff-style output devices, such as terminals, will render text in bold at the normal font size instead. Do not rely upon .SB to communicate semantic information distinct from using bold style at the 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 technical 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 subsection 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 alternation macros below
accept only arguments on the same line as the macro call. If
whitespace 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 with
one or more embedded space characters. Setting all three
different styles within one whitespace-delimited word
presents challenges; it is possible with the
’\c’ and/or ’\f’ escapes, but see
subsection “Portability” below for caveats.
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 .IB italic-text bold-text ... Set each argument in italics and bold, alternately. All macro
package files must be named .IR italic-text roman-text ... Set each argument in italics and roman, alternately. This is the
first command of the .RB roman-text bold-text ... Set each argument in roman and bold, alternately. Also, the
statement .RI roman-text italic-text ... Set each argument in roman and italics, alternately. .RI [ file Horizontal
and vertical spacing Indents set by .RS move the left margin and persist until .RS, .RE, .SH, or .SS is called. The default indentation, exhibited by ordinary .PP paragraphs not within an .RS/.RE relative indent, is 7.2n in troff mode and 7n in nroff mode. 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. Section headings (.SH) are set flush with the left margin of the output device, and subsection headings (.SS) are indented 3n. Resist the temptation to mock up tabular or multi-column output with ASCII 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 cause a line break with the insertion of vertical space: .SH, .SS, .TP, .TQ, .PP (and its synonyms), .IP, and the deprecated .HP. The default inter-section and inter-paragraph spacing is 1 line in nroff mode, and 0.4v in troff mode. (The deprecated macro .PD can change this vertical spacing, but its use is discouraged.) The macros .RS, .RE, .EX, and .EE also cause a break but no insertion of vertical space. Number
registers String
registers
Interaction
with preprocessors '\" 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 preprocessor(s). The usual tbl and eqn macros for table and equation inclusion, .TS, .T&, .TE, .EQ, and .EN, may be used freely. Note that nroff output devices are extremely limited in presentation of mathematical equations. Portability
Note, however, that using raw groff requests is likely to make your page render poorly on the class of viewers that transform it 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 silently dropped. 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:
\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 is transparent to groff. Use this escape to break excessively input long lines for document maintenance.
Before starting
the motor, set the output speed to\~1.
Use these for paired directional single quotes, ’like this’.
Use these for paired directional double quotes, “like this”.
Normally, the
final output file should be named Note that when using this trick with the .BI or .RI macros, you will need to manually add an italic correction escape ’\/’ before the ’\c’ due to way macros expand their arguments. Files processed
with Alternatively, and perhaps with better portability, the ’\f’ font 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.
\fB, \fI, \fR, \fP Switch to bold, italic, roman, or back to the previous font, respectively. Either these or ’\c’ is needed when three different fonts are required in a single whitespace-delimited word. .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ] .RB [
\-\-reference\-dictionary=\c Font 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 groff 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, paragraph, or font face macro calls have intervened. As long as only two fonts are needed in any single whitespace-delimited word, font alternation macros like .BI usually result in more readable source code than ’\f’ escapes do. For maximum portability, escape sequences and special characters not listed above are better avoided in man pages. Deprecated
features Alter the footer for use with AT&T man pages, overriding any definition of the footer-outside argument to .TH. This macro exists only for compatibility; don’t use it. The first argument system can be:
The optional second argument release specifies the release number, such as in “System V Release 3”.
Use of this presentation-level macro is deprecated. It translates poorly to HTML, under which exact whitespace control and tabbing are not readily available. Thus, information or distinctions that you use .DT to express are likely to be lost. If you feel tempted to use it, you should probably be composing 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 many HTML-based manual viewers simply interpret it as a starter for 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 specifies the amount of space; the default scaling is ’v’). Without an argument, the spacing is reset to its default value; see “Horizontal and vertical spacing” above. Use of this presentation-level 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 BSD man pages, overriding any definition of the footer-outside argument to .TH. This macro exists only for compatibility; don’t use it. The argument version can be:
History
OPTIONSThe following groff options set number registers recognized and used by the man macro package.
-rFT=footer-distance Set distance of the footer, relative to the bottom of the page if negative or relative to the top if positive, to footer-distance. The default is -0.5i. -rHY=flags Set hyphenation flags. Permissible values of flags are 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 “Horizontal and vertical spacing” above for the default indentation value. For nroff, 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 in nroff mode and 6.5i in troff mode. 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 normal nroff default 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. If this option is not given, the title length defaults to the line length.
-rSpoint-size Use point-size as the base document font 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 “Horizontal and vertical spacing” above for the default indentation value.
FILES/usr/share/groff/1.22.4/tmac/man.tmac
These are wrapper files to call andoc.tmac. /usr/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/share/groff/1.22.4/tmac/an-old.tmac Most man macros are contained in this file. It also loads the GNU extensions from an-ext.tmac (see below). /usr/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 in classic 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/share/groff/site-tmac/man.local Local changes and customizations should be put into this file. NOTESSome tips on
troubleshooting your man pages follow. The .RS macro sets the indentation relative to the amount of a normal paragraph (.PP and its synonyms). The same default indentation amount is used for .RS, .IP, .TP, and the deprecated .HP. If you need to start an 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 “Horizontal and vertical spacing” above for the values. • .RE doesn’t
reset the indent to the expected level 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. AUTHORSThe GNU version of the man macro package was written by James Clark and contributors. The extension macros were written by Werner Lemberg and Eric S. Raymond. This document was originally written for the Debian GNU/Linux system by Susan G. Kleinmann. 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. SEE ALSOGroff: 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) |