Debian Codegraph @

upstream/debian-trixie/man7/groff_mdoc.7

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