gbranden pushed a commit to branch master
in repository groff.
commit 353937df801445d0bc01b847cbca7b0c4bce8910
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Mon Jul 14 16:35:10 2025 -0500
[ms]: Tighten wording in documentation.
---
doc/groff.texi.in | 105 +++++++++++++++++++++++++++++++++++-----------------
doc/ms.ms | 41 ++++++++++----------
tmac/groff_ms.7.man | 37 +++++++++---------
3 files changed, 113 insertions(+), 70 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 39bfcff6f..093ad655d 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -2861,18 +2861,25 @@ and so forth) and augmented by lists, footnotes,
tables, diagrams, and
similar material. @xref{ms Body Text}.
@item Tables of contents
-Macros enable the collection of entries for a table of contents (or
-index) as the material they discuss appears in the document. You then
-call a macro to emit the table of contents at the end of your document.
-The table of contents must necessarily follow the rest of the text since
-GNU @code{troff} is a single-pass formatter; it thus cannot determine
-the page number of a division of the text until it has been set and
-output. Since @file{ms} was designed for the production of hard copy,
+Macros enable the collection of entries for a table of contents
+(or index)
+as the material they discuss appears in the document.
+A macro call at the end of the document emits the collected entries.
+This material necessarily follows the rest of the text since
+@command{troff} @c GNU
+is a single-pass formatter;
+it cannot determine the page number of a division of the text
+until it has been set and output.
+Since
+@file{ms}
+output was designed for the production of hard copy,
the traditional procedure was to manually relocate the pages containing
-the table of contents between the cover page and the body text. Today,
-page resequencing is more often done in the digital domain. An index
-works similarly, but because it typically needs to be sorted after
-collection, its preparation requires separate processing.
+the table of contents between the cover page and the body text.
+Today,
+page resequencing is more often done in the digital domain.
+An index works similarly,
+but because it typically needs to be sorted after collection,
+its preparation requires separate processing.
@end table
@c ---------------------------------------------------------------------
@@ -3078,10 +3085,12 @@ Default: 5@dmn{n}.
@Defmpreg {PORPHANS, ms}
Defines the minimum number of initial lines of any paragraph that must
be kept together to avoid isolated lines at the bottom of a page. If a
-new paragraph is started close to the bottom of a page, and there is
-insufficient space to accommodate @code{PORPHANS} lines before an
-automatic page break, then a page break is forced before the start of
-the paragraph. This is a GNU extension.
+new paragraph is started close to the bottom of a page,
+and there is insufficient space to accommodate
+@code{PORPHANS}
+@code{groff} @file{ms}
+forces a page break before formatting the paragraph.
+This is a GNU extension.
Effective: next paragraph.
@@ -3292,9 +3301,14 @@ page. If the optional @code{no-repeat-info} argument is
given,
information subsequently (but see the @code{DA} macro below regarding
the date). Normally, @code{RP} sets the page number following the cover
page to@tie{}1. Specifying the optional @code{no-renumber} argument
-suppresses this alteration. Optional arguments can occur in any order.
-@code{no} is recognized as a synonym of @code{no-repeat-info} for
-@acronym{AT&T} compatibility.
+suppresses this alteration.
+Optional arguments can occur in any order.
+@file{ms}
+recognizes
+@code{no}
+as a synonym of
+@code{no-repeat-info}
+to maintain @acronym{AT&T} compatibility.
@endDefmac
@Defmac {TL, , ms}
@@ -3672,16 +3686,30 @@ all more deeply nested heading levels remains in the
10-point type
specified by the @code{PS} register. ``Machairodontinae'' is printed at
11.5 points, since it corresponds to heading level@tie{}2.
-The @code{HORPHANS} register operates in conjunction with the @code{NH}
-and @code{SH} macros to inhibit the printing of isolated headings at the
-bottom of a page; it specifies the minimum number of lines of an
-immediately subsequent paragraph that must be kept on the same page as
-the heading. If insufficient space remains on the current page to
-accommodate the heading and this number of lines of paragraph text, a
-page break is forced before the heading is printed. Any display macro
-call or @code{tbl}, @code{pic}, or @code{eqn} region between the heading
-and the subsequent paragraph suppresses this grouping. @xref{ms keeps
-and displays} and @ref{ms Insertions}.
+In
+@code{groff} @file{ms},
+the
+@code{NH}
+and
+@code{SH}
+macros consult the
+@code{HORPHANS}
+register to prevent the output of isolated headings at the bottom of a
+page;
+it specifies the minimum number of lines of an immediately subsequent
+paragraph that must be kept on the same page as the heading.
+If insufficient space remains on the current page to accommodate the
+heading and this number of lines of paragraph text,
+@code{groff} @file{ms}
+forces a page break before setting the heading.
+Any display macro call or
+@code{tbl},
+@code{pic},
+or
+@code{eqn}
+region between the heading and the subsequent paragraph
+suppresses this grouping.
+@xref{ms keeps and displays} and @ref{ms Insertions}.
@c ---------------------------------------------------------------------
@@ -4063,12 +4091,21 @@ A @dfn{boxed keep} has a frame drawn around it.
boxed keep.
@endDefmac
-Boxed keep macros cause breaks; to box words within a line, recall
-@code{BX} in @ref{Typeface and decoration}. Box lines are drawn as
-close as possible to the text they enclose so that they are usable
-within paragraphs. When boxing entire paragraphs thus, you may
-improve their appearance by calling @code{B1} after the first
-paragraphing macro, and invoking the @code{sp} request before calling
+Boxed keep macros cause breaks;
+to box words within a line,
+recall
+@code{BX}
+in @ref{Typeface and decoration}.
+@file{ms}
+draws box lines close to the text they enclose
+so that they are usable within paragraphs.
+When boxing entire paragraphs thus,
+you may improve their appearance by calling
+@code{B1}
+after the first paragraphing macro,
+and invoking the
+@code{sp}
+request before calling
@code{B2}.
@c Wrap example at 58 columns.
diff --git a/doc/ms.ms b/doc/ms.ms
index eaddeedea..e92225168 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -490,15 +490,13 @@ Macros enable the collection of entries for a table of
contents
(or index)
as the material they discuss appears in the document.
.
-You then call a macro to emit the table of contents at the end of
-your document.
+A macro call at the end of the document emits the collected entries.
.
-The table of contents must necessarily follow the rest of the text since
-GNU
-.I troff
+This material necessarily follows the rest of the text since GNU
+.I troff \" GNU
is a single-pass formatter;
-it thus cannot determine the page number of a division of the text until
-it has been set and output.
+it cannot determine the page number of a division of the text
+until it has been set and output.
.
Since
.I ms
@@ -527,8 +525,8 @@ Document control settings
.
.
.LP
-The document parameters below are presented in the syntax
-used to interpolate their values.
+We present the document parameters below
+in the syntax used to interpolate their contents.
.
For any unsatisfactory default,
define its register,
@@ -745,10 +743,12 @@ argument suppresses this alteration.
.
Optional arguments can occur in any order.
.
+.I ms
+recognizes
.CW no
-is recognized as a synonym of
+as a synonym of
.CW no\-\:\%repeat\-\:\%info
-for AT&T compatibility.
+to maintain AT&T compatibility.
T}
_
\&.TL T{
@@ -1074,7 +1074,7 @@ If a new paragraph starts close to the bottom of a page,
and there is insufficient space to accommodate
.CW \[rs]n[PORPHANS]
lines before an automatic page break,
-.I ms
+.I "groff ms"
forces a page break before formatting the paragraph.
.
This is a GNU extension.
@@ -1524,20 +1524,22 @@ since it corresponds to heading depth\~2.
.
.
.PP
-The
-.CW \[rs]n[HORPHANS]
-register operates in conjunction with the
+In
+.I "groff ms,"
+the
.CW NH
and
.CW SH
-macros to inhibit the printing of isolated headings at the bottom of a
+macros consult the
+.CW HORPHANS
+register to prevent the output of isolated headings at the bottom of a
page;
it specifies the minimum number of lines of the subsequent paragraph
that must be kept on the same page as the heading.
.
If insufficient space remains on the current page to accommodate the
heading and this number of lines of paragraph text,
-.I ms
+.I "groff ms"
forces a page break before setting the heading.
.
Any display macro call or
@@ -2293,8 +2295,9 @@ recall
.CW BX
in section \[lq]Typeface and decoration\[rq] above.
.
-Box lines are drawn as close as possible to the text they enclose so
-that they are usable within paragraphs.
+.I ms
+draws box lines close to the text they enclose
+so that they are usable within paragraphs.
.
When boxing entire paragraphs thus,
you may improve their appearance by calling
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 6242ce957..26d0066a7 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -208,15 +208,13 @@ Macros enable the collection of entries for a table of
contents
(or index)
as the material they discuss appears in the document.
.
-You then call a macro to emit the table of contents at the end of
-your document.
+A macro call at the end of the document emits the collected entries.
.
-The table of contents must necessarily follow the rest of the text since
-GNU
+This material necessarily follows the rest of the text since GNU
.I troff \" GNU
is a single-pass formatter;
-it thus cannot determine the page number of a division of the text until
-it has been set and output.
+it cannot determine the page number of a division of the text
+until it has been set and output.
.
Since
.I ms
@@ -508,10 +506,12 @@ argument suppresses this alteration.
.
Optional arguments can occur in any order.
.
-.RB \[lq] no \[rq]
-is recognized as a synonym of
+.I ms
+recognizes
+.B no
+as a synonym of
.B no\-\:\%repeat\-\:\%info
-for AT&T compatibility.
+to maintain AT&T compatibility.
.
.
.TP
@@ -737,7 +737,7 @@ If a new paragraph starts close to the bottom of a page,
and there is insufficient space to accommodate
.B \[rs]n[PORPHANS]
lines before an automatic page break,
-.I ms
+.I "groff ms"
forces a page break before formatting the paragraph.
.
This is a GNU extension.
@@ -1027,20 +1027,22 @@ are GNU extensions.
.
.
.P
-The
-.B \[rs]n[HORPHANS]
-register operates in conjunction with the
+In
+.I "groff ms,"
+the
.B NH
and
.B SH
-macros to inhibit the printing of isolated headings at the bottom of a
+macros consult the
+.B HORPHANS
+register to prevent the output of isolated headings at the bottom of a
page;
it specifies the minimum number of lines of the subsequent paragraph
that must be kept on the same page as the heading.
.
If insufficient space remains on the current page to accommodate the
heading and this number of lines of paragraph text,
-.I ms
+.I "groff ms"
forces a page break before setting the heading.
.
Any display macro call or
@@ -1349,8 +1351,9 @@ recall
.B BX
in section \[lq]Highlighting\[rq] above.
.
-Box lines are drawn as close as possible to the text they enclose so
-that they are usable within paragraphs.
+.I ms
+draws box lines close to the text they enclose
+so that they are usable within paragraphs.
.
When boxing entire paragraphs thus,
you may improve their appearance by calling
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
