[groff] 05/19: [ms]: Replace incomplete doc of missing V7 macros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 83ba0ebe71ae48281ba0baa36e20453ffdfae1e5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jul 6 02:40:27 2022 -0500

    [ms]: Replace incomplete doc of missing V7 macros.
    
    [ms]: Replace incomplete documentation of unimplemented macros.
    
    * doc/groff.texi (Missing ms Macros):
    * doc/ms.ms (AT&T ms macros not appearing in groff ms): Drop, replacing
      with...
    
    * doc/groff.texi (Unix Version 7 ms Macros Not Implemented by groff ms):
    * doc/ms.ms (Unix Version 7 ms macros not implemented by groff ms):
    * tmac/groff_ms.7.man (Unix Version 7 macros not implemented by groff
      ms): ...these.
    
    We talk specifically about V7 Unix ms since our ms documentation
    explicitly proclaims that release as a baseline.  V10 ms is
    substantially different; for instance, macros for the title, author(s),
    and the abstract all changed name and sometimes behavior.
---
 ChangeLog           | 15 +++++++++
 doc/groff.texi      | 76 ++++++++++++++++++++++----------------------
 doc/ms.ms           | 90 ++++++++++++++++++++++++++++++++---------------------
 tmac/groff_ms.7.man | 42 +++++++++++++++++++++++++
 4 files changed, 150 insertions(+), 73 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d0c8153d..75087c0a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2022-07-06  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [ms]: Replace incomplete documentation of unimplemented macros.
+
+       * doc/groff.texi (Missing ms Macros):
+       * doc/ms.ms (AT&T ms macros not appearing in groff ms): Drop,
+       replacing with...
+
+       * doc/groff.texi (Unix Version 7 ms Macros Not Implemented by
+       groff ms):
+       * doc/ms.ms (Unix Version 7 ms macros not implemented by groff
+       ms):
+       * tmac/groff_ms.7.man (Unix Version 7 macros not implemented by
+       groff ms): ...these.
+
 2022-07-06  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/input.cpp (do_translate): Throw an error
diff --git a/doc/groff.texi b/doc/groff.texi
index 7803ecee..4fcf0e56 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4496,49 +4496,49 @@ register.
 @endDefmpreg
 
 @menu
-* Missing ms Macros::
+* Unix Version 7 ms Macros Not Implemented by groff ms::
 @end menu
 
 @c ---------------------------------------------------------------------
 
-@node Missing ms Macros, , Differences from AT&T ms, Differences from AT&T ms
-@subsubsection @acronym{AT&T} @file{ms} macros not appearing in @code{groff} 
@file{ms}
+@node Unix Version 7 ms Macros Not Implemented by groff ms, , Differences from 
AT&T ms, Differences from AT&T ms
+@subsubsection Unix Version 7 @file{ms} macros not implemented by @code{groff} 
@file{ms}
+
+Several macros described in the Unix Version@tie{}7 @file{ms}
+documentation are unimplemented by @code{groff} @file{ms} because they
+are specific to the requirements of documents produced internally by
+Bell Laboratories, some of which also require a glyph for the Bell
+System logo that @code{groff} does not support.  These include macros
+implementing several document type formats
+(@code{EG}, @c engineer's notes
+@code{IM}, @c internal memorandum
+@code{MF}, @c memorandum for file
+@code{MR}, @c memorandum for record
+@code{TM}, @c technical memorandum
+@code{TR}), @c technical report
+were meaningful only in conjuction with the use of certain document
+types
+(@code{AT}, @c attachments
+@code{CS}, @c cover sheet info for `TM` documents
+@code{CT}, @c copies to
+@code{OK}, @c "other keywords" for `TM` documents
+@code{SG}), @c signatures for `TM` documents
+stored the postal addresses of Bell Labs sites
+(@code{HO}, @c Holmdel
+@code{IH}, @c Naperville
+@code{MH}, @c Murray Hill
+@code{PY}, @c Piscataway
+@code{WH}), @c Whippany
+or lack a stable definition historically
+(@code{UX}). @c Unix; on 1st use, add footnote id'ing trademark owner
+To compatibly render historical @file{ms} documents using these macros,
+we advise you to define replacements with an authentically typeset
+original at hand.  For informal purposes, a simple definition of
+@code{UX} should maintain the readability of the document's substance.
 
-Macros missing from @code{groff} @file{ms} are specific to Bell Labs and
-Berkeley.  The macros known to be missing are:
-
-@table @code
-@item .TM
-Technical memorandum; a cover sheet style
-
-@item .IM
-Internal memorandum; a cover sheet style
-
-@item .MR
-Memo for record; a cover sheet style
-
-@item .MF
-Memo for file; a cover sheet style
-
-@item .EG
-Engineer's notes; a cover sheet style
-
-@item .TR
-Computing Science Technical Report; a cover sheet style
-
-@item .OK
-Other keywords
-
-@item .CS
-Cover sheet information
-
-@item .MH
-Murray Hill Bell Laboratories postal address
-@end table
-
-Tenth Edition @c possibly 9th
-Research Unix supported a pair of @code{P1} and @code{P2} macros for
-setting code examples; @code{groff} @file{ms} does not.
+@CartoucheExample
+.ds UX Unix\"
+@endCartoucheExample
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index d5ebed1d..100b3cdb 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -3746,51 +3746,71 @@ or another implementation should test this register.
 .
 .
 .NH 2
-AT&T
+Unix Version\~7
 .BI ms
-macros not appearing in
+macros not implemented by
 .BI "groff ms"
 .XS
-       AT&T
+       Unix Version 7
 .I ms
-macros not appearing in
+macros not implemented by
 .I "groff ms"
 .XE
 .LP
-Macros missing from
+Several macros described in the Unix Version\~7
+.I ms
+documentation are unimplemented by
 .I "groff ms"
-are cover page macros specific to
-Bell Labs.
-The macros known to be missing are:
-.IP \&.TM 0.5i
-Technical memorandum; a cover sheet style
-.IP \&.IM
-Internal memorandum; a cover sheet style
-.IP \&.MR
-Memo for record; a cover sheet style
-.IP \&.MF
-Memo for file; a cover sheet style
-.IP \&.EG
-Engineer's notes; a cover sheet style
-.IP \&.TR
-Computing Science Tech Report; a cover sheet style
-.IP \&.OK
-Other keywords
-.IP \&.CS
-Cover sheet information
-.IP \&.MH
-A cover sheet macro
+because they are specific to the requirements of documents produced
+internally by Bell Laboratories,
+some of which also require a glyph for the Bell System logo that
+.I groff
+does not support.
 .
+These include macros implementing several document type formats
+(\c
+.CW EG , \" engineer's notes
+.CW IM , \" internal memorandum
+.CW MF , \" memorandum for file
+.CW MR , \" memorandum for record
+.CW TM , \" technical memorandum
+.CW TR ), \" technical report
+were meaningful only in conjuction with the use of certain document
+types
+(\c
+.CW AT , \" attachments
+.CW CS , \" cover sheet info for `TM` documents
+.CW CT , \" copies to
+.CW OK , \" "other keywords" for `TM` documents
+.CW SG ), \" signatures for `TM` documents
+stored the postal addresses of Bell Labs sites
+(\c
+.CW HO , \" Holmdel
+.CW IH , \" Naperville
+.CW MH , \" Murray Hill
+.CW PY , \" Piscataway
+.CW WH ), \" Whippany
+or lack a stable definition historically
+(\c
+.CW UX ). \" Unix; on 1st use, add footnote identifying trademark owner
 .
-.LP
-Tenth Edition \" possibly 9th
-Research Unix supported a pair of
-.CW P1
-and
-.CW P2
-macros for setting code examples;
-.I "groff ms"
-does not.
+To compatibly render historical
+.I ms
+documents using these macros,
+we advise you to define replacements with an authentically typeset
+original at hand.
+.
+For informal purposes,
+a simple definition of
+.CW UX
+should maintain the readability of the document's substance.
+.
+.
+.TS
+box center;
+lf(CR).
+\&.ds UX Unix\[rs]"
+.TE
 .
 .
 .\" ------------------------
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index ca087623..f7ed1270 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -2540,6 +2540,48 @@ or another implementation should test this register.
 .
 .
 .\" ====================================================================
+.SS "Unix Version\~7 macros not implemented by \f[I]groff ms\f[]"
+.\" ====================================================================
+.
+Several macros described in the Unix Version\~7
+.I ms
+documentation are unimplemented by
+.I groff ms
+because they are specific to the requirements of documents produced
+internally by Bell Laboratories,
+some of which also require a glyph for the Bell System logo that
+.I groff
+does not support.
+.
+These include macros implementing several document type formats
+(\c
+.BR EG , \" engineer's notes
+.BR IM , \" internal memorandum
+.BR MF , \" memorandum for file
+.BR MR , \" memorandum for record
+.BR TM , \" technical memorandum
+.BR TR ), \" technical report
+were meaningful only in conjuction with the use of certain document
+types
+(\c
+.BR AT , \" attachments
+.BR CS , \" cover sheet info for `TM` documents
+.BR CT , \" copies to
+.BR OK , \" "other keywords" for `TM` documents
+.BR SG ), \" signatures for `TM` documents
+stored the postal addresses of Bell Labs sites
+(\c
+.BR HO , \" Holmdel
+.BR IH , \" Naperville
+.BR MH , \" Murray Hill
+.BR PY , \" Piscataway
+.BR WH ), \" Whippany
+or lack a stable definition historically
+(\c
+.BR UX ). \" Unix; on 1st use, add footnote identifying trademark owner
+.
+.
+.\" ====================================================================
 .SH "Legacy features"
 .\" ====================================================================
 .