1groff_man_style(7) Miscellaneous Information Manual groff_man_style(7)
2
6 groff_man_style - GNU roff man page tutorial and style guide
7
9 groff -man [option ...] [file ...]
10 groff -m man [option ...] [file ...]
11
13 The GNU implementation of the man macro package is part of the groff
14 document formatting system. It is used to produce manual pages
15 (“man pages”) like the one you are reading.
16 This document presents the macros thematically; for those needing only
18 a quick reference, the following table lists them alphabetically, with
19 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 Paragraphing macros
31 .IR Italic, roman alternating Font style macros
32 .LP Begin paragraph Paragraphing macros
33 .ME Mail-to end Hyperlink macros
34 .MR Man page cross reference Hyperlink macros
35 .MT Mail-to start Hyperlink macros
36 .P Begin paragraph Paragraphing macros
37 .PP Begin paragraph Paragraphing macros
38 .RB Roman, bold alternating Font style macros
39 .RE Relative inset end Document structure macros
40 .RI Roman, italic alternating Font style macros
41 .RS Relative inset 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 Subsection heading Document structure macros
46 .SY Synopsis start Command synopsis macros
47 .TH Title heading Document structure macros
48 .TP Tagged paragraph Paragraphing macros
49 .TQ Supplemental paragraph tag Paragraphing macros
50 .UE URI end Hyperlink macros
51 .UR URI start Hyperlink macros
52 .YS Synopsis end Command synopsis macros
53 We discuss other macros (.AT, .DT, .HP, .OP, .PD, and .UC) in subsec‐
55 tion “Deprecated features” below.
56 Throughout Unix documentation, a manual entry is referred to simply as
58 a “man page”, regardless of its length, without gendered implication,
59 and irrespective of the macro package selected for its composition.
60 Man pages should be encoded using Unicode basic Latin code points ex‐
62 clusively, and employ the Unix line-ending convention (U+000A only).
63 Fundamental concepts
65 groff is a programming system for typesetting: we thus often use the
66 verb “to set” in the sense “to typeset”. The formatter troff(1) col‐
67 lects words from the input and fills output lines with as many as will
68 fit. Words are separated by spaces and newlines. A transition to a
69 new output line is called a break. When formatted, a word may be bro‐
70 ken at hyphens, at \% or \: escape sequences (see subsection “Portabil‐
71 ity” below), or at predetermined locations if automatic hyphenation is
72 enabled (see the -rHY option in section “Options” below). An output
73 line may be supplemented with inter-sentence space, and then optionally
74 adjusted with more space to a consistent line length (see the -dAD op‐
75 tion). roff(7) details these processes.
76 An input line that starts with a dot (.) or neutral apostrophe (') is a
78 control line. To call a macro, put its name after a dot on a control
79 line. We refer to macros in this document using this leading dot.
80 Some macros interpret arguments, words that follow the macro name. A
81 newline, unless escaped (see subsection “Portability” below), marks the
82 end of the macro call. An input line consisting of a dot followed by a
83 newline is called the empty request; it does nothing. Text lines are
84 input lines that are not control lines.
85 We describe below several man macros that plant one-line input traps:
87 the next input line that directly produces formatted output is treated
88 specially. For man documents that follow the advice in section “Porta‐
89 bility” below, this means that control lines using the empty request
90 and uncommented input lines ending with an escaped newline do not
91 spring the trap; anything else does (but see the .TP macro descrip‐
92 tion).
93 Macro reference preliminaries
95 A tagged paragraph describes each macro. We present coupled pairs to‐
96 gether, as with .EX and .EE.
97 Optional macro arguments are indicated by surrounding them with square
99 brackets. If a macro accepts multiple arguments, those containing
100 space characters must be double-quoted to be interpreted correctly. An
101 empty macro argument can be specified with a pair of double-quotes
102 (""), but the man package is designed such that this should seldom be
103 necessary. See section “Notes” below for examples of cases where bet‐
104 ter alternatives to empty arguments in macro calls are available. Most
105 macro arguments will be formatted as text in the output; exceptions are
106 noted.
107 Document structure macros
109 Document structure macros organize a man page's content. All of them
110 break the output line. .TH (title heading) identifies the document as
111 a man page and configures the page headers and footers. Section head‐
112 ings (.SH), one of which is mandatory and many of which are convention‐
113 ally expected, facilitate location of material by the reader and aid
114 the man page writer to discuss all essential aspects of the topic.
115 Subsection headings (.SS) are optional and permit sections that grow
116 long to develop in a controlled way. Many technical discussions bene‐
117 fit from examples; lengthy ones, especially those reflecting multiple
118 lines of input to or output from the system, are usefully bracketed by
119 .EX and .EE. When none of the foregoing meets a structural demand, use
120 .RS/.RE to inset a region within a (sub)section.
121 .TH topic section [footer-middle] [footer-inside] [header-middle]
123 Determine the contents of the page header and footer. roff sys‐
124 tems refer to these collectively as “titles”. The subject of
125 the man page is topic and the section of the manual to which it
126 belongs is section. This use of “section” has nothing to do
127 with the section headings otherwise discussed in this page; it
128 arises from the organizational scheme of printed and bound Unix
129 manuals. See man(1) or intro(1) for the manual sectioning ap‐
130 plicable to your system. topic and section are positioned to‐
131 gether at the left and right in the header (with section in
132 parentheses immediately appended to topic). footer-middle is
133 centered in the footer. The arrangement of the rest of the
134 footer depends on whether double-sided layout is enabled with
135 the option -rD1. When disabled (the default), footer-inside is
136 positioned at the bottom left. Otherwise, footer-inside appears
137 at the bottom left on recto (odd-numbered) pages, and at the
138 bottom right on verso (even-numbered) pages. The outside footer
139 is the page number, except in the continuous-rendering mode en‐
140 abled by the option -rcR=1, in which case it is the topic and
141 section, as in the header. header-middle is centered in the
142 header. If section is an integer between 1 and 9 (inclusive),
143 there is no need to specify header-middle; an.tmac will supply
144 text for it. The macro package may also abbreviate topic and
145 footer-inside with ellipses (...) if they would overrun the
146 space available in the header and footer, respectively. For
147 HTML output, headers and footers are suppressed.
148 Additionally, this macro breaks the page, resetting the number
150 to 1 (unless the -rC1 option is given). This feature is in‐
151 tended only for formatting multiple man documents in sequence.
152 A valid man document calls .TH once, early in the file, prior to
154 any other macro calls.
155 By convention, footer-middle is the date of the most recent mod‐
157 ification to the man page source document, and footer-inside is
158 the name and version or release of the project providing it.
159 .SH [heading-text]
161 Set heading-text as a section heading. If no argument is given,
162 a one-line input trap is planted; text on the next line becomes
163 heading-text. The left margin is reset to zero to set the head‐
164 ing text in bold (or the font specified by the string HF), and,
165 on typesetting devices, slightly larger than the base type size.
166 If the heading font \*[HF] is bold, use of an italic style in
167 heading-text is mapped to the bold-italic style if available in
168 the font family. The inset level is reset to 1, setting the
169 left margin to the value of the IN register. Text after head‐
170 ing-text is set as an ordinary paragraph (.P).
171 The content of heading-text and ordering of sections follows a
173 set of common practices, as has much of the layout of material
174 within sections. For example, a section called “Name” or “NAME”
175 must exist, must be the first section after the .TH call, and
176 must contain only text of the form
177 topic[, another-topic]... \- summary-description
178 for a man page to be properly indexed. See man(7) for the con‐
179 ventions prevailing on your system.
180 .SS [subheading-text]
182 Set subheading-text as a subsection heading indented between a
183 section heading and an ordinary paragraph (.P). If no argument
184 is given, a one-line input trap is planted; text on the next
185 line becomes subheading-text. The left margin is reset to the
186 value of the SN register to set the heading text in bold (or the
187 font specified by the string HF). If the heading font \*[HF] is
188 bold, use of an italic style in subheading-text is mapped to the
189 bold-italic style if available in the font family. The inset
190 level is reset to 1, setting the left margin to the value of the
191 IN register. Text after subheading-text is set as an ordinary
192 paragraph (.P).
193 .EX
195 .EE Begin and end example. After .EX, filling is disabled and a
196 constant-width (monospaced) font is selected. Calling .EE en‐
197 ables filling and restores the previous font.
198 Example regions are useful for formatting code, shell sessions,
200 and text file contents. An example region is not a “literal
201 mode” of any sort: special character escape sequences must still
202 be used to produce correct glyphs for ', -, \, ^, `, and ~, and
203 sentence endings are still detected and additional inter-sen‐
204 tence space applied. If the amount of additional inter-sentence
205 spacing is altered, the rendering of, for instance, regular ex‐
206 pressions using . or ? followed by multiple spaces can change.
207 Use the dummy character escape sequence \& before the spaces.
208 These macros are extensions introduced in Ninth Edition Research
210 Unix. Systems running that troff, or those from Documenter's
211 Workbench, Heirloom Doctools, or Plan 9 troff support them. To
212 be certain your page will be portable to systems that do not,
213 copy their definitions from the an-ext.tmac file of a groff in‐
214 stallation.
215 .RS [inset-amount]
217 Start a new relative inset level. The position of the left mar‐
218 gin is saved, then moved right by inset-amount, if specified,
219 and by the amount of the IN register otherwise. Calls to .RS
220 can be nested; each increments by 1 the inset level used by .RE.
221 The level prior to any .RS calls is 1.
222 .RE [level]
224 End a relative inset. The left margin corresponding to inset
225 level level is restored. If no argument is given, the inset
226 level is reduced by 1.
227 Paragraphing macros
229 An ordinary paragraph (.P) like this one is set without a first-line
230 indentation at the current left margin. In man pages and other techni‐
231 cal literature, definition lists are frequently encountered; these can
232 be set as “tagged paragraphs”, which have one (.TP) or more (.TQ) lead‐
233 ing tags followed by a paragraph that has an additional indentation.
234 The indented paragraph (.IP) macro is useful to continue the indented
235 content of a narrative started with .TP, or to present an itemized or
236 ordered list. All of these macros break the output line. If another
237 paragraph macro has occurred since the previous .SH or .SS, they (ex‐
238 cept for .TQ) follow the break with a default amount of vertical space,
239 which can be changed by the deprecated .PD macro; see subsection “Hori‐
240 zontal and vertical spacing” below. They also reset the type size and
241 font style to defaults (.TQ again excepted); see subsection “Font style
242 macros” below.
243 .P
245 .LP
246 .PP Begin a new paragraph; these macros are synonymous. The inden‐
247 tation is reset to the default value; the left margin, as af‐
248 fected by .RS and .RE, is not.
249 .TP [indentation]
251 Set a paragraph with a leading tag, and the remainder of the
252 paragraph indented. A one-line input trap is planted; text on
253 the next line, which can be formatted with a macro, becomes the
254 tag, which is placed at the current left margin. The tag can be
255 extended with the \c escape sequence. Subsequent text is in‐
256 dented by indentation, if specified, and by the amount of the IN
257 register otherwise. If the tag is not as wide as the indenta‐
258 tion, the paragraph starts on the same line as the tag, at the
259 applicable indentation, and continues on the following lines.
260 Otherwise, the descriptive part of the paragraph begins on the
261 line following the tag.
262 The line containing the tag can include a macro call, for in‐
264 stance to set the tag in bold with .B. .TP was used to write
265 the first paragraph of this description of .TP, and .IP the sub‐
266 sequent one.
267 .TQ Set an additional tag for a paragraph tagged with .TP. An input
269 trap is planted as with .TP.
270 This macro is a GNU extension not defined on systems running
272 AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section
273 “Files” below.
274 The descriptions of .P, .LP, and .PP above were written using
276 .TP and .TQ.
277 .IP [tag] [indentation]
279 Set an indented paragraph with an optional tag. The tag and in‐
280 dentation arguments, if present, are handled as with .TP, with
281 the exception that the tag argument to .IP cannot include a
282 macro call.
283 Two convenient uses for .IP are
285 (1) to start a new paragraph with the same indentation as an
287 immediately preceding .IP or .TP paragraph, if no inden‐
288 tation argument is given; and
289 (2) to set a paragraph with a short tag that is not semanti‐
291 cally important, such as a bullet (•)—obtained with the
292 \(bu special character escape sequence—or list enumera‐
293 tor, as seen in this very paragraph.
294 Command synopsis macros
296 .SY and .YS aid you to construct a command synopsis that has the clas‐
297 sical Unix appearance. They break the output line.
298 These macros are GNU extensions not defined on systems running AT&T,
300 Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.
301 .SY command
303 Begin synopsis. A new paragraph begins at the left margin (as
304 with .P) unless .SY has already been called without a corre‐
305 sponding .YS, in which case only a break is performed. Adjust‐
306 ment and automatic hyphenation are disabled. command is set in
307 bold. If a break is required, lines after the first are in‐
308 dented by the width of command plus a space.
309 .YS End synopsis. Indentation, adjustment, and hyphenation are re‐
311 stored to their previous states.
312 Multiple .SY/.YS blocks can be specified, for instance to distinguish
314 differing modes of operation of a complex command like tar(1); each
315 will be vertically separated as paragraphs are.
316 .SY can be repeated before .YS to indicate synonymous ways of invoking
318 a particular mode of operation.
319 groff's own command-line interface serves to illustrate most of the
321 specimens of synopsis syntax one is likely to encounter.
322 .SY groff
324 .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
325 .RB [ \-d\~\c
326 .IR cs ]
327 .RB [ \-d\~\c
328 .IB name =\c
329 .IR string ]
330 .RB [ \-D\~\c
331 .IR enc ]
332 (and so on similarly)
333 .RI [ file\~ .\|.\|.]
334 .YS
335 .
336 .
337 .SY groff
338 .B \-h
339 .
340 .SY groff
341 .B \-\-help
342 .YS
343 .
344 .
345 .SY groff
346 .B \-v
347 .RI [ option\~ .\|.\|.\&]
348 .RI [ file\~ .\|.\|.]
349 .
350 .SY groff
351 .B \-\-version
352 .RI [ option\~ .\|.\|.\&]
353 .RI [ file\~ .\|.\|.]
354 .YS
355 produces the following output.
357 groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-d name=string]
359 [-D enc] [-f fam] [-F dir] [-I dir] [-K enc] [-L arg]
360 [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
361 [-r reg=expr] [-T dev] [-w name] [-W name] [file ...]
362 groff -h
364 groff --help
365 groff -v [option ...] [file ...]
367 groff --version [option ...] [file ...]
368 Several features of the above example are of note.
370 • The empty request (.), which does nothing, is used to vertically
372 space the input file for readability by the document maintainer. Do
373 not put blank (empty) lines in a man page source document.
374 • Command and option names are presented in bold to cue the user that
376 they should be input literally.
377 • Option dashes are specified with the \- escape sequence; this is an
379 important practice to make them clearly visible and to facilitate
380 copy-and-paste from the rendered man page to a shell prompt or text
381 file.
382 • Option arguments and command operands are presented in italics (but
384 see subsection “Font style macros” below regarding terminals) to cue
385 the user that they must be replaced with appropriate text.
386 • Symbols that are neither to be typed literally nor replaced at the
388 user's discretion appear in the roman style; brackets surround op‐
389 tional arguments, and an ellipsis indicates that the previous syntac‐
390 tical element may be repeated arbitrarily.
391 • The non-breaking adjustable space escape sequence \~ is used to pre‐
393 vent the output line from being broken within the option brackets;
394 see subsection “Portability” below.
395 • The output line continuation escape sequence \c is used with font
397 style alternation macros to allow all three font styles to be set
398 without (breakable) space among them; see subsection “Portability”
399 below.
400 • The dummy character escape sequence \& follows the ellipsis when fur‐
402 ther text will follow after space on the output line, keeping its
403 last period from being interpreted as the end of a sentence and caus‐
404 ing additional inter-sentence space to be placed after it. See sub‐
405 section “Portability” below.
406 Hyperlink macros
408 Man page cross references like ls(1) are best presented with .MR. Text
409 may be hyperlinked to email addresses with .MT/.ME or other URIs with
410 .UR/.UE. Hyperlinked text is supported on HTML and terminal output de‐
411 vices; terminals and pager programs must support ECMA-48 OSC 8 escape
412 sequences (see grotty(1)). When device support is unavailable or dis‐
413 abled with the U register (see section “Options” below), .MT and .UR
414 URIs are rendered between angle brackets after the linked text.
415 .MT, .ME, .UR, and .UE are GNU extensions not defined on systems run‐
417 ning AT&T, Plan 9, or Solaris troff; see an-ext.tmac in section “Files”
418 below. Plan 9 from User Space's troff implements .MR.
419 The arguments to .MR, .MT, and .UR should be prepared for typesetting
421 since they can appear in the output. Use special character escape se‐
422 quences to encode Unicode basic Latin characters where necessary, par‐
423 ticularly the hyphen-minus. (See section “Portability” below.) URIs
424 can be lengthy; rendering them can result in jarring adjustment or
425 variations in line length, or troff warnings when a hyperlink is longer
426 than an output line. The application of non-printing break point es‐
427 cape sequences \: after each slash (or series thereof), and before each
428 dot (or series thereof) is recommended as a rule of thumb. The former
429 practice avoids forcing a trailing slash in a URI onto a separate out‐
430 put line, and the latter helps the reader to avoid mistakenly inter‐
431 preting a dot at the end of a line as a period (or multiple dots as an
432 ellipsis). Thus,
433 .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
434 has several potential break points in the URI shown. Consider adding
435 break points before or after at signs in email addresses, and question
436 marks, ampersands, and number signs in HTTP(S) URIs. The formatter re‐
437 moves \: escape sequences from hyperlinks when supplying device control
438 commands to output drivers.
439 .MR topic manual-section [trailing-text]
441 (since groff 1.23) Set a man page cross reference as “topic(man‐
442 ual-section)”. If trailing-text (typically punctuation) is
443 specified, it follows the closing parenthesis without interven‐
444 ing space. Hyphenation is disabled while the cross reference is
445 set. topic is set in the font specified by the MF string. The
446 cross reference hyperlinks to a URI of the form “man:topic(man‐
447 ual-section)”.
448 The output driver
450 .MR grops 1
451 produces PostScript from
452 .I troff
453 output.
454 .
455 The Ghostscript program (\c
456 .MR gs 1 )
457 interprets PostScript and PDF.
458 .MT address
460 .ME [trailing-text]
461 Identify address as an RFC 6068 addr-spec for a “mailto:” URI
462 with the text between the two macro calls as the link text. An
463 argument to .ME is placed after the link text without interven‐
464 ing space. address may not be visible in the rendered document
465 if hyperlinks are enabled and supported by the output driver.
466 If they are not, address is set in angle brackets after the link
467 text and before trailing-text. If hyperlinking is enabled but
468 there is no link text, address is formatted and hyperlinked
469 without angle brackets.
470 When rendered by groff to a PostScript device,
472 Contact
474 .MT fred\:.foonly@\:fubar\:.net
475 Fred Foonly
476 .ME
477 for more information.
478 displays as “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for
480 more information.”.
481 .UR uri
483 .UE [trailing-text]
484 Identify uri as an RFC 3986 URI hyperlink with the text between
485 the two macro calls as the link text. An argument to .UE is
486 placed after the link text without intervening space. uri may
487 not be visible in the rendered document if hyperlinks are en‐
488 abled and supported by the output driver. If they are not, uri
489 is set in angle brackets after the link text and before trail‐
490 ing-text. If hyperlinking is enabled but there is no link text,
491 uri is formatted and hyperlinked without angle brackets.
492 When rendered by groff to a PostScript device,
494 The GNU Project of the Free Software Foundation
496 hosts the
497 .UR https://\:www\:.gnu\:.org/\:software/\:groff/
498 .I groff
499 home page
500 .UE .
501 displays as “The GNU Project of the Free Software Foundation
503 hosts the groff home page ⟨https://www.gnu.org/software/
504 groff/⟩.”.
505 The hyperlinking of .TP paragraph tags with .UR/.UE and .MT/.ME is not
507 yet supported; if attempted, the hyperlink will be typeset at the be‐
508 ginning of the indented paragraph even on hyperlink-supporting devices.
509 Font style macros
511 The man macro package is limited in its font styling options, offering
512 only bold (.B), italic (.I), and roman. Italic text is usually set un‐
513 derscored instead on terminal devices. The .SM and .SB macros set text
514 in roman or bold, respectively, at a smaller type size; these differ
515 visually from regular-sized roman or bold text only on typesetting de‐
516 vices. It is often necessary to set text in different styles without
517 intervening space. The macros .BI, .BR, .IB, .IR, .RB, and .RI, where
518 “B”, “I”, and “R” indicate bold, italic, and roman, respectively, set
519 their odd- and even-numbered arguments in alternating styles, with no
520 space separating them.
521 Because font styles are presentational rather than semantic, conflict‐
523 ing traditions have arisen regarding which font styles should be used
524 to mark file or path names, environment variables, and inlined liter‐
525 als.
526 The default type size and family for typesetting devices is 10-point
528 Times, except on the X75-12 and X100-12 devices where the type size is
529 12 points. The default style is roman.
530 .B [text]
532 Set text in bold. If no argument is given, a one-line input
533 trap is planted; text on the next line, which can be further
534 formatted with a macro, is set in bold.
535 Use bold for literal portions of syntax synopses, for command-
537 line options in running text, and for literals that are major
538 topics of the subject under discussion; for example, this page
539 uses bold for macro, string, and register names. In an .EX/.EE
540 example of interactive I/O (such as a shell session), set only
541 user input in bold.
542 .I [text]
544 Set text in an italic or oblique face. If no argument is given,
545 a one-line input trap is planted; text on the next line, which
546 can be further formatted with a macro, is set in an italic or
547 oblique face.
548 Use italics for file and path names, for environment variables,
550 for C data types, for enumeration or preprocessor constants in
551 C, for variant (user-replaceable) portions of syntax synopses,
552 for the first occurrence (only) of a technical concept being in‐
553 troduced, for names of journals and of literary works longer
554 than an article, and anywhere a parameter requiring replacement
555 by the user is encountered. An exception involves variant text
556 in a context already typeset in italics, such as file or path
557 names with replaceable components; in such cases, follow the
558 convention of mathematical typography: set the file or path name
559 in italics as usual but use roman for the variant part (see .IR
560 and .RI below), and italics again in running roman text when re‐
561 ferring to the variant material.
562 .SM [text]
564 Set text one point smaller than the default type size on type‐
565 setting devices. If no argument is given, a one-line input trap
566 is planted; text on the next line, which can be further format‐
567 ted with a macro, is set smaller.
568 Note: terminals will render text at normal size instead. Do not
570 rely upon .SM to communicate semantic information distinct from
571 using roman style at normal size; it will be hidden from readers
572 using such devices.
573 .SB [text]
575 Set text in bold and (on typesetting devices) one point smaller
576 than the default type size. If no argument is given, a one-line
577 input trap is planted; text on the next line, which can be fur‐
578 ther formatted with a macro, is set smaller and in bold. This
579 macro is an extension introduced in SunOS 4.0.
580 Note: terminals will render text in bold at the normal size in‐
582 stead. Do not rely upon .SB to communicate semantic information
583 distinct from using bold style at normal size; it will be hidden
584 from readers using such devices.
585 Observe what is not prescribed for setting in bold or italics above:
587 elements of “synopsis language” such as ellipses and brackets around
588 options; proper names and adjectives; titles of anything other than ma‐
589 jor works of literature; identifiers for standards documents or techni‐
590 cal reports such as CSTR #54, RFC 1918, Unicode 13.0, or POSIX.1-2017;
591 acronyms; and occurrences after the first of a technical term.
592 Be frugal with italics for emphasis, and particularly with bold. Arti‐
594 cle titles and brief runs of literal text, such as references to indi‐
595 vidual characters or short strings, including section and subsection
596 headings of man pages, are suitable objects for quotation; see the
597 \(lq, \(rq, \(oq, and \(cq escape sequences in subsection “Portability”
598 below.
599 Unlike the above font style macros, the font style alternation macros
601 below set no input traps; they must be given arguments to have effect.
602 Italic corrections are applied as appropriate. If a space is required
603 within an argument, first consider whether the same result could be
604 achieved with as much clarity by using single-style macros on separate
605 input lines. When it cannot, double-quote an argument containing em‐
606 bedded space characters. Setting all three different styles within a
607 word presents challenges; it is possible with the \c and/or \f escape
608 sequences. See subsection “Portability” below for approaches.
609 .BI bold-text italic-text ...
611 Set each argument in bold and italics, alternately.
612 .BI -r register = numeric-expression
614 .BR bold-text roman-text ...
616 Set each argument in bold and roman, alternately.
617 After
619 .B .NH
620 is called,
621 .IB italic-text bold-text ...
623 Set each argument in italics and bold, alternately.
624 In places where
626 .IB n th
627 is allowed,
628 .IR italic-text roman-text ...
630 Set each argument in italics and roman, alternately.
631 Use GNU
633 .IR pic 's
634 .B figname
635 command to change the name of the vbox.
636 .RB roman-text bold-text ...
638 Set each argument in roman and bold, alternately.
639 if
641 .I file
642 is
643 .RB \[lq] \- \[rq],
644 the standard input stream is read.
645 .RI roman-text italic-text ...
647 Set each argument in roman and italics, alternately.
648 .RI ( tpic
650 was a fork of AT&T
651 .I pic
652 by Tim Morgan of the University of California at Irvine
653 Horizontal and vertical spacing
655 The indentation argument accepted by .IP, .TP, and the deprecated .HP
656 is a number plus an optional scaling unit, as is .RS's inset-amount.
657 If no scaling unit is given, the man package assumes “n”; that is, the
658 width of a letter “n” in the font current when the macro is called (see
659 section “Measurements” in groff(7)). An indentation specified in a
660 call to .IP, .TP, or the deprecated .HP persists until (1) another of
661 these macros is called with an indentation argument, or (2) .SH, .SS,
662 or .P or its synonyms is called; these clear the indentation entirely.
663 The left margin used by ordinary paragraphs set with .P (and its syn‐
665 onyms) not within an .RS/.RE relative inset is 7.2n for typesetting de‐
666 vices and 7n for terminal devices (but see the -rIN option). Headers,
667 footers (both set with .TH), and section headings (.SH) are set at the
668 page offset (see groff(7)) and subsection headings (.SS) indented from
669 it by 3n (but see the -rSN option).
670 It may be helpful to think of the left margin and indentation as re‐
672 lated but distinct concepts; groff's implementation of the man macro
673 package tracks them separately. The left margin is manipulated by .RS
674 and .RE (and by .SH and .SS, which reset it to the default). Indenta‐
675 tion is controlled by the paragraphing macros (though, again, .SH and
676 .SS reset it); it is imposed by the .TP, .IP, and deprecated .HP
677 macros, and cancelled by .P and its synonyms. An extensive example
678 follows.
679 This ordinary (.P) paragraph is not in a relative inset nor does it
681 possess an indentation.
682 Now we have created a relative inset (in other words, moved the
684 left margin) with .RS and started another ordinary paragraph
685 with .P.
686 tag This tagged paragraph, set with .TP, is still within the
688 .RS region, but lines after the first have a supplemen‐
689 tary indentation that the tag lacks.
690 A paragraph like this one, set with .IP, will appear to
692 the reader as also associated with the tag above, because
693 .IP re-uses the previous paragraph's indentation unless
694 given an argument to change it. This paragraph is af‐
695 fected both by the moved left margin (.RS) and indenta‐
696 tion (.IP).
697 ┌─────────────────────────────────┐
699 │This table is affected both by │
700 │the left margin and indentation. │
701 └─────────────────────────────────┘
702 • This indented paragraph has a bullet for a tag, making it
703 more obvious that the left margin and indentation are
704 distinct; only the former affects the tag, but both af‐
705 fect the text of the paragraph.
706 This ordinary (.P) paragraph resets the indentation, but the
708 left margin is still inset.
709 ┌────────────────────────────┐
711 │This table is affected only │
712 │by the left margin. │
713 └────────────────────────────┘
714 Finally, we have ended the relative inset by using .RE, which (because
715 we used only one .RS/.RE pair) has reset the left margin to the de‐
716 fault. This is an ordinary .P paragraph.
717 Resist the temptation to mock up tabular or multi-column output with
719 tab characters or the indentation arguments to .IP, .TP, .RS, or the
720 deprecated .HP; the result may not render comprehensibly on an output
721 device you fail to check, or which is developed in the future. The ta‐
722 ble preprocessor tbl(1) can likely meet your needs.
723 Several macros insert vertical space: .SH, .SS, .TP, .P (and its syn‐
725 onyms), .IP, and the deprecated .HP. The default inter-section and in‐
726 ter-paragraph spacing is is 1v for terminal devices and 0.4v for type‐
727 setting devices (“v” is a unit of vertical distance, where 1v is the
728 distance between adjacent text baselines in a single-spaced document).
729 (The deprecated macro .PD can change this vertical spacing, but its use
730 is discouraged.) Between .EX and .EE calls, the inter-paragraph spac‐
731 ing is 1v regardless of output device.
732 Registers
734 Registers are described in section “Options” below. They can be set
735 not only on the command line but in the site man.local file as well;
736 see section “Files” below.
737 Strings
739 The following strings are defined for use in man pages. Others are
740 supported for configuration of rendering parameters; see section “Op‐
741 tions” below.
742 \*R interpolates a special character escape sequence for the “regis‐
744 tered sign” glyph, \(rg, if available, and “(Reg.)” otherwise.
745 \*S interpolates an escape sequence setting the type size to the
747 document default.
748 \*(lq
750 \*(rq interpolate special character escape sequences for left and
751 right double-quotation marks, \(lq and \(rq, respectively.
752 \*(Tm interpolates a special character escape sequence for the “trade
754 mark sign” glyph, \(tm, if available, and “(TM)” otherwise.
755 None of the above is necessary in a contemporary man page. \*S is su‐
757 perfluous, since type size changes are invisible on terminal devices
758 and macros that change it restore its original value afterward. Better
759 alternatives exist for the rest; simply use the \(rg, \(lq, \(rq, and
760 \(tm special character escape sequences directly. Unless a man page
761 author is aiming for a pathological level of portability, such as the
762 composition of pages for consumption on simulators of 1980s Unix sys‐
763 tems (or Solaris troff, though even it supports \(rg), the above
764 strings should be avoided.
765 Portability
767 It is wise to quote multi-word section and subsection headings; the .SH
768 and .SS macros of man(7) implementations descended from Seventh Edition
769 Unix supported six arguments at most. A similar restriction applied to
770 the .B, .I, .SM, and font style alternation macros.
771 The two major syntactical categories for formatting control in the roff
773 language are requests and escape sequences. Since the man macros are
774 implemented in terms of groff requests and escape sequences, one can,
775 in principle, supplement the functionality of man with these lower-
776 level elements where necessary.
777 However, using raw groff requests (apart from the empty request “.”) is
779 likely to make your page render poorly when processed by other tools;
780 many of these attempt to interpret page sources directly for conversion
781 to HTML. Some requests make implicit assumptions about things like
782 character and page sizes that may not hold in an HTML environment;
783 also, many of these viewers don't interpret the full groff vocabulary,
784 a problem that can lead to portions of your text being omitted or pre‐
785 sented incomprehensibly.
786 For portability to modern viewers, it is best to write your page solely
788 with the macros described in this page (except for the ones identified
789 as deprecated, which should be avoided). The macros we have described
790 as extensions (.EX/.EE, .SY/.YS, .TQ, .UR/.UE, .MT/.ME, .MR, and .SB)
791 should be used with caution, as they may not be built in to some viewer
792 that is important to your audience. See an-ext.tmac in section “Files”
793 below.
794 Similar caveats apply to escape sequences. Some escape sequences are
796 however required for correct typesetting even in man pages and usually
797 do not cause portability problems. Several of these render glyphs cor‐
798 responding to punctuation code points in the Unicode basic Latin range
799 (U+0000–U+007F) that are handled specially in roff input; the escape
800 sequences below must be used to render them correctly and portably when
801 documenting material that uses them syntactically—namely, any of the
802 set ' - \ ^ ` ~ (apostrophe, dash or minus, backslash, caret, grave ac‐
803 cent, tilde).
804 \" Comment. Everything after the double-quote to the end of the
806 input line is ignored. Whole-line comments should be placed im‐
807 mediately after the empty request (“.”).
808 \newline
810 Join the next input line to the current one. Except for the up‐
811 date of the input line counter (used for diagnostic messages and
812 related purposes), a series of lines ending in backslash-newline
813 appears to groff as a single input line. Use this escape se‐
814 quence to split excessively long input lines for document main‐
815 tenance.
816 \% Control hyphenation. The location of this escape sequence
818 within a word marks a hyphenation point, supplementing groff's
819 automatic hyphenation patterns. At the beginning of a word, it
820 suppresses any hyphenation breaks within except those specified
821 with \%.
822 \: Insert a non-printing break point. A word can break at such a
824 point, but a hyphen glyph is not written to the output if it
825 does. This escape sequence is an input word boundary, so the
826 remainder of the word is subject to hyphenation as normal. You
827 can use \: and \% in combination to control breaking of a file
828 name or URI or to permit hyphenation only after certain explicit
829 hyphens within a word. See subsection “Hyperlink macros” above
830 for an example.
831 This escape sequence is a groff extension also supported by
833 Heirloom Doctools troff 050915 (September 2005), mandoc 1.14.5
834 (2019-03-10), and neatroff (commit 399a4936, 2014-02-17), but
835 not by Plan 9, Solaris, or Documenter's Workbench troffs.
836 \~ Adjustable non-breaking space. Use this escape sequence to pre‐
838 vent a break inside a short phrase or between a numerical quan‐
839 tity and its corresponding unit(s).
840 Before starting the motor,
842 set the output speed to\~1.
843 There are 1,024\~bytes in 1\~KiB.
844 CSTR\~#8 documents the B\~language.
845 This escape sequence is a groff extension also supported by
847 Heirloom Doctools troff 050915 (September 2005), mandoc 1.9.5
848 (2009-09-21), neatroff (commit 1c6ab0f6e, 2016-09-13), and
849 Plan 9 from User Space troff (commit 93f8143600, 2022-08-12),
850 but not by Solaris or Documenter's Workbench troffs.
851 \& Dummy character. Insert at the beginning of an input line to
853 prevent a dot or apostrophe from being interpreted as beginning
854 a roff control line. Append to an end-of-sentence punctuation
855 sequence to keep it from being recognized as such.
856 \| Thin space (one-sixth em on typesetters, zero-width on termi‐
858 nals); a non-breaking space. Used primarily in ellipses
859 (“.\|.\|.”) to space the dots more pleasantly on typesetting
860 devices like dvi, pdf, and ps.
861 \c End a text line without inserting space or attempting a break.
863 Normally, if filling is enabled, the end of a text line is
864 treated like a space; an output line may be broken there (if
865 not, an adjustable space is inserted); if filling is disabled,
866 the line will be broken there, as in .EX/.EE examples. The next
867 line is interpreted as usual and can include a macro call (con‐
868 trast with \newline). \c is useful when three font styles are
869 needed in a single word, as in a command synopsis.
870 .RB [ \-\-stylesheet=\c
872 .IR name ]
873 It also helps when changing font styles in .EX/.EE examples,
875 since they are not filled.
876 .EX
878 $ \c
879 .B groff \-T utf8 \-Z \c
880 .I file \c
881 .B | grotty \-i
882 .EE
883 Alternatively, and perhaps with better portability, the \f font
885 selection escape sequence can be used; see below. Using \c to
886 continue a .TP paragraph tag across multiple input lines will
887 render incorrectly with groff 1.22.3, mandoc 1.14.1, older ver‐
888 sions of these programs, and perhaps with some other formatters.
889 \e Format the current escape character on the output; widely used
891 in man pages to render a backslash glyph. It works reliably as
892 long as the “.ec” request is not used, which should never happen
893 in man pages, and it is slightly more portable than the more ex‐
894 plicit \(rs (“reverse solidus”) special character escape se‐
895 quence.
896 \fB, \fI, \fR, \fP
898 Switch to bold, italic, roman, or back to the previous style,
899 respectively. Either \f or \c is needed when three different
900 font styles are required in a word.
901 .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]
903 .RB [ \-\-reference\-dictionary=\c
905 .IR name ]
906 Style escape sequences may be more portable than \c. As shown
908 above, it is up to you to account for italic corrections with
909 “\/” and “\,”, which are themselves GNU extensions, if desired
910 and if supported by your implementation.
911 \fP reliably returns to the style in use immediately preceding
913 the previous \f escape sequence only if no sectioning, para‐
914 graph, or style macro calls have intervened.
915 As long as at most two styles are needed in a word, style macros
917 like .B and .BI usually result in more readable roff source than
918 \f escape sequences do.
919 Several special characters are also widely portable. Except for \-,
921 \(em, and \(ga, AT&T troff did not consistently define the characters
922 listed below, but its descendants, like Plan 9 or Solaris troff, can be
923 made to support them by defining them in font description files, making
924 them aliases of existing glyphs if necessary; see groff_font(5).
925 \- Minus sign or basic Latin hyphen-minus. This escape sequence
927 produces the Unix command-line option dash in the output. “-”
928 is a hyphen in the roff language; some output devices replace it
929 with U+2010 (hyphen) or similar.
930 \(aq Basic Latin neutral apostrophe. Some output devices format “'”
932 as a right single quotation mark.
933 \(oq
935 \(cq Opening (left) and closing (right) single quotation marks. Use
936 these for paired directional single quotes, ‘like this’.
937 \(dq Basic Latin quotation mark (double quote). Use in macro calls
939 to prevent ‘"” from being interpreted as beginning a quoted ar‐
940 gument, or simply for readability.
941 .TP
943 .BI "split \(dq" text \(dq
944 \(lq
946 \(rq Left and right double quotation marks. Use these for paired di‐
947 rectional double quotes, “like this”.
948 \(em Em-dash. Use for an interruption—such as this one—in a sen‐
950 tence.
951 \(en En-dash. Use to separate the ends of a range, particularly be‐
953 tween numbers; for example, “the digits 1–9”.
954 \(ga Basic Latin grave accent. Some output devices format “`” as a
956 left single quotation mark.
957 \(ha Basic Latin circumflex accent (“hat”). Some output devices for‐
959 mat “^” as U+02C6 (modifier letter circumflex accent) or simi‐
960 lar.
961 \(rs Reverse solidus (backslash). The backslash is the default es‐
963 cape character in the roff language, so it does not represent
964 itself in output. Also see \e above.
965 \(ti Basic Latin tilde. Some output devices format “~” as U+02DC
967 (small tilde) or similar.
968 For maximum portability, escape sequences and special characters not
970 listed above are better avoided in man pages.
971 Hooks
973 Two macros, both GNU extensions, are called internally by the groff man
974 package to format page headers and footers and can be redefined by the
975 administrator in a site's man.local file (see section “Files” below).
976 The presentation of .TH above describes the default headers and foot‐
977 ers. Because these macros are hooks for groff man internals, man pages
978 have no reason to call them. Such hook definitions will likely consist
979 of “.sp” and “.tl” requests. They must also increase the page length
980 with “.pl” requests in continuous rendering mode; .PT furthermore has
981 the responsibility of emitting a PDF bookmark after writing the first
982 page header in a document. Consult the existing implementations in
983 an.tmac when drafting replacements.
984 .BT Set the page footer text (“bottom trap”).
986 .PT Set the page header text (“page trap”).
988 To remove a page header or footer entirely, define the appropriate
990 macro as empty rather than deleting it.
991 Deprecated features
993 Use of the following in man pages for public distribution is discour‐
994 aged.
995 .AT [system [release]]
997 Alter the footer for use with legacy AT&T man pages, overriding
998 any definition of the footer-inside argument to .TH. This macro
999 exists only to render man pages from historical systems.
1000 system can be any of the following.
1002 3 7th edition (default)
1004 4 System III
1006 5 System V
1008 The optional release argument specifies the release number, as
1010 in “System V Release 3”.
1011 .DT Reset tab stops to the default (every 0.5i [inches]).
1013 Use of this presentation-oriented macro is deprecated. It
1015 translates poorly to HTML, under which exact space control and
1016 tabulation are not readily available. Thus, information or dis‐
1017 tinctions that you use tab stops to express are likely to be
1018 lost. If you feel tempted to change the tab stops such that
1019 calling this macro later is desirable to restore them, you
1020 should probably be composing a table using tbl(1) instead.
1021 .HP [indentation]
1023 Set up a paragraph with a hanging left indentation. The inden‐
1024 tation argument, if present, is handled as with .TP.
1025 Use of this presentation-oriented macro is deprecated. A hang‐
1027 ing indentation cannot be expressed naturally under HTML, and
1028 non-roff-based man page interpreters may treat .HP as an ordi‐
1029 nary paragraph. Thus, information or distinctions you mean to
1030 express with indentation may be lost.
1031 .OP option-name [option-argument]
1033 Indicate an optional command parameter called option-name, which
1034 is set in bold. If the option takes an argument, specify op‐
1035 tion-argument using a noun, abbreviation, or hyphenated noun
1036 phrase. If present, option-argument is preceded by a space and
1037 set in italics. Square brackets in roman surround both argu‐
1038 ments.
1039 Use of this quasi-semantic macro, an extension originating in
1041 Documenter's Workbench troff, is deprecated. It cannot easily
1042 be used to annotate options that take optional arguments or op‐
1043 tions whose arguments have internal structure (such as a mixture
1044 of literal and variable components). One could work around
1045 these limitations with font selection escape sequences, but it
1046 is preferable to use font style alternation macros, which afford
1047 greater flexibility.
1048 .PD [vertical-space]
1050 Define the vertical space between paragraphs or (sub)sections.
1051 The optional argument vertical-space specifies the amount; the
1052 default scaling unit is “v”. Without an argument, the spacing
1053 is reset to its default value; see subsection “Horizontal and
1054 vertical spacing” above.
1055 Use of this presentation-oriented macro is deprecated. It
1057 translates poorly to HTML, under which exact control of inter-
1058 paragraph spacing is not readily available. Thus, information
1059 or distinctions that you use .PD to express are likely to be
1060 lost.
1061 .UC [version]
1063 Alter the footer for use with legacy BSD man pages, overriding
1064 any definition of the footer-inside argument to .TH. This macro
1065 exists only to render man pages from historical systems.
1066 version can be any of the following.
1068 3 3rd Berkeley Distribution (default)
1070 4 4th Berkeley Distribution
1072 5 4.2 Berkeley Distribution
1074 6 4.3 Berkeley Distribution
1076 7 4.4 Berkeley Distribution
1078 History
1080 M. Douglas McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed, imple‐
1081 mented, and documented the AT&T man macros for Unix Version 7 (1979)
1082 and employed them to edit the first volume of its Programmer's Manual,
1083 a compilation of all man pages supplied by the system. That man sup‐
1084 ported the macros listed in this page not described as extensions, ex‐
1085 cept .P and the deprecated .AT and .UC. The only strings defined were
1086 R and S; no registers were documented.
1087 .UC appeared in 3BSD (1980). Unix System III (1980) introduced .P and
1089 exposed the registers IN and LL, which had been internal to Seventh
1090 Edition Unix man. PWB/UNIX 2.0 (1980) added the Tm string. 4BSD
1091 (1980) added lq and rq strings. SunOS 2.0 (1985) recognized C, D, P,
1092 and X registers. 4.3BSD (1986) added .AT and .P. Ninth Edition Re‐
1093 search Unix (1986) introduced .EX and .EE. SunOS 4.0 (1988) added .SB.
1094 The foregoing features were what James Clark implemented in early ver‐
1096 sions of groff. Later, groff 1.20 (2009) originated .SY/.YS, .TQ,
1097 .MT/.ME, and .UR/.UE. Plan 9 from User Space's troff introduced .MR in
1098 2020.
1099
1101 The following groff options set registers (with -r) and strings (with
1102 -d) recognized and used by the man macro package. To ensure rendering
1103 consistent with output device capabilities and reader preferences, man
1104 pages should never manipulate them.
1105 -dAD=adjustment-mode
1107 Set line adjustment to adjustment-mode, which is typically “b”
1108 for adjustment to both margins (the default), or “l” for left
1109 alignment (ragged right margin). Any valid argument to groff's
1110 “.ad” request may be used. See groff(7) for less-common
1111 choices.
1112 -rcR=1 Enable continuous rendering. Output is not paginated; instead,
1114 one (potentially very long) page is produced. This is the de‐
1115 fault for terminal and HTML devices. Use -rcR=0 to disable it
1116 on terminal devices; on HTML devices, it cannot be disabled.
1117 -rC1 Number output pages consecutively, in strictly increasing se‐
1119 quence, rather than resetting the page number to 1 (or the value
1120 of register P) with each new man document.
1121 -rCS=1 Set section headings (the argument(s) to .SH) in full capitals.
1123 This transformation is off by default because it discards case
1124 distinction information.
1125 -rCT=1 Set the man page topic (the first argument to .TH) in full capi‐
1127 tals in headers and footers. This transformation is off by de‐
1128 fault because it discards case distinction information.
1129 -rD1 Enable double-sided layout, formatting footers for even and odd
1131 pages differently; see the description of .TH in subsection
1132 “Document structure macros” above.
1133 -rFT=footer-distance
1135 Set distance of the footer relative to the bottom of the page to
1136 footer-distance; this amount is always negative. At one half-
1137 inch above this location, the page text is broken before writing
1138 the footer. Ignored if continuous rendering is enabled. The
1139 default is -0.5i.
1140 -dHF=heading-font
1142 Set the font used for section and subsection headings; the de‐
1143 fault is “B” (bold style of the default family). Any valid ar‐
1144 gument to groff's “.ft” request may be used. See groff(7).
1145 -rHY=0 Disable automatic hyphenation. Normally, it is enabled (1).
1147 The hyphenation mode is determined by the groff locale; see sec‐
1148 tion “Localization“ of groff(7).
1149 -rIN=standard-indentation
1151 Set the amount of indentation used for ordinary paragraphs (.P
1152 and its synonyms) and the default indentation amount used by
1153 .IP, .RS, .TP, and the deprecated .HP. See subsection “Horizon‐
1154 tal and vertical spacing” above for the default. For terminal
1155 devices, standard-indentation should always be an integer multi‐
1156 ple of unit “n” to get consistent indentation.
1157 -rLL=line-length
1159 Set line length; the default is 78n for terminal devices and
1160 6.5i for typesetting devices.
1161 -rLT=title-length
1163 Set the line length for titles. (“Titles” is the roff term for
1164 headers and footers.) By default, it is set to the line length
1165 (see -rLL above).
1166 -dMF=man-page-topic-font
1168 Set the font used for man page topics named in .TH and .MR
1169 calls; the default is “I” (italic style of the default family).
1170 Any valid argument to groff's “.ft” request may be used. If the
1171 MF string ends in “I”, it is assumed to be an oblique typeface,
1172 and italic corrections are applied before and after man page
1173 topics.
1174 -rPn Start enumeration of pages at n. The default is 1.
1176 -rStype-size
1178 Use type-size for the document's body text; acceptable values
1179 are 10, 11, or 12 points. See subsection “Font style macros”
1180 above for the default.
1181 -rSN=subsection-indentation
1183 Set indentation of subsection headings to subsection-indenta‐
1184 tion. See subsection “Horizontal and vertical spacing” above
1185 for the default.
1186 -rU1 Enable generation of URI hyperlinks in the grohtml and grotty
1188 output drivers. grohtml enables them by default; grotty does
1189 not, pending more widespread pager support for OSC 8 escape se‐
1190 quences. Use -rU0 to disable hyperlinks; this will make the ar‐
1191 guments to MT and UR calls visible in the document text produced
1192 by link-capable drivers.
1193 -rXp Number successors of page p as pa, pb, pc, and so forth. The
1195 register tracking the suffixed page letter uses format “a” (see
1196 the “.af” request in groff(7)). For example, the option -rX2
1197 produces the following page numbers: 1, 2, 2a, 2b, ..., 2aa,
1198 2ab, and so on.
1199
1201 /usr/share/groff/1.23.0/tmac/an.tmac
1202 Most man macros are defined in this file. It also loads exten‐
1203 sions from an-ext.tmac (see below).
1204 /usr/share/groff/1.23.0/tmac/andoc.tmac
1206 This brief groff program detects whether the man or mdoc macro
1207 package is being used by a document and loads the correct macro
1208 definitions, taking advantage of the fact that pages using them
1209 must call .TH or .Dd, respectively, before any other macros. A
1210 man program or user typing, for example, “groff -mandoc page.1”,
1211 need not know which package the file page.1 uses. Multiple man
1212 pages, in either format, can be handled; andoc reloads each
1213 macro package as necessary.
1214 /usr/share/groff/1.23.0/tmac/an-ext.tmac
1216 Except for .SB, definitions of macros described above as exten‐
1217 sions are contained in this file; in some cases, they are sim‐
1218 pler versions of definitions appearing in an.tmac, and are ig‐
1219 nored if the formatter is GNU troff. They are written to be
1220 compatible with AT&T troff and permissively licensed—not copy‐
1221 lefted. To reduce the risk of name space collisions, string and
1222 register names begin only with “m”. We encourage man page au‐
1223 thors who are concerned about portability to legacy Unix systems
1224 to copy these definitions into their pages, and maintainers of
1225 troff implementations or work-alike systems that format man
1226 pages to re-use them.
1227 The definitions for these macros are read after a page calls
1229 .TH, so they will replace any macros of the same names preceding
1230 it in your file. If you use your own implementations of these
1231 macros, they must be defined after .TH is called to have any ef‐
1232 fect. Furthermore, it is wise to define such page-local macros
1233 (if at all) after the “Name” section to accommodate timid make‐
1234 whatis or mandb implementations that may give up their scan for
1235 indexing material early.
1236 /usr/share/groff/1.23.0/tmac/man.tmac
1238 This is a wrapper that loads an.tmac.
1239 /usr/share/groff/1.23.0/tmac/mandoc.tmac
1241 This is a wrapper that loads andoc.tmac.
1242 /etc/groff/site-tmac/man.local
1244 Put site-local changes and customizations into this file.
1245 .\" Use narrower indentation on terminals and similar.
1247 .if n .nr IN 4n
1248 .\" Put only one space after the end of a sentence.
1249 .ss 12 0 \" See groff(7).
1250 .\" Keep pages narrow even on wide terminals.
1251 .if n .if \n[LL]>78n .nr LL 78n
1252 .\" Ensure hyperlinks are enabled for terminals.
1253 .nr U 1
1254 On multi-user systems, it is more considerate to users whose
1256 preferences may differ from the administrator's to be less ag‐
1257 gressive with such settings, or to permit their override with a
1258 user-specific man.local file. Place the requests below at the
1259 end of the site-local file to manifest courtesy.
1260 .soquiet \V[XDG_CONFIG_HOME]/man.local
1261 .soquiet \V[HOME]/.man.local
1262 However, a security-sandboxed man(1) program may lack permission
1263 to open such files.
1264
1266 Some tips on troubleshooting your man pages follow.
1267 • Some ASCII characters look funny or copy and paste wrong.
1269 On devices with large glyph repertoires, like UTF-8-capable ter‐
1270 minals and PDF, several keyboard glyphs are mapped to code
1271 points outside the Unicode basic Latin range because that usu‐
1272 ally results in better typography in the general case. When
1273 documenting GNU/Linux command or C language syntax, however,
1274 this translation is sometimes not desirable.
1275 To get a “literal”... ...should be input.
1277 ────────────────────────────────────────────
1278 ' \(aq
1279 - \-
1280 \ \(rs
1281 ^ \(ha
1282 ` \(ga
1283 ~ \(ti
1284 ────────────────────────────────────────────
1285 Additionally, if a neutral double quote (") is needed in a macro
1287 argument, you can use \(dq to get it. You should not use \(aq
1288 for an ordinary apostrophe (as in “can't”) or \- for an ordinary
1289 hyphen (as in “word-aligned”). Review subsection “Portability”
1290 above.
1291 • Do I ever need to use an empty macro argument ("")?
1293 Probably not. When this seems necessary, often a shorter or
1294 clearer alternative is available.
1295 Instead of... ...should be considered.
1297 ────────────────────────────────────────────────────────────────
1298 .TP "" .TP
1299 ────────────────────────────────────────────────────────────────
1300 .BI "" italic-text bold-text .IB italic-text bold-text
1301 ────────────────────────────────────────────────────────────────
1302 .TH foo 1 "" "foo 1.2.3" .TH foo 1 yyyy-mm-dd "foo 1.2.3"
1303 ────────────────────────────────────────────────────────────────
1304 .IP "" 4n .IP
1305 ────────────────────────────────────────────────────────────────
1306 .IP "" 4n .RS 4n
1307 paragraph .P
1308 ... paragraph
1309 ... .RE
1310 ────────────────────────────────────────────────────────────────
1311 .B one two "" three .B one two three
1312 In the title heading (.TH), the date of the page's last revision
1314 is more important than packaging information; it should not be
1315 omitted. Ideally, a page maintainer will keep both up to date.
1316 .IP is sometimes ill-understood and misused, especially when no
1318 marker argument is supplied—an indentation argument is not re‐
1319 quired. By setting an explicit indentation, you may be overrid‐
1320 ing the reader's preference as set with the -rIN option. If
1321 your page renders adequately without one, use the simpler form.
1322 If you need to indent multiple (unmarked) paragraphs, consider
1323 setting an inset region with .RS and .RE instead.
1324 In the last example, the empty argument does have a subtly dif‐
1326 ferent effect than its suggested replacement: the empty argument
1327 causes an additional space character to be interpolated between
1328 the arguments “two” and “three”—but it is a regular breaking
1329 space, so it can be discarded at the end of an output line. It
1330 is better not to be subtle, particularly with space, which can
1331 be overlooked in source and rendered forms.
1332 • .RS doesn't indent relative to my indented paragraph.
1334 The .RS macro sets the left margin; that is, the position at
1335 which an ordinary paragraph (.P and its synonyms) will be set.
1336 .IP, .TP, and the deprecated .HP use the same default indenta‐
1337 tion. If not given an argument, .RS moves the left margin by
1338 this same amount. To create an inset relative to an indented
1339 paragraph, call .RS repeatedly until an acceptable indentation
1340 is achieved, or give .RS an indentation argument that is at
1341 least as much as the paragraph's indentation amount relative to
1342 an adjacent .P paragraph. See subsection “Horizontal and verti‐
1343 cal spacing” above for the values.
1344 Another approach you can use with tagged paragraphs is to place
1346 an .RS call immediately after the paragraph tag; this will also
1347 force a break regardless of the width of the tag, which some au‐
1348 thors prefer. Follow-up paragraphs under the tag can then be
1349 set with .P instead of .IP. Remember to use .RE to end the in‐
1350 dented region before starting the next tagged paragraph (at the
1351 appropriate nesting level).
1352 • .RE doesn't move the inset back to the expected level.
1354 • warning: scaling unit invalid in context
1355 • warning: register 'an-saved-marginn' not defined
1356 • warning: register 'an-saved-prevailing-indentn' not defined
1357 The .RS macro takes an indentation amount as an argument; the
1358 .RE macro's argument is a specific inset level. .RE 1 goes to
1359 the level before any .RS macros were called, .RE 2 goes to the
1360 level of the first .RS call you made, and so forth. If you de‐
1361 sire symmetry in your macro calls, simply issue one .RE without
1362 an argument for each .RS that precedes it.
1363 After calls to the .SH and .SS sectioning macros, all relative
1365 insets are cleared and calls to .RE have no effect until .RS is
1366 used again.
1367 • Do I need to keep typing the indentation in a series of .IP calls?
1369 Not if you don't want to change it. Review subsection “Horizon‐
1370 tal and vertical spacing” above.
1371 Instead of... ...should be considered.
1373 ─────────────────────────────────────────────
1374 .IP \(bu 4n .IP \(bu 4n
1375 paragraph paragraph
1376 .IP \(bu 4n .IP \(bu
1377 another-paragraph another-paragraph
1378 ─────────────────────────────────────────────
1379 • Why doesn't the package provide a string to insert an ellipsis?
1381 Examples of ellipsis usage are shown above, in subsection “Com‐
1382 mand synopsis macros”. The idiomatic roff ellipsis is three
1383 dots (periods) with thin space escape sequences \| internally
1384 separating them. Since dots both begin control lines and are
1385 candidate end-of-sentence characters, however, it is sometimes
1386 necessary to prefix and/or suffix an ellipsis with the dummy
1387 character escape sequence \&. That fact stands even if a string
1388 is defined to contain the sequence; further, if the string ends
1389 with \&, end-of-sentence detection is defeated when you use the
1390 string at the end of an actual sentence. (Ending a sentence
1391 with an ellipsis is often poor style, but not always.) A hypo‐
1392 thetical string EL that contained an ellipsis, but not the
1393 trailing dummy character \&, would then need to be suffixed with
1394 the latter when not ending a sentence.
1395 Instead of... ...do this.
1397 ──────────────────────────────────────────────────
1398 .ds EL \&.\|.\|. Arguments are
1399 Arguments are .IR src-file\~ .\|.\|.\&
1400 .IR src-file\~ \*(EL\& .IR dest-dir .
1401 .IR dest-dir .
1402 ──────────────────────────────────────────────────
1403 The first column practices a false economy; the savings in typ‐
1405 ing is offset by the cost of obscuring even the suggestion of an
1406 ellipsis to a casual reader of the source document, and reduced
1407 portability to non-roff man page formatters that cannot handle
1408 string definitions.
1409 There is an ellipsis code point in Unicode, and some fonts have
1411 an ellipsis glyph, which some man pages have accessed in a non-
1412 portable way with the font-dependent \N escape sequence. We
1413 discourage the use of these; on terminals, they may crowd the
1414 dots into a half-width character cell, and will not render at
1415 all if the output device doesn't have the glyph. In syntax syn‐
1416 opses, missing ellipses can cause great confusion. Dots and
1417 space are universally supported.
1418
1420 The initial GNU implementation of the man macro package was written by
1421 James Clark. Later, Werner Lemberg ⟨wl@gnu.org⟩ supplied the S, LT,
1422 and cR registers, the last a 4.3BSD-Reno mdoc(7) feature. Larry Kollar
1423 ⟨kollar@alltel.net⟩ added the FT, HY, and SN registers; the HF string;
1424 and the PT and BT macros. G. Branden Robinson ⟨g.branden.robinson@
1425 gmail.com⟩ implemented the AD and MF strings; CS, CT, and U registers;
1426 and the MR macro. Except for .SB, the extension macros were written by
1427 Lemberg, Eric S. Raymond ⟨esr@thyrsus.com⟩, and Robinson.
1428 This document was originally written for the Debian GNU/Linux system by
1430 Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by
1431 Lemberg and Robinson. The extension macros were documented by Raymond
1432 and Robinson. Raymond also originated the portability section, to
1433 which Ingo Schwarze ⟨schwarze@usta.de⟩ contributed most of the material
1434 on escape sequences.
1435
1437 tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
1438 man(1) describes the man page librarian on your system. groff_mdoc(7)
1439 details the groff version of the BSD-originated alternative macro pack‐
1440 age for man pages.
1441 groff_man(7), groff(7), groff_char(7), man(7)
1443groff 1.23.0 2 November 2023 groff_man_style(7)