| blob | e5374ffd25d73de875d78b8a482d48dbe19dff40 |
1 .\" $Id: mdoc.7,v 1.84 2010/02/17 19:22:50 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 February 20, 2010
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 .Pp
423 See
424 .Sx \&Nm
425 and
426 .Sx \&Nd .
427 .
428 .It Em LIBRARY
429 The name of the library containing the documented material, which is
430 assumed to be a function in a section 2 or 3 manual. The syntax for
431 this is as follows:
432 .Bd -literal -offset indent
433 \&.Lb libarm
434 .Ed
435 .Pp
436 See
437 .Sx \&Lb .
438 .
439 .It Em SYNOPSIS
440 Documents the utility invocation syntax, function call syntax, or device
441 configuration.
442 .Pp
443 For the first, utilities (sections 1, 6, and 8), this is
444 generally structured as follows:
445 .Bd -literal -offset indent
446 \&.Nm foo
447 \&.Op Fl v
448 \&.Op Fl o Ar file
449 \&.Op Ar
450 \&.Nm bar
451 \&.Op Fl v
452 \&.Op Fl o Ar file
453 \&.Op Ar
454 .Ed
455 .Pp
456 For the second, function calls (sections 2, 3, 9):
457 .Bd -literal -offset indent
458 \&.Vt extern const char *global;
459 \&.In header.h
460 \&.Ft "char *"
461 \&.Fn foo "const char *src"
462 \&.Ft "char *"
463 \&.Fn bar "const char *src"
464 .Ed
465 .Pp
466 And for the third, configurations (section 4):
467 .Bd -literal -offset indent
468 \&.Cd \*qit* at isa? port 0x2e\*q
469 \&.Cd \*qit* at isa? port 0x4e\*q
470 .Ed
471 .Pp
472 Manuals not in these sections generally don't need a
473 .Em SYNOPSIS .
474 .Pp
475 See
476 .Sx \&Op ,
477 .Sx \&Cd ,
478 .Sx \&Fn ,
479 .Sx \&Ft ,
480 and
481 .Sx \&Vt .
482 .
483 .It Em DESCRIPTION
484 This expands upon the brief, one-line description in
485 .Em NAME .
486 It usually contains a break-down of the options (if documenting a
487 command), such as:
488 .Bd -literal -offset indent
489 The arguments are as follows:
490 \&.Bl \-tag \-width Ds
491 \&.It Fl v
492 Print verbose information.
493 \&.El
494 .Ed
495 .Pp
496 Manuals not documenting a command won't include the above fragment.
497 .
498 .It Em IMPLEMENTATION NOTES
499 Implementation-specific notes should be kept here. This is useful when
500 implementing standard functions that may have side effects or notable
501 algorithmic implications.
502 .
503 .It Em EXIT STATUS
504 Command exit status for section 1, 6, and 8 manuals. This section is
505 the dual of
506 .Em RETURN VALUES ,
507 which is used for functions. Historically, this information was
508 described in
509 .Em DIAGNOSTICS ,
510 a practise that is now discouraged.
511 .Pp
512 See
513 .Sx \&Ex .
514 .
515 .It Em RETURN VALUES
516 This section is the dual of
517 .Em EXIT STATUS ,
518 which is used for commands. It documents the return values of functions
519 in sections 2, 3, and 9.
520 .Pp
521 See
522 .Sx \&Rv .
523 .
524 .It Em ENVIRONMENT
525 Documents any usages of environment variables, e.g.,
526 .Xr environ 7 .
527 .Pp
528 See
529 .Sx \&Ev .
530 .
531 .It Em FILES
532 Documents files used. It's helpful to document both the file and a
533 short description of how the file is used (created, modified, etc.).
534 .Pp
535 See
536 .Sx \&Pa .
537 .
538 .It Em EXAMPLES
539 Example usages. This often contains snippets of well-formed,
540 well-tested invocations. Make doubly sure that your examples work
541 properly!
542 .
543 .It Em DIAGNOSTICS
544 Documents error conditions. This is most useful in section 4 manuals.
545 Historically, this section was used in place of
546 .Em EXIT STATUS
547 for manuals in sections 1, 6, and 8; however, this practise is
548 discouraged.
549 .Pp
550 See
551 .Sx \&Bl
552 .Fl diag .
553 .
554 .It Em ERRORS
555 Documents error handling in sections 2, 3, and 9.
556 .Pp
557 See
558 .Sx \&Er .
559 .
560 .It Em SEE ALSO
561 References other manuals with related topics. This section should exist
562 for most manuals. Cross-references should conventionally be ordered
563 first by section, then alphabetically.
564 .Pp
565 See
566 .Sx \&Xr .
567 .
568 .It Em STANDARDS
569 References any standards implemented or used. If not adhering to any
570 standards, the
571 .Em HISTORY
572 section should be used instead.
573 .Pp
574 See
575 .Sx \&St .
576 .
577 .It Em HISTORY
578 The history of any manual without a
579 .Em STANDARDS
580 section should be described in this section.
581 .
582 .It Em AUTHORS
583 Credits to authors, if applicable, should appear in this section.
584 Authors should generally be noted by both name and an e-mail address.
585 .Pp
586 See
587 .Sx \&An .
588 .
589 .It Em CAVEATS
590 Explanations of common misuses and misunderstandings should be explained
591 in this section.
592 .
593 .It Em BUGS
594 Extant bugs should be described in this section.
595 .
596 .It Em SECURITY CONSIDERATIONS
597 Documents any security precautions that operators should consider.
598 .
599 .El
600 .
601 .
602 .Sh MACRO SYNTAX
603 Macros are one to three three characters in length and begin with a
604 control character ,
605 .Sq \&. ,
606 at the beginning of the line. An arbitrary amount of whitespace may
607 sit between the control character and the macro name. Thus, the
608 following are equivalent:
609 .Bd -literal -offset indent
610 \&.Pp
611 \&.\ \ \ \&Pp
612 .Ed
613 .
614 .Pp
615 The syntax of a macro depends on its classification. In this section,
616 .Sq \-arg
617 refers to macro arguments, which may be followed by zero or more
618 .Sq parm
619 parameters;
620 .Sq \&Yo
621 opens the scope of a macro; and if specified,
622 .Sq \&Yc
623 closes it out.
624 .
625 .Pp
626 The
627 .Em Callable
628 column indicates that the macro may be called subsequent to the initial
629 line-macro. If a macro is not callable, then its invocation after the
630 initial line macro is interpreted as opaque text, such that
631 .Sq \&.Fl \&Sh
632 produces
633 .Sq Fl \&Sh .
634 .
635 .Pp
636 The
637 .Em Parsable
638 column indicates whether the macro may be followed by further
639 (ostensibly callable) macros. If a macro is not parsable, subsequent
640 macro invocations on the line will be interpreted as opaque text.
641 .
642 .Pp
643 The
644 .Em Scope
645 column, if applicable, describes closure rules.
646 .
647 .
648 .Ss Block full-explicit
649 Multi-line scope closed by an explicit closing macro. All macros
650 contains bodies; only
651 .Sx \&Bf
652 contains a head.
653 .Bd -literal -offset indent
654 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
655 \(lBbody...\(rB
656 \&.Yc
657 .Ed
658 .
659 .Pp
660 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
661 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
662 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
663 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
664 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
665 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
666 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
667 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
668 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
669 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
670 .El
671 .
672 .
673 .Ss Block full-implicit
674 Multi-line scope closed by end-of-file or implicitly by another macro.
675 All macros have bodies; some
676 .Po
677 .Sx \&It Fl bullet ,
678 .Fl hyphen ,
679 .Fl dash ,
680 .Fl enum ,
681 .Fl item
682 .Pc
683 don't have heads; only one
684 .Po
685 .Sx \&It Fl column
686 .Pc
687 has multiple heads.
688 .Bd -literal -offset indent
689 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
690 \(lBbody...\(rB
691 .Ed
692 .
693 .Pp
694 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
695 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
696 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
697 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
698 .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
699 .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
700 .El
701 .
702 .
703 .Ss Block partial-explicit
704 Like block full-explicit, but also with single-line scope. Each
705 has at least a body and, in limited circumstances, a head
706 .Po
707 .Sx \&Fo ,
708 .Sx \&Eo
709 .Pc
710 and/or tail
711 .Pq Sx \&Ec .
712 .Bd -literal -offset indent
713 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
714 \(lBbody...\(rB
715 \&.Yc \(lBtail...\(rB
717 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
718 \(lBbody...\(rB \&Yc \(lBtail...\(rB
719 .Ed
720 .
721 .Pp
722 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
723 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
724 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
725 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
726 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
727 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
728 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
729 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
730 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
731 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
732 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
733 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
734 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
735 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
736 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
737 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
738 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
739 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
740 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
741 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
742 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
743 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
744 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
745 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
746 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
747 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
748 .El
749 .
750 .
751 .Ss Block partial-implicit
752 Like block full-implicit, but with single-line scope closed by
753 .Sx Reserved Characters
754 or end of line.
755 .Bd -literal -offset indent
756 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
757 .Ed
758 .
759 .Pp
760 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
761 .It Em Macro Ta Em Callable Ta Em Parsable
762 .It Sx \&Aq Ta Yes Ta Yes
763 .It Sx \&Bq Ta Yes Ta Yes
764 .It Sx \&Brq Ta Yes Ta Yes
765 .It Sx \&D1 Ta \&No Ta \&Yes
766 .It Sx \&Dl Ta \&No Ta Yes
767 .It Sx \&Dq Ta Yes Ta Yes
768 .It Sx \&Op Ta Yes Ta Yes
769 .It Sx \&Pq Ta Yes Ta Yes
770 .It Sx \&Ql Ta Yes Ta Yes
771 .It Sx \&Qq Ta Yes Ta Yes
772 .It Sx \&Sq Ta Yes Ta Yes
773 .It Sx \&Vt Ta Yes Ta Yes
774 .El
775 .Pp
776 Note that the
777 .Sx \&Vt
778 macro is a
779 .Sx Block partial-implicit
780 only when invoked as the first macro
781 in a SYNOPSIS section line, else it is
782 .Sx In-line .
783 .
784 .
785 .Ss In-line
786 Closed by
787 .Sx Reserved Characters ,
788 end of line, fixed argument lengths, and/or subsequent macros. In-line
789 macros have only text children. If a number (or inequality) of
790 arguments is
791 .Pq n ,
792 then the macro accepts an arbitrary number of arguments.
793 .Bd -literal -offset indent
794 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
796 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
798 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
799 .Ed
800 .
801 .Pp
802 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
803 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
804 .It Sx \&%A Ta \&No Ta \&No Ta >0
805 .It Sx \&%B Ta \&No Ta \&No Ta >0
806 .It Sx \&%C Ta \&No Ta \&No Ta >0
807 .It Sx \&%D Ta \&No Ta \&No Ta >0
808 .It Sx \&%I Ta \&No Ta \&No Ta >0
809 .It Sx \&%J Ta \&No Ta \&No Ta >0
810 .It Sx \&%N Ta \&No Ta \&No Ta >0
811 .It Sx \&%O Ta \&No Ta \&No Ta >0
812 .It Sx \&%P Ta \&No Ta \&No Ta >0
813 .It Sx \&%Q Ta \&No Ta \&No Ta >0
814 .It Sx \&%R Ta \&No Ta \&No Ta >0
815 .It Sx \&%T Ta \&No Ta \&No Ta >0
816 .It Sx \&%U Ta \&No Ta \&No Ta >0
817 .It Sx \&%V Ta \&No Ta \&No Ta >0
818 .It Sx \&Ad Ta Yes Ta Yes Ta n
819 .It Sx \&An Ta Yes Ta Yes Ta n
820 .It Sx \&Ap Ta Yes Ta Yes Ta 0
821 .It Sx \&Ar Ta Yes Ta Yes Ta n
822 .It Sx \&At Ta Yes Ta Yes Ta 1
823 .It Sx \&Bsx Ta Yes Ta Yes Ta n
824 .It Sx \&Bt Ta \&No Ta \&No Ta 0
825 .It Sx \&Bx Ta Yes Ta Yes Ta n
826 .It Sx \&Cd Ta Yes Ta Yes Ta >0
827 .It Sx \&Cm Ta Yes Ta Yes Ta n
828 .It Sx \&Db Ta \&No Ta \&No Ta 1
829 .It Sx \&Dd Ta \&No Ta \&No Ta >0
830 .It Sx \&Dt Ta \&No Ta \&No Ta n
831 .It Sx \&Dv Ta Yes Ta Yes Ta n
832 .It Sx \&Dx Ta Yes Ta Yes Ta n
833 .It Sx \&Em Ta Yes Ta Yes Ta >0
834 .It Sx \&En Ta \&No Ta \&No Ta 0
835 .It Sx \&Er Ta Yes Ta Yes Ta >0
836 .It Sx \&Es Ta \&No Ta \&No Ta 0
837 .It Sx \&Ev Ta Yes Ta Yes Ta n
838 .It Sx \&Ex Ta \&No Ta \&No Ta n
839 .It Sx \&Fa Ta Yes Ta Yes Ta n
840 .It Sx \&Fd Ta \&No Ta \&No Ta >0
841 .It Sx \&Fl Ta Yes Ta Yes Ta n
842 .It Sx \&Fn Ta Yes Ta Yes Ta >0
843 .It Sx \&Fr Ta \&No Ta \&No Ta n
844 .It Sx \&Ft Ta Yes Ta Yes Ta n
845 .It Sx \&Fx Ta Yes Ta Yes Ta n
846 .It Sx \&Hf Ta \&No Ta \&No Ta n
847 .It Sx \&Ic Ta Yes Ta Yes Ta >0
848 .It Sx \&In Ta \&No Ta \&No Ta n
849 .It Sx \&Lb Ta \&No Ta \&No Ta 1
850 .It Sx \&Li Ta Yes Ta Yes Ta n
851 .It Sx \&Lk Ta Yes Ta Yes Ta n
852 .It Sx \&Lp Ta \&No Ta \&No Ta 0
853 .It Sx \&Ms Ta Yes Ta Yes Ta >0
854 .It Sx \&Mt Ta Yes Ta Yes Ta >0
855 .It Sx \&Nm Ta Yes Ta Yes Ta n
856 .It Sx \&No Ta Yes Ta Yes Ta 0
857 .It Sx \&Ns Ta Yes Ta Yes Ta 0
858 .It Sx \&Nx Ta Yes Ta Yes Ta n
859 .It Sx \&Os Ta \&No Ta \&No Ta n
860 .It Sx \&Ot Ta \&No Ta \&No Ta n
861 .It Sx \&Ox Ta Yes Ta Yes Ta n
862 .It Sx \&Pa Ta Yes Ta Yes Ta n
863 .It Sx \&Pf Ta \&No Ta Yes Ta 1
864 .It Sx \&Pp Ta \&No Ta \&No Ta 0
865 .It Sx \&Rv Ta \&No Ta \&No Ta n
866 .It Sx \&Sm Ta \&No Ta \&No Ta 1
867 .It Sx \&St Ta \&No Ta Yes Ta 1
868 .It Sx \&Sx Ta Yes Ta Yes Ta >0
869 .It Sx \&Sy Ta Yes Ta Yes Ta >0
870 .It Sx \&Tn Ta Yes Ta Yes Ta >0
871 .It Sx \&Ud Ta \&No Ta \&No Ta 0
872 .It Sx \&Ux Ta Yes Ta Yes Ta n
873 .It Sx \&Va Ta Yes Ta Yes Ta n
874 .It Sx \&Vt Ta Yes Ta Yes Ta >0
875 .It Sx \&Xr Ta Yes Ta Yes Ta >0
876 .It Sx \&br Ta \&No Ta \&No Ta 0
877 .It Sx \&sp Ta \&No Ta \&No Ta 1
878 .El
879 .
880 .
881 .Sh REFERENCE
882 This section is a canonical reference of all macros, arranged
883 alphabetically. For the scoping of individual macros, see
884 .Sx MACRO SYNTAX .
885 .
886 .Ss \&%A
887 Author name of an
888 .Sx \&Rs
889 block. Multiple authors should each be accorded their own
890 .Sx \%%A
891 line. Author names should be ordered with full or abbreviated
892 forename(s) first, then full surname.
893 .
894 .Ss \&%B
895 Book title of an
896 .Sx \&Rs
897 block. This macro may also be used in a non-bibliographic context when
898 referring to book titles.
899 .
900 .Ss \&%C
901 Publication city or location of an
902 .Sx \&Rs
903 block.
904 .Pp
905 .Em Remarks :
906 this macro is not implemented in
907 .Xr groff 1 .
908 .
909 .Ss \&%D
910 Publication date of an
911 .Sx \&Rs
912 block. This should follow the reduced or canonical form syntax
913 described in
914 .Sx Dates .
915 .
916 .Ss \&%I
917 Publisher or issuer name of an
918 .Sx \&Rs
919 block.
920 .
921 .Ss \&%J
922 Journal name of an
923 .Sx \&Rs
924 block.
925 .
926 .Ss \&%N
927 Issue number (usually for journals) of an
928 .Sx \&Rs
929 block.
930 .
931 .Ss \&%O
932 Optional information of an
933 .Sx \&Rs
934 block.
935 .
936 .Ss \&%P
937 Book or journal page number of an
938 .Sx \&Rs
939 block.
940 .
941 .Ss \&%Q
942 Institutional author (school, government, etc.) of an
943 .Sx \&Rs
944 block. Multiple institutional authors should each be accorded their own
945 .Sx \&%Q
946 line.
947 .
948 .Ss \&%R
949 Technical report name of an
950 .Sx \&Rs
951 block.
952 .
953 .Ss \&%T
954 Article title of an
955 .Sx \&Rs
956 block. This macro may also be used in a non-bibliographical context
957 when referring to article titles.
958 .
959 .Ss \&%U
960 URI of reference document.
961 .
962 .Ss \&%V
963 Volume number of an
964 .Sx \&Rs
965 block.
966 .
967 .Ss \&Ac
968 Closes an
969 .Sx \&Ao
970 block. Does not have any tail arguments.
971 .
972 .Ss \&Ad
973 Address construct: usually in the context of an computational address in
974 memory, not a physical (post) address.
975 .Pp
976 Examples:
977 .Bd -literal -offset indent
978 \&.Ad [0,$]
979 \&.Ad 0x00000000
980 .Ed
981 .
982 .Ss \&An
983 Author name. This macro may alternatively accepts the following
984 arguments, although these may not be specified along with a parameter:
985 .Bl -tag -width 12n -offset indent
986 .It Fl split
987 Renders a line break before each author listing.
988 .It Fl nosplit
989 The opposite of
990 .Fl split .
991 .El
992 .Pp
993 In the AUTHORS section, the default is not to split the first author
994 listing, but all subsequent author listings, whether or not they're
995 interspersed by other macros or text, are split. Thus, specifying
996 .Fl split
997 will cause the first listing also to be split. If not in the AUTHORS
998 section, the default is not to split.
999 .Pp
1000 Examples:
1001 .Bd -literal -offset indent
1002 \&.An -nosplit
1003 \&.An J. E. Hopcraft ,
1004 \&.An J. D. Ullman .
1005 .Ed
1006 .Pp
1007 .Em Remarks :
1008 the effects of
1009 .Fl split
1010 or
1011 .Fl nosplit
1012 are re-set when entering the AUTHORS section, so if one specifies
1013 .Sx \&An Fl nosplit
1014 in the general document body, it must be re-specified in the AUTHORS
1015 section.
1016 .
1017 .Ss \&Ao
1018 Begins a block enclosed by angled brackets. Does not have any head
1019 arguments.
1020 .Pp
1021 Examples:
1022 .Bd -literal -offset indent
1023 \&.Fl -key= Ns Ao Ar val Ac
1024 .Ed
1025 .Pp
1026 See also
1027 .Sx \&Aq .
1028 .
1029 .Ss \&Ap
1030 Inserts an apostrophe without any surrounding white-space. This is
1031 generally used as a grammatic device when referring to the verb form of
1032 a function:
1033 .Bd -literal -offset indent
1034 \&.Fn execve Ap d
1035 .Ed
1036 .
1037 .Ss \&Aq
1038 Encloses its arguments in angled brackets.
1039 .Pp
1040 Examples:
1041 .Bd -literal -offset indent
1042 \&.Fl -key= Ns Aq Ar val
1043 .Ed
1044 .Pp
1045 .Em Remarks :
1046 this macro is often abused for rendering URIs, which should instead use
1047 .Sx \&Lk
1048 or
1049 .Sx \&Mt ,
1050 or to note pre-processor
1051 .Dq Li #include
1052 statements, which should use
1053 .Sx \&In .
1054 .Pp
1055 See also
1056 .Sx \&Ao .
1057 .
1058 .Ss \&Ar
1059 Command arguments. If an argument is not provided, the string
1060 .Dq file ...
1061 is used as a default.
1062 .Pp
1063 Examples:
1064 .Bd -literal -offset indent
1065 \&.Fl o Ns Ar file1
1066 \&.Ar
1067 \&.Ar arg1 , arg2 .
1068 .Ed
1069 .
1070 .Ss \&At
1071 Formats an AT&T version. Accepts at most one parameter:
1072 .Bl -tag -width 12n -offset indent
1073 .It Cm v[1-7] | 32v
1074 A version of
1075 .At .
1076 .It Cm V[.[1-4]]?
1077 A system version of
1078 .At .
1079 .El
1080 .Pp
1081 Note that these parameters do not begin with a hyphen.
1082 .Pp
1083 Examples:
1084 .Bd -literal -offset indent
1085 \&.At
1086 \&.At V.1
1087 .Ed
1088 .Pp
1089 See also
1090 .Sx \&Bsx ,
1091 .Sx \&Bx ,
1092 .Sx \&Dx ,
1093 .Sx \&Fx ,
1094 .Sx \&Nx ,
1095 .Sx \&Ox ,
1096 and
1097 .Sx \&Ux .
1098 .
1099 .Ss \&Bc
1100 Closes a
1101 .Sx \&Bo
1102 block. Does not have any tail arguments.
1103 .
1104 .Ss \&Bd
1105 Begins a display block. A display is collection of macros or text which
1106 may be collectively offset or justified in a manner different from that
1107 of the enclosing context. By default, the block is preceded by a
1108 vertical space.
1109 .Pp
1110 Each display is associated with a type, which must be one of the
1111 following arguments:
1112 .Bl -tag -width 12n -offset indent
1113 .It Fl ragged
1114 Only left-justify the block.
1115 .It Fl unfilled
1116 Do not justify the block at all.
1117 .It Fl filled
1118 Left- and right-justify the block.
1119 .It Fl literal
1120 Alias for
1121 .Fl unfilled .
1122 .It Fl centered
1123 Centre-justify each line.
1124 .El
1125 .Pp
1126 The type must be provided first. Secondary arguments are as follows:
1127 .Bl -tag -width 12n -offset indent
1128 .It Fl offset Ar width
1129 Offset by the value of
1130 .Ar width ,
1131 which is interpreted as one of the following, specified in order:
1132 .Bl -item
1133 .It
1134 As one of the pre-defined strings
1135 .Ar indent ,
1136 the width of standard indentation;
1137 .Ar indent-two ,
1138 twice
1139 .Ar indent ;
1140 .Ar left ,
1141 which has no effect ;
1142 .Ar right ,
1143 which justifies to the right margin; and
1144 .Ar center ,
1145 which aligns around an imagined centre axis.
1146 .It
1147 As a precalculated width for a named macro. The most popular is the
1148 imaginary macro
1149 .Ar \&Ds ,
1150 which resolves to
1151 .Ar 6n .
1152 .It
1153 As a scaling unit following the syntax described in
1154 .Sx Scaling Widths .
1155 .It
1156 As the calculated string length of the opaque string.
1157 .El
1158 .Pp
1159 If unset, it will revert to the value of
1160 .Ar 8n
1161 as described in
1162 .Sx Scaling Widths .
1163 .It Fl compact
1164 Do not assert a vertical space before the block.
1165 .It Fl file Ar file
1166 Prepend the file
1167 .Ar file
1168 before any text or macros within the block.
1169 .El
1170 .Pp
1171 Examples:
1172 .Bd -literal -offset indent
1173 \&.Bd \-unfilled \-offset two-indent \-compact
1174 Hello world.
1175 \&.Ed
1176 .Ed
1177 .Pp
1178 See also
1179 .Sx \&D1
1180 and
1181 .Sx \&Dl .
1182 .
1183 .Ss \&Bf
1184 .Ss \&Bk
1185 .Ss \&Bl
1186 .\" Begins a list composed of one or more list entries. A list entry is
1187 .\" specified by the
1188 .\" .Sx \&It
1189 .\" macro, which consists of a head and optional body. By default, a list
1190 .\" is preceded by a blank line. A list must specify one of the following
1191 .\" list types:
1192 .\" .Bl -tag -width 12n
1193 .\" .It Fl bullet
1194 .\" A list offset by a bullet. The head of list entries must be empty.
1195 .\" List entry bodies are justified after the bullet.
1196 .\" .It Fl column
1197 .\" A columnated list. The number of columns is specified as arguments to
1198 .\" the
1199 .\" .Sx \&Bl
1200 .\" macro (the deprecated form of following the invocation of
1201 .\" .Fl column
1202 .\" is also accepted). Arguments dictate the width of columns specified in
1203 .\" list entries. List entry bodies must be left empty. Columns specified
1204 .\" in the list entry head are justified to their position in the sequence
1205 .\" of columns.
1206 .\" .It Fl dash
1207 .\" A list offset by a dash (hyphen). The head of list entries must be
1208 .\" empty. List entry bodies are justified past the dash.
1209 .\" .It Fl diag
1210 .\" Like
1211 .\" .Fl inset
1212 .\" lists, but with additional formatting to the head.
1213 .\" .It Fl enum
1214 .\" A list offset by a number indicating list entry position. The head of
1215 .\" list entries must be empty. List entry bodies are justified past the
1216 .\" enumeration.
1217 .\" .It Fl hang
1218 .\" Like
1219 .\" .Fl tag ,
1220 .\" but instead of list bodies justifying to the head on the first line,
1221 .\" they trail the head text.
1222 .\" .It Fl hyphen
1223 .\" Synonym for
1224 .\" .Fl dash .
1225 .\" .It Fl inset
1226 .\" Like
1227 .\" .Fl tag ,
1228 .\" but list entry bodies aren't justified.
1229 .\" .It Fl item
1230 .\" An un-justified list. This produces blocks of text.
1231 .\" .It Fl ohang
1232 .\" List bodies are placed on the line following the head.
1233 .\" .It Fl tag
1234 .\" A list offset by list entry heads. List entry bodies are justified
1235 .\" after the head.
1236 .\" .El
1237 .\" .Pp
1238 .\" More...
1239 .\" .
1240 .Ss \&Bo
1241 Begins a block enclosed by square brackets. Does not have any head
1242 arguments.
1243 .Pp
1244 Examples:
1245 .Bd -literal -offset indent
1246 \&.Bo 1 ,
1247 \&.Dv BUFSIZ Bc
1248 .Ed
1249 .Pp
1250 See also
1251 .Sx \&Bq .
1252 .
1253 .Ss \&Bq
1254 Encloses its arguments in square brackets.
1255 .Pp
1256 Examples:
1257 .Bd -literal -offset indent
1258 \&.Bq 1 , Dv BUFSIZ
1259 .Ed
1260 .Pp
1261 .Em Remarks :
1262 this macro is sometimes abused to emulate optional arguments for
1263 commands; the correct macros to use for this purpose are
1264 .Sx \&Op ,
1265 .Sx \&Oo ,
1266 and
1267 .Sx \&Oc .
1268 .Pp
1269 See also
1270 .Sx \&Bo .
1271 .
1272 .Ss \&Brc
1273 Closes a
1274 .Sx \&Bro
1275 block. Does not have any tail arguments.
1276 .
1277 .Ss \&Bro
1278 Begins a block enclosed by curly braces. Does not have any head
1279 arguments.
1280 .Pp
1281 Examples:
1282 .Bd -literal -offset indent
1283 \&.Bro 1 , ... ,
1284 \&.Va n Brc
1285 .Ed
1286 .Pp
1287 See also
1288 .Sx \&Brq .
1289 .
1290 .Ss \&Brq
1291 Encloses its arguments in curly braces.
1292 .Pp
1293 Examples:
1294 .Bd -literal -offset indent
1295 \&.Brq 1 , ... , Va n
1296 .Ed
1297 .Pp
1298 See also
1299 .Sx \&Bro .
1300 .
1301 .Ss \&Bsx
1302 Format the BSD/OS version provided as an argument, or a default value if
1303 no argument is provided.
1304 .Pp
1305 Examples:
1306 .Bd -literal -offset indent
1307 \&.Bsx 1.0
1308 \&.Bsx
1309 .Ed
1310 .Pp
1311 See also
1312 .Sx \&At ,
1313 .Sx \&Bx ,
1314 .Sx \&Dx ,
1315 .Sx \&Fx ,
1316 .Sx \&Nx ,
1317 .Sx \&Ox ,
1318 and
1319 .Sx \&Ux .
1320 .
1321 .Ss \&Bt
1322 Prints
1323 .Dq is currently in beta test.
1324 .
1325 .Ss \&Bx
1326 Format the BSD version provided as an argument, or a default value if no
1327 argument is provided.
1328 .Pp
1329 Examples:
1330 .Bd -literal -offset indent
1331 \&.Bx 4.4
1332 \&.Bx
1333 .Ed
1334 .Pp
1335 See also
1336 .Sx \&At ,
1337 .Sx \&Bsx ,
1338 .Sx \&Dx ,
1339 .Sx \&Fx ,
1340 .Sx \&Nx ,
1341 .Sx \&Ox ,
1342 and
1343 .Sx \&Ux .
1344 .
1345 .Ss \&Cd
1346 Configuration declaration (suggested for use only in section four
1347 manuals). This denotes strings accepted by
1348 .Xr config 8 .
1349 .Pp
1350 Examples:
1351 .Bd -literal -offset indent
1352 \&.Cd device le0 at scode?
1353 .Ed
1354 .Pp
1355 .Em Remarks :
1356 this macro is commonly abused by using quoted literals to retain
1357 white-space and align consecutive
1358 .Sx \&Cd
1359 declarations. This practise is discouraged.
1360 .
1361 .Ss \&Cm
1362 Command modifiers. Useful when specifying configuration options or
1363 keys.
1364 .Pp
1365 Examples:
1366 .Bd -literal -offset indent
1367 \&.Cm ControlPath
1368 \&.Cm ControlMaster
1369 .Ed
1370 .Pp
1371 See also
1372 .Sx \&Fl .
1373 .
1374 .Ss \&D1
1375 One-line indented display. This is formatted by the default rules and
1376 is useful for simple indented statements. It is followed by a newline.
1377 .Pp
1378 Examples:
1379 .Bd -literal -offset indent
1380 \&.D1 Fl abcdefgh
1381 .Ed
1382 .Pp
1383 See also
1384 .Sx \&Bd
1385 and
1386 .Sx \&Dl .
1387 .
1388 .Ss \&Db
1389 .Ss \&Dc
1390 Closes a
1391 .Sx \&Do
1392 block. Does not have any tail arguments.
1393 .
1394 .Ss \&Dd
1395 Document date. This is the mandatory first macro of any
1396 .Nm
1397 manual. Its calling syntax is as follows:
1398 .Pp
1399 .D1 \. Ns Sx \&Dd Cm date
1400 .Pp
1401 The
1402 .Cm date
1403 field may be either
1404 .Ar $\&Mdocdate$ ,
1405 which signifies the current manual revision date dictated by
1406 .Xr cvs 1 ,
1407 or instead a valid canonical date as specified by
1408 .Sx Dates .
1409 If a date does not conform, the current date is used instead.
1410 .Pp
1411 Examples:
1412 .Bd -literal -offset indent
1413 \&.Dd $\&Mdocdate$
1414 \&.Dd $\&Mdocdate: July 21 2007$
1415 \&.Dd July 21, 2007
1416 .Ed
1417 .Pp
1418 See also
1419 .Sx \&Dt
1420 and
1421 .Sx \&Os .
1422 .
1423 .Ss \&Dl
1424 One-line intended display. This is formatted as literal text and is
1425 useful for commands and invocations. It is followed by a newline.
1426 .Pp
1427 Examples:
1428 .Bd -literal -offset indent
1429 \&.Dl % mandoc mdoc.7 | less
1430 .Ed
1431 .Pp
1432 See also
1433 .Sx \&Bd
1434 and
1435 .Sx \&D1 .
1436 .
1437 .Ss \&Do
1438 Begins a block enclosed by double quotes. Does not have any head
1439 arguments.
1440 .Pp
1441 Examples:
1442 .Bd -literal -offset indent
1443 \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
1444 .Ed
1445 .Pp
1446 See also
1447 .Sx \&Dq .
1448 .
1449 .Ss \&Dq
1450 Encloses its arguments in double quotes.
1451 .Pp
1452 Examples:
1453 .Bd -literal -offset indent
1454 \&.Dq April is the cruellest month
1455 \e(em T.S. Eliot
1456 .Ed
1457 .Pp
1458 See also
1459 .Sx \&Do .
1460 .
1461 .Ss \&Dt
1462 Document title. This is the mandatory second macro of any
1463 .Nm
1464 file. Its calling syntax is as follows:
1465 .Pp
1466 .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
1467 .Pp
1468 Its arguments are as follows:
1469 .Bl -tag -width Ds -offset Ds
1470 .It Cm title
1471 The document's title (name). This should be capitalised and is
1472 required.
1473 .It Cm section
1474 The manual section. This may be one of
1475 .Ar 1
1476 .Pq utilities ,
1477 .Ar 2
1478 .Pq system calls ,
1479 .Ar 3
1480 .Pq libraries ,
1481 .Ar 3p
1482 .Pq Perl libraries ,
1483 .Ar 4
1484 .Pq devices ,
1485 .Ar 5
1486 .Pq file formats ,
1487 .Ar 6
1488 .Pq games ,
1489 .Ar 7
1490 .Pq miscellaneous ,
1491 .Ar 8
1492 .Pq system utilities ,
1493 .Ar 9
1494 .Pq kernel functions ,
1495 .Ar X11
1496 .Pq X Window System ,
1497 .Ar X11R6
1498 .Pq X Window System ,
1499 .Ar unass
1500 .Pq unassociated ,
1501 .Ar local
1502 .Pq local system ,
1503 .Ar draft
1504 .Pq draft manual ,
1505 or
1506 .Ar paper
1507 .Pq paper .
1508 It is also required and should correspond to the manual's filename
1509 suffix.
1510 .It Cm volume
1511 This overrides the volume inferred from
1512 .Ar section .
1513 This field is optional, and if specified, must be one of
1514 .Ar USD
1515 .Pq users' supplementary documents ,
1516 .Ar PS1
1517 .Pq programmers' supplementary documents ,
1518 .Ar AMD
1519 .Pq administrators' supplementary documents ,
1520 .Ar SMM
1521 .Pq system managers' manuals ,
1522 .Ar URM
1523 .Pq users' reference manuals ,
1524 .Ar PRM
1525 .Pq programmers' reference manuals ,
1526 .Ar KM
1527 .Pq kernel manuals ,
1528 .Ar IND
1529 .Pq master index ,
1530 .Ar MMI
1531 .Pq master index ,
1532 .Ar LOCAL
1533 .Pq local manuals ,
1534 .Ar LOC
1535 .Pq local manuals ,
1536 or
1537 .Ar CON
1538 .Pq contributed manuals .
1539 .It Cm arch
1540 This specifies a specific relevant architecture. If
1541 .Cm volume
1542 is not provided, it may be used in its place, else it may be used
1543 subsequent that. It, too, is optional. It must be one of
1544 .Ar alpha ,
1545 .Ar amd64 ,
1546 .Ar amiga ,
1547 .Ar arc ,
1548 .Ar arm ,
1549 .Ar armish ,
1550 .Ar aviion ,
1551 .Ar hp300 ,
1552 .Ar hppa ,
1553 .Ar hppa64 ,
1554 .Ar i386 ,
1555 .Ar landisk ,
1556 .Ar luna88k ,
1557 .Ar mac68k ,
1558 .Ar macppc ,
1559 .Ar mvme68k ,
1560 .Ar mvme88k ,
1561 .Ar mvmeppc ,
1562 .Ar pmax ,
1563 .Ar sgi ,
1564 .Ar socppc ,
1565 .Ar sparc ,
1566 .Ar sparc64 ,
1567 .Ar sun3 ,
1568 .Ar vax ,
1569 or
1570 .Ar zaurus .
1571 .El
1572 .Pp
1573 Examples:
1574 .Bd -literal -offset indent
1575 \&.Dt FOO 1
1576 \&.Dt FOO 4 KM
1577 \&.Dt FOO 9 i386
1578 \&.Dt FOO 9 KM i386
1579 .Ed
1580 .Pp
1581 See also
1582 .Sx \&Dd
1583 and
1584 .Sx \&Os .
1585 .
1586 .Ss \&Dv
1587 Defined variables such as preprocessor constants.
1588 .Pp
1589 Examples:
1590 .Bd -literal -offset indent
1591 \&.Dv BUFSIZ
1592 \&.Dv STDOUT_FILENO
1593 .Ed
1594 .Pp
1595 See also
1596 .Sx \&Er .
1597 .
1598 .Ss \&Dx
1599 Format the DragonFly BSD version provided as an argument, or a default
1600 value if no argument is provided.
1601 .Pp
1602 Examples:
1603 .Bd -literal -offset indent
1604 \&.Dx 2.4.1
1605 \&.Dx
1606 .Ed
1607 .Pp
1608 See also
1609 .Sx \&At ,
1610 .Sx \&Bsx ,
1611 .Sx \&Bx ,
1612 .Sx \&Fx ,
1613 .Sx \&Nx ,
1614 .Sx \&Ox ,
1615 and
1616 .Sx \&Ux .
1617 .
1618 .Ss \&Ec
1619 .Ss \&Ed
1620 .Ss \&Ef
1621 .Ss \&Ek
1622 .Ss \&El
1623 .Ss \&Em
1624 Denotes text that should be emphasised. Note that this is a
1625 presentation term and should not be used for stylistically decorating
1626 technical terms.
1627 .Pp
1628 Examples:
1629 .Bd -literal -offset indent
1630 \&.Ed Warnings!
1631 \&.Ed Remarks :
1632 .Ed
1633 .
1634 .Ss \&En
1635 .Ss \&Eo
1636 .Ss \&Er
1637 Error constants (suggested for use only in section two manuals).
1638 .Pp
1639 Examples:
1640 .Bd -literal -offset indent
1641 \&.Er EPERM
1642 \&.Er ENOENT
1643 .Ed
1644 .Pp
1645 See also
1646 .Sx \&Dv .
1647 .
1648 .Ss \&Es
1649 .
1650 .Ss \&Ev
1651 Environmental variables such as those specified in
1652 .Xr environ 7 .
1653 .Pp
1654 Examples:
1655 .Bd -literal -offset indent
1656 \&.Ev DISPLAY
1657 \&.Ev PATH
1658 .Ed
1659 .
1660 .Ss \&Ex
1661 Inserts text regarding a utility's exit values. This macro must have
1662 first the
1663 .Fl std
1664 argument specified, then an optional
1665 .Ar utility .
1666 If
1667 .Ar utility
1668 is not provided, the document's name as stipulated in
1669 .Sx \&Nm
1670 is provided.
1671 .Ss \&Fa
1672 .Ss \&Fc
1673 .Ss \&Fd
1674 .Ss \&Fl
1675 Command-line flag. Used when listing arguments to command-line
1676 utilities. Prints a fixed-width hyphen
1677 .Sq \-
1678 before each delimited argument. If no arguments are provided, a hyphen
1679 is still printed.
1680 .Pp
1681 Examples:
1682 .Bd -literal -offset indent
1683 \&.Fl a b c
1684 \&.Fl
1685 \&.Op Fl o Ns Ar file
1686 .Ed
1687 .Pp
1688 See also
1689 .Sx \&Cm .
1690 .
1691 .Ss \&Fn
1692 .Ss \&Fo
1693 .Ss \&Fr
1694 .Ss \&Ft
1695 .Ss \&Fx
1696 Format the FreeBSD version provided as an argument, or a default value
1697 if no argument is provided.
1698 .Pp
1699 Examples:
1700 .Bd -literal -offset indent
1701 \&.Fx 7.1
1702 \&.Fx
1703 .Ed
1704 .Pp
1705 See also
1706 .Sx \&At ,
1707 .Sx \&Bsx ,
1708 .Sx \&Bx ,
1709 .Sx \&Dx ,
1710 .Sx \&Nx ,
1711 .Sx \&Ox ,
1712 and
1713 .Sx \&Ux .
1714 .
1715 .Ss \&Hf
1716 .Ss \&Ic
1717 .Ss \&In
1718 .Ss \&It
1719 .Ss \&Lb
1720 .Ss \&Li
1721 .Ss \&Lk
1722 Format a hyperlink. The calling syntax is as follows:
1723 .Pp
1724 .D1 \. Ns Sx \&Lk Cm uri Op Cm name
1725 .Pp
1726 Examples:
1727 .Bd -literal -offset indent
1728 \&.Lk http://bsd.lv "The BSD.lv Project"
1729 \&.Lk http://bsd.lv
1730 .Ed
1731 .Pp
1732 See also
1733 .Sx \&Mt .
1734 .
1735 .Ss \&Lp
1736 .Ss \&Ms
1737 .Ss \&Mt
1738 .Ss \&Nd
1739 .Ss \&Nm
1740 .Ss \&No
1741 .Ss \&Ns
1742 .Ss \&Nx
1743 Format the NetBSD version provided as an argument, or a default value if
1744 no argument is provided.
1745 .Pp
1746 Examples:
1747 .Bd -literal -offset indent
1748 \&.Nx 5.01
1749 \&.Nx
1750 .Ed
1751 .Pp
1752 See also
1753 .Sx \&At ,
1754 .Sx \&Bsx ,
1755 .Sx \&Bx ,
1756 .Sx \&Dx ,
1757 .Sx \&Fx ,
1758 .Sx \&Ox ,
1759 and
1760 .Sx \&Ux .
1761 .
1762 .Ss \&Oc
1763 .Ss \&Oo
1764 .Ss \&Op
1765 .Ss \&Os
1766 Document operating system version. This is the mandatory third macro of
1767 any
1768 .Nm
1769 file. Its calling syntax is as follows:
1770 .Pp
1771 .D1 \. Ns Sx \&Os Op Cm system
1772 .Pp
1773 The optional
1774 .Cm system
1775 parameter specifies the relevant operating system or environment. Left
1776 unspecified, it defaults to the local operating system version. This is
1777 the suggested form.
1778 .Pp
1779 Examples:
1780 .Bd -literal -offset indent
1781 \&.Os
1782 \&.Os KTH/CSC/TCS
1783 \&.Os BSD 4.3
1784 .Ed
1785 .Pp
1786 See also
1787 .Sx \&Dd
1788 and
1789 .Sx \&Dt .
1790 .
1791 .Ss \&Ot
1792 Unknown usage.
1793 .Pp
1794 .Em Remarks :
1795 this macro has been deprecated.
1796 .
1797 .Ss \&Ox
1798 Format the OpenBSD version provided as an argument, or a default value
1799 if no argument is provided.
1800 .Pp
1801 Examples:
1802 .Bd -literal -offset indent
1803 \&.Ox 4.5
1804 \&.Ox
1805 .Ed
1806 .Pp
1807 See also
1808 .Sx \&At ,
1809 .Sx \&Bsx ,
1810 .Sx \&Bx ,
1811 .Sx \&Dx ,
1812 .Sx \&Fx ,
1813 .Sx \&Nx ,
1814 and
1815 .Sx \&Ux .
1816 .
1817 .Ss \&Pa
1818 .Ss \&Pc
1819 .Ss \&Pf
1820 .Ss \&Po
1821 .Ss \&Pp
1822 .Ss \&Pq
1823 .Ss \&Qc
1824 .Ss \&Ql
1825 .Ss \&Qo
1826 .Ss \&Qq
1827 .
1828 .Ss \&Re
1829 Closes a
1830 .Sx \&Rs
1831 block. Does not have any tail arguments.
1832 .
1833 .Ss \&Rs
1834 Begins a bibliographic
1835 .Pq Dq reference
1836 block. Does not have any head arguments. The block macro may only
1837 contain
1838 .Sx \&%A ,
1839 .Sx \&%B ,
1840 .Sx \&%C ,
1841 .Sx \&%D ,
1842 .Sx \&%I ,
1843 .Sx \&%J ,
1844 .Sx \&%N ,
1845 .Sx \&%O ,
1846 .Sx \&%P ,
1847 .Sx \&%Q ,
1848 .Sx \&%R ,
1849 .Sx \&%T ,
1850 and
1851 .Sx \&%V
1852 child macros (at least one must be specified).
1853 .Pp
1854 Examples:
1855 .Bd -literal -offset indent
1856 \&.Rs
1857 \&.%A J. E. Hopcroft
1858 \&.%A J. D. Ullman
1859 \&.%B Introduction to Automata Theory, Languages, and Computation
1860 \&.%I Addison-Wesley
1861 \&.%C Reading, Massachusettes
1862 \&.%D 1979
1863 \&.Re
1864 .Ed
1865 .Pp
1866 If an
1867 .Sx \&Rs
1868 block is used within a SEE ALSO section, a vertical space is asserted
1869 before the rendered output, else the block continues on the current
1870 line.
1871 .
1872 .Ss \&Rv
1873 .Ss \&Sc
1874 .Ss \&Sh
1875 .Ss \&Sm
1876 .Ss \&So
1877 .Ss \&Sq
1878 .Ss \&Ss
1879 .Ss \&St
1880 .Ss \&Sx
1881 .Ss \&Sy
1882 .Ss \&Tn
1883 .Ss \&Ud
1884 .Ss \&Ux
1885 Format the UNIX name. Accepts no argument.
1886 .Pp
1887 Examples:
1888 .Bd -literal -offset indent
1889 \&.Ux
1890 .Ed
1891 .Pp
1892 See also
1893 .Sx \&At ,
1894 .Sx \&Bsx ,
1895 .Sx \&Bx ,
1896 .Sx \&Dx ,
1897 .Sx \&Fx ,
1898 .Sx \&Nx ,
1899 and
1900 .Sx \&Ox .
1901 .
1902 .Ss \&Va
1903 .Ss \&Vt
1904 A variable type. This is also used for indicating global variables in the
1905 SYNOPSIS section, in which case a variable name is also specified. Note that
1906 it accepts
1907 .Sx Block partial-implicit
1908 syntax when invoked as the first macro in the SYNOPSIS section, else it
1909 accepts ordinary
1910 .Sx In-line
1911 syntax.
1912 .Pp
1913 Note that this should not be confused with
1914 .Sx \&Ft ,
1915 which is used for function return types.
1916 .Pp
1917 Examples:
1918 .Bd -literal -offset indent
1919 \&.Vt unsigned char
1920 \&.Vt extern const char * const sys_signame[] ;
1921 .Ed
1922 .Pp
1923 See also
1924 .Sx \&Ft
1925 and
1926 .Sx \&Va .
1927 .
1928 .Ss \&Xc
1929 .Ss \&Xo
1930 .Ss \&Xr
1931 Link to another manual
1932 .Pq Qq cross-reference .
1933 Its calling syntax is
1934 .Pp
1935 .D1 \. Ns Sx \&Xr Cm name section
1936 .Pp
1937 The
1938 .Cm name
1939 and
1940 .Cm section
1941 are the name and section of the linked manual. If
1942 .Cm section
1943 is followed by non-punctuation, an
1944 .Sx \&Ns
1945 is inserted into the token stream. This behaviour is for compatibility
1946 with
1947 .Xr groff 1 .
1948 .Pp
1949 Examples:
1950 .Bd -literal -offset indent
1951 \&.Xr mandoc 1
1952 \&.Xr mandoc 1 ;
1953 \&.Xr mandoc 1 s behaviour
1954 .Ed
1955 .
1956 .Ss \&br
1957 .Ss \&sp
1958 .
1959 .
1960 .Sh COMPATIBILITY
1961 This section documents compatibility with other roff implementations, at
1962 this time limited to
1963 .Xr groff 1 .
1964 The term
1965 .Qq historic groff
1966 refers to those versions before the
1967 .Pa doc.tmac
1968 file re-write
1969 .Pq somewhere between 1.15 and 1.19 .
1970 .
1971 .Pp
1972 .Bl -dash -compact
1973 .It
1974 The comment syntax
1975 .Sq \e."
1976 is no longer accepted.
1977 .It
1978 In
1979 .Xr groff 1 ,
1980 the
1981 .Sx \&Pa
1982 macro does not format its arguments when used in the FILES section under
1983 certain list types. This irregular behaviour has been discontinued.
1984 .It
1985 Historic
1986 .Xr groff 1
1987 does not print a dash for empty
1988 .Sx \&Fl
1989 arguments. This behaviour has been discontinued.
1990 .It
1991 .Xr groff 1
1992 behaves strangely (even between versions) when specifying
1993 .Sq \ef
1994 escapes within line-macro scopes. These aberrations have been
1995 normalised.
1996 .It
1997 Negative scaling units are now truncated to zero instead of creating
1998 interesting conditions, such as with
1999 .Sx \&sp
2000 .Fl 1i .
2001 Furthermore, the
2002 .Sq f
2003 scaling unit, while accepted, is rendered as the default unit.
2004 .It
2005 In quoted literals, groff allowed pair-wise double-quotes to produce a
2006 standalone double-quote in formatted output. This idiosyncratic
2007 behaviour is no longer applicable.
2008 .It
2009 Display types
2010 .Sx \&Bd
2011 .Fl center
2012 and
2013 .Fl right
2014 are aliases for
2015 .Fl left .
2016 The
2017 .Fl file Ar file
2018 argument is ignored. Since text is not right-justified,
2019 .Fl ragged
2020 and
2021 .Fl filled
2022 are aliases, as are
2023 .Fl literal
2024 and
2025 .Fl unfilled .
2026 .It
2027 Blocks of whitespace are stripped from both macro and free-form text
2028 lines (except when in literal mode), while groff would retain whitespace
2029 in free-form text lines.
2030 .It
2031 Historic groff has many un-callable macros. Most of these (excluding
2032 some block-level macros) are now callable, conforming to the
2033 non-historic groff version.
2034 .It
2035 The vertical bar
2036 .Sq \(ba
2037 made historic groff
2038 .Qq go orbital
2039 but is a proper delimiter in this implementation.
2040 .It
2041 .Sx \&It
2042 .Fl nested
2043 is assumed for all lists (it wasn't in historic groff): any list may be
2044 nested and
2045 .Fl enum
2046 lists will restart the sequence only for the sub-list.
2047 .It
2048 Some manuals use
2049 .Sx \&Li
2050 incorrectly by following it with a reserved character and expecting the
2051 delimiter to render. This is not supported.
2052 .It
2053 In groff, the
2054 .Sx \&Fo
2055 macro only produces the first parameter. This is no longer the case.
2056 .El
2057 .
2058 .
2059 .Sh SEE ALSO
2060 .Xr mandoc 1 ,
2061 .Xr mandoc_char 7
2062 .
2063 .
2064 .Sh AUTHORS
2065 The
2066 .Nm
2067 reference was written by
2068 .An Kristaps Dzonsons Aq kristaps@kth.se .
2069 .\"
2070 .\" XXX: this really isn't the place for these caveats.
2071 .\" .
2072 .\" .
2073 .\" .Sh CAVEATS
2074 .\" There are many ambiguous parts of mdoc.
2075 .\" .
2076 .\" .Pp
2077 .\" .Bl -dash -compact
2078 .\" .It
2079 .\" .Sq \&Fa
2080 .\" should be
2081 .\" .Sq \&Va
2082 .\" as function arguments are variables.
2083 .\" .It
2084 .\" .Sq \&Ft
2085 .\" should be
2086 .\" .Sq \&Vt
2087 .\" as function return types are still types. Furthermore, the
2088 .\" .Sq \&Ft
2089 .\" should be removed and
2090 .\" .Sq \&Fo ,
2091 .\" which ostensibly follows it, should follow the same convention as
2092 .\" .Sq \&Va .
2093 .\" .It
2094 .\" .Sq \&Va
2095 .\" should formalise that only one or two arguments are acceptable: a
2096 .\" variable name and optional, preceding type.
2097 .\" .It
2098 .\" .Sq \&Fd
2099 .\" is ambiguous. It's commonly used to indicate an include file in the
2100 .\" synopsis section.
2101 .\" .Sq \&In
2102 .\" should be used, instead.
2103 .\" .It
2104 .\" Only the
2105 .\" .Sq \-literal
2106 .\" argument to
2107 .\" .Sq \&Bd
2108 .\" makes sense. The remaining ones should be removed.
2109 .\" .It
2110 .\" The
2111 .\" .Sq \&Xo
2112 .\" and
2113 .\" .Sq \&Xc
2114 .\" macros should be deprecated.
2115 .\" .It
2116 .\" The
2117 .\" .Sq \&Dt
2118 .\" macro lacks clarity. It should be absolutely clear which title will
2119 .\" render when formatting the manual page.
2120 .\" .It
2121 .\" A
2122 .\" .Sq \&Lx
2123 .\" should be provided for Linux (\(`a la
2124 .\" .Sq \&Ox ,
2125 .\" .Sq \&Nx
2126 .\" etc.).
2127 .\" .It
2128 .\" There's no way to refer to references in
2129 .\" .Sq \&Rs/Re
2130 .\" blocks.
2131 .\" .It
2132 .\" The \-split and \-nosplit dictates via
2133 .\" .Sq \&An
2134 .\" are re-set when entering and leaving the AUTHORS section.
2135 .\" .El
2136 .\" .