[groff] 10/30: [ms]: Relocate and update accent string docs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1428485822812ccd4c764a8737404de579412b80
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 11 21:56:27 2022 -0500

    [ms]: Relocate and update accent string docs.
    
    * Move this material into a (sub)section titled "Legacy features".
    * Steer reader toward groff_char(7) for newly composed documents.
    * Document AT&T accent mark strings.
    * Distinguish AT&T and Berkeley accent mark string behavior.
    * Note the fact that Berkeley didn't redefine AT&T's \*C.
    * Update string descriptions to use glyph naming terms familiar from
      Unicode.
    
    * doc/groff.texi: Document Berkeley `/`, `oe`, and `OE` strings.
    
    Also drop workaround for limitation of older Texinfo versions.  We can
    register an index entry of ':' just fine now, it seems.
---
 doc/groff.texi      | 291 +++++++++++++++++++++++++++++-----------------------
 doc/ms.ms           | 125 +++++++++++++++++++---
 tmac/groff_ms.7.man | 131 +++++++++++++++++------
 3 files changed, 367 insertions(+), 180 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 3a9145c2..716b3ca1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2451,6 +2451,7 @@ and Tenth Edition Research Unix have been recreated.
 * ms Body Text::
 * ms Page Layout::
 * Differences from AT&T ms::
+* ms Legacy Features::
 * ms Naming Conventions::
 @end menu
 
@@ -4065,7 +4066,6 @@ arrangement extensively.
 * ms Margins::
 * ms Multiple Columns::
 * ms TOC::
-* ms Strings and Special Characters::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -4178,7 +4178,7 @@ gutter width; it is a GNU extension.
 
 @c ---------------------------------------------------------------------
 
-@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page 
Layout
+@node ms TOC, Differences from AT&T ms, ms Multiple Columns, ms Page Layout
 @subsubsection Creating a table of contents
 @cindex @file{ms} macros, creating table of contents
 @cindex table of contents, creating [@file{ms}]
@@ -4281,126 +4281,6 @@ the dots.  The width of the page number field is stored 
in the
 
 @c ---------------------------------------------------------------------
 
-@node ms Strings and Special Characters,  , ms TOC, ms Page Layout
-@subsubsection Strings and Special Characters
-@cindex @file{ms} macros, strings
-@cindex @file{ms} macros, special characters
-@cindex @file{ms} macros, accent marks
-@cindex accent marks [@file{ms}]
-@cindex special characters [@file{ms}]
-@cindex strings [@file{ms}]
-
-Improved accent marks are available in the @file{ms} macros.
-
-@Defmac {AM, , ms}
-Specify this macro at the beginning of your document to enable extended
-accent marks and special characters.  This is a Berkeley extension.
-
-To use the accent marks, place them @emph{after} the character being
-accented.
-
-Note that @code{groff}'s native support for accents is superior to the
-following definitions.
-@endDefmac
-
-The following accent marks are available after invoking the @code{AM}
-macro:
-
-@Defmpstr {@code{'}, ms}
-Acute accent.
-@endDefmpstr
-
-@Defmpstr {@code{`}, ms}
-Grave accent.
-@endDefmpstr
-
-@Defmpstr {^, ms}
-Circumflex.
-@endDefmpstr
-
-@Defmpstr {\,, ms}
-Cedilla.
-@endDefmpstr
-
-@Defmpstr {~, ms}
-Tilde.
-@endDefmpstr
-
-@deffn String @t{\*[:]}
-@ifnotinfo
-@stindex : @r{[}ms@r{]}
-@end ifnotinfo
-@ifinfo
-@stindex \*[@r{<colon>}] @r{[}ms@r{]}
-@end ifinfo
-Umlaut.
-@end deffn
-
-@Defmpstr {v, ms}
-Hacek.
-@endDefmpstr
-
-@Defmpstr {_, ms}
-Macron (overbar).
-@endDefmpstr
-
-@Defmpstr {., ms}
-Underdot.
-@endDefmpstr
-
-@Defmpstr {o, ms}
-Ring above.
-@endDefmpstr
-
-The following are standalone characters available after invoking the
-@code{AM} macro:
-
-@Defmpstr {?, ms}
-Upside-down question mark.
-@endDefmpstr
-
-@Defmpstr {!, ms}
-Upside-down exclamation point.
-@endDefmpstr
-
-@Defmpstr {8, ms}
-German � ligature.
-@endDefmpstr
-
-@Defmpstr {3, ms}
-Yogh.
-@endDefmpstr
-
-@Defmpstr {Th, ms}
-Uppercase thorn.
-@endDefmpstr
-
-@Defmpstr {th, ms}
-Lowercase thorn.
-@endDefmpstr
-
-@Defmpstr {D-, ms}
-Uppercase eth.
-@endDefmpstr
-
-@Defmpstr {d-, ms}
-Lowercase eth.
-@endDefmpstr
-
-@Defmpstr {q, ms}
-Hooked o.
-@endDefmpstr
-
-@Defmpstr {ae, ms}
-Lowercase � ligature.
-@endDefmpstr
-
-@Defmpstr {Ae, ms}
-Uppercase � ligature.
-@endDefmpstr
-
-@c ---------------------------------------------------------------------
-
 @node Differences from AT&T ms, ms Naming Conventions, ms Page Layout, ms
 @subsection Differences from @acronym{AT&T} @file{ms}
 @cindex @file{ms} macros, @code{groff} differences from @acronym{AT&T}
@@ -4550,11 +4430,6 @@ setting code examples; @code{groff} @file{ms} does not.
 The @code{groff} @file{ms} macros have a few minor extensions to the
 @acronym{AT&T} @file{ms} macros.
 
-@Defmac {AM, , ms}
-Use improved accent marks.  @xref{ms Strings and Special Characters},
-for details.  This is a Berkeley extension.
-@endDefmac
-
 @Defmac {CW, , ms}
 Set text in a @code{constant-width} (monospaced) typeface.  This is a
 Tenth Edition Research Unix extension.
@@ -4566,13 +4441,167 @@ script to capture and process an index generated in 
this manner.
 @endDefmac
 
 Several new strings are available as well.  You can change these to
-handle (for example) the local language.  @xref{ms Strings and Special
-Characters}.
+handle (for example) the local language.  @xref{ms Legacy Features}.
+
+@c ---------------------------------------------------------------------
+
+@node ms Legacy Features, ms Naming Conventions, Differences from AT&T ms, ms
+@subsection Legacy Features
+@cindex @file{ms} macros, strings
+@cindex @file{ms} macros, special characters
+@cindex @file{ms} macros, accent marks
+@cindex accent marks [@file{ms}]
+@cindex special characters [@file{ms}]
+@cindex strings [@file{ms}]
+
+@code{groff} @file{ms} retains support for some legacy features solely
+to support rendering of historical documents; contemporary ones should
+not use them because they can render poorly.  See the
+@cite{groff_char@r{(7)}} man page.
+
+@unnumberedsubsubsec AT&T accent mark strings
+
+AT&T @file{ms} defined accent mark strings as follows.
+
+@Defmpstr {@code{'}, ms}
+Apply acute accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {@code{`}, ms}
+Apply grave accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {:, ms}
+Apply dieresis (umlaut) to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {^, ms}
+Apply circumflex accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {~, ms}
+Apply tilde accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {C, ms}
+Apply caron to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {\,, ms}
+Apply cedilla to subsequent glyph.
+@endDefmpstr
+
+@unnumberedsubsubsec Berkeley accent mark and glyph strings
+
+Berkeley @file{ms} offered an @code{AM} macro; calling it redefined the
+AT&T accent mark strings (except for @samp{\*C}), applied them to the
+@emph{preceding} glyph, and defined additional strings, some for spacing
+glyphs.
+
+@Defmac {AM, , ms}
+Enable alternative accent mark and glyph-producing strings.
+@endDefmac
+
+@Defmpstr {@code{'}, ms}
+Apply acute accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {@code{`}, ms}
+Apply grave accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {:, ms}
+Apply dieresis (umlaut) to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {^, ms}
+Apply circumflex accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {~, ms}
+Apply tilde accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {\,, ms}
+Apply cedilla to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {/, ms}
+Apply stroke (slash) to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {v, ms}
+Apply caron to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {_, ms}
+Apply macron to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {., ms}
+Apply underdot to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {o, ms}
+Apply ring accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {?, ms}
+Interpolate inverted question mark.
+@endDefmpstr
+
+@Defmpstr {!, ms}
+Interpolate inverted exclamation mark.
+@endDefmpstr
+
+@Defmpstr {8, ms}
+Interpolate small letter sharp s.
+@endDefmpstr
+
+@Defmpstr {q, ms}
+Interpolate small letter o with hook accent (ogonek).
+@endDefmpstr
+
+@Defmpstr {3, ms}
+Interpolate small letter yogh.
+@endDefmpstr
+
+@Defmpstr {d-, ms}
+Interpolate small letter eth.
+@endDefmpstr
+
+@Defmpstr {D-, ms}
+Interpolate capital letter eth.
+@endDefmpstr
+
+@Defmpstr {th, ms}
+Interpolate small letter thorn.
+@endDefmpstr
+
+@Defmpstr {Th, ms}
+Interpolate capital letter thorn.
+@endDefmpstr
+
+@Defmpstr {ae, ms}
+Interpolate small � ligature.
+@endDefmpstr
+
+@Defmpstr {Ae, ms}
+Interpolate capital � ligature.
+@endDefmpstr
+
+@Defmpstr {oe, ms}
+Interpolate small oe ligature.
+@endDefmpstr
+
+@Defmpstr {OE, ms}
+Interpolate capital OE ligature.
+@endDefmpstr
 
 @c ---------------------------------------------------------------------
 
-@node ms Naming Conventions,  , Differences from AT&T ms, ms
-@subsection @file{ms} Naming Conventions
+@node ms Naming Conventions,  , ms Legacy Features, ms
+@subsection Naming Conventions
 @cindex @file{ms} macros, naming conventions
 @cindex naming conventions, @file{ms} macros
 
diff --git a/doc/ms.ms b/doc/ms.ms
index b74a463d..6a13e8ef 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -3572,31 +3572,126 @@ macros for setting code examples;
 does not.
 .
 .
-.NH 2
-.BI "groff ms"
-macros not appearing in
-AT&T
-.BI ms
+.\" ------------------------
+.if t .bp
+.NH 1
+Legacy features
 .XS
-       \c
+Legacy features
+.XE
+.
+.
+.LP
 .I "groff ms"
-macros not appearing in
+retains support for some legacy features solely to support rendering of
+historical documents;
+contemporary ones should not use them because they can render poorly.
+.
+See
+.I groff_char (7)
+instead.
+.
+.
+.NH 2
 AT&T
 .I ms
+accent mark strings
+.XS
+       AT&T
+.I ms
+accent mark strings
 .XE
+.LP
+AT&T
+.I ms
+defined
+accent mark strings as follows.
+.
+.
+.TS
+box center;
+Cb Lb
+Lf(CR) Lx.
+String Description
+_
+\[rs]*[\[aq]]  Apply acute accent to subsequent glyph.
+\[rs]*[\[ga]]  Apply grave accent to subsequent glyph.
+\[rs]*[:]      Apply dieresis (umlaut) to subsequent glyph.
+\[rs]*[\[ha]]  Apply circumflex accent to subsequent glyph.
+\[rs]*[\[ti]]  Apply tilde accent to subsequent glyph.
+\[rs]*[C]      Apply caron to subsequent glyph.
+.\" \*v was an undocumented (in Lesk 1978-11-13) synonym for \*C.
+\[rs]*[,]      Apply cedilla to subsequent glyph.
+.TE
 .
 .
+.NH 2
+Berkeley
+.I ms
+accent mark and glyph strings
+.XS
+       Berkeley
+.I ms
+accent mark and glyph strings
+.XE
 .LP
-The
-.I "groff ms"
-macros have some minor extensions,
-not already discussed above,
-compared to the AT&T
+Berkeley
 .I ms
-macros.
+offered an
+.CW AM
+macro;
+calling it redefined the AT&T accent mark strings
+(except for
+.CW \[rs]*C ),
+applied them to the
+.I preceding
+glyph,
+and defined additional strings,
+some for spacing glyphs.
+.
+.
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro  Description
+_
+\&.AM  Enable alternative accent mark and glyph-producing strings.
+.TE
 .
-.IP \&.AM 0.5i
-Improved accent marks.
+.
+.TS
+box center;
+Cb Lb
+Lf(CR) Lx.
+String Description
+_
+\[rs]*[\[aq]]  Apply acute accent to preceding glyph.
+\[rs]*[\[ga]]  Apply grave accent to preceding glyph.
+\[rs]*[:]      Apply dieresis (umlaut) to preceding glyph.
+\[rs]*[\[ha]]  Apply circumflex accent to preceding glyph.
+\[rs]*[\[ti]]  Apply tilde accent to preceding glyph.
+\[rs]*[,]      Apply cedilla to preceding glyph.
+\[rs]*[/]      Apply stroke (slash) to preceding glyph.
+\[rs]*[v]      Apply caron to preceding glyph.
+\[rs]*[_]      Apply macron to preceding glyph.
+\[rs]*[.]      Apply underdot to preceding glyph.
+\[rs]*[o]      Apply ring accent to preceding glyph.
+_
+\[rs]*[?]      Interpolate inverted question mark.
+\[rs]*[!]      Interpolate inverted exclamation mark.
+\[rs]*[8]      Interpolate small letter sharp s.
+\[rs]*[q]      Interpolate small letter o with hook accent (ogonek).
+\[rs]*[3]      Interpolate small letter yogh.
+\[rs]*[d-]     Interpolate small letter eth.
+\[rs]*[D-]     Interpolate capital letter eth.
+\[rs]*[th]     Interpolate small letter thorn.
+\[rs]*[TH]     Interpolate capital letter thorn.
+\[rs]*[ae]     Interpolate small ae ligature.
+\[rs]*[AE]     Interpolate capital ae ligature.
+\[rs]*[oe]     Interpolate small oe ligature.
+\[rs]*[OE]     Interpolate capital oe ligature.
+.TE
 .
 .
 .\" ------------------------
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index aa367f61..6cbb4df7 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -651,7 +651,7 @@ provides a handful of strings to obtain typographical 
symbols not easily
 entered with the keyboard.
 .
 Many others are available as special character escape sequences\[em]see
-.MR groff_char 7 .
+.MR groff_char @MAN7EXT@ .
 .
 .
 .TP
@@ -2524,39 +2524,102 @@ Documents that need to determine whether they are 
being formatted with
 or another implementation should test this register.
 .
 .
-.\" TODO: Put this in a legacy feature support section, alongside AT&T
-.\" accent marks and .AM.
-.\".PP
-.\"The
-.\".B \[rs]*\-
-.\"string produces an em dash\[em]like this.
-.\".
-.\".
-.\".PP
-.\"Use
-.\".B \[rs]*Q
-.\"and
-.\".B \[rs]*U
-.\"to get a left and right typographer's quote,
-.\"respectively, in
-.\".I troff
-.\"(and plain quotes in
-.\".IR nroff ).
-.
-.
-.\" TODO: Put this in a legacy feature support section, alongside AT&T
-.\" accent marks and the \*-, \*Q, \*U strings.
-.\".PP
-.\"Improved accent marks
-.\"(as originally defined in Berkeley's
-.\".I ms
-.\"version)
-.\"are available by specifying the
-.\".B AM
-.\"macro at the beginning of your document.
-.\".
-.\"You can place an accent over most characters by specifying the string
-.\"defining the accent directly after the character.
+.\" ====================================================================
+.SH "Legacy features"
+.\" ====================================================================
+.
+.I "groff ms"
+retains support for some legacy features solely to support rendering of
+historical documents;
+contemporary ones should not use them because they can render poorly.
+.
+See
+.MR groff_char @MAN7EXT@
+instead.
+.
+.
+.\" ====================================================================
+.SS "AT&T \f[I]ms\f[] accent mark strings"
+.\" ====================================================================
+.
+AT&T
+.I ms
+defined
+accent mark strings as follows.
+.
+.
+.TS
+Cb Lb
+Lf(CR) Lx.
+String Description
+_
+\[rs]*[\[aq]]  Apply acute accent to subsequent glyph.
+\[rs]*[\[ga]]  Apply grave accent to subsequent glyph.
+\[rs]*[:]      Apply dieresis (umlaut) to subsequent glyph.
+\[rs]*[\[ha]]  Apply circumflex accent to subsequent glyph.
+\[rs]*[\[ti]]  Apply tilde accent to subsequent glyph.
+\[rs]*[C]      Apply caron to subsequent glyph.
+.\" \*v was an undocumented (in Lesk 1978-11-13) synonym for \*C.
+\[rs]*[,]      Apply cedilla to subsequent glyph.
+.TE
+.
+.
+.\" ====================================================================
+.SS "Berkeley \f[I]ms\f[] accent mark and glyph strings"
+.\" ====================================================================
+.
+Berkeley
+.I ms
+offered an
+.B AM
+macro;
+calling it redefined the AT&T accent mark strings
+(except for
+.BR \[rs]*C ),
+applied them to the
+.I preceding
+glyph,
+and defined additional strings,
+some for spacing glyphs.
+.
+.
+.TP
+.B .AM
+Enable alternative accent mark and glyph-producing strings.
+.
+.
+.P
+.TS
+Cb Lb
+Lf(CR) Lx.
+String Description
+_
+\[rs]*[\[aq]]  Apply acute accent to preceding glyph.
+\[rs]*[\[ga]]  Apply grave accent to preceding glyph.
+\[rs]*[:]      Apply dieresis (umlaut) to preceding glyph.
+\[rs]*[\[ha]]  Apply circumflex accent to preceding glyph.
+\[rs]*[\[ti]]  Apply tilde accent to preceding glyph.
+\[rs]*[,]      Apply cedilla to preceding glyph.
+\[rs]*[/]      Apply stroke (slash) to preceding glyph.
+\[rs]*[v]      Apply caron to preceding glyph.
+\[rs]*[_]      Apply macron to preceding glyph.
+\[rs]*[.]      Apply underdot to preceding glyph.
+\[rs]*[o]      Apply ring accent to preceding glyph.
+_
+\[rs]*[?]      Interpolate inverted question mark.
+\[rs]*[!]      Interpolate inverted exclamation mark.
+\[rs]*[8]      Interpolate small letter sharp s.
+\[rs]*[q]      Interpolate small letter o with hook accent (ogonek).
+\[rs]*[3]      Interpolate small letter yogh.
+\[rs]*[d-]     Interpolate small letter eth.
+\[rs]*[D-]     Interpolate capital letter eth.
+\[rs]*[th]     Interpolate small letter thorn.
+\[rs]*[TH]     Interpolate capital letter thorn.
+\[rs]*[ae]     Interpolate small ae ligature.
+\[rs]*[AE]     Interpolate capital ae ligature.
+\[rs]*[oe]     Interpolate small oe ligature.
+\[rs]*[OE]     Interpolate capital oe ligature.
+.TE
 .
 .
 .\" ====================================================================