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