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 groff_mdoc(7) and 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.
30 .Dt DOCUMENT_TITLE [section] [volume] Title, in uppercase.
31 .Os OPERATING_SYSTEM [version/release] Operating system (BSD).
32 Page Layout Macros
34 Section headers, paragraph breaks, lists and displays.
35 .Sh Section Headers. Valid headers, in the order of presentation:
37 NAME Name section, should include the ‘.Nm’ or ‘.Fn’ and
38 the ‘.Nd’ macros.
39 SYNOPSIS Usage.
40 DESCRIPTION General description, should include options and
41 parameters.
42 RETURN VALUE Sections two and three function calls.
43 ENVIRONMENT Describe environment variables.
44 FILES Files associated with the subject.
45 EXAMPLES Examples and suggestions.
46 DIAGNOSTICS Normally used for section four device interface diag‐
47 nostics.
48 ERRORS Sections two and three error and signal handling.
49 SEE ALSO Cross references and citations.
50 CONFORMING TO
51 Conformance to standards if applicable.
52 HISTORY If a standard is not applicable, the history of the
53 subject should be given.
54 BUGS Gotchas and caveats.
55 other Customized headers may be added at the authors dis‐
56 cretion.
57 .Ss Subsection Headers.
58 .Pp Paragraph Break. Vertical space (one line).
59 .D1 (D-one) Display-one Indent and display one text line.
60 .Dl (D-ell) Display-one literal. Indent and display one line of lit‐
61 eral text.
62 .Bd Begin-display block. Display options:
63 -ragged Unjustified (ragged edges).
64 -filled Justified.
65 -literal Literal text or code.
66 -file name Read in named file and display.
67 -offset string Offset display. Acceptable string values:
68 left Align block on left (default).
69 center Approximate center margin.
70 indent Six constant width spaces (a tab).
71 indent-two Two tabs.
72 right Left aligns block 2 inches from right.
73 xxn Where xx is a number from 4n to 99n.
74 Aa Where Aa is a callable macro name.
75 string The width of string is used.
76 .Ed End-display (matches .Bd).
77 .Bl Begin-list. Create lists or columns. Options:
78 List-types
79 -bullet Bullet Item List
80 -item Unlabeled List
81 -enum Enumerated List
82 -tag Tag Labeled List
83 -diag Diagnostic List
84 -hang Hanging Labeled List
85 -ohang Overhanging Labeled List
86 -inset Inset or Run-on Labeled List
87 List-parameters
88 -offset (All lists.) See ‘.Bd’ begin-display above.
89 -width (-tag and -hang lists only.) See ‘.Bd’.
90 -compact (All lists.) Suppresses blank lines.
91 .El End-list.
92 .It List item.
93
95 The manual and general text domain macros are special in that most of
96 them are parsed for callable macros for example:
97 .Op Fl s Ar file
99 Produces [-s file]
100 In this example, the option enclosure macro ‘.Op’ is parsed, and calls
102 the callable content macro ‘Fl’ which operates on the argument ‘s’ and
103 then calls the callable content macro ‘Ar’ which operates on the argument
104 ‘file’. Some macros may be callable, but are not parsed and vice versa.
105 These macros are indicated in the parsed and callable columns below.
106 Unless stated, manual domain macros share a common syntax:
108 .Va argument [ . , ; : ( ) [ ] argument ... ]
110 Note: Opening and closing punctuation characters are recognized as such
112 only if they are presented one at a time. The string ‘),’ is not recog‐
113 nized as punctuation and will be output with a leading white space and in
114 what ever font the calling macro uses. The argument list ‘] ) ,’ is rec‐
115 ognized as three sequential closing punctuation characters and a leading
116 white space is not output between the characters and the previous argu‐
117 ment (if any). The special meaning of a punctuation character may be
118 escaped with the string ‘\&’. For example the following string,
119 .Ar file1 , file2 , file3 ) . Produces file1, file2, file3).
121 Manual Domain Macros
123 Name Parsed Callable Description
124 Ad Yes Yes Address. (This macro may be deprecated.)
125 An Yes Yes Author name.
126 Ar Yes Yes Command-line argument.
127 Cd No No Configuration declaration (section four
128 only).
129 Cm Yes Yes Command-line argument modifier.
130 Dv Yes Yes Defined variable (source code).
131 Er Yes Yes Error number (source code).
132 Ev Yes Yes Environment variable.
133 Fa Yes Yes Function argument.
134 Fd Yes Yes Function declaration.
135 Fn Yes Yes Function call (also .Fo and .Fc).
136 Ic Yes Yes Interactive command.
137 Li Yes Yes Literal text.
138 Nm Yes Yes Command name.
139 Op Yes Yes Option (also .Oo and .Oc).
140 Ot Yes Yes Old style function type (Fortran only).
141 Pa Yes Yes Pathname or filename.
142 St Yes Yes Standards (-p1003.2, -p1003.1 or -ansiC)
143 Va Yes Yes Variable name.
144 Vt Yes Yes Variable type (Fortran only).
145 Xr Yes Yes Manual Page Cross Reference.
146 General Text Domain Macros
148 Name Parsed Callable Description
149 %A Yes No Reference author.
150 %B Yes Yes Reference book title.
151 %C No No Reference place of publishing (city).
152 %D No No Reference date.
153 %J Yes Yes Reference journal title.
154 %N No No Reference issue number.
155 %O No No Reference optional information.
156 %P No No Reference page number(s).
157 %R No No Reference report Name.
158 %T Yes Yes Reference article title.
159 %V No No Reference volume.
160 Ac Yes Yes Angle close quote.
161 Ao Yes Yes Angle open quote.
162 Ap Yes Yes Apostrophe.
163 Aq Yes Yes Angle quote.
164 At No No AT&T UNIX
165 Bc Yes Yes Bracket close quote.
166 Bf No No Begin font mode.
167 Bo Yes Yes Bracket open quote.
168 Bq Yes Yes Bracket quote.
169 Bx Yes Yes BSD.
170 Db No No Debug (default is "off")
171 Dc Yes Yes Double close quote.
172 Do Yes Yes Double open quote.
173 Dq Yes Yes Double quote.
174 Ec Yes Yes Enclose string close quote.
175 Ef No No End font mode.
176 Em Yes Yes Emphasis (traditional English).
177 Eo Yes Yes Enclose string open quote.
178 Fx No No FreeBSD operating system
179 No Yes Yes Normal text (no-op).
180 Ns Yes Yes No space.
181 Pc Yes Yes Parenthesis close quote.
182 Pf Yes No Prefix string.
183 Po Yes Yes Parenthesis open quote.
184 Pq Yes Yes Parentheses quote.
185 Qc Yes Yes Straight Double close quote.
186 Ql Yes Yes Quoted literal.
187 Qo Yes Yes Straight Double open quote.
188 Qq Yes Yes Straight Double quote.
189 Re No No Reference end.
190 Rs No No Reference start.
191 Rv No No Return values (sections two and three
192 only).
193 Sc Yes Yes Single close quote.
194 So Yes Yes Single open quote.
195 Sq Yes Yes Single quote.
196 Sm No No Space mode (default is "on")
197 Sx Yes Yes Section Cross Reference.
198 Sy Yes Yes Symbolic (traditional English).
199 Tn Yes Yes Trade or type name (small Caps).
200 Ux Yes Yes UNIX
201 Xc Yes Yes Extend argument list close.
202 Xo Yes Yes Extend argument list open.
203 Macro names ending in ‘q’ quote remaining items on the argument list.
205 Macro names ending in ‘o’ begin a quote which may span more than one line
206 of input and are close quoted with the matching macro name ending in ‘c’.
207 Enclosure macros may be nested and are limited to eight arguments.
208 Note: the extended argument list macros (‘.Xo’, ‘.Xc’) and the function
210 enclosure macros (‘.Fo’, ‘.Fc’) are irregular. The extended list macros
211 are used when the number of macro arguments would exceed the troff limi‐
212 tation of nine arguments.
213 The macros UR (starting a URI/URL hypertext reference), UE (ending one),
215 and UN (identifying a target for a reference) are also available. See
216 man(7) for more information on these macros.
217
219 doc.tmac Manual and general text domain macros.
220 tmac/doc-common Common structural macros and definitions.
221 tmac/doc-nroff Site dependent nroff style file.
222 tmac/doc-ditroff Site dependent troff style file.
223 tmac/doc-syms Special defines (such as the standards macro).
224
226 groff_mdoc(7), man(7), man-pages(7), mdoc.samples(7)
227
229 This page is part of release 4.16 of the Linux man-pages project. A
230 description of the project, information about reporting bugs, and the
231 latest version of this page, can be found at
232 https://www.kernel.org/doc/man-pages/.
233Linux July 11, 1999 Linux