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