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 OpenBSD Macro
87 BSD/OS Macro
88 UNIX Macro
89 Emphasis Macro
90 Font Mode
91 Enclosure and Quoting Macros
92 No-Op or Normal Text Macro
93 No-Space Macro
94 Section Cross References
95 Symbolics
96 Mathematical Symbols
97 References and Citations
98 Trade Names (or Acronyms and Type Names)
99 Extended Arguments
100 8. PAGE STRUCTURE DOMAIN
102 Section Headers
103 Subsection Headers
104 Paragraphs and Line Spacing
105 Keeps
106 Examples and Displays
107 Lists and Columns
108 9. MISCELLANEOUS MACROS
110 10. PREDEFINED STRINGS
112 11. DIAGNOSTICS
114 12. FORMATTING WITH GROFF, TROFF, AND NROFF
116 13. FILES
118 14. SEE ALSO
120 15. BUGS
122
124 The -mdoc package attempts to simplify the process of writing a man page.
125 Theoretically, one should not have to learn the tricky details of GNU
126 troff(1) to use -mdoc; however, there are a few limitations which are
127 unavoidable and best gotten out of the way. And, too, be forewarned,
128 this package is not fast.
129 Macro Usage
131 As in GNU troff(1), a macro is called by placing a ‘.’ (dot character) at
132 the beginning of a line followed by the two-character (or three-charac‐
133 ter) name for the macro. There can be space or tab characters between
134 the dot and the macro name. Arguments may follow the macro separated by
135 spaces (but no tabs). It is the dot character at the beginning of the
136 line which causes GNU troff(1) to interpret the next two (or more) char‐
137 acters as a macro name. A single starting dot followed by nothing is
138 ignored. To place a ‘.’ (dot character) at the beginning of an input
139 line in some context other than a macro invocation, precede the ‘.’ (dot)
140 with the ‘\&’ escape sequence which translates literally to a zero-width
141 space, and is never displayed in the output.
142 In general, GNU troff(1) macros accept an unlimited number of arguments
144 (contrary to other versions of troff which can't handle more than nine
145 arguments). In limited cases, arguments may be continued or extended on
146 the next line (See Extended Arguments below). Almost all macros handle
147 quoted arguments (see Passing Space Characters in an Argument below).
148 Most of the -mdoc general text domain and manual domain macros are spe‐
150 cial in that their argument lists are parsed for callable macro names.
151 This means an argument on the argument list which matches a general text
152 or manual domain macro name (and which is defined to be callable) will be
153 executed or called when it is processed. In this case the argument,
154 although the name of a macro, is not preceded by a ‘.’ (dot). This makes
155 it possible to nest macros; for example the option macro, ‘.Op’, may call
156 the flag and argument macros, ‘Fl’ and ‘Ar’, to specify an optional flag
157 with an argument:
158 [-s bytes] is produced by ‘.Op Fl s Ar bytes’
160 To prevent a string from being interpreted as a macro name, precede the
162 string with the escape sequence ‘\&’:
163 [Fl s Ar bytes] is produced by ‘.Op \&Fl s \&Ar bytes’
165 Here the strings ‘Fl’ and ‘Ar’ are not interpreted as macros. Macros
167 whose argument lists are parsed for callable arguments are referred to as
168 parsed and macros which may be called from an argument list are referred
169 to as callable throughout this document. This is a technical faux pas as
170 almost all of the macros in -mdoc are parsed, but as it was cumbersome to
171 constantly refer to macros as being callable and being able to call other
172 macros, the term parsed has been used.
173 In the following, we call an -mdoc macro which starts a line (with a
175 leading dot) a command if this distinction is necessary.
176 Passing Space Characters in an Argument
178 Sometimes it is desirable to give as an argument a string containing one
179 or more blank space characters, say, to specify arguments to commands
180 which expect particular arrangement of items in the argument list. Addi‐
181 tionally, it makes -mdoc working faster. For example, the function com‐
182 mand ‘.Fn’ expects the first argument to be the name of a function and
183 any remaining arguments to be function parameters. As ANSI C stipulates
184 the declaration of function parameters in the parenthesized parameter
185 list, each parameter is guaranteed to be at minimum a two word string.
186 For example, int foo.
187 There are two possible ways to pass an argument which contains an embed‐
189 ded space. One way of passing a string containing blank spaces is to use
190 the hard or unpaddable space character ‘\ ’, that is, a blank space pre‐
191 ceded by the escape character ‘\’. This method may be used with any
192 macro but has the side effect of interfering with the adjustment of text
193 over the length of a line. Troff sees the hard space as if it were any
194 other printable character and cannot split the string into blank or new‐
195 line separated pieces as one would expect. This method is useful for
196 strings which are not expected to overlap a line boundary. An alterna‐
197 tive is to use ‘\~’, a paddable (i.e. stretchable), unbreakable space
198 (this is a GNU troff(1) extension). The second method is to enclose the
199 string with double quotes.
200 For example:
202 fetch(char *str) is created by ‘.Fn fetch char\ *str’
204 fetch(char *str) can also be created by ‘.Fn fetch "char *str"’
206 If the ‘\’ before the space in the first example or double quotes in the
208 second example were omitted, ‘.Fn’ would see three arguments, and the
209 result would be:
210 fetch(char, *str)
212 Trailing Blank Space Characters
214 Troff can be confused by blank space characters at the end of a line. It
215 is a wise preventive measure to globally remove all blank spaces from
216 ⟨blank-space⟩⟨end-of-line⟩ character sequences. Should the need arise to
217 use a blank character at the end of a line, it may be forced with an
218 unpaddable space and the ‘\&’ escape character. For example,
219 ‘string\ \&’.
220 Escaping Special Characters
222 Special characters like the newline character ‘\n’ are handled by replac‐
223 ing the ‘\’ with ‘\e’ (e.g. ‘\en’) to preserve the backslash.
224 Other Possible Pitfalls
226 A warning is emitted when an empty input line is found outside of dis‐
227 plays (see below). Use ‘.sp’ instead. (Well, it is even better to use
228 -mdoc macros to avoid the usage of low-level commands.)
229 Leading spaces will cause a break and are output directly. Avoid this
231 behaviour if possible. Similarly, do not use more than one space charac‐
232 ter between words in an ordinary text line; contrary to other text for‐
233 matters, they are not replaced with a single space.
234 You can't pass ‘"’ directly as an argument. Use ‘\*[q]’ (or ‘\*q’)
236 instead.
237 By default, troff(1) inserts two space characters after a punctuation
239 mark closing a sentence; characters like ‘)’ or ‘'’ are treated transpar‐
240 ently, not influencing the sentence-ending behaviour. To change this,
241 insert ‘\&’ before or after the dot:
242 The
244 .Ql .
245 character.
246 .Pp
247 The
248 .Ql \&.
249 character.
250 .Pp
251 .No test .
252 test
253 .Pp
254 .No test.
255 test
256 gives
258 The ‘’. character
260 The ‘.’ character.
262 test. test
264 test. test
266 As can be seen in the first and third line, -mdoc handles punctuation
268 characters specially in macro arguments. This will be explained in sec‐
269 tion General Syntax below. In the same way, you have to protect trailing
270 full stops of abbreviations with a trailing zero-width space: ‘e.g.\&’.
271 A comment in the source file of a man page can be either started with
273 ‘.\"’ on a single line, ‘\"’ after some input, or ‘\#’ anywhere (the lat‐
274 ter is a GNU troff(1) extension); the rest of such a line is ignored.
275
277 The body of a man page is easily constructed from a basic template:
278 .\" The following commands are required for all man pages.
280 .Dd Month day, year
281 .Os [OPERATING_SYSTEM] [version/release]
282 .Dt DOCUMENT_TITLE [section number] [architecture/volume]
283 .Sh NAME
284 .Nm name
285 .Nd one line description of name
286 .\" This next command is for sections 2 and 3 only.
287 .\" .Sh LIBRARY
288 .Sh SYNOPSIS
289 .Sh DESCRIPTION
290 .\" The following commands should be uncommented and
291 .\" used where appropriate.
292 .\" .Sh IMPLEMENTATION NOTES
293 .\" This next command is for sections 2, 3 and 9 function
294 .\" return values only.
295 .\" .Sh RETURN VALUES
296 .\" This next command is for sections 1, 6, 7 and 8 only.
297 .\" .Sh ENVIRONMENT
298 .\" .Sh FILES
299 .\" .Sh EXAMPLES
300 .\" This next command is for sections 1, 6, 7, 8 and 9 only
301 .\" (command return values (to shell) and
302 .\" fprintf/stderr type diagnostics).
303 .\" .Sh DIAGNOSTICS
304 .\" .Sh COMPATIBILITY
305 .\" This next command is for sections 2, 3 and 9 error
306 .\" and signal handling only.
307 .\" .Sh ERRORS
308 .\" .Sh SEE ALSO
309 .\" .Sh STANDARDS
310 .\" .Sh HISTORY
311 .\" .Sh AUTHORS
312 .\" .Sh BUGS
313 The first items in the template are the commands ‘.Dd’, ‘.Os’, and ‘.Dt’;
315 the document date, the operating system the man page or subject source is
316 developed or modified for, and the man page title (in upper case) along
317 with the section of the manual the page belongs in. These commands iden‐
318 tify the page and are discussed below in TITLE MACROS.
319 The remaining items in the template are section headers (.Sh); of which
321 NAME, SYNOPSIS, and DESCRIPTION are mandatory. The headers are discussed
322 in PAGE STRUCTURE DOMAIN, after presentation of MANUAL DOMAIN. Several
323 content macros are used to demonstrate page layout macros; reading about
324 content macros before page layout macros is recommended.
325
327 In the description of all macros below, optional arguments are put into
328 brackets. An ellipsis (‘...’) represents zero or more additional argu‐
329 ments. Alternative values for a parameter are separated with ‘|’. If
330 there are alternative values for a mandatory parameter, braces are used
331 (together with ‘|’) to enclose the value set. Meta-variables are speci‐
332 fied within angles.
333 Example:
335 .Xx ⟨foo⟩ {bar1 | bar2} [-test1 [-test2 | -test3]] ...
337 Except stated explicitly, all macros are parsed and callable.
339 Note that a macro takes effect up to the next nested macro. For example,
341 ‘.Ic foo Aq bar’ doesn't produce ‘foo <bar>’ but ‘foo ⟨bar⟩’. Conse‐
342 quently, a warning message is emitted for most commands if the first
343 argument is a macro itself since it cancels the effect of the calling
344 command completely. Another consequence is that quoting macros never
345 insert literal quotes; ‘foo <bar>’ has been produced by ‘.Ic "foo
346 <bar>"’.
347 Most macros have a default width value which can be used to specify a
349 label width (-width) or offset (-offset) for the ‘.Bl’ and ‘.Bd’ macros.
350 It is recommended not to use this rather obscure feature to avoid depen‐
351 dencies on local modifications of the -mdoc package.
352
354 The title macros are part of the page structure domain but are presented
355 first and separately for someone who wishes to start writing a man page
356 yesterday. Three header macros designate the document title or manual
357 page title, the operating system, and the date of authorship. These
358 macros are called once at the very beginning of the document and are used
359 to construct headers and footers only.
360 .Dt [⟨document title⟩] [⟨section number⟩] [⟨volume⟩]
362 The document title is the subject of the man page and must be in
363 CAPITALS due to troff limitations. If omitted, ‘UNTITLED’ is
364 used. The section number may be a number in the range 1, ..., 9
365 or ‘unass’, ‘draft’, or ‘paper’. If it is specified, and no vol‐
366 ume name is given, a default volume name is used.
367 Under BSD, the following sections are defined:
369 1 BSD General Commands Manual
371 2 BSD System Calls Manual
372 3 BSD Library Functions Manual
373 4 BSD Kernel Interfaces Manual
374 5 BSD File Formats Manual
375 6 BSD Games Manual
376 7 BSD Miscellaneous Information Manual
377 8 BSD System Manager's Manual
378 9 BSD Kernel Developer's Manual
379 A volume name may be arbitrary or one of the following:
381 USD User's Supplementary Documents
383 PS1 Programmer's Supplementary Documents
384 AMD Ancestral Manual Documents
385 SMM System Manager's Manual
386 URM User's Reference Manual
387 PRM Programmer's Manual
388 KM Kernel Manual
389 IND Manual Master Index
390 LOCAL Local Manual
391 CON Contributed Software Manual
392 For compatibility, ‘MMI’ can be used for ‘IND’, and ‘LOC’ for
394 ‘LOCAL’. Values from the previous table will specify a new vol‐
395 ume name. If the third parameter is a keyword designating a com‐
396 puter architecture, its value is prepended to the default volume
397 name as specified by the second parameter. By default, the fol‐
398 lowing architecture keywords are defined:
399 alpha, amiga, arc, arm26, arm32, atari, bebox, cobalt,
401 evbsh3, hp300, hpcmips, i386, luna68k, m68k, mac68k,
402 macppc, mips, mmeye, mvme68k, news68k, newsmips, next68k,
403 ofppc, pc532, pmax, powerpc, prep, sgimips, sh3, sparc,
404 sparc64, sun3, tahoe, vax, x68k
405 In the following examples, the left (which is identical to the
407 right) and the middle part of the manual page header strings are
408 shown.
409 .Dt FOO 7 ‘FOO(7)’ ‘BSD Miscellaneous Information
411 Manual’
412 .Dt FOO 2 i386 ‘FOO(2)’ ‘BSD/i386 System Calls Manual’
413 .Dt FOO "" bar ‘FOO’ ‘bar’
414 Local, OS-specific additions might be found in the file
416 mdoc.local; look for strings named ‘volume-ds-XXX’ (for the for‐
417 mer type) and ‘volume-as-XXX’ (for the latter type); ‘XXX’ then
418 denotes the keyword to be used with the ‘.Dt’ macro.
419 This macro is neither callable nor parsed.
421 .Os [⟨operating system⟩] [⟨release⟩]
423 If the first parameter is empty, the default ‘BSD’ is used. This
424 may be overridden in the local configuration file, mdoc.local.
425 In general, the name of the operating system should be the common
426 acronym, e.g. BSD or ATT. The release should be the standard
427 release nomenclature for the system specified. In the following
428 table, the possible second arguments for some predefined operat‐
429 ing systems are listed. Similar to ‘.Dt’, local additions might
430 be defined in mdoc.local; look for strings named
431 ‘operating-system-XXX-YYY’, where ‘XXX’ is the acronym for the
432 operating system and ‘YYY’ the release ID.
433 ATT 7th, 7, III, 3, V, V.2, V.3, V.4
435 BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
437 NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
439 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.5, 1.6
440 FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5,
442 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6,
443 2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0,
444 4.1, 4.2, 4.3, 4.4, 4.5, 5.0
445 For ATT, an unknown second parameter will be replaced with the
447 string UNIX; for the other predefined acronyms it will be ignored
448 and a warning message emitted. Unrecognized arguments are dis‐
449 played as given in the page footer. For instance, a typical
450 footer might be:
451 .Os BSD 4.3
453 giving ‘4.3 Berkeley Distribution’, or for a locally produced set
455 .Os CS Department
457 which will produce ‘CS Department’.
459 If the ‘.Os’ macro is not present, the bottom left corner of the
461 manual page will be ugly.
462 This macro is neither callable nor parsed.
464 .Dd [⟨month⟩ ⟨day⟩, ⟨year⟩]
466 If ‘Dd’ has no arguments, ‘Epoch’ is used for the date string.
467 If it has exactly three arguments, they are concatenated, sepa‐
468 rated with unbreakable space:
469 .Dd January 25, 2001
471 Otherwise, the current date is used, ignoring the parameters.
473 This macro is neither callable nor parsed.
475
477 What's in a Name...
478 The manual domain macro names are derived from the day to day informal
479 language used to describe commands, subroutines and related files.
480 Slightly different variations of this language are used to describe the
481 three different aspects of writing a man page. First, there is the
482 description of -mdoc macro command usage. Second is the description of a
483 UNIX command with -mdoc macros, and third, the description of a command
484 to a user in the verbal sense; that is, discussion of a command in the
485 text of a man page.
486 In the first case, troff(1) macros are themselves a type of command; the
488 general syntax for a troff command is:
489 .Xx argument1 argument2 ...
491 ‘.Xx’ is a macro command, and anything following it are arguments to be
493 processed. In the second case, the description of a UNIX command using
494 the content macros is a bit more involved; a typical SYNOPSIS command
495 line might be displayed as:
496 filter [-flag] ⟨infile⟩ ⟨outfile⟩
498 Here, filter is the command name and the bracketed string -flag is a flag
500 argument designated as optional by the option brackets. In -mdoc terms,
501 ⟨infile⟩ and ⟨outfile⟩ are called meta arguments; in this example, the
502 user has to replace the meta expressions given in angle brackets with
503 real file names. Note that in this document meta arguments are used to
504 describe -mdoc commands; in most man pages, meta variables are not
505 specifically written with angle brackets. The macros which formatted the
506 above example:
507 .Nm filter
509 .Op Fl flag
510 .Ao Ar infile Ac Ao Ar outfile Ac
511 In the third case, discussion of commands and command syntax includes
513 both examples above, but may add more detail. The arguments ⟨infile⟩ and
514 ⟨outfile⟩ from the example above might be referred to as operands or file
515 arguments. Some command line argument lists are quite long:
516 make [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I
518 directory] [-j max_jobs] [variable=value] [target ...]
519 Here one might talk about the command make and qualify the argument,
521 makefile, as an argument to the flag, -f, or discuss the optional file
522 operand target. In the verbal context, such detail can prevent confu‐
523 sion, however the -mdoc package does not have a macro for an argument to
524 a flag. Instead the ‘Ar’ argument macro is used for an operand or file
525 argument like target as well as an argument to a flag like variable. The
526 make command line was produced from:
527 .Nm make
529 .Op Fl eiknqrstv
530 .Op Fl D Ar variable
531 .Op Fl d Ar flags
532 .Op Fl f Ar makefile
533 .Op Fl I Ar directory
534 .Op Fl j Ar max_jobs
535 .Op Ar variable Ns = Ns Ar value
536 .Bk
537 .Op Ar target ...
538 .Ek
539 The ‘.Bk’ and ‘.Ek’ macros are explained in Keeps.
541 General Syntax
543 The manual domain and general text domain macros share a similar syntax
544 with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’
545 differ only when called without arguments; and ‘.Fn’ and ‘.Xr’ impose an
546 order on their argument lists. All content macros are capable of recog‐
547 nizing and properly handling punctuation, provided each punctuation char‐
548 acter is separated by a leading space. If a command is given:
549 .Ar sptr, ptr),
551 The result is:
553 sptr, ptr),
555 The punctuation is not recognized and all is output in the font used by
557 ‘.Ar’. If the punctuation is separated by a leading white space:
558 .Ar sptr , ptr ) ,
560 The result is:
562 sptr, ptr),
564 The punctuation is now recognized and output in the default font distin‐
566 guishing it from the argument strings. To remove the special meaning
567 from a punctuation character escape it with ‘\&’.
568 Troff is limited as a macro language, and has difficulty when presented
570 with a string containing a member of the mathematical, logical or quota‐
571 tion set:
572 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
574 The problem is that troff may assume it is supposed to actually perform
576 the operation or evaluation suggested by the characters. To prevent the
577 accidental evaluation of these characters, escape them with ‘\&’. Typi‐
578 cal syntax is shown in the first content macro displayed below, ‘.Ad’.
579
581 Addresses
582 The address macro identifies an address construct.
583 Usage: .Ad ⟨address⟩ ...
585 .Ad addr1 addr1
587 .Ad addr1 . addr1.
588 .Ad addr1 , file2 addr1, file2
589 .Ad f1 , f2 , f3 : f1, f2, f3:
590 .Ad addr ) ) , addr)),
591 The default width is 12n.
593 Author Name
595 The ‘.An’ macro is used to specify the name of the author of the item
596 being documented, or the name of the author of the actual manual page.
597 Usage: .An ⟨author name⟩ ...
599 .An "Joe Author" Joe Author
601 .An "Joe Author" , Joe Author,
603 .An "Joe Author" Aq nobody@FreeBSD.org
605 Joe Author <nobody@FreeBSD.org>
606 .An "Joe Author" ) ) , Joe Author)),
608 The default width is 12n.
610 In the AUTHORS section, the ‘.An’ command causes a line break allowing
612 each new name to appear on its own line. If this is not desirable,
613 .An -nosplit
615 call will turn this off. To turn splitting back on, write
617 .An -split
619 Arguments
621 The .Ar argument macro may be used whenever an argument is referenced.
622 If called without arguments, the ‘file ...’ string is output.
623 Usage: .Ar [⟨argument⟩] ...
625 .Ar file ...
627 .Ar file1 file1
628 .Ar file1 . file1.
629 .Ar file1 file2 file1 file2
630 .Ar f1 f2 f3 : f1 f2 f3:
631 .Ar file ) ) , file)),
632 The default width is 12n.
634 Configuration Declaration (Section Four Only)
636 The ‘.Cd’ macro is used to demonstrate a config(8) declaration for a
637 device interface in a section four manual.
638 Usage: .Cd ⟨argument⟩ ...
640 .Cd "device le0 at scode?" device le0 at scode?
642 In the SYNOPSIS section a ‘.Cd’ command causes a line break before and
644 after its arguments are printed.
645 The default width is 12n.
647 Command Modifiers
649 The command modifier is identical to the ‘.Fl’ (flag) command with the
650 exception that the ‘.Cm’ macro does not assert a dash in front of every
651 argument. Traditionally flags are marked by the preceding dash, however,
652 some commands or subsets of commands do not use them. Command modifiers
653 may also be specified in conjunction with interactive commands such as
654 editor commands. See Flags.
655 The default width is 10n.
657 Defined Variables
659 A variable (or constant) which is defined in an include file is specified
660 by the macro ‘.Dv’.
661 Usage: .Dv ⟨defined variable⟩ ...
663 .Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
665 .Dv TIOCGPGRP ) TIOCGPGRP)
666 The default width is 12n.
668 Errno's
670 The ‘.Er’ errno macro specifies the error return value for section 2, 3,
671 and 9 library routines. The second example below shows ‘.Er’ used with
672 the ‘.Bq’ general text domain macro, as it would be used in a section two
673 manual page.
674 Usage: .Er ⟨errno type⟩ ...
676 .Er ENOENT ENOENT
678 .Er ENOENT ) ; ENOENT);
679 .Bq Er ENOTDIR [ENOTDIR]
680 The default width is 17n.
682 Environment Variables
684 The ‘.Ev’ macro specifies an environment variable.
685 Usage: .Ev ⟨argument⟩ ...
687 .Ev DISPLAY DISPLAY
689 .Ev PATH . PATH.
690 .Ev PRINTER ) ) , PRINTER)),
691 The default width is 15n.
693 Flags
695 The ‘.Fl’ macro handles command line flags. It prepends a dash, ‘-’, to
696 the flag. For interactive command flags, which are not prepended with a
697 dash, the ‘.Cm’ (command modifier) macro is identical, but without the
698 dash.
699 Usage: .Fl ⟨argument⟩ ...
701 .Fl -
703 .Fl cfv -cfv
704 .Fl cfv . -cfv.
705 .Cm cfv . cfv.
706 .Fl s v t -s -v -t
707 .Fl - , --,
708 .Fl xyz ) , -xyz),
709 .Fl | - |
710 The ‘.Fl’ macro without any arguments results in a dash representing
712 stdin/stdout. Note that giving ‘.Fl’ a single dash will result in two
713 dashes.
714 The default width is 12n.
716 Function Declarations
718 The ‘.Fd’ macro is used in the SYNOPSIS section with section two or three
719 functions. It is neither callable nor parsed.
720 Usage: .Fd ⟨argument⟩ ...
722 .Fd "#include <sys/types.h>" #include <sys/types.h>
724 In the SYNOPSIS section a ‘.Fd’ command causes a line break if a function
726 has already been presented and a break has not occurred. This leaves a
727 nice vertical space in between the previous function call and the decla‐
728 ration for the next function.
729 The ‘.In’ (#include statement) macro is the short form of the above exam‐
731 ple. It specifies the C header file as being included in a C program.
732 It also causes a line break, and is neither callable nor parsed.
733 Usage: .In ⟨header file⟩
735 .In stdio.h <stdio.h>
737 Function Types
739 This macro is intended for the SYNOPSIS section. It may be used anywhere
740 else in the man page without problems, but its main purpose is to present
741 the function type in kernel normal form for the SYNOPSIS of sections two
742 and three (it causes a line break, allowing the function name to appear
743 on the next line).
744 Usage: .Ft ⟨type⟩ ...
746 .Ft struct stat struct stat
748 Functions (Library Routines)
750 The ‘.Fn’ macro is modeled on ANSI C conventions.
751 Usage: .Fn ⟨function⟩ [⟨parameter⟩] ...
753 .Fn getchar getchar()
755 .Fn strlen ) , strlen()),
756 .Fn align "char *ptr" , align(char *ptr),
757 Note that any call to another macro signals the end of the ‘.Fn’ call (it
759 will insert a closing parenthesis at that point).
760 For functions with many parameters (which is rare), the macros ‘.Fo’
762 (function open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (func‐
763 tion argument).
764 Example:
766 .Ft int
768 .Fo res_mkquery
769 .Fa "int op"
770 .Fa "char *dname"
771 .Fa "int class"
772 .Fa "int type"
773 .Fa "char *data"
774 .Fa "int datalen"
775 .Fa "struct rrec *newrr"
776 .Fa "char *buf"
777 .Fa "int buflen"
778 .Fc
779 Produces:
781 int res_mkquery(int op, char *dname, int class, int type,
783 char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
784 In the SYNOPSIS section, the function will always begin at the beginning
786 of line. If there is more than one function presented in the SYNOPSIS
787 section and a function type has not been given, a line break will occur,
788 leaving a nice vertical space between the current function name and the
789 one prior.
790 The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respec‐
792 tively.
793 Function Arguments
795 The ‘.Fa’ macro is used to refer to function arguments (parameters) out‐
796 side of the SYNOPSIS section of the manual or inside the SYNOPSIS section
797 if the enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used. ‘.Fa’
798 may also be used to refer to structure members.
799 Usage: .Fa ⟨function argument⟩ ...
801 .Fa d_namlen ) ) , d_namlen)),
803 .Fa iov_len iov_len
804 The default width is 12n.
806 Return Values
808 The ‘.Rv’ macro generates text for use in the RETURN VALUES section.
809 Usage: .Rv [-std] [⟨function⟩ ...]
811 For example, ‘.Rv -std atexit’ produces:
813 The atexit() function returns the value 0 if successful; otherwise
815 the value -1 is returned and the global variable errno is set to
816 indicate the error.
817 The -std option is valid only for manual page sections 2 and 3. Cur‐
819 rently, this macro does nothing if used without the -std flag.
820 Exit Status
822 The ‘.Ex’ macro generates text for use in the DIAGNOSTICS section.
823 Usage: .Ex [-std] [⟨utility⟩ ...]
825 For example, ‘.Ex -std cat’ produces:
827 The cat utility exits 0 on success, and >0 if an error occurs.
829 The -std option is valid only for manual page sections 1, 6 and 8. Cur‐
831 rently, this macro does nothing if used without the -std flag.
832 Interactive Commands
834 The ‘.Ic’ macro designates an interactive or internal command.
835 Usage: .Ic ⟨argument⟩ ...
837 .Ic :wq :wq
839 .Ic "do while {...}" do while {...}
840 .Ic setenv , unsetenv setenv, unsetenv
841 The default width is 12n.
843 Library Names
845 The ‘.Lb’ macro is used to specify the library where a particular func‐
846 tion is compiled in.
847 Usage: .Lb ⟨argument⟩ ...
849 Available arguments to ‘.Lb’ and their results are:
851 libarm32 ARM32 Architecture Library (libarm32, -larm32)
853 libc Standard C Library (libc, -lc)
854 libcompat Compatibility Library (libcompat, -lcompat)
855 libcrypt Crypt Library (libcrypt, -lcrypt)
856 libcurses Curses Library (libcurses, -lcurses)
857 libedit Command Line Editor Library (libedit, -ledit)
858 libi386 i386 Architecture Library (libi386, -li386)
859 libipsec IPsec Policy Control Library (libipsec, -lipsec)
860 libkvm Kernel Data Access Library (libkvm, -lkvm)
861 libm Math Library (libm, -lm)
862 libmenu Curses Menu Library (libmenu, -lmenu)
863 libossaudio OSS Audio Emulation Library (libossaudio, -lossaudio)
864 libposix POSIX Compatibility Library (libposix, -lposix)
865 libresolv DNS Resolver Library (libresolv, -lresolv)
866 libtermcap Termcap Access Library (libtermcap, -ltermcap)
867 libutil System Utilities Library (libutil, -lutil)
868 libz Compression Library (libz, -lz)
869 Local, OS-specific additions might be found in the file mdoc.local; look
871 for strings named ‘str-Lb-XXX’. ‘XXX’ then denotes the keyword to be
872 used with the ‘.Lb’ macro.
873 Literals
875 The ‘.Li’ literal macro may be used for special characters, variable con‐
876 stants, etc. -- anything which should be displayed as it would be typed.
877 Usage: .Li ⟨argument⟩ ...
879 .Li \en \n
881 .Li M1 M2 M3 ; M1 M2 M3;
882 .Li cntrl-D ) , cntrl-D),
883 .Li 1024 ... 1024 ...
884 The default width is 16n.
886 Names
888 The ‘.Nm’ macro is used for the document title or subject name. It has
889 the peculiarity of remembering the first argument it was called with,
890 which should always be the subject name of the page. When called without
891 arguments, ‘.Nm’ regurgitates this initial name for the sole purpose of
892 making less work for the author. Note: A section two or three document
893 function name is addressed with the ‘.Nm’ in the NAME section, and with
894 ‘.Fn’ in the SYNOPSIS and remaining sections. For interactive commands,
895 such as the ‘while’ command keyword in csh(1), the ‘.Ic’ macro should be
896 used. While ‘.Ic’ is nearly identical to ‘.Nm’, it can not recall the
897 first argument it was invoked with.
898 Usage: .Nm [⟨argument⟩] ...
900 .Nm groff_mdoc groff_mdoc
902 .Nm \-mdoc -mdoc
903 .Nm foo ) ) , foo)),
904 .Nm : groff_mdoc:
905 The default width is 10n.
907 Options
909 The ‘.Op’ macro places option brackets around any remaining arguments on
910 the command line, and places any trailing punctuation outside the brack‐
911 ets. The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a closing
912 option bracket respectively) may be used across one or more lines or to
913 specify the exact position of the closing parenthesis.
914 Usage: .Op [⟨option⟩] ...
916 .Op []
918 .Op Fl k [-k]
919 .Op Fl k ) . [-k]).
920 .Op Fl k Ar kookfile [-k kookfile]
921 .Op Fl k Ar kookfile , [-k kookfile],
922 .Op Ar objfil Op Ar corfil [objfil [corfil]]
923 .Op Fl c Ar objfil Op Ar corfil , [-c objfil [corfil]],
924 .Op word1 word2 [word1 word2]
925 .Li .Op Oo Ao option Ac Oc ... .Op [⟨options⟩] ...
926 Here a typical example of the ‘.Oo’ and ‘.Oc’ macros:
928 .Oo
930 .Op Fl k Ar kilobytes
931 .Op Fl i Ar interval
932 .Op Fl c Ar count
933 .Oc
934 Produces:
936 [[-k kilobytes] [-i interval] [-c count]]
938 The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respec‐
940 tively.
941 Pathnames
943 The ‘.Pa’ macro formats path or file names. If called without arguments,
944 the ‘~’ string is output, which represents the current user's home direc‐
945 tory.
946 Usage: .Pa [⟨pathname⟩] ...
948 .Pa ~
950 .Pa /usr/share /usr/share
951 .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).
952 The default width is 32n.
954 Standards
956 The ‘.St’ macro replaces standard abbreviations with their formal names.
957 Usage: .St ⟨abbreviation⟩ ...
959 Available pairs for “Abbreviation/Formal Name” are:
961 ANSI/ISO C
963 -ansiC ANSI X3.159-1989 (“ANSI C89”)
965 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
966 -isoC ISO/IEC 9899:1990 (“ISO C90”)
967 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
968 POSIX Part 1: System API
970 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
972 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
973 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
974 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
975 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
976 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
977 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
978 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
979 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
980 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
981 POSIX Part 2: Shell and Utilities
983 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
985 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
986 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
987 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
988 X/Open
990 -susv2 Version 2 of the Single UNIX Specification
992 (“SUSv2”)
993 -svid4 System V Interface Definition, Fourth Edition
994 (“SVID4”)
995 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
996 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
997 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
998 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
999 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1000 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1001 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1002 -xpg4.2 X/Open Portability Guide Issue 4, Version 2
1003 (“XPG4.2”)
1004 -xsh5 X/Open System Interfaces and Headers Issue 5
1005 (“XSH5”)
1006 Miscellaneous
1008 -ieee754 IEEE Std 754-1985
1010 -iso8802-3 ISO/IEC 8802-3:1989
1011 Variable Types
1013 The ‘.Vt’ macro may be used whenever a type is referenced. In the
1014 SYNOPSIS section, it causes a line break (useful for old style variable
1015 declarations).
1016 Usage: .Vt ⟨type⟩ ...
1018 .Vt extern char *optarg ; extern char *optarg;
1020 .Vt FILE * FILE *
1021 Variables
1023 Generic variable reference.
1024 Usage: .Va ⟨variable⟩ ...
1026 .Va count count
1028 .Va settimer , settimer,
1029 .Va "int *prt" ) : int *prt):
1030 .Va "char s" ] ) ) , char s])),
1031 The default width is 12n.
1033 Manual Page Cross References
1035 The ‘.Xr’ macro expects the first argument to be a manual page name. The
1036 optional second argument, if a string (defining the manual section), is
1037 put into parentheses.
1038 Usage: .Xr ⟨man page name⟩ [⟨section⟩] ...
1040 .Xr mdoc mdoc
1042 .Xr mdoc , mdoc,
1043 .Xr mdoc 7 mdoc(7)
1044 .Xr xinit 1x ; xinit(1x);
1045 The default width is 10n.
1047
1049 AT&T Macro
1050 Usage: .At [⟨version⟩] ...
1051 .At AT&T UNIX
1053 .At v6 . Version 6 AT&T UNIX.
1054 The following values for ⟨version⟩ are possible:
1056 32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4
1058 BSD Macro
1060 Usage: .Bx {-alpha | -beta | -devel} ...
1061 .Bx [⟨version⟩ [⟨release⟩]] ...
1062 .Bx BSD
1064 .Bx 4.3 . 4.3BSD.
1065 .Bx -devel BSD (currently under development)
1066 ⟨version⟩ will be prepended to the string ‘BSD’. The following values
1068 for ⟨release⟩ are possible:
1069 Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
1071 NetBSD Macro
1073 Usage: .Nx [⟨version⟩] ...
1074 .Nx NetBSD
1076 .Nx 1.4 . NetBSD 1.4.
1077 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1079 above in section TITLE MACROS.
1080 FreeBSD Macro
1082 Usage: .Fx [⟨version⟩] ...
1083 .Fx FreeBSD
1085 .Fx 2.2 . FreeBSD 2.2.
1086 For possible values of ⟨version⟩ see the description of the ‘.Os’ command
1088 above in section TITLE MACROS.
1089 OpenBSD Macro
1091 Usage: .Ox [⟨version⟩] ...
1092 .Ox 1.0 OpenBSD 1.0
1094 BSD/OS Macro
1096 Usage: .Bsx [⟨version⟩] ...
1097 .Bsx 1.0 BSD/OS 1.0
1099 UNIX Macro
1101 Usage: .Ux ...
1102 .Ux UNIX
1104 Emphasis Macro
1106 Text may be stressed or emphasized with the ‘.Em’ macro. The usual font
1107 for emphasis is italic.
1108 Usage: .Em ⟨argument⟩ ...
1110 .Em does not does not
1112 .Em exceed 1024 . exceed 1024.
1113 .Em vide infra ) ) , vide infra)),
1114 The default width is 10n.
1116 Font Mode
1118 The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes
1119 no arguments). Font modes may be nested within other font modes.
1120 ‘.Bf’ has the following syntax:
1122 .Bf ⟨font mode⟩
1124 ⟨font mode⟩ must be one of the following three types:
1126 Em | -emphasis Same as if the ‘.Em’ macro was used for the entire
1128 block of text.
1129 Li | -literal Same as if the ‘.Li’ macro was used for the entire
1130 block of text.
1131 Sy | -symbolic Same as if the ‘.Sy’ macro was used for the entire
1132 block of text.
1133 Both macros are neither callable nor parsed.
1135 Enclosure and Quoting Macros
1137 The concept of enclosure is similar to quoting. The object being to
1138 enclose one or more strings between a pair of characters like quotes or
1139 parentheses. The terms quoting and enclosure are used interchangeably
1140 throughout this document. Most of the one-line enclosure macros end in
1141 small letter ‘q’ to give a hint of quoting, but there are a few irregu‐
1142 larities. For each enclosure macro there is also a pair of open and
1143 close macros which end in small letters ‘o’ and ‘c’ respectively.
1144 Quote Open Close Function Result
1146 .Aq .Ao .Ac Angle Bracket Enclosure ⟨string⟩
1147 .Bq .Bo .Bc Bracket Enclosure [string]
1148 .Brq .Bro .Brc Brace Enclosure {string}
1149 .Dq .Do .Dc Double Quote “string”
1150 .Eq .Eo .Ec Enclose String (in XX) XXstringXX
1151 .Pq .Po .Pc Parenthesis Enclosure (string)
1152 .Ql Quoted Literal ‘string’ or string
1153 .Qq .Qo .Qc Straight Double Quote "string"
1154 .Sq .So .Sc Single Quote ‘string’
1155 All macros ending with ‘q’ and ‘o’ have a default width value of 12n.
1157 .Eo, .Ec These macros expect the first argument to be the opening and
1159 closing strings respectively.
1160 .Es, .En Due to the nine-argument limit in the original troff program
1162 two other macros have been implemented which are now rather
1163 obsolete: ‘.Es’ takes the first and second parameter as the
1164 left and right enclosure string, which are then used to enclose
1165 the arguments of ‘.En’. The default width value is 12n for
1166 both macros.
1167 .Eq The first and second arguments of this macro are the opening
1169 and closing strings respectively, followed by the arguments to
1170 be enclosed.
1171 .Ql The quoted literal macro behaves differently in troff and nroff
1173 mode. If formatted with nroff, a quoted literal is always
1174 quoted. If formatted with troff, an item is only quoted if the
1175 width of the item is less than three constant width characters.
1176 This is to make short strings more visible where the font
1177 change to literal (constant width) is less noticeable.
1178 The default width is 16n.
1180 .Pf The prefix macro suppresses the whitespace between its first
1182 and second argument:
1183 .Pf ( Fa name2 (name2
1185 The default width is 12n.
1187 The ‘.Ns’ macro (see below) performs the analogous suffix func‐
1189 tion.
1190 .Ap The ‘.Ap’ macro inserts an apostrophe and exits any special
1192 text modes, continuing in ‘.No’ mode.
1193 Examples of quoting:
1195 .Aq ⟨⟩
1197 .Aq Pa ctype.h ) , ⟨ctype.h⟩),
1198 .Bq []
1199 .Bq Em Greek , French . [Greek, French].
1200 .Dq “”
1201 .Dq string abc . “string abc”.
1202 .Dq ´^[A-Z]´ “´^[A-Z]´”
1203 .Ql man mdoc ‘man mdoc’
1204 .Qq ""
1205 .Qq string ) , "string"),
1206 .Qq string Ns ), "string),"
1207 .Sq ‘’
1208 .Sq string ‘string’
1209 .Em or Ap ing or'ing
1210 For a good example of nested enclosure macros, see the ‘.Op’ option
1212 macro. It was created from the same underlying enclosure macros as those
1213 presented in the list above. The ‘.Xo’ and ‘.Xc’ extended argument list
1214 macros are discussed below.
1215 No-Op or Normal Text Macro
1217 The ‘.No’ macro can be used in a macro command line for parameters which
1218 should not be formatted. Be careful to add ‘\&’ to the word ‘No’ if you
1219 really want that English word (and not the macro) as a parameter.
1220 Usage: .No ⟨argument⟩ ...
1222 .No test Ta with Ta tabs test with tabs
1224 The default width is 12n.
1226 No-Space Macro
1228 The ‘.Ns’ macro suppresses insertion of a space between the current posi‐
1229 tion and its first parameter. For example, it is useful for old style
1230 argument lists where there is no space between the flag and argument:
1231 Usage: ... ⟨argument⟩ Ns [⟨argument⟩] ...
1233 .Ns ⟨argument⟩ ...
1234 .Op Fl I Ns Ar directory [-Idirectory]
1236 Note: The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating
1238 the space unless another macro name follows it. If used as a command
1239 (i.e., the second form above in the ‘Usage’ line), ‘.Ns’ is identical to
1240 ‘.No’.
1241 Section Cross References
1243 The ‘.Sx’ macro designates a reference to a section header within the
1244 same document.
1245 Usage: .Sx ⟨section reference⟩ ...
1247 .Sx FILES FILES
1249 The default width is 16n.
1251 Symbolics
1253 The symbolic emphasis macro is generally a boldface macro in either the
1254 symbolic sense or the traditional English usage.
1255 Usage: .Sy ⟨symbol⟩ ...
1257 .Sy Important Notice Important Notice
1259 The default width is 6n.
1261 Mathematical Symbols
1263 Use this macro for mathematical symbols and similar things.
1264 Usage: .Ms ⟨math symbol⟩ ...
1266 .Ms sigma sigma
1268 The default width is 6n.
1270 References and Citations
1272 The following macros make a modest attempt to handle references. At
1273 best, the macros make it convenient to manually drop in a subset of
1274 refer(1) style references.
1275 .Rs Reference start (does not take arguments). Causes a line
1277 break in the SEE ALSO section and begins collection of ref‐
1278 erence information until the reference end macro is read.
1279 .Re Reference end (does not take arguments). The reference is
1280 printed.
1281 .%A Reference author name; one name per invocation.
1282 .%B Book title.
1283 .%C City/place (not implemented yet).
1284 .%D Date.
1285 .%I Issuer/publisher name.
1286 .%J Journal name.
1287 .%N Issue number.
1288 .%O Optional information.
1289 .%P Page number.
1290 .%Q Corporate or foreign author.
1291 .%R Report name.
1292 .%T Title of article.
1293 .%V Volume.
1294 Macros beginning with ‘%’ are not callable but accept multiple arguments
1296 in the usual way. Only the ‘.Tn’ macro is handled properly as a parame‐
1297 ter; other macros will cause strange output. ‘.%B’ and ‘.%T’ can be used
1298 outside of the ‘.Rs/.Re’ environment.
1299 Example:
1301 .Rs
1303 .%A "Matthew Bar"
1304 .%A "John Foo"
1305 .%T "Implementation Notes on foobar(1)"
1306 .%R "Technical Report ABC-DE-12-345"
1307 .%Q "Drofnats College, Nowhere"
1308 .%D "April 1991"
1309 .Re
1310 produces
1312 Matthew Bar and John Foo, Implementation Notes on foobar(1),
1314 Technical Report ABC-DE-12-345, Drofnats College, Nowhere, April
1315 1991.
1316 Trade Names (or Acronyms and Type Names)
1318 The trade name macro prints its arguments in a smaller font. Its
1319 intended use is to imitate a small caps fonts for uppercase acronyms.
1320 Usage: .Tn ⟨symbol⟩ ...
1322 .Tn DEC DEC
1324 .Tn ASCII ASCII
1325 The default width is 10n.
1327 Extended Arguments
1329 The .Xo and .Xc macros allow one to extend an argument list on a macro
1330 boundary for the ‘.It’ macro (see below). Note that .Xo and .Xc are
1331 implemented similarly to all other macros opening and closing an enclo‐
1332 sure (without inserting characters, of course). This means that the fol‐
1333 lowing is true for those macros also.
1334 Here is an example of ‘.Xo’ using the space mode macro to turn spacing
1336 off:
1337 .Sm off
1339 .It Xo Sy I Ar operation
1340 .No \en Ar count No \en
1341 .Xc
1342 .Sm on
1343 produces
1345 Ioperation\ncount\n
1347 Another one:
1349 .Sm off
1351 .It Cm S No / Ar old_pattern Xo
1352 .No / Ar new_pattern
1353 .No / Op Cm g
1354 .Xc
1355 .Sm on
1356 produces
1358 S/old_pattern/new_pattern/[g]
1360 Another example of ‘.Xo’ and enclosure macros: Test the value of a vari‐
1362 able.
1363 .It Xo
1365 .Ic .ifndef
1366 .Oo \&! Oc Ns Ar variable Oo
1367 .Ar operator variable ...
1368 .Oc Xc
1369 produces
1371 .ifndef [!]variable [operator variable ...]
1373
1375 Section Headers
1376 The following ‘.Sh’ section header macros are required in every man page.
1377 The remaining section headers are recommended at the discretion of the
1378 author writing the manual page. The ‘.Sh’ macro is parsed but not gener‐
1379 ally callable. It can be used as an argument in a call to ‘.Sh’ only; it
1380 then reactivates the default font for ‘.Sh’.
1381 The default width is 8n.
1383 .Sh NAME The ‘.Sh NAME’ macro is mandatory. If not specified,
1385 headers, footers and page layout defaults will not be
1386 set and things will be rather unpleasant. The NAME
1387 section consists of at least three items. The first
1388 is the ‘.Nm’ name macro naming the subject of the man
1389 page. The second is the name description macro,
1390 ‘.Nd’, which separates the subject name from the third
1391 item, which is the description. The description
1392 should be the most terse and lucid possible, as the
1393 space available is small.
1394 ‘.Nd’ first prints ‘-’, then all its arguments.
1396 .Sh LIBRARY This section is for section two and three function
1398 calls. It should consist of a single ‘.Lb’ macro
1399 call; see Library Names.
1400 .Sh SYNOPSIS The SYNOPSIS section describes the typical usage of
1402 the subject of a man page. The macros required are
1403 either ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,
1404 ‘.Fc’, ‘.Fd’, and ‘.Ft’). The function name macro
1405 ‘.Fn’ is required for manual page sections 2 and 3;
1406 the command and general name macro ‘.Nm’ is required
1407 for sections 1, 5, 6, 7, and 8. Section 4 manuals
1408 require a ‘.Nm’, ‘.Fd’ or a ‘.Cd’ configuration device
1409 usage macro. Several other macros may be necessary to
1410 produce the synopsis line as shown below:
1411 cat [-benstuv] [-] file ...
1413 The following macros were used:
1415 .Nm cat
1417 .Op Fl benstuv
1418 .Op Fl
1419 .Ar
1420 .Sh DESCRIPTION In most cases the first text in the DESCRIPTION sec‐
1422 tion is a brief paragraph on the command, function or
1423 file, followed by a lexical list of options and
1424 respective explanations. To create such a list, the
1425 ‘.Bl’ (begin list), ‘.It’ (list item) and ‘.El’ (end
1426 list) macros are used (see Lists and Columns below).
1427 .Sh IMPLEMENTATION NOTES
1429 Implementation specific information should be placed
1430 here.
1431 .Sh RETURN VALUES Sections 2, 3 and 9 function return values should go
1433 here. The ‘.Rv’ macro may be used to generate text
1434 for use in the RETURN VALUES section for most section
1435 2 and 3 library functions; see Return Values.
1436 The following ‘.Sh’ section headers are part of the preferred manual page
1438 layout and must be used appropriately to maintain consistency. They are
1439 listed in the order in which they would be used.
1440 .Sh ENVIRONMENT The ENVIRONMENT section should reveal any related
1442 environment variables and clues to their behavior
1443 and/or usage.
1444 .Sh FILES Files which are used or created by the man page sub‐
1446 ject should be listed via the ‘.Pa’ macro in the FILES
1447 section.
1448 .Sh EXAMPLES There are several ways to create examples. See the
1450 EXAMPLES section below for details.
1451 .Sh DIAGNOSTICS Diagnostic messages from a command should be placed in
1453 this section. The ‘.Ex’ macro may be used to generate
1454 text for use in the DIAGNOSTICS section for most sec‐
1455 tion 1, 6 and 8 commands; see Exit Status.
1456 .Sh COMPATIBILITY Known compatibility issues (e.g. deprecated options or
1458 parameters) should be listed here.
1459 .Sh ERRORS Specific error handling, especially from library func‐
1461 tions (man page sections 2, 3, and 9) should go here.
1462 The ‘.Er’ macro is used to specify an error (errno).
1463 .Sh SEE ALSO References to other material on the man page topic and
1465 cross references to other relevant man pages should be
1466 placed in the SEE ALSO section. Cross references are
1467 specified using the ‘.Xr’ macro. Currently refer(1)
1468 style references are not accommodated.
1469 It is recommended that the cross references are sorted
1471 on the section number, then alphabetically on the
1472 names within a section, and placed in that order and
1473 comma separated. Example:
1474 ls(1), ps(1), group(5), passwd(5)
1476 .Sh STANDARDS If the command, library function or file adheres to a
1478 specific implementation such as IEEE Std 1003.2
1479 (“POSIX.2”) or ANSI X3.159-1989 (“ANSI C89”) this
1480 should be noted here. If the command does not adhere
1481 to any standard, its history should be noted in the
1482 HISTORY section.
1483 .Sh HISTORY Any command which does not adhere to any specific
1485 standards should be outlined historically in this sec‐
1486 tion.
1487 .Sh AUTHORS Credits should be placed here. The ‘.An’ macro should
1489 be used to specify the name(s) of the person(s).
1490 .Sh BUGS Blatant problems with the topic go here.
1492 User-specified ‘.Sh’ sections may be added; for example, this section was
1494 set with:
1495 .Sh "PAGE STRUCTURE DOMAIN"
1497 Subsection Headers
1499 Subsection headers have exactly the same syntax as section headers: ‘.Ss’
1500 is parsed but not generally callable. It can be used as an argument in a
1501 call to ‘.Ss’ only; it then reactivates the default font for ‘.Ss’.
1502 The default width is 8n.
1504 Paragraphs and Line Spacing
1506 .Pp The ‘.Pp’ paragraph command may be used to specify a line space
1507 where necessary. The macro is not necessary after a ‘.Sh’ or ‘.Ss’
1508 macro or before a ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical
1509 distance unless the -compact flag is given).
1510 The macro is neither callable nor parsed and takes no arguments; an
1512 alternative name is ‘.Lp’.
1513 Keeps
1515 The only keep that is implemented at this time is for words. The macros
1516 are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep). The only option that ‘.Bk’
1517 accepts currently is -words (this is also the default if no option is
1518 given) which is useful for preventing line breaks in the middle of
1519 options. In the example for the make command line arguments (see What's
1520 in a Name), the keep prevented nroff from placing up the flag and the
1521 argument on separate lines.
1522 Both macros are neither callable nor parsed.
1524 More work needs to be done with the keep macros; specifically, a -line
1526 option should be added.
1527 Examples and Displays
1529 There are seven types of displays.
1530 .D1 (This is D-one.) Display one line of indented text. This macro is
1532 parsed but not callable.
1533 -ldghfstru
1535 The above was produced by: .D1 Fl ldghfstru.
1537 .Dl (This is D-ell.) Display one line of indented literal text. The
1539 ‘.Dl’ example macro has been used throughout this file. It allows
1540 the indentation (display) of one line of text. Its default font is
1541 set to constant width (literal). ‘.Dl’ is parsed but not callable.
1542 % ls -ldg /usr/local/bin
1544 The above was produced by: .Dl % ls -ldg /usr/local/bin.
1546 .Bd Begin display. The ‘.Bd’ display must be ended with the ‘.Ed’
1548 macro. It has the following syntax:
1549 .Bd {-literal | -filled | -unfilled | -ragged | -centered}
1551 [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]
1552 -ragged Fill, but do not adjust the right margin (only
1554 left-justify).
1555 -centered Center lines between the current left and right
1556 margin. Note that each single line is centered.
1557 -unfilled Do not fill; display a block of text as typed,
1558 using line breaks as specified by the user. This
1559 can produce overlong lines without warning mes‐
1560 sages.
1561 -filled Display a filled block. The block of text is
1562 formatted (i.e., the text is justified on both
1563 the left and right side).
1564 -literal Display block with literal font (usually fixed-
1565 width). Useful for source code or simple tabbed
1566 or spaced text.
1567 -file ⟨file name⟩ The file whose name follows the -file flag is
1568 read and displayed before any data enclosed with
1569 ‘.Bd’ and ‘.Ed’, using the selected display type.
1570 Any troff/-mdoc commands in the file will be pro‐
1571 cessed.
1572 -offset ⟨string⟩ If -offset is specified with one of the following
1573 strings, the string is interpreted to indicate
1574 the level of indentation for the forthcoming
1575 block of text:
1576 left Align block on the current left mar‐
1578 gin; this is the default mode of
1579 ‘.Bd’.
1580 center Supposedly center the block. At this
1581 time unfortunately, the block merely
1582 gets left aligned about an imaginary
1583 center margin.
1584 indent Indent by one default indent value or
1585 tab. The default indent value is
1586 also used for the ‘.D1’ and ‘.Dl’
1587 macros, so one is guaranteed the two
1588 types of displays will line up. The
1589 indentation value is normally set
1590 to 6n or about two thirds of an inch
1591 (six constant width characters).
1592 indent-two Indent two times the default indent
1593 value.
1594 right This left aligns the block about two
1595 inches from the right side of the
1596 page. This macro needs work and per‐
1597 haps may never do the right thing
1598 within troff.
1599 If ⟨string⟩ is a valid numeric expression instead
1601 (with a scale indicator other than ‘u’), use that
1602 value for indentation. The most useful scale
1603 indicators are ‘m’ and ‘n’, specifying the so-
1604 called Em and En square. This is approximately
1605 the width of the letters ‘m’ and ‘n’ respectively
1606 of the current font (for nroff output, both scale
1607 indicators give the same values). If ⟨string⟩
1608 isn't a numeric expression, it is tested whether
1609 it is an -mdoc macro name, and the default offset
1610 value associated with this macro is used.
1611 Finally, if all tests fail, the width of ⟨string⟩
1612 (typeset with a fixed-width font) is taken as the
1613 offset.
1614 -compact Suppress insertion of vertical space before begin
1615 of display.
1616 .Ed End display (takes no arguments).
1618 Lists and Columns
1620 There are several types of lists which may be initiated with the ‘.Bl’
1621 begin-list macro. Items within the list are specified with the ‘.It’
1622 item macro, and each list must end with the ‘.El’ macro. Lists may be
1623 nested within themselves and within displays. The use of columns inside
1624 of lists or lists inside of columns is unproven.
1625 In addition, several list attributes may be specified such as the width
1627 of a tag, the list offset, and compactness (blank lines between items
1628 allowed or disallowed). Most of this document has been formatted with a
1629 tag style list (-tag).
1630 It has the following syntax forms:
1632 .Bl {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
1634 [-offset ⟨string⟩] [-compact]
1635 .Bl -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
1636 .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
1637 ⟨string⟩] [-compact]
1638 And now a detailed description of the list types.
1640 -bullet A bullet list.
1642 .Bl -bullet -offset indent -compact
1644 .It
1645 Bullet one goes here.
1646 .It
1647 Bullet two here.
1648 .El
1649 Produces:
1651 · Bullet one goes here.
1653 · Bullet two here.
1654 -dash (or -hyphen)
1656 A dash list.
1657 .Bl -dash -offset indent -compact
1659 .It
1660 Dash one goes here.
1661 .It
1662 Dash two here.
1663 .El
1664 Produces:
1666 - Dash one goes here.
1668 - Dash two here.
1669 -enum An enumerated list.
1671 .Bl -enum -offset indent -compact
1673 .It
1674 Item one goes here.
1675 .It
1676 And item two here.
1677 .El
1678 The result:
1680 1. Item one goes here.
1682 2. And item two here.
1683 If you want to nest enumerated lists, use the -nested flag
1685 (starting with the second-level list):
1686 .Bl -enum -offset indent -compact
1688 .It
1689 Item one goes here
1690 .Bl -enum -nested -compact
1691 .It
1692 Item two goes here.
1693 .It
1694 And item three here.
1695 .El
1696 .It
1697 And item four here.
1698 .El
1699 Result:
1701 1. Item one goes here.
1703 1.1. Item two goes here.
1704 1.2. And item three here.
1705 2. And item four here.
1706 -item A list of type -item without list markers.
1708 .Bl -item -offset indent
1710 .It
1711 Item one goes here.
1712 Item one goes here.
1713 Item one goes here.
1714 .It
1715 Item two here.
1716 Item two here.
1717 Item two here.
1718 .El
1719 Produces:
1721 Item one goes here. Item one goes here. Item one goes
1723 here.
1724 Item two here. Item two here. Item two here.
1726 -tag A list with tags. Use -width to specify the tag width.
1728 SL sleep time of the process (seconds blocked)
1730 PAGEIN
1731 number of disk I/O's resulting from references by
1732 the process to pages not loaded in core.
1733 UID numerical user-id of process owner
1734 PPID numerical id of parent of process priority (non-pos‐
1735 itive when in non-interruptible wait)
1736 The raw text:
1738 .Bl -tag -width "PPID" -compact -offset indent
1740 .It SL
1741 sleep time of the process (seconds blocked)
1742 .It PAGEIN
1743 number of disk
1744 .Tn I/O Ns 's
1745 resulting from references by the process
1746 to pages not loaded in core.
1747 .It UID
1748 numerical user-id of process owner
1749 .It PPID
1750 numerical id of parent of process priority
1751 (non-positive when in non-interruptible wait)
1752 .El
1753 -diag Diag lists create section four diagnostic lists and are similar
1755 to inset lists except callable macros are ignored. The -width
1756 flag is not meaningful in this context.
1757 Example:
1759 .Bl -diag
1761 .It You can't use Sy here.
1762 The message says all.
1763 .El
1764 produces
1766 You can't use Sy here. The message says all.
1768 -hang A list with hanging tags.
1770 Hanged labels appear similar to tagged lists when the
1772 label is smaller than the label width.
1773 Longer hanged list labels blend into the paragraph unlike
1775 tagged paragraph labels.
1776 And the unformatted text which created it:
1778 .Bl -hang -offset indent
1780 .It Em Hanged
1781 labels appear similar to tagged lists when the
1782 label is smaller than the label width.
1783 .It Em Longer hanged list labels
1784 blend into the paragraph unlike
1785 tagged paragraph labels.
1786 .El
1787 -ohang Lists with overhanging tags do not use indentation for the
1789 items; tags are written to a separate line.
1790 SL
1792 sleep time of the process (seconds blocked)
1793 PAGEIN
1795 number of disk I/O's resulting from references by the
1796 process to pages not loaded in core.
1797 UID
1799 numerical user-id of process owner
1800 PPID
1802 numerical id of parent of process priority (non-positive
1803 when in non-interruptible wait)
1804 The raw text:
1806 .Bl -ohang -offset indent
1808 .It Sy SL
1809 sleep time of the process (seconds blocked)
1810 .It Sy PAGEIN
1811 number of disk
1812 .Tn I/O Ns 's
1813 resulting from references by the process
1814 to pages not loaded in core.
1815 .It Sy UID
1816 numerical user-id of process owner
1817 .It Sy PPID
1818 numerical id of parent of process priority
1819 (non-positive when in non-interruptible wait)
1820 .El
1821 -inset Here is an example of inset labels:
1823 Tag The tagged list (also called a tagged paragraph) is
1825 the most common type of list used in the Berkeley manuals.
1826 Use a -width attribute as described below.
1827 Diag Diag lists create section four diagnostic lists and
1829 are similar to inset lists except callable macros are
1830 ignored.
1831 Hang Hanged labels are a matter of taste.
1833 Ohang Overhanging labels are nice when space is con‐
1835 strained.
1836 Inset Inset labels are useful for controlling blocks of
1838 paragraphs and are valuable for converting -mdoc manuals
1839 to other formats.
1840 Here is the source text which produced the above example:
1842 .Bl -inset -offset indent
1844 .It Em Tag
1845 The tagged list (also called a tagged paragraph)
1846 is the most common type of list used in the
1847 Berkeley manuals.
1848 .It Em Diag
1849 Diag lists create section four diagnostic lists
1850 and are similar to inset lists except callable
1851 macros are ignored.
1852 .It Em Hang
1853 Hanged labels are a matter of taste.
1854 .It Em Ohang
1855 Overhanging labels are nice when space is constrained.
1856 .It Em Inset
1857 Inset labels are useful for controlling blocks of
1858 paragraphs and are valuable for converting
1859 .Nm -mdoc
1860 manuals to other formats.
1861 .El
1862 -column This list type generates multiple columns. The number of col‐
1864 umns and the width of each column is determined by the arguments
1865 to the -column list, ⟨string1⟩, ⟨string2⟩, etc. If ⟨stringN⟩
1866 starts with a ‘.’ (dot) immediately followed by a valid -mdoc
1867 macro name, interpret ⟨stringN⟩ and use the width of the result.
1868 Otherwise, the width of ⟨stringN⟩ (typeset with a fixed-width
1869 font) is taken as the Nth column width.
1870 Each ‘.It’ argument is parsed to make a row, each column within
1872 the row is a separate argument separated by a tab or the ‘.Ta’
1873 macro.
1874 The table:
1876 String Nroff Troff
1878 <= <= ≤
1879 >= >= ≥
1880 was produced by:
1882 .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
1884 .It Sy String Ta Sy Nroff Ta Sy Troff
1885 .It Li <= Ta <= Ta \*(<=
1886 .It Li >= Ta >= Ta \*(>=
1887 .El
1888 Other keywords:
1890 -width ⟨string⟩ If ⟨string⟩ starts with a ‘.’ (dot) immediately fol‐
1892 lowed by a valid -mdoc macro name, interpret ⟨string⟩
1893 and use the width of the result. Almost all lists in
1894 this document use this option.
1895 Example:
1897 .Bl -tag -width ".Fl test Ao Ar string Ac"
1899 .It Fl test Ao Ar string Ac
1900 This is a longer sentence to show how the
1901 .Fl width
1902 flag works in combination with a tag list.
1903 .El
1904 gives:
1906 -test ⟨string⟩ This is a longer sentence to show how
1908 the -width flag works in combination
1909 with a tag list.
1910 (Note that the current state of -mdoc is saved before
1912 ⟨string⟩ is interpreted; afterwards, all variables are
1913 restored again. However, boxes (used for enclosures)
1914 can't be saved in GNU troff(1); as a consequence, argu‐
1915 ments must always be balanced to avoid nasty errors.
1916 For example, do not write ‘.Ao Ar string’ but ‘.Ao Ar
1917 string Xc’ instead if you really need only an opening
1918 angle bracket.)
1919 Otherwise, if ⟨string⟩ is a valid numeric expression
1921 (with a scale indicator other than ‘u’), use that value
1922 for indentation. The most useful scale indicators are
1923 ‘m’ and ‘n’, specifying the so-called Em and En square.
1924 This is approximately the width of the letters ‘m’ and
1925 ‘n’ respectively of the current font (for nroff output,
1926 both scale indicators give the same values). If
1927 ⟨string⟩ isn't a numeric expression, it is tested
1928 whether it is an -mdoc macro name, and the default
1929 width value associated with this macro is used.
1930 Finally, if all tests fail, the width of ⟨string⟩
1931 (typeset with a fixed-width font) is taken as the
1932 width.
1933 If a width is not specified for the tag list type,
1935 every time ‘.It’ is invoked, an attempt is made to
1936 determine an appropriate width. If the first argument
1937 to ‘.It’ is a callable macro, the default width for
1938 that macro will be used; otherwise, the default width
1939 of ‘.No’ is used.
1940 -offset ⟨string⟩ If ⟨string⟩ is indent, a default indent value (normally
1942 set to 6n, similar to the value used in ‘.Dl’ or ‘.Bd’)
1943 is used. If ⟨string⟩ is a valid numeric expression
1944 instead (with a scale indicator other than ‘u’), use
1945 that value for indentation. The most useful scale
1946 indicators are ‘m’ and ‘n’, specifying the so-called Em
1947 and En square. This is approximately the width of the
1948 letters ‘m’ and ‘n’ respectively of the current font
1949 (for nroff output, both scale indicators give the same
1950 values). If ⟨string⟩ isn't a numeric expression, it is
1951 tested whether it is an -mdoc macro name, and the
1952 default offset value associated with this macro is
1953 used. Finally, if all tests fail, the width of
1954 ⟨string⟩ (typeset with a fixed-width font) is taken as
1955 the offset.
1956 -compact Suppress insertion of vertical space before the list
1958 and between list items.
1959
1961 Here a list of the remaining macros which do not fit well into one of the
1962 above sections. We couldn't find real examples for the following macros:
1963 ‘.Me’ and ‘.Ot’. They are documented here for completeness - if you know
1964 how to use them properly please send a mail to bug-groff@gnu.org (includ‐
1965 ing an example).
1966 .Bt prints
1968 is currently in beta test.
1970 It is neither callable nor parsed and takes no arguments.
1972 .Fr
1974 Usage: .Fr ⟨function return value⟩ ...
1976 Don't use this macro. It allows a break right before the return
1978 value (usually a single digit) which is bad typographical behaviour.
1979 Use ‘\~’ to tie the return value to the previous word.
1980 .Hf Use this macro to include a (header) file literally. It first
1982 prints ‘File:’ followed by the file name, then the contents of
1983 ⟨file⟩.
1984 Usage: .Hf ⟨file⟩
1986 It is neither callable nor parsed.
1988 .Lk To be written.
1990 .Me Exact usage unknown. The documentation in the -mdoc source file
1992 describes it as a macro for “menu entries”.
1993 Its default width is 6n.
1995 .Mt To be written.
1997 .Ot Exact usage unknown. The documentation in the -mdoc source file
1999 describes it as “old function type (fortran)”.
2000 .Sm Activate (toggle) space mode.
2002 Usage: .Sm [on | off] ...
2004 If space mode is off, no spaces between macro arguments are
2006 inserted. If called without a parameter (or if the next parameter
2007 is neither ‘on’ nor ‘off’, ‘.Sm’ toggles space mode.
2008 .Ud prints
2010 currently under development.
2012 It is neither callable nor parsed and takes no arguments.
2014
2016 The following strings are predefined:
2017 String Nroff Troff Meaning
2019 <= <= ≤ less equal
2020 >= >= ≥ greater equal
2021 Rq '' ” right double quote
2022 Lq `` “ left double quote
2023 ua ^ ↑ upwards arrow
2024 aa ´ ´ acute accent
2025 ga ` ` grave accent
2026 q " " straight double quote
2027 Pi pi π greek pi
2028 Ne != ≠ not equal
2029 Le <= ≤ less equal
2030 Ge >= ≥ greater equal
2031 Lt < < less than
2032 Gt > > greater than
2033 Pm +- ± plus minus
2034 If infinity ∞ infinity
2035 Am & & ampersand
2036 Na NaN NaN not a number
2037 Ba | | vertical bar
2038 The names of the columns Nroff and Troff are a bit misleading; Nroff
2040 shows the ASCII representation, while Troff gives the best glyph form
2041 available. For example, a Unicode enabled TTY-device will have proper
2042 glyph representations for all strings, whereas the enhancement for a
2043 Latin1 TTY-device is only the plus-minus sign.
2044 String names which consist of two characters can be written as ‘\*(xx’;
2046 string names which consist of one character can be written as ‘\*x’. A
2047 generic syntax for a string name of any length is ‘\*[xxx]’ (this is a
2048 GNU troff(1) extension).
2049
2051 The debugging macro ‘.Db’ available in previous versions of -mdoc has
2052 been removed since GNU troff(1) provides better facilities to check
2053 parameters; additionally, many error and warning messages have been added
2054 to this macro package, making it both more robust and verbose.
2055 The only remaining debugging macro is ‘.Rd’ which yields a register dump
2057 of all global registers and strings. A normal user will never need it.
2058
2060 By default, the package inhibits page breaks, headers, and footers if
2061 displayed with a TTY device like ‘latin1’ or ‘unicode’ to make the manual
2062 more efficient for viewing on-line. This behaviour can be changed (e.g.
2063 to create a hardcopy of the TTY output) by setting the register ‘cR’ to
2064 zero while calling groff:
2065 groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
2067 For double-sided printing, set register ‘D’ to 1:
2069 groff -Tps -rD1 -mdoc foo.man > foo.ps
2071 To change the document font size to 11pt or 12pt, set register ‘S’
2073 accordingly:
2074 groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
2076 Register ‘S’ is ignored for TTY devices.
2078 The line and title length can be changed by setting the registers ‘LL’
2080 and ‘LT’, respectively:
2081 groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less
2083 If not set, both registers default to 78n for TTY devices and 6.5i other‐
2085 wise.
2086
2088 doc.tmac The main manual macro package.
2089 mdoc.tmac A wrapper file to call doc.tmac.
2090 mdoc/doc-common Common strings, definitions, stuff related typographic
2091 output.
2092 mdoc/doc-nroff Definitions used for a TTY output device.
2093 mdoc/doc-ditroff Definitions used for all other devices.
2094 mdoc.local Local additions and customizations.
2095 andoc.tmac This file checks whether the -mdoc or the -man package
2096 should be used.
2097
2099 groff(1), man(1), troff(1), groff_man(7)
2100
2102 Section 3f has not been added to the header routines.
2103 ‘.Nm’ font should be changed in NAME section.
2105 ‘.Fn’ needs to have a check to prevent splitting up if the line length is
2107 too short. Occasionally it separates the last parenthesis, and sometimes
2108 looks ridiculous if a line is in fill mode.
2109 The list and display macros do not do any keeps and certainly should be
2111 able to.
2112BSD October 07, 2002 BSD