groff_man_style(7) — Linux manual page

Name | Synopsis | Description | Options | Files | Notes | Authors | See also | COLOPHON

groff_man_style(7)  Miscellaneous Information Manual  groff_man_style(7)

Name         top

       groff_man_style - GNU roff man page tutorial and style guide

Synopsis         top

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

Description         top

       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

       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 inset end           Document structure macros
       .RI     Roman, italic alternating    Font style macros
       .RS     Relative inset start         Document structure macros
       .SB     Small bold                   Font style macros
       .SH     Section heading              Document structure macros
       .SM     Small                        Font style macros
       .SS     Subsection heading           Document structure macros
       .SY     Synopsis start               Command synopsis macros
       .TH     Title heading                Document structure macros
       .TP     Tagged paragraph             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, .DT, .HP, .PD, and .UC) are
       described in subsection “Deprecated features” below.

       Man pages should be encoded using Unicode basic Latin code points
       exclusively, and employ the Unix line-ending convention (U+000A

   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 appears 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 characters must be double-quoted to be
       interpreted correctly.  An empty macro argument can be specified
       with a pair of double-quotes (“""”), but the man package is
       designed such that this should seldom be necessary.  See section
       “Notes” below for examples of cases where better alternatives to
       empty arguments in macro calls are available.  Most macro
       arguments are strings that will be output as text; exceptions are

       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.  Section headings (.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.  Subsection headings (.SS) are optional and permit
       sections that grow long to develop in a controlled way.  Many
       technical discussions benefit from examples; lengthy ones,
       especially those reflecting multiple lines of input to or output
       from the system, are usefully bracketed by .EX and .EE.  When
       none of the foregoing meets a structural demand, a region within
       a (sub)section can be manually inset 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
              of the manual volume as section.  This use of “section”
              has nothing to do with the section headings otherwise
              discussed in this page; it arises from the organizational
              scheme of printed and bound Unix manuals.  See man(1) 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 arrangement of the
              rest of the footer depends on whether double-sided layout
              is enabled with the option -rD1.  When disabled (the
              default), footer-inside is positioned at the bottom left.
              Otherwise, footer-inside appears at the bottom left on
              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).
              This feature is intended only for formatting multiple man

              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.  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 with no
              indentation, 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 an ordinary 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
              between a section heading and an ordinary paragraph (.PP).
              See subsection “Horizontal and vertical spacing” below for
              the 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 an ordinary paragraph (.PP).

       .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]
              Start a new relative inset level, moving the left margin
              right by 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 inset level used by .RE.  The inset
              level prior to any .RS calls is 1.

       .RE [level]
              End a relative inset; move the left margin back to that
              corresponding to inset 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 indentation 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”,
       which have one (.TP) or more (.TQ) leading tags followed by a
       paragraph that has an additional indentation.  The indented
       paragraph (.IP) macro is useful to continue the indented content
       of a narrative started with .TP, or to present an itemized or
       ordered list.  All 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”

       .P     Begin a new paragraph; these macros are synonymous.  The
              indentation is reset to the default value; the left
              margin, as affected by .RS and .RE, is not.

       .TP [indent]
              Set a paragraph with a leading tag, and the remainder of
              the paragraph indented.  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.

              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 a GNU extension not defined on systems
              running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in
              section “Files” below.

              The descriptions of .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 uses 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;

                     (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

   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 GNU extensions not defined on systems running
       AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section
       “Files” below.

       .SY command
              Begin synopsis.  A new paragraph is begun at the left
              margin (like .PP and its aliases) unless .SY has already
              been called without a corresponding .YS, in which case
              only a break is performed.  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

       .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 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 vertically separated as paragraphs are.

       .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
              .SY groff
              .B \-h
              .SY groff
              .B \-\-help

       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
              vertical spacing in the input file for readability by the
              document maintainer.  Do not put blank (empty) lines in a
              man page 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 terminals) to cue the user that they must be
              replaced with appropriate 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 syntactical element may be repeated arbitrarily.

              Authors of man pages should note the non-printing input
              break escape sequence \& preceding the ellipsis, which
              prevents 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 GNU extensions not defined on systems running
       AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section
       “Files” below.

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

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

              displays as “Contact Fred Foonly ⟨⟩
              for more information.”.

              The use of \: to insert non-printing break points is a GNU
              extension and can be omitted.  We place them before each
              period so that the reader does not mistake them for
              sentence endings.

       .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.  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 terminal or PostScript device,

                     The GNU Project of the Free Software Foundation
                     hosts the
                     .UR https://\:www\:.gnu\\:software/\:groff/
                     .I groff
                     home page
                     .UE .

              displays as “The GNU Project of the Free Software
              Foundation hosts the groff home page

              The use of \: to insert non-printing break points is a GNU
              extension and can be omitted.  We place them before each
              period so that the reader does not mistake them for
              sentence endings.

   Font style macros
       The man macro package is limited in its font styling options,
       offering only bold (.B), italic (.I), and roman.  Italic text is
       usually set 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,
       conflicting traditions have arisen regarding which font styles
       should be used to mark file or path names, environment variables,
       in-line literals, and man page cross-references.

       The default point size and family for typesetter devices is
       10-point Times, except on the X75-12 and X100-12 devices where
       the point size is 12.  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 an .EX/.EE example 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 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 but use roman for
              the variable part (see .IR and .RI below), and italics
              again in running roman text when referring to the variable

       .SM [text]
              Set text one point smaller than the default point size on
              typesetter devices.  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 and (on typesetter devices) 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 information distinct from using bold style at
              normal size; it will be hidden from readers using such

       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 13.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 italics for emphasis, and particularly with 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 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 possible 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

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

                     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 scale indicator.  If no scale
       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)).  An
       indentation 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 indentation entirely.  Relative insets
       created by .RS move the left margin and persist until .RS, .RE,
       .SH, or .SS is called.

       The indentation amount exhibited by ordinary paragraphs set with
       .PP (and its synonyms) not within an .RS/.RE relative inset, and
       the default used when .IP, .RS, .TP, and the deprecated .HP are
       not given an indentation argument, is 7.2n for typesetter devices
       and 7n for terminal devices (but see the -rIN option).  Headers,
       footers (both set with .TH), and section headings (.SH) are set
       with no indentation and subsection headings (.SS) are indented 3n
       (but see the -rSN option).  However, the HTML output device
       ignores indentation completely.

       It may be helpful to think of the left margin and indentation as
       related but distinct concepts; groff's implementation of the man
       macro package tracks them separately.  The left margin is
       manipulated by .RS and .RE (and by .SH and .SS, which reset it to
       the default).  The other kind of indentation is controlled by the
       paragraphing macros (though, again, .SH and .SS reset it).
       Indentation is imposed by the .TP, .IP, and deprecated .HP
       macros, and cancelled by .PP and its synonyms.  An extensive
       example follows.

       This ordinary (.PP) paragraph is not in a relative inset nor does
       it possess an indentation.

              Now we have created a relative inset (in other words,
              moved the left margin) with .RS and started another block
              paragraph with .PP.

              tag    This tagged paragraph, set with .TP, is still
                     within the .RS region, but lines after the first
                     have a supplementary indentation that the tag

                     A paragraph like this one, set with .IP, will
                     appear to the reader as also associated with the
                     tag above, because .IP re-uses the previous
                     paragraph's indentation unless given an argument to
                     change it.  This paragraph is affected both by the
                     moved left margin (.RS) and indentation (.IP).

                     │This table is affected both by   │
                     │the left margin and indentation. │
              •      This indented paragraph has a bullet for a tag,
                     making it more obvious that the left margin and the
                     paragraph indentation are distinct; only the former
                     affects the tag, but both affect the text of the

              This ordinary (.PP) paragraph resets the indentation, but
              the left margin is still inset.

              │This table is affected only │
              │by the left margin.         │
       Finally, we have ended the relative inset by using .RE, which
       (because we only used one .RS/.RE pair) has reset the left margin
       to the default.  This is an ordinary .PP paragraph.

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

       Registers are described in section “Options” below.  They can be
       set not only on the command line but in the site man.local file
       as well; see section “Files” below.

       The following strings are defined for use in man pages.  Others
       are supported for configuration of rendering parameters; see
       section “Options” below.

       \*R    interpolates a special character escape sequence for the
              “registered sign” glyph, \(rg, if available, and “(Reg.)”

       \*S    interpolates an escape sequence setting the point size to
              the document default.

       \*(rq  interpolate special character escape sequences for left
              and right double-quotation marks, \(lq and \(rq,

       \*(Tm  interpolate special character escape sequences for the
              “trade mark sign” glyph, \(tm, if available, and “(TM)”

       None of the above is necessary in a contemporary man page.  \*S
       is superfluous, since point size changes are invisible on
       terminal devices and macros that change it restore its original
       value afterward.  Better alternatives exist for the rest; simply
       use the \(rg, \(lq, \(rq, and \(tm special character escape
       sequences directly.  Unless a man page author is aiming for a
       pathological level of portability, such as the composition of
       pages for consumption on simulators of 1980s Unix systems (or
       Solaris troff, though even it supports \rg), the above strings
       should be avoided.

   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

       The line starts with an apostrophe ('), not a dot, and 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 can use this information to automatically call the
       required preprocessor(s) in the right order.

       The usual tbl and eqn macros for table and equation inclusion,
       .TS, .T&, .TE, .EQ, and .EN, may be used freely.  Terminal
       devices are extremely limited in presentation of mathematical

       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 functionality 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 assumptions about things like character and page sizes
       that may not hold in an HTML environment; also, many of these
       viewers don't interpret the full groff vocabulary, a problem that
       can lead to portions of your text being omitted or presented

       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,
       .TQ, .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.  See an-ext.tmac in section “Files” below.

       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 corresponding to punctuation code points 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 documenting material that uses
       them syntactically—namely, any of the set ' - \ ^ ` ~
       (apostrophe, dash or minus, backslash, caret, grave accent,

       \"     Comment.  Everything after the double-quote to the end of
              the input line is ignored.  Whole-line comments should be
              placed immediately after the empty request “.”).

              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, overriding groff's hyphenation patterns.  At the
              beginning of a word, it suppresses hyphenation entirely.

       \~     Adjustable non-breaking space.  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.

       \&     Non-printing input break.  Insert at the beginning of an
              input line to prevent a dot or apostrophe from being
              interpreted as the beginning of a roff request.  Append to
              an end-of-sentence punctuation sequence to keep it from
              being recognized as such.

       \|     Narrow (one-sixth em on typesetters, zero-width on
              terminals) non-breaking space.  Used primarily in ellipses
              (“.\|.\|.”)  to space the dots more pleasantly on
              typesetter devices like PostScript and PDF.

       \-     Minus sign or basic Latin hyphen-minus.  This escape
              produces the Unix command-line option dash in the output.
              “-” 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.

       \(cq   Opening and closing single quotation marks.  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,
              or simply for readability.

                     .BI split\~\(dq text \(dq

       \(rq   Left and right double quotation marks.  Use these for
              paired directional double quotes, “like this”.

       \(em   Em-dash.  Use for an interruption—such as this one—in a

       \(en   En-dash.  Use to separate the ends of a range,
              particularly between numbers; for example, “the digits

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

       \(rs   Reverse solidus (backslash).  The backslash is the default
              groff escape character, so it does not represent itself in
              output.  Also see \e below.

       \(ti   Basic Latin tilde.  Some output devices replace “~” with
              U+02DC (small tilde) or similar.

       \c     End an input line without inserting space or attempting a
              break.  (Normally, the end of an input line is treated
              like a space; an output line may be broken there (if not,
              an adjustable space is inserted) and will be broken there
              in .EX/.EE examples.)  Anything after \c on the input line
              is ignored.  The next line is interpreted as usual and can
              include a macro call (contrast with \newline).  This
              escape is useful when three different font styles are
              needed in a single word or on a single line in .EX/.EE

                     the final output file should be named
                     .IB file .pdf\c

                     $ \c
                     .B groff \-T utf8 \-Z \c
                     .I file \c
                     .B | grotty \-i

              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

                     Files processed with
                     .B groff \-mom
                     .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

       \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 explicit \(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.

              \fP reliably returns to the style in use immediately
              preceding the previous \f escape only if no sectioning,
              paragraph, 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.

       Two macros, both GNU extensions, are called internally by the
       groff man package to format page headers and footers and can be
       redefined by the administrator in a site's man.local file (see
       section “Files” below).  The default headers and footers are
       documented in the description of .TH above.  Because these macros
       are hooks for groff man internals, man pages have no reason to
       call them.

       .BT    Set the page footer (“bottom trap”).

       .PT    Set the page header (“page trap”).

   Deprecated features
       Use of the following in man pages for public distribution is

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

       .DT    Set tab stops every 0.5i (inches).  Since this macro is
              called by .TH, it would make sense to call it only if a
              man page changes the tab stops.

              Use of this presentation-level macro is deprecated.  It
              translates poorly to HTML, under which exact space control
              and tabulation 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

       .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.  A
              hanging indentation cannot be expressed naturally under
              HTML, and HTML-based man page processors may interpret it
              as starting an ordinary paragraph.  Thus, any information
              or distinction you mean 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; the default scale indicator is “v”.
              Without an argument, the spacing is reset to its default
              value; see subsection “Horizontal and vertical spacing”

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

       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 registers were documented.
       .UC appeared in 3BSD (1980) and .P in Unix System III (1980).
       PWB/UNIX 2.0 (1980) added the Tm string.  4BSD (1980) added lq
       and rq strings.  4.3BSD (1986) added .AT and .P.  Version 9 Unix
       (1986) introduced .EX and .EE.  SunOS 4.0 (1988) may have been
       the first to support .SB.

Options         top

       The following groff options set registers (with the -r option)
       and strings (with the -d option) recognized and used by the man
       macro package.

              Set line adjustment to adjustment-mode, which is typically
              “b” for adjustment to both margins (the default), or “l”
              for left adjustment (ragged right margin).  Any valid
              parameter to groff's “.ad” request may be used.  See
              groff(7) for less-common choices.

       -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

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

              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.

              See the font used for section and subsection headings; the
              default is “B” (bold).  Any valid parameter to groff's
              “.ft” request may be used.  See groff(7).

              Set hyphenation mode, as documented in section
              “Hyphenation” of groff(7).  Use -rHY=0 to disable
              hyphenation.  The default is 4 if continuous rendering is
              enabled (-rcR=1 above), and 6 otherwise.

              Set the amount of indentation used for ordinary paragraphs
              (.PP and its synonyms) and the default indentation amount
              used by .IP, .RS, .TP, and the deprecated .HP.  See
              subsection “Horizontal and vertical spacing” above for the
              default.  For terminal devices, standard-indent should
              always be an integer multiple of unit “n” to get
              consistent indentation.

              Set line length; the default is 78n for terminal devices
              and 6.5i for typesetter devices.

              Set the line length for titles.  (“Titles” is the roff
              term for headers and footers.)  By default, the line
              length (see -rLL above) is used for the title length.

       -rPn   Start enumeration of pages at n rather than 1.

              Use point-size as the base point size; acceptable values
              are 10, 11, or 12.  See subsection “Font style macros”
              above for the default.

              Set indentation of subsection headings to subsection-
              indent.  See subsection “Horizontal and vertical spacing”
              above for the default.

       -rXp   After page p, number pages as pa, pb, pc, and so forth.
              The register tracking the suffixed page letter uses format
              “a” (see the “.af” request in groff(7)).  For example, the
              option -rX2 produces the following page numbers: 1, 2, 2a,
              2b, ..., 2aa, 2ab, and so on.

Files         top

              These are wrapper files to call 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

              Most man macros are contained in this file.  It also loads
              the extensions from an-ext.tmac (see below).

              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.

              The definitions for these macros are read after a page
              calls .TH, so they will replace any macros of the same
              names preceding it in your file.  If you use your own
              implementations of these macros, they must be defined
              after calling .TH to have any effect.  Furthermore, it is
              wise to define such page-local macros (if at all) after
              the “Name” section to accommodate timid mandb
              implementations that may give up their scan for indexing
              material early.

              Put local changes and customizations into this file.

                     .\" Use narrower indentation on terminals and similar.
                     .if n .nr IN 4n
                     .\" Put only one space after the end of a sentence.
                     .ss 12 0 \" See groff(7).
                     .\" Keep pages narrow even on wide terminals.
                     .if n .if \n[LL]>78 .nr LL 78n

              On multi-user systems, it is more considerate to users
              whose preferences may differ from the administrator's to
              be less aggressive with such settings, or to permit their
              override with a user-specific man.local file.  One way to
              achieve the latter is by placing the following at the end
              of /usr/local/share/groff/site-tmac/man.local.
                     .so \V[HOME]/.man.local
              The above request will produce a warning if $HOME/
              man.local does not exist; you may wish to include one in /
              etc/skel or an equivalent account configuration system.
              Furthermore, a security-sandboxed man(1) program may lack
              permission to open the file.

Notes         top

       Some tips on troubleshooting your man pages follow.

       • Do I ever need to use an empty macro argument ("")?
              Probably not.  When this seems necessary, often a shorter
              or clearer alternative is available.

                     Instead of...            this.
              .TP ""                         .TP
              .BI "" italic-text bold-text   .IB italic-text bold-text
              .TH foo 1 "" "foo 1.2.3"       .TH foo 1 yyyy-mm-dd "foo 1.2.3"
              .IP "" 4n                      .TP 4n
              .B one two "" three            .B one two three

              In the title heading (.TH), the date of the page's last
              revision is more important than packaging information; it
              should not be omitted.  Ideally, a page maintainer will
              keep both up to date.

              In the last example, the empty argument does have a subtly
              different effect than its suggested replacement; the empty
              argument causes an additional space character to be
              interpolated between the arguments “two” and “three”—but
              it is a regular breaking space, so it can be discarded at
              the end of an output line.  It is better not to be subtle,
              particularly with space, which can be overlooked in source
              and rendered forms.

       • .RS doesn't indent relative to my indented paragraph
              The .RS macro sets the left margin; that is, the position
              at which an ordinary paragraph (.PP and its synonyms) will
              be set.  .RS, .IP, .TP, and the deprecated .HP all use the
              same default indentation.  To create an inset relative to
              an indented paragraph, call .RS repeatedly until an
              acceptable indentation is achieved, or give .RS an
              indentation argument that is at least as much as the
              paragraph's indentation amount relative to an adjacent .PP
              paragraph.  See subsection “Horizontal and vertical
              spacing” above for the values.

       • .RE doesn't move the inset back 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
              The .RS macro takes an indentation amount as an argument;
              the .RE macro's argument is a specific inset level.  .RE 1
              goes to the level before any .RS macros were called, .RE 2
              goes to the level of the first .RS call you made, and so
              forth.  If you 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 insets are cleared and calls to .RE have no
              effect until .RS is used again.

Authors         top

       M. Douglas McIlroy ⟨⟩ designed,
       implemented, and documented the AT&T man macros, using them when
       he edited the first volume of the Version 7 Unix manual, a
       compilation of all man pages supplied by the system.

       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 ⟨esr@thyrsus

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

       tbl(1), eqn(1), and refer(1) are preprocessors used with man

       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_man(7), groff(7), groff_char(7), man(7)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨⟩.  If you have a bug report
       for this manual page, see ⟨⟩.
       This page was obtained from the project's upstream Git repository
       ⟨⟩ on 2021-04-01.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2021-03-29.)  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

groff 1.23.0.rc1.259-531129-dir1t3yMarch 2021           groff_man_style(7)

Pages that refer to this page: grotty(1)groff_man(7)