-.\" $Id: mdoc.7,v 1.56 2009/08/18 14:27:16 kristaps Exp $
+.\" $Id: mdoc.7,v 1.70 2009/10/26 04:09:45 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: August 18 2009 $
+.Dd $Mdocdate: October 26 2009 $
.Dt MDOC 7
.Os
.
.
.Sh NAME
-. Nm mdoc
-. Nd mdoc language reference
+.Nm mdoc
+.Nd mdoc language reference
.
.
.Sh DESCRIPTION
The
-. Nm mdoc
+.Nm mdoc
language is used to format
-. Bx
-. Ux
+.Bx
+.Ux
manuals. In this reference document, we describe its syntax, structure,
and usage. Our reference implementation is
-. Xr mandoc 1 .
+.Xr mandoc 1 .
The
-. Sx COMPATIBILITY
+.Sx COMPATIBILITY
section describes compatibility with
-. Xr groff 1 .
-. Pp
+.Xr groff 1 .
+.
+.Pp
An
-. Nm
+.Nm
document follows simple rules: lines beginning with the control
character
-. Sq \.
+.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
prior macros:
-. Bd -literal -offset indent
+.Bd -literal -offset indent
\&.Sh Macro lines change control state.
Other lines are interpreted within the current state.
-. Ed
+.Ed
.
.
.Sh LANGUAGE SYNTAX
-. Nm
+.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character. All
manuals must have
-. Ux
+.Ux
line terminators.
.
.
-. Ss Comments
+.Ss Comments
Text following a
-. Sq \e" ,
+.Sq \e" ,
whether in a macro or free-form text line, is ignored to the end of
line. A macro line with only a control character and comment escape,
-. Sq \&.\e" ,
-is also ignored.
+.Sq \&.\e" ,
+is also ignored. Macro lines with only a control charater and optionally
+whitespace are stripped from input.
.
.
-. Ss Reserved Characters
+.Ss Reserved Characters
Within a macro line, the following characters are reserved:
-. Bl -tag -width Ds -offset indent -compact
-. It \&.
-. Pq period
-. It \&,
-. Pq comma
-. It \&:
-. Pq colon
-. It \&;
-. Pq semicolon
-. It \&(
-. Pq left-parenthesis
-. It \&)
-. Pq right-parenthesis
-. It \&[
-. Pq left-bracket
-. It \&]
-. Pq right-bracket
-. It \&?
-. Pq question
-. It \&!
-. Pq exclamation
-. It \&|
-. Pq vertical bar
-. El
-. Pp
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&.
+.Pq period
+.It \&,
+.Pq comma
+.It \&:
+.Pq colon
+.It \&;
+.Pq semicolon
+.It \&(
+.Pq left-parenthesis
+.It \&)
+.Pq right-parenthesis
+.It \&[
+.Pq left-bracket
+.It \&]
+.Pq right-bracket
+.It \&?
+.Pq question
+.It \&!
+.Pq exclamation
+.It \&|
+.Pq vertical bar
+.El
+.
+.Pp
Use of reserved characters is described in
-. Sx MACRO SYNTAX .
+.Sx MACRO SYNTAX .
For general use in macro lines, these characters must either be escaped
with a non-breaking space
-. Pq Sq \e&
+.Pq Sq \e&
or, if applicable, an appropriate escape sequence used.
.
.
-. Ss Special Characters
+.Ss Special Characters
Special characters may occur in both macro and free-form lines.
Sequences begin with the escape character
-. Sq \e
+.Sq \e
followed by either an open-parenthesis
-. Sq \&(
+.Sq \&(
for two-character sequences; an open-bracket
-. Sq \&[
+.Sq \&[
for n-character sequences (terminated at a close-bracket
-. Sq \&] ) ;
+.Sq \&] ) ;
or a single one-character sequence. See
-. Xr mandoc_char 7
+.Xr mandoc_char 7
for a complete list. Examples include
-. Sq \e(em
-. Pq em-dash
+.Sq \e(em
+.Pq em-dash
and
-. Sq \ee
-. Pq back-slash .
+.Sq \ee
+.Pq back-slash .
.
.
-. Ss Text Decoration
+.Ss Text Decoration
Terms may be text-decorated using the
-. Sq \ef
+.Sq \ef
escape followed by an indicator: B (bold), I, (italic), or P and R
(Roman, or reset). This form is not recommended for
-. Nm ,
+.Nm ,
which encourages semantic, not presentation, annotation.
.
.
-. Ss Predefined Strings
+.Ss Predefined Strings
Historically,
-. Xr groff 1
+.Xr groff 1
also defined a set of package-specific
-. Dq predefined strings ,
+.Dq predefined strings ,
which, like
-. Sx Special Characters ,
+.Sx Special Characters ,
demark special output characters and strings by way of input codes.
Predefined strings are escaped with the slash-asterisk,
-. Sq \e* :
+.Sq \e* :
single-character
-. Sq \e*X ,
+.Sq \e*X ,
two-character
-. Sq \e*(XX ,
+.Sq \e*(XX ,
and N-character
-. Sq \e*[N] .
+.Sq \e*[N] .
See
-. Xr mandoc_char 7
+.Xr mandoc_char 7
for a complete list. Examples include
-. Sq \e*(Am
-. Pq ampersand
+.Sq \e*(Am
+.Pq ampersand
and
-. Sq \e*(Ba
-. Pq vertical bar .
+.Sq \e*(Ba
+.Pq vertical bar .
.
.
-. Ss Whitespace
+.Ss Whitespace
In non-literal free-form lines, consecutive blocks of whitespace are
pruned from input and added later in the output filter, if applicable:
-. Bd -literal -offset indent
+.Bd -literal -offset indent
These spaces are pruned from input.
\&.Bd \-literal
These are not.
\&.Ed
-. Ed
-. Pp
+.Ed
+.
+.Pp
In macro lines, whitespace delimits arguments and is discarded. If
arguments are quoted, whitespace within the quotes is retained.
-. Pp
+.
+.Pp
Blank lines are only permitted within literal contexts, as are lines
containing only whitespace. Tab characters are only acceptable when
delimiting
-. Sq \&Bl \-column
+.Sq \&Bl \-column
or when in a literal context.
.
.
-. Ss Quotation
+.Ss Quotation
Macro arguments may be quoted with a double-quote to group
space-delimited terms or to retain blocks of whitespace. A quoted
argument begins with a double-quote preceded by whitespace. The next
double-quote not pair-wise adjacent to another double-quote terminates
the literal, regardless of surrounding whitespace.
-. Pp
+.
+.Pp
This produces tokens
-. Sq a" ,
-. Sq b c ,
-. Sq de ,
+.Sq a" ,
+.Sq b c ,
+.Sq de ,
and
-. Sq fg" .
+.Sq fg" .
Note that any quoted term, be it argument or macro, is indiscriminately
considered literal text. Thus, the following produces
-. Sq \&Em a :
-. Bd -literal -offset indent
+.Sq \&Em a :
+.Bd -literal -offset indent
\&.Em "Em a"
-. Ed
-. Pp
+.Ed
+.
+.Pp
In free-form mode, quotes are regarded as opaque text.
.
+.Ss Dates
+There are several macros in
+.Nm
+that require a date argument. The
+.Em canonical form
+for dates is the American format:
+.Pp
+.D1 Cm Month Day , Year
+.Pp
+The
+.Cm Day
+value is an optionally zero-padded numeral. The
+.Cm Month
+value is the full month name. The
+.Cm Year
+value is the full four-digit year.
+.Pp
+The
+.Em non-canonical form
+is the same as the canonical form, but without the comma between the
+.Cm Day
+and
+.Cm Year
+field.
+.Pp
+Lastly,
+.Em reduced form
+dates range from only a
+.Cm Year
+to the full canonical or non-canonical form.
+.Pp
+Some examples of valid dates follow:
+.Pp
+.D1 "May, 2009" Pq reduced form
+.D1 "2009" Pq reduced form
+.D1 "May 20, 2009" Pq canonical form
+.D1 "May 20 2009" Pq non-canonical form
+.
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments, such as
+stipulating a two-inch list indentation with the following:
+.Bd -literal -offset indent
+\&.Bl -tag -width 2i
+.Ed
+.
+.Pp
+The syntax for scaled widths is
+.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
+where a decimal must be preceded or proceeded by at least one digit.
+Negative numbers, while accepted, are truncated to zero. The following
+scaling units are accepted:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It c
+centimetre
+.It i
+inch
+.It P
+pica (~1/6 inch)
+.It p
+point (~1/72 inch)
+.It f
+synonym for
+.Sq u
+.It v
+default vertical span
+.It m
+width of rendered
+.Sq m
+.Pq em
+character
+.It n
+width of rendered
+.Sq n
+.Pq en
+character
+.It u
+default horizontal span
+.It M
+mini-em (~1/100 em)
+.El
+.Pp
+Using anything other than
+.Sq m ,
+.Sq n ,
+.Sq u ,
+or
+.Sq v
+is necessarily non-portable across output media. See
+.Sx COMPATIBILITY .
+.
.
.Sh MANUAL STRUCTURE
-Each
-. Nm
-document must begin with a document prologue, containing, in order,
-. Sq \&Dd ,
-. Sq \&Dt ,
+A well-formed
+.Nm
+document consists of a document prologue followed by one or more
+sections.
+.Pp
+The prologue, which consists of (in order) the
+.Sx \&Dd ,
+.Sx \&Dt ,
and
-. Sq \&Os ,
-then the NAME section containing at least one
-. Sq \&Nm
+.Sx \&Os
+macros, is required for every document.
+.Pp
+The first section (sections are denoted by
+.Sx \&Sh )
+must be the NAME section, consisting of at least one
+.Sx \&Nm
followed by
-. Sq \&Nd :
-. Bd -literal -offset indent
+.Sx \&Nd .
+.Pp
+Following that, convention dictates specifying at least the SYNOPSIS and
+DESCRIPTION sections, although this varies between manual sections.
+.Pp
+The following is a well-formed skeleton
+.Nm
+file:
+.Bd -literal -offset indent
\&.Dd $\&Mdocdate$
\&.Dt mdoc 7
\&.Os
+\&.
\&.Sh NAME
-\&.Nm mdoc
-\&.Nd mdoc language reference
-. Ed
-. Pp
-Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
-but non-compulsory.
+\&.Nm foo
+\&.Nd a description goes here
+\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q .Sh LIBRARY
+\&.
+\&.Sh SYNOPSIS
+\&.Nm foo
+\&.Op Fl options
+\&.Ar
+\&.
+\&.Sh DESCRIPTION
+The
+\&.Nm
+utility processes files ...
+\&.\e\*q .Sh IMPLEMENTATION NOTES
+\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q .Sh EXIT STATUS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q .Sh RETURN VALUES
+\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q .Sh FILES
+\&.\e\*q .Sh EXAMPLES
+\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
+\&.\e\*q .Sh DIAGNOSTICS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q .Sh ERRORS
+\&.\e\*q .Sh SEE ALSO
+\&.\e\*q .Xr foobar 1
+\&.\e\*q .Sh STANDARDS
+\&.\e\*q .Sh HISTORY
+\&.\e\*q .Sh AUTHORS
+\&.\e\*q .Sh CAVEATS
+\&.\e\*q .Sh BUGS
+\&.\e\*q .Sh SECURITY CONSIDERATIONS
+.Ed
+.Pp
+The sections in a
+.Nm
+document are conventionally ordered as they appear above. Sections
+should be composed as follows:
+.Bl -tag -width Ds -offset Ds
+.It NAME
+Must contain at least one
+.Sx \&Nm
+followed by
+.Sx \&Nd .
+The name needs re-stating since one
+.Nm
+documents can be used for more than one utility or function, such as
+.Xr grep 1
+also being referenced as
+.Xr egrep 1
+and
+.Xr fgrep 1 .
+.It LIBRARY
+.It SYNOPSIS
+.It DESCRIPTION
+.It IMPLEMENTATION NOTES
+.It EXIT STATUS
+.It RETURN VALUES
+.It ENVIRONMENT
+.It FILES
+.It EXAMPLES
+.It DIAGNOSTICS
+.It ERRORS
+.It SEE ALSO
+.It STANDARDS
+.It HISTORY
+.It AUTHORS
+.It CAVEATS
+.It BUGS
+.It SECURITY CONSIDERATIONS
+.El
.
.
.Sh MACRO SYNTAX
Macros are one to three three characters in length and begin with a
control character ,
-. Sq \&. ,
+.Sq \&. ,
at the beginning of the line. An arbitrary amount of whitespace may
-sit between the control character and the macro name. Thus,
-. Sq \&.Pp
-and
-. Sq \&.\ \ \ \&Pp
-are equivalent. Macro names are two or three characters in length.
-. Pp
+sit between the control character and the macro name. Thus, the
+following are equivalent:
+.Bd -literal -offset indent
+\&.Pp
+\&.\ \ \ \&Pp
+.Ed
+.
+.Pp
The syntax of a macro depends on its classification. In this section,
-. Sq \-arg
+.Sq \-arg
refers to macro arguments, which may be followed by zero or more
-. Sq parm
+.Sq parm
parameters;
-. Sq \&Yo
+.Sq \&Yo
opens the scope of a macro; and if specified,
-. Sq \&Yc
+.Sq \&Yc
closes it out.
-. Pp
+.
+.Pp
The
-. Em Callable
+.Em Callable
column indicates that the macro may be called subsequent to the initial
line-macro. If a macro is not callable, then its invocation after the
initial line macro is interpreted as opaque text, such that
-. Sq \&.Fl Sh
+.Sq \&.Fl \&Sh
produces
-. Sq Fl Sh .
-. Pp
+.Sq Fl \&Sh .
+.
+.Pp
The
-. Em Parsable
+.Em Parsable
column indicates whether the macro may be followed by further
(ostensibly callable) macros. If a macro is not parsable, subsequent
macro invocations on the line will be interpreted as opaque text.
-. Pp
+.
+.Pp
The
-. Em Scope
+.Em Scope
column, if applicable, describes closure rules.
.
.
-. Ss Block full-explicit
+.Ss Block full-explicit
Multi-line scope closed by an explicit closing macro. All macros
contains bodies; only
-. Pq Sq \&Bf
+.Sx \&Bf
contains a head.
-. Bd -literal -offset indent
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc
-. Ed
-. Pp
-. Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
-. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-. It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
-. It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
-. It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
-. It \&Bl Ta \&No Ta \&No Ta closed by \&El
-. It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
-. It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
-. It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
-. It \&El Ta \&No Ta \&No Ta opened by \&Bl
-. El
-.
-.
-. Ss Block full-implicit
+.Ed
+.
+.Pp
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
+.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
+.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
+.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
+.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
+.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
+.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
+.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
+.El
+.
+.
+.Ss Block full-implicit
Multi-line scope closed by end-of-file or implicitly by another macro.
All macros have bodies; some
-. Po
-. Sq \&It \-bullet ,
-. Sq \-hyphen ,
-. Sq \-dash ,
-. Sq \-enum ,
-. Sq \-item
-. Pc
-don't have heads, while
-. Sq \&It \-column
-may have multiple heads.
-. Bd -literal -offset indent
+.Po
+.Sx \&It Fl bullet ,
+.Fl hyphen ,
+.Fl dash ,
+.Fl enum ,
+.Fl item
+.Pc
+don't have heads; only one
+.Po
+.Sx \&It Fl column
+.Pc
+has multiple heads.
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
\(lBbody...\(rB
-. Ed
-. Pp
-. Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
-. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-. It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
-. It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
-. It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
-. It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
-. El
-.
-.
-. Ss Block partial-explicit
+.Ed
+.
+.Pp
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
+.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
+.El
+.
+.
+.Ss Block partial-explicit
Like block full-explicit, but also with single-line scope. Each
has at least a body and, in limited circumstances, a head
-. Pq So \&Fo Sc , So \&Eo Sc
+.Po
+.Sx \&Fo ,
+.Sx \&Eo
+.Pc
and/or tail
-. Pq So \&Ec Sc .
-. Bd -literal -offset indent
+.Pq Sx \&Ec .
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc \(lBtail...\(rB
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
\(lBbody...\(rB \&Yc \(lBtail...\(rB
-. Ed
-. Pp
-. Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
-. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
-. It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
-. It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
-. It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
-. It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
-. It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
-. It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
-. It \&Dc Ta Yes Ta Yes Ta opened by \&Do
-. It \&Do Ta Yes Ta Yes Ta closed by \&Dc
-. It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
-. It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
-. It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
-. It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
-. It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
-. It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
-. It \&Pc Ta Yes Ta Yes Ta closed by \&Po
-. It \&Po Ta Yes Ta Yes Ta opened by \&Pc
-. It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
-. It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
-. It \&Re Ta \&No Ta \&No Ta opened by \&Rs
-. It \&Rs Ta \&No Ta \&No Ta closed by \&Re
-. It \&Sc Ta Yes Ta Yes Ta opened by \&So
-. It \&So Ta Yes Ta Yes Ta closed by \&Sc
-. It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
-. It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
-. El
-.
-.
-. Ss Block partial-implicit
+.Ed
+.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
+.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
+.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
+.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
+.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
+.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
+.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
+.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
+.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
+.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
+.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
+.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
+.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
+.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
+.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
+.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
+.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
+.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
+.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
+.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
+.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
+.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
+.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
+.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
+.El
+.
+.
+.Ss Block partial-implicit
Like block full-implicit, but with single-line scope closed by
-. Sx Reserved Characters
+.Sx Reserved Characters
or end of line.
-. Bd -literal -offset indent
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
-. Ed
-. Pp
-. Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
-. It Em Macro Ta Em Callable Ta Em Parsable
-. It \&Aq Ta Yes Ta Yes
-. It \&Bq Ta Yes Ta Yes
-. It \&Brq Ta Yes Ta Yes
-. It \&D1 Ta \&No Ta \&Yes
-. It \&Dl Ta \&No Ta Yes
-. It \&Dq Ta Yes Ta Yes
-. It \&Op Ta Yes Ta Yes
-. It \&Pq Ta Yes Ta Yes
-. It \&Ql Ta Yes Ta Yes
-. It \&Qq Ta Yes Ta Yes
-. It \&Sq Ta Yes Ta Yes
-. El
-.
-.
-. Ss In-line
+.Ed
+.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable
+.It Sx \&Aq Ta Yes Ta Yes
+.It Sx \&Bq Ta Yes Ta Yes
+.It Sx \&Brq Ta Yes Ta Yes
+.It Sx \&D1 Ta \&No Ta \&Yes
+.It Sx \&Dl Ta \&No Ta Yes
+.It Sx \&Dq Ta Yes Ta Yes
+.It Sx \&Op Ta Yes Ta Yes
+.It Sx \&Pq Ta Yes Ta Yes
+.It Sx \&Ql Ta Yes Ta Yes
+.It Sx \&Qq Ta Yes Ta Yes
+.It Sx \&Sq Ta Yes Ta Yes
+.El
+.
+.
+.Ss In-line
Closed by
-. Sx Reserved Characters ,
+.Sx Reserved Characters ,
end of line, fixed argument lengths, and/or subsequent macros. In-line
macros have only text children. If a number (or inequality) of
arguments is
-. Pq n ,
+.Pq n ,
then the macro accepts an arbitrary number of arguments.
-. Bd -literal -offset indent
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
-. Ed
-. Pp
-. Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
-. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
-. It \&%A Ta \&No Ta \&No Ta >0
-. It \&%B Ta \&No Ta \&No Ta >0
-. It \&%C Ta \&No Ta \&No Ta >0
-. It \&%D Ta \&No Ta \&No Ta >0
-. It \&%I Ta \&No Ta \&No Ta >0
-. It \&%J Ta \&No Ta \&No Ta >0
-. It \&%N Ta \&No Ta \&No Ta >0
-. It \&%O Ta \&No Ta \&No Ta >0
-. It \&%P Ta \&No Ta \&No Ta >0
-. It \&%R Ta \&No Ta \&No Ta >0
-. It \&%T Ta \&No Ta \&No Ta >0
-. It \&%V Ta \&No Ta \&No Ta >0
-. It \&Ad Ta Yes Ta Yes Ta n
-. It \&An Ta Yes Ta Yes Ta n
-. It \&Ap Ta Yes Ta Yes Ta 0
-. It \&Ar Ta Yes Ta Yes Ta n
-. It \&At Ta Yes Ta Yes Ta 1
-. It \&Bsx Ta Yes Ta Yes Ta n
-. It \&Bt Ta \&No Ta \&No Ta 0
-. It \&Bx Ta Yes Ta Yes Ta n
-. It \&Cd Ta Yes Ta Yes Ta >0
-. It \&Cm Ta Yes Ta Yes Ta n
-. It \&Db Ta \&No Ta \&No Ta 1
-. It \&Dd Ta \&No Ta \&No Ta >0
-. It \&Dt Ta \&No Ta \&No Ta n
-. It \&Dv Ta Yes Ta Yes Ta n
-. It \&Dx Ta Yes Ta Yes Ta n
-. It \&Em Ta Yes Ta Yes Ta >0
-. It \&En Ta \&No Ta \&No Ta 0
-. It \&Er Ta Yes Ta Yes Ta >0
-. It \&Es Ta \&No Ta \&No Ta 0
-. It \&Ev Ta Yes Ta Yes Ta n
-. It \&Ex Ta \&No Ta \&No Ta 0
-. It \&Fa Ta Yes Ta Yes Ta n
-. It \&Fd Ta \&No Ta \&No Ta >0
-. It \&Fl Ta Yes Ta Yes Ta n
-. It \&Fn Ta Yes Ta Yes Ta >0
-. It \&Fr Ta \&No Ta \&No Ta n
-. It \&Ft Ta Yes Ta Yes Ta n
-. It \&Fx Ta Yes Ta Yes Ta n
-. It \&Hf Ta \&No Ta \&No Ta n
-. It \&Ic Ta Yes Ta Yes Ta >0
-. It \&In Ta \&No Ta \&No Ta n
-. It \&Lb Ta \&No Ta \&No Ta 1
-. It \&Li Ta Yes Ta Yes Ta n
-. It \&Lk Ta Yes Ta Yes Ta n
-. It \&Lp Ta \&No Ta \&No Ta 0
-. It \&Ms Ta Yes Ta Yes Ta >0
-. It \&Mt Ta Yes Ta Yes Ta >0
-. It \&Nm Ta Yes Ta Yes Ta n
-. It \&No Ta Yes Ta Yes Ta 0
-. It \&Ns Ta Yes Ta Yes Ta 0
-. It \&Nx Ta Yes Ta Yes Ta n
-. It \&Os Ta \&No Ta \&No Ta n
-. It \&Ot Ta \&No Ta \&No Ta n
-. It \&Ox Ta Yes Ta Yes Ta n
-. It \&Pa Ta Yes Ta Yes Ta n
-. It \&Pf Ta \&No Ta Yes Ta 1
-. It \&Pp Ta \&No Ta \&No Ta 0
-. It \&Rv Ta \&No Ta \&No Ta 0
-. It \&Sm Ta \&No Ta \&No Ta 1
-. It \&St Ta \&No Ta Yes Ta 1
-. It \&Sx Ta Yes Ta Yes Ta >0
-. It \&Sy Ta Yes Ta Yes Ta >0
-. It \&Tn Ta Yes Ta Yes Ta >0
-. It \&Ud Ta \&No Ta \&No Ta 0
-. It \&Ux Ta Yes Ta Yes Ta n
-. It \&Va Ta Yes Ta Yes Ta n
-. It \&Vt Ta Yes Ta Yes Ta >0
-. It \&Xr Ta Yes Ta Yes Ta >0, <3
-. It \&br Ta \&No Ta \&No Ta 0
-. It \&sp Ta \&No Ta \&No Ta 1
-. El
+.Ed
+.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
+.It Sx \&%A Ta \&No Ta \&No Ta >0
+.It Sx \&%B Ta \&No Ta \&No Ta >0
+.It Sx \&%C Ta \&No Ta \&No Ta >0
+.It Sx \&%D Ta \&No Ta \&No Ta >0
+.It Sx \&%I Ta \&No Ta \&No Ta >0
+.It Sx \&%J Ta \&No Ta \&No Ta >0
+.It Sx \&%N Ta \&No Ta \&No Ta >0
+.It Sx \&%O Ta \&No Ta \&No Ta >0
+.It Sx \&%P Ta \&No Ta \&No Ta >0
+.It Sx \&%Q Ta \&No Ta \&No Ta >0
+.It Sx \&%R Ta \&No Ta \&No Ta >0
+.It Sx \&%T Ta \&No Ta \&No Ta >0
+.It Sx \&%U Ta \&No Ta \&No Ta >0
+.It Sx \&%V Ta \&No Ta \&No Ta >0
+.It Sx \&Ad Ta Yes Ta Yes Ta n
+.It Sx \&An Ta Yes Ta Yes Ta n
+.It Sx \&Ap Ta Yes Ta Yes Ta 0
+.It Sx \&Ar Ta Yes Ta Yes Ta n
+.It Sx \&At Ta Yes Ta Yes Ta 1
+.It Sx \&Bsx Ta Yes Ta Yes Ta n
+.It Sx \&Bt Ta \&No Ta \&No Ta 0
+.It Sx \&Bx Ta Yes Ta Yes Ta n
+.It Sx \&Cd Ta Yes Ta Yes Ta >0
+.It Sx \&Cm Ta Yes Ta Yes Ta n
+.It Sx \&Db Ta \&No Ta \&No Ta 1
+.It Sx \&Dd Ta \&No Ta \&No Ta >0
+.It Sx \&Dt Ta \&No Ta \&No Ta n
+.It Sx \&Dv Ta Yes Ta Yes Ta n
+.It Sx \&Dx Ta Yes Ta Yes Ta n
+.It Sx \&Em Ta Yes Ta Yes Ta >0
+.It Sx \&En Ta \&No Ta \&No Ta 0
+.It Sx \&Er Ta Yes Ta Yes Ta >0
+.It Sx \&Es Ta \&No Ta \&No Ta 0
+.It Sx \&Ev Ta Yes Ta Yes Ta n
+.It Sx \&Ex Ta \&No Ta \&No Ta n
+.It Sx \&Fa Ta Yes Ta Yes Ta n
+.It Sx \&Fd Ta \&No Ta \&No Ta >0
+.It Sx \&Fl Ta Yes Ta Yes Ta n
+.It Sx \&Fn Ta Yes Ta Yes Ta >0
+.It Sx \&Fr Ta \&No Ta \&No Ta n
+.It Sx \&Ft Ta Yes Ta Yes Ta n
+.It Sx \&Fx Ta Yes Ta Yes Ta n
+.It Sx \&Hf Ta \&No Ta \&No Ta n
+.It Sx \&Ic Ta Yes Ta Yes Ta >0
+.It Sx \&In Ta \&No Ta \&No Ta n
+.It Sx \&Lb Ta \&No Ta \&No Ta 1
+.It Sx \&Li Ta Yes Ta Yes Ta n
+.It Sx \&Lk Ta Yes Ta Yes Ta n
+.It Sx \&Lp Ta \&No Ta \&No Ta 0
+.It Sx \&Ms Ta Yes Ta Yes Ta >0
+.It Sx \&Mt Ta Yes Ta Yes Ta >0
+.It Sx \&Nm Ta Yes Ta Yes Ta n
+.It Sx \&No Ta Yes Ta Yes Ta 0
+.It Sx \&Ns Ta Yes Ta Yes Ta 0
+.It Sx \&Nx Ta Yes Ta Yes Ta n
+.It Sx \&Os Ta \&No Ta \&No Ta n
+.It Sx \&Ot Ta \&No Ta \&No Ta n
+.It Sx \&Ox Ta Yes Ta Yes Ta n
+.It Sx \&Pa Ta Yes Ta Yes Ta n
+.It Sx \&Pf Ta \&No Ta Yes Ta 1
+.It Sx \&Pp Ta \&No Ta \&No Ta 0
+.It Sx \&Rv Ta \&No Ta \&No Ta n
+.It Sx \&Sm Ta \&No Ta \&No Ta 1
+.It Sx \&St Ta \&No Ta Yes Ta 1
+.It Sx \&Sx Ta Yes Ta Yes Ta >0
+.It Sx \&Sy Ta Yes Ta Yes Ta >0
+.It Sx \&Tn Ta Yes Ta Yes Ta >0
+.It Sx \&Ud Ta \&No Ta \&No Ta 0
+.It Sx \&Ux Ta Yes Ta Yes Ta n
+.It Sx \&Va Ta Yes Ta Yes Ta n
+.It Sx \&Vt Ta Yes Ta Yes Ta >0
+.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3
+.It Sx \&br Ta \&No Ta \&No Ta 0
+.It Sx \&sp Ta \&No Ta \&No Ta 1
+.El
+.
+.
+.Sh REFERENCE
+This section is a canonical reference of all macros, arranged
+alphabetically. For the scoping of individual macros, see
+.Sx MACRO SYNTAX .
+.
+.Ss \&%A
+Author name of an
+.Sx \&Rs
+block. Multiple authors should each be accorded their own
+.Sx \%%A
+line. Author names should be ordered with full or abbreviated
+forename(s) first, then full surname.
+.
+.Ss \&%B
+Book title of an
+.Sx \&Rs
+block. This macro may also be used in a non-bibliographic context when
+referring to book titles.
+.
+.Ss \&%C
+Publication city or location of an
+.Sx \&Rs
+block.
+.Pp
+.Em Remarks :
+this macro is not implemented in
+.Xr groff 1 .
+.
+.Ss \&%D
+Publication date of an
+.Sx \&Rs
+block. This should follow the reduced syntax for
+.Sx Dates .
+Canonical or non-canonical form is not necessary since publications are
+often referenced only by year, or month and year.
+.
+.Ss \&%I
+Publisher or issuer name of an
+.Sx \&Rs
+block.
+.
+.Ss \&%J
+Journal name of an
+.Sx \&Rs
+block.
+.
+.Ss \&%N
+Issue number (usually for journals) of an
+.Sx \&Rs
+block.
+.
+.Ss \&%O
+Optional information of an
+.Sx \&Rs
+block.
+.
+.Ss \&%P
+Book or journal page number of an
+.Sx \&Rs
+block.
+.
+.Ss \&%Q
+Institutional author (school, government, etc.) of an
+.Sx \&Rs
+block. Multiple institutional authors should each be accorded their own
+.Sx \&%Q
+line.
+.
+.Ss \&%R
+Technical report name of an
+.Sx \&Rs
+block.
+.
+.Ss \&%T
+Article title of an
+.Sx \&Rs
+block. This macro may also be used in a non-bibliographical context
+when referring to article titles.
+.
+.Ss \&%U
+URI of reference document.
+.
+.Ss \&%V
+Volume number of an
+.Sx \&Rs
+block.
+.
+.Ss \&Ac
+Closes an
+.Sx \&Ao
+block. Does not have any tail arguments.
+.
+.Ss \&Ad
+Address construct: usually in the context of an computational address in
+memory, not a physical (post) address.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ad [0,$]
+\&.Ad 0x00000000
+.Ed
+.
+.Ss \&An
+Author name. This macro may alternatively accepts the following
+arguments, although these may not be specified along with a parameter:
+.Bl -tag -width 12n -offset indent
+.It Fl split
+Renders a line break before each author listing.
+.It Fl nosplit
+The opposite of
+.Fl split .
+.El
+.Pp
+In the AUTHORS section, the default is not to split the first author
+listing, but all subsequent author listings, whether or not they're
+interspersed by other macros or text, are split. Thus, specifying
+.Fl split
+will cause the first listing also to be split. If not in the AUTHORS
+section, the default is not to split.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.An -nosplit
+\&.An J. E. Hopcraft ,
+\&.An J. D. Ullman .
+.Ed
+.Pp
+.Em Remarks :
+the effects of
+.Fl split
+or
+.Fl nosplit
+are re-set when entering the AUTHORS section, so if one specifies
+.Sx \&An Fl nosplit
+in the general document body, it must be re-specified in the AUTHORS
+section.
+.
+.Ss \&Ao
+Begins a block enclosed by angled brackets. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl -key= Ns Ao Ar val Ac
+.Ed
+.Pp
+See also
+.Sx \&Aq .
+.
+.Ss \&Ap
+Inserts an apostrophe without any surrounding white-space. This is
+generally used as a grammatic device when referring to the verb form of
+a function:
+.Bd -literal -offset indent
+\&.Fn execve Ap d
+.Ed
+.
+.Ss \&Aq
+Encloses its arguments in angled brackets.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl -key= Ns Aq Ar val
+.Ed
+.Pp
+.Em Remarks :
+this macro is often abused for rendering URIs, which should instead use
+.Sx \&Lk
+or
+.Sx \&Mt ,
+or to note pre-processor
+.Dq Li #include
+statements, which should use
+.Sx \&In .
+.Pp
+See also
+.Sx \&Ao .
+.
+.Ss \&Ar
+Command arguments. If an argument is not provided, the string
+.Dq file ...
+is used as a default.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl o Ns Ar file1
+\&.Ar
+\&.Ar arg1 , arg2 .
+.Ed
+.
+.Ss \&At
+Formats an AT&T version. Accepts at most one parameter:
+.Bl -tag -width 12n -offset indent
+.It Cm v[1-7] | 32v
+A version of
+.At .
+.It Cm V[.[1-4]]?
+A system version of
+.At .
+.El
+.Pp
+Note that these parameters do not begin with a hyphen.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.At
+\&.At V.1
+.Ed
+.Pp
+See also
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Bc
+Closes a
+.Sx \&Bo
+block. Does not have any tail arguments.
+.
+.Ss \&Bd
+Begins a display block. A display is collection of macros or text which
+may be collectively offset or justified in a manner different from that
+of the enclosing context. By default, the block is preceded by a
+vertical space.
+.Pp
+Each display is associated with a type, which must be one of the
+following arguments:
+.Bl -tag -width 12n -offset indent
+.It Fl ragged
+Only left-justify the block.
+.It Fl unfilled
+Do not justify the block at all.
+.It Fl filled
+Left- and right-justify the block.
+.It Fl literal
+Alias for
+.Fl unfilled .
+.It Fl centered
+Centre-justify each line.
+.El
+.Pp
+The type must be provided first. Secondary arguments are as follows:
+.Bl -tag -width 12n -offset indent
+.It Fl offset Ar width
+Offset by the value of
+.Ar width ,
+which is interpreted as one of the following, specified in order:
+.Bl -item
+.It
+As one of the pre-defined strings
+.Ar indent ,
+the width of standard indentation;
+.Ar indent-two ,
+twice
+.Ar indent ;
+.Ar left ,
+which has no effect ;
+.Ar right ,
+which justifies to the right margin; and
+.Ar center ,
+which aligns around an imagined centre axis.
+.It
+As a precalculated width for a named macro. The most popular is the
+imaginary macro
+.Ar \&Ds ,
+which resolves to
+.Ar 6n .
+.It
+As a scaling unit following the syntax described in
+.Sx Scaling Widths .
+.It
+As the calculated string length of the opaque string.
+.El
+.Pp
+If unset, it will revert to the value of
+.Ar 8n
+as described in
+.Sx Scaling Widths .
+.It Fl compact
+Do not assert a vertical space before the block.
+.It Fl file Ar file
+Prepend the file
+.Ar file
+before any text or macros within the block.
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bd \-unfilled \-offset two-indent \-compact
+ Hello world.
+\&.Ed
+.Ed
+.Pp
+See also
+.Sx \&D1
+and
+.Sx \&Dl .
+.
+.Ss \&Bf
+.Ss \&Bk
+.Ss \&Bl
+.
+.Ss \&Bo
+Begins a block enclosed by square brackets. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bo 1 ,
+\&.Dv BUFSIZ Bc
+.Ed
+.Pp
+See also
+.Sx \&Bq .
+.
+.Ss \&Bq
+Encloses its arguments in square brackets.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bq 1 , Dv BUFSIZ
+.Ed
+.Pp
+.Em Remarks :
+this macro is sometimes abused to emulate optional arguments for
+commands; the correct macros to use for this purpose are
+.Sx \&Op ,
+.Sx \&Oo ,
+and
+.Sx \&Oc .
+.Pp
+See also
+.Sx \&Bo .
+.
+.Ss \&Brc
+Closes a
+.Sx \&Bro
+block. Does not have any tail arguments.
+.
+.Ss \&Bro
+Begins a block enclosed by curly braces. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bro 1 , ... ,
+\&.Va n Brc
+.Ed
+.Pp
+See also
+.Sx \&Brq .
+.
+.Ss \&Brq
+Encloses its arguments in curly braces.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Brq 1 , ... , Va n
+.Ed
+.Pp
+See also
+.Sx \&Bro .
+.
+.Ss \&Bsx
+Format the BSD/OS version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bsx 1.0
+\&.Bsx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Bt
+Prints
+.Dq is currently in beta test.
+.
+.Ss \&Bx
+Format the BSD version provided as an argument, or a default value if no
+argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bx 4.4
+\&.Bx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Cd
+Configuration declaration (suggested for use only in section four
+manuals). This denotes strings accepted by
+.Xr config 8 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Cd device le0 at scode?
+.Ed
+.Pp
+.Em Remarks :
+this macro is commonly abused by using quoted literals to retain
+white-space and align consecutive
+.Sx \&Cd
+declarations. This practise is discouraged.
+.
+.Ss \&Cm
+Command modifiers. Useful when specifying configuration options or
+keys.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Cm ControlPath
+\&.Cm ControlMaster
+.Ed
+.Pp
+See also
+.Sx \&Fl .
+.
+.Ss \&D1
+One-line indented display. This is formatted by the default rules and
+is useful for simple indented statements. It is followed by a newline.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.D1 Fl abcdefgh
+.Ed
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&Dl .
+.
+.Ss \&Db
+.Ss \&Dc
+Closes a
+.Sx \&Do
+block. Does not have any tail arguments.
+.
+.Ss \&Dd
+Document date. This is the mandatory first macro of any
+.Nm
+manual. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Dd Cm date
+.Pp
+The
+.Cm date
+field may be either
+.Ar $\&Mdocdate$ ,
+which signifies the current manual revision date dictated by
+.Xr cvs 1
+or instead a valid canonical date as specified by
+.Sx Dates .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dd $\&Mdocdate$
+\&.Dd $\&Mdocdate: July 21 2007$
+\&.Dd July 21, 2007
+.Ed
+.Pp
+See also
+.Sx \&Dt
+and
+.Sx \&Os .
+.
+.Ss \&Dl
+One-line intended display. This is formatted as literal text and is
+useful for commands and invocations. It is followed by a newline.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dl % mandoc mdoc.7 | less
+.Ed
+.Pp
+See also
+.Sx \&Bd
+and
+.Sx \&D1 .
+.
+.Ss \&Do
+Begins a block enclosed by double quotes. Does not have any head
+arguments.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
+.Ed
+.Pp
+See also
+.Sx \&Dq .
+.
+.Ss \&Dq
+Encloses its arguments in double quotes.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dq April is the cruellest month
+\e(em T.S. Eliot
+.Ed
+.Pp
+See also
+.Sx \&Do .
+.
+.Ss \&Dt
+Document title. This is the mandatory second macro of any
+.Nm
+file. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
+.Pp
+Its arguments are as follows:
+.Bl -tag -width Ds -offset Ds
+.It Cm title
+The document's title (name). This should be capitalised and is
+required.
+.It Cm section
+The manual section. This may be one of
+.Ar 1
+.Pq utilities ,
+.Ar 2
+.Pq system calls ,
+.Ar 3
+.Pq libraries ,
+.Ar 3p
+.Pq Perl libraries ,
+.Ar 4
+.Pq devices ,
+.Ar 5
+.Pq file formats ,
+.Ar 6
+.Pq games ,
+.Ar 7
+.Pq miscellaneous ,
+.Ar 8
+.Pq system utilities ,
+.Ar 9
+.Pq kernel functions ,
+.Ar X11
+.Pq X Window System ,
+.Ar X11R6
+.Pq X Window System ,
+.Ar unass
+.Pq unassociated ,
+.Ar local
+.Pq local system ,
+.Ar draft
+.Pq draft manual ,
+or
+.Ar paper
+.Pq paper .
+It is also required and should correspond to the manual's filename
+suffix.
+.It Cm volume
+This overrides the volume inferred from
+.Ar section .
+This field is optional, and if specified, must be one of
+.Ar USD
+.Pq users' supplementary documents ,
+.Ar PS1
+.Pq programmers' supplementary documents ,
+.Ar AMD
+.Pq administrators' supplementary documents ,
+.Ar SMM
+.Pq system managers' manuals ,
+.Ar URM
+.Pq users' reference manuals ,
+.Ar PRM
+.Pq programmers' reference manuals ,
+.Ar KM
+.Pq kernel manuals ,
+.Ar IND
+.Pq master index ,
+.Ar MMI
+.Pq master index ,
+.Ar LOCAL
+.Pq local manuals ,
+.Ar LOC
+.Pq local manuals ,
+or
+.Ar CON
+.Pq contributed manuals .
+.It Cm arch
+This specifies a specific relevant architecture. If
+.Cm volume
+is not provided, it may be used in its place, else it may be used
+subsequent that. It, too, is optional. It must be one of
+.Ar alpha ,
+.Ar amd64 ,
+.Ar amiga ,
+.Ar arc ,
+.Ar arm ,
+.Ar armish ,
+.Ar aviion ,
+.Ar hp300 ,
+.Ar hppa ,
+.Ar hppa64 ,
+.Ar i386 ,
+.Ar landisk ,
+.Ar luna88k ,
+.Ar mac68k ,
+.Ar macppc ,
+.Ar mvme68k ,
+.Ar mvme88k ,
+.Ar mvmeppc ,
+.Ar pmax ,
+.Ar sgi ,
+.Ar socppc ,
+.Ar sparc ,
+.Ar sparc64 ,
+.Ar sun3 ,
+.Ar vax ,
+or
+.Ar zaurus .
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dt FOO 1
+\&.Dt FOO 4 KM
+\&.Dt FOO 9 i386
+\&.Dt FOO 9 KM i386
+.Ed
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Os .
+.
+.Ss \&Dv
+Defined variables such as preprocessor constants.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dv BUFSIZ
+\&.Dv STDOUT_FILENO
+.Ed
+.Pp
+See also
+.Sx \&Er .
+.
+.Ss \&Dx
+Format the DragonFlyBSD version provided as an argument, or a default
+value if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Dx 2.4.1
+\&.Dx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Ec
+.Ss \&Ed
+.Ss \&Ef
+.Ss \&Ek
+.Ss \&El
+.Ss \&Em
+Denotes text that should be emphasised. Note that this is a
+presentation term and should not be used for stylistically decorating
+technical terms.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ed Warnings!
+\&.Ed Remarks :
+.Ed
+.
+.Ss \&En
+.Ss \&Eo
+.Ss \&Er
+Error constants (suggested for use only in section two manuals).
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Er EPERM
+\&.Er ENOENT
+.Ed
+.Pp
+See also
+.Sx \&Dv .
+.
+.Ss \&Es
+.
+.Ss \&Ev
+Environmental variables such as those specified in
+.Xr environ 7 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ev DISPLAY
+\&.Ev PATH
+.Ed
+.
+.Ss \&Ex
+Inserts text regarding a utility's exit values. This macro must have
+first the
+.Fl std
+argument specified, then an optional
+.Ar utility .
+If
+.Ar utility
+is not provided, the document's name as stipulated in
+.Sx \&Nm
+is provided.
+.Ss \&Fa
+.Ss \&Fc
+.Ss \&Fd
+.Ss \&Fl
+.Ss \&Fn
+.Ss \&Fo
+.Ss \&Fr
+.Ss \&Ft
+.Ss \&Fx
+Format the FreeBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fx 7.1
+\&.Fx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Nx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Hf
+.Ss \&Ic
+.Ss \&In
+.Ss \&It
+.Ss \&Lb
+.Ss \&Li
+.Ss \&Lk
+Format a hyperlink. The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Lk http://bsd.lv "The BSD.lv Project"
+\&.Lk http://bsd.lv
+.Ed
+.Pp
+See also
+.Sx \&Mt .
+.
+.Ss \&Lp
+.Ss \&Ms
+.Ss \&Mt
+.Ss \&Nd
+.Ss \&Nm
+.Ss \&No
+.Ss \&Ns
+.Ss \&Nx
+Format the NetBSD version provided as an argument, or a default value if
+no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Nx 5.01
+\&.Nx
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Ox ,
+and
+.Sx \&Ux .
+.
+.Ss \&Oc
+.Ss \&Oo
+.Ss \&Op
+.Ss \&Os
+Document operating system version. This is the mandatory third macro of
+any
+.Nm
+file. Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Os Op Cm system
+.Pp
+The optional
+.Cm system
+parameter specifies the relevant operating system or environment. Left
+unspecified, it defaults to the local operating system version. This is
+the suggested form.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Os
+\&.Os KTH/CSC/TCS
+\&.Os BSD 4.3
+.Ed
+.Pp
+See also
+.Sx \&Dd
+and
+.Sx \&Dt .
+.
+.Ss \&Ot
+Unknown usage.
+.Pp
+.Em Remarks :
+this macro has been deprecated.
+.
+.Ss \&Ox
+Format the OpenBSD version provided as an argument, or a default value
+if no argument is provided.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ox 4.5
+\&.Ox
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ux .
+.
+.Ss \&Pa
+.Ss \&Pc
+.Ss \&Pf
+.Ss \&Po
+.Ss \&Pp
+.Ss \&Pq
+.Ss \&Qc
+.Ss \&Ql
+.Ss \&Qo
+.Ss \&Qq
+.
+.Ss \&Re
+Closes a
+.Sx \&Rs
+block. Does not have any tail arguments.
+.
+.Ss \&Rs
+Begins a bibliographic
+.Pq Dq reference
+block. Does not have any head arguments. The block macro may only
+contain
+.Sx \&%A ,
+.Sx \&%B ,
+.Sx \&%C ,
+.Sx \&%D ,
+.Sx \&%I ,
+.Sx \&%J ,
+.Sx \&%N ,
+.Sx \&%O ,
+.Sx \&%P ,
+.Sx \&%Q ,
+.Sx \&%R ,
+.Sx \&%T ,
+and
+.Sx \&%V
+child macros (at least one must be specified).
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Rs
+\&.%A J. E. Hopcroft
+\&.%A J. D. Ullman
+\&.%B Introduction to Automata Theory, Languages, and Computation
+\&.%I Addison-Wesley
+\&.%C Reading, Massachusettes
+\&.%D 1979
+\&.Re
+.Ed
+.Pp
+If an
+.Sx \&Rs
+block is used within a SEE ALSO section, a vertical space is asserted
+before the rendered output, else the block continues on the current
+line.
+.
+.Ss \&Rv
+.Ss \&Sc
+.Ss \&Sh
+.Ss \&Sm
+.Ss \&So
+.Ss \&Sq
+.Ss \&Ss
+.Ss \&St
+.Ss \&Sx
+.Ss \&Sy
+.Ss \&Tn
+.Ss \&Ud
+.Ss \&Ux
+Format the UNIX name. Accepts no argument.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Ux
+.Ed
+.Pp
+See also
+.Sx \&At ,
+.Sx \&Bsx ,
+.Sx \&Bx ,
+.Sx \&Dx ,
+.Sx \&Fx ,
+.Sx \&Nx ,
+and
+.Sx \&Ox .
+.
+.Ss \&Va
+.Ss \&Vt
+.Ss \&Xc
+.Ss \&Xo
+.Ss \&Xr
+.Ss \&br
+.Ss \&sp
.
.
.Sh COMPATIBILITY
This section documents compatibility with other roff implementations, at
this time limited to
-. Xr groff 1 .
+.Xr groff 1 .
The term
-. Qq historic groff
+.Qq historic groff
refers to those versions before the
-. Pa doc.tmac
+.Pa doc.tmac
file re-write
-. Pq somewhere between 1.15 and 1.19 .
-. Pp
-. Bl -dash -compact
-. It
-The
-. Sq \-split
-or
-. Sq \-nosplit
-argument to
-. Sq \&An
-applies to the whole document, not just to the current section as it
-does in groff.
-. It
+.Pq somewhere between 1.15 and 1.19 .
+.
+.Pp
+.Bl -dash -compact
+.It
+Negative scaling units are now truncated to zero instead of creating
+interesting conditions, such as with
+.Sq \&sp -1i .
+Furthermore, the
+.Sq f
+scaling unit, while accepted, is rendered as the default unit.
+.It
In quoted literals, groff allowed pair-wise double-quotes to produce a
standalone double-quote in formatted output. This idiosyncratic
behaviour is no longer applicable.
-. It
+.It
+Display types
+.Sx \&Bd Fl center
+and
+.Fl right
+are aliases for
+.Fl left .
The
-. Sq \&sp
-macro does not accept negative numbers.
-. It
+.Fl file Ar file
+argument is ignored. Since text is not right-justified,
+.Fl ragged
+and
+.Fl filled
+are aliases, as are
+.Fl literal
+and
+.Fl unfilled .
+.It
Blocks of whitespace are stripped from both macro and free-form text
lines (except when in literal mode), while groff would retain whitespace
in free-form text lines.
-. It
+.It
Historic groff has many un-callable macros. Most of these (excluding
some block-level macros) are now callable, conforming to the
non-historic groff version.
-. It
+.It
The vertical bar
-. Sq \(ba
+.Sq \(ba
made historic groff
-. Qq go orbital
+.Qq go orbital
but is a proper delimiter in this implementation.
-. It
-. Sq \&It \-nested
+.It
+.Sx \&It Fl nested
is assumed for all lists (it wasn't in historic groff): any list may be
nested and
-. Sq \-enum
+.Fl enum
lists will restart the sequence only for the sub-list.
-. It
-. Sq \&It \-column
-syntax where column widths may be preceded by other arguments (instead
-of proceeded) is not supported.
-. It
-The
-. Sq \&At
-macro only accepts a single parameter.
-. It
+.It
Some manuals use
-. Sq \&Li
+.Sx \&Li
incorrectly by following it with a reserved character and expecting the
delimiter to render. This is not supported.
-. It
+.It
In groff, the
-. Sq \&Fo
+.Sx \&Fo
macro only produces the first parameter. This is no longer the case.
-. El
+.El
.
.
.Sh SEE ALSO
-. Xr mandoc 1 ,
-. Xr mandoc_char 7
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
.
.
.Sh AUTHORS
The
-. Nm
+.Nm
reference was written by
-. An Kristaps Dzonsons Aq kristaps@kth.se .
-.
-.
-.Sh CAVEATS
-There are many ambiguous parts of mdoc.
-. Pp
-. Bl -dash -compact
-. It
-. Sq \&Fa
-should be
-. Sq \&Va
-as function arguments are variables.
-. It
-. Sq \&Ft
-should be
-. Sq \&Vt
-as function return types are still types. Furthermore, the
-. Sq \&Ft
-should be removed and
-. Sq \&Fo ,
-which ostensibly follows it, should follow the same convention as
-. Sq \&Va .
-. It
-. Sq \&Va
-should formalise that only one or two arguments are acceptable: a
-variable name and optional, preceding type.
-. It
-. Sq \&Fd
-is ambiguous. It's commonly used to indicate an include file in the
-synopsis section.
-. Sq \&In
-should be used, instead.
-. It
-Only the
-. Sq \-literal
-argument to
-. Sq \&Bd
-makes sense. The remaining ones should be removed.
-. It
-The
-. Sq \&Xo
-and
-. Sq \&Xc
-macros should be deprecated.
-. It
-The
-. Sq \&Dt
-macro lacks clarity. It should be absolutely clear which title will
-render when formatting the manual page.
-. It
-A
-. Sq \&Lx
-should be provided for Linux (\(`a la
-. Sq \&Ox ,
-. Sq \&Nx
-etc.).
-. It
-There's no way to refer to references in
-. Sq \&Rs/Re
-blocks.
-. It
-The \-split and \-nosplit dictates via
-. Sq \&An
-are re-set when entering and leaving the AUTHORS section.
-. El
-.
+.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\"
+.\" XXX: this really isn't the place for these caveats.
+.\" .
+.\" .
+.\" .Sh CAVEATS
+.\" There are many ambiguous parts of mdoc.
+.\" .
+.\" .Pp
+.\" .Bl -dash -compact
+.\" .It
+.\" .Sq \&Fa
+.\" should be
+.\" .Sq \&Va
+.\" as function arguments are variables.
+.\" .It
+.\" .Sq \&Ft
+.\" should be
+.\" .Sq \&Vt
+.\" as function return types are still types. Furthermore, the
+.\" .Sq \&Ft
+.\" should be removed and
+.\" .Sq \&Fo ,
+.\" which ostensibly follows it, should follow the same convention as
+.\" .Sq \&Va .
+.\" .It
+.\" .Sq \&Va
+.\" should formalise that only one or two arguments are acceptable: a
+.\" variable name and optional, preceding type.
+.\" .It
+.\" .Sq \&Fd
+.\" is ambiguous. It's commonly used to indicate an include file in the
+.\" synopsis section.
+.\" .Sq \&In
+.\" should be used, instead.
+.\" .It
+.\" Only the
+.\" .Sq \-literal
+.\" argument to
+.\" .Sq \&Bd
+.\" makes sense. The remaining ones should be removed.
+.\" .It
+.\" The
+.\" .Sq \&Xo
+.\" and
+.\" .Sq \&Xc
+.\" macros should be deprecated.
+.\" .It
+.\" The
+.\" .Sq \&Dt
+.\" macro lacks clarity. It should be absolutely clear which title will
+.\" render when formatting the manual page.
+.\" .It
+.\" A
+.\" .Sq \&Lx
+.\" should be provided for Linux (\(`a la
+.\" .Sq \&Ox ,
+.\" .Sq \&Nx
+.\" etc.).
+.\" .It
+.\" There's no way to refer to references in
+.\" .Sq \&Rs/Re
+.\" blocks.
+.\" .It
+.\" The \-split and \-nosplit dictates via
+.\" .Sq \&An
+.\" are re-set when entering and leaving the AUTHORS section.
+.\" .El
+.\" .
git.ckatri.com / mandoc.git / blobdiff