Removed superfluous FIXMEs in mdoc_term.c.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 72ad225c9737e744f853d3035eac481f93740ad3..a7df1cb98accd611ed095d11af306decf687d6fc 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,28 +1,26 @@
-.\" $Id: mdoc.7,v 1.3 2009/03/13 13:56:13 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.41 2009/07/12 19:34:51 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\"
 .\" 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 13 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: July 12 2009 $
+.Dt MDOC 7

 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc

-.Nd mdoc macro reference
+.Nd mdoc language reference

 .\" SECTION
 .Sh DESCRIPTION
 The
 .\" SECTION
 .Sh DESCRIPTION
 The


@@ -30,29 +28,69 @@ The
 language is used to format 
 .Bx 
 .Ux
 language is used to format 
 .Bx 
 .Ux

-manuals.  An
+manuals.  In this reference document, we describe the syntax and
+structure of the 
+.Nm
+language.  Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with 
+.Xr groff 1 .
+.\" PARAGRAPH
+.Pp
+An

 .Nm
 document follows simple rules:  lines beginning with the control
 .Nm
 document follows simple rules:  lines beginning with the control

-character
+character 

 .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of
 .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of

-prior macros.  This document describes the encoding, ontology and syntax
-of these macros.
+prior macros:
+.Bd -literal -offset indent
+\&.Sh Macro lines change control state.
+Other lines are interpreted within the current state.
+.Ed

 .\" SECTION
 .\" SECTION

-.Sh CHARACTER ENCODING
+.Sh INPUT ENCODING

 .Nm
 .Nm

-documents may contain only printable alphanumeric characters, the space
+documents may contain only graphable 7-bit ASCII characters, the space

 character
 .Sq \  ,
 and, in certain circumstances, the tab character
 .Sq \et .
 All manuals must have
 .Sq \en
 character
 .Sq \  ,
 and, in certain circumstances, the tab character
 .Sq \et .
 All manuals must have
 .Sq \en

-line termination.
+line termination.  
+.Pp
+The only time a blank line is acceptable is within
+the context of 
+.Sq \&.Bd \-literal
+or
+.Sq \&.Bd \-unfilled .
+.Pp
+Tab characters 
+.Pq \et
+are only acceptable when delimiting 
+.Sq \&.Bl \-column 
+and in
+.Sq \&.Bd \-literal
+or
+.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:
 .\" 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 \&,
 .It \&.
 .Pq period
 .It \&,


@@ -72,18 +110,23 @@ Within a macro line, the following characters are reserved:
 .It \&?
 .Pq question
 .It \&!
 .It \&?
 .Pq question
 .It \&!

-.Pq exclmamation 
+.Pq exclamation 
+.It \&|
+.Pq vertical bar 

 .El
 .El

+.\" PARAGRAPH

 .Pp
 .Pp

-Use of these characters must either be escaped with a non-breaking space
+Use of reserved characters is described in
+.Sx Closure .
+For general non-reserved use, characters must either be escaped with a
+non-breaking space

 .Pq Sq \e&
 .Pq Sq \e&

-or, if applicable, an appropriate escape-sequence used.  Use of reserved
-characters is described later in this document.
+or, if applicable, an appropriate escape-sequence used.  

 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character

-.Sq \\
-and followed by either an open-parenthesis 
+.Sq \e
+followed by either an open-parenthesis 

 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[
 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[


@@ -92,166 +135,64 @@ for n-character sequences (terminated at a close-bracket
 or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
 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, however, is
-deprecated.  The following is a table of all available escapes, arranged
-by classification.  
-.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
-.El
-.\" PARAGRAPH
-.Pp
-Enclosures:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.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
-.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
-.El
-.\" PARAGRAPH
-.Pp
-Mathematical:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.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
+.Sq \e* ,
+with the same combinations as described above.

 .Pp
 .Pp

-Diacritics:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(ga
-.Pq accent grave
-.It \\(aa
-.Pq accent accute
-.El
-.\" PARAGRAPH
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(bu
-.Pq bullet
-.It \\(ba
-.Pq bar
-.It \\(Ba
-.Pq bar, deprecated
-.It \\(co
-.Pq copyright
-.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
 .\" SECTION

-.Sh ONTOLOGY
-Macros are classified in an ontology described by scope rules.  
+.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 
 .\" LIST-ITEM
 .It Em Block
 macros enclose other block macros, in-line macros or text, and
 .Bl -inset 
 .\" LIST-ITEM
 .It Em Block
 macros enclose other block macros, in-line macros or text, and

-may span multiple lines.  
-.Qq Implicit 
-block scope is closed by a subsequent invocation of the same macro,
-one of a set of corresponding closure macros or end-of-file.
-.Qq Explicit 
-block scope is closed by a corresponding closure macro.
-.Bl -inset -offset XXXX
+may span multiple lines.
+.Bl -inset -offset indent

 .\" LIST-ITEM
 .It Em Full-block
 .\" LIST-ITEM
 .It Em Full-block

-macros always span multiple lines.  They consist optionally of one or
+macros always span multiple lines.  They consist of zero or 

 more
 .Qq heads ,
 more
 .Qq heads ,

-subsequent macros or text on the same line following invocation; a
+subsequent macros or text on the same line following invocation; an
+optional

 .Qq body ,
 which spans subsequent lines of text or macros; and an optional
 .Qq tail ,
 macros or text on the same line following closure.
 .\" LIST-ITEM
 .It Em Partial-block
 .Qq body ,
 which spans subsequent lines of text or macros; and an optional
 .Qq tail ,
 macros or text on the same line following closure.
 .\" LIST-ITEM
 .It Em Partial-block

-macros may span multiple lines.  They consists optionally of a 
+macros may span multiple lines.  They consists of a optional

 .Qq head ,
 text immediately following invocation; always a 
 .Qq body ,
 .Qq head ,
 text immediately following invocation; always a 
 .Qq body ,


@@ -259,109 +200,60 @@ text or macros following the head on the same and subsequent lines; and
 optionally a
 .Qq tail ,
 text immediately following closure.
 optionally a
 .Qq tail ,
 text immediately following closure.

-.El

 .\" LIST-ITEM
 .It Em In-line
 .\" LIST-ITEM
 .It Em In-line

-macros may only enclose text and span at most a single line.  If
-a macro is parsable, its scope may be closed by subsequent macros or
-delimiting punctuation.  In-line macros follow different conventions for
-closure; see 
-.Sx MACROS 
-for per-macro details.
+macros may only enclose text and span at most a single line. 
+.El
+.El
+.\" SUB-SECTION
+.Ss Closure
+Closure of a macro's scope depends first on its classification, then
+on whether it's parsable.  In this table,
+.Sq BFE
+refers to block full-explicit and so on.
+.\" PARAGRAPH
+.Pp
+.Bl -tag -width 12n -offset indent -compact
+.It BPE , BFE
+corresponding explicit closure macro
+.It BFI
+end-of-file or a corresponding implicit closure macro
+.It BPI
+end-of-line (body may be closed by >0 space-separated
+.Sx Reserved Characters ,
+although block scope will still be open)
+.It INL
+end-of-line

 .El
 .El

-.\" .\" SUB-SECTION
-.\" .Ss Examples
-.\" The following examples illustrate each macro classification.
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit full-block.  Has head, body and no tail.  Scope closed by
-.\" second
-.\" .Sq \&Sh
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested implicit full-block, where the subsection
-.\" .Sq \&Ss
-.\" is within the scope of the parent section
-.\" .Sq \&Sh
-.\" and closed along with its parent by the subsequent
-.\" .Sq \&Sh .
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" \&.Ss Subsection 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit full-block.  Has a head, a body and no tail.  Scope closed by 
-.\" .Sq \&Ef
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bf symbolic
-.\" body...
-.\" \&.Ef
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested explicit/implicit scope.  
-.\" .Sq \&It
-.\" macro is an implicit block whose scope is closed by the explicit
-.\" .Sq \&El
-.\" closure.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bl \-bullet
-.\" \&.It head
-.\" body...
-.\" \&.El
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block.  Has head, body and tail.  Scope closed by
-.\" .Sq \&Ec 
-.\" invocation.
-.\" .Bd -literal -offset XXX
-.\" \&.Eo head body... \&Ec tail
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block.  Has only body.  Scope is closed by end-of-line.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body...
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block with only body and scope closed by 
-.\" .Sq \&Ac
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block enclosing explicit partial-block.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body... \&Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Inline macros, several in sequence.  Scope is closed for
-.\" .Sq \&Fl
-.\" by the punctuation delimiter and 
-.\" .Sq \&Ar
-.\" by the end-of-line.
-.\" .Bd -literal -offset XXXX
-.\" \&.Fl text0 text1 ; Ar text0 text1
-.\" .Ed
+.\" PARAGRAPH
+.Pp
+If a macro (block or in-line) is parsable, it may also be closed out by
+one of the following scenarios (unless specifically noted otherwise):
+.\" PARAGRAPH
+.Pp
+.Bl -dash -offset indent -compact
+.It 
+a sequence of >0 space-separated
+.Sx Reserved Characters ,
+.It
+another macro,
+.It
+end-of-line, or
+.It
+completion of a set number of arguments.
+.El
+.\" PARAGRAPH
+.Pp
+If >0 space-separated
+.Sx Reserved Characters
+are followed by non-reserved characters, the behaviour differs per
+macro.  In general, scope of the macro is closed and re-opened:
+subsequent tokens are interpreted as if the scope had just been opened.
+In other circumstances, scope is simply closed out.

 .\" SECTION
 .Sh SYNTAX
 .\" 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, 
 .Qq \-arg
 refers to the macro arguments (which may contain zero or more values).
 In these illustrations, 


@@ -369,54 +261,57 @@ In these illustrations,
 opens the scope of a macro, and if specified,
 .Sq \&.Yc
 closes it out (closure may be implicit at end-of-line or end-of-file).
 opens the scope of a macro, and if specified,
 .Sq \&.Yc
 closes it out (closure may be implicit at end-of-line or end-of-file).

+.\" PARAGRAPH

 .Pp
 .Pp

-Block full-explicit (may contain head, body, tail):
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
+Block full-explicit (may contain head, body, tail).
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 
+\(lBbody...\(rB 
+\&.Yc \(lBtail...\(rB 

 .Ed
 .Ed

+.\" PARAGRAPH

 .Pp
 .Pp

-Block full-implicit (may contain zero or more heads, body, no tail):
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
-\(lBbody...\(rB
+Block full-implicit (may contain zero or more heads, body, no tail).
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 
+\(lBbody...\(rB 

 \&.Yc
 .Ed
 \&.Yc
 .Ed

+.\" PARAGRAPH

 .Pp
 .Pp

-Block partial-explicit (may contain head, multi-line body, tail):
-.Bd -literal -offset XXXX
+Block partial-explicit (may contain head, multi-line body, tail).
+.Bd -literal -offset indent

 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 

-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
+\(lBbody...\(rB 
+\&.Yc \(lBtail...\(rB 

 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \

-\(lBbody...\(rB \&Yc \(lBtail...\(rB
+\(lBbody...\(rB \&Yc \(lBtail...\(rB 

 .Ed
 .Ed

+.\" PARAGRAPH

 .Pp
 .Pp

-Block partial-implicit (no head, body, no tail):
-.Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB
+Block partial-implicit (no head, body, no tail).  Note that the body
+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 indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB

 .Ed
 .Ed

+.\" PARAGRAPH

 .Pp
 .Pp

-In-line (may be closed by end-of-line, reserved character, subsequent
-macro invocation or finite number of arguments):
-.Bd -literal -offset XXX
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args...
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ;
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx
+In-lines have \(>=0 scoped arguments.
+.Bd -literal -offset indent
+\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB

 
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
 
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed

-.\"
+.\" SECTION

 .Sh MACROS
 This section contains a complete list of all 
 .Nm
 .Sh MACROS
 This section contains a complete list of all 
 .Nm

-macros, arranged ontologically.  A 
+macros, arranged by classification.  A 

 .Qq callable
 .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
 .Qq parsable
 macro may be followed by further (ostensibly callable) macros.
 .\" SUB-SECTION


@@ -425,7 +320,7 @@ The head of these macros follows invocation; the body is the content of
 subsequent lines prior to closure.  None of these macros have tails;
 some 
 .Po
 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 ,
 .Sq \-hyphen , 
 .Sq \-dash ,
 .Sq \-enum ,


@@ -433,8 +328,9 @@ some
 .Pc
 don't have heads.
 .Pp
 .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 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
 .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


@@ -445,7 +341,7 @@ None of these macros are callable or parsed.  The last column indicates
 the explicit scope rules.  All contains bodies, some may contain heads 
 .Pq So \&Bf Sc .
 .Pp
 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
 .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


@@ -461,7 +357,7 @@ the explicit scope rules.  All contains bodies, some may contain heads
 All of these are callable and parsed for further macros.  Their scopes
 close at the invocation's end-of-line.
 .Pp
 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
 .It Em Macro Ta Em Callable Ta Em Parsable
 .It \&.Aq    Ta    Yes   Ta    Yes
 .It \&.Op    Ta    Yes   Ta    Yes


@@ -475,15 +371,33 @@ close at the invocation's end-of-line.
 .It \&.Dl    Ta    \&No  Ta    Yes
 .It \&.Ql    Ta    Yes   Ta    Yes
 .El
 .It \&.Dl    Ta    \&No  Ta    Yes
 .It \&.Ql    Ta    Yes   Ta    Yes
 .El

+.\" PARAGRAPH
+.Pp
+The
+.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
+is technically broken by 
+.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 
 .\" 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 
 and/or tail 

-.Pq So \&Ec Sc .
+.Pq So \&.Ec Sc .

 .Pp
 .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
 .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


@@ -517,36 +431,35 @@ arguments is
 .Pq n , 
 then the macro accepts an arbitrary number of arguments.
 .Pp
 .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 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 \&.Ar    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
 .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n

-.It \&.Dv    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Dv    Ta    Yes   Ta    Yes     Ta    n

 .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0

-.It \&.Ev    Ta    Yes   Ta    Yes     Ta    >0
+.It \&.Ev    Ta    Yes   Ta    Yes     Ta    n

 .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0

-.It \&.Fa    Ta    Yes   Ta    Yes     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 \&.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 \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.In    Ta    \&No  Ta    \&No    Ta    n

-.It \&.Li    Ta    Yes   Ta    Yes     Ta    >0
-.It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
+.It \&.Li    Ta    Yes   Ta    Yes     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 \&.Rv    Ta    \&No  Ta    \&No    Ta    0
 .It \&.St    Ta    \&No  Ta    Yes     Ta    1
 .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 \&.Rv    Ta    \&No  Ta    \&No    Ta    0
 .It \&.St    Ta    \&No  Ta    Yes     Ta    1

-.It \&.Va    Ta    Yes   Ta    Yes     Ta    >0
+.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 \&.%A    Ta    \&No  Ta    \&No    Ta    >0
 .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
 .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0


@@ -567,7 +480,7 @@ then the macro accepts an arbitrary number of arguments.
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
 .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 \&.No    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n


@@ -578,6 +491,7 @@ then the macro accepts an arbitrary number of arguments.
 .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
 .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n

+.It \&.Dx    Ta    Yes   Ta    Yes     Ta    n

 .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
 .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n


@@ -585,23 +499,177 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&.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
 .El

+.Pp
+The
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es 
+and
+.Sq \&.En ,
+macros are obsolete.

 .\" SECTION
 .\" SECTION

-.Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Sh COMPATIBILITY
+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
+Some character sequences in groff are not handled depending on escape
+style, e.g., 
+.Sq \e(ba
+and
+.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
+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 preceded by other arguments (instead
+of proceeded) is not supported.
+.\" LIST-ITEM
+.It
+The 
+.Sq \&.At
+macro only accepts a single parameter.
+.\" LIST-ITEM
+.It
+Some manuals use
+.Sq \&.Li
+incorrectly by following it with a reserved character and expecting the
+delimiter to render.  This is not supported.
+.\" LIST-ITEM
+.It
+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
 .\" SECTION

-.Sh HISTORY
-This manual describes the language accepted by
-.Xr mdoc 3 ,
-which implements the roff-mdoc macro package.
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc_char 7

 .\" SECTION
 .Sh AUTHORS
 The
 .Nm
 utility was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh AUTHORS
 The
 .Nm
 utility was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .

+.\" SECTION
+.Sh CAVEATS
+There are many ambiguous parts of mdoc.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.Sq \&.Fa
+should be 
+.Sq \&.Va
+as function arguments are variables.
+.\" LIST-ITEM
+.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 .
+.\" LIST-ITEM
+.It
+.Sq \&.Va
+should formalise that only one or two arguments are acceptable: a
+variable name and optional, preceding type.
+.\" LIST-ITEM
+.It
+.Sq \&.Fd
+is ambiguous.  It's commonly used to indicate an include file in the
+synopsis section.  
+.Sq \&.In
+should be used, instead.
+.\" LIST-ITEM
+.It
+Only the
+.Sq \-literal
+argument to
+.Sq \&.Bd
+makes sense.  The remaining ones should be removed.
+.\" LIST-ITEM
+.It
+The 
+.Sq \&.Xo
+and
+.Sq \&.Xc
+macros should be deprecated.
+.\" LIST-ITEM
+.It
+The
+.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
+should be provided for Linux (\(`a la 
+.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