Commit | Line | Data |
---|---|---|
3e2f4ebf CL |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
af4627c4 | 4 | .\" %sccs.include.redist.roff% |
3e2f4ebf | 5 | .\" |
c9a5c681 | 6 | .\" @(#)mdoc.samples.7 5.6 (Berkeley) %G% |
3e2f4ebf CL |
7 | .\" |
8 | .\" This sampler invokes every macro in the package several | |
9 | .\" times and is garanteed to give a worst case performance | |
c5174ad4 | 10 | .\" for an already extremely slow package. |
3e2f4ebf CL |
11 | .Dd |
12 | .Os BSD 4.4 | |
13 | .Dt MDOC.SAMPLES 7 | |
14 | .Sh NAME | |
15 | .Nm mdoc.sample | |
c5174ad4 | 16 | .Nd writing manual pages with |
3e2f4ebf CL |
17 | .Nm -mdoc |
18 | macro package | |
19 | .Sh SYNOPSIS | |
20 | .Nm man mdoc.sample | |
21 | .Sh DESCRIPTION | |
c5174ad4 CL |
22 | A tutorial sampler for writing |
23 | .Bx | |
24 | manual pages with the | |
25 | .Nm \-mdoc | |
c9a5c681 CL |
26 | macro package, a |
27 | .Em content Ns \-based | |
28 | formatting | |
c5174ad4 CL |
29 | package for |
30 | .Xr troff 1 . | |
31 | Its predecessor, the | |
32 | .Xr \-man 7 | |
33 | package, | |
34 | addressed page structure leaving the | |
35 | manipulation of fonts and other | |
36 | typesetting details to the individual author. | |
37 | The | |
3e2f4ebf | 38 | .Nm \-mdoc |
c5174ad4 CL |
39 | package |
40 | allows the author to ignore font considerations by | |
41 | using macros to label | |
42 | pieces of text according to content. | |
43 | In the context of manual pages, examples of content | |
44 | are a command name, a file pathname or a cross | |
45 | reference to another manual page; these | |
46 | items have value | |
47 | for both the author and the future user of the manual page. | |
48 | It is hoped the consistency gained | |
49 | across the manual set will provide easier | |
50 | translation to future documentation tools. | |
51 | .Pp | |
52 | Through out the | |
53 | .Ux | |
54 | manual pages, a manual entry | |
55 | is simply referred | |
56 | to as a man page, regardless of actual length and without | |
57 | sexist intention. | |
3e2f4ebf | 58 | .Sh TROFF IDIOSYNCRASIES |
c5174ad4 CL |
59 | The |
60 | .Nm \-mdoc | |
61 | package attempts to simplify the process of writing a man page. | |
62 | Theoretically, one should not have to learn the dirty details of | |
3e2f4ebf | 63 | .Xr troff 1 |
c5174ad4 CL |
64 | to use |
65 | .Nm \-mdoc ; | |
66 | however, there are a few | |
3e2f4ebf | 67 | limitations which are unavoidable and best gotten out |
c5174ad4 CL |
68 | of the way. And, too, be forewarned, this package is |
69 | .Em not | |
70 | fast. | |
3e2f4ebf CL |
71 | .Ss Macro Usage |
72 | As in | |
73 | .Xr troff 1 , | |
c5174ad4 CL |
74 | a macro is called by placing a |
75 | .Ql \&\. | |
3e2f4ebf CL |
76 | (dot character) |
77 | at the beginning of | |
78 | a line followed by the two character name for the macro. | |
c5174ad4 | 79 | Arguments may follow the macro separated by spaces. |
3e2f4ebf CL |
80 | It is the dot character at the beginning of the line which causes |
81 | .Xr troff 1 | |
c5174ad4 | 82 | to interpret the next two characters as a macro name. |
3e2f4ebf | 83 | To place a |
c5174ad4 | 84 | .Ql \&\. |
3e2f4ebf CL |
85 | (dot character) |
86 | at the beginning of a line in some context other than | |
c5174ad4 CL |
87 | a macro macro, precede the |
88 | .Ql \&\. | |
3e2f4ebf | 89 | (dot) with a |
c5174ad4 CL |
90 | .Ql \e& . |
91 | .Pp | |
92 | In general, | |
93 | .Xr troff 1 | |
94 | macros accept up to nine arguments, any | |
95 | extra arguments are ignored. | |
96 | Most macros in | |
97 | .Nm \-mdoc | |
98 | accept nine arguments and, | |
99 | in limited cases, arguments may be continued or extended | |
100 | on the | |
101 | next line (See | |
102 | .Sx Extensions | |
103 | \- | |
104 | macro | |
105 | .Ql \&.Xo | |
106 | and | |
107 | .Ql \&.Xc ) . | |
108 | A few macros handle quoted aguments (see | |
109 | .Sx Passing Space Characters in an Argument | |
110 | below). | |
111 | Many | |
112 | .Nm \-mdoc | |
113 | macros may be given the | |
3e2f4ebf CL |
114 | name of another macro as an argument. In this case |
115 | the argument, although the name of a macro, | |
116 | is not preceded by a | |
c5174ad4 | 117 | .Ql \&\. |
3e2f4ebf | 118 | (dot), |
c5174ad4 CL |
119 | and is |
120 | .Em called | |
121 | when the argument is processed. | |
122 | It is in this manner that some macros are nested; for | |
123 | example | |
124 | the option macro, | |
125 | .Ql \&.Op , | |
126 | may | |
3e2f4ebf | 127 | .Em call |
c5174ad4 CL |
128 | the flag and argument macros, |
129 | .Ql \&.Fl | |
130 | and | |
131 | .Ql \&.Ar , | |
132 | to specify an optional flag with an argument: | |
133 | .nr D 1 | |
134 | .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent | |
135 | .It Op Fl s Ar bytes | |
3e2f4ebf | 136 | is produced by |
c5174ad4 CL |
137 | .Li \&.Op \&Fl s \&Ar bytes |
138 | .El | |
139 | .Pp | |
140 | To prevent a two character | |
141 | string from being interpreted as a macro name, precede | |
142 | the string with the | |
143 | escape sequence | |
144 | .Ql \e& : | |
145 | .Bl -tag -width "[\&Fl s \&Ar bytes]" -offset indent | |
146 | .It Op \&Fl s \&Ar bytes | |
147 | is produced by | |
148 | .Li \&.Op \e&Fl s \e&Ar bytes | |
149 | .El | |
3e2f4ebf | 150 | .Pp |
c5174ad4 CL |
151 | .nr D 0 |
152 | Here the strings | |
153 | .Ql \&Fl | |
154 | and | |
155 | .Ql \&Ar | |
156 | were not interpreted as macros. | |
157 | Details on callable macros are presented in the | |
158 | sections | |
159 | .Sx CONTENT MACROS | |
160 | and | |
161 | .Sx PAGE LAYOUT MACROS. | |
3e2f4ebf | 162 | .Ss Passing Space Characters in an Argument |
c5174ad4 CL |
163 | Sometimes it is desirable to give as one argument a string |
164 | containing one or more blank space characters. This may be necessary | |
165 | to defeat the nine argument limit or to specify arguments to macros | |
166 | which expect particular arrangement of items in the argument list. | |
167 | For example, | |
168 | the function macro | |
169 | .Ql \&.Fn | |
170 | expects the first argument to be the name of a function and any | |
171 | remaining arguments to be function parameters. As | |
172 | .Tn "ANSI C" | |
173 | stipulates the declaration of function parameters in the | |
174 | parenthesized parameter list, each parameter is guaranteed | |
175 | to be at minimum a two word string. For example, | |
176 | .Fa int foo . | |
177 | There are two possible ways to pass an argument which contains | |
178 | an imbedded space. Unfortunately, the most convient way | |
179 | of passing such a space between quotes was too expensive to implement for | |
180 | all the macros. It is however, implemented for the following macros which need | |
181 | it the most: | |
182 | .Pp | |
183 | .Bl -tag -width 4n -offset indent -compact | |
184 | .It Li \&Cd | |
185 | Configuration declaration (section 4 SYNOPSIS) | |
186 | .It Li \&Bl | |
187 | Begin list (for the width specifier). | |
188 | .It Li \&Em | |
189 | Emphasized text. | |
190 | .It Li \&Fn | |
191 | Functions (sections two and four). | |
192 | .It Li \&It | |
193 | List items. | |
194 | .It Li \&Li | |
195 | Literal text. | |
196 | .It Li \&Sy | |
197 | Symbolic text. | |
198 | .It Li \&%B | |
199 | Book titles. | |
200 | .It Li \&%J | |
201 | Journal names. | |
202 | .It Li \&%O | |
203 | Optional notes for a reference. | |
204 | .It Li \&%R | |
205 | Report title (in a reference). | |
206 | .It Li \&%T | |
207 | Title of article in a book or journal. | |
208 | .El | |
209 | .Pp | |
210 | One way of passing a string | |
211 | containing blank spaces is to use the hard or unpaddable space character | |
212 | .Ql \e\ , | |
213 | that is, a blank space preceeded by the escape character | |
214 | .Ql \e . | |
215 | This method may be used with any macro but has the side effect | |
216 | of interfering with the adjustment of text | |
217 | over the length of a line. | |
218 | .Xr Troff | |
219 | sees the hard space as if it were any other printable character and | |
220 | cannot split the string into blank or newline separated pieces as one | |
221 | would expect. The method is useful for strings which are not expected | |
222 | to overlap a line boundary. For example: | |
223 | .Bl -tag -width "fetch(char *str)" -offset indent | |
224 | .It Fn fetch char\ *str | |
3e2f4ebf | 225 | is created by |
c5174ad4 CL |
226 | .Ql \&.Fn fetch char\e *str |
227 | .It Fn fetch "char *str" | |
228 | can also be created by | |
229 | .Ql \&.Fn fetch "\\*q*char *str\\*q" | |
230 | .El | |
231 | .Pp | |
232 | If the | |
233 | .Ql \e | |
234 | or quotes | |
235 | were omitted, | |
236 | .Ql \&.Fn | |
237 | would see three arguments and | |
238 | the result would be: | |
239 | .Pp | |
240 | .Dl Fn fetch char *str | |
241 | .Pp | |
c9a5c681 CL |
242 | For an example of what happens when the parameter list overlaps |
243 | a newline boundary, see the | |
244 | .Sx BUGS | |
245 | section. | |
246 | .\" Note what happens if the parameter list overlaps a newline | |
247 | .\" boundary. For example, the next two examples are repeated several times | |
248 | .\" to make sure a line boundary is crossed: | |
249 | .\" .Bd -literal | |
250 | .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] | |
251 | .\" .Ed | |
252 | .\" .Pp | |
253 | .\" produces, nudge nudge, | |
254 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , | |
255 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , | |
256 | .\" nudge | |
257 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . | |
258 | .\" .Pp | |
259 | .\" If double quotes are used, for example: | |
260 | .\" .Bd -literal | |
261 | .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q | |
262 | .\" .Ed | |
263 | .\" .Pp | |
264 | .\" produces, nudge nudge, | |
265 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , | |
266 | .\" nudge | |
267 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , | |
268 | .\" nudge | |
269 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . | |
270 | .\" .Pp | |
271 | .\" Not a pretty sight... | |
272 | .\" In a paragraph, a long parameter containing unpaddable spaces as | |
273 | .\" in the former example will cause | |
274 | .\" .Xr troff | |
275 | .\" to break the line and spread | |
276 | .\" the remaining words out. The latter example will adjust nicely to | |
277 | .\" justified margins, but may break in between an argument and its | |
278 | .\" declaration. In | |
279 | .\" .Xr nroff | |
280 | .\" the right margin adjustment is normally ragged and the problem is | |
281 | .\" not as severe. | |
c5174ad4 CL |
282 | .Ss Trailing Blank Space Characters |
283 | .Xr Troff | |
284 | can be confused by blank space characters at the end of a line. It | |
285 | is wise preventative measure to globally remove all blank spaces | |
286 | from <blank-space><end-of-line> character sequences. Should the need | |
287 | arise to force a blank character at the end of a line, | |
288 | it may be forced with an unpaddable space and the | |
289 | .Ql \e& | |
290 | escape character. | |
291 | For example, | |
292 | .Ql string\e\ \e& . | |
3e2f4ebf CL |
293 | .Ss Escaping Special Characters |
294 | Special characters | |
295 | like the newline character | |
c5174ad4 | 296 | .Ql \en , |
3e2f4ebf | 297 | are handled by replacing the |
c5174ad4 | 298 | .Ql \e |
3e2f4ebf | 299 | with |
c5174ad4 | 300 | .Ql \ee |
3e2f4ebf | 301 | (e.g. |
c5174ad4 | 302 | .Ql \een ) |
3e2f4ebf CL |
303 | to preserve |
304 | the backslash. | |
c5174ad4 CL |
305 | .Sh THE ANATOMY OF A MAN PAGE (Getting Started) |
306 | There are three basic groups of macros: specific header macros | |
307 | called only once at the very beginning of | |
308 | each manual page, page layout or structure macros | |
309 | which may be called many times, and content macros which also | |
310 | may be called many times. | |
311 | The body of a man page is easily constructed from a basic | |
312 | template found in the file: | |
313 | .Bd -literal -offset indent | |
314 | \&.\e" /usr/share/misc/man.tempate : | |
315 | \&.\e" The following six lines are required. | |
316 | \&.Dt DOCUMENT_TITLE [section number] [volume] | |
317 | \&.Os OPERATING_SYSTEM [version/release] | |
318 | \&.Dd Month day, year | |
319 | \&.Sh NAME | |
320 | \&.Sh SYNOPSIS | |
321 | \&.Sh DESCRIPTION | |
322 | \&.\e" The following requests should be uncommented and | |
323 | \&.\e" used where appropriate. This next request is | |
324 | \&.\e" for sections 2 and 3 function return values only. | |
325 | \&.\e" .Sh RETURN VALUES | |
326 | \&.\e" This next request is for sections 1, 6, 7 & 8 only | |
327 | \&.\e" .Sh ENVIRONMENT | |
328 | \&.\e" .Sh FILES | |
329 | \&.\e" .Sh EXAMPLES | |
330 | \&.\e" This next request is for sections 1, 6, 7 & 8 only | |
331 | \&.\e" (command return values (to shell) and | |
332 | \&.\e" fprintf/stderr type diagnostics) | |
333 | \&.\e" .Sh DIAGNOSTICS | |
334 | \&.\e" The next request is for sections 2 and 3 error | |
335 | \&.\e" and signal handling only. | |
336 | \&.\e" .Sh ERRORS | |
337 | \&.\e" .Sh SEE ALSO | |
338 | \&.\e" .Sh STANDARDS | |
339 | \&.\e" .Sh HISTORY | |
340 | \&.\e" .Sh AUTHORS | |
341 | \&.\e" .Sh BUGS | |
342 | .Ed | |
343 | .Pp | |
344 | The first items in the template are the macros | |
345 | .Pq Li \&.Dt , \&.Dd , \&.Os ; | |
346 | the document or man page title | |
347 | .Pq Em in upper case , | |
348 | the section of the manual the page | |
349 | belongs to, the (document) date, | |
350 | and the operating system the man page is derived | |
351 | from. These macros identify the page, | |
352 | and are discussed below in | |
353 | .Sx TITLE MACROS . | |
354 | .Pp | |
355 | The remaining items in the template are section headers | |
356 | .Pq Li \&.Sh ; | |
357 | of which NAME, SYNOPSIS and DESCRIPTION | |
358 | are mandatory. The | |
359 | headers are | |
360 | discussed in | |
361 | .Sx PAGE LAYOUT MACROS, | |
362 | after | |
363 | presentation of | |
364 | .Sx CONTENT MACROS . | |
365 | Several content macros are used to demonstrate page layout macros; | |
366 | reading about content macros before page layout macros is | |
367 | recommended. | |
368 | .Sh TITLE MACROS | |
3e2f4ebf CL |
369 | Three header macros designate the document title or manual page title, |
370 | the operating system, | |
c5174ad4 | 371 | and the date of authorship. |
3e2f4ebf CL |
372 | These macros are one called once at the very beginning of the document |
373 | and are used to construct the headers and footers only. | |
c5174ad4 CL |
374 | .Bl -tag -width 6n |
375 | .It Li \&.Dt DOCUMENT_TITLE section# [volume] | |
3e2f4ebf CL |
376 | The document title is the |
377 | subject of the man page and must be in CAPITALS due to troff | |
378 | limitations. | |
c5174ad4 | 379 | The section number may be 1,\ ...,\ 8, |
3e2f4ebf CL |
380 | and if it is specified, |
381 | the volume title may be omitted. | |
382 | A volume title may be arbitrary or one of the following: | |
383 | .\" .Cl | |
384 | .\" USD UNIX User's Supplementary Documents | |
385 | .\" .Cl | |
386 | .\" PS1 UNIX Programmers's Supplementary Documents | |
c5174ad4 CL |
387 | .Pp |
388 | .Bl -column SMM -offset indent -compact | |
389 | .It AMD UNIX Ancestral Manual Documents | |
390 | .It SMM UNIX System Manager's Manual | |
391 | .It URM UNIX Reference Manual | |
392 | .It PRM UNIX Programmers's Manual | |
393 | .El | |
394 | .Pp | |
3e2f4ebf CL |
395 | .\" .Cl |
396 | .\" MMI UNIX Manual Master Index | |
397 | .\" .Cl | |
398 | .\" CON UNIX Contributed Software Manual | |
399 | .\" .Cl | |
400 | .\" LOC UNIX Local Manual | |
c5174ad4 | 401 | .It Li \&.Os operating_system release# |
3e2f4ebf CL |
402 | The name of the operating system |
403 | should be the common acronym, e.g. BSD | |
404 | or ATT. The release should be the standard release | |
c5174ad4 | 405 | nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3, |
3e2f4ebf CL |
406 | V.4. Unrecognized arguments are displayed as given in the page footer. |
407 | For instance, for the footer on this page, the 4.4 Berkeley Distribution | |
408 | was produced by: | |
409 | .Pp | |
c5174ad4 CL |
410 | .Dl \&.Os BSD 4.4 |
411 | .It Li \&.Dd month day, year | |
3e2f4ebf CL |
412 | The date should be written formally: |
413 | .Pp | |
414 | .Dl January 25, 1989 | |
c5174ad4 CL |
415 | .El |
416 | .Sh CONTENT MACROS | |
417 | .Ss What's in a name... | |
418 | Content macro names are derived from the day to day | |
419 | informal language used to describe commands, subroutines and related | |
420 | files. Slightly | |
421 | different variations of this language are used to describe | |
422 | the three different aspects of writing a man page. | |
423 | First, there is the description of | |
424 | .Nm \-mdoc | |
425 | macro request usage. | |
426 | Second is the description of a | |
427 | .Ux | |
428 | command | |
429 | .Em with | |
430 | .Nm \-mdoc | |
431 | macros and third, | |
432 | the | |
433 | description a command to a user in the verbal sense; | |
434 | that is, discussion of a command in the text of a man page. | |
435 | .Pp | |
436 | In the first case, | |
437 | .Xr troff 1 | |
438 | macros are themselves a type of command; | |
439 | the general syntax for a troff command is: | |
440 | .Bd -filled -offset indent | |
441 | \&.Va argument1 argument2 ... argument9 | |
442 | .Ed | |
3e2f4ebf | 443 | .Pp |
c5174ad4 CL |
444 | The |
445 | .Ql \&.Va | |
446 | is a macro command or request, and anything following it is an argument to | |
447 | be processed. | |
448 | In the second case, | |
449 | the description of a | |
450 | .Ux | |
451 | command using the content macros is a | |
452 | bit more involved; | |
453 | a typical SYNOPSIS command line might be displayed as: | |
454 | .Pp | |
455 | .Bd -filled -offset indent | |
456 | .Nm filter | |
457 | .Op Fl flag | |
458 | .Ar infile outfile | |
459 | .Ed | |
460 | .Pp | |
461 | Here, | |
462 | .Nm filter | |
463 | is the command name and the | |
464 | bracketed string | |
465 | .Fl flag | |
466 | is a | |
467 | .Em flag | |
468 | argument designated as optional by the option brackets. | |
469 | In | |
470 | .Nm \-mdoc | |
471 | terms, | |
472 | .Ar infile | |
473 | and | |
474 | .Ar outfile | |
475 | are | |
476 | called | |
477 | .Em arguments . | |
478 | The macros which formatted the above example: | |
479 | .Pp | |
c9a5c681 CL |
480 | .Bd -literal -offset indent |
481 | \&.Nm filter | |
482 | \&.Op \&Fl flag | |
483 | \&.Ar infile outfile | |
c5174ad4 CL |
484 | .Ed |
485 | .Pp | |
486 | In the third case, discussion of commands and command syntax | |
487 | includes both examples above, but may add more detail. The | |
488 | arguments | |
489 | .Ar infile | |
490 | and | |
491 | .Ar outfile | |
492 | from the example above might be refered to as | |
493 | .Em operands | |
494 | or | |
495 | .Em file arguments . | |
496 | Some command line argument lists are quite long: | |
497 | .\" .Bl -tag -width make -offset indent | |
498 | .Bl -tag -width make -offset indent | |
499 | .It Nm make | |
500 | .Op Fl eiknqrstv | |
501 | .Op Fl D Ar variable | |
502 | .Op Fl d Ar flags | |
503 | .Op Fl f Ar makefile | |
504 | .Op Fl I Ar directory | |
505 | .Op Fl j Ar max_jobs | |
506 | .Op Ar variable=value | |
507 | .br | |
508 | .Op Ar "target\ ..." | |
509 | .El | |
510 | .Pp | |
511 | Here one might talk about the command | |
512 | .Nm make | |
513 | and qualify the argument | |
514 | .Ar makefile , | |
515 | as an argument to the flag, | |
516 | .Fl f , | |
517 | or discuss the optional | |
518 | file | |
519 | operand | |
520 | .Ar target . | |
521 | In the verbal context, such detail can prevent confusion, | |
522 | however the | |
523 | .Nm \-mdoc | |
524 | package | |
525 | does not have a macro for an argument | |
526 | .Em to | |
527 | a flag. | |
528 | Instead the | |
529 | .Ql \&Ar | |
530 | argument macro is used for an operand or file argument like | |
531 | .Ar target | |
532 | as well as an argument to a flag like | |
533 | .Ar variable : | |
534 | .Bd -literal -offset indent | |
535 | \&.Nm make | |
536 | \&.Op Fl eiknqrstv | |
537 | \&.Op Fl D Ar variable | |
538 | \&.Op Fl d Ar flags | |
539 | \&.Op Fl f Ar makefile | |
540 | \&.Op Fl I Ar directory | |
541 | \&.Op Fl j Ar max_jobs | |
542 | \&.Op Ar variable=value | |
543 | \&.Op Ar target ... | |
544 | .Ed | |
545 | .Ss General Syntax | |
546 | All content macros share a similar | |
547 | syntax with a few minor deviations: | |
548 | .Ql \&.Ar , | |
549 | .Ql \&.Fl , | |
550 | .Ql \&.Nm , | |
551 | and | |
552 | .Ql \&.Pa | |
553 | differ only when called without arguments; | |
554 | .Ql \&.Fn | |
555 | and | |
556 | .Ql \&.Xr | |
557 | impose an order on their argument lists | |
558 | and the | |
559 | .Em enclosure | |
560 | and | |
561 | .Em quoting | |
562 | macros | |
563 | have nesting limitations. All content macros | |
564 | are capable of handling punctuation. | |
3e2f4ebf CL |
565 | Any argument which may be tested for punctuation |
566 | and contains a member of the mathematical, logical or | |
c5174ad4 CL |
567 | quotation set: |
568 | .Bd -literal -offset indent -compact | |
3e2f4ebf | 569 | {+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"} |
c5174ad4 | 570 | .Ed |
3e2f4ebf | 571 | should have |
c5174ad4 CL |
572 | the character escaped with |
573 | .Ql \e& . | |
574 | Typical syntax is shown in the first content macro displayed | |
575 | below, | |
576 | .Ql \&.Ad , | |
577 | and the syntax for enclosure/quoting macros is shown in | |
578 | .Sx Enclosure and Quoting Macros . | |
579 | .Ss Address Macro | |
580 | The address macro constructs an address | |
3e2f4ebf CL |
581 | of the form addr1[,addr2[,addr3]]. |
582 | .Pp | |
c5174ad4 CL |
583 | .Dl Usage: .Ad address ... \*(Pu |
584 | .Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n | |
585 | .It Li \&.Ad addr1 | |
3e2f4ebf | 586 | .Ad addr1 |
c5174ad4 | 587 | .It Li \&.Ad addr1\ . |
3e2f4ebf | 588 | .Ad addr1 . |
c5174ad4 | 589 | .It Li \&.Ad addr1\ , file2 |
3e2f4ebf | 590 | .Ad addr1 , file2 |
c5174ad4 | 591 | .It Li \&.Ad f1\ , f2\ , f3\ : |
3e2f4ebf | 592 | .Ad f1 , f2 , f3 : |
c5174ad4 | 593 | .It Li \&.Ad addr\ )\ )\ , |
3e2f4ebf | 594 | .Ad addr ) ) , |
c5174ad4 CL |
595 | .El |
596 | .Pp | |
3e2f4ebf CL |
597 | It is an error to call |
598 | .Li \&.Ad | |
599 | without arguments. | |
c5174ad4 CL |
600 | .Li \&.Ad |
601 | is callable by other macros and may call other macros. | |
602 | .Ss Argument Macro | |
3e2f4ebf CL |
603 | The |
604 | .Li \&.Ar | |
c5174ad4 | 605 | argument macro may be used whenever |
3e2f4ebf CL |
606 | a command line argument is referenced. |
607 | .Pp | |
608 | .Dl Usage: .Ar argument ... \*(Pu | |
c5174ad4 CL |
609 | .Bl -tag -width ".Ar file1 file2" -compact -offset 15n |
610 | .It Li \&.Ar | |
3e2f4ebf | 611 | .Ar |
c5174ad4 | 612 | .It Li \&.Ar file1 |
3e2f4ebf | 613 | .Ar file1 |
c5174ad4 | 614 | .It Li \&.Ar file1\ . |
3e2f4ebf | 615 | .Ar file1 . |
c5174ad4 | 616 | .It Li \&.Ar file1 file2 |
3e2f4ebf | 617 | .Ar file1 file2 |
c5174ad4 | 618 | .It Li \&.Ar f1 f2 f3\ : |
3e2f4ebf | 619 | .Ar f1 f2 f3 : |
c5174ad4 | 620 | .It Li \&.Ar file\ )\ )\ , |
3e2f4ebf | 621 | .Ar file ) ) , |
c5174ad4 | 622 | .El |
3e2f4ebf CL |
623 | .Pp |
624 | If | |
625 | .Li \&.Ar | |
c5174ad4 CL |
626 | is called without arguments |
627 | .Ql Ar | |
3e2f4ebf CL |
628 | is assumed. The |
629 | .Li \&.Ar | |
c5174ad4 CL |
630 | macro may call other macros, and may be |
631 | called by other macros. | |
632 | .Ss Angle Bracket Quote/Enclosure | |
633 | Encloses a string or strings in between angle brackets. The macro | |
634 | .Ql \&.Aq | |
635 | encloses the remaining arguments on the macro command line, and the | |
636 | .Ql \&.Ao | |
637 | (angle open) and | |
638 | .Ql \&.Ac | |
639 | (angle close) macros may be used across one or more lines. | |
640 | .Pp | |
641 | .Dl Usage: .Aq string ... \*(Pu | |
642 | .Bl -tag -width ".Aq Pa ctype.h ) ," -compact -offset 14n | |
643 | .It Li \&.Aq | |
644 | .Aq | |
645 | .It Li \&.Aq string. | |
646 | .Aq string. | |
647 | .It Li \&.Aq string\ . | |
648 | .Aq string . | |
649 | .It Li \&.Aq stdio.h | |
650 | .Aq stdio.h | |
651 | .It Li \&.Aq \&Ar ctype.h\ )\ , | |
652 | .Aq Ar ctype.h ) , | |
653 | .El | |
654 | .Pp | |
655 | See | |
656 | .Sx Enclosure Macros | |
657 | for discussion and | |
658 | .Sx Options | |
659 | for examples of the open and close | |
660 | macros | |
661 | .Ql \&.Ac | |
662 | and | |
663 | .Ql \&.Ao . | |
664 | .Ql \&.Aq | |
665 | is callable by other macros and may call other macros. | |
c5174ad4 CL |
666 | .Ss Bracket Quotes/Enclosure |
667 | Bracket quotes should be used when the string being bracketed is | |
668 | .Em not | |
669 | an option string. The brackets for an option may be different | |
670 | than the default brackets. The macro | |
671 | .Ql \&.Bq | |
672 | encloses the remaining arguments on a macro command line and the | |
673 | macros | |
674 | .Ql \&.Bo | |
675 | and | |
676 | .Ql \&.Bc | |
677 | may be used across one or more lines. | |
678 | .Pp | |
679 | .Dl Usage: .Bq string ... \*(Pu | |
680 | .Pp | |
681 | The | |
682 | .Li \&.Bq | |
683 | macro exists for statements which use other macros: | |
684 | .Bq Em Greek , French . | |
685 | This was done with: | |
686 | .Pp | |
687 | .Dl Li \&.Bq \&Em Greek \&, French \&. | |
688 | .Pp | |
689 | It also could have been done using the prefix macro: | |
690 | .Pp | |
691 | .Dl Li ".Pf [ Em Greek , French ] ." | |
692 | .Pp | |
693 | See | |
694 | .Sx Enclosure Macros | |
695 | for discussion and | |
696 | .Sx Options | |
697 | for examples of the open and close | |
698 | macros | |
699 | .Ql \&.Bc | |
700 | and | |
701 | .Ql \&.Bo . | |
702 | The | |
703 | .Ql \&.Bq | |
704 | macro | |
705 | is callable and may call other macros. | |
706 | .Ss Configuration Declaration (section four only) | |
3e2f4ebf | 707 | The |
c5174ad4 CL |
708 | .Ql \&.Cd |
709 | macro is used to demonstrate a | |
710 | .Xr config 8 | |
711 | declaration for a device interface in a section four manual. | |
712 | This macro accepts quoted arguments (double quotes only). | |
713 | .Pp | |
714 | .Bl -tag -width "device le0 at scode?" -offset indent | |
715 | .It Cd "device le0 at scode?" | |
716 | produced by: | |
717 | .Ql ".Cd device le0 at scode?" . | |
718 | .El | |
719 | .Ss Command Modifier | |
720 | The command modifier is identical to the | |
721 | .Ql \&.Fl | |
722 | (flag) command with the exception | |
723 | the | |
724 | .Ql \&.Cm | |
725 | macro does not assert a dash | |
726 | in front of every argument. Traditionally flags are marked by the | |
727 | preceding dash, some commands or subsets of commands do not use them. | |
728 | Command modifiers may also be specified in conjunction with interactive | |
729 | commands such as editor commands. | |
730 | See | |
731 | .Sx Flags . | |
732 | .Ss Double Quote macro/Enclosure | |
733 | The | |
734 | .Ql \&.Dq | |
735 | double quote encloses | |
736 | any remaining strings on the command line with double quotes. | |
737 | Punctuation is | |
738 | placed after the end quote. | |
739 | The macros | |
740 | .Ql \&.Do | |
741 | and | |
742 | .Ql \&.Dc | |
743 | may be used across one or more lines. | |
3e2f4ebf CL |
744 | .Pp |
745 | .Dl Usage: .Dq string ... \*(Pu | |
c5174ad4 CL |
746 | .Bl -tag -width ".Dq Ar patternx ) ) ," -compact -offset 14n |
747 | .It Li \&.Dq | |
3e2f4ebf | 748 | .Dq |
c5174ad4 CL |
749 | .It Li ".Dq string." |
750 | .Dq string. | |
751 | .It Li ".Dq string abc ." | |
752 | .Dq string abc . | |
753 | .It Li ".Dq \'^[A-Z]\'" | |
754 | .Dq \'^[A-Z]\' | |
755 | .It Li \&.Dq \&Ar pattern\ )\ )\ , | |
3e2f4ebf | 756 | .Dq Ar pattern ) ) , |
c5174ad4 | 757 | .El |
3e2f4ebf CL |
758 | .Pp |
759 | If | |
c5174ad4 | 760 | .Ql \&.Dq |
3e2f4ebf CL |
761 | is called with no arguments |
762 | .Dq | |
763 | is assumed. The | |
c5174ad4 CL |
764 | .Ql \&.Dq |
765 | macro may call or be called by | |
766 | other macros. | |
767 | See | |
768 | .Sx Enclosure Macros | |
769 | for discussion of | |
770 | .Ql \&.Dc | |
3e2f4ebf | 771 | and |
c5174ad4 CL |
772 | .Ql \&.Do |
773 | macro types. | |
774 | .Ss Defined Variables | |
775 | A variable which is defined in an include file is specified | |
776 | by the macro | |
777 | .Ql \&.Dv . | |
778 | .Pp | |
779 | .Dl Usage: .Dv defined_variable ... \*(Pu | |
780 | .Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n | |
781 | .It Li ".Dv MAXHOSTNAMELEN" | |
782 | .Dv MAXHOSTNAMELEN | |
783 | .It Li ".Dv TIOCGPGRP )" | |
784 | .Dv TIOCGPGRP ) | |
785 | .El | |
786 | .Pp | |
787 | It is an error to call | |
788 | .Ql \&.Dv | |
789 | without arguments. | |
790 | .Ql \&.Dv | |
791 | may call other macros and | |
792 | may be called by other macros. | |
793 | .Ss Emphasis Macro | |
794 | Text may be stressed or emphasized with the | |
795 | .Ql \&.Em | |
796 | macro. The usual font for emphasis is italic. | |
3e2f4ebf CL |
797 | .Pp |
798 | .Dl Usage: .Em argument ... \*(Pu | |
c5174ad4 CL |
799 | .Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n |
800 | .It Li ".Em does not" | |
3e2f4ebf | 801 | .Em does not |
c5174ad4 | 802 | .It Li ".Em exceed 1024 ." |
3e2f4ebf | 803 | .Em exceed 1024 . |
c5174ad4 | 804 | .It Li ".Em vide infra ) ) ," |
3e2f4ebf | 805 | .Em vide infra ) ) , |
c5174ad4 CL |
806 | .El |
807 | .Pp | |
808 | The emphasis can be forced across several lines of text by using | |
809 | the | |
810 | .Ql \&.Bf | |
811 | macro discussed in | |
812 | .Sx Modes | |
813 | under | |
814 | .Sx PAGE LAYOUT . | |
815 | .\" .Pp | |
816 | .\" .Em | |
817 | .\" I'm certain the reason so many people desire an MBA from Harvard | |
818 | .\" is because they want to be successful philanthropists. | |
819 | .\" .Em | |
3e2f4ebf | 820 | .Pp |
c5174ad4 CL |
821 | The |
822 | .Ql \&.Em | |
823 | macro | |
824 | is callable and may call other macros. | |
3e2f4ebf | 825 | It is an error to call |
c5174ad4 | 826 | .Ql \&.Em |
3e2f4ebf | 827 | without arguments. |
c5174ad4 CL |
828 | .Ss Enclosure and Quoting Macros |
829 | The concept of enclosure is similar to quoting. | |
830 | The object is to enclose a string or more between | |
831 | a pair of characters like quotes or parentheses. | |
832 | The terms quoting and enclosure are used | |
833 | interchangeably throughout this document. Many of the | |
834 | one line enclosure macros end | |
835 | end in small letter | |
836 | .Ql q | |
837 | to give a hint of quoting, but there are a few exceptions | |
838 | (the macros | |
839 | .Ql \&.En , | |
840 | .Ql \&.Fn | |
841 | and | |
842 | .Ql \&.Op | |
843 | are also enclosure macros). | |
844 | For each enclosure macro | |
845 | there is also a pair of open and close macros which end | |
846 | in small letters | |
847 | .Ql o | |
848 | and | |
849 | .Ql c | |
850 | respectively. These can be used across one or more lines of text | |
851 | and while they cannot be nested, the one line quote macros | |
852 | can be used inside | |
853 | of them. | |
854 | For a good example of one these macros, see | |
855 | .Sx Options . | |
856 | .Pp | |
857 | .Bd -filled -offset indent | |
858 | .Bl -column "quote" "close" "open" "Enclose Stringx(in XX)" XXstringXX | |
859 | .Em " quote close open function result" | |
860 | \&.Aq, .Ac, .Ao Angle Bracket Enclosure <string> | |
861 | \&.Bq, .Bc, .Bo Bracket Enclosure [string] | |
862 | \&.Dq, .Dc, .Do Double Quote ``string'' | |
863 | .Ec, .Eo Enclose String (in XX) XXstringXX | |
864 | \&.Fn, .Fc, .Fo Function Enclosure function(string) | |
865 | \&.Op, .Oc, .Oo Option Enclosure [string] | |
866 | \&.Pq, .Pc, .Po Parenthesis Enclosure (string) | |
867 | \&.Qq, .Qc, .Qo Straight Double Quote "string" | |
868 | \&.Sq, .Sc, .So Single Quote `string' | |
869 | \& .Xc, .Xo Extend Argument \ \-\- | |
870 | .El | |
871 | .Ed | |
872 | .Pp | |
873 | The macros | |
874 | .Ql \&.Eo | |
875 | and | |
876 | .Ql \&.Ec | |
877 | allow a user to specify an open and close with the first argument as the | |
878 | opening or closing string respectively. | |
879 | .Ss Errno's (Section two only) | |
3e2f4ebf | 880 | The |
c5174ad4 CL |
881 | .Ql \&.Er |
882 | errno macro specifies the error return value | |
883 | for section two library routines. The second example | |
3e2f4ebf | 884 | below shows |
c5174ad4 | 885 | .Ql \&.Er |
3e2f4ebf | 886 | used with the |
c5174ad4 CL |
887 | .Ql \&.Bq |
888 | macro, as it would be used in | |
889 | a section two manual page. | |
3e2f4ebf CL |
890 | .Pp |
891 | .Dl Usage: .Er ERRNOTYPE ... \*(Pu | |
c5174ad4 CL |
892 | .Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n |
893 | .It Li \&.Er ENOENT | |
3e2f4ebf | 894 | .Er ENOENT |
c5174ad4 CL |
895 | .It Li \&.Er ENOENT\ )\ ; |
896 | .Er ENOENT ) ; | |
897 | .It Li \&.Bq \&Er ENOTDIR | |
898 | .Bq Er ENOTDIR | |
899 | .El | |
3e2f4ebf CL |
900 | .Pp |
901 | It is an error to call | |
c5174ad4 | 902 | .Ql \&.Er |
3e2f4ebf | 903 | without arguments. |
c5174ad4 CL |
904 | The |
905 | .Ql \&.Er | |
906 | macro | |
907 | is callable and may call other macros. | |
3e2f4ebf CL |
908 | .Ss Environment Variables |
909 | The | |
c5174ad4 CL |
910 | .Ql \&.Ev |
911 | macro specifies a environment variable. | |
3e2f4ebf CL |
912 | .Pp |
913 | .Dl Usage: .Ev argument ... \*(Pu | |
c5174ad4 CL |
914 | .Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n |
915 | .It Li \&.Ev DISPLAY | |
3e2f4ebf | 916 | .Ev DISPLAY |
c5174ad4 | 917 | .It Li \&.Ev PATH\ . |
3e2f4ebf | 918 | .Ev PATH . |
c5174ad4 | 919 | .It Li \&.Ev PRINTER\ )\ )\ , |
3e2f4ebf | 920 | .Ev PRINTER ) ) , |
c5174ad4 | 921 | .El |
3e2f4ebf CL |
922 | .Pp |
923 | It is an error to call | |
c5174ad4 | 924 | .Ql \&.Ev |
3e2f4ebf | 925 | without arguments. |
c5174ad4 CL |
926 | The |
927 | .Ql \&.Ev | |
928 | macro | |
929 | is callable by other macros and may call other macros. | |
930 | .Ss Function Argument | |
931 | The | |
932 | .Ql \&.Fa | |
933 | macro is used to refer to function arguments (parameters) | |
934 | outside of the SYNOPSIS section of the manual or inside | |
935 | the SYNOPSIS section should a parameter list be too | |
936 | long for the | |
937 | .Ql \&.Fn | |
938 | macro and the enclosure macros | |
939 | .Ql \&.Fo | |
940 | and | |
941 | .Ql \&.Fc | |
942 | must be used. | |
943 | .Ql \&.Fa | |
944 | may also be used to refer to structure members. | |
945 | .Pp | |
946 | .Dl Usage: .Fa function_argument ... \*(Pu | |
947 | .Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n | |
948 | .It Li \&.Fa d_namlen\ )\ )\ , | |
949 | .Fa d_namlen ) ) , | |
950 | .It Li \&.Fa iov_len | |
951 | .Fa iov_len | |
952 | .El | |
953 | .Pp | |
954 | It is an error to call | |
955 | .Ql \&.Fa | |
956 | without arguments. | |
957 | .Ql \&.Fa | |
958 | is callable by other macros and may call other macros. | |
959 | .Ss Function Declaration | |
960 | The | |
961 | .Ql \&.Fd | |
962 | macro is used in the SYNOPSIS section with section two or three | |
963 | functions. The | |
964 | .Ql \&.Fd | |
965 | macro does not call other macros and is not callable by other | |
966 | macros. | |
967 | .Pp | |
968 | .Dl Usage: .Fd include_file (or defined variable) | |
969 | .Pp | |
970 | In the SYNOPSIS section a | |
971 | .Ql \&.Fd | |
972 | request causes a line break if a function has already been presented | |
973 | and a break has not occurred. This leaves a nice vertical space | |
974 | in between the previous function call and the declaration for the | |
975 | next function. | |
3e2f4ebf CL |
976 | .Ss Flags |
977 | The | |
c5174ad4 CL |
978 | .Ql \&.Fl |
979 | macro handles command line flags. It prepends | |
3e2f4ebf | 980 | a dash, |
c5174ad4 | 981 | .Ql \- , |
3e2f4ebf CL |
982 | to the flag. For interactive command flags, which |
983 | are not prepended with a dash, the | |
c5174ad4 CL |
984 | .Ql \&.Cm |
985 | (command modifier) | |
986 | macro is identical, but with out the dash. | |
3e2f4ebf CL |
987 | .Pp |
988 | .Dl Usage: .Fl argument ... \*(Pu | |
c5174ad4 CL |
989 | .Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n |
990 | .It Li \&.Fl | |
3e2f4ebf | 991 | .Fl |
c5174ad4 | 992 | .It Li \&.Fl cfv |
3e2f4ebf | 993 | .Fl cfv |
c5174ad4 | 994 | .It Li \&.Fl cfv\ . |
3e2f4ebf | 995 | .Fl cfv . |
c5174ad4 | 996 | .It Li \&.Fl s v t |
3e2f4ebf | 997 | .Fl s v t |
c5174ad4 | 998 | .It Li \&.Fl -\ , |
3e2f4ebf | 999 | .Fl - , |
c5174ad4 | 1000 | .It Li \&.Fl xyz\ )\ , |
3e2f4ebf | 1001 | .Fl xyz ) , |
c5174ad4 | 1002 | .El |
3e2f4ebf CL |
1003 | .Pp |
1004 | The | |
c5174ad4 CL |
1005 | .Ql \&.Fl |
1006 | macro without any arguments results | |
1007 | in a dash representing stdin/stdout. | |
3e2f4ebf | 1008 | Note that giving |
c5174ad4 | 1009 | .Ql \&.Fl |
3e2f4ebf | 1010 | a single dash, will result in two dashes. |
c5174ad4 CL |
1011 | The |
1012 | .Ql \&.Fl | |
1013 | macro | |
1014 | is callable and may call other macros. | |
3e2f4ebf | 1015 | .Ss Functions (library routines) |
c5174ad4 CL |
1016 | The .Fn macro is modeled on ANSI C conventions. |
1017 | .Bd -literal | |
1018 | Usage: .Fn [type] function [[type] params ... \*(Pu] | |
1019 | .Ed | |
c9a5c681 | 1020 | .Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact |
c5174ad4 | 1021 | .It Li "\&.Fn getchar" |
3e2f4ebf | 1022 | .Fn getchar |
c5174ad4 | 1023 | .It Li "\&.Fn strlen ) ," |
3e2f4ebf | 1024 | .Fn strlen ) , |
c5174ad4 CL |
1025 | .It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , |
1026 | .Fn "int align" "const * char *sptrs" , | |
1027 | .El | |
3e2f4ebf CL |
1028 | .Pp |
1029 | It is an error to call | |
c5174ad4 | 1030 | .Ql \&.Fn |
3e2f4ebf | 1031 | without any arguments. |
c5174ad4 CL |
1032 | The |
1033 | .Ql \&.Fn | |
1034 | macro | |
1035 | is callable by other macros and may call other macros, but | |
1036 | note that any call to another macro signals the end of | |
1037 | the | |
1038 | .Ql \&.Fn | |
1039 | call (it will close-paren at that point). | |
1040 | .Pp | |
1041 | In the SYNOPSIS section, the function will always begin at | |
1042 | the beginning of line. If there is more than one function | |
1043 | presented in the SYNOPSIS section and a function type has not been | |
1044 | given, a line break will occur, leaving a nice vertical space | |
1045 | between the current function name and the one prior. | |
3e2f4ebf | 1046 | At the moment, |
c5174ad4 | 1047 | .Ql \&.Fn |
3e2f4ebf | 1048 | does not check its word boundaries |
c5174ad4 CL |
1049 | against troff line lengths and may split across a newline |
1050 | ungracefully. This will be fixed in the near future. | |
1051 | .Ss Function Type | |
1052 | This macro is intended for the SYNOPSIS section. It may be used | |
1053 | anywhere else in the manpage without problems, but its main purpose | |
1054 | is to present the function type in kernel normal form for the SYNOPSIS | |
1055 | of sections two and three | |
1056 | (it causes a page break allowing the function name to appear | |
1057 | on the next line). | |
1058 | .Pp | |
1059 | .Dl Usage: .Ft type ... \*(Pu | |
1060 | .Pp | |
1061 | .Bl -tag -width "\&.Ft struct stat" -offset 14n -compact | |
1062 | .It Li \&.Ft struct stat | |
1063 | .Ft struct stat | |
1064 | .El | |
1065 | .Pp | |
3e2f4ebf | 1066 | The |
c5174ad4 CL |
1067 | .Ql \&.Ft |
1068 | request is not callable by other macros. | |
1069 | .Ss Interactive Commands | |
1070 | The | |
1071 | .Ql \&.Ic | |
1072 | macro designates an interactive or internal command. | |
1073 | .Pp | |
1074 | .Dl Usage: .Li argument ... \*(Pu | |
1075 | .Bl -tag -width ".Ic setenv , unsetenv" -compact -offset 14n | |
1076 | .It Li \&.Ic :wq | |
1077 | .Ic :wq | |
1078 | .It Li \&.Ic do while {...} | |
1079 | .Ic do while {...} | |
1080 | .It Li \&.Ic setenv\ , unsetenv | |
1081 | .Ic setenv , unsetenv | |
1082 | .El | |
1083 | .Pp | |
1084 | It is an error to call | |
1085 | .Ql \&.Ic | |
1086 | without arguments. | |
1087 | The | |
1088 | .Ql \&.Ic | |
1089 | macro may call other macros and is callable. | |
3e2f4ebf CL |
1090 | .Ss Literals |
1091 | The | |
c5174ad4 CL |
1092 | .Ql \&.Li |
1093 | literal macro may be used for special characters, | |
3e2f4ebf CL |
1094 | variable constants, anything which should be displayed as it |
1095 | would be typed. | |
1096 | .Pp | |
1097 | .Dl Usage: .Li argument ... \*(Pu | |
c5174ad4 CL |
1098 | .Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n |
1099 | .It Li \&.Li \een | |
3e2f4ebf | 1100 | .Li \en |
c5174ad4 | 1101 | .It Li \&.Li M1 M2 M3\ ; |
3e2f4ebf | 1102 | .Li M1 M2 M3 ; |
c5174ad4 | 1103 | .It Li \&.Li cntrl-D\ )\ , |
3e2f4ebf | 1104 | .Li cntrl-D ) , |
c5174ad4 | 1105 | .It Li \&.Li 1024\ ... |
3e2f4ebf | 1106 | .Li 1024 ... |
c5174ad4 | 1107 | .El |
3e2f4ebf | 1108 | .Pp |
3e2f4ebf | 1109 | The |
c5174ad4 CL |
1110 | .Ql \&.Li |
1111 | macro | |
1112 | is callable by other macros and may call other macros. | |
1113 | .Ss Name Macro | |
1114 | The | |
1115 | .Ql \&.Nm | |
1116 | macro is used for the document title or subject name. | |
1117 | It has the peculiarity of remembering the first | |
3e2f4ebf CL |
1118 | argument it was called with, which should |
1119 | always be the subject name of the page. When called without | |
1120 | arguments, | |
c5174ad4 | 1121 | .Ql \&.Nm |
3e2f4ebf CL |
1122 | regurgitates this initial name for the sole purpose |
1123 | of making less work for the author. | |
c5174ad4 CL |
1124 | Note: |
1125 | a section two | |
3e2f4ebf | 1126 | or three document function name is addressed with the |
c5174ad4 CL |
1127 | .Ql \&.Nm |
1128 | in the NAME section, and with | |
1129 | .Ql \&.Fn | |
1130 | in the SYNOPSIS | |
1131 | and remaining sections. | |
3e2f4ebf | 1132 | For interactive commands, such as the |
c5174ad4 | 1133 | .Ql while |
3e2f4ebf CL |
1134 | command keyword in |
1135 | .Xr csh 1 , | |
1136 | the | |
c5174ad4 CL |
1137 | .Ql \&.Ic |
1138 | macro should be used. | |
3e2f4ebf | 1139 | While the |
c5174ad4 | 1140 | .Ql \&.Ic |
3e2f4ebf CL |
1141 | is nearly identical |
1142 | to | |
c5174ad4 | 1143 | .Ql \&.Nm , |
3e2f4ebf CL |
1144 | it can not recall the first argument it was invoked with. |
1145 | .Pp | |
1146 | .Dl Usage: .Nm argument ... \*(Pu | |
c5174ad4 CL |
1147 | .Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n |
1148 | .It Li \&.Nm mdoc.sample | |
3e2f4ebf | 1149 | .Nm mdoc.sample |
c5174ad4 | 1150 | .It Li \&.Nm \-mdoc |
3e2f4ebf | 1151 | .Nm \-mdoc . |
c5174ad4 | 1152 | .It Li \&.Nm foo\ )\ )\ , |
3e2f4ebf | 1153 | .Nm foo ) ) , |
c5174ad4 | 1154 | .It Li \&.Nm |
3e2f4ebf | 1155 | .Nm |
c5174ad4 | 1156 | .El |
3e2f4ebf CL |
1157 | .Pp |
1158 | The | |
c5174ad4 CL |
1159 | .Ql \&.Nm |
1160 | macro | |
1161 | is callable by other macros and may call other macros. | |
1162 | .Ss No\-Op or Normal Text Macro | |
1163 | The macro | |
1164 | .Li \&.No | |
1165 | is | |
1166 | a hack for words in a macro command line which should | |
1167 | .Em not | |
1168 | be formatted and follows the conventional syntax | |
1169 | for content macros. | |
1170 | .Ss No Space Macro | |
1171 | The | |
1172 | .Ql \&.Ns | |
1173 | macro eliminates unwanted spaces in between macro requests. | |
1174 | It is useful for old style argument lists where there is no space | |
1175 | between the flag and argument: | |
1176 | .Bl -tag -width ".Op Fl I Ns Ar directory" -offset indent | |
1177 | .It Li ".Op Fl I Ns Ar directory" | |
1178 | produces | |
1179 | .Op Fl I Ns Ar directory | |
1180 | .El | |
1181 | .Pp | |
1182 | Note: the | |
1183 | .Ql \&.Ns | |
1184 | macro always invokes the | |
1185 | .Ql \&.No | |
1186 | macro after eliminating the space unless another macro name | |
1187 | follows it. | |
1188 | The macro | |
1189 | .Ql \&.Ns | |
1190 | is callable and may call other macros. | |
c5174ad4 CL |
1191 | .Ss Options |
1192 | The | |
1193 | .Ql \&.Op | |
1194 | macro | |
1195 | places option brackets around the any remaining arguments on the command | |
1196 | line, and places any | |
1197 | trailing punctuation outside the brackets. The macros | |
1198 | .Ql \&.Oc | |
1199 | and | |
1200 | .Ql \&.Oo | |
1201 | may be used across one or more lines. | |
1202 | .Pp | |
1203 | .Dl Usage: .Op options ... \*(Pu | |
1204 | .Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent | |
1205 | .It Li \&.Op | |
1206 | .Op | |
1207 | .It Li ".Op Fl k" | |
1208 | .Op Fl k | |
1209 | .It Li ".Op Fl k ) ." | |
1210 | .Op Fl k ) . | |
1211 | .It Li ".Op Fl k Ar kookfile" | |
1212 | .Op Fl k Ar kookfile | |
1213 | .It Li ".Op Fl k Ar kookfile ," | |
1214 | .Op Fl k Ar kookfile , | |
1215 | .It Li ".Op Ar objfil Op Ar corfil" | |
1216 | .Op Ar objfil Op Ar corfil | |
1217 | .It Li ".Op Fl c Ar objfil Op Ar corfil ," | |
1218 | .Op Fl c Ar objfil Op Ar corfil , | |
1219 | .It Li \&.Op word1 word2 | |
1220 | .Op word1 word2 | |
1221 | .El | |
1222 | .Pp | |
1223 | The | |
1224 | .Ql \&.Oc | |
1225 | and | |
1226 | .Ql \&.Oo | |
1227 | macros: | |
1228 | .Bd -literal -offset indent | |
1229 | \&.Oo | |
1230 | \&.Op \&Fl k \&Ar kilobytes | |
1231 | \&.Op \&Fl i \&Ar interval | |
1232 | \&.Op \&Fl c \&Ar count | |
1233 | \&.Oc | |
1234 | .Ed | |
1235 | .Pp | |
1236 | Produce: | |
1237 | .Oo | |
1238 | .Op Fl k Ar kilobytes | |
1239 | .Op Fl i Ar interval | |
1240 | .Op Fl c Ar count | |
1241 | .Oc | |
1242 | .Pp | |
1243 | The macros | |
1244 | .Ql \&.Op , | |
1245 | .Ql \&.Oc | |
1246 | and | |
1247 | .Ql \&.Oo | |
1248 | are callable and may call other macros. | |
1249 | .Ss Parenthesis Quote/Enclosure | |
1250 | Macros | |
1251 | .Li \&.Pq , \&.Pc | |
1252 | and | |
1253 | .Li \&.Po | |
1254 | follow the conventions for a typical quoting macros, | |
1255 | see | |
1256 | .Sx Enclosure Macros | |
1257 | and | |
1258 | .Sx Options | |
1259 | above. | |
3e2f4ebf CL |
1260 | .Ss Pathnames |
1261 | The | |
c5174ad4 CL |
1262 | .Ql \&.Pa |
1263 | macro formats path or file names. | |
3e2f4ebf CL |
1264 | .Pp |
1265 | .Dl Usage: .Pa pathname \*(Pu | |
c5174ad4 CL |
1266 | .Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n |
1267 | .It Li \&.Pa /usr/share | |
3e2f4ebf | 1268 | .Pa /usr/share |
c5174ad4 | 1269 | .It Li \&.Pa /tmp/fooXXXXX\ )\ . |
3e2f4ebf | 1270 | .Pa /tmp/fooXXXXX ) . |
c5174ad4 | 1271 | .El |
3e2f4ebf | 1272 | .Pp |
c5174ad4 CL |
1273 | The |
1274 | .Ql \&.Pa | |
1275 | macro | |
1276 | is callable by other macros and may call other macros. | |
1277 | .Ss Single Quotes/Enclosure | |
1278 | See | |
1279 | .Sx Enclosure Macros . | |
1280 | See | |
1281 | .Sx Double Quote/Enclosure | |
1282 | above. | |
1283 | The single quoting macro | |
1284 | .Ql \&.Sq | |
1285 | works in the identical manner as | |
1286 | .Ql \&.Dq. | |
1287 | .Ss Prefix Macro | |
1288 | The | |
c9a5c681 CL |
1289 | .Ql \&.Pf |
1290 | macro | |
1291 | is a short cut for combining | |
c5174ad4 | 1292 | two strings together, the first of which is |
c9a5c681 | 1293 | in the default font, and the second a content |
c5174ad4 CL |
1294 | specified string. |
1295 | .Pp | |
1296 | .Bl -tag -width ".Pf ( Fa name2 " -offset 14n -compact | |
1297 | .It Li ".Pf ( Fa name2" | |
1298 | becomes | |
1299 | .Pf ( Fa name2 | |
1300 | .El | |
1301 | .Pp | |
1302 | The | |
1303 | .Ql \&.Pf | |
1304 | macro is not callable, but may call other macros. The | |
1305 | .Ql \&.Ns | |
1306 | macro performs the analogus suffix function. | |
1307 | .Ss Section Cross References | |
1308 | The | |
1309 | .Ql \&.Sx | |
1310 | macro designates a reference to a section header | |
1311 | within the same document. It is callable by other macros and may | |
1312 | call other macros. | |
1313 | .Pp | |
1314 | .Bl -tag -width "Li \&.Sx FILES" -offset 14n | |
1315 | .It Li \&.Sx FILES | |
1316 | .Sx FILES | |
1317 | .El | |
1318 | .Ss References and Citations | |
1319 | The following macros make a modest attempt to handle references. | |
1320 | At best, the macros make it convientent to manually drop in a subset of | |
1321 | refer style references. | |
1322 | .Pp | |
1323 | .Bl -tag -width 6n -offset indent -compact | |
1324 | .It Li ".Rs" | |
1325 | Reference Start. Causes a line break and begins collection | |
1326 | of reference information until the | |
1327 | reference end macro is read. | |
1328 | .It Li ".Re" | |
1329 | Reference End. The reference is printed. | |
1330 | .It Li ".%A" | |
1331 | Reference author name, one name per invocation. | |
1332 | .It Li ".%B" | |
1333 | Book title. | |
1334 | .It Li ".%J" | |
1335 | Journal title. | |
1336 | .It Li ".%N" | |
1337 | Issue number. | |
1338 | .It Li ".%O" | |
1339 | Optional information. | |
1340 | .It Li ".%R" | |
1341 | Report name. | |
1342 | .It Li ".%T" | |
1343 | Title of article. | |
1344 | .It Li ".%V" | |
1345 | Volume(s). | |
1346 | .El | |
1347 | .Pp | |
1348 | The macros begining with | |
1349 | .Ql % | |
1350 | are not callable, but may call only the trade name macro which | |
1351 | returns to its caller. The purpose is to allow trade names | |
1352 | to be pretty printed in troff/ditroff output. WARNING: this | |
1353 | has very few trade names defined at the moment and will print unknown | |
1354 | trade names in the default font. | |
3e2f4ebf | 1355 | .Ss Symbolic |
c5174ad4 CL |
1356 | The symbolic emphasis macro is generally a boldface macro in |
1357 | either the symbolic sense or the traditional English usage. | |
3e2f4ebf CL |
1358 | .Pp |
1359 | .Dl Usage: .Sy symbol ... \*(Pu | |
c5174ad4 CL |
1360 | .Bl -tag -width ".Sy Important Notice" -compact -offset 14n |
1361 | .It Li \&.Sy Important Notice | |
1362 | .Sy Important Notice | |
1363 | .El | |
3e2f4ebf CL |
1364 | .Pp |
1365 | The | |
c5174ad4 CL |
1366 | .Ql \&.Sy |
1367 | macro | |
1368 | is callable by other macros and may call other macros, except | |
1369 | in the second form. Arguments to | |
1370 | .Ql \&.Sy | |
1371 | may be quoted. | |
3e2f4ebf CL |
1372 | .Ss Variables |
1373 | Generic variable reference: | |
1374 | .Pp | |
1375 | .Dl Usage: .Va variable ... \*(Pu | |
c5174ad4 CL |
1376 | .Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n |
1377 | .It Li \&.Va count | |
3e2f4ebf | 1378 | .Va count |
c5174ad4 | 1379 | .It Li \&.Va settimer , |
3e2f4ebf | 1380 | .Va settimer , |
c5174ad4 | 1381 | .It Li \&.Va int\ *prt\ )\ : |
3e2f4ebf | 1382 | .Va int\ *prt ) : |
c5174ad4 | 1383 | .It Li \&.Va char\ s\ ]\ )\ )\ , |
3e2f4ebf | 1384 | .Va char\ s ] ) ) , |
c5174ad4 | 1385 | .El |
3e2f4ebf | 1386 | .Pp |
c5174ad4 CL |
1387 | It is an error to call |
1388 | .Ql \&.Va | |
1389 | without any arguments. | |
1390 | The | |
1391 | .Ql \&.Va | |
1392 | macro | |
1393 | is callable by other macros and may call other macros. | |
3e2f4ebf CL |
1394 | .Ss Cross References |
1395 | The | |
c5174ad4 CL |
1396 | .Ql \&.Xr |
1397 | macro expects the first argument to be | |
3e2f4ebf CL |
1398 | a manual page name, and the second argument, if it exists, |
1399 | to be either a section page number or punctuation. Any | |
1400 | remaining arguments are assumed to be punctuation. | |
1401 | .Pp | |
1402 | .Dl Usage: .Xr manpage [1,...,8] \*(Pu | |
c5174ad4 CL |
1403 | .Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n |
1404 | .It Li \&.Xr mdoc | |
3e2f4ebf | 1405 | .Xr mdoc |
c5174ad4 | 1406 | .It Li \&.Xr mdoc\ , |
3e2f4ebf | 1407 | .Xr mdoc , |
c5174ad4 | 1408 | .It Li \&.Xr mdoc 7 |
3e2f4ebf | 1409 | .Xr mdoc 7 |
c5174ad4 | 1410 | .It Li \&.Xr mdoc 7\ )\ )\ , |
3e2f4ebf | 1411 | .Xr mdoc 7 ) ) , |
c5174ad4 | 1412 | .El |
3e2f4ebf CL |
1413 | .Pp |
1414 | The | |
c5174ad4 CL |
1415 | .Ql \&.Xr |
1416 | macro | |
1417 | is callable by other macros and may call other macros. | |
3e2f4ebf | 1418 | It is an error to call |
c5174ad4 | 1419 | .Ql \&.Xr |
3e2f4ebf CL |
1420 | without |
1421 | any arguments. | |
c5174ad4 CL |
1422 | .Ss Extended Arguments |
1423 | The | |
1424 | .Li \&.Xo | |
1425 | and | |
1426 | .Li \&.Xc | |
1427 | maxros allow one to extend an argument list | |
1428 | on a macro boundary. Argument lists cannot | |
1429 | be extended within a macro | |
1430 | which expects all of its arguments on one line such | |
1431 | as | |
1432 | .Ql \&.Op . | |
3e2f4ebf CL |
1433 | .\" --- |
1434 | .Sh PAGE LAYOUT MACROS | |
1435 | .Ss Section Headers | |
c5174ad4 CL |
1436 | The first three |
1437 | .Ql \&.Sh | |
1438 | section header macros | |
1439 | list below are required in every | |
1440 | man page. The remaining section headers | |
1441 | are recommended at the disgression of the author | |
1442 | writing the manual page. The | |
1443 | .Ql \&.Sh | |
1444 | macro can take up to nine arguments. It may call | |
1445 | other macros, but it may not be called by other macros. | |
1446 | .Bl -tag -width ".Sh SYNOPSIS" | |
1447 | .It \&.Sh NAME | |
3e2f4ebf | 1448 | The |
c5174ad4 CL |
1449 | .Ql \&.Sh NAME |
1450 | macro is mandatory. If not specified, | |
3e2f4ebf CL |
1451 | the headers, footers and page layout defaults |
1452 | will not be set and things will be rather unpleasant. | |
1453 | The NAME section consists of at least three items. | |
1454 | The first is the | |
c5174ad4 CL |
1455 | .Ql \&.Nm |
1456 | name macro naming the subject of the man page. | |
1457 | The second is the Name Description macro, | |
1458 | .Ql \&.Nd , | |
3e2f4ebf CL |
1459 | which separates the subject |
1460 | name from the third item, which is the description. The | |
1461 | description should be the most terse and lucid possible, | |
1462 | as the space available is small. | |
c5174ad4 | 1463 | .It \&.Sh SYNOPSIS |
3e2f4ebf | 1464 | The SYNOPSIS section describes the typical usage of the |
c5174ad4 | 1465 | subject of a man page. The macros required |
3e2f4ebf | 1466 | are either |
c5174ad4 CL |
1467 | .Ql ".Nm" , |
1468 | .Ql ".Cd" , | |
3e2f4ebf | 1469 | or |
c5174ad4 CL |
1470 | .Ql ".Fn" |
1471 | (and possibly | |
1472 | .Ql ".Fd" , | |
1473 | .Ql ".Ft" | |
1474 | macros). | |
3e2f4ebf | 1475 | The function name |
c5174ad4 CL |
1476 | macro |
1477 | .Ql ".Fn" | |
3e2f4ebf CL |
1478 | is required |
1479 | for manual page sections 2 and 3, the command and general | |
c5174ad4 CL |
1480 | name macro |
1481 | .Ql \&.Nm | |
1482 | is required for sections 1, 5, 6, 7, 8. | |
1483 | Section 4 manuals require a | |
1484 | .Ql ".Nm" , ".Fd" | |
1485 | or a | |
1486 | .Ql ".Cd" | |
1487 | configuration device usage macro. | |
1488 | Several other macros may be necessary to produce | |
3e2f4ebf CL |
1489 | the synopsis line as shown below: |
1490 | .Pp | |
c5174ad4 | 1491 | .Bd -filled -offset indent |
3e2f4ebf CL |
1492 | .Nm cat |
1493 | .Op Fl benstuv | |
1494 | .Op Fl | |
1495 | .Ar | |
c5174ad4 | 1496 | .Ed |
3e2f4ebf | 1497 | .Pp |
c5174ad4 | 1498 | The following macros were used: |
3e2f4ebf CL |
1499 | .Pp |
1500 | .Dl \&.Nm cat | |
c5174ad4 CL |
1501 | .Dl \&.Op \&Fl benstuv |
1502 | .Dl \&.Op \&Fl | |
3e2f4ebf | 1503 | .Dl \&.Ar |
c5174ad4 | 1504 | .It \&.Sh DESCRIPTION |
3e2f4ebf CL |
1505 | In most cases the first text in the DESCRIPTION section |
1506 | is a brief paragraph on the command, function or file, | |
1507 | followed by a lexical list of options and respective | |
1508 | explanations. To create such a list, the | |
c5174ad4 CL |
1509 | .Ql \&.Bl |
1510 | begin-list, | |
1511 | .Ql \&.It | |
1512 | list-item and | |
1513 | .Ql \&.El | |
1514 | end-list | |
1515 | macros are used (see | |
1516 | .Sx Lists and Columns | |
1517 | below). | |
1518 | .El | |
3e2f4ebf CL |
1519 | .Pp |
1520 | The following | |
c5174ad4 | 1521 | .Ql \&.Sh |
3e2f4ebf CL |
1522 | section headers are part of the |
1523 | preferred manual page layout and must be used appropriately | |
1524 | to maintain consistency. They are listed in the order | |
1525 | in which they would be used. | |
c5174ad4 CL |
1526 | .Bl -tag -width SYNOPSIS |
1527 | .It \&.Sh ENVIRONMENT | |
3e2f4ebf CL |
1528 | The ENVIRONMENT section should reveal any related |
1529 | environment | |
1530 | variables and clues to their behaviour and/or usage. | |
c5174ad4 | 1531 | .It \&.Sh EXAMPLES |
3e2f4ebf CL |
1532 | There are several ways to create examples. See |
1533 | the EXAMPLES section below | |
1534 | for details. | |
c5174ad4 | 1535 | .It \&.Sh FILES |
3e2f4ebf CL |
1536 | Files which are used or created by the man page subject |
1537 | should be listed via the | |
c5174ad4 CL |
1538 | .Ql \&.Pa |
1539 | macro in the FILES section. | |
1540 | .It \&.Sh SEE ALSO | |
3e2f4ebf CL |
1541 | References to other material on the man page topic and |
1542 | cross references to other relevant man pages should | |
1543 | be placed in the SEE ALSO section. Cross references | |
1544 | are specified using the | |
c5174ad4 CL |
1545 | .Ql \&.Xr |
1546 | macro. At this time | |
3e2f4ebf CL |
1547 | .Xr refer 1 |
1548 | style references are not accommodated. | |
c5174ad4 | 1549 | .It \&.Sh STANDARDS |
3e2f4ebf CL |
1550 | If the command, library function or file adheres to a |
1551 | specific implementation such as POSIX 1003.1 or | |
1552 | ANSI C X3.159-1989 this should be noted here. If the | |
1553 | command does not adhere to any standard, its history | |
1554 | should be noted in the HISTORY section. | |
c5174ad4 | 1555 | .It \&.Sh HISTORY |
3e2f4ebf CL |
1556 | Any command which does not adhere to any specific standards |
1557 | should be outlined historically in this section. | |
c5174ad4 | 1558 | .It \&.Sh AUTHORS |
3e2f4ebf | 1559 | Credits, if need be, should be placed here. |
c5174ad4 | 1560 | .It \&.Sh DIAGNOSTICS |
3e2f4ebf | 1561 | Diagnostics from a command should be placed in this section. |
c5174ad4 | 1562 | .It \&.Sh ERRORS |
3e2f4ebf CL |
1563 | Specific error handling, especially from library functions |
1564 | (man page sections 2 and 3) should go here. The | |
c5174ad4 CL |
1565 | .Ql \&.Er |
1566 | macro is used to specify an errno. | |
1567 | .It \&.Sh BUGS | |
3e2f4ebf | 1568 | Blatant problems with the topic go here... |
c5174ad4 | 1569 | .El |
3e2f4ebf | 1570 | .Pp |
c5174ad4 CL |
1571 | User specified |
1572 | .Ql \&.Sh | |
1573 | sections may be added, | |
1574 | for example, this section was set with: | |
1575 | .Bd -literal -offset 14n | |
1576 | \&.Sh PAGE LAYOUT MACROS | |
1577 | .Ed | |
3e2f4ebf | 1578 | .Ss Paragraphs and Line Spacing. |
c5174ad4 CL |
1579 | .Bl -tag -width 6n |
1580 | .It \&.Pp | |
3e2f4ebf CL |
1581 | The \&.Pp paragraph command may |
1582 | be used to specify a line space where necessary. | |
c5174ad4 CL |
1583 | The macro is not necessary after a |
1584 | .Ql \&.Sh | |
3e2f4ebf | 1585 | or |
c5174ad4 CL |
1586 | .Ql \&.Ss |
1587 | macro or before | |
3e2f4ebf | 1588 | a |
c5174ad4 CL |
1589 | .Ql \&.Bl |
1590 | macro. | |
1591 | (The | |
1592 | .Ql \&.Bl | |
1593 | macro asserts a vertical distance unless the -compact flag is given). | |
1594 | .El | |
1595 | .\" .Pp | |
1596 | .\" .Ds I | |
1597 | .\" .Cw (ax+bx+c) \ is\ produced\ by\ \& | |
1598 | .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& | |
1599 | .\" .Cl Cx \t\t | |
1600 | .\" .Li \&.Cx\ ( | |
1601 | .\" .Cx | |
1602 | .\" .Cl Cx \t\t | |
1603 | .\" .Li \&.Va ax | |
1604 | .\" .Cx | |
1605 | .\" .Cl Cx \t\t | |
1606 | .\" .Li \&.Sy \+ | |
1607 | .\" .Cx | |
1608 | .\" .Cl Cx \&(\& | |
1609 | .\" .Va ax | |
1610 | .\" .Cx + | |
1611 | .\" .Va by | |
1612 | .\" .Cx + | |
1613 | .\" .Va c ) | |
1614 | .\" .Cx \t | |
1615 | .\" .Em is produced by | |
1616 | .\" .Cx \t | |
1617 | .\" .Li \&.Va by | |
1618 | .\" .Cx | |
1619 | .\" .Cl Cx \t\t | |
1620 | .\" .Li \&.Sy \+ | |
1621 | .\" .Cx | |
1622 | .\" .Cl Cx \t\t | |
1623 | .\" .Li \&.Va c ) | |
1624 | .\" .Cx | |
1625 | .\" .Cl Cx \t\t | |
1626 | .\" .Li \&.Cx | |
1627 | .\" .Cx | |
1628 | .\" .Cw | |
1629 | .\" .De | |
1630 | .\" .Pp | |
1631 | .\" This example shows the same equation in a different format. The spaces | |
1632 | .\" around the | |
1633 | .\" .Li \&+ | |
1634 | .\" signs were forced with | |
1635 | .\" .Li \e : | |
1636 | .\" .Pp | |
1637 | .\" .Ds I | |
1638 | .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& | |
1639 | .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& | |
1640 | .\" .Cl Cx \t\t | |
1641 | .\" .Li \&.Cx\ ( | |
1642 | .\" .Cx | |
1643 | .\" .Cl Cx \t\t | |
1644 | .\" .Li \&.Va a | |
1645 | .\" .Cx | |
1646 | .\" .Cl Cx \t\t | |
1647 | .\" .Li \&.Sy x | |
1648 | .\" .Cx | |
1649 | .\" .Cl Cx \t\t | |
1650 | .\" .Li \&.Cx \e\ +\e\ \e& | |
1651 | .\" .Cx | |
1652 | .\" .Cl Cx \&(\& | |
1653 | .\" .Va a | |
1654 | .\" .Sy x | |
1655 | .\" .Cx \ +\ \& | |
1656 | .\" .Va b | |
1657 | .\" .Sy y | |
1658 | .\" .Cx \ +\ \& | |
1659 | .\" .Va c ) | |
1660 | .\" .Cx \t | |
1661 | .\" .Em is produced by | |
1662 | .\" .Cl Cx \t\t | |
1663 | .\" .Li \&.Va b | |
1664 | .\" .Cx | |
1665 | .\" .Cl Cx \t\t | |
1666 | .\" .Li \&.Sy y | |
1667 | .\" .Cx | |
1668 | .\" .Cl Cx \t\t | |
1669 | .\" .Li \&.Cx \e\ +\e\ \e& | |
1670 | .\" .Cx | |
1671 | .\" .Cl Cx \t\t | |
1672 | .\" .Li \&.Va c ) | |
1673 | .\" .Cx | |
1674 | .\" .Cl Cx \t\t | |
1675 | .\" .Li \&.Cx | |
1676 | .\" .Cx | |
1677 | .\" .Cw | |
1678 | .\" .De | |
1679 | .\" .Pp | |
1680 | .\" The incantation below was | |
1681 | .\" lifted from the | |
1682 | .\" .Xr adb 1 | |
1683 | .\" manual page: | |
1684 | .\" .Pp | |
1685 | .\" .Ds I | |
1686 | .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by | |
1687 | .\" .Cl Cx \t\t | |
1688 | .\" .Li \&.Cx Op Sy ?/ | |
1689 | .\" .Cx | |
1690 | .\" .Cl Cx \t\t | |
1691 | .\" .Li \&.Nm m | |
1692 | .\" .Cx | |
1693 | .\" .Cl Cx Op Sy ?/ | |
1694 | .\" .Nm m | |
1695 | .\" .Ad \ b1 e1 f1 | |
1696 | .\" .Op Sy ?/ | |
1697 | .\" .Cx \t | |
1698 | .\" .Em is produced by | |
1699 | .\" .Cx \t | |
1700 | .\" .Li \&.Ar \e\ b1 e1 f1 | |
1701 | .\" .Cx | |
1702 | .\" .Cl Cx \t\t | |
1703 | .\" .Li \&.Op Sy ?/ | |
1704 | .\" .Cx | |
1705 | .\" .Cl Cx \t\t | |
1706 | .\" .Li \&.Cx | |
1707 | .\" .Cx | |
1708 | .\" .Cw | |
1709 | .\" .De | |
1710 | .\" .Pp | |
3e2f4ebf | 1711 | .Ss Examples and Displays |
c5174ad4 CL |
1712 | There are five types of displays, a quickie one line indented display |
1713 | .Ql \&.D1 , | |
1714 | a quickie one line literal display | |
1715 | .Ql \&.Dl , | |
1716 | a block literal, block filled and block ragged which use | |
1717 | the | |
1718 | .Ql \&.Bd | |
1719 | begin-display | |
1720 | and | |
1721 | .Ql \&.Ed | |
1722 | end-display macros. | |
1723 | .Pp | |
1724 | .Bl -tag -width \&.D1 | |
1725 | .It Li \&.D1 | |
1726 | (D-one) Display one line of indented text. | |
1727 | Arguments are checked to see if they are callable. | |
1728 | .Bd -ragged -offset indent | |
1729 | .Li \&.D1 \&Fl ldghfstru | |
1730 | .Ed | |
1731 | .Pp | |
1732 | produces: | |
3e2f4ebf | 1733 | .Pp |
c5174ad4 CL |
1734 | .Dl Fl ldghfstru |
1735 | .It Li \&.Dl | |
1736 | (D-ell) | |
1737 | Display one line of indented | |
1738 | .Em literal | |
1739 | text. The | |
1740 | .Ql \&.Dl | |
1741 | example macro has been used throughout this | |
1742 | file. It allows | |
1743 | the indent (display) of one line of text. | |
1744 | Its default font is set to | |
1745 | constant width (literal) however | |
1746 | .Ql \&.Dl | |
1747 | does check arguments to see it they are callable. | |
1748 | Macros called from | |
1749 | .Li \&.Dl | |
1750 | should be content macros; calling macros from | |
1751 | the page layout section | |
1752 | is redundant and may cause unpredictable errors. | |
1753 | .Bd -ragged -offset indent | |
3e2f4ebf | 1754 | .Li \&.Dl % ls -ldg /usr/local/bin |
c5174ad4 | 1755 | .Ed |
3e2f4ebf CL |
1756 | .Pp |
1757 | produces: | |
c5174ad4 | 1758 | .Pp |
3e2f4ebf | 1759 | .Dl % ls -ldg /usr/local/bin |
c5174ad4 CL |
1760 | .It Li \&.Bd |
1761 | Begin-display. The | |
1762 | .Ql \&.Bd | |
1763 | display must be ended with the | |
1764 | .Ql \&.Ed | |
1765 | macro. Displays may be nested within displays and | |
1766 | lists. | |
1767 | .Ql \&.Bd | |
1768 | has the following syntax: | |
3e2f4ebf | 1769 | .Pp |
c5174ad4 | 1770 | .Dl ".Bd display-type [offset offset_value]" |
3e2f4ebf | 1771 | .Pp |
c5174ad4 CL |
1772 | The display-type must be one of the following four types and |
1773 | may have an offset specifier for indentation: | |
1774 | .Ql \&.Bd . | |
3e2f4ebf | 1775 | .Pp |
c5174ad4 CL |
1776 | .Bl -tag -width "literalxx" -compact |
1777 | .It Fl ragged | |
3e2f4ebf | 1778 | Display a block of text as typed, |
c5174ad4 CL |
1779 | right (and left) margin edges are left ragged. |
1780 | .It Fl filled | |
1781 | Display a filled (formatted) block. | |
1782 | The block of text is formatted (the edges are filled \- | |
1783 | not left ragged). | |
1784 | .It Fl literal | |
1785 | Display a literal block, useful for source code or | |
1786 | simple tabbed or spaced text. | |
1787 | .It Fl file Ar file_name | |
1788 | The file name following the | |
1789 | .Fl file | |
1790 | flag is read and displayed. Literal mode is | |
1791 | asserted and tabs are set at 8 constant width character | |
1792 | intervals, however any | |
1793 | .Xr troff/ Ns Nm \-mdoc | |
1794 | commands in file will be processed. | |
1795 | .It Fl offset Ar string | |
1796 | If | |
1797 | .Fl offset | |
1798 | is specified with one of the following strings, the string | |
1799 | is interpreted to indicate the level of indentation for the | |
1800 | forthcoming block of text: | |
1801 | .Pp | |
1802 | .Bl -tag -width "indent" -compact | |
1803 | .It Ar left | |
3e2f4ebf CL |
1804 | Align block on the current left margin, |
1805 | this is the default mode of | |
c5174ad4 CL |
1806 | .Ql \&.Bd . |
1807 | .It Ar center | |
3e2f4ebf CL |
1808 | Supposedly center the block. At this time |
1809 | unfortunately, the block merely gets | |
1810 | left aligned about an imaginary center margin. | |
c5174ad4 CL |
1811 | .It Ar indent |
1812 | Indents by one default indent value or tab. The default | |
1813 | indent value is also used for the | |
1814 | .Ql \&.D1 | |
1815 | display so one can be garanteed of the two types of displays | |
1816 | lining up. This indent is nornally set to 6n or about two | |
1817 | thirds of an inch (six constant width characters). | |
1818 | .It Ar indent-two | |
1819 | Indents two times the default indent value. | |
1820 | .It Ar right | |
1821 | This | |
1822 | .Em left | |
1823 | aligns the block about two inches from | |
1824 | the right side of the page. This macro also needs | |
1825 | work and perhaps may never be right in | |
1826 | .Xr troff . | |
1827 | .El | |
1828 | .El | |
1829 | .It ".Ed" | |
1830 | End-display. | |
1831 | .El | |
1832 | .Ss Tagged Lists and Columns | |
1833 | There are several types of lists which may be initiated with the | |
1834 | .Ql ".Bl" | |
1835 | begin-list macro. Items within the list | |
1836 | are specified with the | |
1837 | .Ql ".It" | |
1838 | item macro and | |
1839 | each list must end with the | |
1840 | .Ql ".El" | |
1841 | macro. Lists may be nested within themselves and within displays. | |
1842 | Columns may be used inside of lists, but lists are unproven | |
1843 | inside of columns. | |
1844 | .Pp | |
1845 | In addition, several list attributes may be specified such as | |
1846 | the width of a tag, the list offset, and compactness specified | |
1847 | (blank lines between items allowed or disallowed). | |
1848 | The following list types are accepted by | |
1849 | .Ql ".Bl": | |
1850 | .Pp | |
1851 | .Bl -ohang -compact | |
1852 | .It Fl bullet | |
1853 | .It Fl item | |
1854 | .It Fl enum | |
1855 | These three are the simplest types of lists. Once the | |
1856 | .Ql ".Bl" | |
1857 | macro has been given, items in the list are merely | |
1858 | indicated by a line consisting solely of the | |
1859 | .Ql ".It" | |
1860 | macro. For example, the source text for a simple enumerated list | |
1861 | would look like: | |
1862 | .Bd -literal -offset indent-two | |
1863 | \&.Bl -enum -compact | |
1864 | \&.It | |
1865 | \&Item one goes here. | |
1866 | \&.It | |
1867 | \&And item two here. | |
1868 | \&.It | |
1869 | \&Lastly item three goes here. | |
1870 | \&.El | |
1871 | .Ed | |
1872 | .Pp | |
1873 | The results: | |
1874 | .Pp | |
1875 | .Bl -enum -offset indent-two -compact | |
1876 | .It | |
1877 | Item one goes here. | |
1878 | .It | |
1879 | And item two here. | |
1880 | .It | |
1881 | Lastly item three goes here. | |
1882 | .El | |
1883 | .Pp | |
1884 | A simple bullet list construction: | |
1885 | .Bd -literal -offset indent-two | |
1886 | \&.Bl -bullet -compact | |
1887 | \&.It | |
1888 | \&Bullet one goes here. | |
1889 | \&.It | |
1890 | \&Bullet two here. | |
1891 | \&.El | |
1892 | .Ed | |
1893 | .Pp | |
1894 | Produces: | |
1895 | .Bl -bullet -offset indent-two -compact | |
1896 | .It | |
1897 | Bullet one goes here. | |
1898 | .It | |
1899 | Bullet two here. | |
1900 | .El | |
1901 | .Pp | |
1902 | .It Fl tag | |
1903 | .It Fl diag | |
1904 | .It Fl hang | |
1905 | .It Fl ohang | |
1906 | .It Fl inset | |
1907 | These list-types collect arguments specified with the | |
1908 | .Ql \&.It | |
1909 | macro and create a label which may be | |
1910 | .Em inset | |
1911 | into the forth coming text, | |
1912 | .Em hanged | |
1913 | (exdented) from the forth coming text, | |
1914 | .Em overhanged | |
1915 | set above the forth coming paragraph or | |
1916 | .Em tagged | |
1917 | (exdented and offset). This | |
1918 | list was constructed with the | |
1919 | .Ql Fl ohang | |
1920 | list-type. The | |
1921 | .Ql \&.It | |
1922 | macro may call any callable macros for the inset, hang | |
1923 | and tag list-types, but will not call macros for the | |
1924 | diag type. | |
1925 | Here is an example of inset labels: | |
1926 | .Bl -inset -offset indent | |
1927 | .It Em Tag | |
1928 | The tagged list (also called a tagged paragraph) is the | |
1929 | most common type of list used in the Berkeley manuals. | |
1930 | .It Em Diag | |
1931 | Diag lists create section four diagnostic lists | |
1932 | and are similar to inset lists except callable | |
1933 | macros are ignored. | |
1934 | .It Em Hang | |
1935 | Hanged labels are a matter of taste. | |
1936 | .It Em Ohang | |
1937 | Over hanging labels are nice when space is constrained. | |
1938 | .It Em Inset | |
1939 | Inset labels are useful for controlling blocks of | |
1940 | paragraphs and are valuable for converting | |
1941 | .Nm \-mdoc | |
1942 | manuals to other formats. | |
1943 | .El | |
1944 | .Pp | |
1945 | Here is the source text which produced the above example: | |
1946 | .Bd -literal -offset indent | |
1947 | \&.Bl -inset -offset indent | |
1948 | \&.It Em Tag | |
1949 | \&The tagged list (also called a tagged paragraph) is the | |
1950 | \&most common type of list used in the Berkeley manuals. | |
1951 | \&.It Em Diag | |
1952 | \&Diag lists create section four diagnostic lists | |
1953 | \&and are similar to inset lists except callable | |
1954 | \¯os are ignored. | |
1955 | \&.It Em Hang | |
1956 | \&Hanged labels are a matter of taste. | |
1957 | \&.It Em Ohang | |
1958 | \&Over hanging labels are nice when space is constrained. | |
1959 | \&.It Em Inset | |
1960 | \&Inset labels are useful for controlling blocks of | |
1961 | \¶graphs and are valuable for converting | |
1962 | \&.Nm \-mdoc | |
1963 | \&manuals to other formats. | |
1964 | \&.El | |
1965 | .Ed | |
1966 | .Pp | |
1967 | Here is a hanged list with just one item: | |
1968 | .Bl -hang -offset indent | |
1969 | .It Em Hanged | |
1970 | labels appear similar to tagged lists when the | |
1971 | label is smaller than the label width. | |
1972 | .It Em Longer hanged list labels | |
1973 | blend in to the paragraph unlike | |
1974 | tagged paragraph labels. | |
1975 | .El | |
1976 | .Pp | |
1977 | And the unfomatted text which created it: | |
1978 | .Bd -literal -offset indent | |
1979 | \&.Bl -hang -offset indent | |
1980 | \&.It Em Hanged | |
1981 | \&labels appear similar to tagged lists when the | |
1982 | \&label is smaller than the label width. | |
1983 | \&.It Em Longer hanged list labels | |
1984 | \&blend in to the paragraph unlike | |
1985 | \&tagged paragraph labels. | |
1986 | \&.El | |
1987 | .Ed | |
1988 | .Pp | |
1989 | The tagged list which follows uses an optional width specifier to controll | |
1990 | the width of the tag. | |
1991 | .Pp | |
1992 | .Bl -tag -width "PAGEIN 10" -compact -offset indent | |
1993 | .It SL 10 | |
1994 | sleep time of the process (seconds blocked) | |
1995 | .It PAGEIN 10 | |
1996 | number of disk i/o's resulting from references | |
1997 | by the process to pages not loaded in core. | |
1998 | .It UID 10 | |
1999 | numerical user-id of process owner | |
2000 | .It PPID 10 | |
2001 | numerical id of parent of process process priority | |
2002 | (non-positive when in non-interruptible wait) | |
2003 | .El | |
3e2f4ebf | 2004 | .Pp |
c5174ad4 CL |
2005 | The raw text: |
2006 | .Bd -literal -offset indent | |
2007 | \&.Bl -tag -width "PAGEIN 10" -compact -offset indent | |
2008 | \&.It SL 10 | |
2009 | \&sleep time of the process (seconds blocked) | |
2010 | \&.It PAGEIN 10 | |
2011 | \&number of disk i/o's resulting from references | |
2012 | \&by the process to pages not loaded in core. | |
2013 | \&.It UID 10 | |
2014 | \&numerical user-id of process owner | |
2015 | \&.It PPID 10 | |
2016 | \&numerical id of parent of process process priority | |
2017 | \&(non-positive when in non-interruptible wait) | |
2018 | \&.El | |
2019 | .Ed | |
2020 | .Pp | |
2021 | Acceptable width specifiers: | |
2022 | .Bl -tag -width Ar -offset indent | |
2023 | .It Fl width Ar "\&Fl" | |
2024 | sets the width to the default width for a flag. All callable | |
2025 | macros have a default width value. The | |
2026 | .Ql \&.Fl , | |
2027 | value is presently | |
3e2f4ebf CL |
2028 | set to ten constant width characters or about five sixth of |
2029 | an inch. | |
c5174ad4 | 2030 | .It Fl width Ar "24n" |
3e2f4ebf CL |
2031 | sets the width to 24 constant width characters or about two |
2032 | inches. The | |
c5174ad4 | 2033 | .Ql n |
3e2f4ebf | 2034 | is absolutely necessary for the scaling to work correctly. |
c5174ad4 CL |
2035 | .It Fl width Ar "ENAMETOOLONG" |
2036 | sets width to the constant width length of the | |
3e2f4ebf | 2037 | string given. |
c5174ad4 | 2038 | .It Fl width Ar "\\*qint mkfifo\\*q" |
3e2f4ebf | 2039 | again, the width is set to the constant width of the string |
c5174ad4 CL |
2040 | given. |
2041 | .El | |
2042 | .Pp | |
2043 | If a width is not specified for the tag list type, the first | |
2044 | time | |
2045 | .Ql \&.It | |
2046 | is invoked, an attempt is made to determine an appropriate | |
2047 | width. If the first argument to | |
2048 | .Ql ".It" | |
2049 | is a callable macro, the default width for that macro will be used | |
2050 | as if the macro name had been supplied as the width. However, | |
2051 | if another item in the list is given with a different callable | |
2052 | macro name, a new and nested list is assumed. Here is an involved | |
2053 | example of a self nesting list: | |
2054 | .Sh DIAGNOSTICS | |
2055 | The debugging facilities for | |
2056 | .Nm \-mdoc | |
2057 | are limited, but can help detect subtle errors such | |
2058 | as the collision of an argument name with an internal | |
2059 | register or macro name. (A what?) | |
2060 | A register is an arithmetic storage class for | |
2061 | .Xr troff | |
2062 | with a one or two character name. | |
2063 | All registers internal to | |
2064 | .Nm \-mdoc | |
2065 | for | |
2066 | .Xr troff | |
2067 | and | |
2068 | .Xr ditroff | |
2069 | are two characters and | |
2070 | of the form <uppercase><lowercase> such as | |
2071 | .Ql \&Ar , | |
2072 | <lowercase><uppercase> as | |
2073 | .Ql \&aR | |
3e2f4ebf | 2074 | or |
c5174ad4 CL |
2075 | <upper or lower letter><digit> as |
2076 | .Ql \&C\&1 . | |
2077 | And adding to the muddle, | |
2078 | .Xr troff | |
2079 | has its own internal registers all of which are either | |
2080 | two lowercase characters or a dot plus a letter or meta-character | |
2081 | character. | |
2082 | In one of the introduction examples, it was shown how to | |
2083 | prevent the interpretation of a macro name with the escape sequence | |
2084 | .Ql \e& . | |
2085 | This is sufficient for the internal register names also. | |
2086 | .Pp | |
2087 | .\" Every callable macro name has a corresponding register | |
2088 | .\" of the same name (<Uppercase><lowercase>). | |
2089 | .\" There are also specific registers which have | |
2090 | .\" been used for stacks and arrays and are listed in the | |
2091 | .\" .Sx Appendix . | |
2092 | .\" .Bd -ragged -offset 4n | |
2093 | .\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') | |
2094 | .\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') | |
2095 | .\" C[0-9] argument types (example C1) | |
2096 | .\" O[0-9] offset stack (displays) | |
2097 | .\" h[0-9] horizontal spacing stack (lists) | |
2098 | .\" o[0-9] offset (stack) (lists) | |
2099 | .\" t[0-9] tag stack (lists) | |
2100 | .\" v[0-9] vertical spacing stack (lists) | |
2101 | .\" w[0-9] width tag/label stack | |
2102 | .\" .Ed | |
2103 | .\" .Pp | |
2104 | If a non-escaped register name is given in the argument list of a request | |
2105 | unpredictable behaviour will occur. In general, anytime huge portions | |
2106 | of text do not appear where expected in the output, or small strings | |
2107 | such as list tags disappear, chances are there is a misunderstanding | |
2108 | about an argument type in the argument list. | |
2109 | Your mother never intended for you to remember this evil stuff - so here | |
2110 | is a way to find out whether or not your arguments are valid: The | |
2111 | .Ql \&.Db | |
2112 | (debug) | |
2113 | macro displays the interpretation of the argument list for most | |
2114 | macros. Macros such as the | |
2115 | .Ql \&.Pp | |
2116 | (paragraph) | |
2117 | macro do not contain debugging information. All of the callable macros do, | |
2118 | and it is strongly advised whenever in doubt, | |
2119 | turn on the | |
2120 | .Ql \&.Db | |
2121 | macro. | |
2122 | .Pp | |
2123 | .Dl Usage: \&.Db [on | off] | |
2124 | .Pp | |
2125 | An example of a portion of text with | |
2126 | the debug macro placed above and below an | |
2127 | artificially created problem (a flag argument | |
2128 | .Ql \&aC | |
2129 | which should be | |
2130 | .Ql \e&aC | |
2131 | in order to work): | |
2132 | .Bd -literal -offset indent | |
2133 | \&.Db on | |
2134 | \&.Op Fl aC Ar file ) | |
2135 | \&.Db off | |
2136 | .Ed | |
2137 | .Pp | |
2138 | The resulting output: | |
2139 | .Bd -literal -offset indent | |
2140 | DEBUGGING ON | |
2141 | DEBUG(argv) MACRO: `.Op' Line #: 2 | |
2142 | Argc: 1 Argv: `Fl' Length: 2 | |
2143 | Space: `' Class: Executable | |
2144 | Argc: 2 Argv: `aC' Length: 2 | |
2145 | Space: `' Class: Executable | |
2146 | Argc: 3 Argv: `Ar' Length: 2 | |
2147 | Space: `' Class: Executable | |
2148 | Argc: 4 Argv: `file' Length: 4 | |
2149 | Space: ` ' Class: String | |
2150 | Argc: 5 Argv: `)' Length: 1 | |
2151 | Space: ` ' Class: Closing Punctuation or suffix | |
2152 | MACRO REQUEST: .Op Fl aC Ar file ) | |
2153 | DEBUGGING OFF | |
2154 | .Ed | |
2155 | .Pp | |
2156 | The first line of information tells the name of the calling | |
2157 | macro, here | |
2158 | .Ql \&.Op , | |
2159 | and the line number it appears on. If one or more files are involved | |
2160 | (especially if text from another file is included) the line number | |
2161 | may be bogus. If there is only one file, it should be accurate. | |
2162 | The second line gives the argument count, the argument | |
2163 | .Pq Ql \&Fl | |
2164 | and its length. If the length of an argument is two characters, the | |
2165 | argument is tested to see if it is executable (unfortunately, any | |
2166 | register which contains a non-zero value appears executable). | |
2167 | The third line gives the space allotted for a class, and the | |
2168 | class type. The problem here is the argument aC should not be | |
2169 | executable. The four types of classes are string, executable, closing | |
2170 | punctuation and opening punctuation. The last line shows the entire | |
2171 | argument list as it was read. In this next example, the offending | |
2172 | .Ql \&aC | |
2173 | is escaped: | |
2174 | .Bd -literal -offset indent | |
2175 | \&.Db on | |
2176 | \&.Em An escaped \e&aC | |
2177 | \&.Db off | |
2178 | .Ed | |
2179 | .Bd -literal -offset indent | |
2180 | DEBUGGING ON | |
2181 | DEBUG(fargv) MACRO: `.Em' Line #: 2 | |
2182 | Argc: 1 Argv: `An' Length: 2 | |
2183 | Space: ` ' Class: String | |
2184 | Argc: 2 Argv: `escaped' Length: 7 | |
2185 | Space: ` ' Class: String | |
2186 | Argc: 3 Argv: `aC' Length: 2 | |
2187 | Space: ` ' Class: String | |
2188 | MACRO REQUEST: .Em An escaped &aC | |
2189 | DEBUGGING OFF | |
2190 | .Ed | |
2191 | .Pp | |
2192 | The argument | |
2193 | .Ql \e&aC | |
2194 | shows up with the same length of 2 as the | |
2195 | .Ql \e& | |
2196 | sequence produces a zero width, but a register | |
2197 | named | |
2198 | .Ql \e&aC | |
2199 | was not found and the type classified as string. | |
2200 | .Pp | |
2201 | Other diagnostics consist of usage statements and are self explanatory. | |
3e2f4ebf | 2202 | .Sh FILES |
c5174ad4 CL |
2203 | .Bl -tag -width /usr/share/man0/template.doc -compact |
2204 | .It Pa /usr/share/tmac/tmac.doc | |
3e2f4ebf | 2205 | manual macro package |
c5174ad4 | 2206 | .It Pa /usr/share/man0/template.doc |
3e2f4ebf | 2207 | template for writing a man page |
c5174ad4 | 2208 | .El |
3e2f4ebf CL |
2209 | .Sh HISTORY |
2210 | 4.4 BSD | |
2211 | .Sh SEE ALSO | |
c5174ad4 | 2212 | .Xr mdoc 7 , |
3e2f4ebf CL |
2213 | .Xr man 1 , |
2214 | .Xr troff 1 | |
2215 | .Sh BUGS | |
3e2f4ebf CL |
2216 | Undesirable hyphenation on the dash of a flag |
2217 | argument is not yet resolved, and causes | |
2218 | occasional mishaps in the DESCRIPTION section. | |
c5174ad4 | 2219 | (line break on the hyphen). |
3e2f4ebf CL |
2220 | .Pp |
2221 | Predefined strings are not declared in documentation. | |
2222 | .Pp | |
2223 | Section 3f has not been added to the header routines. | |
2224 | .Pp | |
c5174ad4 | 2225 | .Ql \&.Nm |
3e2f4ebf CL |
2226 | font should be changed in NAME section. |
2227 | .Pp | |
c5174ad4 | 2228 | .Ql \&.Fn |
3e2f4ebf CL |
2229 | needs to have a check to prevent splitting up |
2230 | if the line length is too short. Right now it | |
2231 | separates the last parenthesis, and sometimes | |
2232 | looks ridiculous if a line is in fill mode. | |
2233 | .Pp | |
2234 | The method used to prevent header and footer page | |
2235 | breaks (other than the initial header and footer) when using | |
2236 | nroff seems to be putting out a partially filled line | |
2237 | at the bottom of the page leaving an unsightly blank space. | |
2238 | .Pp | |
c5174ad4 | 2239 | The list and display macros to not do any keeps |
3e2f4ebf | 2240 | and certainly should be able to. |