[groff] 02/02: [ms]: Advise users of PDF and tables of contents.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1b2b6c8c0fbde674eb898180cb5d4905be7a352e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 21 20:04:23 2023 -0500

    [ms]: Advise users of PDF and tables of contents.
    
    [ms]: Offer advice to users of PDF who want a table of contents at the
    front of the document.
    
    * doc/groff.texi (ms Document Structure): Move mention of pdfjam(1) from
      here...
    
      (ms TOC): ...to here, and identify alternatives, including gropdf(1)'s
      `pdfswitchtopage` macro.
    
    * doc/ms.ms (General structure of an ms document):
      (Creating a table of contents): Similar.
    
    Fixes <https://savannah.gnu.org/bugs/?64278>.  Thanks to Michał
    Kruszewski for the report.
    
    ANNOUNCE: Acknowledge Michał and update bug counts.
---
 ANNOUNCE            |  7 ++++---
 ChangeLog           | 16 ++++++++++++++++
 doc/groff.texi      | 15 ++++++++-------
 doc/ms.ms           | 19 ++++++++++++++-----
 tmac/groff_ms.7.man |  3 +--
 5 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/ANNOUNCE b/ANNOUNCE
index f2b54c0a1..922ce4a65 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -77,7 +77,7 @@ release shipped with three automated unit tests; this one 
ships with
 over 160 unit and regression tests.
 
 As of this writing, per the GNU Savannah bug tracker, the groff project
-has resolved 429 problems as fixed for the 1.23.0 release.  Some of the
+has resolved 430 problems as fixed for the 1.23.0 release.  Some of the
 bugs we've corrected were over 30 years old.
 
 Classifying these issues by type and the component of the project to
@@ -87,7 +87,7 @@ which they apply, we find the following.
   ----                              ---------
   Build/installation           39   Core                          101
   Crash/unresponsive           11   Driver: grohtml                 7
-  Documentation               109   Driver: gropdf                 10
+  Documentation               110   Driver: gropdf                 10
   Feature change               41   Driver: grops                   2
   Incorrect behavior          131   Driver: grotty                  4
   Lint                         15   Driver: others/general          7
@@ -100,7 +100,7 @@ which they apply, we find the following.
                                     Macros: me                     36
                                     Macros: mm                     20
                                     Macros: mom                    11
-                                    Macros: ms                     28
+                                    Macros: ms                     29
                                     Macros: other/general          27
                                     Preprocessor: eqn               5
                                     Preprocessor: grn               3
@@ -228,6 +228,7 @@ John Gardner
 KUBO Koichi
 Keith Marshall
 Ken Mandelberg
+Michał Kruszewski
 Nikita Ivanov
 Oliver Corff
 Olle Lögdahl
diff --git a/ChangeLog b/ChangeLog
index a52b13f2a..728478ce3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2023-06-21  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [ms]: Offer advice to users of PDF who want a table of contents
+       at the front of the document.
+
+       * doc/groff.texi (ms Document Structure): Move mention of
+       pdfjam(1) from here...
+       (ms TOC): ...to here, and identify alternatives, including
+       gropdf(1)'s `pdfswitchtopage` macro.
+
+       * doc/ms.ms (General structure of an ms document):
+       (Creating a table of contents): Similar.
+
+       Fixes <https://savannah.gnu.org/bugs/?64278>.  Thanks to Michał
+       Kruszewski for the report.
+
 2023-06-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [docs]: Migrate terminology to "scaling unit".
diff --git a/doc/groff.texi b/doc/groff.texi
index 40cb4130c..cf9407f0f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2692,10 +2692,9 @@ 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,
 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 can be done in the digital domain with tools like
-@cite{pdfjam@r{(1)}}.  An index works similarly, but because it
-typically needs to be sorted after collection, its preparation requires
-separate processing.
+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 ---------------------------------------------------------------------
@@ -4353,9 +4352,11 @@ maintaining it.  @file{ms} enables the collection of 
material to be
 presented in the table of contents as it appears, saving its page number
 along with it, and then emitting the collected contents on demand toward
 the end of the document.  The table of contents can then be resequenced
-to its desired location as part of post-processing---with a PDF page
-relocation tool, or by physically rearranging the pages of a printed
-document, depending on the output format and circumstances.
+to its desired location by physically rearranging the pages of a printed
+document, or as part of post-processing---with a @cite{sed@r{(1)}}
+script to reorder the pages in @command{troff}'s output, with
+@cite{pdfjam@r{(1)}}, or with @cite{gropdf@r{(1)}}'s
+@samp{.pdfswitchtopage} feature, for example.
 
 Define an entry to appear in the table of contents by bracketing its
 text between calls to the @code{XS} and @code{XE} macros.  A typical
diff --git a/doc/ms.ms b/doc/ms.ms
index d90e1ca34..984c80424 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -496,8 +496,7 @@ 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 can be done in the digital domain with tools like
-.I pdfjam (1).
+page resequencing is more often done in the digital domain.
 .
 An index works similarly,
 but because it typically needs to be sorted after collection,
@@ -3442,9 +3441,19 @@ and then emitting the collected contents on demand 
toward the end of the
 document.
 .
 The table of contents can then be resequenced to its desired location
-as part of post-processing\[em]with a PDF page relocation tool,
-or by physically rearranging the pages of a printed document,
-depending on the output format and circumstances.
+by physically rearranging the pages of a printed document,
+or as part of post-processing\[em]with a
+.I sed (1)
+script to reorder the pages in
+.I troff 's
+output,
+with
+.I pdfjam (1),
+or with
+.I gropdf (1)'s
+.B .pdfswitchtopage
+feature,
+for example.
 .
 .
 .PP
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index e2eaba626..5d154f836 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -223,8 +223,7 @@ 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 can be done in the digital domain with tools like
-.MR pdfjam 1 .
+page resequencing is more often done in the digital domain.
 .
 An index works similarly,
 but because it typically needs to be sorted after collection,