===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.8
retrieving revision 1.19
diff -u -p -r1.8 -r1.19
--- mandoc/mdoc.7	2009/03/19 18:30:26	1.8
+++ mandoc/mdoc.7	2009/03/27 14:56:15	1.19
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.8 2009/03/19 18:30:26 kristaps Exp $
+.\" $Id: mdoc.7,v 1.19 2009/03/27 14:56:15 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -16,13 +16,13 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 19 2009 $
+.Dd $Mdocdate: March 27 2009 $
 .Dt mdoc 7
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
-.Nd mdoc macro reference
+.Nd mdoc language reference
 .\" SECTION
 .Sh DESCRIPTION
 The
@@ -30,24 +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 characters, the space character
+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:
@@ -84,7 +110,7 @@ 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
@@ -94,366 +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
-.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 \\(<<
-.Pq left guillemet
-.It \\(Fc
-.Pq right guillemet
-.It \\(Fo
-.Pq left guilsing
-.It \\(fc
-.Pq right guilsing
-.It \\(fo
-.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 \\(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
-.Pp
-Special symbols:
-.Bl -tag -width 12n -offset "XXXX" -compact
-.It \\(bu
-.Pq bullet
-.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 
 .\" 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 
@@ -535,8 +210,8 @@ subsequent tokens are interpreted as if the scope had 
 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, 
@@ -594,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
@@ -603,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 ,
@@ -653,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
@@ -706,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
@@ -771,11 +464,11 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -788,55 +481,53 @@ compatibility with these systems.
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
-.Sq \&Fo
+.Sq \&.Fo
 and
-.Sq \&St
+.Sq \&.St
 historically weren't always callable.  Both are now correctly callable.
 .\" LIST-ITEM
 .It
-.Sq \&It \-nested
+.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
@@ -850,59 +541,64 @@ There are several ambiguous parts of mdoc.
 .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.
 .\" 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.
 .El