[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 15/35: doc/doc.am (doc/ms.ps): Depend on and use "eqn".
From: |
G. Branden Robinson |
Subject: |
[groff] 15/35: doc/doc.am (doc/ms.ps): Depend on and use "eqn". |
Date: |
Fri, 15 Jul 2022 23:11:58 -0400 (EDT) |
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 .[
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 15/35: doc/doc.am (doc/ms.ps): Depend on and use "eqn".,
G. Branden Robinson <=