1MDOC(7)              BSD Miscellaneous Information Manual              MDOC(7)
2

NAME

4     mdoc — quick reference guide for the -mdoc macro package
5

SYNOPSIS

7     groff -mdoc files ...
8

DESCRIPTION

10     The -mdoc package is a set of content-based and domain-based macros used
11     to format the BSD man pages.  The macro names and their meanings are
12     listed below for quick reference; for a detailed explanation on using the
13     package, see the tutorial sampler mdoc.samples(7).
14
15     Note that this is not the usual macro package for Linux documentation,
16     although it is used for documentation of several widely used programs;
17     see man(7).
18
19     The macros are described in two groups, the first includes the structural
20     and physical page layout macros.  The second contains the manual and gen‐
21     eral text domain macros which differentiate the -mdoc package from other
22     troff formatting packages.
23

PAGE STRUCTURE DOMAIN

25   Title Macros
26     To create a valid manual page, these three macros, in this order, are
27     required:
28     .Dd   Month day, year                       Document date.
29     .Dt   DOCUMENT_TITLE [section] [volume]     Title, in upper case.
30     .Os   OPERATING_SYSTEM [version/release]    Operating system (BSD).
31
32   Page Layout Macros
33     Section headers, paragraph breaks, lists and displays.
34     .Sh   Section Headers.  Valid headers, in the order of presentation:
35           NAME          Name section, should include the ‘.Nm’ or ‘.Fn’ and
36                         the ‘.Nd’ macros.
37           SYNOPSIS      Usage.
38           DESCRIPTION   General description, should include options and
39                         parameters.
40           RETURN VALUE  Sections two and three function calls.
41           ENVIRONMENT   Describe environment variables.
42           FILES         Files associated with the subject.
43           EXAMPLES      Examples and suggestions.
44           DIAGNOSTICS   Normally used for section four device interface diag‐
45                         nostics.
46           ERRORS        Sections two and three error and signal handling.
47           SEE ALSO      Cross references and citations.
48           CONFORMING TO
49                         Conformance to standards if applicable.
50           HISTORY       If a standard is not applicable, the history of the
51                         subject should be given.
52           BUGS          Gotchas and caveats.
53           other         Customized headers may be added at the authors dis‐
54                         cretion.
55     .Ss   Subsection Headers.
56     .Pp   Paragraph Break.  Vertical space (one line).
57     .D1   (D-one) Display-one Indent and display one text line.
58     .Dl   (D-ell) Display-one literal.  Indent and display one line of lit‐
59           eral text.
60     .Bd   Begin-display block.  Display options:
61           -ragged          Unjustified (ragged edges).
62           -filled          Justified.
63           -literal         Literal text or code.
64           -file name       Read in named file and display.
65           -offset string   Offset display.  Acceptable string values:
66                            left        Align block on left (default).
67                            center      Approximate center margin.
68                            indent      Six constant width spaces (a tab).
69                            indent-two  Two tabs.
70                            right       Left aligns block 2 inches from right.
71                            xxn         Where xx is a number from 4n to 99n.
72                            Aa          Where Aa is a callable macro name.
73                            string      The width of string is used.
74     .Ed   End-display (matches .Bd).
75     .Bl   Begin-list.  Create lists or columns.  Options:
76           List-types
77                 -bullet    Bullet Item List
78                 -item      Unlabeled List
79                 -enum      Enumerated List
80                 -tag       Tag Labeled List
81                 -diag      Diagnostic List
82                 -hang      Hanging Labeled List
83                 -ohang     Overhanging Labeled List
84                 -inset     Inset or Run-on Labeled List
85           List-parameters
86                 -offset    (All lists.) See ‘.Bd’ begin-display above.
87                 -width     (-tag and -hang lists only.)  See ‘.Bd’.
88                 -compact   (All lists.)  Suppresses blank lines.
89     .El   End-list.
90     .It   List item.
91

MANUAL AND GENERAL TEXT DOMAIN MACROS

93     The manual and general text domain macros are special in that most of
94     them are parsed for callable macros for example:
95
96           .Op Fl s Ar file
97                       Produces [-s file]
98
99     In this example, the option enclosure macro ‘.Op’ is parsed, and calls
100     the callable content macro ‘Fl’ which operates on the argument ‘s’ and
101     then calls the callable content macro ‘Ar’ which operates on the argument
102     ‘file’.  Some macros may be callable, but are not parsed and vice versa.
103     These macros are indicated in the parsed and callable columns below.
104
105     Unless stated, manual domain macros share a common syntax:
106
107           .Va argument [ . , ; : ( ) [ ] argument ... ]
108
109     Note: Opening and closing punctuation characters are recognized as such
110     only if they are presented one at a time.  The string ‘),’ is not recog‐
111     nized as punctuation and will be output with a leading white space and in
112     what ever font the calling macro uses.  The argument list ‘] ) ,’ is rec‐
113     ognized as three sequential closing punctuation characters and a leading
114     white space is not output between the characters and the previous argu‐
115     ment (if any).  The special meaning of a punctuation character may be
116     escaped with the string ‘\&’.  For example the following string,
117
118           .Ar file1 , file2 , file3 ) .   Produces file1, file2, file3).
119
120   Manual Domain Macros
121     Name    Parsed    Callable     Description
122     Ad      Yes       Yes          Address. (This macro may be deprecated.)
123     An      Yes       Yes          Author name.
124     Ar      Yes       Yes          Command-line argument.
125     Cd      No        No           Configuration declaration (section four
126                                    only).
127     Cm      Yes       Yes          Command-line argument modifier.
128     Dv      Yes       Yes          Defined variable (source code).
129     Er      Yes       Yes          Error number (source code).
130     Ev      Yes       Yes          Environment variable.
131     Fa      Yes       Yes          Function argument.
132     Fd      Yes       Yes          Function declaration.
133     Fn      Yes       Yes          Function call (also .Fo and .Fc).
134     Ic      Yes       Yes          Interactive command.
135     Li      Yes       Yes          Literal text.
136     Nm      Yes       Yes          Command name.
137     Op      Yes       Yes          Option (also .Oo and .Oc).
138     Ot      Yes       Yes          Old style function type (Fortran only).
139     Pa      Yes       Yes          Pathname or filename.
140     St      Yes       Yes          Standards (-p1003.2, -p1003.1 or -ansiC)
141     Va      Yes       Yes          Variable name.
142     Vt      Yes       Yes          Variable type (Fortran only).
143     Xr      Yes       Yes          Manual Page Cross Reference.
144
145   General Text Domain Macros
146     Name    Parsed    Callable     Description
147     %A      Yes       No           Reference author.
148     %B      Yes       Yes          Reference book title.
149     %C      No        No           Reference place of publishing (city).
150     %D      No        No           Reference date.
151     %J      Yes       Yes          Reference journal title.
152     %N      No        No           Reference issue number.
153     %O      No        No           Reference optional information.
154     %P      No        No           Reference page number(s).
155     %R      No        No           Reference report Name.
156     %T      Yes       Yes          Reference article title.
157     %V      No        No           Reference volume.
158     Ac      Yes       Yes          Angle close quote.
159     Ao      Yes       Yes          Angle open quote.
160     Ap      Yes       Yes          Apostrophe.
161     Aq      Yes       Yes          Angle quote.
162     At      No        No           AT&T UNIX
163     Bc      Yes       Yes          Bracket close quote.
164     Bf      No        No           Begin font mode.
165     Bo      Yes       Yes          Bracket open quote.
166     Bq      Yes       Yes          Bracket quote.
167     Bx      Yes       Yes          BSD.
168     Db      No        No           Debug (default is "off")
169     Dc      Yes       Yes          Double close quote.
170     Do      Yes       Yes          Double open quote.
171     Dq      Yes       Yes          Double quote.
172     Ec      Yes       Yes          Enclose string close quote.
173     Ef      No        No           End font mode.
174     Em      Yes       Yes          Emphasis (traditional English).
175     Eo      Yes       Yes          Enclose string open quote.
176     Fx      No        No           FreeBSD operating system
177     No      Yes       Yes          Normal text (no-op).
178     Ns      Yes       Yes          No space.
179     Pc      Yes       Yes          Parenthesis close quote.
180     Pf      Yes       No           Prefix string.
181     Po      Yes       Yes          Parenthesis open quote.
182     Pq      Yes       Yes          Parentheses quote.
183     Qc      Yes       Yes          Straight Double close quote.
184     Ql      Yes       Yes          Quoted literal.
185     Qo      Yes       Yes          Straight Double open quote.
186     Qq      Yes       Yes          Straight Double quote.
187     Re      No        No           Reference end.
188     Rs      No        No           Reference start.
189     Rv      No        No           Return values (sections two and three
190                                    only).
191     Sc      Yes       Yes          Single close quote.
192     So      Yes       Yes          Single open quote.
193     Sq      Yes       Yes          Single quote.
194     Sm      No        No           Space mode (default is "on")
195     Sx      Yes       Yes          Section Cross Reference.
196     Sy      Yes       Yes          Symbolic (traditional English).
197     Tn      Yes       Yes          Trade or type name (small Caps).
198     Ux      Yes       Yes          UNIX
199     Xc      Yes       Yes          Extend argument list close.
200     Xo      Yes       Yes          Extend argument list open.
201
202     Macro names ending in ‘q’ quote remaining items on the argument list.
203     Macro names ending in ‘o’ begin a quote which may span more than one line
204     of input and are close quoted with the matching macro name ending in ‘c’.
205     Enclosure macros may be nested and are limited to eight arguments.
206
207     Note: the extended argument list macros (‘.Xo’, ‘.Xc’) and the function
208     enclosure macros (‘.Fo’, ‘.Fc’) are irregular.  The extended list macros
209     are used when the number of macro arguments would exceed the troff limi‐
210     tation of nine arguments.
211
212     The macros UR (starting a URI/URL hypertext reference), UE (ending one),
213     and UN (identifying a target for a reference) are also available.  See
214     man(7) for more information on these macros.
215

FILES

217     doc.tmac          Manual and general text domain macros.
218     tmac/doc-common   Common structural macros and definitions.
219     tmac/doc-nroff    Site dependent nroff style file.
220     tmac/doc-ditroff  Site dependent troff style file.
221     tmac/doc-syms     Special defines (such as the standards macro).
222

SEE ALSO

224     groff_mdoc(7), mdoc.samples(7), man(7), man-pages(7)
225

COLOPHON

227     This page is part of release 3.53 of the Linux man-pages project.  A
228     description of the project, and information about reporting bugs, can be
229     found at http://www.kernel.org/doc/man-pages/.
230
231Linux                            July 11, 1999                           Linux
Impressum