Penguin
Recent Changes
Annotated edit history of mdoc(7) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ----
2 __NAME__
3
4
5 mdoc - quick reference guide for the -mdoc macro
6 package
7 __SYNOPSIS__
8
9
10 groff -mdoc files ...
11 __DESCRIPTION__
12
13
14 The -mdoc package is a set of content-based and domain-based
15 macros used to format the BSD man pages. The
16 macro names and their meanings are listed below for quick
17 reference; for a detailed explanation on using the package,
18 see the tuto- rial sampler
19 mdoc.samples(7).
20
21
22 Note that this is not the usual macro package for Linux doc- umentation, although it is used for documentation of several widely-used programs; see man(7).
23
24
25 The macros are described in two groups, the first includes
26 the structural and physical page layout macros. The second
27 contains the manual and general text domain macros which
28 differentiate the -mdoc package from other troff
29 formatting packages.
30 __PAGE STRUCTURE DOMAIN__
31
32
33 __Title Macros__
34
35
36 To create a valid manual page, these three macros, in this
37 order, are required:
38 .Dd
39 Month day, year Document
40 date.
41
42
43 .Dt DOCUMENT_TITLE [[section] [[volume]
44 Title, in upper case.
45 .Os OPERATING_SYSTEM [[version/release]
46 Operating system ( BSD ).
47
48
49 __Page Layout Macros__
50 Section headers, paragraph breaks, lists and displays.
51 .Sh
52 Section Headers. Valid headers, in the order of pre- sentation:
53 NAME Name section, should include the .Nm or .Fn and the .Nd macros.
54 SYNOPSIS
55 Usage.
56 DESCRIPTION
57 General description, should include options and parameters.
58 RETURN VALUES
59 Sections two and three function calls.
60 ENVIRONMENT
61 Describe environment variables.
62 FILES
63 Files associated with the subject.
64 EXAMPLES
65 Examples and suggestions.
66 DIAGNOSTICS
67 Normally used for section four device interface diagnostics.
68 ERRORS
69 Sections two and three error and signal handling.
70 SEE ALSO
71 Cross references and citations.
72 CONFORMING TO
73 Conformance to standards if applicable.
74 HISTORY
75 If a standard is not applicable, the his- tory of the subject should be given.
76 BUGS
77 Gotchas and caveats.
78 other
79 Customized headers may be added at the authors discretion.
80 .Ss
81 Subsection Headers.
82 .Pp
83 Paragraph Break. Vertical space (one line).
84 .D1
85 (D-one) Display-one Indent and display one text line.
86 .Dl
87 (D-ell) Display-one literal. Indent and display one line of literal text.
88 .Bd
89 Begin-display block. Display options:
90 -ragged Unjustified (ragged edges).
91 -filled
92 Justified.
93 -literal
94 Literal text or code.
95 -file name
96 Read in named file and display.
97 -offset string
98 Offset display. Acceptable string val- ues:
99 left
100 Align block on left (default).
101 center
102 Approximate center margin.
103 indent
104 Six constant width spaces (a tab).
105 indent-two
106 Two tabs.
107 right
108 Left aligns block 2 inches from right.
109 xxn
110 Where xx is a number from 4n to 99n.
111 Aa
112 Where Aa is a callable macro name.
113 string
114 The width of string is used.
115 .Ed
116 End-display (matches .Bd).
117 .Bl
118 Begin-list. Create lists or columns. Options:
119 List-types
120
121
122 -bullet Bullet Item List
123
124
125 -item Unlabeled List
126
127
128 -enum Enumerated List
129
130
131 -tag Tag Labeled List
132
133
134 -diag Diagnostic List
135
136
137 -hang Hanging Labeled List
138
139
140 -ohang Overhanging Labeled List
141
142
143 -inset Inset or Run-on Labeled List
144 List-parameters
145
146
147 -offset(All lists.) See .Bd begin-display above.
148 -width
149 (-tag and -hang lists only.) See .Bd.
150 -compact
151 (All lists.) Suppresses blank lines.
152 .El
153 End-list.
154 .It
155 List item.
156
157
158 __MANUAL AND GENERAL TEXT DOMAIN MACROS__
159
160
161 The manual and general text domain macros are special in
162 that most of them are parsed for callable macros for exam-
163 ple:
164 .Op Fl s Ar file
165
166
167 Produces [[-s file]
168
169
170 In this example, the option enclosure macro .Op is
171 parsed, and calls the callable content macro Fl
172 which operates on the argument s and then calls the
173 callable content macro Ar which operates on the
174 argument file. Some macros may be callable, but are
175 not parsed and vice versa. These macros are indicated in the
176 ''parsed'' and ''callable'' columns
177 below.
178
179
180 Unless stated, manual domain macros share a common
181 syntax:
182
183
184 .Va argument [[ . , ; : ( ) [[ ] argument ...
185 ]
186
187
188 __Note__: Opening and closing punctuation characters are
189 only recognized as such if they are presented one at a time.
190 The string ), is not recognized as punctuation and
191 will be out- put with a leading white space and in what ever
192 font the calling macro uses. The argument list ] )
193 , is recognized as three sequential closing punctuation
194 characters and a leading white space is not output between
195 the characters and the previous argument (if any). The
196 special meaning of a punctuation character may be escaped
197 with the string . For example the following
198 string,
199
200
201 .Ar file1 , file2 , file3 ) .
202 Produces file1, file2, file3).
203
204
205 __Manual Domain Macros__
206
207
208 ''Name Parsed Callable Description''
209
210
211 Ad Yes Yes Address. (This macro may be
212 deprecated.)
213
214
215 An Yes Yes Author name.
216
217
218 Ar Yes Yes Command line argument.
219
220
221 Cd No No Configuration declaration (section four
222 only).
223
224
225 Cm Yes Yes Command line argument
226 modifier.
227
228
229 Dv Yes Yes Defined variable (source
230 code).
231
232
233 Er Yes Yes Error number (source code).
234
235
236 Ev Yes Yes Environment variable.
237
238
239 Fa Yes Yes Function argument.
240
241
242 Fd Yes Yes Function declaration.
243
244
245 Fn Yes Yes Function call (also .Fo and
246 .Fc).
247
248
249 Ic Yes Yes Interactive command.
250
251
252 Li Yes Yes Literal text.
253
254
255 Nm Yes Yes Command name.
256
257
258 Op Yes Yes Option (also .Oo and .Oc).
259
260
261 Ot Yes Yes Old style function type (Fortran
262 only).
263
264
265 Pa Yes Yes Pathname or file name.
266
267
268 St Yes Yes Standards (-p1003.2, -p1003.1 or
269 -ansiC)
270
271
272 Va Yes Yes Variable name.
273
274
275 Vt Yes Yes Variable type (Fortran
276 only).
277
278
279 Xr Yes Yes Manual Page Cross
280 Reference.
281
282
283 __General Text Domain Macros__
284
285
286 ''Name Parsed Callable Description''
287 %A Yes No Reference author.
288 %B Yes Yes Reference book title.
289 %C No No Reference place of publishing (city).
290 %D No No Reference date.
291 %J Yes Yes Reference journal title.
292 %N No No Reference issue number.
293 %O No No Reference optional information.
294 %P No No Reference page number(s).
295 %R No No Reference report Name.
296 %T Yes Yes Reference article title.
297 %V No No Reference volume.
298 Ac Yes Yes Angle close quote.
299 Ao Yes Yes Angle open quote.
300 Ap Yes Yes Apostrophe.
301 Aq Yes Yes Angle quote.
302 At No No AT
303 Bc Yes Yes Bracket close quote.
304 Bf No No Begin font mode.
305 Bo Yes Yes Bracket open quote.
306 Bq Yes Yes Bracket quote.
307 Bx Yes Yes BSD .
308 Db No No Debug (default is off)
309 Dc Yes Yes Double close quote.
310 Do Yes Yes Double open quote.
311 Dq Yes Yes Double quote.
312 Ec Yes Yes Enclose string close quote.
313 Ef No No End font mode.
314 Em Yes Yes Emphasis (traditional English).
315 Eo Yes Yes Enclose string open quote.
316 Fx No No FreeBSD operating
317 system
318 No Yes Yes Normal text (no-op).
319 Ns Yes Yes No space.
320 Pc Yes Yes Parenthesis close quote.
321 Pf Yes No Prefix string.
322 Po Yes Yes Parenthesis open quote.
323 Pq Yes Yes Parentheses quote.
324 Qc Yes Yes Straight Double close quote.
325 Ql Yes Yes Quoted literal.
326 Qo Yes Yes Straight Double open quote.
327 Qq Yes Yes Straight Double quote.
328 Re No No Reference end.
329 Rs No No Reference start.
330 Rv No No Return values (sections two and three
331 only).
332 Sc Yes Yes Single close quote.
333 So Yes Yes Single open quote.
334 Sq Yes Yes Single quote.
335 Sm No No Space mode (default is on)
336 Sx Yes Yes Section Cross Reference.
337 Sy Yes Yes Symbolic (traditional English).
338 Tn Yes Yes Trade or type name (small Caps).
339 Ux Yes Yes UNIX
340 Xc Yes Yes Extend argument list close.
341 Xo Yes Yes Extend argument list open.
342
343
344 Macro names ending in q quote remaining items on
345 the argu- ment list. Macro names ending in o begin
346 a quote which may span more than one line of input and are
347 close quoted with the matching macro name ending in
348 c. Enclosure macros may be nested and are limited
349 to eight arguments.
350
351
352 Note: the extended argument list macros (.Xo,
353 .Xc) and the function enclosure macros
354 (.Fo, .Fc) are irregular. The extended
355 list macros are used when the number of macro argu- ments
356 would exceed the troff limitation of nine
357 arguments.
358
359
360 The macros UR (starting a URI/URL hypertext reference), UE
361 (ending one), and UN (identifying a target for a reference)
362 are also available. See man(7) for more information
363 on these macros.
364 __CONFIGURATION__
365
366
367 For site specific configuration of the macro package, see
368 the file /usr/src/share/tmac/README.
369 __FILES__
370 tmac.doc
371 Manual and general text domain
372 macros.
373
374
375 tmac.doc-common
376 Common structural macros and definitions.
377 tmac.doc-nroff
378 Site dependent nroff style file.
379 tmac.doc-ditroff
380 Site dependent troff style file.
381 tmac.doc-syms
382 Special defines (such as the standards macro).
383
384
385 __SEE ALSO__
386
387
388 mdoc.samples(7), man(7)
389
390
391 Linux July 11, 1999 1
392 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.