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 | .\" |
b141718f | 6 | .\" @(#)mdoc.samples.7 5.9 (Berkeley) %G% |
3e2f4ebf | 7 | .\" |
be765ac2 CL |
8 | .\" This tutorial sampler invokes every macro in the package several |
9 | .\" times and is guaranteed to give a worst case performance | |
60339870 | 10 | .\" for an already extremely slow package. |
be765ac2 | 11 | .\" |
3e2f4ebf | 12 | .Dd |
be765ac2 | 13 | .Os |
3e2f4ebf CL |
14 | .Dt MDOC.SAMPLES 7 |
15 | .Sh NAME | |
be765ac2 CL |
16 | .Nm mdoc.samples |
17 | .Nd tutorial sampler for writing | |
18 | .Bx | |
19 | manuals with | |
20 | .Nm \-mdoc | |
3e2f4ebf | 21 | .Sh SYNOPSIS |
be765ac2 | 22 | .Nm man mdoc.samples |
3e2f4ebf | 23 | .Sh DESCRIPTION |
c5174ad4 CL |
24 | A tutorial sampler for writing |
25 | .Bx | |
26 | manual pages with the | |
27 | .Nm \-mdoc | |
c9a5c681 CL |
28 | macro package, a |
29 | .Em content Ns \-based | |
be765ac2 CL |
30 | and |
31 | .Em domain Ns \-based | |
c9a5c681 | 32 | formatting |
c5174ad4 CL |
33 | package for |
34 | .Xr troff 1 . | |
35 | Its predecessor, the | |
36 | .Xr \-man 7 | |
37 | package, | |
b141718f | 38 | addressed page layout leaving the |
c5174ad4 CL |
39 | manipulation of fonts and other |
40 | typesetting details to the individual author. | |
be765ac2 CL |
41 | In |
42 | .Nm \-mdoc , | |
43 | page layout macros | |
44 | make up the | |
45 | .Em "page structure domain" | |
46 | which consists of macros for titles, section headers, displays | |
47 | and lists. Essentially items which affect the physical position | |
48 | of text on a formatted page. | |
49 | In addition to the page structure domain, there are two more domains, | |
50 | the manual domain and the general text domain. | |
51 | The general text domain is defined as macros which | |
52 | perform tasks such as quoting or emphasizing pieces of text. | |
53 | The manual domain is defined as macros that are a subset of the | |
54 | day to day informal language used to describe commands, routines | |
55 | and related | |
56 | .Bx | |
57 | files. | |
58 | Macros in the manual domain handle | |
59 | command names, command line arguments and options, function names, | |
60 | function parameters, pathnames, variables, cross | |
61 | references to other manual pages, and so on. | |
62 | These domain | |
c5174ad4 CL |
63 | items have value |
64 | for both the author and the future user of the manual page. | |
65 | It is hoped the consistency gained | |
66 | across the manual set will provide easier | |
67 | translation to future documentation tools. | |
68 | .Pp | |
69 | Through out the | |
70 | .Ux | |
71 | manual pages, a manual entry | |
72 | is simply referred | |
73 | to as a man page, regardless of actual length and without | |
74 | sexist intention. | |
be765ac2 CL |
75 | .Sh GETTING STARTED |
76 | Since a tutorial document is normally read when a person | |
77 | desires to use the material immediately, the assumption has | |
78 | been made that the user of this document may be impatient. | |
79 | The material presented in the remained of this document is | |
80 | outlined as follows: | |
81 | .Bl -enum -offset indent | |
82 | .It | |
83 | .Tn "TROFF IDIOSYNCRASIES" | |
84 | .Bl -tag -width flag -compact -offset indent | |
85 | .It Tn "Macro Usage" . | |
86 | .It Tn "Passing Space Characters in an Argument" . | |
87 | .It Tn "Trailing Blank Space Characters (a warning)" . | |
88 | .It Tn "Escaping Special Characters" . | |
89 | .El | |
90 | .It | |
91 | .Tn "THE ANATOMY OF A MAN PAGE" | |
92 | .Bl -tag -width flag -compact -offset indent | |
93 | .It Tn "A manual page template" . | |
94 | .El | |
95 | .It | |
96 | .Tn "INTRODUCTION OF TITLE MACROS" . | |
97 | .It | |
98 | .Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . | |
99 | .Bl -tag -width flag -compact -offset indent | |
100 | .It Tn "What's in a name..." . | |
101 | .It Tn "General Syntax" . | |
102 | .El | |
103 | .It | |
104 | .Tn "MANUAL DOMAIN" | |
105 | .Bl -tag -width flag -compact -offset indent | |
106 | .It Tn "Addresses" . | |
107 | .It Tn "Arguments" . | |
108 | .It Tn "Configuration Declarations (section four only)" . | |
109 | .It Tn "Command Modifier . | |
110 | .It Tn "Defined Variables" . | |
111 | .It Tn "Errno's (Section two only)" . | |
112 | .It Tn "Environment Variables" . | |
113 | .It Tn "Function Argument" . | |
114 | .It Tn "Function Declaration" . | |
115 | .It Tn "Flags" . | |
116 | .It Tn "Functions (library routines)" . | |
117 | .It Tn "Function Types" . | |
118 | .\" .It Tn "Header File (including source code)" . | |
119 | .It Tn "Interactive Commands" . | |
120 | .It Tn "Literals" . | |
121 | .It Tn "Names" . | |
122 | .It Tn "Options" . | |
123 | .It Tn "Pathnames" . | |
124 | .It Tn "Variables" . | |
125 | .It Tn "Cross References" . | |
126 | .El | |
127 | .It | |
128 | .Tn "GENERAL TEXT DOMAIN" | |
129 | .Bl -tag -width flag -compact -offset indent | |
130 | .It Tn "AT&T Macro" . | |
131 | .It Tn "BSD Macro" . | |
132 | .It Tn "UNIX Macro" . | |
133 | .It Tn "Emphasis Macro" . | |
134 | .It Tn "Enclosure/Quoting Macros" | |
135 | .Bl -tag -width flag -compact -offset indent | |
136 | .It Tn "Angle Bracket Quote/Enclosure" . | |
137 | .It Tn "Bracket Quotes/Enclosure" . | |
138 | .It Tn "Double Quote macro/Enclosure" . | |
139 | .It Tn "Parenthesis Quote/Enclosure" . | |
140 | .It Tn "Single Quotes/Enclosure" . | |
141 | .It Tn "Prefix Macro" . | |
142 | .El | |
143 | .It Tn "Extended Arguments" . | |
144 | .It Tn "No\-Op or Normal Text Macro" . | |
145 | .It Tn "No Space Macro" . | |
146 | .It Tn "Section Cross References" . | |
147 | .It Tn "Symbolic Macro" . | |
148 | .It Tn "References and Citations" . | |
149 | .It Tn "Trade Names (Acronyms and Type Names)" . | |
150 | .El | |
151 | .It | |
152 | .Tn "PAGE STRUCTURE DOMAIN" | |
153 | .Bl -tag -width flag -compact -offset indent | |
154 | .It Tn "Section Headers" . | |
155 | .It Tn "Paragraphs and Line Spacing" . | |
156 | .It Tn "Keeps" . | |
157 | .It Tn "Displays" . | |
158 | .It Tn "Lists and Columns" . | |
159 | .El | |
160 | .It | |
161 | .Tn "PREDEFINED STRINGS" | |
162 | .It | |
163 | .Tn "DIAGNOSTICS" | |
164 | .It | |
165 | .Tn "FORMATTING WITH GROFF, TROFF AND NROFF" | |
166 | .It | |
167 | .Tn "BUGS" | |
168 | .El | |
169 | .ne 7 | |
3e2f4ebf | 170 | .Sh TROFF IDIOSYNCRASIES |
c5174ad4 CL |
171 | The |
172 | .Nm \-mdoc | |
173 | package attempts to simplify the process of writing a man page. | |
174 | Theoretically, one should not have to learn the dirty details of | |
3e2f4ebf | 175 | .Xr troff 1 |
c5174ad4 CL |
176 | to use |
177 | .Nm \-mdoc ; | |
178 | however, there are a few | |
3e2f4ebf | 179 | limitations which are unavoidable and best gotten out |
be765ac2 CL |
180 | of the way. |
181 | And, too, be forewarned, this package is | |
c5174ad4 CL |
182 | .Em not |
183 | fast. | |
3e2f4ebf CL |
184 | .Ss Macro Usage |
185 | As in | |
186 | .Xr troff 1 , | |
c5174ad4 CL |
187 | a macro is called by placing a |
188 | .Ql \&\. | |
3e2f4ebf CL |
189 | (dot character) |
190 | at the beginning of | |
191 | a line followed by the two character name for the macro. | |
c5174ad4 | 192 | Arguments may follow the macro separated by spaces. |
3e2f4ebf CL |
193 | It is the dot character at the beginning of the line which causes |
194 | .Xr troff 1 | |
c5174ad4 | 195 | to interpret the next two characters as a macro name. |
3e2f4ebf | 196 | To place a |
c5174ad4 | 197 | .Ql \&\. |
3e2f4ebf CL |
198 | (dot character) |
199 | at the beginning of a line in some context other than | |
be765ac2 | 200 | a macro invocation, precede the |
c5174ad4 | 201 | .Ql \&\. |
be765ac2 CL |
202 | (dot) with the |
203 | .Ql \e& | |
204 | escape sequence. | |
205 | The | |
206 | .Ql \e& | |
207 | translates literally to a zero width space, and is never displayed in the | |
208 | output. | |
c5174ad4 CL |
209 | .Pp |
210 | In general, | |
211 | .Xr troff 1 | |
212 | macros accept up to nine arguments, any | |
213 | extra arguments are ignored. | |
214 | Most macros in | |
215 | .Nm \-mdoc | |
216 | accept nine arguments and, | |
217 | in limited cases, arguments may be continued or extended | |
218 | on the | |
219 | next line (See | |
be765ac2 CL |
220 | .Sx Extensions ) . |
221 | A few macros handle quoted arguments (see | |
c5174ad4 CL |
222 | .Sx Passing Space Characters in an Argument |
223 | below). | |
be765ac2 CL |
224 | .Pp |
225 | Most of the | |
c5174ad4 | 226 | .Nm \-mdoc |
be765ac2 CL |
227 | general text domain and manual domain macros are special |
228 | in that their argument lists are | |
229 | .Em parsed | |
230 | for callable macro names. | |
231 | This means an argument on the argument list which matches | |
232 | a general text or manual domain macro name and is determined | |
233 | to be callable will be executed | |
234 | or called when it is processed. | |
235 | In this case | |
3e2f4ebf CL |
236 | the argument, although the name of a macro, |
237 | is not preceded by a | |
c5174ad4 | 238 | .Ql \&\. |
be765ac2 CL |
239 | (dot). |
240 | It is in this manner that many macros are nested; for | |
c5174ad4 CL |
241 | example |
242 | the option macro, | |
243 | .Ql \&.Op , | |
244 | may | |
3e2f4ebf | 245 | .Em call |
c5174ad4 | 246 | the flag and argument macros, |
be765ac2 | 247 | .Ql \&Fl |
c5174ad4 | 248 | and |
be765ac2 | 249 | .Ql \&Ar , |
c5174ad4 | 250 | to specify an optional flag with an argument: |
c5174ad4 CL |
251 | .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent |
252 | .It Op Fl s Ar bytes | |
3e2f4ebf | 253 | is produced by |
c5174ad4 CL |
254 | .Li \&.Op \&Fl s \&Ar bytes |
255 | .El | |
256 | .Pp | |
257 | To prevent a two character | |
258 | string from being interpreted as a macro name, precede | |
259 | the string with the | |
260 | escape sequence | |
261 | .Ql \e& : | |
b141718f | 262 | .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent |
c5174ad4 CL |
263 | .It Op \&Fl s \&Ar bytes |
264 | is produced by | |
265 | .Li \&.Op \e&Fl s \e&Ar bytes | |
266 | .El | |
3e2f4ebf | 267 | .Pp |
c5174ad4 CL |
268 | Here the strings |
269 | .Ql \&Fl | |
270 | and | |
271 | .Ql \&Ar | |
b141718f CL |
272 | are not interpreted as macros. |
273 | Macros whose argument lists are parsed for callable arguments | |
274 | are referred to | |
275 | as parsed and macros which may be called from an argument | |
276 | list are referred to as callable | |
be765ac2 | 277 | through out this document and in the companion quick reference |
b141718f | 278 | manual |
be765ac2 | 279 | .Xr mdoc 7 . |
b141718f CL |
280 | This is a technical |
281 | .Em faux pas | |
282 | as almost all of the macros in | |
283 | .Nm \-mdoc | |
284 | are parsed, but as it was cumbersome to constantly refer to macros | |
285 | as being callable and being able to call other macros, | |
286 | the term parsed has been used. | |
3e2f4ebf | 287 | .Ss Passing Space Characters in an Argument |
c5174ad4 | 288 | Sometimes it is desirable to give as one argument a string |
be765ac2 CL |
289 | containing one or more blank space characters. |
290 | This may be necessary | |
c5174ad4 CL |
291 | to defeat the nine argument limit or to specify arguments to macros |
292 | which expect particular arrangement of items in the argument list. | |
293 | For example, | |
294 | the function macro | |
295 | .Ql \&.Fn | |
296 | expects the first argument to be the name of a function and any | |
be765ac2 CL |
297 | remaining arguments to be function parameters. |
298 | As | |
c5174ad4 CL |
299 | .Tn "ANSI C" |
300 | stipulates the declaration of function parameters in the | |
301 | parenthesized parameter list, each parameter is guaranteed | |
be765ac2 CL |
302 | to be at minimum a two word string. |
303 | For example, | |
c5174ad4 | 304 | .Fa int foo . |
be765ac2 | 305 | .Pp |
c5174ad4 | 306 | There are two possible ways to pass an argument which contains |
be765ac2 CL |
307 | an embedded space. |
308 | .Em Implementation note : | |
309 | Unfortunately, the most convenient way | |
310 | of passing spaces in between quotes by reassigning individual | |
311 | arguments before parsing was fairly expensive speed wise | |
312 | and space wise to implement in all the macros for | |
313 | .Tn AT&T | |
314 | .Xr troff . | |
315 | It is not expensive for | |
316 | .Xr groff | |
317 | but for the sake of portability, has been limited | |
318 | to the following macros which need | |
c5174ad4 CL |
319 | it the most: |
320 | .Pp | |
321 | .Bl -tag -width 4n -offset indent -compact | |
322 | .It Li \&Cd | |
be765ac2 CL |
323 | Configuration declaration (section 4 |
324 | .Sx SYNOPSIS ) | |
c5174ad4 CL |
325 | .It Li \&Bl |
326 | Begin list (for the width specifier). | |
327 | .It Li \&Em | |
328 | Emphasized text. | |
329 | .It Li \&Fn | |
330 | Functions (sections two and four). | |
331 | .It Li \&It | |
332 | List items. | |
333 | .It Li \&Li | |
334 | Literal text. | |
335 | .It Li \&Sy | |
336 | Symbolic text. | |
337 | .It Li \&%B | |
338 | Book titles. | |
339 | .It Li \&%J | |
340 | Journal names. | |
341 | .It Li \&%O | |
342 | Optional notes for a reference. | |
343 | .It Li \&%R | |
344 | Report title (in a reference). | |
345 | .It Li \&%T | |
346 | Title of article in a book or journal. | |
347 | .El | |
348 | .Pp | |
349 | One way of passing a string | |
350 | containing blank spaces is to use the hard or unpaddable space character | |
351 | .Ql \e\ , | |
be765ac2 | 352 | that is, a blank space preceded by the escape character |
c5174ad4 CL |
353 | .Ql \e . |
354 | This method may be used with any macro but has the side effect | |
355 | of interfering with the adjustment of text | |
356 | over the length of a line. | |
357 | .Xr Troff | |
358 | sees the hard space as if it were any other printable character and | |
359 | cannot split the string into blank or newline separated pieces as one | |
be765ac2 CL |
360 | would expect. |
361 | The method is useful for strings which are not expected | |
362 | to overlap a line boundary. | |
363 | For example: | |
c5174ad4 CL |
364 | .Bl -tag -width "fetch(char *str)" -offset indent |
365 | .It Fn fetch char\ *str | |
3e2f4ebf | 366 | is created by |
c5174ad4 CL |
367 | .Ql \&.Fn fetch char\e *str |
368 | .It Fn fetch "char *str" | |
369 | can also be created by | |
370 | .Ql \&.Fn fetch "\\*q*char *str\\*q" | |
371 | .El | |
372 | .Pp | |
373 | If the | |
374 | .Ql \e | |
375 | or quotes | |
376 | were omitted, | |
377 | .Ql \&.Fn | |
378 | would see three arguments and | |
379 | the result would be: | |
380 | .Pp | |
381 | .Dl Fn fetch char *str | |
382 | .Pp | |
c9a5c681 CL |
383 | For an example of what happens when the parameter list overlaps |
384 | a newline boundary, see the | |
385 | .Sx BUGS | |
386 | section. | |
c5174ad4 CL |
387 | .Ss Trailing Blank Space Characters |
388 | .Xr Troff | |
be765ac2 CL |
389 | can be confused by blank space characters at the end of a line. |
390 | It | |
391 | is a wise preventive measure to globally remove all blank spaces | |
392 | from <blank-space><end-of-line> character sequences. | |
393 | Should the need | |
c5174ad4 CL |
394 | arise to force a blank character at the end of a line, |
395 | it may be forced with an unpaddable space and the | |
396 | .Ql \e& | |
397 | escape character. | |
398 | For example, | |
399 | .Ql string\e\ \e& . | |
3e2f4ebf CL |
400 | .Ss Escaping Special Characters |
401 | Special characters | |
402 | like the newline character | |
c5174ad4 | 403 | .Ql \en , |
3e2f4ebf | 404 | are handled by replacing the |
c5174ad4 | 405 | .Ql \e |
3e2f4ebf | 406 | with |
c5174ad4 | 407 | .Ql \ee |
3e2f4ebf | 408 | (e.g. |
c5174ad4 | 409 | .Ql \een ) |
3e2f4ebf CL |
410 | to preserve |
411 | the backslash. | |
be765ac2 | 412 | .Sh THE ANATOMY OF A MAN PAGE |
c5174ad4 CL |
413 | The body of a man page is easily constructed from a basic |
414 | template found in the file: | |
415 | .Bd -literal -offset indent | |
be765ac2 | 416 | \&.\e" /usr/share/misc/man.template: |
c5174ad4 | 417 | \&.\e" The following six lines are required. |
c5174ad4 | 418 | \&.Dd Month day, year |
be765ac2 CL |
419 | \&.Os OPERATING_SYSTEM [version/release] |
420 | \&.Dt DOCUMENT_TITLE [section number] [volume] | |
c5174ad4 CL |
421 | \&.Sh NAME |
422 | \&.Sh SYNOPSIS | |
423 | \&.Sh DESCRIPTION | |
424 | \&.\e" The following requests should be uncommented and | |
425 | \&.\e" used where appropriate. This next request is | |
426 | \&.\e" for sections 2 and 3 function return values only. | |
427 | \&.\e" .Sh RETURN VALUES | |
428 | \&.\e" This next request is for sections 1, 6, 7 & 8 only | |
429 | \&.\e" .Sh ENVIRONMENT | |
430 | \&.\e" .Sh FILES | |
431 | \&.\e" .Sh EXAMPLES | |
432 | \&.\e" This next request is for sections 1, 6, 7 & 8 only | |
433 | \&.\e" (command return values (to shell) and | |
434 | \&.\e" fprintf/stderr type diagnostics) | |
435 | \&.\e" .Sh DIAGNOSTICS | |
436 | \&.\e" The next request is for sections 2 and 3 error | |
437 | \&.\e" and signal handling only. | |
438 | \&.\e" .Sh ERRORS | |
439 | \&.\e" .Sh SEE ALSO | |
440 | \&.\e" .Sh STANDARDS | |
441 | \&.\e" .Sh HISTORY | |
442 | \&.\e" .Sh AUTHORS | |
443 | \&.\e" .Sh BUGS | |
444 | .Ed | |
445 | .Pp | |
446 | The first items in the template are the macros | |
be765ac2 CL |
447 | .Pq Li \&.Dd , \&.Os , \&.Dt ; |
448 | the document date, | |
449 | the operating system the man page or subject source is developed | |
450 | or modified for, | |
451 | and the man page title | |
452 | .Pq Em in upper case | |
453 | along with the section of the manual the page | |
454 | belongs in. | |
455 | These macros identify the page, | |
c5174ad4 CL |
456 | and are discussed below in |
457 | .Sx TITLE MACROS . | |
458 | .Pp | |
459 | The remaining items in the template are section headers | |
460 | .Pq Li \&.Sh ; | |
be765ac2 CL |
461 | of which |
462 | .Sx NAME , | |
463 | .Sx SYNOPSIS | |
464 | and | |
465 | .Sx DESCRIPTION | |
466 | are mandatory. | |
467 | The | |
c5174ad4 CL |
468 | headers are |
469 | discussed in | |
be765ac2 | 470 | .Sx PAGE STRUCTURE DOMAIN , |
c5174ad4 CL |
471 | after |
472 | presentation of | |
be765ac2 | 473 | .Sx MANUAL DOMAIN . |
c5174ad4 CL |
474 | Several content macros are used to demonstrate page layout macros; |
475 | reading about content macros before page layout macros is | |
476 | recommended. | |
477 | .Sh TITLE MACROS | |
be765ac2 CL |
478 | The title macros are the first portion of the page structure |
479 | domain, but are presented first and separate for someone who | |
480 | wishes to start writing a man page yesterday. | |
3e2f4ebf CL |
481 | Three header macros designate the document title or manual page title, |
482 | the operating system, | |
c5174ad4 | 483 | and the date of authorship. |
3e2f4ebf CL |
484 | These macros are one called once at the very beginning of the document |
485 | and are used to construct the headers and footers only. | |
c5174ad4 CL |
486 | .Bl -tag -width 6n |
487 | .It Li \&.Dt DOCUMENT_TITLE section# [volume] | |
3e2f4ebf | 488 | The document title is the |
be765ac2 CL |
489 | subject of the man page and must be in |
490 | .Tn CAPITALS | |
491 | due to troff | |
3e2f4ebf | 492 | limitations. |
c5174ad4 | 493 | The section number may be 1,\ ...,\ 8, |
3e2f4ebf CL |
494 | and if it is specified, |
495 | the volume title may be omitted. | |
496 | A volume title may be arbitrary or one of the following: | |
497 | .\" .Cl | |
498 | .\" USD UNIX User's Supplementary Documents | |
499 | .\" .Cl | |
be765ac2 | 500 | .\" PS1 UNIX Programmer's Supplementary Documents |
c5174ad4 CL |
501 | .Pp |
502 | .Bl -column SMM -offset indent -compact | |
be765ac2 CL |
503 | .It Li AMD UNIX Ancestral Manual Documents |
504 | .It Li SMM UNIX System Manager's Manual | |
505 | .It Li URM UNIX Reference Manual | |
506 | .It Li PRM UNIX Programmer's Manual | |
c5174ad4 CL |
507 | .El |
508 | .Pp | |
be765ac2 CL |
509 | The default volume labeling is |
510 | .Li URM | |
511 | for sections 1, 6, and 7; | |
512 | .Li SMM | |
513 | for section 8; | |
514 | .Li PRM | |
515 | for sections 2, 3, 4, and 5. | |
3e2f4ebf CL |
516 | .\" .Cl |
517 | .\" MMI UNIX Manual Master Index | |
518 | .\" .Cl | |
519 | .\" CON UNIX Contributed Software Manual | |
520 | .\" .Cl | |
521 | .\" LOC UNIX Local Manual | |
c5174ad4 | 522 | .It Li \&.Os operating_system release# |
3e2f4ebf | 523 | The name of the operating system |
be765ac2 CL |
524 | should be the common acronym, e.g. |
525 | .Tn BSD | |
526 | or | |
527 | .Tn ATT . | |
528 | The release should be the standard release | |
c5174ad4 | 529 | nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3, |
be765ac2 CL |
530 | V.4. |
531 | Unrecognized arguments are displayed as given in the page footer. | |
532 | For instance, a typical footer might be: | |
533 | .Pp | |
534 | .Dl \&.Os BSD 4.3 | |
535 | .Pp | |
536 | or for a locally produced set | |
537 | .Pp | |
538 | .Dl \&.Os CS Department | |
539 | .Pp | |
540 | The Berkeley default, | |
541 | .Ql \&.Os | |
542 | without an argument, has been defined as | |
543 | .Tn BSD | |
544 | Experimental in the | |
545 | site specific file | |
546 | .Pa /usr/src/share/tmac/doc-common . | |
547 | It really should default to | |
548 | .Tn LOCAL . | |
549 | Note, if the | |
550 | .Ql \&.Os | |
551 | macro is not present, the bottom left corner of the page | |
552 | will be ugly. | |
c5174ad4 | 553 | .It Li \&.Dd month day, year |
3e2f4ebf CL |
554 | The date should be written formally: |
555 | .Pp | |
be765ac2 | 556 | .ne 5 |
3e2f4ebf | 557 | .Dl January 25, 1989 |
c5174ad4 | 558 | .El |
be765ac2 | 559 | .Sh MANUAL DOMAIN |
c5174ad4 | 560 | .Ss What's in a name... |
be765ac2 | 561 | The manual domain macro names are derived from the day to day |
c5174ad4 | 562 | informal language used to describe commands, subroutines and related |
be765ac2 CL |
563 | files. |
564 | Slightly | |
c5174ad4 CL |
565 | different variations of this language are used to describe |
566 | the three different aspects of writing a man page. | |
567 | First, there is the description of | |
568 | .Nm \-mdoc | |
569 | macro request usage. | |
570 | Second is the description of a | |
571 | .Ux | |
572 | command | |
573 | .Em with | |
574 | .Nm \-mdoc | |
575 | macros and third, | |
576 | the | |
577 | description a command to a user in the verbal sense; | |
578 | that is, discussion of a command in the text of a man page. | |
579 | .Pp | |
580 | In the first case, | |
581 | .Xr troff 1 | |
582 | macros are themselves a type of command; | |
583 | the general syntax for a troff command is: | |
584 | .Bd -filled -offset indent | |
585 | \&.Va argument1 argument2 ... argument9 | |
586 | .Ed | |
3e2f4ebf | 587 | .Pp |
c5174ad4 CL |
588 | The |
589 | .Ql \&.Va | |
590 | is a macro command or request, and anything following it is an argument to | |
591 | be processed. | |
592 | In the second case, | |
593 | the description of a | |
594 | .Ux | |
595 | command using the content macros is a | |
596 | bit more involved; | |
be765ac2 CL |
597 | a typical |
598 | .Sx SYNOPSIS | |
599 | command line might be displayed as: | |
c5174ad4 CL |
600 | .Bd -filled -offset indent |
601 | .Nm filter | |
602 | .Op Fl flag | |
603 | .Ar infile outfile | |
604 | .Ed | |
605 | .Pp | |
606 | Here, | |
607 | .Nm filter | |
608 | is the command name and the | |
609 | bracketed string | |
610 | .Fl flag | |
611 | is a | |
612 | .Em flag | |
613 | argument designated as optional by the option brackets. | |
614 | In | |
615 | .Nm \-mdoc | |
616 | terms, | |
617 | .Ar infile | |
618 | and | |
619 | .Ar outfile | |
620 | are | |
621 | called | |
622 | .Em arguments . | |
623 | The macros which formatted the above example: | |
c9a5c681 CL |
624 | .Bd -literal -offset indent |
625 | \&.Nm filter | |
626 | \&.Op \&Fl flag | |
627 | \&.Ar infile outfile | |
c5174ad4 CL |
628 | .Ed |
629 | .Pp | |
630 | In the third case, discussion of commands and command syntax | |
be765ac2 CL |
631 | includes both examples above, but may add more detail. |
632 | The | |
c5174ad4 CL |
633 | arguments |
634 | .Ar infile | |
635 | and | |
636 | .Ar outfile | |
be765ac2 | 637 | from the example above might be referred to as |
c5174ad4 CL |
638 | .Em operands |
639 | or | |
640 | .Em file arguments . | |
641 | Some command line argument lists are quite long: | |
c5174ad4 CL |
642 | .Bl -tag -width make -offset indent |
643 | .It Nm make | |
644 | .Op Fl eiknqrstv | |
645 | .Op Fl D Ar variable | |
646 | .Op Fl d Ar flags | |
647 | .Op Fl f Ar makefile | |
be765ac2 | 648 | .Bk -words |
c5174ad4 | 649 | .Op Fl I Ar directory |
be765ac2 | 650 | .Ek |
c5174ad4 CL |
651 | .Op Fl j Ar max_jobs |
652 | .Op Ar variable=value | |
be765ac2 CL |
653 | .Bk -words |
654 | .Op Ar target ... | |
655 | .Ek | |
c5174ad4 CL |
656 | .El |
657 | .Pp | |
658 | Here one might talk about the command | |
659 | .Nm make | |
660 | and qualify the argument | |
661 | .Ar makefile , | |
662 | as an argument to the flag, | |
663 | .Fl f , | |
664 | or discuss the optional | |
665 | file | |
666 | operand | |
667 | .Ar target . | |
668 | In the verbal context, such detail can prevent confusion, | |
669 | however the | |
670 | .Nm \-mdoc | |
671 | package | |
672 | does not have a macro for an argument | |
673 | .Em to | |
674 | a flag. | |
675 | Instead the | |
676 | .Ql \&Ar | |
677 | argument macro is used for an operand or file argument like | |
678 | .Ar target | |
679 | as well as an argument to a flag like | |
be765ac2 CL |
680 | .Ar variable . |
681 | The make command line was produced from: | |
c5174ad4 CL |
682 | .Bd -literal -offset indent |
683 | \&.Nm make | |
684 | \&.Op Fl eiknqrstv | |
685 | \&.Op Fl D Ar variable | |
686 | \&.Op Fl d Ar flags | |
687 | \&.Op Fl f Ar makefile | |
688 | \&.Op Fl I Ar directory | |
689 | \&.Op Fl j Ar max_jobs | |
690 | \&.Op Ar variable=value | |
be765ac2 | 691 | \&.Bk -words |
c5174ad4 | 692 | \&.Op Ar target ... |
be765ac2 | 693 | \&.Ek |
c5174ad4 | 694 | .Ed |
be765ac2 CL |
695 | .Pp |
696 | The | |
697 | .Ql \&.Bk | |
698 | and | |
699 | .Ql \&.Ek | |
b141718f | 700 | macros are explained in |
be765ac2 | 701 | .Sx Keeps . |
c5174ad4 | 702 | .Ss General Syntax |
be765ac2 | 703 | The manual domain and general text domain macros share a similar |
c5174ad4 CL |
704 | syntax with a few minor deviations: |
705 | .Ql \&.Ar , | |
706 | .Ql \&.Fl , | |
707 | .Ql \&.Nm , | |
708 | and | |
709 | .Ql \&.Pa | |
710 | differ only when called without arguments; | |
711 | .Ql \&.Fn | |
712 | and | |
713 | .Ql \&.Xr | |
714 | impose an order on their argument lists | |
715 | and the | |
be765ac2 | 716 | .Ql \&.Op |
c5174ad4 | 717 | and |
be765ac2 | 718 | .Ql \&.Fn |
c5174ad4 | 719 | macros |
be765ac2 CL |
720 | have nesting limitations. |
721 | All content macros | |
722 | are capable of recognizing and properly handling punctuation, | |
723 | provided each punctuation character is separated by a leading space. | |
724 | If an request is given: | |
725 | .Pp | |
726 | .Dl \&.Li sptr, ptr), | |
727 | .Pp | |
728 | The result is: | |
729 | .Pp | |
730 | .Dl Li sptr, ptr), | |
731 | .Pp | |
732 | The punctuation is not recognized and all is output in the | |
733 | literal font. If the punctuation is separated by a leading | |
734 | white space: | |
735 | .Pp | |
736 | .Dl \&.Li "sptr , ptr ) ," | |
737 | .Pp | |
738 | The result is: | |
739 | .Pp | |
740 | .Dl Li sptr , ptr ) , | |
741 | .Pp | |
742 | The punctuation is now recognized and is output in the | |
743 | default font distinguishing it from the strings in literal font. | |
744 | .Pp | |
745 | To remove the special meaning from a punctuation character | |
746 | escape it with | |
747 | .Ql \e& . | |
748 | .Xr Troff | |
749 | is limited as a macro language, and has difficulty | |
750 | when presented with a string containing | |
751 | a member of the mathematical, logical or | |
c5174ad4 | 752 | quotation set: |
be765ac2 CL |
753 | .Bd -literal -offset indent-two |
754 | \&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"} | |
c5174ad4 | 755 | .Ed |
be765ac2 CL |
756 | .Pp |
757 | The problem is that | |
758 | .Xr troff | |
759 | may assume it is supposed to actually perform the operation | |
760 | or evaluation suggested by the characters. To prevent | |
761 | the accidental evaluation of these characters, | |
762 | escape them with | |
c5174ad4 CL |
763 | .Ql \e& . |
764 | Typical syntax is shown in the first content macro displayed | |
765 | below, | |
be765ac2 | 766 | .Ql \&.Ad . |
c5174ad4 | 767 | .Ss Address Macro |
be765ac2 | 768 | The address macro identifies an address construct |
3e2f4ebf CL |
769 | of the form addr1[,addr2[,addr3]]. |
770 | .Pp | |
c5174ad4 CL |
771 | .Dl Usage: .Ad address ... \*(Pu |
772 | .Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n | |
773 | .It Li \&.Ad addr1 | |
3e2f4ebf | 774 | .Ad addr1 |
c5174ad4 | 775 | .It Li \&.Ad addr1\ . |
3e2f4ebf | 776 | .Ad addr1 . |
c5174ad4 | 777 | .It Li \&.Ad addr1\ , file2 |
3e2f4ebf | 778 | .Ad addr1 , file2 |
c5174ad4 | 779 | .It Li \&.Ad f1\ , f2\ , f3\ : |
3e2f4ebf | 780 | .Ad f1 , f2 , f3 : |
c5174ad4 | 781 | .It Li \&.Ad addr\ )\ )\ , |
3e2f4ebf | 782 | .Ad addr ) ) , |
c5174ad4 CL |
783 | .El |
784 | .Pp | |
3e2f4ebf CL |
785 | It is an error to call |
786 | .Li \&.Ad | |
787 | without arguments. | |
c5174ad4 | 788 | .Li \&.Ad |
b141718f | 789 | is callable by other macros and is parsed. |
c5174ad4 | 790 | .Ss Argument Macro |
3e2f4ebf CL |
791 | The |
792 | .Li \&.Ar | |
c5174ad4 | 793 | argument macro may be used whenever |
3e2f4ebf CL |
794 | a command line argument is referenced. |
795 | .Pp | |
796 | .Dl Usage: .Ar argument ... \*(Pu | |
c5174ad4 CL |
797 | .Bl -tag -width ".Ar file1 file2" -compact -offset 15n |
798 | .It Li \&.Ar | |
3e2f4ebf | 799 | .Ar |
c5174ad4 | 800 | .It Li \&.Ar file1 |
3e2f4ebf | 801 | .Ar file1 |
c5174ad4 | 802 | .It Li \&.Ar file1\ . |
3e2f4ebf | 803 | .Ar file1 . |
c5174ad4 | 804 | .It Li \&.Ar file1 file2 |
3e2f4ebf | 805 | .Ar file1 file2 |
c5174ad4 | 806 | .It Li \&.Ar f1 f2 f3\ : |
3e2f4ebf | 807 | .Ar f1 f2 f3 : |
c5174ad4 | 808 | .It Li \&.Ar file\ )\ )\ , |
3e2f4ebf | 809 | .Ar file ) ) , |
c5174ad4 | 810 | .El |
3e2f4ebf CL |
811 | .Pp |
812 | If | |
813 | .Li \&.Ar | |
c5174ad4 CL |
814 | is called without arguments |
815 | .Ql Ar | |
be765ac2 CL |
816 | is assumed. |
817 | The | |
3e2f4ebf | 818 | .Li \&.Ar |
b141718f | 819 | macro is parsed and is callable. |
c5174ad4 | 820 | .Ss Configuration Declaration (section four only) |
3e2f4ebf | 821 | The |
c5174ad4 CL |
822 | .Ql \&.Cd |
823 | macro is used to demonstrate a | |
824 | .Xr config 8 | |
825 | declaration for a device interface in a section four manual. | |
826 | This macro accepts quoted arguments (double quotes only). | |
827 | .Pp | |
828 | .Bl -tag -width "device le0 at scode?" -offset indent | |
829 | .It Cd "device le0 at scode?" | |
830 | produced by: | |
831 | .Ql ".Cd device le0 at scode?" . | |
832 | .El | |
833 | .Ss Command Modifier | |
834 | The command modifier is identical to the | |
835 | .Ql \&.Fl | |
836 | (flag) command with the exception | |
837 | the | |
838 | .Ql \&.Cm | |
839 | macro does not assert a dash | |
be765ac2 CL |
840 | in front of every argument. |
841 | Traditionally flags are marked by the | |
c5174ad4 CL |
842 | preceding dash, some commands or subsets of commands do not use them. |
843 | Command modifiers may also be specified in conjunction with interactive | |
844 | commands such as editor commands. | |
845 | See | |
846 | .Sx Flags . | |
c5174ad4 CL |
847 | .Ss Defined Variables |
848 | A variable which is defined in an include file is specified | |
849 | by the macro | |
850 | .Ql \&.Dv . | |
851 | .Pp | |
852 | .Dl Usage: .Dv defined_variable ... \*(Pu | |
853 | .Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n | |
854 | .It Li ".Dv MAXHOSTNAMELEN" | |
855 | .Dv MAXHOSTNAMELEN | |
856 | .It Li ".Dv TIOCGPGRP )" | |
857 | .Dv TIOCGPGRP ) | |
858 | .El | |
859 | .Pp | |
860 | It is an error to call | |
861 | .Ql \&.Dv | |
862 | without arguments. | |
863 | .Ql \&.Dv | |
b141718f | 864 | is parsed and is callable. |
c5174ad4 | 865 | .Ss Errno's (Section two only) |
3e2f4ebf | 866 | The |
c5174ad4 CL |
867 | .Ql \&.Er |
868 | errno macro specifies the error return value | |
be765ac2 CL |
869 | for section two library routines. |
870 | The second example | |
3e2f4ebf | 871 | below shows |
c5174ad4 | 872 | .Ql \&.Er |
3e2f4ebf | 873 | used with the |
c5174ad4 | 874 | .Ql \&.Bq |
be765ac2 | 875 | general text domain macro, as it would be used in |
c5174ad4 | 876 | a section two manual page. |
3e2f4ebf CL |
877 | .Pp |
878 | .Dl Usage: .Er ERRNOTYPE ... \*(Pu | |
c5174ad4 CL |
879 | .Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n |
880 | .It Li \&.Er ENOENT | |
3e2f4ebf | 881 | .Er ENOENT |
c5174ad4 CL |
882 | .It Li \&.Er ENOENT\ )\ ; |
883 | .Er ENOENT ) ; | |
884 | .It Li \&.Bq \&Er ENOTDIR | |
885 | .Bq Er ENOTDIR | |
886 | .El | |
3e2f4ebf CL |
887 | .Pp |
888 | It is an error to call | |
c5174ad4 | 889 | .Ql \&.Er |
3e2f4ebf | 890 | without arguments. |
c5174ad4 CL |
891 | The |
892 | .Ql \&.Er | |
b141718f | 893 | macro is parsed and is callable. |
3e2f4ebf CL |
894 | .Ss Environment Variables |
895 | The | |
c5174ad4 CL |
896 | .Ql \&.Ev |
897 | macro specifies a environment variable. | |
3e2f4ebf CL |
898 | .Pp |
899 | .Dl Usage: .Ev argument ... \*(Pu | |
c5174ad4 CL |
900 | .Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n |
901 | .It Li \&.Ev DISPLAY | |
3e2f4ebf | 902 | .Ev DISPLAY |
c5174ad4 | 903 | .It Li \&.Ev PATH\ . |
3e2f4ebf | 904 | .Ev PATH . |
c5174ad4 | 905 | .It Li \&.Ev PRINTER\ )\ )\ , |
3e2f4ebf | 906 | .Ev PRINTER ) ) , |
c5174ad4 | 907 | .El |
3e2f4ebf CL |
908 | .Pp |
909 | It is an error to call | |
c5174ad4 | 910 | .Ql \&.Ev |
3e2f4ebf | 911 | without arguments. |
c5174ad4 CL |
912 | The |
913 | .Ql \&.Ev | |
b141718f | 914 | macro is parsed and is callable. |
c5174ad4 CL |
915 | .Ss Function Argument |
916 | The | |
917 | .Ql \&.Fa | |
918 | macro is used to refer to function arguments (parameters) | |
be765ac2 CL |
919 | outside of the |
920 | .Sx SYNOPSIS | |
921 | section of the manual or inside | |
922 | the | |
923 | .Sx SYNOPSIS | |
924 | section should a parameter list be too | |
c5174ad4 CL |
925 | long for the |
926 | .Ql \&.Fn | |
927 | macro and the enclosure macros | |
928 | .Ql \&.Fo | |
929 | and | |
930 | .Ql \&.Fc | |
931 | must be used. | |
932 | .Ql \&.Fa | |
933 | may also be used to refer to structure members. | |
934 | .Pp | |
935 | .Dl Usage: .Fa function_argument ... \*(Pu | |
936 | .Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n | |
937 | .It Li \&.Fa d_namlen\ )\ )\ , | |
938 | .Fa d_namlen ) ) , | |
939 | .It Li \&.Fa iov_len | |
940 | .Fa iov_len | |
941 | .El | |
942 | .Pp | |
943 | It is an error to call | |
944 | .Ql \&.Fa | |
945 | without arguments. | |
946 | .Ql \&.Fa | |
b141718f | 947 | is parsed and is callable. |
c5174ad4 CL |
948 | .Ss Function Declaration |
949 | The | |
950 | .Ql \&.Fd | |
be765ac2 CL |
951 | macro is used in the |
952 | .Sx SYNOPSIS | |
953 | section with section two or three | |
954 | functions. | |
955 | The | |
c5174ad4 CL |
956 | .Ql \&.Fd |
957 | macro does not call other macros and is not callable by other | |
958 | macros. | |
959 | .Pp | |
960 | .Dl Usage: .Fd include_file (or defined variable) | |
961 | .Pp | |
be765ac2 CL |
962 | In the |
963 | .Sx SYNOPSIS | |
964 | section a | |
c5174ad4 CL |
965 | .Ql \&.Fd |
966 | request causes a line break if a function has already been presented | |
be765ac2 CL |
967 | and a break has not occurred. |
968 | This leaves a nice vertical space | |
c5174ad4 CL |
969 | in between the previous function call and the declaration for the |
970 | next function. | |
3e2f4ebf CL |
971 | .Ss Flags |
972 | The | |
c5174ad4 | 973 | .Ql \&.Fl |
be765ac2 CL |
974 | macro handles command line flags. |
975 | It prepends | |
3e2f4ebf | 976 | a dash, |
c5174ad4 | 977 | .Ql \- , |
be765ac2 CL |
978 | to the flag. |
979 | For interactive command flags, which | |
3e2f4ebf | 980 | are not prepended with a dash, the |
c5174ad4 CL |
981 | .Ql \&.Cm |
982 | (command modifier) | |
983 | macro is identical, but with out the dash. | |
3e2f4ebf CL |
984 | .Pp |
985 | .Dl Usage: .Fl argument ... \*(Pu | |
c5174ad4 CL |
986 | .Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n |
987 | .It Li \&.Fl | |
3e2f4ebf | 988 | .Fl |
c5174ad4 | 989 | .It Li \&.Fl cfv |
3e2f4ebf | 990 | .Fl cfv |
c5174ad4 | 991 | .It Li \&.Fl cfv\ . |
3e2f4ebf | 992 | .Fl cfv . |
c5174ad4 | 993 | .It Li \&.Fl s v t |
3e2f4ebf | 994 | .Fl s v t |
c5174ad4 | 995 | .It Li \&.Fl -\ , |
3e2f4ebf | 996 | .Fl - , |
c5174ad4 | 997 | .It Li \&.Fl xyz\ )\ , |
3e2f4ebf | 998 | .Fl xyz ) , |
c5174ad4 | 999 | .El |
3e2f4ebf CL |
1000 | .Pp |
1001 | The | |
c5174ad4 CL |
1002 | .Ql \&.Fl |
1003 | macro without any arguments results | |
1004 | in a dash representing stdin/stdout. | |
3e2f4ebf | 1005 | Note that giving |
c5174ad4 | 1006 | .Ql \&.Fl |
3e2f4ebf | 1007 | a single dash, will result in two dashes. |
c5174ad4 CL |
1008 | The |
1009 | .Ql \&.Fl | |
b141718f | 1010 | macro is parsed and is callable. |
3e2f4ebf | 1011 | .Ss Functions (library routines) |
c5174ad4 CL |
1012 | The .Fn macro is modeled on ANSI C conventions. |
1013 | .Bd -literal | |
be765ac2 | 1014 | Usage: .Fn [type] function [[type] parameters ... \*(Pu] |
c5174ad4 | 1015 | .Ed |
c9a5c681 | 1016 | .Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact |
c5174ad4 | 1017 | .It Li "\&.Fn getchar" |
3e2f4ebf | 1018 | .Fn getchar |
c5174ad4 | 1019 | .It Li "\&.Fn strlen ) ," |
3e2f4ebf | 1020 | .Fn strlen ) , |
c5174ad4 CL |
1021 | .It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , |
1022 | .Fn "int align" "const * char *sptrs" , | |
1023 | .El | |
3e2f4ebf CL |
1024 | .Pp |
1025 | It is an error to call | |
c5174ad4 | 1026 | .Ql \&.Fn |
3e2f4ebf | 1027 | without any arguments. |
c5174ad4 CL |
1028 | The |
1029 | .Ql \&.Fn | |
1030 | macro | |
be765ac2 | 1031 | is parsed and is callable, |
c5174ad4 CL |
1032 | note that any call to another macro signals the end of |
1033 | the | |
1034 | .Ql \&.Fn | |
be765ac2 CL |
1035 | call (it will close-parenthesis at that point). |
1036 | .Pp | |
1037 | For functions that have more than eight parameters (and this | |
1038 | is rare), the | |
1039 | macros | |
1040 | .Ql \&.Fo | |
1041 | (function open) | |
1042 | and | |
1043 | .Ql \&.Fc | |
1044 | (function close) | |
1045 | may be used with | |
1046 | .Ql \&.Fa | |
1047 | (function argument) | |
1048 | to get around the limitation. For example: | |
1049 | .Bd -literal -offset indent | |
1050 | \&.Fo "int res_mkquery" | |
1051 | \&.Fa "int op" | |
1052 | \&.Fa "char *dname" | |
1053 | \&.Fa "int class" | |
1054 | \&.Fa "int type" | |
1055 | \&.Fa "char *data" | |
1056 | \&.Fa "int datalen" | |
1057 | \&.Fa "struct rrec *newrr" | |
1058 | \&.Fa "char *buf" | |
1059 | \&.Fa "int buflen" | |
1060 | \&.Fc | |
1061 | .Ed | |
1062 | .Pp | |
1063 | Produces: | |
1064 | .Bd -filled -offset indent | |
1065 | .Fo "int res_mkquery" | |
1066 | .Fa "int op" | |
1067 | .Fa "char *dname" | |
1068 | .Fa "int class" | |
1069 | .Fa "int type" | |
1070 | .Fa "char *data" | |
1071 | .Fa "int datalen" | |
1072 | .Fa "struct rrec *newrr" | |
1073 | .Fa "char *buf" | |
1074 | .Fa "int buflen" | |
1075 | .Fc | |
1076 | .Ed | |
c5174ad4 | 1077 | .Pp |
be765ac2 CL |
1078 | The |
1079 | .Ql \&.Fo | |
1080 | and | |
1081 | .Ql \&.Fc | |
1082 | macros are parsed and are callable. | |
1083 | In the | |
1084 | .Sx SYNOPSIS | |
1085 | section, the function will always begin at | |
1086 | the beginning of line. | |
1087 | If there is more than one function | |
1088 | presented in the | |
1089 | .Sx SYNOPSIS | |
1090 | section and a function type has not been | |
c5174ad4 CL |
1091 | given, a line break will occur, leaving a nice vertical space |
1092 | between the current function name and the one prior. | |
3e2f4ebf | 1093 | At the moment, |
c5174ad4 | 1094 | .Ql \&.Fn |
3e2f4ebf | 1095 | does not check its word boundaries |
c5174ad4 | 1096 | against troff line lengths and may split across a newline |
be765ac2 CL |
1097 | ungracefully. |
1098 | This will be fixed in the near future. | |
c5174ad4 | 1099 | .Ss Function Type |
be765ac2 CL |
1100 | This macro is intended for the |
1101 | .Sx SYNOPSIS | |
1102 | section. | |
1103 | It may be used | |
1104 | anywhere else in the man page without problems, but its main purpose | |
1105 | is to present the function type in kernel normal form for the | |
1106 | .Sx SYNOPSIS | |
c5174ad4 CL |
1107 | of sections two and three |
1108 | (it causes a page break allowing the function name to appear | |
1109 | on the next line). | |
1110 | .Pp | |
1111 | .Dl Usage: .Ft type ... \*(Pu | |
c5174ad4 CL |
1112 | .Bl -tag -width "\&.Ft struct stat" -offset 14n -compact |
1113 | .It Li \&.Ft struct stat | |
1114 | .Ft struct stat | |
1115 | .El | |
1116 | .Pp | |
3e2f4ebf | 1117 | The |
c5174ad4 CL |
1118 | .Ql \&.Ft |
1119 | request is not callable by other macros. | |
1120 | .Ss Interactive Commands | |
1121 | The | |
1122 | .Ql \&.Ic | |
1123 | macro designates an interactive or internal command. | |
1124 | .Pp | |
1125 | .Dl Usage: .Li argument ... \*(Pu | |
b141718f | 1126 | .Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n |
c5174ad4 CL |
1127 | .It Li \&.Ic :wq |
1128 | .Ic :wq | |
1129 | .It Li \&.Ic do while {...} | |
1130 | .Ic do while {...} | |
1131 | .It Li \&.Ic setenv\ , unsetenv | |
1132 | .Ic setenv , unsetenv | |
1133 | .El | |
1134 | .Pp | |
1135 | It is an error to call | |
1136 | .Ql \&.Ic | |
1137 | without arguments. | |
1138 | The | |
1139 | .Ql \&.Ic | |
b141718f | 1140 | macro is parsed and is callable. |
3e2f4ebf CL |
1141 | .Ss Literals |
1142 | The | |
c5174ad4 CL |
1143 | .Ql \&.Li |
1144 | literal macro may be used for special characters, | |
3e2f4ebf CL |
1145 | variable constants, anything which should be displayed as it |
1146 | would be typed. | |
1147 | .Pp | |
1148 | .Dl Usage: .Li argument ... \*(Pu | |
c5174ad4 CL |
1149 | .Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n |
1150 | .It Li \&.Li \een | |
3e2f4ebf | 1151 | .Li \en |
c5174ad4 | 1152 | .It Li \&.Li M1 M2 M3\ ; |
3e2f4ebf | 1153 | .Li M1 M2 M3 ; |
c5174ad4 | 1154 | .It Li \&.Li cntrl-D\ )\ , |
3e2f4ebf | 1155 | .Li cntrl-D ) , |
c5174ad4 | 1156 | .It Li \&.Li 1024\ ... |
3e2f4ebf | 1157 | .Li 1024 ... |
c5174ad4 | 1158 | .El |
3e2f4ebf | 1159 | .Pp |
3e2f4ebf | 1160 | The |
c5174ad4 | 1161 | .Ql \&.Li |
b141718f | 1162 | macro is parsed and is callable. |
c5174ad4 CL |
1163 | .Ss Name Macro |
1164 | The | |
1165 | .Ql \&.Nm | |
1166 | macro is used for the document title or subject name. | |
1167 | It has the peculiarity of remembering the first | |
3e2f4ebf | 1168 | argument it was called with, which should |
be765ac2 CL |
1169 | always be the subject name of the page. |
1170 | When called without | |
3e2f4ebf | 1171 | arguments, |
c5174ad4 | 1172 | .Ql \&.Nm |
3e2f4ebf CL |
1173 | regurgitates this initial name for the sole purpose |
1174 | of making less work for the author. | |
c5174ad4 CL |
1175 | Note: |
1176 | a section two | |
3e2f4ebf | 1177 | or three document function name is addressed with the |
c5174ad4 | 1178 | .Ql \&.Nm |
be765ac2 CL |
1179 | in the |
1180 | .Sx NAME | |
1181 | section, and with | |
c5174ad4 | 1182 | .Ql \&.Fn |
be765ac2 CL |
1183 | in the |
1184 | .Sx SYNOPSIS | |
c5174ad4 | 1185 | and remaining sections. |
3e2f4ebf | 1186 | For interactive commands, such as the |
c5174ad4 | 1187 | .Ql while |
3e2f4ebf CL |
1188 | command keyword in |
1189 | .Xr csh 1 , | |
1190 | the | |
c5174ad4 CL |
1191 | .Ql \&.Ic |
1192 | macro should be used. | |
3e2f4ebf | 1193 | While the |
c5174ad4 | 1194 | .Ql \&.Ic |
3e2f4ebf CL |
1195 | is nearly identical |
1196 | to | |
c5174ad4 | 1197 | .Ql \&.Nm , |
3e2f4ebf CL |
1198 | it can not recall the first argument it was invoked with. |
1199 | .Pp | |
1200 | .Dl Usage: .Nm argument ... \*(Pu | |
c5174ad4 CL |
1201 | .Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n |
1202 | .It Li \&.Nm mdoc.sample | |
3e2f4ebf | 1203 | .Nm mdoc.sample |
b141718f | 1204 | .It Li \&.Nm \e-mdoc |
3e2f4ebf | 1205 | .Nm \-mdoc . |
c5174ad4 | 1206 | .It Li \&.Nm foo\ )\ )\ , |
3e2f4ebf | 1207 | .Nm foo ) ) , |
c5174ad4 | 1208 | .It Li \&.Nm |
3e2f4ebf | 1209 | .Nm |
c5174ad4 | 1210 | .El |
3e2f4ebf CL |
1211 | .Pp |
1212 | The | |
c5174ad4 | 1213 | .Ql \&.Nm |
b141718f | 1214 | macro is parsed and is callable. |
be765ac2 | 1215 | .Ss Options |
c5174ad4 CL |
1216 | The |
1217 | .Ql \&.Op | |
1218 | macro | |
1219 | places option brackets around the any remaining arguments on the command | |
1220 | line, and places any | |
be765ac2 CL |
1221 | trailing punctuation outside the brackets. |
1222 | The macros | |
c5174ad4 CL |
1223 | .Ql \&.Oc |
1224 | and | |
1225 | .Ql \&.Oo | |
1226 | may be used across one or more lines. | |
1227 | .Pp | |
1228 | .Dl Usage: .Op options ... \*(Pu | |
1229 | .Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent | |
1230 | .It Li \&.Op | |
1231 | .Op | |
1232 | .It Li ".Op Fl k" | |
1233 | .Op Fl k | |
1234 | .It Li ".Op Fl k ) ." | |
1235 | .Op Fl k ) . | |
1236 | .It Li ".Op Fl k Ar kookfile" | |
1237 | .Op Fl k Ar kookfile | |
1238 | .It Li ".Op Fl k Ar kookfile ," | |
1239 | .Op Fl k Ar kookfile , | |
1240 | .It Li ".Op Ar objfil Op Ar corfil" | |
1241 | .Op Ar objfil Op Ar corfil | |
1242 | .It Li ".Op Fl c Ar objfil Op Ar corfil ," | |
1243 | .Op Fl c Ar objfil Op Ar corfil , | |
1244 | .It Li \&.Op word1 word2 | |
1245 | .Op word1 word2 | |
1246 | .El | |
1247 | .Pp | |
1248 | The | |
1249 | .Ql \&.Oc | |
1250 | and | |
1251 | .Ql \&.Oo | |
1252 | macros: | |
1253 | .Bd -literal -offset indent | |
1254 | \&.Oo | |
1255 | \&.Op \&Fl k \&Ar kilobytes | |
1256 | \&.Op \&Fl i \&Ar interval | |
1257 | \&.Op \&Fl c \&Ar count | |
1258 | \&.Oc | |
1259 | .Ed | |
1260 | .Pp | |
1261 | Produce: | |
1262 | .Oo | |
1263 | .Op Fl k Ar kilobytes | |
1264 | .Op Fl i Ar interval | |
1265 | .Op Fl c Ar count | |
1266 | .Oc | |
1267 | .Pp | |
1268 | The macros | |
1269 | .Ql \&.Op , | |
1270 | .Ql \&.Oc | |
1271 | and | |
1272 | .Ql \&.Oo | |
b141718f | 1273 | are parsed and are callable. |
3e2f4ebf CL |
1274 | .Ss Pathnames |
1275 | The | |
c5174ad4 CL |
1276 | .Ql \&.Pa |
1277 | macro formats path or file names. | |
3e2f4ebf CL |
1278 | .Pp |
1279 | .Dl Usage: .Pa pathname \*(Pu | |
c5174ad4 CL |
1280 | .Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n |
1281 | .It Li \&.Pa /usr/share | |
3e2f4ebf | 1282 | .Pa /usr/share |
c5174ad4 | 1283 | .It Li \&.Pa /tmp/fooXXXXX\ )\ . |
3e2f4ebf | 1284 | .Pa /tmp/fooXXXXX ) . |
c5174ad4 | 1285 | .El |
3e2f4ebf | 1286 | .Pp |
c5174ad4 CL |
1287 | The |
1288 | .Ql \&.Pa | |
b141718f | 1289 | macro is parsed and is callable. |
be765ac2 CL |
1290 | .Ss Variables |
1291 | Generic variable reference: | |
1292 | .Pp | |
1293 | .Dl Usage: .Va variable ... \*(Pu | |
1294 | .Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n | |
1295 | .It Li \&.Va count | |
1296 | .Va count | |
1297 | .It Li \&.Va settimer , | |
1298 | .Va settimer , | |
1299 | .It Li \&.Va int\ *prt\ )\ : | |
1300 | .Va int\ *prt ) : | |
1301 | .It Li \&.Va char\ s\ ]\ )\ )\ , | |
1302 | .Va char\ s ] ) ) , | |
1303 | .El | |
1304 | .Pp | |
1305 | It is an error to call | |
1306 | .Ql \&.Va | |
1307 | without any arguments. | |
1308 | The | |
1309 | .Ql \&.Va | |
b141718f | 1310 | macro is parsed and is callable. |
be765ac2 CL |
1311 | .Ss Manual Page Cross References |
1312 | The | |
1313 | .Ql \&.Xr | |
1314 | macro expects the first argument to be | |
1315 | a manual page name, and the second argument, if it exists, | |
1316 | to be either a section page number or punctuation. | |
1317 | Any | |
1318 | remaining arguments are assumed to be punctuation. | |
1319 | .Pp | |
1320 | .Dl Usage: .Xr man_page [1,...,8] \*(Pu | |
1321 | .Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n | |
1322 | .It Li \&.Xr mdoc | |
1323 | .Xr mdoc | |
1324 | .It Li \&.Xr mdoc\ , | |
1325 | .Xr mdoc , | |
1326 | .It Li \&.Xr mdoc 7 | |
1327 | .Xr mdoc 7 | |
1328 | .It Li \&.Xr mdoc 7\ )\ )\ , | |
1329 | .Xr mdoc 7 ) ) , | |
1330 | .El | |
1331 | .Pp | |
c5174ad4 | 1332 | The |
be765ac2 | 1333 | .Ql \&.Xr |
b141718f | 1334 | macro is parsed and is callable. |
be765ac2 CL |
1335 | It is an error to call |
1336 | .Ql \&.Xr | |
1337 | without | |
1338 | any arguments. | |
1339 | .Sh GENERAL TEXT DOMAIN | |
1340 | .Ss AT&T Macro | |
1341 | .Bd -literal -offset indent -compact | |
1342 | Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu | |
1343 | .Ed | |
1344 | .Bl -tag -width ".At v6 ) ," -compact -offset 14n | |
1345 | .It Li ".At" | |
1346 | .At | |
1347 | .It Li ".At v6 ." | |
1348 | .At v6 . | |
1349 | .El | |
1350 | .Pp | |
1351 | The | |
1352 | .Ql \&.At | |
1353 | macro is | |
1354 | .Em not | |
1355 | parsed and | |
1356 | .Em not | |
1357 | callable. It accepts at most two arguments. | |
1358 | .Ss BSD Macro | |
1359 | .Dl Usage: .Bx [Version/release] ... \*(Pu | |
1360 | .Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n | |
1361 | .It Li ".Bx" | |
1362 | .Bx | |
1363 | .It Li ".Bx 4.3 ." | |
1364 | .Bx 4.3 . | |
1365 | .El | |
1366 | .Pp | |
1367 | The | |
1368 | .Ql \&.Bx | |
1369 | macro is parsed and is callable. | |
1370 | .Ss UNIX Macro | |
1371 | .Dl Usage: .Ux ... \*(Pu | |
1372 | .Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n | |
1373 | .It Li ".Ux" | |
1374 | .Ux | |
1375 | .El | |
1376 | .Pp | |
1377 | The | |
1378 | .Ql \&.Ux | |
1379 | macro is parsed and is callable. | |
1380 | .Ss Emphasis Macro | |
1381 | Text may be stressed or emphasized with the | |
1382 | .Ql \&.Em | |
1383 | macro. | |
1384 | The usual font for emphasis is italic. | |
1385 | .Pp | |
1386 | .Dl Usage: .Em argument ... \*(Pu | |
1387 | .Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n | |
1388 | .It Li ".Em does not" | |
1389 | .Em does not | |
1390 | .It Li ".Em exceed 1024 ." | |
1391 | .Em exceed 1024 . | |
1392 | .It Li ".Em vide infra ) ) ," | |
1393 | .Em vide infra ) ) , | |
1394 | .El | |
be765ac2 | 1395 | .\" .Pp |
b141718f CL |
1396 | .\" The emphasis can be forced across several lines of text by using |
1397 | .\" the | |
1398 | .\" .Ql \&.Bf | |
1399 | .\" macro discussed in | |
1400 | .\" .Sx Modes | |
1401 | .\" under | |
1402 | .\" .Sx PAGE STRUCTURE DOMAIN . | |
1403 | .\" .Pp | |
1404 | .\" .Bf -emphasis | |
be765ac2 CL |
1405 | .\" We are certain the reason most people desire a Harvard MBA |
1406 | .\" so they can become to be successful philanthropists. Only | |
1407 | .\" mathematicians and physicists go to graduate school strictly | |
1408 | .\" to acquire infinite wealthy and fame. Its that inifinity | |
1409 | .\" word that does it to them. Ruins them. | |
b141718f | 1410 | .\" .Ef |
be765ac2 CL |
1411 | .Pp |
1412 | The | |
1413 | .Ql \&.Em | |
b141718f | 1414 | macro is parsed and is callable. |
be765ac2 CL |
1415 | It is an error to call |
1416 | .Ql \&.Em | |
1417 | without arguments. | |
1418 | .Ss Enclosure and Quoting Macros | |
1419 | The concept of enclosure is similar to quoting. | |
1420 | The object being to enclose one or more strings between | |
1421 | a pair of characters like quotes or parentheses. | |
1422 | The terms quoting and enclosure are used | |
1423 | interchangeably throughout this document. | |
1424 | Most of the | |
1425 | one line enclosure macros end | |
1426 | end in small letter | |
1427 | .Ql q | |
1428 | to give a hint of quoting, but there are a few irregularities. | |
1429 | For each enclosure macro | |
1430 | there is also a pair of open and close macros which end | |
1431 | in small letters | |
1432 | .Ql o | |
1433 | and | |
1434 | .Ql c | |
1435 | respectively. | |
1436 | These can be used across one or more lines of text | |
1437 | and while they have nesting limitations, the one line quote macros | |
1438 | can be used inside | |
1439 | of them. | |
be765ac2 | 1440 | .Pp |
b141718f | 1441 | .ne 5 |
be765ac2 CL |
1442 | .Bd -filled -offset indent |
1443 | .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX | |
1444 | .Em " Quote Close Open Function Result" | |
1445 | \&.Aq .Ac .Ao Angle Bracket Enclosure <string> | |
1446 | \&.Bq .Bc .Bo Bracket Enclosure [string] | |
1447 | \&.Dq .Dc .Do Double Quote ``string'' | |
1448 | .Ec .Eo Enclose String (in XX) XXstringXX | |
1449 | \&.Pq .Pc .Po Parenthesis Enclosure (string) | |
1450 | \&.Ql Quoted Literal `st' or string | |
1451 | \&.Qq .Qc .Qo Straight Double Quote "string" | |
1452 | \&.Sq .Sc .So Single Quote `string' | |
1453 | .El | |
1454 | .Ed | |
1455 | .Pp | |
b141718f | 1456 | Except for the irregular macros noted below, all |
be765ac2 CL |
1457 | of the quoting macros are parsed and callable. |
1458 | All handle punctuation properly, as long as it | |
1459 | is presented one character at a time and separated by spaces. | |
1460 | The quoting macros examine opening and closing punctuation | |
1461 | to determine whether it comes before or after the | |
1462 | enclosing string. This makes some nesting possible. | |
1463 | .Bl -tag -width xxx,xxxx | |
1464 | .It Li \&.Ec , \&.Eo | |
1465 | These macros expect the first argument to be the | |
1466 | opening and closing strings respectively. | |
1467 | .It Li \&.Ql | |
1468 | The quoted literal macro behaves differently for | |
1469 | .Xr troff | |
1470 | than | |
1471 | .Xr nroff . | |
1472 | If formatted with | |
1473 | .Xr nroff , | |
1474 | a quoted literal is always quoted. If formatted with | |
1475 | troff, an item is only quoted if the width | |
1476 | of the item is less than three constant width characters. | |
1477 | This is to make short strings more visible where the font change | |
1478 | to literal (constant width) is less noticeable. | |
1479 | .It Li \&.Pf | |
1480 | The prefix macro is not callable, but it is parsed: | |
b141718f CL |
1481 | .Bl -tag -width "(namexx" -offset indent |
1482 | .It Li ".Pf ( Fa name2" | |
c5174ad4 | 1483 | becomes |
be765ac2 | 1484 | .Pf ( Fa name2 . |
b141718f CL |
1485 | .El |
1486 | .Pp | |
be765ac2 CL |
1487 | The |
1488 | .Ql \&.Ns | |
1489 | (no space) macro performs the analogous suffix function. | |
c5174ad4 CL |
1490 | .El |
1491 | .Pp | |
be765ac2 CL |
1492 | .ne 4 |
1493 | Examples of quoting: | |
1494 | .Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent | |
1495 | .It Li \&.Aq | |
1496 | .Aq | |
1497 | .It Li \&.Aq \&Ar ctype.h\ )\ , | |
1498 | .Aq Ar ctype.h ) , | |
1499 | .It Li \&.Bq | |
1500 | .Bq | |
1501 | .It Li \&.Bq \&Em Greek \&, French \&. | |
1502 | .Bq Em Greek , French . | |
1503 | .It Li \&.Dq | |
1504 | .Dq | |
1505 | .It Li ".Dq string abc ." | |
1506 | .Dq string abc . | |
1507 | .It Li ".Dq \'^[A-Z]\'" | |
1508 | .Dq \'^[A-Z]\' | |
1509 | .It Li "\&.Ql man mdoc" | |
1510 | .Ql man mdoc | |
1511 | .It Li \&.Qq | |
1512 | ||
1513 | .It Li "\&.Qq string ) ," | |
1514 | .Qq string ) , | |
b141718f CL |
1515 | .It Li "\&.Qq string Ns )," |
1516 | .Qq string Ns ), | |
be765ac2 CL |
1517 | .It Li \&.Sq |
1518 | .Sq | |
1519 | .It Li "\&.Sq string | |
1520 | .Sq string | |
1521 | .El | |
1522 | .Pp | |
1523 | For a good example of nested enclosure macros, see the | |
1524 | .Ql \&.Op | |
1525 | option macro. | |
1526 | It was created from the same | |
1527 | underlying enclosure macros as those presented in the list | |
1528 | above. | |
c5174ad4 | 1529 | The |
be765ac2 CL |
1530 | .Ql \&.Xo |
1531 | and | |
1532 | .Ql \&.Xc | |
1533 | extended argument list macros | |
1534 | were also built from the same underlying routines and are a good | |
1535 | example of | |
1536 | .Nm \-mdoc | |
1537 | macro usage at its worst. | |
1538 | .Ss No\-Op or Normal Text Macro | |
1539 | The macro | |
1540 | .Li \&.No | |
1541 | is | |
1542 | a hack for words in a macro command line which should | |
1543 | .Em not | |
1544 | be formatted and follows the conventional syntax | |
1545 | for content macros. | |
1546 | .Ss No Space Macro | |
1547 | The | |
1548 | .Ql \&.Ns | |
1549 | macro eliminates unwanted spaces in between macro requests. | |
1550 | It is useful for old style argument lists where there is no space | |
1551 | between the flag and argument: | |
1552 | .Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent | |
1553 | .It Li ".Op Fl I Ns Ar directory" | |
1554 | produces | |
1555 | .Op Fl I Ns Ar directory | |
1556 | .El | |
1557 | .Pp | |
1558 | Note: the | |
c5174ad4 | 1559 | .Ql \&.Ns |
be765ac2 CL |
1560 | macro always invokes the |
1561 | .Ql \&.No | |
1562 | macro after eliminating the space unless another macro name | |
1563 | follows it. | |
1564 | The macro | |
1565 | .Ql \&.Ns | |
b141718f | 1566 | is parsed and is callable. |
c5174ad4 CL |
1567 | .Ss Section Cross References |
1568 | The | |
1569 | .Ql \&.Sx | |
1570 | macro designates a reference to a section header | |
be765ac2 | 1571 | within the same document. |
b141718f | 1572 | It is parsed and is callable. |
c5174ad4 CL |
1573 | .Pp |
1574 | .Bl -tag -width "Li \&.Sx FILES" -offset 14n | |
1575 | .It Li \&.Sx FILES | |
1576 | .Sx FILES | |
1577 | .El | |
be765ac2 CL |
1578 | .Ss Symbolic |
1579 | The symbolic emphasis macro is generally a boldface macro in | |
1580 | either the symbolic sense or the traditional English usage. | |
1581 | .Pp | |
1582 | .Dl Usage: .Sy symbol ... \*(Pu | |
1583 | .Bl -tag -width ".Sy Important Noticex" -compact -offset 14n | |
1584 | .It Li \&.Sy Important Notice | |
1585 | .Sy Important Notice | |
1586 | .El | |
1587 | .Pp | |
1588 | The | |
1589 | .Ql \&.Sy | |
b141718f | 1590 | macro is parsed and is callable. |
be765ac2 CL |
1591 | Arguments to |
1592 | .Ql \&.Sy | |
1593 | may be quoted. | |
c5174ad4 CL |
1594 | .Ss References and Citations |
1595 | The following macros make a modest attempt to handle references. | |
be765ac2 | 1596 | At best, the macros make it convenient to manually drop in a subset of |
c5174ad4 CL |
1597 | refer style references. |
1598 | .Pp | |
1599 | .Bl -tag -width 6n -offset indent -compact | |
1600 | .It Li ".Rs" | |
be765ac2 CL |
1601 | Reference Start. |
1602 | Causes a line break and begins collection | |
c5174ad4 CL |
1603 | of reference information until the |
1604 | reference end macro is read. | |
1605 | .It Li ".Re" | |
be765ac2 CL |
1606 | Reference End. |
1607 | The reference is printed. | |
c5174ad4 CL |
1608 | .It Li ".%A" |
1609 | Reference author name, one name per invocation. | |
1610 | .It Li ".%B" | |
1611 | Book title. | |
be765ac2 CL |
1612 | .It Li ".\&%C" |
1613 | City/place. | |
1614 | .It Li ".\&%D" | |
1615 | Date. | |
c5174ad4 | 1616 | .It Li ".%J" |
be765ac2 | 1617 | Journal name. |
c5174ad4 CL |
1618 | .It Li ".%N" |
1619 | Issue number. | |
1620 | .It Li ".%O" | |
1621 | Optional information. | |
be765ac2 CL |
1622 | .It Li ".%P" |
1623 | Page number. | |
c5174ad4 CL |
1624 | .It Li ".%R" |
1625 | Report name. | |
1626 | .It Li ".%T" | |
1627 | Title of article. | |
1628 | .It Li ".%V" | |
1629 | Volume(s). | |
1630 | .El | |
1631 | .Pp | |
be765ac2 | 1632 | The macros beginning with |
c5174ad4 | 1633 | .Ql % |
be765ac2 CL |
1634 | are not callable, and are parsed only for the trade name macro which |
1635 | returns to its caller. | |
1636 | (And not very predictably at the moment either.) | |
1637 | The purpose is to allow trade names | |
b141718f CL |
1638 | to be pretty printed in |
1639 | .Xr troff Ns / Ns Xr ditroff | |
1640 | output. | |
be765ac2 CL |
1641 | .Ss Trade Names (or Acronyms and Type Names) |
1642 | The trade name macro is generally a small caps macro for | |
1643 | all upper case words longer than two characters. | |
1644 | .Pp | |
1645 | .Dl Usage: .Tn symbol ... \*(Pu | |
1646 | .Bl -tag -width ".Tn ASCII" -compact -offset 14n | |
1647 | .It Li \&.Tn DEC | |
1648 | .Tn DEC | |
1649 | .It Li \&.Tn ASCII | |
1650 | .Tn ASCII | |
c5174ad4 | 1651 | .El |
3e2f4ebf CL |
1652 | .Pp |
1653 | The | |
be765ac2 | 1654 | .Ql \&.Tn |
c5174ad4 | 1655 | macro |
be765ac2 | 1656 | is parsed and is callable by other macros. |
c5174ad4 CL |
1657 | .Ss Extended Arguments |
1658 | The | |
1659 | .Li \&.Xo | |
1660 | and | |
1661 | .Li \&.Xc | |
be765ac2 CL |
1662 | macros allow one to extend an argument list |
1663 | on a macro boundary. | |
1664 | Argument lists cannot | |
c5174ad4 CL |
1665 | be extended within a macro |
1666 | which expects all of its arguments on one line such | |
1667 | as | |
1668 | .Ql \&.Op . | |
be765ac2 CL |
1669 | .Pp |
1670 | Here is an example of | |
1671 | .Ql \&.Xo | |
1672 | using the space mode macro to turn spacing off: | |
1673 | .Bd -literal -offset indent | |
1674 | \&.Sm off | |
1675 | \&.It Xo Sy I Ar operation | |
b141718f | 1676 | \&.No \een Ar count No \een |
be765ac2 CL |
1677 | \&.Xc |
1678 | \&.Sm on | |
1679 | .Ed | |
1680 | .Pp | |
1681 | Produces | |
1682 | .Bd -filled -offset indent | |
1683 | .Bl -tag -width flag -compact | |
1684 | .Sm off | |
1685 | .It Xo Sy I Ar operation | |
1686 | .No \en Ar count No \en | |
1687 | .Xc | |
1688 | .Sm on | |
1689 | .El | |
1690 | .Ed | |
1691 | .Pp | |
1692 | Another one: | |
1693 | .Bd -literal -offset indent | |
1694 | \&.Sm off | |
1695 | \&.It Cm S No \&/ Ar old_pattern Xo | |
1696 | \&.No \&/ Ar new_pattern | |
1697 | \&.No \&/ Op Cm g | |
1698 | \&.Xc | |
1699 | \&.Sm on | |
1700 | .Ed | |
1701 | .Pp | |
1702 | Produces | |
1703 | .Bd -filled -offset indent | |
1704 | .Bl -tag -width flag -compact | |
1705 | .Sm off | |
1706 | .It Cm S No \&/ Ar old_pattern Xo | |
1707 | .No \&/ Ar new_pattern | |
1708 | .No \&/ Op Cm g | |
1709 | .Xc | |
1710 | .Sm on | |
1711 | .El | |
1712 | .Ed | |
1713 | .Pp | |
1714 | Another example of | |
1715 | .Ql \&.Xo | |
1716 | and using enclosure macros: | |
1717 | Test the value of an variable. | |
1718 | .Bd -literal -offset indent | |
1719 | \&.It Xo | |
1720 | \&.Ic .ifndef | |
1721 | \&.Oo \e&! Oc Ns Ar variable | |
1722 | \&.Op Ar operator variable ... | |
1723 | \&.Xc | |
1724 | .Ed | |
1725 | .Pp | |
1726 | Produces | |
1727 | .Bd -filled -offset indent | |
1728 | .Bl -tag -width flag -compact | |
1729 | .It Xo | |
1730 | .Ic .ifndef | |
1731 | .Oo \&! Oc Ns Ar variable | |
1732 | .Op Ar operator variable ... | |
1733 | .Xc | |
1734 | .El | |
1735 | .Ed | |
1736 | .Pp | |
1737 | All of the above examples have used the | |
1738 | .Ql \&.Xo | |
1739 | macro on the argument list of the | |
1740 | .Ql \&.It | |
1741 | (list-item) | |
1742 | macro. | |
1743 | The extend macros are not used very often, and when they are | |
1744 | it is usually to extend the list-item argument list. | |
1745 | Unfortunately, this is also where the extend macros are the | |
1746 | most finicky. | |
1747 | In the first two examples, spacing was turned off; | |
1748 | in the third, spacing was desired in part of the output but | |
1749 | not all of it. | |
1750 | To make these macros work in this situation make sure | |
1751 | the | |
1752 | .Ql \&.Xo | |
1753 | and | |
1754 | .Ql \&.Xc | |
1755 | macros are placed as shown in the third example. | |
1756 | If the | |
1757 | .Ql \&.Xo | |
1758 | macro is not alone on the | |
1759 | .Ql \&.It | |
1760 | argument list, spacing will be unpredictable. | |
1761 | The | |
1762 | .Ql \&.Ns | |
1763 | (no space macro) | |
1764 | must not occur as the first or last macro on a line | |
1765 | in this situation. | |
b141718f | 1766 | Out of 900 manual pages (about 1500 actual pages) |
be765ac2 CL |
1767 | currently released with |
1768 | .Bx | |
1769 | only fifteen use the | |
1770 | .Ql \&.Xo | |
1771 | macro. | |
1772 | .Sh PAGE STRUCTURE DOMAIN | |
3e2f4ebf | 1773 | .Ss Section Headers |
c5174ad4 CL |
1774 | The first three |
1775 | .Ql \&.Sh | |
1776 | section header macros | |
1777 | list below are required in every | |
be765ac2 CL |
1778 | man page. |
1779 | The remaining section headers | |
1780 | are recommended at the discretion of the author | |
1781 | writing the manual page. | |
1782 | The | |
c5174ad4 | 1783 | .Ql \&.Sh |
be765ac2 | 1784 | macro can take up to nine arguments. |
b141718f | 1785 | It is parsed and but is not callable. |
c5174ad4 CL |
1786 | .Bl -tag -width ".Sh SYNOPSIS" |
1787 | .It \&.Sh NAME | |
3e2f4ebf | 1788 | The |
c5174ad4 | 1789 | .Ql \&.Sh NAME |
be765ac2 CL |
1790 | macro is mandatory. |
1791 | If not specified, | |
3e2f4ebf CL |
1792 | the headers, footers and page layout defaults |
1793 | will not be set and things will be rather unpleasant. | |
be765ac2 CL |
1794 | The |
1795 | .Sx NAME | |
1796 | section consists of at least three items. | |
3e2f4ebf | 1797 | The first is the |
c5174ad4 CL |
1798 | .Ql \&.Nm |
1799 | name macro naming the subject of the man page. | |
1800 | The second is the Name Description macro, | |
1801 | .Ql \&.Nd , | |
3e2f4ebf | 1802 | which separates the subject |
be765ac2 CL |
1803 | name from the third item, which is the description. |
1804 | The | |
3e2f4ebf CL |
1805 | description should be the most terse and lucid possible, |
1806 | as the space available is small. | |
c5174ad4 | 1807 | .It \&.Sh SYNOPSIS |
be765ac2 CL |
1808 | The |
1809 | .Sx SYNOPSIS | |
1810 | section describes the typical usage of the | |
1811 | subject of a man page. | |
1812 | The macros required | |
3e2f4ebf | 1813 | are either |
c5174ad4 CL |
1814 | .Ql ".Nm" , |
1815 | .Ql ".Cd" , | |
be765ac2 | 1816 | .Ql ".Fn" , |
c5174ad4 | 1817 | (and possibly |
be765ac2 CL |
1818 | .Ql ".Fo" , |
1819 | .Ql ".Fc" , | |
c5174ad4 CL |
1820 | .Ql ".Fd" , |
1821 | .Ql ".Ft" | |
1822 | macros). | |
3e2f4ebf | 1823 | The function name |
c5174ad4 CL |
1824 | macro |
1825 | .Ql ".Fn" | |
3e2f4ebf CL |
1826 | is required |
1827 | for manual page sections 2 and 3, the command and general | |
c5174ad4 CL |
1828 | name macro |
1829 | .Ql \&.Nm | |
1830 | is required for sections 1, 5, 6, 7, 8. | |
1831 | Section 4 manuals require a | |
1832 | .Ql ".Nm" , ".Fd" | |
1833 | or a | |
1834 | .Ql ".Cd" | |
1835 | configuration device usage macro. | |
1836 | Several other macros may be necessary to produce | |
3e2f4ebf CL |
1837 | the synopsis line as shown below: |
1838 | .Pp | |
c5174ad4 | 1839 | .Bd -filled -offset indent |
3e2f4ebf CL |
1840 | .Nm cat |
1841 | .Op Fl benstuv | |
1842 | .Op Fl | |
1843 | .Ar | |
c5174ad4 | 1844 | .Ed |
3e2f4ebf | 1845 | .Pp |
c5174ad4 | 1846 | The following macros were used: |
3e2f4ebf CL |
1847 | .Pp |
1848 | .Dl \&.Nm cat | |
c5174ad4 CL |
1849 | .Dl \&.Op \&Fl benstuv |
1850 | .Dl \&.Op \&Fl | |
3e2f4ebf | 1851 | .Dl \&.Ar |
b141718f | 1852 | .Pp |
be765ac2 CL |
1853 | .Sy Note : |
1854 | The macros | |
1855 | .Ql \&.Op , | |
1856 | .Ql \&.Fl , | |
1857 | and | |
1858 | .Ql \&.Ar | |
1859 | recognize the pipe bar character | |
b141718f CL |
1860 | .Ql \*(Ba , |
1861 | so a command line such as: | |
be765ac2 CL |
1862 | .Pp |
1863 | .Dl ".Op Fl a | Fl b" | |
1864 | .Pp | |
b141718f | 1865 | will not go orbital. |
be765ac2 CL |
1866 | .Xr Troff |
1867 | normally interprets a \*(Ba as a special operator. | |
1868 | See | |
1869 | .Sx PREDEFINED STRINGS | |
1870 | for a usable \*(Ba | |
1871 | character in other situations. | |
c5174ad4 | 1872 | .It \&.Sh DESCRIPTION |
be765ac2 CL |
1873 | In most cases the first text in the |
1874 | .Sx DESCRIPTION | |
1875 | section | |
3e2f4ebf CL |
1876 | is a brief paragraph on the command, function or file, |
1877 | followed by a lexical list of options and respective | |
be765ac2 CL |
1878 | explanations. |
1879 | To create such a list, the | |
c5174ad4 CL |
1880 | .Ql \&.Bl |
1881 | begin-list, | |
1882 | .Ql \&.It | |
1883 | list-item and | |
1884 | .Ql \&.El | |
1885 | end-list | |
1886 | macros are used (see | |
1887 | .Sx Lists and Columns | |
1888 | below). | |
1889 | .El | |
3e2f4ebf CL |
1890 | .Pp |
1891 | The following | |
c5174ad4 | 1892 | .Ql \&.Sh |
3e2f4ebf CL |
1893 | section headers are part of the |
1894 | preferred manual page layout and must be used appropriately | |
be765ac2 CL |
1895 | to maintain consistency. |
1896 | They are listed in the order | |
3e2f4ebf | 1897 | in which they would be used. |
c5174ad4 CL |
1898 | .Bl -tag -width SYNOPSIS |
1899 | .It \&.Sh ENVIRONMENT | |
be765ac2 CL |
1900 | The |
1901 | .Sx ENVIRONMENT | |
1902 | section should reveal any related | |
3e2f4ebf | 1903 | environment |
be765ac2 | 1904 | variables and clues to their behavior and/or usage. |
c5174ad4 | 1905 | .It \&.Sh EXAMPLES |
be765ac2 CL |
1906 | There are several ways to create examples. |
1907 | See | |
1908 | the | |
1909 | .Sx EXAMPLES | |
1910 | section below | |
3e2f4ebf | 1911 | for details. |
c5174ad4 | 1912 | .It \&.Sh FILES |
3e2f4ebf CL |
1913 | Files which are used or created by the man page subject |
1914 | should be listed via the | |
c5174ad4 | 1915 | .Ql \&.Pa |
be765ac2 CL |
1916 | macro in the |
1917 | .Sx FILES | |
1918 | section. | |
c5174ad4 | 1919 | .It \&.Sh SEE ALSO |
3e2f4ebf CL |
1920 | References to other material on the man page topic and |
1921 | cross references to other relevant man pages should | |
be765ac2 CL |
1922 | be placed in the |
1923 | .Sx SEE ALSO | |
1924 | section. | |
1925 | Cross references | |
3e2f4ebf | 1926 | are specified using the |
c5174ad4 | 1927 | .Ql \&.Xr |
be765ac2 CL |
1928 | macro. |
1929 | At this time | |
3e2f4ebf CL |
1930 | .Xr refer 1 |
1931 | style references are not accommodated. | |
c5174ad4 | 1932 | .It \&.Sh STANDARDS |
3e2f4ebf | 1933 | If the command, library function or file adheres to a |
be765ac2 CL |
1934 | specific implementation such as |
1935 | .St -p1003.2 | |
1936 | or | |
1937 | .St -ansiC | |
1938 | this should be noted here. | |
1939 | If the | |
3e2f4ebf | 1940 | command does not adhere to any standard, its history |
be765ac2 CL |
1941 | should be noted in the |
1942 | .Sx HISTORY | |
1943 | section. | |
c5174ad4 | 1944 | .It \&.Sh HISTORY |
3e2f4ebf CL |
1945 | Any command which does not adhere to any specific standards |
1946 | should be outlined historically in this section. | |
c5174ad4 | 1947 | .It \&.Sh AUTHORS |
3e2f4ebf | 1948 | Credits, if need be, should be placed here. |
c5174ad4 | 1949 | .It \&.Sh DIAGNOSTICS |
3e2f4ebf | 1950 | Diagnostics from a command should be placed in this section. |
c5174ad4 | 1951 | .It \&.Sh ERRORS |
3e2f4ebf | 1952 | Specific error handling, especially from library functions |
be765ac2 CL |
1953 | (man page sections 2 and 3) should go here. |
1954 | The | |
c5174ad4 CL |
1955 | .Ql \&.Er |
1956 | macro is used to specify an errno. | |
1957 | .It \&.Sh BUGS | |
3e2f4ebf | 1958 | Blatant problems with the topic go here... |
c5174ad4 | 1959 | .El |
3e2f4ebf | 1960 | .Pp |
c5174ad4 CL |
1961 | User specified |
1962 | .Ql \&.Sh | |
1963 | sections may be added, | |
1964 | for example, this section was set with: | |
1965 | .Bd -literal -offset 14n | |
1966 | \&.Sh PAGE LAYOUT MACROS | |
1967 | .Ed | |
3e2f4ebf | 1968 | .Ss Paragraphs and Line Spacing. |
c5174ad4 CL |
1969 | .Bl -tag -width 6n |
1970 | .It \&.Pp | |
3e2f4ebf CL |
1971 | The \&.Pp paragraph command may |
1972 | be used to specify a line space where necessary. | |
c5174ad4 CL |
1973 | The macro is not necessary after a |
1974 | .Ql \&.Sh | |
3e2f4ebf | 1975 | or |
c5174ad4 CL |
1976 | .Ql \&.Ss |
1977 | macro or before | |
3e2f4ebf | 1978 | a |
c5174ad4 CL |
1979 | .Ql \&.Bl |
1980 | macro. | |
1981 | (The | |
1982 | .Ql \&.Bl | |
1983 | macro asserts a vertical distance unless the -compact flag is given). | |
1984 | .El | |
be765ac2 | 1985 | .\" This worked with version one, need to redo for version three |
c5174ad4 CL |
1986 | .\" .Pp |
1987 | .\" .Ds I | |
1988 | .\" .Cw (ax+bx+c) \ is\ produced\ by\ \& | |
1989 | .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& | |
1990 | .\" .Cl Cx \t\t | |
1991 | .\" .Li \&.Cx\ ( | |
1992 | .\" .Cx | |
1993 | .\" .Cl Cx \t\t | |
1994 | .\" .Li \&.Va ax | |
1995 | .\" .Cx | |
1996 | .\" .Cl Cx \t\t | |
1997 | .\" .Li \&.Sy \+ | |
1998 | .\" .Cx | |
1999 | .\" .Cl Cx \&(\& | |
2000 | .\" .Va ax | |
2001 | .\" .Cx + | |
2002 | .\" .Va by | |
2003 | .\" .Cx + | |
2004 | .\" .Va c ) | |
2005 | .\" .Cx \t | |
2006 | .\" .Em is produced by | |
2007 | .\" .Cx \t | |
2008 | .\" .Li \&.Va by | |
2009 | .\" .Cx | |
2010 | .\" .Cl Cx \t\t | |
2011 | .\" .Li \&.Sy \+ | |
2012 | .\" .Cx | |
2013 | .\" .Cl Cx \t\t | |
2014 | .\" .Li \&.Va c ) | |
2015 | .\" .Cx | |
2016 | .\" .Cl Cx \t\t | |
2017 | .\" .Li \&.Cx | |
2018 | .\" .Cx | |
2019 | .\" .Cw | |
2020 | .\" .De | |
2021 | .\" .Pp | |
be765ac2 CL |
2022 | .\" This example shows the same equation in a different format. |
2023 | .\" The spaces | |
c5174ad4 CL |
2024 | .\" around the |
2025 | .\" .Li \&+ | |
2026 | .\" signs were forced with | |
2027 | .\" .Li \e : | |
2028 | .\" .Pp | |
2029 | .\" .Ds I | |
2030 | .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& | |
2031 | .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& | |
2032 | .\" .Cl Cx \t\t | |
2033 | .\" .Li \&.Cx\ ( | |
2034 | .\" .Cx | |
2035 | .\" .Cl Cx \t\t | |
2036 | .\" .Li \&.Va a | |
2037 | .\" .Cx | |
2038 | .\" .Cl Cx \t\t | |
2039 | .\" .Li \&.Sy x | |
2040 | .\" .Cx | |
2041 | .\" .Cl Cx \t\t | |
2042 | .\" .Li \&.Cx \e\ +\e\ \e& | |
2043 | .\" .Cx | |
2044 | .\" .Cl Cx \&(\& | |
2045 | .\" .Va a | |
2046 | .\" .Sy x | |
2047 | .\" .Cx \ +\ \& | |
2048 | .\" .Va b | |
2049 | .\" .Sy y | |
2050 | .\" .Cx \ +\ \& | |
2051 | .\" .Va c ) | |
2052 | .\" .Cx \t | |
2053 | .\" .Em is produced by | |
2054 | .\" .Cl Cx \t\t | |
2055 | .\" .Li \&.Va b | |
2056 | .\" .Cx | |
2057 | .\" .Cl Cx \t\t | |
2058 | .\" .Li \&.Sy y | |
2059 | .\" .Cx | |
2060 | .\" .Cl Cx \t\t | |
2061 | .\" .Li \&.Cx \e\ +\e\ \e& | |
2062 | .\" .Cx | |
2063 | .\" .Cl Cx \t\t | |
2064 | .\" .Li \&.Va c ) | |
2065 | .\" .Cx | |
2066 | .\" .Cl Cx \t\t | |
2067 | .\" .Li \&.Cx | |
2068 | .\" .Cx | |
2069 | .\" .Cw | |
2070 | .\" .De | |
2071 | .\" .Pp | |
2072 | .\" The incantation below was | |
2073 | .\" lifted from the | |
2074 | .\" .Xr adb 1 | |
2075 | .\" manual page: | |
2076 | .\" .Pp | |
2077 | .\" .Ds I | |
2078 | .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by | |
2079 | .\" .Cl Cx \t\t | |
2080 | .\" .Li \&.Cx Op Sy ?/ | |
2081 | .\" .Cx | |
2082 | .\" .Cl Cx \t\t | |
2083 | .\" .Li \&.Nm m | |
2084 | .\" .Cx | |
2085 | .\" .Cl Cx Op Sy ?/ | |
2086 | .\" .Nm m | |
2087 | .\" .Ad \ b1 e1 f1 | |
2088 | .\" .Op Sy ?/ | |
2089 | .\" .Cx \t | |
2090 | .\" .Em is produced by | |
2091 | .\" .Cx \t | |
2092 | .\" .Li \&.Ar \e\ b1 e1 f1 | |
2093 | .\" .Cx | |
2094 | .\" .Cl Cx \t\t | |
2095 | .\" .Li \&.Op Sy ?/ | |
2096 | .\" .Cx | |
2097 | .\" .Cl Cx \t\t | |
2098 | .\" .Li \&.Cx | |
2099 | .\" .Cx | |
2100 | .\" .Cw | |
2101 | .\" .De | |
2102 | .\" .Pp | |
be765ac2 CL |
2103 | .Ss Keeps |
2104 | The only keep that is implemented at this time is for words. | |
2105 | The macros are | |
2106 | .Ql \&.Bk | |
2107 | (begin-keep) | |
2108 | and | |
2109 | .Ql \&.Ek | |
2110 | (end-keep). | |
2111 | The only option that | |
2112 | .Ql \&.Bl | |
2113 | accepts is | |
2114 | .Fl words | |
2115 | and is useful for preventing line breaks in the middle of options. | |
2116 | In the example for the make command line arguments (see | |
2117 | .Sx What's in a name ) , | |
2118 | the keep prevented | |
2119 | .Xr nroff | |
2120 | from placing up the | |
2121 | flag and the argument | |
2122 | on separate lines. | |
2123 | (Actually, the option macro used to prevent this from occurring, | |
2124 | but was dropped when the decision (religious) was made to force | |
2125 | right justified margins in | |
2126 | .Xr troff | |
2127 | as options in general look atrocious when spread across a sparse | |
2128 | line. | |
2129 | More work needs to be done with the keep macros, a | |
2130 | .Fl line | |
2131 | option needs to be added.) | |
3e2f4ebf | 2132 | .Ss Examples and Displays |
c5174ad4 CL |
2133 | There are five types of displays, a quickie one line indented display |
2134 | .Ql \&.D1 , | |
2135 | a quickie one line literal display | |
2136 | .Ql \&.Dl , | |
be765ac2 | 2137 | and a block literal, block filled and block ragged which use |
c5174ad4 CL |
2138 | the |
2139 | .Ql \&.Bd | |
2140 | begin-display | |
2141 | and | |
2142 | .Ql \&.Ed | |
2143 | end-display macros. | |
2144 | .Pp | |
be765ac2 | 2145 | .Bl -tag -width \&.Dlxx |
c5174ad4 CL |
2146 | .It Li \&.D1 |
2147 | (D-one) Display one line of indented text. | |
be765ac2 | 2148 | This macro is parsed, but it is not callable. |
3e2f4ebf | 2149 | .Pp |
c5174ad4 | 2150 | .Dl Fl ldghfstru |
be765ac2 CL |
2151 | .Pp |
2152 | The above was produced by: | |
2153 | .Li \&.Dl Fl ldghfstru . | |
c5174ad4 CL |
2154 | .It Li \&.Dl |
2155 | (D-ell) | |
2156 | Display one line of indented | |
2157 | .Em literal | |
be765ac2 CL |
2158 | text. |
2159 | The | |
c5174ad4 CL |
2160 | .Ql \&.Dl |
2161 | example macro has been used throughout this | |
be765ac2 CL |
2162 | file. |
2163 | It allows | |
c5174ad4 CL |
2164 | the indent (display) of one line of text. |
2165 | Its default font is set to | |
2166 | constant width (literal) however | |
be765ac2 CL |
2167 | it is parsed and will recognized other macros. |
2168 | It is not callable however. | |
c5174ad4 | 2169 | .Pp |
3e2f4ebf | 2170 | .Dl % ls -ldg /usr/local/bin |
be765ac2 CL |
2171 | .Pp |
2172 | The above was produced by | |
2173 | .Li \&.Dl % ls -ldg /usr/local/bin . | |
c5174ad4 | 2174 | .It Li \&.Bd |
be765ac2 CL |
2175 | Begin-display. |
2176 | The | |
c5174ad4 CL |
2177 | .Ql \&.Bd |
2178 | display must be ended with the | |
2179 | .Ql \&.Ed | |
be765ac2 CL |
2180 | macro. |
2181 | Displays may be nested within displays and | |
c5174ad4 CL |
2182 | lists. |
2183 | .Ql \&.Bd | |
2184 | has the following syntax: | |
3e2f4ebf | 2185 | .Pp |
be765ac2 | 2186 | .Dl ".Bd display-type [-offset offset_value] [-compact]" |
3e2f4ebf | 2187 | .Pp |
c5174ad4 CL |
2188 | The display-type must be one of the following four types and |
2189 | may have an offset specifier for indentation: | |
2190 | .Ql \&.Bd . | |
3e2f4ebf | 2191 | .Pp |
be765ac2 | 2192 | .Bl -tag -width "file file_name " -compact |
c5174ad4 | 2193 | .It Fl ragged |
3e2f4ebf | 2194 | Display a block of text as typed, |
c5174ad4 CL |
2195 | right (and left) margin edges are left ragged. |
2196 | .It Fl filled | |
2197 | Display a filled (formatted) block. | |
2198 | The block of text is formatted (the edges are filled \- | |
be765ac2 | 2199 | not left unjustified). |
c5174ad4 CL |
2200 | .It Fl literal |
2201 | Display a literal block, useful for source code or | |
2202 | simple tabbed or spaced text. | |
2203 | .It Fl file Ar file_name | |
2204 | The file name following the | |
2205 | .Fl file | |
be765ac2 CL |
2206 | flag is read and displayed. |
2207 | Literal mode is | |
c5174ad4 CL |
2208 | asserted and tabs are set at 8 constant width character |
2209 | intervals, however any | |
2210 | .Xr troff/ Ns Nm \-mdoc | |
2211 | commands in file will be processed. | |
2212 | .It Fl offset Ar string | |
2213 | If | |
2214 | .Fl offset | |
2215 | is specified with one of the following strings, the string | |
2216 | is interpreted to indicate the level of indentation for the | |
2217 | forthcoming block of text: | |
2218 | .Pp | |
be765ac2 | 2219 | .Bl -tag -width "indent-two" -compact |
c5174ad4 | 2220 | .It Ar left |
3e2f4ebf CL |
2221 | Align block on the current left margin, |
2222 | this is the default mode of | |
c5174ad4 CL |
2223 | .Ql \&.Bd . |
2224 | .It Ar center | |
be765ac2 CL |
2225 | Supposedly center the block. |
2226 | At this time | |
3e2f4ebf CL |
2227 | unfortunately, the block merely gets |
2228 | left aligned about an imaginary center margin. | |
c5174ad4 | 2229 | .It Ar indent |
be765ac2 CL |
2230 | Indents by one default indent value or tab. |
2231 | The default | |
c5174ad4 CL |
2232 | indent value is also used for the |
2233 | .Ql \&.D1 | |
be765ac2 CL |
2234 | display so one is guaranteed the two types of displays |
2235 | will line up. | |
2236 | This indent is normally set to 6n or about two | |
c5174ad4 CL |
2237 | thirds of an inch (six constant width characters). |
2238 | .It Ar indent-two | |
2239 | Indents two times the default indent value. | |
2240 | .It Ar right | |
2241 | This | |
2242 | .Em left | |
2243 | aligns the block about two inches from | |
be765ac2 CL |
2244 | the right side of the page. |
2245 | This macro needs | |
2246 | work and perhaps may never do the right thing by | |
c5174ad4 CL |
2247 | .Xr troff . |
2248 | .El | |
2249 | .El | |
2250 | .It ".Ed" | |
2251 | End-display. | |
2252 | .El | |
2253 | .Ss Tagged Lists and Columns | |
2254 | There are several types of lists which may be initiated with the | |
2255 | .Ql ".Bl" | |
be765ac2 CL |
2256 | begin-list macro. |
2257 | Items within the list | |
c5174ad4 CL |
2258 | are specified with the |
2259 | .Ql ".It" | |
2260 | item macro and | |
2261 | each list must end with the | |
2262 | .Ql ".El" | |
be765ac2 CL |
2263 | macro. |
2264 | Lists may be nested within themselves and within displays. | |
c5174ad4 CL |
2265 | Columns may be used inside of lists, but lists are unproven |
2266 | inside of columns. | |
2267 | .Pp | |
2268 | In addition, several list attributes may be specified such as | |
b141718f | 2269 | the width of a tag, the list offset, and compactness |
c5174ad4 | 2270 | (blank lines between items allowed or disallowed). |
be765ac2 CL |
2271 | Most of this document has been formatted with a tag style list |
2272 | .Pq Fl tag . | |
2273 | For a change of pace, the list-type used to present the list-types | |
2274 | is an over-hanging list | |
2275 | .Pq Fl ohang . | |
2276 | This type of list is quite popular with | |
2277 | .Tn TeX | |
b141718f | 2278 | users, but might look a bit funny after having read many pages of |
be765ac2 | 2279 | tagged lists. |
c5174ad4 | 2280 | The following list types are accepted by |
be765ac2 | 2281 | .Ql ".Bl" : |
c5174ad4 CL |
2282 | .Pp |
2283 | .Bl -ohang -compact | |
2284 | .It Fl bullet | |
2285 | .It Fl item | |
2286 | .It Fl enum | |
be765ac2 CL |
2287 | These three are the simplest types of lists. |
2288 | Once the | |
c5174ad4 CL |
2289 | .Ql ".Bl" |
2290 | macro has been given, items in the list are merely | |
2291 | indicated by a line consisting solely of the | |
2292 | .Ql ".It" | |
be765ac2 CL |
2293 | macro. |
2294 | For example, the source text for a simple enumerated list | |
c5174ad4 CL |
2295 | would look like: |
2296 | .Bd -literal -offset indent-two | |
2297 | \&.Bl -enum -compact | |
2298 | \&.It | |
2299 | \&Item one goes here. | |
2300 | \&.It | |
2301 | \&And item two here. | |
2302 | \&.It | |
2303 | \&Lastly item three goes here. | |
2304 | \&.El | |
2305 | .Ed | |
2306 | .Pp | |
2307 | The results: | |
2308 | .Pp | |
2309 | .Bl -enum -offset indent-two -compact | |
2310 | .It | |
2311 | Item one goes here. | |
2312 | .It | |
2313 | And item two here. | |
2314 | .It | |
2315 | Lastly item three goes here. | |
2316 | .El | |
2317 | .Pp | |
2318 | A simple bullet list construction: | |
2319 | .Bd -literal -offset indent-two | |
2320 | \&.Bl -bullet -compact | |
2321 | \&.It | |
2322 | \&Bullet one goes here. | |
2323 | \&.It | |
2324 | \&Bullet two here. | |
2325 | \&.El | |
2326 | .Ed | |
2327 | .Pp | |
2328 | Produces: | |
2329 | .Bl -bullet -offset indent-two -compact | |
2330 | .It | |
2331 | Bullet one goes here. | |
2332 | .It | |
2333 | Bullet two here. | |
2334 | .El | |
2335 | .Pp | |
2336 | .It Fl tag | |
2337 | .It Fl diag | |
2338 | .It Fl hang | |
2339 | .It Fl ohang | |
2340 | .It Fl inset | |
2341 | These list-types collect arguments specified with the | |
2342 | .Ql \&.It | |
2343 | macro and create a label which may be | |
2344 | .Em inset | |
2345 | into the forth coming text, | |
2346 | .Em hanged | |
be765ac2 | 2347 | from the forth coming text, |
c5174ad4 | 2348 | .Em overhanged |
b141718f | 2349 | from above and not indented or |
be765ac2 CL |
2350 | .Em tagged . |
2351 | This | |
c5174ad4 CL |
2352 | list was constructed with the |
2353 | .Ql Fl ohang | |
be765ac2 CL |
2354 | list-type. |
2355 | The | |
c5174ad4 | 2356 | .Ql \&.It |
b141718f CL |
2357 | macro is parsed only for the inset, hang |
2358 | and tag list-types and is not callable. | |
c5174ad4 CL |
2359 | Here is an example of inset labels: |
2360 | .Bl -inset -offset indent | |
2361 | .It Em Tag | |
2362 | The tagged list (also called a tagged paragraph) is the | |
2363 | most common type of list used in the Berkeley manuals. | |
2364 | .It Em Diag | |
2365 | Diag lists create section four diagnostic lists | |
2366 | and are similar to inset lists except callable | |
2367 | macros are ignored. | |
2368 | .It Em Hang | |
2369 | Hanged labels are a matter of taste. | |
2370 | .It Em Ohang | |
2371 | Over hanging labels are nice when space is constrained. | |
2372 | .It Em Inset | |
2373 | Inset labels are useful for controlling blocks of | |
2374 | paragraphs and are valuable for converting | |
2375 | .Nm \-mdoc | |
2376 | manuals to other formats. | |
2377 | .El | |
2378 | .Pp | |
2379 | Here is the source text which produced the above example: | |
2380 | .Bd -literal -offset indent | |
2381 | \&.Bl -inset -offset indent | |
2382 | \&.It Em Tag | |
2383 | \&The tagged list (also called a tagged paragraph) is the | |
2384 | \&most common type of list used in the Berkeley manuals. | |
2385 | \&.It Em Diag | |
2386 | \&Diag lists create section four diagnostic lists | |
2387 | \&and are similar to inset lists except callable | |
2388 | \¯os are ignored. | |
2389 | \&.It Em Hang | |
2390 | \&Hanged labels are a matter of taste. | |
2391 | \&.It Em Ohang | |
2392 | \&Over hanging labels are nice when space is constrained. | |
2393 | \&.It Em Inset | |
2394 | \&Inset labels are useful for controlling blocks of | |
2395 | \¶graphs and are valuable for converting | |
2396 | \&.Nm \-mdoc | |
2397 | \&manuals to other formats. | |
2398 | \&.El | |
2399 | .Ed | |
2400 | .Pp | |
2401 | Here is a hanged list with just one item: | |
2402 | .Bl -hang -offset indent | |
2403 | .It Em Hanged | |
2404 | labels appear similar to tagged lists when the | |
2405 | label is smaller than the label width. | |
2406 | .It Em Longer hanged list labels | |
2407 | blend in to the paragraph unlike | |
2408 | tagged paragraph labels. | |
2409 | .El | |
2410 | .Pp | |
be765ac2 | 2411 | And the unformatted text which created it: |
c5174ad4 CL |
2412 | .Bd -literal -offset indent |
2413 | \&.Bl -hang -offset indent | |
2414 | \&.It Em Hanged | |
2415 | \&labels appear similar to tagged lists when the | |
2416 | \&label is smaller than the label width. | |
2417 | \&.It Em Longer hanged list labels | |
2418 | \&blend in to the paragraph unlike | |
2419 | \&tagged paragraph labels. | |
2420 | \&.El | |
2421 | .Ed | |
2422 | .Pp | |
be765ac2 | 2423 | The tagged list which follows uses an optional width specifier to control |
c5174ad4 CL |
2424 | the width of the tag. |
2425 | .Pp | |
b141718f CL |
2426 | .Bl -tag -width "PAGEIN" -compact -offset indent |
2427 | .It SL | |
c5174ad4 | 2428 | sleep time of the process (seconds blocked) |
b141718f CL |
2429 | .It PAGEIN |
2430 | number of disk | |
2431 | .Tn I/O Ns 's | |
2432 | resulting from references | |
c5174ad4 | 2433 | by the process to pages not loaded in core. |
b141718f | 2434 | .It UID |
c5174ad4 | 2435 | numerical user-id of process owner |
b141718f | 2436 | .It PPID |
c5174ad4 CL |
2437 | numerical id of parent of process process priority |
2438 | (non-positive when in non-interruptible wait) | |
2439 | .El | |
3e2f4ebf | 2440 | .Pp |
c5174ad4 CL |
2441 | The raw text: |
2442 | .Bd -literal -offset indent | |
b141718f CL |
2443 | \&.Bl -tag -width "PAGEIN" -compact -offset indent |
2444 | \&.It SL | |
c5174ad4 | 2445 | \&sleep time of the process (seconds blocked) |
b141718f CL |
2446 | \&.It PAGEIN |
2447 | \&number of disk | |
2448 | \&.Tn I/O Ns 's | |
2449 | \&resulting from references | |
c5174ad4 | 2450 | \&by the process to pages not loaded in core. |
b141718f | 2451 | \&.It UID |
c5174ad4 | 2452 | \&numerical user-id of process owner |
b141718f | 2453 | \&.It PPID |
c5174ad4 CL |
2454 | \&numerical id of parent of process process priority |
2455 | \&(non-positive when in non-interruptible wait) | |
2456 | \&.El | |
2457 | .Ed | |
2458 | .Pp | |
2459 | Acceptable width specifiers: | |
2460 | .Bl -tag -width Ar -offset indent | |
2461 | .It Fl width Ar "\&Fl" | |
be765ac2 CL |
2462 | sets the width to the default width for a flag. |
2463 | All callable | |
2464 | macros have a default width value. | |
2465 | The | |
c5174ad4 CL |
2466 | .Ql \&.Fl , |
2467 | value is presently | |
3e2f4ebf CL |
2468 | set to ten constant width characters or about five sixth of |
2469 | an inch. | |
c5174ad4 | 2470 | .It Fl width Ar "24n" |
3e2f4ebf | 2471 | sets the width to 24 constant width characters or about two |
be765ac2 CL |
2472 | inches. |
2473 | The | |
c5174ad4 | 2474 | .Ql n |
3e2f4ebf | 2475 | is absolutely necessary for the scaling to work correctly. |
c5174ad4 CL |
2476 | .It Fl width Ar "ENAMETOOLONG" |
2477 | sets width to the constant width length of the | |
3e2f4ebf | 2478 | string given. |
c5174ad4 | 2479 | .It Fl width Ar "\\*qint mkfifo\\*q" |
3e2f4ebf | 2480 | again, the width is set to the constant width of the string |
c5174ad4 CL |
2481 | given. |
2482 | .El | |
2483 | .Pp | |
2484 | If a width is not specified for the tag list type, the first | |
2485 | time | |
2486 | .Ql \&.It | |
2487 | is invoked, an attempt is made to determine an appropriate | |
be765ac2 CL |
2488 | width. |
2489 | If the first argument to | |
c5174ad4 CL |
2490 | .Ql ".It" |
2491 | is a callable macro, the default width for that macro will be used | |
be765ac2 CL |
2492 | as if the macro name had been supplied as the width. |
2493 | However, | |
c5174ad4 | 2494 | if another item in the list is given with a different callable |
be765ac2 CL |
2495 | macro name, a new and nested list is assumed. |
2496 | .Sh PREDEFINED STRINGS | |
2497 | The following strings are predefined as may be used by | |
2498 | preceding with the troff string interpreting sequence | |
2499 | .Ql \&\e*(xx | |
2500 | where | |
2501 | .Em xx | |
2502 | is the name of the defined string or as | |
2503 | .Ql \&\e*x | |
2504 | where | |
2505 | .Em x | |
2506 | is the name of the string. | |
2507 | The interpreting sequence may be used any where in the text. | |
2508 | .Pp | |
2509 | .Bl -column "String " "Nroff " "Troff " -offset indent | |
2510 | .It Sy "String Nroff Troff" | |
2511 | .It Li "<=" Ta \&<\&= Ta \*(<= | |
2512 | .It Li ">=" Ta \&>\&= Ta \*(>= | |
2513 | .It Li "Rq" Ta "''" Ta \*(Rq | |
2514 | .It Li "Lq" Ta "``" Ta \*(Lq | |
2515 | .It Li "ua" Ta ^ Ta \*(ua | |
2516 | .It Li "aa" Ta ' Ta \*(aa | |
2517 | .It Li "ga" Ta \` Ta \*(ga | |
2518 | .\" .It Li "sL" Ta ` Ta \*(sL | |
2519 | .\" .It Li "sR" Ta ' Ta \*(sR | |
2520 | .It Li "q" Ta \&" Ta \*q | |
2521 | .It Li "Pi" Ta pi Ta \*(Pi | |
2522 | .It Li "Ne" Ta != Ta \*(Ne | |
2523 | .It Li "Le" Ta <= Ta \*(Le | |
2524 | .It Li "Ge" Ta >= Ta \*(Ge | |
2525 | .It Li "Lt" Ta < Ta \*(Gt | |
2526 | .It Li "Gt" Ta > Ta \*(Lt | |
2527 | .It Li "Pm" Ta +- Ta \*(Pm | |
2528 | .It Li "If" Ta infinity Ta \*(If | |
2529 | .It Li "Na" Ta \fINaN\fP Ta \*(Na | |
2530 | .It Li "Ba" Ta \fR\&|\fP Ta \*(Ba | |
2531 | .El | |
2532 | .Pp | |
2533 | .Sy Note : | |
2534 | The string named | |
2535 | .Ql q | |
2536 | should be written as | |
b141718f CL |
2537 | .Ql \e*q |
2538 | since it is only one char. | |
c5174ad4 CL |
2539 | .Sh DIAGNOSTICS |
2540 | The debugging facilities for | |
2541 | .Nm \-mdoc | |
2542 | are limited, but can help detect subtle errors such | |
2543 | as the collision of an argument name with an internal | |
be765ac2 CL |
2544 | register or macro name. |
2545 | (A what?) | |
c5174ad4 CL |
2546 | A register is an arithmetic storage class for |
2547 | .Xr troff | |
2548 | with a one or two character name. | |
2549 | All registers internal to | |
2550 | .Nm \-mdoc | |
2551 | for | |
2552 | .Xr troff | |
2553 | and | |
2554 | .Xr ditroff | |
2555 | are two characters and | |
be765ac2 | 2556 | of the form <upper_case><lower_case> such as |
c5174ad4 | 2557 | .Ql \&Ar , |
be765ac2 | 2558 | <lower_case><upper_case> as |
c5174ad4 | 2559 | .Ql \&aR |
3e2f4ebf | 2560 | or |
c5174ad4 CL |
2561 | <upper or lower letter><digit> as |
2562 | .Ql \&C\&1 . | |
2563 | And adding to the muddle, | |
2564 | .Xr troff | |
2565 | has its own internal registers all of which are either | |
be765ac2 | 2566 | two lower case characters or a dot plus a letter or meta-character |
c5174ad4 CL |
2567 | character. |
2568 | In one of the introduction examples, it was shown how to | |
2569 | prevent the interpretation of a macro name with the escape sequence | |
2570 | .Ql \e& . | |
2571 | This is sufficient for the internal register names also. | |
2572 | .Pp | |
2573 | .\" Every callable macro name has a corresponding register | |
be765ac2 | 2574 | .\" of the same name (<upper_case><lower_case>). |
c5174ad4 CL |
2575 | .\" There are also specific registers which have |
2576 | .\" been used for stacks and arrays and are listed in the | |
2577 | .\" .Sx Appendix . | |
2578 | .\" .Bd -ragged -offset 4n | |
2579 | .\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') | |
2580 | .\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') | |
2581 | .\" C[0-9] argument types (example C1) | |
2582 | .\" O[0-9] offset stack (displays) | |
2583 | .\" h[0-9] horizontal spacing stack (lists) | |
2584 | .\" o[0-9] offset (stack) (lists) | |
2585 | .\" t[0-9] tag stack (lists) | |
2586 | .\" v[0-9] vertical spacing stack (lists) | |
2587 | .\" w[0-9] width tag/label stack | |
2588 | .\" .Ed | |
2589 | .\" .Pp | |
2590 | If a non-escaped register name is given in the argument list of a request | |
be765ac2 CL |
2591 | unpredictable behavior will occur. |
2592 | In general, any time huge portions | |
c5174ad4 CL |
2593 | of text do not appear where expected in the output, or small strings |
2594 | such as list tags disappear, chances are there is a misunderstanding | |
2595 | about an argument type in the argument list. | |
2596 | Your mother never intended for you to remember this evil stuff - so here | |
2597 | is a way to find out whether or not your arguments are valid: The | |
2598 | .Ql \&.Db | |
2599 | (debug) | |
2600 | macro displays the interpretation of the argument list for most | |
be765ac2 CL |
2601 | macros. |
2602 | Macros such as the | |
c5174ad4 CL |
2603 | .Ql \&.Pp |
2604 | (paragraph) | |
be765ac2 CL |
2605 | macro do not contain debugging information. |
2606 | All of the callable macros do, | |
c5174ad4 CL |
2607 | and it is strongly advised whenever in doubt, |
2608 | turn on the | |
2609 | .Ql \&.Db | |
2610 | macro. | |
2611 | .Pp | |
2612 | .Dl Usage: \&.Db [on | off] | |
2613 | .Pp | |
2614 | An example of a portion of text with | |
2615 | the debug macro placed above and below an | |
2616 | artificially created problem (a flag argument | |
2617 | .Ql \&aC | |
2618 | which should be | |
2619 | .Ql \e&aC | |
2620 | in order to work): | |
2621 | .Bd -literal -offset indent | |
2622 | \&.Db on | |
2623 | \&.Op Fl aC Ar file ) | |
2624 | \&.Db off | |
2625 | .Ed | |
2626 | .Pp | |
2627 | The resulting output: | |
2628 | .Bd -literal -offset indent | |
2629 | DEBUGGING ON | |
2630 | DEBUG(argv) MACRO: `.Op' Line #: 2 | |
2631 | Argc: 1 Argv: `Fl' Length: 2 | |
2632 | Space: `' Class: Executable | |
2633 | Argc: 2 Argv: `aC' Length: 2 | |
2634 | Space: `' Class: Executable | |
2635 | Argc: 3 Argv: `Ar' Length: 2 | |
2636 | Space: `' Class: Executable | |
2637 | Argc: 4 Argv: `file' Length: 4 | |
2638 | Space: ` ' Class: String | |
2639 | Argc: 5 Argv: `)' Length: 1 | |
2640 | Space: ` ' Class: Closing Punctuation or suffix | |
2641 | MACRO REQUEST: .Op Fl aC Ar file ) | |
2642 | DEBUGGING OFF | |
2643 | .Ed | |
2644 | .Pp | |
2645 | The first line of information tells the name of the calling | |
2646 | macro, here | |
2647 | .Ql \&.Op , | |
be765ac2 CL |
2648 | and the line number it appears on. |
2649 | If one or more files are involved | |
c5174ad4 | 2650 | (especially if text from another file is included) the line number |
be765ac2 CL |
2651 | may be bogus. |
2652 | If there is only one file, it should be accurate. | |
c5174ad4 CL |
2653 | The second line gives the argument count, the argument |
2654 | .Pq Ql \&Fl | |
be765ac2 CL |
2655 | and its length. |
2656 | If the length of an argument is two characters, the | |
c5174ad4 CL |
2657 | argument is tested to see if it is executable (unfortunately, any |
2658 | register which contains a non-zero value appears executable). | |
2659 | The third line gives the space allotted for a class, and the | |
be765ac2 CL |
2660 | class type. |
2661 | The problem here is the argument aC should not be | |
2662 | executable. | |
2663 | The four types of classes are string, executable, closing | |
2664 | punctuation and opening punctuation. | |
2665 | The last line shows the entire | |
2666 | argument list as it was read. | |
2667 | In this next example, the offending | |
c5174ad4 CL |
2668 | .Ql \&aC |
2669 | is escaped: | |
2670 | .Bd -literal -offset indent | |
2671 | \&.Db on | |
2672 | \&.Em An escaped \e&aC | |
2673 | \&.Db off | |
2674 | .Ed | |
2675 | .Bd -literal -offset indent | |
2676 | DEBUGGING ON | |
2677 | DEBUG(fargv) MACRO: `.Em' Line #: 2 | |
2678 | Argc: 1 Argv: `An' Length: 2 | |
2679 | Space: ` ' Class: String | |
2680 | Argc: 2 Argv: `escaped' Length: 7 | |
2681 | Space: ` ' Class: String | |
2682 | Argc: 3 Argv: `aC' Length: 2 | |
2683 | Space: ` ' Class: String | |
2684 | MACRO REQUEST: .Em An escaped &aC | |
2685 | DEBUGGING OFF | |
2686 | .Ed | |
2687 | .Pp | |
2688 | The argument | |
2689 | .Ql \e&aC | |
2690 | shows up with the same length of 2 as the | |
2691 | .Ql \e& | |
2692 | sequence produces a zero width, but a register | |
2693 | named | |
2694 | .Ql \e&aC | |
2695 | was not found and the type classified as string. | |
2696 | .Pp | |
2697 | Other diagnostics consist of usage statements and are self explanatory. | |
b141718f CL |
2698 | .Sh GROFF, TROFF AND NROFF |
2699 | The | |
2700 | .Nm \-mdoc | |
2701 | package does not need compatibility mode with | |
2702 | .Xr groff . | |
2703 | .Pp | |
2704 | The package inhibits page breaks, and the headers and footers | |
2705 | which normally occur at those breaks with | |
2706 | .Xr nroff , | |
2707 | to make the manual more efficient for viewing on-line. | |
2708 | At the moment, | |
2709 | .Xr groff | |
2710 | with | |
2711 | .Fl T Ns Ar ascii | |
2712 | does eject the imaginary remainder of the page at end of file. | |
2713 | The inhibiting of the page breaks makes | |
2714 | .Xr nroff Ns 'd | |
2715 | files unsuitable for hardcopy. | |
2716 | There is a register named | |
2717 | .Ql \&cR | |
2718 | which can be set to zero in the site dependent style file | |
2719 | .Pa /usr/src/share/tmac/doc-nroff | |
2720 | to restore the old style behavior. | |
3e2f4ebf | 2721 | .Sh FILES |
c5174ad4 CL |
2722 | .Bl -tag -width /usr/share/man0/template.doc -compact |
2723 | .It Pa /usr/share/tmac/tmac.doc | |
3e2f4ebf | 2724 | manual macro package |
c5174ad4 | 2725 | .It Pa /usr/share/man0/template.doc |
3e2f4ebf | 2726 | template for writing a man page |
c5174ad4 | 2727 | .El |
3e2f4ebf | 2728 | .Sh HISTORY |
be765ac2 CL |
2729 | The |
2730 | .Nm mdoc.samples | |
2731 | tutorial is | |
2732 | .Ud . | |
3e2f4ebf | 2733 | .Sh SEE ALSO |
c5174ad4 | 2734 | .Xr mdoc 7 , |
3e2f4ebf CL |
2735 | .Xr man 1 , |
2736 | .Xr troff 1 | |
2737 | .Sh BUGS | |
3e2f4ebf CL |
2738 | Undesirable hyphenation on the dash of a flag |
2739 | argument is not yet resolved, and causes | |
be765ac2 CL |
2740 | occasional mishaps in the |
2741 | .Sx DESCRIPTION | |
2742 | section. | |
c5174ad4 | 2743 | (line break on the hyphen). |
3e2f4ebf CL |
2744 | .Pp |
2745 | Predefined strings are not declared in documentation. | |
2746 | .Pp | |
2747 | Section 3f has not been added to the header routines. | |
2748 | .Pp | |
c5174ad4 | 2749 | .Ql \&.Nm |
be765ac2 CL |
2750 | font should be changed in |
2751 | .Sx NAME | |
2752 | section. | |
3e2f4ebf | 2753 | .Pp |
c5174ad4 | 2754 | .Ql \&.Fn |
3e2f4ebf | 2755 | needs to have a check to prevent splitting up |
be765ac2 | 2756 | if the line length is too short. |
b141718f | 2757 | Occasionally it |
3e2f4ebf CL |
2758 | separates the last parenthesis, and sometimes |
2759 | looks ridiculous if a line is in fill mode. | |
2760 | .Pp | |
2761 | The method used to prevent header and footer page | |
2762 | breaks (other than the initial header and footer) when using | |
b141718f CL |
2763 | nroff occasionally places an unsightly partially filled line (blank) |
2764 | at the would be bottom of the page. | |
3e2f4ebf | 2765 | .Pp |
c5174ad4 | 2766 | The list and display macros to not do any keeps |
3e2f4ebf | 2767 | and certainly should be able to. |
be765ac2 CL |
2768 | .\" Note what happens if the parameter list overlaps a newline |
2769 | .\" boundary. | |
2770 | .\" to make sure a line boundary is crossed: | |
2771 | .\" .Bd -literal | |
2772 | .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] | |
2773 | .\" .Ed | |
2774 | .\" .Pp | |
2775 | .\" produces, nudge nudge, | |
2776 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , | |
2777 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , | |
2778 | .\" nudge | |
2779 | .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . | |
2780 | .\" .Pp | |
2781 | .\" If double quotes are used, for example: | |
2782 | .\" .Bd -literal | |
2783 | .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q | |
2784 | .\" .Ed | |
2785 | .\" .Pp | |
2786 | .\" produces, nudge nudge, | |
2787 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , | |
2788 | .\" nudge | |
2789 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , | |
2790 | .\" nudge | |
2791 | .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . | |
2792 | .\" .Pp | |
2793 | .\" Not a pretty sight... | |
2794 | .\" In a paragraph, a long parameter containing unpaddable spaces as | |
2795 | .\" in the former example will cause | |
2796 | .\" .Xr troff | |
2797 | .\" to break the line and spread | |
2798 | .\" the remaining words out. | |
2799 | .\" The latter example will adjust nicely to | |
2800 | .\" justified margins, but may break in between an argument and its | |
2801 | .\" declaration. | |
2802 | .\" In | |
2803 | .\" .Xr nroff | |
2804 | .\" the right margin adjustment is normally ragged and the problem is | |
2805 | .\" not as severe. |