1 .\" Copyright (c) 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93
35 .\" This tutorial sampler invokes every macro in the package several
36 .\" times and is guaranteed to give a worst case performance
37 .\" for an already extremely slow package.
44 .Nd tutorial sampler for writing
51 A tutorial sampler for writing
56 .Em content Ns \-based
65 addressed page layout leaving the
66 manipulation of fonts and other
67 typesetting details to the individual author.
72 .Em "page structure domain"
73 which consists of macros for titles, section headers, displays
74 and lists. Essentially items which affect the physical position
75 of text on a formatted page.
76 In addition to the page structure domain, there are two more domains,
77 the manual domain and the general text domain.
78 The general text domain is defined as macros which
79 perform tasks such as quoting or emphasizing pieces of text.
80 The manual domain is defined as macros that are a subset of the
81 day to day informal language used to describe commands, routines
85 Macros in the manual domain handle
86 command names, command line arguments and options, function names,
87 function parameters, pathnames, variables, cross
88 references to other manual pages, and so on.
91 for both the author and the future user of the manual page.
92 It is hoped the consistency gained
93 across the manual set will provide easier
94 translation to future documentation tools.
98 manual pages, a manual entry
100 to as a man page, regardless of actual length and without
103 Since a tutorial document is normally read when a person
104 desires to use the material immediately, the assumption has
105 been made that the user of this document may be impatient.
106 The material presented in the remained of this document is
108 .Bl -enum -offset indent
110 .Tn "TROFF IDIOSYNCRASIES"
111 .Bl -tag -width flag -compact -offset indent
113 .It "Passing Space Characters in an Argument" .
114 .It "Trailing Blank Space Characters (a warning)" .
115 .It "Escaping Special Characters" .
118 .Tn "THE ANATOMY OF A MAN PAGE"
119 .Bl -tag -width flag -compact -offset indent
120 .It "A manual page template" .
125 .Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" .
126 .Bl -tag -width flag -compact -offset indent
127 .It "What's in a name..." .
128 .It "General Syntax" .
132 .Bl -tag -width flag -compact -offset indent
136 .It "Configuration Declarations (section four only)" .
137 .It "Command Modifier" .
138 .It "Defined Variables" .
139 .It "Errno's (Section two only)" .
140 .It "Environment Variables" .
141 .It "Function Argument" .
142 .It "Function Declaration" .
144 .It "Functions (library routines)" .
145 .It "Function Types" .
146 .\" .It "Header File (including source code)" .
147 .It "Interactive Commands" .
153 .It "Cross References" .
156 .Tn "GENERAL TEXT DOMAIN"
157 .Bl -tag -width flag -compact -offset indent
160 .It "FreeBSD/NetBSD/OpenBSD Macro" .
162 .It "Enclosure/Quoting Macros"
163 .Bl -tag -width flag -compact -offset indent
164 .It "Angle Bracket Quote/Enclosure" .
165 .It "Bracket Quotes/Enclosure" .
166 .It "Double Quote macro/Enclosure" .
167 .It "Parenthesis Quote/Enclosure" .
168 .It "Single Quotes/Enclosure" .
171 .It "No\-Op or Normal Text Macro" .
172 .It "No Space Macro" .
173 .It "Section Cross References" .
174 .It "References and Citations" .
175 .It "Return Values (sections two and three only)"
176 .It "Trade Names (Acronyms and Type Names)" .
177 .It "Extended Arguments" .
180 .Tn "PAGE STRUCTURE DOMAIN"
181 .Bl -tag -width flag -compact -offset indent
182 .It "Section Headers" .
183 .It "Paragraphs and Line Spacing" .
186 .It "Font Modes (Emphasis, Literal, and Symbolic)" .
187 .It "Lists and Columns" .
190 .Tn "PREDEFINED STRINGS"
194 .Tn "FORMATTING WITH GROFF, TROFF AND NROFF"
199 .Sh TROFF IDIOSYNCRASIES
202 package attempts to simplify the process of writing a man page.
203 Theoretically, one should not have to learn the dirty details of
207 however, there are a few
208 limitations which are unavoidable and best gotten out
210 And, too, be forewarned, this package is
216 a macro is called by placing a
220 a line followed by the two character name for the macro.
221 Arguments may follow the macro separated by spaces.
222 It is the dot character at the beginning of the line which causes
224 to interpret the next two characters as a macro name.
228 at the beginning of a line in some context other than
229 a macro invocation, precede the
236 translates literally to a zero width space, and is never displayed in the
241 macros accept up to nine arguments, any
242 extra arguments are ignored.
245 accept nine arguments and,
246 in limited cases, arguments may be continued or extended
250 A few macros handle quoted arguments (see
251 .Sx Passing Space Characters in an Argument
256 general text domain and manual domain macros are special
257 in that their argument lists are
259 for callable macro names.
260 This means an argument on the argument list which matches
261 a general text or manual domain macro name and is determined
262 to be callable will be executed
263 or called when it is processed.
265 the argument, although the name of a macro,
269 It is in this manner that many macros are nested; for
275 the flag and argument macros,
279 to specify an optional flag with an argument:
280 .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
283 .Li \&.Op \&Fl s \&Ar bytes
286 To prevent a two character
287 string from being interpreted as a macro name, precede
291 .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
292 .It Op \&Fl s \&Ar bytes
294 .Li \&.Op \e&Fl s \e&Ar bytes
301 are not interpreted as macros.
302 Macros whose argument lists are parsed for callable arguments
304 as parsed and macros which may be called from an argument
305 list are referred to as callable
306 throughout this document and in the companion quick reference
311 as almost all of the macros in
313 are parsed, but as it was cumbersome to constantly refer to macros
314 as being callable and being able to call other macros,
315 the term parsed has been used.
316 .Ss Passing Space Characters in an Argument
317 Sometimes it is desirable to give as one argument a string
318 containing one or more blank space characters.
319 This may be necessary
320 to defeat the nine argument limit or to specify arguments to macros
321 which expect particular arrangement of items in the argument list.
325 expects the first argument to be the name of a function and any
326 remaining arguments to be function parameters.
329 stipulates the declaration of function parameters in the
330 parenthesized parameter list, each parameter is guaranteed
331 to be at minimum a two word string.
335 There are two possible ways to pass an argument which contains
337 .Em Implementation note :
338 Unfortunately, the most convenient way
339 of passing spaces in between quotes by reassigning individual
340 arguments before parsing was fairly expensive speed wise
341 and space wise to implement in all the macros for
344 It is not expensive for
346 but for the sake of portability, has been limited
347 to the following macros which need
350 .Bl -tag -width 4n -offset indent -compact
352 Configuration declaration (section 4
355 Begin list (for the width specifier).
359 Functions (sections two and four).
371 Optional notes for a reference.
373 Report title (in a reference).
375 Title of article in a book or journal.
378 One way of passing a string
379 containing blank spaces is to use the hard or unpaddable space character
381 that is, a blank space preceded by the escape character
383 This method may be used with any macro but has the side effect
384 of interfering with the adjustment of text
385 over the length of a line.
387 sees the hard space as if it were any other printable character and
388 cannot split the string into blank or newline separated pieces as one
390 The method is useful for strings which are not expected
391 to overlap a line boundary.
393 .Bl -tag -width "fetch(char *str)" -offset indent
394 .It Fn fetch char\ *str
396 .Ql \&.Fn fetch char\e *str
397 .It Fn fetch "char *str"
398 can also be created by
399 .Ql \&.Fn fetch "\\*qchar *str\\*q"
407 would see three arguments and
410 .Dl Fn fetch char *str
412 For an example of what happens when the parameter list overlaps
413 a newline boundary, see the
416 .Ss Trailing Blank Space Characters
418 can be confused by blank space characters at the end of a line.
420 is a wise preventive measure to globally remove all blank spaces
421 from <blank-space><end-of-line> character sequences.
423 arise to force a blank character at the end of a line,
424 it may be forced with an unpaddable space and the
429 .Ss Escaping Special Characters
431 like the newline character
433 are handled by replacing the
441 .Sh THE ANATOMY OF A MAN PAGE
442 The body of a man page is easily constructed from a basic
443 template found in the file
444 .Pa /usr/share/misc/mdoc.template .
445 Several example man pages can also be found
447 .Pa /usr/share/examples/mdoc .
449 .Ss A manual page template
450 .Bd -literal -offset indent
451 \&.\e" The following requests are required for all man pages.
452 \&.Dd Month day, year
453 \&.Os OPERATING_SYSTEM [version/release]
454 \&.Dt DOCUMENT_TITLE [section number] [volume]
457 \&.Nd one line description of name
460 \&.\e" The following requests should be uncommented and
461 \&.\e" used where appropriate.
462 \&.\e" .Sh IMPLEMENTATION NOTES
463 \&.\e" This next request is for sections 2, 3 and 9 function return values only.
464 \&.\e" .Sh RETURN VALUES
465 \&.\e" This next request is for sections 1, 6, 7, 8 & 9 only
466 \&.\e" .Sh ENVIRONMENT
469 \&.\e" This next request is for sections 1, 6, 7, 8 & 9 only
470 \&.\e" (command return values (to shell) and
471 \&.\e" fprintf/stderr type diagnostics)
472 \&.\e" .Sh DIAGNOSTICS
473 \&.\e" .Sh COMPATIBILITY
474 \&.\e" The next request is for sections 2, 3 and 9 error
475 \&.\e" and signal handling only.
484 The first items in the template are the macros
485 .Pq Li \&.Dd , \&.Os , \&.Dt ;
487 the operating system the man page or subject source is developed
489 and the man page title
491 along with the section of the manual the page
493 These macros identify the page,
494 and are discussed below in
497 The remaining items in the template are section headers
508 .Sx PAGE STRUCTURE DOMAIN ,
512 Several content macros are used to demonstrate page layout macros;
513 reading about content macros before page layout macros is
516 The title macros are the first portion of the page structure
517 domain, but are presented first and separate for someone who
518 wishes to start writing a man page yesterday.
519 Three header macros designate the document title or manual page title,
520 the operating system,
521 and the date of authorship.
522 These macros are one called once at the very beginning of the document
523 and are used to construct the headers and footers only.
525 .It Li \&.Dt DOCUMENT_TITLE section# [volume]
526 The document title is the
527 subject of the man page and must be in
531 The section number may be 1,\ ...,\ 9,
532 and if it is specified,
533 the volume title may be omitted.
537 the following section numbers and their descriptions are described below:
539 .Bl -column SMM -offset indent -compact
540 .It Li 1 FreeBSD General Commands Manual
541 .It Li 2 FreeBSD System Calls Manaul
542 .It Li 3 FreeBSD Library Calls Manual
543 .It Li 4 FreeBSD Kernel Interfaces Manual
544 .It Li 5 FreeBSD File Formats Manual
545 .It Li 6 FreeBSD Games Manual
546 .It Li 7 FreeBSD Miscellaneous Information Manual
547 .It Li 8 FreeBSD System Manager's Manual
548 .It Li 9 FreeBSD Kernel Developers Guide
551 A volume title may be arbitrary or one of the following:
553 .\" USD UNIX User's Supplementary Documents
555 .\" PS1 UNIX Programmer's Supplementary Documents
557 .Bl -column SMM -offset indent -compact
558 .It Li AMD UNIX Ancestral Manual Documents
559 .It Li SMM UNIX System Manager's Manual
560 .It Li URM UNIX Reference Manual
561 .It Li PRM UNIX Programmer's Manual
564 The default volume labeling is
566 for sections 1, 6, and 7;
570 for sections 2, 3, 4, and 5.
572 .\" MMI UNIX Manual Master Index
574 .\" CON UNIX Contributed Software Manual
576 .\" LOC UNIX Local Manual
577 .It Li \&.Os operating_system release#
578 The name of the operating system
579 should be the common acronym, e.g.
585 The release should be the standard release
586 nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3,
588 Unrecognized arguments are displayed as given in the page footer.
589 For instance, a typical footer might be:
594 .Dl \&.Os FreeBSD 2.2
596 or for a locally produced set
598 .Dl \&.Os CS Department
600 The Berkeley default,
602 without an argument, has been defined as
606 .Pa /usr/share/tmac/mdoc/doc-common .
607 It really should default to
611 macro is not present, the bottom left corner of the page
613 .It Li \&.Dd month day, year
614 The date should be written formally:
619 .Sh INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
620 .Ss What's in a name...
621 The manual domain macro names are derived from the day to day
622 informal language used to describe commands, subroutines and related
625 different variations of this language are used to describe
626 the three different aspects of writing a man page.
627 First, there is the description of
630 Second is the description of a
637 description of a command to a user in the verbal sense;
638 that is, discussion of a command in the text of a man page.
642 macros are themselves a type of command;
643 the general syntax for a troff command is:
644 .Bd -filled -offset indent
645 \&.Va argument1 argument2 ... argument9
650 is a macro command or request, and anything following it is an argument to
655 command using the content macros is a
659 command line might be displayed as:
660 .Bd -filled -offset indent
668 is the command name and the
673 argument designated as optional by the option brackets.
683 The macros which formatted the above example:
684 .Bd -literal -offset indent
690 In the third case, discussion of commands and command syntax
691 includes both examples above, but may add more detail.
697 from the example above might be referred to as
701 Some command line argument lists are quite long:
702 .Bl -tag -width make -offset indent
709 .Op Fl I Ar directory
712 .Op Ar variable=value
718 Here one might talk about the command
720 and qualify the argument
722 as an argument to the flag,
724 or discuss the optional
728 In the verbal context, such detail can prevent confusion,
732 does not have a macro for an argument
737 argument macro is used for an operand or file argument like
739 as well as an argument to a flag like
741 The make command line was produced from:
742 .Bd -literal -offset indent
745 \&.Op Fl D Ar variable
747 \&.Op Fl f Ar makefile
748 \&.Op Fl I Ar directory
749 \&.Op Fl j Ar max_jobs
750 \&.Op Ar variable=value
760 macros are explained in
763 The manual domain and general text domain macros share a similar
764 syntax with a few minor deviations:
770 differ only when called without arguments;
774 impose an order on their argument lists
780 have nesting limitations.
782 are capable of recognizing and properly handling punctuation,
783 provided each punctuation character is separated by a leading space.
784 If an request is given:
786 .Dl \&.Li sptr, ptr),
792 The punctuation is not recognized and all is output in the
793 literal font. If the punctuation is separated by a leading
796 .Dl \&.Li "sptr , ptr ) ,"
800 .Dl Li sptr , ptr ) ,
802 The punctuation is now recognized and is output in the
803 default font distinguishing it from the strings in literal font.
805 To remove the special meaning from a punctuation character
809 is limited as a macro language, and has difficulty
810 when presented with a string containing
811 a member of the mathematical, logical or
813 .Bd -literal -offset indent-two
814 \&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"}
819 may assume it is supposed to actually perform the operation
820 or evaluation suggested by the characters. To prevent
821 the accidental evaluation of these characters,
824 Typical syntax is shown in the first content macro displayed
829 The address macro identifies an address construct
830 of the form addr1[,addr2[,addr3]].
832 .Dl Usage: .Ad address ... \*(Pu
833 .Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
836 .It Li \&.Ad addr1\ .
838 .It Li \&.Ad addr1\ , file2
840 .It Li \&.Ad f1\ , f2\ , f3\ :
842 .It Li \&.Ad addr\ )\ )\ ,
846 It is an error to call
850 is callable by other macros and is parsed.
854 macro is used to specify the name of the author of the item being
855 documented, or the name of the author of the actual manual page.
856 Any remaining arguments after the name information are assumed
859 .Dl Usage: .An author_name \*(Pu
860 .Bl -tag -width ".An Joe Author ) ) ," -compact -offset 14n
861 .It Li \&.An Joe\ Author
863 .It Li \&.An Joe\ Author\ ,
865 .It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG
866 .An Joe Author Aq nobody@FreeBSD.ORG
867 .It Li \&.An Joe\ Author\ )\ )\ ,
873 macro is parsed and is callable.
874 It is an error to call
881 argument macro may be used whenever
882 a command line argument is referenced.
884 .Dl Usage: .Ar argument ... \*(Pu
885 .Bl -tag -width ".Ar file1 file2" -compact -offset 15n
890 .It Li \&.Ar file1\ .
892 .It Li \&.Ar file1 file2
894 .It Li \&.Ar f1 f2 f3\ :
896 .It Li \&.Ar file\ )\ )\ ,
902 is called without arguments
907 macro is parsed and is callable.
908 .Ss Configuration Declaration (section four only)
911 macro is used to demonstrate a
913 declaration for a device interface in a section four manual.
914 This macro accepts quoted arguments (double quotes only).
916 .Bl -tag -width "device le0 at scode?" -offset indent
917 .It Cd "device le0 at scode?"
919 .Ql ".Cd device le0 at scode?" .
922 The command modifier is identical to the
924 (flag) command with the exception
927 macro does not assert a dash
928 in front of every argument.
929 Traditionally flags are marked by the
930 preceding dash, some commands or subsets of commands do not use them.
931 Command modifiers may also be specified in conjunction with interactive
932 commands such as editor commands.
935 .Ss Defined Variables
936 A variable which is defined in an include file is specified
940 .Dl Usage: .Dv defined_variable ... \*(Pu
941 .Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
942 .It Li ".Dv MAXHOSTNAMELEN"
944 .It Li ".Dv TIOCGPGRP )"
948 It is an error to call
952 is parsed and is callable.
953 .Ss Errno's (Section two only)
956 errno macro specifies the error return value
957 for section two library routines.
963 general text domain macro, as it would be used in
964 a section two manual page.
966 .Dl Usage: .Er ERRNOTYPE ... \*(Pu
967 .Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
970 .It Li \&.Er ENOENT\ )\ ;
972 .It Li \&.Bq \&Er ENOTDIR
976 It is an error to call
981 macro is parsed and is callable.
982 .Ss Environment Variables
985 macro specifies an environment variable.
987 .Dl Usage: .Ev argument ... \*(Pu
988 .Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
993 .It Li \&.Ev PRINTER\ )\ )\ ,
997 It is an error to call
1002 macro is parsed and is callable.
1003 .Ss Function Argument
1006 macro is used to refer to function arguments (parameters)
1009 section of the manual or inside
1012 section should a parameter list be too
1015 macro and the enclosure macros
1021 may also be used to refer to structure members.
1023 .Dl Usage: .Fa function_argument ... \*(Pu
1024 .Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
1025 .It Li \&.Fa d_namlen\ )\ )\ ,
1027 .It Li \&.Fa iov_len
1031 It is an error to call
1035 is parsed and is callable.
1036 .Ss Function Declaration
1039 macro is used in the
1041 section with section two or three
1045 macro does not call other macros and is not callable by other
1048 .Dl Usage: .Fd include_file (or defined variable)
1054 request causes a line break if a function has already been presented
1055 and a break has not occurred.
1056 This leaves a nice vertical space
1057 in between the previous function call and the declaration for the
1062 macro handles command line flags.
1067 For interactive command flags, which
1068 are not prepended with a dash, the
1071 macro is identical, but without the dash.
1073 .Dl Usage: .Fl argument ... \*(Pu
1074 .Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
1085 .It Li \&.Fl xyz\ )\ ,
1091 macro without any arguments results
1092 in a dash representing stdin/stdout.
1095 a single dash, will result in two dashes.
1098 macro is parsed and is callable.
1099 .Ss Functions (library routines)
1100 The .Fn macro is modeled on ANSI C conventions.
1102 Usage: .Fn [type] function [[type] parameters ... \*(Pu]
1104 .Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact
1105 .It Li "\&.Fn getchar"
1107 .It Li "\&.Fn strlen ) ,"
1109 .It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
1110 .Fn "int align" "const * char *sptrs" ,
1113 It is an error to call
1115 without any arguments.
1119 is parsed and is callable,
1120 note that any call to another macro signals the end of
1123 call (it will close-parenthesis at that point).
1125 For functions that have more than eight parameters (and this
1136 to get around the limitation. For example:
1137 .Bd -literal -offset indent
1138 \&.Fo "int res_mkquery"
1145 \&.Fa "struct rrec *newrr"
1152 .Bd -filled -offset indent
1153 .Fo "int res_mkquery"
1160 .Fa "struct rrec *newrr"
1170 macros are parsed and are callable.
1173 section, the function will always begin at
1174 the beginning of line.
1175 If there is more than one function
1178 section and a function type has not been
1179 given, a line break will occur, leaving a nice vertical space
1180 between the current function name and the one prior.
1183 does not check its word boundaries
1184 against troff line lengths and may split across a newline
1186 This will be fixed in the near future.
1188 This macro is intended for the
1192 anywhere else in the man page without problems, but its main purpose
1193 is to present the function type in kernel normal form for the
1195 of sections two and three
1196 (it causes a line break allowing the function name to appear
1199 .Dl Usage: .Ft type ... \*(Pu
1200 .Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
1201 .It Li \&.Ft struct stat
1207 request is not callable by other macros.
1208 .Ss Interactive Commands
1211 macro designates an interactive or internal command.
1213 .Dl Usage: .Ic argument ... \*(Pu
1214 .Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n
1217 .It Li \&.Ic do while {...}
1219 .It Li \&.Ic setenv\ , unsetenv
1220 .Ic setenv , unsetenv
1223 It is an error to call
1228 macro is parsed and is callable.
1232 macro is used for the document title or subject name.
1233 It has the peculiarity of remembering the first
1234 argument it was called with, which should
1235 always be the subject name of the page.
1239 regurgitates this initial name for the sole purpose
1240 of making less work for the author.
1243 or three document function name is addressed with the
1251 and remaining sections.
1252 For interactive commands, such as the
1258 macro should be used.
1264 it can not recall the first argument it was invoked with.
1266 .Dl Usage: .Nm argument ... \*(Pu
1267 .Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n
1268 .It Li \&.Nm mdoc.sample
1270 .It Li \&.Nm \e-mdoc
1272 .It Li \&.Nm foo\ )\ )\ ,
1280 macro is parsed and is callable.
1285 places option brackets around any remaining arguments on the command
1286 line, and places any
1287 trailing punctuation outside the brackets.
1292 may be used across one or more lines.
1294 .Dl Usage: .Op options ... \*(Pu
1295 .Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
1300 .It Li ".Op Fl k ) ."
1302 .It Li ".Op Fl k Ar kookfile"
1303 .Op Fl k Ar kookfile
1304 .It Li ".Op Fl k Ar kookfile ,"
1305 .Op Fl k Ar kookfile ,
1306 .It Li ".Op Ar objfil Op Ar corfil"
1307 .Op Ar objfil Op Ar corfil
1308 .It Li ".Op Fl c Ar objfil Op Ar corfil ,"
1309 .Op Fl c Ar objfil Op Ar corfil ,
1310 .It Li \&.Op word1 word2
1319 .Bd -literal -offset indent
1321 \&.Op \&Fl k \&Ar kilobytes
1322 \&.Op \&Fl i \&Ar interval
1323 \&.Op \&Fl c \&Ar count
1329 .Op Fl k Ar kilobytes
1330 .Op Fl i Ar interval
1339 are parsed and are callable.
1343 macro formats path or file names.
1345 .Dl Usage: .Pa pathname \*(Pu
1346 .Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
1347 .It Li \&.Pa /usr/share
1349 .It Li \&.Pa /tmp/fooXXXXX\ )\ .
1350 .Pa /tmp/fooXXXXX ) .
1355 macro is parsed and is callable.
1359 macro replaces standard abbreviature with its formal name.
1361 .Dl Usage: .St abbreviature
1364 .Dq Abbreviature/Formal Name
1366 .Bl -tag -width "-p1003.2-92XX." -compact -offset indent
1383 .It Li "-p1003.1-88"
1385 .It Li "-p1003.1-90"
1389 .It Li "-p1003.1b-93"
1395 .It Li "-p1003.2-92"
1407 Generic variable reference:
1409 .Dl Usage: .Va variable ... \*(Pu
1410 .Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
1413 .It Li \&.Va settimer ,
1415 .It Li \&.Va int\ *prt\ )\ :
1417 .It Li \&.Va char\ s\ ]\ )\ )\ ,
1421 It is an error to call
1423 without any arguments.
1426 macro is parsed and is callable.
1427 .Ss Manual Page Cross References
1430 macro expects the first argument to be
1431 a manual page name, and the second argument, if it exists,
1432 to be either a section page number or punctuation.
1434 remaining arguments are assumed to be punctuation.
1436 .Dl Usage: .Xr man_page [1,...,9] \*(Pu
1437 .Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
1440 .It Li \&.Xr mdoc\ ,
1444 .It Li \&.Xr mdoc 7\ )\ )\ ,
1450 macro is parsed and is callable.
1451 It is an error to call
1455 .Sh GENERAL TEXT DOMAIN
1457 .Bd -literal -offset indent -compact
1458 Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu
1460 .Bl -tag -width ".At v6 ) ," -compact -offset 14n
1473 callable. It accepts at most two arguments.
1475 .Dl Usage: .Bx [Version/release] ... \*(Pu
1476 .Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n
1485 macro is parsed and is callable.
1486 .Ss FreeBSD/NetBSD/OpenBSD Macros
1487 .Bd -literal -offset indent -compact
1488 Usage: .Fx [ Version.release ] ... \*(Pu
1490 .Bl -tag -width ".Fx 2.2 ) ," -compact -offset 14n
1495 .Bd -literal -offset indent -compact
1496 Usage: .Nx [ Version.release ] ... \*(Pu
1498 .Bl -tag -width ".Nx 1.4 ) ," -compact -offset 14n
1503 .Bd -literal -offset indent -compact
1504 Usage: .Ox [ Version.release ] ... \*(Pu
1506 .Bl -tag -width ".Ox 2.5 ) ," -compact -offset 14n
1519 callable. They accept at most two arguments.
1521 .Dl Usage: .Ux ... \*(Pu
1522 .Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n
1529 macro is parsed and is callable.
1530 .Ss Enclosure and Quoting Macros
1531 The concept of enclosure is similar to quoting.
1532 The object being to enclose one or more strings between
1533 a pair of characters like quotes or parentheses.
1534 The terms quoting and enclosure are used
1535 interchangeably throughout this document.
1537 one line enclosure macros end
1540 to give a hint of quoting, but there are a few irregularities.
1541 For each enclosure macro
1542 there is also a pair of open and close macros which end
1548 These can be used across one or more lines of text
1549 and while they have nesting limitations, the one line quote macros
1554 .Bd -filled -offset indent
1555 .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
1556 .Em " Quote Close Open Function Result"
1557 \&.Aq .Ac .Ao Angle Bracket Enclosure <string>
1558 \&.Bq .Bc .Bo Bracket Enclosure [string]
1559 \&.Dq .Dc .Do Double Quote ``string''
1560 .Ec .Eo Enclose String (in XX) XXstringXX
1561 \&.Pq .Pc .Po Parenthesis Enclosure (string)
1562 \&.Ql Quoted Literal `st' or string
1563 \&.Qq .Qc .Qo Straight Double Quote "string"
1564 \&.Sq .Sc .So Single Quote `string'
1568 Except for the irregular macros noted below, all
1569 of the quoting macros are parsed and callable.
1570 All handle punctuation properly, as long as it
1571 is presented one character at a time and separated by spaces.
1572 The quoting macros examine opening and closing punctuation
1573 to determine whether it comes before or after the
1574 enclosing string. This makes some nesting possible.
1575 .Bl -tag -width xxx,xxxx
1576 .It Li \&.Ec , \&.Eo
1577 These macros expect the first argument to be the
1578 opening and closing strings respectively.
1580 The quoted literal macro behaves differently for
1586 a quoted literal is always quoted.
1588 troff, an item is only quoted if the width
1589 of the item is less than three constant width characters.
1590 This is to make short strings more visible where the font change
1591 to literal (constant width) is less noticeable.
1593 The prefix macro is not callable, but it is parsed:
1594 .Bl -tag -width "(namexx" -offset indent
1595 .It Li ".Pf ( Fa name2"
1602 (no space) macro performs the analogous suffix function.
1606 Examples of quoting:
1607 .Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent
1610 .It Li \&.Aq \&Ar ctype.h\ )\ ,
1614 .It Li \&.Bq \&Em Greek \&, French \&.
1615 .Bq Em Greek , French .
1618 .It Li ".Dq string abc ."
1620 .It Li ".Dq \'^[A-Z]\'"
1622 .It Li "\&.Ql man mdoc"
1626 .It Li "\&.Qq string ) ,"
1628 .It Li "\&.Qq string Ns ),"
1632 .It Li "\&.Sq string
1636 For a good example of nested enclosure macros, see the
1639 It was created from the same
1640 underlying enclosure macros as those presented in the list
1646 extended argument list macros
1647 were also built from the same underlying routines and are a good
1650 macro usage at its worst.
1651 .Ss No\-Op or Normal Text Macro
1655 a hack for words in a macro command line which should
1657 be formatted and follows the conventional syntax
1662 macro eliminates unwanted spaces in between macro requests.
1663 It is useful for old style argument lists where there is no space
1664 between the flag and argument:
1665 .Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent
1666 .It Li ".Op Fl I Ns Ar directory"
1668 .Op Fl I Ns Ar directory
1673 macro always invokes the
1675 macro after eliminating the space unless another macro name
1679 is parsed and is callable.
1680 .Ss Section Cross References
1683 macro designates a reference to a section header
1684 within the same document.
1685 It is parsed and is callable.
1687 .Bl -tag -width "Li \&.Sx FILES" -offset 14n
1691 .Ss References and Citations
1692 The following macros make a modest attempt to handle references.
1693 At best, the macros make it convenient to manually drop in a subset of
1694 refer style references.
1696 .Bl -tag -width 6n -offset indent -compact
1699 Causes a line break and begins collection
1700 of reference information until the
1701 reference end macro is read.
1704 The reference is printed.
1706 Reference author name, one name per invocation.
1718 Optional information.
1729 The macros beginning with
1731 are not callable, and are parsed only for the trade name macro which
1732 returns to its caller.
1733 (And not very predictably at the moment either.)
1734 The purpose is to allow trade names
1735 to be pretty printed in
1736 .Xr troff Ns / Ns Xr ditroff
1741 macro generates text for use in the
1745 .Dl Usage: .Rv [-std function]
1747 .Ql \&.Rv -std atexit
1748 will generate the following text:
1754 option is valid only for manual page sections 2 and 3.
1755 .Ss Trade Names (or Acronyms and Type Names)
1756 The trade name macro is generally a small caps macro for
1757 all upper case words longer than two characters.
1759 .Dl Usage: .Tn symbol ... \*(Pu
1760 .Bl -tag -width ".Tn ASCII" -compact -offset 14n
1770 is parsed and is callable by other macros.
1771 .Ss Extended Arguments
1776 macros allow one to extend an argument list
1777 on a macro boundary.
1778 Argument lists cannot
1779 be extended within a macro
1780 which expects all of its arguments on one line such
1784 Here is an example of
1786 using the space mode macro to turn spacing off:
1787 .Bd -literal -offset indent
1789 \&.It Xo Sy I Ar operation
1790 \&.No \een Ar count No \een
1796 .Bd -filled -offset indent
1797 .Bl -tag -width flag -compact
1799 .It Xo Sy I Ar operation
1800 .No \en Ar count No \en
1807 .Bd -literal -offset indent
1809 \&.It Cm S No \&/ Ar old_pattern Xo
1810 \&.No \&/ Ar new_pattern
1817 .Bd -filled -offset indent
1818 .Bl -tag -width flag -compact
1820 .It Cm S No \&/ Ar old_pattern Xo
1821 .No \&/ Ar new_pattern
1830 and using enclosure macros:
1831 Test the value of an variable.
1832 .Bd -literal -offset indent
1835 \&.Oo \e&! Oc Ns Ar variable
1836 \&.Op Ar operator variable ...
1841 .Bd -filled -offset indent
1842 .Bl -tag -width flag -compact
1845 .Oo \&! Oc Ns Ar variable
1846 .Op Ar operator variable ...
1851 All of the above examples have used the
1853 macro on the argument list of the
1857 The extend macros are not used very often, and when they are
1858 it is usually to extend the list-item argument list.
1859 Unfortunately, this is also where the extend macros are the
1861 In the first two examples, spacing was turned off;
1862 in the third, spacing was desired in part of the output but
1864 To make these macros work in this situation make sure
1869 macros are placed as shown in the third example.
1872 macro is not alone on the
1874 argument list, spacing will be unpredictable.
1878 must not occur as the first or last macro on a line
1880 Out of 900 manual pages (about 1500 actual pages)
1881 currently released with
1883 only fifteen use the
1886 .Sh PAGE STRUCTURE DOMAIN
1890 section header macros
1891 list below are required in every
1893 The remaining section headers
1894 are recommended at the discretion of the author
1895 writing the manual page.
1898 macro can take up to nine arguments.
1899 It is parsed and but is not callable.
1900 .Bl -tag -width ".Sh SYNOPSIS"
1906 the headers, footers and page layout defaults
1907 will not be set and things will be rather unpleasant.
1910 section consists of at least three items.
1913 name macro naming the subject of the man page.
1914 The second is the Name Description macro,
1916 which separates the subject
1917 name from the third item, which is the description.
1919 description should be the most terse and lucid possible,
1920 as the space available is small.
1924 section describes the typical usage of the
1925 subject of a man page.
1941 for manual page sections 2 and 3, the command and general
1944 is required for sections 1, 5, 6, 7, 8.
1945 Section 4 manuals require a
1950 configuration device usage macro.
1951 Several other macros may be necessary to produce
1952 the synopsis line as shown below:
1954 .Bd -filled -offset indent
1961 The following macros were used:
1964 .Dl \&.Op \&Fl benstuv
1974 recognize the pipe bar character
1976 so a command line such as:
1978 .Dl ".Op Fl a | Fl b"
1980 will not go orbital.
1982 normally interprets a \*(Ba as a special operator.
1984 .Sx PREDEFINED STRINGS
1986 character in other situations.
1987 .It \&.Sh DESCRIPTION
1988 In most cases the first text in the
1991 is a brief paragraph on the command, function or file,
1992 followed by a lexical list of options and respective
1994 To create such a list, the
2001 macros are used (see
2002 .Sx Lists and Columns
2008 section headers are part of the
2009 preferred manual page layout and must be used appropriately
2010 to maintain consistency.
2011 They are listed in the order
2012 in which they would be used.
2013 .Bl -tag -width SYNOPSIS
2014 .It \&.Sh ENVIRONMENT
2017 section should reveal any related
2019 variables and clues to their behavior and/or usage.
2021 There are several ways to create examples.
2028 Files which are used or created by the man page subject
2029 should be listed via the
2035 References to other material on the man page topic and
2036 cross references to other relevant man pages should
2041 are specified using the
2044 Cross references in the
2046 section should be sorted by section number, and then
2047 placed in alphabetical order and comma separated. For example:
2056 style references are not accommodated.
2058 If the command, library function or file adheres to a
2059 specific implementation such as
2063 this should be noted here.
2065 command does not adhere to any standard, its history
2066 should be noted in the
2070 Any command which does not adhere to any specific standards
2071 should be outlined historically in this section.
2073 Credits, if need be, should be placed here.
2076 macro should be used to specify the name of the person.
2077 .It \&.Sh DIAGNOSTICS
2078 Diagnostics from a command should be placed in this section.
2080 Specific error handling, especially from library functions
2081 (man page sections 2, 3 and 9) should go here.
2084 macro is used to specify an errno.
2086 Blatant problems with the topic go here...
2091 sections may be added,
2092 for example, this section was set with:
2093 .Bd -literal -offset 14n
2094 \&.Sh PAGE STRUCTURE DOMAIN
2096 .Ss Paragraphs and Line Spacing.
2101 paragraph command may
2102 be used to specify a line space where necessary.
2103 The macro is not necessary after a
2113 macro asserts a vertical distance unless the -compact flag is given).
2115 .\" This worked with version one, need to redo for version three
2118 .\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
2119 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
2136 .\" .Em is produced by
2152 .\" This example shows the same equation in a different format.
2156 .\" signs were forced with
2160 .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
2161 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
2172 .\" .Li \&.Cx \e\ +\e\ \e&
2183 .\" .Em is produced by
2191 .\" .Li \&.Cx \e\ +\e\ \e&
2202 .\" The incantation below was
2208 .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
2210 .\" .Li \&.Cx Op Sy ?/
2220 .\" .Em is produced by
2222 .\" .Li \&.Ar \e\ b1 e1 f1
2234 The only keep that is implemented at this time is for words.
2241 The only option that
2245 and is useful for preventing line breaks in the middle of options.
2246 In the example for the make command line arguments (see
2247 .Sx What's in a name ) ,
2251 flag and the argument
2253 (Actually, the option macro used to prevent this from occurring,
2254 but was dropped when the decision (religious) was made to force
2255 right justified margins in
2257 as options in general look atrocious when spread across a sparse
2259 More work needs to be done with the keep macros, a
2261 option needs to be added.)
2262 .Ss Examples and Displays
2263 There are five types of displays, a quickie one line indented display
2265 a quickie one line literal display
2267 and a block literal, block filled and block ragged which use
2275 .Bl -tag -width \&.Dlxx
2277 (D-one) Display one line of indented text.
2278 This macro is parsed, but it is not callable.
2282 The above was produced by:
2283 .Li \&.D1 \&Fl ldghfstru .
2286 Display one line of indented
2291 example macro has been used throughout this
2294 the indent (display) of one line of text.
2295 Its default font is set to
2296 constant width (literal) however
2297 it is parsed and will recognize other macros.
2298 It is not callable however.
2300 .Dl % ls -ldg /usr/local/bin
2302 The above was produced by
2303 .Li \&.Dl % ls -ldg /usr/local/bin .
2308 display must be ended with the
2311 Displays may be nested within displays and
2314 has the following syntax:
2316 .Dl ".Bd display-type [-offset offset_value] [-compact]"
2318 The display-type must be one of the following four types and
2319 may have an offset specifier for indentation:
2322 .Bl -tag -width "file file_name " -compact
2324 Display a block of text as typed,
2325 right (and left) margin edges are left ragged.
2327 Display a filled (formatted) block.
2328 The block of text is formatted (the edges are filled \-
2329 not left unjustified).
2331 Display a literal block, useful for source code or
2332 simple tabbed or spaced text.
2333 .It Fl file Ar file_name
2334 The file name following the
2336 flag is read and displayed.
2338 asserted and tabs are set at 8 constant width character
2339 intervals, however any
2340 .Xr troff/ Ns Nm \-mdoc
2341 commands in file will be processed.
2342 .It Fl offset Ar string
2345 is specified with one of the following strings, the string
2346 is interpreted to indicate the level of indentation for the
2347 forthcoming block of text:
2349 .Bl -tag -width "indent-two" -compact
2351 Align block on the current left margin,
2352 this is the default mode of
2355 Supposedly center the block.
2357 unfortunately, the block merely gets
2358 left aligned about an imaginary center margin.
2360 Indents by one default indent value or tab.
2362 indent value is also used for the
2364 display so one is guaranteed the two types of displays
2366 This indent is normally set to 6n or about two
2367 thirds of an inch (six constant width characters).
2369 Indents two times the default indent value.
2373 aligns the block about two inches from
2374 the right side of the page.
2376 work and perhaps may never do the right thing by
2384 There are five macros for changing the appearance of the manual page text:
2385 .Bl -tag -width \&.Emxx
2387 Text may be stressed or emphasized with the
2390 The usual font for emphasis is italic.
2392 .Dl Usage: .Em argument ... \*(Pu
2393 .Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
2394 .It Li ".Em does not"
2396 .It Li ".Em exceed 1024 ."
2398 .It Li ".Em vide infra ) ) ,"
2399 .Em vide infra ) ) ,
2404 macro is parsed and is callable.
2405 It is an error to call
2411 literal macro may be used for special characters,
2412 variable constants, anything which should be displayed as it
2415 .Dl Usage: .Li argument ... \*(Pu
2416 .Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n
2419 .It Li \&.Li M1 M2 M3\ ;
2421 .It Li \&.Li cntrl-D\ )\ ,
2423 .It Li \&.Li 1024\ ...
2429 macro is parsed and is callable.
2431 The symbolic emphasis macro is generally a boldface macro in
2432 either the symbolic sense or the traditional English usage.
2434 .Dl Usage: .Sy symbol ... \*(Pu
2435 .Bl -tag -width ".Sy Important Noticex" -compact -offset 14n
2436 .It Li \&.Sy Important Notice
2437 .Sy Important Notice
2442 macro is parsed and is callable.
2450 font mode must be ended with the
2453 Font modes may be nested within other font modes.
2455 has the following syntax:
2459 The font-mode must be one of the following three types:
2462 .Bl -tag -width "file file_name " -compact
2463 .It Sy \&Em | Fl emphasis
2466 macro was used for the entire block of text.
2467 .It Sy \&Li | Fl literal
2470 macro was used for the entire block of text.
2471 .It Sy \&Sy | Fl symbolic
2474 macro was used for the entire block of text.
2479 .Ss Tagged Lists and Columns
2480 There are several types of lists which may be initiated with the
2483 Items within the list
2484 are specified with the
2487 each list must end with the
2490 Lists may be nested within themselves and within displays.
2491 Columns may be used inside of lists, but lists are unproven
2494 In addition, several list attributes may be specified such as
2495 the width of a tag, the list offset, and compactness
2496 (blank lines between items allowed or disallowed).
2497 Most of this document has been formatted with a tag style list
2499 For a change of pace, the list-type used to present the list-types
2500 is an over-hanging list
2502 This type of list is quite popular with
2504 users, but might look a bit funny after having read many pages of
2506 The following list types are accepted by
2513 These three are the simplest types of lists.
2516 macro has been given, items in the list are merely
2517 indicated by a line consisting solely of the
2520 For example, the source text for a simple enumerated list
2522 .Bd -literal -offset indent-two
2523 \&.Bl -enum -compact
2525 \&Item one goes here.
2527 \&And item two here.
2529 \&Lastly item three goes here.
2535 .Bl -enum -offset indent-two -compact
2541 Lastly item three goes here.
2544 A simple bullet list construction:
2545 .Bd -literal -offset indent-two
2546 \&.Bl -bullet -compact
2548 \&Bullet one goes here.
2555 .Bl -bullet -offset indent-two -compact
2557 Bullet one goes here.
2567 These list-types collect arguments specified with the
2569 macro and create a label which may be
2571 into the forthcoming text,
2573 from the forthcoming text,
2575 from above and not indented or
2578 list was constructed with the
2583 macro is parsed only for the inset, hang
2584 and tag list-types and is not callable.
2585 Here is an example of inset labels:
2586 .Bl -inset -offset indent
2588 The tagged list (also called a tagged paragraph) is the
2589 most common type of list used in the Berkeley manuals.
2591 Diag lists create section four diagnostic lists
2592 and are similar to inset lists except callable
2595 Hanged labels are a matter of taste.
2597 Overhanging labels are nice when space is constrained.
2599 Inset labels are useful for controlling blocks of
2600 paragraphs and are valuable for converting
2602 manuals to other formats.
2605 Here is the source text which produced the above example:
2606 .Bd -literal -offset indent
2607 \&.Bl -inset -offset indent
2609 \&The tagged list (also called a tagged paragraph) is the
2610 \&most common type of list used in the Berkeley manuals.
2612 \&Diag lists create section four diagnostic lists
2613 \&and are similar to inset lists except callable
2614 \¯os are ignored.
2616 \&Hanged labels are a matter of taste.
2618 \&Overhanging labels are nice when space is constrained.
2620 \&Inset labels are useful for controlling blocks of
2621 \¶graphs and are valuable for converting
2623 \&manuals to other formats.
2627 Here is a hanged list with two items:
2628 .Bl -hang -offset indent
2630 labels appear similar to tagged lists when the
2631 label is smaller than the label width.
2632 .It Em Longer hanged list labels
2633 blend in to the paragraph unlike
2634 tagged paragraph labels.
2637 And the unformatted text which created it:
2638 .Bd -literal -offset indent
2639 \&.Bl -hang -offset indent
2641 \&labels appear similar to tagged lists when the
2642 \&label is smaller than the label width.
2643 \&.It Em Longer hanged list labels
2644 \&blend in to the paragraph unlike
2645 \&tagged paragraph labels.
2649 The tagged list which follows uses an optional width specifier to control
2650 the width of the tag.
2652 .Bl -tag -width "PAGEIN" -compact -offset indent
2654 sleep time of the process (seconds blocked)
2658 resulting from references
2659 by the process to pages not loaded in core.
2661 numerical user-id of process owner
2663 numerical id of parent of process process priority
2664 (non-positive when in non-interruptible wait)
2668 .Bd -literal -offset indent
2669 \&.Bl -tag -width "PAGEIN" -compact -offset indent
2671 \&sleep time of the process (seconds blocked)
2675 \&resulting from references
2676 \&by the process to pages not loaded in core.
2678 \&numerical user-id of process owner
2680 \&numerical id of parent of process process priority
2681 \&(non-positive when in non-interruptible wait)
2685 Acceptable width specifiers:
2686 .Bl -tag -width Ar -offset indent
2687 .It Fl width Ar "\&Fl"
2688 sets the width to the default width for a flag.
2690 macros have a default width value.
2694 set to ten constant width characters or about five sixth of
2696 .It Fl width Ar "24n"
2697 sets the width to 24 constant width characters or about two
2701 is absolutely necessary for the scaling to work correctly.
2702 .It Fl width Ar "ENAMETOOLONG"
2703 sets width to the constant width length of the
2705 .It Fl width Ar "\\*qint mkfifo\\*q"
2706 again, the width is set to the constant width of the string
2710 If a width is not specified for the tag list type, the first
2713 is invoked, an attempt is made to determine an appropriate
2715 If the first argument to
2717 is a callable macro, the default width for that macro will be used
2718 as if the macro name had been supplied as the width.
2720 if another item in the list is given with a different callable
2721 macro name, a new and nested list is assumed.
2722 .Sh PREDEFINED STRINGS
2723 The following strings are predefined and may be used by
2724 preceding with the troff string interpreting sequence
2728 is the name of the defined string or as
2732 is the name of the string.
2733 The interpreting sequence may be used anywhere in the text.
2735 .Bl -column "String " "Nroff " "Troff " -offset indent
2736 .It Sy "String Nroff Troff"
2737 .It Li "<=" Ta \&<\&= Ta \*(<=
2738 .It Li ">=" Ta \&>\&= Ta \*(>=
2739 .It Li "Rq" Ta "''" Ta \*(Rq
2740 .It Li "Lq" Ta "``" Ta \*(Lq
2741 .It Li "ua" Ta ^ Ta \*(ua
2742 .It Li "aa" Ta ' Ta \*(aa
2743 .It Li "ga" Ta \` Ta \*(ga
2744 .\" .It Li "sL" Ta ` Ta \*(sL
2745 .\" .It Li "sR" Ta ' Ta \*(sR
2746 .It Li "q" Ta \&" Ta \*q
2747 .It Li "Pi" Ta pi Ta \*(Pi
2748 .It Li "Ne" Ta != Ta \*(Ne
2749 .It Li "Le" Ta <= Ta \*(Le
2750 .It Li "Ge" Ta >= Ta \*(Ge
2751 .It Li "Lt" Ta < Ta \*(Gt
2752 .It Li "Gt" Ta > Ta \*(Lt
2753 .It Li "Pm" Ta +- Ta \*(Pm
2754 .It Li "If" Ta infinity Ta \*(If
2755 .It Li "Na" Ta \fINaN\fP Ta \*(Na
2756 .It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
2762 should be written as
2764 since it is only one char.
2766 The debugging facilities for
2768 are limited, but can help detect subtle errors such
2769 as the collision of an argument name with an internal
2770 register or macro name.
2772 A register is an arithmetic storage class for
2774 with a one or two character name.
2775 All registers internal to
2781 are two characters and
2782 of the form <upper_case><lower_case> such as
2784 <lower_case><upper_case> as
2787 <upper or lower letter><digit> as
2789 And adding to the muddle,
2791 has its own internal registers all of which are either
2792 two lower case characters or a dot plus a letter or meta-character
2794 In one of the introduction examples, it was shown how to
2795 prevent the interpretation of a macro name with the escape sequence
2797 This is sufficient for the internal register names also.
2799 .\" Every callable macro name has a corresponding register
2800 .\" of the same name (<upper_case><lower_case>).
2801 .\" There are also specific registers which have
2802 .\" been used for stacks and arrays and are listed in the
2804 .\" .Bd -ragged -offset 4n
2805 .\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
2806 .\" [a-z][A-Z] registers corresponding to macro names (example ``aR'')
2807 .\" C[0-9] argument types (example C1)
2808 .\" O[0-9] offset stack (displays)
2809 .\" h[0-9] horizontal spacing stack (lists)
2810 .\" o[0-9] offset (stack) (lists)
2811 .\" t[0-9] tag stack (lists)
2812 .\" v[0-9] vertical spacing stack (lists)
2813 .\" w[0-9] width tag/label stack
2816 If a non-escaped register name is given in the argument list of a request
2817 unpredictable behavior will occur.
2818 In general, any time huge portions
2819 of text do not appear where expected in the output, or small strings
2820 such as list tags disappear, chances are there is a misunderstanding
2821 about an argument type in the argument list.
2822 Your mother never intended for you to remember this evil stuff - so here
2823 is a way to find out whether or not your arguments are valid: The
2826 macro displays the interpretation of the argument list for most
2831 macro do not contain debugging information.
2832 All of the callable macros do,
2833 and it is strongly advised whenever in doubt,
2838 .Dl Usage: \&.Db [on | off]
2840 An example of a portion of text with
2841 the debug macro placed above and below an
2842 artificially created problem (a flag argument
2847 .Bd -literal -offset indent
2849 \&.Op Fl aC Ar file )
2853 The resulting output:
2854 .Bd -literal -offset indent
2856 DEBUG(argv) MACRO: `.Op' Line #: 2
2857 Argc: 1 Argv: `Fl' Length: 2
2858 Space: `' Class: Executable
2859 Argc: 2 Argv: `aC' Length: 2
2860 Space: `' Class: Executable
2861 Argc: 3 Argv: `Ar' Length: 2
2862 Space: `' Class: Executable
2863 Argc: 4 Argv: `file' Length: 4
2864 Space: ` ' Class: String
2865 Argc: 5 Argv: `)' Length: 1
2866 Space: ` ' Class: Closing Punctuation or suffix
2867 MACRO REQUEST: .Op Fl aC Ar file )
2871 The first line of information tells the name of the calling
2874 and the line number it appears on.
2875 If one or more files are involved
2876 (especially if text from another file is included) the line number
2878 If there is only one file, it should be accurate.
2879 The second line gives the argument count, the argument
2882 If the length of an argument is two characters, the
2883 argument is tested to see if it is executable (unfortunately, any
2884 register which contains a non-zero value appears executable).
2885 The third line gives the space allotted for a class, and the
2887 The problem here is the argument aC should not be
2889 The four types of classes are string, executable, closing
2890 punctuation and opening punctuation.
2891 The last line shows the entire
2892 argument list as it was read.
2893 In this next example, the offending
2896 .Bd -literal -offset indent
2898 \&.Em An escaped \e&aC
2901 .Bd -literal -offset indent
2903 DEBUG(fargv) MACRO: `.Em' Line #: 2
2904 Argc: 1 Argv: `An' Length: 2
2905 Space: ` ' Class: String
2906 Argc: 2 Argv: `escaped' Length: 7
2907 Space: ` ' Class: String
2908 Argc: 3 Argv: `aC' Length: 2
2909 Space: ` ' Class: String
2910 MACRO REQUEST: .Em An escaped &aC
2916 shows up with the same length of 2 as the
2918 sequence produces a zero width, but a register
2921 was not found and the type classified as string.
2923 Other diagnostics consist of usage statements and are self explanatory.
2924 .Sh GROFF, TROFF AND NROFF
2927 package does not need compatibility mode with
2930 The package inhibits page breaks, and the headers and footers
2931 which normally occur at those breaks with
2933 to make the manual more efficient for viewing on-line.
2938 does eject the imaginary remainder of the page at end of file.
2939 The inhibiting of the page breaks makes
2941 files unsuitable for hardcopy.
2942 There is a register named
2944 which can be set to zero in the site dependent style file
2945 .Pa /usr/src/share/tmac/doc-nroff
2946 to restore the old style behavior.
2948 .Bl -tag -width /usr/share/man0/template.doc -compact
2949 .It Pa /usr/share/tmac/tmac.doc
2950 manual macro package
2951 .It Pa /usr/share/misc/mdoc.template
2952 template for writing a man page
2953 .It Pa /usr/share/examples/mdoc/*
2954 several example man pages
2961 Undesirable hyphenation on the dash of a flag
2962 argument is not yet resolved, and causes
2963 occasional mishaps in the
2966 (line break on the hyphen).
2968 Predefined strings are not declared in documentation.
2970 Section 3f has not been added to the header routines.
2973 font should be changed in
2978 needs to have a check to prevent splitting up
2979 if the line length is too short.
2981 separates the last parenthesis, and sometimes
2982 looks ridiculous if a line is in fill mode.
2984 The method used to prevent header and footer page
2985 breaks (other than the initial header and footer) when using
2986 nroff occasionally places an unsightly partially filled line (blank)
2987 at the would be bottom of the page.
2989 The list and display macros to not do any keeps
2990 and certainly should be able to.
2991 .\" Note what happens if the parameter list overlaps a newline
2993 .\" to make sure a line boundary is crossed:
2995 .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
2998 .\" produces, nudge nudge,
2999 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
3000 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
3002 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
3004 .\" If double quotes are used, for example:
3006 .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
3009 .\" produces, nudge nudge,
3010 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
3012 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
3014 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
3016 .\" Not a pretty sight...
3017 .\" In a paragraph, a long parameter containing unpaddable spaces as
3018 .\" in the former example will cause
3020 .\" to break the line and spread
3021 .\" the remaining words out.
3022 .\" The latter example will adjust nicely to
3023 .\" justified margins, but may break in between an argument and its
3027 .\" the right margin adjustment is normally ragged and the problem is