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