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