1MAN(7) BSD Miscellaneous Information Manual MAN(7)
2
4 man — legacy formatting language for manual pages
5
7 Traditionally, the man language has been used to write UNIX manuals for
8 the man(1) utility. It supports limited control of presentational
9 details like fonts, indentation and spacing. This reference document
10 describes the structure of manual pages and the syntax and usage of the
11 man language.
12 Do not use man to write your manuals: It lacks support for semantic
14 markup. Use the mdoc(7) language, instead.
15 In a man document, lines beginning with the control character ‘.’ are
17 called “macro lines”. The first word is the macro name. It usually con‐
18 sists of two capital letters. For a list of available macros, see MACRO
19 OVERVIEW. The words following the macro name are arguments to the macro.
20 Lines not beginning with the control character are called “text lines”.
22 They provide free-form text to be printed; the formatting of the text
23 depends on the respective processing context:
24 .SH Macro lines change control state.
26 Text lines are interpreted within the current state.
27 Many aspects of the basic syntax of the man language are based on the
29 roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in
30 the roff(7) manual for details, in particular regarding comments, escape
31 sequences, whitespace, and quoting.
32
34 Each man document must contain the TH macro describing the document's
35 section and title. It may occur anywhere in the document, although con‐
36 ventionally it appears as the first macro.
37 Beyond TH, at least one macro or text line must appear in the document.
39 The following is a well-formed skeleton man file for a utility
41 "progname":
42 .TH PROGNAME 1 2009-10-10
44 .SH NAME
45 \fBprogname\fR \(en one line about what it does
46 .\" .SH LIBRARY
47 .\" For sections 2, 3, and 9 only.
48 .\" Not used in OpenBSD.
49 .SH SYNOPSIS
50 \fBprogname\fR [\fB\-options\fR] \fIfile ...\fR
51 .SH DESCRIPTION
52 The \fBfoo\fR utility processes files ...
53 .\" .Sh CONTEXT
54 .\" For section 9 functions only.
55 .\" .SH IMPLEMENTATION NOTES
56 .\" Not used in OpenBSD.
57 .\" .SH RETURN VALUES
58 .\" For sections 2, 3, and 9 function return values only.
59 .\" .SH ENVIRONMENT
60 .\" For sections 1, 6, 7, and 8 only.
61 .\" .SH FILES
62 .\" .SH EXIT STATUS
63 .\" For sections 1, 6, and 8 only.
64 .\" .SH EXAMPLES
65 .\" .SH DIAGNOSTICS
66 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
67 .\" .SH ERRORS
68 .\" For sections 2, 3, 4, and 9 errno settings only.
69 .\" .SH SEE ALSO
70 .\" .BR foobar ( 1 )
71 .\" .SH STANDARDS
72 .\" .SH HISTORY
73 .\" .SH AUTHORS
74 .\" .SH CAVEATS
75 .\" .SH BUGS
76 .\" .SH SECURITY CONSIDERATIONS
77 .\" Not used in OpenBSD.
78 The sections in a man document are conventionally ordered as they appear
80 above. Sections should be composed as follows:
81 NAME
83 The name(s) and a short description of the documented material.
84 The syntax for this is generally as follows:
85 \fBname\fR \(en description
87 LIBRARY
89 The name of the library containing the documented material, which
90 is assumed to be a function in a section 2 or 3 manual. For func‐
91 tions in the C library, this may be as follows:
92 Standard C Library (libc, -lc)
94 SYNOPSIS
96 Documents the utility invocation syntax, function call syntax, or
97 device configuration.
98 For the first, utilities (sections 1, 6, and 8), this is generally
100 structured as follows:
101 \fBname\fR [-\fBab\fR] [-\fBc\fR\fIarg\fR] \fBpath\fR...
103 For the second, function calls (sections 2, 3, 9):
105 .B char *name(char *\fIarg\fR);
107 And for the third, configurations (section 4):
109 .B name* at cardbus? function?
111 Manuals not in these sections generally don't need a SYNOPSIS.
113 DESCRIPTION
115 This expands upon the brief, one-line description in NAME. It usu‐
116 ally contains a break-down of the options (if documenting a com‐
117 mand).
118 CONTEXT
120 This section lists the contexts in which functions can be called in
121 section 9. The contexts are autoconf, process, or interrupt.
122 IMPLEMENTATION NOTES
124 Implementation-specific notes should be kept here. This is useful
125 when implementing standard functions that may have side effects or
126 notable algorithmic implications.
127 RETURN VALUES
129 This section documents the return values of functions in sections
130 2, 3, and 9.
131 ENVIRONMENT
133 Documents any usages of environment variables, e.g., environ(7).
134 FILES
136 Documents files used. It's helpful to document both the file name
137 and a short description of how the file is used (created, modified,
138 etc.).
139 EXIT STATUS
141 This section documents the command exit status for section 1, 6,
142 and 8 utilities. Historically, this information was described in
143 DIAGNOSTICS, a practise that is now discouraged.
144 EXAMPLES
146 Example usages. This often contains snippets of well-formed, well-
147 tested invocations. Make sure that examples work properly!
148 DIAGNOSTICS
150 Documents error conditions. In section 4 and 9 manuals, these are
151 usually messages printed by the kernel to the console and to the
152 kernel log. In section 1, 6, 7, and 8, these are usually messages
153 printed by userland programs to the standard error output.
154 Historically, this section was used in place of EXIT STATUS for
156 manuals in sections 1, 6, and 8; however, this practise is discour‐
157 aged.
158 ERRORS
160 Documents errno(2) settings in sections 2, 3, 4, and 9.
161 SEE ALSO
163 References other manuals with related topics. This section should
164 exist for most manuals.
165 .BR bar ( 1 ),
167 Cross-references should conventionally be ordered first by section,
169 then alphabetically.
170 STANDARDS
172 References any standards implemented or used, such as
173 IEEE Std 1003.2 (\(lqPOSIX.2\(rq)
175 If not adhering to any standards, the HISTORY section should be
177 used.
178 HISTORY
180 A brief history of the subject, including where support first
181 appeared.
182 AUTHORS
184 Credits to the person or persons who wrote the code and/or documen‐
185 tation. Authors should generally be noted by both name and email
186 address.
187 CAVEATS
189 Common misuses and misunderstandings should be explained in this
190 section.
191 BUGS
193 Known bugs, limitations, and work-arounds should be described in
194 this section.
195 SECURITY CONSIDERATIONS
197 Documents any security precautions that operators should consider.
198
200 This overview is sorted such that macros of similar purpose are listed
201 together, to help find the best macro for any given purpose. Deprecated
202 macros are not included in the overview, but can be found in the alpha‐
203 betical reference below.
204 Page header and footer meta-data
206 TH set the title: title section date [source [volume]]
207 AT display AT&T UNIX version in the page footer (<= 1 argument)
208 UC display BSD version in the page footer (<= 1 argument)
209 Sections and paragraphs
211 SH section header (one line)
212 SS subsection header (one line)
213 PP, LP, P start an undecorated paragraph (no arguments)
214 RS, RE reset the left margin: [width]
215 IP indented paragraph: [head [width]]
216 TP tagged paragraph: [width]
217 HP hanged paragraph: [width]
218 PD set vertical paragraph distance: [height]
219 fi, nf fill mode and no-fill mode (no arguments)
220 in additional indent: [width]
221 Physical markup
223 B boldface font
224 I italic font
225 SB small boldface font
226 SM small roman font
227 BI alternate between boldface and italic fonts
228 BR alternate between boldface and roman fonts
229 IB alternate between italic and boldface fonts
230 IR alternate between italic and roman fonts
231 RB alternate between roman and boldface fonts
232 RI alternate between roman and italic fonts
233
235 This section is a canonical reference to all macros, arranged alphabeti‐
236 cally. For the scoping of individual macros, see MACRO SYNTAX.
237 AT
239 Sets the volume for the footer for compatibility with man pages from AT&T
240 UNIX releases. The optional arguments specify which release it is from.
241 B
243 Text is rendered in bold face.
244 See also I.
246 BI
248 Text is rendered alternately in bold face and italic. Thus, ‘.BI this
249 word and that’ causes ‘this’ and ‘and’ to render in bold face, while
250 ‘word’ and ‘that’ render in italics. Whitespace between arguments is
251 omitted in output.
252 Examples:
254 .BI bold italic bold italic
256 The output of this example will be emboldened “bold” and italicised
258 “italic”, with spaces stripped between arguments.
259 See also IB, BR, RB, RI, and IR.
261 BR
263 Text is rendered alternately in bold face and roman (the default font).
264 Whitespace between arguments is omitted in output.
265 See BI for an equivalent example.
267 See also BI, IB, RB, RI, and IR.
269 DT
271 Restore the default tabulator positions. They are at intervals of 0.5
272 inches. This has no effect unless the tabulator positions were changed
273 with the roff(7) ta request.
274 EE
276 This is a non-standard GNU extension, included only for compatibility.
277 In mandoc(1), it does the same as fi.
278 EX
280 This is a non-standard GNU extension, included only for compatibility.
281 In mandoc(1), it does the same as nf.
282 HP
284 Begin a paragraph whose initial output line is left-justified, but subse‐
285 quent output lines are indented, with the following syntax:
286 .HP [width]
288 The width argument is a roff(7) scaling width. If specified, it's saved
290 for later paragraph left-margins; if unspecified, the saved or default
291 width is used.
292 See also IP, LP, P, PP, and TP.
294 I
296 Text is rendered in italics.
297 See also B.
299 IB
301 Text is rendered alternately in italics and bold face. Whitespace
302 between arguments is omitted in output.
303 See BI for an equivalent example.
305 See also BI, BR, RB, RI, and IR.
307 IP
309 Begin an indented paragraph with the following syntax:
310 .IP [head [width]]
312 The width argument is a roff(7) scaling width defining the left margin.
314 It's saved for later paragraph left-margins; if unspecified, the saved or
315 default width is used.
316 The head argument is used as a leading term, flushed to the left margin.
318 This is useful for bulleted paragraphs and so on.
319 See also HP, LP, P, PP, and TP.
321 IR
323 Text is rendered alternately in italics and roman (the default font).
324 Whitespace between arguments is omitted in output.
325 See BI for an equivalent example.
327 See also BI, IB, BR, RB, and RI.
329 LP
331 Begin an undecorated paragraph. The scope of a paragraph is closed by a
332 subsequent paragraph, sub-section, section, or end of file. The saved
333 paragraph left-margin width is reset to the default.
334 See also HP, IP, P, PP, and TP.
336 ME
338 End a mailto block. This is a non-standard GNU extension, included only
339 for compatibility. See MT.
340 MT
342 Begin a mailto block. This is a non-standard GNU extension, included
343 only for compatibility. It has the following syntax:
344 .MT address
346 link description to be shown
347 .ME
348 OP
350 Optional command-line argument. This is a non-standard GNU extension,
351 included only for compatibility. It has the following syntax:
352 .OP key [value]
354 The key is usually a command-line flag and value its argument.
356 P
358 Synonym for LP.
359 See also HP, IP, LP, PP, and TP.
361 PD
363 Specify the vertical space to be inserted before each new paragraph.
364 The syntax is as follows:
365 .PD [height]
367 The height argument is a roff(7) scaling width. It defaults to 1v. If
369 the unit is omitted, v is assumed.
370 This macro affects the spacing before any subsequent instances of HP, IP,
372 LP, P, PP, SH, SS, and TP.
373 PP
375 Synonym for LP.
376 See also HP, IP, LP, P, and TP.
378 RB
380 Text is rendered alternately in roman (the default font) and bold face.
381 Whitespace between arguments is omitted in output.
382 See BI for an equivalent example.
384 See also BI, IB, BR, RI, and IR.
386 RE
388 Explicitly close out the scope of a prior RS. The default left margin is
389 restored to the state before that RS invocation.
390 The syntax is as follows:
392 .RE [level]
394 Without an argument, the most recent RS block is closed out. If level is
396 1, all open RS blocks are closed out. Otherwise, level − 1 nested RS
397 blocks remain open.
398 RI
400 Text is rendered alternately in roman (the default font) and italics.
401 Whitespace between arguments is omitted in output.
402 See BI for an equivalent example.
404 See also BI, IB, BR, RB, and IR.
406 RS
408 Temporarily reset the default left margin. This has the following syn‐
409 tax:
410 .RS [width]
412 The width argument is a roff(7) scaling width. If not specified, the
414 saved or default width is used.
415 See also RE.
417 SB
419 Text is rendered in small size (one point smaller than the default font)
420 bold face.
421 SH
423 Begin a section. The scope of a section is only closed by another sec‐
424 tion or the end of file. The paragraph left-margin width is reset to the
425 default.
426 SM
428 Text is rendered in small size (one point smaller than the default font).
429 SS
431 Begin a sub-section. The scope of a sub-section is closed by a subse‐
432 quent sub-section, section, or end of file. The paragraph left-margin
433 width is reset to the default.
434 TH
436 Sets the title of the manual page for use in the page header and footer
437 with the following syntax:
438 .TH title section date [source [volume]]
440 Conventionally, the document title is given in all caps. The recommended
442 date format is YYYY-MM-DD as specified in the ISO-8601 standard; if the
443 argument does not conform, it is printed verbatim. If the date is empty
444 or not specified, the current date is used. The optional source string
445 specifies the organisation providing the utility. When unspecified,
446 mandoc(1) uses its -Ios argument. The volume string replaces the default
447 rendered volume, which is dictated by the manual section.
448 Examples:
450 .TH CVS 5 1992-02-12 GNU
452 TP
454 Begin a paragraph where the head, if exceeding the indentation width, is
455 followed by a newline; if not, the body follows on the same line after a
456 buffer to the indentation width. Subsequent output lines are indented.
457 The syntax is as follows:
458 .TP [width]
460 The width argument is a roff(7) scaling width. If specified, it's saved
462 for later paragraph left-margins; if unspecified, the saved or default
463 width is used.
464 See also HP, IP, LP, P, and PP.
466 UC
468 Sets the volume for the footer for compatibility with man pages from BSD
469 releases. The optional first argument specifies which release it is
470 from.
471 UE
473 End a uniform resource identifier block. This is a non-standard GNU
474 extension, included only for compatibility. See UE.
475 UR
477 Begin a uniform resource identifier block. This is a non-standard GNU
478 extension, included only for compatibility. It has the following syntax:
479 .UR uri
481 link description to be shown
482 .UE
483 fi
485 End literal mode begun by nf.
486 in
488 Indent relative to the current indentation:
489 .in [width]
491 If width is signed, the new offset is relative. Otherwise, it is abso‐
493 lute. This value is reset upon the next paragraph, section, or sub-sec‐
494 tion.
495 nf
497 Begin literal mode: all subsequent free-form lines have their end of line
498 boundaries preserved. May be ended by fi. Literal mode is implicitly
499 ended by SH or SS.
500
502 The man macros are classified by scope: line scope or block scope. Line
503 macros are only scoped to the current line (and, in some situations, the
504 subsequent line). Block macros are scoped to the current line and subse‐
505 quent lines until closed by another block macro.
506 Line Macros
508 Line macros are generally scoped to the current line, with the body con‐
509 sisting of zero or more arguments. If a macro is scoped to the next line
510 and the line arguments are empty, the next line, which must be text, is
511 used instead. Thus:
512 .I
514 foo
515 is equivalent to ‘.I foo’. If next-line macros are invoked consecu‐
517 tively, only the last is used. If a next-line macro is followed by a
518 non-next-line macro, an error is raised.
519 The syntax is as follows:
521 .YO [body...]
523 [body...]
524 Macro Arguments Scope Notes
526 AT <=1 current
527 B n next-line
528 BI n current
529 BR n current
530 DT 0 current
531 EE 0 current compat
532 EX 0 current compat
533 I n next-line
534 IB n current
535 IR n current
536 OP 0, 1 current compat
537 PD 1 current
538 RB n current
539 RI n current
540 SB n next-line
541 SM n next-line
542 TH >1, <6 current
543 UC <=1 current
544 fi 0 current compat
545 in 1 current compat
546 nf 0 current compat
547 Macros marked as "compat" are included for compatibility with the signif‐
549 icant corpus of existing manuals that mix dialects of roff. These macros
550 should not be used for portable man manuals.
551 Block Macros
553 Block macros comprise a head and body. As with in-line macros, the head
554 is scoped to the current line and, in one circumstance, the next line
555 (the next-line stipulations as in Line Macros apply here as well).
556 The syntax is as follows:
558 .YO [head...]
560 [head...]
561 [body...]
562 The closure of body scope may be to the section, where a macro is closed
564 by SH; sub-section, closed by a section or SS; part, closed by a section,
565 sub-section, or RE; or paragraph, closed by a section, sub-section, part,
566 HP, IP, LP, P, PP, or TP. No closure refers to an explicit block closing
567 macro.
568 As a rule, block macros may not be nested; thus, calling a block macro
570 while another block macro scope is open, and the open scope is not
571 implicitly closed, is syntactically incorrect.
572 Macro Arguments Head Scope Body Scope Notes
574 HP <2 current paragraph
575 IP <3 current paragraph
576 LP 0 current paragraph
577 P 0 current paragraph
578 PP 0 current paragraph
579 RE 0 current none compat
580 RS 1 current part compat
581 SH >0 next-line section
582 SS >0 next-line sub-section
583 TP n next-line paragraph
584 UE 0 current none compat
585 UR 1 current part compat
586 Macros marked "compat" are as mentioned in Line Macros.
588 If a block macro is next-line scoped, it may only be followed by in-line
590 macros for decorating text.
591 Font handling
593 In man documents, both Physical markup macros and roff(7) ‘\f’ font
594 escape sequences can be used to choose fonts. In text lines, the effect
595 of manual font selection by escape sequences only lasts until the next
596 macro invocation; in macro lines, it only lasts until the end of the
597 macro scope. Note that macros like BR open and close a font scope for
598 each argument.
599
601 man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)
602
604 The man language first appeared as a macro package for the roff typeset‐
605 ting system in Version 7 AT&T UNIX. It was later rewritten by James
606 Clark as a macro package for groff. Eric S. Raymond wrote the extended
607 man macros for groff in 2007. The stand-alone implementation that is
608 part of the mandoc(1) utility written by Kristaps Dzonsons appeared in
609 OpenBSD 4.6.
610
612 This man reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
613
615 Do not use this language. Use mdoc(7), instead.
616BSD June 20, 2019 BSD