1MAN(7)               BSD Miscellaneous Information Manual               MAN(7)
2

NAME

4     man — legacy formatting language for manual pages
5

DESCRIPTION

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
12     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
17     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
21           .SH Macro lines change control state.
22           Text lines are interpreted within the current state.
23
24     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
29     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
32           .TH PROGNAME 1 1979-01-10
33           .SH NAME
34           \fBprogname\fR \(en one line about what it does
35

MACRO OVERVIEW

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
41   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
46   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
56   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

MACRO REFERENCE

69     This section is a canonical reference to all macros, arranged alphabeti‐
70     cally.  For the scoping of individual macros, see MACRO SYNTAX.
71
72     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
76     B    Text is rendered in bold face.
77
78     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
83          Example:
84
85                .BI bold italic bold italic
86
87     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
91     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
95     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
99     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
103     HP   Begin a paragraph whose initial output line is left-justified, but
104          subsequent output lines are indented, with the following syntax:
105
106                .HP [width]
107
108          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
112          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
116     I    Text is rendered in italics.
117
118     IB   Text is rendered alternately in italics and bold face.  Whitespace
119          between arguments is omitted in output.  See also BI.
120
121     IP   Begin an indented paragraph with the following syntax:
122
123                .IP [head [width]]
124
125          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
129          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
132     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
136     LP   A synonym for PP.
137
138     ME   End a mailto block started with MT.  This is a non-standard GNU ex‐
139          tension.
140
141     MT   Begin a mailto block.  This is a non-standard GNU extension.  It has
142          the following syntax:
143
144                .MT address
145                link description to be shown
146                .ME
147
148     OP   Optional command-line argument.  This is a non-standard DWB exten‐
149          sion.  It has the following syntax:
150
151                .OP key [value]
152
153          The key is usually a command-line flag and value its argument.
154
155     P    This synonym for PP is an AT&T System III UNIX extension later
156          adopted by 4.3BSD.
157
158     PD   Specify the vertical space to be inserted before each new paragraph.
159          The syntax is as follows:
160
161                .PD [height]
162
163          The height argument is a roff(7) scaling width.  It defaults to 1v.
164          If the unit is omitted, v is assumed.
165
166          This macro affects the spacing before any subsequent instances of
167          HP, IP, LP, P, PP, SH, SS, SY, and TP.
168
169     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
173     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
177     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
180          The syntax is as follows:
181
182                .RE [level]
183
184          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
188     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
192     RS   Temporarily reset the default left margin.  This has the following
193          syntax:
194
195                .RS [width]
196
197          The width argument is a roff(7) scaling width.  If not specified,
198          the saved or default width is used.
199
200          See also RE.
201
202     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
206     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
210     SM   Text is rendered in small size (one point smaller than the default
211          font).
212
213     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
217     SY   Begin a synopsis block with the following syntax:
218
219                .SY command
220                arguments
221                .YS
222
223          This is a non-standard GNU extension and very rarely used even in
224          GNU manual pages.  Formatting is similar to IP.
225
226     TH   Set the name of the manual page for use in the page header and
227          footer with the following syntax:
228
229                .TH name section date [source [volume]]
230
231          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
240          Examples:
241
242                .TH CVS 5 1992-02-12 GNU
243
244     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
249                .TP [width]
250                head \" one line
251                body
252
253          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
257     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
261     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
265     UE   End a uniform resource identifier block started with UR.  This is a
266          non-standard GNU extension.
267
268     UR   Begin a uniform resource identifier block.  This is a non-standard
269          GNU extension.  It has the following syntax:
270
271                .UR uri
272                link description to be shown
273                .UE
274
275     YS   End a synopsis block started with SY.  This is a non-standard GNU
276          extension.
277
278     in   Indent relative to the current indentation:
279
280                .in [width]
281
282          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

MACRO SYNTAX

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
292   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
298           .I
299           foo
300
301     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
305     The syntax is as follows:
306
307           .YO [body...]
308           [body...]
309
310           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
331   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
336     The syntax is as follows:
337
338           .YO [head...]
339           [head...]
340           [body...]
341
342     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
347     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
351           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
370     If a block macro is next-line scoped, it may only be followed by in-line
371     macros for decorating text.
372
373   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

SEE ALSO

382     man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)
383

HISTORY

385     The man language first appeared as a macro package for the roff typeset‐
386     ting system in Version 7 AT&T UNIX.
387
388     The stand-alone implementation that is part of the mandoc(1) utility
389     first appeared in OpenBSD 4.6.
390

AUTHORS

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
397     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
401     The mandoc(1) program and this man reference were written by Kristaps
402     Dzonsons <kristaps@bsd.lv>.
403
404BSD                             August 5, 2021                             BSD
Impressum