1 .\" groff_mdoc.reference.man
3 .\" A complete reference for mdocNG (not finished yet)
5 .\" Based on NetBSD's mdoc.samples.7, version 1.21.
8 .\" Warning: You can't format this file with the old mdoc macros!
11 .\" Copyright (c) 1990, 1993
12 .\" The Regents of the University of California. All rights reserved.
14 .\" Redistribution and use in source and binary forms, with or without
15 .\" modification, are permitted provided that the following conditions
17 .\" 1. Redistributions of source code must retain the above copyright
18 .\" notice, this list of conditions and the following disclaimer.
19 .\" 2. Redistributions in binary form must reproduce the above copyright
20 .\" notice, this list of conditions and the following disclaimer in the
21 .\" documentation and/or other materials provided with the distribution.
22 .\" 3. All advertising materials mentioning features or use of this software
23 .\" must display the following acknowledgement:
24 .\" This product includes software developed by the University of
25 .\" California, Berkeley and its contributors.
26 .\" 4. Neither the name of the University nor the names of its contributors
27 .\" may be used to endorse or promote products derived from this software
28 .\" without specific prior written permission.
30 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
31 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
32 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
34 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
35 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
36 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
37 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
39 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
42 .\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93
44 .\" This reference invokes every macro in the package several
45 .\" times and is guaranteed to give a worst case performance
46 .\" for an already extremely slow package.
49 .ds doc-punct-chars \f[R]{.\ ,\ :\ ;\ (\ )\ [\ ]}
60 .Nd reference for groff's mdoc implementation
65 .Nm man mdoc.reference
70 A complete reference for writing
78 formatting package for
83 package, addressed page layout leaving the manipulation of fonts and other
84 typesetting details to the individual author.
87 page layout macros make up the
88 .Em "page structure domain"
89 which consists of macros for titles, section headers, displays and lists
90 \- essentially items which affect the physical position of text on a
92 In addition to the page structure domain, there are two more domains, the
97 The general text domain is defined as macros which perform tasks such as
98 quoting or emphasizing pieces of text.
99 The manual domain is defined as macros that are a subset of the day to day
100 informal language used to describe commands, routines and related to
103 Macros in the manual domain handle command names, command line arguments and
104 options, function names, function parameters, pathnames, variables, cross
105 references to other manual pages, and so on.
106 These domain items have value for both the author and the future user of the
108 It is hoped the consistency gained across the manual set will provide easier
109 translation to future documentation tools.
113 manual pages, a manual entry is simply referred to as a man page, regardless
114 of actual length and without sexist intention.
119 The material presented in the remainder of this document is outlined
122 .Bl -enum -width 3n -offset indent
124 . Tn "TROFF IDIOSYNCRASIES"
126 . Bl -tag -width 2n -compact
128 . It "Passing Space Characters in an Argument"
129 . It "Trailing Blank Space Characters"
130 . It "Escaping Special Characters"
131 . It "Other Possible Pitfalls"
135 . Tn "THE ANATOMY OF A MAN PAGE"
137 . Bl -tag -width 2n -compact
138 . It "A Manual Page Template"
148 . Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS"
150 . Bl -tag -width 2n -compact
151 . It "What's in a Name" Ns Ld
152 . It "General Syntax"
158 . Bl -tag -width 2n -compact
161 . It "Configuration Declarations (Section Four Only)"
162 . It "Command Modifiers"
163 . It "Defined Variables"
164 . It "Errno's (Section Two Only)"
165 . It "Environment Variables"
166 . It "Function Arguments"
167 . It "Function Declarations"
169 . It "Functions (Library Routines)"
170 . It "Function Types"
171 . \" .It "Header File (including source code)"
172 . It "Interactive Commands"
178 . It "Cross References"
182 . Tn "GENERAL TEXT DOMAIN"
184 . Bl -tag -width 2n -compact
188 . It "Emphasis Macro"
189 . It "Enclosure/Quoting Macros"
191 . Bl -tag -width 2n -compact
192 . It "Angle Bracket Quote/Enclosure"
193 . It "Bracket Quotes/Enclosure"
194 . It "Double Quote macro/Enclosure"
195 . It "Parenthesis Quote/Enclosure"
196 . It "Single Quotes/Enclosure"
200 . It "Extended Arguments"
201 . It "No\-Op or Normal Text Macro"
202 . It "No\-Space Macro"
203 . It "Section Cross References"
204 . It "Symbolic Macro"
205 . It "References and Citations"
206 . It "Trade Names (Acronyms and Type Names)"
210 . Tn "PAGE STRUCTURE DOMAIN"
212 . Bl -tag -width 2n -compact
213 . It "Section Headers"
214 . It "Paragraphs and Line Spacing"
217 . It "Lists and Columns"
221 . Tn "PREDEFINED STRINGS"
227 . Tn "FORMATTING WITH GROFF, TROFF, AND NROFF"
237 .Sh TROFF IDIOSYNCRASIES
241 package attempts to simplify the process of writing a man page.
242 Theoretically, one should not have to learn the dirty details of
247 however, there are a few limitations which are unavoidable and best gotten
249 And, too, be forewarned, this package is
258 a macro is called by placing a
260 (dot character) at the beginning of a line followed by the two-character
261 (or three-character) name for the macro.
262 There can be space characters between the dot and the macro name (but
265 Arguments may follow the macro separated by spaces (again, no tabs).
266 It is the dot character at the beginning of the line which causes
269 to interpret the next two (or more) characters as a macro name.
270 A single starting dot followed by nothing is ignored.
273 (dot character) at the beginning of an input line in some context other than
274 a macro invocation, precede the
281 translates literally to a zero-width space, and is never displayed in
287 macros accept an unlimited number of arguments (contrary to other versions
288 of troff which can't handle more than nine arguments).
289 In limited cases, arguments may be continued or extended on the next
291 .Sx Extended Arguments
293 Almost all macros handle quoted arguments (see
294 .Sx Passing Space Characters in an Argument
299 general text domain and manual domain macros are special in that their
302 for callable macro names.
303 This means an argument on the argument list which matches a general text or
304 manual domain macro name and is determined to be callable will be executed
305 or called when it is processed.
306 In this case the argument, although the name of a macro, is not preceded by
310 It is in this manner that many macros are nested; for example the
315 the flag and argument macros,
319 to specify an optional flag with an argument:
321 .Bl -tag -xwidth ".Op Fl s Ar bytes" -offset indent
324 .Ql Li ".Op Fl s Ar bytes"
328 To prevent a string from being interpreted as a macro name, precede the
329 string with the escape sequence
332 .Bl -tag -xwidth ".Op \&Fl s \&Ar bytes" -offset indent
333 .It Op \&Fl s \&Ar bytes
335 .Ql Li ".Op \e&Fl s \e&Ar bytes"
343 are not interpreted as macros.
344 Macros whose argument lists are parsed for callable arguments are referred
347 and macros which may be called from an argument list are referred to as
349 throughout this document and in the companion quick-reference manual
353 as almost all of the macros in
355 are parsed, but as it was cumbersome to constantly refer to macros as
356 being callable and being able to call other macros, the term parsed
359 .Ss Passing Space Characters in an Argument
361 Sometimes it is desirable to give as an argument a string containing one or
362 more blank space characters.
363 This may be necessary to specify arguments to macros which expect particular
364 arrangement of items in the argument list. Additionally, it makes
367 For example, the function macro
369 expects the first argument to be the name of a function and any remaining
370 arguments to be function parameters.
373 stipulates the declaration of function parameters in the parenthesized
374 parameter list, each parameter is guaranteed to be at minimum a two word
379 There are two possible ways to pass an argument which contains
381 One way of passing a string containing blank spaces is to use the hard or
382 unpaddable space character
384 that is, a blank space preceded by the escape character
386 This method may be used with any macro but has the side effect of
387 interfering with the adjustment of text over the length of a line.
389 sees the hard space as if it were any other printable character and cannot
390 split the string into blank or newline separated pieces as one would expect.
391 This method is useful for strings which are not expected to overlap a line
393 An alternative is to use
395 a paddable (i.e.\& stretchable), unbreakable space (this is a
399 The second method is to enclose the string with double quotes.
403 .Bl -tag -xwidth ".Fn fetch char\ *str" -offset indent
404 .It Fn fetch char\ *str
406 .Ql .Fn fetch char\e *str
407 .It Fn fetch "char *str"
408 can also be created by
409 .Ql .Fn fetch "\\*[q]char *str\\*[q]"
415 before the space resp.\& the double quotes were omitted,
417 would see three arguments, and the result would be:
419 .Dl Fn fetch char *str
421 For an example of what happens when the parameter list overlaps a newline
426 .Ss Trailing Blank Space Characters
429 can be confused by blank space characters at the end of a line.
430 It is a wise preventive measure to globally remove all blank spaces
432 .Ao blank-space Ac Ns Ao end-of-line Ac
434 Should the need arise to force a blank character at the end of a line, it
435 may be forced with an unpaddable space and the
441 .Ss Escaping Special Characters
443 Special characters like the newline character
445 are handled by replacing the
451 to preserve the backslash.
453 .Ss Other Possible Pitfalls
455 A warning is emitted when an empty input line is found outside of displays
460 (Well, it is even better to use
462 macros to avoid the usage of low-level commands).
464 Leading spaces will cause a break and are output directly.
465 Avoid this behaviour if possible.
466 Similarly, don't use more than one space character between words in an
467 ordinary text line; contrary to other text formatters, they are
469 replaced with a single space.
473 directly as an argument.
482 inserts two space characters after a punctuation mark closing a sentence
487 are treated transparently, not influencing the sentence-ending behaviour).
488 To change this, insert
490 before or after the dot:
492 .Bd -literal -offset indent -compact
511 .Bd -filled -offset indent
528 As can be seen in the first and third line,
530 handles punctuation characters specially in macro arguments.
531 This will be explained in section
534 In the same way, you have to protect trailing full stops of abbreviations
535 with a trailing zero-width space:
538 A comment in the source file of a man page can be either started with
544 anywhere (the latter is a
547 extension); the rest of such a line is ignored.
550 .Sh THE ANATOMY OF A MAN PAGE
552 The body of a man page is easily constructed from a basic template:
554 .Bd -literal -offset indent
555 \&.\e" /usr/share/misc/mdoc.template:
556 \&.\e" The following requests are required for all man pages.
558 \&.Dd Month day, year
559 \&.Os OPERATING_SYSTEM [version/release]
560 \&.Dt DOCUMENT_TITLE [section number] [volume]
563 \&.Nd one line description of name
567 \&.\e" The following requests should be uncommented and
568 \&.\e" used where appropriate.
569 \&.\e" .Sh IMPLEMENTATION NOTES
570 \&.\e" This next request is for sections 2, 3 and 9 function
571 \&.\e" return values only.
572 \&.\e" .Sh RETURN VALUES
574 \&.\e" This next request is for sections 1, 6, 7, 8 & 9 only
575 \&.\e" .Sh ENVIRONMENT
579 \&.\e" This next request is for sections 1, 6, 7, 8 & 9 only
580 \&.\e" (command return values (to shell) and
581 \&.\e" fprintf/stderr type diagnostics)
582 \&.\e" .Sh DIAGNOSTICS
584 \&.\e" The next request is for sections 2, 3 & 9 error
585 \&.\e" and signal handling only.
595 The first items in the template are the macros
600 the document date, the operating system the man page or subject source is
601 developed or modified for, and the man page title (in
603 along with the section of the manual the page belongs in.
604 These macros identify the page and are discussed below in
607 The remaining items in the template are section headers
615 The headers are discussed in
616 .Sx PAGE STRUCTURE DOMAIN ,
617 after presentation of
619 Several content macros are used to demonstrate page layout macros; reading
620 about content macros before page layout macros is recommended.
625 In the description of all macros below, optional arguments are put into
629 represents zero or more additional arguments.
630 Alternative values for a parameter are separated with
632 If there are alternative values for a mandatory parameter, braces are used
635 to enclose the value set.
636 Meta-variables are specified within angles.
640 .Bl -tag -width 6n -offset indent
644 .Op \-test1 Op \-test2 | \-test3
650 Except stated explicitly, all macros are parsed and callable.
655 The title macros are part of the page structure domain but are presented
656 first and separately for someone who wishes to start writing a man page
658 Three header macros designate the document title or manual page title, the
659 operating system, and the date of authorship.
660 These macros are called once at the very beginning of the document and are
661 used to construct headers and footers only.
665 .Op Aq document title
666 .Op Aq section number
669 The document title is the subject of the man page and must be in
671 due to troff limitations.
675 The section number may be a number in the range
676 .No 1,\~ Ns Ld Ns ,\~9
682 If it is specified, and no volume name is given, a default volume name is
684 A volume name may be arbitrary or one of the following:
687 .Bl -column LOCAL -offset indent -compact
688 .It Li USD Ta "\*[volume-ds-USD]"
689 .It Li PS1 Ta "\*[volume-ds-PS1]"
690 .It Li AMD Ta "\*[volume-ds-AMD]"
691 .It Li SMM Ta "\*[volume-ds-SMM]"
692 .It Li URM Ta "\*[volume-ds-URM]"
693 .It Li PRM Ta "\*[volume-ds-PRM]"
694 .It Li KM Ta "\*[volume-ds-KM]"
695 .It Li IND Ta "\*[volume-ds-IND]"
696 .It Li LOCAL Ta "\*[volume-ds-LOCAL]"
697 .It Li CON Ta "\*[volume-ds-CON]"
709 Values from the previous table will specify a new volume name.
710 If the third parameter is a keyword designating a computer architecture,
711 its value is appended to the volume name as specified by the second
712 parameter. By default, the following architecture keywords are defined:
714 \# we use `No' to avoid hyphenation
715 .Bd -ragged -offset indent
716 .No alpha , amiga , arc , arm26 , arm32 , atari , bebox , cobalt , evbsh3 ,
717 .No hp300 , hpcmips , i386 , luna68k , m68k , mac68k , macppc , mips ,
718 .No mmeye , mvme68k , news68k , newsmips , next68k , ofppc , pc532 , pmax ,
719 .No powerpc , prep , sgimips , sh3 , sparc , sparc64 , sun3 , tahoe , vax ,
724 In the following examples, the left (which is identical to the right) and
725 the middle part of the manual page header strings are shown.
728 .Bl -tag -xwidth ".Li .Dt\ FOO\ 2\ mac68k" -compact -offset indent
731 .Ql System Reference Manual
732 .It Li ".Dt FOO 2 mac68k"
734 .Ql System Programmer's Manual (mac68k Architecture)
735 .It Li ".Dt FOO \*[q]\*[q] bar"
742 Local, OS-specific additions might be found in the file
744 look for strings named
746 (for the former type) and
748 (for the latter type);
750 then denotes the keyword to be used with the
754 This macro is neither callable nor parsable.
757 .Op Aq operating system
760 If the first parameter is empty,
762 is used as the default operating system.
763 This may be overridden in the local configuration file.
764 In general, the name of the operating system should be the common acronym,
769 The release should be the standard release nomenclature for the system
771 In the following table, the possible second arguments for some predefined
772 operating systems are listed.
775 local additions might be defined in
777 look for strings named
778 .Ql operating-system-XXX-YYY ,
781 is the acronym for the operating system and
786 .Bl -tag -xwidth ".No FreeBSD" -offset indent
788 7th, 7, III, 3, V, V.2, V.3, V.4
790 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
792 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.2e,
795 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1,
796 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1,
804 an unknown second parameter will be replaced with the string
806 for the other predefined acronyms it will be ignored and a warning message
808 Unrecognized arguments are displayed as given in the page footer.
809 For instance, a typical footer might be:
814 .Ql 4.3\~Berkeley Distribution ,
815 or for a locally produced set
817 .Dl .Os CS Department
824 macro is not present, the bottom left corner of the manual page will be
827 This macro is neither callable nor parsable.
838 is used for the date string.
839 If it has exactly three arguments, they are concatenated, separated with
842 .Dl .Dd January 25, 2001
844 Otherwise, the current date is used, ignoring the parameters.
846 This macro is neither callable nor parsable.
850 .Sh INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
852 .Ss What's in a name Ns Ld
854 The manual domain macro names are derived from the day to day informal
855 language used to describe commands, subroutines and related files.
856 Slightly different variations of this language are used to describe the
857 three different aspects of writing a man page.
858 First, there is the description of
861 Second is the description of a
866 macros, and third, the description of a command to a user in the verbal
867 sense; that is, discussion of a command in the text of a man page.
871 macros are themselves a type of command; the general syntax for a troff
874 .Bd -filled -offset indent
875 .Li ".Xx argument1 argument2" Ld
880 is a macro command or request, and anything following it are arguments to
882 In the second case, the description of a
884 command using the content macros is a bit more involved; a typical
886 command line might be displayed as:
888 .Bd -filled -offset indent
891 .Ao Ar infile Ac Ao Ar outfile Ac
897 is the command name and the
902 argument designated as optional by the option brackets.
911 in this example, the user has to replace the meta expressions given in angle
912 brackets with real file names.
913 Note that in this document meta arguments are used to describe
915 commands; in most man pages, meta variables are not specifically written
917 The macros which formatted the above example:
919 .Bd -literal -offset indent
922 \&.Ao Ar infile Ac Ao Ar outfile Ac
926 In the third case, discussion of commands and command syntax includes both
927 examples above, but may add more detail.
932 from the example above might be referred to as
936 Some command line argument lists are quite long:
939 .Bl -tag -xwidth ".Nm make" -offset indent -compact
945 .Op Fl I Ar directory
947 .Op Ar variable=value
955 Here one might talk about the command
957 and qualify the argument,
959 as an argument to the flag,
961 or discuss the optional file operand
963 In the verbal context, such detail can prevent confusion, however the
965 package does not have a macro for an argument
970 argument macro is used for an operand or file argument like
972 as well as an argument to a flag like
974 The make command line was produced from:
976 .Bd -literal -offset indent
979 \&.Op Fl D Ar variable
981 \&.Op Fl f Ar makefile
982 \&.Op Fl I Ar directory
983 \&.Op Fl j Ar max_jobs
984 \&.Op Ar variable=value
995 macros are explained in
1000 The manual domain and general text domain macros share a similar syntax with
1001 a few minor deviations; most notably,
1007 differ only when called without arguments; and
1011 impose an order on their argument lists.
1012 All content macros are capable of recognizing and properly handling
1013 punctuation, provided each punctuation character is separated by a leading
1015 If a request is given:
1017 .Dl \&.Ar sptr, ptr),
1023 The punctuation is not recognized and all is output in the
1026 If the punctuation is separated by a leading white space:
1028 .Dl \&.Ar "sptr , ptr ) ,"
1032 .Dl Ar sptr , ptr ) ,
1034 The punctuation is now recognized and output in the default font
1035 distinguishing it from the argument strings.
1036 To remove the special meaning from a punctuation character escape it with
1040 is limited as a macro language, and has difficulty when presented with a
1041 string containing a member of the mathematical, logical or quotation set:
1043 .Bd -literal -offset indent-two
1044 {+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
1050 may assume it is supposed to actually perform the operation or evaluation
1051 suggested by the characters.
1052 To prevent the accidental evaluation of these characters, escape them with
1054 Typical syntax is shown in the first content macro displayed below,
1059 The address macro identifies an address construct.
1061 .Dl Usage: .Ad Ao address Ac Ld
1063 .Bl -tag -xwidth ".Li .Ad\ f1\ ,\ f2\ ,\ f3\ :" -compact -offset 15n
1066 .It Li ".Ad addr1 ."
1068 .It Li ".Ad addr1 , file2"
1070 .It Li ".Ad f1 , f2 , f3 :"
1072 .It Li ".Ad addr ) ) ,"
1081 argument macro may be used whenever an argument is referenced.
1083 .Dl Usage: .Ar Oo Ao argument Ac Oc Ld
1085 .Bl -tag -xwidth ".Li .Ar\ file1\ file2" -compact -offset 15n
1090 .It Li ".Ar file1 ."
1092 .It Li ".Ar file1 file2"
1094 .It Li ".Ar f1 f2 f3 :"
1096 .It Li ".Ar file ) ) ,"
1101 .Ss Configuration Declaration (Section Four Only)
1105 macro is used to demonstrate a
1107 declaration for a device interface in a section four manual.
1109 .Dl Usage: .Cd Ao argument Ac Ld
1111 .Bl -tag -xwidth ".Li .Cd\ Xdevice\ le0\ at\ scode?X" -offset 15n
1112 .It Li ".Cd \*[q]device le0 at scode?\*[q]"
1113 \# since .Cd causes a break we use .Nm
1114 .Nm "device le0 at scode?"
1118 .Ss Command Modifier
1120 The command modifier is identical to the
1122 (flag) command with the exception
1125 macro does not assert a dash in front of every argument.
1126 Traditionally flags are marked by the preceding dash, however, some commands
1127 or subsets of commands do not use them.
1128 Command modifiers may also be specified in conjunction with interactive
1129 commands such as editor commands.
1133 .Ss Defined Variables
1135 A variable which is defined in an include file is specified by the macro
1138 .Dl Usage: .Dv Ao defined variable Ac Ld
1140 .Bl -tag -xwidth ".Li .Dv\ MAXHOSTNAMELEN" -compact -offset 15n
1141 .It Li ".Dv MAXHOSTNAMELEN"
1143 .It Li ".Dv TIOCGPGRP )"
1148 .Ss Errno's (Section Two Only)
1152 errno macro specifies the error return value for section two library
1154 The second example below shows
1158 general text domain macro, as it would be used in a section two manual page.
1160 .Dl Usage: .Er Ao errno type Ac Ld
1162 .Bl -tag -xwidth ".Li .Bq\ Er\ ENOTDIR" -compact -offset 15n
1165 .It Li ".Er ENOENT ) ;"
1167 .It Li ".Bq Er ENOTDIR"
1172 .Ss Environment Variables
1176 macro specifies an environment variable.
1178 .Dl Usage: .Ev Ao argument Ac Ld
1180 .Bl -tag -xwidth ".Li .Ev\ PRINTER\ )\ )\ ," -compact -offset 15n
1181 .It Li ".Ev DISPLAY"
1185 .It Li ".Ev PRINTER ) ) ,"
1190 .Ss Function Argument
1194 macro is used to refer to function arguments (parameters) outside of the
1196 section of the manual or inside the
1198 section if the enclosure macros
1206 may also be used to refer to structure members.
1208 .Dl Usage: .Fa Ao function argument Ac Ld
1210 .Bl -tag -xwidth ".Li .Fa\ d_namlen\ )\ )\ ," -compact -offset 15n
1211 .It Li ".Fa d_namlen ) ) ,"
1213 .It Li ".Fa iov_len"
1218 .Ss Function Declaration
1222 macro is used in the
1224 section with section two or three functions.
1225 It is neither parsable nor callable.
1227 .Dl Usage: .Fd Ao argument Ac Ld
1229 .Bl -tag -xwidth ".Li .Fd\ X#include\ <sys/types.h>X" -compact -offset 15n
1230 .It Li ".Fd \*[q]#include <sys/types.h>\*[q]"
1231 .Fd "#include <sys/types.h>"
1238 request causes a line break if a function has already been presented and a
1239 break has not occurred.
1240 This leaves a nice vertical space in between the previous function call and
1241 the declaration for the next function.
1247 macro handles command line flags.
1251 For interactive command flags, which are not prepended with a dash, the
1254 macro is identical, but without the dash.
1256 .Dl Usage: .Fl Ao argument Ac Ld
1258 .Bl -tag -xwidth ".Li .Fl\ xyz\ )\ ," -compact -offset 15n
1271 .It Li ".Fl xyz ) ,"
1279 macro without any arguments results in a dash representing stdin/stdout.
1282 a single dash will result in two dashes.
1284 .Ss Functions (Library Routines)
1288 macro is modeled on ANSI C conventions.
1290 .Dl Usage: .Fn Ao function Ac Oo Ao parameter Ac Oc Ld
1292 .Bl -tag -xwidth ".Li .Fn\ Xint\ alignX\ Xchar\ *ptrX\ ," -compact -offset 15n
1293 .It Li ".Fn getchar"
1295 .It Li ".Fn strlen ) ,"
1297 .It Li ".Fn \*[q]int align\*[q] \*[q]char *ptr\*[q] ,"
1298 .Fn "int align" "char *ptr" ,
1301 Note that any call to another macro signals the end of the
1303 call (it will insert a closing parenthesis at that point).
1305 For functions with many parameters (which is rare), the macros
1313 (function argument).
1317 .Bd -literal -offset indent
1318 \&.Fo "int res_mkquery"
1325 \&.Fa "struct rrec *newrr"
1334 .Bd -ragged -offset indent
1335 .Fo "int res_mkquery"
1342 .Fa "struct rrec *newrr"
1351 section, the function will always begin at the beginning of line.
1352 If there is more than one function presented in the
1354 section and a function type has not been given, a line break will occur,
1355 leaving a nice vertical space between the current function name and the one
1360 This macro is intended for the
1363 It may be used anywhere else in the man page without problems, but its main
1364 purpose is to present the function type in kernel normal form for the
1366 of sections two and three (it causes a page break, allowing the function
1367 name to appear on the next line).
1369 .Dl Usage: .Ft Ao type Ac Ld
1371 .Bl -tag -xwidth ".Li .Ft\ struct\ stat" -compact -offset 15n
1372 .It Li ".Ft struct stat"
1376 .Ss Interactive Commands
1380 macro designates an interactive or internal command.
1382 .Dl Usage: .Ic Ao argument Ac Ld
1384 .Bl -tag -xwidth ".Li .Ic\ setenv\ ,\ unsetenv" -compact -offset 15n
1387 .It Li ".Ic \*[q]do while {...}\*[q]"
1388 .Ic "do while {...}"
1389 .It Li ".Ic setenv , unsetenv"
1390 .Ic setenv , unsetenv
1397 literal macro may be used for special characters, variable constants, etc.\&
1398 -- anything which should be displayed as it would be typed.
1400 .Dl Usage: .Li Ao argument Ac Ld
1402 .Bl -tag -xwidth ".Li .Li\ cntrl-D\ )\ ," -compact -offset 15n
1405 .It Li ".Li M1 M2 M3 ;"
1407 .It Li ".Li cntrl-D ) ,"
1409 .It Li ".Li 1024 Ld"
1417 macro is used for the document title or subject name.
1418 It has the peculiarity of remembering the first argument it was called with,
1419 which should always be the subject name of the page.
1420 When called without arguments,
1422 regurgitates this initial name for the sole purpose of making less work for
1424 Note: A section two or three document function name is addressed with the
1432 and remaining sections.
1433 For interactive commands, such as the
1439 macro should be used.
1445 it can not recall the first argument it was invoked with.
1447 .Dl Usage: .Nm Oo Ao argument Ac Oc Ld
1449 .Bl -tag -xwidth ".Li .Nm\ mdoc.reference" -compact -offset 15n
1450 .It Li ".Nm mdoc.reference"
1452 .It Li ".Nm \e-mdoc"
1454 .It Li ".Nm foo ) ) ,"
1464 macro places option brackets around the any remaining arguments on the
1465 command line, and places any trailing punctuation outside the brackets.
1470 (which produce an opening resp.\& a closing option bracket) may be used
1471 across one or more lines or to specify the exact position of the closing
1474 .Dl Usage: .Op Oo Ao option Ac Oc Ld
1476 .Bl -tag -xwidth ".Li .Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ," -compact -offset 15n
1481 .It Li ".Op Fl k ) ."
1483 .It Li ".Op Fl k Ar kookfile"
1484 .Op Fl k Ar kookfile
1485 .It Li ".Op Fl k Ar kookfile ,"
1486 .Op Fl k Ar kookfile ,
1487 .It Li ".Op Ar objfil Op Ar corfil"
1488 .Op Ar objfil Op Ar corfil
1489 .It Li ".Op Fl c Ar objfil Op Ar corfil ,"
1490 .Op Fl c Ar objfil Op Ar corfil ,
1491 .It Li ".Op word1 word2"
1493 .It Li ".Li .Op Oo Ao option Ac Oc Ld"
1494 .Li .Op Oo Ao options Ac Oc Ld
1497 Here a typical example of the
1503 .Bd -literal -offset indent
1505 \&.Op Fl k Ar kilobytes
1506 \&.Op Fl i Ar interval
1514 .Bd -filled -offset indent
1516 .Op Fl k Ar kilobytes
1517 .Op Fl i Ar interval
1526 macro formats path or file names.
1528 .Dl Usage: .Pa Oo Ao pathname Ac Oc Ld
1530 .Bl -tag -xwidth ".Li .Pa\ /tmp/fooXXXXX\ )\ ." -compact -offset 15n
1533 .It Li ".Pa /usr/share"
1535 .It Li ".Pa /tmp/fooXXXXX ) ."
1536 .Pa /tmp/fooXXXXX ) .
1541 Generic variable reference.
1543 .Dl Usage: .Va Ao variable Ac Ld
1545 .Bl -tag -xwidth ".Li .Va\ Xchar\ sX\ ]\ )\ )\ ," -compact -offset 15n
1548 .It Li ".Va settimer ,"
1550 .It Li ".Va \*[q]int *prt\*[q] ) :"
1552 .It Li ".Va \*[q]char s\*[q] ] ) ) ,"
1553 .Va "char s" ] ) ) ,
1556 .Ss Manual Page Cross References
1560 macro expects the first argument to be a manual page name.
1561 The optional second argument, if a string (defining the manual section), is
1562 put into parentheses.
1564 .Dl Usage: .Xr Ao man page name Ac Oo Ao section Ac Oc Ld
1566 .Bl -tag -xwidth ".Li .Xr\ xinit\ 1x\ ;" -compact -offset 15n
1573 .It Li ".Xr xinit 1x ;"
1578 .Sh GENERAL TEXT DOMAIN
1583 .Dl Usage: .At Oo Ao version Ac Oc Ld
1585 .Bl -tag -xwidth ".Li .At\ v6\ ." -compact -offset 15n
1592 The following values for
1596 .Dl 32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4
1601 .Dl "Usage: .Bx" Bro -alpha | -beta | -devel Brc Ld
1602 .Dl " .Bx" Oo Ao version Ac Oo Ao release Ac Oc Oc Ld
1604 .Bl -tag -xwidth ".Li .Bx\ -devel" -compact -offset 15n
1609 .It Li ".Bx \-devel"
1614 will be prepended to the string
1616 The following values for
1620 .Dl Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
1625 .Dl Usage: .Nx Oo Ao version Ac Oc Ld
1627 .Bl -tag -xwidth ".Li .Nx\ 1.4\ ." -compact -offset 15n
1634 For possible values of
1636 see the description of the
1638 request above in section
1639 .Sx "TITLE MACROS" .
1644 .Dl Usage: .Fx Oo Ao version Ac Oc Ld
1646 .Bl -tag -xwidth ".Li .Fx\ 2.2\ ." -compact -offset 15n
1653 For possible values of
1655 see the description of the
1657 request above in section
1658 .Sx "TITLE MACROS" .
1665 .Bl -tag -xwidth ".Li .Ux" -compact -offset 15n
1672 Text may be stressed or emphasized with the
1675 The usual font for emphasis is italic.
1677 .Dl Usage: .Em Ao argument Ac Ld
1679 .Bl -tag -xwidth ".Li .Em\ vide\ infra\ )\ )\ ," -compact -offset 15n
1680 .It Li ".Em does not"
1682 .It Li ".Em exceed 1024 ."
1684 .It Li ".Em vide infra ) ) ,"
1685 .Em vide infra ) ) ,
1688 .\" The emphasis can be forced across several lines of text by using
1691 .\" macro discussed in
1694 .\" .Sx PAGE STRUCTURE DOMAIN .
1697 .\" We are certain the reason most people desire a Harvard MBA
1698 .\" so they can become to be successful philanthropists. Only
1699 .\" mathematicians and physicists go to graduate school strictly
1700 .\" to acquire infinite wealthy and fame. Its that inifinity
1701 .\" word that does it to them. Ruins them.
1704 .Ss Enclosure and Quoting Macros
1706 The concept of enclosure is similar to quoting.
1707 The object being to enclose one or more strings between a pair of characters
1708 like quotes or parentheses.
1709 The terms quoting and enclosure are used interchangeably throughout this
1711 Most of the one-line enclosure macros end in small letter
1713 to give a hint of quoting, but there are a few irregularities.
1714 For each enclosure macro there is also a pair of open and close macros which
1715 end in small letters
1723 .Bd -filled -offset 4n
1724 .Bl -column "quote" "close" "open" "Angle Bracket Enclosure" "`string' or string"
1725 .Em Quote Ta Em Open Ta Em Close Ta Em Function Ta Em Result
1726 .No .Aq Ta .Ao Ta .Ac Ta "Angle Bracket Enclosure" Ta Ao string Ac
1727 .No .Bq Ta .Bo Ta .Bc Ta "Bracket Enclosure" Ta Bo string Bc
1728 .No .Brq Ta .Bro Ta .Brc Ta "Brace Enclosure" Ta Bro string Brc
1729 .No .Dq Ta .Do Ta .Dc Ta "Double Quote" Ta Do string Dc
1730 .No Ta .Eo Ta .Ec Ta "Enclose String (in XX)" Ta XXstringXX
1731 .No .Pq Ta .Po Ta .Pc Ta "Parenthesis Enclosure" Ta Po string Pc
1732 .No .Ql Ta Ta Ta "Quoted Literal" Ta "`string' or string"
1733 .No .Qq Ta .Qo Ta .Qc Ta "Straight Double Quote" Ta Qo string Qc
1734 .No .Sq Ta .So Ta .Sc Ta "Single Quote" Ta So string Sc
1739 .Bl -tag -xwidth ".Li .Ec , .Eo"
1741 These macros expect the first argument to be the opening and closing strings
1744 The quoted literal macro behaves differently in troff and nroff mode.
1747 a quoted literal is always quoted.
1748 If formatted with troff, an item is only quoted if the width of the item is
1749 less than three constant width characters.
1750 This is to make short strings more visible where the font change to literal
1751 (constant width) is less noticeable.
1753 The prefix macro suppresses the whitespace between its first and second
1756 .Bl -tag -xwidth ".Li .Pf\ (\ Fa\ name2" -offset indent
1757 .It Li ".Pf ( Fa name2"
1764 macro (see below) performs the analogous suffix function.
1768 macro inserts an apostrophe and exits any special text modes, continuing in
1774 Examples of quoting:
1777 .Bl -tag -xwidth ".Li .Bq\ Em\ Greek\ ,\ French\ ." -compact -offset indent
1780 .It Li ".Aq Ar ctype.h ) ,"
1784 .It Li ".Bq Em Greek , French ."
1785 .Bq Em Greek , French .
1788 .It Li ".Dq string abc ."
1790 .It Li ".Dq \'^[A-Z]\'"
1792 .It Li ".Ql man mdoc"
1796 .It Li ".Qq string ) ,"
1798 .It Li ".Qq string Ns ),"
1804 .It Li ".Em or Ap ing"
1809 For a good example of nested enclosure macros, see the
1812 It was created from the same underlying enclosure macros as those presented
1818 extended argument list macros are discussed below.
1820 .Ss No\-Op or Normal Text Macro
1825 can be used in a macro command line for parameters which should
1832 if you really want that English word (and not the macro) as a parameter.
1834 .Dl Usage: .No Ao argument Ac Ld
1836 .Bl -tag -xwidth ".Li .No\ test\ Ta\ with\ Ta\ tabs" -compact -offset 15n
1837 .It Li ".No test Ta with Ta tabs"
1838 .No test Ta with Ta tabs
1845 macro suppresses insertion of a space between the current position and its
1847 For example, it is useful for old style argument lists where there is no
1848 space between the flag and argument:
1850 .Dl "Usage:" Ld Ao argument Ac \&Ns Oo Ao argument Ac Oc Ld
1851 .Dl " " .Ns Ao argument Ac Ld
1853 .Bl -tag -xwidth ".Li .Op\ Fl\ I\ Ns\ Ar\ directory" -compact -offset 15n
1854 .It Li ".Op Fl I Ns Ar directory"
1855 .Op Fl I Ns Ar directory
1860 macro always invokes the
1862 macro after eliminating the space unless another macro name follows it.
1863 If used as a request (i.e., the second form above in the
1870 .Ss Section Cross References
1874 macro designates a reference to a section header within the same document.
1876 .Dl Usage: .Sx Ao section reference Ac Ld
1878 .Bl -tag -xwidth ".Li .Sx\ FILES" -offset 15n
1885 The symbolic emphasis macro is generally a boldface macro in either the
1886 symbolic sense or the traditional English usage.
1888 .Dl Usage: .Sy Ao symbol Ac Ld
1890 .Bl -tag -xwidth ".Li .Sy\ Important\ Notice" -compact -offset 15n
1891 .It Li ".Sy Important Notice"
1892 .Sy Important Notice
1896 .Ss References and Citations
1898 The following macros make a modest attempt to handle references.
1899 At best, the macros make it convenient to manually drop in a subset of
1903 .Bl -tag -width 6n -offset indent -compact
1905 Reference start (does not take arguments).
1906 Causes a line break in the
1908 section and begins collection of reference information until the reference
1911 Reference end (does not take arguments).
1912 The reference is printed.
1914 Reference author name; one name per invocation.
1918 City/place (not implemented yet).
1922 Issuer/publisher name.
1928 Optional information.
1932 Corporate or foreign author.
1941 Macros beginning with
1943 are not callable but accept multiple arguments in the usual way.
1946 macro is handled properly as a parameter; other macros will cause strange
1951 can be used outside of the
1957 .Bd -literal -offset indent
1961 \&.%T "Implementation Notes on foobar(1)"
1962 \&.%R "Technical Report ABC-DE-12-345"
1963 \&.%Q "Drofnats College, Nowhere"
1970 .Bd -ragged -offset indent
1974 .%T "Implementation Notes on foobar(1)"
1975 .%R "Technical Report ABC-DE-12-345"
1976 .%Q "Drofnats College, Nowhere"
1981 .Ss Trade Names (or Acronyms and Type Names)
1983 The trade name macro prints its arguments in a smaller font.
1984 Its intended use is to imitate a small caps fonts for uppercase acronyms.
1986 .Dl Usage: .Tn Ao symbol Ac Ld
1988 .Bl -tag -xwidth ".Li .Tn\ ASCII" -compact -offset 15n
1996 .Ss Extended Arguments
2002 macros allow one to extend an argument list on a macro boundary for the
2009 are implemented similarly to all other macros opening and closing an
2010 enclosure (without inserting characters, of course).
2011 This means that the following is true for those macros also.
2013 Here is an example of
2015 using the space mode macro to turn spacing off:
2017 .Bd -literal -offset indent
2019 \&.It Xo Sy I Ar operation
2020 \&.No \een Ar count No \een
2028 .Bd -filled -offset indent
2031 .It Xo Sy I Ar operation
2032 .No \en Ar count No \en
2041 .Bd -literal -offset indent
2043 \&.It Cm S No / Ar old_pattern Xo
2044 \&.No / Ar new_pattern
2052 .Bd -filled -offset indent
2055 .It Cm S No \&/ Ar old_pattern Xo
2056 .No \&/ Ar new_pattern
2066 and enclosure macros: Test the value of a variable.
2068 .Bd -literal -offset indent
2071 \&.Oo \e&! Oc Ns Ar variable Oo
2072 \&.Ar operator variable Ld
2079 .Bd -filled -offset indent
2080 .Bl -tag -width flag -compact
2083 .Oo \&! Oc Ns Ar variable Oo
2084 .Ar operator variable Ld
2091 .Sh PAGE STRUCTURE DOMAIN
2097 section header macros listed below are required in every man page.
2098 The remaining section headers are recommended at the discretion of the
2099 author writing the manual page.
2102 macro is parsed but not generally callable.
2103 It can be used as an argument in a call to
2105 only; it then reactivates the default font for
2108 .Bl -tag -xwidth ".Li .Sh\ DESCRIPTION"
2113 If not specified, headers, footers and page layout defaults will not be set
2114 and things will be rather unpleasant.
2117 section consists of at least three items.
2120 name macro naming the subject of the man page.
2121 The second is the name description macro,
2123 which separates the subject name from the third item, which is the
2125 The description should be the most terse and lucid possible, as the space
2128 .It Li ".Sh SYNOPSIS"
2131 section describes the typical usage of the subject of a man page.
2132 The macros required are either
2143 The function name macro
2145 is required for manual page sections\~2 and\~3; the command and general name
2148 is required for sections 1, 5, 6, 7, and\~8.
2149 Section\~4 manuals require a
2154 configuration device usage macro.
2155 Several other macros may be necessary to produce the synopsis line as shown
2158 .Bd -filled -offset indent
2166 The following macros were used:
2169 .Dl ".Op Fl benstuv"
2173 .It Li ".Sh DESCRIPTION"
2174 In most cases the first text in the
2176 section is a brief paragraph on the command, function or file, followed by a
2177 lexical list of options and respective explanations.
2178 To create such a list, the
2185 macros are used (see
2186 .Sx Lists and Columns
2193 section headers are part of the preferred manual page layout and must be
2194 used appropriately to maintain consistency.
2195 They are listed in the order in which they would be used.
2197 .Bl -tag -xwidth ".Li .Sh\ ENVIRONMENT"
2198 .It Li ".Sh ENVIRONMENT"
2201 section should reveal any related environment variables and clues to their
2202 behavior and/or usage.
2203 .It Li ".Sh EXAMPLES"
2204 There are several ways to create examples.
2207 section below for details.
2209 Files which are used or created by the man page subject should be listed via
2215 .It Li ".Sh SEE ALSO"
2216 References to other material on the man page topic and cross references to
2217 other relevant man pages should be placed in the
2220 Cross references are specified using the
2225 style references are not accommodated.
2227 It is recommended that the cross references are sorted on the section
2228 number, and then alphabetically on the names within a section.
2229 .It Li ".Sh STANDARDS"
2230 If the command, library function or file adheres to a specific
2231 implementation such as
2235 this should be noted here.
2236 If the command does not adhere to any standard, its history should be noted
2240 .It Li ".Sh HISTORY"
2241 Any command which does not adhere to any specific standards should be
2242 outlined historically in this section.
2243 .It Li ".Sh AUTHORS"
2244 Credits should be placed here.
2245 .It Li ".Sh DIAGNOSTICS"
2246 Diagnostic messages from a command should be placed in this section.
2248 Specific error handling, especially from library functions (man page
2249 sections\~2 and\~3) should go here.
2252 macro is used to specify an error (errno).
2254 Blatant problems with the topic go here.
2260 sections may be added; for example, this section was set with:
2262 .Bd -literal -offset 15n
2263 \&.Sh PAGE LAYOUT MACROS
2266 .Ss Paragraphs and Line Spacing
2268 .Bl -tag -xwidth ".Li .Pp"
2272 paragraph command may be used to specify a line space where necessary.
2273 The macro is not necessary after a
2281 macro (which both assert a vertical distance unless the
2285 The macro is neither callable nor parsed and doesn't take arguments.
2290 .\" This worked with version one, need to redo for version three
2293 .\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
2294 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
2311 .\" .Em is produced by
2327 .\" This example shows the same equation in a different format.
2331 .\" signs were forced with
2335 .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
2336 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
2347 .\" .Li \&.Cx \e\ +\e\ \e&
2358 .\" .Em is produced by
2366 .\" .Li \&.Cx \e\ +\e\ \e&
2377 .\" The incantation below was
2383 .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
2385 .\" .Li \&.Cx Op Sy ?/
2395 .\" .Em is produced by
2397 .\" .Li \&.Ar \e\ b1 e1 f1
2411 The only keep that is implemented at this time is for words.
2418 The only option that
2420 accepts currently is
2422 (this is also the default if no option is given) which is useful for
2423 preventing line breaks in the middle of options.
2424 In the example for the make command line arguments (see
2425 .Sx What's in a name ) ,
2428 from placing up the flag and the argument on separate lines.
2430 Both macros are neither callable nor parsed.
2432 More work needs to be done with the keep macros; specifically, a
2434 option should be added.
2436 .Ss Examples and Displays
2438 There are six types of displays.
2440 .Bl -tag -xwidth ".Li .D1"
2443 Display one line of indented text.
2444 This macro is parsed but not callable.
2448 The above was produced by:
2449 .Li ".Dl Fl ldghfstru" .
2453 Display one line of indented
2458 example macro has been used throughout this file.
2459 It allows the indentation (display) of one line of text.
2460 Its default font is set to constant width (literal).
2462 is parsed but not callable.
2464 .Dl % ls -ldg /usr/local/bin
2466 The above was produced by:
2467 .Li ".Dl % ls -ldg /usr/local/bin" .
2473 display must be ended with the
2476 It has the following syntax:
2478 .Bl -tag -xwidth ".Li .Bd" -offset indent
2480 .Bro \-literal | \-filled | \-unfilled | \-ragged | \-centered Brc
2481 .Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
2485 .Bl -tag -xwidth ".Fl file Ao Ar file name Ac " -compact
2487 Fill, but do not adjust the right margin (only left-justify).
2489 Center lines between the current left and right margin.
2490 Note that each single line is centered.
2492 Do not fill; display a block of text as typed, using line breaks as
2493 specified by the user.
2494 This can produce overlong lines without warning messages.
2496 Display a filled block.
2497 The block of text is formatted (i.e., the text is justified on both the left
2500 Display block with literal font (usually fixed-width).
2501 Useful for source code or simple tabbed or spaced text.
2502 .It Fl file Ao Ar file name Ac
2503 The file name following the
2505 flag is read and displayed.
2506 Literal mode is asserted and tabs are set at 8\~constant width character
2509 .Xr troff/ Ns Nm \-mdoc
2510 commands in the file will be processed.
2511 Currently, this feature is not implemented.
2512 .It Fl offset Ao Ar string Ac
2515 is specified with one of the following strings, the string is interpreted to
2516 indicate the level of indentation for the forthcoming block of text:
2519 .Bl -tag -xwidth ".Ar indent-two" -compact
2521 Align block on the current left margin; this is the default mode of
2524 Supposedly center the block.
2525 At this time unfortunately, the block merely gets left aligned about an
2526 imaginary center margin.
2528 Indent by one default indent value or tab.
2529 The default indent value is also used for the
2533 macros, so one is guaranteed the two types of displays will line up.
2534 The indentation value is normally set to\~6n or about two thirds of an inch
2535 (six constant width characters).
2537 Indent two times the default indent value.
2541 aligns the block about two inches from the right side of the page.
2542 This macro needs work and perhaps may never do the right thing within
2549 is a valid numeric expression instead
2550 .Pf ( Em with a scale indicator other than
2552 use that value for indentation.
2553 The most useful scale indicators are
2557 specifying the so-called
2561 This is approximately the width of the letter
2565 of the current font (for nroff output, both scale indicators give the same
2569 isn't a numeric expression, it is tested whether it is an
2571 macro name, and the default offset value associated with this macro is used.
2572 Finally, if all tests fail,
2575 (typeset with a fixed-width font) is taken as the offset.
2577 Suppress insertion of vertical space before begin of display.
2581 End display (doesn't take parameters).
2584 .Ss Tagged Lists and Columns
2586 There are several types of lists which may be initiated with the
2589 Items within the list are specified with the
2591 item macro, and each list must end with the
2594 Lists may be nested within themselves and within displays.
2595 The use of columns inside of lists or lists inside of columns is unproven.
2597 In addition, several list attributes may be specified such as the width of a
2598 tag, the list offset, and compactness (blank lines between items allowed or
2600 Most of this document has been formatted with a tag style list
2603 It has the following syntax forms:
2605 .Bl -tag -xwidth ".Li .Bl" -offset indent -compact
2607 .Bro \-hang | \-ohang | \-tag | \-diag | \-inset Brc
2608 .Oo \-width Ao string Ac Oc Oo \-xwidth Ao command Ac Oc
2609 .Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
2611 .No \-column Oo \-offset Ao string Ac Oc
2612 .Ao string1 Ac Ao string2 Ac Ld Xc
2614 .Bro \-item | \-enum Oo \-nested Oc | \-bullet | \-hyphen | \-dash Brc
2615 .Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
2619 And now a detailed description of the list types.
2622 .Bl -tag -xwidth ".Fl column" -compact
2626 .Bd -literal -offset indent
2627 \&.Bl -bullet -offset indent -compact
2629 Bullet one goes here.
2639 .Bl -bullet -offset indent -compact
2641 Bullet one goes here.
2647 .It Fl dash No ( or Fl hyphen )
2650 .Bd -literal -offset indent
2651 \&.Bl -dash -offset indent -compact
2663 .Bl -dash -offset indent -compact
2674 .Bd -literal -offset indent
2675 \&.Bl -enum -offset indent -compact
2687 .Bl -enum -offset indent -compact
2695 If you want to nest enumerated lists, use the
2697 flag (starting with the second-level list):
2699 .Bd -literal -offset indent
2700 \&.Bl -enum -offset indent -compact
2703 \&.Bl -enum -nested -compact
2707 And item three here.
2718 .Bl -enum -offset indent -compact
2721 .Bl -enum -nested -compact
2725 And item three here.
2735 without list markers.
2737 .Bd -literal -offset indent
2738 \&.Bl -item -offset indent
2754 .Bl -item -offset indent
2772 to specify the tag width.
2775 .Bl -tag -width "PPID" -compact -offset indent
2777 sleep time of the process (seconds blocked)
2781 resulting from references by the process
2782 to pages not loaded in core.
2784 numerical user-id of process owner
2786 numerical id of parent of process priority
2787 (non-positive when in non-interruptible wait)
2793 .Bd -literal -offset indent
2794 \&.Bl -tag -width "PPID" -compact -offset indent
2796 sleep time of the process (seconds blocked)
2800 resulting from references by the process
2801 to pages not loaded in core.
2803 numerical user-id of process owner
2805 numerical id of parent of process priority
2806 (non-positive when in non-interruptible wait)
2812 Diag lists create section-four diagnostic lists and are similar to inset
2813 lists except callable macros are ignored.
2814 This list type can't be nested; the flags
2822 are not meaningful in this context).
2826 .Bd -literal -offset indent
2828 \&.It You can't use Sy here.
2829 The message says all.
2837 .Sy "You can't use Sy here" . "\ " No "The message says all" .
2841 A list with hanging tags.
2843 .Bl -hang -offset indent
2845 labels appear similar to tagged lists when the
2846 label is smaller than the label width.
2847 .It Em Longer hanged list labels
2848 blend in to the paragraph unlike
2849 tagged paragraph labels.
2852 And the unformatted text which created it:
2854 .Bd -literal -offset indent
2855 \&.Bl -hang -offset indent
2857 labels appear similar to tagged lists when the
2858 label is smaller than the label width.
2859 \&.It Em Longer hanged list labels
2860 blend in to the paragraph unlike
2861 tagged paragraph labels.
2867 Lists with overhanging tags don't use indentation for the items; tags are
2868 written to a separate line.
2870 .Bl -ohang -offset indent
2872 sleep time of the process (seconds blocked)
2876 resulting from references by the process
2877 to pages not loaded in core.
2879 numerical user-id of process owner
2881 numerical id of parent of process priority
2882 (non-positive when in non-interruptible wait)
2888 .Bd -literal -offset indent
2889 \&.Bl -ohang -offset indent
2891 sleep time of the process (seconds blocked)
2895 resulting from references by the process
2896 to pages not loaded in core.
2898 numerical user-id of process owner
2900 numerical id of parent of process priority
2901 (non-positive when in non-interruptible wait)
2907 Here is an example of inset labels:
2908 .Bl -inset -offset indent
2910 The tagged list (also called a tagged paragraph)
2911 is the most common type of list used in the
2915 attribute as described below.
2917 Diag lists create section four diagnostic lists
2918 and are similar to inset lists except callable
2921 Hanged labels are a matter of taste.
2923 Overhanging labels are nice when space is constrained.
2925 Inset labels are useful for controlling blocks of
2926 paragraphs and are valuable for converting
2928 manuals to other formats.
2931 Here is the source text which produced the above example:
2933 .Bd -literal -offset indent
2934 \&.Bl -inset -offset indent
2936 The tagged list (also called a tagged paragraph)
2937 is the most common type of list used in the
2940 Diag lists create section four diagnostic lists
2941 and are similar to inset lists except callable
2944 Hanged labels are a matter of taste.
2946 Overhanging labels are nice when space is constrained.
2948 Inset labels are useful for controlling blocks of
2949 paragraphs and are valuable for converting
2951 manuals to other formats.
2957 This list type generates multiple columns.
2958 The number of columns and the width of each column is determined by the
2964 argument is parsed to make a row, each column within the row is a separate
2965 argument separated by a tab or the
2971 .Bl -column -offset indent String Nroff Troff
2972 .It Sy String Ta Sy Nroff Ta Sy Troff
2973 .It Li <= Ta <= Ta \*(<=
2974 .It Li >= Ta >= Ta \*(>=
2980 .Bd -literal -offset indent
2981 \&.Bl -column -offset indent String Nroff Troff
2982 \&.It Sy String Ta Sy Nroff Ta Sy Troff
2983 \&.It Li <= Ta <= Ta \e*(<=
2984 \&.It Li >= Ta >= Ta \e*(>=
2991 \#=====================================================================
2995 .Bl -tag -xwidth ".Fl width Ar \&Fl" -offset indent
2996 .It Fl width Ar "\&Fl"
2997 sets the width to the default width for a flag.
2999 macros have a default width value.
3003 set to ten constant width characters or about five sixth of
3005 .It Fl width Ar "24n"
3006 sets the width to 24 constant width characters or about two
3010 is absolutely necessary for the scaling to work correctly.
3011 .It Fl width Ar "ENAMETOOLONG"
3012 sets width to the constant width length of the
3014 .It Fl width Ar "\\*qint mkfifo\\*q"
3015 again, the width is set to the constant width of the string
3019 If a width is not specified for the tag list type, the first
3022 is invoked, an attempt is made to determine an appropriate
3024 If the first argument to
3026 is a callable macro, the default width for that macro will be used
3027 as if the macro name had been supplied as the width.
3029 if another item in the list is given with a different callable
3030 macro name, a new and nested list is assumed.
3034 is required for the tag list type.
3036 .Sh PREDEFINED STRINGS
3037 The following strings are predefined as may be used by
3038 preceding with the troff string interpreting sequence
3042 is the name of the defined string or as
3046 is the name of the string.
3047 The interpreting sequence may be used any where in the text.
3049 .Bl -column "String " "Nroff " "Troff " -offset indent
3050 .It Sy "String Nroff Troff"
3051 .It Li "<=" Ta \&<\&= Ta \*(<=
3052 .It Li ">=" Ta \&>\&= Ta \*(>=
3053 .It Li "Rq" Ta "''" Ta \*(Rq
3054 .It Li "Lq" Ta "``" Ta \*(Lq
3055 .It Li "ua" Ta ^ Ta \*(ua
3056 .It Li "aa" Ta ' Ta \*(aa
3057 .It Li "ga" Ta \` Ta \*(ga
3058 .\" .It Li "sL" Ta ` Ta \*(sL
3059 .\" .It Li "sR" Ta ' Ta \*(sR
3060 .It Li "q" Ta \&" Ta \*q
3061 .It Li "Pi" Ta pi Ta \*(Pi
3062 .It Li "Ne" Ta != Ta \*(Ne
3063 .It Li "Le" Ta <= Ta \*(Le
3064 .It Li "Ge" Ta >= Ta \*(Ge
3065 .It Li "Lt" Ta < Ta \*(Gt
3066 .It Li "Gt" Ta > Ta \*(Lt
3067 .It Li "Pm" Ta +\- Ta \*(Pm
3068 .It Li "If" Ta infinity Ta \*(If
3069 .It Li "Na" Ta \fINaN\fP Ta \*(Na
3070 .It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
3076 should be written as
3078 since it is only one char.
3080 The debugging facilities for
3082 are limited, but can help detect subtle errors such
3083 as the collision of an argument name with an internal
3084 register or macro name.
3086 A register is an arithmetic storage class for
3088 with a one or two character name.
3089 All registers internal to
3095 are two characters and
3096 of the form <upper_case><lower_case> such as
3098 <lower_case><upper_case> as
3101 <upper or lower letter><digit> as
3103 And adding to the muddle,
3105 has its own internal registers all of which are either
3106 two lower case characters or a dot plus a letter or meta-character
3108 In one of the introduction examples, it was shown how to
3109 prevent the interpretation of a macro name with the escape sequence
3111 This is sufficient for the internal register names also.
3113 .\" Every callable macro name has a corresponding register
3114 .\" of the same name (<upper_case><lower_case>).
3115 .\" There are also specific registers which have
3116 .\" been used for stacks and arrays and are listed in the
3118 .\" .Bd -ragged -offset 4n
3119 .\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
3120 .\" [a-z][A-Z] registers corresponding to macro names (example ``aR'')
3121 .\" C[0-9] argument types (example C1)
3122 .\" O[0-9] offset stack (displays)
3123 .\" h[0-9] horizontal spacing stack (lists)
3124 .\" o[0-9] offset (stack) (lists)
3125 .\" t[0-9] tag stack (lists)
3126 .\" v[0-9] vertical spacing stack (lists)
3127 .\" w[0-9] width tag/label stack
3130 If a non-escaped register name is given in the argument list of a request
3131 unpredictable behavior will occur.
3132 In general, any time huge portions
3133 of text do not appear where expected in the output, or small strings
3134 such as list tags disappear, chances are there is a misunderstanding
3135 about an argument type in the argument list.
3136 Your mother never intended for you to remember this evil stuff -- so here
3137 is a way to find out whether or not your arguments are valid: The
3140 macro displays the interpretation of the argument list for most
3145 macro do not contain debugging information.
3146 All of the callable macros do,
3147 and it is strongly advised whenever in doubt,
3152 .Dl Usage: \&.Db [on | off]
3154 An example of a portion of text with
3155 the debug macro placed above and below an
3156 artificially created problem (a flag argument
3162 .Bd -literal -offset indent
3164 \&.Op Fl aC Ar file )
3168 The resulting output:
3170 .Bd -literal -offset indent
3172 DEBUG(argv) MACRO: `.Op' Line #: 2
3173 Argc: 1 Argv: `Fl' Length: 2
3174 Space: `' Class: Executable
3175 Argc: 2 Argv: `aC' Length: 2
3176 Space: `' Class: Executable
3177 Argc: 3 Argv: `Ar' Length: 2
3178 Space: `' Class: Executable
3179 Argc: 4 Argv: `file' Length: 4
3180 Space: ` ' Class: String
3181 Argc: 5 Argv: `)' Length: 1
3182 Space: ` ' Class: Closing Punctuation or suffix
3183 MACRO REQUEST: .Op Fl aC Ar file )
3187 The first line of information tells the name of the calling
3190 and the line number it appears on.
3191 If one or more files are involved
3192 (especially if text from another file is included) the line number
3194 If there is only one file, it should be accurate.
3195 The second line gives the argument count, the argument
3198 If the length of an argument is two characters, the
3199 argument is tested to see if it is executable (unfortunately, any
3200 register which contains a non-zero value appears executable).
3201 The third line gives the space allotted for a class, and the
3203 The problem here is the argument aC should not be
3205 The four types of classes are string, executable, closing
3206 punctuation and opening punctuation.
3207 The last line shows the entire
3208 argument list as it was read.
3209 In this next example, the offending
3213 .Bd -literal -offset indent
3215 \&.Em An escaped \e&aC
3219 .Bd -literal -offset indent
3221 DEBUG(fargv) MACRO: `.Em' Line #: 2
3222 Argc: 1 Argv: `An' Length: 2
3223 Space: ` ' Class: String
3224 Argc: 2 Argv: `escaped' Length: 7
3225 Space: ` ' Class: String
3226 Argc: 3 Argv: `aC' Length: 2
3227 Space: ` ' Class: String
3228 MACRO REQUEST: .Em An escaped &aC
3234 shows up with the same length of 2 as the
3236 sequence produces a zero width, but a register
3239 was not found and the type classified as string.
3241 Other diagnostics consist of usage statements and are self explanatory.
3242 .Sh GROFF, TROFF AND NROFF
3245 package does not need compatibility mode with
3248 The package inhibits page breaks, and the headers and footers
3249 which normally occur at those breaks with
3251 to make the manual more efficient for viewing on-line.
3256 does eject the imaginary remainder of the page at end of file.
3257 The inhibiting of the page breaks makes
3259 files unsuitable for hardcopy.
3260 There is a register named
3262 which can be set to zero in the site dependent style file
3263 .Pa /usr/\:src/\:share/\:tmac/\:doc-nroff
3264 to restore the old style behavior.
3266 .Bl -tag -width /usr/share/misc/mdoc.template -compact
3267 .It Pa /usr/share/tmac/tmac.doc
3268 manual macro package
3269 .It Pa /usr/share/misc/mdoc.template
3270 template for writing a man page
3277 Undesirable hyphenation on the dash of a flag
3278 argument is not yet resolved, and causes
3279 occasional mishaps in the
3282 (line break on the hyphen).
3284 Predefined strings are not declared in documentation.
3286 Section 3f has not been added to the header routines.
3289 font should be changed in
3294 needs to have a check to prevent splitting up
3295 if the line length is too short.
3297 separates the last parenthesis, and sometimes
3298 looks ridiculous if a line is in fill mode.
3300 The method used to prevent header and footer page
3301 breaks (other than the initial header and footer) when using
3302 nroff occasionally places an unsightly partially filled line (blank)
3303 at the would be bottom of the page.
3305 If the outer-most list definition doesn't have a
3309 elements of inner lists may not work (producing a list where
3310 each successive element
3314 The list and display macros to not do any keeps
3315 and certainly should be able to.
3316 .\" Note what happens if the parameter list overlaps a newline
3318 .\" to make sure a line boundary is crossed:
3320 .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
3323 .\" produces, nudge nudge,
3324 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
3325 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
3327 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
3329 .\" If double quotes are used, for example:
3331 .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
3334 .\" produces, nudge nudge,
3335 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
3337 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
3339 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
3341 .\" Not a pretty sight...
3342 .\" In a paragraph, a long parameter containing unpaddable spaces as
3343 .\" in the former example will cause
3345 .\" to break the line and spread
3346 .\" the remaining words out.
3347 .\" The latter example will adjust nicely to
3348 .\" justified margins, but may break in between an argument and its
3352 .\" the right margin adjustment is normally ragged and the problem is