diff options
Diffstat (limited to 'contrib/pdfmark')
| -rw-r--r-- | contrib/pdfmark/ChangeLog | 683 | ||||
| -rw-r--r-- | contrib/pdfmark/PROBLEMS | 32 | ||||
| -rw-r--r-- | contrib/pdfmark/README | 57 | ||||
| -rw-r--r-- | contrib/pdfmark/TODO | 60 | ||||
| -rw-r--r-- | contrib/pdfmark/cover.ms | 70 | ||||
| -rw-r--r-- | contrib/pdfmark/pdfmark.am | 99 | ||||
| -rw-r--r-- | contrib/pdfmark/pdfmark.ms | 2831 | ||||
| -rw-r--r-- | contrib/pdfmark/pdfmark.tmac | 1953 | ||||
| -rw-r--r-- | contrib/pdfmark/pdfroff.1.man | 981 | ||||
| -rw-r--r-- | contrib/pdfmark/pdfroff.sh | 682 | ||||
| -rw-r--r-- | contrib/pdfmark/sanitize.tmac | 170 | ||||
| -rw-r--r-- | contrib/pdfmark/spdf.tmac | 328 |
12 files changed, 7946 insertions, 0 deletions
diff --git a/contrib/pdfmark/ChangeLog b/contrib/pdfmark/ChangeLog new file mode 100644 index 0000000..1c5a18f --- /dev/null +++ b/contrib/pdfmark/ChangeLog @@ -0,0 +1,683 @@ +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 new file mode 100644 index 0000000..d31be4a --- /dev/null +++ b/contrib/pdfmark/PROBLEMS @@ -0,0 +1,32 @@ + -*- 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 new file mode 100644 index 0000000..7440ffd --- /dev/null +++ b/contrib/pdfmark/README @@ -0,0 +1,57 @@ + -*- 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 new file mode 100644 index 0000000..219b60e --- /dev/null +++ b/contrib/pdfmark/TODO @@ -0,0 +1,60 @@ + -*- 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 new file mode 100644 index 0000000..b647a29 --- /dev/null +++ b/contrib/pdfmark/cover.ms @@ -0,0 +1,70 @@ +.\" 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 new file mode 100644 index 0000000..15eec8c --- /dev/null +++ b/contrib/pdfmark/pdfmark.am @@ -0,0 +1,99 @@ +# 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 + $(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 new file mode 100644 index 0000000..0d7d28c --- /dev/null +++ b/contrib/pdfmark/pdfmark.ms @@ -0,0 +1,2831 @@ +.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\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4 +.. +.de CWI +\\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4 +.. +.de CWBI +\\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$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 new file mode 100644 index 0000000..5f664f2 --- /dev/null +++ b/contrib/pdfmark/pdfmark.tmac @@ -0,0 +1,1953 @@ +.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 new file mode 100644 index 0000000..029a1f4 --- /dev/null +++ b/contrib/pdfmark/pdfroff.1.man @@ -0,0 +1,981 @@ +.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 +. +. +.SY pdfroff +.B \-h +. +.SY pdfroff +.B \-\-help +.YS +. +. +.SY pdfroff +.B \-v +.RI [ groff-option +\&.\|.\|.\&] +. +.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 new file mode 100644 index 0000000..f34c841 --- /dev/null +++ b/contrib/pdfmark/pdfroff.sh @@ -0,0 +1,682 @@ +#! /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 ... +# + $AWK '/^grohtml-info/ {print ".pdfhref Z", $2, $3, $4}' $WRKFILE >> $REFCOPY +# +# ... appending a 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). +# + echo ".pdfhref Z 0 0 0" >> $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 new file mode 100644 index 0000000..49feaa9 --- /dev/null +++ b/contrib/pdfmark/sanitize.tmac @@ -0,0 +1,170 @@ +.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 new file mode 100644 index 0000000..130d8bd --- /dev/null +++ b/contrib/pdfmark/spdf.tmac @@ -0,0 +1,328 @@ +.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 |