===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -p -r1.27 -r1.28
--- mandoc/mdoc.7	2009/06/12 09:18:00	1.27
+++ mandoc/mdoc.7	2009/06/12 12:40:44	1.28
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.27 2009/06/12 09:18:00 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.28 2009/06/12 12:40:44 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -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
@@ -96,6 +101,8 @@ Within a macro line, the following characters are rese
 .Pq question
 .It \&!
 .Pq exclamation 
+.It \&|
+.Pq vertical bar 
 .El
 .\" PARAGRAPH
 .Pp
@@ -470,27 +477,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 \&.An ,
-.Sq \&.Fo ,
-.Sq \&.Lk ,
-.Sq \&.Ms ,
-.Sq \&.Mt ,
-and
-.Sq \&.St
-historically weren't 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
@@ -505,26 +519,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
@@ -538,7 +543,7 @@ utility was written by 
 .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