[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 07/08: Fix Savannah #63827 (stop distributing pdfmark).
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 07/08: Fix Savannah #63827 (stop distributing pdfmark). |
|
Date: |
Fri, 15 Nov 2024 17:21:40 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit b58576c18b8f696e5a7fb62722caad37c92a6752
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 14 16:59:37 2024 -0600
Fix Savannah #63827 (stop distributing pdfmark).
Stop distributing pdfmark. It is now separately maintained. Please
visit <https://osdn.net/users/keith/pf/groff-pdfmark/> for the latest
version.
* contrib/pdfmark: Recursively delete.
* Makefile.am: Stop including its Automake file.
* doc/doc.am (GROFF_MAN_PAGES1): Drop pdfroff man page.
* src/utils/grog/tests/smoke-test.sh: Stop using
"contrib/pdfmark/{cover,pdfmark}.ms" as test artifacts.
* MANIFEST:
* src/roff/groff/groff.1.man: De-document.
* NEWS: Add item.
Fixes <https://savannah.gnu.org/bugs/?63827>.
Also drop somewhat misleading comments from Makefile.am. (hdtbl,
grohtml, and gropdf all use Ghostscript. Only m4/ax_compare_version.m4
uses the Autoconf-detected version of AWK. A few maintainer-mode
scripts and test scripts use AWK, but they assume it's installed as
"awk" and, looking over the scripts they feed it, none seems to exercise
anything but basic AWK features, possibly compatible all the way back to
Seventh Edition "Original AWK".)
---
ChangeLog | 19 +
MANIFEST | 2 -
Makefile.am | 3 -
NEWS | 5 +
contrib/pdfmark/.gitignore | 3 -
contrib/pdfmark/ChangeLog | 707 ---------
contrib/pdfmark/PROBLEMS | 32 -
contrib/pdfmark/README | 57 -
contrib/pdfmark/TODO | 60 -
contrib/pdfmark/cover.ms | 70 -
contrib/pdfmark/pdfmark.am | 100 --
contrib/pdfmark/pdfmark.ms | 2831 ------------------------------------
contrib/pdfmark/pdfmark.tmac | 1953 -------------------------
contrib/pdfmark/pdfroff.1.man | 985 -------------
contrib/pdfmark/pdfroff.sh | 682 ---------
contrib/pdfmark/sanitize.tmac | 170 ---
contrib/pdfmark/spdf.tmac | 328 -----
doc/doc.am | 1 -
src/roff/groff/groff.1.man | 4 +-
src/utils/grog/tests/smoke-test.sh | 10 -
20 files changed, 26 insertions(+), 7996 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 452facb64..5b18fb6c9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2024-11-14 G. Branden Robinson <g.branden.robinson@gmail.com>
+
+ Stop distributing pdfmark. It is now separately maintained.
+ Please visit <https://osdn.net/users/keith/pf/groff-pdfmark/>
+ for the latest version.
+
+ * contrib/pdfmark: Recursively delete.
+ * Makefile.am: Stop including its Automake file.
+ * doc/doc.am (GROFF_MAN_PAGES1): Drop pdfroff man page.
+ * src/utils/grog/tests/smoke-test.sh: Stop using
+ "contrib/pdfmark/{cover,pdfmark}.ms" as test artifacts.
+
+ * MANIFEST:
+ * src/roff/groff/groff.1.man: De-document.
+
+ * NEWS: Add item.
+
+ Fixes <https://savannah.gnu.org/bugs/?63827>.
+
2024-11-14 G. Branden Robinson <g.branden.robinson@gmail.com>
* NEWS: Explain changes to `\X` and `.device` argument
diff --git a/MANIFEST b/MANIFEST
index 35b260aa1..07c1a0b7d 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -50,8 +50,6 @@ This file summarizes the structure of the groff source
distribution.
hdtbl A sophisticated table macro package.
mm The groff memorandum macro package.
mom Peter Schaffter's "mom", a friendly groff macro package.
- pdfmark Add PDF marks to groff documents; includes "pdfroff",
- which eases creation of PDF documents.
pic2graph Convert pic(1) diagrams into graphical images.
rfc1345 Use RFC 1345 mnemonics as groff special characters.
sboxes Use bordered, shaded background boxes with ms and PDF.
diff --git a/Makefile.am b/Makefile.am
index 412158b27..14b8b52db 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -44,11 +44,9 @@ SH_SEP=@PATH_SEPARATOR@
# 'ALT_GHOSTSCRIPT_PROGS' specifies a list of alternative names to be
# tried if 'GHOSTSCRIPT' cannot be found at run time.
-# XXX: only pdfmark.am uses this
# 'ALT_AWK_PROGS' similarly specifies a list of alternative names,
# which can be tried at run time, to identify the awk program.
-# XXX: only pdfmark.am uses this
# BROKEN_SPOOLER_FLAGS
#
@@ -578,7 +576,6 @@ include $(top_srcdir)/contrib/grap2graph/grap2graph.am
include $(top_srcdir)/contrib/hdtbl/hdtbl.am
include $(top_srcdir)/contrib/mm/mm.am
include $(top_srcdir)/contrib/mom/mom.am
-include $(top_srcdir)/contrib/pdfmark/pdfmark.am
include $(top_srcdir)/contrib/pic2graph/pic2graph.am
include $(top_srcdir)/contrib/rfc1345/rfc1345.am
include $(top_srcdir)/contrib/sboxes/sboxes.am
diff --git a/NEWS b/NEWS
index e6d4f7cba..ac143963f 100644
--- a/NEWS
+++ b/NEWS
@@ -218,6 +218,11 @@ soelim
Macro packages
--------------
+* Keith Marshall's pdfmark package is no longer distributed with groff,
+ but is now separately maintained. Please visit
+ <https://osdn.net/users/keith/pf/groff-pdfmark/> for the latest
+ version.
+
* mom version 2.6 is distributed with this release. It supports
multi-line headings. Thanks to Peter Schaffter.
diff --git a/contrib/pdfmark/.gitignore b/contrib/pdfmark/.gitignore
deleted file mode 100644
index 517d6d711..000000000
--- a/contrib/pdfmark/.gitignore
+++ /dev/null
@@ -1,3 +0,0 @@
-# build artifacts
-/pdfroff.1
-/pdfmark.pdf
diff --git a/contrib/pdfmark/ChangeLog b/contrib/pdfmark/ChangeLog
deleted file mode 100644
index 3e5f49cef..000000000
--- a/contrib/pdfmark/ChangeLog
+++ /dev/null
@@ -1,707 +0,0 @@
-2024-01-22 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am (pdfmark.pdf): Register dependency on
- "tmac/pspic.tmac".
-
-2023-07-17 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfroff.sh: Stop endorsing shebang line space myth. See
- <https://savannah.gnu.org/bugs/?64058>.
-
-2023-02-24 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Do not emit redundant 'pdfhref Z' records.
-
- * pdfroff.sh [grohtml-info] (pdfhref Z): Adapt awk script, to
- emit...
- (pdfhref Z 0 0 0): ...this conditionally, only if at least one
- prior record has been emitted; delete unconditional emission,
- which caused the anomaly reported as groff issue #63133.
-
- Fixes <https://savannah.gnu.org/bugs/?63133>.
-
- {merged from OSDN hg patch by GBR, 2023-04-07}
-
-2023-02-18 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am (uninstall-pdfmark-hook): Simplify uninstallation.
- Try to remove the configured `pdfdocdir` in the event it is
- empty, but do not fail if it isn't. (It can be a directory
- shared with other groff components; we don't know in what order
- the uninstall targets will serialize, but the last one run
- should succeed.)
-
-2022-09-20 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * sanitize.tmac: Move comment to where escape sequences are
- recognized. Problem arose in commit 058b63ce3d, 2021-09-04.
-
- troff:.../contrib/pdfmark/sanitize.tmac:162: warning: macro '\"'
- not defined
-
-2022-05-20 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am: Rename `BUILD_PDFDOC` to `USE_GROPDF`.
-
-2022-03-30 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am: Eliminate `PDFMARK_TFLAG` and `PDFMARK_PFLAG` Make
- macros; they were expanded in only one place.
- (PDFROFF): Track rename of Make macro `TFLAG` to `MFLAG`.
-
-2022-03-30 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * cover.ms: Die horribly if `PSPIC` call fails.
-
-2022-03-26 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am (PDFDOCFILES): Replace hard-coded "gnu.eps"
- file name with expansion of `DOC_GNU_EPS`.
- (contrib/pdfmark/pdfmark.pdf): Pass `-I` option to pdfroff(1) to
- enable location of "gnu.eps" file.
-
-2021-10-24 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Adapt to accommodate global XH and XN implementations.
-
- cf. <https://savannah.gnu.org/bugs/?58946#comment13>
-
- * spdf.tmac (XH-INIT, XN-INIT, XH-UPDATE-TOC): Delete definitions;
- the defaults, provided by s.tmac, are now sufficient.
- (XH-REPLACEMENT, XN-REPLACEMENT): Define these, rather than...
- (XH, XN): ...these, respectively.
-
-2021-10-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Make a minor layout adjustment.
-
- * pdfmark.ms (Section 2.4.3): Add a vertical space reservation, to
- avoid a widow line at the end of the paragraph explaining use of...
- (PDFHREF.Y): ...this computed register, in the definition of...
- (PDFBOOKMARK.VIEW): ...this.
-
-2021-10-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Clarify references to use of the -Tpdf option.
-
- * pdfmark.ms (Section 2, Section 3.1): Add footnotes, indicating that
- only "-Tps" and "-Tpdf" output formats are supported, and that "-Tpdf"
- may avoid a separate step, to convert from PostScript to PDF.
-
-2021-10-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Work around misplacement of link "hot-spots" in footnotes.
-
- * pdfmark.ms (pdfhref-nobreak): New document-local macro; used instead
- of "pdfhref", this forces paragraph adjustment before placement of any
- unbreakable link text, for which line-wrap may be required. Currently
- observed only within footnotes, without adjustment, the "hot-spot" for
- the link may be placed 1v above its associated text.
-
-2021-10-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Link footnote reference marks to footnote text.
-
- * pdfmark.ms (FP): Redefine locally; replace s.tmac default.
- (FF): Do not redefine; our FP replacement macro does not use it.
- [d FS-MARK] (FS-MARK): Redefine locally; map it to...
- (pdf:fn.mark): ...this locally defined macro.
- [!d FS-MARK] (@FS): Rename s.tmac implementation as...
- (pdf:fn.record): ...this, then redefine @FS itself, to call...
- (pdf:fn.mark, pdf:fn.record): ...these, in respective order.
- (groff-1.19.1, GhostScript-8.14): Update footnote reference syntax.
- (Ghostscript-8.14, MSYS): Emulate sentence space after footnote mark.
- (*): Replace s.tmac string definition; make it equivalent to "\c",
- after renaming its original implementation as...
- (pdf:fn.index): ...this; synchronize references with changes to...
- (pdf:fn.index.count): ...this new locally defined register; it is
- auto-incremented by one, as each footnote is placed.
-
-2021-10-01 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Incorporate user-defined TOC leader style.
-
- * pdfmark.ms: Make some comment tidy-up adjustments.
- (TC-LEADER, TC-MARGIN): Define them, to take advantage of new
- s.tmac features; cf. <https://savannah.gnu.org/bugs/?61157>.
-
-2021-09-18 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Factor a further unnecessary macro out of spdf.tmac
-
- * spdf.tmac (XR): Remove it; relocate it to...
- * pdfmark.ms (XR): ...here.
-
-2021-09-13 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Add comments to annotate locally-defined font change macros.
-
- * pdfmark.ms (EM): Annotate this locally-defined emphasis macro...
- (CWB, CWI, CWBI): ...these constant width font interpolation macros...
- (=): ...and this locally-defined IP tag variant string.
-
-2021-09-13 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Update defunct internet URL references.
-
- * pdfmark.ms (pdfmark-manual): Adobe moved the document (again);
- update the document reference macro, to follow the URL relocation.
- (www.mingw.org): The MinGW Project has relinquished this domain;
- update the URL reference, to follow web-site relocation to...
- (mingw.osdn.io): ...here.
-
-2021-09-13 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Factor document-specific bloat out of spdf.tmac
-
- * spdf.tmac: Reorganize; add many comments.
- (XN): Retained, but reimplemented, to serve as...
- (XH, XN): ...both of these; add callback hooks for...
- (XH-INIT, XN-INIT, XH-UPDATE-TOC): ...these; provide no-op stubs;
- factor out TOC collection code, delegating to XH-UPDATE-TOC.
- (opt*XN-N, opt*XN-S, opt*XN-X): Rename internal macros to...
- (de spdf:XH-N, de spdf:XH-S, de spdf:XH-X): ...these, respectively.
- (AN, @AN, IE, IS, LU, NN, PXREF, SAME-PAGE, XM): Delete; we do not
- require these; if users do, they should define their own.
- (pdf@toc): Delete internal macro; fold body into...
- (TC): ...this.
-
- * pdfmark.ms (XH-UPDATE-TOC): Implement callback; it is based on...
- (XN): ...original implementation of this, factored out of spdf.tmac,
- but with significant simplification, to remove unnecessary code.
- (XNVS1, XNVS2, XNVS3): Tighten vertical spacing.
-
-2021-09-04 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Reduce potential for user-space exposure of "ms" internals.
-
- * spdf.tmac (@NH): Append to s.tmac macro; assign...
- (spdf:nh*hl): ...this new internal register; alias it to...
- (.NH): ...this new public name, hence making it track...
- (nh*hl): ...this s.tmac internal numeric register.
- (XN): Use \n[.NH] instead of \n[nh*hl].
-
-2021-09-03 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Sanitize text for use in PDF document outlines.
-
- * sanitize.tmac: New file; it implements...
- (sanitize): ...this new macro; interprets its first argument as a
- string name, and copies its remaining arguments to the named string,
- discarding specific embedded troff escape sequences; currently...
- (\F): ...only this is identified as "specifically discardable".
-
- * pdfmark.am (TMACFILES): Add sanitize.tmac
-
- * spdf.tmac (mso): Include sanitize.tmac
- (xn*ref, xn*argc): Rename all occurrences...
- (spdf:refname, spdf:argc): ...to these, respectively.
- (XN): Stop inserting $* directly into PDF outlines; instead, use...
- (spdf:bm.text): ...this new string; this is locally defined by...
- (spdf:bm.define): ...this new macro; passed the original $* from
- XN, this itself, is locally defined as a redirectable alias for...
- (spdf:bm.basic): ...this new local macro; it simply copies $*,
- passed from XN, to the string named by its first argument, (which is
- always spdf:bm.text), so reproducing previous behaviour.
- (opt*XN-S): New macro; defined for internal use only, it adds a "-S"
- option to XN, such that, when specified, it temporarily redirects...
- (spdf:bm.define): ...this macro mapping alias to...
- (sanitize): ...this.
-
- * pdfmark.ms (XN): Add "-S" option for all headings which include...
- (\F[C]...\F[]): ...this escape sequence.
-
-2021-08-21 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Define, and use registered trade mark strings.
-
- * pdfmark.ms (Adobe, Acrobat, Distiller, PostScript, Microsoft):
- Define as strings. Each expands to its own name, followed by the
- registered trademark symbol, as a superscript, and optional trailing
- punctuation, below the superscript. Use each as required.
-
-2021-08-21 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Prefer "-ize" to "-ise" where etymology permits.
-
- * pdfmark.ms: For all verbs, and their derivative nouns, for which
- British English allows either "-ise" or "-ize" as ending, prefer the
- "-ize" form of verb, and "-ization" form of noun, throughout.
-
-2021-08-20 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Correct a spelling error.
-
- * pdfmark.ms (Section 2.5.3.1): Fix typo: s/exanple/example/.
-
-2021-08-20 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Space out section headings in pdfmark.ms source.
-
- * pdfmark.ms (.NH): Precede each instance by one null request, to
- improve readability.
-
-2021-08-18 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Refine pdfroff "missing ghostscript" diagnostic.
-
- * pdfroff.sh [$GS = ":"]: Fix typo: s/connot/cannot/; refine text.
-
-2020-12-25 G. Branden Robinson <g.branden.robinson@gmail.com>
-
- * pdfmark.am (PDFROFF): Call pdfroff without
- `--keep-temporary-files` option. Temporary directories are
- created with mktemp(1) and files with an embedded process
- identifier, which frustrates reproducible builds.
-
- See <https://savannah.gnu.org/bugs/?57218>.
-
-2018-02-28 Werner LEMBERG <wl@gnu.org>
-
- * pdfmark.am (pdfmark.pdf): Use $(GROFF_V).
-
-2018-02-28 Werner LEMBERG <wl@gnu.org>
-
- * pdfmark.am (pdfroff): Use $(AM_V_GEN) to silence file generation.
-
-2015-08-22 Bernd Warken <groff-bernd.warken-72@web.de>
-
- * pdfroff.1.man: Rename `pdfroff.man'.
-
- * pdfmark.am: Add `Last update'. Setup Emacs mode.
-
-2015-08-05 Bernd Warken <groff-bernd.warken-72@web.de>
-
- * pdfmark.am: Add `Last update'. Setup Emacs mode.
-
-2015-04-03 Werner LEMBERG <wl@gnu.org>
-
- * pdfroff.man: Make it work in compatibility mode.
-
-2014-10-14 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Deduce "--no-toc-relocation" from input stream (revisited).
-
- * pdfroff.sh (WRKFILE): Correct malformed sed expression.
-
- * spdf.tmac (TC): Prefer value of pdfroff's PHASE register to defined
- state of pdf:href.map, when choosing to emit control record to...
- (toc_relocation): ...enable this.
-
-2014-10-13 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Deduce "--no-toc-relocation" from input stream.
-
- * pdfroff.sh (WRKFILE): Scan it for "pdfroff-option:set" records;
- apply settings; check for equivalent of "--no-toc-relocation" option.
-
- * spdf.tmac (TC): Emit "pdfroff-option:set toc-relocation=enabled".
-
-2014-10-12 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Avoid spurious user visible control messages on stderr.
-
- * pdfroff.sh (REFCOPY): Ensure that at least one pdfhref mark of type
- 'Z' will remain in the reference map, after all references have been
- resolved; this is required, to suppress writing of reference control
- records to stderr during the final PDF output processing phase.
-
-2014-09-04 Bernd Warken <groff-bernd.warken-72@web.de>
-
- * all pdfmark source files: Copying (remove last updates and
- replace years with package years) and Emacs setup.
-
-2014-03-30 Steffen Nurpmeso <sdaoden@yandex.com>
-
- * Makefile.sub: Put straight error-prevention prefixes for `rm'.
-
-2014-03-29 Steffen Nurpmeso <sdaoden@yandex.com>
-
- * Makefile.sub: Handle examples separately, controlled by
- $(make{_,_install_,_uninstall_}examples).
-
-2013-01-28 Deri James <deri@chuzzlewit.myzen.co.uk>
-
- * pdfmark.tmac (pdfmark, pdf:composed): Use `\!' instead of `\X'.
-
- With the old pdfmark there are gaps between two of the lines, but
- with the new version they disappear. The use of `.br' and `.in 0'
- is arbitrary any request which causes an implicit break could be
- used. Two breaks together only produce one line break, but if there
- is an intervening `\X' then the second break finds the line buffer
- not empty and generates another line break.
-
- Using `\!' does alter the position of the pdfmark lines in the
- intermediate file sent to grops (the pdfmark lines are output
- immediately rather than being serialised through the output line
- processing), but this has no effect since the contents of the
- pdfmark line stay the same. It is the contents which determine
- where bookmarks jump to not the position of the record in the input
- stream to grops.
-
- I initially used `.output', but hit a snag if a pdfbookmark occurs
- before the document starts to output (message saying to insert an
- explicit `.br'), this is quite likely for things like `.pdfinfo
- /Author' which occur at the top of the document. So I'm using the
- `\!' escape.
-
-2012-09-20 Werner LEMBERG <wl@gnu.org>
-
- Simplify enviroment handling.
-
- Suggested by Ivan Shmakov <oneingray@gmail.com>.
-
- * Makefile.sub (PDFROFF): Don't use export.
-
-2011-12-26 Mike Frysinger <vapier@gentoo.org>
-
- Fix parallel build race failure.
-
- Sometimes building in parallel will fail in the pdfmark directory:
-
- make[2]: Entering directory '.../contrib/pdfmark'
- rm -f pdfroff
- rm -f pdfmark.pdf
- sed -f ... ./pdfroff.sh >pdfroff
- ...; ./pdfroff ... pdfmark.ms >pdfmark.pdf
- /bin/sh: ./pdfroff: Permission denied
- chmod +x pdfroff
- make[2]: *** [pdfmark.pdf] Error 126
-
- This is because the generated pdf files use the local generated
- pdfroff helper script, but they don't depend directly upon it, so
- make tries to create the two in parallel and randomly falls over.
-
- * Makefile.sub: Have all the .pdf files explicitly depend on the
- `pdfroff' helper script.
-
-2010-12-23 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Update copyright notices; pdfmark.tmac bug-fix.
-
- * pdfmark.tmac: Update copyright notices.
- (pdf*href.mark.resolve): Avoid premature removal, by aliasing to...
- (pdf*href.mark.begin): ...this, rather than renaming.
-
- * pdfroff.sh, pdfroff.man: Update copyright notices.
-
-2010-12-14 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Clean up handling of temporary files directory.
-
- * .cvsignore (pdfroff-*): Ignore sub-directories matching this.
- * Makefile.sub (MOSTLCLEANDIRADD): Schedule them for removal.
-
-2010-12-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Address potential temporary file security vulnerabilities.
-
- * pdfroff.sh (GROFF_TMPDIR): Use mktemp(1) to assign it, if possible;
- fall back to ${TMPDIR}, ${TMP} or ${TEMP} if unsuccessful.
- * pdfroff.man: Document it.
-
-2009-08-16 Colin Watson <cjwatson@debian.org>
-
- Make pdfroff's GhostScript invocation safer.
-
- * pdfroff.sh (PDFROFF_POSTPROCESSOR_COMMAND): Add `-dSAFER' option.
- * pdfroff.man: Document it.
-
-2008-12-28 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Avoid phantom line wrapping in pdfhref hot-spots.
-
- * pdfmark.tmac (pdf*href.mark.end): Emit hot-spot end markers within
- scope of `\Z', to prevent possible output line length overflow which
- may occur only in the layout computation passes, but not in the final
- output pass. Problem observed and identified by Nick Stoughton; it
- causes some hot-spots to be displaced from their proper locations.
-
-2007-04-11 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Avoid stray newlines in folded pdfmark literal content.
-
- * pdfmark.tmac (pdf*pdfmark.dispatch.wrapped): New string; define it
- when accumulating long literal content; make it undefined otherwise.
- (PDFMARK.FOLDWIDTH, PDFMARK.FOLDWIDTH.MAX): Reserve space for two
- extra characters, to accommodate a space and an escaped newline,
- while accumulating literal content, in case folding is required.
- (pdf*pdfmark.dispatch) [pdf*pdfmark.dispatch.wrapped]: Add them.
-
-2007-04-11 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfmark.tmac (pdfbookmark): Don't evaluate within diversions; defer
- placement until diversion is copied out at top level.
-
-2007-02-06 Eric S. Raymond <esr@snark.thyrsus.com>
-
- * pdfroff.man: Update .UR/.UE and .MT/.ME to latest changes in
- an-ext.tmac.
-
-2007-01-30 Werner LEMBERG <wl@gnu.org>
-
- * pdfroff.man: Updated.
-
-2007-01-21 Werner LEMBERG <wl@gnu.org>
-
- * pdfroff.man: Revised, based on a patch from Eric Raymond. It now
- uses the new macros from an-ext.tmac. This is the first of a series
- of man patches which Eric has contributed.
-
-2006-07-30 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfroff.sh (PDFROFF_KILL_NULL_PAGES): Require `%%BeginPageSetup' on
- PostScript output line immediately following `%%Page:'.
-
-2006-07-29 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfroff.sh (PDFROFF_KILL_NULL_PAGES): Require `sed' to match a more
- explicit regular expression, for detection of redundant pages.
-
-2006-07-14 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfroff.sh (PDFWRITE): Local shell variable replaced...
- (PDFROFF_POSTPROCESSOR_COMMAND): by this new environment variable...
- (GROFF_GHOSTSCRIPT_INTERPRETER): with this bound to it.
- (PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES): New environment variables.
- (--no-kill-null-pages): New command line option; implement it, and...
- (--help): Add description for it.
-
- * pdfroff.man (PDFROFF_POSTPROCESSOR_COMMAND): Document it.
- (PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES): Document them.
- (--no-kill-null-pages): Document it.
-
-2006-07-14 Zvezdan Petkovic <zpetkovic@acm.org>
-
- * pdfroff.sh (--emit-ps): New command line option; implement it.
- (--help): Add description for it.
-
- * pdfroff.man (--emit-ps): Document it.
-
-2006-06-11 Werner LEMBERG <wl@gnu.org>
-
- * pdfroff.man: Add `.ig' block after NAME section to make mandb
- happy.
-
-2006-03-31 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Split `pdfmark' output as required, to avoid excessively long
- `ps:exec' intermediate output records.
-
- * pdfmark.tmac (pdfmark): Macro extended to deploy ...
- (pdf*pdfmark.limit): New macro; use it to define ...
- (PDFMARK.FOLDWIDTH, PDFMARK.FOLDWIDTH.MAX): New registers.
- (pdf*compose.first, pdf*compose.next, pdf*compose.literal): New
- macros; each will be aliased as required to ...
- (pdf*compose): ... this, to dynamically construct ...
- (pdf:composed.line, pdf:composed.literal): ... these new strings.
- (pdf:compose.test): New dynamically constructed string; use it to
- detect parenthesised literals in pdfmark content, so folding can be
- avoided within them, subject to honouring of `PDFMARK.FOLDWIDTH'.
- (pdf*length.increment): New macro; it triggers output folding when ...
- (pdf:length): ... this new register exceeds `PDFMARK.FOLDWIDTH.MAX'.
- (pdf*pdfmark.post.first, pdf*pdfmark.post.next): New macros; each will
- be aliased as required to ...
- (pdf*pdfmark.post): ... this, and invoked by ...
- (pdf*pdfmark.dispatch): ... this new macro; use it to define ...
- (pdf:composed): ... this dynamically constructed macro; use ...
- (pdf*end): ... this new macro to terminate it.
-
-2006-03-09 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Incorporate portability recommendations by Ralf Wildenhues
- <ralf.wildenhues@gmx.de>
-
- * pdfroff.sh: Avoid unsafe quoting in variable substitutions of
- the form "${VAR+"set"}"; remove outer quotes everywhere; prefix
- with `x' on each side of comparisons.
- ($NULLCMD): Define when `$ZSH_VERSION' is set, i.e. when host
- has `/bin/sh -> zsh'; also...
- (emulate sh): Invoke, for this case.
-
- Enhancement/bug fix requested by Werner LEMBERG <wl@gnu.org>
-
- * pdfroff.sh (--help): Direct output to `stdout', not `stderr'.
- (--keep-temporary-files): New option; implement it.
-
- * pdfroff.man (OPTIONS): Document `--keep-temporary-files' option.
- (FILES): Note names and purpose of files it affects.
-
- * Makefile.sub (PDFROFF): Add `--keep-temporary-files' option;
- retain them in `GROFF_TMPDIR=.'.
- (CLEANADD): Include temporary files matching `pdf[0-9]*'.
-
-2006-03-08 Werner LEMBERG <wl@gnu.org>
-
- * pdfmark.ms: Update URL for Adobe Reference Manual.
-
-2006-02-26 Claudio Fontana <claudio@gnu.org>
-
- * Makefile.sub: Add DESTDIR to install and uninstall targets
- to support staged installations.
-
-2006-02-25 Werner LEMBERG <wl@gnu.org>
-
- * pdfmark.ms: Correct typo; reported by Thomas Klausner.
-
-2006-02-24 Werner LEMBERG <wl@gnu.org>
-
- * pdfmark.ms, pdfroff.sh: Replace legal/illegal with valid/invalid.
-
-2005-06-22 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- pdfroff.sh portability enhancement.
-
- * pdfroff.sh (ARGLIST): Variable removed.
- (GROFF_STYLE): Use it for all groff invocations.
- (INPUT_FILES): Pass to all groff invocations, instead of ARGLIST.
- (CS_MACRO, CE_MACRO): Initialize independently.
- (CS_FILTER): Simplify quoting; it used to confuse some shells.
- (Source): CVS keyword removed; replaced by...
- (RCSfile, Revision): these.
-
-2005-06-17 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfroff.sh (MATCH): Correct quoting.
- (Source): Add terminating `$' on CVS keyword.
-
-2005-06-17 Zvezdan Petkovic <zpetkovic@acm.org>
-
- * Makefile.sub: (RM): Define as `rm -f', for `make' programs
- which don't predefine it.
-
-2005-06-16 Bernd Warken <groff-bernd.warken-72@web.de>
-
- * pdfroff.sh (NULLDEV): Correct misspelled instance of NULDEV.
-
-2005-05-28 Werner LEMBERG <wl@gnu.org>
-
- * Makefile.sub (.ms.pdf): Use `--stylesheet', not `--style'.
-
-2005-05-26 Werner LEMBERG <wl@gnu.org>
-
- * Makefile.sub, pdfmark.tmac, pdfroff.sh, spdf.tmac: Update postal
- address for Free Software Foundation.
-
-2005-05-17 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Improve portability of `pdfroff' shell script.
-
- * pdfroff.sh: Add space in shebang, conforming to portability
- guidelines in `autoconf' docs.
- (searchpath): New shell function; use it instead of `type' command
- to locate prerequisite helper programs.
-
- * pdfroff.man: Document influence of `OSTYPE' and `PATH_SEPARATOR'
- environment variables.
-
- * Makefile.sub (pdfroff): Make it depend on SH_DEPS_SED_SCRIPT,
- from arch/misc/shdeps.sh; use it to customize PATH_SEPARATOR
- initialization code for `searchpath' function in pdfroff.sh.
-
-2005-05-16 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Interim documentation update.
-
- * pdfmark.ms (GROFF-WEBSITE): New string; use it in references and
- examples.
- (Section 2.5): Add definitions of D and Z operators, for use with
- pdfhref macro.
- (Section 2.5.4): Complete description of pdfhref macro usage for
- `Linking to Internet Resources'; provide examples.
-
-2005-05-14 Nick Stoughton <nick@usenix.org>
-
- * pdfmark.tmac (LB): Renamed to ...
- (PDFLB): This to avoid conflicts with mm's LB macro.
-
-2005-05-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Handle parsing anomalies in Cygwin's `ash', and similar, shells.
-
- * pdfroff.sh ($CAT, $GREP, $SED, $GROFF, $DIFF): Avoid interpreting
- misdirected error messages, which `type' sends to `stdout' in some
- shells, as a successful program file match.
-
- ($AWK, $GS): Likewise; also ensure that multiple choice match
- prototypes are eval'ed as such, in case token splitting occurs
- before variable expansion.
-
-2005-04-24 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Add support for folded outlines in PDF documents.
-
- * pdfmark.tmac (PDFOUTLINE.FOLDLEVEL): New register.
- (pdf:bm.emit): Use it.
-
- * pdfmark.ms: Document it.
-
-2005-03-25 Werner LEMBERG <wl@gnu.org>
-
- * Makefile.in: Removed.
-
-2005-03-24 Werner LEMBERG <wl@gnu.org>
-
- * Makefile: Renamed to...
- * Makefile.in: This.
-
-2005-03-22 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * pdfroff.sh: Eliminate invalid program reference to $AWK, when
- invoked with `--no-reference-dictionary' option.
-
-2005-03-02 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- * contrib/pdfmark/Makefile.sub (install_data): Use $(INSTALL_SCRIPT)
- to install `pdfroff'.
- * contrib/pdfmark/pdfroff.man (opte): New macro.
- Use it to remove spurious equal signs from SYNOPSIS.
-
-2005-02-28 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- Provide `pdfroff' shell script, and manpage to document it;
- runs multiple groff passes, to format PDF documents.
-
- * pdfroff.sh: New shell script template;
- * pdfroff.man: New man page to document it.
-
- Integrate `pdfmark' into normal groff build system;
- install macro `pdfmark' packages, build and install `pdfroff',
- and PDF format documentation.
-
- * Makefile.sub: Rewritten.
- * pdfmark.tmac: Modified.
- (pdfhref): New macro operators, `D' and `Z'.
- (pdf*href-D, pdf*href-Z): New macros: implement them.
- (pdf*href.mark.resolve, pdf*href.mark.emit, pdf*href.mark.flush):
- Modified macro algorithm, to eliminate inconsistencies between
- `grohtml' representations of `opminy' from differing groff versions.
- (pdf*href.mark, pdf*href.mark.release, pdf*href.mark.close):
- deleted (redundant macros).
- (PDFHREF.LEADING): Default value changed (was 2.5p; now -1.0p).
- Global comment updates.
-
- * TODO: Updated.
-
-2004-12-10 Werner LEMBERG <wl@gnu.org>
-
- * TODO: Updated.
-
-2004-12-08 Keith Marshall <keith.d.marshall@ntlworld.com>
-
- First import of pdfmark files.
-
-________________________________________________________________________
-
-Copyright (C) 2004-2020 Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
-
-Local Variables:
-fill-column: 72
-mode: change-log
-version-control: never
-End:
-vim:set autoindent textwidth=72:
diff --git a/contrib/pdfmark/PROBLEMS b/contrib/pdfmark/PROBLEMS
deleted file mode 100644
index d31be4a7b..000000000
--- a/contrib/pdfmark/PROBLEMS
+++ /dev/null
@@ -1,32 +0,0 @@
- -*- text -*-
- Copyright (C) 2004-2020 Free Software Foundation, Inc.
-
- Copying and distribution of this file, with or without modification,
- are permitted in any medium without royalty provided the copyright
- notice and this notice are preserved.
-
-Known PROBLEMS in pdfmark.tmac
-==============================
-
-Bounding boxes for link hot-spots which straddle a page break
-are not computed correctly.
-
-*** Resolved: 06-Dec-2004 (KDM): pdfmark.tmac.patch-20041206 ***
-
---------
-
-Documents including a large number of cross references may fail,
-with an 'input stack limit exceeded' error.
-
-*** Resolved: 27-Sep-2004 (KDM): pdfmark.tmac.patch-20040927 ***
-
---------
-
-Links placed in diversions, such as footnotes or floating keeps,
-resolve to the wrong destinations; (mapping order becomes confused
-between links in diversion, and links in running text following
-the diversion).
-
---------
-
-Annotations placed by .pdfnote cannot exceed about 200 chars.
diff --git a/contrib/pdfmark/README b/contrib/pdfmark/README
deleted file mode 100644
index 7440ffdad..000000000
--- a/contrib/pdfmark/README
+++ /dev/null
@@ -1,57 +0,0 @@
- -*- text -*-
- Copyright (C) 2004-2020 Free Software Foundation, Inc.
-
- Copying and distribution of this file, with or without modification,
- are permitted in any medium without royalty provided the copyright
- notice and this notice are preserved.
-
-README for pdfmark.tmac
-=======================
-
-Copyright (C) 2004, 2009 Free Software Foundation Inc.
-Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
-
-This is free software. See file COPYING, for copying permissions,
-and warranty disclaimer.
-
-This is a preview release of a proposed pdfmark.tmac macro package,
-for use with GNU troff (groff). It is not yet complete, and should
-be considered as an alpha release; there are a few problems to be
-resolved (see file PROBLEMS).
-
-Partial documentation is provided, in groff-ms format. To convert
-this to PDF format, you will require a working groff installation,
-a working ghostscript installation, with the gs command in your PATH,
-and a GNU-compatible make. The tarball should be unpacked in the
-top directory of your groff source tree, then:
-
- cd <groff-current>/contrib/pdfmark
- make pdfmark
-
-where <groff-current> is the top directory of your current groff
-source tree.
-
-Included in this package, are:
-
- pdfmark.tmac -- the core pdfmark macro set
- spdf.tmac -- a rudimentary set of bindings for ms macros
- pdfmark.ms -- preliminary documentation
- cover.ms -- a template for the documentation cover sheet
- gnu.eps -- the groff logo, copied from the groff distribution
- Makefile -- makefile, for formatting the documentation
- README -- this file
- PROBLEMS -- a list of known problems
- TODO -- a list of planned features, not yet implemented
-
-To make the pdfmark macros generally usable, copy pdfmark.tmac to the
-'site-tmac' directory appropriate to your groff installation; (ms users
-may also wish to copy spdf.tmac). The macros may then be accessed, by
-including the '-mpdfmark' option on the groff command line; (for ms
-users, '-mspdf' is equivalent to '-ms -mpdfmark', with some extra
-macros 'thrown in').
-
-Comments, and bug reports are welcomed. Please post to the groff
-mailing list, groff@gnu.org; (you must be subscribed to this list to
-post mails). To subscribe, visit
-
- http://lists.gnu.org/mailman/listinfo/groff
diff --git a/contrib/pdfmark/TODO b/contrib/pdfmark/TODO
deleted file mode 100644
index 219b60e30..000000000
--- a/contrib/pdfmark/TODO
+++ /dev/null
@@ -1,60 +0,0 @@
- -*- text -*-
- Copyright 2004-2020 Free Software Foundation, Inc.
-
- Copying and distribution of this file, with or without modification,
- are permitted in any medium without royalty provided the copyright
- notice and this notice are preserved.
-
-TODO items for pdfmark.tmac
-===========================
-
-Add copyright information to PDF documentation.
-
---------
-
-Add acknowledgements and trade mark ownership notifications
-to PDF documentation.
-
---------
-
-Provide documentation in man page and texinfo formats.
-
---------
-
-Add comments in spdf.tmac, to clarify its operation.
-Also add commentary in pdfmark.tmac, to clarify operation of
-recent changes.
-
---------
-
-Make Makefile generic, so 'configure' can resolve target
-system dependencies.
-
-* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
-
-If this refers to contrib/pdfmark/Makefile, then it is addressed by the new
-'pdfroff' script; the original Makefile may be considered redundant. Local
-system dependencies are resolved by 'configure', and applied to 'pdfroff',
-when it is generated from 'pdfroff.sh'.
-
---------
-
-Improve Makefile.sub, to integrate pdfmark.tmac installation
-into a regular groff build. Add it to groff's Makefile.in.
-
-* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
-
-Completed.
-
---------
-
-Provide a 'pdfmark' script (or call it 'groff2pdf'?) which
-actually converts a groff input file to pdf, and which
-takes care of the necessary intermediate steps to handle
-PDF marks.
-
-* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
-
-This facility now provided by 'pdfroff' script; documented in 'pdfroff.man'.
-Man page still requires an additional section, to describe use of 'stylesheet'
-feature. Script also requires documentation in PDF and texinfo formats.
diff --git a/contrib/pdfmark/cover.ms b/contrib/pdfmark/cover.ms
deleted file mode 100644
index b647a29a3..000000000
--- a/contrib/pdfmark/cover.ms
+++ /dev/null
@@ -1,70 +0,0 @@
-.\" Copyright (C) 2004-2020 Free Software Foundation, Inc.
-.\"
-.\" Copying and distribution of this file, with or without modification,
-.\" are permitted in any medium without royalty provided the copyright
-.\" notice and this notice are preserved.
-.\"
-.am pspic*error-hook
-. ab \\n[.F]:\\n[.c]: fatal error: PSPIC failed to include '\\$1'
-..
-.de CS
-.if !rCO .nr CO 0
-.if !rTL .nr TL 0
-.\".nr PO*SAVED \\n[PO]
-.nr LL*SAVED \\n[LL]
-.nr HM*SAVED \\n[HM]
-.nr HM 0
-.nr PO (2.1c+\\n[CO]u)
-.nr LL 17.1c
-\&
-.nr PS*SAVED \\n[PS]
-.nr VS*SAVED \\n[VS]
-.nr PS 24
-.nr VS 30
-.CD
-.fam T
-.sp |(5.9c+\\n[TL]u)
-.als AU au@first
-..
-.de au@first
-.sp 1.5v
-.als AU au@next
-.AU \\$@
-..
-.de au@next
-.DE
-.nr PS 18
-.nr VS 18
-.CD
-.sp 0.5v
-\\$*
-..
-.de AI
-\H'-4z'\\$*\H'0'
-..
-.de CE
-.DE
-.sp |17.5c
-.PSPIC gnu.eps
-.nr PS 19
-.CD
-.fam H
-.tkf HR 10z 2p 20z 4p
-\H'-4z'A GNU MANUAL\H'0'
-.DE
-.\".nr PO \\n[PO*SAVED]
-.nr LL \\n[LL*SAVED]
-.nr PS \\n[PS*SAVED]
-.nr VS \\n[VS*SAVED]
-.nr HM \\n[HM*SAVED]
-.\".rr PO*SAVED
-.rr LL*SAVED
-.rr PS*SAVED
-.rr VS*SAVED
-.rr HM*SAVED
-.fam
-..
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-.\" vim: filetype=groff:
diff --git a/contrib/pdfmark/pdfmark.am b/contrib/pdfmark/pdfmark.am
deleted file mode 100644
index 781c900c1..000000000
--- a/contrib/pdfmark/pdfmark.am
+++ /dev/null
@@ -1,100 +0,0 @@
-# Copyright (C) 2005-2021 Free Software Foundation, Inc.
-# Written by Keith Marshall (keith.d.marshall@ntlworld.com)
-# Automake migration by Bertrand Garrigues
-#
-# 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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.
-
-pdfmark_srcdir = $(top_srcdir)/contrib/pdfmark
-pdfmark_builddir = $(top_builddir)/contrib/pdfmark
-
-man1_MANS += contrib/pdfmark/pdfroff.1
-
-bin_SCRIPTS += pdfroff
-
-# Files installed in $(tmacdir)
-TMACFILES = \
- contrib/pdfmark/pdfmark.tmac \
- contrib/pdfmark/sanitize.tmac \
- contrib/pdfmark/spdf.tmac
-pdfmarktmacdir = $(tmacdir)
-dist_pdfmarktmac_DATA = $(TMACFILES)
-
-# Files installed in $(pdfdocdir)
-PDFDOCFILES = \
- contrib/pdfmark/pdfmark.pdf
-if USE_PDFROFF
-pdfmarkpdfdocdir = $(pdfdocdir)
-nodist_pdfmarkpdfdoc_DATA = $(PDFDOCFILES)
-MOSTLYCLEANFILES += $(PDFDOCFILES)
-else
-EXTRA_DIST += $(PDFDOCFILES)
-endif
-
-EXTRA_DIST += \
- contrib/pdfmark/cover.ms \
- contrib/pdfmark/pdfmark.ms \
- contrib/pdfmark/ChangeLog \
- contrib/pdfmark/README \
- contrib/pdfmark/PROBLEMS \
- contrib/pdfmark/TODO \
- contrib/pdfmark/pdfroff.1.man \
- contrib/pdfmark/pdfroff.sh
-
-PDFROFF=\
- GROFF_TMPDIR=. \
- GROFF_COMMAND_PREFIX= \
- GROFF_BIN_DIR="$(GROFF_BIN_DIR)" \
- GROFF_BIN_PATH="$(GROFF_BIN_PATH)" \
- ./pdfroff \
- $(FFLAG) $(MFLAG) -dpaper=$(PAGE) -P-p$(PAGE) -M$(pdfmark_srcdir)
-
-contrib/pdfmark/pdfmark.pdf: contrib/pdfmark/pdfmark.ms \
- $(TMAC_PACKAGE_MS) tmac/pspic.tmac
- $(GROFF_V)$(MKDIR_P) `dirname $@` \
- && $(PDFROFF) -I $(doc_builddir) -I $(doc_srcdir) -mspdf \
- --stylesheet=$(pdfmark_srcdir)/cover.ms \
- $(top_srcdir)/contrib/pdfmark/pdfmark.ms >$@
-
-# The pdf files use the local script to generate.
-$(PDFDOCFILES): pdfroff groff troff gropdf
-$(PDFDOCFILES): $(dist_devpsfont_DATA) $(nodist_devpsfont_DATA) \
- $(DOC_GNU_EPS)
-
-pdfroff: contrib/pdfmark/pdfroff.sh $(SH_DEPS_SED_SCRIPT)
- $(AM_V_GEN)sed -f $(SH_DEPS_SED_SCRIPT) \
- -e "s|[@]VERSION[@]|$(VERSION)|" \
- -e "s|[@]GROFF_AWK_INTERPRETERS[@]|$(ALT_AWK_PROGS)|" \
- -e
"s|[@]GROFF_GHOSTSCRIPT_INTERPRETERS[@]|$(ALT_GHOSTSCRIPT_PROGS)|" \
- -e "s|[@]GROFF_BIN_DIR[@]|$(bindir)|" $(pdfmark_srcdir)/pdfroff.sh \
- >$@ \
- && chmod +x $@
-
-mostlyclean-local: mostlyclean_pdfmark
-mostlyclean_pdfmark:
- rm -rf $(top_builddir)/pdfroff-*
-
-uninstall_groffdirs: uninstall-pdfmark-hook
-uninstall-pdfmark-hook:
-if USE_PDFROFF
- -rmdir $(DESTDIR)$(pdfmarkpdfdocdir)
-endif
-
-
-# Local Variables:
-# mode: makefile-automake
-# fill-column: 72
-# End:
-# vim: set autoindent filetype=automake textwidth=72:
diff --git a/contrib/pdfmark/pdfmark.ms b/contrib/pdfmark/pdfmark.ms
deleted file mode 100644
index 343f1be5e..000000000
--- a/contrib/pdfmark/pdfmark.ms
+++ /dev/null
@@ -1,2831 +0,0 @@
-.ig
-pdfmark.ms
-
-This file is part of groff, the GNU roff type-setting system.
-
-Copyright (C) 2004-2021 Free Software Foundation, Inc.
-written by Keith Marshall <keith.d.marshall@ntlworld.com>
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts.
-
-A copy of the Free Documentation License is included as a file called
-FDL in the main directory of the groff source package.
-..
-.
-.CS
-Portable Document Format
-Publishing with GNU Troff
-.AU Keith Marshall
-.AI <keith.d.marshall@ntlworld.com>
-.CE
-.
-.\" Specify the Internet address for the groff web site.
-.\"
-.ds GROFF-WEBSITE http://www.gnu.org/software/groff
-.
-.\" Set the PDF default document view attribute, to ensure that the document
-.\" outline is visible, each time the document is opened in Acrobat Reader.
-.\"
-.pdfview /PageMode /UseOutlines
-.\"
-.\" Initialize the outline view to show only three heading levels,
-.\" with additional subordinate level headings folded.
-.\"
-.nr PDFOUTLINE.FOLDLEVEL 3
-.
-.\" Add document identification meta-data
-.\"
-.pdfinfo /Title Portable Document Format Publishing with GNU Troff
-.pdfinfo /Author Keith Marshall
-.pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU
Troff
-.pdfinfo /Keywords groff troff PDF pdfmark
-.
-.\" Set the default cross reference format to indicate section numbers,
-.\" rather than page numbers, when we insert a reference pointer.
-.\"
-.ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
-.
-.\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
-.\"
-.de XR-NO-PREFIX
-.rn PDFHREF.PREFIX xx
-.ds PDFHREF.PREFIX
-.XR \\$@
-.rn xx PDFHREF.PREFIX
-..
-.
-.\" Define a string, to insert a Registered Trade Mark symbol as
-.\" a superscript...
-.\"
-.ds rg \*{\(rg\*}
-.\"
-.\" ...and use it to define strings, representing frequently used
-.\" registered trade marks.
-.\"
-.ds Adobe "Adobe\Z'\\$1'\*(rg\"
-.ds Acrobat "Acrobat\Z'\\$1'\*(rg\"
-.ds Distiller "Distiller\Z'\\$1'\*(rg\"
-.ds PostScript "PostScript\Z'\\$1'\*(rg\"
-.\"
-.ds Microsoft "Microsoft\Z'\\$1'\*(rg\"
-.
-.\" Establish the page layout.
-.\"
-.nr PO 2.5c
-.nr LL 17.0c
-.nr LT 17.0c
-.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
-.
-.
-.\" Implement an interface with the FS macro (from s.tmac) to facilitate
-.\" placement of footnote reference marks, with each serving as an active
-.\" pdfhref link to the associated footnote itself.
-.\"
-.de pdf:fn.mark nr
-.\" Macro to replace original duty performed by "\**"; must be invoked
-.\" at point of footnote mark placement, e.g. by FS, BEFORE recording of
-.\" the associated text within the footnote diversion is commenced.
-.\"
-.ie \\n[.$] \{\
-. pdfhref L -D pdf:fn\\$1 -- \\$2
-. pdfhref M -N pdf:fn\\$1r
-. \}
-.\"
-.\" s.tmac does not publicly expose its auto-incrementing footnote index;
-.\" to avoid a dependency on an undocumented internal feature, we create
-.\" our own counter, while keeping the internal index synchronized, by
-.\" interpolating a renamed "\**", each time we increment our counter.
-.\"
-.el .\\$0 \\n+[pdf:fn.index.count] \\*[pdf:fn.index]
-.nr pdf:fn.index.count 0 1
-.rn * pdf:fn.index
-.ds * \c
-.
-.\" For versions of s.tmac which support the FS-MARK callback hook, it
-.\" is sufficient for us to answer the callback request.
-.\"
-.\" FIXME: in time, we may be able to unconditionally assume that this
-.\" callback hook will be supported...
-.\"
-.ie d FS-MARK .als FS-MARK pdf:fn.mark
-.el \{\
-.\" ...but in the interim, we may need to redefine s.tmac's FS macro,
-.\" (actually the @FS internal macro, rather than FS itself), to gain
-.\" an effect equivalent to taking control of FS-MARK, to achieve the
-.\" placement of a footnote mark as an active pdfhref link.
-.\"
-.rn @FS pdf:fn.record
-.de @FS
-.pdf:fn.mark
-.pdf:fn.record
-..
-.\}
-.\" Override s.tmac's (undocumented) footnote output hook; this emulates
-.\" the default output style for \n[FF] == 3 footnotes, with the footnote
-.\" number formatted as a pdfhref link back to the position at which the
-.\" footnote marker appears, within the document text.
-.\"
-.de FP
-.LP
-.nr pdf:fn.tag.width (u;2*\\n[FI])
-.ds pdf:fn.tag \s'-1.5p'\\$1.\s'+1.5p'
-.pdfhref M -N pdf:fn\\$1
-.in +\\n[pdf:fn.tag.width]u
-.ti -\\n[pdf:fn.tag.width]u
-.nr pdf:fn.tag.width -\\w'\\*[pdf:fn.tag]'u
-.pdfhref L -D pdf:fn\\$1r -A \\h'\\n[pdf:fn.tag.width]u'\c -- \\*[pdf:fn.tag]
-..
-.de pdfhref-nobreak
-.\" FIXME: I've only noticed this anomaly when planting pdfhref links
-.\" within footnotes; if the start of the link text is placed near the
-.\" line length limit, and all of it is moved to the start of the next
-.\" line, the "hot-spot" region is computed to be one line higher than
-.\" it should be; ending the preceding input line with "\c", and then
-.\" invoking pdfhref via this wrapper, works around this issue.
-.\"
-.ie \\n[.l]-\\n[.i]-\\n[.k]-\\w'\\$\\n[.$]' \&
-.el \p
-.pdfhref \\$*
-..
-.
-.\" Define a local macro to facilitate choice of style for emphasis;
-.\" by default, make it equivalent to the ms standard "I" macro.
-.\"
-.de EM
-.\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
-.I \\$@
-..
-.\" Also, define variations on the ms standard "CW" macro, to add
-.\" bold, italic, and both styles to constant width text; note that
-.\" each of these accept two additional arguments, in comparison to
-.\" standard "CW", such that \$1 specifies the text which is to be
-.\" styled, \$2 and \$3 specify inner after/before bracketting, to
-.\" set as regular "CW" text, while \$4 and \$5 become equivalent
-.\" to \$2 and \$3 of standard "CW", acting as outer bracketting.
-.\"
-.de CWB
-\\$5\f(CR\\$3\fP\f(CB\\$1\fP\f(CR\\$2\fP\\$4
-..
-.de CWI
-\\$5\f(CR\\$3\fP\f(CI\\$1\fP\f(CR\\$2\fP\\$4
-..
-.de CWBI
-\\$5\f(CR\\$3\fP\f[CBI]\\$1\fP\f(CR\\$2\fP\\$4
-..
-.\" Finally, augment this group with a variant string, which may be
-.\" used to set constant width tags on "IP" paragraphs, with \$1 set
-.\" as if by "CWB", followed by an optional suffix set as if by "CWBI",
-.\" and with the suffix bracketted by \$3 after and \$4 before, each
-.\" set in the regular "CW" style.
-.\"
-.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
-.
-.\" Additionally, add a cross-reference convenience macro, emulating
-.\" the style of the "ms" font change macros...
-.\"
-.\" .XR <dest-name> [<affixed> [<prefix>]]
-.\"
-.\" ...such that, when invoked with one, two, or three arguments, this
-.\" expands to the equivalent of:
-.\"
-.\" .pdfhref L -D <dest-name> [-A <affixed> [-P <prefix>]]
-.\"
-.\" to place a pdfhref reference link, to a named destination, within
-.\" the same document, using the reference text which is predefined in
-.\" the reference dictionary entry associated with the destination.
-.\"
-.de XR
-.if \\n(.$ \{\
-. if \\n[OPMODE] \{\
-. ds xr!argv -D "\\$1"
-. if \\n(.$>1 .as xr!argv " -A "\\$2"
-. if \\n(.$>2 .as xr!argv " -P "\\$3"
-. pdfhref L \\*[xr!argv]
-. rm xr!argv
-. \}
-. \}
-..
-.
-.NH 1
-.\" Conventionally, in "ms", NH precedes text which is to be set as a
-.\" numbered section heading, but it makes no provision for automatic
-.\" reference to that heading in a table of contents, or (in the case
-.\" of PDF document production) in a document outline. Both of these
-.\" limitations may be mitigated, by using the XN macro, (provided by
-.\" spdf.tmac), which sets its arguments, both as text to be included
-.\" in the section heading, as printed, and as an assocated document
-.\" outline reference; it will also make this same text available to
-.\" 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:
-.\"
-.\" .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...
-. \"
-. 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.
-. \"
-. shift 2
-. nop \h'1.5n'\\$*\h'0.5n'
-. XE
-..
-.XN Introduction
-.\"
-.\" If using an old s.tmac, without the SN-NO-DOT extension, ensure
-.\" that we get SOMETHING in section number references.
-.\"
-.if !d SN-NO-DOT .als SN-NO-DOT SN
-.LP
-It might appear that it is a fairly simple matter to
-produce documents in \*[Adobe]\~\(lqPortable\~Document\~Format\(rq,
-commonly known as PDF, using
-.CW groff ) GNU\~Troff\~(
-as the document formatter.
-Indeed,
-.CW groff 's
-default output format is the native \*[Adobe]\~\*[PostScript] format,
-which PDF producers such as \*[Adobe] \*[Acrobat] \*[Distiller ,]
-or GhostScript, expect as their input format.
-Thus, the PDF production process would seem to entail simply
-formatting the document source with
-.CW groff ,
-to produce a \*[PostScript] version of the document,
-which can subsequently be processed by \*[Acrobat] \*[Distiller]
-or GhostScript, to generate the final PDF document.
-.LP
-For many PDF production requirements,
-the production cycle described above may be sufficient.
-However, this is a limited PDF production method,
-in which the resultant PDF document represents no more than
-an on screen image of the printed form of the document, if
-.CW groff 's
-\*[PostScript] output were printed directly.
-.LP
-The Portable Document Format provides a number of features,
-which significantly enhance the experience of reading a document on screen,
-but which are of little or no value to a document which is merely printed.
-It
-.EM is
-possible to exploit these PDF features, which are described in the \*[Adobe]
-.de pdfmark-manual pdfmark-manual
-.\" This is an example of a resource reference specified by URI ...
-.\" We may need to refer often to the Adobe pdfmark Reference Manual,
-.\" so we create the internet link definition using a macro, to make
-.\" it reusable.
-.\"
-.\" Note also, that we protect the description of the reference by
-.\" preceding it with "--", to avoid "invalid character in name" type
-.\" error messages from groff (caused by the use of "\~").
-.\"
-.pdfhref W -D https://www.adobe.com/go/acrobatsdk_pdfmark \
- -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
-.pdfmark-manual ,
-with some refinement of the simple PDF production method, provided
-appropriate \(lqfeature implementing\(rq instructions can be embedded into
-.CW groff 's
-\*[PostScript] rendering of the document.
-This, of course, implies that the original document source, which
-.CW groff
-will process to generate the \*[PostScript] description of the document,
-must include appropriate markup to exploit the desired PDF features.
-It is this preparation of the
-.CW groff
-document source to exploit a number of these features,
-which provides the principal focus of this document.
-.LP
-The markup techniques to be described have been utilized in the production of
-the PDF version of this document itself.
-This has been formatted using
-.CW groff 's
-.CW ms
-macro package;
-thus, usage examples may be found in the document source file,
-.CW \n(.F ,
-to which comments have been added,
-to help identify appropriate markup examples for implementing PDF features,
-such as:\(en
-.QS
-.IP \(bu
-Selecting a default document view, which defines how the document will appear
-when opened in the reader application; for example, when this document is
-opened in \*[Acrobat]\~Reader, it should display the top of the cover sheet,
-in the document view pane, while a document outline should appear to the left,
-in the \(lqBookmarks\(rq pane.
-.IP \(bu
-Adding document identification \(lqmeta\(hydata\(rq,
-which can be accessed, in \*[Acrobat]\~Reader,
-by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
-.IP \(bu
-Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
-pane of \*[Acrobat]\~Reader, such that readers may quickly navigate to any
-section of the document, simply by clicking on the associated heading
-in the outline view.
-.IP \(bu
-Embedding active links in the body of the document, such that readers may
-quickly navigate to related material at another location within the same
-document, or in another PDF document, or even to a related Internet resource,
-specified by its URI.
-.IP \(bu
-Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
-points within the PDF document.
-.QE
-.LP
-All of the techniques described have been tested on
-.EM both
-GNU/Linux, and on \*[Microsoft] Windows\(tm2000 operating platforms, using
-.CW groff
-.CW 1.19.1 ,\**
-.FS
-Later versions should, and some earlier versions may, be equally suitable.
-See\c
-.pdfhref-nobreak W \*[GROFF-WEBSITE]
-for information and availability of the latest version.
-.FE
-in association with
-.CW AFPL
-.CW GhostScript
-.CW 8.14 .\**
-.FS
-Again, other versions may be suitable.
-See\c
-.pdfhref-nobreak W http://ghostscript.com
-for information and availability.
-.FE
-\&
-Other tools employed, which should be readily available on
-.EM any
-Unix\(tm
-or GNU/Linux system, are
-.CW sed ,
-.CW awk
-and
-.CW make ,
-together with an appropriate text editor, for creating and marking up the
-.CW groff
-input files.
-These additional utilities are not provided, as standard,
-on the \*[Microsoft] Windows\(tm platform,
-but several third party implementations are available.
-Some worth considering include the MKS\*(rg\~Toolkit,\**
-.FS
-A commercial offering; see\c
-.pdfhref-nobreak W http://mkssoftware.com/products/tk/default.asp
-for information.
-.FE
-Cygwin,\**
-.FS
-A
-.EM free
-but comprehensive
-.SM
-POSIX
-.LG
-emulation environment and
-Unix\(tm
-toolkit for \%32\(hybit \*[Microsoft] Windows\(tm platforms; see\c
-.pdfhref-nobreak W http://cygwin.com
-for information and download.
-.FE
-or MSYS.\**
-.FS
-Another free, but minimal suite of common
-Unix\(tm
-tools for \%32\(hybit \*[Microsoft] Windows\(tm, available for download from\c
-.pdfhref-nobreak W -A ; https://mingw.osdn.io
-it
-.EM does
-include those tools listed above,
-and is the package which was actually used when performing the Windows\(tm2000
-platform tests referred to in the text.
-.FE
-\&
-This list is by no means exhaustive, and should in no way be construed as an
-endorsement of any of these packages, nor to imply that other similar packages,
-which may be available, are in any way inferior to them.
-.bp
-.
-.NH 1
-.\" We may wish a section heading to represent a named destination,
-.\" so that we can create a linked reference to it, from some other
-.\" part of the PDF document, (or even from another PDF document).
-.\"
-.\" Here we use the "-N" option of the "XN" macro, to create a named
-.\" PDF link destination, at the location of the heading. Notice that
-.\" we also use the "--" marker to separate the heading text from the
-.\" preceding option specification; it is not strictly necessary in
-.\" this case, but it does help to set off the heading text from the
-.\" option specification.
-.\"
-.XN -N pdf-features -- Exploiting PDF Document Features
-.LP
-To establish a consistent framework for adding PDF features, a
-.CW groff
-macro package, named
-.CW pdfmark.tmac ,
-has been provided.
-Thus, to incorporate PDF features in a document,
-the appropriate macro calls, as described below, may be placed in the
-.CW groff
-document source, which should then be processed with a
-.CW groff
-command of the form\**
-.FS
-.pdfhref M pdf-features-fn
-.nr pdf-features-fn \n[fn*text-num]
-Note that,
-if any
-.CW -T \^\c
-.CWI dev
-option is specified,
-it should be either
-.CW -T \^\c
-.CW ps ,
-or
-.CW -T \^\c
-.CW pdf ;
-any other explicit choice is unlikely to be compatible with
-.CW -m \|\|\c
-.CW pdfmark ,
-and will have an unpredictable
-(possibly erroneous)
-effect on the output.
-If no
-.CW -T \^\c
-.CWI dev
-option is specified,
-(in which case
-.CW -T \^\c
-.CW ps
-is implicitly assumed),
-or if
-.CW -T \^\c
-.CW ps
-is explicitly specified,
-then the output will be produced in \*[PostScript] format,
-and will require conversion to PDF,
-(e.g. by using GhostScript tools);
-explicit specification of
-.CW -T \^\c
-.CW pdf
-will result in direct output in PDF format,
-thus obviating the need for conversion.
-.FE
-.QP
-.fam C
-groff [-Tps\h'0.2p'|\h'0.2p'-Tpdf] [-m\F[]\|\|\FC\c
-.I name ]
--m\F[]\|\|\FC\c
-.B pdfmark
-.I options \F[]\|\|\FC\c [-
-.I file \F[]\|\|\FC\c "...] "
-\&...
-.LP
-It may be noted that the
-.CW pdfmark
-macros have no dependencies on, and no known conflicts with,
-any other
-.CW groff
-macro package; thus, users are free to use any other macro package,
-of their choice, to format their documents, while also using the
-.CW pdfmark
-macros to add PDF features.
-.
-.NH 2
-.XN -S -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
-.LP
-All PDF features are implemented by embedding instances of the
-.B \F[C]pdfmark\F[]
-operator, as described in the \*[Adobe]
-.pdfmark-manual ,
-into
-.CW groff 's
-\*[PostScript] output stream.
-To facilitate the use of this operator, the
-.CW pdfmark
-macro package defines the primitive
-.CW pdfmark
-macro; it simply emits its argument list,
-as arguments to a
-.CW pdfmark
-operator, in the \*[PostScript] output stream.
-.LP
-.pdfhref M -N pdfmark-example
-To illustrate the use of the
-.CW pdfmark
-macro, the following is a much simplified example of how a bookmark
-may be added to a PDF document outline
-.QP
-.CW ".pdfmark \e"
-.RS 4
-.nf
-.fam C
-/Count 2 \e
-/Title (An Example of a Bookmark with Two Children) \e
-/View [/FitH \en[PDFPAGE.Y]] \e
-/OUT
-.RE
-.LP
-In general, users should rarely need to use the
-.CW pdfmark
-macro directly.
-In particular, the above example is too simple for general use; it
-.EM will
-create a bookmark, but it does
-.EM not
-address the issues of setting the proper value for the
-.CW /Count
-key, nor of computing the
-.CW PDFPAGE.Y
-value used in the
-.CW /View
-key. The
-.CW pdfmark
-macro package includes a more robust mechanism for creating bookmarks,
-.\"
-.\" Here is an example of how a local reference may be planted,
-.\" using the automatic formatting feature of the "pdfhref" macro.
-.\"
-.\" This is a forward reference to the named destination "add-outline",
-.\" which is defined below, using the "XN" wrapper macro, from the
-.\" "spdf.tmac" macro package. The automatically formatted reference
-.\" will be enclosed in parentheses, as specified by the use of
-.\" "-P" and "-A" options.
-.\"
-.pdfhref L -P ( -A ), -D add-outline
-.\"
-which addresses these issues automatically.
-Nevertheless, the
-.CW pdfmark
-macro may be useful to users wishing to implement more advanced PDF features,
-than those currently supported directly by the
-.CW pdfmark
-macro package.
-.
-.NH 2
-.XN -N docview -- Selecting an Initial Document View
-.LP
-By default,
-when a PDF document is opened,
-the first page will be displayed,
-at the default magnification set for the reader,
-and outline and thumbnail views will be hidden.
-When using a PDF reader,
-such as \*[Acrobat]\~Reader,
-which supports the
-.CW /DOCVIEW
-class of the
-.CW pdfmark
-operator,
-these default initial view settings may be overridden,
-using the
-.CW pdfview
-macro.
-For example
-.QP
-.CW ".pdfview /PageMode /UseOutlines"
-.LP
-will cause \*[Acrobat]\~Reader to open the document outline view,
-to the left of the normal page view,
-while
-.QP
-.CW ".pdfview /PageMode /UseThumbs"
-.LP
-will open the thumbnail view instead.
-.LP
-Note that the two
-.CW /PageMode
-examples, above, are mutually exclusive \(em it is not possible to have
-.EM both
-outline and thumbnail views open simultaneously.
-However, it
-.EM is
-permitted to add
-.CW /Page
-and
-.CW /View
-keys, to force the document to open at a page other than the first,
-or to change the magnification at which the document is initially displayed;
-see the
-.pdfmark-manual
-for more information.
-.LP
-It should be noted that the view controlling meta\(hydata, defined by the
-.CW pdfview
-macro, is not written immediately to the \*[PostScript] output stream,
-but is stored in an internal meta\(hydata \(lqcache\(rq,
-(simply implemented as a
-.CW groff
-diversion).
-This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
-.CW pdfsync
-macro,
-.\"
-.\" Here is another example of how we may introduce a forward reference.
-.\" This time we are using the shorter notation afforded by the "XR" macro
-.\" provided by "spdf.tmac"; this example is equivalent to the native
-.\" "pdfmark.tmac" form
-.\" .pdfhref L -D pdfsync -P ( -A ).
-.\"
-.XR pdfsync ). (
-.
-.NH 2
-.XN -N docinfo -- Adding Document Identification Meta-Data
-.LP
-In addition to the
-.CW /DOCVIEW
-class of meta\(hydata described above,
-.XR docview ), (
-we may also wish to include document identification meta\(hydata,
-which belongs to the PDF
-.CW /DOCINFO
-class.
-.LP
-To do this, we use the
-.CW pdfinfo
-macro.
-As an example of how it is used,
-the identification meta\(hydata attached to this document
-was specified using a macro sequence similar to:\(en
-.DS I
-.CW
-\&.pdfinfo /Title PDF Document Publishing with GNU Troff
-\&.pdfinfo /Author Keith Marshall
-\&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff
-\&.pdfinfo /Keywords groff troff PDF pdfmark
-.DE
-Notice that the
-.CW pdfinfo
-macro is repeated, once for each
-.CW /DOCINFO
-record to be placed in the document.
-In each case, the first argument is the name of the applicable
-.CW /DOCINFO
-key, which
-.EM must
-be named with an initial solidus character;
-all additional arguments are collected together,
-to define the value to be associated with the specified key.
-.LP
-As is the case with the
-.CW pdfview
-macro,
-.XR docview ), (
-the
-.CW /DOCINFO
-records specified with the
-.CW pdfinfo
-macro are not immediately written to the \*[PostScript] output stream;
-they are stored in the same meta\(hydata cache as
-.CW /DOCVIEW
-specifications, until this cache is explicitly flushed,
-by invoking the
-.CW pdfsync
-macro,
-.XR pdfsync ). (
-.
-.NH 2
-.XN -N add-outline -- Creating a Document Outline
-.LP
-A PDF document outline comprises a table of references,
-to \(lqbookmarked\(rq locations within the document.
-When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
-such as \*[Adobe] \*[Acrobat] Reader,
-this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
-or \(lqBookmarks\(rq pane, to the left of the main document view.
-Individual references in the outline view may then be selected,
-by clicking with the mouse,
-to jump directly to the associated marked location in the document view.
-.LP
-The document outline may be considered as a collection of \(lqhypertext\(rq
-references to \(lqbookmarked\(rq locations within the document.
-The
-.CW pdfmark
-macro package provides a single generalized macro,
-.CW pdfhref ,
-for creating and linking to \(lqhypertext\(rq reference marks.
-This macro will be described more comprehensively in a later section,
-.XR pdfhref ); (
-the description here is restricted to its use for defining document outline
entries.
-.
-.NH 3
-.XN -N basic-outline -- A Basic Document Outline
-.LP
-In its most basic form, the document outline comprises a structured list of
headings,
-each associated with a marked location, or \(lqbookmark\(rq, in the document
text,
-and a specification for how that marked location should be displayed,
-when this bookmark is selected.
-.LP
-To create a PDF bookmark, the
-.CW pdfhref
-macro is used,
-at the point in the document where the bookmark is to be placed,
-in the form
-.QP
-.fam C
-.B ".pdfhref O"
-.I level > <
-.I "descriptive text ..."
-.LP
-in which the reference class
-.CWB O \& \& \(rq \(lq
-stipulates that this is an outline reference.
-.LP
-Alternatively, for those users who may prefer to think of a document outline
-simply as a collection of bookmarks, the
-.CW pdfbookmark
-macro is also provided \(em indeed,
-.CW pdfhref
-invokes it, when processing the
-.CWB O \& \& \(rq \(lq
-reference class operator.
-It may be invoked directly, in the form
-.QP
-.fam C
-.B .pdfbookmark
-.I level > <
-.I "descriptive text ..."
-.LP
-Irrespective of which of the above macro forms is employed, the
-.CWI level > <
-argument is required.
-It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
-in the outline hierarchy, with one being the topmost level.
-Its function may be considered analagous to the
-.EM "heading level"
-of the document's section headings,
-for example, as specified with the
-.CW NH
-macro, if using the
-.CW ms
-macros to format the document.
-.LP
-All further arguments, following the
-.CWI level > <
-argument, are collected together, to specify the heading text which will appear
-in the document's outline view.
-Thus, the outline entry for this section of this document,
-which has a level three heading,
-might be specified as
-.QP
-.CW
-\&.pdfhref O 3 \*(SN A Basic Document Outline
-.LP
-or, in the alternative form using the
-.CW pdfbookmark
-macro, as
-.QP
-.CW
-\&.pdfbookmark 3 \*(SN A Basic Document Outline
-.
-.NH 3
-.XN Hierarchical Structure in a Document Outline
-.LP
-When a document outline is created, using the
-.CW pdfhref
-macro as described in
-.\"
-.\" Here is an example of how we can temporarily modify the format of
-.\" a reference link, in this case to indicate only the section number
-.\" of the link target, in the form "section #", (or, if we define
-.\" "SECREF.BEGIN" before the call, its content followed by the
-.\" section number).
-.\"
-.\" We first define a macro, which will get the reference data from
-.\" pdfhref, as arguments, and will return the formatted output, as we
-.\" require it, the string "PDFHREF.TEXT".
-.\"
-.de SECREF
-.while \\n(.$ \{\
-. ie '\\$1'section' \{\
-. if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
-. ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
-. rm SECREF.BEGIN
-. shift \\n(.$
-. \}
-. el .shift
-. \}
-..
-.\" We now tell "pdfhref" to use our formatting macro, in place of
-.\" its builtin default formatter, before we specify the reference.
-.\"
-.pdfhref F SECREF
-.pdfhref L -A , -D basic-outline
-.\"
-.\" At this point, we would normally revert the "pdfhref" formatter
-.\" to use its default, built in macro. However, in this particular
-.\" case, we want to use our custom format one more time, before we
-.\" revert it, so we will omit the reversion step this time.
-.\"
-and any entry is added at a nesting level greater than one,
-then a hierarchical structure is automatically defined for the outline.
-However, as was noted in the simplified
-.pdfhref L -D pdfmark-example -- example
-in
-.pdfhref L -A , -D pdfmark-operator
-.\"
-.\" And now, we revert to default "pdfhref" formatting behaviour,
-.\" by completing the call we delayed above.
-.\"
-.pdfhref F
-.\"
-the data required by the
-.CW pdfmark
-operator to create the outline entry may not be fully defined,
-when the outline reference is defined in the
-.CW groff
-document source.
-Specifically, when the outline entry is created, its
-.CW /Count
-key must be assigned a value equal to the number of its subordinate entries,
-at the next inner level of the outline hierarchy;
-typically however,
-these subordinate entries will be defined
-.EM later
-in the document source, and the appropriate
-.CW /Count
-value will be unknown, when defining the parent entry.
-.LP
-To resolve this paradox, the
-.CW pdfhref
-macro creates the outline entry in two distinct phases \(em
-a destination marker is placed in the \*[PostScript] output stream immediately,
-when the outline reference is defined,
-but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
-until its subordinate hierarchy has been fully defined;
-it can then be inserted in the output stream, with its
-.CW /Count
-value correctly assigned.
-Effectively, to ensure integrity of the document outline structure,
-this means that each top level outline entry, and
-.EM all
-of its subordinates, are retained in the cache, until the
-.EM next
-top level entry is defined.
-.LP
-One potential problem, which arises from the use of the \(lqoutline cache\(rq,
-is that, at the end of any document formatting run, the last top level outline
entry,
-and any subordinates defined after it, will remain in the cache, and will
-.EM not
-be automatically written to the output stream.
-To avoid this problem, the user should follow the guidelines given in
-.\"
-.\" Here is a more conventional example of how to temporarily change
-.\" to the format used to display reference links. We will again use
-.\" the "SECREF" format, which we defined above, but on this occasion
-.\" we will immediately revert to the default format, after the link
-.\" has been placed.
-.\"
-.pdfhref F SECREF
-.pdfhref L -D pdfsync -A ,
-.pdfhref F
-.\"
-to synchronize the output state with the cache state,
-.XR pdfsync ), (
-at the end of the
-.CW groff
-formatting run.
-.
-.NH 3
-.XN -N outline-view -- Associating a Document View with an Outline Reference
-.LP
-Each \(lqbookmark\(rq entry, in a PDF document outline,
-is associated with a specific document view.
-When the reader selects any outline entry,
-the document view changes to display the document context
-associated with that entry.
-.LP
-The document view specification,
-to be associated with any document outline entry,
-is established at the time when the outline entry is created.
-However, rather than requiring that each individual use of the
-.CW pdhref
-macro, to create an outline entry,
-should include its own view specification,
-the actual specification assigned to each entry is derived from
-a generalized specification defined in the string
-.CW PDFBOOKMARK.VIEW ,
-together with the setting of the numeric register
-.CW PDFHREF.VIEW.LEADING ,
-which determine the effective view specification as follows:\(en
-.QS
-.IP \*[= PDFBOOKMARK.VIEW]
-Establishes the magnification at which the document will be viewed,
-at the location of the \(lqbookmark\(rq; by default, it is defined by
-.RS
-.QP
-.CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
-.RE
-.IP
-which displays the associated document view,
-with the \(lqbookmark\(rq location positioned at the top of the display window,
-and with the magnification set to fit the page width to the width of the
window.
-.IP \*[= PDFHREF.VIEW.LEADING]
-Specifies additional spacing,
-to be placed between the top of the display window
-and the actual location of the \(lqbookmark\(rq on the displayed page view.
-By default, it is set as
-.RS
-.QP
-.CW ".nr PDFHREF.VIEW.LEADING 5.0p"
-.RE
-.IP
-Note that
-.CW PDFHREF.VIEW.LEADING
-does not represent true \(lqleading\(rq, in the typographical sense,
-since any preceding text, set in the specified display space,
-will be visible at the top of the document viewing window,
-when the reference is selected.
-.IP
-Also note that the specification of
-.CW PDFHREF.VIEW.LEADING
-is shared by
-.EM all
-reference views defined by the
-.CW pdfhref
-macro; whereas
-.CW PDFBOOKMARK.VIEW
-is applied exclusively to outline references,
-there is no independent
-.CW PDFBOOKMARK.VIEW.LEADING
-specification.
-.QE
-.LP
-If desired, the view specification may be changed, by redefining the string
-.CW PDFBOOKMARK.VIEW ,
-and possibly also the numeric register
-.CW PDFHREF.VIEW.LEADING .
-Any alternative definition for
-.CW PDFBOOKMARK.VIEW
-.EM must
-be specified in terms of valid view specification parameters,
-as described in the \*[Adobe]
-.pdfmark-manual .
-.LP
-Note the use of the register
-.CW PDFPAGE.Y ,
-in the default definition of
-.CW PDFBOOKMARK.VIEW
-above.
-This register is computed by
-.CW pdfhref ,
-when creating an outline entry;
-it specifies the vertical position of the \(lqbookmark\(rq,
-in basic
-.CW groff
-units, relative to the
-.EM bottom
-edge of the document page on which it is defined,
-and is followed, in the
-.CW PDFBOOKMARK.VIEW
-definition, by the
-.CW grops
-.CW u \(rq \(lq
-operator, to convert it to \*[PostScript] units on output.
-It may be used in any redefined specification for
-.CW PDFBOOKMARK.VIEW ,
-(or in the analogous definition of
-.CW PDFHREF.VIEW ,
-described in
-'ne 2v
-.XR-NO-PREFIX pdfhref-view ),
-but
-.EM not
-in any other context,
-since its value is undefined outside the scope of the
-.CW pdfhref
-macro.
-.LP
-Since
-.CW PDFPAGE.Y
-is computed relative to the
-.EM bottom
-of the PDF output page,
-it is important to ensure that the page length specified to
-.CW troff
-correctly matches the size of the logical PDF page.
-This is most effectively ensured,
-by providing
-.EM identical
-page size specifications to
-.CW groff ,
-.CW grops
-and to the \*[PostScript] to PDF converter employed,
-and avoiding any page length changes within the document source.
-.LP
-Also note that
-.CW PDFPAGE.Y
-is the only automatically computed \(lqbookmark\(rq location parameter;
-if the user redefines
-.CW PDFBOOKMARK.VIEW ,
-and the modified view specification requires any other positional parameters,
-then the user
-.EM must
-ensure that these are computed
-.EM before
-invoking the
-.CW pdfhref
-macro.
-.
-.NH 3
-.XN -N outline-folding -- Folding the Outline to Conceal Less Significant
Headings
-.LP
-When a document incorporates many subheadings,
-at deeply nested levels,
-it may be desirable to \(lqfold\(rq the outline
-such that only the major heading levels are initially visible,
-yet making the inferior subheadings accessible,
-by allowing the reader to expand the view of any heading branch on demand.
-.LP
-The
-.CW pdfmark
-macros support this capability,
-through the setting of the
-.CW PDFOUTLINE.FOLDLEVEL
-register.
-This register should be set to the number of heading levels
-which it is desired to show in expanded form, in the
-.EM initial
-document outline display;
-all subheadings at deeper levels will still be added to the outline,
-but will not become visible until the outline branch containing them is
expanded.
-'ne 5
-For example, the setting used in this document:
-.QS
-.LD
-.fam C
-\&.\e" Initialize the outline view to show only three heading levels,
-\&.\e" with additional subordinate level headings folded.
-\&.\e"
-\&.nr PDFOUTLINE.FOLDLEVEL 3
-.DE
-.QE
-.LP
-results in only the first three levels of headings being displayed
-in the document outline,
-.EM until
-the reader chooses to expand the view,
-and so reveal the lower level headings in any outline branch.
-.LP
-The initial default setting of
-.CW PDFOUTLINE.FOLDLEVEL ,
-if the document author does not choose to change it,
-is 10,000.
-This is orders of magnitude greater than the maximum heading level
-which is likely to be used in any document;
-thus the default behaviour will be to show document outlines fully expanded,
-to display all headings defined,
-at all levels within each document.
-.LP
-The setting of
-.CW PDFOUTLINE.FOLDLEVEL
-may be changed at any time;
-however, the effect of each such change may be difficult to predict,
-since it is applied not only to outline entries which are defined
-.EM after
-the setting is changed,
-but also to any entries which remain in the outline cache,
-.EM at
-this time.
-Therefore, it is recommended that
-.CW PDFOUTLINE.FOLDLEVEL
-should be set
-.EM once ,
-at the start of each document;
-if it
-.EM is
-deemed necessary to change it at any other time,
-the outline cache should be flushed,
-.XR pdfsync ), (
-.EM immediately
-before the change,
-which should immediately preceed a level one heading.
-.
-.NH 3
-.XN -N multipart-outline -- Outlines for Multipart Documents
-.LP
-When a document outline is created, using the
-.CW pdfhref
-macro, each reference mark is automatically assigned a name,
-composed of a fixed stem followed by a serially generated numeric qualifier.
-This ensures that, for each single part document, every outline reference
-has a uniquely named destination.
-.LP
-As the overall size of the PDF document increases,
-it may become convenient to divide it into smaller,
-individually formatted \*[PostScript] components,
-which are then assembled, in the appropriate order,
-to create a composite PDF document.
-While this strategy may simplify the overall process of creating and
-editing larger documents, it does introduce a problem in creating
-an overall document outline,
-since each individual \*[PostScript] component will be assigned
-duplicated sequences of \(lqbookmark\(rq names,
-with each name ultimately referring to multiple locations in the composite
document.
-To avoid such reference naming conflicts, the
-.CW pdfhref
-macro allows the user to specify a \(lqtag\(rq,
-which is appended to the automatically generated \(lqbookmark\(rq name;
-this may be used as a discriminating mark, to distinguish otherwise
-similarly named destinations, in different sections of the composite document.
-.LP
-To create a \(lqtagged\(rq document outline,
-the syntax for invocation of the
-.CW pdfhref
-macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
-.EM before
-the nesting level argument, i.e.
-.QP
-.fam C
-.B ".pdfhref O"
-.B -T \& [
-.I tag >] <
-.I level > <
-.I "descriptive text ..."
-.LP
-The optional
-.CWI tag > <
-argument may be composed of any characters of the user's choice;
-however, its initial character
-.EM "must not"
-be any decimal digit, and ideally it should be kept short
-\(em one or two characters at most.
-.LP
-By employing a different tag in each section,
-the user can ensure that \(lqbookmark\(rq names remain unique,
-throughout all the sections of a composite document.
-For example, when using the
-.CW spdf.tmac
-macro package, which adds
-.CW pdfmark
-capabilities to the standard
-.CW ms
-package,
-.XR using-spdf ), (
-the table of contents is collected into a separate \*[PostScript] section
-from the main body of the document.
-In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
-but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
-.CW TC
-macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
-invoking the
-.CW pdfhref
-macro as
-.QP
-.CW ".pdfhref O -T T 1 \e\e*[TOC]"
-.LP
-to tag the associated outline destination name with the single character
suffix,
-.CW T \(rq. \(lq
-Alternatively, as in the case of the basic outline,
-.XR basic-outline ), (
-this may equally well be specified as
-.QP
-.CW ".pdfbookmark -T T 1 \e\e*[TOC]"
-.
-.NH 3
-.XN Delegation of the Outline Definition
-.LP
-Since the most common use of a document outline
-is to provide a quick method of navigating through a document,
-using active \(lqhypertext\(rq links to chapter and section headings,
-it may be convenient to delegate the responsibility of creating the outline
-to a higher level macro, which is itself used to
-define and format the section headings.
-This approach has been adopted in the
-.CW spdf.tmac
-package, to be described later,
-.XR using-spdf ). (
-.LP
-When such an approach is adopted,
-the user will rarely, if ever, invoke the
-.CW pdfhref
-macro directly, to create a document outline.
-For example, the structure and content of the outline for this document
-has been exclusively defined, using a combination of the
-.CW NH
-macro, from the
-.CW ms
-package, to establish the structure, and the
-.CW XN
-macro from
-.CW spdf.tmac ,
-to define the content.
-In this case,
-the responsibility for invoking the
-.CW pdfhref
-macro, to create the document outline,
-is delegated to the
-.CW XN
-macro.
-.
-.NH 2
-.XN -N pdfhref -- Adding Reference Marks and Links
-.LP
-.pdfhref F SECREF
-.ds SECREF.BEGIN Section
-.pdfhref L -D add-outline
-.pdfhref F
-has shown how the
-.CW pdfhref
-macro may be used to create a PDF document outline.
-While this is undoubtedly a powerful capability,
-it is by no means the only trick in the repertoire of this versatile macro.
-.LP
-The macro name,
-.CW pdfhref ,
-which is a contraction of \(lqPDF HyperText Reference\(rq,
-indicates that the general purpose of this macro is to define
-.EM any
-type of dynamic reference mark, within a PDF document.
-Its generalized usage syntax takes the form
-.QP
-.fam C
-.B .pdfhref
-.BI class > <
-.I "-options ...\&" ] [
-[--]
-.I "descriptive text ...\&" ] [
-.LP
-where
-.CW <\f(CIclass\fP>
-represents a required single character argument,
-which defines the specific reference operation to be performed,
-and may be selected from:\(en
-.QS
-.IP \*[= O]
-Add an entry to the document outline.
-This operation has been described earlier,
-.XR add-outline ). (
-.IP \*[= M]
-Place a \(lqnamed destination\(rq reference mark at the current output
position,
-in the current PDF document,
-.XR mark-dest ). (
-.IP \*[= D]
-Specify the content of a PDF document reference dictionary entry;
-typically, such entries are generated automatically,
-by transformation of the intermediate output resulting from the use of
-.CW pdfhref
-.CWB M \& \& \(rq, \(lq
-with the
-.CWB -X \& \& \(rq \(lq
-modifier,
-.XR create-map ); (
-however, it is also possible to specify such entries manually,
-.XR user-format ). (
-.IP \*[= L]
-Insert an active link to a named destination,
-.XR link-named ), (
-at the current output position in the current PDF document,
-such that when the reader clicks on the link text,
-the document view changes to show the location of the named destination.
-.IP \*[= W]
-Insert an active link to a \(lqweb\(rq resource,
-.XR add-weblink ), (
-at the current output position in the current PDF document.
-This is effectively the same as using the
-.CWB L \& \& \(rq \(lq
-operator to establish a link to a named destination in another PDF document,
-.XR link-extern ), (
-except that in this case, the destination is specified by a
-\(lquniform resource identifier\(rq, or
-.CW URI ;
-this may represent any Internet or local resource
-which can be specified in this manner.
-.IP \*[= F]
-Specify a user defined macro, to be called by
-.CW pdfhref ,
-when formatting the text in the active region of a link,
-.XR set-format ). (
-.IP \*[= Z]
-Define the absolute position on the physical PDF output page,
-where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
-Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
-for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
-specified directly by the user;
-rather, appropriate
-.CW pdfhref
-.CWB Z \& \& \(rq \(lq
-specifications are inserted automatically into the document reference map
-during the PDF document formatting process,
-.XR create-map ). (
-.IP \*[= I]
-Initialize support for
-.CW pdfhref
-features.
-The current
-.CW pdfhref
-implementation provides only one such feature which requires initialization
-\(em a helper macro which must be attached to a user supplied page trap
handler,
-in order to support mapping of reference \(lqhot\(hyspots\(rq
-which extend through a page transition;
-.XR page-trap ). (
-.QE
-.
-.NH 3
-.XN -S -- Optional Features of the \F[C]pdfhref\F[] Macro
-.LP
-The behaviour of a number of the
-.CW pdfhref
-macro operations can be modified,
-by including
-.EM "option specifiers" \(rq \(lq
-after the operation specifying argument,
-but
-.EM before
-any other arguments normally associated with the operation.
-In
-.EM all
-cases, an option is specified by an
-.EM "option flag" \(rq, \(lq
-comprising an initial hyphen,
-followed by one or two option identifying characters.
-Additionally,
-.EM some
-options require
-.EM "exactly one"
-option argument;
-for these options, the argument
-.EM must
-be specified, and it
-.EM must
-be separated from the preceding option flag by one or more
-.EM spaces ,
-(tabs
-.EM "must not"
-be used).
-It may be noted that this paradigm for specifying options
-is reminiscent of most
-Unix\(tm
-shells; however, in the case of the
-.CW pdfhref
-macro, omission of the space separating an option flag from its argument is
-.EM never
-permitted.
-.LP
-A list of
-.EM all
-general purpose options supported by the
-.CW pdfhref
-macro is given below.
-Note that not all options are supported for all
-.CW pdfhref
-operations; the operations affected by each option are noted in the list.
-For
-.EM most
-operations, if an unsupported option is specified,
-it will be silently ignored; however, this behaviour should
-not be relied upon.
-.LP
-The general purpose options, supported by the
-.CW pdfhref
-macro, are:\(en
-.QS
-.IP \*[= -N\0 name > <]
-Allows the
-.CWI name > <
-associated with a PDF reference destination
-to be defined independently from the following text,
-which describes the reference.
-This option affects only the
-.CWB M \& \& \(rq \(lq
-operation of the
-.CW pdfhref
-macro,
-.XR mark-dest ). (
-.IP \*[= -E]
-Also used exclusively with the
-.CWB M \& \& \(rq \(lq
-operator, the
-.CWB -E
-option causes any specified
-.CWI descriptive \& \& \~\c
-.CWI text
-arguments,
-.XR mark-dest ), (
-to be copied, or
-.EM echoed ,
-in the body text of the document,
-at the point where the reference mark is defined;
-(without the
-.CWB -E
-option, such
-.CWI descriptive \& \& \~\c
-.CWI text
-will appear
-.EM only
-at points where links to the reference mark are placed,
-and where the standard reference display format,
-.XR set-format ), (
-is used).
-.IP \*[= -D\0 dest > <]
-Specifies the
-.CW URI ,
-or the destination name associated with a PDF active link,
-independently of the following text,
-which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
-This option affects the behaviour of the
-.CW pdfhref
-macro's
-.CWB L \& \& \(rq \(lq
-and
-.CWB W \& \& \(rq \(lq
-operations.
-.IP
-When used with the
-.CWB L \& \& \(rq \(lq
-operator, the
-.CWI dest > <
-argument must specify a PDF \(lqnamed destination\(rq,
-as defined using
-.CW pdfhref
-with the
-.CWB M \& \& \(rq \(lq
-operator.
-.IP
-When used with the
-.CWB W \& \& \(rq \(lq
-operator,
-.CWI dest > <
-must specify a link destination in the form of a
-\(lquniform resource identifier\(rq, or
-.CW URI ,
-.XR add-weblink ). (
-.IP \*[= -F\0 file > <]
-When used with the
-.CWB L \& \& \(rq \(lq
-.CW pdfhref
-operator,
-.CWI file > <
-specifies an external PDF file in which the named destination
-for the link reference is defined.
-This option
-.EM must
-be specified with the
-.CWB L \& \& \(rq \(lq
-operator,
-to create a link to a destination in a different PDF document;
-when the
-.CWB L \& \& \(rq \(lq
-operator is used
-.EM without
-this option, the link destination is assumed to be defined
-within the same document.
-.IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
-Specifies
-.CWI \(dqprefix\(hytext\(dq > <
-to be attached to the
-.EM start
-of the text describing an active PDF document link,
-with no intervening space, but without itself being included in the
-active area of the link \(lqhot\(hyspot\(rq;
-it is effective with the
-.CWB L \& \& \(rq \(lq
-and
-.CWB W \& \& \(rq \(lq
-.CW pdfhref
-operators.
-.IP
-Typically, this option would be used to insert punctuation before
-the link \(lqhot\(hyspot\(rq.
-Thus, there is little reason for the inclusion of spaces in
-.CWI \(dqprefix\(hytext\(dq > < ;
-however, if such space is required, then the enclosing double quotes
-.EM must
-be specified, as indicated.
-.IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
-Specifies
-.CWI \(dqaffixed\(hytext\(dq > <
-to be attached to the
-.EM end
-of the text describing an active PDF document link,
-with no intervening space, but without itself being included in the
-active area of the link \(lqhot\(hyspot\(rq;
-it is effective with the
-.CWB L \& \& \(rq \(lq
-and
-.CWB W \& \& \(rq \(lq
-.CW pdfhref
-operators.
-.IP
-Typically, this option would be used to insert punctuation after
-the link \(lqhot\(hyspot\(rq.
-Thus, there is little reason for the inclusion of spaces in
-.CWI \(dqaffixed\(hytext\(dq > < ;
-however, if such space is required, then the enclosing double quotes
-.EM must
-be specified, as indicated.
-.IP \*[= -T\0 tag > <]
-When specified with the
-.CWB O \& \& \(rq \(lq
-operator,
-.CWI tag > <
-is appended to the \(lqbookmark\(rq name assigned to the generated outline
entry.
-This option is
-.EM required ,
-to distinguish between the series of \(lqbookmark\(rq names generated in
-individual passes of the
-.CW groff
-formatter, when the final PDF document is to be assembled
-from a number of separately formatted components;
-.XR multipart-outline ). (
-.IP \*[= -X]
-This
-.CW pdfhref
-option is used with either the
-.CWB M \& \& \(rq \(lq
-operator, or with the
-.CWB L \& \& \(rq \(lq
-operator.
-.IP
-When used with the
-.CWB M \& \& \(rq \(lq
-operator,
-.XR mark-dest ), (
-it ensures that a cross reference record for the marked destination
-will be included in the document reference map,
-.XR export-map ). (
-.IP
-When used with the
-.CWB L \& \& \(rq \(lq
-operator,
-.XR link-named ), (
-it causes the reference to be displayed in the standard cross reference format,
-.XR set-format ), (
-but substituting the
-.CWI descriptive \& \& \~\c
-.CWI text
-specified in the
-.CW pdfhref \& \(lq
-.CW L \(rq
-argument list,
-for the description specified in the document reference map.
-.IP \*[= --]
-Marks the end of the option specifiers.
-This may be used with all
-.CW pdfhref
-operations which accept options, to prevent
-.CW pdfhref
-from interpreting any following arguments as option specifiers,
-even if they would otherwise be interpreted as such.
-It is also useful when the argument list to
-.CW pdfhref
-contains special characters \(em any special character,
-which is not valid in a
-.CW groff
-macro name, will cause a parsing error, if
-.CW pdfhref
-attempts to match it as a possible option flag;
-using the
-.CW -- \(rq \(lq
-flag prevents this, so suppressing the
-.CW groff
-warning message, which would otherwise ensue.
-.IP
-Using this flag after
-.EM all
-sequences of macro options is recommended,
-even when it is not strictly necessary,
-if only for the entirely cosmetic benefit of visually separating
-the main argument list from the sequence of preceding options.
-.QE
-.LP
-In addition to the
-.CW pdfhref
-options listed above, a supplementary set of two character options are defined.
-These supplementary options, listed below, are intended for use with the
-.CWB L \& \& \(rq \(lq
-operator, in conjunction with the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option, to specify alternate file names,
-in formats compatible with the file naming conventions
-of alternate operating systems;
-they will be silently ignored, if used in any other context.
-.LP
-The supported alternate file name options,
-which are ignored if the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option is not specified, are:\(en
-.QS
-.IP \*[= -DF\0 dos\(hyfile > <]
-Specifies the name of the file in which a link destination is defined,
-using the file naming semantics of the
-.CW MS\(hyDOS \*(rg
-operating system.
-When the PDF document is read on a machine
-where the operating system uses the
-.CW MS\(hyDOS \*(rg
-file system, then
-.CWI dos\(hyfile > <
-is used as the name of the file containing the reference destination,
-overriding the
-.CWI file > <
-argument specified with the
-.CWB -F
-option.
-.IP \*[= -MF\0 mac\(hyfile > <]
-Specifies the name of the file in which a link destination is defined,
-using the file naming semantics of the
-.CW Apple \*(rg
-.CW Macintosh \*(rg
-operating system.
-When the PDF document is read on a machine
-where the operating system uses the
-.CW Macintosh \*(rg
-file system, then
-.CWI mac\(hyfile > <
-is used as the name of the file containing the reference destination,
-overriding the
-.CWI file > <
-argument specified with the
-.CWB -F
-option.
-.IP \*[= -UF\0 unix\(hyfile > <]
-Specifies the name of the file in which a link destination is defined,
-using the file naming semantics of the
-.CW Unix \(tm
-operating system.
-When the PDF document is read on a machine
-where the operating system uses
-.CW POSIX
-file naming semantics, then
-.CWI unix\(hyfile > <
-is used as the name of the file containing the reference destination,
-overriding the
-.CWI file > <
-argument specified with the
-.CWB -F
-option.
-.IP \*[= -WF\0 win\(hyfile > <]
-Specifies the name of the file in which a link destination is defined,
-using the file naming semantics of the
-.CW MS\(hyWindows \*(rg
-32\(hybit operating system.
-When the PDF document is read on a machine
-where the operating system uses any of the
-.CW MS\(hyWindows \*(rg
-file systems, with long file name support, then
-.CWI win\(hyfile > <
-is used as the name of the file containing the reference destination,
-overriding the
-.CWI file > <
-argument specified with the
-.CWB -F
-option.
-.QE
-.
-.NH 3
-.XN -N mark-dest -- Marking a Reference Destination
-.LP
-The
-.CW pdfhref
-macro may be used to create active links to any Internet resource,
-specified by its
-.CW URI ,
-or to any \(lqnamed destination\(rq,
-either within the same document, or in another PDF document.
-Although the PDF specification allows link destinations to be defined
-in terms of a page number, and an associated view specification,
-this style of reference is not currently supported by the
-.CW pdfhref
-macro, because it is not possible to adequately bind the specification
-for the destination with the intended reference context.
-.LP
-References to Internet resources are interpreted in accordance with the
-.CW W3C
-standard for defining a
-.CW URI ;
-hence the only prerequisite, for creating a link to any Internet resource,
-is that the
-.CW URI
-be properly specified, when declaring the reference;
-.XR add-weblink ). (
-In the case of references to \(lqnamed destinations\(rq in PDF documents,
-however, it is necessary to provide a mechanism for creating such
-\(lqnamed destinations\(rq.
-This may be accomplished, by invoking the
-.CW pdfhref
-macro in the form
-.QP
-.fam C
-.B ".pdfhref M"
-.B -N \& [
-.I name >] <
-.B -X ] [
-.B -E ] [
-.I "descriptive text ...\&" ] [
-.LP
-This creates a \(lqnamed destination\(rq reference mark, with its name
specified by
-.CWI name > < ,
-or, if the
-.CWB -N
-option is not specified, by the first word of
-.CWI descriptive \& \& \~\c
-.CWI text \& \& ;
-(note that this imposes the restriction that,
-if the
-.CWB -N
-option is omitted, then
-.EM "at least"
-one word of
-.CWI descriptive \& \& \~\c
-.CWI text
-.EM must
-be specified).
-Additionally, a reference view will be automatically defined,
-and associated with the reference mark,
-.XR pdfhref-view ), (
-.\" and, if any
-.\" .CWI descriptive
-.\" .CWI text
-.\" is specified, or the
-and, if the
-.CWB -X
-option is specified, and no document cross reference map has been imported,
-.XR import-map ), (
-then a cross reference mapping record,
-.XR export-map ), (
-will be written to the
-.CW stdout
-stream;
-this may be captured, and subsequently used to generate a cross reference map
-for the document,
-.XR create-map ). (
-.LP
-When a \(lqnamed destination\(rq reference mark is created, using the
-.CW pdfhref
-macro's
-.CWB M \& \& \(rq \(lq
-operator, there is normally no visible effect in the formatted document; any
-.CWI descriptive \& \& \~\c
-.CWI text
-which is specified will simply be stored in the cross reference map,
-for use when a link to the reference mark is created.
-This default behaviour may be changed, by specifying the
-.CWB -E
-option, which causes any specified
-.CWI descriptive \& \& \~\c
-.CWI text
-to be \(lqechoed\(rq in the document text,
-at the point where the reference mark is placed,
-in addition to its inclusion in the cross reference map.
-.
-.NH 4
-.XN -N export-map -- Mapping a Destination for Cross Referencing
-.LP
-Effective cross referencing of
-.EM any
-document formatted by
-.CW groff
-requires multiple pass formatting.
-Details of how this multiple pass formatting may be accomplished,
-when working with the
-.CW pdfmark
-macros, will be discussed later,
-.XR do-xref ); (
-at this stage, the discussion will be restricted to the initial preparation,
-which is required at the time when the cross reference destinations are
defined.
-.LP
-The first stage, in the process of cross referencing a document,
-is the generation of a cross reference map.
-Again, the details of
-.EM how
-the cross reference map is generated will be discussed in
-.pdfhref F SECREF L -D do-xref -A ;
-.pdfhref F
-however, it is important to recognize that
-.EM what
-content is included in the cross reference map is established
-when the reference destination is defined \(em it is derived
-from the reference data exported on the
-.CW stderr
-stream by the
-.CW pdfhref
-macro, when it is invoked with the
-.CWB M \& \& \(rq \(lq
-operator, and is controlled by whatever definition of the string
-.CW PDFHREF.INFO
-is in effect, when the
-.CW pdfhref
-macro is invoked.
-.LP
-The initial default setting of
-.CW PDFHREF.INFO
-is
-.QP
-.CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
-.LP
-which ensures that the cross reference map will contain
-at least a page number reference, supplemented by any
-.CWI descriptive \& \& \~\c
-.CWI text
-which is specified for the reference mark, as defined by the
-.CW pdfhref
-macro, with its
-.CWB M \& \& \(rq \(lq
-operator; this may be redefined by the user,
-to export additional cross reference information,
-or to modify the default format for cross reference links,
-.XR set-format ). (
-.
-.NH 4
-.XN -N pdfhref-view -- Associating a Document View with a Reference Mark
-.LP
-In the same manner as each document outline reference, defined by the
-.CW pdfhref
-macro with the
-.CWB O \& \& \(rq \(lq
-operator,
-.XR add-outline ), (
-has a specific document view associated with it,
-each reference destination marked by
-.CW pdfhref
-with the
-.CWB M \& \& \(rq \(lq
-operator, requires an associated document view specification.
-.LP
-The mechanism whereby a document view is associated with a reference mark
-is entirely analogous to that employed for outline references,
-.XR outline-view ), (
-except that the
-.CW PDFHREF.VIEW
-string specification is used, in place of the
-.CW PDFBOOKMARK.VIEW
-specification.
-Thus, the reference view is defined in terms of:\(en
-.QS
-.IP \*[= PDFHREF.VIEW]
-A string,
-establishing the position of the reference mark within the viewing window,
-and the magnification at which the document will be viewed,
-at the location of the marked reference destination;
-by default, it is defined by
-.RS
-.QP
-.CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
-.RE
-.IP
-which displays the reference destination at the top of the viewing window,
-with the magnification set to fit the page width to the width of the window.
-.IP \*[= PDFHREF.VIEW.LEADING]
-A numeric register,
-specifying additional spacing, to be placed between the top of the display
-window and the actual position at which the location of the reference
-destination appears within the window.
-This register is shared with the view specification for outline references,
-and thus has the same default initial setting,
-.RS
-.QP
-.CW ".nr PDFHREF.VIEW.LEADING 5.0p"
-.RE
-.IP
-as in the case of outline reference views.
-.IP
-Again, notice that
-.CW PDFHREF.VIEW.LEADING
-does not represent true typographic \(lqleading\(rq,
-since any preceding text, set in the specified display space,
-will be visible at the top of the viewing window,
-when the reference is selected.
-.QE
-.LP
-Just as the view associated with outline references may be changed,
-by redefining
-.CW PDFBOOKMARK.VIEW ,
-so the view associated with marked reference destinations may be changed,
-by redefining
-.CW PDFHREF.VIEW ,
-and, if desired,
-.CW PDFHREF.VIEW.LEADING ;
-such changes will become effective for all reference destinations marked
-.EM after
-these definitions are changed.
-(Notice that, since the specification of
-.CW PDFHREF.VIEW.LEADING
-is shared by both outline reference views and marked reference views,
-if it is changed, then the views for
-.EM both
-reference types are changed accordingly).
-.LP
-It may again be noted, that the
-.CW PDFPAGE.Y
-register is used in the definition of
-.CW PDFHREF.VIEW ,
-just as it is in the definition of
-.CW PDFBOOKMARK.VIEW ;
-all comments in
-.pdfhref F SECREF L -D outline-view
-.pdfhref F
-relating to its use, and indeed to page position computations in general,
-apply equally to marked reference views and to outline reference views.
-.
-.NH 3
-.XN -N link-named -- Linking to a Marked Reference Destination
-.LP
-Any named destination, such as those marked by the
-.CW pdfhref
-macro, using it's
-.CWB M \& \& \(rq \(lq
-operator, may be referred to from any point in
-.EM any
-PDF document, using an
-.EM "active link" ;
-such active links are created by again using the
-.CW pdfhref
-macro, but in this case, with the
-.CWB L \& \& \(rq \(lq
-operator.
-This operator provides support for two distinct cases,
-depending on whether the reference destination is defined in
-the same document as the link,
-.XR link-intern ), (
-or is defined as a named destination in a different PDF document,
-.XR link-extern ). (
-.
-.NH 4
-.XN -N link-intern -- References within a Single PDF Document
-.LP
-The general syntactic form for invoking the
-.CW pdfhref
-macro,
-when creating a link to a named destination within the same PDF document is
-.QP
-.fam C
-.B .pdfhref
-.B L
-.B -D \& [
-.BI dest-name >] <
-.B -P \& [
-.BI prefix-text >] <
-.B -A \& [
-.BI affixed-text >] <
-\e
-.br
-\0\0\0
-.B -X ] [
-.B -- ] [
-.I "descriptive text ...\&" ] [
-.LP
-where
-.CWI dest-name > <
-specifies the name of the link destination,
-as specified using the
-.CW pdfhref
-.CWB M \& \& \(rq \(lq
-operation; (it may be defined either earlier in the document,
-to create a backward reference, or later, to create a forward reference).
-.\"
-.\" Here's a example of how to add an iconic annotation.
-.\"
-.\".pdfnote -T "Internal Cross References" \
-.\" This description is rather terse, and could benefit from \
-.\" the inclusion of an example.
-.LP
-If any
-.CWI descriptive \& \& \~\c
-.CWI text
-arguments are specified, then they will be inserted into the
-.CW groff
-output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
-region of the link;
-this will be printed in the link colour specified by the string,
-.CW PDFHREF.TEXT.COLOUR ,
-which is described in
-.XR-NO-PREFIX set-colour .
-If the
-.CWB -X
-option is also specified, then the
-.CWI descriptive \& \& \~\c
-.CWI text
-will be augmented, by prefacing it with page and section number indicators,
-in accordance with the reference formatting rules which are in effect,
-.XR set-format ); (
-such indicators will be included within the active link region,
-and will also be printed in the link colour.
-.LP
-Note that
-.EM either
-the
-.CWB -D \& \& \~\c
-.CWBI dest\(hyname > <
-option,
-.EM or
-the
-.CWI descriptive \& \& \~\c
-.CWI text
-arguments,
-.EM "but not both" ,
-may be omitted.
-If the
-.CWB -D \& \& \~\c
-.CWBI dest\(hyname > <
-option is omitted, then the first word of
-.CWI descriptive \& \& \~\c
-.CWI text \& \& ,
-i.e.\~all text up to but not including the first space,
-will be interpreted as the
-.CWBI dest\(hyname > <
-for the link; this text will also appear in the running text of the document,
-within the active region of the link.
-Alternatively, if the
-.CWB -D \& \& \~\c
-.CWBI dest\(hyname > <
-option
-.EM is
-specified, and
-.CWI descriptive \& \& \~\c
-.CWI text
-is not,
-then the running text which defines the reference,
-and its active region,
-will be derived from the reference description which is specified
-when the named destination is marked,
-.XR mark-dest ), (
-and will be formatted according to the reference formatting rules
-which are in effect, when the reference is placed,
-.XR set-format ); (
-in this case, it is not necessary to specify the
-.CWB -X
-option to activate automatic formatting of the reference \(em it is implied,
-by the omission of all
-.CWI descriptive \& \& \~\c
-.CWI text
-arguments.
-.LP
-The
-.CWB -P \& \& \~\c
-.CWBI prefix\(hytext > <
-and
-.CWB -A \& \& \~\c
-.CWBI affixed\(hytext > <
-options may be used to specify additional text
-which will be placed before and after the linked text respectively,
-with no intervening space.
-Such prefixed and affixed text will be printed in the normal text colour,
-and will not be included within the active region of the link.
-This feature is mostly useful for creating parenthetical references,
-or for placing punctuation adjacent to,
-but not included within,
-the text which defines the active region of the link.
-.LP
-The operation of the
-.CW pdfhref
-macro, when used with its
-.CWB L \& \& \(rq \(lq
-operator to place a link to a named PDF destination,
-may best be illustrated by an example.
-However, since the appearance of the link will be influenced by
-factors established when the named destination is marked,
-.XR mark-dest ), (
-and also by the formatting rules in effect when the link is placed,
-the presentation of a suitable example will be deferred,
-until the formatting mechanism has been explained,
-.XR set-format ). (
-.
-.NH 4
-.XN -N link-extern -- References to Destinations in Other PDF Documents
-.LP
-The
-.CW pdfhref
-macro's
-.CWB L \& \& \(rq \(lq
-operator is not restricted to creating reference links
-within a single PDF document.
-When the link destination is defined in a different document,
-then the syntactic form for invoking
-.CW pdfhref
-is modified, by the addition of options to specify the
-name and location of the PDF file in which the destination is defined.
-Thus, the extended
-.CW pdfhref
-syntactic form becomes
-.QP
-.fam C
-.B .pdfhref
-.B L
-.B -F
-.BI file > <
-.B -D \& [
-.BI dest-name >] <
-\e
-.br
-\0\0\0
-.B -DF \& [
-.BI dos-file >] <
-.B -MF \& [
-.BI mac-file >] <
-.B -UF \& [
-.BI unix-file >] <
-\e
-.br
-\0\0\0
-.B -WF \& [
-.BI win-file >] <
-.B -P \& [
-.BI prefix-text >] <
-.B -A \& [
-.BI affixed-text >] <
-\e
-.br
-\0\0\0
-.B -X ] [
-.B -- ] [
-.I "descriptive text ...\&" ] [
-.LP
-where the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option serves
-.EM two
-purposes: it both indicates to the
-.CW pdfhref
-macro that the specified reference destination
-is defined in an external PDF file,
-and it also specifies the normal path name,
-which is to be used to locate this file,
-when a user selects the reference.
-.LP
-In addition to the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option, which
-.EM must
-be specified when referring to a destination in an external PDF file,
-the
-.CWB -DF \& \& \~\c
-.CWBI dos\(hyfile > < ,
-.CWB -MF \& \& \~\c
-.CWBI mac\(hyfile > < ,
-.CWB -UF \& \& \~\c
-.CWBI unix\(hyfile > <
-and
-.CWB -WF \& \& \~\c
-.CWBI win\(hyfile > <
-options may be used to specify the location of the file
-containing the reference destination,
-in a variety of operating system dependent formats.
-These options assign their arguments to the
-.CW /DosFile ,
-.CW /MacFile ,
-.CW /UnixFile
-and
-.CW /WinFile
-keys of the generated
-.CW pdfmark
-respectively; thus when any of these options are specified,
-.EM "in addition to"
-the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option, and the document is read on the appropriate operating systems,
-then the path names specified by
-.CWBI dos\(hyfile > < ,
-.CWBI mac\(hyfile > < ,
-.CWBI unix\(hyfile > <
-and
-.CWBI win\(hyfile > <
-will be searched,
-.EM instead
-of the path name specified by
-.CWBI file > < ,
-for each of the
-.CW MS\(hyDOS \*(rg,
-.CW Apple \*(rg
-.CW Macintosh \*(rg,
-.CW Unix \(tm
-and
-.CW MS\(hyWindows \*(rg
-operating systems, respectively; see the
-.pdfmark-manual ,
-for further details.
-.LP
-Other than the use of these additional options,
-which specify that the reference destination is in an external PDF file,
-the behaviour of the
-.CW pdfhref
-.CWB L \& \& \(rq \(lq
-operator, with the
-.CWB -F \& \& \~\c
-.CWBI file > <
-option, remains identical to its behaviour
-.EM without
-this option,
-.XR link-intern ), (
-with respect to the interpretation of other options,
-the handling of the
-.CWI descriptive \& \& \~\c
-.CWI text
-arguments, and the formatting of the displayed reference.
-.LP
-Once again, since the appearance of the reference is determined by
-factors specified in the document reference map,
-and also by the formatting rules in effect when the reference is placed,
-the presentation of an example of the placing of
-a reference to an external destination will be deferred,
-until the formatting mechanism has been explained,
-.XR set-format ). (
-.
-.NH 3
-.XN -N add-weblink -- Linking to Internet Resources
-.LP
-In addition to supporting the creation of cross references
-to named destinations in PDF documents, the
-.CW pdfhref
-macro also has the capability to create active links to Internet resources,
-or indeed to
-.EM any
-resource which may be specified by a Uniform Resource Identifier,
-(which is usually abbreviated to the acronym \(lqURI\(rq,
-and sometimes also referred to as a Uniform Resource Locator,
-or \(lqURL\(rq).
-.LP
-Since the mechanism for creating a link to a URI differs somewhat
-from that for creating PDF references, the
-.CW pdfhref
-macro is invoked with the
-.CWB W \& \& \(rq \(lq
-(for \(lqweb\(hylink\(rq) operator, rather than the
-.CWB L \& \& \(rq \(lq
-operator; nevertheless, the invocation syntax is similar, having the form
-.QP
-.fam C
-.B .pdfhref
-.B W
-.B -D \& [
-.BI URI >] <
-.B -P \& [
-.BI prefix-text >] <
-.B -A \& [
-.BI affixed-text >] <
-\e
-.br
-\0\0\0
-.B -- ] [
-.I "descriptive text ...\&"
-.LP
-where the optional
-.CWB -D
-.CWBI URI > <
-modifier specifies the address for the target Internet resource,
-in any appropriate
-.EM "Uniform Resource Identifier"
-format, while the
-.CWI descriptive
-.CWI text
-argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
-region, and the
-.CWB -P
-.CWBI prefix\(hytext > <
-and
-.CWB -A
-.CWBI affixed\(hytext > <
-options have the same effect as in the case of local document links,
-.XR link-intern ). (
-.LP
-Notice that it is not mandatory to include the
-.CWB -D
-.CWBI URI > <
-in the link specification; if it
-.EM is
-specified, then it is not necessary for the URI to appear,
-in the running text of the document \(em the
-.CWI descriptive
-.CWI text
-argument exactly defines the text
-which will appear within the \(lqhot\(hyspot\(rq region,
-and this need not include the URI.
-However, if the
-.CWB -D \& \& \~\c
-.CWBI URI > <
-specification is omitted, then the
-.CWI descriptive
-.CWI text
-argument
-.EM must
-be an
-.EM exact
-representation of the URI, which
-.EM will ,
-therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
-For example, we could introduce a reference to
-.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
-in which the actual URI is concealed, by using mark up such as:\(en
-.DS I
-.CW
-For example, we could introduce a reference to
-\&.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
-in which the actual URI is concealed,
-.DE
-Alternatively,
-to refer the reader to the groff web site,
-making it obvious that the appropriate URI is
-.pdfhref W -A , \*[GROFF-WEBSITE]
-the requisite mark up might be:\(en
-.DS I
-.CW
-to refer the reader to the groff web site,
-making it obvious that the appropriate URI is
-\&.pdfhref W -A , \*[GROFF-WEBSITE]
-the requisite mark up might be:\e(en
-.DE
-.
-.NH 3
-.XN -N set-format -- Establishing a Format for References
-.LP
-There are two principal aspects to be addressed,
-when defining the format to be used when displaying references.
-Firstly, it is desirable to provide a visual cue,
-to indicate that the text describing the reference is imbued
-with special properties \(em it is dynamically linked to the reference
-destination \(em and secondly, the textual content should
-describe where the link leads, and ideally,
-it should also describe the content of the reference destination.
-.LP
-The visual cue,
-that a text region defines a dynamically linked reference,
-is most commonly provided by printing the text within the active
-region in a distinctive colour.
-This technique will be employed automatically by the
-.CW pdfhref
-macro \(em
-.XR set-colour
-\(em unless the user specifically chooses to adopt, and implement,
-some alternative strategy.
-.
-.NH 4
-.XN -N set-colour -- Using Colour to Demarcate Link Regions
-.LP
-Typically, when a PDF document contains
-.EM active
-references to other locations, either within the same document,
-or even in other documents, or on the World Wide Web,
-it is usually desirable to make the regions
-where these active links are placed stand out from the surrounding text.
-.
-.NH 4
-.XN -N user-format -- Specifying Reference Text Explicitly
-.
-.NH 4
-.XN -N auto-format -- Using Automatically Formatted Reference Text
-.
-.NH 4
-.XN -N custom-format -- Customizing Automatically Formatted Reference Text
-.LP
-It is incumbent on the user,
-if employing automatic formatting of the displayed reference,
-.XR set-format ), (
-to ensure that an appropriate reference definition
-is created for the reference destination,
-and is included in the reference map for the document
-in which the reference will appear;
-thus, it may be easiest to
-.EM always
-use manual formatting for external references.
-.
-.NH 3
-.XN Problematic Links
-.LP
-Irrespective of whether a
-.CW pdfhref
-reference is placed using the
-.CWB L \& \& \(rq \(lq
-operator, or the
-.CWB W \& \& \(rq \(lq
-operator, there may be occasions when the resulting link
-does function as expected.
-A number of scenarios, which are known to be troublesome,
-are described below.
-.
-.NH 4
-.XN -N page-trap -- Links with a Page Transition in the Active Region
-.LP
-When a link is placed near the bottom of a page,
-it is possible that its active region, or \(lqhot\(hyspot\(rq,
-may extend on to the next page.
-In this situation, a page trap macro is required
-to intercept the page transition, and to restart the mapping of
-the \(lqhot\(hyspot\(rq boundary on the new page.
-.LP
-The
-.CW pdfmark
-macro package includes a suitable page trap macro, to satisfy this requirement.
-However, to avoid pre\(hyempting any other requirement the user may have for
-a page transition trap, this is
-.EM not
-installed as an active page trap,
-unless explicitly requested by the user.
-.LP
-To enable proper handling of page transitions,
-which occur within the active regions of reference links,
-the user should:\(en
-.QS
-.nr ITEM 0 1
-.IP \n+[ITEM].
-Define a page transition macro, to provide whatever features may be required,
-when a page transition occurs \(em e.g.\& printing footnotes,
-adding page footers and headers, etc.
-This macro should end by setting the output position at the correct
-vertical page offset, where the printing of running text is to restart,
-following the page transition.
-.IP \n+[ITEM].
-Plant a trap to invoke this macro, at the appropriate vertical position
-marking the end of normal running text on each page.
-.KS
-.IP \n+[ITEM].
-Initialize the
-.CW pdfhref
-hook into this page transition trap, by invoking
-.RS
-.IP
-.fam C
-.B "pdfhref I -PT"
-.BI macro-name > <
-.LP
-where
-.CWBI macro-name > <
-is the name of the user supplied page trap macro,
-to ensure that
-.CW pdfhref
-will correctly restart mapping of active link regions,
-at the start of each new page.
-.KE
-.RE
-.QE
-.LP
-It may be observed that this initialization of the
-.CW pdfhref
-page transition hook is, typically, required only once
-.EM before
-document formatting begins.
-Users of document formatting macro packages may reasonably expect that
-this initialization should be performed by the macro package itself.
-Thus, writers of such macro packages which include
-.CW pdfmark
-bindings, should provide appropriate initialization,
-so relieving the end user of this responsibility.
-The following example, abstracted from the sample
-.CW ms
-binding package,
-.CW spdf.tmac ,
-illustrates how this may be accomplished:\(en
-.DS I
-.CW
-\&.\e" groff "ms" provides the "pg@bottom" macro, which has already
-\&.\e" been installed as a page transition trap. To ensure proper
-\&.\e" mapping of "pdfhref" links which overflow the bottom of any
-\&.\e" page, we need to install the "pdfhref" page transition hook,
-\&.\e" as an addendum to this macro.
-\&.
-\&.pdfhref I -PT pg@bottom
-.DE
-.
-.NH 2
-.XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
-.
-.NH 2
-.XN -S -N pdfsync -- Synchronizing Output and \F[C]pdfmark\F[] Contexts
-.LP
-It has been noted previously, that the
-.CW pdfview
-macro,
-.XR docview ), (
-the
-.CW pdfinfo
-macro,
-.XR docinfo ), (
-and the
-.CW pdfhref
-macro, when used to create a document outline,
-.XR add-outline ), (
-do not immediately write their
-.CW pdfmark
-output to the \*[PostScript] data stream;
-instead, they cache their output, in a
-.CW groff
-diversion, in the case of the
-.CW pdfview
-and
-.CW pdfinfo
-macros, or in an ordered collection of strings and numeric registers,
-in the case of the document outline,
-until a more appropriate time for copying it out.
-In the case of
-.CW pdfview
-and
-.CW pdfinfo
-\(lqmeta\(hydata\(rq,
-this \(lqmore appropriate time\(rq is explicitly chosen by the user;
-in the case of document outline data,
-.EM some
-cached data may be implicitly written out as the document outline is compiled,
-but there will
-.EM always
-be some remaining data, which must be explicitly flushed out, before the
-.CW groff
-formatting process is allowed to complete.
-.LP
-To allow the user to choose when cached
-.CW pdfmark
-data is to be flushed to the output stream, the
-.CW pdfmark
-macro package provides the
-.CW pdfsync
-macro, (to synchronize the cache and output states).
-In its simplest form, it is invoked without arguments, i.e.
-.QP
-.fam C
-.B .pdfsync
-.LP
-This form of invocation ensures that
-.EM both
-the \(lqmeta\(hydata cache\(rq, containing
-.CW pdfview
-and
-.CW pdfinfo
-data,
-.EM and
-the \(lqoutline cache\(rq,
-containing any previously uncommitted document outline data,
-are flushed; ideally, this should be included in a
-.CW groff
-\(lqend macro\(rq, to ensure that
-.EM both
-caches are flushed, before
-.CW groff
-terminates.
-.LP
-Occasionally,
-it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
-without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
-at a user specified time, prior to reaching the end of the document.
-This may be accomplished, by invoking the
-.CW pdfsync
-macro with an argument, i.e.
-.QP
-.fam C
-.B ".pdfsync M"
-.LP
-to flush only the \(lqmeta\(hydata cache\(rq, or
-.QP
-.fam C
-.B ".pdfsync O"
-.LP
-to flush only the \(lqoutline cache\(rq.
-.LP
-The \(lqmeta\(hydata cache\(rq can normally be safely flushed
-in this manner, at any time
-.EM after
-output of the first page has started;
-(it may cause formatting problems,
-most notably the appearance of unwanted white space, if flushed earlier,
-or indeed, if flushed immediately after a page transition,
-but before the output of the content on the new page has commenced).
-Caution is required, however, when explicitly flushing the
-\(lqoutline cache\(rq, since if the outline is to be
-subsequently extended, then the first outline entry after flushing
-.EM must
-be specified at level 1.
-Nevertheless, such explicit flushing may occasionally be necessary;
-for example, the
-.CW TC
-macro in the
-.CW spdf.tmac
-package,
-.XR using-spdf ), (
-invokes
-.CW ".pdfsync\ O" \(rq \(lq
-to ensure that the outline for the \(lqbody\(rq section of the document
-is terminated,
-.EM before
-it commences the formatting of the table of contents section.
-.bp
-.
-.NH 1
-.XN -N pdf-layout -- PDF Document Layout
-.LP
-The
-.CW pdfmark
-macros described in the preceding section,
-.XR pdf-features ), (
-provide no inherent document formatting capability of their own.
-However,
-they may be used in conjunction with any other
-.CW groff
-macro package of the user's choice,
-to add such capability.
-.LP
-In preparing this document, the standard
-.CW ms
-macro package, supplied as a component of the GNU Troff distribution,
-has been employed.
-To facilitate the use of the
-.CW pdfmark
-macros with the
-.CW ms
-macros,
-a binding macro package,
-.CW spdf.tmac ,
-has been created.
-The use of this binding macro package is described in the following section,
-.XR using-spdf ); (
-it may also serve as an example to users of other standard
-.CW groff
-macro packages,
-as to how the
-.CW pdfmark
-macros may be employed with their chosen primary macro package.
-.
-.NH 2
-.XN -S -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[]
Macro Package
-.LP
-The use of the binding macro package,
-.CW spdf.tmac ,
-allows for the use of the
-.CW pdfmark
-macros in conjunction with the
-.CW ms
-macros,
-simply by issuing a
-.CW groff
-command of the form\**
-.FS
-Once again,
-.pdfhref L -D pdf-features-fn -- as noted in footnote\*{\n[pdf-features-fn]\*}
-to
-.XR-NO-PREFIX pdf-features ,
-do not specify any
-.CW -T \^\c
-.CWI dev
-option,
-other than
-.CW -T \^\c
-.CW ps ,
-or
-.CW -T \^\c
-.CW pdf ;
-specify
-.CW -T \^\c
-.CW pdf ,
-if you wish to avoid the conversion of \*[PostScript] output to PDF,
-which will be required if you specify
-.CW -T \^\c
-.CW ps ,
-or if you omit the
-.CW -T \^\c
-.CWI dev
-option entirely.
-.FE
-.QP
-.fam C
-groff [-Tps\h'0.2p'|\h'0.2p'-Tpdf] [-m\F[]\|\|\FC\c
-.B spdf
-.I options \F[]\|\|\FC\c [-
-.I file \F[]\|\|\FC\c "...] "
-\&...
-.LP
-When using the
-.CW spdf.tmac
-package, the
-.CW groff
-input files may be marked up using any of the standard
-.CW ms
-macros to specify document formatting,
-while PDF features may be added,
-using any of the
-.CW pdfmark
-macros described previously,
-.XR pdf-features ). (
-Additionally,
-.CW spdf.tmac
-defines a number of convenient extensions to the
-.CW ms
-macro set, to better accomodate the use of PDF features within the
-.CW ms
-formatting framework,
-and to address a number of
-.CW ms
-document layout issues,
-which require special handling when producing PDF documents.
-These additional macros,
-and the issues they are intended to address,
-are described below.
-.
-.NH 3
-.XN -S -- \F[C]ms\F[] Section Headings in PDF Documents
-.LP
-Traditionally,
-.CW ms
-provides the
-.CW NH
-and
-.CW SH
-macros, to specify section headings.
-However,
-there is no standard mechanism for generating a
-table of contents entry based on the text of the section heading;
-neither is there any recognized standard method for establishing a
-cross reference link to the section.
-.LP
-To address this
-.CW ms
-limitation,
-.CW spdf.tmac
-defines the
-.CW XN
-macro,
-.XR xn-macro ), (
-to be used in conjunction with the
-.CW NH
-macro.
-.
-.NH 4
-.XN -S -N xn-macro -- The \F[C]XN\F[] Macro
-.bp
-.
-.NH 1
-.XN The PDF Publishing Process
-.
-.NH 2
-.XN -N do-xref -- Resolving Cross References
-.
-.NH 3
-.XN -N create-map -- Creating a Document Reference Map
-.
-.NH 3
-.XN -N import-map -- Deploying a Document Reference Map
-.TC
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-.\" vim: filetype=groff:
diff --git a/contrib/pdfmark/pdfmark.tmac b/contrib/pdfmark/pdfmark.tmac
deleted file mode 100644
index 5f664f277..000000000
--- a/contrib/pdfmark/pdfmark.tmac
+++ /dev/null
@@ -1,1953 +0,0 @@
-.ig
-
-pdfmark.tmac
-
-Copyright (C) 2004-2020 Free Software Foundation, Inc.
- Written by Keith Marshall (keith.d.marshall@ntlworld.com)
-
-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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.
-
-Author's Note
-=============
-
-While I have written this macro package from scratch, much of my
-inspiration has come from discussion on the groff mailing list
-(mailto:groff@gnu.org). I am particularly indebted to:
-
- Kees Zeelenberg, for an earlier macro package he posted,
- a study of which helped me to get started.
-
- Carlos J. G. Duarte and Werner Lemberg, whose discussion
- on computation of the bounding boxes for link "hot-spots"
- forms the basis of such computations in this package.
-..
-.if !\n(.g .ab These pdfmark macros require groff.
-.\"
-.\" Check if we have already been loaded -- do not reload
-.if d pdfmark .nx
-.\"
-.\" ======================================================================
-.\" Module PDFMARK: Insert Arbitrary PDFMARK Code in the Postscript Stream
-.\" ======================================================================
-.\"
-.\" PDFMARK output may be disabled, by zeroing the PDFOPMODE register,
-.\" ( which mimics a more generic OPMODE, if it is defined ).
-.\"
-.if rOPMODE .aln PDFOPMODE OPMODE
-.\"
-.\" but if OPMODE wasn't defined,
-.\" then make the default PDFMARK mode ENABLED.
-.\"
-.if !rPDFOPMODE .nr PDFOPMODE 1
-.\"
-.\" PDFMARK output must be constrained to a maximum line length limit,
-.\" for strict compliance with the Postscript DSC. This limit is defined
-.\" in register "PDFMARK.FOLDWIDTH.MAX". This is user definable, up to a
-.\" ceiling value of 255, which is also its default value; this limit
-.\" is enforced for each PDFMARK, by macro "pdf*pdfmark.limit".
-.\"
-.de pdf*pdfmark.limit
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdf*pdfmark.limit REGISTER-NAME DEFAULT-MAXIMUM-VALUE
-.\" ----------------------------------------------------------------
-.\"
-.\" If a register named REGISTER-NAME has not been defined, then
-.\" define it now, with default value = DEFAULT-MAXIMUM-VALUE.
-.\"
-.if !r\\$1 .nr \\$1 \\$2
-.\"
-.\" But when it has already been defined, ensure that its value does
-.\" not exceed DEFAULT-MAXIMUM-VALUE; if value does exceed this ceiling,
-.\" then redefine it, to enforce the limit.
-.\"
-.if (\\n[\\$1] > \\$2) .nr \\$1 \\$2
-..
-.\" The "pdfmark" macro is responsible for emitting the appropriate
-.\" Postscript code.
-.\"
-.de pdfmark
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdfmark text of pdfmark instruction
-.\" Macro supplies the required opening "[" and closing "pdfmark"
-.\" operator; DO NOT include them in the instruction text!
-.\" ----------------------------------------------------------------
-.\"
-.if \\n[PDFOPMODE] \{\
-.\"
-.\" Strict DSC compliance forbids emission of ps:exec lines which
-.\" exceed 255 characters in length. We will allow the user to specify
-.\" an alternative lesser limit ...
-.\"
-. pdf*pdfmark.limit PDFMARK.FOLDWIDTH.MAX 255
-.\"
-.\" ... and we will also support a second lesser limit, which will be
-.\" applied to literal text parenthetically embedded within the PDFMARK.
-.\"
-. pdf*pdfmark.limit PDFMARK.FOLDWIDTH \\n[PDFMARK.FOLDWIDTH.MAX]
-.\"
-.\" We will push out the entire PDFMARK in one chunk, provided it fits
-.\" within this limit.
-.\"
-. length pdf:length "[\\$* pdfmark\"
-. ie !(\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH]) \{\
-. \"
-. \" This PDFMARK is suitable for single chunk output ...
-. \"
-. nop \!x X ps:exec [\\$* pdfmark
-. \}
-. el \{\
-. \" ... but, when the limit would be violated, then we must
-. \" recompose the specified PDFMARK, spreading it over as many
-. \" continuation lines as are necessary.
-. \"
-. als pdf*compose pdf*compose.first
-. while \\n(.$ \{\
-. pdf*compose \\$1
-. shift
-. \}
-. \"
-. \" Complete the PDFMARK recomposition, by appending a
-. \" "pdfmark" operator, and push it out to the intermediate
-. \" output stream, (excluding its final line break).
-. \"
-. pdf*compose pdfmark
-. pdf*pdfmark.dispatch
-. \"
-. \" And clean up when done.
-. \"
-. rm pdf*compose pdf*pdfmark.post
-. rm pdf:compose.test pdf:composed.literal
-. \}
-. rr pdf:length
-. \}
-..
-.\" When a PDFMARK exceeds the specified output record length limit,
-.\" then we decompose it, subsequently using the dynamically overloaded
-.\" macro, "pdf*compose", to reassemble it into as many continuation
-.\" records as it may require.
-.\"
-.\" Each call to "pdf*compose" uses macro "pdf*length.increment" to
-.\" keep track of the current output record length, so ensuring that
-.\" the active maximum length limit is not violated.
-.\"
-.de pdf*length.increment
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdf*length.increment NEXT-ADDITION
-.\" ----------------------------------------------------------------
-.\"
-.ie d pdf:composed.line \
-. length pdf:length "\\*[pdf:composed.line] \\$*\"
-.el .length pdf:length "\\$*\"
-..
-.\" The first call to "pdf*compose" for each PDFMARK is directed
-.\" to "pdf*compose.first"; this initialises the local strings
-.\" and macros used to compose the eventual PDFMARK output.
-.\"
-.de pdf*compose.first
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .als pdf*compose pdf*compose.first
-.\" . pdf*compose TOKEN
-.\" ----------------------------------------------------------------
-.\"
-.\" Ensure that the output record accumulator will be initialised
-.\" on posting of the first composed PDFMARK record.
-.\"
-.als pdf*pdfmark.post pdf*pdfmark.post.first
-.\"
-.\" The first token passed to "pdf*compose" should not be a
-.\" literal, but be prepared to handle one, just in case.
-.\"
-.ds pdf:compose.test \\$1
-.substring pdf:compose.test 0 0
-.ie '('\\*[pdf:compose.test]' \{\
-.\"
-.\" We found a literal, even though we didn't expect it;
-.\" if it's a single element literal, we can just handle it
-.\" as if it is a regular token anyway.
-.\"
-. ds pdf:compose.test "\\$\\n(.$\"
-. substring pdf:compose.test -1
-. if !')'\\*[pdf:compose.test]' \{\
-. \"
-. \" But when it is the first of a literal sequence,
-. \" then we need to set up "pdf*compose" to handle it.
-. \"
-. ds pdf:composed.literal "[\\$*\"
-. als pdf*compose pdf*compose.literal
-. \}
-. \}
-.el .ds pdf:compose.test )
-.if ')'\\*[pdf:compose.test]' \{\
-.\"
-.\" In the normal case, we start each new PDFMARK with a
-.\" regular token; save it as the first in the composed output
-.\" line sequence, and set up "pdf*compose" to collect
-.\" the rest of the sequence.
-.\"
-. ds pdf:composed.line "[\\$*\"
-. als pdf*compose pdf*compose.next
-. \}
-..
-.\" Subsequent calls to "pdf*compose", while collecting
-.\" regular tokens, are then directed to "pdf*compose.next".
-.\"
-.de pdf*compose.next
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .als pdf*compose pdf*compose.next
-.\" . pdf*compose TOKEN
-.\" ----------------------------------------------------------------
-.\"
-.\" This first checks to ensure that the supplied token really is
-.\" a regular token, and not the first element in a literal.
-.\"
-.ds pdf:compose.test \\$1
-.substring pdf:compose.test 0 0
-.ie '('\\*[pdf:compose.test]' \{\
-.\"
-.\" The supplied token represents the first element of a literal,
-.\" but it may be a single element literal, which we simply handle
-.\" as a regular token anyway.
-.\"
-. ds pdf:compose.test "\\$\\n(.$\"
-. substring pdf:compose.test -1
-. if !')'\\*[pdf:compose.test]' \{\
-. \"
-. \" The supplied token is the first of a sequence of elements
-. \" which collectively define a literal, so start collecting a
-. \" composite literal token, and change the "pdf*compose"
-. \" state, to collect and append the remaining elements.
-. \"
-. ds pdf:composed.literal "\\$*\"
-. als pdf*compose pdf*compose.literal
-. \}
-. \}
-.el .ds pdf:compose.test )
-.if ')'\\*[pdf:compose.test]' \{\
-.\"
-.\" The supplied token IS a regular token; add it, but ensure that
-.\" the active maximum record length limit is honoured.
-.\"
-. pdf*length.increment "\\$*\"
-. ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
-. \"
-. \" Adding this token would cause the current PDFMARK record, in
-. \" groff's intermediate output file, to overflow the active record
-. \" length limit, so post the current record and start another.
-. \"
-. pdf*pdfmark.dispatch
-. ds pdf:composed.line "\\$*\"
-. \}
-. el \{\
-. \"
-. \" This token will fit in the current PDFMARK record, without
-. \" violating the active length limit, so simply add it.
-. \"
-. ie d pdf:composed.line .as pdf:composed.line " \\$*\"
-. el .ds pdf:composed.line "\\$*\"
-. \}
-. \}
-..
-.\" While assembling a multiple token literal sequence into a single
-.\" literal token, successive calls to "pdf*compose" are directed
-.\" to "pdf*compose.literal".
-.\"
-.de pdf*compose.literal
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .als pdf*compose pdf*compose.literal
-.\" . pdf*compose TOKEN
-.\" ----------------------------------------------------------------
-.\"
-.\" First, check to ensure that the current token can be appended to
-.\" the accumulated literal, without extending it beyond the maximum
-.\" allowed literal token length.
-.\"
-.length pdf:length "\\*[pdf:composed.literal] \\$*\"
-.ie (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH] - 2)) \{\
-.\"
-.\" If it has grown too long, then it must be folded across two
-.\" physical PDFMARK output records, so check if we can accommodate
-.\" the portion collected so far within the current output record.
-.\"
-. pdf*length.increment "\\*[pdf:composed.literal]\"
-. if (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH.MAX] - 2)) \{\
-. \"
-. \" The current output record CAN'T accommodate the currently
-. \" composed portion of the literal, so flush out the current
-. \" record, to make way for the accumulated literal, and mark
-. \" the dispatch mode as "wrapped", for the fragments of the
-. \" folded literal string, which are to follow.
-. \"
-. pdf*pdfmark.dispatch
-. ds pdf*pdfmark.dispatch.wrapped
-. \}
-. ie d pdf:composed.line \{\
-. \"
-. \" If we DIDN'T need to flush the current output record,
-. \" then we can simply append the accumulated literal to it...
-. \"
-. as pdf:composed.line " \\*[pdf:composed.literal]\"
-. \}
-. el \{\
-. \"
-. \" otherwise, when the current record has been flushed, or is
-. \" empty, then we promote the accumulated literal, to make it
-. \" the next output record...
-. \"
-. rn pdf:composed.literal pdf:composed.line
-. \}
-.\"
-.\" Now, to complete the fold, flush out any accumulated partial
-.\" output record, and continue accumulating the literal, starting
-.\" with the current token.
-.\"
-. pdf*pdfmark.dispatch
-. ds pdf:composed.literal "\\$*\"
-. \}
-.el \{\
-.\"
-.\" Alternatively, when we HAVEN'T identified a need to fold the
-.\" current output record, then we simply append the current token
-.\" to the accumulated literal token buffer string.
-.\"
-. as pdf:composed.literal " \\$*\"
-. \}
-.\"
-.\" Having ensured that we have sufficient space, in which to
-.\" append the current token to the currently accumulated literal,
-.\" we check its rightmost character, to see if is the closing
-.\" parenthesis, which completes the literal.
-.\"
-.ds pdf:compose.test \\$\\n(.$
-.substring pdf:compose.test -1
-.if ')'\\*[pdf:compose.test]' \{\
-.\"
-.\" The literal has been completely collected, so we may now append
-.\" it to the current output record, as a single literal token, but
-.\" subject to the constraint that it must not extend the output
-.\" record beyond the maximum permitted length.
-.\"
-. pdf*length.increment "\\*[pdf:composed.literal]\"
-. ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
-. \"
-. \" So, when the literal cannot be accommodated within the maximum
-. \" length constraint, then we flush the current record, and start
-. \" a new one, with the literal token as its first entry.
-. \"
-. pdf*pdfmark.dispatch
-. rn pdf:composed.literal pdf:composed.line
-. \}
-. el \{\
-. \"
-. \" When the literal CAN be accommodated within the maximum length
-. \" constraint, then ...
-. \"
-. ie d pdf:composed.line \{\
-. \"
-. \" When an output record has already been instantiated, we
-. \" append the literal token to it, and discard the accumulator
-. \" string, which is no longer required.
-. \"
-. as pdf:composed.line " \\*[pdf:composed.literal]\"
-. rm pdf:composed.literal
-. \}
-. el \{\
-. \"
-. \" But when no output record yet exists, then we simply
-. \" reassign the accumulated literal token, to instantiate a
-. \" new output record.
-. \"
-. rn pdf:composed.literal pdf:composed.line
-. \}
-. \}
-.\"
-.\" Finally, since we have completed the accumulation of the literal, we
-.\" revert to the "unwrapped" mode of operation for "pdf*pdfmark.dispatch",
-.\" and restore the normal "pdf*compose" action, for collection of the next
-.\" token (if any).
-.\"
-. rm pdf*pdfmark.dispatch.wrapped
-. als pdf*compose pdf*compose.next
-. \}
-..
-.\" While composing a multiple record PDFMARK, each composed record
-.\" must be added to the collection, whenever the partially composed
-.\" output record has been filled; this is handled when necessary,
-.\" by calling the "pdf*pdfmark.dispatch" macro.
-.\"
-.de pdf*pdfmark.dispatch
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdf*pdfmark.dispatch
-.\" ----------------------------------------------------------------
-.\"
-.if d pdf:composed.line \{\
-.\"
-.\" This is simply a wrapper around the overloaded "pdf*pdfmark.post"
-.\" macro, ensuring that an output record has actually been collected
-.\" before attempting to post it; it then cleans up after posting, to
-.\" ensure that each collected record is posted only once.
-.\"
-. if d pdf*pdfmark.dispatch.wrapped \{\
-. \"
-. \" When dispatching an excessively long literal string, which
-. \" must be wrapped over multiple records, this mode is active
-. \" for all but the closing record; we must escape the newline
-. \" at the end of each such unclosed literal record.
-. \"
-. as pdf:composed.line " \\\\\\\\\"
-. \}
-. pdf*pdfmark.post
-. rm pdf:composed.line
-. \}
-..
-.\" For each PDFMARK, the first call of "pdf*pdfmark.post" is directed
-.\" to the "pdf*pdfmark.post.first" macro; this initialises the state
-.\" of the "pdf:composed" macro, for assembly of a new PDFMARK.
-.\"
-.de pdf*pdfmark.post.first
-. nop \!x X ps:exec \\*[pdf:composed.line]
-.\"
-.\" Subsequent calls to "pdf*pdfmark.post" are redirected to the
-.\" alternative "pdf*pdfmark.post.next" macro, which simply appends
-.\" additional PDFMARK records to the "pdf:composed" macro.
-.\"
-.als pdf*pdfmark.post pdf*pdfmark.post.next
-..
-.de pdf*pdfmark.post.next
-. nop \!+\\*[pdf:composed.line]
-..
-.\" "pdf*end" is a dummy macro. It is required to mark the end
-.\" of each individual fragment which is added to "pdf:composed";
-.\" other than this, it does nothing.
-.\"
-.de pdf*end
-..
-.\"
-.\" Some supporting macros defer actual pdfmark output until an
-.\" appropriate time for it to be written; the "pdfsync" macro
-.\" provides a mechanism for flushing such deferred output;
-.\" it should be called from an end macro, and at any other time
-.\" when it may be deemed necessary to flush pdfmark context.
-.\"
-.de pdfsync
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdfsync buffer ...
-.\" Arguments indicate which "buffer(s)" to flush:
-.\" O -> bookmark (outline) cache
-.\" M -> document metadata diversion
-.\" If no argument, flush ALL buffers
-.\" ----------------------------------------------------------------
-.\"
-.ie \\n(.$ \{\
-. while \\n(.$ \{\
-. if '\\$1'O' .pdf:bm.sync 1
-. if '\\$1'M' \{\
-. if dpdf:metadata .pdf:metadata
-. rm pdf:metadata
-. \}
-. shift
-. \}
-. \}
-.el .pdfsync O M
-..
-.\"
-.\" some helper functions ...
-.\"
-.\" "pdf:warn" and "pdf:error" write diagnostic messages to stderr
-.\"
-.de pdf:warn
-.\" ----------------------------------------------------------
-.\" Usage:
-.\" .pdf:warn text of message
-.\" ----------------------------------------------------------
-.\"
-.tm \\n(.F:\\n(.c: macro warning: \\$*
-..
-.de pdf:error
-.\" ----------------------------------------------------------
-.\" Usage:
-.\" .pdf:error text of message
-.\" ----------------------------------------------------------
-.\"
-.tm \\n(.F:\\n(.c: macro error: \\$*
-..
-.\" "pdf:pop", assisted by "pdf*pop", allows us to retrieve register,
-.\" or string values, from a string masquerading as a data queue,
-.\" or as a stack.
-.\"
-.de pdf:pop
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdf:pop <type> <to-name> <from-name>
-.\" $1 = nr for numeric register, ds for string
-.\" $2 = name of register or string to be assigned
-.\" $3 = name of string, from which data is to be retrieved
-.\" ----------------------------------------------------------------
-.\"
-.pdf*pop \\$* \\*[\\$3]
-..
-.de pdf*pop
-.ds pdf:stack \\$3
-.\\$1 \\$2 \\$4
-.shift 4
-.ie \\n(.$ .ds \\*[pdf:stack] \\$*
-.el .rm \\*[pdf:stack]
-.rm pdf:stack
-..
-.\"
-.\"
-.\" ===========================================================
-.\" Module PDFINFO: Insert MetaData Entries into a PDF Document
-.\" ===========================================================
-.\"
-.\" N.B.
-.\" Output from the macros in this module is deferred, until
-.\" subsequent invocation of .pdfsync, or .pdfexit
-.\"
-.\" ."pdfinfo" provides a general purpose form of metadata entry ...
-.\" it allows arbitrary text to be associated with any specified
-.\" metadata field name.
-.\"
-.de pdfinfo
-.\" -------------------------------------------------------------------
-.\" Usage:
-.\" .pdfinfo /FieldName field content ...
-.\" Examples:
-.\" .pdfinfo /Title A PDF Document
-.\" .pdfinfo /Author Keith Marshall
-.\" -------------------------------------------------------------------
-.\"
-.ds pdf:meta.field \\$1
-.shift
-.da pdf:metadata
-\!.pdfmark \\*[pdf:meta.field] (\\$*) /DOCINFO
-.di
-.rm pdf:meta.field
-..
-.\"
-.\" Macro "pdfview" defines a special form of metadata entry ...
-.\" it uses the /DOCVIEW pdfmark, to specify the initial (default) view,
-.\" when the document is opened.
-.\"
-.de pdfview
-.\" -------------------------------------------------------------------
-.\" Usage:
-.\" .pdfview view parameters ...
-.\" Examples:
-.\" .pdfview /PageMode /UseOutlines
-.\" .pdfview /Page 2 /View [/FitH \n(.p u]
-.\" -------------------------------------------------------------------
-.\"
-.da pdf:metadata
-\!.pdfmark \\$* /DOCVIEW
-.di
-..
-.\"
-.\"
-.\" =====================================================================
-.\" Module PDFNOTE: Insert "Sticky Note" Style Comments in a PDF Document
-.\" =====================================================================
-.\"
-.\" "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" set the preferred size for
-.\" display of the "sticky note" pane, when opened. Acrobat Reader
-.\" seems not to honour these -- perhaps GhostScript doesn't encode
-.\" them correctly! Anyway, let's set some suitable default values,
-.\" in case the user has a set up which does work as advertised.
-.\"
-.nr PDFNOTE.WIDTH 3.5i
-.nr PDFNOTE.HEIGHT 2.0i
-.\"
-.\" "pdf:bbox" defines the expression used to set the size and location
-.\" of the bounding rectangle for display of notes and link "hot-spots".
-.\" This is defined, such that a note is placed at troff's current text
-.\" position on the current page, with its displayed image size defined
-.\" by the "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" registers, while the
-.\" bounds for a link "hot-spot" are matched to the text region which
-.\" defines the "hot-spot".
-.\"
-.ds pdf:bbox \\n[pdf:llx] u \\n[pdf:lly] u \\n[pdf:urx] u \\n[pdf:ury] u
-.\"
-.\" Getting line breaks into the text of a PDFNOTE is tricky -- we need
-.\" to get a "\n" into the Postscript stream, but three levels of "\" are
-.\" swallowed, when we invoke "pdfnote". The following definition of "PDFLB",
-.\" (for LineBreak), is rather ugly, but does allow us to use
-.\"
-.\" .pdfnote Some text.\*[PDFLB]Some more text, on a new line.
-.\"
-.ds PDFLB \\\\\\\\\\\\\\\\n
-.\"
-.de pdfnote
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" .pdfnote [-T "Text for Title"] Text of note ...
-.\" ----------------------------------------------------------------------
-.\"
-.if \\n[PDFOPMODE] \{\
-.\"
-.\" First, compute the bounding rectangle,
-.\" for this PDFNOTE instance
-.\"
-. mk pdf:ury
-. nr pdf:llx \\n(.k+\\n(.o+\\n[.in]
-. nr pdf:lly \\n[pdf:ury]-\\n[PDFNOTE.HEIGHT]
-. nr pdf:urx \\n[pdf:llx]+\\n[PDFNOTE.WIDTH]
-. ds pdf:note.instance /Rect [\\*[pdf:bbox]]
-.\"
-.\" Parse any specified (recognisable) PDFNOTE options
-.\"
-. while dpdf:note\\$1 \{\
-. pdf:note\\$1 \\$@
-. shift \\n[pdf:note.argc]
-. \}
-.\"
-.\" Emit the note, and clean up
-.\"
-. pdfmark \\*[pdf:note.instance] /Contents (\\$*) /ANN
-. rm pdf:note.instance
-. rr pdf:note.argc
-. \}
-..
-.de pdf:note-T
-.nr pdf:note.argc 2
-.as pdf:note.instance " /Title (\\$2)
-..
-.\"
-.\"
-.\" =====================================================================
-.\" Module PDFBOOKMARK: Add an Outline Reference in the PDF Bookmark Pane
-.\" =====================================================================
-.\"
-.\" "PDFBOOKMARK.VIEW" controls how the document will be displayed,
-.\" when the user selects a bookmark. This default setting will fit
-.\" the page width to the viewing window, with the bookmarked entry
-.\" located at the top of the viewable area.
-.\"
-.ds PDFBOOKMARK.VIEW /FitH \\n[PDFPAGE.Y] u
-.\"
-.\" "PDFOUTLINE.FOLDLEVEL" controls how the document outline will be
-.\" displayed. It is a number, defining the maximum heading level
-.\" which will be visible, without outline expansion by the user, in
-.\" the initial view of the document outline. Assuming that no sane
-.\" document will ever extend to 10,000 levels of nested headings,
-.\" this initial default value causes outlines to be fully expanded.
-.\"
-.nr PDFOUTLINE.FOLDLEVEL 10000
-.\"
-.\" The actual job of creating an outline reference
-.\" is performed by the "pdfbookmark" macro.
-.\"
-.de pdfbookmark
-.\" ------------------------------------------------------------------
-.\" Usage:
-.\" .pdfbookmark [-T tag] level "Text of Outline Entry"
-.\"
-.\" $1 = nesting level for bookmark (1 is top level)
-.\" $2 = text for bookmark, (in PDF viewer bookmarks list)
-.\" $3 = suffix for PDF internal bookmark name (optional)
-.\" ------------------------------------------------------------------
-.\"
-.ie '\\n(.z'' \{\
-.\"
-.\" When we are at the top diversion level, i.e. actually emitting text
-.\" to the output device stream, then we compute the location of, and
-.\" plant this bookmark immediately.
-.\"
-. if \\n[PDFOPMODE] \{\
-. \"
-. \" Make the bookmark name "untagged" by default,
-. \" then parse any specified options, to set a "tag", if required
-. \"
-. ds pdf:href-T
-. while dpdf:href.opt\\$1 \{\
-. pdf:href.opt\\$1 \\$@
-. shift \\n[pdf:href.argc]
-. \}
-. rr pdf:href.argc
-. \"
-. \" If we found "--" to mark the end of the options, discard it
-. \"
-. if '\\$1'--' .shift
-. \"
-. \" Synchronise the bookmark cache
-. \" to the requested bookmark nesting level
-. \"
-. pdf:bm.sync \\$1
-. shift
-. \"
-. \" Increment the bookmark serialisation index
-. \" in order to generate a uniquely serialised bookmark name,
-. \" ( which we return in the string "PDFBOOKMARK.NAME" ),
-. \" and insert this bookmark into the cache
-. \"
-. pdf:href.sety
-. nr pdf:bm.nr +1
-. ds PDFBOOKMARK.NAME pdf:bm\\n[pdf:bm.nr]\\*[pdf:href-T]
-. ds pdf:bm\\n[pdf:bm.nr] /Dest /\\*[PDFBOOKMARK.NAME]
-. pdfmark \\*[pdf:bm\\n[pdf:bm.nr]] /View [\\*[PDFBOOKMARK.VIEW]] /DEST
-. as pdf:bm\\n[pdf:bm.nr] " /Title (\\$*)
-. pdf:href.options.clear
-. rr PDFPAGE.Y
-. \}
-. \}
-.el \{\
-.\"
-.\" But when we are collecting a diversion which will be written out later,
-.\" then we must defer bookmark placement, until we emit the diversion.
-.\" (don't rely on $0 == pdfbookmark here; it may be a volatile alias).
-.\"
-. nop \!.pdfbookmark \\$@
-. \}
-..
-.\"
-.\" Macro "pdf:bm.sync" is called for each bookmark created,
-.\" to establish a cache entry at the appropriate nesting level.
-.\" It will flush ALL previous cache content, when called to
-.\" add a new bookmark at level 1, or if simply called at
-.\" level 1, without adding any bookmark.
-.\"
-.de pdf:bm.sync
-.\" ------------------------------------------------------------------
-.\" Usage:
-.\" .pdf:bm.sync level
-.\" $1 = nesting level of current bookmark, or 1 to flush cache
-.\" ------------------------------------------------------------------
-.\"
-.\" First validate the bookmark nesting level
-.\" adjusting it if required
-.\"
-.if \\$1>\\n[pdf:bm.nl] .nr pdf:bm.nl +1
-.ie \\$1>\\n[pdf:bm.nl] \{\
-. pdf:warn adjusted level \\$1 bookmark; should be <= \\n[pdf:bm.nl]
-. \}
-.el .nr pdf:bm.nl \\$1
-.if \\n[pdf:bm.nl]<1 \{\
-. pdf:warn bad arg (\\$1) in \\$0 \\$1; \\$0 1 forced
-. nr pdf:bm.nl 1
-. \}
-.\"
-.\" If reverting from a higher to a lower nesting level,
-.\" cyclicly adjust cache counts for each pending higher level
-.\"
-.if \\n[pdf:bm.lc]>=\\n[pdf:bm.nl] \{\
-. nr pdf:bm.lc +1
-. if !rpdf:bm.c\\n[pdf:bm.lc].c .nr pdf:bm.c\\n[pdf:bm.lc].c 0
-. while \\n[pdf:bm.lc]>\\n[pdf:bm.nl] \{\
-. as pdf:bm.c\\n[pdf:bm.lc] " \\n[pdf:bm.c\\n[pdf:bm.lc].c]
-. rr pdf:bm.c\\n[pdf:bm.lc].c
-. nr pdf:bm.lc -1
-. \}
-. \}
-.\"
-.\" Update the cache level,
-.\" flushing when we are at level 1
-.\"
-.nr pdf:bm.lc \\n[pdf:bm.nl]
-.ie \\n[pdf:bm.nl]=1 \{\
-. while \\n[pdf:bm.ic]<\\n[pdf:bm.nr] .pdf:bm.emit 0
-. rr pdf:bm.rc
-. \}
-.el .nr pdf:bm.c\\n[pdf:bm.nl].c +1
-..
-.\" Macro "pdf:bm.emit" is called, when the cache is at level 1.
-.\" This flushes ALL pending bookmarks from the cache, i.e. the
-.\" preceding level 1 bookmark, and any nested dependents,
-.\" which it may have.
-.\"
-.de pdf:bm.emit
-.\" ------------------------------------------------------------------
-.\" Usage:
-.\" .pdf:bm.emit flag
-.\" $1 = reference counting flag, used to control recursion
-.\" ------------------------------------------------------------------
-.\"
-.\" First check for nested dependents,
-.\" and append the "dependent count" to the bookmark, as required.
-.\"
-.nr pdf:bm.ic +1
-.nr pdf:bm.lc +1
-.pdf:pop nr pdf:bm.rc pdf:bm.c\\n[pdf:bm.lc]
-.if \\n[pdf:bm.rc] \{\
-. ds pdf:bm.fold
-. if \\n[pdf:bm.lc]>\\n[PDFOUTLINE.FOLDLEVEL] .ds pdf:bm.fold -
-. as pdf:bm\\n[pdf:bm.ic] " /Count \\*[pdf:bm.fold]\\n[pdf:bm.rc]
-. rm pdf:bm.fold
-. \}
-.pdfmark \\*[pdf:bm\\n[pdf:bm.ic]] /OUT
-.rm pdf:bm\\n[pdf:bm.ic]
-.\"
-.\" For ALL dependents, if any,
-.\" recursively flush out any higher level dependents,
-.\" which they themselves may have
-.\"
-.while \\n[pdf:bm.rc] \{\
-. nr pdf:bm.rc -1
-. pdf:bm.emit \\n[pdf:bm.rc]
-. \}
-.\"
-.\" Finally,
-.\" unwind the recursive call stack, until we return to the top level.
-.\"
-.nr pdf:bm.rc \\$1
-.nr pdf:bm.lc -1
-..
-.nr pdf:bm.nr 0
-.nr pdf:bm.nl 1
-.nr pdf:bm.lc 0
-.nr pdf:bm.ic 0
-.\"
-.\"
-.\" =============================================================
-.\" Module PDFHREF: Create Hypertext References in a PDF Document
-.\" =============================================================
-.\"
-.\" "PDFHREF.VIEW" controls how the document will be displayed,
-.\" when the user follows a link to a named reference.
-.\"
-.ds PDFHREF.VIEW /FitH \\n[PDFPAGE.Y] u
-.\"
-.\" This default setting will fit the page width to the viewing
-.\" window, with the bookmarked entry located close to the top
-.\" of the viewable area. "PDFHREF.VIEW.LEADING" controls the
-.\" actual distance below the top of the viewing window, where
-.\" the reference will be positioned; 5 points is a reasonable
-.\" default offset.
-.\"
-.nr PDFHREF.VIEW.LEADING 5.0p
-.\"
-.\" Yuk!!!
-.\" PDF view co-ordinates are mapped from the bottom left corner,
-.\" of the page, whereas page printing co-ordinates are mapped
-.\" conventionally, from top left.
-.\"
-.\" Macro "pdf:href.sety" transforms the vertical position of the
-.\" last printed baseline, from the printing co-ordinate domain to
-.\" the PDF view domain.
-.\"
-.de pdf:href.sety
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdf:href.sety
-.\" ----------------------------------------------------------------
-.\"
-.\" This computation yields the vertical view co-ordinate
-.\" in groff's basic units; don't forget to append grops' "u"
-.\" conversion operator, when writing the pdfmark!
-.\"
-.nr PDFPAGE.Y \\n(.p-\\n(nl+\\n[PDFHREF.VIEW.LEADING]
-..
-.\" When we create a link "hot-spot" ...
-.\" "PDFHREF.LEADING" sets the distance above the top of the glyph
-.\" bounding boxes, in each line of link text, over which the link
-.\" hot-spot will extend, while "PDFHREF.HEIGHT" sets the hot-spot
-.\" height, PER LINE of text occupied by the reference.
-.\"
-.\" Since most fonts specify some leading space within the bounding
-.\" boxes of their glyphs, a better appearance may be achieved when
-.\" NEGATIVE leading is specified for link hot-spots; indeed, when
-.\" the default 10pt Times font is used, -1.0 point seems to be a
-.\" reasonable default value for "PDFHREF.LEADING" -- it may be
-.\" changed, if desired.
-.\"
-.\" "PDFHREF.HEIGHT" is initially set as one vertical spacing unit;
-.\" note that it is defined as a string, so it will adapt to changes
-.\" in the vertical spacing. Changing it is NOT RECOMMENDED.
-.\"
-.nr PDFHREF.LEADING -1.0p
-.ds PDFHREF.HEIGHT 1.0v
-.\"
-.\" PDF readers generally place a rectangular border around link
-.\" "hot-spots". Within text, this looks rather ugly, so we set
-.\" "PDFHREF.BORDER" to suppress it -- the three zeroes represent
-.\" the border parameters in the "/Border [0 0 0]" PDFMARK string,
-.\" and may be changed to any valid form, as defined in Adobe's
-.\" PDFMARK Reference Manual.
-.\"
-.ds PDFHREF.BORDER 0 0 0
-.\"
-.\" "PDFHREF.COLOUR" (note British spelling) defines the colour to
-.\" be used for display of link "hot-spots". This will apply both
-.\" to borders, if used, and, by default to text; however, actual
-.\" text colour is set by "PDFHREF.TEXT.COLOUR", which may be reset
-.\" independently of "PDFHREF.COLOUR", to achieve contrasting text
-.\" and border colours.
-.\"
-.\" "PDFHREF.COLOUR" must be set to a sequence of three values,
-.\" each in the range 0.0 .. 1.0, representing the red, green, and
-.\" blue components of the colour specification in the RGB colour
-.\" domain, which is shared by "groff" and the PDF readers.
-.\"
-.ds PDFHREF.COLOUR 0.35 0.00 0.60
-.defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR]
-.\"
-.\" "PDFHREF.TEXT.COLOUR", on the other hand, is simply defined
-.\" using any "groff" colour name -- this default maps it to the
-.\" same colour value as "PDFHREF.COLOUR".
-.\"
-.ds PDFHREF.TEXT.COLOUR pdf:href.colour
-.\"
-.\" Accommodate users who prefer the American spelling, COLOR, to
-.\" the British spelling, COLOUR.
-.\"
-.als PDFHREF.COLOR PDFHREF.COLOUR
-.als PDFHREF.TEXT.COLOR PDFHREF.TEXT.COLOUR
-.\"
-.\" All PDF "Hypertext" reference capabilities are accessed
-.\" through the "pdfhref" macro
-.\"
-.de pdfhref
-.\" -----------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref <subcommand [options ...] [parameters ...]> ...
-.\" -----------------------------------------------------------------
-.\"
-.if \\n[PDFOPMODE] \{\
-.\"
-.\" Loop over all subcommands specified in the argument list
-.\"
-. while \\n(.$ \{\
-. \"
-. \" Initially, assume each subcommand will complete successfully
-. \"
-. nr pdf:href.ok 1
-. \"
-. \" Initialise -E and -X flags in the OFF state
-. \"
-. nr pdf:href-E 0
-. nr pdf:href-X 0
-. \"
-. \" Handle the case where subcommand is specified as "-class",
-. \" setting up appropriate macro aliases for subcommand handlers.
-. \"
-. if dpdf*href\\$1 .als pdf*href pdf*href\\$1
-. if dpdf*href\\$1.link .als pdf*href.link pdf*href\\$1.link
-. if dpdf*href\\$1.file .als pdf*href.file pdf*href\\$1.file
-. \"
-. \" Repeat macro alias setup
-. \" for the case where the subcommand is specified as "class",
-. \" (without a leading hyphen)
-. \"
-. if dpdf*href-\\$1 .als pdf*href pdf*href-\\$1
-. if dpdf*href-\\$1.link .als pdf*href.link pdf*href-\\$1.link
-. if dpdf*href-\\$1.file .als pdf*href.file pdf*href-\\$1.file
-. \"
-. \" Process one subcommand ...
-. \"
-. ie dpdf*href \{\
-. \"
-. \" Subcommand "class" is recognised ...
-. \" discard the "class" code from the argument list,
-. \" set the initial argument count to swallow all arguments,
-. \" and invoke the selected subcommand handler.
-. \"
-. shift
-. nr pdf:argc \\n(.$
-. pdf*href \\$@
-. \"
-. \" When done,
-. \" discard all arguments actually consumed by the handler,
-. \" before proceeding to the next subcommand (if any).
-. \"
-. shift \\n[pdf:argc]
-. \}
-. el \{\
-. \"
-. \" Subcommand "class" is not recognised ...
-. \" issue a warning, and discard the entire argument list,
-. \" so aborting this "pdfhref" invocation
-. \"
-. pdf:warn \\$0: undefined reference class '\\$1' ignored
-. shift \\n(.$
-. \}
-. \"
-. \" Clean up temporary reference data,
-. \" to ensure it doesn't propagate to any future reference
-. \"
-. rm pdf*href pdf:href.link pdf:href.files
-. rr pdf:href-E pdf:href-X
-. pdf:href.options.clear
-. \}
-. rr pdf:href.ok
-. \}
-..
-.\"
-.\" Macros "pdf:href.flag" and "pdf:href.option"
-.\" provide a generic mechanism for switching on flag type options,
-.\" and for decoding options with arguments, respectively
-.\"
-.de pdf:href.flag
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.nr pdf:href\\$1 1
-.nr pdf:href.argc 1
-..
-.de pdf:href.option
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.ds pdf:href\\$1 \\$2
-.nr pdf:href.argc 2
-..
-.\"
-.\" Valid PDFHREF options are simply declared
-.\" by aliasing option handlers to "pdf:href.option",
-.\" or to "pdf:href.flag", as appropriate
-.\"
-.als pdf:href.opt-A pdf:href.option \" affixed text
-.als pdf:href.opt-D pdf:href.option \" destination name
-.als pdf:href.opt-E pdf:href.flag \" echo link descriptor
-.als pdf:href.opt-F pdf:href.option \" remote file specifier
-.als pdf:href.opt-N pdf:href.option \" reference name
-.als pdf:href.opt-P pdf:href.option \" prefixed text
-.als pdf:href.opt-T pdf:href.option \" bookmark "tag"
-.als pdf:href.opt-X pdf:href.flag \" cross reference
-.\"
-.\" For references to another document file
-.\" we also need to support OS dependent file name specifiers
-.\"
-.als pdf:href.opt-DF pdf:href.option \" /DOSFile specifier
-.als pdf:href.opt-MF pdf:href.option \" /MacFile specifier
-.als pdf:href.opt-UF pdf:href.option \" /UnixFile specifier
-.als pdf:href.opt-WF pdf:href.option \" /WinFile specifier
-.\"
-.\" Macro "pdf:href.options.clear" ensures that ALL option
-.\" argument strings are deleted, after "pdfhref" has completed
-.\" all processing which depends on them
-.\"
-.de pdf:href.options.clear
-.\" -----------------------------------------------------------------
-.\" Usage:
-.\" .pdf:href.options.clear [option ...]
-.\" -----------------------------------------------------------------
-.\"
-.\" When an option list is specified ...
-.\"
-.ie \\n(.$ \{\
-. \"
-. \" then loop through the list,
-. \" deleting each specified option argument string in turn
-. \"
-. while \\n(.$ \{\
-. if dpdf:href-\\$1 .rm pdf:href-\\$1
-. shift
-. \}
-. \}
-.\"
-.\" ... but when no list is specified,
-.\" then recurse, to clear all known option argument strings
-.\"
-.el .pdf:href.options.clear A D F N P T DF MF UF WF
-..
-.\"
-.\" "PDFHREF.INFO" establishes the content of the cross reference
-.\" data record, which is exported via the "stderr" stream, when a
-.\" cross reference anchor is created using a "pdfhref" macro request
-.\" of the form
-.\"
-.\" .pdfhref M -N name -X text ...
-.\"
-.\" .ds PDFHREF.INFO \\*[PDFHREF.NAME] reference data ...
-.\"
-.ds PDFHREF.INFO page \\n% \\$*
-.\"
-.\" Macro "pdf*href-M" is the handler invoked by "pdfhref", when
-.\" called with the "M" reference class specifier, to create a
-.\" named cross reference mark, and to emit a cross reference
-.\" data record, as specified by "PDFHREF.INFO".
-.\"
-.de pdf*href-M
-.\" -----------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref M [-X] [-N name | -D name] [-E] descriptive text ...
-.\" -----------------------------------------------------------------
-.\"
-.\" Initially, declare the -D and -N string options as empty,
-.\" so we avoid warning messages when we try to use them, and find
-.\" that they are undefined.
-.\"
-.ds pdf:href-D
-.ds pdf:href-N
-.\"
-.\" Parse, interpret, and strip any specified options from the
-.\" argument list. (Note that only options with a declared handler
-.\" will be processed; there is no provision for detecting invalid
-.\" options -- anything which is not recognised is assumed to start
-.\" the "descriptive text" component of the argument list).
-.\"
-.while dpdf:href.opt\\$1 \{\
-. pdf:href.opt\\$1 \\$@
-. shift \\n[pdf:href.argc]
-. \}
-.\"
-.\" If we found "--", to mark the end of the options,
-.\" then we should discard it.
-.\"
-.if '\\$1'--' .shift
-.\"
-.\" All PDF reference markers MUST be named. The name may have been
-.\" supplied using the "-N Name" option, (or the "-D Name" option);
-.\" if not, deduce it from the first "word" in the "descriptive text",
-.\" if any, and set the marker -- if we still can't identify the name
-.\" for the destination, then this marker will not be created.
-.\"
-.pdf*href.set \\*[pdf:href-N] \\*[pdf:href-D] \\$1
-.\"
-.\" If we specified a cross reference, with the "-X" option, and the
-.\" reference mark has been successfully created, then we now need to
-.\" write the cross reference info to the STDERR stream
-.\"
-.if \\n[pdf:href-X] .pdf*href.export \\*[PDFHREF.INFO]
-.\"
-.\" Irrespective of whether this marker is created, or not,
-.\" the descriptive text will be copied to the groff output stream,
-.\" provided the "-E" option was specified
-.\"
-.if \\n[pdf:href-E] \&\\$*
-..
-.\"
-.de pdf*href.set
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.pdf*href.map.init
-.ie \\n(.$ \{\
-. \"
-. \" a marker name has been supplied ...
-. \" if we are formatting for immediate output,
-. \" emit PDFMARK code to establish the associated view
-. \"
-. ie '\\n(.z'' \{\
-. pdf:href.sety
-. pdfmark /Dest /\\$1 /View [\\*[PDFHREF.VIEW]] /DEST
-. ds PDFHREF.NAME \\$1
-. rr PDFPAGE.Y
-. \}
-. \"
-. \" but, when formatting a diversion ...
-. \" delay output of the PDFMARK code, until the diversion
-. \" is eventually written out
-. \"
-. el \!.\\$0 \\$@
-. \"
-. \" check if we also need to emit cross reference data
-. \" (caller will do this if "pdf:href-X" is set, but it is
-. \" not necessary, when "pdf:href.map" already exists)
-. \"
-. if dpdf:href.map .nr pdf:href-X 0
-. \}
-.el \{\
-. \" marker is unnamed ...
-. \" issue error message; do not emit reference data
-. \"
-. pdf:warn pdfhref destination marker must be named
-. nr pdf:href-X 0
-. \}
-..
-.de pdf*href.export
-.\"
-.\" Called ONLY by "pdf*href-M",
-.\" this macro ensures that the emission of exported reference data
-.\" is synchronised with the placement of the reference mark,
-.\" especially when the mark is defined within a diversion.
-.\"
-.ie '\\n(.z'' .tm gropdf-info:href \\*[PDFHREF.NAME] \\$*
-.el \!.\\$0 \\$@
-..
-.\"
-.\" Macro "pdf*href-D" is invoked when "pdfhref" is called
-.\" with the "D" reference class specifier; it provides a
-.\" standardised mechanism for interpreting reference data
-.\" exported by the "M" reference class, and may be used
-.\" to directly define external reference data, without the
-.\" use of "M" reference class designators in the source
-.\" document.
-.\"
-.de pdf*href-D
-.ds pdf:href-N
-.\"
-.\" Parse, interpret, and strip any specified options from the
-.\" argument list. (Note that only options with a declared handler
-.\" will be processed; there is no provision for detecting invalid
-.\" options -- anything which is not recognised is assumed to start
-.\" the "descriptive text" component of the argument list).
-.\"
-.while dpdf:href.opt\\$1 \{\
-. pdf:href.opt\\$1 \\$@
-. shift \\n[pdf:href.argc]
-. \}
-.\"
-.\" If we found "--", to mark the end of the options,
-.\" then we should discard it.
-.\"
-.if '\\$1'--' .shift
-.\"
-.ie '\\*[pdf:href-N]'' \{\
-. pdf:warn pdfhref defined reference requires a name
-. \}
-.el \{\
-. ds pdf:href(\\*[pdf:href-N]).info \\$*
-. \}
-..
-.\"
-.\" Macro "pdf*href-F" is invoked when "pdfhref" is called
-.\" with the "F" reference class specifier; it allows the user
-.\" to provide an alternative interpreter macro, which will be
-.\" called when a "PDFHREF.INFO" record is retrieved to define
-.\" the text of a cross reference link "hot spot".
-.\"
-.de pdf*href-F
-.\" ----------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref F [macro-name]
-.\" ----------------------------------------------------------------
-.\"
-.\" Set macro specified by "macro-name" as the format interpreter
-.\" for parsing "PDFHREF.INFO" records; if "macro-name" is omitted,
-.\" or is specified as the reserved name "default", then use the
-.\" default format parser, "pdf*href.format", defined below.
-.\"
-.if '\\$1'default' .shift \\n(.$
-.ie \\n(.$ .als pdf*href.format \\$1
-.el .als pdf*href.format pdf*href.default
-.nr pdf:argc 1
-..
-.\" The default reference formatting macro is defined below.
-.\" It parses the "PDFHREF.INFO" record specific to each reference,
-.\" recognising the keywords "file", "page" and "section", when they
-.\" appear in initial key/value pairs, replacing the key/value pair
-.\" with "PDFHREF.FILEREF", "PDFHREF.PAGEREF" or "PDFHREF.SECTREF"
-.\" respectively; any additional data in the "PDFHREF.INFO" record
-.\" is enclosed in typographic double quotes, and the parsed record
-.\" is appended to "PDFHREF.PREFIX", to be returned as the formatted
-.\" reference text.
-.\"
-.\" Default definitions for the reference strings "PDFHREF.PREFIX",
-.\" "PDFHREF.FILEREF", "PDFHREF.PAGEREF" and "PDFHREF.SECTREF" are
-.\" provided, in the English language. Users may substitute any
-.\" desired alternative definitions, for example, when formatting
-.\" documents in other languages. In each case, "\\$1" may be used
-.\" in the substitution, to represent the "value" component of the
-.\" respective key/value pair specified in the "PDFHREF.INFO" record.
-.\"
-.ds PDFHREF.PREFIX see
-.ds PDFHREF.PAGEREF page \\$1,
-.ds PDFHREF.SECTREF section \\$1,
-.ds PDFHREF.FILEREF \\$1
-.\"
-.de pdf*href.format
-.\" -----------------------------------------------------------------
-.\" Usage: (to be called ONLY by "pdfhref")
-.\" .pdf*href.format cross reference data ...
-.\" -----------------------------------------------------------------
-.\"
-.\" This macro is responsible for defining the strings "PDFHREF.TEXT"
-.\" and "PDFHREF.DESC", which are used by the "pdfhref" macro, as the
-.\" basis for generating the text content of a link "hot spot"; (any
-.\" user specified alternate formatter MUST do likewise).
-.\"
-.\" Note that "PDFHREF.TEXT" defines the overall format for the "link
-.\" text", while "PDFHREF.DESC" is the descriptive component thereof.
-.\"
-.\" This default implementation, subject to user customisation of the
-.\" "internationalisation" strings defined above, formats "hot spots"
-.\" of the style
-.\"
-.\" see page N, section S, "descriptive text ..."
-.\"
-.ds PDFHREF.TEXT \\*[PDFHREF.PREFIX]
-.while d\\$0.\\$1 \{\
-. \\$0.\\$1 "\\$2"
-. shift 2
-. \}
-.\"
-.\" Retrieve the descriptive text from the cross reference data,
-.\" ONLY IF no overriding description has been set by the calling
-.\" "pdfhref" macro invocation.
-.\"
-.if \\n(.$ .if !dPDFHREF.DESC .ds PDFHREF.DESC \\$*
-.\"
-.\" Augment "PDFHREF.TEXT" so the descriptive text will be included
-.\" in the text of the formatted reference
-.\"
-.if dPDFHREF.DESC .as PDFHREF.TEXT " \(lq\\\\*[PDFHREF.DESC]\(rq
-.\"
-.\" Finally, suppress any leading spaces,
-.\" which may have been included in the PDFHREF.TEXT definition.
-.\"
-.ds PDFHREF.TEXT \\*[PDFHREF.TEXT]
-..
-.de pdf*href.format.file
-.\" ----------------------------------------------------------------------
-.\" Include a file identifier in a formatted reference.
-.\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
-.\" reference data includes an initial file identifier tuple.
-.\" ----------------------------------------------------------------------
-.\"
-.as PDFHREF.TEXT " \\*[PDFHREF.FILEREF]
-..
-.de pdf*href.format.page
-.\" ----------------------------------------------------------------------
-.\" Include a page number in a formatted reference.
-.\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
-.\" reference data includes an initial page number tuple.
-.\" ----------------------------------------------------------------------
-.\"
-.as PDFHREF.TEXT " \\*[PDFHREF.PAGEREF]
-..
-.de pdf*href.format.section
-.\" ----------------------------------------------------------------------
-.\" Include a section number in a formatted reference.
-.\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
-.\" reference data includes an initial section number tuple.
-.\" ----------------------------------------------------------------------
-.\"
-.as PDFHREF.TEXT " \\*[PDFHREF.SECTREF]
-..
-.\"
-.\" Make "pdf*href.format" the default cross reference formatter
-.\"
-.als pdf*href.default pdf*href.format
-.\"
-.\"
-.\" Macro "pdf*href" provides a generic mechanism for placing link
-.\" "hot-spots" in a PDF document. ALL "pdfhref" class macros which
-.\" create "hot-spots" are aliased to this macro; each must also have
-.\" an appropriately aliased definition for "pdf*href.template".
-.\"
-.de pdf*href
-.\" ------------------------------------------------------------------
-.\" Usage:
-.\" .pdf*href class [options ...] [link text ...]
-.\" ------------------------------------------------------------------
-.\"
-.\" First, we initialise an empty string, which will be affixed to
-.\" the end of the "link text". (This is needed to cancel the effect
-.\" of a "\c" escape, which is placed at the end of the "link text"
-.\" to support the "-A" option -- any text supplied by the user, when
-.\" the "-A" option is specified, will replace this empty string).
-.\"
-.ds pdf:href-A
-.\"
-.\" Now we interpret, and remove any specified options from the
-.\" argument list. (Note that only options with a declared handler
-.\" will be processed; there is no provision for detecting invalid
-.\" options -- anything which is not recognised is assumed to start
-.\" the "link text" component of the argument list).
-.\"
-.while dpdf:href.opt\\$1 \{\
-. pdf:href.opt\\$1 \\$@
-. shift \\n[pdf:href.argc]
-. \}
-.\"
-.\" If we found "--", to mark the end of the options, then we should
-.\" discard it.
-.\"
-.if '\\$1'--' .shift
-.\"
-.\" All PDF link classes REQUIRE a named destination. This may have
-.\" been supplied using the "-D Name" option, but, if not, deduce it
-.\" from the first "word" in the "link text", if any -- if we still
-.\" can't identify the destination, then set "pdf:href.ok" to zero,
-.\" so this link will not be created.
-.\"
-.if !dpdf:href-D .pdf:href.option -D \\$1
-.if '\\*[pdf:href-D]'' \{\
-. pdf:error pdfhref has no destination
-. nr pdf:href.ok 0
-. \}
-.\"
-.\" Some PDF link classes support a "/File (FilePathName)" argument.
-.\"
-.if dpdf*href.file \{\
-. \"
-. \" When this is supported, it may be specified by supplying
-. \" the "-F FileName" option, which is captured in "pdf:href-F".
-. \"
-. if dpdf:href-F \{\
-. \"
-. \" the /File key is present, so set up the link specification
-. \" to establish the reference to the specified file
-. \"
-. als pdf*href.link pdf*href.file
-. ds pdf:href.files /File (\\*[pdf:href-F])
-. \"
-. \" in addition to the /File key,
-. \" there may also be platform dependent alternate file names
-. \"
-. if dpdf:href-DF .as pdf:href.files " /DOSFile (\\*[pdf:href-DF])
-. if dpdf:href-MF .as pdf:href.files " /MacFile (\\*[pdf:href-MF])
-. if dpdf:href-UF .as pdf:href.files " /UnixFile (\\*[pdf:href-UF])
-. if dpdf:href-WF .as pdf:href.files " /WinFile (\\*[pdf:href-WF])
-. \}
-. \" In some cases, the "/File" key is REQUIRED.
-. \" We will know it is missing, if "pdf*href.link" is not defined.
-. \"
-. if !dpdf*href.link \{\
-. \"
-. \" When a REQUIRED "/File" key specification is not supplied,
-. \" then complain, and set "pdf:href.ok" to abort the creation
-. \" of the current reference.
-. \"
-. pdf:error pdfhref: required -F specification omitted
-. nr pdf:href.ok 0
-. \}
-. \" Now, we have no further use for "pdf*href.file".
-. \"
-. rm pdf*href.file
-. \}
-.\"
-.\" Now, initialise a string, defining the PDFMARK code sequence
-.\" to create the reference, using the appropriate type indicators.
-.\"
-.ds pdf:href.link /Subtype /Link \\*[pdf*href.link]
-.\"
-.\" And now, we have no further use for "pdf*href.link".
-.\"
-.rm pdf*href.link
-.\"
-.\" If the user specified any "link prefix" text, (using the "-P text"
-.\" option), then emit it BEFORE processing the "link text" itself.
-.\"
-.if dpdf:href-P \&\\*[pdf:href-P]\c
-.ie \\n[pdf:href.ok] \{\
-. \"
-. \" This link is VALID (so far as we can determine) ...
-. \" Modify the "link text" argument specification, as required,
-. \" to include any pre-formatted cross reference information
-. \"
-. ie \\n(.$ \{\
-. \"
-. \" One or more "link text" argument(s) are present,
-. \" so, set the link description from the argument(s) ...
-. \"
-. ds PDFHREF.DESC \\\\$*
-. ie \\n[pdf:href-X] \{\
-. \"
-. \" ... and, when the "-X" flag is set,
-. \" also include formatted location information,
-. \" derived from the cross reference record.
-. \"
-. pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
-. \}
-. el \{\
-. \" ... but, when the "-X" flag is NOT set,
-. \" use only the argument(s) as the entire content
-. \" of the "link text"
-. \"
-. rn PDFHREF.DESC PDFHREF.TEXT
-. \}
-. \}
-. el \{\
-. \" No "link text" arguments are present,
-. \" so, format the cross reference record to define
-. \" the content of the "link text".
-. \"
-. pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
-. \}
-. \" Apply border and colour specifications to the PDFMARK string
-. \" definition, as required.
-. \"
-. if dPDFHREF.BORDER .as pdf:href.link " /Border [\\*[PDFHREF.BORDER]]
-. if dPDFHREF.COLOUR .as pdf:href.link " /Color [\\*[PDFHREF.COLOUR]]
-. \"
-. \" Emit the "link text", in its appropriate colour, marking the
-. \" limits of its bounding box(es), as the before and after output
-. \" text positions.
-. \"
-. pdf*href.mark.begin "\\*[pdf:href.link]"
-. if dPDFHREF.COLOUR .defcolor pdf:href.colour rgb \\*[PDFHREF.COLOUR]
-. nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\\*[PDFHREF.TEXT]\m[]\c
-. pdf*href.mark.end
-. \"
-. \" Clean up the temporary registers and strings, used to
-. \" compute the "hot-spot" bounds, and format the reference,
-. \"
-. rm PDFHREF.DESC PDFHREF.TEXT
-. \}
-.\"
-.\" But when we identify an INVALID link ...
-.\" We simply emit the "link text", with no colour change, no border,
-.\" and no associated "hot-spot".
-.\"
-.el \&\\$*\c
-.\"
-.\" And then, if the user specified any affixed text, (using the
-.\" "-A text" option), we tack it on at the end.
-.\"
-.nop \&\\*[pdf:href-A]
-..
-.de pdf*href.map.init
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.\"
-.if dpdf:href.map-1 \{\
-. \"
-. \" We have a reference map, but we haven't started to parse it yet.
-. \" This must be the first map reference in pass 2, so we need to
-. \" "kick-start" the parsing process, by loading the first indexed
-. \" sub-map into the global map.
-. \"
-. rn pdf:href.map-1 pdf:href.map
-. als pdf:href.map.internal pdf:href.map
-. nr pdf:href.map.index 1 1
-. \}
-.als pdf*href.map.init pdf*href.mark.idle
-..
-.\"
-.\" "pdf*href-Z" is used to add link co-ordinate entries to the
-.\" "pdf:href.map". Primarily, it is used by the "pdfroff" formatter,
-.\" to pass link co-ordinate data from one "groff" formatting pass to
-.\" the next, and is not generally useful to the end user.
-.\"
-.de pdf*href-Z
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref Z page-index x-displacement y-displacement
-.\" Where:
-.\" page-index is the reference mark's page number
-.\" x-displacement is its offset from the left edge of the page
-.\" y-displacement is its offset from the top edge of the page
-.\" ( both displacement values are expressed in basic groff units, )
-.\" ( and measured perpendicular to their respective page edges. )
-.\" ----------------------------------------------------------------------
-.\"
-.ie \\n(.$=3 .ds pdf:href.map-\\n+[pdf*href-Z.index] \\$*
-.el .pdf:error pdfhref Z operator expects exactly three arguments
-..
-.\" Initialise the auto-incrementing "pdf*href-Z.index" register,
-.\" to ensure that sub-map numbering starts at 1.
-.\"
-.nr pdf*href-Z.index 0 1
-.\"
-.de pdf*href.map.read
-.\" ----------------------------------------------------------------------
-.\" Usage: (internal use only):
-.\" .pdf*href.map.read co-ordinate name list ...
-.\" ----------------------------------------------------------------------
-.\"
-.\" Reads values from "pdf:href.map" to each named register, in turn
-.\" Reading to "null" discards the corresponding value in "pdf:href.map"
-.\"
-.while \\n(.$ \{\
-. \"
-. \" Loop over all registers named in the argument list,
-. \" assigning values from "pdf:href.map" to each in turn.
-. \"
-. pdf:pop nr pdf:\\$1 pdf:href.map.internal
-. if !dpdf:href.map.internal \{\
-. \"
-. \" We ran out of map references in the current sub-map,
-. \" so move on to the next indexed sub-map, if any.
-. \"
-. if dpdf:href.map-\\n+[pdf:href.map.index] \{\
-. rn pdf:href.map-\\n[pdf:href.map.index] pdf:href.map
-. als pdf:href.map.internal pdf:href.map
-. \}
-. \}
-. \"
-. \" Proceed to the next named co-ordinate, (if any), specified
-. \" in the argument list.
-. \"
-. shift
-. \}
-.\"
-.\" Discard any assignments to a register named "null"
-.\"
-.rr pdf:null
-..
-.de pdf*href.mark.begin
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.pdf*href.map.init
-.ie dpdf:href.map \{\
-. \"
-. \" Once we have established a document reference map,
-. \" then this, and all subsequent calls to "pdf*href.mark.begin",
-. \" may be redirected to the reference mark resolver, and the
-. \" "pdf*href.mark.end" macro has nothing further to do.
-. \"
-. pdf*href.mark.resolve \\$@
-. als pdf*href.mark.begin pdf*href.mark.resolve
-. als pdf*href.mark.end pdf*href.mark.idle
-. \}
-.el \{\
-. \" Since we don't yet have a document reference map, the
-. \" reference mark resolver will not work, in this pass of the
-. \" formatter; this, and all subsequent calls to "pdf*href.mark.begin",
-. \" may be redirected to "pdf*href.mark.end", which is responsible
-. \" for emitting the reference mark data to be incorporated into
-. \" the reference map in a subsequent formatting pass.
-. \"
-. pdf*href.mark.end
-. als pdf*href.mark.begin pdf*href.mark.end
-. \}
-..
-.de pdf*href.mark.resolve
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.ie '\\n(.z'' \{\
-. ds pdf:href.link \\$1
-. nr pdf:urx \\n(.o+\\n(.l
-. pdf*href.map.read spg llx ury epg urx.end lly.end
-. ie \\n[pdf:spg]=\\n[pdf:epg] \{\
-. \"
-. \" This link is entirely contained on a single page ...
-. \" emit the text, which defines the content of the link region,
-. \" then make it active.
-. \"
-. pdf*href.mark.emit 1 \\n[pdf:urx.end]
-. if \\n[pdf:lly]<\\n[pdf:lly.end] \{\
-. \"
-. \" This link spans multiple output lines; we must save its
-. \" original end co-ordinates, then define a new intermediate
-. \" end point, to create a PDFMARK "hot-spot" extending from
-. \" the start of the link to the end if its first line.
-. \"
-. nr pdf:ury +1v
-. nr pdf:llx \\n(.o+\\n[.in]
-. nr pdf:lly \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
-. if \\n[pdf:ury]<\\n[pdf:lly] \{\
-. nr pdf:lly +\\*[PDFHREF.HEIGHT]-1v
-. pdf*href.mark.emit 2
-. nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
-. \}
-. pdf*href.mark.emit 0 \\n[pdf:urx.end]
-. \}
-. pdf*href.mark.flush
-. \}
-. el \{\
-. \" This link is split across a page break, so ...
-. \" We must mark the "hot-spot" region on the current page,
-. \" BEFORE we emit the link text, as we will have moved off
-. \" this page, by the time the text has been output.
-. \"
-. \" First step: define the region from the start of the link,
-. \" to the end of its first line.
-. \"
-. pdf*href.mark.emit 1 \\n[pdf:urx]
-. \"
-. \" All additional regions MUST align with the left margin.
-. \"
-. nr pdf:llx \\n(.o+\\n[.in]
-. \"
-. \" If the current page can accommodate more than the current line,
-. \" then it will include a second active region for this link; this
-. \" will extend from just below the current line to the end of page
-. \" trap, if any, or the bottom of the page otherwise, and occupy
-. \" the full width of the page, between the margins.
-. \"
-. nr pdf:ury +1v
-. pdf*href.mark.emit 3
-. \"
-. \" We now need a page transition trap, to map the active link
-. \" region(s), which overflow on to the following page(s); (the
-. \" handler for this trap MUST have been previously installed).
-. \"
-. ie dpdf*href.mark.hook \{\
-. \"
-. \" The page transition trap handler has been installed,
-. \" so we may activate both it, and also the appropriate
-. \" termination handler, to deactivate it when done.
-. \"
-. als pdf*href.mark.hook pdf*href.mark.trap
-. \"
-. \" Now we set up "pdf:epg" to count the number of page breaks
-. \" which this link will span, and emit the link text, leaving
-. \" the page trap macro to map active regions on intervening
-. \" pages, which are included in the link.
-. \"
-. nr pdf:epg -\\n[pdf:spg] 1
-. \}
-. el \{\
-. \" There was no handler initialised for the page trap,
-. \" so we are unable to map the active regions for this link;
-. \" we may discard the remaining map data for this link,
-. \" and issue a diagnostic.
-. \"
-. pdf:error pdfhref: link dissociated at page break (trap not
initialised)
-. if dPDFHREF.BROKEN.COLOR \{\
-. \"
-. \" The user may opt to have such broken links highlighted.
-. \" We use "PDFHREF.BROKEN.COLOUR" to specify this requirement,
-. \" but the user may prefer the American spelling, so we will
-. \" handle both as equivalent.
-. \"
-. als PDFHREF.BROKEN.COLOUR PDFHREF.BROKEN.COLOR
-. \}
-. if dPDFHREF.BROKEN.COLOUR \{\
-. if dPDFHREF.COLOUR .als PDFHREF.COLOUR PDFHREF.BROKEN.COLOUR
-. \}
-. \}
-. \}
-. \}
-.el \!.\\$0 \\$@
-..
-.\"
-.\" Macro "pdf*href.mark.emit" is called only by "pdf*href". It is
-.\" responsible for emitting the PDFMARK code, to establish the
-.\" "hot-spot" region associated with a document or resource link.
-.\"
-.de pdf*href.mark.emit
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" .pdf*href.mark.emit <action> [<end-urx>]
-.\" <action> == 0 --> normal operation -- link height = 1 line
-.\" <action> == 1 --> start of link -- add leading above text
-.\" <action> == 2 --> overtall link -- set intermediate baseline
-.\" <action> == 3 --> split link -- break at bottom of page
-.\" ----------------------------------------------------------------------
-.\"
-.if \\$1=1 \{\
-. \"
-. \" Initialising a new link region ...
-. \" Some different versions of "groff" disagree about the vertical
-. \" displacement of "opminy", as emitted by "\O1|\h'-\w"|"u'\O2\c",
-. \" relative to the current text baseline. Therefore, recompute
-. \" the link displacement, independently of "opminy".
-. \"
-. mk pdf:ury.base
-. while \\n[pdf:ury.base]<\\n[pdf:ury] .nr pdf:ury.base +1v
-. nr pdf:ury.base -1m+\\n[PDFHREF.LEADING]
-. \"
-. \" adjust the end-point vertical displacement by the same offset,
-. \" and then relocate the link starting point to its new displacement,
-. \" as established by this base line relative computation.
-. \"
-. nr pdf:lly.end +\\n[pdf:ury.base]-\\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
-. rnn pdf:ury.base pdf:ury
-. \}
-.if \\$1<2 \{\
-. \"
-. \" Link segment fits on a single line ...
-. \" Set its height and end-point horizontal displacement accordingly.
-. \"
-. nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
-. if \\n[pdf:lly]>=\\n[pdf:lly.end] .nr pdf:urx \\$2
-. \}
-.ie \\$1=3 \{\
-. \"
-. \" Link segment extends beyond the next page break ...
-. \" Recompute truncated height, to just fit portion on current page,
-. \" recursing to emit it, and leaving page trap mechanism to place
-. \" continuation region(s) on following page(s).
-. \"
-. nr pdf:lly (\\n[.t]u-\\n[.V]u)/1v
-. if \\n[pdf:lly]>0 \{\
-. nr pdf:lly \\n[pdf:ury]+\\n[pdf:lly]v-1v+\\*[PDFHREF.HEIGHT]
-. pdf*href.mark.emit 2
-. \}
-. \}
-.el \{\
-. \" Link region size and placement has been fully specified ...
-. \" Emit it.
-. \"
-. pdfmark \\*[pdf:href.link] /Rect [\\*[pdf:bbox]] /ANN
-. \}
-..
-.\"
-.\" When "pdf*href" emits a link for which the "hot-spot" spans a
-.\" page break, then we need to provide a "hook" in to the page break
-.\" trap, so we can map the "hot-spot" regions which are to be placed
-.\" on either side of the page break.
-.\"
-.\" Macro "pdf*href.mark.idle" is a dummy macro, which provide this
-.\" "hook" for normal page breaks, where there is no link "hot-spot"
-.\" crossing the break.
-.\"
-.de pdf*href.mark.idle
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" Called only as an internal hook, by a page trap macro.
-.\" Expects no arguments, and does nothing.
-.\" ----------------------------------------------------------------------
-..
-.\"
-.\" Macro "pdf*href.mark.trap" is the active "hook", which is substituted
-.\" for "pdf*href,mark.idle" at those page breaks which are crossed by
-.\" a link "hot-spot".
-.\"
-.de pdf*href.mark.trap
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" Called only as an internal hook, by a page trap macro.
-.\" Expects no arguments. Maps residual link "hot-spot" regions,
-.\" which spill beyond any page break. Not to be invoked directly
-.\" by the user, nor by any user supplied macro.
-.\" ----------------------------------------------------------------------
-.\"
-.mk pdf:ury
-.nr pdf:ury +1v-1m-\\n[PDFHREF.LEADING]
-.ie \\n-[pdf:epg] \{\
-. \"
-. \" The link "hot-spot" extends across more than one page break,
-. \" so, for each page which is completely contained within the
-. \" extent of the link, simply mark the entire text area on the
-. \" page as a "hot-spot".
-. \"
-. pdf*href.mark.emit 3
-. \}
-.el \{\
-. \" The link "hot-spot" ends on the page which immediately follows
-. \" the current page transition, so we may now finalise this link.
-. \"
-. nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
-. if \\n[pdf:lly.end]>\\n[pdf:lly] \{\
-. \"
-. \" The "hot-spot" extends beyond the first line of text,
-. \" on its final page; compute and emit "hot-spot" region to cover
-. \" the full with of the text area, including all but the last
-. \" line of the link text.
-. \"
-. while \\n[pdf:lly.end]>\\n[pdf:lly] .nr pdf:lly +1v
-. nr pdf:lly -1v
-. pdf*href.mark.emit 2
-. \"
-. \" Now, adjust the vertical "hot-spot" mapping reference,
-. \" to identify the correct position for the last line of
-. \" text, over which the "hot-spot" extends.
-. \"
-. nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
-. \}
-. \"
-. \" We now have exactly one final line of text, over which we must
-. \" emit a "hot-spot" region; map it, terminate page trap processing
-. \" for this "hot-spot", and clean up the "hot-spot" mapping context.
-. \"
-. pdf*href.mark.emit 0 \\n[pdf:urx.end]
-. als pdf*href.mark.hook pdf*href.mark.idle
-. pdf*href.mark.flush
-. \}
-..
-.de pdf*href.mark.flush
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-.rr pdf:spg pdf:epg
-.rr pdf:llx pdf:lly pdf:urx pdf:ury
-.if dPDFHREF.COLOR .als PDFHREF.COLOUR PDFHREF.COLOR
-.rr pdf:urx.end pdf:lly.end
-..
-.de pdf*href.mark.end
-.\" ----------------------------------------------------------------------
-.\" ----------------------------------------------------------------------
-\O1\Z'|'\O2\c
-..
-.\" Macro "pdf*href-I" is used for one time initialisation of special
-.\" "pdfhref" features; (currently, only the above page trap hook is
-.\" supported, but it is implemented with one level of indirection, to
-.\" accommodate possible future expansion).
-.
-.de pdf*href-I
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref I -<option> <optarg> [-<option> <optarg>] ...
-.\" ----------------------------------------------------------------------
-.\"
-.\" Loop over all arguments, in pairs ...
-.
-.while \\n(.$ \{\
-. \"
-. \" handing them off to their respective initialisers,
-. \" when suitable initialisers exist, or complaining otherwise.
-. \"
-. ie dpdf*href\\$1.init .pdf*href\\$1.init \\$2
-. el .pdf*error pdfhref:init: unknown feature '\\$1'
-. shift 2
-. \}
-..
-.\" Before we can use the page break "hook", we need to initialise it
-.\" as an addendum to a regular page break trap. To ensure that we don't
-.\" compromise the user's page trap setup, we leave the onus for this
-.\" initialisation with the user, but we provide the "pdf*href-PT.init"
-.\" macro, (invoked by ".pdfhref I -PT <macro-name>"), to implement a
-.\" suitable initialisation action.
-.
-.de pdf*href-PT.init
-.\" ----------------------------------------------------------------------
-.\" Usage:
-.\" .pdfhref I -PT <macro-name>
-.\" <macro-name> == name of user's page break trap macro
-.\" ----------------------------------------------------------------------
-.\"
-.\" Initially, map the page break hook to its default, do nothing helper.
-.
-.als pdf*href.mark.hook pdf*href.mark.idle
-.ie !\\n(.$ \{\
-. \"
-. \" Don't have enough arguments to specify a page trap macro name,
-. \" so simply plant "pdf*href.mark.hook" as a top of page trap.
-. \"
-. wh 0 pdf*href.mark.hook
-. \}
-.el \{\
-. \" Page trap macro name is specified in "\\$1" ...
-. \"
-. ie d\\$1 \{\
-. \"
-. \" When this page trap macro already exists, then we simply
-. \" append a call to "pdf*href.mark.hook" to it.
-. \"
-. am \\$1 pdf*href.mark.idle
-. pdf*href.mark.hook
-. pdf*href.mark.idle
-. \}
-. el \{\
-. \" However, when the specified page trap macro does not yet
-. \" exist, then we create it, and plant it as a top of page
-. \" trap.
-. \"
-. de \\$1 pdf*href.mark.idle
-. pdf*href.mark.hook
-. pdf*href.mark.idle
-. wh 0 \\$1
-. \}
-. \}
-..
-.
-.\" "pdf*href-L" is the generic handler for creating references to
-.\" named destinations in PDF documents. It supports both local
-.\" references, to locations within the same document, through its
-.\" "pdf*href-L.link" attribute, and also references to locations
-.\" in any other PDF document, through "pdf*href-L.file".
-.\"
-.als pdf*href-L pdf*href
-.ds pdf*href-L.link /Dest /\\\\*[pdf:href-D]
-.ds pdf*href-L.file /Action /GoToR \\\\*[pdf:href.files] \\*[pdf*href-L.link]
-.\"
-.\" "pdf*href-O" is the "official" handler for creating PDF
-.\" document outlines. It is simply an alias to "pdfbookmark",
-.\" which may also be invoked directly, if preferred. Neither
-.\" a "pdf*href-O.link" nor a "pdf*href-O.file" attribute is
-.\" required.
-.\"
-.als pdf*href-O pdfbookmark
-.\"
-.\" "pdf*href-W" is the generic handler for creating references to
-.\" web resources, (or any resource specified by a uniform resource
-.\" identifier). Such resource links are fully specified by the
-.\" "pdf*href-W.link" attribute.
-.\"
-.als pdf*href-W pdf*href
-.ds pdf*href-W.link /Action << /Subtype /URI /URI (\\\\*[pdf:href-D]) >>
-.\"
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-.\" vim: filetype=groff:
-.\" pdfmark.tmac: end of file
diff --git a/contrib/pdfmark/pdfroff.1.man b/contrib/pdfmark/pdfroff.1.man
deleted file mode 100644
index 1f2b8a0d4..000000000
--- a/contrib/pdfmark/pdfroff.1.man
+++ /dev/null
@@ -1,985 +0,0 @@
-.TH pdfroff @MAN1EXT@ "@MDATE@" "groff @VERSION@"
-.SH Name
-pdfroff \- construct files in Portable Document Format using
-.I groff
-.
-.
-.\" ====================================================================
-.\" Legal Terms
-.\" ====================================================================
-.\"
-.\" Copyright (C) 2005-2020 Free Software Foundation, Inc.
-.\"
-.\" This file is part of groff, the GNU roff type-setting system.
-.\"
-.\" Permission is granted to copy, distribute and/or modify this
-.\" document under the terms of the GNU Free Documentation License,
-.\" Version 1.3 or any later version published by the Free Software
-.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
-.\" and with no Back-Cover Texts.
-.\"
-.\" A copy of the Free Documentation License is included as a file
-.\" called FDL in the main directory of the groff source package.
-.
-.
-.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
-.do nr *groff_pdfroff_1_man_C \n[.cp]
-.cp 0
-.
-.\" Define fallback for groff 1.23's MR macro if the system lacks it.
-.nr do-fallback 0
-.if !\n(.f .nr do-fallback 1 \" mandoc
-.if \n(.g .if !d MR .nr do-fallback 1 \" older groff
-.if !\n(.g .nr do-fallback 1 \" non-groff *roff
-.if \n[do-fallback] \{\
-. de MR
-. ie \\n(.$=1 \
-. I \%\\$1
-. el \
-. IR \%\\$1 (\\$2)\\$3
-. .
-.\}
-.rr do-fallback
-.
-.
-.\" ====================================================================
-.SH Synopsis
-.\" ====================================================================
-.
-.SY pdfroff
-.RI [ groff-option ]
-.RB [ \-\-emit\-ps ]
-.RB [ \-\-no\-toc\-relocation ]
-.RB [ \-\-no\-kill\-null\-pages ]
-.RB [ \-\-stylesheet=\c
-.IR name ]
-.RB [ \-\-no\-pdf\-output ]
-.RB [ \-\-pdf\-output=\c
-.IR name ]
-.RB [ \-\-no\-reference\-dictionary ]
-.RB [ \-\-reference\-dictionary=\c
-.IR name ]
-.RB [ \-\-report\-progress ]
-.RB [ \-\-keep\-temporary\-files ]
-.RI [ file\~ .\|.\|.]
-.YS
-.
-.
-.P
-.SY pdfroff
-.B \-h
-.YS
-.
-.SY pdfroff
-.B \-\-help
-.YS
-.
-.
-.P
-.SY pdfroff
-.B \-v
-.RI [ groff-option
-\&.\|.\|.\&]
-.YS
-.
-.SY pdfroff
-.B \%\-\-version
-.RI [ groff-option
-\&.\|.\|.\&]
-.YS
-.
-.
-.P
-.I groff-option
-is any short option supported by
-.MR groff @MAN1EXT@
-except for
-.BR \-h ,
-.BR \-T ,
-and
-.BR \-v ;
-see section \[lq]Usage\[rq] below.
-.
-.
-.\" ====================================================================
-.SH Description
-.\" ====================================================================
-.
-.I pdfroff
-is a wrapper program for the GNU text processing system,
-.IR groff .
-.
-It transparently handles the mechanics of multiple pass
-.I groff
-processing,
-when applied to suitably marked up
-.I groff
-source files,
-such that tables of contents and body text are formatted separately,
-and are subsequently combined in the correct order,
-for final publication as a single PDF document.
-.
-A further optional \[lq]style sheet\[rq] capability is provided;
-this allows for the definition of content which is required to precede
-the table of contents,
-in the published document.
-.
-.
-.P
-For each invocation of
-.IR pdfroff ,
-the ultimate
-.I groff
-output stream is post-processed by the Ghostscript
-.MR gs 1
-interpreter to produce a finished PDF document.
-.
-.
-.P
-.I pdfroff
-makes no assumptions about,
-and imposes no restrictions on,
-the use of any
-.I groff
-macro packages which the user may choose to employ,
-in order to achieve a desired document format;
-however,
-it
-.I does
-include specific built in support for the
-.I \%pdfmark
-macro package,
-should the user choose to employ it.
-.
-Specifically,
-if the
-.I pdfhref
-macro,
-defined in the
-.I \%pdfmark.tmac
-package,
-is used to define public reference marks,
-or dynamic links to such reference marks,
-then
-.I pdfroff
-performs as many preformatting
-.I groff
-passes as required,
-up to a maximum limit of
-.IR four ,
-in order to compile a document reference dictionary,
-to resolve
-references,
-and to expand the dynamically defined content of links.
-.
-.
-.\" ====================================================================
-.SH Usage
-.\" ====================================================================
-.
-The command line is parsed in accordance with normal GNU conventions,
-but with one exception\(emwhen specifying any short form option
-(i.e.,
-a single character option introduced by a single hyphen),
-and if that option expects an argument,
-then it
-.I must
-be specified independently
-(i.e.,
-it may
-.I not
-be appended to any group of other single character short form options).
-.
-.
-.P
-Long form option names
-(i.e.,
-those introduced by a double hyphen)
-may
-be abbreviated to their minimum length unambiguous initial substring.
-.
-.
-.P
-Otherwise,
-.I pdfroff
-usage closely mirrors that of
-.I groff
-itself.
-.
-Indeed,
-with the exception of the
-.BR \-h ,
-.BR \-v ,
-and
-.BI \-T \ dev
-short form options,
-and all long form options,
-which are parsed
-internally by
-.IR pdfroff ,
-all options and file name arguments specified on the command line are
-passed on to
-.IR groff ,
-to control the formatting of the PDF document.
-.
-Consequently,
-.I pdfroff
-accepts all options and arguments,
-as specified in
-.MR groff @MAN1EXT@ ,
-which may also be considered as the definitive reference for all
-standard
-.I pdfroff
-options and argument usage.
-.
-.
-.\" ====================================================================
-.SH Options
-.\" ====================================================================
-.
-.I pdfroff
-accepts all of the short form options
-(i.e.,
-those introduced by a
-single hyphen),
-which are available with
-.I groff
-itself.
-.
-In most cases,
-these are simply passed transparently to
-.IR groff ;
-the following,
-however,
-are handled specially by
-.IR pdfroff .
-.
-.
-.TP
-.B \-h
-Same as
-.BR \-\-help ;
-see below.
-.
-.
-.TP
-.B \-i
-Process standard input,
-after all other specified input files.
-.
-This is passed transparently to
-.IR groff ,
-but,
-if grouped with other options,
-it
-.I must
-be the first in the group.
-.
-Hiding it within a group breaks standard input processing,
-in the multiple-pass
-.I groff
-processing context of
-.IR pdfroff .
-.
-.
-.TP
-.BI \-T \ dev
-Only
-.B \-T\ ps
-is supported by
-.IR pdfroff .
-.
-Attempting to specify any other device causes
-.I pdfroff
-to abort.
-.
-.
-.TP
-.B \-v
-Same as
-.BR \%\-\-version ;
-see below.
-.
-.
-.P
-See
-.MR groff @MAN1EXT@
-for a description of all other short form options,
-which are
-transparently passed through
-.I pdfroff
-to
-.IR groff .
-.
-.
-.P
-All long form options
-(i.e.,
-those introduced by a double hyphen)
-are interpreted locally by
-.IR pdfroff ;
-they are
-.I not
-passed on to
-.IR groff ,
-unless otherwise stated below.
-.
-.
-.TP
-.B \-\-help
-Causes
-.I pdfroff
-to display a summary of the its usage syntax,
-and supported options,
-and then exit.
-.
-.
-.TP
-.B \-\-emit\-ps
-Suppresses the final output conversion step,
-causing
-.I pdfroff
-to emit PostScript output instead of PDF.
-.
-This may be useful to capture intermediate PostScript output when using
-a specialised postprocessor,
-such as
-.I gpresent
-for example,
-in place of the default Ghostscript PDF writer.
-.
-.
-.TP
-.B \-\-keep\-temporary\-files
-Suppresses the deletion of temporary files,
-which normally occurs
-after
-.I pdfroff
-has completed PDF document formatting;
-this may be useful when debugging formatting problems.
-.
-.
-.IP
-See section \[lq]Files\[rq] below for a description of the temporary
-files used by
-.IR pdfroff .
-.
-.
-.TP
-.B \-\-no\-pdf\-output
-May be used with the
-.BI \%\-\-reference\-dictionary= name
-option
-(described below)
-to eliminate the overhead of PDF formatting when running
-.I pdfroff
-to create a reference dictionary for use in a different document.
-.
-.
-.TP
-.B \-\-no\-reference\-dictionary
-May be used to eliminate the overhead of creating a reference
-dictionary,
-when it is known that the target PDF document contains no public
-references,
-created by the
-.B pdfhref
-macro.
-.
-.
-.TP
-.B \-\-no\-toc\-relocation
-May be used to eliminate the extra
-.I groff
-processing pass,
-which is required to generate a table of contents,
-and relocate it to the start of the PDF document,
-when processing any document which lacks an automatically
-generated table of contents.
-.
-.
-.TP
-.B \-\-no\-kill\-null\-pages
-While preparing for simulation of the manual collation step,
-which is traditionally required to relocate a
-.I "table of contents"
-to the start of a document,
-.I pdfroff
-accumulates a number of empty page descriptions
-into the intermediate PostScript output stream.
-.
-During the final collation step,
-these empty pages are normally discarded from the finished document;
-this option forces
-.I pdfroff
-to leave them in place.
-.
-.
-.TP
-.BI \-\-pdf\-output= name
-Specifies the name to be used for the resultant PDF document;
-if unspecified,
-the PDF output is written to standard output.
-.
-A future version of
-.I pdfroff
-may use this option,
-to encode the document name in a generated reference dictionary.
-.
-.
-.TP
-.BI \-\-reference\-dictionary= name
-Specifies the name to be used for the generated reference dictionary
-file;
-if unspecified,
-the reference dictionary is created in a temporary file,
-which is deleted when
-.I pdfroff
-completes processing of the current document.
-.
-This option
-.I must
-be specified,
-if it is desired to save the reference dictionary,
-for use in references placed in other PDF documents.
-.
-.
-.TP
-.B \-\-report\-progress
-Causes
-.I pdfroff
-to display an informational message on standard error,
-at the start of each
-.I groff
-processing pass.
-.
-.
-.TP
-.BI \-\-stylesheet= name
-Specifies the name of an
-.IR "input file" ,
-to be used as a style sheet for formatting of content,
-which is to be placed
-.I before
-the table of contents,
-in the formatted PDF document.
-.
-.
-.TP
-.B \%\-\-version
-Causes
-.I pdfroff
-to display a version identification message.
-.
-The entire command line is then passed transparently to
-.IR groff ,
-in a
-.I one
-pass operation
-.IR only ,
-in order to display the associated
-.I groff
-version information,
-before exiting.
-.
-.
-.\" ====================================================================
-.SH Environment
-.\" ====================================================================
-.
-The following environment variables may be set,
-and exported,
-to modify the behaviour of
-.IR pdfroff .
-.
-.
-.TP
-.I PDFROFF_COLLATE
-Specifies the program to be used
-for collation of the finished PDF document.
-.
-.
-.IP
-This collation step may be required to move
-.I tables of contents
-to the start of the finished PDF document,
-when formatting with traditional macro packages,
-which print them at the end.
-.
-However,
-users should not normally need to specify
-.IR \%PDFROFF_COLLATE ,
-(and indeed,
-are not encouraged to do so).
-.
-If unspecified,
-.I pdfroff
-uses
-.MR sed @MAN1EXT@
-by default,
-which normally suffices.
-.
-.
-.IP
-If
-.I \%PDFROFF_COLLATE
-.I is
-specified,
-then it must act as a filter,
-accepting a list of file name arguments,
-and write its output to the standard output stream,
-whence it is piped to the
-.IR \%PDFROFF_POSTPROCESSOR_COMMAND ,
-to produce the finished PDF output.
-.
-.
-.IP
-When specifying
-.IR \%PDFROFF_COLLATE ,
-it is normally necessary to also specify
-.IR \%PDFROFF_KILL_NULL_PAGES .
-.
-.
-.IP
-.I \%PDFROFF_COLLATE
-is ignored,
-if
-.I pdfroff
-is invoked with the
-.B \%\-\-no\-kill\-null\-pages
-option.
-.
-.
-.TP
-.I PDFROFF_KILL_NULL_PAGES
-Specifies options to be passed to the
-.I \%PDFROFF_COLLATE
-program.
-.
-.
-.IP
-It should not normally be necessary to specify
-.IR \%PDFROFF_KILL_NULL_PAGES .
-.
-The internal default is a
-.MR sed @MAN1EXT@
-script,
-which is intended to remove completely blank pages
-from the collated output stream,
-and which should be appropriate in most applications of
-.IR pdfroff .
-.
-However,
-if any alternative to
-.MR sed @MAN1EXT@
-is specified for
-.IR \%PDFROFF_COLLATE ,
-then it is likely that a corresponding alternative specification for
-.I \%PDFROFF_KILL_NULL_PAGES
-is required.
-.
-.
-.IP
-As in the case of
-.IR \%PDFROFF_COLLATE ,
-.I \%PDFROFF_KILL_NULL_PAGES
-is ignored,
-if
-.I pdfroff
-is invoked with the
-.B \%\-\-no\-kill\-null\-pages
-option.
-.
-.
-.TP
-.I PDFROFF_POSTPROCESSOR_COMMAND
-Specifies the command to be used for the final document conversion
-from PostScript intermediate output to PDF.
-.
-It must behave as a filter,
-writing its output to the standard output stream,
-and must accept an arbitrary number of
-.I files .\|.\|.\&
-arguments,
-with the special case of
-.RB \[lq] \- \[rq]
-representing the standard input stream.
-.
-.
-.IP
-If unspecified,
-.I \%PDFROFF_POSTPROCESSOR_COMMAND
-defaults to
-.
-.RS 12n
-.EX
-gs \-dBATCH \-dQUIET \-dNOPAUSE \-dSAFER \-sDEVICE=pdfwrite \e
- \-sOutputFile=\-
-.EE
-.RE
-.
-.
-.TP
-.I GROFF_TMPDIR
-Identifies the directory in which
-.I pdfroff
-should create temporary files.
-.
-If
-.I \%GROFF_TMPDIR
-is
-.I not
-specified,
-then the variables
-.IR TMPDIR ,
-.I TMP
-and
-.I TEMP
-are considered in turn as possible temporary file repositories.
-.
-If none of these are set,
-then temporary files are created
-in the current directory.
-.
-.
-.TP
-.I GROFF_GHOSTSCRIPT_INTERPRETER
-Specifies the program to be invoked when
-.I pdfroff
-converts
-.I groff
-PostScript output to PDF.
-.
-If
-.I \%PDFROFF_POSTPROCESSOR_COMMAND
-is specified,
-then the command name it specifies is
-.I implicitly
-assigned to
-.IR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
-overriding any explicit setting specified in the environment.
-.
-If
-.I \%GROFF_GHOSTSCRIPT_INTERPRETER
-is not specified,
-then
-.I pdfroff
-searches the process
-.IR PATH ,
-looking for a program with any of the well known names
-for the Ghostscript interpreter;
-if no Ghostscript interpreter can be found,
-.I pdfroff
-aborts.
-.
-.
-.TP
-.I GROFF_AWK_INTERPRETER
-Specifies the program to be invoked when
-.I pdfroff
-is extracting reference dictionary entries from a
-.I groff
-intermediate message stream.
-.
-If
-.I \%GROFF_AWK_INTERPRETER
-is not specified,
-then
-.I pdfroff
-searches the process
-.IR PATH ,
-looking for any of the preferred programs,
-.IR gawk ,
-.IR mawk ,
-.IR nawk ,
-and
-.IR awk ,
-in that order;
-if none of these are found,
-.I pdfroff
-issues a warning message,
-and continue processing;
-however,
-in this case,
-no reference dictionary is created.
-.
-.
-.TP
-.I OSTYPE
-Typically defined automatically by the operating system,
-.I \%OSTYPE
-is used on Microsoft Win32/MS-DOS platforms
-.IR only ,
-to infer the default
-.I \%PATH_SEPARATOR
-character,
-which is used when parsing the process
-.I PATH
-to search for external helper programs.
-.
-.
-.TP
-.I PATH_SEPARATOR
-If set,
-.I \%PATH_SEPARATOR
-overrides the default separator character,
-(\[oq]:\[cq] on POSIX/Unix systems,
-inferred from
-.I \%OSTYPE
-on Microsoft Win32/MS-DOS),
-which is used when parsing the process
-.I PATH
-to search for external helper programs.
-.
-.
-.TP
-.I SHOW_PROGRESS
-If this is set to a non-empty value,
-then
-.I pdfroff
-always behaves as if the
-.B \%\-\-report\-progress
-option is specified on the command line.
-.
-.
-.\" ====================================================================
-.SH Files
-.\" ====================================================================
-.
-Input and output files for
-.I pdfroff
-may be named according to any convention of the user's choice.
-.
-Typically,
-input files may be named according to the choice of the principal
-normatting macro package,
-e.g.,
-.RI file .ms
-might be an input file for formatting using the
-.I ms
-macros
-.RI ( s.tmac );
-normally,
-the final output file should be named
-.RI file .pdf .
-.
-.
-.P
-Temporary files created by
-.I pdfroff
-are placed in the file system hierarchy,
-in or below the directory specified by environment variables
-(see section \[lq]Environment\[rq] above).
-.
-If
-.MR mktemp @MAN1EXT@
-is available,
-it is invoked to create a private subdirectory of
-the nominated temporary files directory,
-(with subdirectory name derived from the template
-.IR pdfroff\-XXXXXXXXXX );
-if this subdirectory is successfully created,
-the temporary files will be placed within it,
-otherwise they will be placed directly in the directory
-nominated in the environment.
-.
-.
-.P
-All temporary files themselves
-are named according to the convention
-.IR pdf $$ . *,
-where
-.I $$
-is the standard shell variable representing the process identifier of
-the
-.I pdfroff
-process itself,
-and
-.I *
-represents any of the extensions used by
-.I pdfroff
-to identify the following temporary and intermediate files.
-.
-.
-.TP
-.IR pdf $$ .tmp
-A scratch pad file,
-used to capture reference data emitted by
-.IR groff ,
-during the
-.I reference dictionary
-compilation phase.
-.
-.
-.TP
-.IR pdf $$ .ref
-The
-.IR "reference dictionary" ,
-as compiled in the last but one pass of the
-.I reference dictionary
-compilation phase;
-(at the start of the first pass,
-this file is created empty;
-in successive passes,
-it contains the
-.I reference dictionary
-entries,
-as collected in the preceding pass).
-.
-.
-.IP
-If the
-.BR \%\-\-reference\-dictionary =\c
-.I name
-option is specified,
-this intermediate file becomes permanent,
-and is named
-.IR name ,
-rather than
-.IR pdf $$ .ref .
-.
-.
-.TP
-.IR pdf $$ .cmp
-Used to collect
-.I reference dictionary
-entries during the active pass of the
-.I reference dictionary
-compilation phase.
-.
-At the end of any pass,
-when the content of
-.IR pdf $$ .cmp
-compares as identical to
-.IR pdf $$ .ref ,
-(or the corresponding file named by the
-.BR \%\-\-reference\-dictionary =\c
-.I name
-option),
-then
-.I reference dictionary
-compilation is terminated,
-and the
-.I document reference map
-is appended to this intermediate file,
-for inclusion in the final formatting passes.
-.
-.
-.TP
-.IR pdf $$ .tc
-An intermediate
-.I PostScript
-file,
-in which \[lq]Table of Contents\[rq] entries are collected,
-to facilitate relocation before the body text,
-on ultimate output to the
-.I Ghostscript
-postprocessor.
-.
-.
-.TP
-.IR pdf $$ .ps
-An intermediate
-.I PostScript
-file,
-in which the body text is collected prior to ultimate output to the
-.I Ghostscript
-postprocessor,
-in the proper sequence,
-.I after
-.IR pdf $$ .tc .
-.
-.
-.\" ====================================================================
-.SH Authors
-.\" ====================================================================
-.
-.I pdfroff
-was written by
-.MT keith\:.d\:.marshall@\:ntlworld\:.com
-Keith Marshall
-.ME ,
-who maintains it at
-.UR https://\:osdn\:.net/\:users/\:keith/\:pf/\:\%groff\-pdfmark/\
-\:wiki/\:\%FrontPage
-his
-.I groff-pdfmark
-OSDN site
-.UE .
-.
-.IR groff 's
-version may be withdrawn in a future release.
-.
-.
-.\" ====================================================================
-.SH "See also"
-.\" ====================================================================
-.
-.IR "Groff: The GNU Implementation of troff" ,
-by Trent A.\& Fisher and Werner Lemberg,
-is the primary
-.I groff
-manual.
-.
-You can browse it interactively with \[lq]info groff\[rq].
-.
-.
-.P
-Since
-.I pdfroff
-provides a superset of all
-.I groff
-capabilities,
-the above manual,
-or its terser reference page,
-.MR groff @MAN7EXT@
-may also be considered definitive references to all
-.I standard
-capabilities of
-.IR pdfroff ,
-with this document providing the reference to
-.IR pdfroff 's
-extended features.
-.
-.
-.P
-While
-.I pdfroff
-imposes neither any restriction on,
-nor any requirement for,
-the use of any specific
-.I groff
-macro package,
-a number of supplied macro packages,
-and in particular those associated with the package
-.IR \%pdfmark.tmac ,
-are best suited for use with
-.I pdfroff
-as the preferred formatter.
-.
-.
-.TP
-.I @PDFDOCDIR@/\:\%pdfmark.pdf
-\[lq]Portable Document Format Publishing with GNU
-.IR Troff \[rq],
-by Keith Marshall,
-offers detailed documentation on the use of these packages.
-.
-This file,
-together with its source,
-.IR \%pdfmark.ms ,
-is part of the
-.I groff
-distribution.
-.
-.
-.\" Restore compatibility mode (for, e.g., Solaris 10/11).
-.cp \n[*groff_pdfroff_1_man_C]
-.do rr *groff_pdfroff_1_man_C
-.
-.
-.\" Local Variables:
-.\" fill-column: 72
-.\" mode: nroff
-.\" End:
-.\" vim: set filetype=groff textwidth=72:
diff --git a/contrib/pdfmark/pdfroff.sh b/contrib/pdfmark/pdfroff.sh
deleted file mode 100644
index 5c41559e7..000000000
--- a/contrib/pdfmark/pdfroff.sh
+++ /dev/null
@@ -1,682 +0,0 @@
-#!/bin/sh
-#
------------------------------------------------------------------------------
-#
-# Function: Format PDF Output from groff Markup
-#
-# Copyright (C) 2005-2021 Free Software Foundation, Inc.
-# Written by Keith Marshall (keith.d.marshall@ntlworld.com)
-#
-# 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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.
-#
-#
------------------------------------------------------------------------------
-#
-# Set up an identifier for the NULL device.
-# In most cases "/dev/null" will be correct, but some shells on
-# MS-DOS/MS-Windows systems may require us to use "NUL".
-#
- NULLDEV="/dev/null"
- test -c $NULLDEV || NULLDEV="NUL"
-#
-# Set up the command name to use in diagnostic messages.
-# (We can't assume we have 'basename', so use the full path if required.
-# Also use the 'exec 2>...' workaround for a bug in Cygwin's 'ash').
-#
- CMD=`exec 2>$NULLDEV; basename $0` || CMD=$0
-#
-# To ensure that prerequisite helper programs are available, and are
-# executable, a [fairly] portable method of detecting such programs is
-# provided by function 'searchpath'.
-#
- searchpath(){
- #
- # Usage: searchpath progname path
- #
- IFS=${PATH_SEPARATOR-":"} prog=':'
- for dir in $2
- do
- for ext in '' '.exe'
- #
- # try 'progname' with all well known extensions
- # (e.g. Win32 may require 'progname.exe')
- #
- do
- try="$dir/$1$ext"
- test -f "$try" && test -x "$try" && prog="$try" && break
- done
- test "$prog" = ":" || break
- done
- echo "$prog"
- }
-# @PATH_SEARCH_SETUP@
-#
-# If the system maps '/bin/sh' to some 'zsh' implementation,
-# then we may need this hack, adapted from autoconf code.
-#
- test x${ZSH_VERSION+"set"} = x"set" && NULLCMD=":" \
- && (emulate sh) >$NULLDEV 2>&1 && emulate sh
-#
-# We need both 'grep' and 'sed' programs, to parse script options,
-# and we also need 'cat', to display help and some error messages,
-# so ensure they are all installed, before we continue.
-#
- CAT=`searchpath cat "$PATH"`
- GREP=`searchpath grep "$PATH"`
- SED=`searchpath sed "$PATH"`
-#
-# Another fundamental requirement is the 'groff' program itself;
-# we MUST use a 'groff' program located in 'GROFF_BIN_DIR', if this
-# is specified; if not, we will search 'GROFF_BIN_PATH', only falling
-# back to a 'PATH' search, if neither of these is specified.
-#
- if test -n "$GROFF_BIN_DIR"
- then
- GPATH=GROFF_BIN_DIR
- GROFF=`searchpath groff "$GROFF_BIN_DIR"`
-#
- elif test -n "$GROFF_BIN_PATH"
- then
- GPATH=GROFF_BIN_PATH
- GROFF=`searchpath groff "$GROFF_BIN_PATH"`
-#
- else
- GPATH=PATH
- GROFF=`searchpath groff "$PATH"`
- fi
-#
-# If one or more of these is missing, diagnose and bail out.
-#
- NO='' NOPROG="$CMD: installation problem: cannot find program"
- test "$CAT" = ":" && echo >&2 "$NOPROG 'cat' in PATH" && NO="$NO 'cat'"
- test "$GREP" = ":" && echo >&2 "$NOPROG 'grep' in PATH" && NO="$NO 'grep'"
- test "$GROFF" = ":" && echo >&2 "$NOPROG 'groff' in $GPATH" && NO="$NO
'groff'"
- test "$SED" = ":" && echo >&2 "$NOPROG 'sed' in PATH" && NO="$NO 'sed'"
- if test -n "$NO"
- then
- set $NO
- test $# -gt 1 && NO="s" IS="are" || NO='' IS="is"
- while test $# -gt 0
- do
- test $# -gt 2 && NO="$NO $1,"
- test $# -eq 2 && NO="$NO $1 and" && shift
- test $# -lt 2 && NO="$NO $1"
- shift
- done
- $CAT >&2 <<-ETX
-
- *** FATAL INSTALLATION ERROR ***
-
- The program$NO $IS required by '$CMD',
- but cannot be found; '$CMD' is unable to continue.
-
- ETX
- exit 1
- fi
-#
-# Identify the postprocessor command, for writing PDF output.
-# (May be forced, by defining PDFROFF_POSTPROCESSOR_COMMAND in the environment;
-# if this is not set, leave blank to use the built in default).
-#
- if test -n "${PDFROFF_POSTPROCESSOR_COMMAND}"
- then
- GROFF_GHOSTSCRIPT_INTERPRETER=`set command
${PDFROFF_POSTPROCESSOR_COMMAND};
- echo $2`
- fi
-#
-# Set up temporary/intermediate file locations, with traps to
-# clean them up on exit. Note that, for greater portability, we
-# prefer to refer to events by number, rather than by symbolic
-# names; thus, the EXIT event is trapped as event zero.
-#
- export TMPDIR GROFF_TMPDIR
- TMPDIR=${GROFF_TMPDIR=${TMPDIR-${TMP-${TEMP-"."}}}}
- if GROFF_TMPDIR=`exec 2>${NULLDEV}; mktemp -dt pdfroff-XXXXXXXXXX`
- then
- #
- # We successfully created a private temporary directory,
- # so to clean up, we may simply purge it.
- #
- trap "rm -rf ${GROFF_TMPDIR}" 0
- #
- else
- #
- # Creation of a private temporary directory was unsuccessful;
- # fall back to user nominated directory, (using current directory
- # as default), and schedule removal of only the temporary files.
- #
- GROFF_TMPDIR=${TMPDIR}
- trap "rm -f ${GROFF_TMPDIR}/pdf$$.*" 0
- fi
- #
- # In the case of abnormal termination events, we force an exit
- # (with status code '1'), leaving the normal exit trap to clean
- # up the temporary files, as above. Note that we again prefer
- # to refer to events by number, rather than by symbolic names;
- # here we trap SIGHUP, SIGINT, SIGQUIT, SIGPIPE and SIGTERM.
- #
- trap "exit 1" 1 2 3 13 15
-#
- WRKFILE=${GROFF_TMPDIR}/pdf$$.tmp
-#
- REFCOPY=${GROFF_TMPDIR}/pdf$$.cmp
- REFFILE=${GROFF_TMPDIR}/pdf$$.ref
-#
- CS_DATA=""
- TC_DATA=${GROFF_TMPDIR}/pdf$$.tc
- BD_DATA=${GROFF_TMPDIR}/pdf$$.ps
-#
-# Initialise 'groff' format control settings,
-# to discriminate table of contents and document body formatting passes.
-#
- TOC_FORMAT="-rPHASE=1"
- BODY_FORMAT="-rPHASE=2"
-#
- LONGOPTS="
- help reference-dictionary no-reference-dictionary
- stylesheet pdf-output no-pdf-output
- version report-progress no-toc-relocation
- emit-ps keep-temporary-files no-kill-null-pages
- "
-# Parse the command line, to identify 'pdfroff' specific options.
-# Collect all other parameters into new argument and file lists,
-# to be passed on to 'groff', enforcing the '-Tps' option.
-#
- DIFF="" STREAM="" INPUT_FILES=""
- SHOW_VERSION="" GROFF_STYLE="$GROFF -Tps"
- while test $# -gt 0
- do
- case "$1" in
-#
-# Long options must be processed locally ...
-#
- --*)
-#
-# First identify, matching any abbreviation to its full form.
-#
- MATCH="" OPTNAME=`IFS==; set dummy $1; echo $2`
- for OPT in $LONGOPTS
- do
- MATCH="$MATCH"`echo --$OPT | $GREP "^$OPTNAME"`
- done
-#
-# For options in the form --option=value
-# capture any specified value into $OPTARG.
-#
- OPTARG=`echo $1 | $SED -n s?"^${OPTNAME}="??p`
-#
-# Perform case specific processing for matched option ...
-#
- case "$MATCH" in
-
- --help)
- $CAT <<-ETX
- Usage: $CMD [-option ...] [--long-option ...] [file ...]
-
- Options:
- -h
- --help
- Display this usage summary, and exit.
-
- -v
- --version
- Display a version identification message and exit.
-
- --report-progress
- Enable console messages, indicating the progress of the
- PDF document formatting process.
-
- --emit-ps
- Emit PostScript output instead of PDF; this may be
useful
- when the ultimate PDF output is to be generated by a
more
- specialised postprocessor, (e.g. gpresent), rather than
- the default GhostScript PDF writer.
-
- --pdf-output=name
- Write the PDF, (or PostScript), output stream to file
- 'name'; if this option is unspecified, standard output
- is used for PDF, (or PostScript), output.
-
- --no-pdf-output
- Suppress the generation of PDF, (or PostScript), output
- entirely; use this with the --reference-dictionary
option,
- if processing a document stream to produce only a
- reference dictionary.
-
- --no-reference-dictionary
- Suppress the generation of a '$CMD' reference dictionary
- for the PDF document. Normally '$CMD' will create a
- reference dictionary, at the start of document
processing;
- this option can accelerate processing, if it is known in
- advance, that no reference dictionary is required.
-
- --reference-dictionary=name
- Save the document reference dictionary in file 'name'.
- If 'name' already exists, when processing commences, it
- will be used as the base case, from which the updated
- dictionary will be derived. If this option is not used,
- then the reference dictionary, created during the normal
- execution of '$CMD', will be deleted on completion of
- document processing.
-
- --stylesheet=name
- Use the file 'name' as a 'groff' style sheet, to control
- the appearance of the document's front cover section.
If
- this option is not specified, then no special formatting
- is applied, to create a front cover section.
-
- --no-toc-relocation
- Suppress the multiple pass 'groff' processing, which is
- normally required to position the table of contents at
the
- start of a PDF document.
-
- --no-kill-null-pages
- Suppress the 'null page' elimination filter, which is
used
- to remove the excess blank pages produced by the
collation
- algorithm used for 'toc-relocation'.
-
- --keep-temporary-files
- Suppress the normal clean up of temporary files, which
is
- scheduled when 'pdfroff' completes.
-
- ETX
- exit 0
- ;;
-
- --version)
- GROFF_STYLE="$GROFF_STYLE \"$1\""
- SHOW_VERSION="GNU pdfroff (groff) version @VERSION@"
- ;;
-
- --report-progress)
- SHOW_PROGRESS=echo
- ;;
-
- --keep-temporary-files)
- trap "" 0
- ;;
-
- --emit-ps)
- PDFROFF_POSTPROCESSOR_COMMAND="$CAT"
- ;;
-
- --pdf-output)
- PDF_OUTPUT="$OPTARG"
- ;;
-
- --no-pdf-output)
- PDF_OUTPUT="$NULLDEV"
- ;;
-
- --reference-dictionary)
- REFFILE="$OPTARG"
- ;;
-
- --no-reference-dictionary)
- AWK=":" DIFF=":" REFFILE="$NULLDEV" REFCOPY="$NULLDEV"
- ;;
-
- --stylesheet)
- STYLESHEET="$OPTARG" CS_DATA=${GROFF_TMPDIR}/pdf$$.cs
- ;;
-
- --no-toc-relocation)
- TC_DATA="" TOC_FORMAT="" BODY_FORMAT=""
- ;;
-
- --no-kill-null-pages)
- PDFROFF_COLLATE="$CAT" PDFROFF_KILL_NULL_PAGES=""
- ;;
-#
-# any other non-null match must have matched more than one defined
case,
-# so report the ambiguity, and bail out.
-#
- --*)
- echo >&2 "$CMD: ambiguous abbreviation in option '$1'"
- exit 1
- ;;
-#
-# while no match at all simply represents an undefined case.
-#
- *)
- echo >&2 "$CMD: unknown option '$1'"
- exit 1
- ;;
- esac
- ;;
-#
-# A solitary hyphen, as an argument, means "stream STDIN through groff",
-# while the "-i" option means "append STDIN stream to specified input
files",
-# so set up a mechanism to achieve this, for ALL 'groff' passes.
-#
- - | -i*)
- STREAM="$CAT ${GROFF_TMPDIR}/pdf$$.in |"
- test "$1" = "-" && INPUT_FILES="$INPUT_FILES $1" \
- || GROFF_STYLE="$GROFF_STYLE $1"
- ;;
-#
-# Those standard options which expect an argument, but are specified with
-# an intervening space, between flag and argument, must be reparsed, so we
-# can trap invalid use of '-T dev', or missing input files.
-#
- -[dfFILmMnoPrTwW])
- OPTNAME="$1"
- shift; set reparse "$OPTNAME$@"
- ;;
-#
-# Among standard options, '-Tdev' is treated as a special case.
-# '-Tps' is automatically enforced, so if specified, is silently ignored.
-#
- -Tps) ;;
-#
-# No other '-Tdev' option is permitted.
-#
- -T*) echo >&2 "$CMD: option '$1' is incompatible with PDF output"
- exit 1
- ;;
-#
-# '-h' and '-v' options redirect to their equivalent long forms ...
-#
- -h*) set redirect --help
- ;;
-#
- -v*) shift; set redirect --version "$@"
- ;;
-#
-# All other standard options are simply passed through to 'groff',
-# with no validation beforehand.
-#
- -*) GROFF_STYLE="$GROFF_STYLE \"$1\""
- ;;
-#
-# All non-option arguments are considered as possible input file names,
-# and are passed on to 'groff', unaltered.
-#
- *) INPUT_FILES="$INPUT_FILES \"$1\""
- ;;
- esac
- shift
- done
-#
-# If the '-v' or '--version' option was specified,
-# then we simply emulate the behaviour of 'groff', with this option,
-# and quit.
-#
- if test -n "$SHOW_VERSION"
- then
- echo >&2 "$SHOW_VERSION"
- echo >&2; eval $GROFF_STYLE $INPUT_FILES
- exit $?
- fi
-#
-# Establish how to invoke 'echo', suppressing the terminating newline.
-# (Adapted from 'autoconf' code, as found in 'configure' scripts).
-#
- case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in
- *c*,*-n*) n='' c='' ;;
- *c*) n='-n' c='' ;;
- *) n='' c='\c' ;;
- esac
-#
-# If STDIN is specified among the input files,
-# or if no input files are specified, then we need to capture STDIN,
-# so we can replay it into each 'groff' processing pass.
-#
- test -z "$INPUT_FILES" && STREAM="$CAT ${GROFF_TMPDIR}/pdf$$.in |"
- test -n "$STREAM" && $CAT > ${GROFF_TMPDIR}/pdf$$.in
-#
-# Unless reference resolution is explicitly suppressed,
-# we initiate it by touching the cross reference dictionary file,
-# and initialise the comparator, to kickstart the reference resolver loop.
-#
- SAY=":"
- if test -z "$DIFF"
- then
- >> $REFFILE
- echo kickstart > $REFCOPY
- test x${SHOW_PROGRESS+"set"} = x"set" && SAY=echo
-#
-# In order to correctly resolve 'pdfmark' references,
-# we need to have both the 'awk' and 'diff' programs available.
-#
- NO=''
- if test -n "$GROFF_AWK_INTERPRETER"
- then
- AWK="$GROFF_AWK_INTERPRETER"
- test -f "$AWK" && test -x "$AWK" || AWK=":"
- else
- for prog in @GROFF_AWK_INTERPRETERS@
- do
- AWK=`searchpath $prog "$PATH"`
- test "$AWK" = ":" || break
- done
- fi
- DIFF=`searchpath diff "$PATH"`
- test "$AWK" = ":" && echo >&2 "$NOPROG 'awk' in PATH" && NO="$NO 'awk'"
- test "$DIFF" = ":" && echo >&2 "$NOPROG 'diff' in PATH" && NO="$NO 'diff'"
- if test -n "$NO"
- then
- set $NO
- SAY=":" AWK=":" DIFF=":"
- test $# -gt 1 && NO="s $1 and $2 are" || NO=" $1 is"
- $CAT >&2 <<-ETX
-
- *** WARNING ***
-
- The program$NO required, but cannot be found;
- consequently, '$CMD' is unable to resolve 'pdfmark' references.
-
- Document processing will continue, but no 'pdfmark' reference dictionary
- will be compiled; if any 'pdfmark' reference appears in the resulting
PDF
- document, the formatting may not be correct.
-
- ETX
- fi
- fi
-#
-# Run the multi-pass 'pdfmark' reference resolver loop ...
-#
- $SAY >&2 $n Resolving references ..$c
- until $DIFF $REFCOPY $REFFILE 1>$NULLDEV 2>&1
- do
-#
-# until all references are resolved, to yield consistent values
-# in each of two consecutive passes, or until it seems that no consistent
-# resolution is achievable.
-#
- $SAY >&2 $n .$c
- PASS_INDICATOR="${PASS_INDICATOR}."
- if test "$PASS_INDICATOR" = "...."
- then
-#
-# More than three passes required indicates a probable inconsistency
-# in the source document; diagnose, and bail out.
-#
- $SAY >&2 " failed"
- $CAT >&2 <<-ETX
- $CMD: unable to resolve references consistently after three passes
- $CMD: the source document may exhibit instability about the
reference(s) ...
- ETX
-#
-# Report the unresolved references, as a diff between the two pass files,
-# preferring 'unified' or 'context' diffs, when available
-#
- DIFFOPT=''
- $DIFF -c0 $NULLDEV $NULLDEV 1>$NULLDEV 2>&1 && DIFFOPT='-c0'
- $DIFF -u0 $NULLDEV $NULLDEV 1>$NULLDEV 2>&1 && DIFFOPT='-u0'
- $DIFF >&2 $DIFFOPT $REFCOPY $REFFILE
- exit 1
- fi
-#
-# Replace the comparison file copy from any previous pass,
-# with the most recently updated copy of the reference dictionary.
-# (Some versions of 'mv' may not support overwriting of an existing file,
-# so remove the old comparison file first).
-#
- rm -f $REFCOPY
- mv $REFFILE $REFCOPY
-#
-# Run 'groff' and 'awk', to identify reference marks in the document source,
-# filtering them into the reference dictionary; discard incomplete 'groff'
output
-# at this stage.
-#
- eval $STREAM $GROFF_STYLE -Z 1>$NULLDEV 2>$WRKFILE $REFCOPY $INPUT_FILES
- $AWK '/^gropdf-info:href/ {$1 = ".pdfhref D -N"; print}' $WRKFILE >
$REFFILE
- done
- $SAY >&2 " done"
-#
-# To get to here ...
-# We MUST have resolved all 'pdfmark' references, such that the content of the
-# updated reference dictionary file EXACTLY matches the last saved copy.
-#
-# If PDF output has been suppressed, then there is nothing more to do.
-#
- test "$PDF_OUTPUT" = "$NULLDEV" && exit 0
-#
-# We are now ready to start preparing the intermediate PostScript files,
-# from which the PDF output will be compiled -- but before proceeding further
...
-# let's make sure we have a GhostScript interpreter to convert them!
-#
- if test -n "$GROFF_GHOSTSCRIPT_INTERPRETER"
- then
- GS="$GROFF_GHOSTSCRIPT_INTERPRETER"
- test -f "$GS" && test -x "$GS" || GS=":"
- else
- for prog in @GROFF_GHOSTSCRIPT_INTERPRETERS@
- do
- GS=`searchpath $prog "$PATH"`
- test "$GS" = ":" || break
- done
- fi
-#
-# If we could not find a GhostScript interpreter, then we can do no more.
-#
- if test "$GS" = ":"
- then
- echo >&2 "$CMD: installation problem: cannot find GhostScript interpreter"
- $CAT >&2 <<-ETX
-
- *** FATAL INSTALLATION ERROR ***
-
- '$CMD' requires a GhostScript interpreter to convert PostScript to PDF.
- You do not appear to have one installed; thus, '$CMD' cannot continue.
-
- ETX
- exit 1
- fi
-#
-# We now extend the local copy of the reference dictionary file,
-# to create a full 'pdfmark' reference map for the document; when
-# one or more reference marks has been mapped, append one further
-# dummy map reference, to ensure that at least one such is always
-# present; (this is required, to suppress any further intermediate
-# output to stderr during the "press-ready" runs of groff, for PDF
-# output file production).
-#
- $AWK '/^grohtml-info/ {zflag = 1; print ".pdfhref Z", $2, $3, $4}
- END {if(zflag) print ".pdfhref Z 0 0 0"}
- ' $WRKFILE >> $REFCOPY
-#
-# Evaluate any processing options which may have been specified
-# as a result of parsing the document source ...
-#
- eval `$SED -n '/^ *pdfroff-option:set */s///p' $WRKFILE`
-#
-# ... (which is currently supported to enable "toc-relocation",
-# only when the document actually relies on it, and if it is not
-# explicitly disabled from the command line) ...
-#
- if test x${toc_relocation-"auto"} != xenabled
- then
-#
-# ... thus we reproduce the effect of the "--no-toc-relocation"
-# option, when no enabling request is detected in the document
-# control stream.
-#
- TC_DATA="" TOC_FORMAT="" BODY_FORMAT=""
- fi
-#
-# Re-enable progress reporting, if necessary ...
-# (Missing 'awk' or 'diff' may have disabled it, to avoid display
-# of spurious messages associated with reference resolution).
-#
- test x${SHOW_PROGRESS+"set"} = x"set" && SAY=echo
-#
-# If a document cover style sheet is specified ...
-# then we run a special formatting pass, to create a cover section file.
-#
- if test -n "$STYLESHEET"
- then
- DOT='^\.[ ]*'
- CS_MACRO=${CS_MACRO-"CS"} CE_MACRO=${CE_MACRO-"CE"}
- $SAY >&2 $n "Formatting document ... front cover section ..$c"
- CS_FILTER="$STREAM $SED -n '/${DOT}${CS_MACRO}/,/${DOT}${CE_MACRO}/p'"
- eval $CS_FILTER $INPUT_FILES | eval $GROFF_STYLE $STYLESHEET - > $CS_DATA
- $SAY >&2 ". done"
- fi
-#
-# If table of contents relocation is to be performed (it is, by default),
-# then we run an extra 'groff' pass, to format a TOC intermediate file.
-#
- if test -n "$TC_DATA"
- then
- $SAY >&2 $n "Formatting document ... table of contents ..$c"
- eval $STREAM $GROFF_STYLE $TOC_FORMAT $REFCOPY $INPUT_FILES > $TC_DATA
- $SAY >&2 ". done"
- fi
-#
-# In all cases, a final 'groff' pass is required, to format the document body.
-#
- $SAY >&2 $n "Formatting document ... body section ..$c"
- eval $STREAM $GROFF_STYLE $BODY_FORMAT $REFCOPY $INPUT_FILES > $BD_DATA
- $SAY >&2 ". done"
-#
-# Finally ...
-# Invoke GhostScript as a PDF writer, to bind all of the generated
-# PostScript intermediate files into a single PDF output file.
-#
- $SAY >&2 $n "Writing PDF output ..$c"
- if test -z "$PDFROFF_POSTPROCESSOR_COMMAND"
- then
- PDFROFF_POSTPROCESSOR_COMMAND="$GS -dQUIET -dBATCH -dNOPAUSE -dSAFER
- -sDEVICE=pdfwrite -sOutputFile="${PDF_OUTPUT-"-"}
-
- elif test -n "$PDF_OUTPUT"
- then
- exec > $PDF_OUTPUT
- fi
-#
-# (This 'sed' script is a hack, to eliminate redundant blank pages).
-#
- ${PDFROFF_COLLATE-"$SED"} ${PDFROFF_KILL_NULL_PAGES-'
- /%%Page:/{
- N
- /%%BeginPageSetup/b again
- }
- b
- :again
- /%%EndPageSetup/b finish
- /%%Page:/{
- N
- b again
- }
- b
- :finish
- N
- /^%%Page:.*\n0 Cg EP$/d
- '} $TC_DATA $BD_DATA | $PDFROFF_POSTPROCESSOR_COMMAND $CS_DATA -
- $SAY >&2 ". done"
-#
-#
------------------------------------------------------------------------------
-# $RCSfile$ $Revision$: end of file
diff --git a/contrib/pdfmark/sanitize.tmac b/contrib/pdfmark/sanitize.tmac
deleted file mode 100644
index 49feaa9e6..000000000
--- a/contrib/pdfmark/sanitize.tmac
+++ /dev/null
@@ -1,170 +0,0 @@
-.ig
-
-sanitize.tmac
-
-Copyright (C) 2021 Free Software Foundation, Inc.
- Written by Keith Marshall (keith.d.marshall@ntlworld.com)
-
-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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.
-
-..
-.eo
-.de sanitize
-.\" Usage: .sanitize name text ...
-.\"
-.\" Remove designated formatting escape sequences from "text ..."; return
-.\" the sanitized text in a string register, identified by "name".
-.\"
-.\" Begin by initializing the named result as an empty string, bind it to
-.\" an internal reference name, and discard the "name" argument, to leave
-.\" only the text which is to be sanitized, as residual arguments.
-.\"
-. ds \$1
-. als sanitize:result \$1
-. shift
-.
-.\" Initialize a working string register, which we will cyclically reduce
-.\" until it becomes empty, after starting with all of the text passed as
-.\" the residual arguments, and establish its initial length.
-.\"
-. ds sanitize:residual "\$*\"
-. length sanitize:residual.length "\$*\"
-.
-.\" Begin the cyclic reduction loop...
-.\"
-. while \n[sanitize:residual.length] \{\
-. \"
-. \" ...assuming, at the start of each cycle, that the next character
-. \" will not be skipped, and that it will be moved from the residual,
-. \" to the result, as the character-by-character scan proceeds.
-. \"
-. nr sanitize:skip.count 0
-. sanitize:scan.execute
-.
-. \" For each character scanned, we need to check if it matches the
-. \" normal escape character; the check is most readily performed, if
-. \" an alternative escape character is introduced, and when a match
-. \" is found, we prepare to skip an escape sequence.
-. \"
-. ec !
-. if '!*[sanitize:scan.char]'\' .nr sanitize:skip.count 1
-. ec
-. ie \n[sanitize:skip.count] \{\
-. \"
-. \" When a possible escape sequence has been detected, we back it
-. \" up, (in case it isn't recognized, and we need to reinstate its
-. \" content into the result string), then scan ahead to check for
-. \" an identifiable escape sequence...
-. \"
-. rn sanitize:scan.char sanitize:hold
-. sanitize:scan.execute
-. ie d sanitize:esc-\*[sanitize:scan.char] \
-. \"
-. \" ...which we delegate to its appropriate handler, to skip...
-. \"
-. sanitize:esc-\*[sanitize:scan.char]
-.
-. \" ...but, in the case of an unrecognized escape sequence, we copy
-. \" its backed-up content, followed by the character retrieved from
-. \" the current scan cycle, to the result string.
-. \"
-. el .as sanitize:result "\*[sanitize:hold]\*[sanitize:scan.char]\"
-. \}
-.
-. \" When the current scan cycle has retrieved a character, which isn't
-. \" part of any possible escape sequence, we simply copy that character
-. \" to the result string.
-. \"
-. el .as sanitize:result "\*[sanitize:scan.char]\"
-. \}
-.
-.\" Clean up the register space, by deleting all of the string registers,
-.\" and numeric registers, which are designated as temporary, for private
-.\" use within this macro only.
-.\"
-. rm sanitize:hold sanitize:scan.char sanitize:residual sanitize:result
-. rr sanitize:residual.length sanitize:skip.count
-..
-.de sanitize:scan.execute
-.\" Usage (internal): .sanitize:scan.execute
-.\"
-.\" Perform a single-character reduction of sanitize:residual, by copying
-.\" its initial character to sanitize:scan.char, and then deleting it from
-.\" sanitize:residual itself. (Note that we use arithmetic decrementation
-.\" of sanitize:residual.length, rather than repeating the length request
-.\" on sanitize:residual, because reduction WILL fail when there is only
-.\" one character remaining).
-.\"
-. nr sanitize:residual.length -1
-. ds sanitize:scan.char "\*[sanitize:residual]\"
-. substring sanitize:scan.char 0 0
-. substring sanitize:residual 1
-..
-.de sanitize:skip-(
-.\" Usage (internal): .sanitize:skip-(
-.\"
-.\" For any identified escape sequence, with a two-character property name,
-.\" simply skip over the next two characters in the residual string.
-.\"
-. nr sanitize:residual.length -2
-. substring sanitize:residual 2
-..
-.de sanitize:skip-[
-.\" Usage (internal): .sanitize:skip-[
-.\"
-.\" For any identified escape sequence, with an arbitrary-length property
-.\" name, skip following characters in the residual string, until we find
-.\" a terminal "]" character, or we exhaust the residual.
-.\"
-. while \n[sanitize:skip.count] \{\
-. sanitize:scan.execute
-. ie \n[sanitize:residual.length] \{\
-. \" We haven't yet exhausted the residual; if we find a nested "["
-. \" character, increment the nesting level, otherwise decrement it
-. \" for each "]"; it will become zero at the terminal "]".
-. \"
-. ie '\*[sanitize:scan.char]'[' .nr sanitize:skip.count +1
-. el .if '\*[sanitize:scan.char]']' .nr sanitize:skip.count -1
-. \}
-. \" Stop unconditionally, if we do exhaust the residual.
-. \"
-. el .nr sanitize:skip.count 0
-. \}
-..
-.de sanitize:esc-generic
-.\" Usage: .sanitize:esc-X
-.\"
-.\" (X represents any legitimate single-character escape sequence id).
-.\"
-.\" Handler for skipping "\X" sequences, in text which is to be sanitized;
-.\" this will automatically detect sequences conforming to any of the forms
-.\" "\Xc", "\X(cc", or "\X[...]", and will handle each appropriately. The
-.\" implementation is generic, and may be aliased to handle any specific
-.\" escape sequences, which exhibit similar semantics.
-.\"
-. sanitize:scan.execute
-. if d sanitize:skip-\*[sanitize:scan.char] \
-. sanitize:skip-\*[sanitize:scan.char]
-..
-.ec
-.\" Map the generic handler to specific escape sequences, as required.
-.\"
-.als sanitize:esc-F sanitize:esc-generic
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-.\" vim: filetype=groff:
-.\" sanitize.tmac: end of file
diff --git a/contrib/pdfmark/spdf.tmac b/contrib/pdfmark/spdf.tmac
deleted file mode 100644
index 130d8bd07..000000000
--- a/contrib/pdfmark/spdf.tmac
+++ /dev/null
@@ -1,328 +0,0 @@
-.ig
-
-spdf.tmac
-
-Binding macros for use of "-m pdfmark" in conjunction with "-ms".
-
-
-Copyright (C) 2004-2021 Free Software Foundation, Inc.
- Written by Keith Marshall (keith.d.marshall@ntlworld.com)
-
-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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.
-
-..
-.\" Bindings
-.\" ========
-.\"
-.\" Generic output mode control flag; pdfmark.tmac will bind this to
-.\" its own internal PDFOPMODE flag.
-.\"
-.if !r OPMODE .nr OPMODE 1
-.\"
-.mso s.tmac
-.mso sanitize.tmac
-.mso pdfmark.tmac
-.
-.\" Establish a handler to clean up output context, at end of document.
-.\"
-.de pdf@exit em
-. if \\n[OPMODE] .pdfsync
-. pg@end-text
-.em pdf@exit
-.
-.
-.\" Omitted Sections
-.\" ================
-.\"
-.\" Define section markers, for special document sections,
-.\" which are to be omitted from regular document processing.
-.\"
-.\" .OMIT <name1> <name2>
-.\"
-.\" Defines a pair of macros, <name1> and <name2>, such that execution
-.\" of .<name1> marks the start of a block of troff input which should
-.\" be ignored; this block ends, on execution of .<name2>
-.\"
-.de OMIT OMIT
-. de \\$1
-. omit@begin \\$1 \\$2
-. .
-. de \\$2
-. omit@end \\$1 \\$2
-. .
-.\" Definition of the OMIT macro itself, ends when it is first used,
-.\" to identify an omitted section marker macro pair.
-.\"
-.OMIT CS CE \" front cover text, processed independently
-.OMIT MS ME \" menu definitions, for info documents only
-.
-.\" Actual omission is initiated by recording the name of the block
-.\" start macro, followed by injection of an "ig" request...
-.\"
-.de omit@begin
-. ds omit@section \\$1
-\. ig \\$2
-..
-.\" ...and terminates with verification that the end macro matches
-.\" the start macro, and removal of the start macro record; (error
-.\" reporting uses the "@error" macro, from s.tmac).
-.\"
-.de omit@end
-. if !'\\*[omit@section]'\\$1' .@error \\$2 without \\$1
-. rm omit@section
-..
-.
-.\" Document Outlines, and Section Headings
-.\" =======================================
-.\"
-.\" .XH [-N <name>] [-S] [-X] <outline-level> <heading-text> ...
-.\" .XN [-N <name>] [-S] [-X] <heading-text> ...
-.\"
-.\" Use after SH, and XN <n> respectively, to define text to be set
-.\" within the section heading, as a PDF document ouline entry, and
-.\" optionally, as a table of contents entry.
-.\"
-.\" Options:
-.\" -N <name> Assigns <name> as a pdfhref destination,
-.\" and associates it with the heading.
-.\"
-.\" -S Strip troff font-change escapes from the
-.\" text copied to the document outline.
-.\"
-.\" -X Force pdfhref destination assignment; if
-.\" -N <name> is unspecified, use first word
-.\" of <heading-text> as <name>.
-.\"
-.\" Arguments:
-.\" <outline-level> The nesting level of the heading, within
-.\" the document outline, and TOC. Required
-.\" for XH; inferred from NH <n>, for XN.
-.\"
-.\" <heading-text> Text (required) to appear within each of
-.\" the section heading, document outline,
-.\" and (optionally) TOC.
-.\"
-.\" Hooks:
-.\" XH-INIT User-defined macro, called on entry to XH;
-.\" used to specify initialization state which
-.\" may be needed after using SH; e.g. specify
-.\" a PDFHREF.INFO state without incorporation
-.\" of any "section" references.
-.\"
-.\" XN-INIT User-defined macro, called on entry to XN;
-.\" used to specify initialization state which
-.\" may be needed after using NH; e.g. specify
-.\" a PDFHREF.INFO state which may incorporate
-.\" "section" references.
-.\"
-.\" XH-UPDATE-TOC User-defined macro, called by both XH, and
-.\" XN; (there is no XN-UPDATE-TOC). Must be
-.\" defined, if a TOC entry is to be generated
-.\" by either XH, or XN; the format of such a
-.\" TOC entry is determined by the definition
-.\" of this macro.
-.\"
-.\" Our replacements for both XH, and XN macros share a common entry
-.\" point; we map both to their respective replacement hooks, so that
-.\" we may continue to take advantage of setup logic in s.tmac. When
-.\" these are eventually invoked, they will have been renamed so that
-.\" they replace XH, and XH respectively.
-.\"
-.de XH-REPLACEMENT als
-.als XN-REPLACEMENT XH-REPLACEMENT
-.\" FIXME: within s.tmac, the heading level established by the most
-.\" recent prior invocation of the NH macro is tracked by the "nh*hl"
-.\" private register; perhaps s.tmac could expose this more publicly,
-.\" as by this ostensibly read-only alias, since we need it to keep
-.\" PDF document outlines in synchronization with NH level...
-.\"
-.\" .aln .NH nh*hl
-.\"
-.\" ...but maybe a local "belt and braces" approach is better anyway,
-.\" to insulate "nh*hl" from possible abuse of our ".NH" register, by
-.\" any users who may be determined to shoot themselves in the foot!
-.\"
-.ie r nh*hl .nr spdf:nh*hl \n[nh*hl]
-.el .nr spdf:nh*hl 0
-.am @NH
-. nr spdf:nh*hl \\n[nh*hl]
-..
-.aln .NH spdf:nh*hl
-.
-.\" The common entry point for both XH, and XN, handles initialization,
-.\" and interpretation of any specified options, before handing over to
-.\" one of two distinct formatting helper macros, which are specific to
-.\" the XH, and XN implementations respectively.
-.\"
-.am XH-REPLACEMENT \" thus serving as implementation for both XH and XN
-.\"
-.\" The user is expected to furnish the XH-INIT, XH-UPDATE-TOC, and
-.\" XN-INIT handlers. (Note that the XH-UPDATE-TOC hook serves both
-.\" XH and XN; there is no separate XN-UPDATE-TOC). A suitable stub
-.\" for each is provided by s.tmac; we have no need to replace them.
-.\"
-. \\$0-INIT
-. rm spdf:refname
-. als spdf:bm.define spdf:bm.basic
-. while d spdf:XH\\$1 \{\
-. spdf:XH\\$1 \\$*
-. shift \\n[spdf:argc]
-. \}
-. rr spdf:argc
-. if '\\$1'--' .shift
-. spdf:\\$0.format \\$@
-..
-.\" Interpret the "-N <name>" option...
-.\"
-.de spdf:XH-N
-. ds spdf:refname \\$2
-. nr spdf:argc 2
-..
-.\" ...the "-X" option, and...
-.\"
-.de spdf:XH-X
-. if !d spdf:refname .ds spdf:refname \\\\$1
-. nr spdf:argc 1
-..
-.\" ...the "-S" option.
-.\"
-.de spdf:XH-S
-. als spdf:bm.define sanitize
-. nr spdf:argc 1
-..
-.\" By default, when the "-S" option is not specified, the text
-.\" incorporated into the PDF document outline will be a simple
-.\" verbatim copy of the arguments.
-.\"
-.de spdf:bm.basic
-. shift \" ignore \$1; it should always be "spdf:bm.text"
-. ds spdf:bm.text "\\$*\"
-..
-.\" After initialization, and interpretation of options, the XH
-.\" and XN implementations diverge, into this helper macro, which
-.\" is specific to the XH implementation...
-.\"
-.de spdf:XH.format
-. XH-UPDATE-TOC \\$@
-. ds spdf:bm.argv \\$1
-. shift \" finalization doesn't want the outline level in \$1
-. spdf:XH.finalize \\$@
-..
-.\" ...and this, which is specific to XN...
-.\"
-.de spdf:XN.format
-. ds spdf:bm.argv \\n[.NH] \\*[SN]
-. XH-UPDATE-TOC \\n[.NH] \\*[SN] \\$@
-. spdf:XH.finalize \\$@
-..
-.\" ...before ultimately converging back into this finalization
-.\" macro, which is once again common to both XH and XN.
-.\"
-.de spdf:XH.finalize
-. spdf:bm.define spdf:bm.text "\\$*"
-. if d spdf:refname .pdfhref M -X -N \\*[spdf:refname] -- \\$@
-. pdfhref O \\*[spdf:bm.argv] \\*[spdf:bm.text]
-. rm spdf:refname spdf:bm.argv spdf:bm.text
-. nop \\$*
-..
-.
-.\" Cross-Reference Marshalling
-.\" ===========================
-.\"
-.\" s.tmac provides the "pg@bottom" macro, which has already
-.\" been installed as a page transition trap. To ensure proper
-.\" mapping of "pdfhref" links which overflow the bottom of any
-.\" page, we need to install the "pdfhref" page transition hook,
-.\" as an addendum to this macro.
-.
-.pdfhref I -PT pg@bottom
-.
-.
-.\" Phased Output Control
-.\" =====================
-.\"
-.\" Segregate output of table of contents, and document body text,
-.\" into two distinct output phases, to facilitate assembly of the
-.\" aggregate document in the correct order, particularly when the
-.\" TOC is generated at the end, by the default "ms" mechanism.
-.\"
-.nr PDF-TOC-ONLY 1
-.nr PDF-BODY-TEXT 2
-.\"
-.\" .OP [<output-phase>]
-.\"
-.\" If the user-specified PHASE numeric register has been defined,
-.\" and its value matches the <output-phase> argument value, (or if
-.\" no <output-phase> argument is specified), then set the OPMODE
-.\" control flag to one, and activate groff's "pen-down" mode.
-.\"
-.\" Otherwise, if <output-phase> is specified, but does NOT match
-.\" PHASE, set OPMODE to zero, and select "pen-up" mode.
-.\"
-.\" Alternatively, if PHASE has not been defined, unconditionally
-.\" set OPMODE to one, and leave groff's pen state unchanged.
-.\"
-.de OP
-.ie r PHASE \{\
-. ie \\n(.$ \{\
-. nr op:request 0
-. while \\n(.$ \{\
-. if \\$1=\\n[PHASE] .nr op:request 1
-. shift
-. \}
-. \}
-. el .nr op:request 1
-. if !\\n[op:request]=\\n[OPMODE] \{\
-. nr OPMODE \\n[op:request]
-. nop \O[\\n[OPMODE]]\c
-. \}
-. \}
-.el .nr OPMODE 1
-..
-.
-.\" Table of Contents Generation
-.\" ============================
-.\"
-.\" .TC [no]
-.\"
-.\" Replaces (and emulates) the TC macro, from s.tmac, to ensure
-.\" that the pdfmark document outline cache is flushed, before TOC
-.\" generation commences, that an outline reference is added for the
-.\" TOC itself, and that pdfroff TOC relocation mode is enabled, for
-.\" the TOC output phase of document production.
-.\"
-.de TC
-. pdfsync O
-. P1
-. OP \n[PDF-TOC-ONLY]
-. pg@begin 1 i
-. if !\\n[PHASE] .tm pdfroff-option:set toc_relocation=enabled
-. if \\n[OPMODE] \{\
-. pdfhref O -T T 1 "\\*[TOC]"
-. pdfsync O
-. \}
-. PX \\$1
-..
-.
-.\" Initialize the default output state, for production of "body-text".
-.\"
-.OP \n[PDF-BODY-TEXT]
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-.\" vim: filetype=groff:
-.\" spdf.tmac: end of file
diff --git a/doc/doc.am b/doc/doc.am
index 72d8f732d..49da8f26a 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -220,7 +220,6 @@ GROFF_MAN_PAGES1 = \
src/preproc/eqn/neqn.1 \
src/roff/nroff/nroff.1 \
src/devices/gropdf/pdfmom.1 \
- contrib/pdfmark/pdfroff.1 \
src/utils/pfbtops/pfbtops.1 \
src/preproc/pic/pic.1 \
contrib/pic2graph/pic2graph.1 \
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 273390cc3..61185b8af 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -2407,8 +2407,8 @@ Formatter program:
Formatter wrappers:
.\".MR groff @MAN1EXT@ , \" 42 -- this page
.MR @g@nroff @MAN1EXT@ , \" #44
-.MR pdfmom @MAN1EXT@ , \" #30
-.MR pdfroff @MAN1EXT@ \" #14
+.MR pdfmom @MAN1EXT@ \" #30
+.\" MR pdfroff @MAN1EXT@ \" formerly #14
.
.
.TP
diff --git a/src/utils/grog/tests/smoke-test.sh
b/src/utils/grog/tests/smoke-test.sh
index 3c70688ff..c95320484 100755
--- a/src/utils/grog/tests/smoke-test.sh
+++ b/src/utils/grog/tests/smoke-test.sh
@@ -114,16 +114,6 @@ echo "testing mom(7) document $doc" >&2
"$grog" "$doc" | \
grep -Fqx 'groff -mom '"$doc"
-doc=$src/contrib/pdfmark/cover.ms
-echo "testing ms(7) document $doc" >&2
-"$grog" "$doc" | \
- grep -Fqx 'groff -ms '"$doc"
-
-doc=$src/contrib/pdfmark/pdfmark.ms
-echo "testing ms(7) document $doc" >&2
-"$grog" "$doc" | \
- grep -Fqx 'groff -ms '"$doc"
-
doc=$src/doc/pic.ms
echo "testing tbl(1)-, eqn(1)-, and pic(1)-using ms(7) document $doc" \
>&2
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 07/08: Fix Savannah #63827 (stop distributing pdfmark).,
G. Branden Robinson <=