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