1MAN(7) BSD Miscellaneous Information Manual MAN(7)
2
4 man — legacy formatting language for manual pages
5
7 The man language was the standard formatting language for AT&T UNIX man‐
8 ual pages from 1979 to 1989. Do not use it to write new manual pages: it
9 is a purely presentational language and lacks support for semantic
10 markup. Use the mdoc(7) language, instead.
11 In a man document, lines beginning with the control character ‘.’ are
13 called “macro lines”. The first word is the macro name. It usually con‐
14 sists of two capital letters. For a list of portable macros, see MACRO
15 OVERVIEW. The words following the macro name are arguments to the macro.
16 Lines not beginning with the control character are called “text lines”.
18 They provide free-form text to be printed; the formatting of the text
19 depends on the respective processing context:
20 .SH Macro lines change control state.
22 Text lines are interpreted within the current state.
23 Many aspects of the basic syntax of the man language are based on the
25 roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in
26 the roff(7) manual for details, in particular regarding comments, escape
27 sequences, whitespace, and quoting.
28 Each man document starts with the TH macro specifying the document's name
30 and section, followed by the NAME section formatted as follows:
31 .TH PROGNAME 1 1979-01-10
33 .SH NAME
34 \fBprogname\fR \(en one line about what it does
35
37 This overview is sorted such that macros of similar purpose are listed
38 together. Deprecated and non-portable macros are not included in the
39 overview, but can be found in the alphabetical reference below.
40 Page header and footer meta-data
42 TH set the title: name section date [source [volume]]
43 AT display AT&T UNIX version in the page footer (<= 1 argument)
44 UC display BSD version in the page footer (<= 1 argument)
45 Sections and paragraphs
47 SH section header (one line)
48 SS subsection header (one line)
49 PP start an undecorated paragraph (no arguments)
50 RS, RE reset the left margin: [width]
51 IP indented paragraph: [head [width]]
52 TP tagged paragraph: [width]
53 PD set vertical paragraph distance: [height]
54 in additional indent: [width]
55 Physical markup
57 B boldface font
58 I italic font
59 SB small boldface font
60 SM small roman font
61 BI alternate between boldface and italic fonts
62 BR alternate between boldface and roman fonts
63 IB alternate between italic and boldface fonts
64 IR alternate between italic and roman fonts
65 RB alternate between roman and boldface fonts
66 RI alternate between roman and italic fonts
67
69 This section is a canonical reference to all macros, arranged alphabeti‐
70 cally. For the scoping of individual macros, see MACRO SYNTAX.
71 AT Sets the volume for the footer for compatibility with man pages from
73 AT&T UNIX releases. The optional arguments specify which release it
74 is from.
75 B Text is rendered in bold face.
77 BI Text is rendered alternately in bold face and italic. Thus, ‘.BI
79 this word and that’ causes ‘this’ and ‘and’ to render in bold face,
80 while ‘word’ and ‘that’ render in italics. Whitespace between argu‐
81 ments is omitted in output.
82 Example:
84 .BI bold italic bold italic
86 BR Text is rendered alternately in bold face and roman (the default
88 font). Whitespace between arguments is omitted in output. See also
89 BI.
90 DT Restore the default tabulator positions. They are at intervals of
92 0.5 inches. This has no effect unless the tabulator positions were
93 changed with the roff(7) ta request.
94 EE This is a non-standard GNU extension. In mandoc(1), it does the
96 same as the roff(7) fi request (switch to fill mode).
97 EX This is a non-standard GNU extension. In mandoc(1), it does the
99 same as the roff(7) nf request (switch to no-fill mode).
100 HP Begin a paragraph whose initial output line is left-justified, but
102 subsequent output lines are indented, with the following syntax:
103 .HP [width]
105 The width argument is a roff(7) scaling width. If specified, it's
107 saved for later paragraph left margins; if unspecified, the saved or
108 default width is used.
109 This macro is portable, but deprecated because it has no good repre‐
111 sentation in HTML output, usually ending up indistinguishable from
112 PP.
113 I Text is rendered in italics.
115 IB Text is rendered alternately in italics and bold face. Whitespace
117 between arguments is omitted in output. See also BI.
118 IP Begin an indented paragraph with the following syntax:
120 .IP [head [width]]
122 The width argument is a roff(7) scaling width defining the left mar‐
124 gin. It's saved for later paragraph left-margins; if unspecified,
125 the saved or default width is used.
126 The head argument is used as a leading term, flushed to the left
128 margin. This is useful for bulleted paragraphs and so on.
129 IR Text is rendered alternately in italics and roman (the default
131 font). Whitespace between arguments is omitted in output. See also
132 BI.
133 LP A synonym for PP.
135 ME End a mailto block started with MT. This is a non-standard GNU
137 extension.
138 MT Begin a mailto block. This is a non-standard GNU extension. It has
140 the following syntax:
141 .MT address
143 link description to be shown
144 .ME
145 OP Optional command-line argument. This is a non-standard GNU exten‐
147 sion. It has the following syntax:
148 .OP key [value]
150 The key is usually a command-line flag and value its argument.
152 P A synonym for PP.
154 PD Specify the vertical space to be inserted before each new paragraph.
156 The syntax is as follows:
157 .PD [height]
159 The height argument is a roff(7) scaling width. It defaults to 1v.
161 If the unit is omitted, v is assumed.
162 This macro affects the spacing before any subsequent instances of
164 HP, IP, LP, P, PP, SH, SS, SY, and TP.
165 PP Begin an undecorated paragraph. The scope of a paragraph is closed
167 by a subsequent paragraph, sub-section, section, or end of file.
168 The saved paragraph left-margin width is reset to the default.
169 RB Text is rendered alternately in roman (the default font) and bold
171 face. Whitespace between arguments is omitted in output. See also
172 BI.
173 RE Explicitly close out the scope of a prior RS. The default left mar‐
175 gin is restored to the state before that RS invocation.
176 The syntax is as follows:
178 .RE [level]
180 Without an argument, the most recent RS block is closed out. If
182 level is 1, all open RS blocks are closed out. Otherwise, level − 1
183 nested RS blocks remain open.
184 RI Text is rendered alternately in roman (the default font) and ital‐
186 ics. Whitespace between arguments is omitted in output. See also
187 BI.
188 RS Temporarily reset the default left margin. This has the following
190 syntax:
191 .RS [width]
193 The width argument is a roff(7) scaling width. If not specified,
195 the saved or default width is used.
196 See also RE.
198 SB Text is rendered in small size (one point smaller than the default
200 font) bold face.
201 SH Begin a section. The scope of a section is only closed by another
203 section or the end of file. The paragraph left-margin width is
204 reset to the default.
205 SM Text is rendered in small size (one point smaller than the default
207 font).
208 SS Begin a sub-section. The scope of a sub-section is closed by a sub‐
210 sequent sub-section, section, or end of file. The paragraph left-
211 margin width is reset to the default.
212 SY Begin a synopsis block with the following syntax:
214 .SY command
216 arguments
217 .YS
218 This is a non-standard GNU extension and very rarely used even in
220 GNU manual pages. Formatting is similar to IP.
221 TH Set the name of the manual page for use in the page header and
223 footer with the following syntax:
224 .TH name section date [source [volume]]
226 Conventionally, the document name is given in all caps. The section
228 is usually a single digit, in a few cases followed by a letter. The
229 recommended date format is YYYY-MM-DD as specified in the ISO-8601
230 standard; if the argument does not conform, it is printed verbatim.
231 If the date is empty or not specified, the current date is used.
232 The optional source string specifies the organisation providing the
233 utility. When unspecified, mandoc(1) uses its -Ios argument. The
234 volume string replaces the default volume title of the section.
235 Examples:
237 .TH CVS 5 1992-02-12 GNU
239 TP Begin a paragraph where the head, if exceeding the indentation
241 width, is followed by a newline; if not, the body follows on the
242 same line after advancing to the indentation width. Subsequent out‐
243 put lines are indented. The syntax is as follows:
244 .TP [width]
246 head \" one line
247 body
248 The width argument is a roff(7) scaling width. If specified, it's
250 saved for later paragraph left-margins; if unspecified, the saved or
251 default width is used.
252 TQ Like TP, except that no vertical spacing is inserted before the
254 paragraph. This is a non-standard GNU extension and very rarely
255 used even in GNU manual pages.
256 UC Sets the volume for the footer for compatibility with man pages from
258 BSD releases. The optional first argument specifies which release
259 it is from.
260 UE End a uniform resource identifier block started with UR. This is a
262 non-standard GNU extension.
263 UR Begin a uniform resource identifier block. This is a non-standard
265 GNU extension. It has the following syntax:
266 .UR uri
268 link description to be shown
269 .UE
270 YS End a synopsis block started with SY. This is a non-standard GNU
272 extension.
273 in Indent relative to the current indentation:
275 .in [width]
277 If width is signed, the new offset is relative. Otherwise, it is
279 absolute. This value is reset upon the next paragraph, section, or
280 sub-section.
281
283 The man macros are classified by scope: line scope or block scope. Line
284 macros are only scoped to the current line (and, in some situations, the
285 subsequent line). Block macros are scoped to the current line and subse‐
286 quent lines until closed by another block macro.
287 Line Macros
289 Line macros are generally scoped to the current line, with the body con‐
290 sisting of zero or more arguments. If a macro is scoped to the next line
291 and the line arguments are empty, the next line, which must be text, is
292 used instead. Thus:
293 .I
295 foo
296 is equivalent to ‘.I foo’. If next-line macros are invoked consecu‐
298 tively, only the last is used. If a next-line macro is followed by a
299 non-next-line macro, an error is raised.
300 The syntax is as follows:
302 .YO [body...]
304 [body...]
305 Macro Arguments Scope Notes
307 AT <=1 current
308 B n next-line
309 BI n current
310 BR n current
311 DT 0 current
312 EE 0 current GNU
313 EX 0 current GNU
314 I n next-line
315 IB n current
316 IR n current
317 OP >=1 current GNU
318 PD 1 current
319 RB n current
320 RI n current
321 SB n next-line
322 SM n next-line
323 TH >1, <6 current
324 UC <=1 current
325 in 1 current roff(7)
326 Block Macros
328 Block macros comprise a head and body. As with in-line macros, the head
329 is scoped to the current line and, in one circumstance, the next line
330 (the next-line stipulations as in Line Macros apply here as well).
331 The syntax is as follows:
333 .YO [head...]
335 [head...]
336 [body...]
337 The closure of body scope may be to the section, where a macro is closed
339 by SH; sub-section, closed by a section or SS; or paragraph, closed by a
340 section, sub-section, HP, IP, LP, P, PP, RE, SY, or TP. No closure
341 refers to an explicit block closing macro.
342 As a rule, block macros may not be nested; thus, calling a block macro
344 while another block macro scope is open, and the open scope is not
345 implicitly closed, is syntactically incorrect.
346 Macro Arguments Head Scope Body Scope Notes
348 HP <2 current paragraph
349 IP <3 current paragraph
350 LP 0 current paragraph
351 ME 0 none none GNU
352 MT 1 current to ME GNU
353 P 0 current paragraph
354 PP 0 current paragraph
355 RE <=1 current none
356 RS 1 current to RE
357 SH >0 next-line section
358 SS >0 next-line sub-section
359 SY 1 current to YS GNU
360 TP n next-line paragraph
361 TQ n next-line paragraph GNU
362 UE 0 current none GNU
363 UR 1 current part GNU
364 YS 0 none none GNU
365 If a block macro is next-line scoped, it may only be followed by in-line
367 macros for decorating text.
368 Font handling
370 In man documents, both Physical markup macros and roff(7) ‘\f’ font
371 escape sequences can be used to choose fonts. In text lines, the effect
372 of manual font selection by escape sequences only lasts until the next
373 macro invocation; in macro lines, it only lasts until the end of the
374 macro scope. Note that macros like BR open and close a font scope for
375 each argument.
376
378 man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)
379
381 The man language first appeared as a macro package for the roff typeset‐
382 ting system in Version 7 AT&T UNIX. It was later rewritten by James
383 Clark as a macro package for groff. Eric S. Raymond wrote the extended
384 man macros for groff in 2007. The stand-alone implementation that is
385 part of the mandoc(1) utility written by Kristaps Dzonsons appeared in
386 OpenBSD 4.6.
387
389 This man reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
390BSD May 10, 2020 BSD