1MDOC(7) BSD Miscellaneous Information Manual MDOC(7)
2
4 mdoc — quick reference guide for the -mdoc macro package
5
7 groff -mdoc files ...
8
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 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 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
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 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
93 The manual and general text domain macros are special in that most of
94 them are parsed for callable macros for example:
95 .Op Fl s Ar file
97 Produces [-s file]
98 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 Unless stated, manual domain macros share a common syntax:
106 .Va argument [ . , ; : ( ) [ ] argument ... ]
108 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 .Ar file1 , file2 , file3 ) . Produces file1, file2, file3).
119 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 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 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 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 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
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
224 groff_mdoc(7), mdoc.samples(7), man(7), man-pages(7)
225
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/.
230Linux July 11, 1999 Linux