4 File position: <groff-source>/contrib/pdfmark/pdfmark.ms
6 This file is part of groff, the GNU roff type-setting system.
8 Copyright (C) 2004-2018 Free Software Foundation, Inc.
9 written by Keith Marshall <keith.d.marshall@ntlworld.com>
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.3 or
13 any later version published by the Free Software Foundation; with no
14 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
17 A copy of the Free Documentation License is included as a file called
18 FDL in the main directory of the groff source package.
22 Portable Document Format
23 Publishing with GNU Troff
25 .AI <keith.d.marshall@ntlworld.com>
28 .\" Specify the Internet address for the groff web site.
30 .ds GROFF-WEBSITE http://www.gnu.org/software/groff
32 .\" Set the PDF default document view attribute, to ensure that the document
33 .\" outline is visible, each time the document is opened in Acrobat Reader.
35 .pdfview /PageMode /UseOutlines
37 .\" Initialise the outline view to show only three heading levels,
38 .\" with additional subordinate level headings folded.
40 .nr PDFOUTLINE.FOLDLEVEL 3
42 .\" Add document identification meta-data
44 .pdfinfo /Title Portable Document Format Publishing with GNU Troff
45 .pdfinfo /Author Keith Marshall
46 .pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU Troff
47 .pdfinfo /Keywords groff troff PDF pdfmark
49 .\" Set the default cross reference format to indicate section numbers,
50 .\" rather than page numbers, when we insert a reference pointer.
52 .ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
54 .\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
64 .\" to insert a Registered Trade Mark symbol as a superscript.
68 .\" Establish the page layout.
77 .\" Generate headers in larger point sizes, for NH levels < 4,
78 .\" with point size increasing by 1.5p, for each lesser NH level.
84 .\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
88 \\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
91 \\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
94 \\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
96 .ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
99 .\" When we use numbered section headings, we might like to automatically
100 .\" insert a table of contents entry, using the text of the heading itself.
101 .\" The "ms" macros don't provide any standard mechanism for doing this,
102 .\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
104 .\" Here's a simple example of how we might use it. In this case, the word
105 .\" "Introduction" will appear both in the body of the document, as the text
106 .\" of the heading, and it will be added to the table of contents, which is
107 .\" subsequently "printed" using the "TC" macro; in both locations, it will
108 .\" be prefixed by the section number.
110 .\" As an additional side effect, any use of "XN" will cause the table of
111 .\" contents entry to be automatically reproduced, with the exception of its
112 .\" page number reference, as a PDF document outline entry. Thus, the use
113 .\" of "XN" to specify numbered section headings results in the automatic
114 .\" creation of a numbered PDF document outline. This automatic creation
115 .\" of the outline is completely transparent, and will occur regardless
116 .\" of whether the "TC" macro is subsequently invoked, or not.
120 .\" If using an old s.tmac, without the SN-NO-DOT extension,
121 .\" make sure we get SOMETHING in section number references.
123 .if !dSN-NO-DOT .als SN-NO-DOT SN
125 It might appear that it is a fairly simple matter to
126 produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
127 commonly known as PDF, using
128 .CW groff ) GNU\~Troff\~(
129 as the document formatter.
132 default output format is the native Adobe\*(rg\~PostScript\*(rg format,
133 which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
134 or GhostScript, expect as their input format.
135 Thus, the PDF production process would seem to entail simply
136 formatting the document source with
138 to produce a PostScript\*(rg version of the document,
139 which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
140 or GhostScript, to generate the final PDF document.
142 For many PDF production requirements,
143 the production cycle described above may be sufficient.
144 However, this is a limited PDF production method,
145 in which the resultant PDF document represents no more than
146 an on screen image of the printed form of the document, if
148 PostScript\*(rg output were printed directly.
150 The Portable Document Format provides a number of features,
151 which significantly enhance the experience of reading a document on screen,
152 but which are of little or no value to a document which is merely printed.
155 possible to exploit these PDF features, which are described in the Adobe\*(rg
158 .\" This is an example of a resource reference specified by URI ...
159 .\" We may need to refer often to the Adobe pdfmark Reference Manual,
160 .\" so we create the internet link definition using a macro, to make
163 .\" Note also, that we protect the description of the reference by
164 .\" preceding it with "--", to avoid "invalid character in name" type
165 .\" error messages from groff (caused by the use of "\~").
167 .pdfhref W -D http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/pdf_creation_apis_and_specs/pdfmarkReference.pdf \
168 -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
171 with some refinement of the simple PDF production method, provided
172 appropriate \(lqfeature implementing\(rq instructions can be embedded into
174 PostScript\*(rg rendering of the document.
175 This, of course, implies that the original document source, which
177 will process to generate the PostScript\*(rg description of the document,
178 must include appropriate markup to exploit the desired PDF features.
179 It is this preparation of the
181 document source to exploit a number of these features,
182 which provides the principal focus of this document.
184 The markup techniques to be described have been utilised in the production of
185 the PDF version of this document itself.
186 This has been formatted using
190 thus, usage examples may be found in the document source file,
192 to which comments have been added,
193 to help identify appropriate markup examples for implementing PDF features,
197 Selecting a default document view, which defines how the document will appear
198 when opened in the reader application; for example, when this document is
199 opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
200 in the document view pane, while a document outline should appear to the left,
201 in the \(lqBookmarks\(rq pane.
203 Adding document identification \(lqmeta\(hydata\(rq,
204 which can be accessed, in Acrobat\*(rg\~Reader,
205 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
207 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
208 pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
209 section of the document, simply by clicking on the associated heading
212 Embedding active links in the body of the document, such that readers may
213 quickly navigate to related material at another location within the same
214 document, or in another PDF document, or even to a related Internet resource,
215 specified by its URI.
217 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
218 points within the PDF document.
221 All of the techniques described have been tested on
223 GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
226 .pdfhref L -D footnote1 -- \**
229 Later versions should, and some earlier versions may, be equally suitable.
231 .pdfhref W \*[GROFF-WEBSITE]
232 for information and availability of the latest version.
238 .pdfhref L -D footnote2 -- \**
241 Again, other versions may be suitable.
243 .pdfhref W http://ghostscript.com
244 for information and availability.
246 Other tools employed, which should be readily available on
250 or GNU/Linux system, are
255 together with an appropriate text editor, for creating and marking up the
258 These additional utilities are not provided, as standard,
259 on the Microsoft\*(rg Windows\(tm platform,
260 but several third party implementations are available.
261 Some worth considering include the MKS\*(rg\~Toolkit,\**
263 A commercial offering; see
264 .pdfhref W http://mkssoftware.com/products/tk/default.asp
275 emulation environment and
278 toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
279 .pdfhref W http://cygwin.com
280 for information and download.
284 Another free, but minimal suite of common
287 tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
288 .pdfhref W -A ; http://www.mingw.org
291 include those tools listed above,
292 and is the package which was actually used when performing the Windows\(tm2000
293 platform tests referred to in the text.
295 This list is by no means exhaustive, and should in no way be construed as an
296 endorsement of any of these packages, nor to imply that other similar packages,
297 which may be available, are in any way inferior to them.
300 .\" We may wish a section heading to represent a named destination,
301 .\" so that we can create a linked reference to it, from some other
302 .\" part of the PDF document, (or even from another PDF document).
304 .\" Here we use the "-N" option of the "XN" macro, to create a named
305 .\" PDF link destination, at the location of the heading. Notice that
306 .\" we also use the "--" marker to separate the heading text from the
307 .\" preceding option specification; it is not strictly necessary in
308 .\" this case, but it does help to set off the heading text from the
309 .\" option specification.
311 .XN -N pdf-features -- Exploiting PDF Document Features
313 To establish a consistent framework for adding PDF features, a
318 Thus, to incorporate PDF features in a document,
319 the appropriate macro calls, as described below, may be placed in the
321 document source, which should then be processed with a
330 .I "file ..." \& "...] "
332 (Or use the PDF post-processor to avoid using ghostscript,
336 It may be noted that the
338 macros have no dependencies on, and no known conflicts with,
341 macro package; thus, users are free to use any other macro package,
342 of their choice, to format their documents, while also using the
344 macros to add PDF features.
346 .XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
348 All PDF features are implemented by embedding instances of the
350 operator, as described in the Adobe\*(rg
354 PostScript\*(rg output stream.
355 To facilitate the use of this operator, the
357 macro package defines the primitive
359 macro; it simply emits its argument list,
362 operator, in the PostScript\*(rg output stream.
364 .pdfhref M -N pdfmark-example
365 To illustrate the use of the
367 macro, the following is a much simplified example of how a bookmark
368 may be added to a PDF document outline
375 /Title (An Example of a Bookmark with Two Children) \e
376 /View [/FitH \en[PDFPAGE.Y]] \e
380 In general, users should rarely need to use the
383 In particular, the above example is too simple for general use; it
385 create a bookmark, but it does
387 address the issues of setting the proper value for the
389 key, nor of computing the
395 macro package includes a more robust mechanism for creating bookmarks,
397 .\" Here is an example of how a local reference may be planted,
398 .\" using the automatic formatting feature of the "pdfhref" macro.
400 .\" This is a forward reference to the named destination "add-outline",
401 .\" which is defined below, using the "XN" wrapper macro, from the
402 .\" "spdf.tmac" macro package. The automatically formatted reference
403 .\" will be enclosed in parentheses, as specified by the use of
404 .\" "-P" and "-A" options.
406 .pdfhref L -P ( -A ), -D add-outline
408 which addresses these issues automatically.
411 macro may be useful to users wishing to implement more advanced PDF features,
412 than those currently supported directly by the
416 .XN -N docview -- Selecting an Initial Document View
419 when a PDF document is opened,
420 the first page will be displayed,
421 at the default magnification set for the reader,
422 and outline and thumbnail views will be hidden.
423 When using a PDF reader,
424 such as Acrobat\*(rg\~Reader,
430 these default initial view settings may be overridden,
436 .CW ".pdfview /PageMode /UseOutlines"
438 will cause Acrobat\*(rg\~Reader to open the document outline view,
439 to the left of the normal page view,
442 .CW ".pdfview /PageMode /UseThumbs"
444 will open the thumbnail view instead.
448 examples, above, are mutually exclusive \(em it is not possible to have
450 outline and thumbnail views open simultaneously.
457 keys, to force the document to open at a page other than the first,
458 or to change the magnification at which the document is initially displayed;
461 for more information.
463 It should be noted that the view controlling meta\(hydata, defined by the
465 macro, is not written immediately to the PostScript\*(rg output stream,
466 but is stored in an internal meta\(hydata \(lqcache\(rq,
467 (simply implemented as a
470 This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
474 .\" Here is another example of how we may introduce a forward reference.
475 .\" This time we are using the shorter notation afforded by the "XR" macro
476 .\" provided by "spdf.tmac"; this example is equivalent to the native
477 .\" "pdfmark.tmac" form
478 .\" .pdfhref L -D pdfsync -P ( -A ).
483 .XN -N docinfo -- Adding Document Identification Meta-Data
487 class of meta\(hydata described above,
489 we may also wish to include document identification meta\(hydata,
490 which belongs to the PDF
494 To do this, we use the
497 As an example of how it is used,
498 the identification meta\(hydata attached to this document
499 was specified using a macro sequence similar to:\(en
502 \&.pdfinfo /Title PDF Document Publishing with GNU Troff
503 \&.pdfinfo /Author Keith Marshall
504 \&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff
505 \&.pdfinfo /Keywords groff troff PDF pdfmark
509 macro is repeated, once for each
511 record to be placed in the document.
512 In each case, the first argument is the name of the applicable
516 be named with an initial solidus character;
517 all additional arguments are collected together,
518 to define the value to be associated with the specified key.
520 As is the case with the
526 records specified with the
528 macro are not immediately written to the PostScript\*(rg output stream;
529 they are stored in the same meta\(hydata cache as
531 specifications, until this cache is explicitly flushed,
537 .XN -N add-outline -- Creating a Document Outline
539 A PDF document outline comprises a table of references,
540 to \(lqbookmarked\(rq locations within the document.
541 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
542 such as Adobe\*(rg Acrobat\*(rg Reader,
543 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
544 or \(lqBookmarks\(rq pane, to the left of the main document view.
545 Individual references in the outline view may then be selected,
546 by clicking with the mouse,
547 to jump directly to the associated marked location in the document view.
549 The document outline may be considered as a collection of \(lqhypertext\(rq
550 references to \(lqbookmarked\(rq locations within the document.
553 macro package provides a single generalised macro,
555 for creating and linking to \(lqhypertext\(rq reference marks.
556 This macro will be described more comprehensively in a later section,
558 the description here is restricted to its use for defining document outline entries.
560 .XN -N basic-outline -- A Basic Document Outline
562 In its most basic form, the document outline comprises a structured list of headings,
563 each associated with a marked location, or \(lqbookmark\(rq, in the document text,
564 and a specification for how that marked location should be displayed,
565 when this bookmark is selected.
567 To create a PDF bookmark, the
570 at the point in the document where the bookmark is to be placed,
576 .I "descriptive text ..."
578 in which the reference class
579 .CWB O \& \& \(rq \(lq
580 stipulates that this is an outline reference.
582 Alternatively, for those users who may prefer to think of a document outline
583 simply as a collection of bookmarks, the
585 macro is also provided \(em indeed,
587 invokes it, when processing the
588 .CWB O \& \& \(rq \(lq
589 reference class operator.
590 It may be invoked directly, in the form
595 .I "descriptive text ..."
597 Irrespective of which of the above macro forms is employed, the
599 argument is required.
600 It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
601 in the outline hierarchy, with one being the topmost level.
602 Its function may be considered analagous to the
604 of the document's section headings,
605 for example, as specified with the
609 macros to format the document.
611 All further arguments, following the
613 argument, are collected together, to specify the heading text which will appear
614 in the document's outline view.
615 Thus, the outline entry for this section of this document,
616 which has a level three heading,
617 might be specified as
620 \&.pdfhref O 3 \*(SN A Basic Document Outline
622 or, in the alternative form using the
627 \&.pdfbookmark 3 \*(SN A Basic Document Outline
629 .XN Hierarchical Structure in a Document Outline
631 When a document outline is created, using the
633 macro as described in
635 .\" Here is an example of how we can temporarily modify the format of
636 .\" a reference link, in this case to indicate only the section number
637 .\" of the link target, in the form "section #", (or, if we define
638 .\" "SECREF.BEGIN" before the call, its content followed by the
641 .\" We first define a macro, which will get the reference data from
642 .\" pdfhref, as arguments, and will return the formatted output, as we
643 .\" require it, the string "PDFHREF.TEXT".
647 . ie '\\$1'section' \{\
648 . if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
649 . ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
656 .\" We now tell "pdfhref" to use our formatting macro, in place of
657 .\" its builtin default formatter, before we specify the reference.
660 .pdfhref L -A , -D basic-outline
662 .\" At this point, we would normally revert the "pdfhref" formatter
663 .\" to use its default, built in macro. However, in this particular
664 .\" case, we want to use our custom format one more time, before we
665 .\" revert it, so we will omit the reversion step this time.
667 and any entry is added at a nesting level greater than one,
668 then a hierarchical structure is automatically defined for the outline.
669 However, as was noted in the simplified
670 .pdfhref L -D pdfmark-example -- example
672 .pdfhref L -A , -D pdfmark-operator
674 .\" And now, we revert to default "pdfhref" formatting behaviour,
675 .\" by completing the call we delayed above.
679 the data required by the
681 operator to create the outline entry may not be fully defined,
682 when the outline reference is defined in the
685 Specifically, when the outline entry is created, its
687 key must be assigned a value equal to the number of its subordinate entries,
688 at the next inner level of the outline hierarchy;
690 these subordinate entries will be defined
692 in the document source, and the appropriate
694 value will be unknown, when defining the parent entry.
696 To resolve this paradox, the
698 macro creates the outline entry in two distinct phases \(em
699 a destination marker is placed in the PostScript\*(rg output stream immediately,
700 when the outline reference is defined,
701 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
702 until its subordinate hierarchy has been fully defined;
703 it can then be inserted in the output stream, with its
705 value correctly assigned.
706 Effectively, to ensure integrity of the document outline structure,
707 this means that each top level outline entry, and
709 of its subordinates, are retained in the cache, until the
711 top level entry is defined.
713 One potential problem, which arises from the use of the \(lqoutline cache\(rq,
714 is that, at the end of any document formatting run, the last top level outline entry,
715 and any subordinates defined after it, will remain in the cache, and will
717 be automatically written to the output stream.
718 To avoid this problem, the user should follow the guidelines given in
720 .\" Here is a more conventional example of how to temporarily change
721 .\" to the format used to display reference links. We will again use
722 .\" the "SECREF" format, which we defined above, but on this occasion
723 .\" we will immediately revert to the default format, after the link
727 .pdfhref L -D pdfsync -A ,
730 to synchronise the output state with the cache state,
736 .XN -N outline-view -- Associating a Document View with an Outline Reference
738 Each \(lqbookmark\(rq entry, in a PDF document outline,
739 is associated with a specific document view.
740 When the reader selects any outline entry,
741 the document view changes to display the document context
742 associated with that entry.
744 The document view specification,
745 to be associated with any document outline entry,
746 is established at the time when the outline entry is created.
747 However, rather than requiring that each individual use of the
749 macro, to create an outline entry,
750 should include its own view specification,
751 the actual specification assigned to each entry is derived from
752 a generalised specification defined in the string
753 .CW PDFBOOKMARK.VIEW ,
754 together with the setting of the numeric register
755 .CW PDFHREF.VIEW.LEADING ,
756 which determine the effective view specification as follows:\(en
758 .IP \*[= PDFBOOKMARK.VIEW]
759 Establishes the magnification at which the document will be viewed,
760 at the location of the \(lqbookmark\(rq; by default, it is defined by
763 .CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
766 which displays the associated document view,
767 with the \(lqbookmark\(rq location positioned at the top of the display window,
768 and with the magnification set to fit the page width to the width of the window.
769 .IP \*[= PDFHREF.VIEW.LEADING]
770 Specifies additional spacing,
771 to be placed between the top of the display window
772 and the actual location of the \(lqbookmark\(rq on the displayed page view.
773 By default, it is set as
776 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
780 .CW PDFHREF.VIEW.LEADING
781 does not represent true \(lqleading\(rq, in the typographical sense,
782 since any preceding text, set in the specified display space,
783 will be visible at the top of the document viewing window,
784 when the reference is selected.
786 Also note that the specification of
787 .CW PDFHREF.VIEW.LEADING
790 reference views defined by the
794 is applied exclusively to outline references,
795 there is no independent
796 .CW PDFBOOKMARK.VIEW.LEADING
800 If desired, the view specification may be changed, by redefining the string
801 .CW PDFBOOKMARK.VIEW ,
802 and possibly also the numeric register
803 .CW PDFHREF.VIEW.LEADING .
804 Any alternative definition for
807 be specified in terms of valid view specification parameters,
808 as described in the Adobe\*(rg
811 Note the use of the register
813 in the default definition of
816 This register is computed by
818 when creating an outline entry;
819 it specifies the vertical position of the \(lqbookmark\(rq,
822 units, relative to the
824 edge of the document page on which it is defined,
825 and is followed, in the
830 operator, to convert it to PostScript\*(rg units on output.
831 It may be used in any redefined specification for
832 .CW PDFBOOKMARK.VIEW ,
833 (or in the analogous definition of
836 .XR-NO-PREFIX pdfhref-view ),
839 in any other context,
840 since its value is undefined outside the scope of the
846 is computed relative to the
848 of the PDF output page,
849 it is important to ensure that the page length specified to
851 correctly matches the size of the logical PDF page.
852 This is most effectively ensured,
855 page size specifications to
858 and to the PostScript\*(rg to PDF converter employed,
859 and avoiding any page length changes within the document source.
863 is the only automatically computed \(lqbookmark\(rq location parameter;
864 if the user redefines
865 .CW PDFBOOKMARK.VIEW ,
866 and the modified view specification requires any other positional parameters,
869 ensure that these are computed
875 .XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
877 When a document incorporates many subheadings,
878 at deeply nested levels,
879 it may be desirable to \(lqfold\(rq the outline
880 such that only the major heading levels are initially visible,
881 yet making the inferior subheadings accessible,
882 by allowing the reader to expand the view of any heading branch on demand.
886 macros support this capability,
887 through the setting of the
888 .CW PDFOUTLINE.FOLDLEVEL
890 This register should be set to the number of heading levels
891 which it is desired to show in expanded form, in the
893 document outline display;
894 all subheadings at deeper levels will still be added to the outline,
895 but will not become visible until the outline branch containing them is expanded.
897 For example, the setting used in this document:
901 \&.\e" Initialise the outline view to show only three heading levels,
902 \&.\e" with additional subordinate level headings folded.
904 \&.nr PDFOUTLINE.FOLDLEVEL 3
908 results in only the first three levels of headings being displayed
909 in the document outline,
911 the reader chooses to expand the view,
912 and so reveal the lower level headings in any outline branch.
914 The initial default setting of
915 .CW PDFOUTLINE.FOLDLEVEL ,
916 if the document author does not choose to change it,
918 This is orders of magnitude greater than the maximum heading level
919 which is likely to be used in any document;
920 thus the default behaviour will be to show document outlines fully expanded,
921 to display all headings defined,
922 at all levels within each document.
925 .CW PDFOUTLINE.FOLDLEVEL
926 may be changed at any time;
927 however, the effect of each such change may be difficult to predict,
928 since it is applied not only to outline entries which are defined
930 the setting is changed,
931 but also to any entries which remain in the outline cache,
934 Therefore, it is recommended that
935 .CW PDFOUTLINE.FOLDLEVEL
938 at the start of each document;
941 deemed necessary to change it at any other time,
942 the outline cache should be flushed,
946 which should immediately preceed a level one heading.
948 .XN -N multipart-outline -- Outlines for Multipart Documents
950 When a document outline is created, using the
952 macro, each reference mark is automatically assigned a name,
953 composed of a fixed stem followed by a serially generated numeric qualifier.
954 This ensures that, for each single part document, every outline reference
955 has a uniquely named destination.
957 As the overall size of the PDF document increases,
958 it may become convenient to divide it into smaller,
959 individually formatted PostScript\*(rg components,
960 which are then assembled, in the appropriate order,
961 to create a composite PDF document.
962 While this strategy may simplify the overall process of creating and
963 editing larger documents, it does introduce a problem in creating
964 an overall document outline,
965 since each individual PostScript\*(rg component will be assigned
966 duplicated sequences of \(lqbookmark\(rq names,
967 with each name ultimately referring to multiple locations in the composite document.
968 To avoid such reference naming conflicts, the
970 macro allows the user to specify a \(lqtag\(rq,
971 which is appended to the automatically generated \(lqbookmark\(rq name;
972 this may be used as a discriminating mark, to distinguish otherwise
973 similarly named destinations, in different sections of the composite document.
975 To create a \(lqtagged\(rq document outline,
976 the syntax for invocation of the
978 macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
980 the nesting level argument, i.e.
987 .I "descriptive text ..."
991 argument may be composed of any characters of the user's choice;
992 however, its initial character
994 be any decimal digit, and ideally it should be kept short
995 \(em one or two characters at most.
997 By employing a different tag in each section,
998 the user can ensure that \(lqbookmark\(rq names remain unique,
999 throughout all the sections of a composite document.
1000 For example, when using the
1002 macro package, which adds
1004 capabilities to the standard
1008 the table of contents is collected into a separate PostScript\*(rg section
1009 from the main body of the document.
1010 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
1011 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
1013 macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
1018 .CW ".pdfhref O -T T 1 \e\e*[TOC]"
1020 to tag the associated outline destination name with the single character suffix,
1022 Alternatively, as in the case of the basic outline,
1023 .XR basic-outline ), (
1024 this may equally well be specified as
1026 .CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1028 .XN Delegation of the Outline Definition
1030 Since the most common use of a document outline
1031 is to provide a quick method of navigating through a document,
1032 using active \(lqhypertext\(rq links to chapter and section headings,
1033 it may be convenient to delegate the responsibility of creating the outline
1034 to a higher level macro, which is itself used to
1035 define and format the section headings.
1036 This approach has been adopted in the
1038 package, to be described later,
1041 When such an approach is adopted,
1042 the user will rarely, if ever, invoke the
1044 macro directly, to create a document outline.
1045 For example, the structure and content of the outline for this document
1046 has been exclusively defined, using a combination of the
1050 package, to establish the structure, and the
1054 to define the content.
1056 the responsibility for invoking the
1058 macro, to create the document outline,
1063 .XN -N pdfhref -- Adding Reference Marks and Links
1066 .ds SECREF.BEGIN Section
1067 .pdfhref L -D add-outline
1071 macro may be used to create a PDF document outline.
1072 While this is undoubtedly a powerful capability,
1073 it is by no means the only trick in the repertoire of this versatile macro.
1077 which is a contraction of \(lqPDF HyperText Reference\(rq,
1078 indicates that the general purpose of this macro is to define
1080 type of dynamic reference mark, within a PDF document.
1081 Its generalised usage syntax takes the form
1086 .I "-options ...\&" ] [
1088 .I "descriptive text ...\&" ] [
1092 represents a required single character argument,
1093 which defines the specific reference operation to be performed,
1094 and may be selected from:\(en
1097 Add an entry to the document outline.
1098 This operation has been described earlier,
1099 .XR add-outline ). (
1101 Place a \(lqnamed destination\(rq reference mark at the current output position,
1102 in the current PDF document,
1105 Specify the content of a PDF document reference dictionary entry;
1106 typically, such entries are generated automatically,
1107 by transformation of the intermediate output resulting from the use of
1109 .CWB M \& \& \(rq, \(lq
1111 .CWB -X \& \& \(rq \(lq
1114 however, it is also possible to specify such entries manually,
1115 .XR user-format ). (
1117 Insert an active link to a named destination,
1119 at the current output position in the current PDF document,
1120 such that when the reader clicks on the link text,
1121 the document view changes to show the location of the named destination.
1123 Insert an active link to a \(lqweb\(rq resource,
1124 .XR add-weblink ), (
1125 at the current output position in the current PDF document.
1126 This is effectively the same as using the
1127 .CWB L \& \& \(rq \(lq
1128 operator to establish a link to a named destination in another PDF document,
1129 .XR link-extern ), (
1130 except that in this case, the destination is specified by a
1131 \(lquniform resource identifier\(rq, or
1133 this may represent any Internet or local resource
1134 which can be specified in this manner.
1136 Specify a user defined macro, to be called by
1138 when formatting the text in the active region of a link,
1141 Define the absolute position on the physical PDF output page,
1142 where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
1143 Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
1144 for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
1145 specified directly by the user;
1148 .CWB Z \& \& \(rq \(lq
1149 specifications are inserted automatically into the document reference map
1150 during the PDF document formatting process,
1153 Initialise support for
1158 implementation provides only one such feature which requires initialisation
1159 \(em a helper macro which must be attached to a user supplied page trap handler,
1160 in order to support mapping of reference \(lqhot\(hyspots\(rq
1161 which extend through a page transition;
1165 .XN Optional Features of the \F[C]pdfhref\F[] Macro
1167 The behaviour of a number of the
1169 macro operations can be modified,
1171 .EM "option specifiers" \(rq \(lq
1172 after the operation specifying argument,
1175 any other arguments normally associated with the operation.
1178 cases, an option is specified by an
1179 .EM "option flag" \(rq, \(lq
1180 comprising an initial hyphen,
1181 followed by one or two option identifying characters.
1187 for these options, the argument
1189 be specified, and it
1191 be separated from the preceding option flag by one or more
1196 It may be noted that this paradigm for specifying options
1197 is reminiscent of most
1200 shells; however, in the case of the
1202 macro, omission of the space separating an option flag from its argument is
1208 general purpose options supported by the
1210 macro is given below.
1211 Note that not all options are supported for all
1213 operations; the operations affected by each option are noted in the list.
1216 operations, if an unsupported option is specified,
1217 it will be silently ignored; however, this behaviour should
1220 The general purpose options, supported by the
1224 .IP \*[= -N\0 name > <]
1227 associated with a PDF reference destination
1228 to be defined independently from the following text,
1229 which describes the reference.
1230 This option affects only the
1231 .CWB M \& \& \(rq \(lq
1237 Also used exclusively with the
1238 .CWB M \& \& \(rq \(lq
1241 option causes any specified
1242 .CWI descriptive \& \& \~\c
1248 in the body text of the document,
1249 at the point where the reference mark is defined;
1253 .CWI descriptive \& \& \~\c
1257 at points where links to the reference mark are placed,
1258 and where the standard reference display format,
1261 .IP \*[= -D\0 dest > <]
1264 or the destination name associated with a PDF active link,
1265 independently of the following text,
1266 which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1267 This option affects the behaviour of the
1270 .CWB L \& \& \(rq \(lq
1272 .CWB W \& \& \(rq \(lq
1276 .CWB L \& \& \(rq \(lq
1279 argument must specify a PDF \(lqnamed destination\(rq,
1283 .CWB M \& \& \(rq \(lq
1287 .CWB W \& \& \(rq \(lq
1290 must specify a link destination in the form of a
1291 \(lquniform resource identifier\(rq, or
1293 .XR add-weblink ). (
1294 .IP \*[= -F\0 file > <]
1296 .CWB L \& \& \(rq \(lq
1300 specifies an external PDF file in which the named destination
1301 for the link reference is defined.
1304 be specified with the
1305 .CWB L \& \& \(rq \(lq
1307 to create a link to a destination in a different PDF document;
1309 .CWB L \& \& \(rq \(lq
1312 this option, the link destination is assumed to be defined
1313 within the same document.
1314 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1316 .CWI \(dqprefix\(hytext\(dq > <
1317 to be attached to the
1319 of the text describing an active PDF document link,
1320 with no intervening space, but without itself being included in the
1321 active area of the link \(lqhot\(hyspot\(rq;
1322 it is effective with the
1323 .CWB L \& \& \(rq \(lq
1325 .CWB W \& \& \(rq \(lq
1329 Typically, this option would be used to insert punctuation before
1330 the link \(lqhot\(hyspot\(rq.
1331 Thus, there is little reason for the inclusion of spaces in
1332 .CWI \(dqprefix\(hytext\(dq > < ;
1333 however, if such space is required, then the enclosing double quotes
1335 be specified, as indicated.
1336 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1338 .CWI \(dqaffixed\(hytext\(dq > <
1339 to be attached to the
1341 of the text describing an active PDF document link,
1342 with no intervening space, but without itself being included in the
1343 active area of the link \(lqhot\(hyspot\(rq;
1344 it is effective with the
1345 .CWB L \& \& \(rq \(lq
1347 .CWB W \& \& \(rq \(lq
1351 Typically, this option would be used to insert punctuation after
1352 the link \(lqhot\(hyspot\(rq.
1353 Thus, there is little reason for the inclusion of spaces in
1354 .CWI \(dqaffixed\(hytext\(dq > < ;
1355 however, if such space is required, then the enclosing double quotes
1357 be specified, as indicated.
1358 .IP \*[= -T\0 tag > <]
1359 When specified with the
1360 .CWB O \& \& \(rq \(lq
1363 is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1366 to distinguish between the series of \(lqbookmark\(rq names generated in
1367 individual passes of the
1369 formatter, when the final PDF document is to be assembled
1370 from a number of separately formatted components;
1371 .XR multipart-outline ). (
1375 option is used with either the
1376 .CWB M \& \& \(rq \(lq
1377 operator, or with the
1378 .CWB L \& \& \(rq \(lq
1382 .CWB M \& \& \(rq \(lq
1385 it ensures that a cross reference record for the marked destination
1386 will be included in the document reference map,
1390 .CWB L \& \& \(rq \(lq
1393 it causes the reference to be displayed in the standard cross reference format,
1395 but substituting the
1396 .CWI descriptive \& \& \~\c
1402 for the description specified in the document reference map.
1404 Marks the end of the option specifiers.
1405 This may be used with all
1407 operations which accept options, to prevent
1409 from interpreting any following arguments as option specifiers,
1410 even if they would otherwise be interpreted as such.
1411 It is also useful when the argument list to
1413 contains special characters \(em any special character,
1414 which is not valid in a
1416 macro name, will cause a parsing error, if
1418 attempts to match it as a possible option flag;
1421 flag prevents this, so suppressing the
1423 warning message, which would otherwise ensue.
1425 Using this flag after
1427 sequences of macro options is recommended,
1428 even when it is not strictly necessary,
1429 if only for the entirely cosmetic benefit of visually separating
1430 the main argument list from the sequence of preceding options.
1435 options listed above, a supplementary set of two character options are defined.
1436 These supplementary options, listed below, are intended for use with the
1437 .CWB L \& \& \(rq \(lq
1438 operator, in conjunction with the
1441 option, to specify alternate file names,
1442 in formats compatible with the file naming conventions
1443 of alternate operating systems;
1444 they will be silently ignored, if used in any other context.
1446 The supported alternate file name options,
1447 which are ignored if the
1450 option is not specified, are:\(en
1452 .IP \*[= -DF\0 dos\(hyfile > <]
1453 Specifies the name of the file in which a link destination is defined,
1454 using the file naming semantics of the
1457 When the PDF document is read on a machine
1458 where the operating system uses the
1461 .CWI dos\(hyfile > <
1462 is used as the name of the file containing the reference destination,
1465 argument specified with the
1468 .IP \*[= -MF\0 mac\(hyfile > <]
1469 Specifies the name of the file in which a link destination is defined,
1470 using the file naming semantics of the
1474 When the PDF document is read on a machine
1475 where the operating system uses the
1478 .CWI mac\(hyfile > <
1479 is used as the name of the file containing the reference destination,
1482 argument specified with the
1485 .IP \*[= -UF\0 unix\(hyfile > <]
1486 Specifies the name of the file in which a link destination is defined,
1487 using the file naming semantics of the
1490 When the PDF document is read on a machine
1491 where the operating system uses
1493 file naming semantics, then
1494 .CWI unix\(hyfile > <
1495 is used as the name of the file containing the reference destination,
1498 argument specified with the
1501 .IP \*[= -WF\0 win\(hyfile > <]
1502 Specifies the name of the file in which a link destination is defined,
1503 using the file naming semantics of the
1504 .CW MS\(hyWindows \*(rg
1505 32\(hybit operating system.
1506 When the PDF document is read on a machine
1507 where the operating system uses any of the
1508 .CW MS\(hyWindows \*(rg
1509 file systems, with long file name support, then
1510 .CWI win\(hyfile > <
1511 is used as the name of the file containing the reference destination,
1514 argument specified with the
1519 .XN -N mark-dest -- Marking a Reference Destination
1523 macro may be used to create active links to any Internet resource,
1526 or to any \(lqnamed destination\(rq,
1527 either within the same document, or in another PDF document.
1528 Although the PDF specification allows link destinations to be defined
1529 in terms of a page number, and an associated view specification,
1530 this style of reference is not currently supported by the
1532 macro, because it is not possible to adequately bind the specification
1533 for the destination with the intended reference context.
1535 References to Internet resources are interpreted in accordance with the
1537 standard for defining a
1539 hence the only prerequisite, for creating a link to any Internet resource,
1542 be properly specified, when declaring the reference;
1543 .XR add-weblink ). (
1544 In the case of references to \(lqnamed destinations\(rq in PDF documents,
1545 however, it is necessary to provide a mechanism for creating such
1546 \(lqnamed destinations\(rq.
1547 This may be accomplished, by invoking the
1557 .I "descriptive text ...\&" ] [
1559 This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1563 option is not specified, by the first word of
1564 .CWI descriptive \& \& \~\c
1566 (note that this imposes the restriction that,
1569 option is omitted, then
1572 .CWI descriptive \& \& \~\c
1576 Additionally, a reference view will be automatically defined,
1577 and associated with the reference mark,
1578 .XR pdfhref-view ), (
1580 .\" .CWI descriptive
1582 .\" is specified, or the
1585 option is specified, and no document cross reference map has been imported,
1587 then a cross reference mapping record,
1589 will be written to the
1592 this may be captured, and subsequently used to generate a cross reference map
1596 When a \(lqnamed destination\(rq reference mark is created, using the
1599 .CWB M \& \& \(rq \(lq
1600 operator, there is normally no visible effect in the formatted document; any
1601 .CWI descriptive \& \& \~\c
1603 which is specified will simply be stored in the cross reference map,
1604 for use when a link to the reference mark is created.
1605 This default behaviour may be changed, by specifying the
1607 option, which causes any specified
1608 .CWI descriptive \& \& \~\c
1610 to be \(lqechoed\(rq in the document text,
1611 at the point where the reference mark is placed,
1612 in addition to its inclusion in the cross reference map.
1614 .XN -N export-map -- Mapping a Destination for Cross Referencing
1616 Effective cross referencing of
1618 document formatted by
1620 requires multiple pass formatting.
1621 Details of how this multiple pass formatting may be accomplished,
1622 when working with the
1624 macros, will be discussed later,
1626 at this stage, the discussion will be restricted to the initial preparation,
1627 which is required at the time when the cross reference destinations are defined.
1629 The first stage, in the process of cross referencing a document,
1630 is the generation of a cross reference map.
1631 Again, the details of
1633 the cross reference map is generated will be discussed in
1634 .pdfhref F SECREF L -D do-xref -A ;
1636 however, it is important to recognise that
1638 content is included in the cross reference map is established
1639 when the reference destination is defined \(em it is derived
1640 from the reference data exported on the
1644 macro, when it is invoked with the
1645 .CWB M \& \& \(rq \(lq
1646 operator, and is controlled by whatever definition of the string
1648 is in effect, when the
1652 The initial default setting of
1656 .CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1658 which ensures that the cross reference map will contain
1659 at least a page number reference, supplemented by any
1660 .CWI descriptive \& \& \~\c
1662 which is specified for the reference mark, as defined by the
1665 .CWB M \& \& \(rq \(lq
1666 operator; this may be redefined by the user,
1667 to export additional cross reference information,
1668 or to modify the default format for cross reference links,
1671 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
1673 In the same manner as each document outline reference, defined by the
1676 .CWB O \& \& \(rq \(lq
1678 .XR add-outline ), (
1679 has a specific document view associated with it,
1680 each reference destination marked by
1683 .CWB M \& \& \(rq \(lq
1684 operator, requires an associated document view specification.
1686 The mechanism whereby a document view is associated with a reference mark
1687 is entirely analogous to that employed for outline references,
1688 .XR outline-view ), (
1691 string specification is used, in place of the
1692 .CW PDFBOOKMARK.VIEW
1694 Thus, the reference view is defined in terms of:\(en
1696 .IP \*[= PDFHREF.VIEW]
1698 establishing the position of the reference mark within the viewing window,
1699 and the magnification at which the document will be viewed,
1700 at the location of the marked reference destination;
1701 by default, it is defined by
1704 .CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
1707 which displays the reference destination at the top of the viewing window,
1708 with the magnification set to fit the page width to the width of the window.
1709 .IP \*[= PDFHREF.VIEW.LEADING]
1711 specifying additional spacing, to be placed between the top of the display
1712 window and the actual position at which the location of the reference
1713 destination appears within the window.
1714 This register is shared with the view specification for outline references,
1715 and thus has the same default initial setting,
1718 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
1721 as in the case of outline reference views.
1724 .CW PDFHREF.VIEW.LEADING
1725 does not represent true typographic \(lqleading\(rq,
1726 since any preceding text, set in the specified display space,
1727 will be visible at the top of the viewing window,
1728 when the reference is selected.
1731 Just as the view associated with outline references may be changed,
1733 .CW PDFBOOKMARK.VIEW ,
1734 so the view associated with marked reference destinations may be changed,
1738 .CW PDFHREF.VIEW.LEADING ;
1739 such changes will become effective for all reference destinations marked
1741 these definitions are changed.
1742 (Notice that, since the specification of
1743 .CW PDFHREF.VIEW.LEADING
1744 is shared by both outline reference views and marked reference views,
1745 if it is changed, then the views for
1747 reference types are changed accordingly).
1749 It may again be noted, that the
1751 register is used in the definition of
1753 just as it is in the definition of
1754 .CW PDFBOOKMARK.VIEW ;
1756 .pdfhref F SECREF L -D outline-view
1758 relating to its use, and indeed to page position computations in general,
1759 apply equally to marked reference views and to outline reference views.
1761 .XN -N link-named -- Linking to a Marked Reference Destination
1763 Any named destination, such as those marked by the
1766 .CWB M \& \& \(rq \(lq
1767 operator, may be referred to from any point in
1769 PDF document, using an
1771 such active links are created by again using the
1773 macro, but in this case, with the
1774 .CWB L \& \& \(rq \(lq
1776 This operator provides support for two distinct cases,
1777 depending on whether the reference destination is defined in
1778 the same document as the link,
1779 .XR link-intern ), (
1780 or is defined as a named destination in a different PDF document,
1781 .XR link-extern ). (
1783 .XN -N link-intern -- References within a Single PDF Document
1785 The general syntactic form for invoking the
1788 when creating a link to a named destination within the same PDF document is
1796 .BI prefix-text >] <
1798 .BI affixed-text >] <
1804 .I "descriptive text ...\&" ] [
1808 specifies the name of the link destination,
1809 as specified using the
1811 .CWB M \& \& \(rq \(lq
1812 operation; (it may be defined either earlier in the document,
1813 to create a backward reference, or later, to create a forward reference).
1815 .\" Here's a example of how to add an iconic annotation.
1817 .\".pdfnote -T "Internal Cross References" \
1818 .\" This description is rather terse, and could benefit from \
1819 .\" the inclusion of an example.
1822 .CWI descriptive \& \& \~\c
1824 arguments are specified, then they will be inserted into the
1826 output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
1828 this will be printed in the link colour specified by the string,
1829 .CW PDFHREF.TEXT.COLOUR ,
1830 which is described in
1831 .XR-NO-PREFIX set-colour .
1834 option is also specified, then the
1835 .CWI descriptive \& \& \~\c
1837 will be augmented, by prefacing it with page and section number indicators,
1838 in accordance with the reference formatting rules which are in effect,
1840 such indicators will be included within the active link region,
1841 and will also be printed in the link colour.
1847 .CWBI dest\(hyname > <
1851 .CWI descriptive \& \& \~\c
1854 .EM "but not both" ,
1858 .CWBI dest\(hyname > <
1859 option is omitted, then the first word of
1860 .CWI descriptive \& \& \~\c
1862 i.e.\~all text up to but not including the first space,
1863 will be interpreted as the
1864 .CWBI dest\(hyname > <
1865 for the link; this text will also appear in the running text of the document,
1866 within the active region of the link.
1867 Alternatively, if the
1869 .CWBI dest\(hyname > <
1873 .CWI descriptive \& \& \~\c
1876 then the running text which defines the reference,
1877 and its active region,
1878 will be derived from the reference description which is specified
1879 when the named destination is marked,
1881 and will be formatted according to the reference formatting rules
1882 which are in effect, when the reference is placed,
1884 in this case, it is not necessary to specify the
1886 option to activate automatic formatting of the reference \(em it is implied,
1887 by the omission of all
1888 .CWI descriptive \& \& \~\c
1894 .CWBI prefix\(hytext > <
1897 .CWBI affixed\(hytext > <
1898 options may be used to specify additional text
1899 which will be placed before and after the linked text respectively,
1900 with no intervening space.
1901 Such prefixed and affixed text will be printed in the normal text colour,
1902 and will not be included within the active region of the link.
1903 This feature is mostly useful for creating parenthetical references,
1904 or for placing punctuation adjacent to,
1905 but not included within,
1906 the text which defines the active region of the link.
1908 The operation of the
1910 macro, when used with its
1911 .CWB L \& \& \(rq \(lq
1912 operator to place a link to a named PDF destination,
1913 may best be illustrated by an example.
1914 However, since the appearance of the link will be influenced by
1915 factors established when the named destination is marked,
1917 and also by the formatting rules in effect when the link is placed,
1918 the presentation of a suitable exanple will be deferred,
1919 until the formatting mechanism has been explained,
1922 .XN -N link-extern -- References to Destinations in Other PDF Documents
1927 .CWB L \& \& \(rq \(lq
1928 operator is not restricted to creating reference links
1929 within a single PDF document.
1930 When the link destination is defined in a different document,
1931 then the syntactic form for invoking
1933 is modified, by the addition of options to specify the
1934 name and location of the PDF file in which the destination is defined.
1937 syntactic form becomes
1961 .BI prefix-text >] <
1963 .BI affixed-text >] <
1969 .I "descriptive text ...\&" ] [
1976 purposes: it both indicates to the
1978 macro that the specified reference destination
1979 is defined in an external PDF file,
1980 and it also specifies the normal path name,
1981 which is to be used to locate this file,
1982 when a user selects the reference.
1989 be specified when referring to a destination in an external PDF file,
1992 .CWBI dos\(hyfile > < ,
1994 .CWBI mac\(hyfile > < ,
1996 .CWBI unix\(hyfile > <
1999 .CWBI win\(hyfile > <
2000 options may be used to specify the location of the file
2001 containing the reference destination,
2002 in a variety of operating system dependent formats.
2003 These options assign their arguments to the
2009 keys of the generated
2011 respectively; thus when any of these options are specified,
2012 .EM "in addition to"
2016 option, and the document is read on the appropriate operating systems,
2017 then the path names specified by
2018 .CWBI dos\(hyfile > < ,
2019 .CWBI mac\(hyfile > < ,
2020 .CWBI unix\(hyfile > <
2022 .CWBI win\(hyfile > <
2025 of the path name specified by
2028 .CW MS\(hyDOS \*(rg,
2030 .CW Macintosh \*(rg,
2033 .CW MS\(hyWindows \*(rg
2034 operating systems, respectively; see the
2036 for further details.
2038 Other than the use of these additional options,
2039 which specify that the reference destination is in an external PDF file,
2040 the behaviour of the
2042 .CWB L \& \& \(rq \(lq
2046 option, remains identical to its behaviour
2049 .XR link-intern ), (
2050 with respect to the interpretation of other options,
2052 .CWI descriptive \& \& \~\c
2054 arguments, and the formatting of the displayed reference.
2056 Once again, since the appearance of the reference is determined by
2057 factors specified in the document reference map,
2058 and also by the formatting rules in effect when the reference is placed,
2059 the presentation of an example of the placing of
2060 a reference to an external destination will be deferred,
2061 until the formatting mechanism has been explained,
2064 .XN -N add-weblink -- Linking to Internet Resources
2066 In addition to supporting the creation of cross references
2067 to named destinations in PDF documents, the
2069 macro also has the capability to create active links to Internet resources,
2072 resource which may be specified by a Uniform Resource Identifier,
2073 (which is usually abbreviated to the acronym \(lqURI\(rq,
2074 and sometimes also referred to as a Uniform Resource Locator,
2077 Since the mechanism for creating a link to a URI differs somewhat
2078 from that for creating PDF references, the
2080 macro is invoked with the
2081 .CWB W \& \& \(rq \(lq
2082 (for \(lqweb\(hylink\(rq) operator, rather than the
2083 .CWB L \& \& \(rq \(lq
2084 operator; nevertheless, the invocation syntax is similar, having the form
2092 .BI prefix-text >] <
2094 .BI affixed-text >] <
2099 .I "descriptive text ...\&"
2104 modifier specifies the address for the target Internet resource,
2106 .EM "Uniform Resource Identifier"
2110 argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
2113 .CWBI prefix\(hytext > <
2116 .CWBI affixed\(hytext > <
2117 options have the same effect as in the case of local document links,
2118 .XR link-intern ). (
2120 Notice that it is not mandatory to include the
2123 in the link specification; if it
2125 specified, then it is not necessary for the URI to appear,
2126 in the running text of the document \(em the
2129 argument exactly defines the text
2130 which will appear within the \(lqhot\(hyspot\(rq region,
2131 and this need not include the URI.
2135 specification is omitted, then the
2142 representation of the URI, which
2144 therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
2145 For example, we could introduce a reference to
2146 .pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2147 in which the actual URI is concealed, by using mark up such as:\(en
2150 For example, we could introduce a reference to
2151 \&.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2152 in which the actual URI is concealed,
2155 to refer the reader to the groff web site,
2156 making it obvious that the appropriate URI is
2157 .pdfhref W -A , \*[GROFF-WEBSITE]
2158 the requisite mark up might be:\(en
2161 to refer the reader to the groff web site,
2162 making it obvious that the appropriate URI is
2163 \&.pdfhref W -A , \*[GROFF-WEBSITE]
2164 the requisite mark up might be:\e(en
2167 .XN -N set-format -- Establishing a Format for References
2169 There are two principal aspects to be addressed,
2170 when defining the format to be used when displaying references.
2171 Firstly, it is desirable to provide a visual cue,
2172 to indicate that the text describing the reference is imbued
2173 with special properties \(em it is dynamically linked to the reference
2174 destination \(em and secondly, the textual content should
2175 describe where the link leads, and ideally,
2176 it should also describe the content of the reference destination.
2179 that a text region defines a dynamically linked reference,
2180 is most commonly provided by printing the text within the active
2181 region in a distinctive colour.
2182 This technique will be employed automatically by the
2186 \(em unless the user specifically chooses to adopt, and implement,
2187 some alternative strategy.
2189 .XN -N set-colour -- Using Colour to Demarcate Link Regions
2191 Typically, when a PDF document contains
2193 references to other locations, either within the same document,
2194 or even in other documents, or on the World Wide Web,
2195 it is usually desirable to make the regions
2196 where these active links are placed stand out from the surrounding text.
2198 .XN -N user-format -- Specifying Reference Text Explicitly
2200 .XN -N auto-format -- Using Automatically Formatted Reference Text
2202 .XN -N custom-format -- Customising Automatically Formatted Reference Text
2204 It is incumbent on the user,
2205 if employing automatic formatting of the displayed reference,
2207 to ensure that an appropriate reference definition
2208 is created for the reference destination,
2209 and is included in the reference map for the document
2210 in which the reference will appear;
2211 thus, it may be easiest to
2213 use manual formatting for external references.
2215 .XN Problematic Links
2217 Irrespective of whether a
2219 reference is placed using the
2220 .CWB L \& \& \(rq \(lq
2222 .CWB W \& \& \(rq \(lq
2223 operator, there may be occasions when the resulting link
2224 does function as expected.
2225 A number of scenarios, which are known to be troublesome,
2226 are described below.
2228 .XN -N page-trap -- Links with a Page Transition in the Active Region
2230 When a link is placed near the bottom of a page,
2231 it is possible that its active region, or \(lqhot\(hyspot\(rq,
2232 may extend on to the next page.
2233 In this situation, a page trap macro is required
2234 to intercept the page transition, and to restart the mapping of
2235 the \(lqhot\(hyspot\(rq boundary on the new page.
2239 macro package includes a suitable page trap macro, to satisfy this requirement.
2240 However, to avoid pre\(hyempting any other requirement the user may have for
2241 a page transition trap, this is
2243 installed as an active page trap,
2244 unless explicitly requested by the user.
2246 To enable proper handling of page transitions,
2247 which occur within the active regions of reference links,
2248 the user should:\(en
2252 Define a page transition macro, to provide whatever features may be required,
2253 when a page transition occurs \(em e.g.\& printing footnotes,
2254 adding page footers and headers, etc.
2255 This macro should end by setting the output position at the correct
2256 vertical page offset, where the printing of running text is to restart,
2257 following the page transition.
2259 Plant a trap to invoke this macro, at the appropriate vertical position
2260 marking the end of normal running text on each page.
2265 hook into this page transition trap, by invoking
2273 .CWBI macro-name > <
2274 is the name of the user supplied page trap macro,
2277 will correctly restart mapping of active link regions,
2278 at the start of each new page.
2283 It may be observed that this initialisation of the
2285 page transition hook is, typically, required only once
2287 document formatting begins.
2288 Users of document formatting macro packages may reasonably expect that
2289 this initialisation should be performed by the macro package itself.
2290 Thus, writers of such macro packages which include
2292 bindings, should provide appropriate initialisation,
2293 so relieving the end user of this responsibility.
2294 The following example, abstracted from the sample
2298 illustrates how this may be accomplished:\(en
2301 \&.\e" groff "ms" provides the "pg@bottom" macro, which has already
2302 \&.\e" been installed as a page transition trap. To ensure proper
2303 \&.\e" mapping of "pdfhref" links which overflow the bottom of any
2304 \&.\e" page, we need to install the "pdfhref" page transition hook,
2305 \&.\e" as an addendum to this macro.
2307 \&.pdfhref I -PT pg@bottom
2310 .XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
2312 .XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts
2314 It has been noted previously, that the
2324 macro, when used to create a document outline,
2325 .XR add-outline ), (
2326 do not immediately write their
2328 output to the PostScript\*(rg data stream;
2329 instead, they cache their output, in a
2331 diversion, in the case of the
2335 macros, or in an ordered collection of strings and numeric registers,
2336 in the case of the document outline,
2337 until a more appropriate time for copying it out.
2342 \(lqmeta\(hydata\(rq,
2343 this \(lqmore appropriate time\(rq is explicitly chosen by the user;
2344 in the case of document outline data,
2346 cached data may be implicitly written out as the document outline is compiled,
2349 be some remaining data, which must be explicitly flushed out, before the
2351 formatting process is allowed to complete.
2353 To allow the user to choose when cached
2355 data is to be flushed to the output stream, the
2357 macro package provides the
2359 macro, (to synchronise the cache and output states).
2360 In its simplest form, it is invoked without arguments, i.e.
2365 This form of invocation ensures that
2367 the \(lqmeta\(hydata cache\(rq, containing
2373 the \(lqoutline cache\(rq,
2374 containing any previously uncommitted document outline data,
2375 are flushed; ideally, this should be included in a
2377 \(lqend macro\(rq, to ensure that
2379 caches are flushed, before
2384 it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
2385 without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
2386 at a user specified time, prior to reaching the end of the document.
2387 This may be accomplished, by invoking the
2389 macro with an argument, i.e.
2394 to flush only the \(lqmeta\(hydata cache\(rq, or
2399 to flush only the \(lqoutline cache\(rq.
2401 The \(lqmeta\(hydata cache\(rq can normally be safely flushed
2402 in this manner, at any time
2404 output of the first page has started;
2405 (it may cause formatting problems,
2406 most notably the appearance of unwanted white space, if flushed earlier,
2407 or indeed, if flushed immediately after a page transition,
2408 but before the output of the content on the new page has commenced).
2409 Caution is required, however, when explicitly flushing the
2410 \(lqoutline cache\(rq, since if the outline is to be
2411 subsequently extended, then the first outline entry after flushing
2413 be specified at level 1.
2414 Nevertheless, such explicit flushing may occasionally be necessary;
2422 .CW ".pdfsync\ O" \(rq \(lq
2423 to ensure that the outline for the \(lqbody\(rq section of the document
2426 it commences the formatting of the table of contents section.
2429 .XN -N pdf-layout -- PDF Document Layout
2433 macros described in the preceding section,
2434 .XR pdf-features ), (
2435 provide no inherent document formatting capability of their own.
2437 they may be used in conjunction with any other
2439 macro package of the user's choice,
2440 to add such capability.
2442 In preparing this document, the standard
2444 macro package, supplied as a component of the GNU Troff distribution,
2446 To facilitate the use of the
2451 a binding macro package,
2454 The use of this binding macro package is described in the following section,
2456 it may also serve as an example to users of other standard
2461 macros may be employed with their chosen primary macro package.
2463 .XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
2465 The use of the binding macro package,
2467 allows for the use of the
2469 macros in conjunction with the
2479 .I "-options ...\&" ] [
2482 (Or use the PDF post-processor to avoid using ghostscript,
2490 input files may be marked up using any of the standard
2492 macros to specify document formatting,
2493 while PDF features may be added,
2496 macros described previously,
2497 .XR pdf-features ). (
2500 defines a number of convenient extensions to the
2502 macro set, to better accomodate the use of PDF features within the
2504 formatting framework,
2505 and to address a number of
2507 document layout issues,
2508 which require special handling when producing PDF documents.
2509 These additional macros,
2510 and the issues they are intended to address,
2511 are described below.
2513 .XN \F[C]ms\F[] Section Headings in PDF Documents
2521 macros, to specify section headings.
2523 there is no standard mechanism for generating a
2524 table of contents entry based on the text of the section heading;
2525 neither is there any recognised standard method for establishing a
2526 cross reference link to the section.
2536 to be used in conjunction with the
2540 .XN -N xn-macro -- The \F[C]XN\F[] Macro
2542 .XN The PDF Publishing Process
2544 .XN -N do-xref -- Resolving Cross References
2546 .XN -N create-map -- Creating a Document Reference Map
2548 .XN -N import-map -- Deploying a Document Reference Map
2550 .\" Local Variables:
2553 .\" vim: filetype=groff:
projects / platform / upstream / groff.git / blob