[groff] 10/10: [ms]: Improve documentation of pic(1) usage.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 9e6b349e9ecd9f1e06d86080ad9eb785f8cf86a5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jul 18 08:56:25 2023 -0500

    [ms]: Improve documentation of pic(1) usage.
    
    * tmac/groff_ms.7.man (Tables, figures, equations, and references):
      Document the mandatory arguments to `PS`.  Explain that pic(1) will
      supply them.  (This is documentation of the _package's_ interface.)
    
    * doc/groff.texi: As above, and add example of pic(1) input.  Also
      tighten wording.
    
    * doc/ms.ms: As above, and supply pic output corresponding to example
      (if typesetting).  Add a keep.
    
    * doc/doc.am (doc/ms.ps): Preprocess with pic; call groff with `-p`
      option when generating document.
    
    * src/utils/grog/tests/smoke-test.sh: Drop a test case; we no longer
      have an ms(7) document in the tree that uses tbl and eqn but not pic.
---
 ChangeLog                          | 22 ++++++++++++++++++
 doc/doc.am                         |  4 ++--
 doc/groff.texi                     | 27 +++++++++++++++++-----
 doc/ms.ms                          | 46 +++++++++++++++++++++++++++++++++++---
 src/utils/grog/tests/smoke-test.sh |  5 -----
 tmac/groff_ms.7.man                |  9 +++++++-
 6 files changed, 96 insertions(+), 17 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c5c163982..fc2b5bafc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+2023-07-18  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [ms]: Improve documentation of pic(1) usage.
+
+       * tmac/groff_ms.7.man
+       (Tables, figures, equations, and references): Document the
+       mandatory arguments to `PS`.  Explain that pic(1) will supply
+       them.  (This is documentation of the _package's_ interface.)
+
+       * doc/groff.texi: As above, and add example of pic(1) input.
+       Also tighten wording.
+
+       * doc/ms.ms: As above, and supply pic output corresponding to
+       example (if typesetting).  Add a keep.
+
+       * doc/doc.am (doc/ms.ps): Preprocess with pic; call groff with
+       `-p` option when generating document.
+
+       * src/utils/grog/tests/smoke-test.sh: Drop a test case; we no
+       longer have an ms(7) document in the tree that uses tbl and eqn
+       but not pic.
+
 2023-07-17  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [tbl]: Fix post-1.23.0 regression.
diff --git a/doc/doc.am b/doc/doc.am
index a127b5bf7..46e544d25 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -345,9 +345,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 $(TMAC_PACKAGE_MS) eqn tbl
+doc/ms.ps: $(doc_srcdir)/ms.ms $(TMAC_PACKAGE_MS) eqn pic tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
-       && $(DOC_GROFF) -et -Tps -ms $(doc_srcdir)/ms.ms >$@
+       && $(DOC_GROFF) -pet -Tps -ms $(doc_srcdir)/ms.ms >$@
 
 doc/pic.ps: $(doc_srcdir)/pic.ms $(TMAC_PACKAGE_MS) eqn pic tbl
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
diff --git a/doc/groff.texi b/doc/groff.texi
index b2a9ac154..66e4c6c2e 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4005,13 +4005,15 @@ comprehensive reference to the preprocessor and offers 
examples of its
 use.
 @endDefmac
 
-@DefmacList {PS, , ms}
+@DefmacList {PS, @var{h} @var{v}, ms}
 @DefmacItemx {PE, , ms}
 @DefmacListEndx {PF, , ms}
 @code{PS} begins a picture to be processed by the @command{gpic}
 preprocessor; either of @code{PE} or @code{PF} ends it, the latter with
-``flyback'' to the vertical position at its top.  You can create
-@code{pic} input manually or with a program such as @code{xfig}.
+``flyback'' to the vertical position at its top.  Create @code{pic}
+input manually or with a program such as @code{xfig}.  @var{h} and
+@var{v} are the horizontal and vertical dimensions of the picture;
+@command{gpic} supplies them automatically.
 @endDefmac
 
 @DefmacList {EQ, [@Var{align} [@Var{label}]], ms}
@@ -4074,9 +4076,22 @@ 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.
 
-Use @command{groff} options to run preprocessors on the input:@:
-@option{-e} for @command{geqn}, @option{-p} for @command{gpic},
-@option{-R} for @command{grefer}, and @option{-t} for @command{gtbl}.
+@need 200
+Create diagrams with @command{gpic}.
+
+@CartoucheExample
+.PS
+circle "input";
+arrow;
+box width 1.5i "\f[CR]groff -Rept -ms\f[]";
+arrow;
+circle "output";
+.PE
+@endCartoucheExample
+
+@command{groff} options run preprocessors on the input:@: @option{-e}
+for @command{geqn}, @option{-p} for @command{gpic}, @option{-R} for
+@command{grefer}, and @option{-t} for @command{gtbl}.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 9ad900f98..cc3a877fd 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2495,6 +2495,7 @@ T}
 _
 T{
 \&.PS
+.I "h v"
 .br
 \&.PE
 .br
@@ -2511,10 +2512,17 @@ or
 ends it,
 the latter with \[lq]flyback\[rq] to the vertical position at its top.
 .
-You can create
+Create
 .I pic
 input manually or with a program such as
 .I xfig (1).
+.
+.I h
+and
+.I v
+are the horizontal and vertical dimensions of the picture;
+.I pic
+supplies them automatically.
 T}
 _
 T{
@@ -2644,10 +2652,40 @@ giving us more flexibility to reorganize the document.
 p ~ = ~ q sqrt { 1 + ~ ( x / q sup 2 ) }
 .EN
 .
-Use
+.
+.PP
+Create diagrams with
+.I pic .
+.
+.
+.TS
+box center;
+Lf(CR).
+\&.PS
+circle "input";
+arrow;
+box width 1.5i "\[rs]f[CR]groff \-Rept \-ms\[rs]f[]";
+arrow;
+circle "output";
+\&.PE
+.TE
+.
+.
+.if t \{\
+.PS
+circle "input";
+arrow;
+box width 1.5i "\f[CR]groff \-Rept \-ms\f[]";
+arrow;
+circle "output";
+.PE
+.\}
+.
+.
+.PP
 .I groff
 options
-to run preprocessors on the input:
+run preprocessors on the input:
 .CW \-e
 for
 .I eqn ,
@@ -2814,6 +2852,7 @@ this macro has an empty definition.
 is a GNU extension.
 .
 .
+.KS
 .PP
 The following input was used to produce the first sentence in this
 section.
@@ -2834,6 +2873,7 @@ like this symbolic footnote
 \&.FE
 or arbitrary user-specified text.
 .TE
+.KE
 .
 .
 .PP
diff --git a/src/utils/grog/tests/smoke-test.sh 
b/src/utils/grog/tests/smoke-test.sh
index 2da1fc4bc..3c70688ff 100755
--- a/src/utils/grog/tests/smoke-test.sh
+++ b/src/utils/grog/tests/smoke-test.sh
@@ -124,11 +124,6 @@ echo "testing ms(7) document $doc" >&2
 "$grog" "$doc" | \
     grep -Fqx 'groff -ms '"$doc"
 
-doc=$src/doc/ms.ms
-echo "testing eqn(1)- and tbl(1)-using ms(7) document $doc" >&2
-"$grog" "$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" \
     >&2
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 5d154f836..0c7480ed5 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1521,7 +1521,7 @@ examples of its use.
 .
 .
 .TP
-.B .PS
+.BI .PS\~ "h v"
 .TQ
 .B .PE
 .TQ
@@ -1537,6 +1537,13 @@ or
 ends it,
 the latter with \[lq]flyback\[rq] to the vertical position at its top.
 .
+.I h
+and
+.I v
+are the horizontal and vertical dimensions of the picture;
+.I pic
+supplies them automatically.
+.
 .
 .TP
 .BR .EQ \~[\c