6 Copyright (C) 2004-2014 Free Software Foundation, Inc.
7 Written by Keith Marshall (keith.d.marshall@ntlworld.com)
9 This file is part of groff.
11 groff is free software; you can redistribute it and/or modify it under
12 the terms of the GNU General Public License as published by the Free
13 Software Foundation, either version 3 of the License, or
14 (at your option) any later version.
16 groff is distributed in the hope that it will be useful, but WITHOUT ANY
17 WARRANTY; without even the implied warranty of MERCHANTABILITY or
18 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 You should have received a copy of the GNU General Public License
22 along with this program. If not, see <http://www.gnu.org/licenses/>.
27 While I have written this macro package from scratch, much of my
28 inspiration has come from discussion on the groff mailing list
29 (mailto:groff@gnu.org). I am particularly indebted to:
31 Kees Zeelenberg, for an earlier macro package he posted,
32 a study of which helped me to get started.
34 Carlos J. G. Duarte and Werner Lemberg, whose discussion
35 on computation of the bounding boxes for link "hot-spots"
36 forms the basis of such computations in this package.
38 .if !\n(.g .ab These pdfmark macros require groff.
40 .\" Check if we have already been loaded -- do not reload
43 .\" ======================================================================
44 .\" Module PDFMARK: Insert Arbitrary PDFMARK Code in the Postscript Stream
45 .\" ======================================================================
47 .\" PDFMARK output may be disabled, by zeroing the PDFOPMODE register,
48 .\" ( which mimics a more generic OPMODE, if it is defined ).
50 .if rOPMODE .aln PDFOPMODE OPMODE
52 .\" but if OPMODE wasn't defined,
53 .\" then make the default PDFMARK mode ENABLED.
55 .if !rPDFOPMODE .nr PDFOPMODE 1
57 .\" PDFMARK output must be constrained to a maximum line length limit,
58 .\" for strict compliance with the Postscript DSC. This limit is defined
59 .\" in register "PDFMARK.FOLDWIDTH.MAX". This is user definable, up to a
60 .\" ceiling value of 255, which is also its default value; this limit
61 .\" is enforced for each PDFMARK, by macro "pdf*pdfmark.limit".
64 .\" ----------------------------------------------------------------
66 .\" .pdf*pdfmark.limit REGISTER-NAME DEFAULT-MAXIMUM-VALUE
67 .\" ----------------------------------------------------------------
69 .\" If a register named REGISTER-NAME has not been defined, then
70 .\" define it now, with default value = DEFAULT-MAXIMUM-VALUE.
72 .if !r\\$1 .nr \\$1 \\$2
74 .\" But when it has already been defined, ensure that its value does
75 .\" not exceed DEFAULT-MAXIMUM-VALUE; if value does exceed this ceiling,
76 .\" then redefine it, to enforce the limit.
78 .if (\\n[\\$1] > \\$2) .nr \\$1 \\$2
80 .\" The "pdfmark" macro is responsible for emitting the appropriate
84 .\" ----------------------------------------------------------------
86 .\" .pdfmark text of pdfmark instruction
87 .\" Macro supplies the required opening "[" and closing "pdfmark"
88 .\" operator; DO NOT include them in the instruction text!
89 .\" ----------------------------------------------------------------
91 .if \\n[PDFOPMODE] \{\
93 .\" Strict DSC compliance forbids emission of ps:exec lines which
94 .\" exceed 255 characters in length. We will allow the user to specify
95 .\" an alternative lesser limit ...
97 . pdf*pdfmark.limit PDFMARK.FOLDWIDTH.MAX 255
99 .\" ... and we will also support a second lesser limit, which will be
100 .\" applied to literal text parenthetically embedded within the PDFMARK.
102 . pdf*pdfmark.limit PDFMARK.FOLDWIDTH \\n[PDFMARK.FOLDWIDTH.MAX]
104 .\" We will push out the entire PDFMARK in one chunk, provided it fits
105 .\" within this limit.
107 . length pdf:length "[\\$* pdfmark\"
108 . ie !(\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH]) \{\
110 . \" This PDFMARK is suitable for single chunk output ...
112 . nop \!x X ps:exec [\\$* pdfmark
115 . \" ... but, when the limit would be violated, then we must
116 . \" recompose the specified PDFMARK, spreading it over as many
117 . \" continuation lines as are necessary.
119 . als pdf*compose pdf*compose.first
125 . \" Complete the PDFMARK recomposition, by appending a
126 . \" "pdfmark" operator, and push it out to the intermediate
127 . \" output stream, (excluding its final line break).
129 . pdf*compose pdfmark
130 . pdf*pdfmark.dispatch
132 . \" And clean up when done.
134 . rm pdf*compose pdf*pdfmark.post
135 . rm pdf:compose.test pdf:composed.literal
140 .\" When a PDFMARK exceeds the specified output record length limit,
141 .\" then we decompose it, subsequently using the dynamically overloaded
142 .\" macro, "pdf*compose", to reassemble it into as many continuation
143 .\" records as it may require.
145 .\" Each call to "pdf*compose" uses macro "pdf*length.increment" to
146 .\" keep track of the current output record length, so ensuring that
147 .\" the active maximum length limit is not violated.
149 .de pdf*length.increment
150 .\" ----------------------------------------------------------------
152 .\" .pdf*length.increment NEXT-ADDITION
153 .\" ----------------------------------------------------------------
155 .ie d pdf:composed.line \
156 . length pdf:length "\\*[pdf:composed.line] \\$*\"
157 .el .length pdf:length "\\$*\"
159 .\" The first call to "pdf*compose" for each PDFMARK is directed
160 .\" to "pdf*compose.first"; this initialises the local strings
161 .\" and macros used to compose the eventual PDFMARK output.
163 .de pdf*compose.first
164 .\" ----------------------------------------------------------------
166 .\" .als pdf*compose pdf*compose.first
167 .\" . pdf*compose TOKEN
168 .\" ----------------------------------------------------------------
170 .\" Ensure that the output record accumulator will be initialised
171 .\" on posting of the first composed PDFMARK record.
173 .als pdf*pdfmark.post pdf*pdfmark.post.first
175 .\" The first token passed to "pdf*compose" should not be a
176 .\" literal, but be prepared to handle one, just in case.
178 .ds pdf:compose.test \\$1
179 .substring pdf:compose.test 0 0
180 .ie '('\\*[pdf:compose.test]' \{\
182 .\" We found a literal, even though we didn't expect it;
183 .\" if it's a single element literal, we can just handle it
184 .\" as if it is a regular token anyway.
186 . ds pdf:compose.test "\\$\\n(.$\"
187 . substring pdf:compose.test -1
188 . if !')'\\*[pdf:compose.test]' \{\
190 . \" But when it is the first of a literal sequence,
191 . \" then we need to set up "pdf*compose" to handle it.
193 . ds pdf:composed.literal "[\\$*\"
194 . als pdf*compose pdf*compose.literal
197 .el .ds pdf:compose.test )
198 .if ')'\\*[pdf:compose.test]' \{\
200 .\" In the normal case, we start each new PDFMARK with a
201 .\" regular token; save it as the first in the composed output
202 .\" line sequence, and set up "pdf*compose" to collect
203 .\" the rest of the sequence.
205 . ds pdf:composed.line "[\\$*\"
206 . als pdf*compose pdf*compose.next
209 .\" Subsequent calls to "pdf*compose", while collecting
210 .\" regular tokens, are then directed to "pdf*compose.next".
213 .\" ----------------------------------------------------------------
215 .\" .als pdf*compose pdf*compose.next
216 .\" . pdf*compose TOKEN
217 .\" ----------------------------------------------------------------
219 .\" This first checks to ensure that the supplied token really is
220 .\" a regular token, and not the first element in a literal.
222 .ds pdf:compose.test \\$1
223 .substring pdf:compose.test 0 0
224 .ie '('\\*[pdf:compose.test]' \{\
226 .\" The supplied token represents the first element of a literal,
227 .\" but it may be a single element literal, which we simply handle
228 .\" as a regular token anyway.
230 . ds pdf:compose.test "\\$\\n(.$\"
231 . substring pdf:compose.test -1
232 . if !')'\\*[pdf:compose.test]' \{\
234 . \" The supplied token is the first of a sequence of elements
235 . \" which collectively define a literal, so start collecting a
236 . \" composite literal token, and change the "pdf*compose"
237 . \" state, to collect and append the remaining elements.
239 . ds pdf:composed.literal "\\$*\"
240 . als pdf*compose pdf*compose.literal
243 .el .ds pdf:compose.test )
244 .if ')'\\*[pdf:compose.test]' \{\
246 .\" The supplied token IS a regular token; add it, but ensure that
247 .\" the active maximum record length limit is honoured.
249 . pdf*length.increment "\\$*\"
250 . ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
252 . \" Adding this token would cause the current PDFMARK record, in
253 . \" groff's intermediate output file, to overflow the active record
254 . \" length limit, so post the current record and start another.
256 . pdf*pdfmark.dispatch
257 . ds pdf:composed.line "\\$*\"
261 . \" This token will fit in the current PDFMARK record, without
262 . \" violating the active length limit, so simply add it.
264 . ie d pdf:composed.line .as pdf:composed.line " \\$*\"
265 . el .ds pdf:composed.line "\\$*\"
269 .\" While assembling a multiple token literal sequence into a single
270 .\" literal token, successive calls to "pdf*compose" are directed
271 .\" to "pdf*compose.literal".
273 .de pdf*compose.literal
274 .\" ----------------------------------------------------------------
276 .\" .als pdf*compose pdf*compose.literal
277 .\" . pdf*compose TOKEN
278 .\" ----------------------------------------------------------------
280 .\" First, check to ensure that the current token can be appended to
281 .\" the accumulated literal, without extending it beyond the maximum
282 .\" allowed literal token length.
284 .length pdf:length "\\*[pdf:composed.literal] \\$*\"
285 .ie (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH] - 2)) \{\
287 .\" If it has grown too long, then it must be folded across two
288 .\" physical PDFMARK output records, so check if we can accommodate
289 .\" the portion collected so far within the current output record.
291 . pdf*length.increment "\\*[pdf:composed.literal]\"
292 . if (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH.MAX] - 2)) \{\
294 . \" The current output record CAN'T accommodate the currently
295 . \" composed portion of the literal, so flush out the current
296 . \" record, to make way for the accumulated literal, and mark
297 . \" the dispatch mode as "wrapped", for the fragments of the
298 . \" folded literal string, which are to follow.
300 . pdf*pdfmark.dispatch
301 . ds pdf*pdfmark.dispatch.wrapped
303 . ie d pdf:composed.line \{\
305 . \" If we DIDN'T need to flush the current output record,
306 . \" then we can simply append the accumulated literal to it...
308 . as pdf:composed.line " \\*[pdf:composed.literal]\"
312 . \" otherwise, when the current record has been flushed, or is
313 . \" empty, then we promote the accumulated literal, to make it
314 . \" the next output record...
316 . rn pdf:composed.literal pdf:composed.line
319 .\" Now, to complete the fold, flush out any accumulated partial
320 .\" output record, and continue accumulating the literal, starting
321 .\" with the current token.
323 . pdf*pdfmark.dispatch
324 . ds pdf:composed.literal "\\$*\"
328 .\" Alternatively, when we HAVEN'T identified a need to fold the
329 .\" current output record, then we simply append the current token
330 .\" to the accumulated literal token buffer string.
332 . as pdf:composed.literal " \\$*\"
335 .\" Having ensured that we have sufficient space, in which to
336 .\" append the current token to the currently accumulated literal,
337 .\" we check its rightmost character, to see if is the closing
338 .\" parenthesis, which completes the literal.
340 .ds pdf:compose.test \\$\\n(.$
341 .substring pdf:compose.test -1
342 .if ')'\\*[pdf:compose.test]' \{\
344 .\" The literal has been completely collected, so we may now append
345 .\" it to the current output record, as a single literal token, but
346 .\" subject to the constraint that it must not extend the output
347 .\" record beyond the maximum permitted length.
349 . pdf*length.increment "\\*[pdf:composed.literal]\"
350 . ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
352 . \" So, when the literal cannot be accommodated within the maximum
353 . \" length constraint, then we flush the current record, and start
354 . \" a new one, with the literal token as its first entry.
356 . pdf*pdfmark.dispatch
357 . rn pdf:composed.literal pdf:composed.line
361 . \" When the literal CAN be accommodated within the maximum length
362 . \" constraint, then ...
364 . ie d pdf:composed.line \{\
366 . \" When an output record has already been instantiated, we
367 . \" append the literal token to it, and discard the accumulator
368 . \" string, which is no longer required.
370 . as pdf:composed.line " \\*[pdf:composed.literal]\"
371 . rm pdf:composed.literal
375 . \" But when no output record yet exists, then we simply
376 . \" reassign the accumulated literal token, to instantiate a
377 . \" new output record.
379 . rn pdf:composed.literal pdf:composed.line
383 .\" Finally, since we have completed the accumulation of the literal, we
384 .\" revert to the "unwrapped" mode of operation for "pdf*pdfmark.dispatch",
385 .\" and restore the normal "pdf*compose" action, for collection of the next
388 . rm pdf*pdfmark.dispatch.wrapped
389 . als pdf*compose pdf*compose.next
392 .\" While composing a multiple record PDFMARK, each composed record
393 .\" must be added to the collection, whenever the partially composed
394 .\" output record has been filled; this is handled when necessary,
395 .\" by calling the "pdf*pdfmark.dispatch" macro.
397 .de pdf*pdfmark.dispatch
398 .\" ----------------------------------------------------------------
400 .\" .pdf*pdfmark.dispatch
401 .\" ----------------------------------------------------------------
403 .if d pdf:composed.line \{\
405 .\" This is simply a wrapper around the overloaded "pdf*pdfmark.post"
406 .\" macro, ensuring that an output record has actually been collected
407 .\" before attempting to post it; it then cleans up after posting, to
408 .\" ensure that each collected record is posted only once.
410 . if d pdf*pdfmark.dispatch.wrapped \{\
412 . \" When dispatching an excessively long literal string, which
413 . \" must be wrapped over multiple records, this mode is active
414 . \" for all but the closing record; we must escape the newline
415 . \" at the end of each such unclosed literal record.
417 . as pdf:composed.line " \\\\\\\\\"
420 . rm pdf:composed.line
423 .\" For each PDFMARK, the first call of "pdf*pdfmark.post" is directed
424 .\" to the "pdf*pdfmark.post.first" macro; this initialises the state
425 .\" of the "pdf:composed" macro, for assembly of a new PDFMARK.
427 .de pdf*pdfmark.post.first
428 . nop \!x X ps:exec \\*[pdf:composed.line]
430 .\" Subsequent calls to "pdf*pdfmark.post" are redirected to the
431 .\" alternative "pdf*pdfmark.post.next" macro, which simply appends
432 .\" additional PDFMARK records to the "pdf:composed" macro.
434 .als pdf*pdfmark.post pdf*pdfmark.post.next
436 .de pdf*pdfmark.post.next
437 . nop \!+\\*[pdf:composed.line]
439 .\" "pdf*end" is a dummy macro. It is required to mark the end
440 .\" of each individual fragment which is added to "pdf:composed";
441 .\" other than this, it does nothing.
446 .\" Some supporting macros defer actual pdfmark output until an
447 .\" appropriate time for it to be written; the "pdfsync" macro
448 .\" provides a mechanism for flushing such deferred output;
449 .\" it should be called from an end macro, and at any other time
450 .\" when it may be deemed necessary to flush pdfmark context.
453 .\" ----------------------------------------------------------------
455 .\" .pdfsync buffer ...
456 .\" Arguments indicate which "buffer(s)" to flush:
457 .\" O -> bookmark (outline) cache
458 .\" M -> document metadata diversion
459 .\" If no argument, flush ALL buffers
460 .\" ----------------------------------------------------------------
464 . if '\\$1'O' .pdf:bm.sync 1
466 . if dpdf:metadata .pdf:metadata
475 .\" some helper functions ...
477 .\" "pdf:warn" and "pdf:error" write diagnostic messages to stderr
480 .\" ----------------------------------------------------------
482 .\" .pdf:warn text of message
483 .\" ----------------------------------------------------------
485 .tm \\n(.F:\\n(.c: macro warning: \\$*
488 .\" ----------------------------------------------------------
490 .\" .pdf:error text of message
491 .\" ----------------------------------------------------------
493 .tm \\n(.F:\\n(.c: macro error: \\$*
495 .\" "pdf:pop", assisted by "pdf*pop", allows us to retrieve register,
496 .\" or string values, from a string masquerading as a data queue,
500 .\" ----------------------------------------------------------------
502 .\" .pdf:pop <type> <to-name> <from-name>
503 .\" $1 = nr for numeric register, ds for string
504 .\" $2 = name of register or string to be assigned
505 .\" $3 = name of string, from which data is to be retrieved
506 .\" ----------------------------------------------------------------
508 .pdf*pop \\$* \\*[\\$3]
514 .ie \\n(.$ .ds \\*[pdf:stack] \\$*
515 .el .rm \\*[pdf:stack]
520 .\" ===========================================================
521 .\" Module PDFINFO: Insert MetaData Entries into a PDF Document
522 .\" ===========================================================
525 .\" Output from the macros in this module is deferred, until
526 .\" subsequent invocation of .pdfsync, or .pdfexit
528 .\" ."pdfinfo" provides a general purpose form of metadata entry ...
529 .\" it allows arbitrary text to be associated with any specified
530 .\" metadata field name.
533 .\" -------------------------------------------------------------------
535 .\" .pdfinfo /FieldName field content ...
537 .\" .pdfinfo /Title A PDF Document
538 .\" .pdfinfo /Author Keith Marshall
539 .\" -------------------------------------------------------------------
541 .ds pdf:meta.field \\$1
544 \!.pdfmark \\*[pdf:meta.field] (\\$*) /DOCINFO
549 .\" Macro "pdfview" defines a special form of metadata entry ...
550 .\" it uses the /DOCVIEW pdfmark, to specify the initial (default) view,
551 .\" when the document is opened.
554 .\" -------------------------------------------------------------------
556 .\" .pdfview view parameters ...
558 .\" .pdfview /PageMode /UseOutlines
559 .\" .pdfview /Page 2 /View [/FitH \n(.p u]
560 .\" -------------------------------------------------------------------
563 \!.pdfmark \\$* /DOCVIEW
568 .\" =====================================================================
569 .\" Module PDFNOTE: Insert "Sticky Note" Style Comments in a PDF Document
570 .\" =====================================================================
572 .\" "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" set the preferred size for
573 .\" display of the "sticky note" pane, when opened. Acrobat Reader
574 .\" seems not to honour these -- perhaps GhostScript doesn't encode
575 .\" them correctly! Anyway, let's set some suitable default values,
576 .\" in case the user has a set up which does work as advertised.
578 .nr PDFNOTE.WIDTH 3.5i
579 .nr PDFNOTE.HEIGHT 2.0i
581 .\" "pdf:bbox" defines the expression used to set the size and location
582 .\" of the bounding rectangle for display of notes and link "hot-spots".
583 .\" This is defined, such that a note is placed at troff's current text
584 .\" position on the current page, with its displayed image size defined
585 .\" by the "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" registers, while the
586 .\" bounds for a link "hot-spot" are matched to the text region which
587 .\" defines the "hot-spot".
589 .ds pdf:bbox \\n[pdf:llx] u \\n[pdf:lly] u \\n[pdf:urx] u \\n[pdf:ury] u
591 .\" Getting line breaks into the text of a PDFNOTE is tricky -- we need
592 .\" to get a "\n" into the Postscript stream, but three levels of "\" are
593 .\" swallowed, when we invoke "pdfnote". The following definition of "PDFLB",
594 .\" (for LineBreak), is rather ugly, but does allow us to use
596 .\" .pdfnote Some text.\*[PDFLB]Some more text, on a new line.
598 .ds PDFLB \\\\\\\\\\\\\\\\n
601 .\" ----------------------------------------------------------------------
603 .\" .pdfnote [-T "Text for Title"] Text of note ...
604 .\" ----------------------------------------------------------------------
606 .if \\n[PDFOPMODE] \{\
608 .\" First, compute the bounding rectangle,
609 .\" for this PDFNOTE instance
612 . nr pdf:llx \\n(.k+\\n(.o+\\n[.in]
613 . nr pdf:lly \\n[pdf:ury]-\\n[PDFNOTE.HEIGHT]
614 . nr pdf:urx \\n[pdf:llx]+\\n[PDFNOTE.WIDTH]
615 . ds pdf:note.instance /Rect [\\*[pdf:bbox]]
617 .\" Parse any specified (recognisable) PDFNOTE options
619 . while dpdf:note\\$1 \{\
621 . shift \\n[pdf:note.argc]
624 .\" Emit the note, and clean up
626 . pdfmark \\*[pdf:note.instance] /Contents (\\$*) /ANN
627 . rm pdf:note.instance
633 .as pdf:note.instance " /Title (\\$2)
637 .\" =====================================================================
638 .\" Module PDFBOOKMARK: Add an Outline Reference in the PDF Bookmark Pane
639 .\" =====================================================================
641 .\" "PDFBOOKMARK.VIEW" controls how the document will be displayed,
642 .\" when the user selects a bookmark. This default setting will fit
643 .\" the page width to the viewing window, with the bookmarked entry
644 .\" located at the top of the viewable area.
646 .ds PDFBOOKMARK.VIEW /FitH \\n[PDFPAGE.Y] u
648 .\" "PDFOUTLINE.FOLDLEVEL" controls how the document outline will be
649 .\" displayed. It is a number, defining the maximum heading level
650 .\" which will be visible, without outline expansion by the user, in
651 .\" the initial view of the document outline. Assuming that no sane
652 .\" document will ever extend to 10,000 levels of nested headings,
653 .\" this initial default value causes outlines to be fully expanded.
655 .nr PDFOUTLINE.FOLDLEVEL 10000
657 .\" The actual job of creating an outline reference
658 .\" is performed by the "pdfbookmark" macro.
661 .\" ------------------------------------------------------------------
663 .\" .pdfbookmark [-T tag] level "Text of Outline Entry"
665 .\" $1 = nesting level for bookmark (1 is top level)
666 .\" $2 = text for bookmark, (in PDF viewer bookmarks list)
667 .\" $3 = suffix for PDF internal bookmark name (optional)
668 .\" ------------------------------------------------------------------
672 .\" When we are at the top diversion level, i.e. actually emitting text
673 .\" to the output device stream, then we compute the location of, and
674 .\" plant this bookmark immediately.
676 . if \\n[PDFOPMODE] \{\
678 . \" Make the bookmark name "untagged" by default,
679 . \" then parse any specified options, to set a "tag", if required
682 . while dpdf:href.opt\\$1 \{\
683 . pdf:href.opt\\$1 \\$@
684 . shift \\n[pdf:href.argc]
688 . \" If we found "--" to mark the end of the options, discard it
690 . if '\\$1'--' .shift
692 . \" Synchronise the bookmark cache
693 . \" to the requested bookmark nesting level
698 . \" Increment the bookmark serialisation index
699 . \" in order to generate a uniquely serialised bookmark name,
700 . \" ( which we return in the string "PDFBOOKMARK.NAME" ),
701 . \" and insert this bookmark into the cache
705 . ds PDFBOOKMARK.NAME pdf:bm\\n[pdf:bm.nr]\\*[pdf:href-T]
706 . ds pdf:bm\\n[pdf:bm.nr] /Dest /\\*[PDFBOOKMARK.NAME]
707 . pdfmark \\*[pdf:bm\\n[pdf:bm.nr]] /View [\\*[PDFBOOKMARK.VIEW]] /DEST
708 . as pdf:bm\\n[pdf:bm.nr] " /Title (\\$*)
709 . pdf:href.options.clear
715 .\" But when we are collecting a diversion which will be written out later,
716 .\" then we must defer bookmark placement, until we emit the diversion.
717 .\" (don't rely on $0 == pdfbookmark here; it may be a volatile alias).
719 . nop \!.pdfbookmark \\$@
723 .\" Macro "pdf:bm.sync" is called for each bookmark created,
724 .\" to establish a cache entry at the appropriate nesting level.
725 .\" It will flush ALL previous cache content, when called to
726 .\" add a new bookmark at level 1, or if simply called at
727 .\" level 1, without adding any bookmark.
730 .\" ------------------------------------------------------------------
732 .\" .pdf:bm.sync level
733 .\" $1 = nesting level of current bookmark, or 1 to flush cache
734 .\" ------------------------------------------------------------------
736 .\" First validate the bookmark nesting level
737 .\" adjusting it if required
739 .if \\$1>\\n[pdf:bm.nl] .nr pdf:bm.nl +1
740 .ie \\$1>\\n[pdf:bm.nl] \{\
741 . pdf:warn adjusted level \\$1 bookmark; should be <= \\n[pdf:bm.nl]
743 .el .nr pdf:bm.nl \\$1
744 .if \\n[pdf:bm.nl]<1 \{\
745 . pdf:warn bad arg (\\$1) in \\$0 \\$1; \\$0 1 forced
749 .\" If reverting from a higher to a lower nesting level,
750 .\" cyclicly adjust cache counts for each pending higher level
752 .if \\n[pdf:bm.lc]>=\\n[pdf:bm.nl] \{\
754 . if !rpdf:bm.c\\n[pdf:bm.lc].c .nr pdf:bm.c\\n[pdf:bm.lc].c 0
755 . while \\n[pdf:bm.lc]>\\n[pdf:bm.nl] \{\
756 . as pdf:bm.c\\n[pdf:bm.lc] " \\n[pdf:bm.c\\n[pdf:bm.lc].c]
757 . rr pdf:bm.c\\n[pdf:bm.lc].c
762 .\" Update the cache level,
763 .\" flushing when we are at level 1
765 .nr pdf:bm.lc \\n[pdf:bm.nl]
766 .ie \\n[pdf:bm.nl]=1 \{\
767 . while \\n[pdf:bm.ic]<\\n[pdf:bm.nr] .pdf:bm.emit 0
770 .el .nr pdf:bm.c\\n[pdf:bm.nl].c +1
772 .\" Macro "pdf:bm.emit" is called, when the cache is at level 1.
773 .\" This flushes ALL pending bookmarks from the cache, i.e. the
774 .\" preceding level 1 bookmark, and any nested dependents,
775 .\" which it may have.
778 .\" ------------------------------------------------------------------
780 .\" .pdf:bm.emit flag
781 .\" $1 = reference counting flag, used to control recursion
782 .\" ------------------------------------------------------------------
784 .\" First check for nested dependents,
785 .\" and append the "dependent count" to the bookmark, as required.
789 .pdf:pop nr pdf:bm.rc pdf:bm.c\\n[pdf:bm.lc]
790 .if \\n[pdf:bm.rc] \{\
792 . if \\n[pdf:bm.lc]>\\n[PDFOUTLINE.FOLDLEVEL] .ds pdf:bm.fold -
793 . as pdf:bm\\n[pdf:bm.ic] " /Count \\*[pdf:bm.fold]\\n[pdf:bm.rc]
796 .pdfmark \\*[pdf:bm\\n[pdf:bm.ic]] /OUT
797 .rm pdf:bm\\n[pdf:bm.ic]
799 .\" For ALL dependents, if any,
800 .\" recursively flush out any higher level dependents,
801 .\" which they themselves may have
803 .while \\n[pdf:bm.rc] \{\
805 . pdf:bm.emit \\n[pdf:bm.rc]
809 .\" unwind the recursive call stack, until we return to the top level.
820 .\" =============================================================
821 .\" Module PDFHREF: Create Hypertext References in a PDF Document
822 .\" =============================================================
824 .\" "PDFHREF.VIEW" controls how the document will be displayed,
825 .\" when the user follows a link to a named reference.
827 .ds PDFHREF.VIEW /FitH \\n[PDFPAGE.Y] u
829 .\" This default setting will fit the page width to the viewing
830 .\" window, with the bookmarked entry located close to the top
831 .\" of the viewable area. "PDFHREF.VIEW.LEADING" controls the
832 .\" actual distance below the top of the viewing window, where
833 .\" the reference will be positioned; 5 points is a reasonable
836 .nr PDFHREF.VIEW.LEADING 5.0p
839 .\" PDF view co-ordinates are mapped from the bottom left corner,
840 .\" of the page, whereas page printing co-ordinates are mapped
841 .\" conventionally, from top left.
843 .\" Macro "pdf:href.sety" transforms the vertical position of the
844 .\" last printed baseline, from the printing co-ordinate domain to
845 .\" the PDF view domain.
848 .\" ----------------------------------------------------------------
851 .\" ----------------------------------------------------------------
853 .\" This computation yields the vertical view co-ordinate
854 .\" in groff's basic units; don't forget to append grops' "u"
855 .\" conversion operator, when writing the pdfmark!
857 .nr PDFPAGE.Y \\n(.p-\\n(nl+\\n[PDFHREF.VIEW.LEADING]
859 .\" When we create a link "hot-spot" ...
860 .\" "PDFHREF.LEADING" sets the distance above the top of the glyph
861 .\" bounding boxes, in each line of link text, over which the link
862 .\" hot-spot will extend, while "PDFHREF.HEIGHT" sets the hot-spot
863 .\" height, PER LINE of text occupied by the reference.
865 .\" Since most fonts specify some leading space within the bounding
866 .\" boxes of their glyphs, a better appearance may be achieved when
867 .\" NEGATIVE leading is specified for link hot-spots; indeed, when
868 .\" the default 10pt Times font is used, -1.0 point seems to be a
869 .\" reasonable default value for "PDFHREF.LEADING" -- it may be
870 .\" changed, if desired.
872 .\" "PDFHREF.HEIGHT" is initially set as one vertical spacing unit;
873 .\" note that it is defined as a string, so it will adapt to changes
874 .\" in the vertical spacing. Changing it is NOT RECOMMENDED.
876 .nr PDFHREF.LEADING -1.0p
877 .ds PDFHREF.HEIGHT 1.0v
879 .\" PDF readers generally place a rectangular border around link
880 .\" "hot-spots". Within text, this looks rather ugly, so we set
881 .\" "PDFHREF.BORDER" to suppress it -- the three zeroes represent
882 .\" the border parameters in the "/Border [0 0 0]" PDFMARK string,
883 .\" and may be changed to any valid form, as defined in Adobe's
884 .\" PDFMARK Reference Manual.
886 .ds PDFHREF.BORDER 0 0 0
888 .\" "PDFHREF.COLOUR" (note British spelling) defines the colour to
889 .\" be used for display of link "hot-spots". This will apply both
890 .\" to borders, if used, and, by default to text; however, actual
891 .\" text colour is set by "PDFHREF.TEXT.COLOUR", which may be reset
892 .\" independently of "PDFHREF.COLOUR", to achieve contrasting text
893 .\" and border colours.
895 .\" "PDFHREF.COLOUR" must be set to a sequence of three values,
896 .\" each in the range 0.0 .. 1.0, representing the red, green, and
897 .\" blue components of the colour specification in the RGB colour
898 .\" domain, which is shared by "groff" and the PDF readers.
900 .ds PDFHREF.COLOUR 0.35 0.00 0.60
901 .defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR]
903 .\" "PDFHREF.TEXT.COLOUR", on the other hand, is simply defined
904 .\" using any "groff" colour name -- this default maps it to the
905 .\" same colour value as "PDFHREF.COLOUR".
907 .ds PDFHREF.TEXT.COLOUR pdf:href.colour
909 .\" Accommodate users who prefer the American spelling, COLOR, to
910 .\" the British spelling, COLOUR.
912 .als PDFHREF.COLOR PDFHREF.COLOUR
913 .als PDFHREF.TEXT.COLOR PDFHREF.TEXT.COLOUR
915 .\" All PDF "Hypertext" reference capabilities are accessed
916 .\" through the "pdfhref" macro
919 .\" -----------------------------------------------------------------
921 .\" .pdfhref <subcommand [options ...] [parameters ...]> ...
922 .\" -----------------------------------------------------------------
924 .if \\n[PDFOPMODE] \{\
926 .\" Loop over all subcommands specified in the argument list
930 . \" Initially, assume each subcommand will complete successfully
934 . \" Initialise -E and -X flags in the OFF state
939 . \" Handle the case where subcommand is specified as "-class",
940 . \" setting up appropriate macro aliases for subcommand handlers.
942 . if dpdf*href\\$1 .als pdf*href pdf*href\\$1
943 . if dpdf*href\\$1.link .als pdf*href.link pdf*href\\$1.link
944 . if dpdf*href\\$1.file .als pdf*href.file pdf*href\\$1.file
946 . \" Repeat macro alias setup
947 . \" for the case where the subcommand is specified as "class",
948 . \" (without a leading hyphen)
950 . if dpdf*href-\\$1 .als pdf*href pdf*href-\\$1
951 . if dpdf*href-\\$1.link .als pdf*href.link pdf*href-\\$1.link
952 . if dpdf*href-\\$1.file .als pdf*href.file pdf*href-\\$1.file
954 . \" Process one subcommand ...
958 . \" Subcommand "class" is recognised ...
959 . \" discard the "class" code from the argument list,
960 . \" set the initial argument count to swallow all arguments,
961 . \" and invoke the selected subcommand handler.
968 . \" discard all arguments actually consumed by the handler,
969 . \" before proceeding to the next subcommand (if any).
971 . shift \\n[pdf:argc]
975 . \" Subcommand "class" is not recognised ...
976 . \" issue a warning, and discard the entire argument list,
977 . \" so aborting this "pdfhref" invocation
979 . pdf:warn \\$0: undefined reference class '\\$1' ignored
983 . \" Clean up temporary reference data,
984 . \" to ensure it doesn't propagate to any future reference
986 . rm pdf*href pdf:href.link pdf:href.files
987 . rr pdf:href-E pdf:href-X
988 . pdf:href.options.clear
994 .\" Macros "pdf:href.flag" and "pdf:href.option"
995 .\" provide a generic mechanism for switching on flag type options,
996 .\" and for decoding options with arguments, respectively
999 .\" ----------------------------------------------------------------------
1000 .\" ----------------------------------------------------------------------
1005 .\" ----------------------------------------------------------------------
1006 .\" ----------------------------------------------------------------------
1007 .ds pdf:href\\$1 \\$2
1011 .\" Valid PDFHREF options are simply declared
1012 .\" by aliasing option handlers to "pdf:href.option",
1013 .\" or to "pdf:href.flag", as appropriate
1015 .als pdf:href.opt-A pdf:href.option \" affixed text
1016 .als pdf:href.opt-D pdf:href.option \" destination name
1017 .als pdf:href.opt-E pdf:href.flag \" echo link descriptor
1018 .als pdf:href.opt-F pdf:href.option \" remote file specifier
1019 .als pdf:href.opt-N pdf:href.option \" reference name
1020 .als pdf:href.opt-P pdf:href.option \" prefixed text
1021 .als pdf:href.opt-T pdf:href.option \" bookmark "tag"
1022 .als pdf:href.opt-X pdf:href.flag \" cross reference
1024 .\" For references to another document file
1025 .\" we also need to support OS dependent file name specifiers
1027 .als pdf:href.opt-DF pdf:href.option \" /DOSFile specifier
1028 .als pdf:href.opt-MF pdf:href.option \" /MacFile specifier
1029 .als pdf:href.opt-UF pdf:href.option \" /UnixFile specifier
1030 .als pdf:href.opt-WF pdf:href.option \" /WinFile specifier
1032 .\" Macro "pdf:href.options.clear" ensures that ALL option
1033 .\" argument strings are deleted, after "pdfhref" has completed
1034 .\" all processing which depends on them
1036 .de pdf:href.options.clear
1037 .\" -----------------------------------------------------------------
1039 .\" .pdf:href.options.clear [option ...]
1040 .\" -----------------------------------------------------------------
1042 .\" When an option list is specified ...
1046 . \" then loop through the list,
1047 . \" deleting each specified option argument string in turn
1050 . if dpdf:href-\\$1 .rm pdf:href-\\$1
1055 .\" ... but when no list is specified,
1056 .\" then recurse, to clear all known option argument strings
1058 .el .pdf:href.options.clear A D F N P T DF MF UF WF
1061 .\" "PDFHREF.INFO" establishes the content of the cross reference
1062 .\" data record, which is exported via the "stderr" stream, when a
1063 .\" cross reference anchor is created using a "pdfhref" macro request
1066 .\" .pdfhref M -N name -X text ...
1068 .\" .ds PDFHREF.INFO \\*[PDFHREF.NAME] reference data ...
1070 .ds PDFHREF.INFO page \\n% \\$*
1072 .\" Macro "pdf*href-M" is the handler invoked by "pdfhref", when
1073 .\" called with the "M" reference class specifier, to create a
1074 .\" named cross reference mark, and to emit a cross reference
1075 .\" data record, as specified by "PDFHREF.INFO".
1078 .\" -----------------------------------------------------------------
1080 .\" .pdfhref M [-X] [-N name | -D name] [-E] descriptive text ...
1081 .\" -----------------------------------------------------------------
1083 .\" Initially, declare the -D and -N string options as empty,
1084 .\" so we avoid warning messages when we try to use them, and find
1085 .\" that they are undefined.
1090 .\" Parse, interpret, and strip any specified options from the
1091 .\" argument list. (Note that only options with a declared handler
1092 .\" will be processed; there is no provision for detecting invalid
1093 .\" options -- anything which is not recognised is assumed to start
1094 .\" the "descriptive text" component of the argument list).
1096 .while dpdf:href.opt\\$1 \{\
1097 . pdf:href.opt\\$1 \\$@
1098 . shift \\n[pdf:href.argc]
1101 .\" If we found "--", to mark the end of the options,
1102 .\" then we should discard it.
1104 .if '\\$1'--' .shift
1106 .\" All PDF reference markers MUST be named. The name may have been
1107 .\" supplied using the "-N Name" option, (or the "-D Name" option);
1108 .\" if not, deduce it from the first "word" in the "descriptive text",
1109 .\" if any, and set the marker -- if we still can't identify the name
1110 .\" for the destination, then this marker will not be created.
1112 .pdf*href.set \\*[pdf:href-N] \\*[pdf:href-D] \\$1
1114 .\" If we specified a cross reference, with the "-X" option, and the
1115 .\" reference mark has been successfully created, then we now need to
1116 .\" write the cross reference info to the STDERR stream
1118 .if \\n[pdf:href-X] .pdf*href.export \\*[PDFHREF.INFO]
1120 .\" Irrespective of whether this marker is created, or not,
1121 .\" the descriptive text will be copied to the groff output stream,
1122 .\" provided the "-E" option was specified
1124 .if \\n[pdf:href-E] \&\\$*
1128 .\" ----------------------------------------------------------------------
1129 .\" ----------------------------------------------------------------------
1133 . \" a marker name has been supplied ...
1134 . \" if we are formatting for immediate output,
1135 . \" emit PDFMARK code to establish the associated view
1139 . pdfmark /Dest /\\$1 /View [\\*[PDFHREF.VIEW]] /DEST
1140 . ds PDFHREF.NAME \\$1
1144 . \" but, when formatting a diversion ...
1145 . \" delay output of the PDFMARK code, until the diversion
1146 . \" is eventually written out
1150 . \" check if we also need to emit cross reference data
1151 . \" (caller will do this if "pdf:href-X" is set, but it is
1152 . \" not necessary, when "pdf:href.map" already exists)
1154 . if dpdf:href.map .nr pdf:href-X 0
1157 . \" marker is unnamed ...
1158 . \" issue error message; do not emit reference data
1160 . pdf:warn pdfhref destination marker must be named
1166 .\" Called ONLY by "pdf*href-M",
1167 .\" this macro ensures that the emission of exported reference data
1168 .\" is synchronised with the placement of the reference mark,
1169 .\" especially when the mark is defined within a diversion.
1171 .ie '\\n(.z'' .tm gropdf-info:href \\*[PDFHREF.NAME] \\$*
1175 .\" Macro "pdf*href-D" is invoked when "pdfhref" is called
1176 .\" with the "D" reference class specifier; it provides a
1177 .\" standardised mechanism for interpreting reference data
1178 .\" exported by the "M" reference class, and may be used
1179 .\" to directly define external reference data, without the
1180 .\" use of "M" reference class designators in the source
1186 .\" Parse, interpret, and strip any specified options from the
1187 .\" argument list. (Note that only options with a declared handler
1188 .\" will be processed; there is no provision for detecting invalid
1189 .\" options -- anything which is not recognised is assumed to start
1190 .\" the "descriptive text" component of the argument list).
1192 .while dpdf:href.opt\\$1 \{\
1193 . pdf:href.opt\\$1 \\$@
1194 . shift \\n[pdf:href.argc]
1197 .\" If we found "--", to mark the end of the options,
1198 .\" then we should discard it.
1200 .if '\\$1'--' .shift
1202 .ie '\\*[pdf:href-N]'' \{\
1203 . pdf:warn pdfhref defined reference requires a name
1206 . ds pdf:href(\\*[pdf:href-N]).info \\$*
1210 .\" Macro "pdf*href-F" is invoked when "pdfhref" is called
1211 .\" with the "F" reference class specifier; it allows the user
1212 .\" to provide an alternative interpreter macro, which will be
1213 .\" called when a "PDFHREF.INFO" record is retrieved to define
1214 .\" the text of a cross reference link "hot spot".
1217 .\" ----------------------------------------------------------------
1219 .\" .pdfhref F [macro-name]
1220 .\" ----------------------------------------------------------------
1222 .\" Set macro specified by "macro-name" as the format interpreter
1223 .\" for parsing "PDFHREF.INFO" records; if "macro-name" is omitted,
1224 .\" or is specified as the reserved name "default", then use the
1225 .\" default format parser, "pdf*href.format", defined below.
1227 .if '\\$1'default' .shift \\n(.$
1228 .ie \\n(.$ .als pdf*href.format \\$1
1229 .el .als pdf*href.format pdf*href.default
1232 .\" The default reference formatting macro is defined below.
1233 .\" It parses the "PDFHREF.INFO" record specific to each reference,
1234 .\" recognising the keywords "file", "page" and "section", when they
1235 .\" appear in initial key/value pairs, replacing the key/value pair
1236 .\" with "PDFHREF.FILEREF", "PDFHREF.PAGEREF" or "PDFHREF.SECTREF"
1237 .\" respectively; any additional data in the "PDFHREF.INFO" record
1238 .\" is enclosed in typographic double quotes, and the parsed record
1239 .\" is appended to "PDFHREF.PREFIX", to be returned as the formatted
1242 .\" Default definitions for the reference strings "PDFHREF.PREFIX",
1243 .\" "PDFHREF.FILEREF", "PDFHREF.PAGEREF" and "PDFHREF.SECTREF" are
1244 .\" provided, in the English language. Users may substitute any
1245 .\" desired alternative definitions, for example, when formatting
1246 .\" documents in other languages. In each case, "\\$1" may be used
1247 .\" in the substitution, to represent the "value" component of the
1248 .\" respective key/value pair specified in the "PDFHREF.INFO" record.
1250 .ds PDFHREF.PREFIX see
1251 .ds PDFHREF.PAGEREF page \\$1,
1252 .ds PDFHREF.SECTREF section \\$1,
1253 .ds PDFHREF.FILEREF \\$1
1256 .\" -----------------------------------------------------------------
1257 .\" Usage: (to be called ONLY by "pdfhref")
1258 .\" .pdf*href.format cross reference data ...
1259 .\" -----------------------------------------------------------------
1261 .\" This macro is responsible for defining the strings "PDFHREF.TEXT"
1262 .\" and "PDFHREF.DESC", which are used by the "pdfhref" macro, as the
1263 .\" basis for generating the text content of a link "hot spot"; (any
1264 .\" user specified alternate formatter MUST do likewise).
1266 .\" Note that "PDFHREF.TEXT" defines the overall format for the "link
1267 .\" text", while "PDFHREF.DESC" is the descriptive component thereof.
1269 .\" This default implementation, subject to user customisation of the
1270 .\" "internationalisation" strings defined above, formats "hot spots"
1273 .\" see page N, section S, "descriptive text ..."
1275 .ds PDFHREF.TEXT \\*[PDFHREF.PREFIX]
1276 .while d\\$0.\\$1 \{\
1281 .\" Retrieve the descriptive text from the cross reference data,
1282 .\" ONLY IF no overriding description has been set by the calling
1283 .\" "pdfhref" macro invocation.
1285 .if \\n(.$ .if !dPDFHREF.DESC .ds PDFHREF.DESC \\$*
1287 .\" Augment "PDFHREF.TEXT" so the descriptive text will be included
1288 .\" in the text of the formatted reference
1290 .if dPDFHREF.DESC .as PDFHREF.TEXT " \(lq\\\\*[PDFHREF.DESC]\(rq
1292 .\" Finally, suppress any leading spaces,
1293 .\" which may have been included in the PDFHREF.TEXT definition.
1295 .ds PDFHREF.TEXT \\*[PDFHREF.TEXT]
1297 .de pdf*href.format.file
1298 .\" ----------------------------------------------------------------------
1299 .\" Include a file identifier in a formatted reference.
1300 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1301 .\" reference data includes an initial file identifier tuple.
1302 .\" ----------------------------------------------------------------------
1304 .as PDFHREF.TEXT " \\*[PDFHREF.FILEREF]
1306 .de pdf*href.format.page
1307 .\" ----------------------------------------------------------------------
1308 .\" Include a page number in a formatted reference.
1309 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1310 .\" reference data includes an initial page number tuple.
1311 .\" ----------------------------------------------------------------------
1313 .as PDFHREF.TEXT " \\*[PDFHREF.PAGEREF]
1315 .de pdf*href.format.section
1316 .\" ----------------------------------------------------------------------
1317 .\" Include a section number in a formatted reference.
1318 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1319 .\" reference data includes an initial section number tuple.
1320 .\" ----------------------------------------------------------------------
1322 .as PDFHREF.TEXT " \\*[PDFHREF.SECTREF]
1325 .\" Make "pdf*href.format" the default cross reference formatter
1327 .als pdf*href.default pdf*href.format
1330 .\" Macro "pdf*href" provides a generic mechanism for placing link
1331 .\" "hot-spots" in a PDF document. ALL "pdfhref" class macros which
1332 .\" create "hot-spots" are aliased to this macro; each must also have
1333 .\" an appropriately aliased definition for "pdf*href.template".
1336 .\" ------------------------------------------------------------------
1338 .\" .pdf*href class [options ...] [link text ...]
1339 .\" ------------------------------------------------------------------
1341 .\" First, we initialise an empty string, which will be affixed to
1342 .\" the end of the "link text". (This is needed to cancel the effect
1343 .\" of a "\c" escape, which is placed at the end of the "link text"
1344 .\" to support the "-A" option -- any text supplied by the user, when
1345 .\" the "-A" option is specified, will replace this empty string).
1349 .\" Now we interpret, and remove any specified options from the
1350 .\" argument list. (Note that only options with a declared handler
1351 .\" will be processed; there is no provision for detecting invalid
1352 .\" options -- anything which is not recognised is assumed to start
1353 .\" the "link text" component of the argument list).
1355 .while dpdf:href.opt\\$1 \{\
1356 . pdf:href.opt\\$1 \\$@
1357 . shift \\n[pdf:href.argc]
1360 .\" If we found "--", to mark the end of the options, then we should
1363 .if '\\$1'--' .shift
1365 .\" All PDF link classes REQUIRE a named destination. This may have
1366 .\" been supplied using the "-D Name" option, but, if not, deduce it
1367 .\" from the first "word" in the "link text", if any -- if we still
1368 .\" can't identify the destination, then set "pdf:href.ok" to zero,
1369 .\" so this link will not be created.
1371 .if !dpdf:href-D .pdf:href.option -D \\$1
1372 .if '\\*[pdf:href-D]'' \{\
1373 . pdf:error pdfhref has no destination
1377 .\" Some PDF link classes support a "/File (FilePathName)" argument.
1379 .if dpdf*href.file \{\
1381 . \" When this is supported, it may be specified by supplying
1382 . \" the "-F FileName" option, which is captured in "pdf:href-F".
1384 . if dpdf:href-F \{\
1386 . \" the /File key is present, so set up the link specification
1387 . \" to establish the reference to the specified file
1389 . als pdf*href.link pdf*href.file
1390 . ds pdf:href.files /File (\\*[pdf:href-F])
1392 . \" in addition to the /File key,
1393 . \" there may also be platform dependent alternate file names
1395 . if dpdf:href-DF .as pdf:href.files " /DOSFile (\\*[pdf:href-DF])
1396 . if dpdf:href-MF .as pdf:href.files " /MacFile (\\*[pdf:href-MF])
1397 . if dpdf:href-UF .as pdf:href.files " /UnixFile (\\*[pdf:href-UF])
1398 . if dpdf:href-WF .as pdf:href.files " /WinFile (\\*[pdf:href-WF])
1400 . \" In some cases, the "/File" key is REQUIRED.
1401 . \" We will know it is missing, if "pdf*href.link" is not defined.
1403 . if !dpdf*href.link \{\
1405 . \" When a REQUIRED "/File" key specification is not supplied,
1406 . \" then complain, and set "pdf:href.ok" to abort the creation
1407 . \" of the current reference.
1409 . pdf:error pdfhref: required -F specification omitted
1412 . \" Now, we have no further use for "pdf*href.file".
1417 .\" Now, initialise a string, defining the PDFMARK code sequence
1418 .\" to create the reference, using the appropriate type indicators.
1420 .ds pdf:href.link /Subtype /Link \\*[pdf*href.link]
1422 .\" And now, we have no further use for "pdf*href.link".
1426 .\" If the user specified any "link prefix" text, (using the "-P text"
1427 .\" option), then emit it BEFORE processing the "link text" itself.
1429 .if dpdf:href-P \&\\*[pdf:href-P]\c
1430 .ie \\n[pdf:href.ok] \{\
1432 . \" This link is VALID (so far as we can determine) ...
1433 . \" Modify the "link text" argument specification, as required,
1434 . \" to include any pre-formatted cross reference information
1438 . \" One or more "link text" argument(s) are present,
1439 . \" so, set the link description from the argument(s) ...
1441 . ds PDFHREF.DESC \\\\$*
1442 . ie \\n[pdf:href-X] \{\
1444 . \" ... and, when the "-X" flag is set,
1445 . \" also include formatted location information,
1446 . \" derived from the cross reference record.
1448 . pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
1451 . \" ... but, when the "-X" flag is NOT set,
1452 . \" use only the argument(s) as the entire content
1453 . \" of the "link text"
1455 . rn PDFHREF.DESC PDFHREF.TEXT
1459 . \" No "link text" arguments are present,
1460 . \" so, format the cross reference record to define
1461 . \" the content of the "link text".
1463 . pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
1465 . \" Apply border and colour specifications to the PDFMARK string
1466 . \" definition, as required.
1468 . if dPDFHREF.BORDER .as pdf:href.link " /Border [\\*[PDFHREF.BORDER]]
1469 . if dPDFHREF.COLOUR .as pdf:href.link " /Color [\\*[PDFHREF.COLOUR]]
1471 . \" Emit the "link text", in its appropriate colour, marking the
1472 . \" limits of its bounding box(es), as the before and after output
1473 . \" text positions.
1475 . pdf*href.mark.begin "\\*[pdf:href.link]"
1476 . if dPDFHREF.COLOUR .defcolor pdf:href.colour rgb \\*[PDFHREF.COLOUR]
1477 . nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\\*[PDFHREF.TEXT]\m[]\c
1480 . \" Clean up the temporary registers and strings, used to
1481 . \" compute the "hot-spot" bounds, and format the reference,
1483 . rm PDFHREF.DESC PDFHREF.TEXT
1486 .\" But when we identify an INVALID link ...
1487 .\" We simply emit the "link text", with no colour change, no border,
1488 .\" and no associated "hot-spot".
1492 .\" And then, if the user specified any affixed text, (using the
1493 .\" "-A text" option), we tack it on at the end.
1495 .nop \&\\*[pdf:href-A]
1497 .de pdf*href.map.init
1498 .\" ----------------------------------------------------------------------
1499 .\" ----------------------------------------------------------------------
1501 .if dpdf:href.map-1 \{\
1503 . \" We have a reference map, but we haven't started to parse it yet.
1504 . \" This must be the first map reference in pass 2, so we need to
1505 . \" "kick-start" the parsing process, by loading the first indexed
1506 . \" sub-map into the global map.
1508 . rn pdf:href.map-1 pdf:href.map
1509 . als pdf:href.map.internal pdf:href.map
1510 . nr pdf:href.map.index 1 1
1512 .als pdf*href.map.init pdf*href.mark.idle
1515 .\" "pdf*href-Z" is used to add link co-ordinate entries to the
1516 .\" "pdf:href.map". Primarily, it is used by the "pdfroff" formatter,
1517 .\" to pass link co-ordinate data from one "groff" formatting pass to
1518 .\" the next, and is not generally useful to the end user.
1521 .\" ----------------------------------------------------------------------
1523 .\" .pdfhref Z page-index x-displacement y-displacement
1525 .\" page-index is the reference mark's page number
1526 .\" x-displacement is its offset from the left edge of the page
1527 .\" y-displacement is its offset from the top edge of the page
1528 .\" ( both displacement values are expressed in basic groff units, )
1529 .\" ( and measured perpendicular to their respective page edges. )
1530 .\" ----------------------------------------------------------------------
1532 .ie \\n(.$=3 .ds pdf:href.map-\\n+[pdf*href-Z.index] \\$*
1533 .el .pdf:error pdfhref Z operator expects exactly three arguments
1535 .\" Initialise the auto-incrementing "pdf*href-Z.index" register,
1536 .\" to ensure that sub-map numbering starts at 1.
1538 .nr pdf*href-Z.index 0 1
1540 .de pdf*href.map.read
1541 .\" ----------------------------------------------------------------------
1542 .\" Usage: (internal use only):
1543 .\" .pdf*href.map.read co-ordinate name list ...
1544 .\" ----------------------------------------------------------------------
1546 .\" Reads values from "pdf:href.map" to each named register, in turn
1547 .\" Reading to "null" discards the corresponding value in "pdf:href.map"
1551 . \" Loop over all registers named in the argument list,
1552 . \" assigning values from "pdf:href.map" to each in turn.
1554 . pdf:pop nr pdf:\\$1 pdf:href.map.internal
1555 . if !dpdf:href.map.internal \{\
1557 . \" We ran out of map references in the current sub-map,
1558 . \" so move on to the next indexed sub-map, if any.
1560 . if dpdf:href.map-\\n+[pdf:href.map.index] \{\
1561 . rn pdf:href.map-\\n[pdf:href.map.index] pdf:href.map
1562 . als pdf:href.map.internal pdf:href.map
1566 . \" Proceed to the next named co-ordinate, (if any), specified
1567 . \" in the argument list.
1572 .\" Discard any assignments to a register named "null"
1576 .de pdf*href.mark.begin
1577 .\" ----------------------------------------------------------------------
1578 .\" ----------------------------------------------------------------------
1580 .ie dpdf:href.map \{\
1582 . \" Once we have established a document reference map,
1583 . \" then this, and all subsequent calls to "pdf*href.mark.begin",
1584 . \" may be redirected to the reference mark resolver, and the
1585 . \" "pdf*href.mark.end" macro has nothing further to do.
1587 . pdf*href.mark.resolve \\$@
1588 . als pdf*href.mark.begin pdf*href.mark.resolve
1589 . als pdf*href.mark.end pdf*href.mark.idle
1592 . \" Since we don't yet have a document reference map, the
1593 . \" reference mark resolver will not work, in this pass of the
1594 . \" formatter; this, and all subsequent calls to "pdf*href.mark.begin",
1595 . \" may be redirected to "pdf*href.mark.end", which is responsible
1596 . \" for emitting the reference mark data to be incorporated into
1597 . \" the reference map in a subsequent formatting pass.
1600 . als pdf*href.mark.begin pdf*href.mark.end
1603 .de pdf*href.mark.resolve
1604 .\" ----------------------------------------------------------------------
1605 .\" ----------------------------------------------------------------------
1607 . ds pdf:href.link \\$1
1608 . nr pdf:urx \\n(.o+\\n(.l
1609 . pdf*href.map.read spg llx ury epg urx.end lly.end
1610 . ie \\n[pdf:spg]=\\n[pdf:epg] \{\
1612 . \" This link is entirely contained on a single page ...
1613 . \" emit the text, which defines the content of the link region,
1614 . \" then make it active.
1616 . pdf*href.mark.emit 1 \\n[pdf:urx.end]
1617 . if \\n[pdf:lly]<\\n[pdf:lly.end] \{\
1619 . \" This link spans multiple output lines; we must save its
1620 . \" original end co-ordinates, then define a new intermediate
1621 . \" end point, to create a PDFMARK "hot-spot" extending from
1622 . \" the start of the link to the end if its first line.
1625 . nr pdf:llx \\n(.o+\\n[.in]
1626 . nr pdf:lly \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1627 . if \\n[pdf:ury]<\\n[pdf:lly] \{\
1628 . nr pdf:lly +\\*[PDFHREF.HEIGHT]-1v
1629 . pdf*href.mark.emit 2
1630 . nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1632 . pdf*href.mark.emit 0 \\n[pdf:urx.end]
1634 . pdf*href.mark.flush
1637 . \" This link is split across a page break, so ...
1638 . \" We must mark the "hot-spot" region on the current page,
1639 . \" BEFORE we emit the link text, as we will have moved off
1640 . \" this page, by the time the text has been output.
1642 . \" First step: define the region from the start of the link,
1643 . \" to the end of its first line.
1645 . pdf*href.mark.emit 1 \\n[pdf:urx]
1647 . \" All additional regions MUST align with the left margin.
1649 . nr pdf:llx \\n(.o+\\n[.in]
1651 . \" If the current page can accommodate more than the current line,
1652 . \" then it will include a second active region for this link; this
1653 . \" will extend from just below the current line to the end of page
1654 . \" trap, if any, or the bottom of the page otherwise, and occupy
1655 . \" the full width of the page, between the margins.
1658 . pdf*href.mark.emit 3
1660 . \" We now need a page transition trap, to map the active link
1661 . \" region(s), which overflow on to the following page(s); (the
1662 . \" handler for this trap MUST have been previously installed).
1664 . ie dpdf*href.mark.hook \{\
1666 . \" The page transition trap handler has been installed,
1667 . \" so we may activate both it, and also the appropriate
1668 . \" termination handler, to deactivate it when done.
1670 . als pdf*href.mark.hook pdf*href.mark.trap
1672 . \" Now we set up "pdf:epg" to count the number of page breaks
1673 . \" which this link will span, and emit the link text, leaving
1674 . \" the page trap macro to map active regions on intervening
1675 . \" pages, which are included in the link.
1677 . nr pdf:epg -\\n[pdf:spg] 1
1680 . \" There was no handler initialised for the page trap,
1681 . \" so we are unable to map the active regions for this link;
1682 . \" we may discard the remaining map data for this link,
1683 . \" and issue a diagnostic.
1685 . pdf:error pdfhref: link dissociated at page break (trap not initialised)
1686 . if dPDFHREF.BROKEN.COLOR \{\
1688 . \" The user may opt to have such broken links highlighted.
1689 . \" We use "PDFHREF.BROKEN.COLOUR" to specify this requirement,
1690 . \" but the user may prefer the American spelling, so we will
1691 . \" handle both as equivalent.
1693 . als PDFHREF.BROKEN.COLOUR PDFHREF.BROKEN.COLOR
1695 . if dPDFHREF.BROKEN.COLOUR \{\
1696 . if dPDFHREF.COLOUR .als PDFHREF.COLOUR PDFHREF.BROKEN.COLOUR
1704 .\" Macro "pdf*href.mark.emit" is called only by "pdf*href". It is
1705 .\" responsible for emitting the PDFMARK code, to establish the
1706 .\" "hot-spot" region associated with a document or resource link.
1708 .de pdf*href.mark.emit
1709 .\" ----------------------------------------------------------------------
1711 .\" .pdf*href.mark.emit <action> [<end-urx>]
1712 .\" <action> == 0 --> normal operation -- link height = 1 line
1713 .\" <action> == 1 --> start of link -- add leading above text
1714 .\" <action> == 2 --> overtall link -- set intermediate baseline
1715 .\" <action> == 3 --> split link -- break at bottom of page
1716 .\" ----------------------------------------------------------------------
1720 . \" Initialising a new link region ...
1721 . \" Some different versions of "groff" disagree about the vertical
1722 . \" displacement of "opminy", as emitted by "\O1|\h'-\w"|"u'\O2\c",
1723 . \" relative to the current text baseline. Therefore, recompute
1724 . \" the link displacement, independently of "opminy".
1727 . while \\n[pdf:ury.base]<\\n[pdf:ury] .nr pdf:ury.base +1v
1728 . nr pdf:ury.base -1m+\\n[PDFHREF.LEADING]
1730 . \" adjust the end-point vertical displacement by the same offset,
1731 . \" and then relocate the link starting point to its new displacement,
1732 . \" as established by this base line relative computation.
1734 . nr pdf:lly.end +\\n[pdf:ury.base]-\\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1735 . rnn pdf:ury.base pdf:ury
1739 . \" Link segment fits on a single line ...
1740 . \" Set its height and end-point horizontal displacement accordingly.
1742 . nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1743 . if \\n[pdf:lly]>=\\n[pdf:lly.end] .nr pdf:urx \\$2
1747 . \" Link segment extends beyond the next page break ...
1748 . \" Recompute truncated height, to just fit portion on current page,
1749 . \" recursing to emit it, and leaving page trap mechanism to place
1750 . \" continuation region(s) on following page(s).
1752 . nr pdf:lly (\\n[.t]u-\\n[.V]u)/1v
1753 . if \\n[pdf:lly]>0 \{\
1754 . nr pdf:lly \\n[pdf:ury]+\\n[pdf:lly]v-1v+\\*[PDFHREF.HEIGHT]
1755 . pdf*href.mark.emit 2
1759 . \" Link region size and placement has been fully specified ...
1762 . pdfmark \\*[pdf:href.link] /Rect [\\*[pdf:bbox]] /ANN
1766 .\" When "pdf*href" emits a link for which the "hot-spot" spans a
1767 .\" page break, then we need to provide a "hook" in to the page break
1768 .\" trap, so we can map the "hot-spot" regions which are to be placed
1769 .\" on either side of the page break.
1771 .\" Macro "pdf*href.mark.idle" is a dummy macro, which provide this
1772 .\" "hook" for normal page breaks, where there is no link "hot-spot"
1773 .\" crossing the break.
1775 .de pdf*href.mark.idle
1776 .\" ----------------------------------------------------------------------
1778 .\" Called only as an internal hook, by a page trap macro.
1779 .\" Expects no arguments, and does nothing.
1780 .\" ----------------------------------------------------------------------
1783 .\" Macro "pdf*href.mark.trap" is the active "hook", which is substituted
1784 .\" for "pdf*href,mark.idle" at those page breaks which are crossed by
1785 .\" a link "hot-spot".
1787 .de pdf*href.mark.trap
1788 .\" ----------------------------------------------------------------------
1790 .\" Called only as an internal hook, by a page trap macro.
1791 .\" Expects no arguments. Maps residual link "hot-spot" regions,
1792 .\" which spill beyond any page break. Not to be invoked directly
1793 .\" by the user, nor by any user supplied macro.
1794 .\" ----------------------------------------------------------------------
1797 .nr pdf:ury +1v-1m-\\n[PDFHREF.LEADING]
1798 .ie \\n-[pdf:epg] \{\
1800 . \" The link "hot-spot" extends across more than one page break,
1801 . \" so, for each page which is completely contained within the
1802 . \" extent of the link, simply mark the entire text area on the
1803 . \" page as a "hot-spot".
1805 . pdf*href.mark.emit 3
1808 . \" The link "hot-spot" ends on the page which immediately follows
1809 . \" the current page transition, so we may now finalise this link.
1811 . nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1812 . if \\n[pdf:lly.end]>\\n[pdf:lly] \{\
1814 . \" The "hot-spot" extends beyond the first line of text,
1815 . \" on its final page; compute and emit "hot-spot" region to cover
1816 . \" the full with of the text area, including all but the last
1817 . \" line of the link text.
1819 . while \\n[pdf:lly.end]>\\n[pdf:lly] .nr pdf:lly +1v
1821 . pdf*href.mark.emit 2
1823 . \" Now, adjust the vertical "hot-spot" mapping reference,
1824 . \" to identify the correct position for the the last line of
1825 . \" text, over which the "hot-spot" extends.
1827 . nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1830 . \" We now have exactly one final line of text, over which we must
1831 . \" emit a "hot-spot" region; map it, terminate page trap processing
1832 . \" for this "hot-spot", and clean up the "hot-spot" mapping context.
1834 . pdf*href.mark.emit 0 \\n[pdf:urx.end]
1835 . als pdf*href.mark.hook pdf*href.mark.idle
1836 . pdf*href.mark.flush
1839 .de pdf*href.mark.flush
1840 .\" ----------------------------------------------------------------------
1841 .\" ----------------------------------------------------------------------
1843 .rr pdf:llx pdf:lly pdf:urx pdf:ury
1844 .if dPDFHREF.COLOR .als PDFHREF.COLOUR PDFHREF.COLOR
1845 .rr pdf:urx.end pdf:lly.end
1847 .de pdf*href.mark.end
1848 .\" ----------------------------------------------------------------------
1849 .\" ----------------------------------------------------------------------
1852 .\" Macro "pdf*href-I" is used for one time initialisation of special
1853 .\" "pdfhref" features; (currently, only the above page trap hook is
1854 .\" supported, but it is implemented with one level of indirection, to
1855 .\" accommodate possible future expansion).
1858 .\" ----------------------------------------------------------------------
1860 .\" .pdfhref I -<option> <optarg> [-<option> <optarg>] ...
1861 .\" ----------------------------------------------------------------------
1863 .\" Loop over all arguments, in pairs ...
1867 . \" handing them off to their respective initialisers,
1868 . \" when suitable initialisers exist, or complaining otherwise.
1870 . ie dpdf*href\\$1.init .pdf*href\\$1.init \\$2
1871 . el .pdf*error pdfhref:init: unknown feature '\\$1'
1875 .\" Before we can use the page break "hook", we need to initialise it
1876 .\" as an addendum to a regular page break trap. To ensure that we don't
1877 .\" compromise the user's page trap setup, we leave the onus for this
1878 .\" initialisation with the user, but we provide the "pdf*href-PT.init"
1879 .\" macro, (invoked by ".pdfhref I -PT <macro-name>"), to implement a
1880 .\" suitable initialisation action.
1882 .de pdf*href-PT.init
1883 .\" ----------------------------------------------------------------------
1885 .\" .pdfhref I -PT <macro-name>
1886 .\" <macro-name> == name of user's page break trap macro
1887 .\" ----------------------------------------------------------------------
1889 .\" Initially, map the page break hook to its default, do nothing helper.
1891 .als pdf*href.mark.hook pdf*href.mark.idle
1894 . \" Don't have enough arguments to specify a page trap macro name,
1895 . \" so simply plant "pdf*href.mark.hook" as a top of page trap.
1897 . wh 0 pdf*href.mark.hook
1900 . \" Page trap macro name is specified in "\\$1" ...
1904 . \" When this page trap macro already exists, then we simply
1905 . \" append a call to "pdf*href.mark.hook" to it.
1907 . am \\$1 pdf*href.mark.idle
1908 . pdf*href.mark.hook
1909 . pdf*href.mark.idle
1912 . \" However, when the specified page trap macro does not yet
1913 . \" exist, then we create it, and plant it as a top of page
1916 . de \\$1 pdf*href.mark.idle
1917 . pdf*href.mark.hook
1918 . pdf*href.mark.idle
1924 .\" "pdf*href-L" is the generic handler for creating references to
1925 .\" named destinations in PDF documents. It supports both local
1926 .\" references, to locations within the same document, through its
1927 .\" "pdf*href-L.link" attribute, and also references to locations
1928 .\" in any other PDF document, through "pdf*href-L.file".
1930 .als pdf*href-L pdf*href
1931 .ds pdf*href-L.link /Dest /\\\\*[pdf:href-D]
1932 .ds pdf*href-L.file /Action /GoToR \\\\*[pdf:href.files] \\*[pdf*href-L.link]
1934 .\" "pdf*href-O" is the "official" handler for creating PDF
1935 .\" document outlines. It is simply an alias to "pdfbookmark",
1936 .\" which may also be invoked directly, if preferred. Neither
1937 .\" a "pdf*href-O.link" nor a "pdf*href-O.file" attribute is
1940 .als pdf*href-O pdfbookmark
1942 .\" "pdf*href-W" is the generic handler for creating references to
1943 .\" web resources, (or any resource specified by a uniform resource
1944 .\" identifier). Such resource links are fully specified by the
1945 .\" "pdf*href-W.link" attribute.
1947 .als pdf*href-W pdf*href
1948 .ds pdf*href-W.link /Action << /Subtype /URI /URI (\\\\*[pdf:href-D]) >>
1950 .\" pdfmark.tmac: end of file / vim: ft=groff
projects / platform / upstream / groff.git / blob