| blob | 3b39324741f7f31e0c24d30affdccbad86be2518 |
1 .\" $Id: mdoc.7,v 1.78 2009/11/16 09:52:47 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd November 19, 2009
18 .Dt MDOC 7
19 .Os
20 .
21 .
22 .Sh NAME
23 .Nm mdoc
24 .Nd mdoc language reference
25 .
26 .
27 .Sh DESCRIPTION
28 The
29 .Nm mdoc
30 language is used to format
31 .Bx
32 .Ux
33 manuals. In this reference document, we describe its syntax, structure,
34 and usage. Our reference implementation is
35 .Xr mandoc 1 .
36 The
37 .Sx COMPATIBILITY
38 section describes compatibility with
39 .Xr groff 1 .
40 .
41 .Pp
42 An
43 .Nm
44 document follows simple rules: lines beginning with the control
45 character
46 .Sq \.
47 are parsed for macros. Other lines are interpreted within the scope of
48 prior macros:
49 .Bd -literal -offset indent
50 \&.Sh Macro lines change control state.
51 Other lines are interpreted within the current state.
52 .Ed
53 .
54 .
55 .Sh LANGUAGE SYNTAX
56 .Nm
57 documents may contain only graphable 7-bit ASCII characters, the space
58 character, and, in certain circumstances, the tab character. All
59 manuals must have
60 .Ux
61 line terminators.
62 .
63 .
64 .Ss Comments
65 Text following a
66 .Sq \e" ,
67 whether in a macro or free-form text line, is ignored to the end of
68 line. A macro line with only a control character and comment escape,
69 .Sq \&.\e" ,
70 is also ignored. Macro lines with only a control charater and optionally
71 whitespace are stripped from input.
72 .
73 .
74 .Ss Reserved Characters
75 Within a macro line, the following characters are reserved:
76 .Pp
77 .Bl -tag -width Ds -offset indent -compact
78 .It \&.
79 .Pq period
80 .It \&,
81 .Pq comma
82 .It \&:
83 .Pq colon
84 .It \&;
85 .Pq semicolon
86 .It \&(
87 .Pq left-parenthesis
88 .It \&)
89 .Pq right-parenthesis
90 .It \&[
91 .Pq left-bracket
92 .It \&]
93 .Pq right-bracket
94 .It \&?
95 .Pq question
96 .It \&!
97 .Pq exclamation
98 .It \&|
99 .Pq vertical bar
100 .El
101 .
102 .Pp
103 Use of reserved characters is described in
104 .Sx MACRO SYNTAX .
105 For general use in macro lines, these characters must either be escaped
106 with a non-breaking space
107 .Pq Sq \e&
108 or, if applicable, an appropriate escape sequence used.
109 .
110 .
111 .Ss Special Characters
112 Special characters may occur in both macro and free-form lines.
113 Sequences begin with the escape character
114 .Sq \e
115 followed by either an open-parenthesis
116 .Sq \&(
117 for two-character sequences; an open-bracket
118 .Sq \&[
119 for n-character sequences (terminated at a close-bracket
120 .Sq \&] ) ;
121 or a single one-character sequence. See
122 .Xr mandoc_char 7
123 for a complete list. Examples include
124 .Sq \e(em
125 .Pq em-dash
126 and
127 .Sq \ee
128 .Pq back-slash .
129 .
130 .
131 .Ss Text Decoration
132 Terms may be text-decorated using the
133 .Sq \ef
134 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
135 (revert to previous mode):
136 .Pp
137 .D1 \efBbold\efR \efIitalic\efP
138 .Pp
139 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
140 respectively) may be used instead. A text decoration is valid within
141 the current font scope only: if a macro opens a font scope alongside
142 its own scope, such as
143 .Sx \&Bf
144 .Cm \&Sy ,
145 in-scope invocations of
146 .Sq \ef
147 are only valid within the font scope of the macro. If
148 .Sq \ef
149 is specified outside of any font scope, such as in unenclosed, free-form
150 text, it will affect the remainder of the document.
151 .Pp
152 Text may also be sized with the
153 .Sq \es
154 escape, whose syntax is one of
155 .Sq \es+-n
156 for one-digit numerals;
157 .Sq \es(+-nn
158 or
159 .Sq \es+-(nn
160 for two-digit numerals; and
161 .Sq \es[+-N] ,
162 .Sq \es+-[N] ,
163 .Sq \es'+-N' ,
164 or
165 .Sq \es+-'N'
166 for arbitrary-digit numerals:
167 .Pp
168 .D1 \es+1bigger\es-1
169 .D1 \es[+10]much bigger\es[-10]
170 .D1 \es+(10much bigger\es-(10
171 .D1 \es+'100'much much bigger\es-'100'
172 .Pp
173 Note these forms are
174 .Em not
175 recommended for
176 .Nm ,
177 which encourages semantic annotation.
178 .
179 .
180 .Ss Predefined Strings
181 Historically,
182 .Xr groff 1
183 also defined a set of package-specific
184 .Dq predefined strings ,
185 which, like
186 .Sx Special Characters ,
187 demark special output characters and strings by way of input codes.
188 Predefined strings are escaped with the slash-asterisk,
189 .Sq \e* :
190 single-character
191 .Sq \e*X ,
192 two-character
193 .Sq \e*(XX ,
194 and N-character
195 .Sq \e*[N] .
196 See
197 .Xr mandoc_char 7
198 for a complete list. Examples include
199 .Sq \e*(Am
200 .Pq ampersand
201 and
202 .Sq \e*(Ba
203 .Pq vertical bar .
204 .
205 .
206 .Ss Whitespace
207 In non-literal free-form lines, consecutive blocks of whitespace are
208 pruned from input and added later in the output filter, if applicable:
209 .Bd -literal -offset indent
210 These spaces are pruned from input.
211 \&.Bd \-literal
212 These are not.
213 \&.Ed
214 .Ed
215 .
216 .Pp
217 In macro lines, whitespace delimits arguments and is discarded. If
218 arguments are quoted, whitespace within the quotes is retained.
219 .
220 .Pp
221 Blank lines are only permitted within literal contexts, as are lines
222 containing only whitespace. Tab characters are only acceptable when
223 delimiting
224 .Sq \&Bl \-column
225 or when in a literal context.
226 .
227 .
228 .Ss Quotation
229 Macro arguments may be quoted with a double-quote to group
230 space-delimited terms or to retain blocks of whitespace. A quoted
231 argument begins with a double-quote preceded by whitespace. The next
232 double-quote not pair-wise adjacent to another double-quote terminates
233 the literal, regardless of surrounding whitespace.
234 .
235 .Pp
236 This produces tokens
237 .Sq a" ,
238 .Sq b c ,
239 .Sq de ,
240 and
241 .Sq fg" .
242 Note that any quoted term, be it argument or macro, is indiscriminately
243 considered literal text. Thus, the following produces
244 .Sq \&Em a :
245 .Bd -literal -offset indent
246 \&.Em "Em a"
247 .Ed
248 .
249 .Pp
250 In free-form mode, quotes are regarded as opaque text.
251 .
252 .Ss Dates
253 There are several macros in
254 .Nm
255 that require a date argument. The canonical form for dates is the
256 American format:
257 .Pp
258 .D1 Cm Month Day , Year
259 .Pp
260 The
261 .Cm Day
262 value is an optionally zero-padded numeral. The
263 .Cm Month
264 value is the full month name. The
265 .Cm Year
266 value is the full four-digit year.
267 .Pp
268 Reduced form dates are broken-down canonical form dates:
269 .Pp
270 .D1 Cm Month , Year
271 .D1 Cm Year
272 .Pp
273 Some examples of valid dates follow:
274 .Pp
275 .D1 "May, 2009" Pq reduced form
276 .D1 "2009" Pq reduced form
277 .D1 "May 20, 2009" Pq canonical form
278 .
279 .Ss Scaling Widths
280 Many macros support scaled widths for their arguments, such as
281 stipulating a two-inch list indentation with the following:
282 .Bd -literal -offset indent
283 \&.Bl -tag -width 2i
284 .Ed
285 .
286 .Pp
287 The syntax for scaled widths is
288 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
289 where a decimal must be preceded or proceeded by at least one digit.
290 Negative numbers, while accepted, are truncated to zero. The following
291 scaling units are accepted:
292 .Pp
293 .Bl -tag -width Ds -offset indent -compact
294 .It c
295 centimetre
296 .It i
297 inch
298 .It P
299 pica (~1/6 inch)
300 .It p
301 point (~1/72 inch)
302 .It f
303 synonym for
304 .Sq u
305 .It v
306 default vertical span
307 .It m
308 width of rendered
309 .Sq m
310 .Pq em
311 character
312 .It n
313 width of rendered
314 .Sq n
315 .Pq en
316 character
317 .It u
318 default horizontal span
319 .It M
320 mini-em (~1/100 em)
321 .El
322 .Pp
323 Using anything other than
324 .Sq m ,
325 .Sq n ,
326 .Sq u ,
327 or
328 .Sq v
329 is necessarily non-portable across output media. See
330 .Sx COMPATIBILITY .
331 .
332 .
333 .Sh MANUAL STRUCTURE
334 A well-formed
335 .Nm
336 document consists of a document prologue followed by one or more
337 sections.
338 .Pp
339 The prologue, which consists of (in order) the
340 .Sx \&Dd ,
341 .Sx \&Dt ,
342 and
343 .Sx \&Os
344 macros, is required for every document.
345 .Pp
346 The first section (sections are denoted by
347 .Sx \&Sh )
348 must be the NAME section, consisting of at least one
349 .Sx \&Nm
350 followed by
351 .Sx \&Nd .
352 .Pp
353 Following that, convention dictates specifying at least the SYNOPSIS and
354 DESCRIPTION sections, although this varies between manual sections.
355 .Pp
356 The following is a well-formed skeleton
357 .Nm
358 file:
359 .Bd -literal -offset indent
360 \&.Dd $\&Mdocdate$
361 \&.Dt mdoc 7
362 \&.Os
363 \&.
364 \&.Sh NAME
365 \&.Nm foo
366 \&.Nd a description goes here
367 \&.\e\*q The next is for sections 2 & 3 only.
368 \&.\e\*q .Sh LIBRARY
369 \&.
370 \&.Sh SYNOPSIS
371 \&.Nm foo
372 \&.Op Fl options
373 \&.Ar
374 \&.
375 \&.Sh DESCRIPTION
376 The
377 \&.Nm
378 utility processes files ...
379 \&.\e\*q .Sh IMPLEMENTATION NOTES
380 \&.\e\*q The next is for sections 1 & 8 only.
381 \&.\e\*q .Sh EXIT STATUS
382 \&.\e\*q The next is for sections 2, 3, & 9 only.
383 \&.\e\*q .Sh RETURN VALUES
384 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
385 \&.\e\*q .Sh ENVIRONMENT
386 \&.\e\*q .Sh FILES
387 \&.\e\*q .Sh EXAMPLES
388 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
389 \&.\e\*q .Sh DIAGNOSTICS
390 \&.\e\*q The next is for sections 2, 3, & 9 only.
391 \&.\e\*q .Sh ERRORS
392 \&.\e\*q .Sh SEE ALSO
393 \&.\e\*q .Xr foobar 1
394 \&.\e\*q .Sh STANDARDS
395 \&.\e\*q .Sh HISTORY
396 \&.\e\*q .Sh AUTHORS
397 \&.\e\*q .Sh CAVEATS
398 \&.\e\*q .Sh BUGS
399 \&.\e\*q .Sh SECURITY CONSIDERATIONS
400 .Ed
401 .Pp
402 The sections in a
403 .Nm
404 document are conventionally ordered as they appear above. Sections
405 should be composed as follows:
406 .Bl -ohang -offset Ds
407 .It Em NAME
408 The name(s) and a short description of the documented material. The
409 syntax for this as follows:
410 .Bd -literal -offset indent
411 \&.Nm name0
412 \&.Nm name1
413 \&.Nm name2
414 \&.Nd a short description
415 .Ed
416 .Pp
417 The
418 .Sx \&Nm
419 macro(s) must precede the
420 .Sx \&Nd
421 macro.
422 .
423 .It Em LIBRARY
424 The name of the library containing the documented material, which is
425 assumed to be a function in a section 2 or 3 manual. The syntax for
426 this is as follows:
427 .Bd -literal -offset indent
428 \&.Lb libarm
429 .Ed
430 .Pp
431 See
432 .Sx \&Lb
433 for details.
434 .
435 .It Em SYNOPSIS
436 Documents the utility invocation syntax, function call syntax, or device
437 configuration.
438 .Pp
439 For the first, utilities (sections 1, 6, and 8), this is
440 generally structured as follows:
441 .Bd -literal -offset indent
442 \&.Nm foo
443 \&.Op Fl v
444 \&.Op Fl o Ar file
445 \&.Op Ar
446 \&.Nm bar
447 \&.Op Fl v
448 \&.Op Fl o Ar file
449 \&.Op Ar
450 .Ed
451 .Pp
452 For the second, function calls (sections 2, 3, 9):
453 .Bd -literal -offset indent
454 \&.Vt extern const char *global;
455 \&.In header.h
456 \&.Ft "char *"
457 \&.Fn foo "const char *src"
458 \&.Ft "char *"
459 \&.Fn bar "const char *src"
460 .Ed
461 .Pp
462 And for the third, configurations (section 4):
463 .Bd -literal -offset indent
464 \&.Cd \*qit* at isa? port 0x2e\*q
465 \&.Cd \*qit* at isa? port 0x4e\*q
466 .Ed
467 .Pp
468 Manuals not in these sections generally don't need a
469 .Em SYNOPSIS .
470 .
471 .It Em DESCRIPTION
472 This expands upon the brief, one-line description in
473 .Em NAME .
474 It usually contains a break-down of the options (if documenting a
475 command), such as:
476 .Bd -literal -offset indent
477 The arguments are as follows:
478 \&.Bl \-tag \-width Ds
479 \&.It Fl v
480 Print verbose information.
481 \&.El
482 .Ed
483 Manuals not documenting a command won't include the above fragment.
484 .
485 .It Em IMPLEMENTATION NOTES
486 Implementation-specific notes should be kept here. This is useful when
487 implementing standard functions that may have side effects or notable
488 algorithmic implications.
489 .
490 .It Em EXIT STATUS
491 Command exit status for section 1, 6, and 8 manuals. This section is
492 the dual of
493 .Em RETURN VALUES ,
494 which is used for functions. Historically, this information was
495 described in
496 .Em DIAGNOSTICS ,
497 a practise that is now discouraged.
498 .Pp
499 See
500 .Sx \&Ex .
501 .
502 .It Em RETURN VALUES
503 This section is the dual of
504 .Em EXIT STATUS ,
505 which is used for commands. It documents the return values of functions
506 in sections 2, 3, and 9.
507 .Pp
508 See
509 .Sx \&Rv .
510 .
511 .It Em ENVIRONMENT
512 Documents any usages of environment variables, e.g.,
513 .Xr environ 7 .
514 .Pp
515 See
516 .Sx \&Ev .
517 .
518 .It Em FILES
519 Documents files used. It's helpful to document both the file and a
520 short description of how the file is used (created, modified, etc.).
521 .Pp
522 See
523 .Sx \&Pa .
524 .
525 .It Em EXAMPLES
526 Example usages. This often contains snippets of well-formed,
527 well-tested invocations. Make doubly sure that your examples work
528 properly!
529 .
530 .It Em DIAGNOSTICS
531 Documents error conditions. This is most useful in section 4 manuals.
532 Historically, this section was used in place of
533 .Em EXIT STATUS
534 for manuals in sections 1, 6, and 8; however, this practise is
535 discouraged.
536 .Pp
537 See
538 .Sx \&Bl No \-diag .
539 .
540 .It Em ERRORS
541 Documents error handling in sections 2, 3, and 9.
542 .Pp
543 See
544 .Sx \&Er .
545 .
546 .It Em SEE ALSO
547 References other manuals with related topics. This section should exist
548 for most manuals. Cross-references should conventionally be ordered
549 first by section, then alphabetically.
550 .Pp
551 See
552 .Sx \&Xr .
553 .
554 .It Em STANDARDS
555 References any standards implemented or used. If not adhering to any
556 standards, the
557 .Em HISTORY
558 section should be used instead.
559 .Pp
560 See
561 .Sx \&St .
562 .
563 .It Em HISTORY
564 The history of any manual without a
565 .Em STANDARDS
566 section should be described in this section.
567 .
568 .It Em AUTHORS
569 Credits to authors, if applicable, should appear in this section.
570 Authors should generally be noted by both name and an e-mail address.
571 .Pp
572 See
573 .Sx \&An .
574 .
575 .It Em CAVEATS
576 Explanations of common misuses and misunderstandings should be explained
577 in this section.
578 .
579 .It Em BUGS
580 Extant bugs should be described in this section.
581 .
582 .It Em SECURITY CONSIDERATIONS
583 Documents any security precautions that operators should consider.
584 .
585 .El
586 .
587 .
588 .Sh MACRO SYNTAX
589 Macros are one to three three characters in length and begin with a
590 control character ,
591 .Sq \&. ,
592 at the beginning of the line. An arbitrary amount of whitespace may
593 sit between the control character and the macro name. Thus, the
594 following are equivalent:
595 .Bd -literal -offset indent
596 \&.Pp
597 \&.\ \ \ \&Pp
598 .Ed
599 .
600 .Pp
601 The syntax of a macro depends on its classification. In this section,
602 .Sq \-arg
603 refers to macro arguments, which may be followed by zero or more
604 .Sq parm
605 parameters;
606 .Sq \&Yo
607 opens the scope of a macro; and if specified,
608 .Sq \&Yc
609 closes it out.
610 .
611 .Pp
612 The
613 .Em Callable
614 column indicates that the macro may be called subsequent to the initial
615 line-macro. If a macro is not callable, then its invocation after the
616 initial line macro is interpreted as opaque text, such that
617 .Sq \&.Fl \&Sh
618 produces
619 .Sq Fl \&Sh .
620 .
621 .Pp
622 The
623 .Em Parsable
624 column indicates whether the macro may be followed by further
625 (ostensibly callable) macros. If a macro is not parsable, subsequent
626 macro invocations on the line will be interpreted as opaque text.
627 .
628 .Pp
629 The
630 .Em Scope
631 column, if applicable, describes closure rules.
632 .
633 .
634 .Ss Block full-explicit
635 Multi-line scope closed by an explicit closing macro. All macros
636 contains bodies; only
637 .Sx \&Bf
638 contains a head.
639 .Bd -literal -offset indent
640 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
641 \(lBbody...\(rB
642 \&.Yc
643 .Ed
644 .
645 .Pp
646 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
647 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
648 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
649 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
650 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
651 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
652 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
653 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
654 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
655 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
656 .El
657 .
658 .
659 .Ss Block full-implicit
660 Multi-line scope closed by end-of-file or implicitly by another macro.
661 All macros have bodies; some
662 .Po
663 .Sx \&It Fl bullet ,
664 .Fl hyphen ,
665 .Fl dash ,
666 .Fl enum ,
667 .Fl item
668 .Pc
669 don't have heads; only one
670 .Po
671 .Sx \&It Fl column
672 .Pc
673 has multiple heads.
674 .Bd -literal -offset indent
675 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
676 \(lBbody...\(rB
677 .Ed
678 .
679 .Pp
680 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
681 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
682 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
683 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
684 .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
685 .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
686 .El
687 .
688 .
689 .Ss Block partial-explicit
690 Like block full-explicit, but also with single-line scope. Each
691 has at least a body and, in limited circumstances, a head
692 .Po
693 .Sx \&Fo ,
694 .Sx \&Eo
695 .Pc
696 and/or tail
697 .Pq Sx \&Ec .
698 .Bd -literal -offset indent
699 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
700 \(lBbody...\(rB
701 \&.Yc \(lBtail...\(rB
703 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
704 \(lBbody...\(rB \&Yc \(lBtail...\(rB
705 .Ed
706 .
707 .Pp
708 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
709 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
710 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
711 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
712 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
713 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
714 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
715 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
716 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
717 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
718 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
719 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
720 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
721 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
722 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
723 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
724 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
725 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
726 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
727 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
728 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
729 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
730 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
731 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
732 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
733 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
734 .El
735 .
736 .
737 .Ss Block partial-implicit
738 Like block full-implicit, but with single-line scope closed by
739 .Sx Reserved Characters
740 or end of line.
741 .Bd -literal -offset indent
742 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
743 .Ed
744 .
745 .Pp
746 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
747 .It Em Macro Ta Em Callable Ta Em Parsable
748 .It Sx \&Aq Ta Yes Ta Yes
749 .It Sx \&Bq Ta Yes Ta Yes
750 .It Sx \&Brq Ta Yes Ta Yes
751 .It Sx \&D1 Ta \&No Ta \&Yes
752 .It Sx \&Dl Ta \&No Ta Yes
753 .It Sx \&Dq Ta Yes Ta Yes
754 .It Sx \&Op Ta Yes Ta Yes
755 .It Sx \&Pq Ta Yes Ta Yes
756 .It Sx \&Ql Ta Yes Ta Yes
757 .It Sx \&Qq Ta Yes Ta Yes
758 .It Sx \&Sq Ta Yes Ta Yes
759 .El
760 .
761 .
762 .Ss In-line
763 Closed by
764 .Sx Reserved Characters ,
765 end of line, fixed argument lengths, and/or subsequent macros. In-line
766 macros have only text children. If a number (or inequality) of
767 arguments is
768 .Pq n ,
769 then the macro accepts an arbitrary number of arguments.
770 .Bd -literal -offset indent
771 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
773 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
775 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
776 .Ed
777 .
778 .Pp
779 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
780 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
781 .It Sx \&%A Ta \&No Ta \&No Ta >0
782 .It Sx \&%B Ta \&No Ta \&No Ta >0
783 .It Sx \&%C Ta \&No Ta \&No Ta >0
784 .It Sx \&%D Ta \&No Ta \&No Ta >0
785 .It Sx \&%I Ta \&No Ta \&No Ta >0
786 .It Sx \&%J Ta \&No Ta \&No Ta >0
787 .It Sx \&%N Ta \&No Ta \&No Ta >0
788 .It Sx \&%O Ta \&No Ta \&No Ta >0
789 .It Sx \&%P Ta \&No Ta \&No Ta >0
790 .It Sx \&%Q Ta \&No Ta \&No Ta >0
791 .It Sx \&%R Ta \&No Ta \&No Ta >0
792 .It Sx \&%T Ta \&No Ta \&No Ta >0
793 .It Sx \&%U Ta \&No Ta \&No Ta >0
794 .It Sx \&%V Ta \&No Ta \&No Ta >0
795 .It Sx \&Ad Ta Yes Ta Yes Ta n
796 .It Sx \&An Ta Yes Ta Yes Ta n
797 .It Sx \&Ap Ta Yes Ta Yes Ta 0
798 .It Sx \&Ar Ta Yes Ta Yes Ta n
799 .It Sx \&At Ta Yes Ta Yes Ta 1
800 .It Sx \&Bsx Ta Yes Ta Yes Ta n
801 .It Sx \&Bt Ta \&No Ta \&No Ta 0
802 .It Sx \&Bx Ta Yes Ta Yes Ta n
803 .It Sx \&Cd Ta Yes Ta Yes Ta >0
804 .It Sx \&Cm Ta Yes Ta Yes Ta n
805 .It Sx \&Db Ta \&No Ta \&No Ta 1
806 .It Sx \&Dd Ta \&No Ta \&No Ta >0
807 .It Sx \&Dt Ta \&No Ta \&No Ta n
808 .It Sx \&Dv Ta Yes Ta Yes Ta n
809 .It Sx \&Dx Ta Yes Ta Yes Ta n
810 .It Sx \&Em Ta Yes Ta Yes Ta >0
811 .It Sx \&En Ta \&No Ta \&No Ta 0
812 .It Sx \&Er Ta Yes Ta Yes Ta >0
813 .It Sx \&Es Ta \&No Ta \&No Ta 0
814 .It Sx \&Ev Ta Yes Ta Yes Ta n
815 .It Sx \&Ex Ta \&No Ta \&No Ta n
816 .It Sx \&Fa Ta Yes Ta Yes Ta n
817 .It Sx \&Fd Ta \&No Ta \&No Ta >0
818 .It Sx \&Fl Ta Yes Ta Yes Ta n
819 .It Sx \&Fn Ta Yes Ta Yes Ta >0
820 .It Sx \&Fr Ta \&No Ta \&No Ta n
821 .It Sx \&Ft Ta Yes Ta Yes Ta n
822 .It Sx \&Fx Ta Yes Ta Yes Ta n
823 .It Sx \&Hf Ta \&No Ta \&No Ta n
824 .It Sx \&Ic Ta Yes Ta Yes Ta >0
825 .It Sx \&In Ta \&No Ta \&No Ta n
826 .It Sx \&Lb Ta \&No Ta \&No Ta 1
827 .It Sx \&Li Ta Yes Ta Yes Ta n
828 .It Sx \&Lk Ta Yes Ta Yes Ta n
829 .It Sx \&Lp Ta \&No Ta \&No Ta 0
830 .It Sx \&Ms Ta Yes Ta Yes Ta >0
831 .It Sx \&Mt Ta Yes Ta Yes Ta >0
832 .It Sx \&Nm Ta Yes Ta Yes Ta n
833 .It Sx \&No Ta Yes Ta Yes Ta 0
834 .It Sx \&Ns Ta Yes Ta Yes Ta 0
835 .It Sx \&Nx Ta Yes Ta Yes Ta n
836 .It Sx \&Os Ta \&No Ta \&No Ta n
837 .It Sx \&Ot Ta \&No Ta \&No Ta n
838 .It Sx \&Ox Ta Yes Ta Yes Ta n
839 .It Sx \&Pa Ta Yes Ta Yes Ta n
840 .It Sx \&Pf Ta \&No Ta Yes Ta 1
841 .It Sx \&Pp Ta \&No Ta \&No Ta 0
842 .It Sx \&Rv Ta \&No Ta \&No Ta n
843 .It Sx \&Sm Ta \&No Ta \&No Ta 1
844 .It Sx \&St Ta \&No Ta Yes Ta 1
845 .It Sx \&Sx Ta Yes Ta Yes Ta >0
846 .It Sx \&Sy Ta Yes Ta Yes Ta >0
847 .It Sx \&Tn Ta Yes Ta Yes Ta >0
848 .It Sx \&Ud Ta \&No Ta \&No Ta 0
849 .It Sx \&Ux Ta Yes Ta Yes Ta n
850 .It Sx \&Va Ta Yes Ta Yes Ta n
851 .It Sx \&Vt Ta Yes Ta Yes Ta >0
852 .It Sx \&Xr Ta Yes Ta Yes Ta >0, <3
853 .It Sx \&br Ta \&No Ta \&No Ta 0
854 .It Sx \&sp Ta \&No Ta \&No Ta 1
855 .El
856 .
857 .
858 .Sh REFERENCE
859 This section is a canonical reference of all macros, arranged
860 alphabetically. For the scoping of individual macros, see
861 .Sx MACRO SYNTAX .
862 .
863 .Ss \&%A
864 Author name of an
865 .Sx \&Rs
866 block. Multiple authors should each be accorded their own
867 .Sx \%%A
868 line. Author names should be ordered with full or abbreviated
869 forename(s) first, then full surname.
870 .
871 .Ss \&%B
872 Book title of an
873 .Sx \&Rs
874 block. This macro may also be used in a non-bibliographic context when
875 referring to book titles.
876 .
877 .Ss \&%C
878 Publication city or location of an
879 .Sx \&Rs
880 block.
881 .Pp
882 .Em Remarks :
883 this macro is not implemented in
884 .Xr groff 1 .
885 .
886 .Ss \&%D
887 Publication date of an
888 .Sx \&Rs
889 block. This should follow the reduced or canonical form syntax
890 described in
891 .Sx Dates .
892 .
893 .Ss \&%I
894 Publisher or issuer name of an
895 .Sx \&Rs
896 block.
897 .
898 .Ss \&%J
899 Journal name of an
900 .Sx \&Rs
901 block.
902 .
903 .Ss \&%N
904 Issue number (usually for journals) of an
905 .Sx \&Rs
906 block.
907 .
908 .Ss \&%O
909 Optional information of an
910 .Sx \&Rs
911 block.
912 .
913 .Ss \&%P
914 Book or journal page number of an
915 .Sx \&Rs
916 block.
917 .
918 .Ss \&%Q
919 Institutional author (school, government, etc.) of an
920 .Sx \&Rs
921 block. Multiple institutional authors should each be accorded their own
922 .Sx \&%Q
923 line.
924 .
925 .Ss \&%R
926 Technical report name of an
927 .Sx \&Rs
928 block.
929 .
930 .Ss \&%T
931 Article title of an
932 .Sx \&Rs
933 block. This macro may also be used in a non-bibliographical context
934 when referring to article titles.
935 .
936 .Ss \&%U
937 URI of reference document.
938 .
939 .Ss \&%V
940 Volume number of an
941 .Sx \&Rs
942 block.
943 .
944 .Ss \&Ac
945 Closes an
946 .Sx \&Ao
947 block. Does not have any tail arguments.
948 .
949 .Ss \&Ad
950 Address construct: usually in the context of an computational address in
951 memory, not a physical (post) address.
952 .Pp
953 Examples:
954 .Bd -literal -offset indent
955 \&.Ad [0,$]
956 \&.Ad 0x00000000
957 .Ed
958 .
959 .Ss \&An
960 Author name. This macro may alternatively accepts the following
961 arguments, although these may not be specified along with a parameter:
962 .Bl -tag -width 12n -offset indent
963 .It Fl split
964 Renders a line break before each author listing.
965 .It Fl nosplit
966 The opposite of
967 .Fl split .
968 .El
969 .Pp
970 In the AUTHORS section, the default is not to split the first author
971 listing, but all subsequent author listings, whether or not they're
972 interspersed by other macros or text, are split. Thus, specifying
973 .Fl split
974 will cause the first listing also to be split. If not in the AUTHORS
975 section, the default is not to split.
976 .Pp
977 Examples:
978 .Bd -literal -offset indent
979 \&.An -nosplit
980 \&.An J. E. Hopcraft ,
981 \&.An J. D. Ullman .
982 .Ed
983 .Pp
984 .Em Remarks :
985 the effects of
986 .Fl split
987 or
988 .Fl nosplit
989 are re-set when entering the AUTHORS section, so if one specifies
990 .Sx \&An Fl nosplit
991 in the general document body, it must be re-specified in the AUTHORS
992 section.
993 .
994 .Ss \&Ao
995 Begins a block enclosed by angled brackets. Does not have any head
996 arguments.
997 .Pp
998 Examples:
999 .Bd -literal -offset indent
1000 \&.Fl -key= Ns Ao Ar val Ac
1001 .Ed
1002 .Pp
1003 See also
1004 .Sx \&Aq .
1005 .
1006 .Ss \&Ap
1007 Inserts an apostrophe without any surrounding white-space. This is
1008 generally used as a grammatic device when referring to the verb form of
1009 a function:
1010 .Bd -literal -offset indent
1011 \&.Fn execve Ap d
1012 .Ed
1013 .
1014 .Ss \&Aq
1015 Encloses its arguments in angled brackets.
1016 .Pp
1017 Examples:
1018 .Bd -literal -offset indent
1019 \&.Fl -key= Ns Aq Ar val
1020 .Ed
1021 .Pp
1022 .Em Remarks :
1023 this macro is often abused for rendering URIs, which should instead use
1024 .Sx \&Lk
1025 or
1026 .Sx \&Mt ,
1027 or to note pre-processor
1028 .Dq Li #include
1029 statements, which should use
1030 .Sx \&In .
1031 .Pp
1032 See also
1033 .Sx \&Ao .
1034 .
1035 .Ss \&Ar
1036 Command arguments. If an argument is not provided, the string
1037 .Dq file ...
1038 is used as a default.
1039 .Pp
1040 Examples:
1041 .Bd -literal -offset indent
1042 \&.Fl o Ns Ar file1
1043 \&.Ar
1044 \&.Ar arg1 , arg2 .
1045 .Ed
1046 .
1047 .Ss \&At
1048 Formats an AT&T version. Accepts at most one parameter:
1049 .Bl -tag -width 12n -offset indent
1050 .It Cm v[1-7] | 32v
1051 A version of
1052 .At .
1053 .It Cm V[.[1-4]]?
1054 A system version of
1055 .At .
1056 .El
1057 .Pp
1058 Note that these parameters do not begin with a hyphen.
1059 .Pp
1060 Examples:
1061 .Bd -literal -offset indent
1062 \&.At
1063 \&.At V.1
1064 .Ed
1065 .Pp
1066 See also
1067 .Sx \&Bsx ,
1068 .Sx \&Bx ,
1069 .Sx \&Dx ,
1070 .Sx \&Fx ,
1071 .Sx \&Nx ,
1072 .Sx \&Ox ,
1073 and
1074 .Sx \&Ux .
1075 .
1076 .Ss \&Bc
1077 Closes a
1078 .Sx \&Bo
1079 block. Does not have any tail arguments.
1080 .
1081 .Ss \&Bd
1082 Begins a display block. A display is collection of macros or text which
1083 may be collectively offset or justified in a manner different from that
1084 of the enclosing context. By default, the block is preceded by a
1085 vertical space.
1086 .Pp
1087 Each display is associated with a type, which must be one of the
1088 following arguments:
1089 .Bl -tag -width 12n -offset indent
1090 .It Fl ragged
1091 Only left-justify the block.
1092 .It Fl unfilled
1093 Do not justify the block at all.
1094 .It Fl filled
1095 Left- and right-justify the block.
1096 .It Fl literal
1097 Alias for
1098 .Fl unfilled .
1099 .It Fl centered
1100 Centre-justify each line.
1101 .El
1102 .Pp
1103 The type must be provided first. Secondary arguments are as follows:
1104 .Bl -tag -width 12n -offset indent
1105 .It Fl offset Ar width
1106 Offset by the value of
1107 .Ar width ,
1108 which is interpreted as one of the following, specified in order:
1109 .Bl -item
1110 .It
1111 As one of the pre-defined strings
1112 .Ar indent ,
1113 the width of standard indentation;
1114 .Ar indent-two ,
1115 twice
1116 .Ar indent ;
1117 .Ar left ,
1118 which has no effect ;
1119 .Ar right ,
1120 which justifies to the right margin; and
1121 .Ar center ,
1122 which aligns around an imagined centre axis.
1123 .It
1124 As a precalculated width for a named macro. The most popular is the
1125 imaginary macro
1126 .Ar \&Ds ,
1127 which resolves to
1128 .Ar 6n .
1129 .It
1130 As a scaling unit following the syntax described in
1131 .Sx Scaling Widths .
1132 .It
1133 As the calculated string length of the opaque string.
1134 .El
1135 .Pp
1136 If unset, it will revert to the value of
1137 .Ar 8n
1138 as described in
1139 .Sx Scaling Widths .
1140 .It Fl compact
1141 Do not assert a vertical space before the block.
1142 .It Fl file Ar file
1143 Prepend the file
1144 .Ar file
1145 before any text or macros within the block.
1146 .El
1147 .Pp
1148 Examples:
1149 .Bd -literal -offset indent
1150 \&.Bd \-unfilled \-offset two-indent \-compact
1151 Hello world.
1152 \&.Ed
1153 .Ed
1154 .Pp
1155 See also
1156 .Sx \&D1
1157 and
1158 .Sx \&Dl .
1159 .
1160 .Ss \&Bf
1161 .Ss \&Bk
1162 .Ss \&Bl
1163 .
1164 .Ss \&Bo
1165 Begins a block enclosed by square brackets. Does not have any head
1166 arguments.
1167 .Pp
1168 Examples:
1169 .Bd -literal -offset indent
1170 \&.Bo 1 ,
1171 \&.Dv BUFSIZ Bc
1172 .Ed
1173 .Pp
1174 See also
1175 .Sx \&Bq .
1176 .
1177 .Ss \&Bq
1178 Encloses its arguments in square brackets.
1179 .Pp
1180 Examples:
1181 .Bd -literal -offset indent
1182 \&.Bq 1 , Dv BUFSIZ
1183 .Ed
1184 .Pp
1185 .Em Remarks :
1186 this macro is sometimes abused to emulate optional arguments for
1187 commands; the correct macros to use for this purpose are
1188 .Sx \&Op ,
1189 .Sx \&Oo ,
1190 and
1191 .Sx \&Oc .
1192 .Pp
1193 See also
1194 .Sx \&Bo .
1195 .
1196 .Ss \&Brc
1197 Closes a
1198 .Sx \&Bro
1199 block. Does not have any tail arguments.
1200 .
1201 .Ss \&Bro
1202 Begins a block enclosed by curly braces. Does not have any head
1203 arguments.
1204 .Pp
1205 Examples:
1206 .Bd -literal -offset indent
1207 \&.Bro 1 , ... ,
1208 \&.Va n Brc
1209 .Ed
1210 .Pp
1211 See also
1212 .Sx \&Brq .
1213 .
1214 .Ss \&Brq
1215 Encloses its arguments in curly braces.
1216 .Pp
1217 Examples:
1218 .Bd -literal -offset indent
1219 \&.Brq 1 , ... , Va n
1220 .Ed
1221 .Pp
1222 See also
1223 .Sx \&Bro .
1224 .
1225 .Ss \&Bsx
1226 Format the BSD/OS version provided as an argument, or a default value if
1227 no argument is provided.
1228 .Pp
1229 Examples:
1230 .Bd -literal -offset indent
1231 \&.Bsx 1.0
1232 \&.Bsx
1233 .Ed
1234 .Pp
1235 See also
1236 .Sx \&At ,
1237 .Sx \&Bx ,
1238 .Sx \&Dx ,
1239 .Sx \&Fx ,
1240 .Sx \&Nx ,
1241 .Sx \&Ox ,
1242 and
1243 .Sx \&Ux .
1244 .
1245 .Ss \&Bt
1246 Prints
1247 .Dq is currently in beta test.
1248 .
1249 .Ss \&Bx
1250 Format the BSD version provided as an argument, or a default value if no
1251 argument is provided.
1252 .Pp
1253 Examples:
1254 .Bd -literal -offset indent
1255 \&.Bx 4.4
1256 \&.Bx
1257 .Ed
1258 .Pp
1259 See also
1260 .Sx \&At ,
1261 .Sx \&Bsx ,
1262 .Sx \&Dx ,
1263 .Sx \&Fx ,
1264 .Sx \&Nx ,
1265 .Sx \&Ox ,
1266 and
1267 .Sx \&Ux .
1268 .
1269 .Ss \&Cd
1270 Configuration declaration (suggested for use only in section four
1271 manuals). This denotes strings accepted by
1272 .Xr config 8 .
1273 .Pp
1274 Examples:
1275 .Bd -literal -offset indent
1276 \&.Cd device le0 at scode?
1277 .Ed
1278 .Pp
1279 .Em Remarks :
1280 this macro is commonly abused by using quoted literals to retain
1281 white-space and align consecutive
1282 .Sx \&Cd
1283 declarations. This practise is discouraged.
1284 .
1285 .Ss \&Cm
1286 Command modifiers. Useful when specifying configuration options or
1287 keys.
1288 .Pp
1289 Examples:
1290 .Bd -literal -offset indent
1291 \&.Cm ControlPath
1292 \&.Cm ControlMaster
1293 .Ed
1294 .Pp
1295 See also
1296 .Sx \&Fl .
1297 .
1298 .Ss \&D1
1299 One-line indented display. This is formatted by the default rules and
1300 is useful for simple indented statements. It is followed by a newline.
1301 .Pp
1302 Examples:
1303 .Bd -literal -offset indent
1304 \&.D1 Fl abcdefgh
1305 .Ed
1306 .Pp
1307 See also
1308 .Sx \&Bd
1309 and
1310 .Sx \&Dl .
1311 .
1312 .Ss \&Db
1313 .Ss \&Dc
1314 Closes a
1315 .Sx \&Do
1316 block. Does not have any tail arguments.
1317 .
1318 .Ss \&Dd
1319 Document date. This is the mandatory first macro of any
1320 .Nm
1321 manual. Its calling syntax is as follows:
1322 .Pp
1323 .D1 \. Ns Sx \&Dd Cm date
1324 .Pp
1325 The
1326 .Cm date
1327 field may be either
1328 .Ar $\&Mdocdate$ ,
1329 which signifies the current manual revision date dictated by
1330 .Xr cvs 1 ,
1331 or instead a valid canonical date as specified by
1332 .Sx Dates .
1333 If a date does not conform, the current date is used instead.
1334 .Pp
1335 Examples:
1336 .Bd -literal -offset indent
1337 \&.Dd $\&Mdocdate$
1338 \&.Dd $\&Mdocdate: July 21 2007$
1339 \&.Dd July 21, 2007
1340 .Ed
1341 .Pp
1342 See also
1343 .Sx \&Dt
1344 and
1345 .Sx \&Os .
1346 .
1347 .Ss \&Dl
1348 One-line intended display. This is formatted as literal text and is
1349 useful for commands and invocations. It is followed by a newline.
1350 .Pp
1351 Examples:
1352 .Bd -literal -offset indent
1353 \&.Dl % mandoc mdoc.7 | less
1354 .Ed
1355 .Pp
1356 See also
1357 .Sx \&Bd
1358 and
1359 .Sx \&D1 .
1360 .
1361 .Ss \&Do
1362 Begins a block enclosed by double quotes. Does not have any head
1363 arguments.
1364 .Pp
1365 Examples:
1366 .Bd -literal -offset indent
1367 \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
1368 .Ed
1369 .Pp
1370 See also
1371 .Sx \&Dq .
1372 .
1373 .Ss \&Dq
1374 Encloses its arguments in double quotes.
1375 .Pp
1376 Examples:
1377 .Bd -literal -offset indent
1378 \&.Dq April is the cruellest month
1379 \e(em T.S. Eliot
1380 .Ed
1381 .Pp
1382 See also
1383 .Sx \&Do .
1384 .
1385 .Ss \&Dt
1386 Document title. This is the mandatory second macro of any
1387 .Nm
1388 file. Its calling syntax is as follows:
1389 .Pp
1390 .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
1391 .Pp
1392 Its arguments are as follows:
1393 .Bl -tag -width Ds -offset Ds
1394 .It Cm title
1395 The document's title (name). This should be capitalised and is
1396 required.
1397 .It Cm section
1398 The manual section. This may be one of
1399 .Ar 1
1400 .Pq utilities ,
1401 .Ar 2
1402 .Pq system calls ,
1403 .Ar 3
1404 .Pq libraries ,
1405 .Ar 3p
1406 .Pq Perl libraries ,
1407 .Ar 4
1408 .Pq devices ,
1409 .Ar 5
1410 .Pq file formats ,
1411 .Ar 6
1412 .Pq games ,
1413 .Ar 7
1414 .Pq miscellaneous ,
1415 .Ar 8
1416 .Pq system utilities ,
1417 .Ar 9
1418 .Pq kernel functions ,
1419 .Ar X11
1420 .Pq X Window System ,
1421 .Ar X11R6
1422 .Pq X Window System ,
1423 .Ar unass
1424 .Pq unassociated ,
1425 .Ar local
1426 .Pq local system ,
1427 .Ar draft
1428 .Pq draft manual ,
1429 or
1430 .Ar paper
1431 .Pq paper .
1432 It is also required and should correspond to the manual's filename
1433 suffix.
1434 .It Cm volume
1435 This overrides the volume inferred from
1436 .Ar section .
1437 This field is optional, and if specified, must be one of
1438 .Ar USD
1439 .Pq users' supplementary documents ,
1440 .Ar PS1
1441 .Pq programmers' supplementary documents ,
1442 .Ar AMD
1443 .Pq administrators' supplementary documents ,
1444 .Ar SMM
1445 .Pq system managers' manuals ,
1446 .Ar URM
1447 .Pq users' reference manuals ,
1448 .Ar PRM
1449 .Pq programmers' reference manuals ,
1450 .Ar KM
1451 .Pq kernel manuals ,
1452 .Ar IND
1453 .Pq master index ,
1454 .Ar MMI
1455 .Pq master index ,
1456 .Ar LOCAL
1457 .Pq local manuals ,
1458 .Ar LOC
1459 .Pq local manuals ,
1460 or
1461 .Ar CON
1462 .Pq contributed manuals .
1463 .It Cm arch
1464 This specifies a specific relevant architecture. If
1465 .Cm volume
1466 is not provided, it may be used in its place, else it may be used
1467 subsequent that. It, too, is optional. It must be one of
1468 .Ar alpha ,
1469 .Ar amd64 ,
1470 .Ar amiga ,
1471 .Ar arc ,
1472 .Ar arm ,
1473 .Ar armish ,
1474 .Ar aviion ,
1475 .Ar hp300 ,
1476 .Ar hppa ,
1477 .Ar hppa64 ,
1478 .Ar i386 ,
1479 .Ar landisk ,
1480 .Ar luna88k ,
1481 .Ar mac68k ,
1482 .Ar macppc ,
1483 .Ar mvme68k ,
1484 .Ar mvme88k ,
1485 .Ar mvmeppc ,
1486 .Ar pmax ,
1487 .Ar sgi ,
1488 .Ar socppc ,
1489 .Ar sparc ,
1490 .Ar sparc64 ,
1491 .Ar sun3 ,
1492 .Ar vax ,
1493 or
1494 .Ar zaurus .
1495 .El
1496 .Pp
1497 Examples:
1498 .Bd -literal -offset indent
1499 \&.Dt FOO 1
1500 \&.Dt FOO 4 KM
1501 \&.Dt FOO 9 i386
1502 \&.Dt FOO 9 KM i386
1503 .Ed
1504 .Pp
1505 See also
1506 .Sx \&Dd
1507 and
1508 .Sx \&Os .
1509 .
1510 .Ss \&Dv
1511 Defined variables such as preprocessor constants.
1512 .Pp
1513 Examples:
1514 .Bd -literal -offset indent
1515 \&.Dv BUFSIZ
1516 \&.Dv STDOUT_FILENO
1517 .Ed
1518 .Pp
1519 See also
1520 .Sx \&Er .
1521 .
1522 .Ss \&Dx
1523 Format the DragonFly BSD version provided as an argument, or a default
1524 value if no argument is provided.
1525 .Pp
1526 Examples:
1527 .Bd -literal -offset indent
1528 \&.Dx 2.4.1
1529 \&.Dx
1530 .Ed
1531 .Pp
1532 See also
1533 .Sx \&At ,
1534 .Sx \&Bsx ,
1535 .Sx \&Bx ,
1536 .Sx \&Fx ,
1537 .Sx \&Nx ,
1538 .Sx \&Ox ,
1539 and
1540 .Sx \&Ux .
1541 .
1542 .Ss \&Ec
1543 .Ss \&Ed
1544 .Ss \&Ef
1545 .Ss \&Ek
1546 .Ss \&El
1547 .Ss \&Em
1548 Denotes text that should be emphasised. Note that this is a
1549 presentation term and should not be used for stylistically decorating
1550 technical terms.
1551 .Pp
1552 Examples:
1553 .Bd -literal -offset indent
1554 \&.Ed Warnings!
1555 \&.Ed Remarks :
1556 .Ed
1557 .
1558 .Ss \&En
1559 .Ss \&Eo
1560 .Ss \&Er
1561 Error constants (suggested for use only in section two manuals).
1562 .Pp
1563 Examples:
1564 .Bd -literal -offset indent
1565 \&.Er EPERM
1566 \&.Er ENOENT
1567 .Ed
1568 .Pp
1569 See also
1570 .Sx \&Dv .
1571 .
1572 .Ss \&Es
1573 .
1574 .Ss \&Ev
1575 Environmental variables such as those specified in
1576 .Xr environ 7 .
1577 .Pp
1578 Examples:
1579 .Bd -literal -offset indent
1580 \&.Ev DISPLAY
1581 \&.Ev PATH
1582 .Ed
1583 .
1584 .Ss \&Ex
1585 Inserts text regarding a utility's exit values. This macro must have
1586 first the
1587 .Fl std
1588 argument specified, then an optional
1589 .Ar utility .
1590 If
1591 .Ar utility
1592 is not provided, the document's name as stipulated in
1593 .Sx \&Nm
1594 is provided.
1595 .Ss \&Fa
1596 .Ss \&Fc
1597 .Ss \&Fd
1598 .Ss \&Fl
1599 .Ss \&Fn
1600 .Ss \&Fo
1601 .Ss \&Fr
1602 .Ss \&Ft
1603 .Ss \&Fx
1604 Format the FreeBSD version provided as an argument, or a default value
1605 if no argument is provided.
1606 .Pp
1607 Examples:
1608 .Bd -literal -offset indent
1609 \&.Fx 7.1
1610 \&.Fx
1611 .Ed
1612 .Pp
1613 See also
1614 .Sx \&At ,
1615 .Sx \&Bsx ,
1616 .Sx \&Bx ,
1617 .Sx \&Dx ,
1618 .Sx \&Nx ,
1619 .Sx \&Ox ,
1620 and
1621 .Sx \&Ux .
1622 .
1623 .Ss \&Hf
1624 .Ss \&Ic
1625 .Ss \&In
1626 .Ss \&It
1627 .Ss \&Lb
1628 .Ss \&Li
1629 .Ss \&Lk
1630 Format a hyperlink. The calling syntax is as follows:
1631 .Pp
1632 .D1 \. Ns Sx \&Lk Cm uri Op Cm name
1633 .Pp
1634 Examples:
1635 .Bd -literal -offset indent
1636 \&.Lk http://bsd.lv "The BSD.lv Project"
1637 \&.Lk http://bsd.lv
1638 .Ed
1639 .Pp
1640 See also
1641 .Sx \&Mt .
1642 .
1643 .Ss \&Lp
1644 .Ss \&Ms
1645 .Ss \&Mt
1646 .Ss \&Nd
1647 .Ss \&Nm
1648 .Ss \&No
1649 .Ss \&Ns
1650 .Ss \&Nx
1651 Format the NetBSD version provided as an argument, or a default value if
1652 no argument is provided.
1653 .Pp
1654 Examples:
1655 .Bd -literal -offset indent
1656 \&.Nx 5.01
1657 \&.Nx
1658 .Ed
1659 .Pp
1660 See also
1661 .Sx \&At ,
1662 .Sx \&Bsx ,
1663 .Sx \&Bx ,
1664 .Sx \&Dx ,
1665 .Sx \&Fx ,
1666 .Sx \&Ox ,
1667 and
1668 .Sx \&Ux .
1669 .
1670 .Ss \&Oc
1671 .Ss \&Oo
1672 .Ss \&Op
1673 .Ss \&Os
1674 Document operating system version. This is the mandatory third macro of
1675 any
1676 .Nm
1677 file. Its calling syntax is as follows:
1678 .Pp
1679 .D1 \. Ns Sx \&Os Op Cm system
1680 .Pp
1681 The optional
1682 .Cm system
1683 parameter specifies the relevant operating system or environment. Left
1684 unspecified, it defaults to the local operating system version. This is
1685 the suggested form.
1686 .Pp
1687 Examples:
1688 .Bd -literal -offset indent
1689 \&.Os
1690 \&.Os KTH/CSC/TCS
1691 \&.Os BSD 4.3
1692 .Ed
1693 .Pp
1694 See also
1695 .Sx \&Dd
1696 and
1697 .Sx \&Dt .
1698 .
1699 .Ss \&Ot
1700 Unknown usage.
1701 .Pp
1702 .Em Remarks :
1703 this macro has been deprecated.
1704 .
1705 .Ss \&Ox
1706 Format the OpenBSD version provided as an argument, or a default value
1707 if no argument is provided.
1708 .Pp
1709 Examples:
1710 .Bd -literal -offset indent
1711 \&.Ox 4.5
1712 \&.Ox
1713 .Ed
1714 .Pp
1715 See also
1716 .Sx \&At ,
1717 .Sx \&Bsx ,
1718 .Sx \&Bx ,
1719 .Sx \&Dx ,
1720 .Sx \&Fx ,
1721 .Sx \&Nx ,
1722 and
1723 .Sx \&Ux .
1724 .
1725 .Ss \&Pa
1726 .Ss \&Pc
1727 .Ss \&Pf
1728 .Ss \&Po
1729 .Ss \&Pp
1730 .Ss \&Pq
1731 .Ss \&Qc
1732 .Ss \&Ql
1733 .Ss \&Qo
1734 .Ss \&Qq
1735 .
1736 .Ss \&Re
1737 Closes a
1738 .Sx \&Rs
1739 block. Does not have any tail arguments.
1740 .
1741 .Ss \&Rs
1742 Begins a bibliographic
1743 .Pq Dq reference
1744 block. Does not have any head arguments. The block macro may only
1745 contain
1746 .Sx \&%A ,
1747 .Sx \&%B ,
1748 .Sx \&%C ,
1749 .Sx \&%D ,
1750 .Sx \&%I ,
1751 .Sx \&%J ,
1752 .Sx \&%N ,
1753 .Sx \&%O ,
1754 .Sx \&%P ,
1755 .Sx \&%Q ,
1756 .Sx \&%R ,
1757 .Sx \&%T ,
1758 and
1759 .Sx \&%V
1760 child macros (at least one must be specified).
1761 .Pp
1762 Examples:
1763 .Bd -literal -offset indent
1764 \&.Rs
1765 \&.%A J. E. Hopcroft
1766 \&.%A J. D. Ullman
1767 \&.%B Introduction to Automata Theory, Languages, and Computation
1768 \&.%I Addison-Wesley
1769 \&.%C Reading, Massachusettes
1770 \&.%D 1979
1771 \&.Re
1772 .Ed
1773 .Pp
1774 If an
1775 .Sx \&Rs
1776 block is used within a SEE ALSO section, a vertical space is asserted
1777 before the rendered output, else the block continues on the current
1778 line.
1779 .
1780 .Ss \&Rv
1781 .Ss \&Sc
1782 .Ss \&Sh
1783 .Ss \&Sm
1784 .Ss \&So
1785 .Ss \&Sq
1786 .Ss \&Ss
1787 .Ss \&St
1788 .Ss \&Sx
1789 .Ss \&Sy
1790 .Ss \&Tn
1791 .Ss \&Ud
1792 .Ss \&Ux
1793 Format the UNIX name. Accepts no argument.
1794 .Pp
1795 Examples:
1796 .Bd -literal -offset indent
1797 \&.Ux
1798 .Ed
1799 .Pp
1800 See also
1801 .Sx \&At ,
1802 .Sx \&Bsx ,
1803 .Sx \&Bx ,
1804 .Sx \&Dx ,
1805 .Sx \&Fx ,
1806 .Sx \&Nx ,
1807 and
1808 .Sx \&Ox .
1809 .
1810 .Ss \&Va
1811 .Ss \&Vt
1812 .Ss \&Xc
1813 .Ss \&Xo
1814 .Ss \&Xr
1815 .Ss \&br
1816 .Ss \&sp
1817 .
1818 .
1819 .Sh COMPATIBILITY
1820 This section documents compatibility with other roff implementations, at
1821 this time limited to
1822 .Xr groff 1 .
1823 The term
1824 .Qq historic groff
1825 refers to those versions before the
1826 .Pa doc.tmac
1827 file re-write
1828 .Pq somewhere between 1.15 and 1.19 .
1829 .
1830 .Pp
1831 .Bl -dash -compact
1832 .It
1833 .Xr groff 1
1834 behaves strangely (even between versions) when specifying
1835 .Sq \ef
1836 escapes within line-macro scopes. These aberrations have been
1837 normalised.
1838 .It
1839 Negative scaling units are now truncated to zero instead of creating
1840 interesting conditions, such as with
1841 .Sx \&sp
1842 .Cm \-1i .
1843 Furthermore, the
1844 .Sq f
1845 scaling unit, while accepted, is rendered as the default unit.
1846 .It
1847 In quoted literals, groff allowed pair-wise double-quotes to produce a
1848 standalone double-quote in formatted output. This idiosyncratic
1849 behaviour is no longer applicable.
1850 .It
1851 Display types
1852 .Sx \&Bd
1853 .Fl center
1854 and
1855 .Fl right
1856 are aliases for
1857 .Fl left .
1858 The
1859 .Fl file Ar file
1860 argument is ignored. Since text is not right-justified,
1861 .Fl ragged
1862 and
1863 .Fl filled
1864 are aliases, as are
1865 .Fl literal
1866 and
1867 .Fl unfilled .
1868 .It
1869 Blocks of whitespace are stripped from both macro and free-form text
1870 lines (except when in literal mode), while groff would retain whitespace
1871 in free-form text lines.
1872 .It
1873 Historic groff has many un-callable macros. Most of these (excluding
1874 some block-level macros) are now callable, conforming to the
1875 non-historic groff version.
1876 .It
1877 The vertical bar
1878 .Sq \(ba
1879 made historic groff
1880 .Qq go orbital
1881 but is a proper delimiter in this implementation.
1882 .It
1883 .Sx \&It
1884 .Fl nested
1885 is assumed for all lists (it wasn't in historic groff): any list may be
1886 nested and
1887 .Fl enum
1888 lists will restart the sequence only for the sub-list.
1889 .It
1890 Some manuals use
1891 .Sx \&Li
1892 incorrectly by following it with a reserved character and expecting the
1893 delimiter to render. This is not supported.
1894 .It
1895 In groff, the
1896 .Sx \&Fo
1897 macro only produces the first parameter. This is no longer the case.
1898 .El
1899 .
1900 .
1901 .Sh SEE ALSO
1902 .Xr mandoc 1 ,
1903 .Xr mandoc_char 7
1904 .
1905 .
1906 .Sh AUTHORS
1907 The
1908 .Nm
1909 reference was written by
1910 .An Kristaps Dzonsons Aq kristaps@kth.se .
1911 .\"
1912 .\" XXX: this really isn't the place for these caveats.
1913 .\" .
1914 .\" .
1915 .\" .Sh CAVEATS
1916 .\" There are many ambiguous parts of mdoc.
1917 .\" .
1918 .\" .Pp
1919 .\" .Bl -dash -compact
1920 .\" .It
1921 .\" .Sq \&Fa
1922 .\" should be
1923 .\" .Sq \&Va
1924 .\" as function arguments are variables.
1925 .\" .It
1926 .\" .Sq \&Ft
1927 .\" should be
1928 .\" .Sq \&Vt
1929 .\" as function return types are still types. Furthermore, the
1930 .\" .Sq \&Ft
1931 .\" should be removed and
1932 .\" .Sq \&Fo ,
1933 .\" which ostensibly follows it, should follow the same convention as
1934 .\" .Sq \&Va .
1935 .\" .It
1936 .\" .Sq \&Va
1937 .\" should formalise that only one or two arguments are acceptable: a
1938 .\" variable name and optional, preceding type.
1939 .\" .It
1940 .\" .Sq \&Fd
1941 .\" is ambiguous. It's commonly used to indicate an include file in the
1942 .\" synopsis section.
1943 .\" .Sq \&In
1944 .\" should be used, instead.
1945 .\" .It
1946 .\" Only the
1947 .\" .Sq \-literal
1948 .\" argument to
1949 .\" .Sq \&Bd
1950 .\" makes sense. The remaining ones should be removed.
1951 .\" .It
1952 .\" The
1953 .\" .Sq \&Xo
1954 .\" and
1955 .\" .Sq \&Xc
1956 .\" macros should be deprecated.
1957 .\" .It
1958 .\" The
1959 .\" .Sq \&Dt
1960 .\" macro lacks clarity. It should be absolutely clear which title will
1961 .\" render when formatting the manual page.
1962 .\" .It
1963 .\" A
1964 .\" .Sq \&Lx
1965 .\" should be provided for Linux (\(`a la
1966 .\" .Sq \&Ox ,
1967 .\" .Sq \&Nx
1968 .\" etc.).
1969 .\" .It
1970 .\" There's no way to refer to references in
1971 .\" .Sq \&Rs/Re
1972 .\" blocks.
1973 .\" .It
1974 .\" The \-split and \-nosplit dictates via
1975 .\" .Sq \&An
1976 .\" are re-set when entering and leaving the AUTHORS section.
1977 .\" .El
1978 .\" .