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