Added some clarifying bits to mdoc.7 regarding GNU troff, mandoc, and Heirloom troff...

diff --git a/mdoc.7 b/mdoc.7
index 829c00f61d9635c5916a1d6943440f65981fd6d5..4b4c4b503776d3e25382c8687b0986cd8c8e4a12 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.92 2010/04/07 18:50:35 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.93 2010/04/07 19:37:54 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -31,12 +31,9 @@ language is used to format
 .Bx
 .Ux
 manuals.  In this reference document, we describe its syntax, structure,
-and usage.  Our reference implementation is
-.Xr mandoc 1 .
-The
+and usage.  Our reference implementation is mandoc; the
 .Sx COMPATIBILITY
-section describes compatibility with
-.Xr groff 1 .
+section describes compatibility with other troff \-mdoc implementations.
 .
 .Pp
 An
@@ -1322,8 +1319,7 @@ and
 .Sx \&Ux .
 .
 .Ss \&Cd
-Configuration declaration (suggested for use in section four and nine
-manuals).  This denotes strings accepted by
+Configuration declaration.  This denotes strings accepted by
 .Xr config 8 .
 .Pp
 Examples:
@@ -1906,53 +1902,54 @@ Examples:
 .
 .
 .Sh COMPATIBILITY
-This section documents compatibility with other roff implementations, at
-this time limited to
-.Xr groff 1 .
+This section documents compatibility between mandoc and other other
+troff implementations, at this time limited to GNU troff
+.Pq Qq groff .
 The term
 .Qq historic groff
-refers to those versions before the
+refers to groff versions before the
 .Pa doc.tmac
 file re-write
 .Pq somewhere between 1.15 and 1.19 .
 .
 .Pp
+Heirloom troff, the other significant troff implementation accepting
+\-mdoc, is similar to historic groff.
+.
+.Pp
 .Bl -dash -compact
 .It
 The comment syntax
 .Sq \e."
 is no longer accepted.
+.
 .It
-In
-.Xr groff 1 ,
-the
+In groff, the
 .Sx \&Pa
 macro does not format its arguments when used in the FILES section under
-certain list types.  This irregular behaviour has been discontinued.
+certain list types.  mandoc does.
+.
 .It
-Historic
-.Xr groff 1
-does not print a dash for empty
+Historic groff does not print a dash for empty
 .Sx \&Fl
-arguments.  This behaviour has been discontinued.
+arguments.  mandoc and newer groff implementations do.
 .It
-.Xr groff 1
-behaves strangely (even between versions) when specifying
+groff behaves irregularly when specifying
 .Sq \ef
-escapes within line-macro scopes.  These aberrations have been
-normalised.
+.Sx Text Decoration
+within line-macro scopes.  mandoc follows a consistent system.
+.
 .It
-Negative scaling units are now truncated to zero instead of creating
-interesting conditions, such as with
-.Sx \&sp
-.Fl 1i .
-Furthermore, the
+In mandoc, negative scaling units are truncated to zero; groff would
+move to prior lines.  Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
+.
 .It
 In quoted literals, groff allowed pair-wise double-quotes to produce a
 standalone double-quote in formatted output.  This idiosyncratic
-behaviour is no longer applicable.
+behaviour is not applicable in mandoc.
+.
 .It
 Display types
 .Sx \&Bd
@@ -1960,10 +1957,11 @@ Display types
 and
 .Fl right
 are aliases for
-.Fl left .
-The
+.Fl left
+in manodc.  Furthermore, the
 .Fl file Ar file
-argument is ignored.  Since text is not right-justified,
+argument is ignored.  Lastly, since text is not right-justified in
+mandoc (or even groff),
 .Fl ragged
 and
 .Fl filled
@@ -1971,36 +1969,50 @@ are aliases, as are
 .Fl literal
 and
 .Fl unfilled .
+.
 .It
-Blocks of whitespace are stripped from both macro and free-form text
-lines (except when in literal mode), while groff would retain whitespace
-in free-form text lines.
+In mandoc, blocks of whitespace are stripped from both macro and
+free-form text lines (except when in literal mode); groff would retain
+whitespace in free-form text lines.
+.
 .It
 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.
+some block-level macros) are now callable.
+.
 .It
 The vertical bar
 .Sq \(ba
 made historic groff
 .Qq go orbital
-but is a proper delimiter in this implementation.
+but has been a proper delimiter since then.
+.
 .It
-.Sx \&It
-.Fl nested
+.Sx \&It Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
 .Fl enum
 lists will restart the sequence only for the sub-list.
+.
 .It
 Some manuals use
 .Sx \&Li
 incorrectly by following it with a reserved character and expecting the
-delimiter to render.  This is not supported.
+delimiter to render.  This is not supported in mandoc.
+.
 .It
 In groff, the
 .Sx \&Fo
-macro only produces the first parameter.  This is no longer the case.
+macro only produces the first parameter.  This is not the case in
+mandoc.
+.
+.It
+In groff, the
+.Sx \&Cd ,
+.Sx \&Er ,
+and
+.Sx \&Ex
+macros were stipulated only to occur in certain manual sections.  mandoc
+does not have these restrictions.
 .El
 .
 .