[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/02: [ms]: Advise users of PDF and tables of contents.
From: |
G. Branden Robinson |
Subject: |
[groff] 02/02: [ms]: Advise users of PDF and tables of contents. |
Date: |
Wed, 21 Jun 2023 21:10:26 -0400 (EDT) |
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,
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 02/02: [ms]: Advise users of PDF and tables of contents.,
G. Branden Robinson <=