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