Debian Codegraph @

upstream/debian-unstable/man7/groff_mdoc.7

raw
1 '\" t
2 .\" a complete reference to the mdoc macro package for GNU troff
3 .\"
4 .\" Copyright (C) 1990, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Copyright 2001-2024 Free Software Foundation, Inc.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\" 3. [Deleted. See
19 .\" ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change]
20 .\" 4. Neither the name of the University nor the names of its
21 .\" contributors may be used to endorse or promote products derived
22 .\" from this software without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS"
25 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
27 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
28 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
31 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
32 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
33 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
34 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" SUCH DAMAGE.
36 .\"
37 .\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93
38 .\"
39 .\" This reference invokes every macro in the package several times and
40 .\" is guaranteed to give worst-case performance for an already
41 .\" extremely slow package.
42 .
43 .
44 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
45 .do nr *groff_groff_mdoc_7_man_C \n[.cp]
46 .cp 0
47 .
48 .
49 .Dd 2026-04-22
50 .Dt groff_mdoc 7
51 .Os groff 1.24.1
52 .
53 .
54 .Sh Name
55 .
56 .Nm groff_mdoc
57 .Nd compose BSD-style manual (man) pages with GNU
58 .Xr roff
59 .
60 .
61 .Sh Synopsis
62 .
63 .Nm groff Fl m Ns Cm doc Ar file No ...
64 .
65 .
66 .Sh Description
67 .
68 The GNU implementation of the
69 .Xr mdoc
70 macro package is part of the
71 .Xr groff 1
72 document formatting system.
73 .
74 .Xr mdoc
75 is a
76 structurally- and semantically-oriented package for writing
77 .Ux
78 manual pages with
79 .Xr \%troff 1 .
80 .
81 Its predecessor,
82 the
83 .Xr man 7
84 package,
85 primarily addressed page layout and presentational concerns,
86 leaving the selection of fonts and other typesetting details to the
87 individual author.
88 .
89 This discretion has led to divergent styling practices among authors
90 using it.
91 .
92 .
93 .Pp
94 .Xr mdoc
95 organizes its macros into
96 .Em domains .
97 .
98 The
99 .Em "page structure domain"
100 lays out the page and
101 comprises titles,
102 section headings,
103 displays,
104 and lists.
105 .
106 The
107 .Em "general text domain"
108 supplies macros to quote or style text,
109 or to interpolate common noun phrases.
110 .
111 The
112 .Em "manual domain"
113 offers semantic macros corresponding to the terminology used by
114 practitioners in discussion of
115 .Ux
116 commands,
117 routines,
118 and files.
119 .
120 Manual domain macros distinguish
121 command-line arguments and options,
122 function names,
123 function parameters,
124 pathnames,
125 variables,
126 cross references to other manual pages,
127 and so on.
128 .
129 These terms are meaningful both to the author and the readers of a
130 manual page.
131 .
132 It is hoped that the resulting increased consistency of the man page
133 corpus will enable easier translation to future documentation tools.
134 .
135 .
136 .Pp
137 Throughout
138 .Ux
139 documentation,
140 a manual entry is referred to simply as a
141 .Dq "man page" ,
142 regardless of its length,
143 without gendered implication,
144 and irrespective of the macro package selected for its composition.
145 .
146 .
147 .Sh "Getting started"
148 .
149 The
150 .Xr mdoc
151 package attempts to simplify man page authorship and maintenance without
152 requiring mastery of the
153 .Xr roff
154 language.
155 .
156 This document presents only essential facts about
157 .Xr roff.
158 .
159 For further background,
160 including a discussion of basic typographical concepts like
161 .Dq breaking ,
162 .Dq filling ,
163 and
164 .Dq adjustment ,
165 see
166 .Xr roff 7 .
167 .
168 Specialized units of measurement also arise,
169 namely
170 ens,
171 vees,
172 inches,
173 and points,
174 abbreviated
175 .Dq n ,
176 .Dq v ,
177 .Dq i ,
178 and
179 .Dq p ,
180 respectively;
181 see section
182 .Sx Measurements
183 of
184 .Xr groff 7 .
185 .
186 .
187 .Pp
188 For brief examples,
189 we employ an arrow notation illustrating a transformation of input on
190 the left to rendered output on the right.
191 .
192 Consider the
193 .Pf . Ic \&Dq
194 macro,
195 which double-quotes its arguments.
196 .
197 .Bl -tag -width ".Dq\ man page" -offset indent -compact
198 .It Li ".Dq man page"
199 \[->]
200 .Dq man page
201 .El
202 .
203 .
204 .Ss Usage
205 .
206 An
207 .Xr mdoc
208 .Em macro
209 is
210 .Em called
211 by placing the
212 .Xr roff
213 control character,
214 .Ql .\&
215 (dot)
216 at the beginning of a line followed by its name.
217 .\" XXX; All mdoc macro names except Brq, Bro, Brc are 2 characters long
218 .\" and thus portable to old troffs. Why the innovation here, when
219 .\" `Cq`, `Co`, and `Cc` were available? Try to sell this reform to
220 .\" Ingo Schwarze.
221 .
222 In this document,
223 we often discuss a macro name with this leading dot to identify it
224 clearly,
225 but the dot is
226 .Em not
227 part of its name.
228 .
229 Space or tab characters can separate the dot from the macro name.
230 .
231 Arguments may follow,
232 separated from the macro name and each other by spaces,
233 but
234 .Em not
235 tabs.
236 .
237 The dot at the beginning of the line prepares the formatter to expect a
238 macro name.
239 .
240 A dot followed immediately by a newline is ignored;
241 this is called the
242 .Em "empty request" .
243 .
244 To begin an input line with a dot
245 (or a neutral apostrophe
246 .Ql \[aq] )
247 in some context other than a macro call,
248 precede it with the
249 .Ql \e&
250 escape sequence;
251 this is a dummy character,
252 not formatted for output.
253 .
254 The backslash is the
255 .Xr roff
256 escape character;
257 it can appear anywhere and it always followed by at least one more
258 character.
259 .
260 If followed by a newline,
261 the backslash escapes the input line break;
262 you can thus keep input lines to a reasonable length without affecting
263 their interpretation.
264 .
265 .
266 .Pp
267 Macros in GNU
268 .Xr troff
269 accept an unlimited number of arguments;
270 other
271 .Xr troff Ns No s
272 often can't handle more than nine.
273 .
274 In some cases,
275 arguments may continue or extend onto the next input line
276 without resort to the
277 .Ql \e Ns Em newline
278 escape sequence;
279 see subsection
280 .Sx "Extended arguments"
281 below.
282 .
283 Neutral double quotes
284 .Li \[dq]
285 can be used to group multiple words into an argument;
286 see subsection
287 .Sx "Passing space characters in an argument"
288 below.
289 .
290 .
291 .Pp
292 Most of
293 .Xr mdoc Ns No 's
294 general text and manual domain macros
295 .Em parse
296 their argument lists
297 for
298 .Em callable
299 macro names.
300 .
301 This means that an argument in the list matching a general text or
302 manual domain macro name
303 (and defined to be callable)
304 will be called with the remaining arguments when it is encountered.
305 .
306 In such cases,
307 the argument,
308 although the name of a macro,
309 is not preceded by a dot.
310 .
311 Macro calls can thus be nested.
312 .
313 This approach to macro argument processing is a unique characteristic of
314 the
315 .Xr mdoc
316 package,
317 not a general feature of
318 .Xr roff
319 syntax.
320 .
321 .
322 .Pp
323 For example,
324 the option macro,
325 .Pf . Ic \&Op ,
326 may call the flag and argument macros,
327 .Pf . Ic \&Fl
328 and
329 .Pf . Ic \&Ar ,
330 to specify an optional flag with an argument.
331 .
332 .\" Use width of second example below.
333 .Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact
334 .It Li ".Op Fl s Ar bytes"
335 \[->]
336 .Op Fl s Ar bytes
337 .El
338 .
339 To prevent a word from being interpreted as a macro name,
340 precede it with the dummy character.
341 .
342 .Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact
343 .It Li ".Op \e&Fl s \e&Ar bytes"
344 \[->]
345 .Op \&Fl s \&Ar bytes
346 .El
347 .
348 .
349 .Pp
350 In this document,
351 a macro that parses its argument list for other macro names is termed
352 .Em parsed ;
353 macros that permit other macros to call them thus are described as
354 .Em callable .
355 .
356 This usage is a technical
357 .Em "faux pas" ,
358 since all
359 .Xr mdoc
360 macros are in fact interpreted
361 (unless prevented with
362 .Ql \e& ) ,
363 but as it is cumbersome to constantly refer to macros as
364 .Dq "being able to call other macros" ,
365 we employ the term
366 .Dq parsed
367 instead.
368 .
369 Except where explicitly stated,
370 all
371 .Xr mdoc
372 macros are parsed and callable.
373 .
374 .
375 .Pp
376 In the following,
377 we term an
378 .Xr mdoc
379 macro that starts a line
380 (with a leading dot)
381 a
382 .Em command
383 if a distinction from those appearing as arguments of other macros is
384 necessary.
385 .
386 .
387 .Ss "Passing space characters in an argument"
388 .
389 Sometimes it is desirable to give a macro an argument containing one or
390 more space characters,
391 for instance to specify a particular arrangement of arguments demanded
392 by the macro.
393 .
394 Additionally,
395 quoting multi-word arguments that are to be treated the same makes
396 .Xr mdoc
397 work faster;
398 macros that parse arguments do so once
399 (at most)
400 for each.
401 .
402 For example,
403 the function command
404 .Pf . Ic \&Fn
405 expects its first argument to be the name of a function and any
406 remaining arguments to be function parameters.
407 .
408 Because C language standards mandate the inclusion of types
409 .Em and
410 identifiers in the parameter lists of function definitions,
411 each
412 .Ql \&Fn
413 parameter after the first will be at least two words in length,
414 as in
415 .Dq Ar "int foo" .
416 .
417 .
418 .Pp
419 There are a few ways to embed a space in a macro argument.
420 .
421 One is to use the unadjustable space escape sequence
422 .Li \[rs] Ns Em space .
423 .
424 The formatter treats this escape sequence as if it were any other
425 printable character,
426 and will not break a line there as it would a word space when the
427 output line is full.
428 .
429 This method is useful for macro arguments that are not expected to
430 straddle an output line boundary,
431 but has a drawback:
432 this space does not adjust as others do when the output line is
433 formatted.
434 .
435 An alternative is to use the unbreakable space escape sequence,
436 .Ql \[rs]\[ti] ,
437 which cannot break but does adjust.
438 .
439 This
440 .Xr groff
441 extension is widely but not perfectly portable.
442 .
443 Another method is to enclose the string in double quotes.
444 .
445 .Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
446 -compact
447 .It Li ".Fn fetch char\e *str"
448 \[->]
449 .Fn fetch char\ *str
450 .It Li ".Fn fetch char\e\[ti]*str"
451 \[->]
452 .Fn fetch char\~*str
453 .It Li ".Fn fetch \[dq]char *str\[dq]"
454 \[->]
455 .Fn fetch "char *str"
456 .El
457 .
458 If the
459 .Ql \[rs]
460 before the space in the first example
461 or the double quotes in the third example
462 were omitted,
463 .Ql .Fn
464 would see three arguments,
465 and the result would contain an undesired comma.
466 .
467 .\" Use same width as before so it's easier to see the discrepancy.
468 .Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \
469 -compact
470 .It Li ".Fn fetch char *str"
471 \[->]
472 .Fn fetch char *str
473 .El
474 .
475 .
476 .\".Pp
477 .\" For an example of what happens when the parameter list overlaps a
478 .\" newline boundary,
479 .\" see the
480 .\" .Sx Bugs
481 .\" section.
482 .
483 .
484 .Ss "Trailing space characters"
485 .
486 .\" XXX: This claim of confusion is nonsense. The formatter ignores
487 .\" them. If mdoc doesn't, that's a bug or design flaw. It's still
488 .\" good style not to have them. Whitespace churn makes diff(1) and
489 .\" revision control users unhappy.
490 .\"
491 .\".Xr \%troff
492 .\"can be confused by space characters at the end of a line.
493 .
494 It is wise to remove trailing spaces from the ends of input lines.
495 .
496 Should the need arise to put a formattable space at the end of a line,
497 do so with the unadjustable or unbreakable space escape sequences.
498 .
499 .
500 .Ss "Formatting the backslash and other glyphs"
501 .
502 When you need the
503 .Xr roff
504 escape character
505 .Ql \[rs]
506 to appear in the output,
507 use
508 .Ql \[rs]e
509 or
510 .Ql \[rs][rs]
511 instead.
512 .
513 Strictly,
514 .Ql \[rs]e
515 formats the current escape character;
516 it works reliably as long as no
517 .Xr roff
518 request is used to change it,
519 which should never happen in man pages.
520 .
521 .Ql \[rs][rs]
522 is a
523 .Xr groff
524 .Em "special character"
525 escape sequence that explicitly formats the
526 .Dq "reverse solidus"
527 (backslash) glyph.
528 .
529 In general,
530 use special character escape sequences to format characters
531 outside the ISO\~646
532 .Pf ( Dq Tn ASCII )
533 or Unicode Basic Latin range,
534 and to format correct glyphs for the characters
535 .Sq \[dq] ,
536 .Dq \[aq] ,
537 .Sq \- ,
538 .Sq \[ha] ,
539 .Sq \[ga] ,
540 and
541 .Sq \[ti] .
542 .
543 .Xr groff_char 7
544 presents the formatter's special character identifiers,
545 annotating those that are portable to legacy systems.
546 .
547 Section
548 .Sx "Predefined strings"
549 below lists characters commonly used by
550 .Xr mdoc
551 documents.
552 .
553 .
554 .Ss "Other possible pitfalls"
555 .
556 .Xr "groff mdoc"
557 warns when an empty input line is found outside of a
558 .Em display ,
559 a topic presented in subsection
560 .Sx "Examples and displays"
561 below.
562 .
563 Use empty requests to space the source document for maintenance.
564 .
565 .
566 .Pp
567 Leading spaces cause a break and are formatted.
568 .
569 Avoid this behaviour if possible.
570 .
571 Similarly,
572 do not put more than one space between words in an ordinary text line;
573 they are not
574 .Dq normalized
575 to a single space as other text formatters might do.
576 .
577 .
578 .Pp
579 Don't try to use the neutral double quote character
580 .Ql \[dq]
581 to represent itself in an argument.
582 .
583 Use the special character escape sequence
584 .Ql \[rs][dq]
585 to format it.
586 .\" That's NOT a groffism, but showed up in the "post" and "Latin1"
587 .\" devices of Documenter's Workbench (DWB) 3.3 troff.
588 .
589 Avoid using
590 .Ql \[rs][dq]
591 for conventional quotation;
592 see subsection
593 .Sx "Enclosure and quoting macros"
594 below.
595 .
596 .
597 .Pp
598 If your document must be portable to legacy systems like
599 .Bx 4.4 ,
600 special character escape sequences shown here in the form
601 .Li \[rs][ Ns Va xx Ns Li ]
602 must be spelled
603 .Li \[rs]( Ns Va xx
604 instead.
605 .
606 No version of
607 .Xr groff
608 or
609 .Xr mandoc
610 requires the latter form.
611 .
612 .
613 .Pp
614 As a typesetting system,
615 .Xr roff
616 distinguishes hyphens,
617 minus signs,
618 and dashes of various widths.
619 .
620 When inputting a hyphen or dash
621 .Pq Dq hyphen-minus
622 (Unicode U+002D)
623 that should be usable
624 in URLs
625 or copy-and-paste operations to shell prompts or program code,
626 prefix it with the escape character:
627 .Ql \[rs]\- .
628 .
629 .
630 .Pp
631 The formatter attempts to detect the ends of sentences and by default
632 puts the equivalent of two spaces between sentences on the same output
633 line;
634 see
635 .Xr roff 7 .
636 .
637 To defeat this detection in a parsed list of macro arguments,
638 put
639 .Ql \e&
640 before the punctuation mark.
641 .
642 Thus,
643 .
644 .Bd -literal -offset indent -compact
645 The
646 \&.Ql .
647 character.
648 \&.Pp
649 The
650 \&.Ql \e&.
651 character.
652 \&.Pp
653 \&.No test .
654 test
655 \&.Pp
656 \&.No test.
657 test
658 .Ed
659 .
660 gives
661 .
662 .Bd -filled -offset indent -compact
663 The
664 .Ql .
665 character
666 .
667 .
668 .Pp
669 The
670 .Ql \&.
671 character.
672 .
673 .
674 .Pp
675 .No test .
676 test
677 .
678 .
679 .Pp
680 .No test.
681 test
682 .Ed
683 .
684 as output.
685 .
686 As can be seen in the first and third output lines,
687 .Xr mdoc
688 handles punctuation characters specially in macro arguments.
689 .
690 This will be explained in section
691 .Sx "General syntax"
692 below.
693 .
694 .
695 .Pp
696 A comment in the source file of a man page can begin with
697 .Ql .\e\[dq]
698 at the start of an input line,
699 .Ql \e\[dq]
700 after other input,
701 or
702 .Ql \e#
703 anywhere
704 (the last is a
705 .Xr groff
706 extension);
707 the remainder of any such line is ignored.
708 .
709 .
710 .Sh "A man page template"
711 .
712 Use
713 .Xr mdoc
714 to construct a man page from the following template.
715 .
716 .Bd -literal -offset indent
717 \&.\e" The following three macro calls are required.
718 \&.Dd date
719 \&.Dt identifier [section-id [section-keyword-or-title]]
720 \&.Os [package-or-operating system [version-or-release]]
721 \&.Sh Name
722 \&.Nm topic
723 \&.Nd summary-description
724 \&.\e" The next heading is used in sections 2 and 3.
725 \&.\e" .Sh Library
726 \&.\e" The next heading is used in sections 1-4, 6, 8, and 9.
727 \&.Sh Synopsis
728 \&.Sh Description
729 \&.\e" Uncomment and populate the following sections as needed.
730 \&.\e" .Sh \[dq]Implementation notes\[dq]
731 \&.\e" The next heading is used in sections 2, 3, and 9.
732 \&.\e" .Sh \[dq]Return values\[dq]
733 \&.\e" The next heading is used in sections 1, 3, 6, and 8.
734 \&.\e" .Sh Environment
735 \&.\e" .Sh Files
736 \&.\e" The next heading is used in sections 1, 6, and 8.
737 \&.\e" .Sh \[dq]Exit status\[dq]
738 \&.\e" .Sh Examples
739 \&.\e" The next heading is used in sections 1, 4, 6, 8, and 9.
740 \&.\e" .Sh Diagnostics
741 \&.\e" .Sh Compatibility
742 \&.\e" The next heading is used in sections 2, 3, 4, and 9.
743 \&.\e" .Sh Errors
744 \&.\e" .Sh \[dq]See also\[dq]
745 \&.\e" .Sh Standards
746 \&.\e" .Sh History
747 \&.\e" .Sh Authors
748 \&.\e" .Sh Caveats
749 \&.\e" .Sh Bugs
750 .Ed
751 .
752 .
753 .Pp
754 The first items in the template are the commands
755 .Pf . Ic \&Dd ,
756 .Pf . Ic \&Dt ,
757 and
758 .Pf . Ic \&Os .
759 .
760 They identify the page and are discussed below in section
761 .Sx "Title macros" .
762 .
763 .
764 .Pp
765 The remaining items in the template are section headings
766 .Pf ( Pf . Ic \&Sh ) ;
767 of which
768 .Sx Name
769 and
770 .Sx Description
771 are mandatory.
772 .
773 These headings are discussed in section
774 .Sx "Page structure domain" ,
775 which follows section
776 .Sx "Manual domain" .
777 .
778 Familiarize yourself with manual domain macros first;
779 we use them to illustrate the use of page structure domain macros.
780 .
781 .
782 .Sh Conventions
783 .
784 In the descriptions of macros below,
785 square brackets surround optional arguments.
786 .
787 An ellipsis
788 .Pf ( Sq ... )
789 represents repetition of the preceding argument zero or more times.
790 .
791 Alternative values of a parameter are separated with
792 .Ql | .
793 .
794 If a mandatory parameter can take one of several alternative values,
795 use braces to enclose the set,
796 with spaces and
797 .Ql |
798 separating the items.
799 .
800 .\" XXX: Angle brackets should only be necessary when space doesn't
801 .\" separate parameters.
802 .\" .
803 .\" Metasyntactic variables are specified within angle brackets.
804 .\"Bl -tag -width 6n -offset indent -compact
805 .Bl -tag -offset indent -compact
806 .It Nm ztar Xo
807 .Brq Cm c | Cm x
808 .Op Fl w Op Fl y | Fl z
809 .Op Fl f Ar archive
810 .Ar member No ...
811 .Xc
812 .El
813 .
814 An alternative to using braces is to separately synopsize distinct
815 operation modes,
816 particularly if the list of valid optional arguments is dependent on the
817 user's choice of a mandatory parameter.
818 .
819 .Bl -tag -offset indent -compact
820 .It Nm ztar Xo
821 .Cm c
822 .Op Fl w Op Fl y | Fl z
823 .Op Fl f Ar archive
824 .Ar member No ...
825 .Xc
826 .It Nm ztar Xo
827 .Cm x
828 .Op Fl w Op Fl y | Fl z
829 .Op Fl f Ar archive
830 .Ar member No ...
831 .Xc
832 .El
833 .
834 .
835 .Pp
836 Most macros affect subsequent arguments until another macro or a newline
837 is encountered.
838 .
839 For example,
840 .Sq Li ".Li ls Bq Ar file"
841 doesn't produce
842 .Sq Li "ls [file]" ,
843 but
844 .Sq Li ls Bq Ar file .
845 .
846 Consequently,
847 a warning message is emitted for many commands if the first argument is
848 itself a macro,
849 since it cancels the effect of the preceding one.
850 .\" XXX: I don't think it is made clear which macros eat only one
851 .\" argument and which ones devour tokens until another macro is
852 .\" encountered. -- GBR
853 .
854 On rare occasions,
855 you might want to format a word along with surrounding brackets as a
856 literal.
857 .
858 .\" XXX: Why do we need the extra "\ " for the width parameter? Without
859 .\" it, the line breaks before the arrow on a 78n terminal. But there
860 .\" should be room anyway...bug?
861 .\"
862 .\" XXX: Arguably, Bq should respect the altered font family in a `Bl`,
863 .\" but it sets the brackets and argument in Times roman. Maybe all the
864 .\" enclosures work this way.
865 .Bl -tag -width "Li\ \[dq]ls\ [file]\[dq]\ " -offset indent -compact
866 .It Li ".Li \[dq]ls [file]\[dq]"
867 \[->]
868 .Li "ls [file]"
869 .Em "# list any files named e, f, i, or l"
870 .El
871 .
872 .
873 .Pp
874 Many macros possess an implicit width,
875 .\" See tmac/mdoc/doc-common for values.
876 used when they are contained in lists and displays.
877 .
878 If you avoid relying on these default measurements,
879 you escape potential conflicts with site-local modifications of the
880 .Xr mdoc
881 package.
882 .
883 Explicit
884 .Fl width
885 and
886 .Fl offset
887 arguments to the
888 .Pf . Ic \&Bl
889 and
890 .Pf . Ic \&Bd
891 macros are preferable.
892 .
893 .
894 .Sh "Title macros"
895 .
896 We present the
897 .Sy mandatory
898 title macros first due to their importance even though they formally
899 belong to the page structure domain macros.
900 .\" XXX: This was formerly "...for someone who wishes to start writing a
901 .\" man page yesterday."
902 .\"
903 .\" Cute joke, but we're 800+ lines into this page source and four pages
904 .\" into the document when formatted for U.S. letter paper. We lost
905 .\" that kind of reader last _week_.
906 .
907 They designate the
908 page identifier and section of the manual,
909 date of last revision,
910 and the operating system or software project associated with the page.
911 .
912 Call each once at the beginning of the document.
913 .
914 They populate the page headers and footers,
915 .Dq titles
916 in
917 .Xr roff
918 parlance.
919 .
920 .
921 .Bl -tag -width 6n
922 .It Li .Dd Xo
923 .Ar date
924 .Xc
925 This first macro of any
926 .Xr mdoc
927 manual records the last modification date of the document source.
928 .
929 Arguments are catenated and separated with space characters.
930 .
931 .
932 .Pp
933 Historically,
934 .Ar date
935 was written in U.S.\& traditional format,
936 .Do
937 .Ar Month day Li , Ar year
938 .Dc
939 where
940 .Em Month
941 is the full month name in English,
942 .Em day
943 an integer without a leading zero,
944 and
945 .Em year
946 the four-digit year.
947 .
948 This localism is not enforced,
949 however.
950 .
951 .Xr groff
952 recommends ISO\~8601 format,
953 .Em YYYY-MM-DD.
954 .
955 A
956 .Ar date
957 of the form
958 .Sq Li $Mdocdate: Ar Month day year Li $
959 is also recognized.
960 .
961 It is used in
962 .Ox
963 manuals to automatically insert the current date when committing.
964 .
965 .
966 .Pp
967 This macro is neither callable nor parsed.
968 .
969 .
970 .\"br
971 .\"ne 5v
972 .It Li .Dt Ar identifier Op Ar section-id \
973 Op Ar section-keyword-or-title
974 .
975 .Ar identifier
976 and
977 .Ar section-id
978 together should uniquely indicate the man page on the system.
979 .
980 A
981 .Ar section-id
982 that begins with an integer in the range 1\[en]9
983 or is one of the words
984 .Ql unass ,
985 .Ql draft ,
986 or
987 .Ql paper
988 selects a predefined section title.
989 .
990 This use of
991 .Dq section
992 has nothing to do with the section headings otherwise discussed in this
993 page;
994 it arises from the organizational scheme of printed and bound Unix
995 manuals.
996 .
997 .
998 .br
999 .ne 3v
1000 .Pp
1001 In this implementation,
1002 the following titles are defined for integral section numbers.
1003 .
1004 .
1005 .Bd -unfilled -offset indent
1006 .TS
1007 Lf(CR) L.
1008 1 \*[doc-volume-ds-1]
1009 2 \*[doc-volume-ds-2]
1010 3 \*[doc-volume-ds-3]
1011 4 \*[doc-volume-ds-4]
1012 5 \*[doc-volume-ds-5]
1013 6 \*[doc-volume-ds-6]
1014 7 \*[doc-volume-ds-7]
1015 8 \*[doc-volume-ds-8]
1016 9 \*[doc-volume-ds-9]
1017 .TE
1018 .Ed
1019 .
1020 .
1021 .Pp
1022 A section title may be arbitrary or one of the following abbreviations.
1023 .
1024 .
1025 .Bd -unfilled -offset indent
1026 .TS
1027 Lf(CR) L.
1028 USD \*[doc-volume-ds-USD]
1029 PS1 \*[doc-volume-ds-PS1]
1030 AMD \*[doc-volume-ds-AMD]
1031 SMM \*[doc-volume-ds-SMM]
1032 URM \*[doc-volume-ds-URM]
1033 PRM \*[doc-volume-ds-PRM]
1034 KM \*[doc-volume-ds-KM]
1035 IND \*[doc-volume-ds-IND]
1036 LOCAL \*[doc-volume-ds-LOCAL]
1037 CON \*[doc-volume-ds-CON]
1038 .TE
1039 .Ed
1040 .
1041 .
1042 .Pp
1043 For compatibility,
1044 .Ql MMI
1045 can be used for
1046 .Ql IND ,
1047 and
1048 .Ql LOC
1049 for
1050 .Ql LOCAL .
1051 .
1052 Values from the previous table will specify a new section title.
1053 .
1054 If
1055 .Ar section-keyword-or-title
1056 designates a computer architecture recognized by
1057 .Xr "groff mdoc" ,
1058 its value is prepended to the default section title as specified by the
1059 second parameter.
1060 .\" mandoc(1) appears to put the architecture string after (or in place
1061 .\" of) the section title, in parentheses.
1062 .
1063 By default,
1064 the following architecture keywords are defined.
1065 .
1066 \# we use 'No' to avoid hyphenation
1067 .\" Resort to ps/vs violence if necessary because this macro package is
1068 .\" obsessed with dumping gigantic piles of identifiers on users, and I
1069 .\" need the space to keep this macro description to a single page in
1070 .\" PS/PDF(!). Lists of information like this simply beg to bit-rot.
1071 .\" -- GBR
1072 .br
1073 .if t \{\
1074 .ps -2
1075 .vs -2
1076 .\}
1077 .Bd -ragged -offset 4n
1078 .No acorn26 , acorn32 , algor , alpha , amd64 , amiga , amigappc ,
1079 .No arc , arm , arm26 , arm32 , armish , atari , aviion ,
1080 .No beagle , bebox , cats , cesfic , cobalt , dreamcast ,
1081 .No emips , evbarm , evbmips , evbppc , evbsh3 , ews4800mips ,
1082 .No hp300 , hp700 , hpcarm , hpcmips , hpcsh , hppa , hppa64 ,
1083 .No i386 , ia64 , ibmnws , iyonix , landisk , loongson , luna68k ,
1084 .No luna88k , m68k , mac68k , macppc , mips , mips64 , mipsco , mmeye ,
1085 .No mvme68k , mvme88k , mvmeppc , netwinder , news68k , newsmips ,
1086 .No next68k , ofppc , palm , pc532 , playstation2 , pmax , pmppc ,
1087 .No powerpc , prep , rs6000 , sandpoint , sbmips , sgi , sgimips , sh3 ,
1088 .No shark , socppc , solbourne , sparc , sparc64 , sun2 , sun3 ,
1089 .No tahoe , vax , x68k , x86_64 , xen , zaurus
1090 .Ed
1091 .if t \{\
1092 .vs
1093 .ps
1094 .\}
1095 .
1096 .
1097 .Pp
1098 If a section title is not determined after the above matches have been
1099 attempted,
1100 .Ar section-keyword-or-title
1101 is used.
1102 .
1103 .
1104 .\"br
1105 .\"ne 10v \" Keep explanatory paragraph with the following table.
1106 .Pp
1107 The effects of varying
1108 .Ql .Dt
1109 arguments on the page header content
1110 are shown below.
1111 .
1112 Observe how
1113 .Ql \[rs]&
1114 prevents the numeral\~2 from being used to look up a predefined section
1115 title.
1116 .
1117 .
1118 .Pp
1119 .\" On terminals, 2n is as far as we can offset without overrunning a
1120 .\" 78n width.
1121 .Bd -unfilled -offset 2n
1122 .TS
1123 tab(@);
1124 Lf(CR)1 L2 L C R.
1125 \&.Dt foo 2@\[->]@foo(2)@System Calls Manual@foo(2)
1126 \&.Dt foo 2 m68k@\[->]@foo(2)@m68k System Calls Manual@foo(2)
1127 \&.Dt foo 2 baz@\[->]@foo(2)@System Calls Manual@foo(2)
1128 \&.Dt foo \[rs]&2 baz@\[->]@foo(2)@baz@foo(2)
1129 \&.Dt foo \[dq]\[dq] baz@\[->]@foo@baz@foo
1130 \&.Dt foo M Z80@\[->]@foo(M)@Z80@foo(M)
1131 .TE
1132 .Ed
1133 .
1134 .
1135 .Pp
1136 .Xr roff
1137 strings define section titles and architecture identifiers.
1138 .
1139 Site-specific additions might be found in the file
1140 .Pa mdoc.local ;
1141 see section
1142 .Sx Files
1143 below.
1144 .
1145 .
1146 .Pp
1147 This macro is neither callable nor parsed.
1148 .
1149 .
1150 .It Li .Os Op Ar operating-system-or-package-name \
1151 Op Ar version-or-release
1152 .
1153 This macro associates the document with a software distribution.
1154 .
1155 When composing a man page to be included in the base installation of an
1156 operating system,
1157 do not provide an argument;
1158 .Xr mdoc
1159 will supply it.
1160 .
1161 In this implementation,
1162 that default is
1163 .Dq "\*[doc-default-operating-system]" .
1164 .
1165 It may be overridden in the site configuration file,
1166 .Pa mdoc.local ;
1167 see section
1168 .Sx Files
1169 below.
1170 .
1171 A portable software package maintaining its own man pages can supply
1172 its name and version number or release identifier as optional arguments.
1173 .
1174 A
1175 .Em version-or-release
1176 argument should use the standard nomenclature for the software
1177 specified.
1178 .
1179 In the following table,
1180 recognized
1181 .Em version-or-release
1182 arguments for some predefined operating systems are listed.
1183 .
1184 As with
1185 .Pf . Ic \&Dt ,
1186 site additions might be defined in
1187 .Pa mdoc.local .
1188 .
1189 .Bd -ragged -compact
1190 .Bl -tag -width ".No DragonFly" -offset indent
1191 .It ATT
1192 7th, 7, III, 3, V, V.2, V.3, V.4
1193 .It BSD
1194 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
1195 .It NetBSD
1196 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.2e,
1197 1.3, 1.3a, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.6,
1198 1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 3.0, 3.0.1, 3.0.2,
1199 3.0.3, 3.1, 3.1.1, 4.0, 4.0.1, 5.0, 5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3,
1200 5.1.4, 5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6,
1201 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1, 7.0.2, 7.1, 7.1.1,
1202 7.1.2, 7.2, 8.0, 8.1
1203 .It FreeBSD
1204 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6, 2.1.7, 2.2,
1205 2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2, 3.3,
1206 3.4, 3.5, 4.0, 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8,
1207 4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3, 5.4, 5.5, 6.0, 6.1, 6.2,
1208 6.3, 6.4, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 9.0, 9.1,
1209 9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0,
1210 12.1
1211 .It OpenBSD
1212 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0, 3.1, 3.2, 3.3,
1213 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7,
1214 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 6.0, 6.1,
1215 6.2, 6.3, 6.4, 6.5, 6.6
1216 .It DragonFly
1217 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.8.1, 1.9, 1.10, 1.11,
1218 1.12, 1.12.2, 1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9,
1219 2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2,
1220 3.2.1, 3.2.2, 3.3, 3.4, 3.4.1, 3.4.2, 3.4.3, 3.5, 3.6, 3.6.1, 3.6.2,
1221 3.7, 3.8, 3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4, 4.0.5, 4.0.6,
1222 4.1, 4.2, 4.2.1, 4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1, 4.4.2, 4.4.3,
1223 4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1,
1224 5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2, 5.4.3, 5.5, 5.6, 5.6.1, 5.6.2
1225 .It Darwin
1226 8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0, 8.7.0, 8.8.0, 8.9.0,
1227 8.10.0, 8.11.0, 9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0, 9.7.0,
1228 9.8.0, 10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0, 10.5.0, 10.6.0, 10.7.0,
1229 10.8.0, 11.0.0, 11.1.0, 11.2.0, 11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0,
1230 12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0, 14.0.0, 14.1.0, 14.2.0,
1231 14.3.0, 14.4.0, 14.5.0, 15.0.0, 15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0,
1232 15.6.0, 16.0.0, 16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0, 16.6.0, 17.0.0,
1233 17.1.0, 17.2.0, 17.3.0, 17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0,
1234 18.2.0, 18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0
1235 .El
1236 .Ed
1237 .
1238 .
1239 .Pp
1240 Historically,
1241 the first argument used with
1242 .Pf . Ic \&Dt
1243 was
1244 .Li BSD
1245 or
1246 .Li ATT .
1247 .
1248 An unrecognized version argument after
1249 .Li ATT
1250 is replaced with
1251 .Dq Ux ;
1252 for other predefined abbreviations,
1253 it is ignored and a warning diagnostic emitted.
1254 .
1255 Otherwise,
1256 unrecognized arguments are displayed verbatim in the page footer.
1257 .
1258 For instance,
1259 this page uses
1260 .Dq Li .Os groff 1.24.1
1261 whereas a locally produced page might employ
1262 .Dq Li .Os \[dq]UXYZ CS Department\[dq] ,
1263 omitting versioning.
1264 .
1265 .
1266 .Pp
1267 This macro is neither callable nor parsed.
1268 .El
1269 .
1270 .
1271 .\"br
1272 .\"ne 4v
1273 .Sh "Introduction to manual and general text domains"
1274 .
1275 .
1276 .Ss "What's in a Name" Ns ... \" XXX: Ns not scrubbed for PDF bookmark
1277 .
1278 The manual domain macro names are derived from the day to day informal
1279 language used to describe commands, subroutines and related files.
1280 Slightly different variations of this language are used to describe the
1281 three different aspects of writing a man page.
1282 First, there is the description of
1283 .Xr mdoc
1284 macro command usage.
1285 Second is the description of a
1286 .Ux
1287 command
1288 .Em with
1289 .Xr mdoc
1290 macros, and third, the description of a command to a user in the verbal
1291 sense; that is, discussion of a command in the text of a man page.
1292 .
1293 .
1294 .Pp
1295 In the first case,
1296 .Xr \%troff
1297 macros are themselves a type of command;
1298 the general syntax for a
1299 .Xr troff
1300 command is:
1301 .
1302 .Bd -filled -offset indent
1303 .Li ".Xx argument1 argument2" ...
1304 .Ed
1305 .
1306 .
1307 .Pp
1308 .
1309 .Ql .Xx
1310 is a macro command, and anything following it are arguments to
1311 be processed.
1312 In the second case, the description of a
1313 .Ux
1314 command using the manual domain macros is a bit more involved;
1315 a typical
1316 .Sx Synopsis
1317 command line might be displayed as:
1318 .
1319 .Bd -filled -offset indent
1320 .Nm filter
1321 .Op Fl flag
1322 .Ao Ar infile Ac Ao Ar outfile Ac
1323 .Ed
1324 .
1325 .
1326 .Pp
1327 Here,
1328 .Nm filter
1329 is the command name and the
1330 bracketed string
1331 .Fl flag
1332 is a
1333 .Em flag
1334 argument designated as optional by the option brackets.
1335 In
1336 .Xr mdoc
1337 terms,
1338 .Ao Ar infile Ac
1339 and
1340 .Ao Ar outfile Ac
1341 are called
1342 .Em meta arguments ;
1343 in this example, the user has to replace the meta expressions given in angle
1344 brackets with real file names.
1345 Note that in this document meta arguments are used to describe
1346 .Xr mdoc
1347 commands; in most man pages, meta variables are not specifically written
1348 with angle brackets.
1349 .
1350 The macros that formatted the above example:
1351 .
1352 .Bd -literal -offset indent
1353 \&.Nm filter
1354 \&.Op Fl flag
1355 \&.Ao Ar infile Ac Ao Ar outfile Ac
1356 .Ed
1357 .
1358 .
1359 .Pp
1360 In the third case,
1361 discussion of commands and command syntax includes both examples above,
1362 but may add more detail.
1363 .
1364 The arguments
1365 .Ao Ar infile Ac
1366 and
1367 .Ao Ar outfile Ac
1368 from the example above might be referred to as
1369 .Em operands
1370 or
1371 .Em file arguments .
1372 .
1373 Some command-line argument lists are quite long:
1374 .
1375 .Bd -ragged
1376 .Bl -tag -width ".Nm make" -offset indent -compact
1377 .It Nm make
1378 .Op Fl eiknqrstv
1379 .Op Fl D Ar variable
1380 .Op Fl d Ar flags
1381 .Op Fl f Ar makefile
1382 .Op Fl I Ar directory
1383 .Op Fl j Ar max_jobs
1384 .Op Ar variable Ns = Ns Ar value
1385 .Bk
1386 .Op Ar target No ...
1387 .Ek
1388 .El
1389 .Ed
1390 .
1391 .
1392 .Pp
1393 Here one might talk about the command
1394 .Xr make
1395 and qualify the argument,
1396 .Ar makefile ,
1397 as an argument to the flag,
1398 .Fl f ,
1399 or discuss the optional file operand
1400 .Ar target .
1401 In the verbal context, such detail can prevent confusion, however the
1402 .Xr mdoc
1403 package does not have a macro for an argument
1404 .Em to
1405 a flag.
1406 Instead the
1407 .Ql \&Ar
1408 argument macro is used for an operand or file argument like
1409 .Ar target
1410 as well as an argument to a flag like
1411 .Ar variable .
1412 The make command line was produced from:
1413 .
1414 .Bd -literal -offset indent
1415 \&.Nm make
1416 \&.Op Fl eiknqrstv
1417 \&.Op Fl D Ar variable
1418 \&.Op Fl d Ar flags
1419 \&.Op Fl f Ar makefile
1420 \&.Op Fl I Ar directory
1421 \&.Op Fl j Ar max_jobs
1422 \&.Op Ar variable Ns = Ns Ar value
1423 \&.Bk
1424 \&.Op Ar target ...
1425 \&.Ek
1426 .Ed
1427 .
1428 .
1429 .Pp
1430 The
1431 .Ql .Bk
1432 and
1433 .Ql .Ek
1434 macros are explained in
1435 .Sx Keeps .
1436 .
1437 .
1438 .Ss "General Syntax"
1439 .
1440 The manual domain and general text domain macros share a similar syntax
1441 with a few minor deviations;
1442 most notably,
1443 .Ql .Ar ,
1444 .Ql .Fl ,
1445 .Ql .Nm ,
1446 and
1447 .Ql .Pa
1448 differ only when called without arguments; and
1449 .Ql .Fn
1450 and
1451 .Ql .Xr
1452 impose an order on their argument lists.
1453 .
1454 All manual domain macros are capable of recognizing and properly
1455 handling punctuation,
1456 provided each punctuation character is separated by a leading space.
1457 .
1458 If a command is given:
1459 .
1460 .
1461 .Pp
1462 .Dl \&.Ar sptr, ptr),
1463 .
1464 .
1465 .Pp
1466 The result is:
1467 .
1468 .
1469 .Pp
1470 .Dl Ar sptr, ptr),
1471 .
1472 .
1473 .Pp
1474 The punctuation is not recognized and all is output in the
1475 font used by
1476 .Ql .Ar .
1477 If the punctuation is separated by a leading whitespace:
1478 .
1479 .
1480 .Pp
1481 .Dl \&.Ar "sptr , ptr ) ,"
1482 .
1483 .
1484 .Pp
1485 The result is:
1486 .
1487 .
1488 .Pp
1489 .Dl Ar sptr , ptr ) ,
1490 .
1491 .
1492 .Pp
1493 The punctuation is now recognized and output in the default font
1494 distinguishing it from the argument strings.
1495 .
1496 To remove the special meaning from a punctuation character,
1497 escape it with
1498 .Ql \e& .
1499 .
1500 .
1501 .Pp
1502 The following punctuation characters are recognized by
1503 .Xr mdoc :
1504 .
1505 .Bl -column -offset indent-two XXXXXX XXXXXX XXXXXX XXXXXX
1506 .It Li .\& Ta Li ,\& Ta Li :\& Ta Li ;\& Ta Li (\&
1507 .It Li )\& Ta Li [\& Ta Li ]\& Ta Li ?\& Ta Li !\&
1508 .El
1509 .
1510 .
1511 .Pp
1512 .
1513 .Xr troff
1514 is limited as a macro language,
1515 and has difficulty when presented with a string containing certain
1516 mathematical,
1517 logical,
1518 or quotation character sequences:
1519 .
1520 .Bd -literal -offset indent-two
1521 {+,\-,/,*,%,<,>,<=,>=,=,==,&,\[ga],\[aq],"}
1522 .Ed
1523 .
1524 .
1525 .Pp
1526 The problem is that
1527 .Xr troff
1528 may assume it is supposed to actually perform the operation or
1529 evaluation suggested by the characters.
1530 .
1531 To prevent the accidental evaluation of these characters,
1532 escape them with
1533 .Ql \e& .
1534 .
1535 Typical syntax is shown in the first manual domain macro displayed
1536 below,
1537 .Ql .Ad .
1538 .
1539 .
1540 .Sh "Manual domain"
1541 .
1542 .
1543 .Ss Addresses
1544 .
1545 The address macro identifies an address construct.
1546 .
1547 .
1548 .Pp
1549 .Dl Usage: .Ad Ao address Ac ...
1550 .
1551 .
1552 .Pp
1553 .Bl -tag -width ".Li .Ad\ f1\ ,\ f2\ ,\ f3\ :" -compact -offset 15n
1554 .It Li ".Ad addr1"
1555 .Ad addr1
1556 .It Li ".Ad addr1 ."
1557 .Ad addr1 .
1558 .It Li ".Ad addr1 , file2"
1559 .Ad addr1 , file2
1560 .It Li ".Ad f1 , f2 , f3 :"
1561 .Ad f1 , f2 , f3 :
1562 .It Li ".Ad addr ) ) ,"
1563 .Ad addr ) ) ,
1564 .El
1565 .
1566 .
1567 .Pp
1568 The default width is 12n.
1569 .
1570 .Ss "Author Name"
1571 .
1572 The
1573 .Ql .An
1574 macro is used to specify the name of the author of the item being
1575 documented, or the name of the author of the actual manual page.
1576 .
1577 .
1578 .Pp
1579 .Dl Usage: .An Ao author name Ac ...
1580 .
1581 .
1582 .Pp
1583 .Bl -tag -width ".Li .An\ \[dq]Joe\ Author\[dq]\ )\ )\ ," -offset 15n
1584 .It Li ".An \[dq]Joe Author\[dq]"
1585 .An "Joe Author"
1586 .It Li ".An \[dq]Joe Author\[dq] ,"
1587 .An "Joe Author" ,
1588 .It Li ".An \[dq]Joe Author\[dq] Aq [email protected]"
1589 .An "Joe Author" Aq [email protected]
1590 .It Li ".An \[dq]Joe Author\[dq] ) ) ,"
1591 .An "Joe Author" ) ) ,
1592 .El
1593 .
1594 .
1595 .Pp
1596 The default width is 12n.
1597 .
1598 .
1599 .Pp
1600 In a section titled
1601 .Dq Authors ,
1602 .Ql \&An
1603 causes a break,
1604 allowing each new name to appear on its own line.
1605 .
1606 If this is not desirable,
1607 .
1608 .Bd -literal -offset indent
1609 \&.An \-nosplit
1610 .Ed
1611 .
1612 .
1613 .Pp
1614 .
1615 call will turn this off.
1616 To turn splitting back on, write
1617 .
1618 .Bd -literal -offset indent
1619 \&.An \-split
1620 .Ed
1621 .
1622 .
1623 .Ss Arguments
1624 .
1625 The
1626 .Li .Ar
1627 argument macro may be used whenever an argument is referenced.
1628 .
1629 If called without arguments,
1630 .Sq Ar
1631 is output.
1632 .
1633 .
1634 .Pp
1635 .Dl Usage: .Ar Oo Ao argument Ac Oc No ...
1636 .
1637 .
1638 .Pp
1639 .Bl -tag -width ".Li .Ar\ file\ ...\ dest-dir" -compact -offset 15n
1640 .It Li .Ar
1641 .Ar
1642 .It Li ".Ar file1"
1643 .Ar file1
1644 .It Li ".Ar file1 ."
1645 .Ar file1 .
1646 .It Li ".Ar file1 file2"
1647 .Ar file1 file2
1648 .It Li ".Ar file ... dest-dir"
1649 .Ar file ... dest-dir
1650 .It Li ".Ar f1 f2 f3 :"
1651 .Ar f1 f2 f3 :
1652 .It Li ".Ar file ) ) ,"
1653 .Ar file ) ) ,
1654 .El
1655 .
1656 .
1657 .Pp
1658 .
1659 The default width is 12n.
1660 .
1661 .
1662 .Ss "Configuration Declaration (Section Four Only)"
1663 .
1664 The
1665 .Ql .Cd
1666 macro is used to demonstrate a
1667 .Xr config 8
1668 declaration for a device interface in a section four manual.
1669 .
1670 .
1671 .Pp
1672 .Dl Usage: .Cd Ao argument Ac ...
1673 .
1674 .
1675 .Pp
1676 .Bl -tag -width ".Li .Cd\ Xdevice\ le0\ at\ scode?X" -offset 15n
1677 .It Li ".Cd \[dq]device le0 at scode?\[dq]"
1678 .Cd "device le0 at scode?"
1679 .El
1680 .
1681 .
1682 .Pp
1683 In a section titled
1684 .Dq Synopsis ,
1685 .Ql \&Cd
1686 causes a break before and after its arguments.
1687 .
1688 .
1689 .Pp
1690 The default width is 12n.
1691 .
1692 .
1693 .Ss "Command Modifiers"
1694 .
1695 The command modifier is identical to the
1696 .Ql .Fl
1697 (flag) command with the exception that the
1698 .Ql .Cm
1699 macro does not assert a dash in front of every argument.
1700 Traditionally flags are marked by the preceding dash, however, some commands
1701 or subsets of commands do not use them.
1702 Command modifiers may also be specified in conjunction with interactive
1703 commands such as editor commands.
1704 See
1705 .Sx Flags .
1706 .
1707 .
1708 .Pp
1709 The default width is 10n.
1710 .
1711 .
1712 .Ss "Defined Variables"
1713 .
1714 A variable
1715 (or constant)
1716 that is defined in an include file is specified by the macro
1717 .Ql .Dv .
1718 .
1719 .
1720 .Pp
1721 .Dl Usage: .Dv Ao defined-variable Ac ...
1722 .
1723 .
1724 .Pp
1725 .Bl -tag -width ".Li .Dv\ MAXHOSTNAMELEN" -compact -offset 15n
1726 .It Li ".Dv MAXHOSTNAMELEN"
1727 .Dv MAXHOSTNAMELEN
1728 .It Li ".Dv TIOCGPGRP )"
1729 .Dv TIOCGPGRP )
1730 .El
1731 .
1732 .
1733 .Pp
1734 .
1735 The default width is 12n.
1736 .
1737 .
1738 .Ss Errnos
1739 .
1740 The
1741 .Ql .Er
1742 errno macro specifies the error return value for section 2,
1743 3,
1744 and\~9 library routines.
1745 .
1746 The second example below shows
1747 .Ql .Er
1748 used with the
1749 .Ql .Bq
1750 general text domain macro,
1751 as it would be used in a section two manual page.
1752 .
1753 .
1754 .Pp
1755 .Dl Usage: .Er Ao errno type Ac ...
1756 .Pp
1757 .Bl -tag -width ".Li .Bq\ Er\ ENOTDIR" -compact -offset 15n
1758 .It Li ".Er ENOENT"
1759 .Er ENOENT
1760 .It Li ".Er ENOENT ) ;"
1761 .Er ENOENT ) ;
1762 .It Li ".Bq Er ENOTDIR"
1763 .Bq Er ENOTDIR
1764 .El
1765 .Pp
1766 .
1767 The default width is 17n.
1768 .
1769 .
1770 .Ss "Environment Variables"
1771 .
1772 The
1773 .Ql .Ev
1774 macro specifies an environment variable.
1775 .Pp
1776 .Dl Usage: .Ev Ao argument Ac ...
1777 .Pp
1778 .Bl -tag -width ".Li .Ev\ PRINTER\ )\ )\ ," -compact -offset 15n
1779 .It Li ".Ev DISPLAY"
1780 .Ev DISPLAY
1781 .It Li ".Ev PATH ."
1782 .Ev PATH .
1783 .It Li ".Ev PRINTER ) ) ,"
1784 .Ev PRINTER ) ) ,
1785 .El
1786 .Pp
1787 .
1788 The default width is 15n.
1789 .
1790 .
1791 .Ss Flags
1792 .
1793 The
1794 .Ql .Fl
1795 macro handles command-line flags.
1796 It prepends a dash,
1797 .Ql \- ,
1798 to the flag.
1799 .
1800 For interactive command flags that are not prepended with a dash,
1801 the
1802 .Ql .Cm
1803 (command modifier)
1804 macro is identical,
1805 but without the dash.
1806 .
1807 .
1808 .Pp
1809 .Dl Usage: .Fl Ao argument Ac ...
1810 .Pp
1811 .Bl -tag -width ".Li .Fl\ xyz\ )\ ," -compact -offset 15n
1812 .It Li .Fl
1813 .Fl
1814 .It Li ".Fl cfv"
1815 .Fl cfv
1816 .It Li ".Fl cfv ."
1817 .Fl cfv .
1818 .It Li ".Cm cfv ."
1819 .Cm cfv .
1820 .It Li ".Fl s v t"
1821 .Fl s v t
1822 .It Li ".Fl \- ,"
1823 .Fl \- ,
1824 .It Li ".Fl xyz ) ,"
1825 .Fl xyz ) ,
1826 .It Li ".Fl |"
1827 .Fl |
1828 .El
1829 .Pp
1830 The
1831 .Ql .Fl
1832 macro without any arguments results in a dash representing stdin/stdout.
1833 Note that giving
1834 .Ql .Fl
1835 a single dash will result in two dashes.
1836 .Pp
1837 The default width is 12n.
1838 .
1839 .
1840 .Ss "Function Declarations"
1841 .
1842 The
1843 .Ql .Fd
1844 macro is used in the
1845 .Sx Synopsis
1846 section with section two or three functions.
1847 It is neither callable nor parsed.
1848 .Pp
1849 .Dl Usage: .Fd Ao argument Ac ...
1850 .Pp
1851 .Bl -tag -width ".Li .Fd\ X#include\ <sys/types.h>X" -compact -offset 15n
1852 .It Li ".Fd \[dq]#include <sys/types.h>\[dq]"
1853 .Fd "#include <sys/types.h>"
1854 .El
1855 .
1856 .
1857 .Pp
1858 In a section titled
1859 .Dq Synopsis ,
1860 .Ql \&Fd
1861 causes a break if a function has already been presented and a break has
1862 not occurred,
1863 leaving vertical space between one function declaration and the next.
1864 .\" XXX: that's not what "break" means
1865 .
1866 .
1867 .Pp
1868 In a section titled
1869 .Dq Synopsis ,
1870 the
1871 .Ql \&In
1872 macro represents the
1873 .Li #include
1874 statement,
1875 and is the short form of the above example.
1876 .
1877 It specifies the C\~header file as being included in a C\~program.
1878 .
1879 It also causes a break.
1880 .
1881 .
1882 .Pp
1883 While not in the
1884 .Dq Synopsis
1885 section,
1886 it represents the header file enclosed in angle brackets.
1887 .
1888 .
1889 .Pp
1890 .Dl Usage: .In Ao header file Ac
1891 .
1892 .
1893 .Pp
1894 .Bl -tag -width ".Li .In\ stdio.h" -compact -offset 15n
1895 .nr in-synopsis-section 1
1896 .It Li ".In stdio.h"
1897 .In stdio.h
1898 .nr in-synopsis-section 0
1899 .It Li ".In stdio.h"
1900 .In stdio.h
1901 .El
1902 .
1903 .
1904 .Ss "Function Types"
1905 .
1906 This macro is intended for the
1907 .Dq Synopsis
1908 section.
1909 .
1910 It may be used anywhere else in the man page without problems,
1911 but its main purpose is to present the function type
1912 (in BSD kernel normal form)
1913 for the
1914 .Dq Synopsis
1915 of sections two and three.
1916 .
1917 (It causes a break,
1918 allowing the function name to appear on the next line.)
1919 .
1920 .
1921 .Pp
1922 .Dl Usage: .Ft Ao type Ac ...
1923 .Pp
1924 .Bl -tag -width ".Li .Ft\ struct\ stat" -compact -offset 15n
1925 .It Li ".Ft struct stat"
1926 .Ft struct stat
1927 .El
1928 .
1929 .
1930 .Ss "Functions (Library Routines)"
1931 .
1932 The
1933 .Ql .Fn
1934 macro is modeled on
1935 .Tn ANSI\~C
1936 conventions.
1937 .Pp
1938 .Dl Usage: .Fn Ao function Ac Oo Ao parameter Ac Oc ...
1939 .Pp
1940 .Bl -tag -width ".Li .Fn\ align\ Xchar\ *ptrX\ ," -compact -offset 15n
1941 .It Li ".Fn getchar"
1942 .Fn getchar
1943 .It Li ".Fn strlen ) ,"
1944 .Fn strlen ) ,
1945 .It Li ".Fn align \[dq]char *ptr\[dq] ,"
1946 .Fn align "char *ptr" ,
1947 .El
1948 .Pp
1949 Note that any call to another macro signals the end of the
1950 .Ql .Fn
1951 call (it will insert a closing parenthesis at that point).
1952 .
1953 .
1954 .Pp
1955 For functions with many parameters
1956 (which is rare),
1957 the macros
1958 .Ql .Fo
1959 (function open)
1960 and
1961 .Ql .Fc
1962 (function close)
1963 may be used with
1964 .Ql .Fa
1965 (function argument).
1966 .Pp
1967 Example:
1968 .
1969 .Bd -literal -offset indent
1970 \&.Ft int
1971 \&.Fo res_mkquery
1972 \&.Fa "int op"
1973 \&.Fa "char *dname"
1974 \&.Fa "int class"
1975 \&.Fa "int type"
1976 \&.Fa "char *data"
1977 \&.Fa "int datalen"
1978 \&.Fa "struct rrec *newrr"
1979 \&.Fa "char *buf"
1980 \&.Fa "int buflen"
1981 \&.Fc
1982 .Ed
1983 .Pp
1984 .
1985 Produces:
1986 .
1987 .Bd -ragged -offset indent
1988 .Ft int
1989 .Fo res_mkquery
1990 .Fa "int op"
1991 .Fa "char *dname"
1992 .Fa "int class"
1993 .Fa "int type"
1994 .Fa "char *data"
1995 .Fa "int datalen"
1996 .Fa "struct rrec *newrr"
1997 .Fa "char *buf"
1998 .Fa "int buflen"
1999 .Fc
2000 .Ed
2001 .
2002 .
2003 .Pp
2004 Typically,
2005 in a
2006 .Dq Synopsis
2007 section,
2008 the function declaration will begin the line.
2009 .
2010 If more than one function is presented in the
2011 .Dq Synopsis
2012 section and a function type has not been given,
2013 a break will occur,
2014 leaving vertical space between the current and prior function names.
2015 .\" XXX: that's not what "break" means
2016 .
2017 .
2018 .Pp
2019 The default width values of
2020 .Ql .Fn
2021 and
2022 .Ql .Fo
2023 are 12n and 16n,
2024 respectively.
2025 .
2026 .
2027 .Ss "Function Arguments"
2028 .
2029 The
2030 .Ql .Fa
2031 macro is used to refer to function arguments (parameters) outside of the
2032 .Sx Synopsis
2033 section of the manual or inside the
2034 .Sx Synopsis
2035 section if the enclosure macros
2036 .Ql .Fo
2037 and
2038 .Ql .Fc
2039 instead of
2040 .Ql .Fn
2041 are used.
2042 .Ql .Fa
2043 may also be used to refer to structure members.
2044 .Pp
2045 .Dl Usage: .Fa Ao function argument Ac ...
2046 .Pp
2047 .Bl -tag -width ".Li .Fa\ d_namlen\ )\ )\ ," -compact -offset 15n
2048 .It Li ".Fa d_namlen ) ) ,"
2049 .Fa d_namlen ) ) ,
2050 .It Li ".Fa iov_len"
2051 .Fa iov_len
2052 .El
2053 .Pp
2054 .
2055 The default width is 12n.
2056 .
2057 .
2058 .Ss "Return Values"
2059 .
2060 The
2061 .Ql .Rv
2062 macro generates text for use in the
2063 .Sx Return values
2064 section.
2065 .Pp
2066 .Dl Usage: .Rv Oo \-std Oc Op Ao function Ac ...
2067 .Pp
2068 For example,
2069 .Ql ".Rv \-std atexit"
2070 produces:
2071 .
2072 .Bd -ragged -offset indent
2073 \# a small hack to suppress a warning message
2074 .ds doc-section-old "\*[doc-section]
2075 .ds doc-section 3
2076 .Rv -std atexit
2077 .ds doc-section "\*[doc-section-old]
2078 .Ed
2079 .Pp
2080 .
2081 The
2082 .Fl std
2083 option is valid only for manual page sections\~2 and\~3.
2084 Currently, this macro does nothing if used without the
2085 .Fl std
2086 flag.
2087 .
2088 .
2089 .Ss "Exit Status"
2090 .
2091 The
2092 .Ql .Ex
2093 macro generates text for use in the
2094 .Sx Diagnostics
2095 section.
2096 .Pp
2097 .Dl Usage: .Ex Oo \-std Oc Op Ao utility Ac ...
2098 .Pp
2099 For example,
2100 .Ql ".Ex \-std cat"
2101 produces:
2102 .
2103 .Bd -ragged -offset indent
2104 \# a small hack to suppress a warning message
2105 .ds doc-section-old "\*[doc-section]
2106 .ds doc-section 1
2107 .Ex -std cat
2108 .ds doc-section "\*[doc-section-old]
2109 .Ed
2110 .Pp
2111 .
2112 The
2113 .Fl std
2114 option is valid only for manual page sections 1, 6 and\~8.
2115 Currently, this macro does nothing if used without the
2116 .Fl std
2117 flag.
2118 .
2119 .
2120 .Ss "Interactive Commands"
2121 .
2122 The
2123 .Ql .Ic
2124 macro designates an interactive or internal command.
2125 .Pp
2126 .Dl Usage: .Ic Ao argument Ac ...
2127 .Pp
2128 .Bl -tag -width ".Li .Ic\ setenv\ ,\ unsetenv" -compact -offset 15n
2129 .It Li ".Ic :wq"
2130 .Ic :wq
2131 .It Li ".Ic \[dq]do while {...}\[dq]"
2132 .Ic "do while {...}"
2133 .It Li ".Ic setenv , unsetenv"
2134 .Ic setenv , unsetenv
2135 .El
2136 .Pp
2137 .
2138 The default width is 12n.
2139 .
2140 .
2141 .Ss "Library Names"
2142 .
2143 The
2144 .Ql .Lb
2145 macro is used to specify the library where a particular function is compiled
2146 in.
2147 .Pp
2148 .Dl Usage: .Lb Ao argument Ac ...
2149 .Pp
2150 Available arguments to
2151 .Ql .Lb
2152 and their results are:
2153 .
2154 .Pp
2155 .Bl -tag -width ".Li librpcsec_gss" -compact -offset indent
2156 .It Li libarchive
2157 .Lb libarchive
2158 .It Li libarm
2159 .Lb libarm
2160 .It Li libarm32
2161 .Lb libarm32
2162 .It Li libbluetooth
2163 .Lb libbluetooth
2164 .It Li libbsm
2165 .Lb libbsm
2166 .It Li libc
2167 .Lb libc
2168 .It Li libc_r
2169 .Lb libc_r
2170 .It Li libcalendar
2171 .Lb libcalendar
2172 .It Li libcam
2173 .Lb libcam
2174 .It Li libcdk
2175 .Lb libcdk
2176 .It Li libcipher
2177 .Lb libcipher
2178 .It Li libcompat
2179 .Lb libcompat
2180 .It Li libcrypt
2181 .Lb libcrypt
2182 .It Li libcurses
2183 .Lb libcurses
2184 .It Li libdevinfo
2185 .Lb libdevinfo
2186 .It Li libdevstat
2187 .Lb libdevstat
2188 .It Li libdisk
2189 .Lb libdisk
2190 .It Li libdwarf
2191 .Lb libdwarf
2192 .It Li libedit
2193 .Lb libedit
2194 .It Li libelf
2195 .Lb libelf
2196 .It Li libevent
2197 .Lb libevent
2198 .It Li libfetch
2199 .Lb libfetch
2200 .It Li libform
2201 .Lb libform
2202 .It Li libgeom
2203 .Lb libgeom
2204 .It Li libgpib
2205 .Lb libgpib
2206 .It Li libi386
2207 .Lb libi386
2208 .It Li libintl
2209 .Lb libintl
2210 .It Li libipsec
2211 .Lb libipsec
2212 .It Li libipx
2213 .Lb libipx
2214 .It Li libiscsi
2215 .Lb libiscsi
2216 .It Li libjail
2217 .Lb libjail
2218 .It Li libkiconv
2219 .Lb libkiconv
2220 .It Li libkse
2221 .Lb libkse
2222 .It Li libkvm
2223 .Lb libkvm
2224 .It Li libm
2225 .Lb libm
2226 .It Li libm68k
2227 .Lb libm68k
2228 .It Li libmagic
2229 .Lb libmagic
2230 .It Li libmd
2231 .Lb libmd
2232 .It Li libmemstat
2233 .Lb libmemstat
2234 .It Li libmenu
2235 .Lb libmenu
2236 .It Li libnetgraph
2237 .Lb libnetgraph
2238 .It Li libnetpgp
2239 .Lb libnetpgp
2240 .It Li libossaudio
2241 .Lb libossaudio
2242 .It Li libpam
2243 .Lb libpam
2244 .It Li libpcap
2245 .Lb libpcap
2246 .It Li libpci
2247 .Lb libpci
2248 .It Li libpmc
2249 .Lb libpmc
2250 .It Li libposix
2251 .Lb libposix
2252 .It Li libprop
2253 .Lb libprop
2254 .It Li libpthread
2255 .Lb libpthread
2256 .It Li libpuffs
2257 .Lb libpuffs
2258 .It Li librefuse
2259 .Lb librefuse
2260 .It Li libresolv
2261 .Lb libresolv
2262 .It Li librpcsec_gss
2263 .Lb librpcsec_gss
2264 .It Li librpcsvc
2265 .Lb librpcsvc
2266 .It Li librt
2267 .Lb librt
2268 .It Li libsdp
2269 .Lb libsdp
2270 .It Li libssp
2271 .Lb libssp
2272 .It Li libSystem
2273 .Lb libSystem
2274 .It Li libtermcap
2275 .Lb libtermcap
2276 .It Li libterminfo
2277 .Lb libterminfo
2278 .It Li libthr
2279 .Lb libthr
2280 .It Li libufs
2281 .Lb libufs
2282 .It Li libugidfw
2283 .Lb libugidfw
2284 .It Li libulog
2285 .Lb libulog
2286 .It Li libusbhid
2287 .Lb libusbhid
2288 .It Li libutil
2289 .Lb libutil
2290 .It Li libvgl
2291 .Lb libvgl
2292 .It Li libx86_64
2293 .Lb libx86_64
2294 .It Li libz
2295 .Lb libz
2296 .El
2297 .
2298 .
2299 .Pp
2300 Site-specific additions might be found in the file
2301 .Pa mdoc.local ;
2302 see section
2303 .Sx Files
2304 below.
2305 .
2306 .
2307 .Pp
2308 In a section titled
2309 .Dq Library ,
2310 .Ql \&Lb
2311 causes a break before and after its arguments.
2312 .
2313 .
2314 .Ss Literals
2315 .
2316 The
2317 .Ql \&Li
2318 literal macro may be used for special characters,
2319 symbolic constants,
2320 and other syntactical items that should be typed exactly as displayed.
2321 .
2322 .
2323 .Pp
2324 .Dl Usage: .Li Ao argument Ac ...
2325 .Pp
2326 .Bl -tag -width ".Li .Li\ cntrl\-D\ )\ ," -compact -offset 15n
2327 .It Li ".Li \een"
2328 .Li \en
2329 .It Li ".Li M1 M2 M3 ;"
2330 .Li M1 M2 M3 ;
2331 .It Li ".Li cntrl\-D ) ,"
2332 .Li cntrl-D ) ,
2333 .It Li ".Li 1024 ..."
2334 .Li 1024 ...
2335 .El
2336 .Pp
2337 .
2338 The default width is 16n.
2339 .
2340 .
2341 .Ss Names
2342 .
2343 The
2344 .Ql \&Nm
2345 macro identifies the document's central topic.
2346 .
2347 Upon its first call,
2348 it has the peculiarity of remembering its argument.
2349 .
2350 When subsequently called without arguments,
2351 .Ql \&Nm
2352 regurgitates this initial name for the sole purpose of making less work
2353 for the document's author.
2354 .
2355 Use of
2356 .Ql \&Nm
2357 is also appropriate when presenting a command synopsis for the topic of
2358 a man page in section 1,
2359 6,
2360 or 8.
2361 .
2362 Its behavior changes when presented with arguments of various forms.
2363 .
2364 .
2365 .Pp
2366 .Bl -tag -width ".Li .Nm\ groff_mdoc" -compact -offset 15n
2367 .It Li ".Nm groff_mdoc"
2368 .Nm groff_mdoc
2369 .It Li ".Nm"
2370 .Nm
2371 .It Li ".Nm \e\-mdoc"
2372 .Nm \-mdoc
2373 .It Li ".Nm foo ) ) ,"
2374 .Nm foo ) ) ,
2375 .It Li ".Nm :"
2376 .Nm :
2377 .El
2378 .
2379 .
2380 .Pp
2381 By default,
2382 the topic is set in boldface to reflect its prime importance in the
2383 discussion.
2384 .
2385 Cross references to other man page topics should use
2386 .Ql \&Xr ;
2387 including a second argument for the section number enables them to be
2388 hyperlinked.
2389 .
2390 By default,
2391 cross-referenced topics are set in italics to avoid cluttering the page
2392 with boldface.
2393 .
2394 .
2395 .Pp
2396 The default width is 10n.
2397 .
2398 .
2399 .Ss Options
2400 The
2401 .Ql .Op
2402 macro places option brackets around any remaining arguments on the
2403 command line,
2404 and places any trailing punctuation outside the brackets.
2405 .
2406 The macros
2407 .Ql .Oo
2408 and
2409 .Ql .Oc
2410 (which produce an opening and a closing option bracket,
2411 respectively)
2412 may be used across one or more lines or to specify the exact position of
2413 the closing parenthesis.
2414 .
2415 .
2416 .Pp
2417 .Dl Usage: .Op Oo Ao option Ac Oc ...
2418 .Pp
2419 .Bl -tag -width ".Li .Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ," -compact -offset 15n
2420 .It Li .Op
2421 .Op
2422 .It Li ".Op Fl k"
2423 .Op Fl k
2424 .It Li ".Op Fl k ) ."
2425 .Op Fl k ) .
2426 .It Li ".Op Fl k Ar kookfile"
2427 .Op Fl k Ar kookfile
2428 .It Li ".Op Fl k Ar kookfile ,"
2429 .Op Fl k Ar kookfile ,
2430 .It Li ".Op Ar objfil Op Ar corfil"
2431 .Op Ar objfil Op Ar corfil
2432 .It Li ".Op Fl c Ar objfil Op Ar corfil ,"
2433 .Op Fl c Ar objfil Op Ar corfil ,
2434 .It Li ".Op word1 word2"
2435 .Op word1 word2
2436 .It Li ".Li .Op Oo Ao option Ac Oc ..."
2437 .Li .Op Oo Ao option Ac Oc ...
2438 .El
2439 .Pp
2440 Here a typical example of the
2441 .Ql .Oo
2442 and
2443 .Ql .Oc
2444 macros:
2445 .
2446 .Bd -literal -offset indent
2447 \&.Oo
2448 \&.Op Fl k Ar kilobytes
2449 \&.Op Fl i Ar interval
2450 \&.Op Fl c Ar count
2451 \&.Oc
2452 .Ed
2453 .Pp
2454 .
2455 Produces:
2456 .
2457 .Bd -filled -offset indent
2458 .Oo
2459 .Op Fl k Ar kilobytes
2460 .Op Fl i Ar interval
2461 .Op Fl c Ar count
2462 .Oc
2463 .Ed
2464 .Pp
2465 .
2466 The default width values of
2467 .Ql .Op
2468 and
2469 .Ql .Oo
2470 are 14n and 10n, respectively.
2471 .
2472 .
2473 .Ss Pathnames
2474 .
2475 The
2476 .Ql .Pa
2477 macro formats file specifications.
2478 .
2479 If called without arguments,
2480 .Sq Pa
2481 (recognized by many shells)
2482 is output,
2483 representing the user's home directory.
2484 .
2485 .
2486 .Pp
2487 .Dl Usage: .Pa Oo Ao pathname Ac Oc ...
2488 .Pp
2489 .Bl -tag -width ".Li .Pa\ /tmp/fooXXXXX\ )\ ." -compact -offset 15n
2490 .It Li .Pa
2491 .Pa
2492 .It Li ".Pa /usr/share"
2493 .Pa /usr/share
2494 .It Li ".Pa /tmp/fooXXXXX ) ."
2495 .Pa /tmp/fooXXXXX ) .
2496 .El
2497 .Pp
2498 .
2499 The default width is 32n.
2500 .
2501 .
2502 .Ss Standards
2503 .
2504 The
2505 .Ql .St
2506 macro replaces standard abbreviations with their formal names.
2507 .Pp
2508 .Dl Usage: .St Ao abbreviation Ac ...
2509 .Pp
2510 Available pairs for
2511 .Dq Abbreviation/Formal Name
2512 are:
2513 .
2514 .Pp
2515 .Tn ANSI/ISO C
2516 .Pp
2517 .Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent
2518 .It Li \-ansiC
2519 .St -ansiC
2520 .It Li \-ansiC\-89
2521 .St -ansiC-89
2522 .It Li \-isoC
2523 .St -isoC
2524 .It Li \-isoC\-90
2525 .St -isoC-90
2526 .It Li \-isoC\-99
2527 .St -isoC-99
2528 .It Li \-isoC\-2011
2529 .St -isoC-2011
2530 .It Li \-isoC\-2023
2531 .St -isoC-2023
2532 .El
2533 .Pp
2534 .
2535 .Tn POSIX
2536 Part 1: System API
2537 .Pp
2538 .Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent
2539 .It Li \-iso9945\-1\-90
2540 .St -iso9945-1-90
2541 .It Li \-iso9945\-1\-96
2542 .St -iso9945-1-96
2543 .It Li \-p1003.1
2544 .St -p1003.1
2545 .It Li \-p1003.1\-88
2546 .St -p1003.1-88
2547 .It Li \-p1003.1\-90
2548 .St -p1003.1-90
2549 .It Li \-p1003.1\-96
2550 .St -p1003.1-96
2551 .It Li \-p1003.1b\-93
2552 .St -p1003.1b-93
2553 .It Li \-p1003.1c\-95
2554 .St -p1003.1c-95
2555 .It Li \-p1003.1g\-2000
2556 .St -p1003.1g-2000
2557 .It Li \-p1003.1i\-95
2558 .St -p1003.1i-95
2559 .It Li \-p1003.1\-2001
2560 .St -p1003.1-2001
2561 .It Li \-p1003.1\-2004
2562 .St -p1003.1-2004
2563 .It Li \-p1003.1\-2008
2564 .St -p1003.1-2008
2565 .It Li \-p1003.1\-2024
2566 .St -p1003.1-2024
2567 .El
2568 .Pp
2569 .
2570 .Tn POSIX
2571 Part 2: Shell and Utilities
2572 .Pp
2573 .Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent
2574 .It Li \-iso9945\-2\-93
2575 .St -iso9945-2-93
2576 .It Li \-p1003.2
2577 .St -p1003.2
2578 .It Li \-p1003.2\-92
2579 .St -p1003.2-92
2580 .It Li \-p1003.2a\-92
2581 .St -p1003.2a-92
2582 .El
2583 .Pp
2584 .
2585 X/Open
2586 .Pp
2587 .Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent
2588 .It Li \-susv1
2589 .St -susv1
2590 .It Li \-susv2
2591 .St -susv2
2592 .It Li \-susv3
2593 .St -susv3
2594 .It Li \-susv4
2595 .St -susv4
2596 .It Li \-svid4
2597 .St -svid4
2598 .It Li \-xbd5
2599 .St -xbd5
2600 .It Li \-xcu5
2601 .St -xcu5
2602 .It Li \-xcurses4.2
2603 .St -xcurses4.2
2604 .It Li \-xns5
2605 .St -xns5
2606 .It Li \-xns5.2
2607 .St -xns5.2
2608 .It Li \-xpg3
2609 .St -xpg3
2610 .It Li \-xpg4
2611 .St -xpg4
2612 .It Li \-xpg4.2
2613 .St -xpg4.2
2614 .It Li \-xsh5
2615 .St -xsh5
2616 .El
2617 .Pp
2618 .
2619 .\"br
2620 .\"ne 4v
2621 Miscellaneous
2622 .Pp
2623 .Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent
2624 .It Li \-ieee754
2625 .St -ieee754
2626 .It Li \-iso8601
2627 .St -iso8601
2628 .It Li \-iso8802\-3
2629 .St -iso8802-3
2630 .El
2631 .
2632 .
2633 .Ss "Variable Types"
2634 The
2635 .Ql .Vt
2636 macro may be used whenever a type is referenced.
2637 .
2638 In a section titled
2639 .Dq Synopsis ,
2640 .Ql \&Vt
2641 causes a break
2642 (useful for old-style C variable declarations).
2643 .
2644 .
2645 .Pp
2646 .Dl Usage: .Vt Ao type Ac ...
2647 .Pp
2648 .Bl -tag -width ".Li .Vt\ extern\ char\ *optarg\ ;" -compact -offset 15n
2649 .It Li ".Vt extern char *optarg ;"
2650 .Vt extern char *optarg ;
2651 .It Li ".Vt FILE *"
2652 .Vt FILE *
2653 .El
2654 .
2655 .
2656 .Ss Variables
2657 .
2658 Generic variable reference.
2659 .Pp
2660 .Dl Usage: .Va Ao variable Ac ...
2661 .Pp
2662 .Bl -tag -width ".Li .Va\ Xchar\ sX\ ]\ )\ )\ ," -compact -offset 15n
2663 .It Li ".Va count"
2664 .Va count
2665 .It Li ".Va settimer ,"
2666 .Va settimer ,
2667 .It Li ".Va \[dq]int *prt\[dq] ) :"
2668 .Va "int *prt" ) :
2669 .It Li ".Va \[dq]char s\[dq] ] ) ) ,"
2670 .Va "char s" ] ) ) ,
2671 .El
2672 .Pp
2673 .
2674 The default width is 12n.
2675 .
2676 .
2677 .Ss "Manual Page Cross References"
2678 .
2679 The
2680 .Ql .Xr
2681 macro expects the first argument to be a manual page name.
2682 .
2683 The optional second argument,
2684 if a string
2685 (defining the manual section),
2686 is
2687 put into parentheses.
2688 .
2689 .
2690 .Pp
2691 .Dl Usage: .Xr Ao man page name Ac Oo Ao section Ac Oc ...
2692 .
2693 .
2694 .Pp
2695 .Bl -tag -width ".Li .Xr\ xinit\ 1x\ ;" -compact -offset 15n
2696 .It Li ".Xr mdoc"
2697 .Xr mdoc
2698 .It Li ".Xr mdoc ,"
2699 .Xr mdoc ,
2700 .It Li ".Xr mdoc 7"
2701 .Xr mdoc 7
2702 .It Li ".Xr xinit 1x ;"
2703 .Xr xinit 1x ;
2704 .El
2705 .
2706 .
2707 .Pp
2708 The default width is 10n.
2709 .
2710 .
2711 .Sh "General text domain"
2712 .
2713 .
2714 .Ss "AT&T Macro"
2715 .
2716 .Pp
2717 .Dl Usage: .At Oo Ao version Ac Oc ...
2718 .Pp
2719 .Bl -tag -width ".Li .At\ v6\ ." -compact -offset 15n
2720 .It Li .At
2721 .At
2722 .It Li ".At v6 ."
2723 .At v6 .
2724 .El
2725 .Pp
2726 The following values for
2727 .Ao version Ac
2728 are possible:
2729 .Pp
2730 .Dl 32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4
2731 .
2732 .
2733 .Ss "BSD Macro"
2734 .
2735 .Pp
2736 .Dl "Usage: .Bx" Bro \-alpha | \-beta | \-devel Brc ...
2737 .Dl " .Bx" Oo Ao version Ac Oo Ao release Ac Oc Oc ...
2738 .Pp
2739 .Bl -tag -width ".Li .Bx\ -devel" -compact -offset 15n
2740 .It Li .Bx
2741 .Bx
2742 .It Li ".Bx 4.3 ."
2743 .Bx 4.3 .
2744 .It Li ".Bx \-devel"
2745 .Bx -devel
2746 .El
2747 .Pp
2748 .Ao version Ac
2749 will be prepended to the string
2750 .Sq Bx .
2751 The following values for
2752 .Ao release Ac
2753 are possible:
2754 .Pp
2755 .Dl Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
2756 .
2757 .
2758 .Ss "NetBSD Macro"
2759 .
2760 .Pp
2761 .Dl Usage: .Nx Oo Ao version Ac Oc ...
2762 .Pp
2763 .Bl -tag -width ".Li .Nx\ 1.4\ ." -compact -offset 15n
2764 .It Li .Nx
2765 .Nx
2766 .It Li ".Nx 1.4 ."
2767 .Nx 1.4 .
2768 .El
2769 .Pp
2770 For possible values of
2771 .Ao version Ac
2772 see the description of the
2773 .Ql .Os
2774 command above in section
2775 .Sx "Title macros" .
2776 .
2777 .
2778 .Ss "FreeBSD Macro"
2779 .
2780 .Pp
2781 .Dl Usage: .Fx Oo Ao version Ac Oc ...
2782 .Pp
2783 .Bl -tag -width ".Li .Fx\ 2.2\ ." -compact -offset 15n
2784 .It Li .Fx
2785 .Fx
2786 .It Li ".Fx 2.2 ."
2787 .Fx 2.2 .
2788 .El
2789 .Pp
2790 For possible values of
2791 .Ao version Ac
2792 see the description of the
2793 .Ql .Os
2794 command above in section
2795 .Sx "Title macros" .
2796 .
2797 .
2798 .Ss "DragonFly Macro"
2799 .
2800 .Pp
2801 .Dl Usage: .Dx Oo Ao version Ac Oc ...
2802 .Pp
2803 .Bl -tag -width ".Li .Dx\ 1.4\ ." -compact -offset 15n
2804 .It Li .Dx
2805 .Dx
2806 .It Li ".Dx 1.4 ."
2807 .Dx 1.4 .
2808 .El
2809 .Pp
2810 For possible values of
2811 .Ao version Ac
2812 see the description of the
2813 .Ql .Os
2814 command above in section
2815 .Sx "Title macros" .
2816 .
2817 .
2818 .Ss "OpenBSD Macro"
2819 .
2820 .Pp
2821 .Dl Usage: .Ox Oo Ao version Ac Oc ...
2822 .Pp
2823 .Bl -tag -width ".Li .Ox\ 1.0" -compact -offset 15n
2824 .It Li ".Ox 1.0"
2825 .Ox 1.0
2826 .El
2827 .
2828 .
2829 .Ss "BSD/OS Macro"
2830 .
2831 .Pp
2832 .Dl Usage: .Bsx Oo Ao version Ac Oc ...
2833 .Pp
2834 .Bl -tag -width ".Li .Bsx\ 1.0" -compact -offset 15n
2835 .It Li ".Bsx 1.0"
2836 .Bsx 1.0
2837 .El
2838 .
2839 .
2840 .Ss "Unix Macro"
2841 .
2842 .Pp
2843 .Dl Usage: .Ux ...
2844 .Pp
2845 .Bl -tag -width ".Li .Ux" -compact -offset 15n
2846 .It Li .Ux
2847 .Ux
2848 .El
2849 .
2850 .
2851 .Ss "Emphasis Macro"
2852 .
2853 Text may be stressed or emphasized with the
2854 .Ql .Em
2855 macro.
2856 The usual font for emphasis is italic.
2857 .Pp
2858 .Dl Usage: .Em Ao argument Ac ...
2859 .Pp
2860 .Bl -tag -width ".Li .Em\ vide\ infra\ )\ )\ ," -compact -offset 15n
2861 .It Li ".Em does not"
2862 .Em does not
2863 .It Li ".Em exceed 1024 ."
2864 .Em exceed 1024 .
2865 .It Li ".Em vide infra ) ) ,"
2866 .Em vide infra ) ) ,
2867 .El
2868 .Pp
2869 .
2870 The default width is 10n.
2871 .
2872 .
2873 .Ss "Font Mode"
2874 .
2875 The
2876 .Ql .Bf
2877 font mode must be ended with the
2878 .Ql .Ef
2879 macro (the latter takes no arguments).
2880 Font modes may be nested within other font modes.
2881 .Pp
2882 .Ql .Bf
2883 has the following syntax:
2884 .Pp
2885 .Dl .Bf Ao font mode Ac
2886 .Pp
2887 .Ao font mode Ac
2888 must be one of the following three types:
2889 .Pp
2890 .Bl -tag -width ".Sy \&Sy | Fl symbolic" -compact -offset indent
2891 .It Sy \&Em | Fl emphasis
2892 Same as if the
2893 .Ql .Em
2894 macro was used for the entire block of text.
2895 .It Sy \&Li | Fl literal
2896 Same as if the
2897 .Ql .Li
2898 macro was used for the entire block of text.
2899 .It Sy \&Sy | Fl symbolic
2900 Same as if the
2901 .Ql .Sy
2902 macro was used for the entire block of text.
2903 .El
2904 .Pp
2905 Both macros are neither callable nor parsed.
2906 .
2907 .
2908 .Ss "Enclosure and Quoting Macros"
2909 .
2910 The concept of enclosure is similar to quoting.
2911 The object being to enclose one or more strings between a pair of characters
2912 like quotes or parentheses.
2913 The terms quoting and enclosure are used interchangeably throughout this
2914 document.
2915 Most of the one-line enclosure macros end in small letter
2916 .Ql q
2917 to give a hint of quoting, but there are a few irregularities.
2918 .
2919 For each enclosure macro,
2920 there is a pair of opening and closing macros that end with the
2921 lowercase letters
2922 .Ql o
2923 and
2924 .Ql c
2925 respectively.
2926 .Pp
2927 \# XXX
2928 .if t \
2929 . ne 10
2930 .
2931 .TS
2932 lb lb lb lb lb
2933 l l l l l.
2934 Quote Open Close Function Result
2935 \&.Aq .Ao .Ac Angle Bracket Enclosure <string>
2936 \&.Bq .Bo .Bc Bracket Enclosure [string]
2937 \&.Brq .Bro .Brc Brace Enclosure {string}
2938 \&.Dq .Do .Dc Double Quote \[lq]string\[rq]
2939 \&.Eq .Eo .Ec Enclose String (in XY) XstringY
2940 \&.Pq .Po .Pc Parenthesis Enclosure (string)
2941 \&.Ql Quoted or Literal \[lq]string\[rq] or \
2942 \f[CR]string\f[]
2943 \&.Qq .Qo .Qc Straight Double Quote "string"
2944 \&.Sq .So .Sc Single Quote \[oq]string\[cq]
2945 .TE
2946 .Pp
2947 All macros ending with
2948 .Sq q
2949 and
2950 .Sq o
2951 have a default width value of 12n.
2952 .
2953 .Bl -tag -width ".Li .Ec , .Eo"
2954 .It Li .Eo , .Ec
2955 These macros expect the first argument to be the opening and closing
2956 strings,
2957 respectively.
2958 .
2959 .It Li .Es , .En
2960 To work around the nine-argument limit in the original
2961 .Xr troff \" generic
2962 program,
2963 .Xr mdoc
2964 supports two other macros that are now obsolete.
2965 .
2966 .Ql .Es
2967 uses its first and second parameters as opening and closing marks which
2968 are then used to enclose the arguments of
2969 .Ql .En .
2970 .
2971 The default width value is 12n for both macros.
2972 .
2973 .It Li .Eq
2974 The first and second arguments of this macro are the opening and
2975 closing strings respectively, followed by the arguments to be enclosed.
2976 .
2977 .It Li .Ql
2978 The quoted-or-literal macro behaves differently in
2979 .Xr troff \" mode
2980 and
2981 .Xr nroff \" mode
2982 modes.
2983 .
2984 When formatting with
2985 .Xr \%nroff 1 ,
2986 .Xr mdoc
2987 quotes the arguments.
2988 .
2989 With
2990 .Xr \%troff ,
2991 .Xr mdoc
2992 sets them in a constant-width font.
2993 .
2994 .
2995 .Pp
2996 The default width is 16n.
2997 .
2998 .It Li .Pf
2999 The prefix macro suppresses the whitespace between its first and second
3000 argument:
3001 .
3002 .Bl -tag -width ".Li .Pf\ (\ Fa\ name2" -offset indent
3003 .It Li ".Pf ( Fa name2"
3004 .Pf ( Fa name2
3005 .El
3006 .Pp
3007 .
3008 The default width is 12n.
3009 .Pp
3010 The
3011 .Ql .Ns
3012 macro (see below) performs the analogous suffix function.
3013 .It Li .Ap
3014 The
3015 .Ql .Ap
3016 macro inserts an apostrophe and exits any special text modes, continuing in
3017 .Ql .No
3018 mode.
3019 .El
3020 .Pp
3021 .
3022 Examples of quoting:
3023 .
3024 .Pp
3025 .Bl -tag -width ".Li .Bq\ Em\ Greek\ ,\ French\ ." -compact -offset indent
3026 .It Li .Aq
3027 .Aq
3028 .It Li ".Aq Pa ctype.h ) ,"
3029 .Aq Pa ctype.h ) ,
3030 .It Li .Bq
3031 .Bq
3032 .It Li ".Bq Em Greek , French ."
3033 .Bq Em Greek , French .
3034 .It Li .Dq
3035 .Dq
3036 .It Li ".Dq string abc ."
3037 .Dq string abc .
3038 .It Li ".Dq \[aq]\[rs][ha][A\-Z]\[aq]"
3039 .Dq '\[ha][A-Z]'
3040 .It Li ".Ql man mdoc"
3041 .Ql man mdoc
3042 .It Li .Qq
3043 .Qq
3044 .It Li ".Qq string ) ,"
3045 .Qq string ) ,
3046 .It Li ".Qq string Ns ),"
3047 .Qq string Ns ),
3048 .It Li .Sq
3049 .Sq
3050 .It Li ".Sq string"
3051 .Sq string
3052 .It Li ".Em or Ap ing"
3053 .Em or Ap ing
3054 .El
3055 .Pp
3056 .
3057 For a good example of nested enclosure macros, see the
3058 .Ql .Op
3059 option macro.
3060 It was created from the same underlying enclosure macros as those presented
3061 in the list above.
3062 The
3063 .Ql .Xo
3064 and
3065 .Ql .Xc
3066 extended argument list macros are discussed below.
3067 .
3068 .
3069 .Ss "Normal text macro"
3070 .
3071 .Ql \&No
3072 formats subsequent argument(s) normally,
3073 ending the effect of
3074 .Ql \&Em
3075 and similar.
3076 .
3077 Parsing is
3078 .Em not
3079 suppressed,
3080 so you must prefix words like
3081 .Ql \&No
3082 with
3083 .Ql \e&
3084 to avoid their interpretation as
3085 .Xr mdoc
3086 macros.
3087 .
3088 .
3089 .Pp
3090 .Dl Usage: .No Ar argument No ...
3091 .
3092 .
3093 .Pp
3094 .Bl -tag -width ".Li .Em\ Use\ caution\ No\ here\ ." \
3095 -compact -offset 15n
3096 .It Li ".Em Use caution No here ."
3097 \[->]
3098 .Em Use caution No here .
3099 .It Li ".Em No dogs allowed ."
3100 \[->]
3101 .\" We cheat here to prevent a diagnostic warning. We want to
3102 .\" illustrate output that may surprise the novice.
3103 .Em \&No No dogs allowed .
3104 .It Li ".Em \e&No dogs allowed ."
3105 \[->]
3106 .Em \&No dogs allowed .
3107 .El
3108 .
3109 .
3110 .Pp
3111 The default width is 12n.
3112 .
3113 .
3114 .Ss "No-Space Macro"
3115 .
3116 The
3117 .Ql .Ns
3118 macro suppresses insertion of a space between the current position and its
3119 first parameter.
3120 For example, it is useful for old style argument lists where there is no
3121 space between the flag and argument:
3122 .Pp
3123 .Dl "Usage:" ... Ao argument Ac \&Ns Oo Ao argument Ac Oc ...
3124 .Dl " " .Ns Ao argument Ac ...
3125 .Pp
3126 .Bl -tag -width ".Li .Op\ Fl\ I\ Ns\ Ar\ directory" -compact -offset 15n
3127 .It Li ".Op Fl I Ns Ar directory"
3128 .Op Fl I Ns Ar directory
3129 .El
3130 .Pp
3131 Note: The
3132 .Ql .Ns
3133 macro always invokes the
3134 .Ql .No
3135 macro after eliminating the space unless another macro name follows it.
3136 If used as a command (i.e., the second form above in the
3137 .Sq Usage
3138 line),
3139 .Ql .Ns
3140 is identical to
3141 .Ql .No .
3142 .
3143 .
3144 .Ss "(Sub)section cross references"
3145 .
3146 Use the
3147 .Ql .Sx
3148 macro to cite a (sub)section heading within the given document.
3149 .
3150 .
3151 .Pp
3152 .Dl Usage: .Sx Ao section-reference Ac ...
3153 .
3154 .
3155 .Pp
3156 .Bl -tag -width ".Li .Sx\ Files" -offset 15n
3157 .It Li ".Sx Files"
3158 \[->]
3159 .Sx Files
3160 .El
3161 .
3162 .
3163 .Pp
3164 The default width is 16n.
3165 .
3166 .
3167 .Ss Symbolics
3168 .
3169 The symbolic emphasis macro is generally a boldface macro in either the
3170 symbolic sense or the traditional English usage.
3171 .
3172 .
3173 .Pp
3174 .Dl Usage: .Sy Ao symbol Ac ...
3175 .
3176 .
3177 .Pp
3178 .Bl -tag -width ".Li .Sy\ Important\ Notice" -compact -offset 15n
3179 .It Li ".Sy Important Notice"
3180 \[->]
3181 .Sy Important Notice
3182 .El
3183 .
3184 .
3185 .Pp
3186 The default width is 6n.
3187 .
3188 .
3189 .Ss "Mathematical Symbols"
3190 .
3191 Use this macro for mathematical symbols and similar things.
3192 .
3193 .
3194 .Pp
3195 .Dl Usage: .Ms Ao math symbol Ac ...
3196 .
3197 .
3198 .Pp
3199 .Bl -tag -width ".Li .Ms\ sigma" -compact -offset 15n
3200 .It Li ".Ms sigma"
3201 \[->]
3202 .Ms sigma
3203 .El
3204 .
3205 .
3206 .Pp
3207 The default width is 6n.
3208 .
3209 .
3210 .Ss "References and Citations"
3211 .
3212 The following macros make a modest attempt to handle references.
3213 .
3214 At best,
3215 the macros make it convenient to manually drop in a subset of
3216 .Xr \%refer 1
3217 style references.
3218 .
3219 .
3220 .Pp
3221 .Bl -tag -width 6n -offset indent -compact
3222 .It Li .Rs
3223 Reference start
3224 (does not take arguments).
3225 .
3226 In a section titled
3227 .Dq "See also" ,
3228 it causes a break
3229 and begins collection of reference information until the reference end
3230 macro is read.
3231 .
3232 .It Li .Re
3233 Reference end (does not take arguments).
3234 The reference is printed.
3235 .It Li .%A
3236 Reference author name; one name per invocation.
3237 .It Li .%B
3238 Book title.
3239 .It Li .%C
3240 City/place.
3241 .It Li .%D
3242 Date.
3243 .It Li .%I
3244 Issuer/publisher name.
3245 .It Li .%J
3246 Journal name.
3247 .It Li .%N
3248 Issue number.
3249 .It Li .%O
3250 Optional information.
3251 .It Li .%P
3252 Page number.
3253 .It Li .%Q
3254 Corporate or foreign author.
3255 .It Li .%R
3256 Report name.
3257 .It Li .%T
3258 Title of article.
3259 .It Li .%U
3260 Optional hypertext reference.
3261 .It Li .%V
3262 Volume.
3263 .El
3264 .Pp
3265 Macros beginning with
3266 .Ql %
3267 are not callable but accept multiple arguments in the usual way.
3268 Only the
3269 .Ql .Tn
3270 macro is handled properly as a parameter; other macros will cause strange
3271 output.
3272 .Ql .%B
3273 and
3274 .Ql .%T
3275 can be used outside of the
3276 .Ql .Rs/.Re
3277 environment.
3278 .Pp
3279 Example:
3280 .
3281 .Bd -literal -offset indent
3282 \&.Rs
3283 \&.%A "Matthew Bar"
3284 \&.%A "John Foo"
3285 \&.%T "Implementation Notes on foobar(1)"
3286 \&.%R "Technical Report ABC\-DE\-12\-345"
3287 \&.%Q "Drofnats College"
3288 \&.%C "Nowhere"
3289 \&.%D "April 1991"
3290 \&.Re
3291 .Ed
3292 .Pp
3293 produces
3294 .
3295 .Bd -ragged -offset indent
3296 .Rs
3297 .%A "Matthew Bar"
3298 .%A "John Foo"
3299 .%T "Implementation Notes on foobar(1)"
3300 .%R "Technical Report ABC-DE-12-345"
3301 .%Q "Drofnats College"
3302 .%C "Nowhere"
3303 .%D "April 1991"
3304 .Re
3305 .Ed
3306 .
3307 .Ss "Trade Names or Acronyms"
3308 .
3309 The trade name macro prints its arguments at a smaller type size.
3310 .
3311 It is intended to imitate a small caps fonts for fully capitalized
3312 acronyms.
3313 .
3314 .
3315 .Pp
3316 .Dl Usage: .Tn Ao symbol Ac ...
3317 .Pp
3318 .Bl -tag -width ".Li .Tn\ ASCII" -compact -offset 15n
3319 .It Li ".Tn DEC"
3320 .Tn DEC
3321 .It Li ".Tn ASCII"
3322 .Tn ASCII
3323 .El
3324 .Pp
3325 .
3326 The default width is 10n.
3327 .
3328 .
3329 .Ss "Extended Arguments"
3330 .
3331 The
3332 .Li .Xo
3333 and
3334 .Li .Xc
3335 macros allow one to extend an argument list on a macro boundary for the
3336 .Ql .It
3337 macro (see below).
3338 Note that
3339 .Li .Xo
3340 and
3341 .Li .Xc
3342 are implemented similarly to all other macros opening and closing an
3343 enclosure (without inserting characters, of course).
3344 This means that the following is true for those macros also.
3345 .Pp
3346 Here is an example of
3347 .Ql .Xo
3348 using the space mode macro to turn spacing off:
3349 .
3350 .Bd -literal -offset indent
3351 \&.Bd \-literal \-offset indent
3352 \&.Sm off
3353 \&.It Xo Sy I Ar operation
3354 \&.No \een Ar count No \een
3355 \&.Xc
3356 \&.Sm on
3357 \&.Ed
3358 .Ed
3359 .Pp
3360 .
3361 produces
3362 .
3363 .Bd -filled -offset indent
3364 .Bl -tag -compact
3365 .Sm off
3366 .It Xo Sy I Ar operation
3367 .No \en Ar count No \en
3368 .Xc
3369 .Sm on
3370 .El
3371 .Ed
3372 .Pp
3373 .
3374 Another one:
3375 .
3376 .Bd -literal -offset indent
3377 \&.Bd \-literal \-offset indent
3378 \&.Sm off
3379 \&.It Cm S No / Ar old_pattern Xo
3380 \&.No / Ar new_pattern
3381 \&.No / Op Cm g
3382 \&.Xc
3383 \&.Sm on
3384 \&.Ed
3385 .Ed
3386 .Pp
3387 .
3388 produces
3389 .
3390 .Bd -filled -offset indent
3391 .Bl -tag -compact
3392 .Sm off
3393 .It Cm S No \&/ Ar old_pattern Xo
3394 .No \&/ Ar new_pattern
3395 .No \&/ Op Cm g
3396 .Xc
3397 .Sm on
3398 .El
3399 .Ed
3400 .Pp
3401 .
3402 Another example of
3403 .Ql .Xo
3404 and enclosure macros: Test the value of a variable.
3405 .
3406 .Bd -literal -offset indent
3407 \&.Bd \-literal \-offset indent
3408 \&.It Xo
3409 \&.Ic .ifndef
3410 \&.Oo \e&! Oc Ns Ar variable Oo
3411 \&.Ar operator variable No ...
3412 \&.Oc Xc
3413 \&.Ed
3414 .Ed
3415 .Pp
3416 .
3417 produces
3418 .
3419 .Bd -filled -offset indent
3420 .Bl -tag -width flag -compact
3421 .It Xo
3422 .Ic .ifndef
3423 .Oo \&! Oc Ns Ar variable Oo
3424 .Ar operator variable No ...
3425 .Oc Xc
3426 .El
3427 .Ed
3428 .Pp
3429 .
3430 .
3431 .Sh "Page structure domain"
3432 .
3433 .
3434 .Ss "Section headings"
3435 .
3436 The following
3437 .Ql .Sh
3438 section heading macros are required in every man page.
3439 .
3440 The remaining section headings are recommended at the discretion of the
3441 author writing the manual page.
3442 The
3443 .Ql .Sh
3444 macro is parsed but not generally callable.
3445 It can be used as an argument in a call to
3446 .Ql .Sh
3447 only; it then reactivates the default font for
3448 .Ql .Sh .
3449 .Pp
3450 The default width is 8n.
3451 .
3452 .Bl -tag -width ".Li .Sh\ Return\ values"
3453 .It Li ".Sh Name"
3454 The
3455 .Ql ".Sh Name"
3456 macro is mandatory.
3457 .
3458 If not specified,
3459 headers,
3460 footers,
3461 and page layout defaults will not be set and things will be rather
3462 unpleasant.
3463 .
3464 The
3465 .Em Name
3466 section consists of at least three items.
3467 The first is the
3468 .Ql .Nm
3469 name macro naming the subject of the man page.
3470 The second is the name description macro,
3471 .Ql .Nd ,
3472 which separates the subject name from the third item, which is the
3473 description.
3474 The description should be the most terse and lucid possible, as the space
3475 available is small.
3476 .Pp
3477 .Ql .Nd
3478 first prints
3479 .Ql \- ,
3480 then all its arguments.
3481 .
3482 .It Li ".Sh Library"
3483 This section is for section two and three function calls.
3484 It should consist of a single
3485 .Ql .Lb
3486 macro call;
3487 see
3488 .Sx "Library Names" .
3489 .
3490 .It Li ".Sh Synopsis"
3491 The
3492 .Sx Synopsis
3493 section describes the typical usage of the subject of a man page.
3494 The macros required are either
3495 .Ql .Nm ,
3496 .Ql .Cd ,
3497 or
3498 .Ql .Fn
3499 (and possibly
3500 .Ql .Fo ,
3501 .Ql .Fc ,
3502 .Ql .Fd ,
3503 and
3504 .Ql .Ft ) .
3505 The function name macro
3506 .Ql .Fn
3507 is required for manual page sections\~2 and\~3; the command and general name
3508 macro
3509 .Ql .Nm
3510 is required for sections 1, 5, 6, 7, and\~8.
3511 Section\~4 manuals require a
3512 .Ql .Nm ,
3513 .Ql .Fd
3514 or a
3515 .Ql .Cd
3516 configuration device usage macro.
3517 Several other macros may be necessary to produce the synopsis line as shown
3518 below:
3519 .
3520 .Bd -filled -offset indent
3521 .Nm cat
3522 .Op Fl benstuv
3523 .Op Fl
3524 .Ar file No ...
3525 .Ed
3526 .Pp
3527 .
3528 The following macros were used:
3529 .Pp
3530 .Dl ".Nm cat"
3531 .Dl ".Op Fl benstuv"
3532 .Dl ".Op Fl"
3533 .Dl ".Ar file No ..."
3534 .
3535 .It Li ".Sh Description"
3536 In most cases the first text in the
3537 .Sx Description
3538 section is a brief paragraph on the command, function or file, followed by a
3539 lexical list of options and respective explanations.
3540 To create such a list, the
3541 .Ql .Bl
3542 (begin list),
3543 .Ql .It
3544 (list item) and
3545 .Ql .El
3546 (end list)
3547 macros are used (see
3548 .Sx Lists and Columns
3549 below).
3550 .
3551 .It Li ".Sh Implementation notes"
3552 Implementation specific information should be placed here.
3553 .
3554 .It Li ".Sh Return values"
3555 Sections 2, 3 and\~9 function return values should go here.
3556 The
3557 .Ql .Rv
3558 macro may be used to generate text for use in the
3559 .Sx Return values
3560 section for most section 2 and 3 library functions;
3561 see
3562 .Sx "Return Values" .
3563 .El
3564 .Pp
3565 .
3566 The following
3567 .Ql .Sh
3568 section headings are part of the preferred manual page layout and must
3569 be used appropriately to maintain consistency.
3570 They are listed in the order in which they would be used.
3571 .
3572 .Bl -tag -width ".Li .Sh\ Compatibility"
3573 .It Li ".Sh Environment"
3574 The
3575 .Em Environment
3576 section should reveal any related environment variables and clues to their
3577 behavior and/or usage.
3578 .
3579 .It Li ".Sh Files"
3580 Files which are used or created by the man page subject should be listed via
3581 the
3582 .Ql .Pa
3583 macro in the
3584 .Sx Files
3585 section.
3586 .
3587 .It Li ".Sh Examples"
3588 There are several ways to create examples.
3589 See subsection
3590 .Sx "Examples and Displays"
3591 below for details.
3592 .
3593 .It Li ".Sh Diagnostics"
3594 Diagnostic messages from a command should be placed in this section.
3595 The
3596 .Ql .Ex
3597 macro may be used to generate text for use in the
3598 .Sx Diagnostics
3599 section for most section 1, 6 and\~8 commands;
3600 see
3601 .Sx "Exit Status" .
3602 .
3603 .It Li ".Sh Compatibility"
3604 Known compatibility issues (e.g.\& deprecated options or parameters)
3605 should be listed here.
3606 .
3607 .It Li ".Sh Errors"
3608 Specific error handling, especially from library functions (man page
3609 sections 2, 3, and\~9) should go here.
3610 The
3611 .Ql .Er
3612 macro is used to specify an error (errno).
3613 .
3614 .It Li ".Sh See also"
3615 References to other material on the man page topic and cross references
3616 to other relevant man pages should be placed in the
3617 .Sx "See also"
3618 section.
3619 .
3620 Cross references are specified using the
3621 .Ql .Xr
3622 macro.
3623 .
3624 Currently
3625 .Xr \%refer 1
3626 style references are not accommodated.
3627 .
3628 .
3629 .Pp
3630 It is recommended that the cross references be sorted by section number,
3631 then alphabetically by name within each section,
3632 then separated by commas.
3633 .
3634 Example:
3635 .
3636 .
3637 .Pp
3638 .Xr ls 1 ,
3639 .Xr ps 1 ,
3640 .Xr group 5 ,
3641 .Xr passwd 5
3642 .
3643 .It Li ".Sh Standards"
3644 If the command,
3645 library function,
3646 or file adheres to a specific implementation such as
3647 .St -p1003.2
3648 or
3649 .St -ansiC
3650 this should be noted here.
3651 .
3652 If the command does not adhere to any standard,
3653 its history should be noted in the
3654 .Em History
3655 section.
3656 .
3657 .It Li ".Sh History"
3658 Any command which does not adhere to any specific standards should be
3659 outlined historically in this section.
3660 .
3661 .It Li ".Sh Authors"
3662 Credits should be placed here.
3663 .
3664 Use the
3665 .Ql .An
3666 macro for names and the
3667 .Ql .Aq
3668 macro for email addresses within optional contact information.
3669 .
3670 Explicitly indicate whether the person authored the initial manual page
3671 or the software or whatever the person is being credited for.
3672 .It Li ".Sh Bugs"
3673 Blatant problems with the topic go here.
3674 .El
3675 .Pp
3676 .
3677 User-specified
3678 .Ql .Sh
3679 sections may be added; for example, this section was set with:
3680 .
3681 .Bd -literal -offset 15n
3682 \&.Sh "Page structure domain"
3683 .Ed
3684 .
3685 .
3686 .Ss "Subsection headings"
3687 .
3688 Subsection headings have exactly the same syntax as section headings:
3689 .Ql .Ss
3690 is parsed but not generally callable.
3691 It can be used as an argument in a call to
3692 .Ql .Ss
3693 only; it then reactivates the default font for
3694 .Ql .Ss .
3695 .Pp
3696 The default width is 8n.
3697 .
3698 .
3699 .Ss "Paragraphs and Line Spacing"
3700 .
3701 .Bl -tag -width ".Li .Pp"
3702 .It Li .Pp
3703 The
3704 .Ql .Pp
3705 paragraph command may be used to specify a line space where necessary.
3706 The macro is not necessary after a
3707 .Ql .Sh
3708 or
3709 .Ql .Ss
3710 macro or before a
3711 .Ql .Bl
3712 or
3713 .Ql .Bd
3714 macro (which both assert a vertical distance unless the
3715 .Fl compact
3716 flag is given).
3717 .Pp
3718 The macro is neither callable nor parsed and takes no arguments; an
3719 alternative name is
3720 .Ql .Lp .
3721 .El
3722 .
3723 .\" XXX
3724 .
3725 .\" This worked with version one, need to redo for version three
3726 .\" .Pp
3727 .\" .Ds I
3728 .\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
3729 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
3730 .\" .Cl Cx \t\t
3731 .\" .Li \&.Cx\ (
3732 .\" .Cx
3733 .\" .Cl Cx \t\t
3734 .\" .Li \&.Va ax
3735 .\" .Cx
3736 .\" .Cl Cx \t\t
3737 .\" .Li \&.Sy \+
3738 .\" .Cx
3739 .\" .Cl Cx \&(\&
3740 .\" .Va ax
3741 .\" .Cx +
3742 .\" .Va by
3743 .\" .Cx +
3744 .\" .Va c )
3745 .\" .Cx \t
3746 .\" .Em is produced by
3747 .\" .Cx \t
3748 .\" .Li \&.Va by
3749 .\" .Cx
3750 .\" .Cl Cx \t\t
3751 .\" .Li \&.Sy \+
3752 .\" .Cx
3753 .\" .Cl Cx \t\t
3754 .\" .Li \&.Va c )
3755 .\" .Cx
3756 .\" .Cl Cx \t\t
3757 .\" .Li \&.Cx
3758 .\" .Cx
3759 .\" .Cw
3760 .\" .De
3761 .\" .Pp
3762 .\" This example shows the same equation in a different format.
3763 .\" The spaces
3764 .\" around the
3765 .\" .Li \&+
3766 .\" signs were forced with
3767 .\" .Li \e :
3768 .\" .Pp
3769 .\" .Ds I
3770 .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
3771 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
3772 .\" .Cl Cx \t\t
3773 .\" .Li \&.Cx\ (
3774 .\" .Cx
3775 .\" .Cl Cx \t\t
3776 .\" .Li \&.Va a
3777 .\" .Cx
3778 .\" .Cl Cx \t\t
3779 .\" .Li \&.Sy x
3780 .\" .Cx
3781 .\" .Cl Cx \t\t
3782 .\" .Li \&.Cx \e\ +\e\ \e&
3783 .\" .Cx
3784 .\" .Cl Cx \&(\&
3785 .\" .Va a
3786 .\" .Sy x
3787 .\" .Cx \ +\ \&
3788 .\" .Va b
3789 .\" .Sy y
3790 .\" .Cx \ +\ \&
3791 .\" .Va c )
3792 .\" .Cx \t
3793 .\" .Em is produced by
3794 .\" .Cl Cx \t\t
3795 .\" .Li \&.Va b
3796 .\" .Cx
3797 .\" .Cl Cx \t\t
3798 .\" .Li \&.Sy y
3799 .\" .Cx
3800 .\" .Cl Cx \t\t
3801 .\" .Li \&.Cx \e\ +\e\ \e&
3802 .\" .Cx
3803 .\" .Cl Cx \t\t
3804 .\" .Li \&.Va c )
3805 .\" .Cx
3806 .\" .Cl Cx \t\t
3807 .\" .Li \&.Cx
3808 .\" .Cx
3809 .\" .Cw
3810 .\" .De
3811 .\" .Pp
3812 .\" The incantation below was
3813 .\" lifted from the
3814 .\" .Xr adb 1
3815 .\" manual page:
3816 .\" .Pp
3817 .\" .Ds I
3818 .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
3819 .\" .Cl Cx \t\t
3820 .\" .Li \&.Cx Op Sy ?/
3821 .\" .Cx
3822 .\" .Cl Cx \t\t
3823 .\" .Li \&.Nm m
3824 .\" .Cx
3825 .\" .Cl Cx Op Sy ?/
3826 .\" .Nm m
3827 .\" .Ad \ b1 e1 f1
3828 .\" .Op Sy ?/
3829 .\" .Cx \t
3830 .\" .Em is produced by
3831 .\" .Cx \t
3832 .\" .Li \&.Ar \e\ b1 e1 f1
3833 .\" .Cx
3834 .\" .Cl Cx \t\t
3835 .\" .Li \&.Op Sy ?/
3836 .\" .Cx
3837 .\" .Cl Cx \t\t
3838 .\" .Li \&.Cx
3839 .\" .Cx
3840 .\" .Cw
3841 .\" .De
3842 .\" .Pp
3843 .
3844 .
3845 .Ss Keeps
3846 .
3847 The only keep that is implemented at this time is for words.
3848 .
3849 The macros are
3850 .Ql .Bk
3851 (begin keep)
3852 and
3853 .Ql .Ek
3854 (end keep).
3855 .
3856 The only option that
3857 .Ql .Bk
3858 currently accepts is
3859 .Fl words
3860 (also the default);
3861 this prevents breaks in the middle of options.
3862 .
3863 In the example for
3864 .Nm make
3865 command-line arguments
3866 (see
3867 .Sx What's in a Name ) ,
3868 the keep prevents
3869 .Xr \%nroff
3870 from placing the flag and the argument on separate lines.
3871 .
3872 .
3873 .Pp
3874 Neither macro is callable or parsed.
3875 .
3876 .
3877 .Pp
3878 More work needs to be done on the keep macros;
3879 specifically,
3880 a
3881 .Fl line
3882 option should be added.
3883 .
3884 .
3885 .Ss "Examples and Displays"
3886 .
3887 There are seven types of displays.
3888 .
3889 .
3890 .Pp
3891 .Bl -tag -width ".Li .D1"
3892 .It Li .D1
3893 (This is D-one.)
3894 Display one line of indented text.
3895 This macro is parsed but not callable.
3896 .
3897 .
3898 .Pp
3899 .D1 Fl ldghfstru
3900 .
3901 .
3902 .Pp
3903 The above was produced by:
3904 .Li ".D1 Fl ldghfstru" .
3905 .
3906 .It Li .Dl
3907 (This is D-ell.)
3908 Display one line of indented
3909 .Em literal
3910 text.
3911 The
3912 .Ql .Dl
3913 example macro has been used throughout this file.
3914 It allows the indentation (display) of one line of text.
3915 Its default font is set to constant width (literal).
3916 .Ql .Dl
3917 is parsed but not callable.
3918 .
3919 .
3920 .Pp
3921 .Dl % ls \-ldg /usr/local/bin
3922 .
3923 .
3924 .Pp
3925 The above was produced by:
3926 .Li ".Dl % ls \e\-ldg /usr/local/bin" .
3927 .
3928 .It Li .Bd
3929 Begin display.
3930 The
3931 .Ql .Bd
3932 display must be ended with the
3933 .Ql .Ed
3934 macro.
3935 It has the following syntax:
3936 .
3937 .
3938 .Pp
3939 .Bd -ragged -compact
3940 .Bl -tag -width ".Li .Bd" -offset indent
3941 .It Li .Bd Xo
3942 .Bro \-literal | \-filled | \-unfilled | \-ragged | \-centered Brc
3943 .Oo \-offset Ao string Ac Oc Oo \-file Ao file name Ac Oc Oo \-compact Oc Xc
3944 .El
3945 .Ed
3946 .
3947 .
3948 .Pp
3949 .Bl -tag -width ".Fl file Ao Ar file name Ac " -compact
3950 .It Fl ragged
3951 Fill,
3952 but do not adjust
3953 (leave the right margin ragged).
3954 .
3955 .It Fl centered
3956 Center lines between the current left and right margin.
3957 .
3958 Note that each single line is centered.
3959 .
3960 .It Fl unfilled
3961 Do not fill;
3962 break lines where their input lines are broken.
3963 .
3964 This can produce overlong lines without warning messages.
3965 .
3966 .It Fl filled
3967 Display a filled block.
3968 Text is filled and adjusted;
3969 the left and right margins are straight.
3970 .
3971 .It Fl literal
3972 Display block with literal font (usually fixed-width).
3973 .
3974 Useful for source code or simple tabbed or spaced text.
3975 .
3976 .It Fl file Ao Ar file name Ac
3977 The file whose name follows the
3978 .Fl file
3979 flag is read and displayed before any data enclosed with
3980 .Ql .Bd
3981 and
3982 .Ql .Ed ,
3983 using the selected display type.
3984 .
3985 Any
3986 .Xr \%troff/ Ns Xr mdoc
3987 commands in the file will be processed.
3988 .
3989 .It Fl offset Ao Ar string Ac
3990 If
3991 .Fl offset
3992 is specified with one of the following strings, the string is interpreted to
3993 indicate the level of indentation for the forthcoming block of text:
3994 .
3995 .
3996 .Pp
3997 .Bl -tag -width ".Ar indent-two" -compact
3998 .It Ar left
3999 Align block on the current left margin; this is the default mode of
4000 .Ql .Bd .
4001 .It Ar center
4002 Supposedly center the block.
4003 At this time unfortunately, the block merely gets left aligned about an
4004 imaginary center margin.
4005 .It Ar indent
4006 Indent by one default indent value or tab.
4007 The default indent value is also used for the
4008 .Ql .D1
4009 and
4010 .Ql .Dl
4011 macros, so one is guaranteed the two types of displays will line up.
4012 The indentation value is normally set to\~6n or about two thirds of an inch
4013 (six constant width characters).
4014 .It Ar indent\-two
4015 Indent two times the default indent value.
4016 .It Ar right
4017 This
4018 .Em left
4019 aligns the block about two inches from the right side of the page.
4020 This macro needs work and perhaps may never do the right thing within
4021 .Xr \%troff .
4022 .El
4023 .
4024 .
4025 .Pp
4026 If
4027 .Ao string Ac
4028 is a valid numeric expression instead
4029 .Pf ( Em with a scaling indicator other than
4030 .Sq Em u ) ,
4031 use that value for indentation.
4032 The most useful scaling indicators are
4033 .Sq m
4034 and
4035 .Sq n ,
4036 specifying the so-called
4037 .Em \&Em
4038 and
4039 .Em "En square" .
4040 .
4041 This is approximately the width of the letters
4042 .Sq m
4043 and
4044 .Sq n
4045 respectively
4046 of the current font
4047 (for
4048 .Xr nroff
4049 output,
4050 both scaling indicators give the same values).
4051 .
4052 If
4053 .Ao string Ac
4054 isn't a numeric expression, it is tested whether it is an
4055 .Xr mdoc
4056 macro name, and the default offset value associated with this macro is used.
4057 Finally, if all tests fail,
4058 the width of
4059 .Ao string Ac
4060 (typeset with a fixed-width font) is taken as the offset.
4061 .It Fl compact
4062 Suppress insertion of vertical space before begin of display.
4063 .El
4064 .
4065 .It Li .Ed
4066 End display (takes no arguments).
4067 .El
4068 .
4069 .
4070 .Ss "Lists and Columns"
4071 .
4072 There are several types of lists which may be initiated with the
4073 .Ql .Bl
4074 begin-list macro.
4075 .
4076 Items within the list are specified with the
4077 .Ql .It
4078 item macro,
4079 and each list must end with the
4080 .Ql .El
4081 macro.
4082 .
4083 Lists may be nested within themselves and within displays.
4084 .
4085 The use of columns inside of lists or lists inside of columns is
4086 untested.
4087 .
4088 .
4089 .Pp
4090 In addition,
4091 several list attributes may be specified such as the width of a tag,
4092 the list offset,
4093 and compactness
4094 (blank lines between items allowed or disallowed).
4095 .
4096 Most of this document has been formatted with a tag style list
4097 .Pf ( Fl tag ) .
4098 .
4099 .
4100 .Pp
4101 It has the following syntax forms:
4102 .
4103 .
4104 .Pp
4105 .Bd -ragged -compact
4106 .Bl -tag -width ".Li .Bl" -offset indent -compact
4107 .It Li .Bl Xo
4108 .Bro \-hang | \-ohang | \-tag | \-diag | \-inset Brc
4109 .Oo \-width Ao string Ac Oc
4110 .Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
4111 .It Li .Bl Xo
4112 .No \-column Oo \-offset Ao string Ac Oc
4113 .Ao string1 Ac Ao string2 Ac ... Xc
4114 .It Li .Bl Xo
4115 .Bro \-item | \-enum Oo \-nested Oc | \-bullet | \-hyphen | \-dash Brc
4116 .Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
4117 .El
4118 .Ed
4119 .
4120 .
4121 .Pp
4122 And now a detailed description of the list types.
4123 .
4124 .
4125 .Pp
4126 .Bl -tag -width ".Fl column" -compact
4127 .It Fl bullet
4128 A bullet list.
4129 .
4130 .Bd -literal -offset indent
4131 \&.Bl \-bullet \-offset indent \-compact
4132 \&.It
4133 Bullet one goes here.
4134 \&.It
4135 Bullet two here.
4136 \&.El
4137 .Ed
4138 .
4139 .
4140 .Pp
4141 Produces:
4142 .
4143 .
4144 .Pp
4145 .Bl -bullet -offset indent -compact
4146 .It
4147 Bullet one goes here.
4148 .It
4149 Bullet two here.
4150 .El
4151 .
4152 .
4153 .Pp
4154 .
4155 .It Fl dash No ( or Fl hyphen )
4156 A dash list.
4157 .
4158 .Bd -literal -offset indent
4159 \&.Bl \-dash \-offset indent \-compact
4160 \&.It
4161 Dash one goes here.
4162 \&.It
4163 Dash two here.
4164 \&.El
4165 .Ed
4166 .
4167 .
4168 .Pp
4169 Produces:
4170 .
4171 .
4172 .Pp
4173 .Bl -dash -offset indent -compact
4174 .It
4175 Dash one goes here.
4176 .It
4177 Dash two here.
4178 .El
4179 .
4180 .
4181 .Pp
4182 .It Fl enum
4183 An enumerated list.
4184 .
4185 .Bd -literal -offset indent
4186 \&.Bl \-enum \-offset indent \-compact
4187 \&.It
4188 Item one goes here.
4189 \&.It
4190 And item two here.
4191 \&.El
4192 .Ed
4193 .
4194 .
4195 .Pp
4196 The result:
4197 .
4198 .
4199 .Pp
4200 .Bl -enum -offset indent -compact
4201 .It
4202 Item one goes here.
4203 .It
4204 And item two here.
4205 .El
4206 .
4207 .
4208 .Pp
4209 If you want to nest enumerated lists,
4210 use the
4211 .Fl nested
4212 flag
4213 (starting with the second-level list):
4214 .
4215 .Bd -literal -offset indent
4216 \&.Bl \-enum \-offset indent \-compact
4217 \&.It
4218 Item one goes here
4219 \&.Bl \-enum \-nested \-compact
4220 \&.It
4221 Item two goes here.
4222 \&.It
4223 And item three here.
4224 \&.El
4225 \&.It
4226 And item four here.
4227 \&.El
4228 .Ed
4229 .
4230 .
4231 .Pp
4232 Result:
4233 .
4234 .
4235 .Pp
4236 .Bl -enum -offset indent -compact
4237 .It
4238 Item one goes here.
4239 .Bl -enum -nested -compact
4240 .It
4241 Item two goes here.
4242 .It
4243 And item three here.
4244 .El
4245 .It
4246 And item four here.
4247 .El
4248 .
4249 .
4250 .Pp
4251 .
4252 .It Fl item
4253 A list of type
4254 .Fl item
4255 without list markers.
4256 .
4257 .Bd -literal -offset indent
4258 \&.Bl \-item \-offset indent
4259 \&.It
4260 Item one goes here.
4261 Item one goes here.
4262 Item one goes here.
4263 \&.It
4264 Item two here.
4265 Item two here.
4266 Item two here.
4267 \&.El
4268 .Ed
4269 .
4270 .
4271 .Pp
4272 Produces:
4273 .
4274 .
4275 .Pp
4276 .Bl -item -offset indent
4277 .It
4278 Item one goes here.
4279 Item one goes here.
4280 Item one goes here.
4281 .It
4282 Item two here.
4283 Item two here.
4284 Item two here.
4285 .El
4286 .
4287 .
4288 .Pp
4289 .It Fl tag
4290 A list with tags.
4291 Use
4292 .Fl width
4293 to specify the tag width.
4294 .
4295 .
4296 .Pp
4297 .Bl -tag -width "PPID" -compact -offset indent
4298 .It SL
4299 sleep time of the process (seconds blocked)
4300 .It PAGEIN
4301 number of disk I/O operations resulting from references by the process
4302 to pages not loaded in core.
4303 .It UID
4304 numerical user-id of process owner
4305 .It PPID
4306 numerical id of parent of process priority
4307 (non-positive when in non-interruptible wait)
4308 .El
4309 .
4310 .
4311 .Pp
4312 The raw text:
4313 .
4314 .Bd -literal -offset indent
4315 \&.Bl \-tag \-width "PPID" \-compact \-offset indent
4316 \&.It SL
4317 sleep time of the process (seconds blocked)
4318 \&.It PAGEIN
4319 number of disk I/O operations resulting from references
4320 by the process to pages not loaded in core.
4321 \&.It UID
4322 numerical user\-id of process owner
4323 \&.It PPID
4324 numerical id of parent of process priority
4325 (non\-positive when in non\-interruptible wait)
4326 \&.El
4327 .Ed
4328 .
4329 .
4330 .Pp
4331 .It Fl diag
4332 Diag lists create section four diagnostic lists and are similar to inset
4333 lists except callable macros are ignored.
4334 The
4335 .Fl width
4336 flag is not meaningful in this context.
4337 .
4338 .
4339 .Pp
4340 Example:
4341 .
4342 .Bd -literal -offset indent
4343 \&.Bl \-diag
4344 \&.It You can't use Sy here.
4345 The message says all.
4346 \&.El
4347 .Ed
4348 .
4349 .
4350 .Pp
4351 produces
4352 .
4353 .Bl -diag
4354 .It You can't use Sy here.
4355 The message says all.
4356 .El
4357 .
4358 .
4359 .Pp
4360 .It Fl hang
4361 A list with hanging tags.
4362 .
4363 .Bl -hang -offset indent
4364 .It Em Hanged
4365 labels appear similar to tagged lists when the
4366 label is smaller than the label width.
4367 .It Em Longer hanged list labels
4368 blend into the paragraph unlike
4369 tagged paragraph labels.
4370 .El
4371 .
4372 .
4373 .Pp
4374 And the unformatted text which created it:
4375 .
4376 .Bd -literal -offset indent
4377 \&.Bl \-hang \-offset indent
4378 \&.It Em Hanged
4379 labels appear similar to tagged lists when the
4380 label is smaller than the label width.
4381 \&.It Em Longer hanged list labels
4382 blend into the paragraph unlike
4383 tagged paragraph labels.
4384 \&.El
4385 .Ed
4386 .
4387 .
4388 .Pp
4389 .It Fl ohang
4390 Lists with overhanging tags do not use indentation for the items;
4391 tags are written to a separate line.
4392 .
4393 .
4394 .Pp
4395 .Bl -ohang -offset indent
4396 .It Sy SL
4397 sleep time of the process (seconds blocked)
4398 .It Sy PAGEIN
4399 number of disk I/O operations resulting from references by the process
4400 to pages not loaded in core.
4401 .It Sy UID
4402 numerical user-id of process owner
4403 .It Sy PPID
4404 numerical id of parent of process priority
4405 (non-positive when in non-interruptible wait)
4406 .El
4407 .
4408 .
4409 .Pp
4410 The raw text:
4411 .
4412 .Bd -literal -offset indent
4413 \&.Bl \-ohang \-offset indent
4414 \&.It Sy SL
4415 sleep time of the process (seconds blocked)
4416 \&.It Sy PAGEIN
4417 number of disk I/O operations resulting from references
4418 by the process to pages not loaded in core.
4419 \&.It Sy UID
4420 numerical user\-id of process owner
4421 \&.It Sy PPID
4422 numerical id of parent of process priority
4423 (non\-positive when in non\-interruptible wait)
4424 \&.El
4425 .Ed
4426 .
4427 .
4428 .Pp
4429 .It Fl inset
4430 Here is an example of inset labels:
4431 .Bl -inset -offset indent
4432 .It Em Tag
4433 The tagged list (also called a tagged paragraph)
4434 is the most common type of list used in the
4435 Berkeley manuals.
4436 Use a
4437 .Fl width
4438 attribute as described below.
4439 .It Em Diag
4440 Diag lists create section four diagnostic lists
4441 and are similar to inset lists except callable
4442 macros are ignored.
4443 .It Em Hang
4444 Hanged labels are a matter of taste.
4445 .It Em Ohang
4446 Overhanging labels are nice when space is constrained.
4447 .It Em Inset
4448 Inset labels are useful for controlling blocks of
4449 paragraphs and are valuable for converting
4450 .Xr mdoc
4451 manuals to other formats.
4452 .El
4453 .
4454 .
4455 .Pp
4456 Here is the source text which produced the above example:
4457 .
4458 .Bd -literal -offset indent
4459 \&.Bl \-inset \-offset indent
4460 \&.It Em Tag
4461 The tagged list (also called a tagged paragraph)
4462 is the most common type of list used in the
4463 Berkeley manuals.
4464 \&.It Em Diag
4465 Diag lists create section four diagnostic lists
4466 and are similar to inset lists except callable
4467 macros are ignored.
4468 \&.It Em Hang
4469 Hanged labels are a matter of taste.
4470 \&.It Em Ohang
4471 Overhanging labels are nice when space is constrained.
4472 \&.It Em Inset
4473 Inset labels are useful for controlling blocks of
4474 paragraphs and are valuable for converting
4475 \&.Xr mdoc
4476 manuals to other formats.
4477 \&.El
4478 .Ed
4479 .
4480 .
4481 .Pp
4482 .
4483 .It Fl column
4484 This list type generates multiple columns.
4485 The number of columns and the width of each column is determined by the
4486 arguments to the
4487 .Fl column
4488 list,
4489 .Aq Ar string1 ,
4490 .Aq Ar string2 ,
4491 etc.
4492 If
4493 .Aq Ar stringN
4494 starts with a
4495 .Ql .\&
4496 (dot) immediately followed by a valid
4497 .Xr mdoc
4498 macro name, interpret
4499 .Aq Ar stringN
4500 and use the width of the result.
4501 Otherwise, the width of
4502 .Aq Ar stringN
4503 (typeset with a fixed-width font) is taken as the
4504 .Ar N Ns th
4505 column width.
4506 .
4507 .
4508 .Pp
4509 Each
4510 .Ql .It
4511 argument is parsed to make a row, each column within the row is a separate
4512 argument separated by a tab or the
4513 .Ql .Ta
4514 macro.
4515 .
4516 .
4517 .Pp
4518 The table:
4519 .
4520 .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
4521 .It Sy String Ta Sy Nroff Ta Sy Troff
4522 .It Li <= Ta <= Ta \*(<=
4523 .It Li >= Ta >= Ta \*(>=
4524 .El
4525 .
4526 .
4527 .Pp
4528 was produced by:
4529 .
4530 .Bd -literal
4531 \&.Bl \-column \-offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
4532 \&.It Sy String Ta Sy Nroff Ta Sy Troff
4533 \&.It Li <= Ta <= Ta \e*(<=
4534 \&.It Li >= Ta >= Ta \e*(>=
4535 \&.El
4536 .Ed
4537 .
4538 .
4539 .Pp
4540 Don't abuse this list type!
4541 .
4542 For more complicated cases it might be far better and easier to use
4543 .Xr \%tbl 1 ,
4544 the table preprocessor.
4545 .El
4546 .
4547 .
4548 .Pp
4549 Other keywords:
4550 .
4551 .Bl -tag -width ".Fl indent Ao Ar string Ac"
4552 .It Fl width Ao Ar string Ac
4553 If
4554 .Aq Ar string
4555 starts with a
4556 .Ql .\&
4557 (dot) immediately followed by a valid
4558 .Xr mdoc
4559 macro name, interpret
4560 .Aq Ar string
4561 and use the width of the result.
4562 .
4563 Almost all lists in this document use this option.
4564 .
4565 .
4566 .Pp
4567 Example:
4568 .
4569 .Bd -literal -offset indent
4570 \&.Bl \-tag \-width ".Fl test Ao Ar string Ac"
4571 \&.It Fl test Ao Ar string Ac
4572 This is a longer sentence to show how the
4573 \&.Fl width
4574 flag works in combination with a tag list.
4575 \&.El
4576 .Ed
4577 .
4578 .
4579 .Pp
4580 gives:
4581 .
4582 .Bl -tag -width ".Fl test Ao Ar string Ac"
4583 .It Fl test Ao Ar string Ac
4584 This is a longer sentence to show how the
4585 .Fl width
4586 flag works in combination with a tag list.
4587 .El
4588 .
4589 .
4590 .Pp
4591 (Note that the current state of
4592 .Xr mdoc
4593 is saved before
4594 .Aq Ar string
4595 is interpreted;
4596 afterward,
4597 all variables are restored again.
4598 .
4599 However,
4600 boxes
4601 (used for enclosures)
4602 can't be saved in
4603 .Tn GNU
4604 .Xr \%troff 1 ;
4605 as a consequence,
4606 arguments must always be
4607 .Em balanced
4608 to avoid nasty errors.
4609 .
4610 For example,
4611 do not write
4612 .Ql ".Ao Ar string"
4613 but
4614 .Ql ".Ao Ar string Xc"
4615 instead if you really need only an opening angle bracket.)
4616 .
4617 .
4618 .Pp
4619 Otherwise,
4620 if
4621 .Aq Ar string
4622 is a valid numeric expression
4623 .Em ( with a scaling indicator other than
4624 .Sq Em u ) ,
4625 use that value for indentation.
4626 The most useful scaling indicators are
4627 .Sq m
4628 and
4629 .Sq n ,
4630 specifying the so-called
4631 .Em \&Em
4632 and
4633 .Em "En square" .
4634 This is approximately the width of the letters
4635 .Sq m
4636 and
4637 .Sq n
4638 respectively
4639 of the current font
4640 (for
4641 .Xr \%nroff
4642 output,
4643 both scaling indicators give the same values).
4644 .
4645 If
4646 .Aq Ar string
4647 isn't a numeric expression, it is tested whether it is an
4648 .Xr mdoc
4649 macro name, and the default width value associated with this macro is used.
4650 Finally, if all tests fail,
4651 the width of
4652 .Aq Ar string
4653 (typeset with a fixed-width font) is taken as the width.
4654 .
4655 .
4656 .Pp
4657 If a width is not specified for the tag list type,
4658 .Sq 6n
4659 is used.
4660 .It Fl offset Ao Ar string Ac
4661 If
4662 .Aq Ar string
4663 is
4664 .Ar indent ,
4665 a default indent value (normally set to\~6n,
4666 similar to the value used in
4667 .Ql .Dl
4668 or
4669 .Ql .Bd )
4670 is used.
4671 If
4672 .Aq Ar string
4673 is a valid numeric expression instead
4674 .Pf ( Em with a scaling indicator other than
4675 .Sq Em u ) ,
4676 use that value for indentation.
4677 The most useful scaling indicators are
4678 .Sq m
4679 and
4680 .Sq n ,
4681 specifying the so-called
4682 .Em \&Em
4683 and
4684 .Em "En square" .
4685 .
4686 This is approximately the width of the letters
4687 .Sq m
4688 and
4689 .Sq n
4690 respectively
4691 of the current font
4692 (for
4693 .Xr nroff
4694 output,
4695 both scaling indicators give the same values).
4696 .
4697 If
4698 .Aq Ar string
4699 isn't a numeric expression, it is tested whether it is an
4700 .Xr mdoc
4701 macro name, and the default offset value associated with this macro is used.
4702 Finally, if all tests fail,
4703 the width of
4704 .Aq Ar string
4705 (typeset with a fixed-width font) is taken as the offset.
4706 .It Fl compact
4707 Suppress insertion of vertical space before the list and between list items.
4708 .El
4709 .
4710 .
4711 .Sh "Miscellaneous macros"
4712 .
4713 A double handful of macros fit only uncomfortably into one of the above
4714 sections.
4715 .
4716 Of these,
4717 we couldn't find attested examples for
4718 .Ql \&Me
4719 or
4720 .Ql \&Ot .
4721 .
4722 They are documented here for completeness\[em]if you know their proper
4723 usage,
4724 please send a mail to
4725 .Mt [email protected]
4726 and include a specimen with its provenance.
4727 .
4728 .
4729 .Bl -tag -width ".Li .Bt"
4730 .It Li .Bt
4731 formats boilerplate text.
4732 .
4733 .\" XXX: .Bt gets parsed (i.e., called) _and_ measured even _with_ a
4734 .\" leading dot. See Savannah #63672.
4735 .Bl -tag -width \&.Bt -offset indent
4736 .It Li .Bt
4737 \[->]
4738 .Bt
4739 .El
4740 .
4741 .
4742 .Pp
4743 It is neither callable nor parsed and takes no arguments.
4744 .
4745 Its default width is 6n.
4746 .
4747 .
4748 .It Li .Fr
4749 is an obsolete means of specifying a function return value.
4750 .
4751 .
4752 .Pp
4753 .D1 Usage: Pf . Ic \&Fr Ar return-value No ...
4754 .
4755 .
4756 .Pp
4757 .Ql \&Fr
4758 allows a break right before the return value
4759 (usually a single digit)
4760 which is bad typographical behaviour.
4761 .
4762 Instead,
4763 set the return value with the rest of the code,
4764 using
4765 .Ql \[rs]\[ti]
4766 to tie the return value to the previous word.
4767 .
4768 .
4769 .Pp
4770 Its default width is 12n.
4771 .
4772 .
4773 .It Li .Hf
4774 Inlines the contents of a (header) file into the document.
4775 .
4776 .
4777 .Pp
4778 .D1 Usage: Pf . Ic \&Hf Ar file
4779 .
4780 .
4781 .Pp
4782 It first prints
4783 .Ql File:
4784 followed by the file name,
4785 then the contents of
4786 .Ar file .
4787 .
4788 It is neither callable nor parsed.
4789 .
4790 .
4791 .It Li .Lk
4792 Embed hyperlink.
4793 .
4794 This is a GNU extension introduced in
4795 .Em groff
4796 1.17
4797 (April 2001).
4798 .
4799 .
4800 .Pp
4801 .D1 Usage: Pf . Ic \&Lk Ar uri Op Ar link-text
4802 .
4803 .
4804 .Pp
4805 Its default width is 6n.
4806 .
4807 .
4808 .It Li .Me
4809 Usage unknown.
4810 .
4811 The
4812 .Xr mdoc
4813 sources describe it as a macro for
4814 .Dq "menu entries" .
4815 .
4816 .
4817 .Pp
4818 Its default width is 6n.
4819 .
4820 .
4821 .It Li .Mt
4822 Embed email address.
4823 .
4824 This is a GNU extension introduced in
4825 .Em groff
4826 1.17
4827 (April 2001).
4828 .
4829 .
4830 .Pp
4831 .D1 Usage: Pf . Ic \&Mt Ar email-address
4832 .
4833 .
4834 .Pp
4835 Its default width is 6n.
4836 .
4837 .
4838 .It Li .Ot
4839 Usage unknown.
4840 The
4841 .Xr mdoc
4842 sources describe it as
4843 .Dq "old function type (fortran)" .
4844 .
4845 .
4846 .It Li .Sm
4847 Manipulate or toggle argument-spacing mode.
4848 .
4849 .
4850 .Pp
4851 .D1 Usage: Pf . Ic \&Sm Oo Li on | Li off Oc ...
4852 .
4853 .
4854 .Pp
4855 If argument-spacing mode is off,
4856 no spaces between macro arguments are inserted.
4857 .
4858 If called without a parameter
4859 (or if the next parameter is neither
4860 .Ql on
4861 nor
4862 .Ql off ) ,
4863 .Ql \&Sm
4864 toggles argument-spacing mode.
4865 .
4866 .
4867 .Pp
4868 Its default width is 8n.
4869 .\" XXX: The package demands it, but how is that meaningful?
4870 .
4871 .
4872 .It Li .Ud
4873 formats boilerplate text.
4874 .
4875 .\" XXX: .Ud gets parsed (i.e., called) _and_ measured even _with_ a
4876 .\" leading dot. See Savannah #63672.
4877 .Bl -tag -width \&.Ud -offset indent
4878 .It Li .Ud
4879 \[->]
4880 .Ud
4881 .El
4882 .
4883 .
4884 .Pp
4885 It is neither callable nor parsed and takes no arguments.
4886 .
4887 Its default width is 8n.
4888 .El
4889 .
4890 .
4891 .Sh "Predefined strings"
4892 .
4893 The following strings are predefined for compatibility with legacy
4894 .Xr mdoc
4895 documents.
4896 .
4897 Contemporary ones should use the alternatives shown in the
4898 .Dq Prefer
4899 column below.
4900 .
4901 See
4902 .Xr groff_char 7
4903 for a full discussion of these special character escape sequences.
4904 .
4905 .
4906 .Pp
4907 .\" Note: This table pushes 80-column ASCII and Latin-1 terminals to
4908 .\" the limits of their capacity. Observe the spacing parameters of the
4909 .\" 2nd and 3rd columns; we had to steal a character cell from each (the
4910 .\" default is 3) because in the UCS column, the word "infinity" gets
4911 .\" written out in full, which in turn pushes the >= and Ge rows past
4912 .\" the historical 78n norm. Update with caution. See Savannah #59424.
4913 .TS
4914 Cb Lb2 Lb2 Lb Lb Lb
4915 Lf(CR) L2 L2 L Lf(CR) L.
4916 String 7-bit 8-bit UCS Prefer Meaning
4917 \[rs]*(<= <= <= \*[<=] \[rs][<=] less than or equal to
4918 \[rs]*(>= >= >= \*[>=] \[rs][>=] greater than or equal to
4919 \[rs]*(Rq " " \*[Rq] \[rs][rq] right double quote
4920 \[rs]*(Lq " " \*[Lq] \[rs][lq] left double quote
4921 \[rs]*(ua \[ha] \[ha] \*[ua] \[rs][ua] vertical arrow up
4922 \[rs]*(aa \[aq] \' \*[aa] \[rs][aa] acute accent
4923 \[rs]*(ga \` \` \*[ga] \[rs][ga] grave accent
4924 \[rs]*(q \&" \&" \*[q] \[rs][dq] neutral double quote
4925 \[rs]*(Pi pi pi \*[Pi] \[rs][*p] lowercase pi
4926 \[rs]*(Ne != != \*[Ne] \[rs][!=] not equals
4927 \[rs]*(Le <= <= \*[Le] \[rs][<=] less than or equal to
4928 \[rs]*(Ge >= >= \*[Ge] \[rs][>=] greater than or equal to
4929 \[rs]*(Lt < < \*[Lt] < less than
4930 \[rs]*(Gt > > \*[Gt] > greater than
4931 \[rs]*(Pm +\- \[+-] \*[Pm] \[rs][+\-] plus or minus
4932 \[rs]*(If infinity infinity \*[If] \[rs][if] infinity
4933 \[rs]*(Am \*[Am] \*[Am] \*[Am] & ampersand
4934 \[rs]*(Na \*[Na] \*[Na] \*[Na] .Em NaN not a number (slanted)
4935 \[rs]*(Ba \*[Ba] \*[Ba] \*[Ba] | bar (upright)
4936 .TE
4937 .
4938 .
4939 .Pp
4940 Some column headings are shorthand for standardized character encodings;
4941 \[lq]7-bit\[rq] for ISO\~646:1991\~IRV (US-ASCII),
4942 \[lq]8-bit\[rq] for ISO\~Latin-1 (8859-1),
4943 and
4944 \[lq]UCS\[rq] for ISO 10646 (Unicode character set).
4945 .
4946 Historically, \" (\[ti]1989)
4947 .Xr mdoc
4948 configured the string definitions to fit the capabilities expected of
4949 the output device.
4950 .
4951 Old typesetters \" like the C/A/T
4952 lacked directional double quotes,
4953 producing repeated directional single quotes
4954 \[oq]\[oq]like this\[cq]\[cq];
4955 early versions of
4956 .Xr mdoc
4957 in fact defined the
4958 .Ql Lq
4959 and
4960 .Ql Rq
4961 strings this way. \" thanks to Ingo Schwarze for the research
4962 .
4963 Nowadays,
4964 output drivers \" technically, their macro files or font descriptions
4965 take on the responsibility of glyph substitution,
4966 as they possess relevant knowledge of their available repertoires.
4967 .
4968 The
4969 .Ql Ba
4970 and
4971 .Ql Na
4972 strings imply a mandatory typeface:
4973 upright (roman) in the former,
4974 and slanted (italics) with the latter.
4975 .
4976 .
4977 .Sh Diagnostics
4978 .
4979 The debugging macro
4980 .Ql .Db
4981 offered by
4982 previous versions of
4983 .Xr mdoc
4984 is unavailable in
4985 .Tn GNU
4986 .Xr \%troff 1
4987 since the latter provides better facilities to check parameters;
4988 additionally,
4989 .Xr "groff mdoc"
4990 implements many error and warning messages,
4991 making the package more robust and more verbose.
4992 .
4993 .
4994 .Pp
4995 The remaining debugging macro is
4996 .Ql .Rd ,
4997 which dumps the package's global register and string contents to the
4998 standard error stream.
4999 .
5000 A normal user will never need it.
5001 .
5002 .
5003 .Sh Options
5004 .
5005 The following
5006 .Xr groff
5007 options set registers
5008 (with
5009 .Fl r )
5010 and strings
5011 (with
5012 .Fl d )
5013 recognized and used by the
5014 .Xr mdoc
5015 macro package.
5016 .
5017 To ensure rendering consistent with output device capabilities and
5018 reader preferences,
5019 man pages should never manipulate them.
5020 .
5021 .
5022 .Pp
5023 Setting string
5024 .Ql AD
5025 configures the adjustment mode for most formatted text.
5026 .
5027 Typical values are
5028 .Ql b
5029 for adjustment to both margins
5030 (the default),
5031 or
5032 .Ql l
5033 for left alignment
5034 (ragged right margin).
5035 .
5036 Any valid argument to
5037 .Xr groff Ns 's
5038 .Ql ad
5039 request may be used.
5040 .
5041 See
5042 .Xr groff 7
5043 for less-common choices.
5044 .
5045 .Dl groff \-Tutf8 \-dAD=l \-mdoc groff_mdoc.7 | less \-R
5046 .
5047 .
5048 .Pp
5049 Setting register
5050 .Ql C
5051 to\~1 numbers output pages consecutively,
5052 rather than resetting the page number to\~1
5053 (or the value of register
5054 .Ql P )
5055 with each new
5056 .Xr mdoc
5057 document.
5058 .
5059 .
5060 .Pp
5061 By default,
5062 the package inhibits page breaks,
5063 headers,
5064 and footers in the midst of the document text if it is being displayed
5065 with a terminal device such as
5066 .Sq latin1
5067 or
5068 .Sq utf8 ,
5069 to enable more efficient viewing of the page.
5070 .
5071 This behavior can be changed to format the page as if for 66-line
5072 Teletype output by setting the continuous rendering register
5073 .Ql cR
5074 to zero while calling
5075 .Xr groff 1 .
5076 .
5077 .Dl groff \-Tlatin1 \-rcR=0 \-mdoc foo.man > foo.txt
5078 .
5079 On HTML devices,
5080 it cannot be disabled.
5081 .
5082 .
5083 .Pp
5084 Section headings
5085 (defined with
5086 .Ql .Sh )
5087 and page titles in headers
5088 (defined with
5089 .Ql .Dt )
5090 can be presented in full capitals by setting the registers
5091 .Ql CS
5092 and
5093 .Ql CT ,
5094 respectively,
5095 to 1.
5096 .
5097 These transformations are off by default because they discard case
5098 distinction information.
5099 .
5100 .
5101 .Pp
5102 Setting register
5103 .Ql D
5104 to\~1 enables double-sided page layout,
5105 which is only distinct when not continuously rendering.
5106 .
5107 It places the page number at the bottom right on odd-numbered (recto)
5108 pages,
5109 and at the bottom left on even-numbered (verso) pages,
5110 swapping places with the arguments to
5111 .Ql .Os .
5112 .
5113 .Dl groff \-Tps \-rD1 \-mdoc foo.man > foo.ps
5114 .
5115 .
5116 .Pp
5117 The value of the
5118 .Ql FT
5119 register determines the footer's distance from the page bottom;
5120 this amount is always negative and should specify a scaling unit.
5121 .
5122 At one half-inch above this location,
5123 the page text is broken before writing the footer.
5124 .
5125 It is ignored if continuous rendering is enabled.
5126 .
5127 The default is \(lq\-0.5i\~\-\~1v\(rq.
5128 .
5129 .
5130 .Pp
5131 The
5132 .Ql HF
5133 string sets
5134 the font used for section and subsection headings;
5135 the default is
5136 .Ql B
5137 (bold style of the default family).
5138 .
5139 Any valid argument to
5140 .Xr groff Ns 's
5141 .Ql ft
5142 request may be used.
5143 .
5144 .
5145 .Pp
5146 Normally,
5147 automatic hyphenation is enabled using a mode appropriate to the
5148 .Xr groff
5149 locale;
5150 see section \[lq]Localization\[lq] of
5151 .Xr groff 7 .
5152 .
5153 It can be disabled by setting the
5154 .Ql HY
5155 register to zero.
5156 .
5157 .Dl groff \-Tutf8 \-rHY=0 \-mdoc foo.man | less \-R
5158 .
5159 .
5160 .Pp
5161 The paragraph and subsection heading indentation amounts can be changed
5162 by setting the registers
5163 .Ql BP
5164 and
5165 .Ql SN .
5166 .
5167 .Dl groff \-Tutf8 \-rBP=4n \-rSN=2n \-mdoc foo.man | less \-R
5168 .
5169 The default paragraph and subsection heading indentation amounts are 5n
5170 and 3n, respectively.
5171 .
5172 Section headings are set with an indentation of zero.
5173 .
5174 .
5175 .Pp
5176 The line and title lengths can be changed by setting the registers
5177 .Ql LL
5178 and
5179 .Ql LT ,
5180 respectively:
5181 .
5182 .Dl groff \-Tutf8 \-rLL=100n \-rLT=100n \-mdoc foo.man | less \-R
5183 .
5184 If not set,
5185 both registers default to 80n for terminal devices and 6.5i otherwise.
5186 .
5187 .
5188 .Pp
5189 The
5190 .Ql MF
5191 string sets
5192 the font used for man page identifiers in document headers and footers
5193 and in the formatted output of the
5194 .Ql \&Xr
5195 macro.
5196 .
5197 The default is
5198 .Ql I
5199 (italic style of the default family).
5200 .
5201 Any valid argument to
5202 .Xr groff Ns 's
5203 .Ql ft
5204 request may be used.
5205 .
5206 .
5207 .Pp
5208 Setting the
5209 .Ql P
5210 register starts enumeration of pages at its value.
5211 .
5212 The default is\~1.
5213 .
5214 .
5215 .Pp
5216 The
5217 .Ql PO
5218 register configures the page offset.
5219 .
5220 The default is device-dependent;
5221 typically 0 for terminal devices and 1i otherwise.
5222 .
5223 .
5224 .Pp
5225 To change the document font size to 11p or 12p,
5226 set register
5227 .Ql S
5228 accordingly:
5229 .
5230 .Dl groff \-Tdvi \-rS11 \-mdoc foo.man > foo.dvi
5231 .
5232 Register
5233 .Ql S
5234 is ignored when formatting for terminal devices.
5235 .
5236 .
5237 .Pp
5238 By default,
5239 .Xr groff
5240 hyperlinks the formatted text of
5241 .Ql \&Lk ,
5242 .Ql \&Mt ,
5243 and
5244 .Ql \&Xr
5245 calls on output devices that support hyperlinking
5246 .Pf ( Dq html ,
5247 .Dq pdf ,
5248 and
5249 terminal devices).
5250 .
5251 Set the
5252 .Ql U
5253 register to 0 to disable this feature.
5254 .
5255 .
5256 .Pp
5257 Setting the
5258 .Ql X
5259 register to a page number
5260 .Ar p
5261 numbers its successors as
5262 .Ar p Ns Li a ,
5263 .Ar p Ns Li b ,
5264 .Ar p Ns Li c ,
5265 and so forth.
5266 .
5267 The register tracking the suffixed page letter uses format
5268 .Ql a
5269 (see the
5270 .Ql af
5271 request in
5272 .Xr groff 7 ) .
5273 .
5274 .
5275 .\"br
5276 .\"ne 4v
5277 .Sh Files
5278 .
5279 .Bl -tag
5280 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:andoc\:.tmac
5281 This brief
5282 .Xr groff
5283 program detects whether the
5284 .Xr man
5285 or
5286 .Xr mdoc
5287 macro package is being used by a document and loads the correct macro
5288 definitions,
5289 taking advantage of the fact that pages using them must call
5290 .Li TH
5291 or
5292 .Li Dd ,
5293 respectively,
5294 before any other macros.
5295 .
5296 A user typing,
5297 for example,
5298 .Dl groff \-mandoc page.1
5299 need not know which package the file
5300 .Pa page.1
5301 uses.
5302 .
5303 Multiple man pages,
5304 in either format,
5305 can be handled;
5306 .Pa \%andoc\:.tmac
5307 reloads each macro package as necessary.
5308 .
5309 .
5310 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:doc\:.tmac
5311 implements the bulk of the
5312 .Xr groff Xr mdoc
5313 package and loads further components as needed from the
5314 .Pa mdoc
5315 subdirectory.
5316 .
5317 .
5318 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:doc\-old\:.tmac
5319 implements a legacy version of the
5320 .Xr mdoc
5321 package;
5322 it was superseded in 4.4BSD (1994)
5323 and is needed only to render certain man pages from 4.3BSD-Reno.
5324 .
5325 .
5326 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:mdoc\:.tmac
5327 is a wrapper enabling the package to be loaded with the option
5328 .Dq Li "\-m mdoc" .
5329 .
5330 .
5331 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:mdoc/\:doc\-common
5332 defines macros,
5333 registers,
5334 and strings
5335 concerned with the production of formatted output.
5336 .\" XXX: This is a weak explanation. The boundary between doc.tmac's
5337 .\" concerns and doc-common's is not at all clear to GBR. Should some
5338 .\" of these files be merged?
5339 .
5340 It includes strings of the form
5341 .Ql doc\-volume\-ds\- Ns Ar X
5342 and
5343 .Ql doc\-volume\-as\- Ns Ar X
5344 for manual section titles and architecture identifiers,
5345 respectively,
5346 where
5347 .Ar X
5348 is an argument recognized by
5349 .Pf . Ic \&Dt .
5350 .
5351 .
5352 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:mdoc/\:doc\-nroff
5353 defines parameters appropriate for rendering to terminal devices.
5354 .
5355 .
5356 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:mdoc/\:doc\-ditroff
5357 defines parameters appropriate for rendering to typesetter devices.
5358 .
5359 .
5360 .It Pa /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:mdoc/\:doc\-syms
5361 defines many strings and macros that interpolate formatted text,
5362 such as names of operating system releases,
5363 *BSD libraries,
5364 and standards documents.
5365 .
5366 The string names are of the form
5367 .Ql doc\-str\- Ns Ar O Ns Li \- Ns Ar V ,
5368 .Ql doc\-str\-St Ns Li \-\- Ns Ar S Ns Li \- Ns Ar I
5369 (observe the double dashes),
5370 or
5371 .Ql doc\-str\-Lb\- Ns Ar L ,
5372 where
5373 .Ar O
5374 is one of the operating system macros from section
5375 .Sx "General text domain"
5376 above,
5377 .Ar V
5378 is an encoding of an operating system release
5379 (sometimes omitted along with the
5380 .Ql \-
5381 preceding it),
5382 .Ar S
5383 an identifier for a standards body or committee,
5384 .Ar I
5385 one for an issue of a standard promulgated by
5386 .Ar S ,
5387 and
5388 .Ar L
5389 a keyword identifying a *BSD library.
5390 .
5391 .
5392 .It Pa /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:mdoc\:.local
5393 This file houses local additions and customizations to the package.
5394 .
5395 It can be empty.
5396 .El
5397 .
5398 .
5399 .Sh "See also"
5400 .
5401 The
5402 .Lk https://mandoc.bsd.lv/ mandoc
5403 project maintains an independent implementation of the
5404 .Xr mdoc
5405 language and a renderer that directly parses its markup as well as that
5406 of
5407 .Xr man .
5408 .
5409 .
5410 .Pp
5411 .Xr groff 1 ,
5412 .Xr man 1 ,
5413 .Xr \%troff 1 ,
5414 .Xr groff_man 7 ,
5415 .Xr mdoc 7
5416 .
5417 .
5418 .Sh Bugs
5419 .
5420 Section 3f has not been added to the header routines.
5421 .
5422 .
5423 .Pp
5424 .Ql .Fn
5425 needs to have a check to prevent splitting up the line if its length is
5426 too short.
5427 .
5428 Occasionally it separates the last parenthesis,
5429 and sometimes looks ridiculous if output lines are being filled.
5430 .
5431 .
5432 .Pp
5433 The list and display macros do not do any keeps and certainly should be
5434 able to.
5435 .
5436 .
5437 .Pp
5438 As of
5439 .Xr groff
5440 1.23,
5441 .Ql \&Tn
5442 no longer changes the type size;
5443 this functionality may return in a future release.
5444 .\" Note what happens if the parameter list overlaps a newline
5445 .\" boundary.
5446 .\" to make sure a line boundary is crossed:
5447 .\" .Bd -literal
5448 .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
5449 .\" .Ed
5450 .\" .
5451 .\" .
5452 .\" .Pp
5453 .\" produces, nudge nudge,
5454 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
5455 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
5456 .\" nudge
5457 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
5458 .\" .
5459 .\" .
5460 .\" .Pp
5461 .\" If double quotes are used, for example:
5462 .\" .Bd -literal
5463 .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
5464 .\" .Ed
5465 .\" .
5466 .\" .
5467 .\" .Pp
5468 .\" produces, nudge nudge,
5469 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
5470 .\" nudge
5471 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
5472 .\" nudge
5473 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
5474 .\" .
5475 .\" .
5476 .\" .Pp
5477 .\" Not a pretty sight...
5478 .\" In a paragraph, a long parameter containing unpaddable spaces as
5479 .\" in the former example will cause
5480 .\" .Xr \%troff
5481 .\" to break the line and spread
5482 .\" the remaining words out.
5483 .\" The latter example will adjust nicely to
5484 .\" justified margins, but may break in between an argument and its
5485 .\" declaration.
5486 .\" In
5487 .\" .Xr \%nroff
5488 .\" the right margin is normally ragged and the problem is not as
5489 .\" severe.
5490 .
5491 .
5492 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
5493 .cp \n[*groff_groff_mdoc_7_man_C]
5494 .do rr *groff_groff_mdoc_7_man_C
5495 .
5496 .
5497 .\" Local Variables:
5498 .\" mode: nroff
5499 .\" fill-column: 72
5500 .\" End:
5501 .\" vim: set filetype=groff textwidth=72: