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