提交: a01868c021e548e9fd93d910e39deadc8c7f774e - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

Commit MetaInfo

• 修訂: a01868c021e548e9fd93d910e39deadc8c7f774e (tree)
• 時間: 2022-03-30 04:12:08
• 作者: Keith Marshall <keith@user...>
• Commiter: Keith Marshall

Log Message

Implement a more effective TOC generation strategy.

* tmac/toc.tmac: New file; it implements a basic, extensible,
table of contents generator macro framework; use it...
* pdfmark.ms (XH-UPDATE-TOC): ...here; modify it to generate...
(pdfmark.toc): ...this new file, subsequently included and used by...
(toc.outline, toc.refmark, toc.pageref): ...these new document-local
toc.tmac extending macros, to generate TOC in-line, superseding...
(TC): ...use of this spdf.tmac macro; delete reference.
[TOC] (PDFHREF.TEXT.COLOUR): Set it to match...
(\n[.m]): ...this.

* Makefile.in (pdfmark.pdf): Update dependencies, requiring...
(pdfmark.toc): ...this new intermediate file; add rules to generate
it, by performing a separate pre-processing pass over...
(pdfmark.ms): ...this primary source file.
(clean): Remove "*.toc" files.

Change Summary

• modified: Makefile.in
• modified: pdfmark.ms
• add: tmac/toc.tmac

差異

diff -r dfbd1d88c3e4 -r a01868c021e5 Makefile.in
--- a/Makefile.in	Mon Mar 28 16:43:31 2022 +0100
+++ b/Makefile.in	Tue Mar 29 20:12:08 2022 +0100
@@ -83,8 +83,8 @@
 # We want to use the locally maintained groff macro files, as those in
 # the system's groff installation may not be sufficiently up-to-date.
 #
+pdfroff := pdfroff
 tmacdir := ${srcdir}/tmac
-pdfroff := GROFF_TMAC_PATH=${tmacdir} pdfroff
 
 vpath %.ms ${srcdir}
 vpath %.tmac ${srcdir}/tmac
@@ -92,13 +92,19 @@
 # Specific prerequisites of "pdfmark.pdf", to be used...
 #
 pdfmark.pdf: style := --style=${srcdir}/cover.ms
-pdfmark.pdf: gnu.eps spdf.tmac s.tmac pdfmark.tmac sanitize.tmac
+pdfmark.pdf pdfmark.toc: spdf.tmac s.tmac pdfmark.tmac sanitize.tmac toc.tmac
+pdfmark.pdf: gnu.eps pdfmark.toc
+
+override pdfroff := GROFF_TMAC_PATH=${tmacdir} $(pdfroff)
 
 # ...in conjunction with this generic build rule.
 #
 %.pdf: %.ms
 	$(pdfroff) -mspdf $(style) -dpaper=a4 -P-pa4 $< > $@
-	
+
+%.toc: %.ms
+	$(pdfroff) -U -mspdf --no-pdf-output -dpaper=a4 -P-pa4 $<
+
 # We require copies of embeddable artwork files to be accessible
 # via references in the working build directory.
 #
@@ -109,7 +115,7 @@
 # -------------
 #
 clean mostlyclean:
-	$(RM) *.pdf
+	$(RM) *.pdf *.toc
 
 distclean: clean
 	$(RM) config.* *.eps

diff -r dfbd1d88c3e4 -r a01868c021e5 pdfmark.ms
--- a/pdfmark.ms	Mon Mar 28 16:43:31 2022 +0100
+++ b/pdfmark.ms	Tue Mar 29 20:12:08 2022 +0100
@@ -85,19 +85,160 @@
 .nr DI  5n
 .nr HY  0
 .
-.\" Within the table of contents, the width of the right-hand margin,
-.\" in which space is reserved for the display of page numbers, and the
-.\" appearance of the leaders which precede it, are controlled by:-
-.\"
-.char \[TC-LEADER] \h'0.8n'.
-.nr TC-MARGIN \w'00000'
-.
 .\" Generate headers in larger point sizes, for NH levels < 4,
 .\" with point size increasing by 1.5p, for each lesser NH level.
 .\"
 .nr GROWPS 4
 .nr PSINCR 1.5p
 .
+.\" Immediately following the cover sheet, and front-matter, is the
+.\" conventional placement for the table of contents; we begin this
+.\" on a new page, with a centred heading, which we have choosen to
+.\" set at a font size 2pts greater than that of normal paragraphs,
+.\" (thus matching standard "ms" convention), with lower case roman
+.\" numerals for page numbering, with its own entry within the PDF
+.\" document outline, and with the equivalent of two blank lines
+.\" separating the heading from the TOC references.
+.\"
+.af % i
+.LP
+.ce 1
+.pdfhref O 1 \\*[TOC]
+.\"pdfhref O -N toc 1 \\*[TOC]
+.B "\s'+2p'\*[TOC]\s'-2p'"
+.sp 2v
+.\"
+.\" The traditional mechanism, supported by "ms", for generation of
+.\" tables of contents, relies on post-press collation, to print the
+.\" table of contents AFTER the document body, and then to relocate
+.\" it to its conventional position, BEFORE the body content.
+.\"
+.\" While pdfroff DOES support such post-press collation, it is not
+.\" the most effective method for placement of the tables of contents
+.\" within PDF documents.  Although a method for use of the technique
+.\" is described, in Section 3 of this document, it is not the actual
+.\" method employed; in particular, it has been found to be unsuited
+.\" to the creation of a table of contents which is actively linked
+.\" to its corresponding body content.  Consequently, the preferred
+.\" method of table of contents generation is now to save relevant
+.\" reference data during the pdfroff pre-press phase, and then to
+.\" reimport it during the body content publication phase, using
+.\" the toc.tmac macros, integrated with pdfroff...
+.\"
+.mso toc.tmac
+.if \n[.U] .toc file pdfmark.toc
+.\"
+.\" ...by means of the following integration hooks, and auxillary
+.\" helper script, (noting that this bypasses groff's "safer" mode
+.\" protection, WITHOUT requiring the "-U" option):
+.\"
+.\"ds TOC.REQUEST gropdf-info:toc
+.\"pdfroff option $AWK -f pdfmark.toc.awk $WRKFILE > pdfmark.tmp
+.\"
+.\" Within the table of contents, structural layout will be achieved,
+.\" under the direction of the following spacing control constants:
+.\"
+.ds TC-VS1 0.40v  \" leading for top level
+.ds TC-VS2 0.15v  \" leading at nesting level increment
+.ds TC-VS3 0.25v  \" leading following nested group
+.\"
+.\" Additionally, the width of the right-hand margin, in which space
+.\" is reserved for the display of page numbers, and the appearance of
+.\" the leaders which precede it, are controlled by:-
+.\"
+.nr TC-MARGIN \w'00000'
+.char \[TC-LEADER] \h'0.8n'.
+.lc \[TC-LEADER]
+.\"
+.\" Macro "toc.outline" initializes output state for each individual
+.\" TOC reference entry, controlling indentation based on designated
+.\" outline-level, as passed in the initiating XH-UPDATE-TOC call.
+.\"
+.de toc.outline
+.   ie \\$1>1 \{\
+.      \" Entries at outline-levels greater than one are indented
+.      \" by 1em for each level; additionally, on increasing level
+.      \" from that of the preceding entry, as recorded in the local
+.      \" register, "toc.outline.current", additional vertical space
+.      \" equal to "TC-VS2" is inserted, while on decreasing to any
+.      \" level which remains greater than one, similar additional
+.      \" vertical space equal to "TC-VS3" is inserted.
+.      \"
+.         nr toc.indent \\$1m-1m
+.         ie \\$1>\\n[toc.outline.current] .sp \*[TC-VS2]
+.         el .if \\n[toc.outline.current]>\\$1 .sp \*[TC-VS3]
+.         nop \h'\\n[toc.indent]u'\c
+.
+.      \" After emitting the appropriate indentation space, the
+.      \" tab-stop settings must be adjusted to compensate.
+.      \"
+.         nr toc.indent \\n[.l]-\\n[.i]-\\n[toc.indent]
+.         ta (u;\\n[toc.indent]-\\n[TC-MARGIN]) (u;\\n[toc.indent])R
+.         rr toc.indent
+.      \}
+.   el \{\
+.      \" Entries at outline-level one are not indented, but each
+.      \" except the first, (identified by not yet having defined
+.      \" the "toc.outline.current" register), will be preceded by
+.      \" vertical space equal to "TC-VS1"; in any case, tab-stops
+.      \" are reset to match "ms" convention, in preparation for
+.      \" output of level one TOC entry.
+.      \"
+.         if r toc.outline.current .sp \*[TC-VS1]
+.         ta (u;\\n[.l]-\\n[.i]-\\n[TC-MARGIN]) (u;\\n[.l]-\\n[.i])R
+.      \}
+.
+.\" After initialization for the first TOC entry, tracking of the
+.\" current outline-level is persistently maintained, by recording
+.\" of the "toc.outline.current" register.
+.\"
+.   nr toc.outline.current \\$1
+..
+.\" The collected TOC reference data is interpolated back into the
+.\" document output stream, initially by the toc.refmark macro...
+.\"
+.de toc.refmark
+.   \" ...which simply stores the text for the TOC pageref entry,
+.   \" within the toc.refmark.text string, whence it is...
+.   \"
+.   ds \\$0.text \\$*
+..
+.\" ...subsequently retrieved by the toc.pageref macro...
+.\"
+.de toc.pageref
+.   \" ...to be incorporated into an active pdfhref link, along
+.   \" with the appropriate page number reference, and emitted
+.   \" to the document output stream.
+.   \"
+.   pdfhref L -D \\*[toc.refmark.text]\a\t\\$*
+.   rm toc.refmark.text
+.   br
+..
+.\" Although the TOC is to be entirely populated by active PDFHREF
+.\" links, we prefer to not over-emphasize this by use of the link
+.\" highlight colour; thus, after breaking the PDFHREF.TEXT.COLOUR
+.\" to PDFHREF.TEXT.COLOR equivalence, we may adjust the effective
+.\" link colour, to match the normal body text colour.
+.\"
+.rm PDFHREF.TEXT.COLOUR
+.ds PDFHREF.TEXT.COLOUR \n(.m
+.\"
+.\" Actual content for the TOC has been dynamically captured in the
+.\" pdfmark.toc file; simply include it here.
+.\"
+.so pdfmark.toc
+.\"
+.\" After output of the TOC, we may clear the PDFHREF.TEXT.COLOUR
+.\" reassignment; the next call of pdfhref L, or of pdfhref W, will
+.\" re-establish its equivalence to PDFHREF.TEXT.COLOR
+.\"
+.rm PDFHREF.TEXT.COLOUR
+.\"
+.\" Finally, reset the page numbering style, and prepare for output
+.\" of the document body from page number one.
+.\"
+.af % 0
+.bp 1
 .
 .\" Implement an interface with the FS macro (from s.tmac) to facilitate
 .\" placement of footnote reference marks, with each serving as an active
@@ -254,13 +395,6 @@
 .\" the user-specified callback macro,  XH-UPDATE-TOC, whereby it may
 .\" be used, e.g. to construct a table of contents entry.
 .\"
-.\" Within the table of contents, structural layout will be achieved,
-.\" under the direction of the following spacing control constants:
-.\"
-.ds XNVS1 0.50v  \" leading for top level
-.ds XNVS2 0.15v  \" leading at nesting level increment
-.ds XNVS3 0.30v  \" leading following nested group
-.\"
 .\" Note that one TOC related callback hook is shared by both XH and
 .\" XN; its is called XH-UPDATE-TOC, regardless of whether called by
 .\" XH or by XN; when called by XN, it is invoked with arguments:
@@ -268,55 +402,37 @@
 .\"  .XH-UPDATE-TOC <outline-level> <section-number> <text> ...
 .\"
 .de XH-UPDATE-TOC
-.\" This implementation of XH-UPDATE-TOC utilizes the rudimentary ms
-.\" mechanism for formatting a table of contents, using XS and XE to
-.\" bracket individual entries.
-.   XS
-.   \" A local register, tc*hl, is used to track the outline level
-.   \" of each TOC entry, as it is added; it is not defined, until
-.   \" the first entry is recorded...
+.   \" Collection of TOC reference data is performed in pdfroff's
+.   \" pre-press phase, (before any PHASE indicator register value
+.   \" has been assigned); once PHASE has been assigned, this will
+.   \" simply appear as noise on standard error, so we may just as
+.   \" well suppress it.
 .   \"
-.      if r tc*hl \{\
-.         \" ...after which, we use it to establish indentation,
-.         \" to reflect changes in outline level.
-.         \"
-.            ie \\$1>1 \{\
-.               \" When at any outline level greater than one,
-.               \" any level increment will be offset by XNVS2
-.               \" units of vertical space...
-.               \"
-.                  ie \\$1>\\n[tc*hl] .sp \\*[XNVS2]
-.
-.               \" ...whereas any decrement will be offset by
-.               \" XNVS3 units.
-.               \"
-.                  el .if \\n[tc*hl]>\\$1 .sp \\*[XNVS3]
-.               \}
-.
-.         \" ...but every top-level entry, after the first, is
-.         \" offset by XNVS1 units.
-.         \"
-.            el .sp \\*[XNVS1]
-.         \}
-.
-.   \" \$1 becomes the effective outline level for the current table
-.   \" of contents entry, but we must ensure that it is one or more.
-.   \"
-.      ie \\$1 .nr tc*hl \\$1
-.      el .nr tc*hl 1
-.
-.   \" The current outline level determines the indentation at which
-.   \" we place the section number reference...
-.   \"
-.      nop \h'\\n[tc*hl]-1m'\\$2\c
-.
-.   \" ...after which we discard \$1 and \$2,  allowing us to append
-.   \" all remaining arguments, ensuring that there is at least 0.5n
-.   \" of following space, before the first leader dot.
-.   \"
+.   if !\\n[PHASE] \{\
+.      \" When collecting the reference data, we begin by storing
+.      \" the <outline-level>, the associated name assigned to the
+.      \" outline bookmark, and the <section-number> string...
+.      \"
+.      toc put outline \\$1
+.      ds toc.refmark.text \\*[PDFBOOKMARK.NAME] -- \\$2
+.      \"
+.      \" Having stored these two arguments, we discard them, so
+.      \" that we are left with only the <text> ... argument list,
+.      \" which we append to the collected TOC reference data...
+.      \"
 .      shift 2
-.      nop \h'1.5n'\\$*\h'0.5n'
-.   XE
+.      toc put refmark \\*[toc.refmark.text]\h'1.5n'\\$*\h'0.5n'
+.      \"
+.      \" ...which is then completed, by the addition of a page
+.      \" number reference.
+.      \"
+.      toc put pageref \\n%
+.      \"
+.      \" Finally, clean up the temporary storage, which we have
+.      \" used to collect the TOC reference data.
+.      \"
+.      rm toc.refmark.text
+.   \}
 ..
 .XN Introduction
 .\"
@@ -4602,7 +4718,7 @@
 .
 .NH 3
 .XN -N import-map -- Deploying a Document Reference Map
-.TC
+.
 .\" Local Variables:
 .\" mode: nroff
 .\" End:

diff -r dfbd1d88c3e4 -r a01868c021e5 tmac/toc.tmac
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tmac/toc.tmac	Tue Mar 29 20:12:08 2022 +0100
@@ -0,0 +1,115 @@
+.\" -*- nroff -*-
+.ig
+
+toc.tmac
+
+A minimal foundation macro framework, for construction of tables
+of contents; provides the "toc" macro, with basic support for:
+
+     .toc file [filename]
+     .toc put operation [arguments ...]
+     .toc error message ...
+
+This basic framework is extensible, by provision of user-supplied
+auxiliary macros, with names of the form "toc.operation", to add
+support for arbitrary operations, designated as:
+
+     .toc operation [arguments ...]
+
+
+Copyright (C) 2022, Free Software Foundation, Inc.
+     Written by Keith Marshall ([e-mail])
+
+
+This file is part of groff.
+
+groff is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2, or (at your option) any later
+version.
+
+groff is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with groff; see the file COPYING.  If not, write to the Free Software
+Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
+..
+.if !\n(.g .ab These TOC macros require groff.
+.
+.\" Check if we have already been loaded -- do not reload
+.if d toc.put .nx
+.
+.de toc
+.\" Usage: .toc operation [argument ...]
+.\"
+.\" Primary entry point for user calls; performs a simple redirection
+.\" to an appropriate handler for the specified operation, or emits an
+.\" error diagnostic message, if no handler exists.
+.\"
+.   ie d \\$0.\\$1 .\\$0.\\$*
+.   el .toc error \\$0: \\$1: unknown keyword
+..
+.
+.\" User adjustable configuration parameters...
+.
+.ds TOC.REQUEST .toc
+.
+.de toc.error
+.\" Usage: .toc error message ...
+.\"
+.\" Emit a package-specific diagnostic message on the stderr stream.
+.\"
+.   tm toc macro error: \\$*
+..
+.de toc.file
+.\" Usage: .toc file [filename]
+.\"
+.\" Assign a file, in which to collect TOC reference data; "filename"
+.\" may be omitted, to close any previously assigned collection file,
+.\" activating collection of subsequent reference data via "stderr".
+.\"
+.\" Note that data collection to a named file requires "groff" to be
+.\" invoked with the "-U" option; this restriction does not apply to
+.\" data collection via "stderr".
+.\"
+.   if \\n[toc#stream] .close toc!stream
+.   nr toc#stream 0
+.   als toc.put toc.put.tty
+.   if !'\\$1'' \{\
+.      ie \\n[.U] \{\
+.         open toc!stream \\$1
+.         als toc.put toc.put.file
+.         nr toc#stream 1
+.      \}
+.      el .toc error \\$1: unsafe mode required to write file.
+.   \}
+..
+.de toc.put.file
+.\" Usage: .toc put request arguments ...
+.\"
+.\" Service the .toc put request, when collecting such requests in
+.\" a user designated file.  Prefixed by the string which is defined
+.\" as TOC.REQUEST, (which is ".toc" by default), the request and its
+.\" arguments are copied to the designated file.
+.\"
+.   write toc!stream \\*[TOC.REQUEST] \\$*
+..
+.de toc.put.tty
+.\" Usage: .toc put request arguments ...
+.\"
+.\" Service the .toc put request, when collecting such requests via
+.\" the stderr output stream.  Prefixed by the string which is defined
+.\" as TOC.REQUEST, (which is ".toc" by default), the request and its
+.\" arguments are copied to the stderr stream.
+.\"
+.   tm \\*[TOC.REQUEST] \\$*
+..
+.\" Initialize for default .toc request collection via stderr.
+.\"
+.toc file
+.
+.
+.\" toc.tmac: end of file: vim: filetype=groff