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 as‐
78 pects of the topic. Subsections (.SS) are optional and permit sections
79 that grow long to develop in a controlled way. Many technical discus‐
80 sions require examples; lengthy ones, especially those reflecting mul‐
81 tiple lines of input to or output from the system, are usefully brack‐
82 eted by .EX and .EE. When none of the foregoing meets a structural de‐
83 mand, a section of the discussion can be manually indented within .RS
84 and .RE macros.
85 .TH title section [footer-middle] [footer-outside] [header-middle]
87 Define the title of the man page as title and the section as
88 section. See man(1) for details on the section numbers and suf‐
89 fixes applicable to your system. title and section are posi‐
90 tioned together at the left and right in the header line (with
91 section in parentheses immediately appended to title). footer-
92 middle is centered in the footer line. footer-outside is posi‐
93 tioned at the left in the footer line (or at the left on even
94 pages and at the right on odd pages if double-sided printing is
95 active). header-middle is centered in the header line. If sec‐
96 tion is a simple integer between 1 and 9 (inclusive), or is ex‐
97 actly “3p”, there is no need to specify header-middle; the macro
98 package will supply text for it.
99 For HTML output, headers and footers are completely suppressed.
101 Additionally, this macro starts a new page; the page number is
103 reset to 1 (unless the -rC1 option is given on the command
104 line). This feature is intended only for formatting multiple
105 man pages.
106 A man page should contain exactly one .TH call at or near the
108 beginning of the file, prior to any other macro calls.
109 By convention, footer-middle is the most recent modification
111 date of the man page source document, and footer-outside is the
112 name and version or release of the project providing it.
113 .SH [heading-text]
115 Set heading-text as a section heading flush left. The text fol‐
116 lowing .SH up to the end of the line, or the text on the next
117 input line if .SH is given no arguments, is set in bold (or the
118 font specified by the string register HF) slightly larger than
119 the base font size. Additionally, the left margin and indenta‐
120 tion affecting subsequent text are reset to their default val‐
121 ues. Text on input lines after heading-text is set as a normal
122 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]
134 Set subheading-text as a subsection heading indented (by de‐
135 fault) partway between a section heading and a normally-indented
136 paragraph (.PP). The text following .SS up to the end of the
137 line, or the text on the next input line if .SS is given no ar‐
138 guments, is set in bold (or the font specified by the string
139 register HF) at the base font size. Additionally, the left mar‐
140 gin and indentation affecting subsequent text are reset to their
141 default values. Text on input lines after subheading-text is
142 set as a normal paragraph (.PP).
143 .EX
145 .EE Begin and end example. After .EX, filling and hyphenation are
146 disabled and a constant-width (monospaced) font is selected.
147 Calling .EE enables filling and restores the previous hyphena‐
148 tion setting and font.
149 Example regions are useful for formatting code, shell sessions,
151 and text file contents.
152 These macros are defined on many (but not all) legacy Unix sys‐
154 tems running classic troff. To be certain your page will be
155 portable to those systems, copy their definitions from the
156 an-ext.tmac file of a groff installation.
157 .RS [indent]
159 Move the left margin to the right by the value indent, if speci‐
160 fied, and by a default amount otherwise; see subsection “Hori‐
161 zontal and vertical spacing” below. Calls to .RS can be nested;
162 each call increments by 1 the indentation level used by .RE.
163 The indentation level prior to any .RS calls is 1.
164 .RE [level]
166 Move the left margin back to that corresponding to indentation
167 level level. If no argument is given, move the left margin one
168 level back.
169 Paragraph macros
171 A typical paragraph (.PP) is set at the current left margin, which by
172 default is indented from the left margin of the output device. In man
173 pages and other technical literature, definition lists are frequently
174 encountered; these can be set as “tagged paragraphs” (.TP and .TQ),
175 which have one or more leading tags followed by a paragraph that has an
176 additional left indent. The indented paragraph (.IP) macro is useful
177 to continue the indented content of a narrative started with .TP, or to
178 present an itemized or ordered list.
179 .LP
181 .PP
182 .P Begin a new paragraph; these macros are synonymous. They break
183 the output line at the current position, followed by a vertical
184 space downward by a default amount (which can be changed by the
185 deprecated .PD macro). The font size and style are reset to de‐
186 faults; see subsection “Font style macros” below. Finally, the
187 left margin and indentation are reset to default values.
188 .TP [indent]
190 Set a tagged, indented paragraph. The input line following this
191 macro, known as the tag, is printed at the current left margin.
192 Subsequent text is indented by indent, if specified, and by a
193 default amount otherwise; see subsection “Horizontal and verti‐
194 cal spacing” below.
195 If the tag is not as wide as the indentation, the paragraph
197 starts on the same line as the tag, at the applicable indenta‐
198 tion, and continues on the following lines. Otherwise, the de‐
199 scriptive part of the paragraph begins on the line following the
200 tag, entirely indented. The line containing the tag can include
201 a macro call, for instance to set the tag in bold with .B.
202 .TP was used to write the first paragraph of this description of
204 .TP, and .IP the subsequent ones.
205 .TQ Set an additional tag for a paragraph tagged with .TP. The
207 pending output line is broken. The tag on the input line fol‐
208 lowing this macro and subsequent lines are handled as with .TP.
209 This macro is not defined on legacy Unix systems running classic
211 troff. To be certain your page will be portable to those sys‐
212 tems, copy its definition from the an-ext.tmac file of a groff
213 installation.
214 The descriptions of .LP, .PP, and .P above were written using
216 .TP and .TQ.
217 .IP [tag] [indent]
219 Set an indented paragraph with an optional tag. The tag and in‐
220 dent arguments, if present, are handled as with .TP, with the
221 exception that the tag argument to .IP cannot include a macro
222 call.
223 Two convenient use cases for .IP are
225 (1) to start a new paragraph with the same indentation as
227 the previous .IP or .TP paragraph, if no indent argu‐
228 ment is given; and
229 (2) to set a paragraph with a short tag that is not se‐
231 mantically important, such as a bullet (•)—obtained
232 with the ‘\(bu’ character escape—or list enumerator,
233 as seen in this very paragraph.
234 Command synopsis macros
236 Command synopses are a staple of section 1 and 8 man pages. These
237 macros aid you to construct one that has the classical Unix appearance.
238 Furthermore, some tools are able to interpret these macros semantically
239 and treat them appropriately for localization and/or presentation. A
240 command synopsis is wrapped in .SY/.YS calls, with command-line options
241 of some formats indicated by .OP.
242 These macros are not defined on legacy Unix systems running classic
244 troff. To be certain your page will be portable to those systems, copy
245 their definitions from the an-ext.tmac file of a groff installation.
246 .SY command
248 Begin synopsis. Hyphenation is turned off. The command argu‐
249 ment is set in bold. The output line is filled as normal, but
250 if a break is required, subsequent output lines are indented by
251 the width of command plus a space.
252 .OP option-name [option-argument]
254 Indicate an optional command parameter called option-name, which
255 is set in bold. If the option takes an argument, specify op‐
256 tion-argument using a noun, abbreviation, or hyphenated noun
257 phrase. If present, option-argument is preceded by a space and
258 set in italics. Square brackets (in roman) surround both argu‐
259 ments.
260 .YS End synopsis. Restore indentation and hyphenation to previous
262 values.
263 Multiple .SY/.YS blocks can be specified, for instance to distinguish
265 differing modes of operation of a complex command like tar(1); each
266 will be separated by a paragraph space.
267 .SY can also be repeated multiple times before a closing .YS, which is
269 useful to indicate synonymous ways of invoking a particular mode of op‐
270 eration.
271 For example,
273 .SY groff
275 .OP \-abcegiklpstzCEGNRSUVXZ
276 .OP \-d cs
277 .OP \-f fam
278 .OP \-F dir
279 .OP \-I dir
280 .OP \-K arg
281 .OP \-L arg
282 .OP \-m name
283 .OP \-M dir
284 .OP \-n num
285 .OP \-o list
286 .OP \-P arg
287 .OP \-r cn
288 .OP \-T dev
289 .OP \-w name
290 .OP \-W name
291 .RI [ file
292 \&.\|.\|.\&]
293 .YS
294 .
295 .SY groff
296 .B \-h
297 .SY groff
298 .B \-\-help
299 .YS
300 produces the following output.
302 groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
304 [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
305 [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
306 [file ...]
307 groff -h
309 groff --help
310 Several features of the above example are of note.
312 • The empty request (.), which does nothing, is used for vertical
314 spacing in the input file for readability by the document main‐
315 tainer. Do not put empty lines in a roff source document.
316 • The command and option names are presented in bold to cue the
318 user that they should be input literally.
319 • Option dashes are specified with the ‘\-’ escape sequence; this
321 is an important practice to make them clearly visible and to fa‐
322 cilitate cut-and-paste from the rendered man page to a shell
323 prompt or text file.
324 • Option arguments and command operands are presented in italics
326 (underlined on some output devices, such as terminals and emula‐
327 tors), to cue the user that they must be replaced with appropri‐
328 ate text.
329 • Symbols that are neither to be typed literally nor simply re‐
331 placed appear in the roman style; brackets surround optional ar‐
332 guments, and an ellipsis indicates that the previous syntactical
333 element may be repeated arbitrarily.
334 Some man pages use a brace-and-pipe notation such as
336 “{--diff|--compare}” to indicate that one and only one of the
337 ‘|’-separated items within the braces must be input. If this
338 braced construct is furthermore surrounded by square brackets,
339 it means that at most one of the items is accepted.
340 Authors of man pages should note the use of the zero-width space
342 escape sequence ‘\&’ on both sides of the ellipsis; this is a
343 good practice to avoid surprises in the event the ellipsis gets
344 refilled in your text editor. See “Portability”, below. The
345 morbidly curious may consult groff(7) regarding the narrow-space
346 escape sequence ‘\|’.
347 Hyperlink and email macros
349 Email addresses are bracketed with .MT/.ME and URL hyperlinks with
350 .UR/.UE.
351 These macros are not defined on legacy Unix systems running classic
353 troff. To be certain your page will be portable to those systems, copy
354 their definitions from the an-ext.tmac file of a groff installation.
355 .MT address
357 .ME [punctuation]
358 Identify address as an RFC 6068 addr-spec for a “mailto:” URI
359 with the text between the two macro calls as the link text. A
360 punctuation argument to .ME is placed at the end of the link
361 text without intervening space. Note that address may not be
362 visible in the output text, particularly if the man page is be‐
363 ing viewed as HTML. On a device that is not a browser, address
364 is set in angle brackets after the link text and before punctua‐
365 tion.
366 When rendered by groff to a TTY or PostScript output device,
368 Contact
370 .MT fred.foonly@\:fubar.net
371 Fred Foonly
372 .ME
373 for more information.
374 displays as: “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for
376 more information.”.
377 The use of ‘\:’ to insert hyphenless discretionary breaks is a
379 groff extension and can be omitted.
380 .UR URL
382 .UE [punctuation]
383 Identify URL as an RFC 3986 URI hyperlink with the text between
384 the two macro calls as the link text. A punctuation argument to
385 .UE is placed at the end of the link text without intervening
386 space. Note that URL may not be visible in the output text,
387 particularly if the man page is being viewed as HTML. On a de‐
388 vice that is not a browser, URL is set in angle brackets after
389 the link text and before punctuation.
390 When rendered by groff to a TTY or PostScript output device,
392 The GNU Project of the Free Software Foundation hosts the
394 .UR https://\:www.gnu.org/\:software/\:groff/
395 Groff home page
396 .UE .
397 displays as: “The GNU Project of the Free Software Foundation
399 hosts the Groff home page ⟨https://www.gnu.org/software/
400 groff/⟩.”.
401 The use of ‘\:’ to insert hyphenless discretionary breaks is a
403 groff extension and can be omitted.
404 Font style macros
406 The man macro package is limited in its font styling options, offering
407 only bold (.B), italic (.I), and roman (the default). Italic text is
408 usually set underscored instead on terminals and other classical nroff-
409 style output devices. The .SM and .SB macros set text in roman or
410 bold, respectively, at a smaller point size; these differ visually from
411 regular-sized roman or bold text only on troff-style output devices.
412 The foregoing macros cause word breaks before and after their argu‐
413 ments, but it is often necessary to set text in different styles with‐
414 out intervening whitespace. The macros .BI, .BR, .IB, .IR, .RB, and
415 .RI, where ‘B’, ‘I’, and ‘R’ indicate bold, italic, and roman, respec‐
416 tively, set their odd- and even-numbered arguments in alternating
417 styles, with no whitespace separating them.
418 Because font styles are presentational rather than semantic, conflict‐
420 ing traditions have arisen regarding which font styles should be used
421 to mark file or path names, environment variables, in-line literals,
422 and even man page cross-references.
423 The default font size and family (for troff output devices) is 10-point
425 Times. The default style is roman.
426 .B [text]
428 Set text in bold. If the macro is given no arguments, the text
429 of the next input line is set in bold.
430 Use bold for literal portions of syntax synopses, for command-
432 line options in running text, and for literals that are major
433 topics of the subject under discussion; for example, this page
434 uses bold for macro and register names. In .EX/.EE examples of
435 interactive I/O (such as a shell session), set only the user-
436 typed input in bold.
437 .I [text]
439 Set text in italics. If the macro is given no arguments, the
440 text of the next input line is set in italics.
441 Use italics for file and path names, for environment variables,
443 for enumeration or preprocessor constants in C, for variable
444 (user-determined) portions of syntax synopses, for the first oc‐
445 currence only of a technical concept being introduced, for names
446 of works of software (including commands and functions, but ex‐
447 cluding names of operating systems or their kernels), and any‐
448 where a parameter requiring replacement by the user is encoun‐
449 tered. An exception involves variable text in a context that is
450 already marked up in italics, such as file or path names with
451 variable components; in such cases, follow the convention of
452 mathematical typography: set the file or path name in italics as
453 usual (see .IR below), but use roman for the variable part, and
454 italics again in running roman text when referring to the vari‐
455 able material.
456 .SM [text]
458 Set text one point size smaller than the default size. If the
459 macro is given no arguments, the text of the next input line is
460 set smaller.
461 Note: nroff-style output devices, such as terminals, will render
463 text at the normal font size instead. Do not rely upon .SM to
464 communicate semantic information distinct from using roman style
465 at the normal size; it will be hidden from readers using such
466 devices.
467 .SB [text]
469 Set text in bold, one point size smaller than the default size.
470 If the macro is given no arguments, the text of the next input
471 line is set smaller and in bold.
472 Note: nroff-style output devices, such as terminals, will render
474 text in bold at the normal font size instead. Do not rely upon
475 .SB to communicate semantic information distinct from using bold
476 style at the normal size; it will be hidden from readers using
477 such devices.
478 Note what is not prescribed for setting in bold or italics above: ele‐
480 ments of “synopsis language” such as ellipses and brackets around op‐
481 tions; proper names and adjectives; titles of anything other than works
482 of literature or software; identifiers for standards documents or tech‐
483 nical reports such as CSTR #54, RFC 1918, Unicode 11.0, or
484 POSIX.1-2017; acronyms; and occurrences after the first of a technical
485 term or piece of jargon. Again, the names of operating systems and
486 their kernels are, by practically universal convention, set in roman.
487 Be frugal with the use of italics for emphasis, and particularly with
489 the use of bold. Brief runs of literal text, such as references to in‐
490 dividual characters or short strings, including section and subsection
491 headings of man pages, are suitable objects for quotation; see the
492 ‘\(lq’, ‘\(rq’, ‘\(oq’, and ‘\(cq’ escapes in subsection “Portability”
493 below.
494 Unlike the above font style macros, the font alternation macros below
496 accept only arguments on the same line as the macro call. If white‐
497 space is required within one of the arguments, first consider whether
498 the same result could be achieved with as much clarity by using the
499 single-style macros on separate input lines. When it cannot, double-
500 quote an argument with one or more embedded space characters. Setting
501 all three different styles within one whitespace-delimited word
502 presents challenges; it is possible with the ‘\c’ and/or ‘\f’ escapes,
503 but see subsection “Portability” below for caveats.
504 .BI bold-text italic-text ...
506 Set each argument in bold and italics, alternately.
507 .BI \-r name = n
509 .BR bold-text roman-text ...
511 Set each argument in bold and roman, alternately.
512 Any such change becomes effective with the first use of
514 .BR .NH ,
515 .I after
516 the new alias is defined.
517 .IB italic-text bold-text ...
519 Set each argument in italics and bold, alternately.
520 All macro package files must be named
522 .IB name .tmac
523 to fully use the
524 .I tmac
525 mechanism.
526 .IR italic-text roman-text ...
528 Set each argument in italics and roman, alternately.
529 This is the first command of the
531 .IR prologue .
532 .RB roman-text bold-text ...
534 Set each argument in roman and bold, alternately.
535 Also, the statement
537 .RB \(oq "delim on" \(cq
538 is not handled specially.
539 .RI roman-text italic-text ...
541 Set each argument in roman and italics, alternately.
542 .RI [ file
544 \&.\|.\|.\&]
545 Horizontal and vertical spacing
547 The indent argument accepted by .RS, .IP, .TP, and the deprecated .HP
548 is a number plus an optional scaling indicator. If no scaling indica‐
549 tor is given, the man package assumes ‘n’; that is, the width of a let‐
550 ter “n” in the font current when the macro is called. See section “Nu‐
551 merical Expressions” in groff(7) for further details. An indent speci‐
552 fied in a call to .IP, .TP, or the deprecated .HP persists until (1)
553 another of these macros is called with an explicit indent argument, or
554 (2) .SH, .SS, or .PP or its synonyms is called; these clear the indent
555 entirely.
556 Indents set by .RS move the left margin and persist until .RS, .RE,
558 .SH, or .SS is called. The default indentation, exhibited by ordinary
559 .PP paragraphs not within an .RS/.RE relative indent, is 7.2n in troff
560 mode and 7n in nroff mode. The HTML output device is an exception; it
561 ignores indentation completely. This same indentation is used again
562 (additively) for the defaults of .IP, .TP, .RS, and the deprecated .HP.
563 Section headings (.SH) are set flush with the left margin of the output
564 device, and subsection headings (.SS) are indented 3n.
565 Resist the temptation to mock up tabular or multi-column output with
567 ASCII tab characters or the indentation arguments to .IP, .TP, .RS, or
568 the deprecated .HP; the result may not render comprehensibly on an out‐
569 put device you fail to check, or which is developed in the future. The
570 table preprocessor tbl(1) can likely meet your needs.
571 The following macros cause a line break with the insertion of vertical
573 space: .SH, .SS, .TP, .TQ, .PP (and its synonyms), .IP, and the depre‐
574 cated .HP. The default inter-section and inter-paragraph spacing is
575 1 line in nroff mode, and 0.4v in troff mode. (The deprecated macro
576 .PD can change this vertical spacing, but its use is discouraged.) The
577 macros .RS, .RE, .EX, and .EE also cause a break but no insertion of
578 vertical space.
579 Number registers
581 Number registers are described in section “Options” below.
582 String registers
584 The following strings are defined.
585 \*R expands to the character escape for the “registered sign” glyph,
587 ‘\(rg’, if available, and “(Reg.)” otherwise.
588 \*S expands to an escape setting the font size to the document de‐
590 fault.
591 \*(HF expands to the font identifier used to print headings and sub‐
593 headings. The default is ‘B’.
594 \*(lq
596 \*(rq expand to the character escapes for left and right double-quota‐
597 tion marks, ‘\(lq’ and ‘\(rq’, respectively.
598 \*(Tm expands to the character escape for the “trade mark sign” glyph,
600 ‘\(tm’, if available, and “(TM)” otherwise.
601 Interaction with preprocessors
603 When a preprocessor like tbl or eqn is needed, a hint can be given to
604 the man page formatter by making the first line of a man page look like
605 this:
606 '\" word
608 Note that the line starts with an apostrophe ('), not a dot, and that a
610 single space character follows the double quote. The word consists of
611 one letter for each needed preprocessor: ‘e’ for eqn, ‘r’ for refer,
612 and ‘t’ for tbl. Modern implementations of the man program interpret
613 this first line and automatically call the right preprocessor(s).
614 The usual tbl and eqn macros for table and equation inclusion, .TS,
616 .T&, .TE, .EQ, and .EN, may be used freely. Note that nroff output de‐
617 vices are extremely limited in presentation of mathematical equations.
618 Portability
620 The two major syntactical categories of roff languages are requests and
621 escapes. Since the man macros are implemented in terms of groff re‐
622 quests and escapes, one can, in principle, supplement the functionality
623 of man with these lower-level elements where necessary.
624 Note, however, that using raw groff requests is likely to make your
626 page render poorly on the class of viewers that transform it to HTML.
627 Some requests make implicit assumptions about things like character and
628 page sizes that may not hold in an HTML environment; also, many of
629 these viewers don't interpret the full groff vocabulary, a problem that
630 can lead to portions of your text being silently dropped.
631 For portability to modern viewers, it is best to write your page en‐
633 tirely with the macros described in this page (except for the ones
634 identified as deprecated, which should be avoided). The macros we have
635 described as extensions (.EX/.EE, .SY/.OP/.YS, .UR/.UE, and .MT/.ME)
636 should be used with caution, as they may not yet be built in to some
637 viewer that is important to your audience. If in doubt, copy the im‐
638 plementation into your page—after the .TH call and the “Name” section,
639 to accommodate timid mandb implementations.
640 Similar caveats apply to escapes. Some escape sequences are however
642 required for correct typesetting even in man pages and usually do not
643 cause portability problems:
644 \" Comment. Everything after the double-quote to the end of the
646 input line is ignored. Whole-line comments are frequently
647 placed immediately after the empty request ‘.’.
648 \newline
650 Join the next input line to the current one. Except for the up‐
651 date of the input line counter (used for diagnostic messages and
652 related purposes), a series of lines ending in backslash-newline
653 is transparent to groff. Use this escape to break excessively
654 input long lines for document maintenance.
655 \~ Adjustable, non-breaking space character. Use this escape to
657 prevent a break inside a short phrase or between a numerical
658 quantity and its corresponding unit(s).
659 Before starting the motor, set the output speed to\~1.
661 There are 1,024\~bytes in 1\~kiB.
662 CSTR\~#8 documents the B language.
663 \& Zero-width space. Append to an input line to prevent an end-of-
665 sentence punctuation sequence from being recognized as such, or
666 insert at the beginning of an input line to prevent a dot or
667 apostrophe from being interpreted as the beginning of a roff re‐
668 quest.
669 \(aq ASCII apostrophe. Use for syntax elements of programming lan‐
671 guages because some output devices might replace unescaped apos‐
672 trophes with right single quotation marks.
673 \(oq Opening single quotation mark.
675 \(cq Closing single quotation mark.
676 Use these for paired directional single quotes, ‘like this’.
678 \(dq ASCII double-quote. Sometimes needed after macro calls to pre‐
680 vent the interpretation of the ASCII quotation mark character
681 ‘"’ as the beginning or end of a macro argument.
682 \(lq Left double quotation mark.
684 \(rq Right double quotation mark.
685 Use these for paired directional double quotes, “like this”.
687 \(em Em-dash. Use for an interruption in a sentence—such as this
689 one.
690 \(en En-dash. Use to separate the two ends of a range, in particular
692 between numbers, for example: the digits 1–9.
693 \(ga ASCII grave accent. Use for syntax elements of programming lan‐
695 guages, for example shell command substitutions, because some
696 output devices might replace unescaped grave accents with left
697 single quotation marks.
698 \(ha ASCII circumflex accent. Use for syntax elements of programming
700 languages because some output devices might replace unescaped
701 circumflex accents with non-ASCII glyphs like the Unicode U+02C6
702 modifier letter circumflex.
703 \(ti ASCII tilde. Use for syntax elements of programming languages
705 because some output devices might replace unescaped tildes with
706 non-ASCII glyphs like the Unicode U+02DC small tilde.
707 \- Minus sign. Also use this to display syntax elements that re‐
709 quire the ASCII hyphen-minus character, for example command-line
710 options and C language operators. The unescaped ‘-’ input char‐
711 acter is not appropriate for these cases because it may render
712 as a hyphen on some output devices.
713 \c If this escape sequence occurs at the end of an input line, no
715 white space is inserted between the last glyph on it and the
716 first glyph resulting from the next input line. This is occa‐
717 sionally useful when three different fonts are needed in a sin‐
718 gle word.
719 Normally, the final output file should be named
721 .IB file .pdf\c
722 \&.
723 Note that when using this trick with the .BI or .RI macros, you
725 will need to manually add an italic correction escape ‘\/’ be‐
726 fore the ‘\c’ due to way macros expand their arguments.
727 Files processed with
729 .B groff \-mom
730 (or
731 .BI "\-m " mom\/\c
732 ) produce PostScript output by default.
733 Alternatively, and perhaps with better portability, the ‘\f’
735 font escape sequence can be used; see below. Using ‘\c’ to in‐
736 clude the output from more than one input line into the next-
737 line argument of a .TP macro will render incorrectly with groff
738 1.22.3, mandoc 1.14.1, older versions of these programs, and
739 perhaps with some other formatters.
740 \e Widely used in man pages to represent a backslash output glyph.
742 It works reliably as long as the .ec request is not used, which
743 should never happen in man pages, and it is slightly more porta‐
744 ble than the more exact ‘\(rs’ (“reverse solidus”) escape se‐
745 quence.
746 \fB, \fI, \fR, \fP
748 Switch to bold, italic, roman, or back to the previous font, re‐
749 spectively. Either these or ‘\c’ is needed when three different
750 fonts are required in a single whitespace-delimited word.
751 .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]
753 .RB [ \-\-reference\-dictionary=\c
755 .IR name ]
756 Font escapes may be more portable than ‘\c’. As shown above, it
758 is up to you to account for italic corrections with ‘\/’ and
759 ‘\,’, which are themselves groff extensions, if desired and if
760 supported by your implementation.
761 Note that ‘\fP’ reliably returns to the style in use immediately
763 preceding the previous ‘\f’ escape only if no sectioning, para‐
764 graph, or font face macro calls have intervened.
765 As long as only two fonts are needed in any single whitespace-
767 delimited word, font alternation macros like .BI usually result
768 in more readable source code than ‘\f’ escapes do.
769 For maximum portability, escape sequences and special characters not
771 listed above are better avoided in man pages.
772 Deprecated features
774 Use of the following is discouraged.
775 .AT [system [release]]
777 Alter the footer for use with AT&T man pages, overriding any
778 definition of the footer-outside argument to .TH. This macro
779 exists only for compatibility; don't use it.
780 The first argument system can be:
782 3 7th edition (default)
784 4 System III
786 5 System V
788 The optional second argument release specifies the release num‐
790 ber, such as in “System V Release 3”.
791 .BT Set the page footer. Redefine this macro to get control of the
793 footer.
794 .DT Set tabs every 0.5 inches. Since this macro is always called
796 during a .TH macro, it makes sense to call it only if the tab
797 positions have been changed.
798 Use of this presentation-level macro is deprecated. It trans‐
800 lates poorly to HTML, under which exact whitespace control and
801 tabbing are not readily available. Thus, information or dis‐
802 tinctions that you use .DT to express are likely to be lost. If
803 you feel tempted to use it, you should probably be composing a
804 table using tbl(1) markup instead.
805 .HP [indent]
807 Set up a paragraph with a hanging left indentation. The indent
808 argument, if present, is handled as with .TP.
809 Use of this presentation-level macro is deprecated. While it is
811 universally portable to legacy Unix systems, a hanging indenta‐
812 tion cannot be expressed naturally under HTML, and many HTML-
813 based manual viewers simply interpret it as a starter for a nor‐
814 mal paragraph. Thus, any information or distinction you tried
815 to express with the indentation may be lost.
816 .PD [vertical-space]
818 Define the vertical space between paragraphs or (sub)sections.
819 The optional argument vertical-space specifies the amount of
820 space; the default scaling is ‘v’). Without an argument, the
821 spacing is reset to its default value; see “Horizontal and ver‐
822 tical spacing” above.
823 Use of this presentation-level macro is deprecated. It trans‐
825 lates poorly to HTML, under which exact control of inter-para‐
826 graph spacing is not readily available. Thus, information or
827 distinctions that you use .PD to express are likely to be lost.
828 .PT Set the page header. Redefine this macro to get control of the
830 header.
831 .UC [version]
833 Alter the footer for use with BSD man pages, overriding any def‐
834 inition of the footer-outside argument to .TH. This macro ex‐
835 ists only for compatibility; don't use it.
836 The argument version can be:
838 3 3rd Berkeley Distribution (default)
840 4 4th Berkeley Distribution
842 5 4.2 Berkeley Distribution
844 6 4.3 Berkeley Distribution
846 7 4.4 Berkeley Distribution
848 History
850 According to its own man(7) page, Version 7 Unix (1979) supported all
851 of the macros described in this page not listed as GNU extensions, ex‐
852 cept .P, .SB, .SS, and the deprecated .AT, .BT, .PT, and .UC. The only
853 string registers defined were R and S; no number registers were docu‐
854 mented.
855
857 The following groff options set number registers recognized and used by
858 the man macro package.
859 -rcR=1 Continuous rendering. Create a single, very long page instead
861 of multiple pages. This is the default in nroff mode. Use
862 -rcR=0 to disable it.
863 -rC1 Number pages continuously. If more than one man page is given
865 on the command line, number the pages continuously, rather than
866 starting each at 1.
867 -rD1 Enable double-sided printing. Footers for even and odd pages
869 are formatted differently; see the description of .TH in “Docu‐
870 ment structure macros”, above.
871 -rFT=footer-distance
873 Set distance of the footer, relative to the bottom of the page
874 if negative or relative to the top if positive, to footer-dis‐
875 tance. The default is -0.5i.
876 -rHY=flags
878 Set hyphenation flags. Permissible values of flags are docu‐
879 mented in section “Hyphenation” of groff(7). The default is 4
880 if continuous rendering is enabled (-rcR=1 above), and 6 other‐
881 wise.
882 -rIN=indent
884 Set the body text indentation (for normal paragraphs) to indent.
885 See “Horizontal and vertical spacing” above for the default in‐
886 dentation value. For nroff, indent should always be an integer
887 multiple of unit ‘n’ to get consistent indentation.
888 -rLL=line-length
890 Set line length. If this option is not given, the line length
891 is set to respect any value set by a prior “.ll” request (which
892 must be in effect when the .TH macro is invoked), if this dif‐
893 fers from the built-in default for the formatter; otherwise it
894 defaults to 78n in nroff mode and 6.5i in troff mode.
895 Note that the use of a “.ll” request to initialize the line
897 length is supported for backward compatibility with some ver‐
898 sions of the man program; direct initialization of the LL regis‐
899 ter should always be preferred to the use of such a request. In
900 particular, note that a “.ll 65n” request does not preserve the
901 normal nroff default line length (the man default initialization
902 to 78n prevails), whereas the -rLL=65n option, or an equivalent
903 “.nr LL 65n” request preceding the use of the .TH macro, does
904 set a line length of 65n.
905 -rLT=title-length
907 Set title length. If this option is not given, the title length
908 defaults to the line length.
909 -rPn Start enumeration of pages at n rather than 1.
911 -rSpoint-size
913 Use point-size as the base document font size. Acceptable val‐
914 ues are 10, 11, or 12. See subsection “Font style macros” above
915 for the default.
916 -rSN=subsection-indent
918 Set subsection indentation to subsection-indent. See “Horizon‐
919 tal and vertical spacing” above for the default indentation
920 value.
921 -rXp After page p, number pages as pa, pb, pc, and so forth. For ex‐
923 ample, the option -rX2 produces the following page numbers: 1,
924 2, 2a, 2b, 2c, and so on.
925
927 /usr/share/groff/1.22.4/tmac/man.tmac
928 /usr/share/groff/1.22.4/tmac/an.tmac
929 These are wrapper files to call andoc.tmac.
930 /usr/share/groff/1.22.4/tmac/andoc.tmac
932 This brief groff program detects whether the man or mdoc macro
933 package is being used by a document and loads the correct macro
934 definitions, taking advantage of the fact that pages using them
935 must call .TH or .Dd, respectively, as their first macro. Be‐
936 cause the wrappers above load this file, a man program or user
937 typing, for example, “groff -man page.1”, need not know which
938 package the file page.1 uses. Multiple man pages, in either
939 format, can be handled.
940 /usr/share/groff/1.22.4/tmac/an-old.tmac
942 Most man macros are contained in this file. It also loads the
943 GNU extensions from an-ext.tmac (see below).
944 /usr/share/groff/1.22.4/tmac/an-ext.tmac
946 The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
947 .UR/.UE, and .MT/.ME are contained in this file, which is writ‐
948 ten in classic troff and permissively licensed—not copylefted.
949 Man page authors concerned about portability to legacy Unix sys‐
950 tems are encouraged to copy these definitions into their pages,
951 and maintainers of troff implementations or work-alike systems
952 that format man pages are encouraged to re-use them.
953 Note that the definitions for these macros are read after the
955 call of .TH, so they will replace any macros of the same names
956 preceding it in your file. If you use your own implementations
957 of these macros, they must be defined after calling .TH to have
958 any effect.
959 /etc/groff/site-tmac/man.local
961 Local changes and customizations should be put into this file.
962
964 Some tips on troubleshooting your man pages follow.
965 • .RS doesn't indent relative to my indented paragraph
967 The .RS macro sets the indentation relative to the amount of a
968 normal paragraph (.PP and its synonyms). The same default in‐
969 dentation amount is used for .RS, .IP, .TP, and the deprecated
970 .HP. If you need to start an indent relative to an indented
971 paragraph, call .RS repeatedly until an acceptable indentation
972 is achieved, or give .RS an indentation argument that is at
973 least as much as the paragraph's indentation amount relative to
974 an adjacent .PP paragraph. See “Horizontal and vertical spac‐
975 ing” above for the values.
976 • .RE doesn't reset the indent to the expected level
978 • warning: scale indicator invalid in this context
979 • warning: number register 'an-saved-marginn' not defined
980 • warning: number register 'an-saved-prevailing-indentn' not defined
981 The .RS macro takes an indentation amount as an argument; the
982 .RE macro's argument is a specific indentation level. .RE 1
983 goes to the level before any .RS macros were called, .RE 2 goes
984 to the level of the first .RS call you made, and so forth. If
985 you desire symmetry in your macro calls, simply issue one .RE
986 without an argument for each .RS that precedes it.
987 After calls to the .SH and .SS sectioning macros, all relative
989 indents are cleared and calls to .RE have no effect.
990
992 The GNU version of the man macro package was written by James Clark and
993 contributors. The extension macros were written by Werner Lemberg ⟨wl@
994 gnu.org⟩ and Eric S. Raymond ⟨esr@thyrsus.com⟩.
995 This document was originally written for the Debian GNU/Linux system by
997 Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by
998 Werner Lemberg and G. Branden Robinson. The extension macros were doc‐
999 umented by Eric S. Raymond; he also originated the portability section,
1000 to which Ingo Schwarze contributed most of the material on escape se‐
1001 quences.
1002
1004 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
1005 Lemberg, is the main groff documentation. You can browse it interac‐
1006 tively with “info groff”.
1007 tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
1009 man(1) describes the man page formatter on your system.
1011 groff_mdoc(7) describes the groff version of the BSD-originated alter‐
1013 native macro package for man pages.
1014 groff(7), groff_char(7), man(7)
1016groff 1.22.4 19 January 2023 GROFF_MAN(7)