1
3 groff_mdoc — compose BSD-style manual (man) pages with GNU roff
4
6 groff -mdoc file ...
7
9 The GNU implementation of the mdoc macro package is part of the groff(1)
10 document formatting system. mdoc is a structurally- and semantically-
11 oriented package for writing UNIX manual pages with troff(1). Its prede‐
12 cessor, the man(7) package, primarily addressed page layout and presenta‐
13 tional concerns, leaving the selection of fonts and other typesetting de‐
14 tails to the individual author. This discretion has led to divergent
15 styling practices among authors using it.
16
17 mdoc organizes its macros into domains. The page structure domain lays
18 out the page and comprises titles, section headings, displays, and lists.
19 The general text domain supplies macros to quote or style text, or to in‐
20 terpolate common noun phrases. The manual domain offers semantic macros
21 corresponding to the terminology used by practitioners in discussion of
22 UNIX commands, routines, and files. Manual domain macros distinguish
23 command-line arguments and options, function names, function parameters,
24 pathnames, variables, cross references to other manual pages, and so on.
25 These terms are meaningful both to the author and the readers of a manual
26 page. It is hoped that the resulting increased consistency of the man
27 page corpus will enable easier translation to future documentation tools.
28
29 Throughout UNIX documentation, a manual entry is referred to simply as a
30 “man page”, regardless of its length, without gendered implication, and
31 irrespective of the macro package selected for its composition.
32
34 The mdoc package attempts to simplify man page authorship and maintenance
35 without requiring mastery of the roff language. This document presents
36 only essential facts about roff. For further background, including a dis‐
37 cussion of basic typographical concepts like “breaking”, “filling”, and
38 “adjustment”, see roff(7). Specialized units of measurement also arise,
39 namely ens, vees, inches, and points, abbreviated “n”, “v”, “i”, and “p”,
40 respectively; see section Measurements of groff(7).
41
42 For brief examples, we employ an arrow notation illustrating a transfor‐
43 mation of input on the left to rendered output on the right. Consider
44 the .Dq macro, which double-quotes its arguments.
45 .Dq man page → “man page”
46
47 Usage
48 An mdoc macro is called by placing the roff control character, ‘.’ (dot)
49 at the beginning of a line followed by its name. In this document, we
50 often discuss a macro name with this leading dot to identify it clearly,
51 but the dot is not part of its name. Space or tab characters can sepa‐
52 rate the dot from the macro name. Arguments may follow, separated from
53 the macro name and each other by spaces, but not tabs. The dot at the
54 beginning of the line prepares the formatter to expect a macro name. A
55 dot followed immediately by a newline is ignored; this is called the
56 empty request. To begin an input line with a dot (or a neutral apostro‐
57 phe ‘'’) in some context other than a macro call, precede it with the
58 ‘\&’ escape sequence; this is a dummy character, not formatted for out‐
59 put. The backslash is the roff escape character; it can appear anywhere
60 and it always followed by at least one more character. If followed by a
61 newline, the backslash escapes the input line break; you can thus keep
62 input lines to a reasonable length without affecting their interpreta‐
63 tion.
64
65 Macros in GNU troff accept an unlimited number of arguments, in contrast
66 to other troffs that often can't handle more than nine. In limited
67 cases, arguments may be continued or extended on the next input line
68 without resort to the ‘\newline’ escape sequence; see subsection Extended
69 arguments below. Neutral double quotes " can be used to group multiple
70 words into an argument; see subsection Passing space characters in an
71 argument below.
72
73 Most of mdoc's general text and manual domain macros parse their argument
74 lists for callable macro names. This means that an argument in the list
75 matching a general text or manual domain macro name (and defined to be
76 callable) will be called with the remaining arguments when it is encoun‐
77 tered. In such cases, the argument, although the name of a macro, is not
78 preceded by a dot. Macro calls can thus be nested. This approach to
79 macro argument processing is a unique characteristic of the mdoc package,
80 not a general feature of roff syntax.
81
82 For example, the option macro, .Op, may call the flag and argument
83 macros, .Fl and .Ar, to specify an optional flag with an argument.
84 .Op Fl s Ar bytes → [-s bytes]
85 To prevent a word from being interpreted as a macro name, precede it with
86 the dummy character.
87 .Op \&Fl s \&Ar bytes → [Fl s Ar bytes]
88
89 In this document, macros whose argument lists are parsed for callable ar‐
90 guments are referred to as parsed, and those that may be called from an
91 argument list are referred to as callable. This usage is a technical
92 faux pas, since all mdoc macros are in fact interpreted (unless prevented
93 with ‘\&’), but as it is cumbersome to constantly refer to macros as
94 “being able to call other macros”, we employ the term “parsed” instead.
95 Except where explicitly stated, all mdoc macros are parsed and callable.
96
97 In the following, we term an mdoc macro that starts a line (with a lead‐
98 ing dot) a command if a distinction from those appearing as arguments of
99 other macros is necessary.
100
101 Passing space characters in an argument
102 Sometimes it is desirable to give a macro an argument containing one or
103 more space characters, for instance to specify a particular arrangement
104 of arguments demanded by the macro. Additionally, quoting multi-word ar‐
105 guments that are to be treated the same makes mdoc work faster; macros
106 that parse arguments do so once (at most) for each. For example, the
107 function command .Fn expects its first argument to be the name of a func‐
108 tion and any remaining arguments to be function parameters. Because C
109 language standards mandate the inclusion of types and identifiers in the
110 parameter lists of function definitions, each ‘Fn’ parameter after the
111 first will be at least two words in length, as in “int foo”.
112
113 There are a few ways to embed a space in a macro argument. One is to use
114 the unadjustable space escape sequence \space. The formatter treats this
115 escape sequence as if it were any other printable character, and will not
116 break a line there as it would a word space when the output line is full.
117 This method is useful for macro arguments that are not expected to strad‐
118 dle an output line boundary, but has a drawback: this space does not ad‐
119 just as others do when the output line is formatted. An alternative is
120 to use the unbreakable space escape sequence, ‘\~’, which cannot break
121 but does adjust. This groff extension is widely but not perfectly porta‐
122 ble. Another method is to enclose the string in double quotes.
123 .Fn fetch char\ *str → fetch(char *str)
124 .Fn fetch char\~*str → fetch(char *str)
125 .Fn fetch "char *str" → fetch(char *str)
126 If the ‘\’ before the space in the first example or the double quotes in
127 the third example were omitted, ‘.Fn’ would see three arguments, and the
128 result would contain an undesired comma.
129 .Fn fetch char *str → fetch(char, *str)
130
131 Trailing space characters
132 It is wise to remove trailing spaces from the ends of input lines.
133 Should the need arise to put a formattable space at the end of a line, do
134 so with the unadjustable or unbreakable space escape sequences.
135
136 Formatting the backslash glyph
137 When you need the roff escape character ‘\’ to appear in the output, use
138 ‘\e’ or ‘\(rs’ instead. Technically, ‘\e’ formats the current escape
139 character; it works reliably as long as no roff request is used to change
140 it, which should never happen in man pages. ‘\(rs’ is a groff special
141 character escape sequence that explicitly formats the “reverse solidus”
142 (backslash) glyph.
143
144 Other possible pitfalls
145 groff mdoc warns when an empty input line is found outside of a display,
146 a topic presented in subsection Examples and displays below. Use empty
147 requests to space the source document for maintenance.
148
149 Leading spaces cause a break and are formatted. Avoid this behaviour if
150 possible. Similarly, do not put more than one space between words in an
151 ordinary text line; they are not “normalized” to a single space as other
152 text formatters might do.
153
154 Don't try to use the neutral double quote character ‘"’ to represent it‐
155 self in an argument. Use the special character escape sequence ‘\(dq’ to
156 format it. Further, this glyph should not be used for conventional quo‐
157 tation; mdoc offers several quotation macros. See subsection Enclosure
158 and quoting macros below.
159
160 The formatter attempts to detect the ends of sentences and by default
161 puts the equivalent of two spaces between sentences on the same output
162 line; see roff(7). To defeat this detection in a parsed list of macro
163 arguments, put ‘\&’ before the punctuation mark. Thus,
164 The
165 .Ql .
166 character.
167 .Pp
168 The
169 .Ql \&.
170 character.
171 .Pp
172 .No test .
173 test
174 .Pp
175 .No test.
176 test
177 gives
178 The ‘’. character
179
180 The ‘.’ character.
181
182 test. test
183
184 test. test
185 as output. As can be seen in the first and third output lines, mdoc han‐
186 dles punctuation characters specially in macro arguments. This will be
187 explained in section General syntax below.
188
189 A comment in the source file of a man page can begin with ‘.\"’ at the
190 start of an input line, ‘\"’ after other input, or ‘\#’ anywhere (the
191 last is a groff extension); the remainder of any such line is ignored.
192
194 Use mdoc to construct a man page from the following template.
195
196 .\" The following three macro calls are required.
197 .Dd date
198 .Dt topic [section-identifier [section-keyword-or-title]]
199 .Os [package-or-operating system [version-or-release]]
200 .Sh Name
201 .Nm topic
202 .Nd summary-description
203 .\" The next heading is used in sections 2 and 3.
204 .\" .Sh Library
205 .\" The next heading is used in sections 1-4, 6, 8, and 9.
206 .Sh Synopsis
207 .Sh Description
208 .\" Uncomment and populate the following sections as needed.
209 .\" .Sh "Implementation notes"
210 .\" The next heading is used in sections 2, 3, and 9.
211 .\" .Sh "Return values"
212 .\" The next heading is used in sections 1, 3, 6, and 8.
213 .\" .Sh Environment
214 .\" .Sh Files
215 .\" The next heading is used in sections 1, 6, and 8.
216 .\" .Sh "Exit status"
217 .\" .Sh Examples
218 .\" The next heading is used in sections 1, 4, 6, 8, and 9.
219 .\" .Sh Diagnostics
220 .\" .Sh Compatibility
221 .\" The next heading is used in sections 2, 3, 4, and 9.
222 .\" .Sh Errors
223 .\" .Sh "See also"
224 .\" .Sh Standards
225 .\" .Sh History
226 .\" .Sh Authors
227 .\" .Sh Caveats
228 .\" .Sh Bugs
229
230 The first items in the template are the commands .Dd, .Dt, and .Os. They
231 identify the page and are discussed below in section Title macros.
232
233 The remaining items in the template are section headings (.Sh); of which
234 Name and Description are mandatory. These headings are discussed in sec‐
235 tion Page structure domain, which follows section Manual domain. Famil‐
236 iarize yourself with manual domain macros first; we use them to illus‐
237 trate the use of page structure domain macros.
238
240 In the descriptions of macros below, square brackets surround optional
241 arguments. An ellipsis (‘...’) represents repetition of the preceding
242 argument zero or more times. Alternative values of a parameter are sepa‐
243 rated with ‘|’. If a mandatory parameter can take one of several alter‐
244 native values, use braces to enclose the set, with spaces and ‘|’ sepa‐
245 rating the items.
246 ztar {c | x} [-w [-y | -z]] [-f archive] member ...
247 An alternative to using braces is to separately synopsize distinct opera‐
248 tion modes, particularly if the list of valid optional arguments is de‐
249 pendent on the user's choice of a mandatory parameter.
250 ztar c [-w [-y | -z]] [-f archive] member ...
251 ztar x [-w [-y | -z]] [-f archive] member ...
252
253 Most macros affect subsequent arguments until another macro or a newline
254 is encountered. For example, ‘.Li ls Bq Ar file’ doesn't produce ‘ls
255 [file]’, but ‘ls [file]’. Consequently, a warning message is emitted for
256 many commands if the first argument is itself a macro, since it cancels
257 the effect of the preceding one. On rare occasions, you might want to
258 format a word along with surrounding brackets as a literal.
259 .Li "ls [file]" → ls [file] # list any files named e, f, i, or l
260
261 Many macros possess an implicit width, used when they are contained in
262 lists and displays. If you avoid relying on these default measurements,
263 you escape potential conflicts with site-local modifications of the mdoc
264 package. Explicit -width and -offset arguments to the .Bl and .Bd macros
265 are preferable.
266
268 We present the mandatory title macros first due to their importance even
269 though they formally belong to the page structure domain macros. They
270 designate the topic, date of last revision, and the operating system or
271 software project associated with the page. Call each once at the begin‐
272 ning of the document. They populate the page headers and footers, which
273 are in roff parlance termed “titles”.
274
275 .Dd date
276 This first macro of any mdoc manual records the last modification
277 date of the document source. Arguments are concatenated and sep‐
278 arated with space characters.
279
280 Historically, date was written in U.S. traditional format, “Month
281 day , year” where Month is the full month name in English, day an
282 integer without a leading zero, and year the four-digit year.
283 This localism is not enforced, however. You may prefer ISO 8601
284 format, YYYY-MM-DD. A date of the form ‘$Mdocdate: Month day year
285 $’ is also recognized. It is used in OpenBSD manuals to automat‐
286 ically insert the current date when committing.
287
288 This macro is neither callable nor parsed.
289
290 .Dt topic [section-identifier [section-keyword-or-title]]
291 topic is the subject of the man page. A section-identifier that
292 begins with an integer in the range 1–9 or is one of the words
293 ‘unass’, ‘draft’, or ‘paper’ selects a predefined section title.
294 This use of “section” has nothing to do with the section headings
295 otherwise discussed in this page; it arises from the organiza‐
296 tional scheme of printed and bound Unix manuals.
297
298 In this implementation, the following titles are defined for in‐
299 tegral section numbers.
300
301 1 General Commands Manual
302 2 System Calls Manual
303 3 Library Functions Manual
304 4 Kernel Interfaces Manual
305 5 File Formats Manual
306 6 Games Manual
307 7 Miscellaneous Information Manual
308 8 System Manager's Manual
309 9 Kernel Developer's Manual
310
311 A section title may be arbitrary or one of the following abbrevi‐
312 ations.
313
314 USD User's Supplementary Documents
315 PS1 Programmer's Supplementary Documents
316 AMD Ancestral Manual Documents
317 SMM System Manager's Manual
318 URM User's Reference Manual
319 PRM Programmer's Manual
320 KM Kernel Manual
321 IND Manual Master Index
322 LOCAL Local Manual
323 CON Contributed Software Manual
324
325 For compatibility, ‘MMI’ can be used for ‘IND’, and ‘LOC’ for
326 ‘LOCAL’. Values from the previous table will specify a new sec‐
327 tion title. If section-keyword-or-title designates a computer
328 architecture recognized by groff mdoc, its value is prepended to
329 the default section title as specified by the second parameter.
330 By default, the following architecture keywords are defined.
331
332 acorn26, acorn32, algor, alpha, amd64, amiga, amigappc, arc,
333 arm, arm26, arm32, armish, atari, aviion, beagle, bebox,
334 cats, cesfic, cobalt, dreamcast, emips, evbarm, evbmips,
335 evbppc, evbsh3, ews4800mips, hp300, hp700, hpcarm, hpcmips,
336 hpcsh, hppa, hppa64, i386, ia64, ibmnws, iyonix, landisk,
337 loongson, luna68k, luna88k, m68k, mac68k, macppc, mips,
338 mips64, mipsco, mmeye, mvme68k, mvme88k, mvmeppc, netwinder,
339 news68k, newsmips, next68k, ofppc, palm, pc532, playstation2,
340 pmax, pmppc, powerpc, prep, rs6000, sandpoint, sbmips, sgi,
341 sgimips, sh3, shark, socppc, solbourne, sparc, sparc64, sun2,
342 sun3, tahoe, vax, x68k, x86_64, xen, zaurus
343
344 If a section title is not determined after the above matches have
345 been attempted, section-keyword-or-title is used.
346
347 The effects of varying ‘.Dt’ arguments on the page header content
348 are shown below. Observe how ‘\&’ prevents the numeral 2 from
349 being used to look up a predefined section title.
350
351 .Dt foo 2 → foo(2) System Calls Manual foo(2)
352 .Dt foo 2 m68k → foo(2) m68k System Calls Manual foo(2)
353 .Dt foo 2 baz → foo(2) System Calls Manual foo(2)
354 .Dt foo \&2 baz → foo(2) baz foo(2)
355 .Dt foo "" baz → foo baz foo
356 .Dt foo M Z80 → foo(M) Z80 foo(M)
357
358 roff strings define section titles and architecture identifiers.
359 Site-specific additions might be found in the file mdoc.local;
360 see section Files below.
361
362 This macro is neither callable nor parsed.
363
364 .Os [operating-system-or-package-name [version-or-release]]
365 This macro associates the document with a software distribution.
366 When composing a man page to be included in the base installation
367 of an operating system, do not provide an argument; mdoc will
368 supply it. In this implementation, that default is “BSD”. It
369 may be overridden in the site configuration file, mdoc.local; see
370 section Files below. A portable software package maintaining its
371 own man pages can supply its name and version number or release
372 identifier as optional arguments. A version-or-release argument
373 should use the standard nomenclature for the software specified.
374 In the following table, recognized version-or-release arguments
375 for some predefined operating systems are listed. As with .Dt,
376 site additions might be defined in mdoc.local.
377
378 ATT 7th, 7, III, 3, V, V.2, V.3, V.4
379
380 BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
381
382 NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
383 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.4.1,
384 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.6,
385 1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3,
386 2.1, 3.0, 3.0.1, 3.0.2, 3.0.3, 3.1, 3.1.1, 4.0,
387 4.0.1, 5.0, 5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3,
388 5.1.4, 5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2,
389 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.1, 6.1.1, 6.1.2,
390 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1, 7.0.2, 7.1,
391 7.1.1, 7.1.2, 7.2, 8.0, 8.1
392
393 FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1,
394 2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5,
395 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2, 3.3,
396 3.4, 3.5, 4.0, 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5,
397 4.6, 4.6.2, 4.7, 4.8, 4.9, 4.10, 4.11, 5.0, 5.1,
398 5.2, 5.2.1, 5.3, 5.4, 5.5, 6.0, 6.1, 6.2, 6.3,
399 6.4, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2,
400 8.3, 8.4, 9.0, 9.1, 9.2, 9.3, 10.0, 10.1, 10.2,
401 10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0, 12.1
402
403 OpenBSD 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8,
404 2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7,
405 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6,
406 4.7, 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4, 5.5,
407 5.6, 5.7, 5.8, 5.9, 6.0, 6.1, 6.2, 6.3, 6.4,
408 6.5, 6.6
409
410 DragonFly 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8,
411 1.8.1, 1.9, 1.10, 1.11, 1.12, 1.12.2, 1.13, 2.0,
412 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9,
413 2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0,
414 3.0.1, 3.0.2, 3.1, 3.2, 3.2.1, 3.2.2, 3.3, 3.4,
415 3.4.1, 3.4.2, 3.4.3, 3.5, 3.6, 3.6.1, 3.6.2,
416 3.7, 3.8, 3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2,
417 4.0.3, 4.0.4, 4.0.5, 4.0.6, 4.1, 4.2, 4.2.1,
418 4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1, 4.4.2,
419 4.4.3, 4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.8, 4.8.1,
420 4.9, 5.0, 5.0.1, 5.0.2, 5.1, 5.2, 5.2.1, 5.2.2,
421 5.3, 5.4, 5.4.1, 5.4.2, 5.4.3, 5.5, 5.6, 5.6.1,
422 5.6.2
423
424 Darwin 8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0,
425 8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0, 9.0.0,
426 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0, 9.7.0,
427 9.8.0, 10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0,
428 10.5.0, 10.6.0, 10.7.0, 10.8.0, 11.0.0, 11.1.0,
429 11.2.0, 11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0,
430 12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0,
431 14.0.0, 14.1.0, 14.2.0, 14.3.0, 14.4.0, 14.5.0,
432 15.0.0, 15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0,
433 15.6.0, 16.0.0, 16.1.0, 16.2.0, 16.3.0, 16.4.0,
434 16.5.0, 16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0,
435 17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0,
436 18.2.0, 18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0,
437 19.0.0, 19.1.0, 19.2.0
438
439 Historically, the first argument used with .Dt was BSD or ATT.
440 An unrecognized version argument after ATT is replaced with
441 “UNIX”; for other predefined abbreviations, it is ignored and a
442 warning diagnostic emitted. Otherwise, unrecognized arguments
443 are displayed verbatim in the page footer. For instance, this
444 page uses “.Os groff 1.23.0” whereas a locally produced page
445 might employ “.Os "UXYZ CS Department"”, omitting versioning.
446
447 This macro is neither callable nor parsed.
448
450 What's in a Name...
451 The manual domain macro names are derived from the day to day informal
452 language used to describe commands, subroutines and related files.
453 Slightly different variations of this language are used to describe the
454 three different aspects of writing a man page. First, there is the de‐
455 scription of mdoc macro command usage. Second is the description of a
456 UNIX command with mdoc macros, and third, the description of a command to
457 a user in the verbal sense; that is, discussion of a command in the text
458 of a man page.
459
460 In the first case, troff macros are themselves a type of command; the
461 general syntax for a troff command is:
462
463 .Xx argument1 argument2 ...
464
465 ‘.Xx’ is a macro command, and anything following it are arguments to be
466 processed. In the second case, the description of a UNIX command using
467 the manual domain macros is a bit more involved; a typical Synopsis com‐
468 mand line might be displayed as:
469
470 filter [-flag] ⟨infile⟩ ⟨outfile⟩
471
472 Here, filter is the command name and the bracketed string -flag is a flag
473 argument designated as optional by the option brackets. In mdoc terms,
474 ⟨infile⟩ and ⟨outfile⟩ are called meta arguments; in this example, the
475 user has to replace the meta expressions given in angle brackets with
476 real file names. Note that in this document meta arguments are used to
477 describe mdoc commands; in most man pages, meta variables are not specif‐
478 ically written with angle brackets. The macros that formatted the above
479 example:
480
481 .Nm filter
482 .Op Fl flag
483 .Ao Ar infile Ac Ao Ar outfile Ac
484
485 In the third case, discussion of commands and command syntax includes
486 both examples above, but may add more detail. The arguments ⟨infile⟩ and
487 ⟨outfile⟩ from the example above might be referred to as operands or file
488 arguments. Some command-line argument lists are quite long:
489
490 make [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I
491 directory] [-j max_jobs] [variable=value] [target ...]
492
493 Here one might talk about the command make and qualify the argument,
494 makefile, as an argument to the flag, -f, or discuss the optional file
495 operand target. In the verbal context, such detail can prevent confu‐
496 sion, however the mdoc package does not have a macro for an argument to a
497 flag. Instead the ‘Ar’ argument macro is used for an operand or file ar‐
498 gument like target as well as an argument to a flag like variable. The
499 make command line was produced from:
500
501 .Nm make
502 .Op Fl eiknqrstv
503 .Op Fl D Ar variable
504 .Op Fl d Ar flags
505 .Op Fl f Ar makefile
506 .Op Fl I Ar directory
507 .Op Fl j Ar max_jobs
508 .Op Ar variable Ns = Ns Ar value
509 .Bk
510 .Op Ar target ...
511 .Ek
512
513 The ‘.Bk’ and ‘.Ek’ macros are explained in Keeps.
514
515 General Syntax
516 The manual domain and general text domain macros share a similar syntax
517 with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’
518 differ only when called without arguments; and ‘.Fn’ and ‘.Xr’ impose an
519 order on their argument lists. All manual domain macros are capable of
520 recognizing and properly handling punctuation, provided each punctuation
521 character is separated by a leading space. If a command is given:
522
523 .Ar sptr, ptr),
524
525 The result is:
526
527 sptr, ptr),
528
529 The punctuation is not recognized and all is output in the font used by
530 ‘.Ar’. If the punctuation is separated by a leading white space:
531
532 .Ar sptr , ptr ) ,
533
534 The result is:
535
536 sptr, ptr),
537
538 The punctuation is now recognized and output in the default font distin‐
539 guishing it from the argument strings. To remove the special meaning
540 from a punctuation character, escape it with ‘\&’.
541
542 The following punctuation characters are recognized by mdoc:
543
544 . , : ; (
545 ) [ ] ? !
546
547 troff is limited as a macro language, and has difficulty when presented
548 with a string containing certain mathematical, logical, or quotation
549 character sequences:
550
551 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
552
553 The problem is that troff may assume it is supposed to actually perform
554 the operation or evaluation suggested by the characters. To prevent the
555 accidental evaluation of these characters, escape them with ‘\&’. Typi‐
556 cal syntax is shown in the first manual domain macro displayed below,
557 ‘.Ad’.
558
560 Addresses
561 The address macro identifies an address construct.
562
563 Usage: .Ad ⟨address⟩ ...
564
565 .Ad addr1 addr1
566 .Ad addr1 . addr1.
567 .Ad addr1 , file2 addr1, file2
568 .Ad f1 , f2 , f3 : f1, f2, f3:
569 .Ad addr ) ) , addr)),
570
571 The default width is 12n.
572
573 Author Name
574 The ‘.An’ macro is used to specify the name of the author of the item be‐
575 ing documented, or the name of the author of the actual manual page.
576
577 Usage: .An ⟨author name⟩ ...
578
579 .An "Joe Author" Joe Author
580
581 .An "Joe Author" , Joe Author,
582
583 .An "Joe Author" Aq nobody@FreeBSD.org
584 Joe Author <nobody@FreeBSD.org>
585
586 .An "Joe Author" ) ) , Joe Author)),
587
588 The default width is 12n.
589
590 In a section titled “Authors”, ‘An’ causes a break, allowing each new
591 name to appear on its own line. If this is not desirable,
592
593 .An -nosplit
594
595 call will turn this off. To turn splitting back on, write
596
597 .An -split
598
599 Arguments
600 The .Ar argument macro may be used whenever an argument is referenced.
601 If called without arguments, ‘file ...’ is output. This places the el‐
602 lipsis in italics, which is ugly and incorrect, and will be noticed on
603 terminals that underline text instead of using an oblique typeface. We
604 recommend using ‘.Ar file No ...’ instead.
605
606 Usage: .Ar [⟨argument⟩] ...
607
608 .Ar file ...
609 .Ar file No ... file ...
610 .Ar file1 file1
611 .Ar file1 . file1.
612 .Ar file1 file2 file1 file2
613 .Ar f1 f2 f3 : f1 f2 f3:
614 .Ar file ) ) , file)),
615
616 The default width is 12n.
617
618 Configuration Declaration (Section Four Only)
619 The ‘.Cd’ macro is used to demonstrate a config(8) declaration for a de‐
620 vice interface in a section four manual.
621
622 Usage: .Cd ⟨argument⟩ ...
623
624 .Cd "device le0 at scode?" device le0 at scode?
625
626 In a section titled “Synopsis”, ‘Cd’ causes a break before and after its
627 arguments.
628
629 The default width is 12n.
630
631 Command Modifiers
632 The command modifier is identical to the ‘.Fl’ (flag) command with the
633 exception that the ‘.Cm’ macro does not assert a dash in front of every
634 argument. Traditionally flags are marked by the preceding dash, however,
635 some commands or subsets of commands do not use them. Command modifiers
636 may also be specified in conjunction with interactive commands such as
637 editor commands. See Flags.
638
639 The default width is 10n.
640
641 Defined Variables
642 A variable (or constant) that is defined in an include file is specified
643 by the macro ‘.Dv’.
644
645 Usage: .Dv ⟨defined-variable⟩ ...
646
647 .Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
648 .Dv TIOCGPGRP ) TIOCGPGRP)
649
650 The default width is 12n.
651
652 Errnos
653 The ‘.Er’ errno macro specifies the error return value for section 2, 3,
654 and 9 library routines. The second example below shows ‘.Er’ used with
655 the ‘.Bq’ general text domain macro, as it would be used in a section two
656 manual page.
657
658 Usage: .Er ⟨errno type⟩ ...
659
660 .Er ENOENT ENOENT
661 .Er ENOENT ) ; ENOENT);
662 .Bq Er ENOTDIR [ENOTDIR]
663
664 The default width is 17n.
665
666 Environment Variables
667 The ‘.Ev’ macro specifies an environment variable.
668
669 Usage: .Ev ⟨argument⟩ ...
670
671 .Ev DISPLAY DISPLAY
672 .Ev PATH . PATH.
673 .Ev PRINTER ) ) , PRINTER)),
674
675 The default width is 15n.
676
677 Flags
678 The ‘.Fl’ macro handles command-line flags. It prepends a dash, ‘-’, to
679 the flag. For interactive command flags that are not prepended with a
680 dash, the ‘.Cm’ (command modifier) macro is identical, but without the
681 dash.
682
683 Usage: .Fl ⟨argument⟩ ...
684
685 .Fl -
686 .Fl cfv -cfv
687 .Fl cfv . -cfv.
688 .Cm cfv . cfv.
689 .Fl s v t -s -v -t
690 .Fl - , --,
691 .Fl xyz ) , -xyz),
692 .Fl | - |
693
694 The ‘.Fl’ macro without any arguments results in a dash representing
695 stdin/stdout. Note that giving ‘.Fl’ a single dash will result in two
696 dashes.
697
698 The default width is 12n.
699
700 Function Declarations
701 The ‘.Fd’ macro is used in the Synopsis section with section two or three
702 functions. It is neither callable nor parsed.
703
704 Usage: .Fd ⟨argument⟩ ...
705
706 .Fd "#include <sys/types.h>" #include <sys/types.h>
707
708 In a section titled “Synopsis”, ‘Fd’ causes a break if a function has al‐
709 ready been presented and a break has not occurred, leaving vertical space
710 between one function declaration and the next.
711
712 In a section titled “Synopsis”, the ‘In’ macro represents the #include
713 statement, and is the short form of the above example. It specifies the
714 C header file as being included in a C program. It also causes a break.
715
716 While not in the “Synopsis” section, it represents the header file en‐
717 closed in angle brackets.
718
719 Usage: .In ⟨header file⟩
720
721 .In stdio.h <stdio.h>
722 .In stdio.h <stdio.h>
723
724 Function Types
725 This macro is intended for the “Synopsis” section. It may be used any‐
726 where else in the man page without problems, but its main purpose is to
727 present the function type (in BSD kernel normal form) for the “Synopsis”
728 of sections two and three. (It causes a break, allowing the function
729 name to appear on the next line.)
730
731 Usage: .Ft ⟨type⟩ ...
732
733 .Ft struct stat struct stat
734
735 Functions (Library Routines)
736 The ‘.Fn’ macro is modeled on ANSI C conventions.
737
738 Usage: .Fn ⟨function⟩ [⟨parameter⟩] ...
739
740 .Fn getchar getchar()
741 .Fn strlen ) , strlen()),
742 .Fn align "char *ptr" , align(char *ptr),
743
744 Note that any call to another macro signals the end of the ‘.Fn’ call (it
745 will insert a closing parenthesis at that point).
746
747 For functions with many parameters (which is rare), the macros ‘.Fo’
748 (function open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (func‐
749 tion argument).
750
751 Example:
752
753 .Ft int
754 .Fo res_mkquery
755 .Fa "int op"
756 .Fa "char *dname"
757 .Fa "int class"
758 .Fa "int type"
759 .Fa "char *data"
760 .Fa "int datalen"
761 .Fa "struct rrec *newrr"
762 .Fa "char *buf"
763 .Fa "int buflen"
764 .Fc
765
766 Produces:
767
768 int res_mkquery(int op, char *dname, int class, int type,
769 char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
770
771 Typically, in a “Synopsis” section, the function delcaration will begin
772 the line. If more than one function is presented in the “Synopsis” sec‐
773 tion and a function type has not been given, a break will occur, leaving
774 vertical space between the current and prior function names.
775
776 The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respec‐
777 tively.
778
779 Function Arguments
780 The ‘.Fa’ macro is used to refer to function arguments (parameters) out‐
781 side of the Synopsis section of the manual or inside the Synopsis section
782 if the enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used. ‘.Fa’
783 may also be used to refer to structure members.
784
785 Usage: .Fa ⟨function argument⟩ ...
786
787 .Fa d_namlen ) ) , d_namlen)),
788 .Fa iov_len iov_len
789
790 The default width is 12n.
791
792 Return Values
793 The ‘.Rv’ macro generates text for use in the Return values section.
794
795 Usage: .Rv [-std] [⟨function⟩ ...]
796
797 For example, ‘.Rv -std atexit’ produces:
798
799 The atexit() function returns the value 0 if successful; otherwise
800 the value -1 is returned and the global variable errno is set to
801 indicate the error.
802
803 The -std option is valid only for manual page sections 2 and 3. Cur‐
804 rently, this macro does nothing if used without the -std flag.
805
806 Exit Status
807 The ‘.Ex’ macro generates text for use in the Diagnostics section.
808
809 Usage: .Ex [-std] [⟨utility⟩ ...]
810
811 For example, ‘.Ex -std cat’ produces:
812
813 The cat utility exits 0 on success, and >0 if an error occurs.
814
815 The -std option is valid only for manual page sections 1, 6 and 8. Cur‐
816 rently, this macro does nothing if used without the -std flag.
817
818 Interactive Commands
819 The ‘.Ic’ macro designates an interactive or internal command.
820
821 Usage: .Ic ⟨argument⟩ ...
822
823 .Ic :wq :wq
824 .Ic "do while {...}" do while {...}
825 .Ic setenv , unsetenv setenv, unsetenv
826
827 The default width is 12n.
828
829 Library Names
830 The ‘.Lb’ macro is used to specify the library where a particular func‐
831 tion is compiled in.
832
833 Usage: .Lb ⟨argument⟩ ...
834
835 Available arguments to ‘.Lb’ and their results are:
836
837 libarchive Reading and Writing Streaming Archives Library
838 (libarchive, -larchive)
839 libarm ARM Architecture Library (libarm, -larm)
840 libarm32 ARM32 Architecture Library (libarm32, -larm32)
841 libbluetooth Bluetooth Library (libbluetooth, -lbluetooth)
842 libbsm Basic Security Module Library (libbsm, -lbsm)
843 libc Standard C Library (libc, -lc)
844 libc_r Reentrant C Library (libc_r, -lc_r)
845 libcalendar Calendar Arithmetic Library (libcalendar,
846 -lcalendar)
847 libcam Common Access Method User Library (libcam, -lcam)
848 libcdk Curses Development Kit Library (libcdk, -lcdk)
849 libcipher FreeSec Crypt Library (libcipher, -lcipher)
850 libcompat Compatibility Library (libcompat, -lcompat)
851 libcrypt Crypt Library (libcrypt, -lcrypt)
852 libcurses Curses Library (libcurses, -lcurses)
853 libdevinfo Device and Resource Information Utility Library
854 (libdevinfo, -ldevinfo)
855 libdevstat Device Statistics Library (libdevstat, -ldevstat)
856 libdisk Interface to Slice and Partition Labels Library
857 (libdisk, -ldisk)
858 libdwarf DWARF Access Library (libdwarf, -ldwarf)
859 libedit Command Line Editor Library (libedit, -ledit)
860 libelf ELF Access Library (libelf, -lelf)
861 libevent Event Notification Library (libevent, -levent)
862 libfetch File Transfer Library for URLs (libfetch, -lfetch)
863 libform Curses Form Library (libform, -lform)
864 libgeom Userland API Library for kernel GEOM subsystem
865 (libgeom, -lgeom)
866 libgpib General-Purpose Instrument Bus (GPIB) library
867 (libgpib, -lgpib)
868 libi386 i386 Architecture Library (libi386, -li386)
869 libintl Internationalized Message Handling Library (libintl,
870 -lintl)
871 libipsec IPsec Policy Control Library (libipsec, -lipsec)
872 libipx IPX Address Conversion Support Library (libipx,
873 -lipx)
874 libiscsi iSCSI protocol library (libiscsi, -liscsi)
875 libjail Jail Library (libjail, -ljail)
876 libkiconv Kernel side iconv library (libkiconv, -lkiconv)
877 libkse N:M Threading Library (libkse, -lkse)
878 libkvm Kernel Data Access Library (libkvm, -lkvm)
879 libm Math Library (libm, -lm)
880 libm68k m68k Architecture Library (libm68k, -lm68k)
881 libmagic Magic Number Recognition Library (libmagic, -lmagic)
882 libmd Message Digest (MD4, MD5, etc.) Support Library
883 (libmd, -lmd)
884 libmemstat Kernel Memory Allocator Statistics Library
885 (libmemstat, -lmemstat)
886 libmenu Curses Menu Library (libmenu, -lmenu)
887 libnetgraph Netgraph User Library (libnetgraph, -lnetgraph)
888 libnetpgp Netpgp signing, verification, encryption and
889 decryption (libnetpgp, -lnetpgp)
890 libossaudio OSS Audio Emulation Library (libossaudio,
891 -lossaudio)
892 libpam Pluggable Authentication Module Library (libpam,
893 -lpam)
894 libpcap Packet Capture Library (libpcap, -lpcap)
895 libpci PCI Bus Access Library (libpci, -lpci)
896 libpmc Performance Counters Library (libpmc, -lpmc)
897 libposix POSIX Compatibility Library (libposix, -lposix)
898 libprop Property Container Object Library (libprop, -lprop)
899 libpthread POSIX Threads Library (libpthread, -lpthread)
900 libpuffs puffs Convenience Library (libpuffs, -lpuffs)
901 librefuse File System in Userspace Convenience Library
902 (librefuse, -lrefuse)
903 libresolv DNS Resolver Library (libresolv, -lresolv)
904 librpcsec_gss RPC GSS-API Authentication Library (librpcsec_gss,
905 -lrpcsec_gss)
906 librpcsvc RPC Service Library (librpcsvc, -lrpcsvc)
907 librt POSIX Real-time Library (librt, -lrt)
908 libsdp Bluetooth Service Discovery Protocol User Library
909 (libsdp, -lsdp)
910 libssp Buffer Overflow Protection Library (libssp, -lssp)
911 libSystem System Library (libSystem, -lSystem)
912 libtermcap Termcap Access Library (libtermcap, -ltermcap)
913 libterminfo Terminal Information Library (libterminfo,
914 -lterminfo)
915 libthr 1:1 Threading Library (libthr, -lthr)
916 libufs UFS File System Access Library (libufs, -lufs)
917 libugidfw File System Firewall Interface Library (libugidfw,
918 -lugidfw)
919 libulog User Login Record Library (libulog, -lulog)
920 libusbhid USB Human Interface Devices Library (libusbhid,
921 -lusbhid)
922 libutil System Utilities Library (libutil, -lutil)
923 libvgl Video Graphics Library (libvgl, -lvgl)
924 libx86_64 x86_64 Architecture Library (libx86_64, -lx86_64)
925 libz Compression Library (libz, -lz)
926
927 Site-specific additions might be found in the file mdoc.local; see sec‐
928 tion Files below.
929
930 In a section titled “Library”, ‘Lb’ causes a break before and after its
931 arguments.
932
933 Literals
934 The ‘Li’ literal macro may be used for special characters, symbolic con‐
935 stants, and other syntactical items that should be typed exactly as dis‐
936 played.
937
938 Usage: .Li ⟨argument⟩ ...
939
940 .Li \en \n
941 .Li M1 M2 M3 ; M1 M2 M3;
942 .Li cntrl-D ) , cntrl-D),
943 .Li 1024 ... 1024 ...
944
945 The default width is 16n.
946
947 Names
948 The ‘Nm’ macro is used for the document title or page topic. Upon its
949 first call, it has the peculiarity of remembering its argument, which
950 should always be the topic of the man page. When subsequently called
951 without arguments, ‘Nm’ regurgitates this initial name for the sole pur‐
952 pose of making less work for the author. Use of ‘Nm’ is also appropriate
953 when presenting a command synopsis for the topic of a man page in section
954 1, 6, or 8. Its behavior changes when presented with arguments of vari‐
955 ous forms.
956
957 .Nm groff_mdoc groff_mdoc
958 .Nm groff_mdoc
959 .Nm \-mdoc -mdoc
960 .Nm foo ) ) , foo)),
961 .Nm : groff_mdoc:
962
963 By default, the topic is set in boldface to reflect its prime importance
964 in the discussion. Cross references to other man page topics should use
965 ‘Xr’; including a second argument for the section number enables them to
966 be hyperlinked. By default, cross-referenced topics are set in italics
967 to avoid cluttering the page with boldface.
968
969 The default width is 10n.
970
971 Options
972 The ‘.Op’ macro places option brackets around any remaining arguments on
973 the command line, and places any trailing punctuation outside the brack‐
974 ets. The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a closing
975 option bracket, respectively) may be used across one or more lines or to
976 specify the exact position of the closing parenthesis.
977
978 Usage: .Op [⟨option⟩] ...
979
980 .Op []
981 .Op Fl k [-k]
982 .Op Fl k ) . [-k]).
983 .Op Fl k Ar kookfile [-k kookfile]
984 .Op Fl k Ar kookfile , [-k kookfile],
985 .Op Ar objfil Op Ar corfil [objfil [corfil]]
986 .Op Fl c Ar objfil Op Ar corfil , [-c objfil [corfil]],
987 .Op word1 word2 [word1 word2]
988 .Li .Op Oo Ao option Ac Oc ... .Op [⟨option⟩] ...
989
990 Here a typical example of the ‘.Oo’ and ‘.Oc’ macros:
991
992 .Oo
993 .Op Fl k Ar kilobytes
994 .Op Fl i Ar interval
995 .Op Fl c Ar count
996 .Oc
997
998 Produces:
999
1000 [[-k kilobytes] [-i interval] [-c count]]
1001
1002 The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respec‐
1003 tively.
1004
1005 Pathnames
1006 The ‘.Pa’ macro formats file specifications. If called without argu‐
1007 ments, ‘~’ (recognized by many shells) is output, representing the user's
1008 home directory.
1009
1010 Usage: .Pa [⟨pathname⟩] ...
1011
1012 .Pa ~
1013 .Pa /usr/share /usr/share
1014 .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).
1015
1016 The default width is 32n.
1017
1018 Standards
1019 The ‘.St’ macro replaces standard abbreviations with their formal names.
1020
1021 Usage: .St ⟨abbreviation⟩ ...
1022
1023 Available pairs for “Abbreviation/Formal Name” are:
1024
1025 ANSI/ISO C
1026
1027 -ansiC ANSI X3.159-1989 (“ANSI C89”)
1028 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
1029 -isoC ISO/IEC 9899:1990 (“ISO C90”)
1030 -isoC-90 ISO/IEC 9899:1990 (“ISO C90”)
1031 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
1032 -isoC-2011 ISO/IEC 9899:2011 (“ISO C11”)
1033
1034 POSIX Part 1: System API
1035
1036 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1037 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1038 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
1039 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
1040 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1041 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1042 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
1043 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
1044 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
1045 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
1046 -p1003.1-2001 IEEE Std 1003.1-2001 (“POSIX.1”)
1047 -p1003.1-2004 IEEE Std 1003.1-2004 (“POSIX.1”)
1048 -p1003.1-2008 IEEE Std 1003.1-2008 (“POSIX.1”)
1049
1050 POSIX Part 2: Shell and Utilities
1051
1052 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
1053 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
1054 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
1055 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
1056
1057 X/Open
1058
1059 -susv1
1060 -susv2 Version 2 of the Single UNIX Specification
1061 (“SUSv2”)
1062 -susv3 Version 3 of the Single UNIX Specification
1063 (“SUSv3”)
1064 -susv4
1065 -svid4 System V Interface Definition, Fourth Edition
1066 (“SVID4”)
1067 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
1068 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
1069 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1070 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
1071 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1072 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1073 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1074 -xpg4.2 X/Open Portability Guide Issue 4, Version 2
1075 (“XPG4.2”)
1076 -xsh5 X/Open System Interfaces and Headers Issue 5
1077 (“XSH5”)
1078
1079 Miscellaneous
1080
1081 -ieee754 IEEE Std 754-1985
1082 -iso8601 ISO 8601
1083 -iso8802-3 ISO/IEC 8802-3:1989
1084
1085 Variable Types
1086 The ‘.Vt’ macro may be used whenever a type is referenced. In a section
1087 titled “Synopsis”, ‘Vt’ causes a break (useful for old-style C variable
1088 declarations).
1089
1090 Usage: .Vt ⟨type⟩ ...
1091
1092 .Vt extern char *optarg ; extern char *optarg;
1093 .Vt FILE * FILE *
1094
1095 Variables
1096 Generic variable reference.
1097
1098 Usage: .Va ⟨variable⟩ ...
1099
1100 .Va count count
1101 .Va settimer , settimer,
1102 .Va "int *prt" ) : int *prt):
1103 .Va "char s" ] ) ) , char s])),
1104
1105 The default width is 12n.
1106
1107 Manual Page Cross References
1108 The ‘.Xr’ macro expects the first argument to be a manual page name. The
1109 optional second argument, if a string (defining the manual section), is
1110 put into parentheses.
1111
1112 Usage: .Xr ⟨man page name⟩ [⟨section⟩] ...
1113
1114 .Xr mdoc mdoc
1115 .Xr mdoc , mdoc,
1116 .Xr mdoc 7 mdoc(7)
1117 .Xr xinit 1x ; xinit(1x);
1118
1119 The default width is 10n.
1120
1122 AT&T Macro
1123 Usage: .At [⟨version⟩] ...
1124
1125 .At AT&T UNIX
1126 .At v6 . Version 6 AT&T UNIX.
1127
1128 The following values for ⟨version⟩ are possible:
1129
1130 32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4
1131
1132 BSD Macro
1133 Usage: .Bx {-alpha | -beta | -devel} ...
1134 .Bx [⟨version⟩ [⟨release⟩]] ...
1135
1136 .Bx BSD
1137 .Bx 4.3 . 4.3BSD.
1138 .Bx -devel BSD (currently under development)
1139
1140 ⟨version⟩ will be prepended to the string ‘BSD’. The following values
1141 for ⟨release⟩ are possible:
1142
1143 Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
1144
1145 NetBSD Macro
1146 Usage: .Nx [⟨version⟩] ...
1147
1148 .Nx NetBSD
1149 .Nx 1.4 . NetBSD 1.4.
1150
1151 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1152 above in section Title macros.
1153
1154 FreeBSD Macro
1155 Usage: .Fx [⟨version⟩] ...
1156
1157 .Fx FreeBSD
1158 .Fx 2.2 . FreeBSD 2.2.
1159
1160 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1161 above in section Title macros.
1162
1163 DragonFly Macro
1164 Usage: .Dx [⟨version⟩] ...
1165
1166 .Dx DragonFly
1167 .Dx 1.4 . DragonFly 1.4.
1168
1169 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1170 above in section Title macros.
1171
1172 OpenBSD Macro
1173 Usage: .Ox [⟨version⟩] ...
1174
1175 .Ox 1.0 OpenBSD 1.0
1176
1177 BSD/OS Macro
1178 Usage: .Bsx [⟨version⟩] ...
1179
1180 .Bsx 1.0 BSD/OS 1.0
1181
1182 Unix Macro
1183 Usage: .Ux ...
1184
1185 .Ux UNIX
1186
1187 Emphasis Macro
1188 Text may be stressed or emphasized with the ‘.Em’ macro. The usual font
1189 for emphasis is italic.
1190
1191 Usage: .Em ⟨argument⟩ ...
1192
1193 .Em does not does not
1194 .Em exceed 1024 . exceed 1024.
1195 .Em vide infra ) ) , vide infra)),
1196
1197 The default width is 10n.
1198
1199 Font Mode
1200 The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes
1201 no arguments). Font modes may be nested within other font modes.
1202
1203 ‘.Bf’ has the following syntax:
1204
1205 .Bf ⟨font mode⟩
1206
1207 ⟨font mode⟩ must be one of the following three types:
1208
1209 Em | -emphasis Same as if the ‘.Em’ macro was used for the entire
1210 block of text.
1211 Li | -literal Same as if the ‘.Li’ macro was used for the entire
1212 block of text.
1213 Sy | -symbolic Same as if the ‘.Sy’ macro was used for the entire
1214 block of text.
1215
1216 Both macros are neither callable nor parsed.
1217
1218 Enclosure and Quoting Macros
1219 The concept of enclosure is similar to quoting. The object being to en‐
1220 close one or more strings between a pair of characters like quotes or
1221 parentheses. The terms quoting and enclosure are used interchangeably
1222 throughout this document. Most of the one-line enclosure macros end in
1223 small letter ‘q’ to give a hint of quoting, but there are a few irregu‐
1224 larities. For each enclosure macro, there is a pair of opening and clos‐
1225 ing macros that end with the lowercase letters ‘o’ and ‘c’ respectively.
1226
1227 Quote Open Close Function Result
1228 .Aq .Ao .Ac Angle Bracket Enclosure <string>
1229 .Bq .Bo .Bc Bracket Enclosure [string]
1230 .Brq .Bro .Brc Brace Enclosure {string}
1231 .Dq .Do .Dc Double Quote “string”
1232 .Eq .Eo .Ec Enclose String (in XY) XstringY
1233 .Pq .Po .Pc Parenthesis Enclosure (string)
1234 .Ql Quoted Literal “string” or string
1235 .Qq .Qo .Qc Straight Double Quote "string"
1236 .Sq .So .Sc Single Quote ‘string’
1237
1238 All macros ending with ‘q’ and ‘o’ have a default width value of 12n.
1239
1240 .Eo, .Ec These macros expect the first argument to be the opening and
1241 closing strings, respectively.
1242
1243 .Es, .En To work around the nine-argument limit in the original troff
1244 program, mdoc supports two other macros that are now obsolete.
1245 ‘.Es’ uses its first and second parameters as opening and clos‐
1246 ing marks which are then used to enclose the arguments of
1247 ‘.En’. The default width value is 12n for both macros.
1248
1249 .Eq The first and second arguments of this macro are the opening
1250 and closing strings respectively, followed by the arguments to
1251 be enclosed.
1252
1253 .Ql The quoted literal macro behaves differently in troff and nroff
1254 modes. If formatted with nroff(1), a quoted literal is always
1255 quoted. If formatted with troff, an item is only quoted if the
1256 width of the item is less than three constant-width characters.
1257 This is to make short strings more visible where the font
1258 change to literal (constant-width) is less noticeable.
1259
1260 The default width is 16n.
1261
1262 .Pf The prefix macro suppresses the whitespace between its first
1263 and second argument:
1264
1265 .Pf ( Fa name2 (name2
1266
1267 The default width is 12n.
1268
1269 The ‘.Ns’ macro (see below) performs the analogous suffix func‐
1270 tion.
1271
1272 .Ap The ‘.Ap’ macro inserts an apostrophe and exits any special
1273 text modes, continuing in ‘.No’ mode.
1274
1275 Examples of quoting:
1276
1277 .Aq ⟨⟩
1278 .Aq Pa ctype.h ) , ⟨ctype.h⟩),
1279 .Bq []
1280 .Bq Em Greek , French . [Greek, French].
1281 .Dq “”
1282 .Dq string abc . “string abc”.
1283 .Dq '\[ha][A-Z]' “'^[A-Z]'”
1284 .Ql man mdoc ‘man mdoc’
1285 .Qq ""
1286 .Qq string ) , "string"),
1287 .Qq string Ns ), "string),"
1288 .Sq ‘’
1289 .Sq string ‘string’
1290 .Em or Ap ing or'ing
1291
1292 For a good example of nested enclosure macros, see the ‘.Op’ option
1293 macro. It was created from the same underlying enclosure macros as those
1294 presented in the list above. The ‘.Xo’ and ‘.Xc’ extended argument list
1295 macros are discussed below.
1296
1297 Normal text macro
1298 ‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’
1299 and similar. Parsing is not suppressed, so you must prefix words like
1300 ‘No’ with ‘\&’ to avoid their interpretation as mdoc macros.
1301
1302 Usage: .No argument ...
1303
1304 .Em Use caution No here . → Use caution here.
1305 .Em No dogs allowed . → No dogs allowed.
1306 .Em \&No dogs allowed . → No dogs allowed.
1307
1308 The default width is 12n.
1309
1310 No-Space Macro
1311 The ‘.Ns’ macro suppresses insertion of a space between the current posi‐
1312 tion and its first parameter. For example, it is useful for old style
1313 argument lists where there is no space between the flag and argument:
1314
1315 Usage: ... ⟨argument⟩ Ns [⟨argument⟩] ...
1316 .Ns ⟨argument⟩ ...
1317
1318 .Op Fl I Ns Ar directory [-Idirectory]
1319
1320 Note: The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating
1321 the space unless another macro name follows it. If used as a command
1322 (i.e., the second form above in the ‘Usage’ line), ‘.Ns’ is identical to
1323 ‘.No’.
1324
1325 (Sub)section cross references
1326 Use the ‘.Sx’ macro to cite a (sub)section heading within the given docu‐
1327 ment.
1328
1329 Usage: .Sx ⟨section-reference⟩ ...
1330
1331 .Sx Files → Files
1332
1333 The default width is 16n.
1334
1335 Symbolics
1336 The symbolic emphasis macro is generally a boldface macro in either the
1337 symbolic sense or the traditional English usage.
1338
1339 Usage: .Sy ⟨symbol⟩ ...
1340
1341 .Sy Important Notice → Important Notice
1342
1343 The default width is 6n.
1344
1345 Mathematical Symbols
1346 Use this macro for mathematical symbols and similar things.
1347
1348 Usage: .Ms ⟨math symbol⟩ ...
1349
1350 .Ms sigma → sigma
1351
1352 The default width is 6n.
1353
1354 References and Citations
1355 The following macros make a modest attempt to handle references. At
1356 best, the macros make it convenient to manually drop in a subset of
1357 refer(1) style references.
1358
1359 .Rs Reference start (does not take arguments). In a section
1360 titled “See also”, it causes a break and begins collection
1361 of reference information until the reference end macro is
1362 read.
1363 .Re Reference end (does not take arguments). The reference is
1364 printed.
1365 .%A Reference author name; one name per invocation.
1366 .%B Book title.
1367 .%C City/place.
1368 .%D Date.
1369 .%I Issuer/publisher name.
1370 .%J Journal name.
1371 .%N Issue number.
1372 .%O Optional information.
1373 .%P Page number.
1374 .%Q Corporate or foreign author.
1375 .%R Report name.
1376 .%T Title of article.
1377 .%U Optional hypertext reference.
1378 .%V Volume.
1379
1380 Macros beginning with ‘%’ are not callable but accept multiple arguments
1381 in the usual way. Only the ‘.Tn’ macro is handled properly as a parame‐
1382 ter; other macros will cause strange output. ‘.%B’ and ‘.%T’ can be used
1383 outside of the ‘.Rs/.Re’ environment.
1384
1385 Example:
1386
1387 .Rs
1388 .%A "Matthew Bar"
1389 .%A "John Foo"
1390 .%T "Implementation Notes on foobar(1)"
1391 .%R "Technical Report ABC-DE-12-345"
1392 .%Q "Drofnats College"
1393 .%C "Nowhere"
1394 .%D "April 1991"
1395 .Re
1396
1397 produces
1398
1399 Matthew Bar and John Foo, Implementation Notes on foobar(1),
1400 Technical Report ABC-DE-12-345, Drofnats College, Nowhere, April
1401 1991.
1402
1403 Trade Names or Acronyms
1404 The trade name macro prints its arguments at a smaller type size. It is
1405 intended to imitate a small caps fonts for fully capitalized acronyms.
1406
1407 Usage: .Tn ⟨symbol⟩ ...
1408
1409 .Tn DEC DEC
1410 .Tn ASCII ASCII
1411
1412 The default width is 10n.
1413
1414 Extended Arguments
1415 The .Xo and .Xc macros allow one to extend an argument list on a macro
1416 boundary for the ‘.It’ macro (see below). Note that .Xo and .Xc are im‐
1417 plemented similarly to all other macros opening and closing an enclosure
1418 (without inserting characters, of course). This means that the following
1419 is true for those macros also.
1420
1421 Here is an example of ‘.Xo’ using the space mode macro to turn spacing
1422 off:
1423
1424 .Bd -literal -offset indent
1425 .Sm off
1426 .It Xo Sy I Ar operation
1427 .No \en Ar count No \en
1428 .Xc
1429 .Sm on
1430 .Ed
1431
1432 produces
1433
1434 Ioperation\ncount\n
1435
1436 Another one:
1437
1438 .Bd -literal -offset indent
1439 .Sm off
1440 .It Cm S No / Ar old_pattern Xo
1441 .No / Ar new_pattern
1442 .No / Op Cm g
1443 .Xc
1444 .Sm on
1445 .Ed
1446
1447 produces
1448
1449 S/old_pattern/new_pattern/[g]
1450
1451 Another example of ‘.Xo’ and enclosure macros: Test the value of a vari‐
1452 able.
1453
1454 .Bd -literal -offset indent
1455 .It Xo
1456 .Ic .ifndef
1457 .Oo \&! Oc Ns Ar variable Oo
1458 .Ar operator variable No ...
1459 .Oc Xc
1460 .Ed
1461
1462 produces
1463
1464 .ifndef [!]variable [operator variable ...]
1465
1467 Section headings
1468 The following ‘.Sh’ section heading macros are required in every man
1469 page. The remaining section headings are recommended at the discretion
1470 of the author writing the manual page. The ‘.Sh’ macro is parsed but not
1471 generally callable. It can be used as an argument in a call to ‘.Sh’
1472 only; it then reactivates the default font for ‘.Sh’.
1473
1474 The default width is 8n.
1475
1476 .Sh Name The ‘.Sh Name’ macro is mandatory. If not specified,
1477 headers, footers, and page layout defaults will not be
1478 set and things will be rather unpleasant. The Name
1479 section consists of at least three items. The first
1480 is the ‘.Nm’ name macro naming the subject of the man
1481 page. The second is the name description macro,
1482 ‘.Nd’, which separates the subject name from the third
1483 item, which is the description. The description
1484 should be the most terse and lucid possible, as the
1485 space available is small.
1486
1487 ‘.Nd’ first prints ‘-’, then all its arguments.
1488
1489 .Sh Library This section is for section two and three function
1490 calls. It should consist of a single ‘.Lb’ macro
1491 call; see Library Names.
1492
1493 .Sh Synopsis The Synopsis section describes the typical usage of
1494 the subject of a man page. The macros required are
1495 either ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,
1496 ‘.Fc’, ‘.Fd’, and ‘.Ft’). The function name macro
1497 ‘.Fn’ is required for manual page sections 2 and 3;
1498 the command and general name macro ‘.Nm’ is required
1499 for sections 1, 5, 6, 7, and 8. Section 4 manuals re‐
1500 quire a ‘.Nm’, ‘.Fd’ or a ‘.Cd’ configuration device
1501 usage macro. Several other macros may be necessary to
1502 produce the synopsis line as shown below:
1503
1504 cat [-benstuv] [-] file ...
1505
1506 The following macros were used:
1507
1508 .Nm cat
1509 .Op Fl benstuv
1510 .Op Fl
1511 .Ar file No ...
1512
1513 .Sh Description In most cases the first text in the Description sec‐
1514 tion is a brief paragraph on the command, function or
1515 file, followed by a lexical list of options and re‐
1516 spective explanations. To create such a list, the
1517 ‘.Bl’ (begin list), ‘.It’ (list item) and ‘.El’ (end
1518 list) macros are used (see Lists and Columns below).
1519
1520 .Sh Implementation notes
1521 Implementation specific information should be placed
1522 here.
1523
1524 .Sh Return values Sections 2, 3 and 9 function return values should go
1525 here. The ‘.Rv’ macro may be used to generate text
1526 for use in the Return values section for most section
1527 2 and 3 library functions; see Return Values.
1528
1529 The following ‘.Sh’ section headings are part of the preferred manual
1530 page layout and must be used appropriately to maintain consistency. They
1531 are listed in the order in which they would be used.
1532
1533 .Sh Environment The Environment section should reveal any related en‐
1534 vironment variables and clues to their behavior and/or
1535 usage.
1536
1537 .Sh Files Files which are used or created by the man page sub‐
1538 ject should be listed via the ‘.Pa’ macro in the Files
1539 section.
1540
1541 .Sh Examples There are several ways to create examples. See sub‐
1542 section Examples and Displays below for details.
1543
1544 .Sh Diagnostics Diagnostic messages from a command should be placed in
1545 this section. The ‘.Ex’ macro may be used to generate
1546 text for use in the Diagnostics section for most sec‐
1547 tion 1, 6 and 8 commands; see Exit Status.
1548
1549 .Sh Compatibility Known compatibility issues (e.g. deprecated options or
1550 parameters) should be listed here.
1551
1552 .Sh Errors Specific error handling, especially from library func‐
1553 tions (man page sections 2, 3, and 9) should go here.
1554 The ‘.Er’ macro is used to specify an error (errno).
1555
1556 .Sh See also References to other material on the man page topic and
1557 cross references to other relevant man pages should be
1558 placed in the See also section. Cross references are
1559 specified using the ‘.Xr’ macro. Currently refer(1)
1560 style references are not accommodated.
1561
1562 It is recommended that the cross references be sorted
1563 by section number, then alphabetically by name within
1564 each section, then separated by commas. Example:
1565
1566 ls(1), ps(1), group(5), passwd(5)
1567
1568 .Sh Standards If the command, library function, or file adheres to a
1569 specific implementation such as IEEE Std 1003.2
1570 (“POSIX.2”) or ANSI X3.159-1989 (“ANSI C89”) this
1571 should be noted here. If the command does not adhere
1572 to any standard, its history should be noted in the
1573 History section.
1574
1575 .Sh History Any command which does not adhere to any specific
1576 standards should be outlined historically in this sec‐
1577 tion.
1578
1579 .Sh Authors Credits should be placed here. Use the ‘.An’ macro
1580 for names and the ‘.Aq’ macro for email addresses
1581 within optional contact information. Explicitly indi‐
1582 cate whether the person authored the initial manual
1583 page or the software or whatever the person is being
1584 credited for.
1585
1586 .Sh Bugs Blatant problems with the topic go here.
1587
1588 User-specified ‘.Sh’ sections may be added; for example, this section was
1589 set with:
1590
1591 .Sh "Page structure domain"
1592
1593 Subsection headings
1594 Subsection headings have exactly the same syntax as section headings:
1595 ‘.Ss’ is parsed but not generally callable. It can be used as an argu‐
1596 ment in a call to ‘.Ss’ only; it then reactivates the default font for
1597 ‘.Ss’.
1598
1599 The default width is 8n.
1600
1601 Paragraphs and Line Spacing
1602 .Pp The ‘.Pp’ paragraph command may be used to specify a line space
1603 where necessary. The macro is not necessary after a ‘.Sh’ or ‘.Ss’
1604 macro or before a ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical
1605 distance unless the -compact flag is given).
1606
1607 The macro is neither callable nor parsed and takes no arguments; an
1608 alternative name is ‘.Lp’.
1609
1610 Keeps
1611 The only keep that is implemented at this time is for words. The macros
1612 are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep). The only option that ‘.Bk’
1613 currently accepts is -words (also the default); this prevents breaks in
1614 the middle of options. In the example for make command-line arguments
1615 (see What's in a Name), the keep prevents nroff from placing the flag and
1616 the argument on separate lines.
1617
1618 Neither macro is callable or parsed.
1619
1620 More work needs to be done on the keep macros; specifically, a -line op‐
1621 tion should be added.
1622
1623 Examples and Displays
1624 There are seven types of displays.
1625
1626 .D1 (This is D-one.) Display one line of indented text. This macro is
1627 parsed but not callable.
1628
1629 -ldghfstru
1630
1631 The above was produced by: .D1 Fl ldghfstru.
1632
1633 .Dl (This is D-ell.) Display one line of indented literal text. The
1634 ‘.Dl’ example macro has been used throughout this file. It allows
1635 the indentation (display) of one line of text. Its default font is
1636 set to constant width (literal). ‘.Dl’ is parsed but not callable.
1637
1638 % ls -ldg /usr/local/bin
1639
1640 The above was produced by: .Dl % ls \-ldg /usr/local/bin.
1641
1642 .Bd Begin display. The ‘.Bd’ display must be ended with the ‘.Ed’
1643 macro. It has the following syntax:
1644
1645 .Bd {-literal | -filled | -unfilled | -ragged | -centered}
1646 [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]
1647
1648 -ragged Fill, but do not adjust the right margin (only
1649 left-justify).
1650 -centered Center lines between the current left and right
1651 margin. Note that each single line is centered.
1652 -unfilled Do not fill; break lines where their input lines
1653 are broken. This can produce overlong lines
1654 without warning messages.
1655 -filled Display a filled block. The block of text is
1656 formatted (i.e., the text is justified on both
1657 the left and right side).
1658 -literal Display block with literal font (usually fixed-
1659 width). Useful for source code or simple tabbed
1660 or spaced text.
1661 -file ⟨file name⟩ The file whose name follows the -file flag is
1662 read and displayed before any data enclosed with
1663 ‘.Bd’ and ‘.Ed’, using the selected display type.
1664 Any troff/mdoc commands in the file will be pro‐
1665 cessed.
1666 -offset ⟨string⟩ If -offset is specified with one of the following
1667 strings, the string is interpreted to indicate
1668 the level of indentation for the forthcoming
1669 block of text:
1670
1671 left Align block on the current left mar‐
1672 gin; this is the default mode of
1673 ‘.Bd’.
1674 center Supposedly center the block. At this
1675 time unfortunately, the block merely
1676 gets left aligned about an imaginary
1677 center margin.
1678 indent Indent by one default indent value or
1679 tab. The default indent value is
1680 also used for the ‘.D1’ and ‘.Dl’
1681 macros, so one is guaranteed the two
1682 types of displays will line up. The
1683 indentation value is normally set
1684 to 6n or about two thirds of an inch
1685 (six constant width characters).
1686 indent-two Indent two times the default indent
1687 value.
1688 right This left aligns the block about two
1689 inches from the right side of the
1690 page. This macro needs work and per‐
1691 haps may never do the right thing
1692 within troff.
1693
1694 If ⟨string⟩ is a valid numeric expression instead
1695 (with a scaling indicator other than ‘u’), use
1696 that value for indentation. The most useful
1697 scaling indicators are ‘m’ and ‘n’, specifying
1698 the so-called Em and En square. This is approxi‐
1699 mately the width of the letters ‘m’ and ‘n’ re‐
1700 spectively of the current font (for nroff output,
1701 both scaling indicators give the same values).
1702 If ⟨string⟩ isn't a numeric expression, it is
1703 tested whether it is an mdoc macro name, and the
1704 default offset value associated with this macro
1705 is used. Finally, if all tests fail, the width
1706 of ⟨string⟩ (typeset with a fixed-width font) is
1707 taken as the offset.
1708 -compact Suppress insertion of vertical space before begin
1709 of display.
1710
1711 .Ed End display (takes no arguments).
1712
1713 Lists and Columns
1714 There are several types of lists which may be initiated with the ‘.Bl’
1715 begin-list macro. Items within the list are specified with the ‘.It’
1716 item macro, and each list must end with the ‘.El’ macro. Lists may be
1717 nested within themselves and within displays. The use of columns inside
1718 of lists or lists inside of columns is untested.
1719
1720 In addition, several list attributes may be specified such as the width
1721 of a tag, the list offset, and compactness (blank lines between items al‐
1722 lowed or disallowed). Most of this document has been formatted with a
1723 tag style list (-tag).
1724
1725 It has the following syntax forms:
1726
1727 .Bl {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
1728 [-offset ⟨string⟩] [-compact]
1729 .Bl -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
1730 .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
1731 ⟨string⟩] [-compact]
1732
1733 And now a detailed description of the list types.
1734
1735 -bullet A bullet list.
1736
1737 .Bl -bullet -offset indent -compact
1738 .It
1739 Bullet one goes here.
1740 .It
1741 Bullet two here.
1742 .El
1743
1744 Produces:
1745
1746 • Bullet one goes here.
1747 • Bullet two here.
1748
1749 -dash (or -hyphen)
1750 A dash list.
1751
1752 .Bl -dash -offset indent -compact
1753 .It
1754 Dash one goes here.
1755 .It
1756 Dash two here.
1757 .El
1758
1759 Produces:
1760
1761 - Dash one goes here.
1762 - Dash two here.
1763
1764 -enum An enumerated list.
1765
1766 .Bl -enum -offset indent -compact
1767 .It
1768 Item one goes here.
1769 .It
1770 And item two here.
1771 .El
1772
1773 The result:
1774
1775 1. Item one goes here.
1776 2. And item two here.
1777
1778 If you want to nest enumerated lists, use the -nested flag
1779 (starting with the second-level list):
1780
1781 .Bl -enum -offset indent -compact
1782 .It
1783 Item one goes here
1784 .Bl -enum -nested -compact
1785 .It
1786 Item two goes here.
1787 .It
1788 And item three here.
1789 .El
1790 .It
1791 And item four here.
1792 .El
1793
1794 Result:
1795
1796 1. Item one goes here.
1797 1.1. Item two goes here.
1798 1.2. And item three here.
1799 2. And item four here.
1800
1801 -item A list of type -item without list markers.
1802
1803 .Bl -item -offset indent
1804 .It
1805 Item one goes here.
1806 Item one goes here.
1807 Item one goes here.
1808 .It
1809 Item two here.
1810 Item two here.
1811 Item two here.
1812 .El
1813
1814 Produces:
1815
1816 Item one goes here. Item one goes here. Item one goes
1817 here.
1818
1819 Item two here. Item two here. Item two here.
1820
1821 -tag A list with tags. Use -width to specify the tag width.
1822
1823 SL sleep time of the process (seconds blocked)
1824 PAGEIN
1825 number of disk I/O operations resulting from refer‐
1826 ences by the process to pages not loaded in core.
1827 UID numerical user-id of process owner
1828 PPID numerical id of parent of process priority (non-pos‐
1829 itive when in non-interruptible wait)
1830
1831 The raw text:
1832
1833 .Bl -tag -width "PPID" -compact -offset indent
1834 .It SL
1835 sleep time of the process (seconds blocked)
1836 .It PAGEIN
1837 number of disk I/O operations resulting from references
1838 by the process to pages not loaded in core.
1839 .It UID
1840 numerical user-id of process owner
1841 .It PPID
1842 numerical id of parent of process priority
1843 (non-positive when in non-interruptible wait)
1844 .El
1845
1846 -diag Diag lists create section four diagnostic lists and are similar
1847 to inset lists except callable macros are ignored. The -width
1848 flag is not meaningful in this context.
1849
1850 Example:
1851
1852 .Bl -diag
1853 .It You can't use Sy here.
1854 The message says all.
1855 .El
1856
1857 produces
1858
1859 You can't use Sy here. The message says all.
1860
1861 -hang A list with hanging tags.
1862
1863 Hanged labels appear similar to tagged lists when the la‐
1864 bel is smaller than the label width.
1865
1866 Longer hanged list labels blend into the paragraph unlike
1867 tagged paragraph labels.
1868
1869 And the unformatted text which created it:
1870
1871 .Bl -hang -offset indent
1872 .It Em Hanged
1873 labels appear similar to tagged lists when the
1874 label is smaller than the label width.
1875 .It Em Longer hanged list labels
1876 blend into the paragraph unlike
1877 tagged paragraph labels.
1878 .El
1879
1880 -ohang Lists with overhanging tags do not use indentation for the
1881 items; tags are written to a separate line.
1882
1883 SL
1884 sleep time of the process (seconds blocked)
1885
1886 PAGEIN
1887 number of disk I/O operations resulting from references by
1888 the process to pages not loaded in core.
1889
1890 UID
1891 numerical user-id of process owner
1892
1893 PPID
1894 numerical id of parent of process priority (non-positive
1895 when in non-interruptible wait)
1896
1897 The raw text:
1898
1899 .Bl -ohang -offset indent
1900 .It Sy SL
1901 sleep time of the process (seconds blocked)
1902 .It Sy PAGEIN
1903 number of disk I/O operations resulting from references
1904 by the process to pages not loaded in core.
1905 .It Sy UID
1906 numerical user-id of process owner
1907 .It Sy PPID
1908 numerical id of parent of process priority
1909 (non-positive when in non-interruptible wait)
1910 .El
1911
1912 -inset Here is an example of inset labels:
1913
1914 Tag The tagged list (also called a tagged paragraph) is
1915 the most common type of list used in the Berkeley manuals.
1916 Use a -width attribute as described below.
1917
1918 Diag Diag lists create section four diagnostic lists and
1919 are similar to inset lists except callable macros are ig‐
1920 nored.
1921
1922 Hang Hanged labels are a matter of taste.
1923
1924 Ohang Overhanging labels are nice when space is con‐
1925 strained.
1926
1927 Inset Inset labels are useful for controlling blocks of
1928 paragraphs and are valuable for converting mdoc manuals to
1929 other formats.
1930
1931 Here is the source text which produced the above example:
1932
1933 .Bl -inset -offset indent
1934 .It Em Tag
1935 The tagged list (also called a tagged paragraph)
1936 is the most common type of list used in the
1937 Berkeley manuals.
1938 .It Em Diag
1939 Diag lists create section four diagnostic lists
1940 and are similar to inset lists except callable
1941 macros are ignored.
1942 .It Em Hang
1943 Hanged labels are a matter of taste.
1944 .It Em Ohang
1945 Overhanging labels are nice when space is constrained.
1946 .It Em Inset
1947 Inset labels are useful for controlling blocks of
1948 paragraphs and are valuable for converting
1949 .Xr mdoc
1950 manuals to other formats.
1951 .El
1952
1953 -column This list type generates multiple columns. The number of col‐
1954 umns and the width of each column is determined by the arguments
1955 to the -column list, ⟨string1⟩, ⟨string2⟩, etc. If ⟨stringN⟩
1956 starts with a ‘.’ (dot) immediately followed by a valid mdoc
1957 macro name, interpret ⟨stringN⟩ and use the width of the result.
1958 Otherwise, the width of ⟨stringN⟩ (typeset with a fixed-width
1959 font) is taken as the Nth column width.
1960
1961 Each ‘.It’ argument is parsed to make a row, each column within
1962 the row is a separate argument separated by a tab or the ‘.Ta’
1963 macro.
1964
1965 The table:
1966
1967 String Nroff Troff
1968 <= <= ≤
1969 >= >= ≥
1970
1971 was produced by:
1972
1973 .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
1974 .It Sy String Ta Sy Nroff Ta Sy Troff
1975 .It Li <= Ta <= Ta \*(<=
1976 .It Li >= Ta >= Ta \*(>=
1977 .El
1978
1979 Don't abuse this list type! For more complicated cases it might
1980 be far better and easier to use tbl(1), the table preprocessor.
1981
1982 Other keywords:
1983
1984 -width ⟨string⟩ If ⟨string⟩ starts with a ‘.’ (dot) immediately fol‐
1985 lowed by a valid mdoc macro name, interpret ⟨string⟩
1986 and use the width of the result. Almost all lists in
1987 this document use this option.
1988
1989 Example:
1990
1991 .Bl -tag -width ".Fl test Ao Ar string Ac"
1992 .It Fl test Ao Ar string Ac
1993 This is a longer sentence to show how the
1994 .Fl width
1995 flag works in combination with a tag list.
1996 .El
1997
1998 gives:
1999
2000 -test ⟨string⟩ This is a longer sentence to show how
2001 the -width flag works in combination
2002 with a tag list.
2003
2004 (Note that the current state of mdoc is saved before
2005 ⟨string⟩ is interpreted; afterwards, all variables are
2006 restored again. However, boxes (used for enclosures)
2007 can't be saved in GNU troff(1); as a consequence, argu‐
2008 ments must always be balanced to avoid nasty errors.
2009 For example, do not write ‘.Ao Ar string’ but ‘.Ao Ar
2010 string Xc’ instead if you really need only an opening
2011 angle bracket.)
2012
2013 Otherwise, if ⟨string⟩ is a valid numeric expression
2014 (with a scaling indicator other than ‘u’), use that
2015 value for indentation. The most useful scaling indica‐
2016 tors are ‘m’ and ‘n’, specifying the so-called Em and
2017 En square. This is approximately the width of the let‐
2018 ters ‘m’ and ‘n’ respectively of the current font (for
2019 nroff output, both scaling indicators give the same
2020 values). If ⟨string⟩ isn't a numeric expression, it is
2021 tested whether it is an mdoc macro name, and the de‐
2022 fault width value associated with this macro is used.
2023 Finally, if all tests fail, the width of ⟨string⟩
2024 (typeset with a fixed-width font) is taken as the
2025 width.
2026
2027 If a width is not specified for the tag list type, ‘6n’
2028 is used.
2029
2030 -offset ⟨string⟩ If ⟨string⟩ is indent, a default indent value (normally
2031 set to 6n, similar to the value used in ‘.Dl’ or ‘.Bd’)
2032 is used. If ⟨string⟩ is a valid numeric expression in‐
2033 stead (with a scaling indicator other than ‘u’), use
2034 that value for indentation. The most useful scaling
2035 indicators are ‘m’ and ‘n’, specifying the so-called Em
2036 and En square. This is approximately the width of the
2037 letters ‘m’ and ‘n’ respectively of the current font
2038 (for nroff output, both scaling indicators give the
2039 same values). If ⟨string⟩ isn't a numeric expression,
2040 it is tested whether it is an mdoc macro name, and the
2041 default offset value associated with this macro is
2042 used. Finally, if all tests fail, the width of
2043 ⟨string⟩ (typeset with a fixed-width font) is taken as
2044 the offset.
2045
2046 -compact Suppress insertion of vertical space before the list
2047 and between list items.
2048
2050 A double handful of macros fit only uncomfortably into one of the above
2051 sections. Of these, we couldn't find attested examples for ‘Me’ or ‘Ot’.
2052 They are documented here for completeness—if you know their proper usage,
2053 please send a mail to groff@gnu.org and include a specimen with its
2054 provenance.
2055
2056 .Bt formats boilerplate text.
2057
2058 .Bt → is currently in beta test.
2059
2060 It is neither callable nor parsed and takes no arguments. Its de‐
2061 fault width is 6n.
2062
2063 .Fr is an obsolete means of specifying a function return value.
2064
2065 Usage: .Fr return-value ...
2066
2067 ‘Fr’ allows a break right before the return value (usually a single
2068 digit) which is bad typographical behaviour. Instead, set the re‐
2069 turn value with the rest of the code, using ‘\~’ to tie the return
2070 value to the previous word.
2071
2072 Its default width is 12n.
2073
2074 .Hf Inlines the contents of a (header) file into the document.
2075
2076 Usage: .Hf file
2077
2078 It first prints ‘File:’ followed by the file name, then the contents
2079 of file. It is neither callable nor parsed.
2080
2081 .Lk Embed hyperlink.
2082
2083 Usage: .Lk uri [link-text]
2084
2085 Its default width is 6n.
2086
2087 .Me Usage unknown. The mdoc sources describe it as a macro for “menu
2088 entries”.
2089
2090 Its default width is 6n.
2091
2092 .Mt Embed email address.
2093
2094 Usage: .Mt email-address
2095
2096 Its default width is 6n.
2097
2098 .Ot Usage unknown. The mdoc sources describe it as “old function type
2099 (fortran)”.
2100
2101 .Sm Manipulate or toggle argument-spacing mode.
2102
2103 Usage: .Sm [on | off] ...
2104
2105 If argument-spacing mode is off, no spaces between macro arguments
2106 are inserted. If called without a parameter (or if the next parame‐
2107 ter is neither ‘on’ nor ‘off’), ‘Sm’ toggles argument-spacing mode.
2108
2109 Its default width is 8n.
2110
2111 .Ud formats boilerplate text.
2112
2113 .Ud → currently under development.
2114
2115 It is neither callable nor parsed and takes no arguments. Its de‐
2116 fault width is 8n.
2117
2119 The following strings are predefined for compatibility with legacy mdoc
2120 documents. Contemporary ones should use the alternatives shown in the
2121 “Prefer” column below. See groff_char(7) for a full discussion of these
2122 special character escape sequences.
2123
2124 String 7-bit 8-bit UCS Prefer Meaning
2125 \*(<= <= <= ≤ \(<= less than or equal to
2126 \*(>= >= >= ≥ \(>= greater than or equal to
2127 \*(Rq " " ” \(rq right double quote
2128 \*(Lq " " “ \(lq left double quote
2129 \*(ua ^ ^ ↑ \(ua vertical arrow up
2130 \*(aa ' ´ ´ \(aa acute accent
2131 \*(ga ` ` ` \(ga grave accent
2132 \*(q " " " \(dq neutral double quote
2133 \*(Pi pi pi π \(*p lowercase pi
2134 \*(Ne != != ≠ \(!= not equals
2135 \*(Le <= <= ≤ \(<= less than or equal to
2136 \*(Ge >= >= ≥ \(>= greater than or equal to
2137 \*(Lt < < < < less than
2138 \*(Gt > > > > greater than
2139 \*(Pm +- ± ± \(+- plus or minus
2140 \*(If infinity infinity ∞ \(if infinity
2141 \*(Am & & & & ampersand
2142 \*(Na NaN NaN NaN NaN not a number
2143 \*(Ba | | | | bar
2144
2145 Some column headings are shorthand for standardized character encodings;
2146 “7-bit” for ISO 646:1991 IRV (US-ASCII), “8-bit” for ISO 8859-1 (Latin-1)
2147 and IBM code page 1047, and “UCS” for ISO 10646 (Unicode character set).
2148 Historically, mdoc configured the string definitions to fit the capabili‐
2149 ties expected of the output device. Old typesetters lacked directional
2150 double quotes, producing repeated directional single quotes ‘‘like
2151 this’’; early versions of mdoc in fact defined the ‘Lq’ and ‘Rq’ strings
2152 this way. Nowadays, output drivers take on the responsibility of glyph
2153 substitution, as they possess relevant knowledge of their available
2154 repertoires.
2155
2157 The debugging macro ‘.Db’ offered by previous versions of mdoc is un‐
2158 available in GNU troff(1) since the latter provides better facilities to
2159 check parameters; additionally, groff mdoc implements many error and
2160 warning messages, making the package more robust and more verbose.
2161
2162 The remaining debugging macro is ‘.Rd’, which dumps the package's global
2163 register and string contents to the standard error stream. A normal user
2164 will never need it.
2165
2167 The following groff options set registers (with -r) and strings (with -d)
2168 recognized and used by the mdoc macro package. To ensure rendering con‐
2169 sistent with output device capabilities and reader preferences, man pages
2170 should never manipulate them.
2171
2172 Setting string ‘AD’ configures the adjustment mode for most formatted
2173 text. Typical values are ‘b’ for adjustment to both margins (the de‐
2174 fault), or ‘l’ for left alignment (ragged right margin). Any valid argu‐
2175 ment to groff's ‘ad’ request may be used. See groff(7) for less-common
2176 choices.
2177 groff -Tutf8 -dAD=l -mdoc groff_mdoc.7 | less -R
2178
2179 Setting register ‘C’ to 1 numbers output pages consecutively, rather than
2180 resetting the page number to 1 (or the value of register ‘P’) with each
2181 new mdoc document.
2182
2183 By default, the package inhibits page breaks, headers, and footers in the
2184 midst of the document text if it is being displayed with a terminal de‐
2185 vice such as ‘latin1’ or ‘utf8’, to enable more efficient viewing of the
2186 page. This behavior can be changed to format the page as if for 66-line
2187 Teletype output by setting the continuous rendering register ‘cR’ to zero
2188 while calling groff(1).
2189 groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
2190 On HTML devices, it cannot be disabled.
2191
2192 Section headings (defined with ‘.Sh’) and page titles in headers (defined
2193 with ‘.Dt’) can be presented in full capitals by setting the registers
2194 ‘CS’ and ‘CT’, respectively, to 1. These transformations are off by de‐
2195 fault because they discard case distinction information.
2196
2197 Setting register ‘D’ to 1 enables double-sided page layout, which is only
2198 distinct when not continuously rendering. It places the page number at
2199 the bottom right on odd-numbered (recto) pages, and at the bottom left on
2200 even-numbered (verso) pages, swapping places with the arguments to ‘.Os’.
2201 groff -Tps -rD1 -mdoc foo.man > foo.ps
2202
2203 The value of the ‘FT’ register determines the footer's distance from the
2204 page bottom; this amount is always negative and should specify a scaling
2205 unit. At one half-inch above this location, the page text is broken be‐
2206 fore writing the footer. It is ignored if continuous rendering is en‐
2207 abled. The default is -0.5i.
2208
2209 The ‘HF’ string sets the font used for section and subsection headings;
2210 the default is ‘B’ (bold style of the default family). Any valid argu‐
2211 ment to groff's ‘ft’ request may be used.
2212
2213 Normally, automatic hyphenation is enabled using a mode appropriate to
2214 the groff locale; see section “Localization“ of groff(7). It can be dis‐
2215 abled by setting the ‘HY’ register to zero.
2216 groff -Tutf8 -rHY=0 -mdoc foo.man | less -R
2217
2218 The paragraph and subsection heading indentation amounts can be changed
2219 by setting the registers ‘IN’ and ‘SN’.
2220 groff -Tutf8 -rIN=5n -rSN=2n -mdoc foo.man | less -R
2221 The default paragraph indentation is 7.2n on typesetters and 7n on termi‐
2222 nals. The default subsection heading indentation amount is 3n; section
2223 headings are set with an indentation of zero.
2224
2225 The line and title lengths can be changed by setting the registers ‘LL’
2226 and ‘LT’, respectively:
2227 groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less -R
2228 If not set, both registers default to 78n for terminal devices and 6.5i
2229 otherwise.
2230
2231 Setting the ‘P’ register starts enumeration of pages at its value. The
2232 default is 1.
2233
2234 To change the document font size to 11p or 12p, set register ‘S’ accord‐
2235 ingly:
2236 groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
2237 Register ‘S’ is ignored when formatting for terminal devices.
2238
2239 Setting the ‘X’ register to a page number p numbers its successors as pa,
2240 pb, pc, and so forth. The register tracking the suffixed page letter
2241 uses format ‘a’ (see the ‘af’ request in groff(7)).
2242
2243
2244
2245
2247 /usr/share/groff/1.23.0/tmac/andoc.tmac
2248 This brief groff program detects whether the man or mdoc macro
2249 package is being used by a document and loads the correct macro
2250 definitions, taking advantage of the fact that pages using them
2251 must call TH or Dd, respectively, before any other macros. A
2252 user typing, for example,
2253 groff -mandoc page.1
2254 need not know which package the file page.1 uses. Multiple man
2255 pages, in either format, can be handled; andoc.tmac reloads each
2256 macro package as necessary.
2257
2258 /usr/share/groff/1.23.0/tmac/doc.tmac
2259 implements the bulk of the groff mdoc package and loads further
2260 components as needed from the mdoc subdirectory.
2261
2262 /usr/share/groff/1.23.0/tmac/mdoc.tmac
2263 is a wrapper that loads doc.tmac.
2264
2265 /usr/share/groff/1.23.0/tmac/mdoc/doc-common
2266 defines macros, registers, and strings concerned with the produc‐
2267 tion of formatted output. It includes strings of the form
2268 ‘doc-volume-ds-X’ and ‘doc-volume-as-X’ for manual section titles
2269 and architecture identifiers, respectively, where X is an argu‐
2270 ment recognized by .Dt.
2271
2272 /usr/share/groff/1.23.0/tmac/mdoc/doc-nroff
2273 defines parameters appropriate for rendering to terminal devices.
2274
2275 /usr/share/groff/1.23.0/tmac/mdoc/doc-ditroff
2276 defines parameters appropriate for rendering to typesetter de‐
2277 vices.
2278
2279 /usr/share/groff/1.23.0/tmac/mdoc/doc-syms
2280 defines many strings and macros that interpolate formatted text,
2281 such as names of operating system releases, *BSD libraries, and
2282 standards documents. The string names are of the form
2283 ‘doc-str-O-V’, ‘doc-str-St--S-I’ (observe the double dashes), or
2284 ‘doc-str-Lb-L’, where O is one of the operating system macros
2285 from section General text domain above, V is an encoding of an
2286 operating system release (sometimes omitted along with the ‘-’
2287 preceding it), S an identifier for a standards body or committee,
2288 I one for an issue of a standard promulgated by S, and L a key‐
2289 word identifying a *BSD library.
2290
2291 /etc/groff/site-tmac/mdoc.local
2292 This file houses local additions and customizations to the pack‐
2293 age. It can be empty.
2294
2296 The mandoc: https://mandoc.bsd.lv/ project maintains an independent im‐
2297 plementation of the mdoc language and a renderer that directly parses its
2298 markup as well as that of man.
2299
2300 groff(1), man(1), troff(1), groff_man(7), mdoc(7)
2301
2303 Section 3f has not been added to the header routines.
2304
2305 ‘.Fn’ needs to have a check to prevent splitting up the line if its
2306 length is too short. Occasionally it separates the last parenthesis, and
2307 sometimes looks ridiculous if output lines are being filled.
2308
2309 The list and display macros do not do any keeps and certainly should be
2310 able to.
2311
2312 As of groff 1.23, ‘Tn’ no longer changes the type size; this functional‐
2313 ity may return in the next release.
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376