| blob | c3224aebebfa971a2119a3a3f6b9b2295c0e949e |
1 .\" $NetBSD: mdoc.7,v 1.28 2003/08/07 10:31:20 agc Exp $
2 .\"
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93
31 .\"
32 .Dd April 16, 2003
33 .Os
34 .Dt MDOC 7
35 .Sh NAME
36 .Nm mdoc
37 .Nd quick reference guide for the
38 .Nm \-mdoc
39 macro package
40 .Sh SYNOPSIS
41 .Nm groff
42 .Fl m Ns Ar doc
43 .Ar files ...
44 .Sh DESCRIPTION
45 The
46 .Nm \-mdoc
47 package is a set of content-based and domain-based macros
48 used to format the
49 .Bx
50 man pages.
51 The macro names and their meanings are
52 listed below for quick reference; for
53 a detailed explanation on using the package,
54 see the tutorial sampler
55 .Xr mdoc.samples 7 .
56 .Pp
57 The macros are described in two groups, the first
58 includes the structural and physical page layout macros.
59 The second contains the manual and general text domain
60 macros which differentiate the
61 .Nm -\mdoc
62 package from other
63 .Xr troff 1
64 formatting packages.
65 .Sh PAGE STRUCTURE DOMAIN
66 .Ss Title Macros
67 To create a valid manual page, these three macros, in this order,
68 are required:
69 .Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact
70 .It Li "\&.Dd " Ar "Month day, year"
71 Document date.
72 .It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]"
73 Title, in upper case.
74 .It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]"
75 Operating system
76 .Pq Tn BSD .
77 .El
78 .Ss Page Layout Macros
79 Section headers, paragraph breaks, lists and displays.
80 .Bl -tag -width flag -compact
81 .It Li \&.Sh
82 Section Headers.
83 Valid headers, in the order of presentation:
84 .Bl -tag -width "RETURN VALUES" -compact
85 .It Ar NAME
86 Name section, should include the
87 .Ql \&.Nm
88 or
89 .Ql \&.Fn
90 and the
91 .Ql \&.Nd
92 macros.
93 .It Ar LIBRARY
94 Sections two and three function calls.
95 .It Ar SYNOPSIS
96 Usage.
97 .It Ar DESCRIPTION
98 General description, should include
99 options and parameters.
100 .It Ar EXIT STATUS
101 Sections one and eight commands and utilities.
102 .It Ar RETURN VALUES
103 Sections two and three function calls.
104 .It Ar ENVIRONMENT
105 Describe environment variables.
106 .It Ar FILES
107 Files associated with the subject.
108 .It Ar EXAMPLES
109 Examples and suggestions.
110 .It Ar DIAGNOSTICS
111 Normally used for section four device interface diagnostics.
112 .It Ar ERRORS
113 Sections two and three error and signal
114 handling.
115 .It Ar SEE ALSO
116 Cross references and citations.
117 .It Ar STANDARDS
118 Conformance to standards if applicable.
119 .It Ar HISTORY
120 If a standard is not applicable, the history
121 of the subject should be given.
122 .It Ar BUGS
123 Gotchas and caveats.
124 .It Ar SECURITY CONSIDERATIONS
125 Security issues to be aware of.
126 .It Ar other
127 Customized headers may be added at
128 the author's discretion.
129 .El
130 .It Li \&.Ss
131 Subsection Headers.
132 .It Li \&.Pp
133 Paragraph Break.
134 Vertical space (one line).
135 .It Li \&.D1
136 (D-one) Display-one
137 Indent and display one text line.
138 .It Li \&.Dl
139 (D-ell) Display-one literal.
140 Indent and display one line of literal text.
141 .It Li \&.Bd
142 Begin-display block.
143 Display options:
144 .Bl -tag -width "xoffset string " -compact
145 .It Fl ragged
146 Unjustified (ragged edges).
147 .It Fl filled
148 Filled, and if
149 .Xr troff 1 ,
150 also justified.
151 .It Fl unfilled
152 Unfilled, unjustified.
153 .It Fl literal
154 Literal text or code.
155 .It Fl file Ar name
156 Read in named
157 .Ar file
158 and display.
159 .It Fl offset Ar string
160 Offset display.
161 Acceptable
162 .Ar string
163 values:
164 .Bl -tag -width indent-two -compact
165 .It Ar left
166 Align block on left (default).
167 .It Ar center
168 Approximate center margin.
169 .It Ar indent
170 Six constant width spaces (a tab).
171 .It Ar indent-two
172 Two tabs.
173 .It Ar right
174 Left aligns block 2 inches from
175 right.
176 .It Ar xx Ns Cm n
177 Where
178 .Ar xx
179 is a number from
180 .No \&4 Ns Cm n
181 to
182 .No \&9\&9 Ns Cm n .
183 .It Ar Aa
184 Where
185 .Ar Aa
186 is a callable macro name.
187 .It Ar string
188 The width of
189 .Ar string
190 is used.
191 .El
192 .El
193 .It Li \&.Ed
194 End-display (matches \&.Bd).
195 .It Li \&.Bl
196 Begin-list.
197 Create lists or columns.
198 Options:
199 .Bl -tag -width flag -compact
200 .It Em List-types
201 .Bl -column "xbullet " -compact
202 .It Fl bullet Ta "Bullet Item List"
203 .It Fl dash Ta "Dash Item List"
204 .It Fl hyphen Ta "(as per" Fl dash ")"
205 .It Fl item Ta "Unlabeled List"
206 .It Fl enum Ta "Enumerated List"
207 .It Fl tag Ta "Tag Labeled List"
208 .It Fl diag Ta "Diagnostic List"
209 .It Fl hang Ta "Hanging Labeled List"
210 .It Fl ohang Ta "Overhanging Labeled List"
211 .It Fl inset Ta "Inset or Run-on Labeled List"
212 .It Fl column Ta "Multiple Columns"
213 .El
214 .It Em List-parameters
215 .Bl -tag -width "xcompact " -compact
216 .It Fl offset
217 (All lists.) See
218 .Ql \&.Bd
219 begin-display above.
220 .It Fl width
221 .Pf ( Fl tag
222 and
223 .Fl hang
224 lists only.)
225 See
226 .Ql \&.Bd .
227 This parameter is effectively required for
228 .Fl tag
229 lists.
230 .It Fl compact
231 (All lists.)
232 Suppresses blank lines.
233 .El
234 .El
235 .It Li \&.El
236 End-list.
237 .It Li \&.It
238 List item.
239 .El
240 .Sh MANUAL AND GENERAL TEXT DOMAIN MACROS
241 The manual and general text domain macros are special in that
242 most of them are parsed for callable macros
243 for example:
244 .Bd -unfilled -offset indent
245 .Li "\&.Op Fl s Ar file"
246 .Ed
247 .Pp
248 Produces:
249 .Bd -unfilled -offset indent
250 .Op Fl s Ar file
251 .Ed
252 .Pp
253 In this example, the option enclosure macro
254 .Ql \&.Op
255 is parsed, and calls the callable content macro
256 .Ql \&Fl
257 which operates on the argument
258 .Ql s
259 and then calls the callable content macro
260 .Ql \&Ar
261 which operates on the argument
262 .Ql file .
263 Some macros may be callable, but are not parsed and vice versa.
264 These macros are indicated in the
265 .Em parsed
266 and
267 .Em callable
268 columns below.
269 .Pp
270 Unless stated, manual domain macros share a common syntax:
271 .Pp
272 .Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ]
273 .Pp
274 .Sy Note :
275 Opening and closing
276 punctuation characters are only recognized as such if they are presented
277 one at a time.
278 The string
279 .Ql "),"
280 is not recognized as punctuation and will be output with a leading white
281 space and in whatever font the calling macro uses.
282 The
283 argument list
284 .Ql "] ) ,"
285 is recognized as three sequential closing punctuation characters
286 and a leading white space is not output between the characters
287 and the previous argument (if any).
288 .Pp
289 The special meaning of a punctuation character may be escaped
290 with the string
291 .Ql \e\*[Am] .
292 For example the following string:
293 .Bd -unfilled -offset indent
294 .Li "\&.Ar file1\ \e\*[Am], file2\ , file3\ )\ ."
295 .Ed
296 .Pp
297 Produces:
298 .Bd -unfilled -offset indent
299 .Ar file1 \&, file2 , file3 ) .
300 .Ed
301 .ne 1i
302 .Ss Manual Domain Macros
303 .Bl -column "Name" "Parsed" "Callable" -compact
304 .It Em Name Parsed Callable Description
305 .It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)"
306 .It Li \&Ar Ta Yes Ta Yes Ta "Command line argument."
307 .It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)."
308 .It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier."
309 .It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)."
310 .It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)."
311 .It Li \&Ev Ta Yes Ta Yes Ta "Environment variable."
312 .It Li \&Fa Ta Yes Ta Yes Ta "Function argument."
313 .It Li \&Fd Ta \&No Ta \&No Ta "Function declaration."
314 .It Li \&Fl Ta Yes Ta Yes Ta "Command line flag."
315 .It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)."
316 .It Li \&Ft Ta Yes Ta Yes Ta "Function type."
317 .It Li \&Ic Ta Yes Ta Yes Ta "Interactive command."
318 .It Li \&In Ta \&No Ta \&No Ta "Include header."
319 .It Li \&Lb Ta Yes Ta Yes Ta "Library name."
320 .It Li \&Li Ta Yes Ta Yes Ta "Literal text."
321 .It Li \&Nd Ta \&No Ta \&No Ta "Name description."
322 .It Li \&Nm Ta Yes Ta Yes Ta "Command name."
323 .It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)."
324 .It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)."
325 .It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name."
326 .It Li \&St Ta Yes Ta Yes Ta "Standards (-p1003.2, -p1003.1 or -ansiC)"
327 .It Li \&Va Ta Yes Ta Yes Ta "Variable name."
328 .It Li \&Vt Ta Yes Ta Yes Ta "Variable type."
329 .It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference."
330 .El
331 .Ss General Text Domain Macros
332 .Bl -column "Name" "Parsed" "Callable" -compact
333 .It Em "Name Parsed Callable Description"
334 .It Li \&%A Ta Yes Ta \&No Ta "Reference author."
335 .It Li \&%B Ta Yes Ta Yes Ta "Reference book title."
336 .It Li \&%\&C Ta \&No Ta \&No Ta "Reference place of publishing (city)."
337 .It Li \&%\&D Ta \&No Ta \&No Ta "Reference date."
338 .It Li \&%J Ta Yes Ta Yes Ta "Reference journal title."
339 .It Li \&%N Ta \&No Ta \&No Ta "Reference issue number."
340 .It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information."
341 .It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)."
342 .It Li \&%R Ta \&No Ta \&No Ta "Reference report Name."
343 .It Li \&%T Ta Yes Ta Yes Ta "Reference article title."
344 .It Li \&%V Ta \&No Ta \&No Ta "Reference volume."
345 .It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote."
346 .It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote."
347 .It Li \&Ap Ta Yes Ta Yes Ta "Insert apostrophe; switch to .No mode "
348 .It Li \&Aq Ta Yes Ta Yes Ta "Angle quote."
349 .It Li \&At Ta \&No Ta \&No Ta Tn "AT\*[Am]T UNIX."
350 .It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote."
351 .It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode."
352 .It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote."
353 .It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote."
354 .It Li \&Bsx Ta Yes Ta Yes Ta "BSD/OS."
355 .It Li \&Bx Ta Yes Ta Yes Ta "BSD" .
356 .It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)."
357 .It Li \&Dc Ta Yes Ta Yes Ta "Double close quote."
358 .It Li \&Do Ta Yes Ta Yes Ta "Double open quote."
359 .It Li \&Dq Ta Yes Ta Yes Ta "Double quote."
360 .It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote."
361 .It Li \&Ef Ta \&No Ta \&No Ta "End font mode."
362 .It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)."
363 .It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote."
364 .It Li \&Fx Ta Yes Ta Yes Ta "FreeBSD."
365 .It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)."
366 .It Li \&Ns Ta Yes Ta Yes Ta "No space."
367 .It Li \&Nx Ta Yes Ta Yes Ta "NetBSD."
368 .It Li \&Ox Ta Yes Ta Yes Ta "OpenBSD."
369 .It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote."
370 .It Li \&Pf Ta Yes Ta \&No Ta "Prefix string."
371 .It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote."
372 .It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote."
373 .It Li \&Qc Ta Yes Ta Yes Ta "Straight Double close quote."
374 .It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal."
375 .It Li \&Qo Ta Yes Ta Yes Ta "Straight Double open quote."
376 .It Li \&Qq Ta Yes Ta Yes Ta "Straight Double quote."
377 .It Li \&Re Ta \&No Ta \&No Ta "Reference end."
378 .It Li \&Rs Ta \&No Ta \&No Ta "Reference start."
379 .It Li \&Sc Ta Yes Ta Yes Ta "Single close quote."
380 .It Li \&So Ta Yes Ta Yes Ta "Single open quote."
381 .It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)."
382 .It Li \&Sq Ta Yes Ta Yes Ta "Single quote."
383 .It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference."
384 .It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)."
385 .It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)."
386 .It Li \&Ux Ta Yes Ta Yes Ta "UNIX."
387 .It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close."
388 .It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open."
389 .El
390 .\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header"
391 .Pp
392 Macro names ending in
393 .Ql q
394 quote remaining items on the argument list.
395 Macro names ending in
396 .Ql o
397 begin a quote which may span more than one line of input and
398 are close quoted with the matching macro name ending in
399 .Ql c .
400 Enclosure macros may be nested and are limited to
401 eight arguments.
402 .Pp
403 Note: the extended argument list macros
404 .Pf ( Ql \&.Xo ,
405 .Ql \&.Xc )
406 and the function enclosure macros
407 .Pf ( Ql \&.Fo ,
408 .Ql \&.Fc )
409 are irregular.
410 The extended list macros are used when the number of macro arguments
411 would exceed the
412 .Xr troff 1
413 limitation of nine arguments.
414 .\" .Sh CONFIGURATION
415 .\" For site specific configuration of the macro package,
416 .\" see the file
417 .\" .Pa /usr/src/share/tmac/README .
418 .Sh FILES
419 .Bl -tag -width "tmac.doc-ditroff" -compact
420 .It Pa tmac.doc
421 Manual and general text domain macros.
422 .It Pa tmac.doc-common
423 Common structural macros and definitions.
424 .It Pa tmac.doc-nroff
425 Site dependent
426 .Xr nroff 1
427 style file.
428 .It Pa tmac.doc-ditroff
429 Site dependent
430 .Xr troff 1
431 style file.
432 .It Pa tmac.doc-syms
433 Special defines (such as the standards macro).
434 .El
435 .Sh SEE ALSO
436 .Xr mdoc.samples 7