===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -p -r1.4 -r1.5
--- mandoc/mdoc.7	2009/03/14 05:21:58	1.4
+++ mandoc/mdoc.7	2009/03/16 22:19:19	1.5
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.4 2009/03/14 05:21:58 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 14 2009 $
+.Dd $Mdocdate: March 16 2009 $
 .Dt mdoc 7
 .Os
 .\" SECTION
@@ -72,14 +72,16 @@ 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
-.Pq Sq \e&
-or, if applicable, an appropriate escape-sequence used.  Use of reserved
-characters is described in
+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.  
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character
@@ -121,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
@@ -160,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
@@ -200,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
@@ -219,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
@@ -239,17 +351,18 @@ 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 ,
@@ -307,95 +420,6 @@ are followed by non-reserved characters, the behaviour
 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.
-.\" .\" 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
 .\" SECTION
 .Sh SYNTAX
 Macros are generally two and at times three characters in length.  The
@@ -640,6 +664,12 @@ compatibility with these systems.
 .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
@@ -689,3 +719,58 @@ 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