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