3 Portable Document Format
4 Publishing with GNU Troff
6 .AI <keith.d.marshall@ntlworld.com>
8 .\" Set the PDF default document view attribute, to ensure that the document
9 .\" outline is visible, each time the document is opened in Acrobat Reader.
11 .pdfview /PageMode /UseOutlines
13 .\" Initialise the outline view to show only three heading levels,
14 .\" with additional subordinate level headings folded.
16 .nr PDFOUTLINE.FOLDLEVEL 3
18 .\" Add document identification meta-data
20 .pdfinfo /Title Portable Document Format Publishing with GNU Troff
21 .pdfinfo /Author Keith Marshall
22 .pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU Troff
23 .pdfinfo /Keywords groff troff PDF pdfmark
25 .\" Set the default cross reference format to indicate section numbers,
26 .\" rather than page numbers, when we insert a reference pointer.
28 .ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
30 .\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
40 .\" to insert a Registered Trade Mark symbol as a superscript.
44 .\" Establish the page layout.
53 .\" Generate headers in larger point sizes, for NH levels < 4,
54 .\" with point size increasing by 1.5p, for each lesser NH level.
60 .\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
64 \\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
67 \\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
70 \\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
72 .ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
75 .\" When we use numbered section headings, we might like to automatically
76 .\" insert a table of contents entry, using the text of the heading itself.
77 .\" The "ms" macros don't provide any standard mechanism for doing this,
78 .\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
80 .\" Here's a simple example of how we might use it. In this case, the word
81 .\" "Introduction" will appear both in the body of the document, as the text
82 .\" of the heading, and it will be added to the table of contents, which is
83 .\" subsequently "printed" using the "TC" macro; in both locations, it will
84 .\" be prefixed by the section number.
86 .\" As an additional side effect, any use of "XN" will cause the table of
87 .\" contents entry to be automatically reproduced, with the exception of its
88 .\" page number reference, as a PDF document outline entry. Thus, the use
89 .\" of "XN" to specify numbered section headings results in the automatic
90 .\" creation of a numbered PDF document outline. This automatic creation
91 .\" of the outline is completely transparent, and will occur regardless
92 .\" of whether the "TC" macro is subsequently invoked, or not.
96 .\" If using an old s.tmac, without the SN-NO-DOT extension,
97 .\" make sure we get SOMETHING in section number references.
99 .if !dSN-NO-DOT .als SN-NO-DOT SN
101 It might appear that it is a fairly simple matter to
102 produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
103 commonly known as PDF, using
104 .CW groff ) GNU\~Troff\~(
105 as the document formatter.
108 default output format is the native Adobe\*(rg\~PostScript\*(rg format,
109 which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
110 or GhostScript, expect as their input format.
111 Thus, the PDF production process would seem to entail simply
112 formatting the document source with
114 to produce a PostScript\*(rg version of the document,
115 which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
116 or GhostScript, to generate the final PDF document.
118 For many PDF production requirements,
119 the production cycle described above may be sufficient.
120 However, this is a limited PDF production method,
121 in which the resultant PDF document represents no more than
122 an on screen image of the printed form of the document, if
124 PostScript\*(rg output were printed directly.
126 The Portable Document Format provides a number of features,
127 which significantly enhance the experience of reading a document on screen,
128 but which are of little or no value to a document which is merely printed.
131 possible to exploit these PDF features, which are described in the Adobe\*(rg
134 .\" This is an example of a resource reference specified by URI ...
135 .\" We may need to refer often to the Adobe pdfmark Reference Manual,
136 .\" so we create the internet link definition using a macro, to make
139 .\" Note also, that we protect the description of the reference by
140 .\" preceding it with "--", to avoid "invalid character in name" type
141 .\" error messages from groff (caused by the use of "\~").
143 .pdfhref W -D http://partners.adobe.com/asn/acrobat/docs/pdfmark.pdf \
144 -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
147 with some refinement of the simple PDF production method, provided
148 appropriate \(lqfeature implementing\(rq instructions can be embedded into
150 PostScript\*(rg rendering of the document.
151 This, of course, implies that the original document source, which
153 will process to generate the PostScript\*(rg description of the document,
154 must include appropriate markup to exploit the desired PDF features.
155 It is this preparation of the
157 document source to exploit a number of these features,
158 which provides the principal focus of this document.
160 The markup techniques to be described have been utilised in the production of
161 the PDF version of this document itself.
162 This has been formatted using
166 thus, usage examples may be found in the document source file,
168 to which comments have been added,
169 to help identify appropriate markup examples for implementing PDF features,
173 Selecting a default document view, which defines how the document will appear
174 when opened in the reader application; for example, when this document is
175 opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
176 in the document view pane, while a document outline should appear to the left,
177 in the \(lqBookmarks\(rq pane.
179 Adding document identification \(lqmeta\(hydata\(rq,
180 which can be accessed, in Acrobat\*(rg\~Reader,
181 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
183 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
184 pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
185 section of the document, simply by clicking on the associated heading
188 Embedding active links in the body of the document, such that readers may
189 quickly navigate to related material at another location within the same
190 document, or in another PDF document, or even to a related Internet resource,
191 specified by its URI.
193 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
194 points within the PDF document.
197 All of the techniques described have been tested on
199 GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
202 .pdfhref L -D footnote1 -- \**
205 Later versions should, and some earlier versions may, be equally suitable.
207 .pdfhref W http://groff.ffii.org
208 for information and availability of the latest version.
214 .pdfhref L -D footnote2 -- \**
217 Again, other versions may be suitable.
219 .pdfhref W http://ghostscript.com
220 for information and availability.
222 Other tools employed, which should be readily available on
227 or GNU/Linux system, are
232 together with an appropriate text editor, for creating and marking up the
235 These additional utilities are not provided, as standard,
236 on the Microsoft\*(rg Windows\(tm platform,
237 but several third party implementations are available.
238 Some worth considering include the MKS\*(rg\~Toolkit,\**
240 A commercial offering; see
241 .pdfhref W http://mkssoftware.com/products/tk/default.asp
252 emulation environment and
256 toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
257 .pdfhref W http://cygwin.com
258 for information and download.
262 Another free, but minimal suite of common
266 tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
267 .pdfhref W -A ; http://www.mingw.org
270 include those tools listed above,
271 and is the package which was actually used when performing the Windows\(tm2000
272 platform tests referred to in the text.
274 This list is by no means exhaustive, and should in no way be construed as an
275 endorsement of any of these packages, nor to imply that other similar packages,
276 which may be available, are in any way inferior to them.
279 .\" We may wish a section heading to represent a named destination,
280 .\" so that we can create a linked reference to it, from some other
281 .\" part of the PDF document, (or even from another PDF document).
283 .\" Here we use the "-N" option of the "XN" macro, to create a named
284 .\" PDF link destination, at the location of the heading. Notice that
285 .\" we also use the "--" marker to separate the heading text from the
286 .\" preceding option specification; it is not strictly necessary in
287 .\" this case, but it does help to set off the heading text from the
288 .\" option specification.
290 .XN -N pdf-features -- Exploiting PDF Document Features
292 To establish a consistent framework for adding PDF features, a
297 Thus, to incorporate PDF features in a document,
298 the appropriate macro calls, as described below, may be placed in the
300 document source, which should then be processed with a
309 .I "file ..." \& "...] "
311 It may be noted that the
313 macros have no dependencies on, and no known conflicts with,
316 macro package; thus, users are free to use any other macro package,
317 of their choice, to format their documents, while also using the
319 macros to add PDF features.
321 .XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
323 All PDF features are implemented by embedding instances of the
325 operator, as described in the Adobe\*(rg
329 PostScript\*(rg output stream.
330 To facilitate the use of this operator, the
332 macro package defines the primitive
334 macro; it simply emits its argument list,
337 operator, in the PostScript\*(rg output stream.
339 .pdfhref M -N pdfmark-example
340 To illustrate the use of the
342 macro, the following is a much simplified example of how a bookmark
343 may be added to a PDF document outline
350 /Title (An Example of a Bookmark with Two Children) \e
351 /View [/FitH \en[PDFPAGE.Y]] \e
355 In general, users should rarely need to use the
358 In particular, the above example is too simple for general use; it
360 create a bookmark, but it does
362 address the issues of setting the proper value for the
364 key, nor of computing the
370 macro package includes a more robust mechanism for creating bookmarks,
372 .\" Here is an example of how a local reference may be planted,
373 .\" using the automatic formatting feature of the "pdfhref" macro.
375 .\" This is a forward reference to the named destination "add-outline",
376 .\" which is defined below, using the "XN" wrapper macro, from the
377 .\" "spdf.tmac" macro package. The automatically formatted reference
378 .\" will be enclosed in parentheses, as specified by the use of
379 .\" "-P" and "-A" options.
381 .pdfhref L -P ( -A ), -D add-outline
383 which addresses these issues automatically.
386 macro may be useful to users wishing to implement more advanced PDF features,
387 than those currently supported directly by the
391 .XN -N docview -- Selecting an Initial Document View
394 when a PDF document is opened,
395 the first page will be displayed,
396 at the default magnification set for the reader,
397 and outline and thumbnail views will be hidden.
398 When using a PDF reader,
399 such as Acrobat\*(rg\~Reader,
405 these default initial view settings may be overridden,
411 .CW ".pdfview /PageMode /UseOutlines"
413 will cause Acrobat\*(rg\~Reader to open the document outline view,
414 to the left of the normal page view,
417 .CW ".pdfview /PageMode /UseThumbs"
419 will open the thumbnail view instead.
423 examples, above, are mutually exclusive \(em it is not possible to have
425 outline and thumbnail views open simultaneously.
432 keys, to force the document to open at a page other than the first,
433 or to change the magnification at which the document is initially displayed;
436 for more information.
438 It should be noted that the view controlling meta\(hydata, defined by the
440 macro, is not written immediately to the PostScript\*(rg output stream,
441 but is stored in an internal meta\(hydata \(lqcache\(rq,
442 (simply implemented as a
445 This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
449 .\" Here is another example of how we may introduce a forward reference.
450 .\" This time we are using the shorter notation afforded by the "XR" macro
451 .\" provided by "spdf.tmac"; this example is equivalent to the native
452 .\" "pdfmark.tmac" form
453 .\" .pdfhref L -D pdfsync -P ( -A ).
458 .XN -N docinfo -- Adding Document Identification Meta-Data
462 class of meta\(hydata described above,
464 we may also wish to include document identification meta\(hydata,
465 which belongs to the PDF
469 To do this, we use the
472 As an example of how it is used,
473 the identification meta\(hydata attached to this document
474 was specified using a macro sequence similar to:\(en
478 \&.pdfinfo /Title PDF Document Publishing with GNU Troff
479 \&.pdfinfo /Author Keith Marshall
480 \&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff
481 \&.pdfinfo /Keywords groff troff PDF pdfmark
486 macro is repeated, once for each
488 record to be placed in the document.
489 In each case, the first argument is the name of the applicable
493 be named with an initial solidus character;
494 all additional arguments are collected together,
495 to define the value to be associated with the specified key.
497 As is the case with the
503 records specified with the
505 macro are not immediately written to the PostScript\*(rg output stream;
506 they are stored in the same meta\(hydata cache as
508 specifications, until this cache is explicitly flushed,
514 .XN -N add-outline -- Creating a Document Outline
516 A PDF document outline comprises a table of references,
517 to \(lqbookmarked\(rq locations within the document.
518 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
519 such as Adobe\*(rg Acrobat\*(rg Reader,
520 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
521 or \(lqBookmarks\(rq pane, to the left of the main document view.
522 Individual references in the outline view may then be selected,
523 by clicking with the mouse,
524 to jump directly to the associated marked location in the document view.
526 The document outline may be considered as a collection of \(lqhypertext\(rq
527 references to \(lqbookmarked\(rq locations within the document.
530 macro package provides a single generalised macro,
532 for creating and linking to \(lqhypertext\(rq reference marks.
533 This macro will be described more comprehensively in a later section,
535 the description here is restricted to its use for defining document outline entries.
537 .XN -N basic-outline -- A Basic Document Outline
539 In its most basic form, the document outline comprises a structured list of headings,
540 each associated with a marked location, or \(lqbookmark\(rq, in the document text,
541 and a specification for how that marked location should be displayed,
542 when this bookmark is selected.
544 To create a PDF bookmark, the
547 at the point in the document where the bookmark is to be placed,
553 .I "descriptive text ..."
555 in which the reference class
556 .CWB O \& \& \(rq \(lq
557 stipulates that this is an outline reference.
559 Alternatively, for those users who may prefer to think of a document outline
560 simply as a collection of bookmarks, the
562 macro is also provided \(em indeed,
564 invokes it, when processing the
565 .CWB O \& \& \(rq \(lq
566 reference class operator.
567 It may be invoked directly, in the form
572 .I "descriptive text ..."
574 Irrespective of which of the above macro forms is employed, the
576 argument is required.
577 It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
578 in the outline hierarchy, with one being the topmost level.
579 Its function may be considered analagous to the
581 of the document's section headings,
582 for example, as specified with the
586 macros to format the document.
588 All further arguments, following the
590 argument, are collected together, to specify the heading text which will appear
591 in the document's outline view.
592 Thus, the outline entry for this section of this document,
593 which has a level three heading,
594 might be specified as
597 \&.pdfhref O 3 \*(SN A Basic Document Outline
599 or, in the alternative form using the
604 \&.pdfbookmark 3 \*(SN A Basic Document Outline
606 .XN Hierarchical Structure in a Document Outline
608 When a document outline is created, using the
610 macro as described in
612 .\" Here is an example of how we can temporarily modify the format of
613 .\" a reference link, in this case to indicate only the section number
614 .\" of the link target, in the form "section #", (or, if we define
615 .\" "SECREF.BEGIN" before the call, its content followed by the
618 .\" We first define a macro, which will get the reference data from
619 .\" pdfhref, as arguments, and will return the formatted output, as we
620 .\" require it, the string "PDFHREF.TEXT".
624 . ie '\\$1'section' \{\
625 . if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
626 . ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
633 .\" We now tell "pdfhref" to use our formatting macro, in place of
634 .\" its builtin default formatter, before we specify the reference.
637 .pdfhref L -A , -D basic-outline
639 .\" At this point, we would normally revert the "pdfhref" formatter
640 .\" to use its default, built in macro. However, in this particular
641 .\" case, we want to use our custom format one more time, before we
642 .\" revert it, so we will omit the reversion step this time.
644 and any entry is added at a nesting level greater than one,
645 then a hierarchical structure is automatically defined for the outline.
646 However, as was noted in the simplified
647 .pdfhref L -D pdfmark-example -- example
649 .pdfhref L -A , -D pdfmark-operator
651 .\" And now, we revert to default "pdfhref" formatting behaviour,
652 .\" by completing the call we delayed above.
656 the data required by the
658 operator to create the outline entry may not be fully defined,
659 when the outline reference is defined in the
662 Specifically, when the outline entry is created, its
664 key must be assigned a value equal to the number of its subordinate entries,
665 at the next inner level of the outline hierarchy;
667 these subordinate entries will be defined
669 in the document source, and the appropriate
671 value will be unknown, when defining the parent entry.
673 To resolve this paradox, the
675 macro creates the outline entry in two distinct phases \(em
676 a destination marker is placed in the PostScript\*(rg output stream immediately,
677 when the outline reference is defined,
678 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
679 until its subordinate hierarchy has been fully defined;
680 it can then be inserted in the output stream, with its
682 value correctly assigned.
683 Effectively, to ensure integrity of the document outline structure,
684 this means that each top level outline entry, and
686 of its subordinates, are retained in the cache, until the
688 top level entry is defined.
690 One potential problem, which arises from the use of the \(lqoutline cache\(rq,
691 is that, at the end of any document formatting run, the last top level outline entry,
692 and any subordinates defined after it, will remain in the cache, and will
694 be automatically written to the output stream.
695 To avoid this problem, the user should follow the guidelines given in
697 .\" Here is a more conventional example of how to temporarily change
698 .\" to the format used to display reference links. We will again use
699 .\" the "SECREF" format, which we defined above, but on this occasion
700 .\" we will immediately revert to the default format, after the link
704 .pdfhref L -D pdfsync -A ,
707 to synchronise the output state with the cache state,
713 .XN -N outline-view -- Associating a Document View with an Outline Reference
715 Each \(lqbookmark\(rq entry, in a PDF document outline,
716 is associated with a specific document view.
717 When the reader selects any outline entry,
718 the document view changes to display the document context
719 associated with that entry.
721 The document view specification,
722 to be associated with any document outline entry,
723 is established at the time when the outline entry is created.
724 However, rather than requiring that each individual use of the
726 macro, to create an outline entry,
727 should include its own view specification,
728 the actual specification assigned to each entry is derived from
729 a generalised specification defined in the string
730 .CW PDFBOOKMARK.VIEW ,
731 together with the setting of the numeric register
732 .CW PDFHREF.VIEW.LEADING ,
733 which determine the effective view specification as follows:\(en
735 .IP \*[= PDFBOOKMARK.VIEW]
736 Establishes the magnification at which the document will be viewed,
737 at the location of the \(lqbookmark\(rq; by default, it is defined by
740 .CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
743 which displays the associated document view,
744 with the \(lqbookmark\(rq location positioned at the top of the display window,
745 and with the magnification set to fit the page width to the width of the window.
746 .IP \*[= PDFHREF.VIEW.LEADING]
747 Specifies additional spacing,
748 to be placed between the top of the display window
749 and the actual location of the \(lqbookmark\(rq on the displayed page view.
750 By default, it is set as
753 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
757 .CW PDFHREF.VIEW.LEADING
758 does not represent true \(lqleading\(rq, in the typographical sense,
759 since any preceding text, set in the specified display space,
760 will be visible at the top of the document viewing window,
761 when the reference is selected.
763 Also note that the specification of
764 .CW PDFHREF.VIEW.LEADING
767 reference views defined by the
771 is applied exclusively to outline references,
772 there is no independent
773 .CW PDFBOOKMARK.VIEW.LEADING
777 If desired, the view specification may be changed, by redefining the string
778 .CW PDFBOOKMARK.VIEW ,
779 and possibly also the numeric register
780 .CW PDFHREF.VIEW.LEADING .
781 Any alternative definition for
784 be specified in terms of valid view specification parameters,
785 as described in the Adobe\*(rg
788 Note the use of the register
790 in the default definition of
793 This register is computed by
795 when creating an outline entry;
796 it specifies the vertical position of the \(lqbookmark\(rq,
799 units, relative to the
801 edge of the document page on which it is defined,
802 and is followed, in the
807 operator, to convert it to PostScript\*(rg units on output.
808 It may be used in any redefined specification for
809 .CW PDFBOOKMARK.VIEW ,
810 (or in the analogous definition of
813 .XR-NO-PREFIX pdfhref-view ),
816 in any other context,
817 since its value is undefined outside the scope of the
823 is computed relative to the
825 of the PDF output page,
826 it is important to ensure that the page length specified to
828 correctly matches the size of the logical PDF page.
829 This is most effectively ensured,
832 page size specifications to
835 and to the PostScript\*(rg to PDF converter employed,
836 and avoiding any page length changes within the document source.
840 is the only automatically computed \(lqbookmark\(rq location parameter;
841 if the user redefines
842 .CW PDFBOOKMARK.VIEW ,
843 and the modified view specification requires any other positional parameters,
846 ensure that these are computed
852 .XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
854 When a document incorporates many subheadings,
855 at deeply nested levels,
856 it may be desirable to \(lqfold\(rq the outline
857 such that only the major heading levels are initially visible,
858 yet making the inferior subheadings accessible,
859 by allowing the reader to expand the view of any heading branch on demand.
863 macros support this capability,
864 through the setting of the
865 .CW PDFOUTLINE.FOLDLEVEL
867 This register should be set to the number of heading levels
868 which it is desired to show in expanded form, in the
870 document outline display;
871 all subheadings at deeper levels will still be added to the outline,
872 but will not become visible until the outline branch containing them is expanded.
874 For example, the setting used in this document:
878 \&.\e" Initialise the outline view to show only three heading levels,
879 \&.\e" with additional subordinate level headings folded.
881 \&.nr PDFOUTLINE.FOLDLEVEL 3
885 results in only the first three levels of headings being displayed
886 in the document outline,
888 the reader chooses to expand the view,
889 and so reveal the lower level headings in any outline branch.
891 The initial default setting of
892 .CW PDFOUTLINE.FOLDLEVEL ,
893 if the document author does not choose to change it,
895 This is orders of magnitude greater than the maximum heading level
896 which is likely to be used in any document;
897 thus the default behaviour will be to show document outlines fully expanded,
898 to display all headings defined,
899 at all levels within each document.
902 .CW PDFOUTLINE.FOLDLEVEL
903 may be changed at any time;
904 however, the effect of each such change may be difficult to predict,
905 since it is applied not only to outline entries which are defined
907 the setting is changed,
908 but also to any entries which remain in the outline cache,
911 Therefore, it is recommended that
912 .CW PDFOUTLINE.FOLDLEVEL
915 at the start of each document;
918 deemed necessary to change it at any other time,
919 the outline cache should be flushed,
923 which should immediately preceed a level one heading.
925 .XN -N multipart-outline -- Outlines for Multipart Documents
927 When a document outline is created, using the
929 macro, each reference mark is automatically assigned a name,
930 composed of a fixed stem followed by a serially generated numeric qualifier.
931 This ensures that, for each single part document, every outline reference
932 has a uniquely named destination.
934 As the overall size of the PDF document increases,
935 it may become convenient to divide it into smaller,
936 individually formatted PostScript\*(rg components,
937 which are then assembled, in the appropriate order,
938 to create a composite PDF document.
939 While this strategy may simplify the overall process of creating and
940 editing larger documents, it does introduce a problem in creating
941 an overall document outline,
942 since each individual PostScript\*(rg component will be assigned
943 duplicated sequences of \(lqbookmark\(rq names,
944 with each name ultimately referring to multiple locations in the composite document.
945 To avoid such reference naming conflicts, the
947 macro allows the user to specify a \(lqtag\(rq,
948 which is appended to the automatically generated \(lqbookmark\(rq name;
949 this may be used as a discriminating mark, to distinguish otherwise
950 similarly named destinations, in different sections of the composite document.
952 To create a \(lqtagged\(rq document outline,
953 the syntax for invocation of the
955 macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
957 the nesting level argument, i.e.
964 .I "descriptive text ..."
968 argument may be composed of any characters of the user's choice;
969 however, its initial character
971 be any decimal digit, and ideally it should be kept short
972 \(em one or two characters at most.
974 By employing a different tag in each section,
975 the user can ensure that \(lqbookmark\(rq names remain unique,
976 throughout all the sections of a composite document.
977 For example, when using the
979 macro package, which adds
981 capabilities to the standard
985 the table of contents is collected into a separate PostScript\*(rg section
986 from the main body of the document.
987 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
988 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
990 macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
995 .CW ".pdfhref O -T T 1 \e\e*[TOC]"
997 to tag the associated outline destination name with the single character suffix,
999 Alternatively, as in the case of the basic outline,
1000 .XR basic-outline ), (
1001 this may equally well be specified as
1003 .CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1005 .XN Delegation of the Outline Definition
1007 Since the most common use of a document outline
1008 is to provide a quick method of navigating through a document,
1009 using active \(lqhypertext\(rq links to chapter and section headings,
1010 it may be convenient to delegate the responsibility of creating the outline
1011 to a higher level macro, which is itself used to
1012 define and format the section headings.
1013 This approach has been adopted in the
1015 package, to be described later,
1018 When such an approach is adopted,
1019 the user will rarely, if ever, invoke the
1021 macro directly, to create a document outline.
1022 For example, the structure and content of the outline for this document
1023 has been exclusively defined, using a combination of the
1027 package, to establish the structure, and the
1031 to define the content.
1033 the responsibility for invoking the
1035 macro, to create the document outline,
1040 .XN -N pdfhref -- Adding Reference Marks and Links
1043 .ds SECREF.BEGIN Section
1044 .pdfhref L -D add-outline
1048 macro may be used to create a PDF document outline.
1049 While this is undoubtedly a powerful capability,
1050 it is by no means the only trick in the repertoire of this versatile macro.
1054 which is a contraction of \(lqPDF HyperText Reference\(rq,
1055 indicates that the general purpose of this macro is to define
1057 type of dynamic reference mark, within a PDF document.
1058 Its generalised usage syntax takes the form
1063 .I "-options ...\&" ] [
1065 .I "descriptive text ...\&" ] [
1069 represents a required single character argument,
1070 which defines the specific reference operation to be performed,
1071 and may be selected from:\(en
1074 Add an entry to the document outline.
1075 This operation has been described earlier,
1076 .XR add-outline ). (
1078 Place a \(lqnamed destination\(rq reference mark at the current output position,
1079 in the current PDF document,
1082 Insert an active link to a named destination,
1084 at the current output position in the current PDF document,
1085 such that when the reader clicks on the link text,
1086 the document view changes to show the location of the named destination.
1088 Insert an active link to a \(lqweb\(rq resource,
1089 .XR add-weblink ), (
1090 at the current output position in the current PDF document.
1091 This is effectively the same as using the
1092 .CWB L \& \& \(rq \(lq
1093 operator to establish a link to a named destination in another PDF document,
1094 .XR link-extern ), (
1095 except that in this case, the destination is specified by a
1096 \(lquniform resource identifier\(rq, or
1098 this may represent any Internet or local resource
1099 which can be specified in this manner.
1101 Specify a user defined macro, to be called by
1103 when formatting the text in the active region of a link,
1106 Initialise support for
1111 implementation provides only one such feature which requires initialisation
1112 \(em a helper macro which must be attached to a user supplied page trap handler,
1113 in order to support mapping of reference \(lqhot\(hyspots\(rq
1114 which extend through a page transition;
1118 .XN Optional Features of the \F[C]pdfhref\F[] Macro
1120 The behaviour of a number of the
1122 macro operations can be modified,
1124 .EM "option specifiers" \(rq \(lq
1125 after the operation specifying argument,
1128 any other arguments normally associated with the operation.
1131 cases, an option is specified by an
1132 .EM "option flag" \(rq, \(lq
1133 comprising an initial hyphen,
1134 followed by one or two option identifying characters.
1140 for these options, the argument
1142 be specified, and it
1144 be separated from the preceding option flag by one or more
1149 It may be noted that this paradigm for specifying options
1150 is reminiscent of most
1154 shells; however, in the case of the
1156 macro, omission of the space separating an option flag from its argument is
1162 general purpose options supported by the
1164 macro is given below.
1165 Note that not all options are supported for all
1167 operations; the operations affected by each option are noted in the list.
1170 operations, if an unsupported option is specified,
1171 it will be silently ignored; however, this behaviour should
1174 The general purpose options, supported by the
1178 .IP \*[= -N\0 name > <]
1181 associated with a PDF reference destination
1182 to be defined independently from the following text,
1183 which describes the reference.
1184 This option affects only the
1185 .CWB M \& \& \(rq \(lq
1191 Also used exclusively with the
1192 .CWB M \& \& \(rq \(lq
1195 option causes any specified
1196 .CWI descriptive \& \& \~\c
1202 in the body text of the document,
1203 at the point where the reference mark is defined;
1207 .CWI descriptive \& \& \~\c
1211 at points where links to the reference mark are placed,
1212 and where the standard reference display format,
1215 .IP \*[= -D\0 dest > <]
1218 or the destination name associated with a PDF active link,
1219 independently of the following text,
1220 which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1221 This option affects the behaviour of the
1224 .CWB L \& \& \(rq \(lq
1226 .CWB W \& \& \(rq \(lq
1230 .CWB L \& \& \(rq \(lq
1233 argument must specify a PDF \(lqnamed destination\(rq,
1237 .CWB M \& \& \(rq \(lq
1241 .CWB W \& \& \(rq \(lq
1244 must specify a link destination in the form of a
1245 \(lquniform resource identifier\(rq, or
1247 .XR add-weblink ). (
1248 .IP \*[= -F\0 file > <]
1250 .CWB L \& \& \(rq \(lq
1254 specifies an external PDF file in which the named destination
1255 for the link reference is defined.
1258 be specified with the
1259 .CWB L \& \& \(rq \(lq
1261 to create a link to a destination in a different PDF document;
1263 .CWB L \& \& \(rq \(lq
1266 this option, the link destination is assumed to be defined
1267 within the same document.
1268 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1270 .CWI \(dqprefix\(hytext\(dq > <
1271 to be attached to the
1273 of the text describing an active PDF document link,
1274 with no intervening space, but without itself being included in the
1275 active area of the link \(lqhot\(hyspot\(rq;
1276 it is effective with the
1277 .CWB L \& \& \(rq \(lq
1279 .CWB W \& \& \(rq \(lq
1283 Typically, this option would be used to insert punctuation before
1284 the link \(lqhot\(hyspot\(rq.
1285 Thus, there is little reason for the inclusion of spaces in
1286 .CWI \(dqprefix\(hytext\(dq > < ;
1287 however, if such space is required, then the enclosing double quotes
1289 be specified, as indicated.
1290 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1292 .CWI \(dqaffixed\(hytext\(dq > <
1293 to be attached to the
1295 of the text describing an active PDF document link,
1296 with no intervening space, but without itself being included in the
1297 active area of the link \(lqhot\(hyspot\(rq;
1298 it is effective with the
1299 .CWB L \& \& \(rq \(lq
1301 .CWB W \& \& \(rq \(lq
1305 Typically, this option would be used to insert punctuation after
1306 the link \(lqhot\(hyspot\(rq.
1307 Thus, there is little reason for the inclusion of spaces in
1308 .CWI \(dqaffixed\(hytext\(dq > < ;
1309 however, if such space is required, then the enclosing double quotes
1311 be specified, as indicated.
1312 .IP \*[= -T\0 tag > <]
1313 When specified with the
1314 .CWB O \& \& \(rq \(lq
1317 is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1320 to distinguish between the series of \(lqbookmark\(rq names generated in
1321 individual passes of the
1323 formatter, when the final PDF document is to be assembled
1324 from a number of separately formatted components;
1325 .XR multipart-outline ). (
1329 option is used with either the
1330 .CWB M \& \& \(rq \(lq
1331 operator, or with the
1332 .CWB L \& \& \(rq \(lq
1336 .CWB M \& \& \(rq \(lq
1339 it ensures that a cross reference record for the marked destination
1340 will be included in the document reference map,
1344 .CWB L \& \& \(rq \(lq
1347 it causes the reference to be displayed in the standard cross reference format,
1349 but substituting the
1350 .CWI descriptive \& \& \~\c
1356 for the description specified in the document reference map.
1358 Marks the end of the option specifiers.
1359 This may be used with all
1361 operations which accept options, to prevent
1363 from interpreting any following arguments as option specifiers,
1364 even if they would otherwise be interpreted as such.
1365 It is also useful when the argument list to
1367 contains special characters \(em any special character,
1368 which is not legal in a
1370 macro name, will cause a parsing error, if
1372 attempts to match it as a possible option flag;
1375 flag prevents this, so suppressing the
1377 warning message, which would otherwise ensue.
1379 Using this flag after
1381 sequences of macro options is recommended,
1382 even when it is not strictly necessary,
1383 if only for the entirely cosmetic benefit of visually separating
1384 the main argument list from the sequence of preceding options.
1389 options listed above, a supplementary set of two character options are defined.
1390 These supplementary options, listed below, are intended for use with the
1391 .CWB L \& \& \(rq \(lq
1392 operator, in conjunction with the
1395 option, to specify alternate file names,
1396 in formats compatible with the file naming conventions
1397 of alternate operating systems;
1398 they will be silently ignored, if used in any other context.
1400 The supported alternate file name options,
1401 which are ignored if the
1404 option is not specified, are:\(en
1406 .IP \*[= -DF\0 dos\(hyfile > <]
1407 Specifies the name of the file in which a link destination is defined,
1408 using the file naming semantics of the
1411 When the PDF document is read on a machine
1412 where the operating system uses the
1415 .CWI dos\(hyfile > <
1416 is used as the name of the file containing the reference destination,
1419 argument specified with the
1422 .IP \*[= -MF\0 mac\(hyfile > <]
1423 Specifies the name of the file in which a link destination is defined,
1424 using the file naming semantics of the
1428 When the PDF document is read on a machine
1429 where the operating system uses the
1432 .CWI mac\(hyfile > <
1433 is used as the name of the file containing the reference destination,
1436 argument specified with the
1439 .IP \*[= -UF\0 unix\(hyfile > <]
1440 Specifies the name of the file in which a link destination is defined,
1441 using the file naming semantics of the
1444 When the PDF document is read on a machine
1445 where the operating system uses
1447 file naming semantics, then
1448 .CWI unix\(hyfile > <
1449 is used as the name of the file containing the reference destination,
1452 argument specified with the
1455 .IP \*[= -WF\0 win\(hyfile > <]
1456 Specifies the name of the file in which a link destination is defined,
1457 using the file naming semantics of the
1458 .CW MS\(hyWindows \*(rg
1459 32\(hybit operating system.
1460 When the PDF document is read on a machine
1461 where the operating system uses any of the
1462 .CW MS\(hyWindows \*(rg
1463 file systems, with long file name support, then
1464 .CWI win\(hyfile > <
1465 is used as the name of the file containing the reference destination,
1468 argument specified with the
1473 .XN -N mark-dest -- Marking a Reference Destination
1477 macro may be used to create active links to any Internet resource,
1480 or to any \(lqnamed destination\(rq,
1481 either within the same document, or in another PDF document.
1482 Although the PDF specification allows link destinations to be defined
1483 in terms of a page number, and an associated view specification,
1484 this style of reference is not currently supported by the
1486 macro, because it is not possible to adequately bind the specification
1487 for the destination with the intended reference context.
1489 References to Internet resources are interpreted in accordance with the
1491 standard for defining a
1493 hence the only prerequisite, for creating a link to any Internet resource,
1496 be properly specified, when declaring the reference;
1497 .XR add-weblink ). (
1498 In the case of references to \(lqnamed destinations\(rq in PDF documents,
1499 however, it is necessary to provide a mechanism for creating such
1500 \(lqnamed destinations\(rq.
1501 This may be accomplished, by invoking the
1511 .I "descriptive text ...\&" ] [
1513 This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1517 option is not specified, by the first word of
1518 .CWI descriptive \& \& \~\c
1520 (note that this imposes the restriction that,
1523 option is omitted, then
1526 .CWI descriptive \& \& \~\c
1530 Additionally, a reference view will be automatically defined,
1531 and associated with the reference mark,
1532 .XR pdfhref-view ), (
1534 .\" .CWI descriptive
1536 .\" is specified, or the
1539 option is specified, and no document cross reference map has been imported,
1541 then a cross reference mapping record,
1543 will be written to the
1546 this may be captured, and subsequently used to generate a cross reference map
1550 When a \(lqnamed destination\(rq reference mark is created, using the
1553 .CWB M \& \& \(rq \(lq
1554 operator, there is normally no visible effect in the formatted document; any
1555 .CWI descriptive \& \& \~\c
1557 which is specified will simply be stored in the cross reference map,
1558 for use when a link to the reference mark is created.
1559 This default behaviour may be changed, by specifying the
1561 option, which causes any specified
1562 .CWI descriptive \& \& \~\c
1564 to be \(lqechoed\(rq in the document text,
1565 at the point where the reference mark is placed,
1566 in addition to its inclusion in the cross reference map.
1568 .XN -N export-map -- Mapping a Destination for Cross Referencing
1570 Effective cross referencing of
1572 document formatted by
1574 requires multiple pass formatting.
1575 Details of how this multiple pass formatting may be accomplished,
1576 when working with the
1578 macros, will be discussed later,
1580 at this stage, the discussion will be restricted to the initial preparation,
1581 which is required at the time when the cross reference destinations are defined.
1583 The first stage, in the process of cross referencing a document,
1584 is the generation of a cross reference map.
1585 Again, the details of
1587 the cross reference map is generated will be discussed in
1588 .pdfhref F SECREF L -D do-xref -A ;
1590 however, it is important to recognise that
1592 content is included in the cross reference map is established
1593 when the reference destination is defined \(em it is derived
1594 from the reference data exported on the
1598 macro, when it is invoked with the
1599 .CWB M \& \& \(rq \(lq
1600 operator, and is controlled by whatever definition of the string
1602 is in effect, when the
1606 The initial default setting of
1610 .CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1612 which ensures that the cross reference map will contain
1613 at least a page number reference, supplemented by any
1614 .CWI descriptive \& \& \~\c
1616 which is specified for the reference mark, as defined by the
1619 .CWB M \& \& \(rq \(lq
1620 operator; this may be redefined by the user,
1621 to export additional cross reference information,
1622 or to modify the default format for cross reference links,
1625 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
1627 In the same manner as each document outline reference, defined by the
1630 .CWB O \& \& \(rq \(lq
1632 .XR add-outline ), (
1633 has a specific document view associated with it,
1634 each reference destination marked by
1637 .CWB M \& \& \(rq \(lq
1638 operator, requires an associated document view specification.
1640 The mechanism whereby a document view is associated with a reference mark
1641 is entirely analogous to that employed for outline references,
1642 .XR outline-view ), (
1645 string specification is used, in place of the
1646 .CW PDFBOOKMARK.VIEW
1648 Thus, the reference view is defined in terms of:\(en
1650 .IP \*[= PDFHREF.VIEW]
1652 establishing the position of the reference mark within the viewing window,
1653 and the magnification at which the document will be viewed,
1654 at the location of the marked reference destination;
1655 by default, it is defined by
1658 .CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
1661 which displays the reference destination at the top of the viewing window,
1662 with the magnification set to fit the page width to the width of the window.
1663 .IP \*[= PDFHREF.VIEW.LEADING]
1665 specifying additional spacing, to be placed between the top of the display
1666 window and the actual position at which the location of the reference
1667 destination appears within the window.
1668 This register is shared with the view specification for outline references,
1669 and thus has the same default initial setting,
1672 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
1675 as in the case of outline reference views.
1678 .CW PDFHREF.VIEW.LEADING
1679 does not represent true typographic \(lqleading\(rq,
1680 since any preceding text, set in the specified display space,
1681 will be visible at the top of the viewing window,
1682 when the reference is selected.
1685 Just as the view associated with outline references may be changed,
1687 .CW PDFBOOKMARK.VIEW ,
1688 so the view associated with marked reference destinations may be changed,
1692 .CW PDFHREF.VIEW.LEADING ;
1693 such changes will become effective for all reference destinations marked
1695 these definitions are changed.
1696 (Notice that, since the specification of
1697 .CW PDFHREF.VIEW.LEADING
1698 is shared by both outline reference views and marked reference views,
1699 if it is changed, then the views for
1701 reference types are changed accordingly).
1703 It may again be noted, that the
1705 register is used in the definition of
1707 just as it is in the definition of
1708 .CW PDFBOOKMARK.VIEW ;
1710 .pdfhref F SECREF L -D outline-view
1712 relating to its use, and indeed to page position computations in general,
1713 apply equally to marked reference views and to outline reference views.
1715 .XN -N link-named -- Linking to a Marked Reference Destination
1717 Any named destination, such as those marked by the
1720 .CWB M \& \& \(rq \(lq
1721 operator, may be referred to from any point in
1723 PDF document, using an
1725 such active links are created by again using the
1727 macro, but in this case, with the
1728 .CWB L \& \& \(rq \(lq
1730 This operator provides support for two distinct cases,
1731 depending on whether the reference destination is defined in
1732 the same document as the link,
1733 .XR link-intern ), (
1734 or is defined as a named destination in a different PDF document,
1735 .XR link-extern ). (
1737 .XN -N link-intern -- References within a Single PDF Document
1739 The general syntactic form for invoking the
1742 when creating a link to a named destination within the same PDF document is
1750 .BI prefix-text >] <
1752 .BI affixed-text >] <
1758 .I "descriptive text ...\&" ] [
1762 specifies the name of the link destination,
1763 as specified using the
1765 .CWB M \& \& \(rq \(lq
1766 operation; (it may be defined either earlier in the document,
1767 to create a backward reference, or later, to create a forward reference).
1769 .\" Here's a example of how to add an iconic annotation.
1771 .\".pdfnote -T "Internal Cross References" \
1772 .\" This description is rather terse, and could benefit from \
1773 .\" the inclusion of an example.
1776 .CWI descriptive \& \& \~\c
1778 arguments are specified, then they will be inserted into the
1780 output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
1782 this will be printed in the link colour specified by the string,
1783 .CW PDFHREF.TEXT.COLOUR ,
1784 which is described in
1785 .XR-NO-PREFIX set-colour .
1788 option is also specified, then the
1789 .CWI descriptive \& \& \~\c
1791 will be augmented, by prefacing it with page and section number indicators,
1792 in accordance with the reference formatting rules which are in effect,
1794 such indicators will be included within the active link region,
1795 and will also be printed in the link colour.
1801 .CWBI dest\(hyname > <
1805 .CWI descriptive \& \& \~\c
1808 .EM "but not both" ,
1812 .CWBI dest\(hyname > <
1813 option is omitted, then the first word of
1814 .CWI descriptive \& \& \~\c
1816 i.e.\~all text up to but not including the first space,
1817 will be interpreted as the
1818 .CWBI dest\(hyname > <
1819 for the link; this text will also appear in the running text of the document,
1820 within the active region of the link.
1821 Alternatively, if the
1823 .CWBI dest\(hyname > <
1827 .CWI descriptive \& \& \~\c
1830 then the running text which defines the reference,
1831 and its active region,
1832 will be derived from the reference description which is specified
1833 when the named destination is marked,
1835 and will be formatted according to the reference formatting rules
1836 which are in effect, when the reference is placed,
1838 in this case, it is not necessary to specify the
1840 option to activate automatic formatting of the reference \(em it is implied,
1841 by the omission of all
1842 .CWI descriptive \& \& \~\c
1848 .CWBI prefix\(hytext > <
1851 .CWBI affixed\(hytext > <
1852 options may be used to specify additional text
1853 which will be placed before and after the linked text respectively,
1854 with no intervening space.
1855 Such prefixed and affixed text will be printed in the normal text colour,
1856 and will not be included within the active region of the link.
1857 This feature is mostly useful for creating parenthetical references,
1858 or for placing punctuation adjacent to,
1859 but not included within,
1860 the text which defines the active region of the link.
1862 The operation of the
1864 macro, when used with its
1865 .CWB L \& \& \(rq \(lq
1866 operator to place a link to a named PDF destination,
1867 may best be illustrated by an example.
1868 However, since the appearance of the link will be influenced by
1869 factors established when the named destination is marked,
1871 and also by the formatting rules in effect when the link is placed,
1872 the presentation of a suitable exanple will be deferred,
1873 until the formatting mechanism has been explained,
1876 .XN -N link-extern -- References to Destinations in Other PDF Documents
1881 .CWB L \& \& \(rq \(lq
1882 operator is not restricted to creating reference links
1883 within a single PDF document.
1884 When the link destination is defined in a different document,
1885 then the syntactic form for invoking
1887 is modified, by the addition of options to specify the
1888 name and location of the PDF file in which the destination is defined.
1891 syntactic form becomes
1915 .BI prefix-text >] <
1917 .BI affixed-text >] <
1923 .I "descriptive text ...\&" ] [
1930 purposes: it both indicates to the
1932 macro that the specified reference destination
1933 is defined in an external PDF file,
1934 and it also specifies the normal path name,
1935 which is to be used to locate this file,
1936 when a user selects the reference.
1943 be specified when referring to a destination in an external PDF file,
1946 .CWBI dos\(hyfile > < ,
1948 .CWBI mac\(hyfile > < ,
1950 .CWBI unix\(hyfile > <
1953 .CWBI win\(hyfile > <
1954 options may be used to specify the location of the file
1955 containing the reference destination,
1956 in a variety of operating system dependent formats.
1957 These options assign their arguments to the
1963 keys of the generated
1965 respectively; thus when any of these options are specified,
1966 .EM "in addition to"
1970 option, and the document is read on the appropriate operating systems,
1971 then the path names specified by
1972 .CWBI dos\(hyfile > < ,
1973 .CWBI mac\(hyfile > < ,
1974 .CWBI unix\(hyfile > <
1976 .CWBI win\(hyfile > <
1979 of the path name specified by
1982 .CW MS\(hyDOS \*(rg,
1984 .CW Macintosh \*(rg,
1987 .CW MS\(hyWindows \*(rg
1988 operating systems, respectively; see the
1990 for further details.
1992 Other than the use of these additional options,
1993 which specify that the reference destination is in an external PDF file,
1994 the behaviour of the
1996 .CWB L \& \& \(rq \(lq
2000 option, remains identical to its behaviour
2003 .XR link-intern ), (
2004 with respect to the interpretation of other options,
2006 .CWI descriptive \& \& \~\c
2008 arguments, and the formatting of the displayed reference.
2010 Once again, since the appearance of the reference is determined by
2011 factors specified in the document reference map,
2012 and also by the formatting rules in effect when the reference is placed,
2013 the presentation of an example of the placing of
2014 a reference to an external destination will be deferred,
2015 until the formatting mechanism has been explained,
2018 .XN -N add-weblink -- Linking to Internet Resources
2020 In addition to supporting the creation of cross references
2021 to named destinations in PDF documents, the
2023 macro also has the capability to create active links to Internet resources,
2026 resource which may be specified by a Uniform Resource Identifier,
2027 (which is usually abbreviated to the acronym \(lqURI\(rq,
2028 and sometimes also referred to as a Uniform Resource Locator,
2031 Since the mechanism for creating a link to a URI differs somewhat
2032 from that for creating PDF references, the
2034 macro is invoked with the
2035 .CWB W \& \& \(rq \(lq
2036 (for \(lqweb\(hylink\(rq) operator, rather than the
2037 .CWB L \& \& \(rq \(lq
2038 operator; nevertheless, the invocation syntax is similar, having the form
2046 .BI prefix-text >] <
2048 .BI affixed-text >] <
2053 .I "descriptive text ...\&"
2057 .XN -N set-format -- Establishing a Format for References
2059 There are two principal aspects to be addressed,
2060 when defining the format to be used when displaying references.
2061 Firstly, it is desirable to provide a visual cue,
2062 to indicate that the text describing the reference is imbued
2063 with special properties \(em it is dynamically linked to the reference
2064 destination \(em and secondly, the textual content should
2065 describe where the link leads, and ideally,
2066 it should also describe the content of the reference destination.
2069 that a text region defines a dynamically linked reference,
2070 is most commonly provided by printing the text within the active
2071 region in a distinctive colour.
2072 This technique will be employed automatically by the
2076 \(em unless the user specifically chooses to adopt, and implement,
2077 some alternative strategy.
2079 .XN -N set-colour -- Using Colour to Demarcate Link Regions
2081 Typically, when a PDF document contains
2083 references to other locations, either within the same document,
2084 or even in other documents, or on the World Wide Web,
2085 it is usually desirable to make the regions
2086 where these active links are placed stand out from the surrounding text.
2088 .XN -N user-format -- Specifying Reference Text Explicitly
2090 .XN -N auto-format -- Using Automatically Formatted Reference Text
2092 .XN -N custom-format -- Customising Automatically Formatted Reference Text
2094 It is incumbent on the user,
2095 if employing automatic formatting of the displayed reference,
2097 to ensure that an appropriate reference definition
2098 is created for the reference destination,
2099 and is included in the reference map for the document
2100 in which the reference will appear;
2101 thus, it may be easiest to
2103 use manual formatting for external references.
2105 .XN Problematic Links
2107 Irrespective of whether a
2109 reference is placed using the
2110 .CWB L \& \& \(rq \(lq
2112 .CWB W \& \& \(rq \(lq
2113 operator, there may be occasions when the resulting link
2114 does function as expected.
2115 A number of scenarios, which are known to be troublesome,
2116 are described below.
2118 .XN -N page-trap -- Links with a Page Transition in the Active Region
2120 When a link is placed near the bottom of a page,
2121 it is possible that its active region, or \(lqhot\(hyspot\(rq,
2122 may extend on to the next page.
2123 In this situation, a page trap macro is required
2124 to intercept the page transition, and to restart the mapping of
2125 the \(lqhot\(hyspot\(rq boundary on the new page.
2129 macro package includes a suitable page trap macro, to satisfy this requirement.
2130 However, to avoid pre\(hyempting any other requirement the user may have for
2131 a page transition trap, this is
2133 installed as an active page trap,
2134 unless explicitly requested by the user.
2136 To enable proper handling of page transitions,
2137 which occur within the active regions of reference links,
2138 the user should:\(en
2142 Define a page transition macro, to provide whatever features may be required,
2143 when a page transition occurs \(em e.g.\& printing footnotes,
2144 adding page footers and headers, etc.
2145 This macro should end by setting the output position at the correct
2146 vertical page offset, where the printing of running text is to restart,
2147 following the page transition.
2149 Plant a trap to invoke this macro, at the appropriate vertical position
2150 marking the end of normal running text on each page.
2155 hook into this page transition trap, by invoking
2163 .CWBI macro-name > <
2164 is the name of the user supplied page trap macro,
2167 will correctly restart mapping of active link regions,
2168 at the start of each new page.
2173 It may be observed that this initialisation of the
2175 page transition hook is, typically, required only once
2177 document formatting begins.
2178 Users of document formatting macro packages may reasonably expect that
2179 this initialisation should be performed by the macro package itself.
2180 Thus, writers of such macro packages which include
2182 bindings, should provide appropriate initialisation,
2183 so relieving the end user of this responsibility.
2184 The following example, abstracted from the sample
2188 illustrates how this may be accomplished:\(en
2191 \&.\e" groff "ms" provides the "pg@bottom" macro, which has already
2192 \&.\e" been installed as a page transition trap. To ensure proper
2193 \&.\e" mapping of "pdfhref" links which overflow the bottom of any
2194 \&.\e" page, we need to install the "pdfhref" page transition hook,
2195 \&.\e" as an addendum to this macro.
2197 \&.pdfhref I -PT pg@bottom
2200 .XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
2202 .XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts
2204 It has been noted previously, that the
2214 macro, when used to create a document outline,
2215 .XR add-outline ), (
2216 do not immediately write their
2218 output to the PostScript\*(rg data stream;
2219 instead, they cache their output, in a
2221 diversion, in the case of the
2225 macros, or in an ordered collection of strings and numeric registers,
2226 in the case of the document outline,
2227 until a more appropriate time for copying it out.
2232 \(lqmeta\(hydata\(rq,
2233 this \(lqmore appropriate time\(rq is explicitly chosen by the user;
2234 in the case of document outline data,
2236 cached data may be implicitly written out as the document outline is compiled,
2239 be some remaining data, which must be explicitly flushed out, before the
2241 formatting process is allowed to complete.
2243 To allow the user to choose when cached
2245 data is to be flushed to the output stream, the
2247 macro package provides the
2249 macro, (to synchronise the cache and output states).
2250 In its simplest form, it is invoked without arguments, i.e.
2255 This form of invocation ensures that
2257 the \(lqmeta\(hydata cache\(rq, containing
2263 the \(lqoutline cache\(rq,
2264 containing any previously uncommitted document outline data,
2265 are flushed; ideally, this should be included in a
2267 \(lqend macro\(rq, to ensure that
2269 caches are flushed, before
2274 it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
2275 without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
2276 at a user specified time, prior to reaching the end of the document.
2277 This may be accomplished, by invoking the
2279 macro with an argument, i.e.
2284 to flush only the \(lqmeta\(hydata cache\(rq, or
2289 to flush only the \(lqoutline cache\(rq.
2291 The \(lqmeta\(hydata cache\(rq can normally be safely flushed
2292 in this manner, at any time
2294 output of the first page has started;
2295 (it may cause formatting problems,
2296 most notably the appearance of unwanted white space, if flushed earlier,
2297 or indeed, if flushed immediately after a page transition,
2298 but before the output of the content on the new page has commenced).
2299 Caution is required, however, when explicitly flushing the
2300 \(lqoutline cache\(rq, since if the outline is to be
2301 subsequently extended, then the first outline entry after flushing
2303 be specified at level 1.
2304 Nevertheless, such explict flushing may occasionally be necessary;
2312 .CW ".pdfsync\ O" \(rq \(lq
2313 to ensure that the outline for the \(lqbody\(rq section of the document
2316 it commences the formatting of the table of contents section.
2319 .XN -N pdf-layout -- PDF Document Layout
2323 macros described in the preceding section,
2324 .XR pdf-features ), (
2325 provide no inherent document formatting capability of their own.
2327 they may be used in conjunction with any other
2329 macro package of the user's choice,
2330 to add such capability.
2332 In preparing this document, the standard
2334 macro package, supplied as a component of the GNU Troff distribution,
2336 To facilitate the use of the
2341 a binding macro package,
2344 The use of this binding macro package is described in the following section,
2346 it may also serve as an example to users of other standard
2351 macros may be employed with their chosen primary macro package.
2353 .XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
2355 The use of the binding macro package,
2357 allows for the use of the
2359 macros in conjunction with the
2369 .I "-options ...\&" ] [
2376 input files may be marked up using any of the standard
2378 macros to specify document formatting,
2379 while PDF features may be added,
2382 macros described previously,
2383 .XR pdf-features ). (
2386 defines a number of convenient extensions to the
2388 macro set, to better accomodate the use of PDF features within the
2390 formatting framework,
2391 and to address a number of
2393 document layout issues,
2394 which require special handling when producing PDF documents.
2395 These additional macros,
2396 and the issues they are intended to address,
2397 are described below.
2399 .XN \F[C]ms\F[] Section Headings in PDF Documents
2407 macros, to specify section headings.
2409 there is no standard mechanism for generating a
2410 table of contents entry based on the text of the section heading;
2411 neither is there any recognised standard method for establishing a
2412 cross reference link to the section.
2422 to be used in conjunction with the
2426 .XN -N xn-macro -- The \F[C]XN\F[] Macro
2428 .XN The PDF Publishing Process
2430 .XN -N do-xref -- Resolving Cross References
2432 .XN -N create-map -- Creating a Document Reference Map
2434 .XN -N import-map -- Deploying a Document Reference Map