[groff] 05/08: [ms]: Be more specific about supported macros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cdf80b3ee5d63e32a21b65c8f8608cd3674be15d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 4 02:24:06 2021 +1000

    [ms]: Be more specific about supported macros.
    
    In our documentation, clarify the groff ms "social contract" by noting
    that we support AT&T ms's _documented_ interface (and by that, we
    really mean the ms from Version 7 Unix, with extensions from 4.2BSD and
    some others cherry-picked from Version 10 Research Unix).
    
    Drop the incompatibility notice regarding cut marks; Lesk 1978 didn't
    mention this feature.  It apparently was designed specifically for the
    Graphic Systems C/A/T, which printed to a scroll of paper rather than
    individual leaves.  Few but historians will care about this today.
---
 doc/groff.texi      | 10 ++++++----
 doc/ms.ms           | 19 +++++++++++++++++++
 tmac/groff_ms.7.man | 19 ++++++++++++-------
 3 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index fd7e10a..d8f0e73 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4165,7 +4165,12 @@ This section lists the (minor) differences between the 
@code{groff}
 The internals of @code{groff} @file{ms} differ from the internals of
 @acronym{AT&T} @code{troff} @file{ms}.  Documents that depend upon
 implementation details of @acronym{AT&T} @code{troff} @file{ms} may not
-format properly with @code{groff} @file{ms}.
+format properly with @code{groff} @file{ms}.  Such details include
+macros whose function was not documented in the @acronym{AT&T}
+@code{troff} @file{ms} manual.@footnote{@cite{Typing Documents on the
+UNIX System: Using the -ms Macros with Troff and Nroff}, M.@: E.@: Lesk,
+Bell Laboratories, 1978.}
+@c XXX: We support RT anyway; maybe we should stop?
 
 @item
 The general error-handling policy of @code{groff} @file{ms} is to detect
@@ -4177,9 +4182,6 @@ and report errors, rather than silently to ignore them.
 it aborts processing with a diagnostic message.
 
 @item
-@code{groff} @file{ms} does not provide cut marks.
-
-@item
 Multiple line spacing is not supported.  Use a larger vertical spacing
 instead.
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 6d08d31..f11409f 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2448,6 +2448,25 @@ macros.
 .
 .
 .PP
+The internals of
+.I "groff ms"
+differ from the internals of AT&T
+.I "troff ms" .
+.
+Documents that depend upon implementation details of AT&T
+.I ms
+may not format properly with
+.I "groff ms" .
+.
+Such details include macros whose function was not documented in the
+AT&T
+.I "troff ms"
+manual [Lesk 1978].
+.\" TODO: Use refer(1).
+.\" XXX: We support RT anyway; maybe we should stop?
+.
+.
+.PP
 .I "groff ms"
 supports the
 .CW PN
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 7b690ee..a7ff892 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1533,17 +1533,26 @@ they cannot be used with AT&T
 .
 Other differences include:
 .
+.
 .IP \[bu] 3n
 The internals of
 .I groff ms
-differ from the internals of Unix
-.IR ms .
+differ from the internals of AT&T
+.IR "troff ms" .
 .
-Documents that depend upon implementation details of Unix
+Documents that depend upon implementation details of AT&T
 .I ms
 may not format properly with
 .IR "groff ms" .
 .
+Such details include macros whose function was not documented in the
+AT&T
+.I troff ms
+manual [Lesk 1978].
+.\" TODO: Use refer(1)?
+.\" XXX: We support RT anyway; maybe we should stop?
+.
+.
 .IP \[bu]
 The error-handling policy of
 .I groff ms
@@ -1583,10 +1592,6 @@ it aborts processing with a diagnostic message.
 .
 .
 .IP \[bu]
-.I groff ms
-does not provide cut marks.
-.
-.IP \[bu]
 Multiple line spacing is not supported
 (use a larger vertical spacing instead).
 .