[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 10/10: [ms]: Improve documentation of pic(1) usage.
From: |
G. Branden Robinson |
Subject: |
[groff] 10/10: [ms]: Improve documentation of pic(1) usage. |
Date: |
Tue, 18 Jul 2023 10:49:51 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 10/10: [ms]: Improve documentation of pic(1) usage.,
G. Branden Robinson <=