[groff] 15/35: doc/doc.am (doc/ms.ps): Depend on and use "eqn".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6ed7d0d66facc19f8630cf1816993e9546987242
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 10 00:44:20 2022 -0500

    doc/doc.am (doc/ms.ps): Depend on and use "eqn".
    
    Correct and expand documentation of eqn(1) usage with ms macro package.
    
    * doc/groff.texi (ms Insertions):
    * doc/ms.ms (Tables, figures, equations, and references):
    * tmac/groff_ms.man (Tables, figures, equations, and references):
      Document optional second argument to `EQ` macro.
    
    * doc/groff.texi (ms Headings):
    * doc/ms.ms (Headings):
    * tmac/groff_ms.man (Headings): Document additional applications of `SN`
      string.
    
    * doc/groff.texi (Example multi-page table):
    * doc/ms.ms (An example multi-page table): Drop node/section title.
    
    * doc/groff.texi (ms Insertions):
    * doc/ms.ms (Tables, figures, equations, and references): Add example of
      eqn usage.
    
    * src/utils/grog/tests/smoke-test.sh: Update expected "grog" output for
      the ms.ms document.
---
 ChangeLog                          |  7 ++++
 doc/doc.am                         |  4 +-
 doc/groff.texi                     | 55 +++++++++++++++----------
 doc/ms.ms                          | 82 ++++++++++++++++++++++++++++++--------
 src/utils/grog/tests/smoke-test.sh |  4 +-
 tmac/groff_ms.7.man                | 22 ++++++----
 6 files changed, 125 insertions(+), 49 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 652f6bbe..68a86172 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-07-10  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/doc.am (doc/ms.ps): Add dependency on "eqn", and call
+       groff with "-e" option.
+       * src/utils/grog/tests/smoke-test.sh: Update expected "grog"
+       output for the ms.ms document.
+
 2022-07-09  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/doc.am (doc/ms.ps): Add dependency on "tbl".
diff --git a/doc/doc.am b/doc/doc.am
index c5bb7f5c..806058d9 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -332,9 +332,9 @@ doc/meintro_fr.ps: doc/meintro_fr.me preconv
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
        && $(DOC_GROFF) -K utf8 -t -Tps -me -mfr $< >$@
 
-doc/ms.ps: $(doc_srcdir)/ms.ms tbl
+doc/ms.ps: $(doc_srcdir)/ms.ms eqn tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
-       && $(DOC_GROFF) -t -Tps -ms $(doc_srcdir)/ms.ms >$@
+       && $(DOC_GROFF) -et -Tps -ms $(doc_srcdir)/ms.ms >$@
 
 doc/pic.ps: $(doc_srcdir)/pic.ms eqn pic tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
diff --git a/doc/groff.texi b/doc/groff.texi
index 2a6e01e1..aa23ffe5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3181,7 +3181,6 @@ footnotes, and inclusions of material such as tables and 
figures.
 * Indented regions in ms::
 * ms keeps and displays::
 * ms Insertions::
-* Example multi-page table::
 * ms Footnotes::
 * ms language and localization::
 @end menu
@@ -3402,9 +3401,9 @@ define the alias as follows.
 Any such change in numbering style becomes effective from the next use
 of @code{NH} following redefinition of the alias for @code{SN-STYLE}.
 The formatted number of the current heading is available in the
-@code{SN} string (a feature first documented by Berkeley), facilitating
-its inclusion in @code{XS}/@code{XA}/@code{XE} table of contents
-entries.
+@code{SN} string (a feature first documented by Berkeley); this feature
+facilitates its inclusion in, for example, table captions, equation
+labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
 @endDefmpstr
 
 @Defmac {SH, [@Var{depth}], ms}
@@ -3911,7 +3910,7 @@ effect at the next display boundary.
 
 @c ---------------------------------------------------------------------
 
-@node ms Insertions, Example multi-page table, ms keeps and displays, ms Body 
Text
+@node ms Insertions, ms Footnotes, ms keeps and displays, ms Body Text
 @subsubsection Tables, figures, equations, and references
 @cindex @file{ms} macros, tables
 @cindex @file{ms} macros, figures
@@ -3950,13 +3949,13 @@ can create @code{pic} input manually or by using a 
program such as
 @code{xfig}.
 @endDefmac
 
-@DefmacList {EQ, [@Var{align}], ms}
+@DefmacList {EQ, [@Var{align} [@Var{label}], ms}
 @DefmacListEndx {EN, , ms}
 Demarcate an equation to be processed by the @code{eqn} preprocessor.
-The equation is center-aligned by default; the optional @var{align}
-argument can be @samp{C}, @samp{L}, or @samp{I} to center, left-align,
-or indent it by the amount stored in the @code{DI} register,
-respectively.
+The equation is centered by default; @var{align} can be @samp{C},
+@samp{L}, or @samp{I} to (explicitly) center, left-align, or indent it
+by the amount stored in the @code{DI} register, respectively.  If
+specified, @var{label} is set right-aligned.
 @endDefmac
 
 @DefmacList {[, , ms}
@@ -3972,17 +3971,8 @@ When @code{refer} emits collected references (as might 
be done on a
 ``Works Cited'' page), it interpolates the @code{REFERENCES} string as
 an unnumbered heading (@code{SH}).
 
-@menu
-* Example multi-page table::
-@end menu
-
-@c ---------------------------------------------------------------------
-
-@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
-@subsubsection An example multi-page table
-@cindex example markup, multi-page table [@file{ms}]
-@cindex multi-page table, example markup [@file{ms}]
-
+@cindex table, multi-page, example [@file{ms}]
+@cindex multi-page table example [@file{ms}]
 The following is an example of how to set up a table that may print
 across two or more pages.
 
@@ -3999,13 +3989,34 @@ GH-1978@arrow{}Fribulating gonkulator
 .TE
 @endCartoucheExample
 
+@noindent
 Attempting to place a multi-page table inside a keep can lead to
 unpleasant results, particularly if the @code{tbl} @code{allbox} option
 is used.
 
+@cindex equation example [@file{ms}]
+Mathematics can be typeset using the language of the @code{eqn}
+preprocessor.
+
+@CartoucheExample
+.EQ C (\*[SN-NO-DOT]a)
+p ~ = ~ q sqrt @{ ( 1 + ~ ( x / q sup 2 ) @}
+.EN
+@endCartoucheExample
+
+@noindent
+This input formats a labelled equation.  We used the @code{SN-NO-DOT}
+string to base the equation label on the current heading number, giving
+us more flexibility to reorganize the document.
+
+Remember to run any desired preprocessors on the input; @command{groff}
+options will take care of this.  Use @option{-e} for @command{geqn},
+@option{-p} for @command{gpic}, @option{-R} for @command{grefer}, and
+@option{-t} for @command{gtbl}.
+
 @c ---------------------------------------------------------------------
 
-@node ms Footnotes,  , Example multi-page table, ms Body Text
+@node ms Footnotes, , ms Insertions, ms Body Text
 @subsubsection Footnotes
 @cindex @file{ms} macros, footnotes
 @cindex footnotes [@file{ms}]
diff --git a/doc/ms.ms b/doc/ms.ms
index 63a5929e..0f5eb525 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1279,8 +1279,12 @@ following redefinition of the alias for
 .
 The formatted number of the current heading is available in
 .CW \[rs]*[SN]
-(a feature first documented by Berkeley),
-facilitating its inclusion in
+(a feature first documented by Berkeley);
+this feature facilitates its inclusion in,
+for example,
+table captions,
+equation labels,
+and
 .CW .XS /\c
 .CW .XA /\c
 .CW .XE
@@ -2382,7 +2386,8 @@ _
 T{
 \&.EQ
 .R
-.I align ] [
+.I align \~[\c [
+.I label ]]
 .CW
 .br
 \&.EN
@@ -2391,19 +2396,22 @@ Demarcate an equation to be processed by the
 .I eqn
 preprocessor.
 .
-The equation is center-aligned by default;
-the optional
+The equation is centered by default;
 .I align
-argument can be
+can be
 .CW C ,
 .CW L ,
 or
 .CW I
-to center,
+to (explicitly) center,
 left-align,
 or indent it by
 .CW \[rs]n[DI] ,
 respectively.
+.
+If specified,
+.I label
+is set right-aligned.
 T}
 _
 T{
@@ -2436,14 +2444,7 @@ as an unnumbered heading
 .
 .
 .KS
-.NH 3
-An example multi-page table
-.XS
-               An example multi-page table
-.XE
-.
-.
-.LP
+.PP
 The following is an example of how to set up a table that may print
 across two or more pages.
 .
@@ -2473,7 +2474,6 @@ T}
 .TE
 .
 .
-.PP
 Attempting to place a multi-page table inside a keep can lead to
 unpleasant results,
 particularly if the
@@ -2483,6 +2483,56 @@ option is used.
 .KE
 .
 .
+.PP
+Mathematics can be typeset using the language of the
+.I eqn
+preprocessor.
+.
+.
+.TS
+box center;
+Lf(CR).
+\&.EQ C (\[rs]*[SN\-NO\-DOT]a)
+p \[ti] = \[ti] q sqrt { ( 1 + \[ti] ( x / q sup 2 ) }
+\&.EN
+.TE
+.
+.
+This input formats a labelled equation.
+.
+We used the
+.CW SN\-NO\-DOT
+string to base the equation label on the current heading number,
+giving us more flexibility to reorganize the document.
+.
+.
+.EQ C (\*[SN-NO-DOT]a)
+p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) }
+.EN
+.
+.
+.PP
+Remember to run any desired preprocessors on the input;
+.I groff
+options
+will take care of this.
+.
+Use
+.CW \-e
+for
+.I eqn ,
+.CW \-p
+for
+.I pic ,
+.CW \-R
+for
+.I refer ,
+and
+.CW \-t
+for
+.I tbl.
+.
+.
 .KS
 .NH 2
 Footnotes
diff --git a/src/utils/grog/tests/smoke-test.sh 
b/src/utils/grog/tests/smoke-test.sh
index c1128263..2da1fc4b 100755
--- a/src/utils/grog/tests/smoke-test.sh
+++ b/src/utils/grog/tests/smoke-test.sh
@@ -125,9 +125,9 @@ echo "testing ms(7) document $doc" >&2
     grep -Fqx 'groff -ms '"$doc"
 
 doc=$src/doc/ms.ms
-echo "testing tbl(1)-using ms(7) document $doc" >&2
+echo "testing eqn(1)- and tbl(1)-using ms(7) document $doc" >&2
 "$grog" "$doc" | \
-    grep -Fqx 'groff -t -ms '"$doc"
+    grep -Fqx 'groff -e -t -ms '"$doc"
 
 doc=$src/doc/pic.ms
 echo "testing tbl(1)-, eqn(1)-, and pic(1)-using ms(7) document $doc" \
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index e04bdd31..9963450f 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -894,8 +894,12 @@ following redefinition of the alias for
 .
 The formatted number of the current heading is available in
 .B \[rs]*[SN]
-(a feature first documented by Berkeley),
-facilitating its inclusion in
+(a feature first documented by Berkeley);
+this feature facilitates its inclusion in,
+for example,
+table captions,
+equation labels,
+and
 .BR .XS / .XA / .XE
 table of contents entries.
 .
@@ -1484,26 +1488,30 @@ preprocessor.
 .
 .TP
 .BR .EQ \~[\c
-.IR align ]
+.IR align \~[\c]
+.IR label ]]
 .TQ
 .B .EN
 Demarcate an equation to be processed by the
 .I eqn
 preprocessor.
 .
-The equation is center-aligned by default;
-the optional
+The equation is centered by default;
 .I align
-argument can be
+can be
 .BR C ,
 .BR L ,
 .RB or\~ I
-to center,
+to (explicitly) center,
 left-align,
 or indent it by
 .BR \[rs]n[DI] ,
 respectively.
 .
+If specified,
+.I label
+is set right-aligned.
+.
 .
 .TP
 .B .[