GROFF_MAN

NAME

groff_man - GNU roff macro package for formatting man pages

SYNOPSIS

groff -man [option ...] [input-file ...] groff -m man [option ...] [input-file ...]

DESCRIPTION

The 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

Each macro is described in a tagged paragraph. Closely related macros, such as .EX and .EE, are grouped together.

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 language for typesetting. Consequently, the verb “set” is frequently used below in the sense of “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 fundamental information enabling its indexing by mandb(8). Sections (.SH), one of which is mandatory and many of which are standardized, facilitate quick location of relevant information by the reader and aid the man page writer to comprehensively 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 section of the discussion can be manually indented within .RS and .RE macros.
.TH title section [extra1] [extra2] [extra3]

Set the title of the man page to title and the section to section, which must take on a value between 1 and 8. The value section may also have a string appended, e.g. ‘pm’, to indicate a specific subsection of the man pages. Both title and section are positioned at the left and right in the header line (with section in parentheses immediately appended to title. extra1 is positioned in the middle of the footer line. extra2 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). extra3 is centered in the header line.

For HTML output, headers and footers are completely suppressed.

Additionally, this macro starts a new page; the new line number is 1 again (except if the ‘-rC1’ option is given on the command line). This feature is intended only for formatting multiple man pages; a single man page should contain exactly one TH macro at the beginning of the file.

.SH [text for a heading]

Set up an unnumbered section heading sticking out to the left. Prints out all the text following .SH up to the end of the line (or the text in the next input line if there is no argument to .SH) in bold face (or the font specified by the string HF), one size larger than the base document size. Additionally, the left margin and the indentation for the following text is reset to the default values.

.SS [text for a heading]

Set up a secondary, unnumbered section heading. Prints out all the text following .SS up to the end of the line (or the text in the next input line if there is no argument to .SS) in bold face (or the font specified by the string HF), at the same size as the base document size. Additionally, the left margin and the indentation for the following text is reset to the default values.

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 [nnn]

This macro moves the left margin to the right by the value nnn if specified (default unit is ‘n’); otherwise it is set to the previous indentation value specified with .TP, .IP, or .HP (or to the default value if none of them have been used yet). The indentation value is then set to the default.

Calls to the RS macro can be nested.

.RE [nnn]

This macro moves the left margin back to level nnn, restoring the previous left margin. If no argument is given, it moves one level back. The first level (i.e., no call to .RS yet) has number 1, and each call to .RS increases the level by 1.

Paragraph macros

A typical paragraph (.PP) is set at the current left margin. 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.

.TP [nnn]

Set up an indented paragraph with label. The indentation is set to nnn if that argument is supplied (the default unit is ‘n’ if omitted), otherwise it is set to the previous indentation value specified with .TP, .IP, or .HP (or to the default value if none of them have been used yet).

The first input line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines. Nevertheless, if the label is not as wide as the indentation the paragraph starts at the same line (but indented), continuing on the following lines. If the label is wider than the indentation the descriptive part of the paragraph begins on the line following the label, entirely indented. Note that neither font shape nor font size of the label is set to a default value; on the other hand, the rest of the text has default font settings.

.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.

.IP [designator] [nnn]

Set up an indented paragraph, using designator as a tag to mark its beginning. The indentation is set to nnn if that argument is supplied (the default unit is ‘n’ if omitted), otherwise it is set to the previous indentation value specified with .TP, .IP, or .HP (or to the default value if none of them have been used yet). Font size and face of the paragraph (but not the designator) are reset to its default values.

To start an indented paragraph with a particular indentation but without a designator, use ‘""’ (two doublequotes) as the first argument.

For example, the following paragraphs were all set up with bullets as the designator, using ‘.IP \(bu 4’. The whole block has been enclosed with .RS and .RE to set the left margin temporarily to the current indentation value.

Command synopsis macros

The following 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.

These macros are a convenience for authors. Together, they produce the traditional look of a Unix command synopsis. They also assist automated translation tools and help browsers in recognizing command synopses and treating them differently from running text.
.SY command

Begin synopsis. Takes a single argument, the name of a command. Text following, until closed by .YS, is set with a hanging indentation of the width of command plus a space. Hyphenation is turned off.

.OP option-name [option-argument]

Indicate an optional command parameter called option-name. If the option takes an argument, specify option-argument using a noun, abbreviation, or hyphenated noun phrase.

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

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 ...]

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. If necessary, you can use a br request to insert a mandatory line break.

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 reflowed in your text editor. See “Portability”, below. The morbidly curious may consult groff(7) regarding the narrow-space escape sequence “\|”.

Hyperlink and email macros

The following 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.

Using these macros helps ensure that you get hyperlinks when your manual page is rendered in a browser or other program that is Web-enabled.
.MT address
.ME [punctuation]

Wrap an email address. The argument of .MT is the address; text following, until .ME, is a name to be associated with the address. Any argument to the ME macro is pasted to the end of the link text. On a device that is not a browser,

contact
.MT fred.foonly@\:fubar.net
Fred Foonly
.ME
for more information

usually displays like this: “contact Fred Foonly <fred.foonly@ fubar.net> for more information”.

The use of \: to insert hyphenless breakpoints is a groff extension and can be omitted.

.UR URL
.UE [punctuation]

Wrap a World Wide Web hyperlink. The argument to .UR is the URL; thereafter, lines until .UE are collected and used as the link text. Any argument to the UE macro is pasted to the end of the text. On a device that is not a browser,

this is a link to
.UR http://\:randomsite.org/\:fubar
some random site
.UE ,
given as an example

usually displays like this: “this is a link to some random site ⟨http://randomsite.org/fubar⟩, given as an example”.

The use of \: to insert hyphenless breakpoints is a groff extension and can be omitted.

Font face macros

The default font size and family (for troff output devices) is 10-point Times. The default face is roman.
.B [text]

Causes text to appear in bold face. If no text is present on the line where the macro is called the text of the next input line appears in bold face.

.I [text]

Causes text to appear in italic. If no text is present on the line where the macro is called the text of the next input line appears in italic.

.SM [text]

Causes the text on the same line or the text on the next input line to appear in a font that is one point size smaller than the default font.

.SB [text]

Causes the text on the same line or the text on the next input line to appear in boldface font, one point size smaller than the default font.

.BI text

Causes text on the same line to appear alternately in bold face and italic. The text must be on the same line as the macro call. Thus

.BI this "word and" that

would cause ‘this’ and ‘that’ to appear in bold face, while ‘word and’ appears in italics.

.BR text

Causes text on the same line to appear alternately in bold face and roman. The text must be on the same line as the macro call.

.IB text

Causes text to appear alternately in italic and bold face. The text must be on the same line as the macro call.

.IR text

Causes text on the same line to appear alternately in italic and roman. The text must be on the same line as the macro call.

.RB text

Causes text on the same line to appear alternately in roman and bold face. The text must be on the same line as the macro call.

.RI text

Causes text on the same line to appear alternately in roman and italic. The text must be on the same line as the macro call.

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 indicator 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) for further details. 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 made; 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 ordinary .PP paragraphs not within an .RS/.RE relative indent, is 7.2n in troff mode and 7n in nroff mode, except for grohtml, which ignores indentation. 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, LP (PP, P), IP, and the deprecated HP. (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.

String registers

The following strings are defined:

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 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

Since the man macros consist of groups of groff requests, one can, in principle, supplement the functionality of the man macros with individual groff requests where necessary. See the groff info pages for a complete reference of all requests.

Note, however, that using raw troff requests is likely to make your page render poorly on the class of viewers that transform it to HTML. Troff requests make implicit assumptions about things like character and page sizes that may break in an HTML environment; also, many of these viewers don’t interpret the full troff 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 in the requests described on this page. Further, it is best to completely avoid those we have described as ‘presentation-level’ (.HP, .PD, and .DT) in “Deprecated features”, below.

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 onto your page.

In a way similar to using groff requests, it is possible to use the facilities documented in the ESCAPE SEQUENCES section of the groff(7) manual page and in the groff_char(7) manual page. Regarding portability, similar caveats apply as with respect to groff requests. Some escape sequences are however required for correct typesetting even in manual pages and usually do not cause portability problems:

There are 2.54\ cm in an inch, and 1,024\ bytes in 1\ kiB.

Use these for paired directional single quotes, ‘like this’.

Use these for paired directional double quotes, “like this”.

.BR "dd if" =\c
.I file

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
.B groff \-mom
(or
.BI "\-m " mom\/\c
) produce PostScript output by default.

Alternatively, and perhaps with better portability, the \f font escape sequence can be used; see below. Attempting to use \c to include the output from more than one macro line into the next-line argument of a .TP macro will misrender 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. This is needed when three different fonts are required on a single input line, for example:

.TP
\fBif\fP=\fIfile\fP

It can also be used if three different fonts are needed in a single word. It may be more portable than \c. 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.

As long as at most two fonts are needed in any one whitespace-delimited word, using font alternation macros like .BR usually results in more readable source code.

For maximum portability, escape sequences and special characters not listed above are better avoided in manual pages.

Deprecated features

Use of the following is discouraged.
.AT [system [release]]

Alter the footer for use with AT&T man pages. This macro exists only for compatibility; don’t use it. See the groff info manual for more.

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 [nnn]

Set up a paragraph with hanging left indentation. The indentation is set to nnn if that argument is supplied (the default unit is ‘n’ if omitted), otherwise it is set to the previous indentation value specified with .TP, .IP, or .HP (or to the default value if none of them have been used yet). Font size and face are reset to its default values. The following paragraph illustrates the effect of this macro with hanging indentation set to 4 (enclosed by .RS and .RE to set the left margin temporarily to the current indentation):

can see, it produces a paragraph where all lines but the first are indented.

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 [nnn]

Adjust the empty space before a new paragraph or section. The optional argument gives the amount of space (default unit is ‘v’); without parameter, the value is reset to its default value (1 line in nroff mode, 0.4v otherwise). This affects the macros SH, SS, TP, LP (resp. PP and P), IP, and HP.

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. This macro exists only for compatibility; don’t use it. See the groff info manual for more.

OPTIONS

The man macros understand the following command-line options (which define various registers).
-rcR=1

This option (the default if in nroff mode) creates a single, very long page instead of multiple pages. Say -rcR=0 to disable it.

-rFT=dist

Set distance of the footer relative to the bottom of the page if negative or relative to the top if positive. The default is -0.5i.

-rHY=flags

Set hyphenation flags. Possible values are 1 to not hyphenate the first and last character of a word, 2 to not hyphenate the last word on a page, 4 to not hyphenate the last two characters of a word, 8 to not hyphenate the first two characters of a word, 16 to enable hyphenation before the last character of a word, and 32 to enable hyphenation after the first character of a word. These values are additive; the default is 6. Values 4 and 16 can’t be used together since they contradict each other; the same holds for values 8 and 32.

-rIN=width

Set body text indentation to width. The default is 7n for nroff, 7.2n for troff. For nroff, this value 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.

-rPnnn

Enumeration of pages start with nnn rather than with 1.

-rSN=width

Set sub-subheading indentation to width. The default is 3n.

-rXnnn

After page nnn, number pages as nnna, nnnb, nnnc, etc. For example, the option ‘-rX2’ produces the following page numbers: 1, 2, 2a, 2b, 2c, etc.

FILES

/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 GNU 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 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/local/share/groff/site-tmac/man.local

Local changes and customizations should be put into this file.

NOTES

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 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, 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
• warning: scale indicator invalid in this context
• warning: number register 'an-saved-marginn' not defined
• warning: number 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 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.

AUTHORS

The 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. The extension macros were documented by Eric S. Raymond; he also originated the portability advice.

SEE ALSO

tbl(1), eqn(1), refer(1), man(1), man(7), groff_mdoc(7)