summaryrefslogtreecommitdiffstats
path: root/mdoc.7
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-08-20 12:08:40 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-08-20 12:08:40 +0000
commit0ab938250f5dd690284d8a5c93da8b67649816ee (patch)
treed9169894d7e3525c7abfbf3fd9a3fdb83ae946e6 /mdoc.7
parentc7edeacf2a329a580fb993cc428ebc007c409cf3 (diff)
downloadmandoc-0ab938250f5dd690284d8a5c93da8b67649816ee.tar.gz
Documented omission of `na' and `Dt'.
Clarified COMPATIBILITY section (which modes/inputs).
Diffstat (limited to 'mdoc.7')
-rw-r--r--mdoc.7730
1 files changed, 374 insertions, 356 deletions
diff --git a/mdoc.7 b/mdoc.7
index 44fd5faa..3c6168d1 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -20,209 +20,216 @@
.
.
.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" ,
+.Sq \&.\e" ,
is also ignored.
.
.
-. 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
+.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.
.
.
.Sh MANUAL STRUCTURE
Each
-. Nm
+.Nm
document must begin with a document prologue, containing, in order,
-. Sq \&Dd ,
-. Sq \&Dt ,
+.Sq \&Dd ,
+.Sq \&Dt ,
and
-. Sq \&Os ,
+.Sq \&Os ,
then the NAME section containing at least one
-. Sq \&Nm
+.Sq \&Nm
followed by
-. Sq \&Nd :
-. Bd -literal -offset indent
+.Sq \&Nd :
+.Bd -literal -offset indent
\&.Dd $\&Mdocdate$
\&.Dt mdoc 7
\&.Os
\&.Sh NAME
\&.Nm mdoc
\&.Nd mdoc language reference
-. Ed
-. Pp
+.Ed
+.
+.Pp
Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
but non-compulsory.
.
@@ -230,397 +237,408 @@ but non-compulsory.
.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
+.Sq \&.Pp
and
-. Sq \&.\ \ \ \&Pp
+.Sq \&.\ \ \ \&Pp
are equivalent. Macro names are two or three characters in length.
-. Pp
+.
+.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
+.Pq Sq \&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 \&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
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
+.Po
+.Sq \&It \-bullet ,
+.Sq \-hyphen ,
+.Sq \-dash ,
+.Sq \-enum ,
+.Sq \-item
+.Pc
don't have heads, while
-. Sq \&It \-column
+.Sq \&It \-column
may have multiple heads.
-. Bd -literal -offset indent
+.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 \&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
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
+.Pq So \&Fo Sc , So \&Eo Sc
and/or tail
-. Pq So \&Ec Sc .
-. Bd -literal -offset indent
+.Pq So \&Ec Sc .
+.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 \&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
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 \&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
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 \&%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
.
.
.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
+.Pq somewhere between 1.15 and 1.19 .
+.
+.Pp
+.Bl -dash -compact
+.It
The
-. Sq \-split
+.Sq \-split
or
-. Sq \-nosplit
+.Sq \-nosplit
argument to
-. Sq \&An
+.Sq \&An
applies to the whole document, not just to the current section as it
does in groff.
-. It
+.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
The
-. Sq \&sp
+.Sq \&sp
macro does not accept negative numbers.
-. It
+.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
+.Sq \&It \-nested
is assumed for all lists (it wasn't in historic groff): any list may be
nested and
-. Sq \-enum
+.Sq \-enum
lists will restart the sequence only for the sub-list.
-. It
-. Sq \&It \-column
+.It
+.Sq \&It \-column
syntax where column widths may be preceded by other arguments (instead
of proceeded) is not supported.
-. It
+.It
The
-. Sq \&At
+.Sq \&At
macro only accepts a single parameter.
-. It
+.It
Some manuals use
-. Sq \&Li
+.Sq \&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
+.Sq \&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 .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
.
.
.Sh CAVEATS
There are many ambiguous parts of mdoc.
-. Pp
-. Bl -dash -compact
-. It
-. Sq \&Fa
+.
+.Pp
+.Bl -dash -compact
+.It
+.Sq \&Fa
should be
-. Sq \&Va
+.Sq \&Va
as function arguments are variables.
-. It
-. Sq \&Ft
+.It
+.Sq \&Ft
should be
-. Sq \&Vt
+.Sq \&Vt
as function return types are still types. Furthermore, the
-. Sq \&Ft
+.Sq \&Ft
should be removed and
-. Sq \&Fo ,
+.Sq \&Fo ,
which ostensibly follows it, should follow the same convention as
-. Sq \&Va .
-. It
-. Sq \&Va
+.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
+.It
+.Sq \&Fd
is ambiguous. It's commonly used to indicate an include file in the
synopsis section.
-. Sq \&In
+.Sq \&In
should be used, instead.
-. It
+.It
Only the
-. Sq \-literal
+.Sq \-literal
argument to
-. Sq \&Bd
+.Sq \&Bd
makes sense. The remaining ones should be removed.
-. It
+.It
The
-. Sq \&Xo
+.Sq \&Xo
and
-. Sq \&Xc
+.Sq \&Xc
macros should be deprecated.
-. It
+.It
The
-. Sq \&Dt
+.Sq \&Dt
macro lacks clarity. It should be absolutely clear which title will
render when formatting the manual page.
-. It
+.It
A
-. Sq \&Lx
+.Sq \&Lx
should be provided for Linux (\(`a la
-. Sq \&Ox ,
-. Sq \&Nx
+.Sq \&Ox ,
+.Sq \&Nx
etc.).
-. It
+.It
There's no way to refer to references in
-. Sq \&Rs/Re
+.Sq \&Rs/Re
blocks.
-. It
+.It
The \-split and \-nosplit dictates via
-. Sq \&An
+.Sq \&An
are re-set when entering and leaving the AUTHORS section.
-. El
+.El
.