3 Portable Document Format
4 Publishing with GNU Troff
6 .AI <keith.d.marshall@ntlworld.com>
9 .\" Specify the Internet address for the groff web site.
10 .\" Currently, there are two available addresses; a copy is maintained at ...
12 .ds GROFF-WEBSITE http://www.gnu.org/software/groff
14 .\" ... but the official home site is at ...
16 .ds GROFF-WEBSITE http://groff.ffii.org
18 .\" Set the PDF default document view attribute, to ensure that the document
19 .\" outline is visible, each time the document is opened in Acrobat Reader.
21 .pdfview /PageMode /UseOutlines
23 .\" Initialise the outline view to show only three heading levels,
24 .\" with additional subordinate level headings folded.
26 .nr PDFOUTLINE.FOLDLEVEL 3
28 .\" Add document identification meta-data
30 .pdfinfo /Title Portable Document Format Publishing with GNU Troff
31 .pdfinfo /Author Keith Marshall
32 .pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU Troff
33 .pdfinfo /Keywords groff troff PDF pdfmark
35 .\" Set the default cross reference format to indicate section numbers,
36 .\" rather than page numbers, when we insert a reference pointer.
38 .ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
40 .\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
50 .\" to insert a Registered Trade Mark symbol as a superscript.
54 .\" Establish the page layout.
63 .\" Generate headers in larger point sizes, for NH levels < 4,
64 .\" with point size increasing by 1.5p, for each lesser NH level.
70 .\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
74 \\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
77 \\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
80 \\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
82 .ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
85 .\" When we use numbered section headings, we might like to automatically
86 .\" insert a table of contents entry, using the text of the heading itself.
87 .\" The "ms" macros don't provide any standard mechanism for doing this,
88 .\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
90 .\" Here's a simple example of how we might use it. In this case, the word
91 .\" "Introduction" will appear both in the body of the document, as the text
92 .\" of the heading, and it will be added to the table of contents, which is
93 .\" subsequently "printed" using the "TC" macro; in both locations, it will
94 .\" be prefixed by the section number.
96 .\" As an additional side effect, any use of "XN" will cause the table of
97 .\" contents entry to be automatically reproduced, with the exception of its
98 .\" page number reference, as a PDF document outline entry. Thus, the use
99 .\" of "XN" to specify numbered section headings results in the automatic
100 .\" creation of a numbered PDF document outline. This automatic creation
101 .\" of the outline is completely transparent, and will occur regardless
102 .\" of whether the "TC" macro is subsequently invoked, or not.
106 .\" If using an old s.tmac, without the SN-NO-DOT extension,
107 .\" make sure we get SOMETHING in section number references.
109 .if !dSN-NO-DOT .als SN-NO-DOT SN
111 It might appear that it is a fairly simple matter to
112 produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
113 commonly known as PDF, using
114 .CW groff ) GNU\~Troff\~(
115 as the document formatter.
118 default output format is the native Adobe\*(rg\~PostScript\*(rg format,
119 which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
120 or GhostScript, expect as their input format.
121 Thus, the PDF production process would seem to entail simply
122 formatting the document source with
124 to produce a PostScript\*(rg version of the document,
125 which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
126 or GhostScript, to generate the final PDF document.
128 For many PDF production requirements,
129 the production cycle described above may be sufficient.
130 However, this is a limited PDF production method,
131 in which the resultant PDF document represents no more than
132 an on screen image of the printed form of the document, if
134 PostScript\*(rg output were printed directly.
136 The Portable Document Format provides a number of features,
137 which significantly enhance the experience of reading a document on screen,
138 but which are of little or no value to a document which is merely printed.
141 possible to exploit these PDF features, which are described in the Adobe\*(rg
144 .\" This is an example of a resource reference specified by URI ...
145 .\" We may need to refer often to the Adobe pdfmark Reference Manual,
146 .\" so we create the internet link definition using a macro, to make
149 .\" Note also, that we protect the description of the reference by
150 .\" preceding it with "--", to avoid "invalid character in name" type
151 .\" error messages from groff (caused by the use of "\~").
153 .pdfhref W -D http://partners.adobe.com/asn/acrobat/docs/pdfmark.pdf \
154 -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
157 with some refinement of the simple PDF production method, provided
158 appropriate \(lqfeature implementing\(rq instructions can be embedded into
160 PostScript\*(rg rendering of the document.
161 This, of course, implies that the original document source, which
163 will process to generate the PostScript\*(rg description of the document,
164 must include appropriate markup to exploit the desired PDF features.
165 It is this preparation of the
167 document source to exploit a number of these features,
168 which provides the principal focus of this document.
170 The markup techniques to be described have been utilised in the production of
171 the PDF version of this document itself.
172 This has been formatted using
176 thus, usage examples may be found in the document source file,
178 to which comments have been added,
179 to help identify appropriate markup examples for implementing PDF features,
183 Selecting a default document view, which defines how the document will appear
184 when opened in the reader application; for example, when this document is
185 opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
186 in the document view pane, while a document outline should appear to the left,
187 in the \(lqBookmarks\(rq pane.
189 Adding document identification \(lqmeta\(hydata\(rq,
190 which can be accessed, in Acrobat\*(rg\~Reader,
191 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
193 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
194 pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
195 section of the document, simply by clicking on the associated heading
198 Embedding active links in the body of the document, such that readers may
199 quickly navigate to related material at another location within the same
200 document, or in another PDF document, or even to a related Internet resource,
201 specified by its URI.
203 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
204 points within the PDF document.
207 All of the techniques described have been tested on
209 GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
212 .pdfhref L -D footnote1 -- \**
215 Later versions should, and some earlier versions may, be equally suitable.
217 .pdfhref W \*[GROFF-WEBSITE]
218 for information and availability of the latest version.
224 .pdfhref L -D footnote2 -- \**
227 Again, other versions may be suitable.
229 .pdfhref W http://ghostscript.com
230 for information and availability.
232 Other tools employed, which should be readily available on
237 or GNU/Linux system, are
242 together with an appropriate text editor, for creating and marking up the
245 These additional utilities are not provided, as standard,
246 on the Microsoft\*(rg Windows\(tm platform,
247 but several third party implementations are available.
248 Some worth considering include the MKS\*(rg\~Toolkit,\**
250 A commercial offering; see
251 .pdfhref W http://mkssoftware.com/products/tk/default.asp
262 emulation environment and
266 toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
267 .pdfhref W http://cygwin.com
268 for information and download.
272 Another free, but minimal suite of common
276 tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
277 .pdfhref W -A ; http://www.mingw.org
280 include those tools listed above,
281 and is the package which was actually used when performing the Windows\(tm2000
282 platform tests referred to in the text.
284 This list is by no means exhaustive, and should in no way be construed as an
285 endorsement of any of these packages, nor to imply that other similar packages,
286 which may be available, are in any way inferior to them.
289 .\" We may wish a section heading to represent a named destination,
290 .\" so that we can create a linked reference to it, from some other
291 .\" part of the PDF document, (or even from another PDF document).
293 .\" Here we use the "-N" option of the "XN" macro, to create a named
294 .\" PDF link destination, at the location of the heading. Notice that
295 .\" we also use the "--" marker to separate the heading text from the
296 .\" preceding option specification; it is not strictly necessary in
297 .\" this case, but it does help to set off the heading text from the
298 .\" option specification.
300 .XN -N pdf-features -- Exploiting PDF Document Features
302 To establish a consistent framework for adding PDF features, a
307 Thus, to incorporate PDF features in a document,
308 the appropriate macro calls, as described below, may be placed in the
310 document source, which should then be processed with a
319 .I "file ..." \& "...] "
321 It may be noted that the
323 macros have no dependencies on, and no known conflicts with,
326 macro package; thus, users are free to use any other macro package,
327 of their choice, to format their documents, while also using the
329 macros to add PDF features.
331 .XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
333 All PDF features are implemented by embedding instances of the
335 operator, as described in the Adobe\*(rg
339 PostScript\*(rg output stream.
340 To facilitate the use of this operator, the
342 macro package defines the primitive
344 macro; it simply emits its argument list,
347 operator, in the PostScript\*(rg output stream.
349 .pdfhref M -N pdfmark-example
350 To illustrate the use of the
352 macro, the following is a much simplified example of how a bookmark
353 may be added to a PDF document outline
360 /Title (An Example of a Bookmark with Two Children) \e
361 /View [/FitH \en[PDFPAGE.Y]] \e
365 In general, users should rarely need to use the
368 In particular, the above example is too simple for general use; it
370 create a bookmark, but it does
372 address the issues of setting the proper value for the
374 key, nor of computing the
380 macro package includes a more robust mechanism for creating bookmarks,
382 .\" Here is an example of how a local reference may be planted,
383 .\" using the automatic formatting feature of the "pdfhref" macro.
385 .\" This is a forward reference to the named destination "add-outline",
386 .\" which is defined below, using the "XN" wrapper macro, from the
387 .\" "spdf.tmac" macro package. The automatically formatted reference
388 .\" will be enclosed in parentheses, as specified by the use of
389 .\" "-P" and "-A" options.
391 .pdfhref L -P ( -A ), -D add-outline
393 which addresses these issues automatically.
396 macro may be useful to users wishing to implement more advanced PDF features,
397 than those currently supported directly by the
401 .XN -N docview -- Selecting an Initial Document View
404 when a PDF document is opened,
405 the first page will be displayed,
406 at the default magnification set for the reader,
407 and outline and thumbnail views will be hidden.
408 When using a PDF reader,
409 such as Acrobat\*(rg\~Reader,
415 these default initial view settings may be overridden,
421 .CW ".pdfview /PageMode /UseOutlines"
423 will cause Acrobat\*(rg\~Reader to open the document outline view,
424 to the left of the normal page view,
427 .CW ".pdfview /PageMode /UseThumbs"
429 will open the thumbnail view instead.
433 examples, above, are mutually exclusive \(em it is not possible to have
435 outline and thumbnail views open simultaneously.
442 keys, to force the document to open at a page other than the first,
443 or to change the magnification at which the document is initially displayed;
446 for more information.
448 It should be noted that the view controlling meta\(hydata, defined by the
450 macro, is not written immediately to the PostScript\*(rg output stream,
451 but is stored in an internal meta\(hydata \(lqcache\(rq,
452 (simply implemented as a
455 This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
459 .\" Here is another example of how we may introduce a forward reference.
460 .\" This time we are using the shorter notation afforded by the "XR" macro
461 .\" provided by "spdf.tmac"; this example is equivalent to the native
462 .\" "pdfmark.tmac" form
463 .\" .pdfhref L -D pdfsync -P ( -A ).
468 .XN -N docinfo -- Adding Document Identification Meta-Data
472 class of meta\(hydata described above,
474 we may also wish to include document identification meta\(hydata,
475 which belongs to the PDF
479 To do this, we use the
482 As an example of how it is used,
483 the identification meta\(hydata attached to this document
484 was specified using a macro sequence similar to:\(en
487 \&.pdfinfo /Title PDF Document Publishing with GNU Troff
488 \&.pdfinfo /Author Keith Marshall
489 \&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff
490 \&.pdfinfo /Keywords groff troff PDF pdfmark
494 macro is repeated, once for each
496 record to be placed in the document.
497 In each case, the first argument is the name of the applicable
501 be named with an initial solidus character;
502 all additional arguments are collected together,
503 to define the value to be associated with the specified key.
505 As is the case with the
511 records specified with the
513 macro are not immediately written to the PostScript\*(rg output stream;
514 they are stored in the same meta\(hydata cache as
516 specifications, until this cache is explicitly flushed,
522 .XN -N add-outline -- Creating a Document Outline
524 A PDF document outline comprises a table of references,
525 to \(lqbookmarked\(rq locations within the document.
526 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
527 such as Adobe\*(rg Acrobat\*(rg Reader,
528 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
529 or \(lqBookmarks\(rq pane, to the left of the main document view.
530 Individual references in the outline view may then be selected,
531 by clicking with the mouse,
532 to jump directly to the associated marked location in the document view.
534 The document outline may be considered as a collection of \(lqhypertext\(rq
535 references to \(lqbookmarked\(rq locations within the document.
538 macro package provides a single generalised macro,
540 for creating and linking to \(lqhypertext\(rq reference marks.
541 This macro will be described more comprehensively in a later section,
543 the description here is restricted to its use for defining document outline entries.
545 .XN -N basic-outline -- A Basic Document Outline
547 In its most basic form, the document outline comprises a structured list of headings,
548 each associated with a marked location, or \(lqbookmark\(rq, in the document text,
549 and a specification for how that marked location should be displayed,
550 when this bookmark is selected.
552 To create a PDF bookmark, the
555 at the point in the document where the bookmark is to be placed,
561 .I "descriptive text ..."
563 in which the reference class
564 .CWB O \& \& \(rq \(lq
565 stipulates that this is an outline reference.
567 Alternatively, for those users who may prefer to think of a document outline
568 simply as a collection of bookmarks, the
570 macro is also provided \(em indeed,
572 invokes it, when processing the
573 .CWB O \& \& \(rq \(lq
574 reference class operator.
575 It may be invoked directly, in the form
580 .I "descriptive text ..."
582 Irrespective of which of the above macro forms is employed, the
584 argument is required.
585 It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
586 in the outline hierarchy, with one being the topmost level.
587 Its function may be considered analagous to the
589 of the document's section headings,
590 for example, as specified with the
594 macros to format the document.
596 All further arguments, following the
598 argument, are collected together, to specify the heading text which will appear
599 in the document's outline view.
600 Thus, the outline entry for this section of this document,
601 which has a level three heading,
602 might be specified as
605 \&.pdfhref O 3 \*(SN A Basic Document Outline
607 or, in the alternative form using the
612 \&.pdfbookmark 3 \*(SN A Basic Document Outline
614 .XN Hierarchical Structure in a Document Outline
616 When a document outline is created, using the
618 macro as described in
620 .\" Here is an example of how we can temporarily modify the format of
621 .\" a reference link, in this case to indicate only the section number
622 .\" of the link target, in the form "section #", (or, if we define
623 .\" "SECREF.BEGIN" before the call, its content followed by the
626 .\" We first define a macro, which will get the reference data from
627 .\" pdfhref, as arguments, and will return the formatted output, as we
628 .\" require it, the string "PDFHREF.TEXT".
632 . ie '\\$1'section' \{\
633 . if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
634 . ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
641 .\" We now tell "pdfhref" to use our formatting macro, in place of
642 .\" its builtin default formatter, before we specify the reference.
645 .pdfhref L -A , -D basic-outline
647 .\" At this point, we would normally revert the "pdfhref" formatter
648 .\" to use its default, built in macro. However, in this particular
649 .\" case, we want to use our custom format one more time, before we
650 .\" revert it, so we will omit the reversion step this time.
652 and any entry is added at a nesting level greater than one,
653 then a hierarchical structure is automatically defined for the outline.
654 However, as was noted in the simplified
655 .pdfhref L -D pdfmark-example -- example
657 .pdfhref L -A , -D pdfmark-operator
659 .\" And now, we revert to default "pdfhref" formatting behaviour,
660 .\" by completing the call we delayed above.
664 the data required by the
666 operator to create the outline entry may not be fully defined,
667 when the outline reference is defined in the
670 Specifically, when the outline entry is created, its
672 key must be assigned a value equal to the number of its subordinate entries,
673 at the next inner level of the outline hierarchy;
675 these subordinate entries will be defined
677 in the document source, and the appropriate
679 value will be unknown, when defining the parent entry.
681 To resolve this paradox, the
683 macro creates the outline entry in two distinct phases \(em
684 a destination marker is placed in the PostScript\*(rg output stream immediately,
685 when the outline reference is defined,
686 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
687 until its subordinate hierarchy has been fully defined;
688 it can then be inserted in the output stream, with its
690 value correctly assigned.
691 Effectively, to ensure integrity of the document outline structure,
692 this means that each top level outline entry, and
694 of its subordinates, are retained in the cache, until the
696 top level entry is defined.
698 One potential problem, which arises from the use of the \(lqoutline cache\(rq,
699 is that, at the end of any document formatting run, the last top level outline entry,
700 and any subordinates defined after it, will remain in the cache, and will
702 be automatically written to the output stream.
703 To avoid this problem, the user should follow the guidelines given in
705 .\" Here is a more conventional example of how to temporarily change
706 .\" to the format used to display reference links. We will again use
707 .\" the "SECREF" format, which we defined above, but on this occasion
708 .\" we will immediately revert to the default format, after the link
712 .pdfhref L -D pdfsync -A ,
715 to synchronise the output state with the cache state,
721 .XN -N outline-view -- Associating a Document View with an Outline Reference
723 Each \(lqbookmark\(rq entry, in a PDF document outline,
724 is associated with a specific document view.
725 When the reader selects any outline entry,
726 the document view changes to display the document context
727 associated with that entry.
729 The document view specification,
730 to be associated with any document outline entry,
731 is established at the time when the outline entry is created.
732 However, rather than requiring that each individual use of the
734 macro, to create an outline entry,
735 should include its own view specification,
736 the actual specification assigned to each entry is derived from
737 a generalised specification defined in the string
738 .CW PDFBOOKMARK.VIEW ,
739 together with the setting of the numeric register
740 .CW PDFHREF.VIEW.LEADING ,
741 which determine the effective view specification as follows:\(en
743 .IP \*[= PDFBOOKMARK.VIEW]
744 Establishes the magnification at which the document will be viewed,
745 at the location of the \(lqbookmark\(rq; by default, it is defined by
748 .CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
751 which displays the associated document view,
752 with the \(lqbookmark\(rq location positioned at the top of the display window,
753 and with the magnification set to fit the page width to the width of the window.
754 .IP \*[= PDFHREF.VIEW.LEADING]
755 Specifies additional spacing,
756 to be placed between the top of the display window
757 and the actual location of the \(lqbookmark\(rq on the displayed page view.
758 By default, it is set as
761 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
765 .CW PDFHREF.VIEW.LEADING
766 does not represent true \(lqleading\(rq, in the typographical sense,
767 since any preceding text, set in the specified display space,
768 will be visible at the top of the document viewing window,
769 when the reference is selected.
771 Also note that the specification of
772 .CW PDFHREF.VIEW.LEADING
775 reference views defined by the
779 is applied exclusively to outline references,
780 there is no independent
781 .CW PDFBOOKMARK.VIEW.LEADING
785 If desired, the view specification may be changed, by redefining the string
786 .CW PDFBOOKMARK.VIEW ,
787 and possibly also the numeric register
788 .CW PDFHREF.VIEW.LEADING .
789 Any alternative definition for
792 be specified in terms of valid view specification parameters,
793 as described in the Adobe\*(rg
796 Note the use of the register
798 in the default definition of
801 This register is computed by
803 when creating an outline entry;
804 it specifies the vertical position of the \(lqbookmark\(rq,
807 units, relative to the
809 edge of the document page on which it is defined,
810 and is followed, in the
815 operator, to convert it to PostScript\*(rg units on output.
816 It may be used in any redefined specification for
817 .CW PDFBOOKMARK.VIEW ,
818 (or in the analogous definition of
821 .XR-NO-PREFIX pdfhref-view ),
824 in any other context,
825 since its value is undefined outside the scope of the
831 is computed relative to the
833 of the PDF output page,
834 it is important to ensure that the page length specified to
836 correctly matches the size of the logical PDF page.
837 This is most effectively ensured,
840 page size specifications to
843 and to the PostScript\*(rg to PDF converter employed,
844 and avoiding any page length changes within the document source.
848 is the only automatically computed \(lqbookmark\(rq location parameter;
849 if the user redefines
850 .CW PDFBOOKMARK.VIEW ,
851 and the modified view specification requires any other positional parameters,
854 ensure that these are computed
860 .XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
862 When a document incorporates many subheadings,
863 at deeply nested levels,
864 it may be desirable to \(lqfold\(rq the outline
865 such that only the major heading levels are initially visible,
866 yet making the inferior subheadings accessible,
867 by allowing the reader to expand the view of any heading branch on demand.
871 macros support this capability,
872 through the setting of the
873 .CW PDFOUTLINE.FOLDLEVEL
875 This register should be set to the number of heading levels
876 which it is desired to show in expanded form, in the
878 document outline display;
879 all subheadings at deeper levels will still be added to the outline,
880 but will not become visible until the outline branch containing them is expanded.
882 For example, the setting used in this document:
886 \&.\e" Initialise the outline view to show only three heading levels,
887 \&.\e" with additional subordinate level headings folded.
889 \&.nr PDFOUTLINE.FOLDLEVEL 3
893 results in only the first three levels of headings being displayed
894 in the document outline,
896 the reader chooses to expand the view,
897 and so reveal the lower level headings in any outline branch.
899 The initial default setting of
900 .CW PDFOUTLINE.FOLDLEVEL ,
901 if the document author does not choose to change it,
903 This is orders of magnitude greater than the maximum heading level
904 which is likely to be used in any document;
905 thus the default behaviour will be to show document outlines fully expanded,
906 to display all headings defined,
907 at all levels within each document.
910 .CW PDFOUTLINE.FOLDLEVEL
911 may be changed at any time;
912 however, the effect of each such change may be difficult to predict,
913 since it is applied not only to outline entries which are defined
915 the setting is changed,
916 but also to any entries which remain in the outline cache,
919 Therefore, it is recommended that
920 .CW PDFOUTLINE.FOLDLEVEL
923 at the start of each document;
926 deemed necessary to change it at any other time,
927 the outline cache should be flushed,
931 which should immediately preceed a level one heading.
933 .XN -N multipart-outline -- Outlines for Multipart Documents
935 When a document outline is created, using the
937 macro, each reference mark is automatically assigned a name,
938 composed of a fixed stem followed by a serially generated numeric qualifier.
939 This ensures that, for each single part document, every outline reference
940 has a uniquely named destination.
942 As the overall size of the PDF document increases,
943 it may become convenient to divide it into smaller,
944 individually formatted PostScript\*(rg components,
945 which are then assembled, in the appropriate order,
946 to create a composite PDF document.
947 While this strategy may simplify the overall process of creating and
948 editing larger documents, it does introduce a problem in creating
949 an overall document outline,
950 since each individual PostScript\*(rg component will be assigned
951 duplicated sequences of \(lqbookmark\(rq names,
952 with each name ultimately referring to multiple locations in the composite document.
953 To avoid such reference naming conflicts, the
955 macro allows the user to specify a \(lqtag\(rq,
956 which is appended to the automatically generated \(lqbookmark\(rq name;
957 this may be used as a discriminating mark, to distinguish otherwise
958 similarly named destinations, in different sections of the composite document.
960 To create a \(lqtagged\(rq document outline,
961 the syntax for invocation of the
963 macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
965 the nesting level argument, i.e.
972 .I "descriptive text ..."
976 argument may be composed of any characters of the user's choice;
977 however, its initial character
979 be any decimal digit, and ideally it should be kept short
980 \(em one or two characters at most.
982 By employing a different tag in each section,
983 the user can ensure that \(lqbookmark\(rq names remain unique,
984 throughout all the sections of a composite document.
985 For example, when using the
987 macro package, which adds
989 capabilities to the standard
993 the table of contents is collected into a separate PostScript\*(rg section
994 from the main body of the document.
995 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
996 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
998 macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
1003 .CW ".pdfhref O -T T 1 \e\e*[TOC]"
1005 to tag the associated outline destination name with the single character suffix,
1007 Alternatively, as in the case of the basic outline,
1008 .XR basic-outline ), (
1009 this may equally well be specified as
1011 .CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1013 .XN Delegation of the Outline Definition
1015 Since the most common use of a document outline
1016 is to provide a quick method of navigating through a document,
1017 using active \(lqhypertext\(rq links to chapter and section headings,
1018 it may be convenient to delegate the responsibility of creating the outline
1019 to a higher level macro, which is itself used to
1020 define and format the section headings.
1021 This approach has been adopted in the
1023 package, to be described later,
1026 When such an approach is adopted,
1027 the user will rarely, if ever, invoke the
1029 macro directly, to create a document outline.
1030 For example, the structure and content of the outline for this document
1031 has been exclusively defined, using a combination of the
1035 package, to establish the structure, and the
1039 to define the content.
1041 the responsibility for invoking the
1043 macro, to create the document outline,
1048 .XN -N pdfhref -- Adding Reference Marks and Links
1051 .ds SECREF.BEGIN Section
1052 .pdfhref L -D add-outline
1056 macro may be used to create a PDF document outline.
1057 While this is undoubtedly a powerful capability,
1058 it is by no means the only trick in the repertoire of this versatile macro.
1062 which is a contraction of \(lqPDF HyperText Reference\(rq,
1063 indicates that the general purpose of this macro is to define
1065 type of dynamic reference mark, within a PDF document.
1066 Its generalised usage syntax takes the form
1071 .I "-options ...\&" ] [
1073 .I "descriptive text ...\&" ] [
1077 represents a required single character argument,
1078 which defines the specific reference operation to be performed,
1079 and may be selected from:\(en
1082 Add an entry to the document outline.
1083 This operation has been described earlier,
1084 .XR add-outline ). (
1086 Place a \(lqnamed destination\(rq reference mark at the current output position,
1087 in the current PDF document,
1090 Specify the content of a PDF document reference dictionary entry;
1091 typically, such entries are generated automatically,
1092 by transformation of the intermediate output resulting from the use of
1094 .CWB M \& \& \(rq, \(lq
1096 .CWB -X \& \& \(rq \(lq
1099 however, it is also possible to specify such entries manually,
1100 .XR user-format ). (
1102 Insert an active link to a named destination,
1104 at the current output position in the current PDF document,
1105 such that when the reader clicks on the link text,
1106 the document view changes to show the location of the named destination.
1108 Insert an active link to a \(lqweb\(rq resource,
1109 .XR add-weblink ), (
1110 at the current output position in the current PDF document.
1111 This is effectively the same as using the
1112 .CWB L \& \& \(rq \(lq
1113 operator to establish a link to a named destination in another PDF document,
1114 .XR link-extern ), (
1115 except that in this case, the destination is specified by a
1116 \(lquniform resource identifier\(rq, or
1118 this may represent any Internet or local resource
1119 which can be specified in this manner.
1121 Specify a user defined macro, to be called by
1123 when formatting the text in the active region of a link,
1126 Define the absolute position on the physical PDF output page,
1127 where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
1128 Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
1129 for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
1130 specified directly by the user;
1133 .CWB Z \& \& \(rq \(lq
1134 specifications are inserted automatically into the document reference map
1135 during the PDF document formatting process,
1138 Initialise support for
1143 implementation provides only one such feature which requires initialisation
1144 \(em a helper macro which must be attached to a user supplied page trap handler,
1145 in order to support mapping of reference \(lqhot\(hyspots\(rq
1146 which extend through a page transition;
1150 .XN Optional Features of the \F[C]pdfhref\F[] Macro
1152 The behaviour of a number of the
1154 macro operations can be modified,
1156 .EM "option specifiers" \(rq \(lq
1157 after the operation specifying argument,
1160 any other arguments normally associated with the operation.
1163 cases, an option is specified by an
1164 .EM "option flag" \(rq, \(lq
1165 comprising an initial hyphen,
1166 followed by one or two option identifying characters.
1172 for these options, the argument
1174 be specified, and it
1176 be separated from the preceding option flag by one or more
1181 It may be noted that this paradigm for specifying options
1182 is reminiscent of most
1186 shells; however, in the case of the
1188 macro, omission of the space separating an option flag from its argument is
1194 general purpose options supported by the
1196 macro is given below.
1197 Note that not all options are supported for all
1199 operations; the operations affected by each option are noted in the list.
1202 operations, if an unsupported option is specified,
1203 it will be silently ignored; however, this behaviour should
1206 The general purpose options, supported by the
1210 .IP \*[= -N\0 name > <]
1213 associated with a PDF reference destination
1214 to be defined independently from the following text,
1215 which describes the reference.
1216 This option affects only the
1217 .CWB M \& \& \(rq \(lq
1223 Also used exclusively with the
1224 .CWB M \& \& \(rq \(lq
1227 option causes any specified
1228 .CWI descriptive \& \& \~\c
1234 in the body text of the document,
1235 at the point where the reference mark is defined;
1239 .CWI descriptive \& \& \~\c
1243 at points where links to the reference mark are placed,
1244 and where the standard reference display format,
1247 .IP \*[= -D\0 dest > <]
1250 or the destination name associated with a PDF active link,
1251 independently of the following text,
1252 which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1253 This option affects the behaviour of the
1256 .CWB L \& \& \(rq \(lq
1258 .CWB W \& \& \(rq \(lq
1262 .CWB L \& \& \(rq \(lq
1265 argument must specify a PDF \(lqnamed destination\(rq,
1269 .CWB M \& \& \(rq \(lq
1273 .CWB W \& \& \(rq \(lq
1276 must specify a link destination in the form of a
1277 \(lquniform resource identifier\(rq, or
1279 .XR add-weblink ). (
1280 .IP \*[= -F\0 file > <]
1282 .CWB L \& \& \(rq \(lq
1286 specifies an external PDF file in which the named destination
1287 for the link reference is defined.
1290 be specified with the
1291 .CWB L \& \& \(rq \(lq
1293 to create a link to a destination in a different PDF document;
1295 .CWB L \& \& \(rq \(lq
1298 this option, the link destination is assumed to be defined
1299 within the same document.
1300 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1302 .CWI \(dqprefix\(hytext\(dq > <
1303 to be attached to the
1305 of the text describing an active PDF document link,
1306 with no intervening space, but without itself being included in the
1307 active area of the link \(lqhot\(hyspot\(rq;
1308 it is effective with the
1309 .CWB L \& \& \(rq \(lq
1311 .CWB W \& \& \(rq \(lq
1315 Typically, this option would be used to insert punctuation before
1316 the link \(lqhot\(hyspot\(rq.
1317 Thus, there is little reason for the inclusion of spaces in
1318 .CWI \(dqprefix\(hytext\(dq > < ;
1319 however, if such space is required, then the enclosing double quotes
1321 be specified, as indicated.
1322 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1324 .CWI \(dqaffixed\(hytext\(dq > <
1325 to be attached to the
1327 of the text describing an active PDF document link,
1328 with no intervening space, but without itself being included in the
1329 active area of the link \(lqhot\(hyspot\(rq;
1330 it is effective with the
1331 .CWB L \& \& \(rq \(lq
1333 .CWB W \& \& \(rq \(lq
1337 Typically, this option would be used to insert punctuation after
1338 the link \(lqhot\(hyspot\(rq.
1339 Thus, there is little reason for the inclusion of spaces in
1340 .CWI \(dqaffixed\(hytext\(dq > < ;
1341 however, if such space is required, then the enclosing double quotes
1343 be specified, as indicated.
1344 .IP \*[= -T\0 tag > <]
1345 When specified with the
1346 .CWB O \& \& \(rq \(lq
1349 is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1352 to distinguish between the series of \(lqbookmark\(rq names generated in
1353 individual passes of the
1355 formatter, when the final PDF document is to be assembled
1356 from a number of separately formatted components;
1357 .XR multipart-outline ). (
1361 option is used with either the
1362 .CWB M \& \& \(rq \(lq
1363 operator, or with the
1364 .CWB L \& \& \(rq \(lq
1368 .CWB M \& \& \(rq \(lq
1371 it ensures that a cross reference record for the marked destination
1372 will be included in the document reference map,
1376 .CWB L \& \& \(rq \(lq
1379 it causes the reference to be displayed in the standard cross reference format,
1381 but substituting the
1382 .CWI descriptive \& \& \~\c
1388 for the description specified in the document reference map.
1390 Marks the end of the option specifiers.
1391 This may be used with all
1393 operations which accept options, to prevent
1395 from interpreting any following arguments as option specifiers,
1396 even if they would otherwise be interpreted as such.
1397 It is also useful when the argument list to
1399 contains special characters \(em any special character,
1400 which is not legal in a
1402 macro name, will cause a parsing error, if
1404 attempts to match it as a possible option flag;
1407 flag prevents this, so suppressing the
1409 warning message, which would otherwise ensue.
1411 Using this flag after
1413 sequences of macro options is recommended,
1414 even when it is not strictly necessary,
1415 if only for the entirely cosmetic benefit of visually separating
1416 the main argument list from the sequence of preceding options.
1421 options listed above, a supplementary set of two character options are defined.
1422 These supplementary options, listed below, are intended for use with the
1423 .CWB L \& \& \(rq \(lq
1424 operator, in conjunction with the
1427 option, to specify alternate file names,
1428 in formats compatible with the file naming conventions
1429 of alternate operating systems;
1430 they will be silently ignored, if used in any other context.
1432 The supported alternate file name options,
1433 which are ignored if the
1436 option is not specified, are:\(en
1438 .IP \*[= -DF\0 dos\(hyfile > <]
1439 Specifies the name of the file in which a link destination is defined,
1440 using the file naming semantics of the
1443 When the PDF document is read on a machine
1444 where the operating system uses the
1447 .CWI dos\(hyfile > <
1448 is used as the name of the file containing the reference destination,
1451 argument specified with the
1454 .IP \*[= -MF\0 mac\(hyfile > <]
1455 Specifies the name of the file in which a link destination is defined,
1456 using the file naming semantics of the
1460 When the PDF document is read on a machine
1461 where the operating system uses the
1464 .CWI mac\(hyfile > <
1465 is used as the name of the file containing the reference destination,
1468 argument specified with the
1471 .IP \*[= -UF\0 unix\(hyfile > <]
1472 Specifies the name of the file in which a link destination is defined,
1473 using the file naming semantics of the
1476 When the PDF document is read on a machine
1477 where the operating system uses
1479 file naming semantics, then
1480 .CWI unix\(hyfile > <
1481 is used as the name of the file containing the reference destination,
1484 argument specified with the
1487 .IP \*[= -WF\0 win\(hyfile > <]
1488 Specifies the name of the file in which a link destination is defined,
1489 using the file naming semantics of the
1490 .CW MS\(hyWindows \*(rg
1491 32\(hybit operating system.
1492 When the PDF document is read on a machine
1493 where the operating system uses any of the
1494 .CW MS\(hyWindows \*(rg
1495 file systems, with long file name support, then
1496 .CWI win\(hyfile > <
1497 is used as the name of the file containing the reference destination,
1500 argument specified with the
1505 .XN -N mark-dest -- Marking a Reference Destination
1509 macro may be used to create active links to any Internet resource,
1512 or to any \(lqnamed destination\(rq,
1513 either within the same document, or in another PDF document.
1514 Although the PDF specification allows link destinations to be defined
1515 in terms of a page number, and an associated view specification,
1516 this style of reference is not currently supported by the
1518 macro, because it is not possible to adequately bind the specification
1519 for the destination with the intended reference context.
1521 References to Internet resources are interpreted in accordance with the
1523 standard for defining a
1525 hence the only prerequisite, for creating a link to any Internet resource,
1528 be properly specified, when declaring the reference;
1529 .XR add-weblink ). (
1530 In the case of references to \(lqnamed destinations\(rq in PDF documents,
1531 however, it is necessary to provide a mechanism for creating such
1532 \(lqnamed destinations\(rq.
1533 This may be accomplished, by invoking the
1543 .I "descriptive text ...\&" ] [
1545 This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1549 option is not specified, by the first word of
1550 .CWI descriptive \& \& \~\c
1552 (note that this imposes the restriction that,
1555 option is omitted, then
1558 .CWI descriptive \& \& \~\c
1562 Additionally, a reference view will be automatically defined,
1563 and associated with the reference mark,
1564 .XR pdfhref-view ), (
1566 .\" .CWI descriptive
1568 .\" is specified, or the
1571 option is specified, and no document cross reference map has been imported,
1573 then a cross reference mapping record,
1575 will be written to the
1578 this may be captured, and subsequently used to generate a cross reference map
1582 When a \(lqnamed destination\(rq reference mark is created, using the
1585 .CWB M \& \& \(rq \(lq
1586 operator, there is normally no visible effect in the formatted document; any
1587 .CWI descriptive \& \& \~\c
1589 which is specified will simply be stored in the cross reference map,
1590 for use when a link to the reference mark is created.
1591 This default behaviour may be changed, by specifying the
1593 option, which causes any specified
1594 .CWI descriptive \& \& \~\c
1596 to be \(lqechoed\(rq in the document text,
1597 at the point where the reference mark is placed,
1598 in addition to its inclusion in the cross reference map.
1600 .XN -N export-map -- Mapping a Destination for Cross Referencing
1602 Effective cross referencing of
1604 document formatted by
1606 requires multiple pass formatting.
1607 Details of how this multiple pass formatting may be accomplished,
1608 when working with the
1610 macros, will be discussed later,
1612 at this stage, the discussion will be restricted to the initial preparation,
1613 which is required at the time when the cross reference destinations are defined.
1615 The first stage, in the process of cross referencing a document,
1616 is the generation of a cross reference map.
1617 Again, the details of
1619 the cross reference map is generated will be discussed in
1620 .pdfhref F SECREF L -D do-xref -A ;
1622 however, it is important to recognise that
1624 content is included in the cross reference map is established
1625 when the reference destination is defined \(em it is derived
1626 from the reference data exported on the
1630 macro, when it is invoked with the
1631 .CWB M \& \& \(rq \(lq
1632 operator, and is controlled by whatever definition of the string
1634 is in effect, when the
1638 The initial default setting of
1642 .CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1644 which ensures that the cross reference map will contain
1645 at least a page number reference, supplemented by any
1646 .CWI descriptive \& \& \~\c
1648 which is specified for the reference mark, as defined by the
1651 .CWB M \& \& \(rq \(lq
1652 operator; this may be redefined by the user,
1653 to export additional cross reference information,
1654 or to modify the default format for cross reference links,
1657 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
1659 In the same manner as each document outline reference, defined by the
1662 .CWB O \& \& \(rq \(lq
1664 .XR add-outline ), (
1665 has a specific document view associated with it,
1666 each reference destination marked by
1669 .CWB M \& \& \(rq \(lq
1670 operator, requires an associated document view specification.
1672 The mechanism whereby a document view is associated with a reference mark
1673 is entirely analogous to that employed for outline references,
1674 .XR outline-view ), (
1677 string specification is used, in place of the
1678 .CW PDFBOOKMARK.VIEW
1680 Thus, the reference view is defined in terms of:\(en
1682 .IP \*[= PDFHREF.VIEW]
1684 establishing the position of the reference mark within the viewing window,
1685 and the magnification at which the document will be viewed,
1686 at the location of the marked reference destination;
1687 by default, it is defined by
1690 .CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
1693 which displays the reference destination at the top of the viewing window,
1694 with the magnification set to fit the page width to the width of the window.
1695 .IP \*[= PDFHREF.VIEW.LEADING]
1697 specifying additional spacing, to be placed between the top of the display
1698 window and the actual position at which the location of the reference
1699 destination appears within the window.
1700 This register is shared with the view specification for outline references,
1701 and thus has the same default initial setting,
1704 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
1707 as in the case of outline reference views.
1710 .CW PDFHREF.VIEW.LEADING
1711 does not represent true typographic \(lqleading\(rq,
1712 since any preceding text, set in the specified display space,
1713 will be visible at the top of the viewing window,
1714 when the reference is selected.
1717 Just as the view associated with outline references may be changed,
1719 .CW PDFBOOKMARK.VIEW ,
1720 so the view associated with marked reference destinations may be changed,
1724 .CW PDFHREF.VIEW.LEADING ;
1725 such changes will become effective for all reference destinations marked
1727 these definitions are changed.
1728 (Notice that, since the specification of
1729 .CW PDFHREF.VIEW.LEADING
1730 is shared by both outline reference views and marked reference views,
1731 if it is changed, then the views for
1733 reference types are changed accordingly).
1735 It may again be noted, that the
1737 register is used in the definition of
1739 just as it is in the definition of
1740 .CW PDFBOOKMARK.VIEW ;
1742 .pdfhref F SECREF L -D outline-view
1744 relating to its use, and indeed to page position computations in general,
1745 apply equally to marked reference views and to outline reference views.
1747 .XN -N link-named -- Linking to a Marked Reference Destination
1749 Any named destination, such as those marked by the
1752 .CWB M \& \& \(rq \(lq
1753 operator, may be referred to from any point in
1755 PDF document, using an
1757 such active links are created by again using the
1759 macro, but in this case, with the
1760 .CWB L \& \& \(rq \(lq
1762 This operator provides support for two distinct cases,
1763 depending on whether the reference destination is defined in
1764 the same document as the link,
1765 .XR link-intern ), (
1766 or is defined as a named destination in a different PDF document,
1767 .XR link-extern ). (
1769 .XN -N link-intern -- References within a Single PDF Document
1771 The general syntactic form for invoking the
1774 when creating a link to a named destination within the same PDF document is
1782 .BI prefix-text >] <
1784 .BI affixed-text >] <
1790 .I "descriptive text ...\&" ] [
1794 specifies the name of the link destination,
1795 as specified using the
1797 .CWB M \& \& \(rq \(lq
1798 operation; (it may be defined either earlier in the document,
1799 to create a backward reference, or later, to create a forward reference).
1801 .\" Here's a example of how to add an iconic annotation.
1803 .\".pdfnote -T "Internal Cross References" \
1804 .\" This description is rather terse, and could benefit from \
1805 .\" the inclusion of an example.
1808 .CWI descriptive \& \& \~\c
1810 arguments are specified, then they will be inserted into the
1812 output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
1814 this will be printed in the link colour specified by the string,
1815 .CW PDFHREF.TEXT.COLOUR ,
1816 which is described in
1817 .XR-NO-PREFIX set-colour .
1820 option is also specified, then the
1821 .CWI descriptive \& \& \~\c
1823 will be augmented, by prefacing it with page and section number indicators,
1824 in accordance with the reference formatting rules which are in effect,
1826 such indicators will be included within the active link region,
1827 and will also be printed in the link colour.
1833 .CWBI dest\(hyname > <
1837 .CWI descriptive \& \& \~\c
1840 .EM "but not both" ,
1844 .CWBI dest\(hyname > <
1845 option is omitted, then the first word of
1846 .CWI descriptive \& \& \~\c
1848 i.e.\~all text up to but not including the first space,
1849 will be interpreted as the
1850 .CWBI dest\(hyname > <
1851 for the link; this text will also appear in the running text of the document,
1852 within the active region of the link.
1853 Alternatively, if the
1855 .CWBI dest\(hyname > <
1859 .CWI descriptive \& \& \~\c
1862 then the running text which defines the reference,
1863 and its active region,
1864 will be derived from the reference description which is specified
1865 when the named destination is marked,
1867 and will be formatted according to the reference formatting rules
1868 which are in effect, when the reference is placed,
1870 in this case, it is not necessary to specify the
1872 option to activate automatic formatting of the reference \(em it is implied,
1873 by the omission of all
1874 .CWI descriptive \& \& \~\c
1880 .CWBI prefix\(hytext > <
1883 .CWBI affixed\(hytext > <
1884 options may be used to specify additional text
1885 which will be placed before and after the linked text respectively,
1886 with no intervening space.
1887 Such prefixed and affixed text will be printed in the normal text colour,
1888 and will not be included within the active region of the link.
1889 This feature is mostly useful for creating parenthetical references,
1890 or for placing punctuation adjacent to,
1891 but not included within,
1892 the text which defines the active region of the link.
1894 The operation of the
1896 macro, when used with its
1897 .CWB L \& \& \(rq \(lq
1898 operator to place a link to a named PDF destination,
1899 may best be illustrated by an example.
1900 However, since the appearance of the link will be influenced by
1901 factors established when the named destination is marked,
1903 and also by the formatting rules in effect when the link is placed,
1904 the presentation of a suitable exanple will be deferred,
1905 until the formatting mechanism has been explained,
1908 .XN -N link-extern -- References to Destinations in Other PDF Documents
1913 .CWB L \& \& \(rq \(lq
1914 operator is not restricted to creating reference links
1915 within a single PDF document.
1916 When the link destination is defined in a different document,
1917 then the syntactic form for invoking
1919 is modified, by the addition of options to specify the
1920 name and location of the PDF file in which the destination is defined.
1923 syntactic form becomes
1947 .BI prefix-text >] <
1949 .BI affixed-text >] <
1955 .I "descriptive text ...\&" ] [
1962 purposes: it both indicates to the
1964 macro that the specified reference destination
1965 is defined in an external PDF file,
1966 and it also specifies the normal path name,
1967 which is to be used to locate this file,
1968 when a user selects the reference.
1975 be specified when referring to a destination in an external PDF file,
1978 .CWBI dos\(hyfile > < ,
1980 .CWBI mac\(hyfile > < ,
1982 .CWBI unix\(hyfile > <
1985 .CWBI win\(hyfile > <
1986 options may be used to specify the location of the file
1987 containing the reference destination,
1988 in a variety of operating system dependent formats.
1989 These options assign their arguments to the
1995 keys of the generated
1997 respectively; thus when any of these options are specified,
1998 .EM "in addition to"
2002 option, and the document is read on the appropriate operating systems,
2003 then the path names specified by
2004 .CWBI dos\(hyfile > < ,
2005 .CWBI mac\(hyfile > < ,
2006 .CWBI unix\(hyfile > <
2008 .CWBI win\(hyfile > <
2011 of the path name specified by
2014 .CW MS\(hyDOS \*(rg,
2016 .CW Macintosh \*(rg,
2019 .CW MS\(hyWindows \*(rg
2020 operating systems, respectively; see the
2022 for further details.
2024 Other than the use of these additional options,
2025 which specify that the reference destination is in an external PDF file,
2026 the behaviour of the
2028 .CWB L \& \& \(rq \(lq
2032 option, remains identical to its behaviour
2035 .XR link-intern ), (
2036 with respect to the interpretation of other options,
2038 .CWI descriptive \& \& \~\c
2040 arguments, and the formatting of the displayed reference.
2042 Once again, since the appearance of the reference is determined by
2043 factors specified in the document reference map,
2044 and also by the formatting rules in effect when the reference is placed,
2045 the presentation of an example of the placing of
2046 a reference to an external destination will be deferred,
2047 until the formatting mechanism has been explained,
2050 .XN -N add-weblink -- Linking to Internet Resources
2052 In addition to supporting the creation of cross references
2053 to named destinations in PDF documents, the
2055 macro also has the capability to create active links to Internet resources,
2058 resource which may be specified by a Uniform Resource Identifier,
2059 (which is usually abbreviated to the acronym \(lqURI\(rq,
2060 and sometimes also referred to as a Uniform Resource Locator,
2063 Since the mechanism for creating a link to a URI differs somewhat
2064 from that for creating PDF references, the
2066 macro is invoked with the
2067 .CWB W \& \& \(rq \(lq
2068 (for \(lqweb\(hylink\(rq) operator, rather than the
2069 .CWB L \& \& \(rq \(lq
2070 operator; nevertheless, the invocation syntax is similar, having the form
2078 .BI prefix-text >] <
2080 .BI affixed-text >] <
2085 .I "descriptive text ...\&"
2090 modifier specifies the address for the target Internet resource,
2092 .EM "Uniform Resource Identifier"
2096 argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
2099 .CWBI prefix\(hytext > <
2102 .CWBI affixed\(hytext > <
2103 options have the same effect as in the case of local document links,
2104 .XR link-intern ). (
2106 Notice that it is not mandatory to include the
2109 in the link specification; if it
2111 specified, then it is not necessary for the URI to appear,
2112 in the running text of the document \(em the
2115 argument exactly defines the text
2116 which will appear within the \(lqhot\(hyspot\(rq region,
2117 and this need not include the URI.
2121 specification is omitted, then the
2128 representation of the URI, which
2130 therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
2131 For example, we could introduce a reference to
2132 .pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2133 in which the actual URI is concealed, by using mark up such as:\(en
2136 For example, we could introduce a reference to
2137 \&.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2138 in which the actual URI is concealed,
2141 to refer the reader to the groff web site,
2142 making it obvious that the appropriate URI is
2143 .pdfhref W -A , \*[GROFF-WEBSITE]
2144 the requisite mark up might be:\(en
2147 to refer the reader to the groff web site,
2148 making it obvious that the appropriate URI is
2149 \&.pdfhref W -A , \*[GROFF-WEBSITE]
2150 the requisite mark up might be:\e(en
2153 .XN -N set-format -- Establishing a Format for References
2155 There are two principal aspects to be addressed,
2156 when defining the format to be used when displaying references.
2157 Firstly, it is desirable to provide a visual cue,
2158 to indicate that the text describing the reference is imbued
2159 with special properties \(em it is dynamically linked to the reference
2160 destination \(em and secondly, the textual content should
2161 describe where the link leads, and ideally,
2162 it should also describe the content of the reference destination.
2165 that a text region defines a dynamically linked reference,
2166 is most commonly provided by printing the text within the active
2167 region in a distinctive colour.
2168 This technique will be employed automatically by the
2172 \(em unless the user specifically chooses to adopt, and implement,
2173 some alternative strategy.
2175 .XN -N set-colour -- Using Colour to Demarcate Link Regions
2177 Typically, when a PDF document contains
2179 references to other locations, either within the same document,
2180 or even in other documents, or on the World Wide Web,
2181 it is usually desirable to make the regions
2182 where these active links are placed stand out from the surrounding text.
2184 .XN -N user-format -- Specifying Reference Text Explicitly
2186 .XN -N auto-format -- Using Automatically Formatted Reference Text
2188 .XN -N custom-format -- Customising Automatically Formatted Reference Text
2190 It is incumbent on the user,
2191 if employing automatic formatting of the displayed reference,
2193 to ensure that an appropriate reference definition
2194 is created for the reference destination,
2195 and is included in the reference map for the document
2196 in which the reference will appear;
2197 thus, it may be easiest to
2199 use manual formatting for external references.
2201 .XN Problematic Links
2203 Irrespective of whether a
2205 reference is placed using the
2206 .CWB L \& \& \(rq \(lq
2208 .CWB W \& \& \(rq \(lq
2209 operator, there may be occasions when the resulting link
2210 does function as expected.
2211 A number of scenarios, which are known to be troublesome,
2212 are described below.
2214 .XN -N page-trap -- Links with a Page Transition in the Active Region
2216 When a link is placed near the bottom of a page,
2217 it is possible that its active region, or \(lqhot\(hyspot\(rq,
2218 may extend on to the next page.
2219 In this situation, a page trap macro is required
2220 to intercept the page transition, and to restart the mapping of
2221 the \(lqhot\(hyspot\(rq boundary on the new page.
2225 macro package includes a suitable page trap macro, to satisfy this requirement.
2226 However, to avoid pre\(hyempting any other requirement the user may have for
2227 a page transition trap, this is
2229 installed as an active page trap,
2230 unless explicitly requested by the user.
2232 To enable proper handling of page transitions,
2233 which occur within the active regions of reference links,
2234 the user should:\(en
2238 Define a page transition macro, to provide whatever features may be required,
2239 when a page transition occurs \(em e.g.\& printing footnotes,
2240 adding page footers and headers, etc.
2241 This macro should end by setting the output position at the correct
2242 vertical page offset, where the printing of running text is to restart,
2243 following the page transition.
2245 Plant a trap to invoke this macro, at the appropriate vertical position
2246 marking the end of normal running text on each page.
2251 hook into this page transition trap, by invoking
2259 .CWBI macro-name > <
2260 is the name of the user supplied page trap macro,
2263 will correctly restart mapping of active link regions,
2264 at the start of each new page.
2269 It may be observed that this initialisation of the
2271 page transition hook is, typically, required only once
2273 document formatting begins.
2274 Users of document formatting macro packages may reasonably expect that
2275 this initialisation should be performed by the macro package itself.
2276 Thus, writers of such macro packages which include
2278 bindings, should provide appropriate initialisation,
2279 so relieving the end user of this responsibility.
2280 The following example, abstracted from the sample
2284 illustrates how this may be accomplished:\(en
2287 \&.\e" groff "ms" provides the "pg@bottom" macro, which has already
2288 \&.\e" been installed as a page transition trap. To ensure proper
2289 \&.\e" mapping of "pdfhref" links which overflow the bottom of any
2290 \&.\e" page, we need to install the "pdfhref" page transition hook,
2291 \&.\e" as an addendum to this macro.
2293 \&.pdfhref I -PT pg@bottom
2296 .XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
2298 .XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts
2300 It has been noted previously, that the
2310 macro, when used to create a document outline,
2311 .XR add-outline ), (
2312 do not immediately write their
2314 output to the PostScript\*(rg data stream;
2315 instead, they cache their output, in a
2317 diversion, in the case of the
2321 macros, or in an ordered collection of strings and numeric registers,
2322 in the case of the document outline,
2323 until a more appropriate time for copying it out.
2328 \(lqmeta\(hydata\(rq,
2329 this \(lqmore appropriate time\(rq is explicitly chosen by the user;
2330 in the case of document outline data,
2332 cached data may be implicitly written out as the document outline is compiled,
2335 be some remaining data, which must be explicitly flushed out, before the
2337 formatting process is allowed to complete.
2339 To allow the user to choose when cached
2341 data is to be flushed to the output stream, the
2343 macro package provides the
2345 macro, (to synchronise the cache and output states).
2346 In its simplest form, it is invoked without arguments, i.e.
2351 This form of invocation ensures that
2353 the \(lqmeta\(hydata cache\(rq, containing
2359 the \(lqoutline cache\(rq,
2360 containing any previously uncommitted document outline data,
2361 are flushed; ideally, this should be included in a
2363 \(lqend macro\(rq, to ensure that
2365 caches are flushed, before
2370 it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
2371 without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
2372 at a user specified time, prior to reaching the end of the document.
2373 This may be accomplished, by invoking the
2375 macro with an argument, i.e.
2380 to flush only the \(lqmeta\(hydata cache\(rq, or
2385 to flush only the \(lqoutline cache\(rq.
2387 The \(lqmeta\(hydata cache\(rq can normally be safely flushed
2388 in this manner, at any time
2390 output of the first page has started;
2391 (it may cause formatting problems,
2392 most notably the appearance of unwanted white space, if flushed earlier,
2393 or indeed, if flushed immediately after a page transition,
2394 but before the output of the content on the new page has commenced).
2395 Caution is required, however, when explicitly flushing the
2396 \(lqoutline cache\(rq, since if the outline is to be
2397 subsequently extended, then the first outline entry after flushing
2399 be specified at level 1.
2400 Nevertheless, such explict flushing may occasionally be necessary;
2408 .CW ".pdfsync\ O" \(rq \(lq
2409 to ensure that the outline for the \(lqbody\(rq section of the document
2412 it commences the formatting of the table of contents section.
2415 .XN -N pdf-layout -- PDF Document Layout
2419 macros described in the preceding section,
2420 .XR pdf-features ), (
2421 provide no inherent document formatting capability of their own.
2423 they may be used in conjunction with any other
2425 macro package of the user's choice,
2426 to add such capability.
2428 In preparing this document, the standard
2430 macro package, supplied as a component of the GNU Troff distribution,
2432 To facilitate the use of the
2437 a binding macro package,
2440 The use of this binding macro package is described in the following section,
2442 it may also serve as an example to users of other standard
2447 macros may be employed with their chosen primary macro package.
2449 .XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
2451 The use of the binding macro package,
2453 allows for the use of the
2455 macros in conjunction with the
2465 .I "-options ...\&" ] [
2472 input files may be marked up using any of the standard
2474 macros to specify document formatting,
2475 while PDF features may be added,
2478 macros described previously,
2479 .XR pdf-features ). (
2482 defines a number of convenient extensions to the
2484 macro set, to better accomodate the use of PDF features within the
2486 formatting framework,
2487 and to address a number of
2489 document layout issues,
2490 which require special handling when producing PDF documents.
2491 These additional macros,
2492 and the issues they are intended to address,
2493 are described below.
2495 .XN \F[C]ms\F[] Section Headings in PDF Documents
2503 macros, to specify section headings.
2505 there is no standard mechanism for generating a
2506 table of contents entry based on the text of the section heading;
2507 neither is there any recognised standard method for establishing a
2508 cross reference link to the section.
2518 to be used in conjunction with the
2522 .XN -N xn-macro -- The \F[C]XN\F[] Macro
2524 .XN The PDF Publishing Process
2526 .XN -N do-xref -- Resolving Cross References
2528 .XN -N create-map -- Creating a Document Reference Map
2530 .XN -N import-map -- Deploying a Document Reference Map
projects / FreeBSD / releng / 9.2.git / blob