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 de‐
19 pends 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. This macro is an extension that first appeared in 4.3BSD.
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 Version 9 AT&T UNIX extension later adopted
96 by GNU. In mandoc(1), it does the same as the roff(7) fi request
97 (switch to fill mode).
98 EX This is a non-standard Version 9 AT&T UNIX extension later adopted
100 by GNU. In mandoc(1), it does the same as the roff(7) nf request
101 (switch to no-fill mode).
102 HP Begin a paragraph whose initial output line is left-justified, but
104 subsequent output lines are indented, with the following syntax:
105 .HP [width]
107 The width argument is a roff(7) scaling width. If specified, it's
109 saved for later paragraph left margins; if unspecified, the saved or
110 default width is used.
111 This macro is portable, but deprecated because it has no good repre‐
113 sentation in HTML output, usually ending up indistinguishable from
114 PP.
115 I Text is rendered in italics.
117 IB Text is rendered alternately in italics and bold face. Whitespace
119 between arguments is omitted in output. See also BI.
120 IP Begin an indented paragraph with the following syntax:
122 .IP [head [width]]
124 The width argument is a roff(7) scaling width defining the left mar‐
126 gin. It's saved for later paragraph left-margins; if unspecified,
127 the saved or default width is used.
128 The head argument is used as a leading term, flushed to the left
130 margin. This is useful for bulleted paragraphs and so on.
131 IR Text is rendered alternately in italics and roman (the default
133 font). Whitespace between arguments is omitted in output. See also
134 BI.
135 LP A synonym for PP.
137 ME End a mailto block started with MT. This is a non-standard GNU ex‐
139 tension.
140 MT Begin a mailto block. This is a non-standard GNU extension. It has
142 the following syntax:
143 .MT address
145 link description to be shown
146 .ME
147 OP Optional command-line argument. This is a non-standard DWB exten‐
149 sion. It has the following syntax:
150 .OP key [value]
152 The key is usually a command-line flag and value its argument.
154 P This synonym for PP is an AT&T System III UNIX extension later
156 adopted by 4.3BSD.
157 PD Specify the vertical space to be inserted before each new paragraph.
159 The syntax is as follows:
160 .PD [height]
162 The height argument is a roff(7) scaling width. It defaults to 1v.
164 If the unit is omitted, v is assumed.
165 This macro affects the spacing before any subsequent instances of
167 HP, IP, LP, P, PP, SH, SS, SY, and TP.
168 PP Begin an undecorated paragraph. The scope of a paragraph is closed
170 by a subsequent paragraph, sub-section, section, or end of file.
171 The saved paragraph left-margin width is reset to the default.
172 RB Text is rendered alternately in roman (the default font) and bold
174 face. Whitespace between arguments is omitted in output. See also
175 BI.
176 RE Explicitly close out the scope of a prior RS. The default left mar‐
178 gin is restored to the state before that RS invocation.
179 The syntax is as follows:
181 .RE [level]
183 Without an argument, the most recent RS block is closed out. If
185 level is 1, all open RS blocks are closed out. Otherwise, level − 1
186 nested RS blocks remain open.
187 RI Text is rendered alternately in roman (the default font) and ital‐
189 ics. Whitespace between arguments is omitted in output. See also
190 BI.
191 RS Temporarily reset the default left margin. This has the following
193 syntax:
194 .RS [width]
196 The width argument is a roff(7) scaling width. If not specified,
198 the saved or default width is used.
199 See also RE.
201 SB Text is rendered in small size (one point smaller than the default
203 font) bold face. This macro is an extension that probably first ap‐
204 peared in SunOS 4.0 and was later adopted by GNU and by 4.4BSD.
205 SH Begin a section. The scope of a section is only closed by another
207 section or the end of file. The paragraph left-margin width is re‐
208 set to the default.
209 SM Text is rendered in small size (one point smaller than the default
211 font).
212 SS Begin a sub-section. The scope of a sub-section is closed by a sub‐
214 sequent sub-section, section, or end of file. The paragraph left-
215 margin width is reset to the default.
216 SY Begin a synopsis block with the following syntax:
218 .SY command
220 arguments
221 .YS
222 This is a non-standard GNU extension and very rarely used even in
224 GNU manual pages. Formatting is similar to IP.
225 TH Set the name of the manual page for use in the page header and
227 footer with the following syntax:
228 .TH name section date [source [volume]]
230 Conventionally, the document name is given in all caps. The section
232 is usually a single digit, in a few cases followed by a letter. The
233 recommended date format is YYYY-MM-DD as specified in the ISO-8601
234 standard; if the argument does not conform, it is printed verbatim.
235 If the date is empty or not specified, the current date is used.
236 The optional source string specifies the organisation providing the
237 utility. When unspecified, mandoc(1) uses its -Ios argument. The
238 volume string replaces the default volume title of the section.
239 Examples:
241 .TH CVS 5 1992-02-12 GNU
243 TP Begin a paragraph where the head, if exceeding the indentation
245 width, is followed by a newline; if not, the body follows on the
246 same line after advancing to the indentation width. Subsequent out‐
247 put lines are indented. The syntax is as follows:
248 .TP [width]
250 head \" one line
251 body
252 The width argument is a roff(7) scaling width. If specified, it's
254 saved for later paragraph left-margins; if unspecified, the saved or
255 default width is used.
256 TQ Like TP, except that no vertical spacing is inserted before the
258 paragraph. This is a non-standard GNU extension and very rarely
259 used even in GNU manual pages.
260 UC Sets the volume for the footer for compatibility with man pages from
262 BSD releases. The optional first argument specifies which release
263 it is from. This macro is an extension that first appeared in 3BSD.
264 UE End a uniform resource identifier block started with UR. This is a
266 non-standard GNU extension.
267 UR Begin a uniform resource identifier block. This is a non-standard
269 GNU extension. It has the following syntax:
270 .UR uri
272 link description to be shown
273 .UE
274 YS End a synopsis block started with SY. This is a non-standard GNU
276 extension.
277 in Indent relative to the current indentation:
279 .in [width]
281 If width is signed, the new offset is relative. Otherwise, it is
283 absolute. This value is reset upon the next paragraph, section, or
284 sub-section.
285
287 The man macros are classified by scope: line scope or block scope. Line
288 macros are only scoped to the current line (and, in some situations, the
289 subsequent line). Block macros are scoped to the current line and subse‐
290 quent lines until closed by another block macro.
291 Line Macros
293 Line macros are generally scoped to the current line, with the body con‐
294 sisting of zero or more arguments. If a macro is scoped to the next line
295 and the line arguments are empty, the next line, which must be text, is
296 used instead. Thus:
297 .I
299 foo
300 is equivalent to ‘.I foo’. If next-line macros are invoked consecu‐
302 tively, only the last is used. If a next-line macro is followed by a
303 non-next-line macro, an error is raised.
304 The syntax is as follows:
306 .YO [body...]
308 [body...]
309 Macro Arguments Scope Notes
311 AT <=1 current
312 B n next-line
313 BI n current
314 BR n current
315 DT 0 current
316 EE 0 current Version 9 AT&T UNIX
317 EX 0 current Version 9 AT&T UNIX
318 I n next-line
319 IB n current
320 IR n current
321 OP >=1 current DWB
322 PD 1 current
323 RB n current
324 RI n current
325 SB n next-line
326 SM n next-line
327 TH >1, <6 current
328 UC <=1 current
329 in 1 current roff(7)
330 Block Macros
332 Block macros comprise a head and body. As with in-line macros, the head
333 is scoped to the current line and, in one circumstance, the next line
334 (the next-line stipulations as in Line Macros apply here as well).
335 The syntax is as follows:
337 .YO [head...]
339 [head...]
340 [body...]
341 The closure of body scope may be to the section, where a macro is closed
343 by SH; sub-section, closed by a section or SS; or paragraph, closed by a
344 section, sub-section, HP, IP, LP, P, PP, RE, SY, or TP. No closure
345 refers to an explicit block closing macro.
346 As a rule, block macros may not be nested; thus, calling a block macro
348 while another block macro scope is open, and the open scope is not im‐
349 plicitly closed, is syntactically incorrect.
350 Macro Arguments Head Scope Body Scope Notes
352 HP <2 current paragraph
353 IP <3 current paragraph
354 LP 0 current paragraph
355 ME 0 none none GNU
356 MT 1 current to ME GNU
357 P 0 current paragraph
358 PP 0 current paragraph
359 RE <=1 current none
360 RS 1 current to RE
361 SH >0 next-line section
362 SS >0 next-line sub-section
363 SY 1 current to YS GNU
364 TP n next-line paragraph
365 TQ n next-line paragraph GNU
366 UE 0 current none GNU
367 UR 1 current part GNU
368 YS 0 none none GNU
369 If a block macro is next-line scoped, it may only be followed by in-line
371 macros for decorating text.
372 Font handling
374 In man documents, both Physical markup macros and roff(7) ‘\f’ font es‐
375 cape sequences can be used to choose fonts. In text lines, the effect of
376 manual font selection by escape sequences only lasts until the next macro
377 invocation; in macro lines, it only lasts until the end of the macro
378 scope. Note that macros like BR open and close a font scope for each ar‐
379 gument.
380
382 man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)
383
385 The man language first appeared as a macro package for the roff typeset‐
386 ting system in Version 7 AT&T UNIX.
387 The stand-alone implementation that is part of the mandoc(1) utility
389 first appeared in OpenBSD 4.6.
390
392 Douglas McIlroy <m.douglas.mcilroy@dartmouth.edu> designed and imple‐
393 mented the original version of these macros, wrote the original version
394 of this manual page, and was the first to use them when he edited volume
395 1 of the Version 7 AT&T UNIX manual pages.
396 James Clark later rewrote the macros for groff. Eric S. Raymond
398 <esr@thyrsus.com> and Werner Lemberg <wl@gnu.org> added the extended man
399 macros to groff in 2007.
400 The mandoc(1) program and this man reference were written by Kristaps
402 Dzonsons <kristaps@bsd.lv>.
403BSD August 5, 2021 BSD