1GROFF_MAN(7) Miscellaneous Information Manual GROFF_MAN(7)
2
6 groff_man - GNU roff macro package for formatting man pages
7
9 groff -man [option ...] [input-file ...]
10 groff -m man [option ...] [input-file ...]
11
13 The man macro package for groff is used to produce manual pages
14 (“man pages”) like the one you are reading. GNU roff's implementation
15 was written by James Clark.
16 This document presents the macros thematically to aid learners; for
18 those needing only a quick reference, the following table lists them
19 alphabetically, with cross-references to appropriate subsections below.
20 Macro Meaning Subsection
22 ───────────────────────────────────────────────────────────────────
23 .B Bold Font style macros
24 .BI Bold, italic alternating Font style macros
25 .BR Bold, roman alternating Font style macros
26 .EE Example end Document structure macros
27 .EX Example begin Document structure macros
28 .I Italic Font style macros
29 .IB Italic, bold alternating Font style macros
30 .IP Indented paragraph Paragraph macros
31 .IR Italic, roman alternating Font style macros
32 .LP (Left) paragraph Paragraph macros
33 .ME Mail-to end Hyperlink and email macros
34 .MT Mail-to start Hyperlink and email macros
35 .OP (Command-line) option Command synopsis macros
36 .P Paragraph Paragraph macros
37 .PP Paragraph Paragraph macros
38 .RB Roman, bold alternating Font style macros
39 .RE Relative-indent end Document structure macros
40 .RI Roman, italic alternating Font style macros
41 .RS Relative-indent start Document structure macros
42 .SB Small bold Font style macros
43 .SH Section heading Document structure macros
44 .SM Small Font style macros
45 .SS Subection heading Document structure macros
46 .SY Synopsis start Command synopsis macros
47 .TH Title heading Document structure macros
48 .TP Tagged paragraph Paragraph macros
49 .TQ Tagged paragraph continuation Paragraph macros
50 .UE URL end Hyperlink and email macros
51 .UR URL start Hyperlink and email macros
52 .YS Synopsis end Command synopsis macros
53 Macros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC)
55 are described in subsection “Deprecated features”, below.
56 Macro reference preliminaries
58 Each macro is described in a tagged paragraph. Closely related macros,
59 such as .EX and .EE, are grouped together.
60 Optional macro arguments are indicated by surrounding them with square
62 brackets. If a macro accepts multiple arguments, arguments containing
63 whitespace must be double-quoted ("one two"), to be interpreted cor‐
64 rectly. Most macro arguments are strings that will be output as text;
65 exceptions are noted.
66 Bear in mind that groff is fundamentally a programming system for type‐
68 setting. Consequently, the verb “to set” is frequently used below in
69 the sense “to typeset”.
70 Document structure macros
72 The highest level of organization of a man page is determined by this
73 group of macros. .TH (title heading) identifies the document as a man
74 page and defines information enabling its indexing by mandb(8) or a
75 similar tool. Sections (.SH), one of which is mandatory and many of
76 which are standardized, facilitate quick location of relevant material
77 by the reader and aid the man page writer to discuss all essential
78 aspects of the topic. Subsections (.SS) are optional and permit sec‐
79 tions that grow long to develop in a controlled way. Many technical
80 discussions require examples; lengthy ones, especially those reflecting
81 multiple lines of input to or output from the system, are usefully
82 bracketed by .EX and .EE. When none of the foregoing meets a struc‐
83 tural demand, a section of the discussion can be manually indented
84 within .RS and .RE macros.
85 .TH title section
87 [footer-middle] [footer-outside] [header-middle] Define the
88 title of the man page as title and the section as section. See
89 man(1) for details on the section numbers and suffixes applica‐
90 ble to your system. title and section are positioned together
91 at the left and right in the header line (with section in paren‐
92 theses immediately appended to title). footer-middle is cen‐
93 tered in the footer line. footer-outside is positioned at the
94 left in the footer line (or at the left on even pages and at the
95 right on odd pages if double-sided printing is active). header-
96 middle is centered in the header line. If section is a simple
97 integer between 1 and 9 (inclusive), or is exactly “3p”, there
98 is no need to specify header-middle; the macro package will sup‐
99 ply text for it.
100 For HTML output, headers and footers are completely suppressed.
102 Additionally, this macro starts a new page; the page number is
104 reset to 1 (unless the -rC1 option is given on the command
105 line). This feature is intended only for formatting multiple
106 man pages.
107 A man page should contain exactly one .TH call at or near the
109 beginning of the file, prior to any other macro calls.
110 By convention, footer-middle is the most recent modification
112 date of the man page source document, and footer-outside is the
113 name and version or release of the project providing it.
114 .SH [ heading-text] Set heading-text as a section heading flush left.
116 The text following .SH up to the end of the line, or the text on
117 the next input line if .SH is given no arguments, is set in bold
118 (or the font specified by the string register HF) slightly
119 larger than the base font size. Additionally, the left margin
120 and indentation affecting subsequent text are reset to their
121 default values. Text on input lines after heading-text is set
122 as a normal paragraph (.PP).
123 The content of heading-text and ordering of sections has been
125 standardized by common practice, as has much of the layout of
126 material within sections. For example, a section called “Name”
127 or “NAME” must exist, must be the first section after the .TH
128 call, and must contain only a line of the form
129 page-topic[, ...] \- summary-description
130 for a man page to be properly indexed. See man(7) for the con‐
131 ventions prevailing on your system.
132 .SS [ subheading-text] Set subheading-text as a subsection heading
134 indented (by default) partway between a section heading and a
135 normally-indented paragraph (.PP). The text following .SS up to
136 the end of the line, or the text on the next input line if .SS
137 is given no arguments, is set in bold (or the font specified by
138 the string register HF) at the base font size. Additionally,
139 the left margin and indentation affecting subsequent text are
140 reset to their default values. Text on input lines after sub‐
141 heading-text is set as a normal paragraph (.PP).
142 .EX
144 .EE Begin and end example. After .EX, filling and hyphenation are
145 disabled and a constant-width (monospaced) font is selected.
146 Calling .EE enables filling and restores the previous hyphen‐
147 ation setting and font.
148 Example regions are useful for formatting code, shell sessions,
150 and text file contents.
151 These macros are defined on many (but not all) legacy Unix sys‐
153 tems running classic troff. To be certain your page will be
154 portable to those systems, copy their definitions from the
155 an-ext.tmac file of a groff installation.
156 .RS [ indent] Move the left margin to the right by the value indent,
158 if specified, and by a default amount otherwise; see subsection
159 “Horizontal and vertical spacing” below. Calls to .RS can be
160 nested; each call increments by 1 the indentation level used by
161 .RE. The indentation level prior to any .RS calls is 1.
162 .RE [ level] Move the left margin back to that corresponding to inden‐
164 tation level level. If no argument is given, move the left mar‐
165 gin one level back.
166 Paragraph macros
168 A typical paragraph (.PP) is set at the current left margin, which by
169 default is indented from the left margin of the output device. In man
170 pages and other technical literature, definition lists are frequently
171 encountered; these can be set as “tagged paragraphs” (.TP and .TQ),
172 which have one or more leading tags followed by a paragraph that has an
173 additional left indent. The indented paragraph (.IP) macro is useful
174 to continue the indented content of a narrative started with .TP, or to
175 present an itemized or ordered list.
176 .LP
178 .PP
179 .P Begin a new paragraph; these macros are synonymous. They break
180 the output line at the current position, followed by a vertical
181 space downward by a default amount (which can be changed by the
182 deprecated .PD macro). The font size and style are reset to
183 defaults; see subsection “Font style macros” below. Finally,
184 the left margin and indentation are reset to default values.
185 .TP [ indent] Set a tagged, indented paragraph. The input line fol‐
187 lowing this macro, known as the tag, is printed at the current
188 left margin. Subsequent text is indented by indent, if speci‐
189 fied, and by a default amount otherwise; see subsection “Hori‐
190 zontal and vertical spacing” below.
191 If the tag is not as wide as the indentation, the paragraph
193 starts on the same line as the tag, at the applicable indenta‐
194 tion, and continues on the following lines. Otherwise, the
195 descriptive part of the paragraph begins on the line following
196 the tag, entirely indented. The line containing the tag can
197 include a macro call, for instance to set the tag in bold with
198 .B.
199 .TP was used to write the first paragraph of this description of
201 .TP, and .IP the subsequent ones.
202 .TQ Set an additional tag for a paragraph tagged with .TP. The
204 pending output line is broken. The tag on the input line fol‐
205 lowing this macro and subsequent lines are handled as with .TP.
206 This macro is not defined on legacy Unix systems running classic
208 troff. To be certain your page will be portable to those sys‐
209 tems, copy its definition from the an-ext.tmac file of a groff
210 installation.
211 The descriptions of .LP, .PP, and .P above were written using
213 .TP and .TQ.
214 .IP [ tag] [indent] Set an indented paragraph with an optional tag.
216 The tag and indent arguments, if present, are handled as with
217 .TP, with the exception that the tag argument to .IP cannot
218 include a macro call.
219 Two convenient use cases for .IP are
221 (1) to start a new paragraph with the same indentation as
223 the previous .IP or .TP paragraph, if no indent argu‐
224 ment is given; and
225 (2) to set a paragraph with a short tag that is not
227 semantically important, such as a bullet (·)—obtained
228 with the ‘\(bu’ character escape—or list enumerator,
229 as seen in this very paragraph.
230 Command synopsis macros
232 Command synopses are a staple of section 1 and 8 man pages. These
233 macros aid you to construct one that has the classical Unix appearance.
234 Furthermore, some tools are able to interpret these macros semantically
235 and treat them appropriately for localization and/or presentation. A
236 command synopsis is wrapped in .SY/.YS calls, with command-line options
237 of some formats indicated by .OP.
238 These macros are not defined on legacy Unix systems running classic
240 troff. To be certain your page will be portable to those systems, copy
241 their definitions from the an-ext.tmac file of a groff installation.
242 .SY command
244 Begin synopsis. Hyphenation is turned off. The command argu‐
245 ment is set in bold. The output line is filled as normal, but
246 if a break is required, subsequent output lines are indented by
247 the width of command plus a space.
248 .OP option-name
250 [option-argument] Indicate an optional command parameter called
251 option-name, which is set in bold. If the option takes an argu‐
252 ment, specify option-argument using a noun, abbreviation, or
253 hyphenated noun phrase. If present, option-argument is preceded
254 by a space and set in italics. Square brackets (in roman) sur‐
255 round both arguments.
256 .YS End synopsis. Restore indentation and hyphenation to previous
258 values.
259 Multiple .SY/.YS blocks can be specified, for instance to distinguish
261 differing modes of operation of a complex command like tar(1); each
262 will be separated by a paragraph space.
263 .SY can also be repeated multiple times before a closing .YS, which is
265 useful to indicate synonymous ways of invoking a particular mode of
266 operation.
267 For example,
269 .SY groff
271 .OP \-abcegiklpstzCEGNRSUVXZ
272 .OP \-d cs
273 .OP \-f fam
274 .OP \-F dir
275 .OP \-I dir
276 .OP \-K arg
277 .OP \-L arg
278 .OP \-m name
279 .OP \-M dir
280 .OP \-n num
281 .OP \-o list
282 .OP \-P arg
283 .OP \-r cn
284 .OP \-T dev
285 .OP \-w name
286 .OP \-W name
287 .RI [ file
288 \&.\|.\|.\&]
289 .YS
290 .
291 .SY groff
292 .B \-h
293 .SY groff
294 .B \-\-help
295 .YS
296 produces the following output.
298 groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
300 [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
301 [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
302 [file ...]
303 groff -h
305 groff --help
306 Several features of the above example are of note.
308 · The empty request (.), which does nothing, is used for vertical
310 spacing in the input file for readability by the document main‐
311 tainer. Do not put empty lines in a roff source document.
312 · The command and option names are presented in bold to cue the
314 user that they should be input literally.
315 · Option dashes are specified with the ‘\-’ escape sequence; this
317 is an important practice to make them clearly visible and to
318 facilitate cut-and-paste from the rendered man page to a shell
319 prompt or text file.
320 · Option arguments and command operands are presented in italics
322 (underlined on some output devices, such as terminals and emula‐
323 tors), to cue the user that they must be replaced with appropri‐
324 ate text.
325 · Symbols that are neither to be typed literally nor simply
327 replaced appear in the roman style; brackets surround optional
328 arguments, and an ellipsis indicates that the previous syntacti‐
329 cal element may be repeated arbitrarily.
330 Some man pages use a brace-and-pipe notation such as
332 “{--diff|--compare}” to indicate that one and only one of the
333 ‘|’-separated items within the braces must be input. If this
334 braced construct is furthermore surrounded by square brackets,
335 it means that at most one of the items is accepted.
336 Authors of man pages should note the use of the zero-width space
338 escape sequence ‘\&’ on both sides of the ellipsis; this is a
339 good practice to avoid surprises in the event the ellipsis gets
340 refilled in your text editor. See “Portability”, below. The
341 morbidly curious may consult groff(7) regarding the narrow-space
342 escape sequence ‘\|’.
343 Hyperlink and email macros
345 Email addresses are bracketed with .MT/.ME and URL hyperlinks with
346 .UR/.UE.
347 These macros are not defined on legacy Unix systems running classic
349 troff. To be certain your page will be portable to those systems, copy
350 their definitions from the an-ext.tmac file of a groff installation.
351 .MT address
353 .ME [ punctuation] Identify address as an RFC 6068 addr-spec for a
354 “mailto:” URI with the text between the two macro calls as the
355 link text. A punctuation argument to .ME is placed at the end
356 of the link text without intervening space. Note that address
357 may not be visible in the output text, particularly if the man
358 page is being viewed as HTML. On a device that is not a
359 browser, address is set in angle brackets after the link text
360 and before punctuation.
361 When rendered by groff to a TTY or PostScript output device,
363 Contact
365 .MT fred.foonly@\:fubar.net
366 Fred Foonly
367 .ME
368 for more information.
369 displays as: “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for
371 more information.”.
372 The use of ‘\:’ to insert hyphenless discretionary breaks is a
374 groff extension and can be omitted.
375 .UR URL
377 .UE [ punctuation] Identify URL as an RFC 3986 URI hyperlink with the
378 text between the two macro calls as the link text. A punctua‐
379 tion argument to .UE is placed at the end of the link text with‐
380 out intervening space. Note that URL may not be visible in the
381 output text, particularly if the man page is being viewed as
382 HTML. On a device that is not a browser, URL is set in angle
383 brackets after the link text and before punctuation.
384 When rendered by groff to a TTY or PostScript output device,
386 The GNU Project of the Free Software Foundation hosts the
388 .UR https://\:www.gnu.org/\:software/\:groff/
389 Groff home page
390 .UE .
391 displays as: “The GNU Project of the Free Software Foundation
393 hosts the Groff home page ⟨https://www.gnu.org/software/
394 groff/⟩.”.
395 The use of ‘\:’ to insert hyphenless discretionary breaks is a
397 groff extension and can be omitted.
398 Font style macros
400 The man macro package is limited in its font styling options, offering
401 only bold (.B), italic (.I), and roman (the default). Italic text is
402 usually set underscored instead on terminals and other classical nroff-
403 style output devices. The .SM and .SB macros set text in roman or
404 bold, respectively, at a smaller point size; these differ visually from
405 regular-sized roman or bold text only on troff-style output devices.
406 The foregoing macros cause word breaks before and after their argu‐
407 ments, but it is often necessary to set text in different styles with‐
408 out intervening whitespace. The macros .BI, .BR, .IB, .IR, .RB, and
409 .RI, where ‘B’, ‘I’, and ‘R’ indicate bold, italic, and roman, respec‐
410 tively, set their odd- and even-numbered arguments in alternating
411 styles, with no whitespace separating them.
412 Because font styles are presentational rather than semantic, conflict‐
414 ing traditions have arisen regarding which font styles should be used
415 to mark file or path names, environment variables, in-line literals,
416 and even man page cross-references.
417 The default font size and family (for troff output devices) is 10-point
419 Times. The default style is roman.
420 .B [ text] Set text in bold. If the macro is given no arguments, the
422 text of the next input line is set in bold.
423 Use bold for literal portions of syntax synopses, for command-
425 line options in running text, and for literals that are major
426 topics of the subject under discussion; for example, this page
427 uses bold for macro and register names. In .EX/.EE examples of
428 interactive I/O (such as a shell session), set only the user-
429 typed input in bold.
430 .I [ text] Set text in italics. If the macro is given no arguments,
432 the text of the next input line is set in italics.
433 Use italics for file and path names, for environment variables,
435 for enumeration or preprocessor constants in C, for variable
436 (user-determined) portions of syntax synopses, for the first
437 occurrence only of a technical concept being introduced, for
438 names of works of software (including commands and functions,
439 but excluding names of operating systems or their kernels), and
440 anywhere a parameter requiring replacement by the user is
441 encountered. An exception involves variable text in a context
442 that is already marked up in italics, such as file or path names
443 with variable components; in such cases, follow the convention
444 of mathematical typography: set the file or path name in italics
445 as usual (see .IR below), but use roman for the variable part,
446 and italics again in running roman text when referring to the
447 variable material.
448 .SM [ text] Set text one point size smaller than the default size. If
450 the macro is given no arguments, the text of the next input line
451 is set smaller.
452 Note: nroff-style output devices, such as terminals, will render
454 text at the normal font size instead. Do not rely upon .SM to
455 communicate semantic information distinct from using roman style
456 at the normal size; it will be hidden from readers using such
457 devices.
458 .SB [ text] Set text in bold, one point size smaller than the default
460 size. If the macro is given no arguments, the text of the next
461 input line is set smaller and in bold.
462 Note: nroff-style output devices, such as terminals, will render
464 text in bold at the normal font size instead. Do not rely upon
465 .SB to communicate semantic information distinct from using bold
466 style at the normal size; it will be hidden from readers using
467 such devices.
468 Note what is not prescribed for setting in bold or italics above: ele‐
470 ments of “synopsis language” such as ellipses and brackets around
471 options; proper names and adjectives; titles of anything other than
472 works of literature or software; identifiers for standards documents or
473 technical reports such as CSTR #54, RFC 1918, Unicode 11.0, or
474 POSIX.1-2017; acronyms; and occurrences after the first of a technical
475 term or piece of jargon. Again, the names of operating systems and
476 their kernels are, by practically universal convention, set in roman.
477 Be frugal with the use of italics for emphasis, and particularly with
479 the use of bold. Brief runs of literal text, such as references to
480 individual characters or short strings, including section and subsec‐
481 tion headings of man pages, are suitable objects for quotation; see the
482 ‘\(lq’, ‘\(rq’, ‘\(oq’, and ‘\(cq’ escapes in subsection “Portability”
483 below.
484 Unlike the above font style macros, the font alternation macros below
486 accept only arguments on the same line as the macro call. If white‐
487 space is required within one of the arguments, first consider whether
488 the same result could be achieved with as much clarity by using the
489 single-style macros on separate input lines. When it cannot, double-
490 quote an argument with one or more embedded space characters. Setting
491 all three different styles within one whitespace-delimited word
492 presents challenges; it is possible with the ‘\c’ and/or ‘\f’ escapes,
493 but see subsection “Portability” below for caveats.
494 .BI bold-text italic-text
496 ... Set each argument in bold and italics, alternately.
497 .BI \-r name = n
499 .BR bold-text roman-text
501 ... Set each argument in bold and roman, alternately.
502 Any such change becomes effective with the first use of
504 .BR .NH ,
505 .I after
506 the new alias is defined.
507 .IB italic-text bold-text
509 ... Set each argument in italics and bold, alternately.
510 All macro package files must be named
512 .IB name .tmac
513 to fully use the
514 .I tmac
515 mechanism.
516 .IR italic-text roman-text
518 ... Set each argument in italics and roman, alternately.
519 This is the first command of the
521 .IR prologue .
522 .RB roman-text bold-text
524 ... Set each argument in roman and bold, alternately.
525 Also, the statement
527 .RB \(oq "delim on" \(cq
528 is not handled specially.
529 .RI roman-text italic-text
531 ... Set each argument in roman and italics, alternately.
532 .RI [ file
534 \&.\|.\|.\&]
535 Horizontal and vertical spacing
537 The indent argument accepted by .RS, .IP, .TP, and the deprecated .HP
538 is a number plus an optional scaling indicator. If no scaling indica‐
539 tor is given, the man package assumes ‘n’; that is, the width of a let‐
540 ter “n” in the font current when the macro is called. See section
541 “Numerical Expressions” in groff(7) for further details. An indent
542 specified in a call to .IP, .TP, or the deprecated .HP persists until
543 (1) another of these macros is called with an explicit indent argument,
544 or (2) .SH, .SS, or .PP or its synonyms is called; these clear the
545 indent entirely.
546 Indents set by .RS move the left margin and persist until .RS, .RE,
548 .SH, or .SS is called. The default indentation, exhibited by ordinary
549 .PP paragraphs not within an .RS/.RE relative indent, is 7.2n in troff
550 mode and 7n in nroff mode. The HTML output device is an exception; it
551 ignores indentation completely. This same indentation is used again
552 (additively) for the defaults of .IP, .TP, .RS, and the deprecated .HP.
553 Section headings (.SH) are set flush with the left margin of the output
554 device, and subsection headings (.SS) are indented 3n.
555 Resist the temptation to mock up tabular or multi-column output with
557 ASCII tab characters or the indentation arguments to .IP, .TP, .RS, or
558 the deprecated .HP; the result may not render comprehensibly on an out‐
559 put device you fail to check, or which is developed in the future. The
560 table preprocessor tbl(1) can likely meet your needs.
561 The following macros cause a line break with the insertion of vertical
563 space: .SH, .SS, .TP, .TQ, .PP (and its synonyms), .IP, and the depre‐
564 cated .HP. The default inter-section and inter-paragraph spacing is
565 1 line in nroff mode, and 0.4v in troff mode. (The deprecated macro
566 .PD can change this vertical spacing, but its use is discouraged.) The
567 macros .RS, .RE, .EX, and .EE also cause a break but no insertion of
568 vertical space.
569 Number registers
571 Number registers are described in section “Options” below.
572 String registers
574 The following strings are defined.
575 \*R expands to the character escape for the “registered sign” glyph,
577 ‘\(rg’, if available, and “(Reg.)” otherwise.
578 \*S expands to an escape setting the font size to the document
580 default.
581 \*(HF expands to the font identifier used to print headings and sub‐
583 headings. The default is ‘B’.
584 \*(lq
586 \*(rq expand to the character escapes for left and right double-quota‐
587 tion marks, ‘\(lq’ and ‘\(rq’, respectively.
588 \*(Tm expands to the character escape for the “trade mark sign” glyph,
590 ‘\(tm’, if available, and “(TM)” otherwise.
591 Interaction with preprocessors
593 When a preprocessor like tbl or eqn is needed, a hint can be given to
594 the man page formatter by making the first line of a man page look like
595 this:
596 '\" word
598 Note that the line starts with an apostrophe ('), not a dot, and that a
600 single space character follows the double quote. The word consists of
601 one letter for each needed preprocessor: ‘e’ for eqn, ‘r’ for refer,
602 and ‘t’ for tbl. Modern implementations of the man program interpret
603 this first line and automatically call the right preprocessor(s).
604 The usual tbl and eqn macros for table and equation inclusion, .TS,
606 .T&, .TE, .EQ, and .EN, may be used freely. Note that nroff output
607 devices are extremely limited in presentation of mathematical equa‐
608 tions.
609 Portability
611 The two major syntactical categories of roff languages are requests and
612 escapes. Since the man macros are implemented in terms of groff
613 requests and escapes, one can, in principle, supplement the functional‐
614 ity of man with these lower-level elements where necessary.
615 Note, however, that using raw groff requests is likely to make your
617 page render poorly on the class of viewers that transform it to HTML.
618 Some requests make implicit assumptions about things like character and
619 page sizes that may not hold in an HTML environment; also, many of
620 these viewers don't interpret the full groff vocabulary, a problem that
621 can lead to portions of your text being silently dropped.
622 For portability to modern viewers, it is best to write your page
624 entirely with the macros described in this page (except for the ones
625 identified as deprecated, which should be avoided). The macros we have
626 described as extensions (.EX/.EE, .SY/.OP/.YS, .UR/.UE, and .MT/.ME)
627 should be used with caution, as they may not yet be built in to some
628 viewer that is important to your audience. If in doubt, copy the
629 implementation into your page—after the .TH call and the “Name” sec‐
630 tion, to accommodate timid mandb implementations.
631 Similar caveats apply to escapes. Some escape sequences are however
633 required for correct typesetting even in man pages and usually do not
634 cause portability problems:
635 \" Comment. Everything after the double-quote to the end of the
637 input line is ignored. Whole-line comments are frequently
638 placed immediately after the empty request ‘.’.
639 \newline
641 Join the next input line to the current one. Except for the
642 update of the input line counter (used for diagnostic messages
643 and related purposes), a series of lines ending in backslash-
644 newline is transparent to groff. Use this escape to break
645 excessively input long lines for document maintenance.
646 \~ Adjustable, non-breaking space character. Use this escape to
648 prevent a break inside a short phrase or between a numerical
649 quantity and its corresponding unit(s).
650 Before starting the motor, set the output speed to\~1.
652 There are 1,024\~bytes in 1\~kiB.
653 CSTR\~#8 documents the B language.
654 \& Zero-width space. Append to an input line to prevent an end-of-
656 sentence punctuation sequence from being recognized as such, or
657 insert at the beginning of an input line to prevent a dot or
658 apostrophe from being interpreted as the beginning of a roff
659 request.
660 \(aq ASCII apostrophe. Use for syntax elements of programming lan‐
662 guages because some output devices might replace unescaped apos‐
663 trophes with right single quotation marks.
664 \(oq Opening single quotation mark.
666 \(cq Closing single quotation mark.
667 Use these for paired directional single quotes, ‘like this’.
669 \(dq ASCII double-quote. Sometimes needed after macro calls to pre‐
671 vent the interpretation of the ASCII quotation mark character
672 ‘"’ as the beginning or end of a macro argument.
673 \(lq Left double quotation mark.
675 \(rq Right double quotation mark.
676 Use these for paired directional double quotes, “like this”.
678 \(em Em-dash. Use for an interruption in a sentence—such as this
680 one.
681 \(en En-dash. Use to separate the two ends of a range, in particular
683 between numbers, for example: the digits 1–9.
684 \(ga ASCII grave accent. Use for syntax elements of programming lan‐
686 guages, for example shell command substitutions, because some
687 output devices might replace unescaped grave accents with left
688 single quotation marks.
689 \(ha ASCII circumflex accent. Use for syntax elements of programming
691 languages because some output devices might replace unescaped
692 circumflex accents with non-ASCII glyphs like the Unicode U+02C6
693 modifier letter circumflex.
694 \(ti ASCII tilde. Use for syntax elements of programming languages
696 because some output devices might replace unescaped tildes with
697 non-ASCII glyphs like the Unicode U+02DC small tilde.
698 \- Minus sign. Also use this to display syntax elements that
700 require the ASCII hyphen-minus character, for example command-
701 line options and C language operators. The unescaped ‘-’ input
702 character is not appropriate for these cases because it may ren‐
703 der as a hyphen on some output devices.
704 \c If this escape sequence occurs at the end of an input line, no
706 white space is inserted between the last glyph on it and the
707 first glyph resulting from the next input line. This is occa‐
708 sionally useful when three different fonts are needed in a sin‐
709 gle word.
710 Normally, the final output file should be named
712 .IB file .pdf\c
713 \&.
714 Note that when using this trick with the .BI or .RI macros, you
716 will need to manually add an italic correction escape ‘\/’
717 before the ‘\c’ due to way macros expand their arguments.
718 Files processed with
720 .B groff \-mom
721 (or
722 .BI "\-m " mom\/\c
723 ) produce PostScript output by default.
724 Alternatively, and perhaps with better portability, the ‘\f’
726 font escape sequence can be used; see below. Using ‘\c’ to
727 include the output from more than one input line into the next-
728 line argument of a .TP macro will render incorrectly with groff
729 1.22.3, mandoc 1.14.1, older versions of these programs, and
730 perhaps with some other formatters.
731 \e Widely used in man pages to represent a backslash output glyph.
733 It works reliably as long as the .ec request is not used, which
734 should never happen in man pages, and it is slightly more porta‐
735 ble than the more exact ‘\(rs’ (“reverse solidus”) escape
736 sequence.
737 \fB, \fI, \fR, \fP
739 Switch to bold, italic, roman, or back to the previous font,
740 respectively. Either these or ‘\c’ is needed when three differ‐
741 ent fonts are required in a single whitespace-delimited word.
742 .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]
744 .RB [ \-\-reference\-dictionary=\c
746 .IR name ]
747 Font escapes may be more portable than ‘\c’. As shown above, it
749 is up to you to account for italic corrections with ‘\/’ and
750 ‘\,’, which are themselves groff extensions, if desired and if
751 supported by your implementation.
752 Note that ‘\fP’ reliably returns to the style in use immediately
754 preceding the previous ‘\f’ escape only if no sectioning, para‐
755 graph, or font face macro calls have intervened.
756 As long as only two fonts are needed in any single whitespace-
758 delimited word, font alternation macros like .BI usually result
759 in more readable source code than ‘\f’ escapes do.
760 For maximum portability, escape sequences and special characters not
762 listed above are better avoided in man pages.
763 Deprecated features
765 Use of the following is discouraged.
766 .AT [ system [release]] Alter the footer for use with AT&T man pages,
768 overriding any definition of the footer-outside argument to .TH.
769 This macro exists only for compatibility; don't use it.
770 The first argument system can be:
772 3 7th edition (default)
774 4 System III
776 5 System V
778 The optional second argument release specifies the release num‐
780 ber, such as in “System V Release 3”.
781 .BT Set the page footer. Redefine this macro to get control of the
783 footer.
784 .DT Set tabs every 0.5 inches. Since this macro is always called
786 during a .TH macro, it makes sense to call it only if the tab
787 positions have been changed.
788 Use of this presentation-level macro is deprecated. It trans‐
790 lates poorly to HTML, under which exact whitespace control and
791 tabbing are not readily available. Thus, information or dis‐
792 tinctions that you use .DT to express are likely to be lost. If
793 you feel tempted to use it, you should probably be composing a
794 table using tbl(1) markup instead.
795 .HP [ indent] Set up a paragraph with a hanging left indentation. The
797 indent argument, if present, is handled as with .TP.
798 Use of this presentation-level macro is deprecated. While it is
800 universally portable to legacy Unix systems, a hanging indenta‐
801 tion cannot be expressed naturally under HTML, and many HTML-
802 based manual viewers simply interpret it as a starter for a nor‐
803 mal paragraph. Thus, any information or distinction you tried
804 to express with the indentation may be lost.
805 .PD [ vertical-space] Define the vertical space between paragraphs or
807 (sub)sections. The optional argument vertical-space specifies
808 the amount of space; the default scaling is ‘v’). Without an
809 argument, the spacing is reset to its default value; see “Hori‐
810 zontal and vertical spacing” above.
811 Use of this presentation-level macro is deprecated. It trans‐
813 lates poorly to HTML, under which exact control of inter-para‐
814 graph spacing is not readily available. Thus, information or
815 distinctions that you use .PD to express are likely to be lost.
816 .PT Set the page header. Redefine this macro to get control of the
818 header.
819 .UC [ version] Alter the footer for use with BSD man pages, overriding
821 any definition of the footer-outside argument to .TH. This
822 macro exists only for compatibility; don't use it.
823 The argument version can be:
825 3 3rd Berkeley Distribution (default)
827 4 4th Berkeley Distribution
829 5 4.2 Berkeley Distribution
831 6 4.3 Berkeley Distribution
833 7 4.4 Berkeley Distribution
835 History
837 According to its own man(7) page, Version 7 Unix (1979) supported all
838 of the macros described in this page not listed as GNU extensions,
839 except .P, .SB, .SS, and the deprecated .AT, .BT, .PT, and .UC. The
840 only string registers defined were R and S; no number registers were
841 documented.
842
844 The following groff options set number registers recognized and used by
845 the man macro package.
846 -rcR=1 Continuous rendering. Create a single, very long page instead
848 of multiple pages. This is the default in nroff mode. Use
849 -rcR=0 to disable it.
850 -rC1 Number pages continuously. If more than one man page is given
852 on the command line, number the pages continuously, rather than
853 starting each at 1.
854 -rD1 Enable double-sided printing. Footers for even and odd pages
856 are formatted differently; see the description of .TH in “Docu‐
857 ment structure macros”, above.
858 -rFT=footer-distance
860 Set distance of the footer, relative to the bottom of the page
861 if negative or relative to the top if positive, to footer-dis‐
862 tance. The default is -0.5i.
863 -rHY=flags
865 Set hyphenation flags. Permissible values of flags are docu‐
866 mented in section “Hyphenation” of groff(7). The default is 4
867 if continuous rendering is enabled (-rcR=1 above), and 6 other‐
868 wise.
869 -rIN=indent
871 Set the body text indentation (for normal paragraphs) to indent.
872 See “Horizontal and vertical spacing” above for the default
873 indentation value. For nroff, indent should always be an inte‐
874 ger multiple of unit ‘n’ to get consistent indentation.
875 -rLL=line-length
877 Set line length. If this option is not given, the line length
878 is set to respect any value set by a prior “.ll” request (which
879 must be in effect when the .TH macro is invoked), if this dif‐
880 fers from the built-in default for the formatter; otherwise it
881 defaults to 78n in nroff mode and 6.5i in troff mode.
882 Note that the use of a “.ll” request to initialize the line
884 length is supported for backward compatibility with some ver‐
885 sions of the man program; direct initialization of the LL regis‐
886 ter should always be preferred to the use of such a request. In
887 particular, note that a “.ll 65n” request does not preserve the
888 normal nroff default line length (the man default initialization
889 to 78n prevails), whereas the -rLL=65n option, or an equivalent
890 “.nr LL 65n” request preceding the use of the .TH macro, does
891 set a line length of 65n.
892 -rLT=title-length
894 Set title length. If this option is not given, the title length
895 defaults to the line length.
896 -rPn Start enumeration of pages at n rather than 1.
898 -rSpoint-size
900 Use point-size as the base document font size. Acceptable val‐
901 ues are 10, 11, or 12. See subsection “Font style macros” above
902 for the default.
903 -rSN=subsection-indent
905 Set subsection indentation to subsection-indent. See “Horizon‐
906 tal and vertical spacing” above for the default indentation
907 value.
908 -rXp After page p, number pages as pa, pb, pc, and so forth. For
910 example, the option -rX2 produces the following page numbers: 1,
911 2, 2a, 2b, 2c, and so on.
912
914 /usr/share/groff/1.22.4/tmac/man.tmac
915 /usr/share/groff/1.22.4/tmac/an.tmac
916 These are wrapper files to call andoc.tmac.
917 /usr/share/groff/1.22.4/tmac/andoc.tmac
919 This brief groff program detects whether the man or mdoc macro
920 package is being used by a document and loads the correct macro
921 definitions, taking advantage of the fact that pages using them
922 must call .TH or .Dd, respectively, as their first macro.
923 Because the wrappers above load this file, a man program or user
924 typing, for example, “groff -man page.1”, need not know which
925 package the file page.1 uses. Multiple man pages, in either
926 format, can be handled.
927 /usr/share/groff/1.22.4/tmac/an-old.tmac
929 Most man macros are contained in this file. It also loads the
930 GNU extensions from an-ext.tmac (see below).
931 /usr/share/groff/1.22.4/tmac/an-ext.tmac
933 The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
934 .UR/.UE, and .MT/.ME are contained in this file, which is writ‐
935 ten in classic troff and permissively licensed—not copylefted.
936 Man page authors concerned about portability to legacy Unix sys‐
937 tems are encouraged to copy these definitions into their pages,
938 and maintainers of troff implementations or work-alike systems
939 that format man pages are encouraged to re-use them.
940 Note that the definitions for these macros are read after the
942 call of .TH, so they will replace any macros of the same names
943 preceding it in your file. If you use your own implementations
944 of these macros, they must be defined after calling .TH to have
945 any effect.
946 /etc/groff/site-tmac/man.local
948 Local changes and customizations should be put into this file.
949
951 Some tips on troubleshooting your man pages follow.
952 · .RS doesn't indent relative to my indented paragraph
954 The .RS macro sets the indentation relative to the amount of a
955 normal paragraph (.PP and its synonyms). The same default
956 indentation amount is used for .RS, .IP, .TP, and the deprecated
957 .HP. If you need to start an indent relative to an indented
958 paragraph, call .RS repeatedly until an acceptable indentation
959 is achieved, or give .RS an indentation argument that is at
960 least as much as the paragraph's indentation amount relative to
961 an adjacent .PP paragraph. See “Horizontal and vertical spac‐
962 ing” above for the values.
963 · .RE doesn't reset the indent to the expected level
965 · warning: scale indicator invalid in this context
966 · warning: number register 'an-saved-margin
967 n' not defined
968 · warning: number register 'an-saved-prevailing-indent
969 n' not defined The .RS macro takes an indentation amount as an
970 argument; the .RE macro's argument is a specific indentation
971 level. .RE 1 goes to the level before any .RS macros were
972 called, .RE 2 goes to the level of the first .RS call you made,
973 and so forth. If you desire symmetry in your macro calls, sim‐
974 ply issue one .RE without an argument for each .RS that precedes
975 it.
976 After calls to the .SH and .SS sectioning macros, all relative
978 indents are cleared and calls to .RE have no effect.
979
981 The GNU version of the man macro package was written by James Clark and
982 contributors. The extension macros were written by Werner Lemberg ⟨wl@
983 gnu.org⟩ and Eric S. Raymond ⟨esr@thyrsus.com⟩.
984 This document was originally written for the Debian GNU/Linux system by
986 Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by
987 Werner Lemberg and G. Branden Robinson. The extension macros were doc‐
988 umented by Eric S. Raymond; he also originated the portability section,
989 to which Ingo Schwarze contributed most of the material on escape
990 sequences.
991
993 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
994 Lemberg, is the main groff documentation. You can browse it interac‐
995 tively with “info groff”.
996 tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
998 man(1) describes the man page formatter on your system.
1000 groff_mdoc(7) describes the groff version of the BSD-originated alter‐
1002 native macro package for man pages.
1003 groff(7), groff_char(7), man(7)
1005groff 1.22.4 3 November 2020 GROFF_MAN(7)