-.\" $Id: mdoc.7,v 1.13 2009/03/22 08:52:27 kristaps Exp $
+.\" $Id: mdoc.7,v 1.41 2009/07/12 19:34:51 kristaps Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the
-.\" above copyright notice and this permission notice appear in all
-.\" copies.
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
-.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
-.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
-.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
-.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-.\" PERFORMANCE OF THIS SOFTWARE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: March 22 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: July 12 2009 $
+.Dt MDOC 7
.Os
.\" SECTION
.Sh NAME
.Nm mdoc
-.Nd mdoc macro reference
+.Nd mdoc language reference
.\" SECTION
.Sh DESCRIPTION
The
language is used to format
.Bx
.Ux
-manuals. In this reference document, we describe the syntax, ontology
-and structure of the
+manuals. In this reference document, we describe the syntax and
+structure of the
.Nm
-language.
+language. Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with
+.Xr groff 1 .
.\" PARAGRAPH
.Pp
An
.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
prior macros:
-.Bd -literal -offset XXX
+.Bd -literal -offset indent
\&.Sh Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
-.\" PARAGRAPH
-.Pp
-Macros are two- or three-character sequences whose scope rules, rules
-that dictate handling of subsequent-line or same-line arguments, are
-governed by one of five classifications described in this document.
.\" SECTION
.Sh INPUT ENCODING
.Nm
.Pp
The only time a blank line is acceptable is within
the context of
-.Sq \&Bd \-literal
+.Sq \&.Bd \-literal
or
-.Sq \&Bd \-unfilled .
+.Sq \&.Bd \-unfilled .
.Pp
Tab characters
.Pq \et
are only acceptable when delimiting
-.Sq \&Bl \-column
+.Sq \&.Bl \-column
and in
-.Sq \&Bd \-literal
+.Sq \&.Bd \-literal
or
-.Sq \&Bd \-unfilled
+.Sq \&.Bd \-unfilled
contexts.
.\" SUB-SECTION
+.Ss Comments
+Anything following a
+.Sq \e"
+delimiter is considered a comment (unless the
+.Sq \e
+itself has been escaped) and is ignored to the end of line.
+Furthermore, a macro line with only a control character
+.Sq \. ,
+optionally followed by whitespace, is ignored.
+.\" SUB-SECTION
.Ss Reserved Characters
Within a macro line, the following characters are reserved:
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset indent -compact
.It \&.
.Pq period
.It \&,
.Pq question
.It \&!
.Pq exclamation
+.It \&|
+.Pq vertical bar
.El
.\" PARAGRAPH
.Pp
.\" SUB-SECTION
.Ss Special Characters
Special character sequences begin with the escape character
-.Sq \\
+.Sq \e
followed by either an open-parenthesis
.Sq \&(
for two-character sequences; an open-bracket
or a single one-character sequence.
.Pp
Characters may alternatively be escaped by a slash-asterisk,
-.Sq \\* ,
-with the same combinations as described above. This form is deprecated.
-.Pp
-The following is a table of all available escapes.
-.Pp
-Grammatic:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(em
-.Pq em-dash
-.It \\(en
-.Pq en-dash
-.It \e-
-.Pq hyphen
-.It \\\\
-.Pq back-slash
-.It \e'
-.Pq apostrophe
-.It \e`
-.Pq back-tick
-.It \\
-.Pq space
-.It \\.
-.Pq period
-.It \\(r!
-.Pq upside-down exclamation
-.It \\(r?
-.Pq upside-down question
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(lh
-.Pq left hand
-.It \\(rh
-.Pq right hand
-.It \\(Fo
-.Pq left guillemet
-.It \\(Fc
-.Pq right guillemet
-.It \\(fo
-.Pq left guilsing
-.It \\(fc
-.Pq right guilsing
-.It \\(rC
-.Pq right brace
-.It \\(lC
-.Pq left brace
-.It \\(ra
-.Pq right angle
-.It \\(la
-.Pq left angle
-.It \\(rB
-.Pq right bracket
-.It \\(lB
-.Pq left bracket
-.It \\q
-.Pq double-quote
-.It \\(lq
-.Pq left double-quote
-.It \\(Lq
-.Pq left double-quote, deprecated
-.It \\(rq
-.Pq right double-quote
-.It \\(Rq
-.Pq right double-quote, deprecated
-.It \\(oq
-.Pq left single-quote
-.It \\(aq
-.Pq right single-quote
-.It \\(Bq
-.Pq right low double-quote
-.It \\(bq
-.Pq right low single-quote
-.El
-.\" PARAGRAPH
-.Pp
-Indicatives:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(<-
-.Pq left arrow
-.It \\(->
-.Pq right arrow
-.It \\(ua
-.Pq up arrow
-.It \\(da
-.Pq down arrow
-.It \\(<>
-.Pq left-right arrow
-.It \\(lA
-.Pq left double-arrow
-.It \\(rA
-.Pq right double-arrow
-.It \\(uA
-.Pq up double-arrow
-.It \\(dA
-.Pq down double-arrow
-.It \\(hA
-.Pq left-right double-arrow
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(es
-.Pq empty set
-.It \\(ca
-.Pq intersection
-.It \\(cu
-.Pq union
-.It \\(gr
-.Pq gradient
-.It \\(pd
-.Pq partial differential
-.It \\(ap
-.Pq similarity
-.It \\(=)
-.Pq proper superset
-.It \\((=
-.Pq proper subset
-.It \\(eq
-.Pq equals
-.It \\(di
-.Pq division
-.It \\(mu
-.Pq multiplication
-.It \\(pl
-.Pq addition
-.It \\(nm
-.Pq not element
-.It \\(mo
-.Pq element
-.It \\(Im
-.Pq imaginary
-.It \\(Re
-.Pq real
-.It \\(Ah
-.Pq aleph
-.It \\(te
-.Pq existential quantifier
-.It \\(fa
-.Pq universal quantifier
-.It \\(AN
-.Pq logical AND
-.It \\(OR
-.Pq logical OR
-.It \\(no
-.Pq logical NOT
-.It \\(st
-.Pq such that
-.It \\(tf
-.Pq therefore
-.It \\(~~
-.Pq approximate
-.It \\(~=
-.Pq approximately equals
-.It \\(=~
-.Pq congruent
-.It \\(Gt
-.Pq greater-than, deprecated
-.It \\(Lt
-.Pq less-than, deprecated
-.It \\(<=
-.Pq less-than-equal
-.It \\(Le
-.Pq less-than-equal, deprecated
-.It \\(>=
-.Pq greater-than-equal
-.It \\(Ge
-.Pq greater-than-equal
-.It \\(==
-.Pq equal
-.It \\(!=
-.Pq not equal
-.It \\(Ne
-.Pq not equal, deprecated
-.It \\(if
-.Pq infinity
-.It \\(If
-.Pq infinity, deprecated
-.It \\(na
-.Pq NaN , an extension
-.It \\(Na
-.Pq NaN, deprecated
-.It \\(+-
-.Pq plus-minus
-.It \\(Pm
-.Pq plus-minus, deprecated
-.It \\(**
-.Pq asterisk
-.El
-.\" PARAGRAPH
-.Pp
-Ligatures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ss
-.Pq German eszett
-.It \\(AE
-.Pq upper-case AE
-.It \\(ae
-.Pq lower-case AE
-.It \\(OE
-.Pq upper-case OE
-.It \\(oe
-.Pq lower-case OE
-.It \\(ff
-.Pq ff ligature
-.It \\(fi
-.Pq fi ligature
-.It \\(fl
-.Pq fl ligature
-.It \\(Fi
-.Pq ffi ligature
-.It \\(Fl
-.Pq ffl ligature
-.El
-.\" PARAGRAPH
-.Pp
-Diacritics and letters:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq grave accent
-.It \\(aa
-.Pq accute accent
-.It \\(a"
-.Pq umlaut accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(a~
-.Pq tilde accent
-.It \\(a^
-.Pq circumflex accent
-.It \\(ac
-.Pq cedilla accent
-.It \\(ad
-.Pq dieresis accent
-.It \\(ah
-.Pq caron accent
-.It \\(ao
-.Pq ring accent
-.It \\(ho
-.Pq hook accent
-.It \\(ab
-.Pq breve accent
-.It \\(a-
-.Pq macron accent
-.It \\(-D
-.Pq upper-case eth
-.It \\(Sd
-.Pq lower-case eth
-.It \\(TP
-.Pq upper-case thorn
-.It \\(Tp
-.Pq lower-case thorn
-.It \\('A
-.Pq upper-case acute A
-.It \\('E
-.Pq upper-case acute E
-.It \\('I
-.Pq upper-case acute I
-.It \\('O
-.Pq upper-case acute O
-.It \\('U
-.Pq upper-case acute U
-.It \\('a
-.Pq lower-case acute a
-.It \\('e
-.Pq lower-case acute e
-.It \\('i
-.Pq lower-case acute i
-.It \\('o
-.Pq lower-case acute o
-.It \\('u
-.Pq lower-case acute u
-.It \\(`A
-.Pq upper-case grave A
-.It \\(`E
-.Pq upper-case grave E
-.It \\(`I
-.Pq upper-case grave I
-.It \\(`O
-.Pq upper-case grave O
-.It \\(`U
-.Pq upper-case grave U
-.It \\(`a
-.Pq lower-case grave a
-.It \\(`e
-.Pq lower-case grave e
-.It \\(`i
-.Pq lower-case grave i
-.It \\(`o
-.Pq lower-case grave o
-.It \\(`u
-.Pq lower-case grave u
-.It \\(~A
-.Pq upper-case tilde A
-.It \\(~N
-.Pq upper-case tilde N
-.It \\(~O
-.Pq upper-case tilde O
-.It \\(~a
-.Pq lower-case tilde a
-.It \\(~n
-.Pq lower-case tilde n
-.It \\(~o
-.Pq lower-case tilde o
-.It \\(:A
-.Pq upper-case dieresis A
-.It \\(:E
-.Pq upper-case dieresis E
-.It \\(:I
-.Pq upper-case dieresis I
-.It \\(:O
-.Pq upper-case dieresis O
-.It \\(:U
-.Pq upper-case dieresis U
-.It \\(:a
-.Pq lower-case dieresis a
-.It \\(:e
-.Pq lower-case dieresis e
-.It \\(:i
-.Pq lower-case dieresis i
-.It \\(:o
-.Pq lower-case dieresis o
-.It \\(:u
-.Pq lower-case dieresis u
-.It \\(:y
-.Pq lower-case dieresis y
-.It \\(^A
-.Pq upper-case circumflex A
-.It \\(^E
-.Pq upper-case circumflex E
-.It \\(^I
-.Pq upper-case circumflex I
-.It \\(^O
-.Pq upper-case circumflex O
-.It \\(^U
-.Pq upper-case circumflex U
-.It \\(^a
-.Pq lower-case circumflex a
-.It \\(^e
-.Pq lower-case circumflex e
-.It \\(^i
-.Pq lower-case circumflex i
-.It \\(^o
-.Pq lower-case circumflex o
-.It \\(^u
-.Pq lower-case circumflex u
-.It \\(,C
-.Pq upper-case cedilla C
-.It \\(,c
-.Pq lower-case cedilla c
-.It \\(/L
-.Pq upper-case stroke L
-.It \\(/l
-.Pq lower-case stroke l
-.It \\(/O
-.Pq upper-case stroke O
-.It \\(/o
-.Pq lower-case stroke o
-.It \\(oA
-.Pq upper-case ring A
-.It \\(oa
-.Pq lower-case ring a
-.El
-.\" PARAGRAPH
-.Pp
-Monetary:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(Cs
-.Pq Scandinavian
-.It \\(Do
-.Pq dollar
-.It \\(Po
-.Pq pound
-.It \\(Ye
-.Pq yen
-.It \\(Fn
-.Pq florin
-.It \\(ct
-.Pq cent
-.El
-.\" PARAGRAPH
+.Sq \e* ,
+with the same combinations as described above.
.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(de
-.Pq degree
-.It \\(ps
-.Pq paragraph
-.It \\(sc
-.Pq section
-.It \\(dg
-.Pq dagger
-.It \\(dd
-.Pq double dagger
-.It \\(ci
-.Pq circle
-.It \\(ba
-.Pq bar
-.It \\(bb
-.Pq broken bar
-.It \\(Ba
-.Pq bar, deprecated
-.It \\(co
-.Pq copyright
-.It \\(rg
-.Pq registered
-.It \\(tm
-.Pq trademarked
-.It \\&
-.Pq non-breaking space
-.It \\e
-.Pq escape
-.It \\(Am
-.Pq ampersand, deprecated
-.El
+Terms may also be text-decorated using the
+.Sq \ef
+escape followed by a text-decoration letter: B (bold), I, (italic), or P
+and R (Roman, or reset). This form is not recommended.
+.\" SUB-SECTION
+.Ss Whitespace
+Unless in literal mode or specifically escaped, consecutive blocks of
+whitespace are pruned from input. These are later re-added, if
+applicable, by a front-end utility such as
+.Xr mandoc 1 .
.\" SECTION
-.Sh ONTOLOGY
-Macros are classified in an ontology described by their scope rules.
-Some macros are allowed to deviate from their classifications to
-preserve backward-compatibility with old macro combinations still found
-in the manual corpus. These are specifically noted on a per-macro
-basis.
+.Sh STRUCTURE
+Each
+.Nm
+document must begin with the document prologue, containing, in order,
+.Sq \&.Dd ,
+.Sq \&.Dt ,
+and
+.Sq \&.Os .
+Following these, the document body must begin with the NAME section
+containing at least one
+.Sq \&.Nm
+followed by a
+.Sq \&.Nd
+macro.
+.Pp
+At least one free-form or macro line must follow this prologue.
+.\"
+.Ss Classification
+Macros are classified by their scope rules. Some macros are allowed to
+deviate from their classifications to preserve backward-compatibility
+with old macro combinations still found in the manual corpus. These are
+specifically noted on a per-macro basis.
.\" SUB-SECTION
.Ss Scope
.Bl -inset
.It Em Block
macros enclose other block macros, in-line macros or text, and
may span multiple lines.
-.Bl -inset -offset XXXX
+.Bl -inset -offset indent
.\" LIST-ITEM
.It Em Full-block
macros always span multiple lines. They consist of zero or
refers to block full-explicit and so on.
.\" PARAGRAPH
.Pp
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width 12n -offset indent -compact
.It BPE , BFE
corresponding explicit closure macro
.It BFI
one of the following scenarios (unless specifically noted otherwise):
.\" PARAGRAPH
.Pp
-.Bl -dash -offset XXXX -compact
+.Bl -dash -offset indent -compact
.It
a sequence of >0 space-separated
.Sx Reserved Characters ,
In other circumstances, scope is simply closed out.
.\" SECTION
.Sh SYNTAX
-Macros are generally two and at times three characters in length. The
-syntax of macro invocation depends on its classification.
+Macros are two or three characters in length. The syntax of macro
+invocation depends on its classification.
.Qq \-arg
refers to the macro arguments (which may contain zero or more values).
In these illustrations,
.\" PARAGRAPH
.Pp
Block full-explicit (may contain head, body, tail).
-.Bd -literal -offset XXXX
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc \(lBtail...\(rB
.\" PARAGRAPH
.Pp
Block full-implicit (may contain zero or more heads, body, no tail).
-.Bd -literal -offset XXXX
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
\(lBbody...\(rB
\&.Yc
.\" PARAGRAPH
.Pp
Block partial-explicit (may contain head, multi-line body, tail).
-.Bd -literal -offset XXXX
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc \(lBtail...\(rB
section may be followed by zero or more
.Sx Reserved Words .
These are in the block scope, but not in the body scope.
-.Bd -literal -offset XXXX
+.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
.Ed
.\" PARAGRAPH
.Pp
In-lines have \(>=0 scoped arguments.
-.Bd -literal -offset XXX
+.Bd -literal -offset indent
\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
.Ed
-.\"
+.\" SECTION
.Sh MACROS
This section contains a complete list of all
.Nm
-macros, arranged ontologically. A
+macros, arranged by classification. A
.Qq callable
-macro is may be invoked subsequent to the initial macro-line macro. A
+macro is invoked subsequent to the initial macro-line macro. A
.Qq parsable
macro may be followed by further (ostensibly callable) macros.
.\" SUB-SECTION
subsequent lines prior to closure. None of these macros have tails;
some
.Po
-.Sq \&It \-bullet ,
+.Sq \&.It \-bullet ,
.Sq \-hyphen ,
.Sq \-dash ,
.Sq \-enum ,
.Pc
don't have heads.
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "Closing"
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
+.It \&.Nd Ta \&No Ta \&No Ta \&.Sh
.It \&.Sh Ta \&No Ta \&No Ta \&.Sh
.It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
.It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
the explicit scope rules. All contains bodies, some may contain heads
.Pq So \&Bf Sc .
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
+.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 \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
All of these are callable and parsed for further macros. Their scopes
close at the invocation's end-of-line.
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable
.It \&.Aq Ta Yes Ta Yes
.It \&.Op Ta Yes Ta Yes
.\" PARAGRAPH
.Pp
The
-.Sq \&Op
-may be broken by \&Oc as in the following example:
-.Bd -literal -offset XXXX
+.Sq \&.Op
+may be broken by
+.Sq \&.Oc
+as in the following example:
+.Bd -literal -offset indent
\&.Oo
\&.Op Fl a Oc
.Ed
.Pp
In the above example, the scope of
-.Sq \&Op
+.Sq \&.Op
is technically broken by
-.Sq \&Oc ,
+.Sq \&.Oc ,
however, due to the overwhelming existence of this sequence, it's
allowed.
.\" SUB-SECTION
.Ss Block partial-explicit
Each of these contains 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 .
+.Pq So \&.Ec Sc .
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
.It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
.It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
.Pq n ,
then the macro accepts an arbitrary number of arguments.
.Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
.It \&.Dd Ta \&No Ta \&No Ta >0
.It \&.Dt Ta \&No Ta \&No Ta n
.It \&.Os Ta \&No Ta \&No Ta n
.It \&.Pp Ta \&No Ta \&No Ta 0
.It \&.Ad Ta Yes Ta Yes Ta n
-.It \&.An Ta \&No Ta Yes Ta n
+.It \&.An Ta Yes Ta Yes Ta n
.It \&.Ar Ta Yes Ta Yes Ta n
.It \&.Cd Ta Yes Ta \&No Ta >0
.It \&.Cm 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 \&.Ft Ta \&No Ta Yes Ta n
+.It \&.Ft Ta Yes Ta Yes Ta n
.It \&.Ic Ta Yes Ta Yes Ta >0
.It \&.In Ta \&No Ta \&No Ta n
.It \&.Li Ta Yes Ta Yes Ta n
-.It \&.Nd Ta \&No Ta \&No Ta n
.It \&.Nm Ta Yes Ta Yes Ta n
.It \&.Ot Ta \&No Ta \&No Ta n
.It \&.Pa Ta Yes Ta Yes Ta n
.It \&.Bsx Ta Yes Ta Yes Ta n
.It \&.Bx Ta Yes Ta Yes Ta n
.It \&.Db Ta \&No Ta \&No Ta 1
-.It \&.Em Ta Yes Ta Yes Ta n
+.It \&.Em Ta Yes Ta Yes Ta >0
.It \&.Fx Ta Yes Ta Yes Ta n
-.It \&.Ms Ta \&No Ta Yes Ta >0
+.It \&.Ms Ta Yes Ta Yes Ta >0
.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 \&.Lb Ta \&No Ta \&No Ta 1
.It \&.Ap Ta Yes Ta Yes Ta 0
.It \&.Lp Ta \&No Ta \&No Ta 0
-.It \&.Lk Ta \&No Ta Yes Ta >0
-.It \&.Mt Ta \&No Ta Yes Ta >0
+.It \&.Lk Ta Yes Ta Yes Ta n
+.It \&.Mt Ta Yes Ta Yes Ta >0
.It \&.Es Ta \&No Ta \&No Ta 0
.It \&.En Ta \&No Ta \&No Ta 0
.El
.Pp
The
-.Sq \&Ot ,
-.Sq \&Fr ,
-.Sq \&Es
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es
and
-.Sq \&En ,
+.Sq \&.En ,
macros are obsolete.
.\" SECTION
.Sh COMPATIBILITY
-The mdoc language was traditionally a
-.Qq roff
-macro package; most existing manuals were written with mdoc syntax
-dictated by system-dependent roff installations. This section documents
-compatibility with these systems.
+This section documents compatibility with other roff implementations, at
+this time limited to
+.Xr groff 1 .
+The term
+.Qq historic groff
+refers to those versions before the
+.Pa doc.tmac
+file re-write
+.Pq somewhere between 1.15 and 1.19 .
.Pp
.Bl -dash -compact
.\" LIST-ITEM
.It
-.Sq \&Fo
+Some character sequences in groff are not handled depending on escape
+style, e.g.,
+.Sq \e(ba
and
-.Sq \&St
-historically weren't always callable. Both are now correctly callable.
+.Sq \e*(Ba
+may not be interchanged. This is no longer the case: all character
+sequences resolve to the same symbol, regardless the escape style.
+.\" LIST-ITEM
+.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.
.\" LIST-ITEM
.It
-.Sq \&It \-nested
-is assumed for all lists: any list may be nested and
+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.
+.\" LIST-ITEM
+.It
+The vertical bar
+.Sq \(ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.
+.\" LIST-ITEM
+.It
+.Sq \&.It \-nested
+is assumed for all lists (it wasn't in historic groff): any list may be
+nested and
.Sq \-enum
lists will restart the sequence only for the sub-list.
.\" LIST-ITEM
.It
-.Sq \&It \-column
-syntax where column widths may be preceeded by other arguments (instead
+.Sq \&.It \-column
+syntax where column widths may be preceded by other arguments (instead
of proceeded) is not supported.
.\" LIST-ITEM
.It
The
-.Sq \&At
+.Sq \&.At
macro only accepts a single parameter.
.\" LIST-ITEM
.It
-The system-name macros (
-.Ns Sq \&At ,
-.Sq \&Bsx ,
-.Sq \&Bx ,
-.Sq \&Fx ,
-.Sq \&Nx ,
-.Sq \&Ox ,
-and
-.Sq \&Ux )
-are callable.
-.\" LIST-ITEM
-.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.
.\" LIST-ITEM
.It
-.Sq \&Cd
-is callable.
+If an special-character control character is escaped
+.Sq \e\e ,
+it will obviously not render the subsequent sequence. Even newer
+versions of groff seem to dither on this.
+.\" LIST-ITEM
+.It
+In groff, the
+.Sq \&.Fo
+macro only produces the first parameter. This is no longer the case.
.El
.\" SECTION
.Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
.\" SECTION
.Sh AUTHORS
The
.Nm
utility was written by
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
.\" SECTION
.Sh CAVEATS
-There are several ambiguous parts of mdoc.
+There are many ambiguous parts of mdoc.
.Pp
.Bl -dash -compact
.\" LIST-ITEM
.It
-.Sq \&Fa
+.Sq \&.Fa
should be
-.Sq \&Va
+.Sq \&.Va
as function arguments are variables.
.\" LIST-ITEM
.It
-.Sq \&Ft
+.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 .
+.Sq \&.Va .
.\" LIST-ITEM
.It
-.Sq \&Va
+.Sq \&.Va
should formalise that only one or two arguments are acceptable: a
-variable name and optional, preceeding type.
+variable name and optional, preceding type.
.\" LIST-ITEM
.It
-.Sq \&Fd
+.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.
.\" LIST-ITEM
.It
Only the
.Sq \-literal
argument to
-.Sq \&Bd
+.Sq \&.Bd
makes sense. The remaining ones should be removed.
.\" LIST-ITEM
.It
The
-.Sq \&Xo
+.Sq \&.Xo
and
-.Sq \&Xc
+.Sq \&.Xc
macros should be deprecated.
.\" LIST-ITEM
.It
The
-.Sq \&Dt
+.Sq \&.Dt
macro lacks clarity. It should be absolutely clear which title will
render when formatting the manual page.
.\" LIST-ITEM
.It
A
-.Sq \&Lx
+.Sq \&.Lx
should be provided for Linux (\(`a la
-.Sq \&Ox ,
-.Sq \&Nx
+.Sq \&.Ox ,
+.Sq \&.Nx
etc.).
+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&.Rs/.Re
+blocks.
+.\" LIST-ITEM
+.It
+The \-split and \-nosplit arguments to
+.Sq \&.An
+are inane.
+.\" LIST-ITEM
+.It
+The end-of-line whitespace warnings are superfluous holdovers from
+historic groff.
.El
git.ckatri.com / mandoc.git / blobdiff