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