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 .Os [OPERATING_SYSTEM] [version/release]
283 .Dt DOCUMENT_TITLE [section number] [architecture/volume]
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 The first items in the template are the commands ‘.Dd’, ‘.Os’, and ‘.Dt’;
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 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 Example:
336 .Xx ⟨foo⟩ {bar1 | bar2} [-test1 [-test2 | -test3]] ...
338 Except stated explicitly, all macros are parsed and callable.
340 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 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 .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 Under BSD, the following sections are defined:
370 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 A volume name may be arbitrary or one of the following:
382 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 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 alpha, acorn26, acorn32, algor, amd64, amiga, arc, arm26,
402 arm32, atari, bebox, cats, cesfic, cobalt, dreamcast,
403 evbarm, evbmips, evbppc, evbsh3, hp300, hp700, hpcmips,
404 i386, luna68k, m68k, mac68k, macppc, mips, mmeye, mvme68k,
405 mvmeppc, netwinder, news68k, newsmips, next68k, ofppc,
406 pc532, pmax, pmppc, powerpc, prep, sandpoint, sgimips, sh3,
407 shark, sparc, sparc64, sun3, tahoe, vax, x68k, x86_64
408 If the section number is neither a numeric expression in the
410 range 1 to 9 nor one of the above described keywords, the third
411 parameter is used verbatim as the volume name.
412 In the following examples, the left (which is identical to the
414 right) and the middle part of the manual page header strings are
415 shown. Note how ‘\&’ prevents the digit 7 from being a valid
416 numeric expression.
417 .Dt FOO 7 ‘FOO(7)’ ‘BSD Miscellaneous Information
419 Manual’
420 .Dt FOO 7 bar ‘FOO(7)’ ‘BSD Miscellaneous Information
421 Manual’
422 .Dt FOO \&7 bar
423 ‘FOO(7)’ ‘bar’
424 .Dt FOO 2 i386 ‘FOO(2)’ ‘BSD/i386 System Calls Manual’
425 .Dt FOO "" bar ‘FOO’ ‘bar’
426 Local, OS-specific additions might be found in the file
428 mdoc.local; look for strings named ‘volume-ds-XXX’ (for the for‐
429 mer type) and ‘volume-as-XXX’ (for the latter type); ‘XXX’ then
430 denotes the keyword to be used with the ‘.Dt’ macro.
431 This macro is neither callable nor parsed.
433 .Os [⟨operating system⟩] [⟨release⟩]
435 If the first parameter is empty, the default ‘BSD’ is used. This
436 may be overridden in the local configuration file, mdoc.local.
437 In general, the name of the operating system should be the common
438 acronym, e.g. BSD or ATT. The release should be the standard
439 release nomenclature for the system specified. In the following
440 table, the possible second arguments for some predefined operat‐
441 ing systems are listed. Similar to ‘.Dt’, local additions might
442 be defined in mdoc.local; look for strings named
443 ‘operating-system-XXX-YYY’, where ‘XXX’ is the acronym for the
444 operating system and ‘YYY’ the release ID.
445 ATT 7th, 7, III, 3, V, V.2, V.3, V.4
447 BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
449 NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
451 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.4.1,
452 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.6,
453 1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3,
454 2.1, 3.0, 3.0.1, 3.0.2, 3.1, 4.0, 4.0.1
455 FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5,
457 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6,
458 2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0,
459 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7,
460 4.8, 4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3,
461 5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4, 7.0, 7.1
462 DragonFly
464 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.8, 1.8.1,
465 1.10, 1.12, 1.12.2, 2.0
466 Darwin 8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0,
468 8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0, 9.0.0, 9.1.0,
469 9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0
470 For ATT, an unknown second parameter will be replaced with the
472 string UNIX; for the other predefined acronyms it will be ignored
473 and a warning message emitted. Unrecognized arguments are dis‐
474 played as given in the page footer. For instance, a typical
475 footer might be:
476 .Os BSD 4.3
478 giving ‘4.3 Berkeley Distribution’, or for a locally produced set
480 .Os CS Department
482 which will produce ‘CS Department’.
484 If the ‘.Os’ macro is not present, the bottom left corner of the
486 manual page will be ugly.
487 This macro is neither callable nor parsed.
489 .Dd [⟨month⟩ ⟨day⟩, ⟨year⟩]
491 If ‘Dd’ has no arguments, ‘Epoch’ is used for the date string.
492 If it has exactly three arguments, they are concatenated, sepa‐
493 rated with unbreakable space:
494 .Dd January 25, 2001
496 The month's name shall not be abbreviated.
498 With any other number of arguments, the current date is used,
500 ignoring the parameters.
501 This macro is neither callable nor parsed.
503
505 What's in a Name...
506 The manual domain macro names are derived from the day to day informal
507 language used to describe commands, subroutines and related files.
508 Slightly different variations of this language are used to describe the
509 three different aspects of writing a man page. First, there is the
510 description of -mdoc macro command usage. Second is the description of a
511 UNIX command with -mdoc macros, and third, the description of a command
512 to a user in the verbal sense; that is, discussion of a command in the
513 text of a man page.
514 In the first case, troff(1) macros are themselves a type of command; the
516 general syntax for a troff command is:
517 .Xx argument1 argument2 ...
519 ‘.Xx’ is a macro command, and anything following it are arguments to be
521 processed. In the second case, the description of a UNIX command using
522 the content macros is a bit more involved; a typical SYNOPSIS command
523 line might be displayed as:
524 filter [-flag] ⟨infile⟩ ⟨outfile⟩
526 Here, filter is the command name and the bracketed string -flag is a flag
528 argument designated as optional by the option brackets. In -mdoc terms,
529 ⟨infile⟩ and ⟨outfile⟩ are called meta arguments; in this example, the
530 user has to replace the meta expressions given in angle brackets with
531 real file names. Note that in this document meta arguments are used to
532 describe -mdoc commands; in most man pages, meta variables are not
533 specifically written with angle brackets. The macros which formatted the
534 above example:
535 .Nm filter
537 .Op Fl flag
538 .Ao Ar infile Ac Ao Ar outfile Ac
539 In the third case, discussion of commands and command syntax includes
541 both examples above, but may add more detail. The arguments ⟨infile⟩ and
542 ⟨outfile⟩ from the example above might be referred to as operands or file
543 arguments. Some command line argument lists are quite long:
544 make [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I
546 directory] [-j max_jobs] [variable=value] [target ...]
547 Here one might talk about the command make and qualify the argument,
549 makefile, as an argument to the flag, -f, or discuss the optional file
550 operand target. In the verbal context, such detail can prevent confu‐
551 sion, however the -mdoc package does not have a macro for an argument to
552 a flag. Instead the ‘Ar’ argument macro is used for an operand or file
553 argument like target as well as an argument to a flag like variable. The
554 make command line was produced from:
555 .Nm make
557 .Op Fl eiknqrstv
558 .Op Fl D Ar variable
559 .Op Fl d Ar flags
560 .Op Fl f Ar makefile
561 .Op Fl I Ar directory
562 .Op Fl j Ar max_jobs
563 .Op Ar variable Ns = Ns Ar value
564 .Bk
565 .Op Ar target ...
566 .Ek
567 The ‘.Bk’ and ‘.Ek’ macros are explained in Keeps.
569 General Syntax
571 The manual domain and general text domain macros share a similar syntax
572 with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’
573 differ only when called without arguments; and ‘.Fn’ and ‘.Xr’ impose an
574 order on their argument lists. All content macros are capable of recog‐
575 nizing and properly handling punctuation, provided each punctuation char‐
576 acter is separated by a leading space. If a command is given:
577 .Ar sptr, ptr),
579 The result is:
581 sptr, ptr),
583 The punctuation is not recognized and all is output in the font used by
585 ‘.Ar’. If the punctuation is separated by a leading white space:
586 .Ar sptr , ptr ) ,
588 The result is:
590 sptr, ptr),
592 The punctuation is now recognized and output in the default font distin‐
594 guishing it from the argument strings. To remove the special meaning
595 from a punctuation character escape it with ‘\&’.
596 The following punctuation characters are recognized by -mdoc:
598 . , : ; (
600 ) [ ] ? !
601 Troff is limited as a macro language, and has difficulty when presented
603 with a string containing a member of the mathematical, logical or quota‐
604 tion set:
605 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
607 The problem is that troff may assume it is supposed to actually perform
609 the operation or evaluation suggested by the characters. To prevent the
610 accidental evaluation of these characters, escape them with ‘\&’. Typi‐
611 cal syntax is shown in the first content macro displayed below, ‘.Ad’.
612
614 Addresses
615 The address macro identifies an address construct.
616 Usage: .Ad ⟨address⟩ ...
618 .Ad addr1 addr1
620 .Ad addr1 . addr1.
621 .Ad addr1 , file2 addr1, file2
622 .Ad f1 , f2 , f3 : f1, f2, f3:
623 .Ad addr ) ) , addr)),
624 The default width is 12n.
626 Author Name
628 The ‘.An’ macro is used to specify the name of the author of the item
629 being documented, or the name of the author of the actual manual page.
630 Usage: .An ⟨author name⟩ ...
632 .An "Joe Author" Joe Author
634 .An "Joe Author" , Joe Author,
636 .An "Joe Author" Aq nobody@FreeBSD.org
638 Joe Author <nobody@FreeBSD.org>
639 .An "Joe Author" ) ) , Joe Author)),
641 The default width is 12n.
643 In the AUTHORS section, the ‘.An’ command causes a line break allowing
645 each new name to appear on its own line. If this is not desirable,
646 .An -nosplit
648 call will turn this off. To turn splitting back on, write
650 .An -split
652 Arguments
654 The .Ar argument macro may be used whenever an argument is referenced.
655 If called without arguments, the ‘file ...’ string is output.
656 Usage: .Ar [⟨argument⟩] ...
658 .Ar file ...
660 .Ar file1 file1
661 .Ar file1 . file1.
662 .Ar file1 file2 file1 file2
663 .Ar f1 f2 f3 : f1 f2 f3:
664 .Ar file ) ) , file)),
665 The default width is 12n.
667 Configuration Declaration (Section Four Only)
669 The ‘.Cd’ macro is used to demonstrate a config(8) declaration for a
670 device interface in a section four manual.
671 Usage: .Cd ⟨argument⟩ ...
673 .Cd "device le0 at scode?" device le0 at scode?
675 In the SYNOPSIS section a ‘.Cd’ command causes a line break before and
677 after its arguments are printed.
678 The default width is 12n.
680 Command Modifiers
682 The command modifier is identical to the ‘.Fl’ (flag) command with the
683 exception that the ‘.Cm’ macro does not assert a dash in front of every
684 argument. Traditionally flags are marked by the preceding dash, however,
685 some commands or subsets of commands do not use them. Command modifiers
686 may also be specified in conjunction with interactive commands such as
687 editor commands. See Flags.
688 The default width is 10n.
690 Defined Variables
692 A variable (or constant) which is defined in an include file is specified
693 by the macro ‘.Dv’.
694 Usage: .Dv ⟨defined variable⟩ ...
696 .Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
698 .Dv TIOCGPGRP ) TIOCGPGRP)
699 The default width is 12n.
701 Errno's
703 The ‘.Er’ errno macro specifies the error return value for section 2, 3,
704 and 9 library routines. The second example below shows ‘.Er’ used with
705 the ‘.Bq’ general text domain macro, as it would be used in a section two
706 manual page.
707 Usage: .Er ⟨errno type⟩ ...
709 .Er ENOENT ENOENT
711 .Er ENOENT ) ; ENOENT);
712 .Bq Er ENOTDIR [ENOTDIR]
713 The default width is 17n.
715 Environment Variables
717 The ‘.Ev’ macro specifies an environment variable.
718 Usage: .Ev ⟨argument⟩ ...
720 .Ev DISPLAY DISPLAY
722 .Ev PATH . PATH.
723 .Ev PRINTER ) ) , PRINTER)),
724 The default width is 15n.
726 Flags
728 The ‘.Fl’ macro handles command line flags. It prepends a dash, ‘-’, to
729 the flag. For interactive command flags, which are not prepended with a
730 dash, the ‘.Cm’ (command modifier) macro is identical, but without the
731 dash.
732 Usage: .Fl ⟨argument⟩ ...
734 .Fl -
736 .Fl cfv -cfv
737 .Fl cfv . -cfv.
738 .Cm cfv . cfv.
739 .Fl s v t -s -v -t
740 .Fl - , --,
741 .Fl xyz ) , -xyz),
742 .Fl | - |
743 The ‘.Fl’ macro without any arguments results in a dash representing
745 stdin/stdout. Note that giving ‘.Fl’ a single dash will result in two
746 dashes.
747 The default width is 12n.
749 Function Declarations
751 The ‘.Fd’ macro is used in the SYNOPSIS section with section two or three
752 functions. It is neither callable nor parsed.
753 Usage: .Fd ⟨argument⟩ ...
755 .Fd "#include <sys/types.h>" #include <sys/types.h>
757 In the SYNOPSIS section a ‘.Fd’ command causes a line break if a function
759 has already been presented and a break has not occurred. This leaves a
760 nice vertical space in between the previous function call and the decla‐
761 ration for the next function.
762 The ‘.In’ macro, while in the SYNOPSIS section, represents the #include
764 statement, and is the short form of the above example. It specifies the
765 C header file as being included in a C program. It also causes a line
766 break.
767 While not in the SYNOPSIS section, it represents the header file enclosed
769 in angle brackets.
770 Usage: .In ⟨header file⟩
772 .In stdio.h #include <stdio.h>
774 .In stdio.h <stdio.h>
775 Function Types
777 This macro is intended for the SYNOPSIS section. It may be used anywhere
778 else in the man page without problems, but its main purpose is to present
779 the function type in kernel normal form for the SYNOPSIS of sections two
780 and three (it causes a line break, allowing the function name to appear
781 on the next line).
782 Usage: .Ft ⟨type⟩ ...
784 .Ft struct stat struct stat
786 Functions (Library Routines)
788 The ‘.Fn’ macro is modeled on ANSI C conventions.
789 Usage: .Fn ⟨function⟩ [⟨parameter⟩] ...
791 .Fn getchar getchar()
793 .Fn strlen ) , strlen()),
794 .Fn align "char *ptr" , align(char *ptr),
795 Note that any call to another macro signals the end of the ‘.Fn’ call (it
797 will insert a closing parenthesis at that point).
798 For functions with many parameters (which is rare), the macros ‘.Fo’
800 (function open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (func‐
801 tion argument).
802 Example:
804 .Ft int
806 .Fo res_mkquery
807 .Fa "int op"
808 .Fa "char *dname"
809 .Fa "int class"
810 .Fa "int type"
811 .Fa "char *data"
812 .Fa "int datalen"
813 .Fa "struct rrec *newrr"
814 .Fa "char *buf"
815 .Fa "int buflen"
816 .Fc
817 Produces:
819 int res_mkquery(int op, char *dname, int class, int type,
821 char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
822 In the SYNOPSIS section, the function will always begin at the beginning
824 of line. If there is more than one function presented in the SYNOPSIS
825 section and a function type has not been given, a line break will occur,
826 leaving a nice vertical space between the current function name and the
827 one prior.
828 The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respec‐
830 tively.
831 Function Arguments
833 The ‘.Fa’ macro is used to refer to function arguments (parameters) out‐
834 side of the SYNOPSIS section of the manual or inside the SYNOPSIS section
835 if the enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used. ‘.Fa’
836 may also be used to refer to structure members.
837 Usage: .Fa ⟨function argument⟩ ...
839 .Fa d_namlen ) ) , d_namlen)),
841 .Fa iov_len iov_len
842 The default width is 12n.
844 Return Values
846 The ‘.Rv’ macro generates text for use in the RETURN VALUES section.
847 Usage: .Rv [-std] [⟨function⟩ ...]
849 For example, ‘.Rv -std atexit’ produces:
851 The atexit() function returns the value 0 if successful; otherwise
853 the value -1 is returned and the global variable errno is set to
854 indicate the error.
855 The -std option is valid only for manual page sections 2 and 3. Cur‐
857 rently, this macro does nothing if used without the -std flag.
858 Exit Status
860 The ‘.Ex’ macro generates text for use in the DIAGNOSTICS section.
861 Usage: .Ex [-std] [⟨utility⟩ ...]
863 For example, ‘.Ex -std cat’ produces:
865 The cat utility exits 0 on success, and >0 if an error occurs.
867 The -std option is valid only for manual page sections 1, 6 and 8. Cur‐
869 rently, this macro does nothing if used without the -std flag.
870 Interactive Commands
872 The ‘.Ic’ macro designates an interactive or internal command.
873 Usage: .Ic ⟨argument⟩ ...
875 .Ic :wq :wq
877 .Ic "do while {...}" do while {...}
878 .Ic setenv , unsetenv setenv, unsetenv
879 The default width is 12n.
881 Library Names
883 The ‘.Lb’ macro is used to specify the library where a particular func‐
884 tion is compiled in.
885 Usage: .Lb ⟨argument⟩ ...
887 Available arguments to ‘.Lb’ and their results are:
889 libarm ARM Architecture Library (libarm, -larm)
891 libarm32 ARM32 Architecture Library (libarm32, -larm32)
892 libc Standard C Library (libc, -lc)
893 libcdk Curses Development Kit Library (libcdk, -lcdk)
894 libcompat Compatibility Library (libcompat, -lcompat)
895 libcrypt Crypt Library (libcrypt, -lcrypt)
896 libcurses Curses Library (libcurses, -lcurses)
897 libedit Command Line Editor Library (libedit, -ledit)
898 libevent Event Notification Library (libevent, -levent)
899 libform Curses Form Library (libform, -lform)
900 libi386 i386 Architecture Library (libi386, -li386)
901 libintl Internationalized Message Handling Library (libintl,
902 -lintl)
903 libipsec IPsec Policy Control Library (libipsec, -lipsec)
904 libkvm Kernel Data Access Library (libkvm, -lkvm)
905 libm Math Library (libm, -lm)
906 libm68k m68k Architecture Library (libm68k, -lm68k)
907 libmagic Magic Number Recognition Library (libmagic, -lmagic)
908 libmenu Curses Menu Library (libmenu, -lmenu)
909 libossaudio OSS Audio Emulation Library (libossaudio, -lossaudio)
910 libpam Pluggable Authentication Module Library (libpam,
911 -lpam)
912 libpcap Packet Capture Library (libpcap, -lpcap)
913 libpci PCI Bus Access Library (libpci, -lpci)
914 libpmc Performance Counters Library (libpmc, -lpmc)
915 libposix POSIX Compatibility Library (libposix, -lposix)
916 libpthread POSIX Threads Library (libpthread, -lpthread)
917 libresolv DNS Resolver Library (libresolv, -lresolv)
918 librt POSIX Real-time Library (librt, -lrt)
919 libtermcap Termcap Access Library (libtermcap, -ltermcap)
920 libusbhid USB Human Interface Devices Library (libusbhid,
921 -lusbhid)
922 libutil System Utilities Library (libutil, -lutil)
923 libx86_64 x86_64 Architecture Library (libx86_64, -lx86_64)
924 libz Compression Library (libz, -lz)
925 Local, OS-specific additions might be found in the file mdoc.local; look
927 for strings named ‘str-Lb-XXX’. ‘XXX’ then denotes the keyword to be
928 used with the ‘.Lb’ macro.
929 In the LIBRARY section an ‘.Lb’ command causes a line break before and
931 after its arguments are printed.
932 Literals
934 The ‘.Li’ literal macro may be used for special characters, variable con‐
935 stants, etc. - anything which should be displayed as it would be typed.
936 Usage: .Li ⟨argument⟩ ...
938 .Li \en \n
940 .Li M1 M2 M3 ; M1 M2 M3;
941 .Li cntrl-D ) , cntrl-D),
942 .Li 1024 ... 1024 ...
943 The default width is 16n.
945 Names
947 The ‘.Nm’ macro is used for the document title or subject name. It has
948 the peculiarity of remembering the first argument it was called with,
949 which should always be the subject name of the page. When called without
950 arguments, ‘.Nm’ regurgitates this initial name for the sole purpose of
951 making less work for the author. Note: A section two or three document
952 function name is addressed with the ‘.Nm’ in the NAME section, and with
953 ‘.Fn’ in the SYNOPSIS and remaining sections. For interactive commands,
954 such as the ‘while’ command keyword in csh(1), the ‘.Ic’ macro should be
955 used. While ‘.Ic’ is nearly identical to ‘.Nm’, it can not recall the
956 first argument it was invoked with.
957 Usage: .Nm [⟨argument⟩] ...
959 .Nm groff_mdoc groff_mdoc
961 .Nm \-mdoc -mdoc
962 .Nm foo ) ) , foo)),
963 .Nm : groff_mdoc:
964 The default width is 10n.
966 Options
968 The ‘.Op’ macro places option brackets around any remaining arguments on
969 the command line, and places any trailing punctuation outside the brack‐
970 ets. The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a closing
971 option bracket respectively) may be used across one or more lines or to
972 specify the exact position of the closing parenthesis.
973 Usage: .Op [⟨option⟩] ...
975 .Op []
977 .Op Fl k [-k]
978 .Op Fl k ) . [-k]).
979 .Op Fl k Ar kookfile [-k kookfile]
980 .Op Fl k Ar kookfile , [-k kookfile],
981 .Op Ar objfil Op Ar corfil [objfil [corfil]]
982 .Op Fl c Ar objfil Op Ar corfil , [-c objfil [corfil]],
983 .Op word1 word2 [word1 word2]
984 .Li .Op Oo Ao option Ac Oc ... .Op [⟨option⟩] ...
985 Here a typical example of the ‘.Oo’ and ‘.Oc’ macros:
987 .Oo
989 .Op Fl k Ar kilobytes
990 .Op Fl i Ar interval
991 .Op Fl c Ar count
992 .Oc
993 Produces:
995 [[-k kilobytes] [-i interval] [-c count]]
997 The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respec‐
999 tively.
1000 Pathnames
1002 The ‘.Pa’ macro formats path or file names. If called without arguments,
1003 the ‘~’ string is output, which represents the current user's home direc‐
1004 tory.
1005 Usage: .Pa [⟨pathname⟩] ...
1007 .Pa ~
1009 .Pa /usr/share /usr/share
1010 .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).
1011 The default width is 32n.
1013 Standards
1015 The ‘.St’ macro replaces standard abbreviations with their formal names.
1016 Usage: .St ⟨abbreviation⟩ ...
1018 Available pairs for “Abbreviation/Formal Name” are:
1020 ANSI/ISO C
1022 -ansiC ANSI X3.159-1989 (“ANSI C89”)
1024 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
1025 -isoC ISO/IEC 9899:1990 (“ISO C90”)
1026 -isoC-90 ISO/IEC 9899:1990 (“ISO C90”)
1027 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
1028 POSIX Part 1: System API
1030 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1032 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1033 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
1034 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
1035 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1036 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1037 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
1038 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
1039 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
1040 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
1041 -p1003.1-2001 IEEE Std 1003.1-2001 (“POSIX.1”)
1042 -p1003.1-2004 IEEE Std 1003.1-2004 (“POSIX.1”)
1043 POSIX Part 2: Shell and Utilities
1045 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
1047 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
1048 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
1049 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
1050 X/Open
1052 -susv2 Version 2 of the Single UNIX Specification
1054 (“SUSv2”)
1055 -susv3 Version 3 of the Single UNIX Specification
1056 (“SUSv3”)
1057 -svid4 System V Interface Definition, Fourth Edition
1058 (“SVID4”)
1059 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
1060 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
1061 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1062 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
1063 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1064 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1065 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1066 -xpg4.2 X/Open Portability Guide Issue 4, Version 2
1067 (“XPG4.2”)
1068 -xsh5 X/Open System Interfaces and Headers Issue 5
1069 (“XSH5”)
1070 Miscellaneous
1072 -ieee754 IEEE Std 754-1985
1074 -iso8802-3 ISO/IEC 8802-3:1989
1075 Variable Types
1077 The ‘.Vt’ macro may be used whenever a type is referenced. In the
1078 SYNOPSIS section, it causes a line break (useful for old style variable
1079 declarations).
1080 Usage: .Vt ⟨type⟩ ...
1082 .Vt extern char *optarg ; extern char *optarg;
1084 .Vt FILE * FILE *
1085 Variables
1087 Generic variable reference.
1088 Usage: .Va ⟨variable⟩ ...
1090 .Va count count
1092 .Va settimer , settimer,
1093 .Va "int *prt" ) : int *prt):
1094 .Va "char s" ] ) ) , char s])),
1095 The default width is 12n.
1097 Manual Page Cross References
1099 The ‘.Xr’ macro expects the first argument to be a manual page name. The
1100 optional second argument, if a string (defining the manual section), is
1101 put into parentheses.
1102 Usage: .Xr ⟨man page name⟩ [⟨section⟩] ...
1104 .Xr mdoc mdoc
1106 .Xr mdoc , mdoc,
1107 .Xr mdoc 7 mdoc(7)
1108 .Xr xinit 1x ; xinit(1x);
1109 The default width is 10n.
1111
1113 AT&T Macro
1114 Usage: .At [⟨version⟩] ...
1115 .At AT&T UNIX
1117 .At v6 . Version 6 AT&T UNIX.
1118 The following values for ⟨version⟩ are possible:
1120 32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4
1122 BSD Macro
1124 Usage: .Bx {-alpha | -beta | -devel} ...
1125 .Bx [⟨version⟩ [⟨release⟩]] ...
1126 .Bx BSD
1128 .Bx 4.3 . 4.3BSD.
1129 .Bx -devel BSD (currently under development)
1130 ⟨version⟩ will be prepended to the string ‘BSD’. The following values
1132 for ⟨release⟩ are possible:
1133 Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
1135 NetBSD Macro
1137 Usage: .Nx [⟨version⟩] ...
1138 .Nx NetBSD
1140 .Nx 1.4 . NetBSD 1.4.
1141 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1143 above in section TITLE MACROS.
1144 FreeBSD Macro
1146 Usage: .Fx [⟨version⟩] ...
1147 .Fx FreeBSD
1149 .Fx 2.2 . FreeBSD 2.2.
1150 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1152 above in section TITLE MACROS.
1153 DragonFly Macro
1155 Usage: .Dx [⟨version⟩] ...
1156 .Dx DragonFly
1158 .Dx 1.4 . DragonFly 1.4.
1159 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1161 above in section TITLE MACROS.
1162 OpenBSD Macro
1164 Usage: .Ox [⟨version⟩] ...
1165 .Ox 1.0 OpenBSD 1.0
1167 BSD/OS Macro
1169 Usage: .Bsx [⟨version⟩] ...
1170 .Bsx 1.0 BSD/OS 1.0
1172 UNIX Macro
1174 Usage: .Ux ...
1175 .Ux UNIX
1177 Emphasis Macro
1179 Text may be stressed or emphasized with the ‘.Em’ macro. The usual font
1180 for emphasis is italic.
1181 Usage: .Em ⟨argument⟩ ...
1183 .Em does not does not
1185 .Em exceed 1024 . exceed 1024.
1186 .Em vide infra ) ) , vide infra)),
1187 The default width is 10n.
1189 Font Mode
1191 The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes
1192 no arguments). Font modes may be nested within other font modes.
1193 ‘.Bf’ has the following syntax:
1195 .Bf ⟨font mode⟩
1197 ⟨font mode⟩ must be one of the following three types:
1199 Em | -emphasis Same as if the ‘.Em’ macro was used for the entire
1201 block of text.
1202 Li | -literal Same as if the ‘.Li’ macro was used for the entire
1203 block of text.
1204 Sy | -symbolic Same as if the ‘.Sy’ macro was used for the entire
1205 block of text.
1206 Both macros are neither callable nor parsed.
1208 Enclosure and Quoting Macros
1210 The concept of enclosure is similar to quoting. The object being to
1211 enclose one or more strings between a pair of characters like quotes or
1212 parentheses. The terms quoting and enclosure are used interchangeably
1213 throughout this document. Most of the one-line enclosure macros end in
1214 small letter ‘q’ to give a hint of quoting, but there are a few irregu‐
1215 larities. For each enclosure macro there is also a pair of open and
1216 close macros which end in small letters ‘o’ and ‘c’ respectively.
1217 Quote Open Close Function Result
1219 .Aq .Ao .Ac Angle Bracket Enclosure ⟨string⟩
1220 .Bq .Bo .Bc Bracket Enclosure [string]
1221 .Brq .Bro .Brc Brace Enclosure {string}
1222 .Dq .Do .Dc Double Quote “string”
1223 .Eq .Eo .Ec Enclose String (in XX) XXstringXX
1224 .Pq .Po .Pc Parenthesis Enclosure (string)
1225 .Ql Quoted Literal ‘string’ or string
1226 .Qq .Qo .Qc Straight Double Quote "string"
1227 .Sq .So .Sc Single Quote ‘string’
1228 All macros ending with ‘q’ and ‘o’ have a default width value of 12n.
1230 .Eo, .Ec These macros expect the first argument to be the opening and
1232 closing strings respectively.
1233 .Es, .En Due to the nine-argument limit in the original troff program
1235 two other macros have been implemented which are now rather
1236 obsolete: ‘.Es’ takes the first and second parameter as the
1237 left and right enclosure string, which are then used to enclose
1238 the arguments of ‘.En’. The default width value is 12n for
1239 both macros.
1240 .Eq The first and second arguments of this macro are the opening
1242 and closing strings respectively, followed by the arguments to
1243 be enclosed.
1244 .Ql The quoted literal macro behaves differently in troff and nroff
1246 mode. If formatted with nroff, a quoted literal is always
1247 quoted. If formatted with troff, an item is only quoted if the
1248 width of the item is less than three constant width characters.
1249 This is to make short strings more visible where the font
1250 change to literal (constant width) is less noticeable.
1251 The default width is 16n.
1253 .Pf The prefix macro suppresses the whitespace between its first
1255 and second argument:
1256 .Pf ( Fa name2 (name2
1258 The default width is 12n.
1260 The ‘.Ns’ macro (see below) performs the analogous suffix func‐
1262 tion.
1263 .Ap The ‘.Ap’ macro inserts an apostrophe and exits any special
1265 text modes, continuing in ‘.No’ mode.
1266 Examples of quoting:
1268 .Aq ⟨⟩
1270 .Aq Pa ctype.h ) , ⟨ctype.h⟩),
1271 .Bq []
1272 .Bq Em Greek , French . [Greek, French].
1273 .Dq “”
1274 .Dq string abc . “string abc”.
1275 .Dq ´^[A-Z]´ “´^[A-Z]´”
1276 .Ql man mdoc ‘man mdoc’
1277 .Qq ""
1278 .Qq string ) , "string"),
1279 .Qq string Ns ), "string),"
1280 .Sq ‘’
1281 .Sq string ‘string’
1282 .Em or Ap ing or'ing
1283 For a good example of nested enclosure macros, see the ‘.Op’ option
1285 macro. It was created from the same underlying enclosure macros as those
1286 presented in the list above. The ‘.Xo’ and ‘.Xc’ extended argument list
1287 macros are discussed below.
1288 No-Op or Normal Text Macro
1290 The ‘.No’ macro can be used in a macro command line for parameters which
1291 should not be formatted. Be careful to add ‘\&’ to the word ‘No’ if you
1292 really want that English word (and not the macro) as a parameter.
1293 Usage: .No ⟨argument⟩ ...
1295 .No test Ta with Ta tabs test with tabs
1297 The default width is 12n.
1299 No-Space Macro
1301 The ‘.Ns’ macro suppresses insertion of a space between the current posi‐
1302 tion and its first parameter. For example, it is useful for old style
1303 argument lists where there is no space between the flag and argument:
1304 Usage: ... ⟨argument⟩ Ns [⟨argument⟩] ...
1306 .Ns ⟨argument⟩ ...
1307 .Op Fl I Ns Ar directory [-Idirectory]
1309 Note: The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating
1311 the space unless another macro name follows it. If used as a command
1312 (i.e., the second form above in the ‘Usage’ line), ‘.Ns’ is identical to
1313 ‘.No’.
1314 Section Cross References
1316 The ‘.Sx’ macro designates a reference to a section header within the
1317 same document.
1318 Usage: .Sx ⟨section reference⟩ ...
1320 .Sx FILES FILES
1322 The default width is 16n.
1324 Symbolics
1326 The symbolic emphasis macro is generally a boldface macro in either the
1327 symbolic sense or the traditional English usage.
1328 Usage: .Sy ⟨symbol⟩ ...
1330 .Sy Important Notice Important Notice
1332 The default width is 6n.
1334 Mathematical Symbols
1336 Use this macro for mathematical symbols and similar things.
1337 Usage: .Ms ⟨math symbol⟩ ...
1339 .Ms sigma sigma
1341 The default width is 6n.
1343 References and Citations
1345 The following macros make a modest attempt to handle references. At
1346 best, the macros make it convenient to manually drop in a subset of
1347 refer(1) style references.
1348 .Rs Reference start (does not take arguments). Causes a line
1350 break in the SEE ALSO section and begins collection of ref‐
1351 erence information until the reference end macro is read.
1352 .Re Reference end (does not take arguments). The reference is
1353 printed.
1354 .%A Reference author name; one name per invocation.
1355 .%B Book title.
1356 .%C City/place (not implemented yet).
1357 .%D Date.
1358 .%I Issuer/publisher name.
1359 .%J Journal name.
1360 .%N Issue number.
1361 .%O Optional information.
1362 .%P Page number.
1363 .%Q Corporate or foreign author.
1364 .%R Report name.
1365 .%T Title of article.
1366 .%V Volume.
1367 Macros beginning with ‘%’ are not callable but accept multiple arguments
1369 in the usual way. Only the ‘.Tn’ macro is handled properly as a parame‐
1370 ter; other macros will cause strange output. ‘.%B’ and ‘.%T’ can be used
1371 outside of the ‘.Rs/.Re’ environment.
1372 Example:
1374 .Rs
1376 .%A "Matthew Bar"
1377 .%A "John Foo"
1378 .%T "Implementation Notes on foobar(1)"
1379 .%R "Technical Report ABC-DE-12-345"
1380 .%Q "Drofnats College, Nowhere"
1381 .%D "April 1991"
1382 .Re
1383 produces
1385 Matthew Bar and John Foo, Implementation Notes on foobar(1),
1387 Technical Report ABC-DE-12-345, Drofnats College, Nowhere, April
1388 1991.
1389 Trade Names (or Acronyms and Type Names)
1391 The trade name macro prints its arguments in a smaller font. Its
1392 intended use is to imitate a small caps fonts for uppercase acronyms.
1393 Usage: .Tn ⟨symbol⟩ ...
1395 .Tn DEC DEC
1397 .Tn ASCII ASCII
1398 The default width is 10n.
1400 Extended Arguments
1402 The .Xo and .Xc macros allow one to extend an argument list on a macro
1403 boundary for the ‘.It’ macro (see below). Note that .Xo and .Xc are
1404 implemented similarly to all other macros opening and closing an enclo‐
1405 sure (without inserting characters, of course). This means that the fol‐
1406 lowing is true for those macros also.
1407 Here is an example of ‘.Xo’ using the space mode macro to turn spacing
1409 off:
1410 .Sm off
1412 .It Xo Sy I Ar operation
1413 .No \en Ar count No \en
1414 .Xc
1415 .Sm on
1416 produces
1418 Ioperation\ncount\n
1420 Another one:
1422 .Sm off
1424 .It Cm S No / Ar old_pattern Xo
1425 .No / Ar new_pattern
1426 .No / Op Cm g
1427 .Xc
1428 .Sm on
1429 produces
1431 S/old_pattern/new_pattern/[g]
1433 Another example of ‘.Xo’ and enclosure macros: Test the value of a vari‐
1435 able.
1436 .It Xo
1438 .Ic .ifndef
1439 .Oo \&! Oc Ns Ar variable Oo
1440 .Ar operator variable ...
1441 .Oc Xc
1442 produces
1444 .ifndef [!]variable [operator variable ...]
1446
1448 Section Headers
1449 The following ‘.Sh’ section header macros are required in every man page.
1450 The remaining section headers are recommended at the discretion of the
1451 author writing the manual page. The ‘.Sh’ macro is parsed but not gener‐
1452 ally callable. It can be used as an argument in a call to ‘.Sh’ only; it
1453 then reactivates the default font for ‘.Sh’.
1454 The default width is 8n.
1456 .Sh NAME The ‘.Sh NAME’ macro is mandatory. If not specified,
1458 headers, footers and page layout defaults will not be
1459 set and things will be rather unpleasant. The NAME
1460 section consists of at least three items. The first
1461 is the ‘.Nm’ name macro naming the subject of the man
1462 page. The second is the name description macro,
1463 ‘.Nd’, which separates the subject name from the third
1464 item, which is the description. The description
1465 should be the most terse and lucid possible, as the
1466 space available is small.
1467 ‘.Nd’ first prints ‘-’, then all its arguments.
1469 .Sh LIBRARY This section is for section two and three function
1471 calls. It should consist of a single ‘.Lb’ macro
1472 call; see Library Names.
1473 .Sh SYNOPSIS The SYNOPSIS section describes the typical usage of
1475 the subject of a man page. The macros required are
1476 either ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,
1477 ‘.Fc’, ‘.Fd’, and ‘.Ft’). The function name macro
1478 ‘.Fn’ is required for manual page sections 2 and 3;
1479 the command and general name macro ‘.Nm’ is required
1480 for sections 1, 5, 6, 7, and 8. Section 4 manuals
1481 require a ‘.Nm’, ‘.Fd’ or a ‘.Cd’ configuration device
1482 usage macro. Several other macros may be necessary to
1483 produce the synopsis line as shown below:
1484 cat [-benstuv] [-] file ...
1486 The following macros were used:
1488 .Nm cat
1490 .Op Fl benstuv
1491 .Op Fl
1492 .Ar
1493 .Sh DESCRIPTION In most cases the first text in the DESCRIPTION sec‐
1495 tion is a brief paragraph on the command, function or
1496 file, followed by a lexical list of options and
1497 respective explanations. To create such a list, the
1498 ‘.Bl’ (begin list), ‘.It’ (list item) and ‘.El’ (end
1499 list) macros are used (see Lists and Columns below).
1500 .Sh IMPLEMENTATION NOTES
1502 Implementation specific information should be placed
1503 here.
1504 .Sh RETURN VALUES Sections 2, 3 and 9 function return values should go
1506 here. The ‘.Rv’ macro may be used to generate text
1507 for use in the RETURN VALUES section for most section
1508 2 and 3 library functions; see Return Values.
1509 The following ‘.Sh’ section headers are part of the preferred manual page
1511 layout and must be used appropriately to maintain consistency. They are
1512 listed in the order in which they would be used.
1513 .Sh ENVIRONMENT The ENVIRONMENT section should reveal any related
1515 environment variables and clues to their behavior
1516 and/or usage.
1517 .Sh FILES Files which are used or created by the man page sub‐
1519 ject should be listed via the ‘.Pa’ macro in the FILES
1520 section.
1521 .Sh EXAMPLES There are several ways to create examples. See the
1523 EXAMPLES section below for details.
1524 .Sh DIAGNOSTICS Diagnostic messages from a command should be placed in
1526 this section. The ‘.Ex’ macro may be used to generate
1527 text for use in the DIAGNOSTICS section for most sec‐
1528 tion 1, 6 and 8 commands; see Exit Status.
1529 .Sh COMPATIBILITY Known compatibility issues (e.g. deprecated options or
1531 parameters) should be listed here.
1532 .Sh ERRORS Specific error handling, especially from library func‐
1534 tions (man page sections 2, 3, and 9) should go here.
1535 The ‘.Er’ macro is used to specify an error (errno).
1536 .Sh SEE ALSO References to other material on the man page topic and
1538 cross references to other relevant man pages should be
1539 placed in the SEE ALSO section. Cross references are
1540 specified using the ‘.Xr’ macro. Currently refer(1)
1541 style references are not accommodated.
1542 It is recommended that the cross references are sorted
1544 on the section number, then alphabetically on the
1545 names within a section, and placed in that order and
1546 comma separated. Example:
1547 ls(1), ps(1), group(5), passwd(5)
1549 .Sh STANDARDS If the command, library function or file adheres to a
1551 specific implementation such as IEEE Std 1003.2
1552 (“POSIX.2”) or ANSI X3.159-1989 (“ANSI C89”) this
1553 should be noted here. If the command does not adhere
1554 to any standard, its history should be noted in the
1555 HISTORY section.
1556 .Sh HISTORY Any command which does not adhere to any specific
1558 standards should be outlined historically in this sec‐
1559 tion.
1560 .Sh AUTHORS Credits should be placed here. Use the ‘.An’ macro
1562 for names and the ‘.Aq’ macro for e-mail addresses
1563 within optional contact information. Explicitly indi‐
1564 cate whether the person authored the initial manual
1565 page or the software or whatever the person is being
1566 credited for.
1567 .Sh BUGS Blatant problems with the topic go here.
1569 User-specified ‘.Sh’ sections may be added; for example, this section was
1571 set with:
1572 .Sh "PAGE STRUCTURE DOMAIN"
1574 Subsection Headers
1576 Subsection headers have exactly the same syntax as section headers: ‘.Ss’
1577 is parsed but not generally callable. It can be used as an argument in a
1578 call to ‘.Ss’ only; it then reactivates the default font for ‘.Ss’.
1579 The default width is 8n.
1581 Paragraphs and Line Spacing
1583 .Pp The ‘.Pp’ paragraph command may be used to specify a line space
1584 where necessary. The macro is not necessary after a ‘.Sh’ or ‘.Ss’
1585 macro or before a ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical
1586 distance unless the -compact flag is given).
1587 The macro is neither callable nor parsed and takes no arguments; an
1589 alternative name is ‘.Lp’.
1590 Keeps
1592 The only keep that is implemented at this time is for words. The macros
1593 are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep). The only option that ‘.Bk’
1594 accepts currently is -words (this is also the default if no option is
1595 given) which is useful for preventing line breaks in the middle of
1596 options. In the example for the make command line arguments (see What's
1597 in a Name), the keep prevented nroff from placing up the flag and the
1598 argument on separate lines.
1599 Both macros are neither callable nor parsed.
1601 More work needs to be done with the keep macros; specifically, a -line
1603 option should be added.
1604 Examples and Displays
1606 There are seven types of displays.
1607 .D1 (This is D-one.) Display one line of indented text. This macro is
1609 parsed but not callable.
1610 -ldghfstru
1612 The above was produced by: .D1 Fl ldghfstru.
1614 .Dl (This is D-ell.) Display one line of indented literal text. The
1616 ‘.Dl’ example macro has been used throughout this file. It allows
1617 the indentation (display) of one line of text. Its default font is
1618 set to constant width (literal). ‘.Dl’ is parsed but not callable.
1619 % ls -ldg /usr/local/bin
1621 The above was produced by: .Dl % ls \-ldg /usr/local/bin.
1623 .Bd Begin display. The ‘.Bd’ display must be ended with the ‘.Ed’
1625 macro. It has the following syntax:
1626 .Bd {-literal | -filled | -unfilled | -ragged | -centered}
1628 [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]
1629 -ragged Fill, but do not adjust the right margin (only
1631 left-justify).
1632 -centered Center lines between the current left and right
1633 margin. Note that each single line is centered.
1634 -unfilled Do not fill; display a block of text as typed,
1635 using line breaks as specified by the user. This
1636 can produce overlong lines without warning mes‐
1637 sages.
1638 -filled Display a filled block. The block of text is
1639 formatted (i.e., the text is justified on both
1640 the left and right side).
1641 -literal Display block with literal font (usually fixed-
1642 width). Useful for source code or simple tabbed
1643 or spaced text.
1644 -file ⟨file name⟩ The file whose name follows the -file flag is
1645 read and displayed before any data enclosed with
1646 ‘.Bd’ and ‘.Ed’, using the selected display type.
1647 Any troff/-mdoc commands in the file will be pro‐
1648 cessed.
1649 -offset ⟨string⟩ If -offset is specified with one of the following
1650 strings, the string is interpreted to indicate
1651 the level of indentation for the forthcoming
1652 block of text:
1653 left Align block on the current left mar‐
1655 gin; this is the default mode of
1656 ‘.Bd’.
1657 center Supposedly center the block. At this
1658 time unfortunately, the block merely
1659 gets left aligned about an imaginary
1660 center margin.
1661 indent Indent by one default indent value or
1662 tab. The default indent value is
1663 also used for the ‘.D1’ and ‘.Dl’
1664 macros, so one is guaranteed the two
1665 types of displays will line up. The
1666 indentation value is normally set
1667 to 6n or about two thirds of an inch
1668 (six constant width characters).
1669 indent-two Indent two times the default indent
1670 value.
1671 right This left aligns the block about two
1672 inches from the right side of the
1673 page. This macro needs work and per‐
1674 haps may never do the right thing
1675 within troff.
1676 If ⟨string⟩ is a valid numeric expression instead
1678 (with a scale indicator other than ‘u’), use that
1679 value for indentation. The most useful scale
1680 indicators are ‘m’ and ‘n’, specifying the so-
1681 called Em and En square. This is approximately
1682 the width of the letters ‘m’ and ‘n’ respectively
1683 of the current font (for nroff output, both scale
1684 indicators give the same values). If ⟨string⟩
1685 isn't a numeric expression, it is tested whether
1686 it is an -mdoc macro name, and the default offset
1687 value associated with this macro is used.
1688 Finally, if all tests fail, the width of ⟨string⟩
1689 (typeset with a fixed-width font) is taken as the
1690 offset.
1691 -compact Suppress insertion of vertical space before begin
1692 of display.
1693 .Ed End display (takes no arguments).
1695 Lists and Columns
1697 There are several types of lists which may be initiated with the ‘.Bl’
1698 begin-list macro. Items within the list are specified with the ‘.It’
1699 item macro, and each list must end with the ‘.El’ macro. Lists may be
1700 nested within themselves and within displays. The use of columns inside
1701 of lists or lists inside of columns is unproven.
1702 In addition, several list attributes may be specified such as the width
1704 of a tag, the list offset, and compactness (blank lines between items
1705 allowed or disallowed). Most of this document has been formatted with a
1706 tag style list (-tag).
1707 It has the following syntax forms:
1709 .Bl {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
1711 [-offset ⟨string⟩] [-compact]
1712 .Bl -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
1713 .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
1714 ⟨string⟩] [-compact]
1715 And now a detailed description of the list types.
1717 -bullet A bullet list.
1719 .Bl -bullet -offset indent -compact
1721 .It
1722 Bullet one goes here.
1723 .It
1724 Bullet two here.
1725 .El
1726 Produces:
1728 · Bullet one goes here.
1730 · Bullet two here.
1731 -dash (or -hyphen)
1733 A dash list.
1734 .Bl -dash -offset indent -compact
1736 .It
1737 Dash one goes here.
1738 .It
1739 Dash two here.
1740 .El
1741 Produces:
1743 - Dash one goes here.
1745 - Dash two here.
1746 -enum An enumerated list.
1748 .Bl -enum -offset indent -compact
1750 .It
1751 Item one goes here.
1752 .It
1753 And item two here.
1754 .El
1755 The result:
1757 1. Item one goes here.
1759 2. And item two here.
1760 If you want to nest enumerated lists, use the -nested flag
1762 (starting with the second-level list):
1763 .Bl -enum -offset indent -compact
1765 .It
1766 Item one goes here
1767 .Bl -enum -nested -compact
1768 .It
1769 Item two goes here.
1770 .It
1771 And item three here.
1772 .El
1773 .It
1774 And item four here.
1775 .El
1776 Result:
1778 1. Item one goes here.
1780 1.1. Item two goes here.
1781 1.2. And item three here.
1782 2. And item four here.
1783 -item A list of type -item without list markers.
1785 .Bl -item -offset indent
1787 .It
1788 Item one goes here.
1789 Item one goes here.
1790 Item one goes here.
1791 .It
1792 Item two here.
1793 Item two here.
1794 Item two here.
1795 .El
1796 Produces:
1798 Item one goes here. Item one goes here. Item one goes
1800 here.
1801 Item two here. Item two here. Item two here.
1803 -tag A list with tags. Use -width to specify the tag width.
1805 SL sleep time of the process (seconds blocked)
1807 PAGEIN
1808 number of disk I/O's resulting from references by
1809 the process to pages not loaded in core.
1810 UID numerical user-id of process owner
1811 PPID numerical id of parent of process priority (non-pos‐
1812 itive when in non-interruptible wait)
1813 The raw text:
1815 .Bl -tag -width "PPID" -compact -offset indent
1817 .It SL
1818 sleep time of the process (seconds blocked)
1819 .It PAGEIN
1820 number of disk
1821 .Tn I/O Ns 's
1822 resulting from references by the process
1823 to pages not loaded in core.
1824 .It UID
1825 numerical user-id of process owner
1826 .It PPID
1827 numerical id of parent of process priority
1828 (non-positive when in non-interruptible wait)
1829 .El
1830 -diag Diag lists create section four diagnostic lists and are similar
1832 to inset lists except callable macros are ignored. The -width
1833 flag is not meaningful in this context.
1834 Example:
1836 .Bl -diag
1838 .It You can't use Sy here.
1839 The message says all.
1840 .El
1841 produces
1843 You can't use Sy here. The message says all.
1845 -hang A list with hanging tags.
1847 Hanged labels appear similar to tagged lists when the
1849 label is smaller than the label width.
1850 Longer hanged list labels blend into the paragraph unlike
1852 tagged paragraph labels.
1853 And the unformatted text which created it:
1855 .Bl -hang -offset indent
1857 .It Em Hanged
1858 labels appear similar to tagged lists when the
1859 label is smaller than the label width.
1860 .It Em Longer hanged list labels
1861 blend into the paragraph unlike
1862 tagged paragraph labels.
1863 .El
1864 -ohang Lists with overhanging tags do not use indentation for the
1866 items; tags are written to a separate line.
1867 SL
1869 sleep time of the process (seconds blocked)
1870 PAGEIN
1872 number of disk I/O's resulting from references by the
1873 process to pages not loaded in core.
1874 UID
1876 numerical user-id of process owner
1877 PPID
1879 numerical id of parent of process priority (non-positive
1880 when in non-interruptible wait)
1881 The raw text:
1883 .Bl -ohang -offset indent
1885 .It Sy SL
1886 sleep time of the process (seconds blocked)
1887 .It Sy PAGEIN
1888 number of disk
1889 .Tn I/O Ns 's
1890 resulting from references by the process
1891 to pages not loaded in core.
1892 .It Sy UID
1893 numerical user-id of process owner
1894 .It Sy PPID
1895 numerical id of parent of process priority
1896 (non-positive when in non-interruptible wait)
1897 .El
1898 -inset Here is an example of inset labels:
1900 Tag The tagged list (also called a tagged paragraph) is
1902 the most common type of list used in the Berkeley manuals.
1903 Use a -width attribute as described below.
1904 Diag Diag lists create section four diagnostic lists and
1906 are similar to inset lists except callable macros are
1907 ignored.
1908 Hang Hanged labels are a matter of taste.
1910 Ohang Overhanging labels are nice when space is con‐
1912 strained.
1913 Inset Inset labels are useful for controlling blocks of
1915 paragraphs and are valuable for converting -mdoc manuals
1916 to other formats.
1917 Here is the source text which produced the above example:
1919 .Bl -inset -offset indent
1921 .It Em Tag
1922 The tagged list (also called a tagged paragraph)
1923 is the most common type of list used in the
1924 Berkeley manuals.
1925 .It Em Diag
1926 Diag lists create section four diagnostic lists
1927 and are similar to inset lists except callable
1928 macros are ignored.
1929 .It Em Hang
1930 Hanged labels are a matter of taste.
1931 .It Em Ohang
1932 Overhanging labels are nice when space is constrained.
1933 .It Em Inset
1934 Inset labels are useful for controlling blocks of
1935 paragraphs and are valuable for converting
1936 .Nm -mdoc
1937 manuals to other formats.
1938 .El
1939 -column This list type generates multiple columns. The number of col‐
1941 umns and the width of each column is determined by the arguments
1942 to the -column list, ⟨string1⟩, ⟨string2⟩, etc. If ⟨stringN⟩
1943 starts with a ‘.’ (dot) immediately followed by a valid -mdoc
1944 macro name, interpret ⟨stringN⟩ and use the width of the result.
1945 Otherwise, the width of ⟨stringN⟩ (typeset with a fixed-width
1946 font) is taken as the Nth column width.
1947 Each ‘.It’ argument is parsed to make a row, each column within
1949 the row is a separate argument separated by a tab or the ‘.Ta’
1950 macro.
1951 The table:
1953 String Nroff Troff
1955 <= <= ≤
1956 >= >= ≥
1957 was produced by:
1959 .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
1961 .It Sy String Ta Sy Nroff Ta Sy Troff
1962 .It Li <= Ta <= Ta \*(<=
1963 .It Li >= Ta >= Ta \*(>=
1964 .El
1965 Don't abuse this list type! For more complicated cases it might
1967 be far better and easier to use tbl(1), the table preprocessor.
1968 Other keywords:
1970 -width ⟨string⟩ If ⟨string⟩ starts with a ‘.’ (dot) immediately fol‐
1972 lowed by a valid -mdoc macro name, interpret ⟨string⟩
1973 and use the width of the result. Almost all lists in
1974 this document use this option.
1975 Example:
1977 .Bl -tag -width ".Fl test Ao Ar string Ac"
1979 .It Fl test Ao Ar string Ac
1980 This is a longer sentence to show how the
1981 .Fl width
1982 flag works in combination with a tag list.
1983 .El
1984 gives:
1986 -test ⟨string⟩ This is a longer sentence to show how
1988 the -width flag works in combination
1989 with a tag list.
1990 (Note that the current state of -mdoc is saved before
1992 ⟨string⟩ is interpreted; afterwards, all variables are
1993 restored again. However, boxes (used for enclosures)
1994 can't be saved in GNU troff(1); as a consequence, argu‐
1995 ments must always be balanced to avoid nasty errors.
1996 For example, do not write ‘.Ao Ar string’ but ‘.Ao Ar
1997 string Xc’ instead if you really need only an opening
1998 angle bracket.)
1999 Otherwise, if ⟨string⟩ is a valid numeric expression
2001 (with a scale indicator other than ‘u’), use that value
2002 for indentation. The most useful scale indicators are
2003 ‘m’ and ‘n’, specifying the so-called Em and En square.
2004 This is approximately the width of the letters ‘m’ and
2005 ‘n’ respectively of the current font (for nroff output,
2006 both scale indicators give the same values). If
2007 ⟨string⟩ isn't a numeric expression, it is tested
2008 whether it is an -mdoc macro name, and the default
2009 width value associated with this macro is used.
2010 Finally, if all tests fail, the width of ⟨string⟩
2011 (typeset with a fixed-width font) is taken as the
2012 width.
2013 If a width is not specified for the tag list type,
2015 every time ‘.It’ is invoked, an attempt is made to
2016 determine an appropriate width. If the first argument
2017 to ‘.It’ is a callable macro, the default width for
2018 that macro will be used; otherwise, the default width
2019 of ‘.No’ is used.
2020 -offset ⟨string⟩ If ⟨string⟩ is indent, a default indent value (normally
2022 set to 6n, similar to the value used in ‘.Dl’ or ‘.Bd’)
2023 is used. If ⟨string⟩ is a valid numeric expression
2024 instead (with a scale indicator other than ‘u’), use
2025 that value for indentation. The most useful scale
2026 indicators are ‘m’ and ‘n’, specifying the so-called Em
2027 and En square. This is approximately the width of the
2028 letters ‘m’ and ‘n’ respectively of the current font
2029 (for nroff output, both scale indicators give the same
2030 values). If ⟨string⟩ isn't a numeric expression, it is
2031 tested whether it is an -mdoc macro name, and the
2032 default offset value associated with this macro is
2033 used. Finally, if all tests fail, the width of
2034 ⟨string⟩ (typeset with a fixed-width font) is taken as
2035 the offset.
2036 -compact Suppress insertion of vertical space before the list
2038 and between list items.
2039
2041 Here a list of the remaining macros which do not fit well into one of the
2042 above sections. We couldn't find real examples for the following macros:
2043 ‘.Me’ and ‘.Ot’. They are documented here for completeness - if you know
2044 how to use them properly please send a mail to bug-groff@gnu.org (includ‐
2045 ing an example).
2046 .Bt prints
2048 is currently in beta test.
2050 It is neither callable nor parsed and takes no arguments.
2052 .Fr
2054 Usage: .Fr ⟨function return value⟩ ...
2056 Don't use this macro. It allows a break right before the return
2058 value (usually a single digit) which is bad typographical behaviour.
2059 Use ‘\~’ to tie the return value to the previous word.
2060 .Hf Use this macro to include a (header) file literally. It first
2062 prints ‘File:’ followed by the file name, then the contents of
2063 ⟨file⟩.
2064 Usage: .Hf ⟨file⟩
2066 It is neither callable nor parsed.
2068 .Lk To be written.
2070 .Me Exact usage unknown. The documentation in the -mdoc source file
2072 describes it as a macro for “menu entries”.
2073 Its default width is 6n.
2075 .Mt To be written.
2077 .Ot Exact usage unknown. The documentation in the -mdoc source file
2079 describes it as “old function type (fortran)”.
2080 .Sm Activate (toggle) space mode.
2082 Usage: .Sm [on | off] ...
2084 If space mode is off, no spaces between macro arguments are
2086 inserted. If called without a parameter (or if the next parameter
2087 is neither ‘on’ nor ‘off’, ‘.Sm’ toggles space mode.
2088 .Ud prints
2090 currently under development.
2092 It is neither callable nor parsed and takes no arguments.
2094
2096 The following strings are predefined:
2097 String Nroff Troff Meaning
2099 <= <= ≤ less equal
2100 >= >= ≥ greater equal
2101 Rq '' ” right double quote
2102 Lq `` “ left double quote
2103 ua ^ ↑ upwards arrow
2104 aa ´ ´ acute accent
2105 ga ` ` grave accent
2106 q " " straight double quote
2107 Pi pi π greek pi
2108 Ne != ≠ not equal
2109 Le <= ≤ less equal
2110 Ge >= ≥ greater equal
2111 Lt < < less than
2112 Gt > > greater than
2113 Pm +- ± plus minus
2114 If infinity ∞ infinity
2115 Am & & ampersand
2116 Na NaN NaN not a number
2117 Ba | | vertical bar
2118 The names of the columns Nroff and Troff are a bit misleading; Nroff
2120 shows the ASCII representation, while Troff gives the best glyph form
2121 available. For example, a Unicode enabled TTY-device will have proper
2122 glyph representations for all strings, whereas the enhancement for a
2123 Latin1 TTY-device is only the plus-minus sign.
2124 String names which consist of two characters can be written as ‘\*(xx’;
2126 string names which consist of one character can be written as ‘\*x’. A
2127 generic syntax for a string name of any length is ‘\*[xxx]’ (this is a
2128 GNU troff(1) extension).
2129
2131 The debugging macro ‘.Db’ available in previous versions of -mdoc has
2132 been removed since GNU troff(1) provides better facilities to check
2133 parameters; additionally, many error and warning messages have been added
2134 to this macro package, making it both more robust and verbose.
2135 The only remaining debugging macro is ‘.Rd’ which yields a register dump
2137 of all global registers and strings. A normal user will never need it.
2138
2140 By default, the package inhibits page breaks, headers, and footers if
2141 displayed with a TTY device like ‘latin1’ or ‘unicode’, to make the man‐
2142 ual more efficient for viewing on-line. This behaviour can be changed
2143 (e.g. to create a hardcopy of the TTY output) by setting the register
2144 ‘cR’ to zero while calling groff(1), resulting in multiple pages instead
2145 of a single, very long page:
2146 groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
2148 For double-sided printing, set register ‘D’ to 1:
2150 groff -Tps -rD1 -mdoc foo.man > foo.ps
2152 To change the document font size to 11pt or 12pt, set register ‘S’
2154 accordingly:
2155 groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
2157 Register ‘S’ is ignored for TTY devices.
2159 The line and title length can be changed by setting the registers ‘LL’
2161 and ‘LT’, respectively:
2162 groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less
2164 If not set, both registers default to 78n for TTY devices and 6.5i other‐
2166 wise.
2167
2169 doc.tmac The main manual macro package.
2170 mdoc.tmac A wrapper file to call doc.tmac.
2171 mdoc/doc-common Common strings, definitions, stuff related typographic
2172 output.
2173 mdoc/doc-nroff Definitions used for a TTY output device.
2174 mdoc/doc-ditroff Definitions used for all other devices.
2175 mdoc.local Local additions and customizations.
2176 andoc.tmac Use this file if you don't know whether the -mdoc or
2177 the -man package should be used. Multiple man pages
2178 (in either format) can be handled.
2179
2181 groff(1), man(1), troff(1), groff_man(7)
2182
2184 Section 3f has not been added to the header routines.
2185 ‘.Nm’ font should be changed in NAME section.
2187 ‘.Fn’ needs to have a check to prevent splitting up if the line length is
2189 too short. Occasionally it separates the last parenthesis, and sometimes
2190 looks ridiculous if a line is in fill mode.
2191 The list and display macros do not do any keeps and certainly should be
2193 able to.
2194BSD January 5, 2006 BSD