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