===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.4
retrieving revision 1.20
diff -u -p -r1.4 -r1.20
--- mandoc/mdoc.7	2009/03/14 05:21:58	1.4
+++ mandoc/mdoc.7	2009/04/12 19:19:57	1.20
@@ -1,6 +1,6 @@
-.\" $Id: mdoc.7,v 1.4 2009/03/14 05:21:58 kristaps Exp $
+.\" $Id: mdoc.7,v 1.20 2009/04/12 19:19:57 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the
@@ -16,13 +16,13 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 14 2009 $
-.Dt mdoc 7
+.Dd $Mdocdate: April 12 2009 $
+.Dt MDOC 7
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
-.Nd mdoc macro reference
+.Nd mdoc language reference
 .\" SECTION
 .Sh DESCRIPTION
 The
@@ -30,25 +30,50 @@ The
 language is used to format 
 .Bx 
 .Ux
-manuals.  An
+manuals.  In this reference document, we describe the syntax, ontology
+and structure of the 
 .Nm
+language.
+.\" PARAGRAPH
+.Pp
+An
+.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
-prior macros.  This document describes the encoding, ontology and syntax
-of these macros.
+prior macros:
+.Bd -literal -offset XXX
+\&.Sh Macro lines change control state.
+Other lines are interpreted within the current state.
+.Ed
 .\" SECTION
-.Sh CHARACTER ENCODING
+.Sh INPUT ENCODING
 .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
-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 Reserved Characters
 Within a macro line, the following characters are reserved:
@@ -72,18 +97,20 @@ 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
-.Sq \\
+.Sq \e
 followed by either an open-parenthesis 
 .Sq \&(
 for two-character sequences; an open-bracket
@@ -93,142 +120,15 @@ for n-character sequences (terminated at a close-brack
 or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
-.Sq \\* ,
+.Sq \e* ,
 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
-.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
-.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 
 .\" SECTION
-.Sh ONTOLOGY
-Macros are classified in an ontology described by scope rules.  
+.Sh STRUCTURE
+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.
 .\" SUB-SECTION
 .Ss Scope
 .Bl -inset 
@@ -239,17 +139,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,99 +208,10 @@ 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
-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, 
@@ -457,7 +269,7 @@ This section contains a complete list of all 
 .Nm
 macros, arranged ontologically.  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
@@ -466,7 +278,7 @@ The head of these macros follows invocation; the body 
 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 ,
@@ -516,13 +328,31 @@ close at the invocation's end-of-line.
 .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 XXXX
+\&.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 
-.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
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
@@ -569,25 +399,25 @@ then the macro accepts an arbitrary number of argument
 .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 \&.Ev    Ta    Yes   Ta    Yes     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    >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 \&.Ft    Ta    \&No  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    >0
+.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 \&.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
@@ -619,6 +449,7 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -628,7 +459,17 @@ then the macro accepts an arbitrary number of argument
 .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 \&.Es    Ta    \&No  Ta    \&No    Ta    0
+.It \&.En    Ta    \&No  Ta    \&No    Ta    0
 .El
+.Pp
+The
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es 
+and
+.Sq \&.En ,
+macros are obsolete.
 .\" SECTION
 .Sh COMPATIBILITY
 The mdoc language was traditionally a 
@@ -640,52 +481,124 @@ compatibility with these systems.
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
-.Sq \&It \-nested
+.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
+.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
+.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 ,
+.Ns Sq \&.At ,
+.Sq \&.Bsx ,
+.Sq \&.Bx ,
+.Sq \&.Fx ,
+.Sq \&.Nx ,
+.Sq \&.Ox ,
 and
-.Sq \&Ux )
+.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
+.Sq \&.Cd
 is callable.
 .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@kth.se .
+.An Kristaps Dzonsons Aq kristaps@openbsd.org .
+.\" 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.
+.\" 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.
+.El