]> git.cameronkatri.com Git - mandoc.git/blob - mdoc.7
Minimal COMPATIBILITY cleanup:
[mandoc.git] / mdoc.7
1 .\" $Id: mdoc.7,v 1.229 2014/06/22 17:07:06 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd $Mdocdate: June 22 2014 $
19 .Dt MDOC 7
20 .Os
21 .Sh NAME
22 .Nm mdoc
23 .Nd semantic markup language for formatting manual pages
24 .Sh DESCRIPTION
25 The
26 .Nm mdoc
27 language supports authoring of manual pages for the
28 .Xr man 1
29 utility by allowing semantic annotations of words, phrases,
30 page sections and complete manual pages.
31 Such annotations are used by formatting tools to achieve a uniform
32 presentation across all manuals written in
33 .Nm ,
34 and to support hyperlinking if supported by the output medium.
35 .Pp
36 This reference document describes the structure of manual pages
37 and the syntax and usage of the
38 .Nm
39 language.
40 The reference implementation of a parsing and formatting tool is
41 .Xr mandoc 1 ;
42 the
43 .Sx COMPATIBILITY
44 section describes compatibility with other implementations.
45 .Pp
46 In an
47 .Nm
48 document, lines beginning with the control character
49 .Sq \&.
50 are called
51 .Dq macro lines .
52 The first word is the macro name.
53 It consists of two or three letters.
54 Most macro names begin with a capital letter.
55 For a list of available macros, see
56 .Sx MACRO OVERVIEW .
57 The words following the macro name are arguments to the macro, optionally
58 including the names of other, callable macros; see
59 .Sx MACRO SYNTAX
60 for details.
61 .Pp
62 Lines not beginning with the control character are called
63 .Dq text lines .
64 They provide free-form text to be printed; the formatting of the text
65 depends on the respective processing context:
66 .Bd -literal -offset indent
67 \&.Sh Macro lines change control state.
68 Text lines are interpreted within the current state.
69 .Ed
70 .Pp
71 Many aspects of the basic syntax of the
72 .Nm
73 language are based on the
74 .Xr roff 7
75 language; see the
76 .Em LANGUAGE SYNTAX
77 and
78 .Em MACRO SYNTAX
79 sections in the
80 .Xr roff 7
81 manual for details, in particular regarding
82 comments, escape sequences, whitespace, and quoting.
83 However, using
84 .Xr roff 7
85 requests in
86 .Nm
87 documents is discouraged;
88 .Xr mandoc 1
89 supports some of them merely for backward compatibility.
90 .Sh MANUAL STRUCTURE
91 A well-formed
92 .Nm
93 document consists of a document prologue followed by one or more
94 sections.
95 .Pp
96 The prologue, which consists of the
97 .Sx \&Dd ,
98 .Sx \&Dt ,
99 and
100 .Sx \&Os
101 macros in that order, is required for every document.
102 .Pp
103 The first section (sections are denoted by
104 .Sx \&Sh )
105 must be the NAME section, consisting of at least one
106 .Sx \&Nm
107 followed by
108 .Sx \&Nd .
109 .Pp
110 Following that, convention dictates specifying at least the
111 .Em SYNOPSIS
112 and
113 .Em DESCRIPTION
114 sections, although this varies between manual sections.
115 .Pp
116 The following is a well-formed skeleton
117 .Nm
118 file for a utility
119 .Qq progname :
120 .Bd -literal -offset indent
121 \&.Dd $\&Mdocdate$
122 \&.Dt PROGNAME section
123 \&.Os
124 \&.Sh NAME
125 \&.Nm progname
126 \&.Nd one line about what it does
127 \&.\e\(dq .Sh LIBRARY
128 \&.\e\(dq For sections 2, 3, and 9 only.
129 \&.\e\(dq Not used in OpenBSD.
130 \&.Sh SYNOPSIS
131 \&.Nm progname
132 \&.Op Fl options
133 \&.Ar
134 \&.Sh DESCRIPTION
135 The
136 \&.Nm
137 utility processes files ...
138 \&.\e\(dq .Sh CONTEXT
139 \&.\e\(dq For section 9 functions only.
140 \&.\e\(dq .Sh IMPLEMENTATION NOTES
141 \&.\e\(dq Not used in OpenBSD.
142 \&.\e\(dq .Sh RETURN VALUES
143 \&.\e\(dq For sections 2, 3, and 9 function return values only.
144 \&.\e\(dq .Sh ENVIRONMENT
145 \&.\e\(dq For sections 1, 6, 7, and 8 only.
146 \&.\e\(dq .Sh FILES
147 \&.\e\(dq .Sh EXIT STATUS
148 \&.\e\(dq For sections 1, 6, and 8 only.
149 \&.\e\(dq .Sh EXAMPLES
150 \&.\e\(dq .Sh DIAGNOSTICS
151 \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
152 \&.\e\(dq .Sh ERRORS
153 \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
154 \&.\e\(dq .Sh SEE ALSO
155 \&.\e\(dq .Xr foobar 1
156 \&.\e\(dq .Sh STANDARDS
157 \&.\e\(dq .Sh HISTORY
158 \&.\e\(dq .Sh AUTHORS
159 \&.\e\(dq .Sh CAVEATS
160 \&.\e\(dq .Sh BUGS
161 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
162 \&.\e\(dq Not used in OpenBSD.
163 .Ed
164 .Pp
165 The sections in an
166 .Nm
167 document are conventionally ordered as they appear above.
168 Sections should be composed as follows:
169 .Bl -ohang -offset Ds
170 .It Em NAME
171 The name(s) and a one line description of the documented material.
172 The syntax for this as follows:
173 .Bd -literal -offset indent
174 \&.Nm name0 ,
175 \&.Nm name1 ,
176 \&.Nm name2
177 \&.Nd a one line description
178 .Ed
179 .Pp
180 Multiple
181 .Sq \&Nm
182 names should be separated by commas.
183 .Pp
184 The
185 .Sx \&Nm
186 macro(s) must precede the
187 .Sx \&Nd
188 macro.
189 .Pp
190 See
191 .Sx \&Nm
192 and
193 .Sx \&Nd .
194 .It Em LIBRARY
195 The name of the library containing the documented material, which is
196 assumed to be a function in a section 2, 3, or 9 manual.
197 The syntax for this is as follows:
198 .Bd -literal -offset indent
199 \&.Lb libarm
200 .Ed
201 .Pp
202 See
203 .Sx \&Lb .
204 .It Em SYNOPSIS
205 Documents the utility invocation syntax, function call syntax, or device
206 configuration.
207 .Pp
208 For the first, utilities (sections 1, 6, and 8), this is
209 generally structured as follows:
210 .Bd -literal -offset indent
211 \&.Nm bar
212 \&.Op Fl v
213 \&.Op Fl o Ar file
214 \&.Op Ar
215 \&.Nm foo
216 \&.Op Fl v
217 \&.Op Fl o Ar file
218 \&.Op Ar
219 .Ed
220 .Pp
221 Commands should be ordered alphabetically.
222 .Pp
223 For the second, function calls (sections 2, 3, 9):
224 .Bd -literal -offset indent
225 \&.In header.h
226 \&.Vt extern const char *global;
227 \&.Ft "char *"
228 \&.Fn foo "const char *src"
229 \&.Ft "char *"
230 \&.Fn bar "const char *src"
231 .Ed
232 .Pp
233 Ordering of
234 .Sx \&In ,
235 .Sx \&Vt ,
236 .Sx \&Fn ,
237 and
238 .Sx \&Fo
239 macros should follow C header-file conventions.
240 .Pp
241 And for the third, configurations (section 4):
242 .Bd -literal -offset indent
243 \&.Cd \(dqit* at isa? port 0x2e\(dq
244 \&.Cd \(dqit* at isa? port 0x4e\(dq
245 .Ed
246 .Pp
247 Manuals not in these sections generally don't need a
248 .Em SYNOPSIS .
249 .Pp
250 Some macros are displayed differently in the
251 .Em SYNOPSIS
252 section, particularly
253 .Sx \&Nm ,
254 .Sx \&Cd ,
255 .Sx \&Fd ,
256 .Sx \&Fn ,
257 .Sx \&Fo ,
258 .Sx \&In ,
259 .Sx \&Vt ,
260 and
261 .Sx \&Ft .
262 All of these macros are output on their own line.
263 If two such dissimilar macros are pairwise invoked (except for
264 .Sx \&Ft
265 before
266 .Sx \&Fo
267 or
268 .Sx \&Fn ) ,
269 they are separated by a vertical space, unless in the case of
270 .Sx \&Fo ,
271 .Sx \&Fn ,
272 and
273 .Sx \&Ft ,
274 which are always separated by vertical space.
275 .Pp
276 When text and macros following an
277 .Sx \&Nm
278 macro starting an input line span multiple output lines,
279 all output lines but the first will be indented to align
280 with the text immediately following the
281 .Sx \&Nm
282 macro, up to the next
283 .Sx \&Nm ,
284 .Sx \&Sh ,
285 or
286 .Sx \&Ss
287 macro or the end of an enclosing block, whichever comes first.
288 .It Em DESCRIPTION
289 This begins with an expansion of the brief, one line description in
290 .Em NAME :
291 .Bd -literal -offset indent
292 The
293 \&.Nm
294 utility does this, that, and the other.
295 .Ed
296 .Pp
297 It usually follows with a breakdown of the options (if documenting a
298 command), such as:
299 .Bd -literal -offset indent
300 The arguments are as follows:
301 \&.Bl \-tag \-width Ds
302 \&.It Fl v
303 Print verbose information.
304 \&.El
305 .Ed
306 .Pp
307 Manuals not documenting a command won't include the above fragment.
308 .Pp
309 Since the
310 .Em DESCRIPTION
311 section usually contains most of the text of a manual, longer manuals
312 often use the
313 .Sx \&Ss
314 macro to form subsections.
315 In very long manuals, the
316 .Em DESCRIPTION
317 may be split into multiple sections, each started by an
318 .Sx \&Sh
319 macro followed by a non-standard section name, and each having
320 several subsections, like in the present
321 .Nm
322 manual.
323 .It Em CONTEXT
324 This section lists the contexts in which functions can be called in section 9.
325 The contexts are autoconf, process, or interrupt.
326 .It Em IMPLEMENTATION NOTES
327 Implementation-specific notes should be kept here.
328 This is useful when implementing standard functions that may have side
329 effects or notable algorithmic implications.
330 .It Em RETURN VALUES
331 This section documents the
332 return values of functions in sections 2, 3, and 9.
333 .Pp
334 See
335 .Sx \&Rv .
336 .It Em ENVIRONMENT
337 Lists the environment variables used by the utility,
338 and explains the syntax and semantics of their values.
339 The
340 .Xr environ 7
341 manual provides examples of typical content and formatting.
342 .Pp
343 See
344 .Sx \&Ev .
345 .It Em FILES
346 Documents files used.
347 It's helpful to document both the file name and a short description of how
348 the file is used (created, modified, etc.).
349 .Pp
350 See
351 .Sx \&Pa .
352 .It Em EXIT STATUS
353 This section documents the
354 command exit status for section 1, 6, and 8 utilities.
355 Historically, this information was described in
356 .Em DIAGNOSTICS ,
357 a practise that is now discouraged.
358 .Pp
359 See
360 .Sx \&Ex .
361 .It Em EXAMPLES
362 Example usages.
363 This often contains snippets of well-formed, well-tested invocations.
364 Make sure that examples work properly!
365 .It Em DIAGNOSTICS
366 Documents error messages.
367 In section 4 and 9 manuals, these are usually messages printed by the
368 kernel to the console and to the kernel log.
369 In section 1, 6, 7, and 8, these are usually messages printed by
370 userland programs to the standard error output.
371 .Pp
372 Historically, this section was used in place of
373 .Em EXIT STATUS
374 for manuals in sections 1, 6, and 8; however, this practise is
375 discouraged.
376 .Pp
377 See
378 .Sx \&Bl
379 .Fl diag .
380 .It Em ERRORS
381 Documents
382 .Xr errno 2
383 settings in sections 2, 3, 4, and 9.
384 .Pp
385 See
386 .Sx \&Er .
387 .It Em SEE ALSO
388 References other manuals with related topics.
389 This section should exist for most manuals.
390 Cross-references should conventionally be ordered first by section, then
391 alphabetically.
392 .Pp
393 References to other documentation concerning the topic of the manual page,
394 for example authoritative books or journal articles, may also be
395 provided in this section.
396 .Pp
397 See
398 .Sx \&Rs
399 and
400 .Sx \&Xr .
401 .It Em STANDARDS
402 References any standards implemented or used.
403 If not adhering to any standards, the
404 .Em HISTORY
405 section should be used instead.
406 .Pp
407 See
408 .Sx \&St .
409 .It Em HISTORY
410 A brief history of the subject, including where it was first implemented,
411 and when it was ported to or reimplemented for the operating system at hand.
412 .It Em AUTHORS
413 Credits to the person or persons who wrote the code and/or documentation.
414 Authors should generally be noted by both name and email address.
415 .Pp
416 See
417 .Sx \&An .
418 .It Em CAVEATS
419 Common misuses and misunderstandings should be explained
420 in this section.
421 .It Em BUGS
422 Known bugs, limitations, and work-arounds should be described
423 in this section.
424 .It Em SECURITY CONSIDERATIONS
425 Documents any security precautions that operators should consider.
426 .El
427 .Sh MACRO OVERVIEW
428 This overview is sorted such that macros of similar purpose are listed
429 together, to help find the best macro for any given purpose.
430 Deprecated macros are not included in the overview, but can be found below
431 in the alphabetical
432 .Sx MACRO REFERENCE .
433 .Ss Document preamble and NAME section macros
434 .Bl -column "Brq, Bro, Brc" description
435 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
436 .It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
437 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
438 .It Sx \&Nm Ta document name (one argument)
439 .It Sx \&Nd Ta document description (one line)
440 .El
441 .Ss Sections and cross references
442 .Bl -column "Brq, Bro, Brc" description
443 .It Sx \&Sh Ta section header (one line)
444 .It Sx \&Ss Ta subsection header (one line)
445 .It Sx \&Sx Ta internal cross reference to a section or subsection
446 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
447 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
448 .El
449 .Ss Displays and lists
450 .Bl -column "Brq, Bro, Brc" description
451 .It Sx \&Bd , \&Ed Ta display block:
452 .Fl Ar type
453 .Op Fl offset Ar width
454 .Op Fl compact
455 .It Sx \&D1 Ta indented display (one line)
456 .It Sx \&Dl Ta indented literal display (one line)
457 .It Sx \&Bl , \&El Ta list block:
458 .Fl Ar type
459 .Op Fl width Ar val
460 .Op Fl offset Ar val
461 .Op Fl compact
462 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
463 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
464 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
465 .El
466 .Ss Spacing control
467 .Bl -column "Brq, Bro, Brc" description
468 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
469 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
470 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
471 .It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
472 .It Sx \&Bk , \&Ek Ta keep block: Fl words
473 .It Sx \&br Ta force output line break in text mode (no arguments)
474 .It Sx \&sp Ta force vertical space: Op Ar height
475 .El
476 .Ss Semantic markup for command line utilities:
477 .Bl -column "Brq, Bro, Brc" description
478 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
479 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
480 .It Sx \&Cm Ta command modifier (>0 arguments)
481 .It Sx \&Ar Ta command arguments (>=0 arguments)
482 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
483 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
484 .It Sx \&Ev Ta environmental variable (>0 arguments)
485 .It Sx \&Pa Ta file system path (>=0 arguments)
486 .El
487 .Ss Semantic markup for function libraries:
488 .Bl -column "Brq, Bro, Brc" description
489 .It Sx \&Lb Ta function library (one argument)
490 .It Sx \&In Ta include file (one argument)
491 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
492 .It Sx \&Ft Ta function type (>0 arguments)
493 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
494 .It Sx \&Fn Ta function name:
495 .Op Ar functype
496 .Ar funcname
497 .Oo
498 .Op Ar argtype
499 .Ar argname
500 .Oc
501 .It Sx \&Fa Ta function argument (>0 arguments)
502 .It Sx \&Vt Ta variable type (>0 arguments)
503 .It Sx \&Va Ta variable name (>0 arguments)
504 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
505 .It Sx \&Er Ta error constant (>0 arguments)
506 .It Sx \&Ev Ta environmental variable (>0 arguments)
507 .El
508 .Ss Various semantic markup:
509 .Bl -column "Brq, Bro, Brc" description
510 .It Sx \&An Ta author name (>0 arguments)
511 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
512 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
513 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
514 .It Sx \&Ad Ta memory address (>0 arguments)
515 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
516 .It Sx \&Tn Ta tradename (>0 arguments)
517 .El
518 .Ss Physical markup
519 .Bl -column "Brq, Bro, Brc" description
520 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
521 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
522 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
523 .It Sx \&No Ta return to roman font (normal) (no arguments)
524 .It Sx \&Bf , \&Ef Ta font block:
525 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
526 .El
527 .Ss Physical enclosures
528 .Bl -column "Brq, Bro, Brc" description
529 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
530 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
531 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
532 .It Sx \&Ql Ta single-quoted literal text: Ql text
533 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
534 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
535 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
536 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
537 .It Sx \&Eo , \&Ec Ta generic enclosure
538 .El
539 .Ss Text production
540 .Bl -column "Brq, Bro, Brc" description
541 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
542 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
543 .It Sx \&St Ta reference to a standards document (one argument)
544 .It Sx \&Ux Ta Ux
545 .It Sx \&At Ta At
546 .It Sx \&Bx Ta Bx
547 .It Sx \&Bsx Ta Bsx
548 .It Sx \&Nx Ta Nx
549 .It Sx \&Fx Ta Fx
550 .It Sx \&Ox Ta Ox
551 .It Sx \&Dx Ta Dx
552 .El
553 .Sh MACRO REFERENCE
554 This section is a canonical reference of all macros, arranged
555 alphabetically.
556 For the scoping of individual macros, see
557 .Sx MACRO SYNTAX .
558 .Ss \&%A
559 Author name of an
560 .Sx \&Rs
561 block.
562 Multiple authors should each be accorded their own
563 .Sx \%%A
564 line.
565 Author names should be ordered with full or abbreviated forename(s)
566 first, then full surname.
567 .Ss \&%B
568 Book title of an
569 .Sx \&Rs
570 block.
571 This macro may also be used in a non-bibliographic context when
572 referring to book titles.
573 .Ss \&%C
574 Publication city or location of an
575 .Sx \&Rs
576 block.
577 .Ss \&%D
578 Publication date of an
579 .Sx \&Rs
580 block.
581 Recommended formats of arguments are
582 .Ar month day , year
583 or just
584 .Ar year .
585 .Ss \&%I
586 Publisher or issuer name of an
587 .Sx \&Rs
588 block.
589 .Ss \&%J
590 Journal name of an
591 .Sx \&Rs
592 block.
593 .Ss \&%N
594 Issue number (usually for journals) of an
595 .Sx \&Rs
596 block.
597 .Ss \&%O
598 Optional information of an
599 .Sx \&Rs
600 block.
601 .Ss \&%P
602 Book or journal page number of an
603 .Sx \&Rs
604 block.
605 .Ss \&%Q
606 Institutional author (school, government, etc.) of an
607 .Sx \&Rs
608 block.
609 Multiple institutional authors should each be accorded their own
610 .Sx \&%Q
611 line.
612 .Ss \&%R
613 Technical report name of an
614 .Sx \&Rs
615 block.
616 .Ss \&%T
617 Article title of an
618 .Sx \&Rs
619 block.
620 This macro may also be used in a non-bibliographical context when
621 referring to article titles.
622 .Ss \&%U
623 URI of reference document.
624 .Ss \&%V
625 Volume number of an
626 .Sx \&Rs
627 block.
628 .Ss \&Ac
629 Close an
630 .Sx \&Ao
631 block.
632 Does not have any tail arguments.
633 .Ss \&Ad
634 Memory address.
635 Do not use this for postal addresses.
636 .Pp
637 Examples:
638 .Dl \&.Ad [0,$]
639 .Dl \&.Ad 0x00000000
640 .Ss \&An
641 Author name.
642 Can be used both for the authors of the program, function, or driver
643 documented in the manual, or for the authors of the manual itself.
644 Requires either the name of an author or one of the following arguments:
645 .Pp
646 .Bl -tag -width "-nosplitX" -offset indent -compact
647 .It Fl split
648 Start a new output line before each subsequent invocation of
649 .Sx \&An .
650 .It Fl nosplit
651 The opposite of
652 .Fl split .
653 .El
654 .Pp
655 The default is
656 .Fl nosplit .
657 The effect of selecting either of the
658 .Fl split
659 modes ends at the beginning of the
660 .Em AUTHORS
661 section.
662 In the
663 .Em AUTHORS
664 section, the default is
665 .Fl nosplit
666 for the first author listing and
667 .Fl split
668 for all other author listings.
669 .Pp
670 Examples:
671 .Dl \&.An -nosplit
672 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
673 .Ss \&Ao
674 Begin a block enclosed by angle brackets.
675 Does not have any head arguments.
676 .Pp
677 Examples:
678 .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
679 .Pp
680 See also
681 .Sx \&Aq .
682 .Ss \&Ap
683 Inserts an apostrophe without any surrounding whitespace.
684 This is generally used as a grammatical device when referring to the verb
685 form of a function.
686 .Pp
687 Examples:
688 .Dl \&.Fn execve \&Ap d
689 .Ss \&Aq
690 Encloses its arguments in angle brackets.
691 .Pp
692 Examples:
693 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
694 .Pp
695 .Em Remarks :
696 this macro is often abused for rendering URIs, which should instead use
697 .Sx \&Lk
698 or
699 .Sx \&Mt ,
700 or to note pre-processor
701 .Dq Li #include
702 statements, which should use
703 .Sx \&In .
704 .Pp
705 See also
706 .Sx \&Ao .
707 .Ss \&Ar
708 Command arguments.
709 If an argument is not provided, the string
710 .Dq file ...\&
711 is used as a default.
712 .Pp
713 Examples:
714 .Dl ".Fl o Ar file"
715 .Dl ".Ar"
716 .Dl ".Ar arg1 , arg2 ."
717 .Pp
718 The arguments to the
719 .Sx \&Ar
720 macro are names and placeholders for command arguments;
721 for fixed strings to be passed verbatim as arguments, use
722 .Sx \&Fl
723 or
724 .Sx \&Cm .
725 .Ss \&At
726 Formats an
727 .At
728 version.
729 Accepts one optional argument:
730 .Pp
731 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
732 .It Cm v[1-7] | 32v
733 A version of
734 .At .
735 .It Cm III
736 .At III .
737 .It Cm V[.[1-4]]?
738 A version of
739 .At V .
740 .El
741 .Pp
742 Note that these arguments do not begin with a hyphen.
743 .Pp
744 Examples:
745 .Dl \&.At
746 .Dl \&.At III
747 .Dl \&.At V.1
748 .Pp
749 See also
750 .Sx \&Bsx ,
751 .Sx \&Bx ,
752 .Sx \&Dx ,
753 .Sx \&Fx ,
754 .Sx \&Nx ,
755 .Sx \&Ox ,
756 and
757 .Sx \&Ux .
758 .Ss \&Bc
759 Close a
760 .Sx \&Bo
761 block.
762 Does not have any tail arguments.
763 .Ss \&Bd
764 Begin a display block.
765 Its syntax is as follows:
766 .Bd -ragged -offset indent
767 .Pf \. Sx \&Bd
768 .Fl Ns Ar type
769 .Op Fl offset Ar width
770 .Op Fl compact
771 .Ed
772 .Pp
773 Display blocks are used to select a different indentation and
774 justification than the one used by the surrounding text.
775 They may contain both macro lines and text lines.
776 By default, a display block is preceded by a vertical space.
777 .Pp
778 The
779 .Ar type
780 must be one of the following:
781 .Bl -tag -width 13n -offset indent
782 .It Fl centered
783 Produce one output line from each input line, and centre-justify each line.
784 Using this display type is not recommended; many
785 .Nm
786 implementations render it poorly.
787 .It Fl filled
788 Change the positions of line breaks to fill each line, and left- and
789 right-justify the resulting block.
790 .It Fl literal
791 Produce one output line from each input line,
792 and do not justify the block at all.
793 Preserve white space as it appears in the input.
794 Always use a constant-width font.
795 Use this for displaying source code.
796 .It Fl ragged
797 Change the positions of line breaks to fill each line, and left-justify
798 the resulting block.
799 .It Fl unfilled
800 The same as
801 .Fl literal ,
802 but using the same font as for normal text, which is a variable width font
803 if supported by the output device.
804 .El
805 .Pp
806 The
807 .Ar type
808 must be provided first.
809 Additional arguments may follow:
810 .Bl -tag -width 13n -offset indent
811 .It Fl offset Ar width
812 Indent the display by the
813 .Ar width ,
814 which may be one of the following:
815 .Bl -item
816 .It
817 One of the pre-defined strings
818 .Cm indent ,
819 the width of a standard indentation (six constant width characters);
820 .Cm indent-two ,
821 twice
822 .Cm indent ;
823 .Cm left ,
824 which has no effect;
825 .Cm right ,
826 which justifies to the right margin; or
827 .Cm center ,
828 which aligns around an imagined centre axis.
829 .It
830 A macro invocation, which selects a predefined width
831 associated with that macro.
832 The most popular is the imaginary macro
833 .Ar \&Ds ,
834 which resolves to
835 .Sy 6n .
836 .It
837 A scaling width as described in
838 .Xr roff 7 .
839 .It
840 An arbitrary string, which indents by the length of this string.
841 .El
842 .Pp
843 When the argument is missing,
844 .Fl offset
845 is ignored.
846 .It Fl compact
847 Do not assert vertical space before the display.
848 .El
849 .Pp
850 Examples:
851 .Bd -literal -offset indent
852 \&.Bd \-literal \-offset indent \-compact
853 Hello world.
854 \&.Ed
855 .Ed
856 .Pp
857 See also
858 .Sx \&D1
859 and
860 .Sx \&Dl .
861 .Ss \&Bf
862 Change the font mode for a scoped block of text.
863 Its syntax is as follows:
864 .Bd -ragged -offset indent
865 .Pf \. Sx \&Bf
866 .Oo
867 .Fl emphasis | literal | symbolic |
868 .Cm \&Em | \&Li | \&Sy
869 .Oc
870 .Ed
871 .Pp
872 The
873 .Fl emphasis
874 and
875 .Cm \&Em
876 argument are equivalent, as are
877 .Fl symbolic
878 and
879 .Cm \&Sy ,
880 and
881 .Fl literal
882 and
883 .Cm \&Li .
884 Without an argument, this macro does nothing.
885 The font mode continues until broken by a new font mode in a nested
886 scope or
887 .Sx \&Ef
888 is encountered.
889 .Pp
890 See also
891 .Sx \&Li ,
892 .Sx \&Ef ,
893 .Sx \&Em ,
894 and
895 .Sx \&Sy .
896 .Ss \&Bk
897 For each macro, keep its output together on the same output line,
898 until the end of the macro or the end of the input line is reached,
899 whichever comes first.
900 Line breaks in text lines are unaffected.
901 The syntax is as follows:
902 .Pp
903 .D1 Pf \. Sx \&Bk Fl words
904 .Pp
905 The
906 .Fl words
907 argument is required; additional arguments are ignored.
908 .Pp
909 The following example will not break within each
910 .Sx \&Op
911 macro line:
912 .Bd -literal -offset indent
913 \&.Bk \-words
914 \&.Op Fl f Ar flags
915 \&.Op Fl o Ar output
916 \&.Ek
917 .Ed
918 .Pp
919 Be careful in using over-long lines within a keep block!
920 Doing so will clobber the right margin.
921 .Ss \&Bl
922 Begin a list.
923 Lists consist of items specified using the
924 .Sx \&It
925 macro, containing a head or a body or both.
926 The list syntax is as follows:
927 .Bd -ragged -offset indent
928 .Pf \. Sx \&Bl
929 .Fl Ns Ar type
930 .Op Fl width Ar val
931 .Op Fl offset Ar val
932 .Op Fl compact
933 .Op HEAD ...
934 .Ed
935 .Pp
936 The list
937 .Ar type
938 is mandatory and must be specified first.
939 The
940 .Fl width
941 and
942 .Fl offset
943 arguments accept scaling widths as described in
944 .Xr roff 7
945 or use the length of the given string.
946 The
947 .Fl offset
948 is a global indentation for the whole list, affecting both item heads
949 and bodies.
950 For those list types supporting it, the
951 .Fl width
952 argument requests an additional indentation of item bodies,
953 to be added to the
954 .Fl offset .
955 Unless the
956 .Fl compact
957 argument is specified, list entries are separated by vertical space.
958 .Pp
959 A list must specify one of the following list types:
960 .Bl -tag -width 12n -offset indent
961 .It Fl bullet
962 No item heads can be specified, but a bullet will be printed at the head
963 of each item.
964 Item bodies start on the same output line as the bullet
965 and are indented according to the
966 .Fl width
967 argument.
968 .It Fl column
969 A columnated list.
970 The
971 .Fl width
972 argument has no effect; instead, each argument specifies the width
973 of one column, using either the scaling width syntax described in
974 .Xr roff 7
975 or the string length of the argument.
976 If the first line of the body of a
977 .Fl column
978 list is not an
979 .Sx \&It
980 macro line,
981 .Sx \&It
982 contexts spanning one input line each are implied until an
983 .Sx \&It
984 macro line is encountered, at which point items start being interpreted as
985 described in the
986 .Sx \&It
987 documentation.
988 .It Fl dash
989 Like
990 .Fl bullet ,
991 except that dashes are used in place of bullets.
992 .It Fl diag
993 Like
994 .Fl inset ,
995 except that item heads are not parsed for macro invocations.
996 Most often used in the
997 .Em DIAGNOSTICS
998 section with error constants in the item heads.
999 .It Fl enum
1000 A numbered list.
1001 No item heads can be specified.
1002 Formatted like
1003 .Fl bullet ,
1004 except that cardinal numbers are used in place of bullets,
1005 starting at 1.
1006 .It Fl hang
1007 Like
1008 .Fl tag ,
1009 except that the first lines of item bodies are not indented, but follow
1010 the item heads like in
1011 .Fl inset
1012 lists.
1013 .It Fl hyphen
1014 Synonym for
1015 .Fl dash .
1016 .It Fl inset
1017 Item bodies follow items heads on the same line, using normal inter-word
1018 spacing.
1019 Bodies are not indented, and the
1020 .Fl width
1021 argument is ignored.
1022 .It Fl item
1023 No item heads can be specified, and none are printed.
1024 Bodies are not indented, and the
1025 .Fl width
1026 argument is ignored.
1027 .It Fl ohang
1028 Item bodies start on the line following item heads and are not indented.
1029 The
1030 .Fl width
1031 argument is ignored.
1032 .It Fl tag
1033 Item bodies are indented according to the
1034 .Fl width
1035 argument.
1036 When an item head fits inside the indentation, the item body follows
1037 this head on the same output line.
1038 Otherwise, the body starts on the output line following the head.
1039 .El
1040 .Pp
1041 Lists may be nested within lists and displays.
1042 Nesting of
1043 .Fl column
1044 and
1045 .Fl enum
1046 lists may not be portable.
1047 .Pp
1048 See also
1049 .Sx \&El
1050 and
1051 .Sx \&It .
1052 .Ss \&Bo
1053 Begin a block enclosed by square brackets.
1054 Does not have any head arguments.
1055 .Pp
1056 Examples:
1057 .Bd -literal -offset indent -compact
1058 \&.Bo 1 ,
1059 \&.Dv BUFSIZ \&Bc
1060 .Ed
1061 .Pp
1062 See also
1063 .Sx \&Bq .
1064 .Ss \&Bq
1065 Encloses its arguments in square brackets.
1066 .Pp
1067 Examples:
1068 .Dl \&.Bq 1 , \&Dv BUFSIZ
1069 .Pp
1070 .Em Remarks :
1071 this macro is sometimes abused to emulate optional arguments for
1072 commands; the correct macros to use for this purpose are
1073 .Sx \&Op ,
1074 .Sx \&Oo ,
1075 and
1076 .Sx \&Oc .
1077 .Pp
1078 See also
1079 .Sx \&Bo .
1080 .Ss \&Brc
1081 Close a
1082 .Sx \&Bro
1083 block.
1084 Does not have any tail arguments.
1085 .Ss \&Bro
1086 Begin a block enclosed by curly braces.
1087 Does not have any head arguments.
1088 .Pp
1089 Examples:
1090 .Bd -literal -offset indent -compact
1091 \&.Bro 1 , ... ,
1092 \&.Va n \&Brc
1093 .Ed
1094 .Pp
1095 See also
1096 .Sx \&Brq .
1097 .Ss \&Brq
1098 Encloses its arguments in curly braces.
1099 .Pp
1100 Examples:
1101 .Dl \&.Brq 1 , ... , \&Va n
1102 .Pp
1103 See also
1104 .Sx \&Bro .
1105 .Ss \&Bsx
1106 Format the
1107 .Bsx
1108 version provided as an argument, or a default value if
1109 no argument is provided.
1110 .Pp
1111 Examples:
1112 .Dl \&.Bsx 1.0
1113 .Dl \&.Bsx
1114 .Pp
1115 See also
1116 .Sx \&At ,
1117 .Sx \&Bx ,
1118 .Sx \&Dx ,
1119 .Sx \&Fx ,
1120 .Sx \&Nx ,
1121 .Sx \&Ox ,
1122 and
1123 .Sx \&Ux .
1124 .Ss \&Bt
1125 Prints
1126 .Dq is currently in beta test.
1127 .Ss \&Bx
1128 Format the
1129 .Bx
1130 version provided as an argument, or a default value if no
1131 argument is provided.
1132 .Pp
1133 Examples:
1134 .Dl \&.Bx 4.3 Tahoe
1135 .Dl \&.Bx 4.4
1136 .Dl \&.Bx
1137 .Pp
1138 See also
1139 .Sx \&At ,
1140 .Sx \&Bsx ,
1141 .Sx \&Dx ,
1142 .Sx \&Fx ,
1143 .Sx \&Nx ,
1144 .Sx \&Ox ,
1145 and
1146 .Sx \&Ux .
1147 .Ss \&Cd
1148 Kernel configuration declaration.
1149 This denotes strings accepted by
1150 .Xr config 8 .
1151 It is most often used in section 4 manual pages.
1152 .Pp
1153 Examples:
1154 .Dl \&.Cd device le0 at scode?
1155 .Pp
1156 .Em Remarks :
1157 this macro is commonly abused by using quoted literals to retain
1158 whitespace and align consecutive
1159 .Sx \&Cd
1160 declarations.
1161 This practise is discouraged.
1162 .Ss \&Cm
1163 Command modifiers.
1164 Typically used for fixed strings passed as arguments, unless
1165 .Sx \&Fl
1166 is more appropriate.
1167 Also useful when specifying configuration options or keys.
1168 .Pp
1169 Examples:
1170 .Dl ".Nm mt Fl f Ar device Cm rewind"
1171 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1172 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1173 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1174 .Dl ".Cm LogLevel Dv DEBUG"
1175 .Ss \&D1
1176 One-line indented display.
1177 This is formatted by the default rules and is useful for simple indented
1178 statements.
1179 It is followed by a newline.
1180 .Pp
1181 Examples:
1182 .Dl \&.D1 \&Fl abcdefgh
1183 .Pp
1184 See also
1185 .Sx \&Bd
1186 and
1187 .Sx \&Dl .
1188 .Ss \&Db
1189 Switch debugging mode.
1190 Its syntax is as follows:
1191 .Pp
1192 .D1 Pf \. Sx \&Db Cm on | off
1193 .Pp
1194 This macro is ignored by
1195 .Xr mandoc 1 .
1196 .Ss \&Dc
1197 Close a
1198 .Sx \&Do
1199 block.
1200 Does not have any tail arguments.
1201 .Ss \&Dd
1202 Document date.
1203 This is the mandatory first macro of any
1204 .Nm
1205 manual.
1206 Its syntax is as follows:
1207 .Pp
1208 .D1 Pf \. Sx \&Dd Ar month day , year
1209 .Pp
1210 The
1211 .Ar month
1212 is the full English month name, the
1213 .Ar day
1214 is an optionally zero-padded numeral, and the
1215 .Ar year
1216 is the full four-digit year.
1217 .Pp
1218 Other arguments are not portable; the
1219 .Xr mandoc 1
1220 utility handles them as follows:
1221 .Bl -dash -offset 3n -compact
1222 .It
1223 To have the date automatically filled in by the
1224 .Ox
1225 version of
1226 .Xr cvs 1 ,
1227 the special string
1228 .Dq $\&Mdocdate$
1229 can be given as an argument.
1230 .It
1231 A few alternative date formats are accepted as well
1232 and converted to the standard form.
1233 .It
1234 If a date string cannot be parsed, it is used verbatim.
1235 .It
1236 If no date string is given, the current date is used.
1237 .El
1238 .Pp
1239 Examples:
1240 .Dl \&.Dd $\&Mdocdate$
1241 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1242 .Dl \&.Dd July 21, 2007
1243 .Pp
1244 See also
1245 .Sx \&Dt
1246 and
1247 .Sx \&Os .
1248 .Ss \&Dl
1249 One-line intended display.
1250 This is formatted as literal text and is useful for commands and
1251 invocations.
1252 It is followed by a newline.
1253 .Pp
1254 Examples:
1255 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1256 .Pp
1257 See also
1258 .Sx \&Bd
1259 and
1260 .Sx \&D1 .
1261 .Ss \&Do
1262 Begin a block enclosed by double quotes.
1263 Does not have any head arguments.
1264 .Pp
1265 Examples:
1266 .Bd -literal -offset indent -compact
1267 \&.Do
1268 April is the cruellest month
1269 \&.Dc
1270 \e(em T.S. Eliot
1271 .Ed
1272 .Pp
1273 See also
1274 .Sx \&Dq .
1275 .Ss \&Dq
1276 Encloses its arguments in
1277 .Dq typographic
1278 double-quotes.
1279 .Pp
1280 Examples:
1281 .Bd -literal -offset indent -compact
1282 \&.Dq April is the cruellest month
1283 \e(em T.S. Eliot
1284 .Ed
1285 .Pp
1286 See also
1287 .Sx \&Qq ,
1288 .Sx \&Sq ,
1289 and
1290 .Sx \&Do .
1291 .Ss \&Dt
1292 Document title.
1293 This is the mandatory second macro of any
1294 .Nm
1295 file.
1296 Its syntax is as follows:
1297 .Bd -ragged -offset indent
1298 .Pf \. Sx \&Dt
1299 .Oo
1300 .Ar title
1301 .Oo
1302 .Ar section
1303 .Op Ar volume
1304 .Op Ar arch
1305 .Oc
1306 .Oc
1307 .Ed
1308 .Pp
1309 Its arguments are as follows:
1310 .Bl -tag -width Ds -offset Ds
1311 .It Ar title
1312 The document's title (name), defaulting to
1313 .Dq UNKNOWN
1314 if unspecified.
1315 It should be capitalised.
1316 .It Ar section
1317 The manual section.
1318 This may be one of
1319 .Cm 1
1320 .Pq utilities ,
1321 .Cm 2
1322 .Pq system calls ,
1323 .Cm 3
1324 .Pq libraries ,
1325 .Cm 3p
1326 .Pq Perl libraries ,
1327 .Cm 4
1328 .Pq devices ,
1329 .Cm 5
1330 .Pq file formats ,
1331 .Cm 6
1332 .Pq games ,
1333 .Cm 7
1334 .Pq miscellaneous ,
1335 .Cm 8
1336 .Pq system utilities ,
1337 .Cm 9
1338 .Pq kernel functions ,
1339 .Cm X11
1340 .Pq X Window System ,
1341 .Cm X11R6
1342 .Pq X Window System ,
1343 .Cm unass
1344 .Pq unassociated ,
1345 .Cm local
1346 .Pq local system ,
1347 .Cm draft
1348 .Pq draft manual ,
1349 or
1350 .Cm paper
1351 .Pq paper .
1352 It should correspond to the manual's filename suffix and defaults to
1353 .Cm 1
1354 if unspecified.
1355 .It Ar volume
1356 This overrides the volume inferred from
1357 .Ar section .
1358 This field is optional, and if specified, must be one of
1359 .Cm USD
1360 .Pq users' supplementary documents ,
1361 .Cm PS1
1362 .Pq programmers' supplementary documents ,
1363 .Cm AMD
1364 .Pq administrators' supplementary documents ,
1365 .Cm SMM
1366 .Pq system managers' manuals ,
1367 .Cm URM
1368 .Pq users' reference manuals ,
1369 .Cm PRM
1370 .Pq programmers' reference manuals ,
1371 .Cm KM
1372 .Pq kernel manuals ,
1373 .Cm IND
1374 .Pq master index ,
1375 .Cm MMI
1376 .Pq master index ,
1377 .Cm LOCAL
1378 .Pq local manuals ,
1379 .Cm LOC
1380 .Pq local manuals ,
1381 or
1382 .Cm CON
1383 .Pq contributed manuals .
1384 .It Ar arch
1385 This specifies the machine architecture a manual page applies to,
1386 where relevant, for example
1387 .Cm alpha ,
1388 .Cm amd64 ,
1389 .Cm i386 ,
1390 or
1391 .Cm sparc64 .
1392 The list of supported architectures varies by operating system.
1393 For the full list of all architectures recognized by
1394 .Xr mandoc 1 ,
1395 see the file
1396 .Pa arch.in
1397 in the source distribution.
1398 .El
1399 .Pp
1400 Examples:
1401 .Dl \&.Dt FOO 1
1402 .Dl \&.Dt FOO 4 KM
1403 .Dl \&.Dt FOO 9 i386
1404 .Pp
1405 See also
1406 .Sx \&Dd
1407 and
1408 .Sx \&Os .
1409 .Ss \&Dv
1410 Defined variables such as preprocessor constants, constant symbols,
1411 enumeration values, and so on.
1412 .Pp
1413 Examples:
1414 .Dl \&.Dv NULL
1415 .Dl \&.Dv BUFSIZ
1416 .Dl \&.Dv STDOUT_FILENO
1417 .Pp
1418 See also
1419 .Sx \&Er
1420 and
1421 .Sx \&Ev
1422 for special-purpose constants,
1423 .Sx \&Va
1424 for variable symbols, and
1425 .Sx \&Fd
1426 for listing preprocessor variable definitions in the
1427 .Em SYNOPSIS .
1428 .Ss \&Dx
1429 Format the
1430 .Dx
1431 version provided as an argument, or a default
1432 value if no argument is provided.
1433 .Pp
1434 Examples:
1435 .Dl \&.Dx 2.4.1
1436 .Dl \&.Dx
1437 .Pp
1438 See also
1439 .Sx \&At ,
1440 .Sx \&Bsx ,
1441 .Sx \&Bx ,
1442 .Sx \&Fx ,
1443 .Sx \&Nx ,
1444 .Sx \&Ox ,
1445 and
1446 .Sx \&Ux .
1447 .Ss \&Ec
1448 Close a scope started by
1449 .Sx \&Eo .
1450 Its syntax is as follows:
1451 .Pp
1452 .D1 Pf \. Sx \&Ec Op Ar TERM
1453 .Pp
1454 The
1455 .Ar TERM
1456 argument is used as the enclosure tail, for example, specifying \e(rq
1457 will emulate
1458 .Sx \&Dc .
1459 .Ss \&Ed
1460 End a display context started by
1461 .Sx \&Bd .
1462 .Ss \&Ef
1463 End a font mode context started by
1464 .Sx \&Bf .
1465 .Ss \&Ek
1466 End a keep context started by
1467 .Sx \&Bk .
1468 .Ss \&El
1469 End a list context started by
1470 .Sx \&Bl .
1471 .Pp
1472 See also
1473 .Sx \&Bl
1474 and
1475 .Sx \&It .
1476 .Ss \&Em
1477 Denotes text that should be
1478 .Em emphasised .
1479 Note that this is a presentation term and should not be used for
1480 stylistically decorating technical terms.
1481 Depending on the output device, this is usually represented
1482 using an italic font or underlined characters.
1483 .Pp
1484 Examples:
1485 .Dl \&.Em Warnings!
1486 .Dl \&.Em Remarks :
1487 .Pp
1488 See also
1489 .Sx \&Bf ,
1490 .Sx \&Li ,
1491 .Sx \&No ,
1492 and
1493 .Sx \&Sy .
1494 .Ss \&En
1495 This macro is obsolete and not implemented in
1496 .Xr mandoc 1 .
1497 .Ss \&Eo
1498 An arbitrary enclosure.
1499 Its syntax is as follows:
1500 .Pp
1501 .D1 Pf \. Sx \&Eo Op Ar TERM
1502 .Pp
1503 The
1504 .Ar TERM
1505 argument is used as the enclosure head, for example, specifying \e(lq
1506 will emulate
1507 .Sx \&Do .
1508 .Ss \&Er
1509 Error constants for definitions of the
1510 .Va errno
1511 libc global variable.
1512 This is most often used in section 2 and 3 manual pages.
1513 .Pp
1514 Examples:
1515 .Dl \&.Er EPERM
1516 .Dl \&.Er ENOENT
1517 .Pp
1518 See also
1519 .Sx \&Dv
1520 for general constants.
1521 .Ss \&Es
1522 This macro is obsolete and not implemented.
1523 .Ss \&Ev
1524 Environmental variables such as those specified in
1525 .Xr environ 7 .
1526 .Pp
1527 Examples:
1528 .Dl \&.Ev DISPLAY
1529 .Dl \&.Ev PATH
1530 .Pp
1531 See also
1532 .Sx \&Dv
1533 for general constants.
1534 .Ss \&Ex
1535 Insert a standard sentence regarding command exit values of 0 on success
1536 and >0 on failure.
1537 This is most often used in section 1, 6, and 8 manual pages.
1538 Its syntax is as follows:
1539 .Pp
1540 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1541 .Pp
1542 If
1543 .Ar utility
1544 is not specified, the document's name set by
1545 .Sx \&Nm
1546 is used.
1547 Multiple
1548 .Ar utility
1549 arguments are treated as separate utilities.
1550 .Pp
1551 See also
1552 .Sx \&Rv .
1553 .Ss \&Fa
1554 Function argument.
1555 Its syntax is as follows:
1556 .Bd -ragged -offset indent
1557 .Pf \. Sx \&Fa
1558 .Op Cm argtype
1559 .Cm argname
1560 .Ed
1561 .Pp
1562 This may be invoked for names with or without the corresponding type.
1563 It is also used to specify the field name of a structure.
1564 Most often, the
1565 .Sx \&Fa
1566 macro is used in the
1567 .Em SYNOPSIS
1568 within
1569 .Sx \&Fo
1570 section when documenting multi-line function prototypes.
1571 If invoked with multiple arguments, the arguments are separated by a
1572 comma.
1573 Furthermore, if the following macro is another
1574 .Sx \&Fa ,
1575 the last argument will also have a trailing comma.
1576 .Pp
1577 Examples:
1578 .Dl \&.Fa \(dqconst char *p\(dq
1579 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1580 .Dl \&.Fa foo
1581 .Pp
1582 See also
1583 .Sx \&Fo .
1584 .Ss \&Fc
1585 End a function context started by
1586 .Sx \&Fo .
1587 .Ss \&Fd
1588 Preprocessor directive, in particular for listing it in the
1589 .Em SYNOPSIS .
1590 Historically, it was also used to document include files.
1591 The latter usage has been deprecated in favour of
1592 .Sx \&In .
1593 .Pp
1594 Its syntax is as follows:
1595 .Bd -ragged -offset indent
1596 .Pf \. Sx \&Fd
1597 .Li # Ns Ar directive
1598 .Op Ar argument ...
1599 .Ed
1600 .Pp
1601 Examples:
1602 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1603 .Dl \&.Fd #define SIO_MAXNFDS
1604 .Dl \&.Fd #ifdef FS_DEBUG
1605 .Dl \&.Ft void
1606 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1607 .Dl \&.Fd #endif
1608 .Pp
1609 See also
1610 .Sx MANUAL STRUCTURE ,
1611 .Sx \&In ,
1612 and
1613 .Sx \&Dv .
1614 .Ss \&Fl
1615 Command-line flag or option.
1616 Used when listing arguments to command-line utilities.
1617 Prints a fixed-width hyphen
1618 .Sq \-
1619 directly followed by each argument.
1620 If no arguments are provided, a hyphen is printed followed by a space.
1621 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1622 output.
1623 .Pp
1624 Examples:
1625 .Dl ".Fl R Op Fl H | L | P"
1626 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1627 .Dl ".Fl type Cm d Fl name Pa CVS"
1628 .Dl ".Fl Ar signal_number"
1629 .Dl ".Fl o Fl"
1630 .Pp
1631 See also
1632 .Sx \&Cm .
1633 .Ss \&Fn
1634 A function name.
1635 Its syntax is as follows:
1636 .Bd -ragged -offset indent
1637 .Pf \. Ns Sx \&Fn
1638 .Op Ar functype
1639 .Ar funcname
1640 .Op Oo Ar argtype Oc Ar argname
1641 .Ed
1642 .Pp
1643 Function arguments are surrounded in parenthesis and
1644 are delimited by commas.
1645 If no arguments are specified, blank parenthesis are output.
1646 In the
1647 .Em SYNOPSIS
1648 section, this macro starts a new output line,
1649 and a blank line is automatically inserted between function definitions.
1650 .Pp
1651 Examples:
1652 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1653 .Dl \&.Fn funcname \(dqint arg0\(dq
1654 .Dl \&.Fn funcname arg0
1655 .Pp
1656 .Bd -literal -offset indent -compact
1657 \&.Ft functype
1658 \&.Fn funcname
1659 .Ed
1660 .Pp
1661 When referring to a function documented in another manual page, use
1662 .Sx \&Xr
1663 instead.
1664 See also
1665 .Sx MANUAL STRUCTURE ,
1666 .Sx \&Fo ,
1667 and
1668 .Sx \&Ft .
1669 .Ss \&Fo
1670 Begin a function block.
1671 This is a multi-line version of
1672 .Sx \&Fn .
1673 Its syntax is as follows:
1674 .Pp
1675 .D1 Pf \. Sx \&Fo Ar funcname
1676 .Pp
1677 Invocations usually occur in the following context:
1678 .Bd -ragged -offset indent
1679 .Pf \. Sx \&Ft Ar functype
1680 .br
1681 .Pf \. Sx \&Fo Ar funcname
1682 .br
1683 .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
1684 .br
1685 \&.\.\.
1686 .br
1687 .Pf \. Sx \&Fc
1688 .Ed
1689 .Pp
1690 A
1691 .Sx \&Fo
1692 scope is closed by
1693 .Sx \&Fc .
1694 .Pp
1695 See also
1696 .Sx MANUAL STRUCTURE ,
1697 .Sx \&Fa ,
1698 .Sx \&Fc ,
1699 and
1700 .Sx \&Ft .
1701 .Ss \&Fr
1702 This macro is obsolete and not implemented in
1703 .Xr mandoc 1 .
1704 .Pp
1705 It was used to show function return values.
1706 The syntax was:
1707 .Pp
1708 .Dl Pf . Sx \&Fr Ar value
1709 .Ss \&Ft
1710 A function type.
1711 Its syntax is as follows:
1712 .Pp
1713 .D1 Pf \. Sx \&Ft Ar functype
1714 .Pp
1715 In the
1716 .Em SYNOPSIS
1717 section, a new output line is started after this macro.
1718 .Pp
1719 Examples:
1720 .Dl \&.Ft int
1721 .Bd -literal -offset indent -compact
1722 \&.Ft functype
1723 \&.Fn funcname
1724 .Ed
1725 .Pp
1726 See also
1727 .Sx MANUAL STRUCTURE ,
1728 .Sx \&Fn ,
1729 and
1730 .Sx \&Fo .
1731 .Ss \&Fx
1732 Format the
1733 .Fx
1734 version provided as an argument, or a default value
1735 if no argument is provided.
1736 .Pp
1737 Examples:
1738 .Dl \&.Fx 7.1
1739 .Dl \&.Fx
1740 .Pp
1741 See also
1742 .Sx \&At ,
1743 .Sx \&Bsx ,
1744 .Sx \&Bx ,
1745 .Sx \&Dx ,
1746 .Sx \&Nx ,
1747 .Sx \&Ox ,
1748 and
1749 .Sx \&Ux .
1750 .Ss \&Hf
1751 This macro is not implemented in
1752 .Xr mandoc 1 .
1753 .Pp
1754 It was used to include the contents of a (header) file literally.
1755 The syntax was:
1756 .Pp
1757 .Dl Pf . Sx \&Hf Ar filename
1758 .Ss \&Ic
1759 Designate an internal or interactive command.
1760 This is similar to
1761 .Sx \&Cm
1762 but used for instructions rather than values.
1763 .Pp
1764 Examples:
1765 .Dl \&.Ic :wq
1766 .Dl \&.Ic hash
1767 .Dl \&.Ic alias
1768 .Pp
1769 Note that using
1770 .Sx \&Bd Fl literal
1771 or
1772 .Sx \&D1
1773 is preferred for displaying code; the
1774 .Sx \&Ic
1775 macro is used when referring to specific instructions.
1776 .Ss \&In
1777 An
1778 .Dq include
1779 file.
1780 When invoked as the first macro on an input line in the
1781 .Em SYNOPSIS
1782 section, the argument is displayed in angle brackets
1783 and preceded by
1784 .Dq #include ,
1785 and a blank line is inserted in front if there is a preceding
1786 function declaration.
1787 This is most often used in section 2, 3, and 9 manual pages.
1788 .Pp
1789 Examples:
1790 .Dl \&.In sys/types.h
1791 .Pp
1792 See also
1793 .Sx MANUAL STRUCTURE .
1794 .Ss \&It
1795 A list item.
1796 The syntax of this macro depends on the list type.
1797 .Pp
1798 Lists
1799 of type
1800 .Fl hang ,
1801 .Fl ohang ,
1802 .Fl inset ,
1803 and
1804 .Fl diag
1805 have the following syntax:
1806 .Pp
1807 .D1 Pf \. Sx \&It Ar args
1808 .Pp
1809 Lists of type
1810 .Fl bullet ,
1811 .Fl dash ,
1812 .Fl enum ,
1813 .Fl hyphen
1814 and
1815 .Fl item
1816 have the following syntax:
1817 .Pp
1818 .D1 Pf \. Sx \&It
1819 .Pp
1820 with subsequent lines interpreted within the scope of the
1821 .Sx \&It
1822 until either a closing
1823 .Sx \&El
1824 or another
1825 .Sx \&It .
1826 .Pp
1827 The
1828 .Fl tag
1829 list has the following syntax:
1830 .Pp
1831 .D1 Pf \. Sx \&It Op Cm args
1832 .Pp
1833 Subsequent lines are interpreted as with
1834 .Fl bullet
1835 and family.
1836 The line arguments correspond to the list's left-hand side; body
1837 arguments correspond to the list's contents.
1838 .Pp
1839 The
1840 .Fl column
1841 list is the most complicated.
1842 Its syntax is as follows:
1843 .Pp
1844 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1845 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1846 .Pp
1847 The arguments consist of one or more lines of text and macros
1848 representing a complete table line.
1849 Cells within the line are delimited by tabs or by the special
1850 .Sx \&Ta
1851 block macro.
1852 The tab cell delimiter may only be used within the
1853 .Sx \&It
1854 line itself; on following lines, only the
1855 .Sx \&Ta
1856 macro can be used to delimit cells, and
1857 .Sx \&Ta
1858 is only recognised as a macro when called by other macros,
1859 not as the first macro on a line.
1860 .Pp
1861 Note that quoted strings may span tab-delimited cells on an
1862 .Sx \&It
1863 line.
1864 For example,
1865 .Pp
1866 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
1867 .Pp
1868 will preserve the semicolon whitespace except for the last.
1869 .Pp
1870 See also
1871 .Sx \&Bl .
1872 .Ss \&Lb
1873 Specify a library.
1874 The syntax is as follows:
1875 .Pp
1876 .D1 Pf \. Sx \&Lb Ar library
1877 .Pp
1878 The
1879 .Ar library
1880 parameter may be a system library, such as
1881 .Cm libz
1882 or
1883 .Cm libpam ,
1884 in which case a small library description is printed next to the linker
1885 invocation; or a custom library, in which case the library name is
1886 printed in quotes.
1887 This is most commonly used in the
1888 .Em SYNOPSIS
1889 section as described in
1890 .Sx MANUAL STRUCTURE .
1891 .Pp
1892 Examples:
1893 .Dl \&.Lb libz
1894 .Dl \&.Lb libmandoc
1895 .Ss \&Li
1896 Denotes text that should be in a
1897 .Li literal
1898 font mode.
1899 Note that this is a presentation term and should not be used for
1900 stylistically decorating technical terms.
1901 .Pp
1902 On terminal output devices, this is often indistinguishable from
1903 normal text.
1904 .Pp
1905 See also
1906 .Sx \&Bf ,
1907 .Sx \&Em ,
1908 .Sx \&No ,
1909 and
1910 .Sx \&Sy .
1911 .Ss \&Lk
1912 Format a hyperlink.
1913 Its syntax is as follows:
1914 .Pp
1915 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1916 .Pp
1917 Examples:
1918 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
1919 .Dl \&.Lk http://bsd.lv
1920 .Pp
1921 See also
1922 .Sx \&Mt .
1923 .Ss \&Lp
1924 Synonym for
1925 .Sx \&Pp .
1926 .Ss \&Ms
1927 Display a mathematical symbol.
1928 Its syntax is as follows:
1929 .Pp
1930 .D1 Pf \. Sx \&Ms Ar symbol
1931 .Pp
1932 Examples:
1933 .Dl \&.Ms sigma
1934 .Dl \&.Ms aleph
1935 .Ss \&Mt
1936 Format a
1937 .Dq mailto:
1938 hyperlink.
1939 Its syntax is as follows:
1940 .Pp
1941 .D1 Pf \. Sx \&Mt Ar address
1942 .Pp
1943 Examples:
1944 .Dl \&.Mt discuss@manpages.bsd.lv
1945 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
1946 .Ss \&Nd
1947 A one line description of the manual's content.
1948 This may only be invoked in the
1949 .Em SYNOPSIS
1950 section subsequent the
1951 .Sx \&Nm
1952 macro.
1953 .Pp
1954 Examples:
1955 .Dl Pf . Sx \&Nd mdoc language reference
1956 .Dl Pf . Sx \&Nd format and display UNIX manuals
1957 .Pp
1958 The
1959 .Sx \&Nd
1960 macro technically accepts child macros and terminates with a subsequent
1961 .Sx \&Sh
1962 invocation.
1963 Do not assume this behaviour: some
1964 .Xr whatis 1
1965 database generators are not smart enough to parse more than the line
1966 arguments and will display macros verbatim.
1967 .Pp
1968 See also
1969 .Sx \&Nm .
1970 .Ss \&Nm
1971 The name of the manual page, or \(em in particular in section 1, 6,
1972 and 8 pages \(em of an additional command or feature documented in
1973 the manual page.
1974 When first invoked, the
1975 .Sx \&Nm
1976 macro expects a single argument, the name of the manual page.
1977 Usually, the first invocation happens in the
1978 .Em NAME
1979 section of the page.
1980 The specified name will be remembered and used whenever the macro is
1981 called again without arguments later in the page.
1982 The
1983 .Sx \&Nm
1984 macro uses
1985 .Sx Block full-implicit
1986 semantics when invoked as the first macro on an input line in the
1987 .Em SYNOPSIS
1988 section; otherwise, it uses ordinary
1989 .Sx In-line
1990 semantics.
1991 .Pp
1992 Examples:
1993 .Bd -literal -offset indent
1994 \&.Sh SYNOPSIS
1995 \&.Nm cat
1996 \&.Op Fl benstuv
1997 \&.Op Ar
1998 .Ed
1999 .Pp
2000 In the
2001 .Em SYNOPSIS
2002 of section 2, 3 and 9 manual pages, use the
2003 .Sx \&Fn
2004 macro rather than
2005 .Sx \&Nm
2006 to mark up the name of the manual page.
2007 .Ss \&No
2008 Normal text.
2009 Closes the scope of any preceding in-line macro.
2010 When used after physical formatting macros like
2011 .Sx \&Em
2012 or
2013 .Sx \&Sy ,
2014 switches back to the standard font face and weight.
2015 Can also be used to embed plain text strings in macro lines
2016 using semantic annotation macros.
2017 .Pp
2018 Examples:
2019 .Dl ".Em italic , Sy bold , No and roman"
2020 .Pp
2021 .Bd -literal -offset indent -compact
2022 \&.Sm off
2023 \&.Cm :C No / Ar pattern No / Ar replacement No /
2024 \&.Sm on
2025 .Ed
2026 .Pp
2027 See also
2028 .Sx \&Em ,
2029 .Sx \&Li ,
2030 and
2031 .Sx \&Sy .
2032 .Ss \&Ns
2033 Suppress a space between the output of the preceding macro
2034 and the following text or macro.
2035 Following invocation, input is interpreted as normal text
2036 just like after an
2037 .Sx \&No
2038 macro.
2039 .Pp
2040 This has no effect when invoked at the start of a macro line.
2041 .Pp
2042 Examples:
2043 .Dl ".Ar name Ns = Ns Ar value"
2044 .Dl ".Cm :M Ns Ar pattern"
2045 .Dl ".Fl o Ns Ar output"
2046 .Pp
2047 See also
2048 .Sx \&No
2049 and
2050 .Sx \&Sm .
2051 .Ss \&Nx
2052 Format the
2053 .Nx
2054 version provided as an argument, or a default value if
2055 no argument is provided.
2056 .Pp
2057 Examples:
2058 .Dl \&.Nx 5.01
2059 .Dl \&.Nx
2060 .Pp
2061 See also
2062 .Sx \&At ,
2063 .Sx \&Bsx ,
2064 .Sx \&Bx ,
2065 .Sx \&Dx ,
2066 .Sx \&Fx ,
2067 .Sx \&Ox ,
2068 and
2069 .Sx \&Ux .
2070 .Ss \&Oc
2071 Close multi-line
2072 .Sx \&Oo
2073 context.
2074 .Ss \&Oo
2075 Multi-line version of
2076 .Sx \&Op .
2077 .Pp
2078 Examples:
2079 .Bd -literal -offset indent -compact
2080 \&.Oo
2081 \&.Op Fl flag Ns Ar value
2082 \&.Oc
2083 .Ed
2084 .Ss \&Op
2085 Optional part of a command line.
2086 Prints the argument(s) in brackets.
2087 This is most often used in the
2088 .Em SYNOPSIS
2089 section of section 1 and 8 manual pages.
2090 .Pp
2091 Examples:
2092 .Dl \&.Op \&Fl a \&Ar b
2093 .Dl \&.Op \&Ar a | b
2094 .Pp
2095 See also
2096 .Sx \&Oo .
2097 .Ss \&Os
2098 Document operating system version.
2099 This is the mandatory third macro of
2100 any
2101 .Nm
2102 file.
2103 Its syntax is as follows:
2104 .Pp
2105 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2106 .Pp
2107 The optional
2108 .Ar system
2109 parameter specifies the relevant operating system or environment.
2110 Left unspecified, it defaults to the local operating system version.
2111 This is the suggested form.
2112 .Pp
2113 Examples:
2114 .Dl \&.Os
2115 .Dl \&.Os KTH/CSC/TCS
2116 .Dl \&.Os BSD 4.3
2117 .Pp
2118 See also
2119 .Sx \&Dd
2120 and
2121 .Sx \&Dt .
2122 .Ss \&Ot
2123 This macro is obsolete and not implemented in
2124 .Xr mandoc 1 .
2125 .Pp
2126 Historical
2127 .Nm
2128 packages described it as
2129 .Dq "old function type (FORTRAN)" .
2130 .Ss \&Ox
2131 Format the
2132 .Ox
2133 version provided as an argument, or a default value
2134 if no argument is provided.
2135 .Pp
2136 Examples:
2137 .Dl \&.Ox 4.5
2138 .Dl \&.Ox
2139 .Pp
2140 See also
2141 .Sx \&At ,
2142 .Sx \&Bsx ,
2143 .Sx \&Bx ,
2144 .Sx \&Dx ,
2145 .Sx \&Fx ,
2146 .Sx \&Nx ,
2147 and
2148 .Sx \&Ux .
2149 .Ss \&Pa
2150 An absolute or relative file system path, or a file or directory name.
2151 If an argument is not provided, the character
2152 .Sq \(ti
2153 is used as a default.
2154 .Pp
2155 Examples:
2156 .Dl \&.Pa /usr/bin/mandoc
2157 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2158 .Pp
2159 See also
2160 .Sx \&Lk .
2161 .Ss \&Pc
2162 Close parenthesised context opened by
2163 .Sx \&Po .
2164 .Ss \&Pf
2165 Removes the space between its argument
2166 .Pq Dq prefix
2167 and the following macro.
2168 Its syntax is as follows:
2169 .Pp
2170 .D1 .Pf Ar prefix macro arguments ...
2171 .Pp
2172 This is equivalent to:
2173 .Pp
2174 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2175 .Pp
2176 Examples:
2177 .Dl ".Pf $ Ar variable_name"
2178 .Dl ".Pf 0x Ar hex_digits"
2179 .Pp
2180 See also
2181 .Sx \&Ns
2182 and
2183 .Sx \&Sm .
2184 .Ss \&Po
2185 Multi-line version of
2186 .Sx \&Pq .
2187 .Ss \&Pp
2188 Break a paragraph.
2189 This will assert vertical space between prior and subsequent macros
2190 and/or text.
2191 .Pp
2192 Paragraph breaks are not needed before or after
2193 .Sx \&Sh
2194 or
2195 .Sx \&Ss
2196 macros or before displays
2197 .Pq Sx \&Bd
2198 or lists
2199 .Pq Sx \&Bl
2200 unless the
2201 .Fl compact
2202 flag is given.
2203 .Ss \&Pq
2204 Parenthesised enclosure.
2205 .Pp
2206 See also
2207 .Sx \&Po .
2208 .Ss \&Qc
2209 Close quoted context opened by
2210 .Sx \&Qo .
2211 .Ss \&Ql
2212 Format a single-quoted literal.
2213 See also
2214 .Sx \&Qq
2215 and
2216 .Sx \&Sq .
2217 .Ss \&Qo
2218 Multi-line version of
2219 .Sx \&Qq .
2220 .Ss \&Qq
2221 Encloses its arguments in
2222 .Qq typewriter
2223 double-quotes.
2224 Consider using
2225 .Sx \&Dq .
2226 .Pp
2227 See also
2228 .Sx \&Dq ,
2229 .Sx \&Sq ,
2230 and
2231 .Sx \&Qo .
2232 .Ss \&Re
2233 Close an
2234 .Sx \&Rs
2235 block.
2236 Does not have any tail arguments.
2237 .Ss \&Rs
2238 Begin a bibliographic
2239 .Pq Dq reference
2240 block.
2241 Does not have any head arguments.
2242 The block macro may only contain
2243 .Sx \&%A ,
2244 .Sx \&%B ,
2245 .Sx \&%C ,
2246 .Sx \&%D ,
2247 .Sx \&%I ,
2248 .Sx \&%J ,
2249 .Sx \&%N ,
2250 .Sx \&%O ,
2251 .Sx \&%P ,
2252 .Sx \&%Q ,
2253 .Sx \&%R ,
2254 .Sx \&%T ,
2255 .Sx \&%U ,
2256 and
2257 .Sx \&%V
2258 child macros (at least one must be specified).
2259 .Pp
2260 Examples:
2261 .Bd -literal -offset indent -compact
2262 \&.Rs
2263 \&.%A J. E. Hopcroft
2264 \&.%A J. D. Ullman
2265 \&.%B Introduction to Automata Theory, Languages, and Computation
2266 \&.%I Addison-Wesley
2267 \&.%C Reading, Massachusettes
2268 \&.%D 1979
2269 \&.Re
2270 .Ed
2271 .Pp
2272 If an
2273 .Sx \&Rs
2274 block is used within a SEE ALSO section, a vertical space is asserted
2275 before the rendered output, else the block continues on the current
2276 line.
2277 .Ss \&Rv
2278 Insert a standard sentence regarding a function call's return value of 0
2279 on success and \-1 on error, with the
2280 .Va errno
2281 libc global variable set on error.
2282 Its syntax is as follows:
2283 .Pp
2284 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2285 .Pp
2286 If
2287 .Ar function
2288 is not specified, the document's name set by
2289 .Sx \&Nm
2290 is used.
2291 Multiple
2292 .Ar function
2293 arguments are treated as separate functions.
2294 .Pp
2295 See also
2296 .Sx \&Ex .
2297 .Ss \&Sc
2298 Close single-quoted context opened by
2299 .Sx \&So .
2300 .Ss \&Sh
2301 Begin a new section.
2302 For a list of conventional manual sections, see
2303 .Sx MANUAL STRUCTURE .
2304 These sections should be used unless it's absolutely necessary that
2305 custom sections be used.
2306 .Pp
2307 Section names should be unique so that they may be keyed by
2308 .Sx \&Sx .
2309 Although this macro is parsed, it should not consist of child node or it
2310 may not be linked with
2311 .Sx \&Sx .
2312 .Pp
2313 See also
2314 .Sx \&Pp ,
2315 .Sx \&Ss ,
2316 and
2317 .Sx \&Sx .
2318 .Ss \&Sm
2319 Switches the spacing mode for output generated from macros.
2320 Its syntax is as follows:
2321 .Pp
2322 .D1 Pf \. Sx \&Sm Cm on | off
2323 .Pp
2324 By default, spacing is
2325 .Cm on .
2326 When switched
2327 .Cm off ,
2328 no white space is inserted between macro arguments and between the
2329 output generated from adjacent macros, but text lines
2330 still get normal spacing between words and sentences.
2331 .Ss \&So
2332 Multi-line version of
2333 .Sx \&Sq .
2334 .Ss \&Sq
2335 Encloses its arguments in
2336 .Sq typewriter
2337 single-quotes.
2338 .Pp
2339 See also
2340 .Sx \&Dq ,
2341 .Sx \&Qq ,
2342 and
2343 .Sx \&So .
2344 .Ss \&Ss
2345 Begin a new subsection.
2346 Unlike with
2347 .Sx \&Sh ,
2348 there is no convention for the naming of subsections.
2349 Except
2350 .Em DESCRIPTION ,
2351 the conventional sections described in
2352 .Sx MANUAL STRUCTURE
2353 rarely have subsections.
2354 .Pp
2355 Sub-section names should be unique so that they may be keyed by
2356 .Sx \&Sx .
2357 Although this macro is parsed, it should not consist of child node or it
2358 may not be linked with
2359 .Sx \&Sx .
2360 .Pp
2361 See also
2362 .Sx \&Pp ,
2363 .Sx \&Sh ,
2364 and
2365 .Sx \&Sx .
2366 .Ss \&St
2367 Replace an abbreviation for a standard with the full form.
2368 The following standards are recognised.
2369 Where multiple lines are given without a blank line in between,
2370 they all refer to the same standard, and using the first form
2371 is recommended.
2372 .Bl -tag -width 1n
2373 .It C language standards
2374 .Pp
2375 .Bl -tag -width "-p1003.1g-2000" -compact
2376 .It \-ansiC
2377 .St -ansiC
2378 .It \-ansiC-89
2379 .St -ansiC-89
2380 .It \-isoC
2381 .St -isoC
2382 .It \-isoC-90
2383 .St -isoC-90
2384 .br
2385 The original C standard.
2386 .Pp
2387 .It \-isoC-amd1
2388 .St -isoC-amd1
2389 .Pp
2390 .It \-isoC-tcor1
2391 .St -isoC-tcor1
2392 .Pp
2393 .It \-isoC-tcor2
2394 .St -isoC-tcor2
2395 .Pp
2396 .It \-isoC-99
2397 .St -isoC-99
2398 .It \-ansiC-99
2399 .St -ansiC-99
2400 .br
2401 The second major version of the C language standard.
2402 .Pp
2403 .It \-isoC-2011
2404 .St -isoC-2011
2405 .br
2406 The third major version of the C language standard.
2407 .El
2408 .It POSIX.1 before the Single UNIX Specification
2409 .Pp
2410 .Bl -tag -width "-p1003.1g-2000" -compact
2411 .It \-p1003.1-88
2412 .St -p1003.1-88
2413 .It \-p1003.1
2414 .St -p1003.1
2415 .br
2416 The original POSIX standard, based on ANSI C.
2417 .Pp
2418 .It \-p1003.1-90
2419 .St -p1003.1-90
2420 .It \-iso9945-1-90
2421 .St -iso9945-1-90
2422 .br
2423 The first update of POSIX.1.
2424 .Pp
2425 .It \-p1003.1b-93
2426 .St -p1003.1b-93
2427 .It \-p1003.1b
2428 .St -p1003.1b
2429 .br
2430 Real-time extensions.
2431 .Pp
2432 .It \-p1003.1c-95
2433 .St -p1003.1c-95
2434 .br
2435 POSIX thread interfaces.
2436 .Pp
2437 .It \-p1003.1i-95
2438 .St -p1003.1i-95
2439 .br
2440 Technical Corrigendum.
2441 .Pp
2442 .It \-p1003.1-96
2443 .St -p1003.1-96
2444 .It \-iso9945-1-96
2445 .St -iso9945-1-96
2446 .br
2447 Includes POSIX.1-1990, 1b, 1c, and 1i.
2448 .El
2449 .It X/Open Portability Guide version 4 and related standards
2450 .Pp
2451 .Bl -tag -width "-p1003.1g-2000" -compact
2452 .It \-xpg3
2453 .St -xpg3
2454 .br
2455 An XPG4 precursor, published in 1989.
2456 .Pp
2457 .It \-p1003.2
2458 .St -p1003.2
2459 .It \-p1003.2-92
2460 .St -p1003.2-92
2461 .It \-iso9945-2-93
2462 .St -iso9945-2-93
2463 .br
2464 An XCU4 precursor.
2465 .Pp
2466 .It \-p1003.2a-92
2467 .St -p1003.2a-92
2468 .br
2469 Updates to POSIX.2.
2470 .Pp
2471 .It \-xpg4
2472 .St -xpg4
2473 .br
2474 Based on POSIX.1 and POSIX.2, published in 1992.
2475 .El
2476 .It Single UNIX Specification version 1 and related standards
2477 .Pp
2478 .Bl -tag -width "-p1003.1g-2000" -compact
2479 .It \-xpg4.2
2480 .St -xpg4.2
2481 .br
2482 This standard was published in 1994 and is also called SUSv1.
2483 It was used as the basis for UNIX 95 certification.
2484 The following three refer to parts of it.
2485 .Pp
2486 .It \-xsh4.2
2487 .St -xsh4.2
2488 .Pp
2489 .It \-xcurses4.2
2490 .St -xcurses4.2
2491 .Pp
2492 .It \-p1003.1g-2000
2493 .St -p1003.1g-2000
2494 .br
2495 Networking APIs, including sockets.
2496 .Pp
2497 .It \-xpg4.3
2498 .St -xpg4.3
2499 .Pp
2500 .It \-svid4
2501 .St -svid4 ,
2502 .br
2503 Published in 1995.
2504 .El
2505 .It Single UNIX Specification version 2 and related standards
2506 .Pp
2507 .Bl -tag -width "-p1003.1g-2000" -compact
2508 .It \-susv2
2509 .St -susv2
2510 This Standard was published in 1997
2511 and is also called X/Open Portability Guide version 5.
2512 It was used as the basis for UNIX 98 certification.
2513 The following refer to parts of it.
2514 .Pp
2515 .It \-xbd5
2516 .St -xbd5
2517 .Pp
2518 .It \-xsh5
2519 .St -xsh5
2520 .Pp
2521 .It \-xcu5
2522 .St -xcu5
2523 .Pp
2524 .It \-xns5
2525 .St -xns5
2526 .It \-xns5.2d2.0
2527 .St -xns5.2d2.0
2528 .It \-xns5.2
2529 .St -xns5.2
2530 .Pp
2531 .It \-p1387.2
2532 .St -p1387.2
2533 .It \-p1387.2-95
2534 .St -p1387.2-95
2535 .br
2536 POSIX software administration.
2537 .El
2538 .It Single UNIX Specification version 3 and related standards
2539 .Pp
2540 .Bl -tag -width "-p1003.1g-2000X" -compact
2541 .It \-p1003.1d-99
2542 .St -p1003.1d-99
2543 .br
2544 Additional real-time extensions.
2545 .Pp
2546 .It \-p1003.1j-2000
2547 .St -p1003.1j-2000
2548 .br
2549 Advanced real-time extensions.
2550 .Pp
2551 .It \-p1003.1q-2000
2552 .St -p1003.1q-2000
2553 .br
2554 Amendment 7: Tracing [C Language].
2555 .Pp
2556 .It \-p1003.1-2001
2557 .St -p1003.1-2001
2558 .It \-susv3
2559 .St -susv3
2560 .br
2561 This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2562 It is also called X/Open Portability Guide version 6.
2563 It is used as the basis for UNIX 03 certification.
2564 .Pp
2565 .It \-p1003.1-2004
2566 .St -p1003.1-2004
2567 .br
2568 The second and last Technical Corrigendum.
2569 .El
2570 .It Single UNIX Specification version 4
2571 .Pp
2572 .Bl -tag -width "-p1003.1g-2000" -compact
2573 .It \-p1003.1-2008
2574 .St -p1003.1-2008
2575 .br
2576 This standard is also called SUSv4 and
2577 X/Open Portability Guide version 7.
2578 .Pp
2579 .It \-p1003.1-2013
2580 .St -p1003.1-2013
2581 .br
2582 This is the first Technical Corrigendum.
2583 .El
2584 .It Other standards
2585 .Pp
2586 .Bl -tag -width "-p1003.1g-2000" -compact
2587 .It \-ieee754
2588 .St -ieee754
2589 .br
2590 Floating-point arithmetic.
2591 .Pp
2592 .It \-iso8601
2593 .St -iso8601
2594 .br
2595 Representation of dates and times, published in 1988.
2596 .Pp
2597 .It \-iso8802-3
2598 .St -iso8802-3
2599 .br
2600 Ethernet local area networks.
2601 .Pp
2602 .It \-ieee1275-94
2603 .St -ieee1275-94
2604 .El
2605 .El
2606 .Ss \&Sx
2607 Reference a section or subsection in the same manual page.
2608 The referenced section or subsection name must be identical to the
2609 enclosed argument, including whitespace.
2610 .Pp
2611 Examples:
2612 .Dl \&.Sx MANUAL STRUCTURE
2613 .Pp
2614 See also
2615 .Sx \&Sh
2616 and
2617 .Sx \&Ss .
2618 .Ss \&Sy
2619 Format enclosed arguments in symbolic
2620 .Pq Dq boldface .
2621 Note that this is a presentation term and should not be used for
2622 stylistically decorating technical terms.
2623 .Pp
2624 See also
2625 .Sx \&Bf ,
2626 .Sx \&Em ,
2627 .Sx \&Li ,
2628 and
2629 .Sx \&No .
2630 .Ss \&Ta
2631 Table cell separator in
2632 .Sx \&Bl Fl column
2633 lists; can only be used below
2634 .Sx \&It .
2635 .Ss \&Tn
2636 Format a tradename.
2637 .Pp
2638 Since this macro is often implemented to use a small caps font,
2639 it has historically been used for acronyms (like ASCII) as well.
2640 Such usage is not recommended because it would use the same macro
2641 sometimes for semantical annotation, sometimes for physical formatting.
2642 .Pp
2643 Examples:
2644 .Dl \&.Tn IBM
2645 .Ss \&Ud
2646 Prints out
2647 .Dq currently under development.
2648 .Ss \&Ux
2649 Format the
2650 .Ux
2651 name.
2652 Accepts no argument.
2653 .Pp
2654 Examples:
2655 .Dl \&.Ux
2656 .Pp
2657 See also
2658 .Sx \&At ,
2659 .Sx \&Bsx ,
2660 .Sx \&Bx ,
2661 .Sx \&Dx ,
2662 .Sx \&Fx ,
2663 .Sx \&Nx ,
2664 and
2665 .Sx \&Ox .
2666 .Ss \&Va
2667 A variable name.
2668 .Pp
2669 Examples:
2670 .Dl \&.Va foo
2671 .Dl \&.Va const char *bar ;
2672 .Ss \&Vt
2673 A variable type.
2674 This is also used for indicating global variables in the
2675 .Em SYNOPSIS
2676 section, in which case a variable name is also specified.
2677 Note that it accepts
2678 .Sx Block partial-implicit
2679 syntax when invoked as the first macro on an input line in the
2680 .Em SYNOPSIS
2681 section, else it accepts ordinary
2682 .Sx In-line
2683 syntax.
2684 In the former case, this macro starts a new output line,
2685 and a blank line is inserted in front if there is a preceding
2686 function definition or include directive.
2687 .Pp
2688 Note that this should not be confused with
2689 .Sx \&Ft ,
2690 which is used for function return types.
2691 .Pp
2692 Examples:
2693 .Dl \&.Vt unsigned char
2694 .Dl \&.Vt extern const char * const sys_signame[] \&;
2695 .Pp
2696 See also
2697 .Sx MANUAL STRUCTURE
2698 and
2699 .Sx \&Va .
2700 .Ss \&Xc
2701 Close a scope opened by
2702 .Sx \&Xo .
2703 .Ss \&Xo
2704 Extend the header of an
2705 .Sx \&It
2706 macro or the body of a partial-implicit block macro
2707 beyond the end of the input line.
2708 This macro originally existed to work around the 9-argument limit
2709 of historic
2710 .Xr roff 7 .
2711 .Ss \&Xr
2712 Link to another manual
2713 .Pq Qq cross-reference .
2714 Its syntax is as follows:
2715 .Pp
2716 .D1 Pf \. Sx \&Xr Ar name Op section
2717 .Pp
2718 Cross reference the
2719 .Ar name
2720 and
2721 .Ar section
2722 number of another man page;
2723 omitting the section number is rarely useful.
2724 .Pp
2725 Examples:
2726 .Dl \&.Xr mandoc 1
2727 .Dl \&.Xr mandoc 1 \&;
2728 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2729 .Ss \&br
2730 Emits a line-break.
2731 This macro should not be used; it is implemented for compatibility with
2732 historical manuals.
2733 .Pp
2734 Consider using
2735 .Sx \&Pp
2736 in the event of natural paragraph breaks.
2737 .Ss \&sp
2738 Emits vertical space.
2739 This macro should not be used; it is implemented for compatibility with
2740 historical manuals.
2741 Its syntax is as follows:
2742 .Pp
2743 .D1 Pf \. Sx \&sp Op Ar height
2744 .Pp
2745 The
2746 .Ar height
2747 argument is a scaling width as described in
2748 .Xr roff 7 .
2749 If unspecified,
2750 .Sx \&sp
2751 asserts a single vertical space.
2752 .Sh MACRO SYNTAX
2753 The syntax of a macro depends on its classification.
2754 In this section,
2755 .Sq \-arg
2756 refers to macro arguments, which may be followed by zero or more
2757 .Sq parm
2758 parameters;
2759 .Sq \&Yo
2760 opens the scope of a macro; and if specified,
2761 .Sq \&Yc
2762 closes it out.
2763 .Pp
2764 The
2765 .Em Callable
2766 column indicates that the macro may also be called by passing its name
2767 as an argument to another macro.
2768 For example,
2769 .Sq \&.Op \&Fl O \&Ar file
2770 produces
2771 .Sq Op Fl O Ar file .
2772 To prevent a macro call and render the macro name literally,
2773 escape it by prepending a zero-width space,
2774 .Sq \e& .
2775 For example,
2776 .Sq \&Op \e&Fl O
2777 produces
2778 .Sq Op \&Fl O .
2779 If a macro is not callable but its name appears as an argument
2780 to another macro, it is interpreted as opaque text.
2781 For example,
2782 .Sq \&.Fl \&Sh
2783 produces
2784 .Sq Fl \&Sh .
2785 .Pp
2786 The
2787 .Em Parsed
2788 column indicates whether the macro may call other macros by receiving
2789 their names as arguments.
2790 If a macro is not parsed but the name of another macro appears
2791 as an argument, it is interpreted as opaque text.
2792 .Pp
2793 The
2794 .Em Scope
2795 column, if applicable, describes closure rules.
2796 .Ss Block full-explicit
2797 Multi-line scope closed by an explicit closing macro.
2798 All macros contains bodies; only
2799 .Sx \&Bf
2800 and
2801 .Pq optionally
2802 .Sx \&Bl
2803 contain a head.
2804 .Bd -literal -offset indent
2805 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2806 \(lBbody...\(rB
2807 \&.Yc
2808 .Ed
2809 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2810 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2811 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
2812 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
2813 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
2814 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
2815 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
2816 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
2817 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
2818 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
2819 .El
2820 .Ss Block full-implicit
2821 Multi-line scope closed by end-of-file or implicitly by another macro.
2822 All macros have bodies; some
2823 .Po
2824 .Sx \&It Fl bullet ,
2825 .Fl hyphen ,
2826 .Fl dash ,
2827 .Fl enum ,
2828 .Fl item
2829 .Pc
2830 don't have heads; only one
2831 .Po
2832 .Sx \&It
2833 in
2834 .Sx \&Bl Fl column
2835 .Pc
2836 has multiple heads.
2837 .Bd -literal -offset indent
2838 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2839 \(lBbody...\(rB
2840 .Ed
2841 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2842 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2843 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
2844 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2845 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2846 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
2847 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
2848 .El
2849 .Pp
2850 Note that the
2851 .Sx \&Nm
2852 macro is a
2853 .Sx Block full-implicit
2854 macro only when invoked as the first macro
2855 in a
2856 .Em SYNOPSIS
2857 section line, else it is
2858 .Sx In-line .
2859 .Ss Block partial-explicit
2860 Like block full-explicit, but also with single-line scope.
2861 Each has at least a body and, in limited circumstances, a head
2862 .Po
2863 .Sx \&Fo ,
2864 .Sx \&Eo
2865 .Pc
2866 and/or tail
2867 .Pq Sx \&Ec .
2868 .Bd -literal -offset indent
2869 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2870 \(lBbody...\(rB
2871 \&.Yc \(lBtail...\(rB
2872
2873 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2874 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2875 .Ed
2876 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2877 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2878 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
2879 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
2880 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
2881 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
2882 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
2883 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
2884 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
2885 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
2886 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
2887 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
2888 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
2889 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
2890 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
2891 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
2892 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
2893 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
2894 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
2895 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
2896 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
2897 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
2898 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
2899 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
2900 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
2901 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
2902 .El
2903 .Ss Block partial-implicit
2904 Like block full-implicit, but with single-line scope closed by the
2905 end of the line.
2906 .Bd -literal -offset indent
2907 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2908 .Ed
2909 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2910 .It Em Macro Ta Em Callable Ta Em Parsed
2911 .It Sx \&Aq Ta Yes Ta Yes
2912 .It Sx \&Bq Ta Yes Ta Yes
2913 .It Sx \&Brq Ta Yes Ta Yes
2914 .It Sx \&D1 Ta \&No Ta \&Yes
2915 .It Sx \&Dl Ta \&No Ta Yes
2916 .It Sx \&Dq Ta Yes Ta Yes
2917 .It Sx \&Op Ta Yes Ta Yes
2918 .It Sx \&Pq Ta Yes Ta Yes
2919 .It Sx \&Ql Ta Yes Ta Yes
2920 .It Sx \&Qq Ta Yes Ta Yes
2921 .It Sx \&Sq Ta Yes Ta Yes
2922 .It Sx \&Vt Ta Yes Ta Yes
2923 .El
2924 .Pp
2925 Note that the
2926 .Sx \&Vt
2927 macro is a
2928 .Sx Block partial-implicit
2929 only when invoked as the first macro
2930 in a
2931 .Em SYNOPSIS
2932 section line, else it is
2933 .Sx In-line .
2934 .Ss Special block macro
2935 The
2936 .Sx \&Ta
2937 macro can only be used below
2938 .Sx \&It
2939 in
2940 .Sx \&Bl Fl column
2941 lists.
2942 It delimits blocks representing table cells;
2943 these blocks have bodies, but no heads.
2944 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2945 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2946 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
2947 .El
2948 .Ss In-line
2949 Closed by the end of the line, fixed argument lengths,
2950 and/or subsequent macros.
2951 In-line macros have only text children.
2952 If a number (or inequality) of arguments is
2953 .Pq n ,
2954 then the macro accepts an arbitrary number of arguments.
2955 .Bd -literal -offset indent
2956 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
2957
2958 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
2959
2960 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
2961 .Ed
2962 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
2963 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
2964 .It Sx \&%A Ta \&No Ta \&No Ta >0
2965 .It Sx \&%B Ta \&No Ta \&No Ta >0
2966 .It Sx \&%C Ta \&No Ta \&No Ta >0
2967 .It Sx \&%D Ta \&No Ta \&No Ta >0
2968 .It Sx \&%I Ta \&No Ta \&No Ta >0
2969 .It Sx \&%J Ta \&No Ta \&No Ta >0
2970 .It Sx \&%N Ta \&No Ta \&No Ta >0
2971 .It Sx \&%O Ta \&No Ta \&No Ta >0
2972 .It Sx \&%P Ta \&No Ta \&No Ta >0
2973 .It Sx \&%Q Ta \&No Ta \&No Ta >0
2974 .It Sx \&%R Ta \&No Ta \&No Ta >0
2975 .It Sx \&%T Ta \&No Ta \&No Ta >0
2976 .It Sx \&%U Ta \&No Ta \&No Ta >0
2977 .It Sx \&%V Ta \&No Ta \&No Ta >0
2978 .It Sx \&Ad Ta Yes Ta Yes Ta >0
2979 .It Sx \&An Ta Yes Ta Yes Ta >0
2980 .It Sx \&Ap Ta Yes Ta Yes Ta 0
2981 .It Sx \&Ar Ta Yes Ta Yes Ta n
2982 .It Sx \&At Ta Yes Ta Yes Ta 1
2983 .It Sx \&Bsx Ta Yes Ta Yes Ta n
2984 .It Sx \&Bt Ta \&No Ta \&No Ta 0
2985 .It Sx \&Bx Ta Yes Ta Yes Ta n
2986 .It Sx \&Cd Ta Yes Ta Yes Ta >0
2987 .It Sx \&Cm Ta Yes Ta Yes Ta >0
2988 .It Sx \&Db Ta \&No Ta \&No Ta 1
2989 .It Sx \&Dd Ta \&No Ta \&No Ta n
2990 .It Sx \&Dt Ta \&No Ta \&No Ta n
2991 .It Sx \&Dv Ta Yes Ta Yes Ta >0
2992 .It Sx \&Dx Ta Yes Ta Yes Ta n
2993 .It Sx \&Em Ta Yes Ta Yes Ta >0
2994 .It Sx \&En Ta \&No Ta \&No Ta 0
2995 .It Sx \&Er Ta Yes Ta Yes Ta >0
2996 .It Sx \&Es Ta \&No Ta \&No Ta 0
2997 .It Sx \&Ev Ta Yes Ta Yes Ta >0
2998 .It Sx \&Ex Ta \&No Ta \&No Ta n
2999 .It Sx \&Fa Ta Yes Ta Yes Ta >0
3000 .It Sx \&Fd Ta \&No Ta \&No Ta >0
3001 .It Sx \&Fl Ta Yes Ta Yes Ta n
3002 .It Sx \&Fn Ta Yes Ta Yes Ta >0
3003 .It Sx \&Fr Ta \&No Ta \&No Ta n
3004 .It Sx \&Ft Ta Yes Ta Yes Ta >0
3005 .It Sx \&Fx Ta Yes Ta Yes Ta n
3006 .It Sx \&Hf Ta \&No Ta \&No Ta n
3007 .It Sx \&Ic Ta Yes Ta Yes Ta >0
3008 .It Sx \&In Ta \&No Ta \&No Ta 1
3009 .It Sx \&Lb Ta \&No Ta \&No Ta 1
3010 .It Sx \&Li Ta Yes Ta Yes Ta >0
3011 .It Sx \&Lk Ta Yes Ta Yes Ta >0
3012 .It Sx \&Lp Ta \&No Ta \&No Ta 0
3013 .It Sx \&Ms Ta Yes Ta Yes Ta >0
3014 .It Sx \&Mt Ta Yes Ta Yes Ta >0
3015 .It Sx \&Nm Ta Yes Ta Yes Ta n
3016 .It Sx \&No Ta Yes Ta Yes Ta 0
3017 .It Sx \&Ns Ta Yes Ta Yes Ta 0
3018 .It Sx \&Nx Ta Yes Ta Yes Ta n
3019 .It Sx \&Os Ta \&No Ta \&No Ta n
3020 .It Sx \&Ot Ta \&No Ta \&No Ta n
3021 .It Sx \&Ox Ta Yes Ta Yes Ta n
3022 .It Sx \&Pa Ta Yes Ta Yes Ta n
3023 .It Sx \&Pf Ta Yes Ta Yes Ta 1
3024 .It Sx \&Pp Ta \&No Ta \&No Ta 0
3025 .It Sx \&Rv Ta \&No Ta \&No Ta n
3026 .It Sx \&Sm Ta \&No Ta \&No Ta 1
3027 .It Sx \&St Ta \&No Ta Yes Ta 1
3028 .It Sx \&Sx Ta Yes Ta Yes Ta >0
3029 .It Sx \&Sy Ta Yes Ta Yes Ta >0
3030 .It Sx \&Tn Ta Yes Ta Yes Ta >0
3031 .It Sx \&Ud Ta \&No Ta \&No Ta 0
3032 .It Sx \&Ux Ta Yes Ta Yes Ta n
3033 .It Sx \&Va Ta Yes Ta Yes Ta n
3034 .It Sx \&Vt Ta Yes Ta Yes Ta >0
3035 .It Sx \&Xr Ta Yes Ta Yes Ta >0
3036 .It Sx \&br Ta \&No Ta \&No Ta 0
3037 .It Sx \&sp Ta \&No Ta \&No Ta 1
3038 .El
3039 .Ss Delimiters
3040 When a macro argument consists of one single input character
3041 considered as a delimiter, the argument gets special handling.
3042 This does not apply when delimiters appear in arguments containing
3043 more than one character.
3044 Consequently, to prevent special handling and just handle it
3045 like any other argument, a delimiter can be escaped by prepending
3046 a zero-width space
3047 .Pq Sq \e& .
3048 In text lines, delimiters never need escaping, but may be used
3049 as normal punctuation.
3050 .Pp
3051 For many macros, when the leading arguments are opening delimiters,
3052 these delimiters are put before the macro scope,
3053 and when the trailing arguments are closing delimiters,
3054 these delimiters are put after the macro scope.
3055 For example,
3056 .Pp
3057 .D1 Pf \. \&Aq "( [ word ] ) ."
3058 .Pp
3059 renders as:
3060 .Pp
3061 .D1 Aq ( [ word ] ) .
3062 .Pp
3063 Opening delimiters are:
3064 .Pp
3065 .Bl -tag -width Ds -offset indent -compact
3066 .It \&(
3067 left parenthesis
3068 .It \&[
3069 left bracket
3070 .El
3071 .Pp
3072 Closing delimiters are:
3073 .Pp
3074 .Bl -tag -width Ds -offset indent -compact
3075 .It \&.
3076 period
3077 .It \&,
3078 comma
3079 .It \&:
3080 colon
3081 .It \&;
3082 semicolon
3083 .It \&)
3084 right parenthesis
3085 .It \&]
3086 right bracket
3087 .It \&?
3088 question mark
3089 .It \&!
3090 exclamation mark
3091 .El
3092 .Pp
3093 Note that even a period preceded by a backslash
3094 .Pq Sq \e.\&
3095 gets this special handling; use
3096 .Sq \e&.
3097 to prevent that.
3098 .Pp
3099 Many in-line macros interrupt their scope when they encounter
3100 delimiters, and resume their scope when more arguments follow that
3101 are not delimiters.
3102 For example,
3103 .Pp
3104 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3105 .Pp
3106 renders as:
3107 .Pp
3108 .D1 Fl a ( b | c \*(Ba d ) e
3109 .Pp
3110 This applies to both opening and closing delimiters,
3111 and also to the middle delimiter:
3112 .Pp
3113 .Bl -tag -width Ds -offset indent -compact
3114 .It \&|
3115 vertical bar
3116 .El
3117 .Pp
3118 As a special case, the predefined string \e*(Ba is handled and rendered
3119 in the same way as a plain
3120 .Sq \&|
3121 character.
3122 Using this predefined string is not recommended in new manuals.
3123 .Ss Font handling
3124 In
3125 .Nm
3126 documents, usage of semantic markup is recommended in order to have
3127 proper fonts automatically selected; only when no fitting semantic markup
3128 is available, consider falling back to
3129 .Sx Physical markup
3130 macros.
3131 Whenever any
3132 .Nm
3133 macro switches the
3134 .Xr roff 7
3135 font mode, it will automatically restore the previous font when exiting
3136 its scope.
3137 Manually switching the font using the
3138 .Xr roff 7
3139 .Ql \ef
3140 font escape sequences is never required.
3141 .Sh COMPATIBILITY
3142 This section provides an incomplete list of compatibility issues
3143 between mandoc and other troff implementations, at this time limited
3144 to GNU troff
3145 .Pq Qq groff .
3146 The term
3147 .Qq historic groff
3148 refers to groff versions before 1.17,
3149 which featured a significant update of the
3150 .Pa doc.tmac
3151 file.
3152 .Pp
3153 Heirloom troff, the other significant troff implementation accepting
3154 \-mdoc, is similar to historic groff.
3155 .Pp
3156 The following problematic behaviour is found in groff:
3157 .ds hist (Historic groff only.)
3158 .Pp
3159 .Bl -dash -compact
3160 .It
3161 Display macros
3162 .Po
3163 .Sx \&Bd ,
3164 .Sx \&Dl ,
3165 and
3166 .Sx \&D1
3167 .Pc
3168 may not be nested.
3169 \*[hist]
3170 .It
3171 .Sx \&At
3172 with unknown arguments produces no output at all.
3173 \*[hist]
3174 Newer groff and mandoc print
3175 .Qq AT&T UNIX
3176 and the arguments.
3177 .It
3178 .Sx \&Bl Fl column
3179 does not recognise trailing punctuation characters when they immediately
3180 precede tabulator characters, but treats them as normal text and
3181 outputs a space before them.
3182 .It
3183 .Sx \&Bd Fl ragged compact
3184 does not start a new line.
3185 \*[hist]
3186 .It
3187 .Sx \&Dd
3188 with non-standard arguments behaves very strangely.
3189 When there are three arguments, they are printed verbatim.
3190 Any other number of arguments is replaced by the current date,
3191 but without any arguments the string
3192 .Dq Epoch
3193 is printed.
3194 .It
3195 .Sx \&Fl
3196 does not print a dash for an empty argument.
3197 \*[hist]
3198 .It
3199 .Sx \&Fn
3200 does not start a new line unless invoked as the line macro in the
3201 .Em SYNOPSIS
3202 section.
3203 \*[hist]
3204 .It
3205 .Sx \&Fo
3206 with
3207 .Pf non- Sx \&Fa
3208 children causes inconsistent spacing between arguments.
3209 In mandoc, a single space is always inserted between arguments.
3210 .It
3211 .Sx \&Ft
3212 in the
3213 .Em SYNOPSIS
3214 causes inconsistent vertical spacing, depending on whether a prior
3215 .Sx \&Fn
3216 has been invoked.
3217 See
3218 .Sx \&Ft
3219 and
3220 .Sx \&Fn
3221 for the normalised behaviour in mandoc.
3222 .It
3223 .Sx \&In
3224 ignores additional arguments and is not treated specially in the
3225 .Em SYNOPSIS .
3226 \*[hist]
3227 .It
3228 .Sx \&It
3229 sometimes requires a
3230 .Fl nested
3231 flag.
3232 \*[hist]
3233 In new groff and mandoc, any list may be nested by default and
3234 .Fl enum
3235 lists will restart the sequence only for the sub-list.
3236 .It
3237 .Sx \&Li
3238 followed by a delimiter is incorrectly used in some manuals
3239 instead of properly quoting that character, which sometimes works with
3240 historic groff.
3241 .It
3242 .Sx \&Lk
3243 only accepts a single link-name argument; the remainder is misformatted.
3244 .It
3245 .Sx \&Pa
3246 does not format its arguments when used in the FILES section under
3247 certain list types.
3248 .It
3249 .Sx \&Ta
3250 can only be called by other macros, but not at the beginning of a line.
3251 .It
3252 .Sx \&%C
3253 is not implemented (up to and including groff-1.22.2).
3254 .It
3255 Historic groff only allows up to eight or nine arguments per macro input
3256 line, depending on the exact situation.
3257 Providing more arguments causes garbled output.
3258 The number of arguments on one input line is not limited with mandoc.
3259 .It
3260 Historic groff has many un-callable macros.
3261 Most of these (excluding some block-level macros) are callable
3262 in new groff and mandoc.
3263 .It
3264 .Sq \(ba
3265 (vertical bar) is not fully supported as a delimiter.
3266 \*[hist]
3267 .It
3268 .Sq \ef
3269 .Pq font face
3270 and
3271 .Sq \eF
3272 .Pq font family face
3273 .Sx Text Decoration
3274 escapes behave irregularly when specified within line-macro scopes.
3275 .It
3276 Negative scaling units return to prior lines.
3277 Instead, mandoc truncates them to zero.
3278 .El
3279 .Pp
3280 The following features are unimplemented in mandoc:
3281 .Pp
3282 .Bl -dash -compact
3283 .It
3284 .Sx \&Bd
3285 .Fl file Ar file .
3286 .It
3287 .Sx \&Bd
3288 .Fl offset Cm center
3289 and
3290 .Fl offset Cm right .
3291 Groff does not implement centred and flush-right rendering either,
3292 but produces large indentations.
3293 .El
3294 .Sh SEE ALSO
3295 .Xr man 1 ,
3296 .Xr mandoc 1 ,
3297 .Xr eqn 7 ,
3298 .Xr man 7 ,
3299 .Xr mandoc_char 7 ,
3300 .Xr roff 7 ,
3301 .Xr tbl 7
3302 .Sh HISTORY
3303 The
3304 .Nm
3305 language first appeared as a troff macro package in
3306 .Bx 4.4 .
3307 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3308 in groff-1.17.
3309 The standalone implementation that is part of the
3310 .Xr mandoc 1
3311 utility written by Kristaps Dzonsons appeared in
3312 .Ox 4.6 .
3313 .Sh AUTHORS
3314 The
3315 .Nm
3316 reference was written by
3317 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .