===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.3
retrieving revision 1.5
diff -u -p -r1.3 -r1.5
--- mandoc/mdoc.7	2009/03/13 13:56:13	1.3
+++ mandoc/mdoc.7	2009/03/16 22:19:19	1.5
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.3 2009/03/13 13:56:13 kristaps Exp $
+.\" $Id: mdoc.7,v 1.5 2009/03/16 22:19:19 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -16,7 +16,7 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 13 2009 $
+.Dd $Mdocdate: March 16 2009 $
 .Dt mdoc 7
 .Os
 .\" SECTION
@@ -72,18 +72,21 @@ Within a macro line, the following characters are rese
 .It \&?
 .Pq question
 .It \&!
-.Pq exclmamation 
+.Pq exclamation 
 .El
+.\" PARAGRAPH
 .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&
-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
 .Sq \\
-and followed by either an open-parenthesis 
+followed by either an open-parenthesis 
 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[
@@ -93,10 +96,10 @@ 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.  
+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
@@ -120,6 +123,14 @@ Grammatic:
 .Pp
 Enclosures:
 .Bl -tag -width 12n -offset "XXXX" -compact
+.It \\(lh
+.Pq left hand
+.It \\(rh
+.Pq right hand
+.It \\(<<
+.Pq left guillemot
+.It \\(>>
+.Pq right guillemot
 .It \\(rC
 .Pq right brace
 .It \\(lC
@@ -159,6 +170,18 @@ Indicatives:
 .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
@@ -199,12 +222,98 @@ Mathematical:
 .El
 .\" PARAGRAPH
 .Pp
-Diacritics:
+Diacritics and letter combinations:
 .Bl -tag -width 12n -offset "XXXX" -compact
 .It \\(ga
 .Pq accent grave
 .It \\(aa
 .Pq accent accute
+.It \\(ad
+.Pq accent dieresis
+.It \\(a~
+.Pq accent tilde
+.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 \\('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
 .El
 .\" PARAGRAPH
 .Pp
@@ -218,6 +327,10 @@ Special symbols:
 .Pq bar, deprecated
 .It \\(co
 .Pq copyright
+.It \\(rg
+.Pq registered
+.It \\(tm
+.Pq trademarked
 .It \\&
 .Pq non-breaking space
 .It \\e
@@ -228,30 +341,28 @@ Special symbols:
 .\" SECTION
 .Sh ONTOLOGY
 Macros are classified in an ontology described by scope rules.  
+.\" SUB-SECTION
+.Ss Scope
 .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.
+may span multiple lines.
 .Bl -inset -offset XXXX
 .\" 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 ,
-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
-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 ,
@@ -259,105 +370,56 @@ text or macros following the head on the same and subs
 optionally a
 .Qq tail ,
 text immediately following closure.
-.El
 .\" 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
-.\" .\" 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
+.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 XXXX -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
+.\" 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 XXXX -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
 Macros are generally two and at times three characters in length.  The
@@ -369,45 +431,48 @@ 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).
+.\" PARAGRAPH
 .Pp
-Block full-explicit (may contain head, body, tail):
+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
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 
+\(lBbody...\(rB 
+\&.Yc \(lBtail...\(rB 
 .Ed
+.\" PARAGRAPH
 .Pp
-Block full-implicit (may contain zero or more heads, body, no tail):
+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
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 
+\(lBbody...\(rB 
 \&.Yc
 .Ed
+.\" PARAGRAPH
 .Pp
-Block partial-explicit (may contain head, multi-line body, tail):
+Block partial-explicit (may contain head, multi-line body, tail).
 .Bd -literal -offset XXXX
 \&.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 \
-\(lBbody...\(rB \&Yc \(lBtail...\(rB
+\(lBbody...\(rB \&Yc \(lBtail...\(rB 
 .Ed
+.\" PARAGRAPH
 .Pp
-Block partial-implicit (no head, body, no tail):
+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 XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
 .Ed
+.\" PARAGRAPH
 .Pp
-In-line (may be closed by end-of-line, reserved character, subsequent
-macro invocation or finite number of arguments):
+In-lines have \(>=0 scoped arguments.
 .Bd -literal -offset XXX
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args...
+\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
 
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ;
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx
-
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
 .\"
@@ -589,19 +654,123 @@ then the macro accepts an arbitrary number of argument
 .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
 .El
 .\" 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.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.Sq \&Fo
+and
+.Sq \&St
+historically weren't always callable.  Both are now correctly callable.
+.\" LIST-ITEM
+.It
+.Sq \&It \-nested
+is assumed for all lists: 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
+of proceeded) is not supported.
+.\" LIST-ITEM
+.It
+The 
+.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
+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.
+.El
+.\" SECTION
 .Sh SEE ALSO
 .Xr mdoctree 1 ,
 .Xr mdoclint 1 ,
 .Xr mdocterm 1 ,
 .Xr mdoc 3
 .\" SECTION
-.Sh HISTORY
-This manual describes the language accepted by
-.Xr mdoc 3 ,
-which implements the roff-mdoc macro package.
-.\" SECTION
 .Sh AUTHORS
 The
 .Nm
 utility was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .
+.\" SECTION
+.Sh CAVEATS
+There are several 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, preceeding 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.
+.El