diff options
Diffstat (limited to 'contrib/pdfmark/spdf.tmac')
| -rw-r--r-- | contrib/pdfmark/spdf.tmac | 328 |
1 files changed, 328 insertions, 0 deletions
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 |