===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.22
retrieving revision 1.29
diff -u -p -r1.22 -r1.29
--- mandoc/mdoc.7	2009/04/12 19:45:26	1.22
+++ mandoc/mdoc.7	2009/06/16 19:13:28	1.29
@@ -1,6 +1,6 @@
-.\"	$Id: mdoc.7,v 1.22 2009/04/12 19:45:26 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.29 2009/06/16 19:13:28 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" 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
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: April 12 2009 $
+.Dd $Mdocdate: June 16 2009 $
 .Dt MDOC 7
 .Os
 .\" SECTION
@@ -31,7 +31,12 @@ language is used to format 
 manuals.  In this reference document, we describe the syntax, ontology
 and structure of the 
 .Nm
-language.
+language.  Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with 
+.Xr groff 1 .
 .\" PARAGRAPH
 .Pp
 An
@@ -73,9 +78,19 @@ 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:
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset XXXX -compact
 .It \&.
 .Pq period
 .It \&,
@@ -96,6 +111,8 @@ Within a macro line, the following characters are rese
 .Pq question
 .It \&!
 .Pq exclamation 
+.It \&|
+.Pq vertical bar 
 .El
 .\" PARAGRAPH
 .Pp
@@ -393,7 +410,7 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -405,7 +422,7 @@ then the macro accepts an arbitrary number of argument
 .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 \&.Li    Ta    Yes   Ta    Yes     Ta    n
@@ -436,7 +453,7 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -455,8 +472,8 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -470,23 +487,34 @@ and
 macros are obsolete.
 .\" 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.
+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
-.Sq \&.Fo
-and
-.Sq \&.St
-historically weren't always callable.  Both are now correctly callable.
+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: any list may be nested and
+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
@@ -501,26 +529,17 @@ The 
 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.
+If an special-character control character 
+.Sq \e 
+is escaped, it will
+obviously not render the sequence.  Even newer versions of groff seem to
+dither on this.
 .El
 .\" SECTION
 .Sh SEE ALSO
@@ -531,10 +550,10 @@ is callable.
 The
 .Nm
 utility was written by 
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
+.An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
-There are several ambiguous parts of mdoc.
+There are many ambiguous parts of mdoc.
 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM