1 .\" vim: ft=groff -*- nroff -*-
5 File position: <groff-source>/contrib/pdfmark/pdfmark.ms
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2004-2014 Free Software Foundation, Inc.
10 written by Keith Marshall <keith.d.marshall@ntlworld.com>
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with no
15 Front-Cover Texts, no Back-Cover Texts, and the following Invariant
18 a) This "Legal Matters" section, extending from the start of
19 the document, to the end of the enclosing ".ig" section.
21 b) The two lines below starting with `.AU' and `.AI'.
23 A copy of the Free Documentation License is included as a file called
24 FDL in the main directory of the groff source package.
28 Portable Document Format
29 Publishing with GNU Troff
31 .AI <keith.d.marshall@ntlworld.com>
34 .\" Specify the Internet address for the groff web site.
35 .\" Currently, there are two available addresses; a copy is maintained at ...
37 .ds GROFF-WEBSITE http://www.gnu.org/software/groff
39 .\" ... but the official home site is at ...
41 .ds GROFF-WEBSITE http://groff.ffii.org
43 .\" Set the PDF default document view attribute, to ensure that the document
44 .\" outline is visible, each time the document is opened in Acrobat Reader.
46 .pdfview /PageMode /UseOutlines
48 .\" Initialise the outline view to show only three heading levels,
49 .\" with additional subordinate level headings folded.
51 .nr PDFOUTLINE.FOLDLEVEL 3
53 .\" Add document identification meta-data
55 .pdfinfo /Title Portable Document Format Publishing with GNU Troff
56 .pdfinfo /Author Keith Marshall
57 .pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU Troff
58 .pdfinfo /Keywords groff troff PDF pdfmark
60 .\" Set the default cross reference format to indicate section numbers,
61 .\" rather than page numbers, when we insert a reference pointer.
63 .ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
65 .\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
75 .\" to insert a Registered Trade Mark symbol as a superscript.
79 .\" Establish the page layout.
88 .\" Generate headers in larger point sizes, for NH levels < 4,
89 .\" with point size increasing by 1.5p, for each lesser NH level.
95 .\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
99 \\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
102 \\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
105 \\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
107 .ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
110 .\" When we use numbered section headings, we might like to automatically
111 .\" insert a table of contents entry, using the text of the heading itself.
112 .\" The "ms" macros don't provide any standard mechanism for doing this,
113 .\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
115 .\" Here's a simple example of how we might use it. In this case, the word
116 .\" "Introduction" will appear both in the body of the document, as the text
117 .\" of the heading, and it will be added to the table of contents, which is
118 .\" subsequently "printed" using the "TC" macro; in both locations, it will
119 .\" be prefixed by the section number.
121 .\" As an additional side effect, any use of "XN" will cause the table of
122 .\" contents entry to be automatically reproduced, with the exception of its
123 .\" page number reference, as a PDF document outline entry. Thus, the use
124 .\" of "XN" to specify numbered section headings results in the automatic
125 .\" creation of a numbered PDF document outline. This automatic creation
126 .\" of the outline is completely transparent, and will occur regardless
127 .\" of whether the "TC" macro is subsequently invoked, or not.
131 .\" If using an old s.tmac, without the SN-NO-DOT extension,
132 .\" make sure we get SOMETHING in section number references.
134 .if !dSN-NO-DOT .als SN-NO-DOT SN
136 It might appear that it is a fairly simple matter to
137 produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
138 commonly known as PDF, using
139 .CW groff ) GNU\~Troff\~(
140 as the document formatter.
143 default output format is the native Adobe\*(rg\~PostScript\*(rg format,
144 which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
145 or GhostScript, expect as their input format.
146 Thus, the PDF production process would seem to entail simply
147 formatting the document source with
149 to produce a PostScript\*(rg version of the document,
150 which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
151 or GhostScript, to generate the final PDF document.
153 For many PDF production requirements,
154 the production cycle described above may be sufficient.
155 However, this is a limited PDF production method,
156 in which the resultant PDF document represents no more than
157 an on screen image of the printed form of the document, if
159 PostScript\*(rg output were printed directly.
161 The Portable Document Format provides a number of features,
162 which significantly enhance the experience of reading a document on screen,
163 but which are of little or no value to a document which is merely printed.
166 possible to exploit these PDF features, which are described in the Adobe\*(rg
169 .\" This is an example of a resource reference specified by URI ...
170 .\" We may need to refer often to the Adobe pdfmark Reference Manual,
171 .\" so we create the internet link definition using a macro, to make
174 .\" Note also, that we protect the description of the reference by
175 .\" preceding it with "--", to avoid "invalid character in name" type
176 .\" error messages from groff (caused by the use of "\~").
178 .pdfhref W -D http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/pdf_creation_apis_and_specs/pdfmarkReference.pdf \
179 -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
182 with some refinement of the simple PDF production method, provided
183 appropriate \(lqfeature implementing\(rq instructions can be embedded into
185 PostScript\*(rg rendering of the document.
186 This, of course, implies that the original document source, which
188 will process to generate the PostScript\*(rg description of the document,
189 must include appropriate markup to exploit the desired PDF features.
190 It is this preparation of the
192 document source to exploit a number of these features,
193 which provides the principal focus of this document.
195 The markup techniques to be described have been utilised in the production of
196 the PDF version of this document itself.
197 This has been formatted using
201 thus, usage examples may be found in the document source file,
203 to which comments have been added,
204 to help identify appropriate markup examples for implementing PDF features,
208 Selecting a default document view, which defines how the document will appear
209 when opened in the reader application; for example, when this document is
210 opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
211 in the document view pane, while a document outline should appear to the left,
212 in the \(lqBookmarks\(rq pane.
214 Adding document identification \(lqmeta\(hydata\(rq,
215 which can be accessed, in Acrobat\*(rg\~Reader,
216 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
218 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
219 pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
220 section of the document, simply by clicking on the associated heading
223 Embedding active links in the body of the document, such that readers may
224 quickly navigate to related material at another location within the same
225 document, or in another PDF document, or even to a related Internet resource,
226 specified by its URI.
228 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
229 points within the PDF document.
232 All of the techniques described have been tested on
234 GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
237 .pdfhref L -D footnote1 -- \**
240 Later versions should, and some earlier versions may, be equally suitable.
242 .pdfhref W \*[GROFF-WEBSITE]
243 for information and availability of the latest version.
249 .pdfhref L -D footnote2 -- \**
252 Again, other versions may be suitable.
254 .pdfhref W http://ghostscript.com
255 for information and availability.
257 Other tools employed, which should be readily available on
262 or GNU/Linux system, are
267 together with an appropriate text editor, for creating and marking up the
270 These additional utilities are not provided, as standard,
271 on the Microsoft\*(rg Windows\(tm platform,
272 but several third party implementations are available.
273 Some worth considering include the MKS\*(rg\~Toolkit,\**
275 A commercial offering; see
276 .pdfhref W http://mkssoftware.com/products/tk/default.asp
287 emulation environment and
291 toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
292 .pdfhref W http://cygwin.com
293 for information and download.
297 Another free, but minimal suite of common
301 tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
302 .pdfhref W -A ; http://www.mingw.org
305 include those tools listed above,
306 and is the package which was actually used when performing the Windows\(tm2000
307 platform tests referred to in the text.
309 This list is by no means exhaustive, and should in no way be construed as an
310 endorsement of any of these packages, nor to imply that other similar packages,
311 which may be available, are in any way inferior to them.
314 .\" We may wish a section heading to represent a named destination,
315 .\" so that we can create a linked reference to it, from some other
316 .\" part of the PDF document, (or even from another PDF document).
318 .\" Here we use the "-N" option of the "XN" macro, to create a named
319 .\" PDF link destination, at the location of the heading. Notice that
320 .\" we also use the "--" marker to separate the heading text from the
321 .\" preceding option specification; it is not strictly necessary in
322 .\" this case, but it does help to set off the heading text from the
323 .\" option specification.
325 .XN -N pdf-features -- Exploiting PDF Document Features
327 To establish a consistent framework for adding PDF features, a
332 Thus, to incorporate PDF features in a document,
333 the appropriate macro calls, as described below, may be placed in the
335 document source, which should then be processed with a
344 .I "file ..." \& "...] "
346 (Or use the PDF post-processor to avoid using ghostscript,
350 It may be noted that the
352 macros have no dependencies on, and no known conflicts with,
355 macro package; thus, users are free to use any other macro package,
356 of their choice, to format their documents, while also using the
358 macros to add PDF features.
360 .XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
362 All PDF features are implemented by embedding instances of the
364 operator, as described in the Adobe\*(rg
368 PostScript\*(rg output stream.
369 To facilitate the use of this operator, the
371 macro package defines the primitive
373 macro; it simply emits its argument list,
376 operator, in the PostScript\*(rg output stream.
378 .pdfhref M -N pdfmark-example
379 To illustrate the use of the
381 macro, the following is a much simplified example of how a bookmark
382 may be added to a PDF document outline
389 /Title (An Example of a Bookmark with Two Children) \e
390 /View [/FitH \en[PDFPAGE.Y]] \e
394 In general, users should rarely need to use the
397 In particular, the above example is too simple for general use; it
399 create a bookmark, but it does
401 address the issues of setting the proper value for the
403 key, nor of computing the
409 macro package includes a more robust mechanism for creating bookmarks,
411 .\" Here is an example of how a local reference may be planted,
412 .\" using the automatic formatting feature of the "pdfhref" macro.
414 .\" This is a forward reference to the named destination "add-outline",
415 .\" which is defined below, using the "XN" wrapper macro, from the
416 .\" "spdf.tmac" macro package. The automatically formatted reference
417 .\" will be enclosed in parentheses, as specified by the use of
418 .\" "-P" and "-A" options.
420 .pdfhref L -P ( -A ), -D add-outline
422 which addresses these issues automatically.
425 macro may be useful to users wishing to implement more advanced PDF features,
426 than those currently supported directly by the
430 .XN -N docview -- Selecting an Initial Document View
433 when a PDF document is opened,
434 the first page will be displayed,
435 at the default magnification set for the reader,
436 and outline and thumbnail views will be hidden.
437 When using a PDF reader,
438 such as Acrobat\*(rg\~Reader,
444 these default initial view settings may be overridden,
450 .CW ".pdfview /PageMode /UseOutlines"
452 will cause Acrobat\*(rg\~Reader to open the document outline view,
453 to the left of the normal page view,
456 .CW ".pdfview /PageMode /UseThumbs"
458 will open the thumbnail view instead.
462 examples, above, are mutually exclusive \(em it is not possible to have
464 outline and thumbnail views open simultaneously.
471 keys, to force the document to open at a page other than the first,
472 or to change the magnification at which the document is initially displayed;
475 for more information.
477 It should be noted that the view controlling meta\(hydata, defined by the
479 macro, is not written immediately to the PostScript\*(rg output stream,
480 but is stored in an internal meta\(hydata \(lqcache\(rq,
481 (simply implemented as a
484 This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
488 .\" Here is another example of how we may introduce a forward reference.
489 .\" This time we are using the shorter notation afforded by the "XR" macro
490 .\" provided by "spdf.tmac"; this example is equivalent to the native
491 .\" "pdfmark.tmac" form
492 .\" .pdfhref L -D pdfsync -P ( -A ).
497 .XN -N docinfo -- Adding Document Identification Meta-Data
501 class of meta\(hydata described above,
503 we may also wish to include document identification meta\(hydata,
504 which belongs to the PDF
508 To do this, we use the
511 As an example of how it is used,
512 the identification meta\(hydata attached to this document
513 was specified using a macro sequence similar to:\(en
516 \&.pdfinfo /Title PDF Document Publishing with GNU Troff
517 \&.pdfinfo /Author Keith Marshall
518 \&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff
519 \&.pdfinfo /Keywords groff troff PDF pdfmark
523 macro is repeated, once for each
525 record to be placed in the document.
526 In each case, the first argument is the name of the applicable
530 be named with an initial solidus character;
531 all additional arguments are collected together,
532 to define the value to be associated with the specified key.
534 As is the case with the
540 records specified with the
542 macro are not immediately written to the PostScript\*(rg output stream;
543 they are stored in the same meta\(hydata cache as
545 specifications, until this cache is explicitly flushed,
551 .XN -N add-outline -- Creating a Document Outline
553 A PDF document outline comprises a table of references,
554 to \(lqbookmarked\(rq locations within the document.
555 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
556 such as Adobe\*(rg Acrobat\*(rg Reader,
557 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
558 or \(lqBookmarks\(rq pane, to the left of the main document view.
559 Individual references in the outline view may then be selected,
560 by clicking with the mouse,
561 to jump directly to the associated marked location in the document view.
563 The document outline may be considered as a collection of \(lqhypertext\(rq
564 references to \(lqbookmarked\(rq locations within the document.
567 macro package provides a single generalised macro,
569 for creating and linking to \(lqhypertext\(rq reference marks.
570 This macro will be described more comprehensively in a later section,
572 the description here is restricted to its use for defining document outline entries.
574 .XN -N basic-outline -- A Basic Document Outline
576 In its most basic form, the document outline comprises a structured list of headings,
577 each associated with a marked location, or \(lqbookmark\(rq, in the document text,
578 and a specification for how that marked location should be displayed,
579 when this bookmark is selected.
581 To create a PDF bookmark, the
584 at the point in the document where the bookmark is to be placed,
590 .I "descriptive text ..."
592 in which the reference class
593 .CWB O \& \& \(rq \(lq
594 stipulates that this is an outline reference.
596 Alternatively, for those users who may prefer to think of a document outline
597 simply as a collection of bookmarks, the
599 macro is also provided \(em indeed,
601 invokes it, when processing the
602 .CWB O \& \& \(rq \(lq
603 reference class operator.
604 It may be invoked directly, in the form
609 .I "descriptive text ..."
611 Irrespective of which of the above macro forms is employed, the
613 argument is required.
614 It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
615 in the outline hierarchy, with one being the topmost level.
616 Its function may be considered analagous to the
618 of the document's section headings,
619 for example, as specified with the
623 macros to format the document.
625 All further arguments, following the
627 argument, are collected together, to specify the heading text which will appear
628 in the document's outline view.
629 Thus, the outline entry for this section of this document,
630 which has a level three heading,
631 might be specified as
634 \&.pdfhref O 3 \*(SN A Basic Document Outline
636 or, in the alternative form using the
641 \&.pdfbookmark 3 \*(SN A Basic Document Outline
643 .XN Hierarchical Structure in a Document Outline
645 When a document outline is created, using the
647 macro as described in
649 .\" Here is an example of how we can temporarily modify the format of
650 .\" a reference link, in this case to indicate only the section number
651 .\" of the link target, in the form "section #", (or, if we define
652 .\" "SECREF.BEGIN" before the call, its content followed by the
655 .\" We first define a macro, which will get the reference data from
656 .\" pdfhref, as arguments, and will return the formatted output, as we
657 .\" require it, the string "PDFHREF.TEXT".
661 . ie '\\$1'section' \{\
662 . if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
663 . ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
670 .\" We now tell "pdfhref" to use our formatting macro, in place of
671 .\" its builtin default formatter, before we specify the reference.
674 .pdfhref L -A , -D basic-outline
676 .\" At this point, we would normally revert the "pdfhref" formatter
677 .\" to use its default, built in macro. However, in this particular
678 .\" case, we want to use our custom format one more time, before we
679 .\" revert it, so we will omit the reversion step this time.
681 and any entry is added at a nesting level greater than one,
682 then a hierarchical structure is automatically defined for the outline.
683 However, as was noted in the simplified
684 .pdfhref L -D pdfmark-example -- example
686 .pdfhref L -A , -D pdfmark-operator
688 .\" And now, we revert to default "pdfhref" formatting behaviour,
689 .\" by completing the call we delayed above.
693 the data required by the
695 operator to create the outline entry may not be fully defined,
696 when the outline reference is defined in the
699 Specifically, when the outline entry is created, its
701 key must be assigned a value equal to the number of its subordinate entries,
702 at the next inner level of the outline hierarchy;
704 these subordinate entries will be defined
706 in the document source, and the appropriate
708 value will be unknown, when defining the parent entry.
710 To resolve this paradox, the
712 macro creates the outline entry in two distinct phases \(em
713 a destination marker is placed in the PostScript\*(rg output stream immediately,
714 when the outline reference is defined,
715 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
716 until its subordinate hierarchy has been fully defined;
717 it can then be inserted in the output stream, with its
719 value correctly assigned.
720 Effectively, to ensure integrity of the document outline structure,
721 this means that each top level outline entry, and
723 of its subordinates, are retained in the cache, until the
725 top level entry is defined.
727 One potential problem, which arises from the use of the \(lqoutline cache\(rq,
728 is that, at the end of any document formatting run, the last top level outline entry,
729 and any subordinates defined after it, will remain in the cache, and will
731 be automatically written to the output stream.
732 To avoid this problem, the user should follow the guidelines given in
734 .\" Here is a more conventional example of how to temporarily change
735 .\" to the format used to display reference links. We will again use
736 .\" the "SECREF" format, which we defined above, but on this occasion
737 .\" we will immediately revert to the default format, after the link
741 .pdfhref L -D pdfsync -A ,
744 to synchronise the output state with the cache state,
750 .XN -N outline-view -- Associating a Document View with an Outline Reference
752 Each \(lqbookmark\(rq entry, in a PDF document outline,
753 is associated with a specific document view.
754 When the reader selects any outline entry,
755 the document view changes to display the document context
756 associated with that entry.
758 The document view specification,
759 to be associated with any document outline entry,
760 is established at the time when the outline entry is created.
761 However, rather than requiring that each individual use of the
763 macro, to create an outline entry,
764 should include its own view specification,
765 the actual specification assigned to each entry is derived from
766 a generalised specification defined in the string
767 .CW PDFBOOKMARK.VIEW ,
768 together with the setting of the numeric register
769 .CW PDFHREF.VIEW.LEADING ,
770 which determine the effective view specification as follows:\(en
772 .IP \*[= PDFBOOKMARK.VIEW]
773 Establishes the magnification at which the document will be viewed,
774 at the location of the \(lqbookmark\(rq; by default, it is defined by
777 .CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
780 which displays the associated document view,
781 with the \(lqbookmark\(rq location positioned at the top of the display window,
782 and with the magnification set to fit the page width to the width of the window.
783 .IP \*[= PDFHREF.VIEW.LEADING]
784 Specifies additional spacing,
785 to be placed between the top of the display window
786 and the actual location of the \(lqbookmark\(rq on the displayed page view.
787 By default, it is set as
790 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
794 .CW PDFHREF.VIEW.LEADING
795 does not represent true \(lqleading\(rq, in the typographical sense,
796 since any preceding text, set in the specified display space,
797 will be visible at the top of the document viewing window,
798 when the reference is selected.
800 Also note that the specification of
801 .CW PDFHREF.VIEW.LEADING
804 reference views defined by the
808 is applied exclusively to outline references,
809 there is no independent
810 .CW PDFBOOKMARK.VIEW.LEADING
814 If desired, the view specification may be changed, by redefining the string
815 .CW PDFBOOKMARK.VIEW ,
816 and possibly also the numeric register
817 .CW PDFHREF.VIEW.LEADING .
818 Any alternative definition for
821 be specified in terms of valid view specification parameters,
822 as described in the Adobe\*(rg
825 Note the use of the register
827 in the default definition of
830 This register is computed by
832 when creating an outline entry;
833 it specifies the vertical position of the \(lqbookmark\(rq,
836 units, relative to the
838 edge of the document page on which it is defined,
839 and is followed, in the
844 operator, to convert it to PostScript\*(rg units on output.
845 It may be used in any redefined specification for
846 .CW PDFBOOKMARK.VIEW ,
847 (or in the analogous definition of
850 .XR-NO-PREFIX pdfhref-view ),
853 in any other context,
854 since its value is undefined outside the scope of the
860 is computed relative to the
862 of the PDF output page,
863 it is important to ensure that the page length specified to
865 correctly matches the size of the logical PDF page.
866 This is most effectively ensured,
869 page size specifications to
872 and to the PostScript\*(rg to PDF converter employed,
873 and avoiding any page length changes within the document source.
877 is the only automatically computed \(lqbookmark\(rq location parameter;
878 if the user redefines
879 .CW PDFBOOKMARK.VIEW ,
880 and the modified view specification requires any other positional parameters,
883 ensure that these are computed
889 .XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
891 When a document incorporates many subheadings,
892 at deeply nested levels,
893 it may be desirable to \(lqfold\(rq the outline
894 such that only the major heading levels are initially visible,
895 yet making the inferior subheadings accessible,
896 by allowing the reader to expand the view of any heading branch on demand.
900 macros support this capability,
901 through the setting of the
902 .CW PDFOUTLINE.FOLDLEVEL
904 This register should be set to the number of heading levels
905 which it is desired to show in expanded form, in the
907 document outline display;
908 all subheadings at deeper levels will still be added to the outline,
909 but will not become visible until the outline branch containing them is expanded.
911 For example, the setting used in this document:
915 \&.\e" Initialise the outline view to show only three heading levels,
916 \&.\e" with additional subordinate level headings folded.
918 \&.nr PDFOUTLINE.FOLDLEVEL 3
922 results in only the first three levels of headings being displayed
923 in the document outline,
925 the reader chooses to expand the view,
926 and so reveal the lower level headings in any outline branch.
928 The initial default setting of
929 .CW PDFOUTLINE.FOLDLEVEL ,
930 if the document author does not choose to change it,
932 This is orders of magnitude greater than the maximum heading level
933 which is likely to be used in any document;
934 thus the default behaviour will be to show document outlines fully expanded,
935 to display all headings defined,
936 at all levels within each document.
939 .CW PDFOUTLINE.FOLDLEVEL
940 may be changed at any time;
941 however, the effect of each such change may be difficult to predict,
942 since it is applied not only to outline entries which are defined
944 the setting is changed,
945 but also to any entries which remain in the outline cache,
948 Therefore, it is recommended that
949 .CW PDFOUTLINE.FOLDLEVEL
952 at the start of each document;
955 deemed necessary to change it at any other time,
956 the outline cache should be flushed,
960 which should immediately preceed a level one heading.
962 .XN -N multipart-outline -- Outlines for Multipart Documents
964 When a document outline is created, using the
966 macro, each reference mark is automatically assigned a name,
967 composed of a fixed stem followed by a serially generated numeric qualifier.
968 This ensures that, for each single part document, every outline reference
969 has a uniquely named destination.
971 As the overall size of the PDF document increases,
972 it may become convenient to divide it into smaller,
973 individually formatted PostScript\*(rg components,
974 which are then assembled, in the appropriate order,
975 to create a composite PDF document.
976 While this strategy may simplify the overall process of creating and
977 editing larger documents, it does introduce a problem in creating
978 an overall document outline,
979 since each individual PostScript\*(rg component will be assigned
980 duplicated sequences of \(lqbookmark\(rq names,
981 with each name ultimately referring to multiple locations in the composite document.
982 To avoid such reference naming conflicts, the
984 macro allows the user to specify a \(lqtag\(rq,
985 which is appended to the automatically generated \(lqbookmark\(rq name;
986 this may be used as a discriminating mark, to distinguish otherwise
987 similarly named destinations, in different sections of the composite document.
989 To create a \(lqtagged\(rq document outline,
990 the syntax for invocation of the
992 macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
994 the nesting level argument, i.e.
1001 .I "descriptive text ..."
1005 argument may be composed of any characters of the user's choice;
1006 however, its initial character
1008 be any decimal digit, and ideally it should be kept short
1009 \(em one or two characters at most.
1011 By employing a different tag in each section,
1012 the user can ensure that \(lqbookmark\(rq names remain unique,
1013 throughout all the sections of a composite document.
1014 For example, when using the
1016 macro package, which adds
1018 capabilities to the standard
1022 the table of contents is collected into a separate PostScript\*(rg section
1023 from the main body of the document.
1024 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
1025 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
1027 macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
1032 .CW ".pdfhref O -T T 1 \e\e*[TOC]"
1034 to tag the associated outline destination name with the single character suffix,
1036 Alternatively, as in the case of the basic outline,
1037 .XR basic-outline ), (
1038 this may equally well be specified as
1040 .CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1042 .XN Delegation of the Outline Definition
1044 Since the most common use of a document outline
1045 is to provide a quick method of navigating through a document,
1046 using active \(lqhypertext\(rq links to chapter and section headings,
1047 it may be convenient to delegate the responsibility of creating the outline
1048 to a higher level macro, which is itself used to
1049 define and format the section headings.
1050 This approach has been adopted in the
1052 package, to be described later,
1055 When such an approach is adopted,
1056 the user will rarely, if ever, invoke the
1058 macro directly, to create a document outline.
1059 For example, the structure and content of the outline for this document
1060 has been exclusively defined, using a combination of the
1064 package, to establish the structure, and the
1068 to define the content.
1070 the responsibility for invoking the
1072 macro, to create the document outline,
1077 .XN -N pdfhref -- Adding Reference Marks and Links
1080 .ds SECREF.BEGIN Section
1081 .pdfhref L -D add-outline
1085 macro may be used to create a PDF document outline.
1086 While this is undoubtedly a powerful capability,
1087 it is by no means the only trick in the repertoire of this versatile macro.
1091 which is a contraction of \(lqPDF HyperText Reference\(rq,
1092 indicates that the general purpose of this macro is to define
1094 type of dynamic reference mark, within a PDF document.
1095 Its generalised usage syntax takes the form
1100 .I "-options ...\&" ] [
1102 .I "descriptive text ...\&" ] [
1106 represents a required single character argument,
1107 which defines the specific reference operation to be performed,
1108 and may be selected from:\(en
1111 Add an entry to the document outline.
1112 This operation has been described earlier,
1113 .XR add-outline ). (
1115 Place a \(lqnamed destination\(rq reference mark at the current output position,
1116 in the current PDF document,
1119 Specify the content of a PDF document reference dictionary entry;
1120 typically, such entries are generated automatically,
1121 by transformation of the intermediate output resulting from the use of
1123 .CWB M \& \& \(rq, \(lq
1125 .CWB -X \& \& \(rq \(lq
1128 however, it is also possible to specify such entries manually,
1129 .XR user-format ). (
1131 Insert an active link to a named destination,
1133 at the current output position in the current PDF document,
1134 such that when the reader clicks on the link text,
1135 the document view changes to show the location of the named destination.
1137 Insert an active link to a \(lqweb\(rq resource,
1138 .XR add-weblink ), (
1139 at the current output position in the current PDF document.
1140 This is effectively the same as using the
1141 .CWB L \& \& \(rq \(lq
1142 operator to establish a link to a named destination in another PDF document,
1143 .XR link-extern ), (
1144 except that in this case, the destination is specified by a
1145 \(lquniform resource identifier\(rq, or
1147 this may represent any Internet or local resource
1148 which can be specified in this manner.
1150 Specify a user defined macro, to be called by
1152 when formatting the text in the active region of a link,
1155 Define the absolute position on the physical PDF output page,
1156 where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
1157 Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
1158 for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
1159 specified directly by the user;
1162 .CWB Z \& \& \(rq \(lq
1163 specifications are inserted automatically into the document reference map
1164 during the PDF document formatting process,
1167 Initialise support for
1172 implementation provides only one such feature which requires initialisation
1173 \(em a helper macro which must be attached to a user supplied page trap handler,
1174 in order to support mapping of reference \(lqhot\(hyspots\(rq
1175 which extend through a page transition;
1179 .XN Optional Features of the \F[C]pdfhref\F[] Macro
1181 The behaviour of a number of the
1183 macro operations can be modified,
1185 .EM "option specifiers" \(rq \(lq
1186 after the operation specifying argument,
1189 any other arguments normally associated with the operation.
1192 cases, an option is specified by an
1193 .EM "option flag" \(rq, \(lq
1194 comprising an initial hyphen,
1195 followed by one or two option identifying characters.
1201 for these options, the argument
1203 be specified, and it
1205 be separated from the preceding option flag by one or more
1210 It may be noted that this paradigm for specifying options
1211 is reminiscent of most
1215 shells; however, in the case of the
1217 macro, omission of the space separating an option flag from its argument is
1223 general purpose options supported by the
1225 macro is given below.
1226 Note that not all options are supported for all
1228 operations; the operations affected by each option are noted in the list.
1231 operations, if an unsupported option is specified,
1232 it will be silently ignored; however, this behaviour should
1235 The general purpose options, supported by the
1239 .IP \*[= -N\0 name > <]
1242 associated with a PDF reference destination
1243 to be defined independently from the following text,
1244 which describes the reference.
1245 This option affects only the
1246 .CWB M \& \& \(rq \(lq
1252 Also used exclusively with the
1253 .CWB M \& \& \(rq \(lq
1256 option causes any specified
1257 .CWI descriptive \& \& \~\c
1263 in the body text of the document,
1264 at the point where the reference mark is defined;
1268 .CWI descriptive \& \& \~\c
1272 at points where links to the reference mark are placed,
1273 and where the standard reference display format,
1276 .IP \*[= -D\0 dest > <]
1279 or the destination name associated with a PDF active link,
1280 independently of the following text,
1281 which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1282 This option affects the behaviour of the
1285 .CWB L \& \& \(rq \(lq
1287 .CWB W \& \& \(rq \(lq
1291 .CWB L \& \& \(rq \(lq
1294 argument must specify a PDF \(lqnamed destination\(rq,
1298 .CWB M \& \& \(rq \(lq
1302 .CWB W \& \& \(rq \(lq
1305 must specify a link destination in the form of a
1306 \(lquniform resource identifier\(rq, or
1308 .XR add-weblink ). (
1309 .IP \*[= -F\0 file > <]
1311 .CWB L \& \& \(rq \(lq
1315 specifies an external PDF file in which the named destination
1316 for the link reference is defined.
1319 be specified with the
1320 .CWB L \& \& \(rq \(lq
1322 to create a link to a destination in a different PDF document;
1324 .CWB L \& \& \(rq \(lq
1327 this option, the link destination is assumed to be defined
1328 within the same document.
1329 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1331 .CWI \(dqprefix\(hytext\(dq > <
1332 to be attached to the
1334 of the text describing an active PDF document link,
1335 with no intervening space, but without itself being included in the
1336 active area of the link \(lqhot\(hyspot\(rq;
1337 it is effective with the
1338 .CWB L \& \& \(rq \(lq
1340 .CWB W \& \& \(rq \(lq
1344 Typically, this option would be used to insert punctuation before
1345 the link \(lqhot\(hyspot\(rq.
1346 Thus, there is little reason for the inclusion of spaces in
1347 .CWI \(dqprefix\(hytext\(dq > < ;
1348 however, if such space is required, then the enclosing double quotes
1350 be specified, as indicated.
1351 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1353 .CWI \(dqaffixed\(hytext\(dq > <
1354 to be attached to the
1356 of the text describing an active PDF document link,
1357 with no intervening space, but without itself being included in the
1358 active area of the link \(lqhot\(hyspot\(rq;
1359 it is effective with the
1360 .CWB L \& \& \(rq \(lq
1362 .CWB W \& \& \(rq \(lq
1366 Typically, this option would be used to insert punctuation after
1367 the link \(lqhot\(hyspot\(rq.
1368 Thus, there is little reason for the inclusion of spaces in
1369 .CWI \(dqaffixed\(hytext\(dq > < ;
1370 however, if such space is required, then the enclosing double quotes
1372 be specified, as indicated.
1373 .IP \*[= -T\0 tag > <]
1374 When specified with the
1375 .CWB O \& \& \(rq \(lq
1378 is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1381 to distinguish between the series of \(lqbookmark\(rq names generated in
1382 individual passes of the
1384 formatter, when the final PDF document is to be assembled
1385 from a number of separately formatted components;
1386 .XR multipart-outline ). (
1390 option is used with either the
1391 .CWB M \& \& \(rq \(lq
1392 operator, or with the
1393 .CWB L \& \& \(rq \(lq
1397 .CWB M \& \& \(rq \(lq
1400 it ensures that a cross reference record for the marked destination
1401 will be included in the document reference map,
1405 .CWB L \& \& \(rq \(lq
1408 it causes the reference to be displayed in the standard cross reference format,
1410 but substituting the
1411 .CWI descriptive \& \& \~\c
1417 for the description specified in the document reference map.
1419 Marks the end of the option specifiers.
1420 This may be used with all
1422 operations which accept options, to prevent
1424 from interpreting any following arguments as option specifiers,
1425 even if they would otherwise be interpreted as such.
1426 It is also useful when the argument list to
1428 contains special characters \(em any special character,
1429 which is not valid in a
1431 macro name, will cause a parsing error, if
1433 attempts to match it as a possible option flag;
1436 flag prevents this, so suppressing the
1438 warning message, which would otherwise ensue.
1440 Using this flag after
1442 sequences of macro options is recommended,
1443 even when it is not strictly necessary,
1444 if only for the entirely cosmetic benefit of visually separating
1445 the main argument list from the sequence of preceding options.
1450 options listed above, a supplementary set of two character options are defined.
1451 These supplementary options, listed below, are intended for use with the
1452 .CWB L \& \& \(rq \(lq
1453 operator, in conjunction with the
1456 option, to specify alternate file names,
1457 in formats compatible with the file naming conventions
1458 of alternate operating systems;
1459 they will be silently ignored, if used in any other context.
1461 The supported alternate file name options,
1462 which are ignored if the
1465 option is not specified, are:\(en
1467 .IP \*[= -DF\0 dos\(hyfile > <]
1468 Specifies the name of the file in which a link destination is defined,
1469 using the file naming semantics of the
1472 When the PDF document is read on a machine
1473 where the operating system uses the
1476 .CWI dos\(hyfile > <
1477 is used as the name of the file containing the reference destination,
1480 argument specified with the
1483 .IP \*[= -MF\0 mac\(hyfile > <]
1484 Specifies the name of the file in which a link destination is defined,
1485 using the file naming semantics of the
1489 When the PDF document is read on a machine
1490 where the operating system uses the
1493 .CWI mac\(hyfile > <
1494 is used as the name of the file containing the reference destination,
1497 argument specified with the
1500 .IP \*[= -UF\0 unix\(hyfile > <]
1501 Specifies the name of the file in which a link destination is defined,
1502 using the file naming semantics of the
1505 When the PDF document is read on a machine
1506 where the operating system uses
1508 file naming semantics, then
1509 .CWI unix\(hyfile > <
1510 is used as the name of the file containing the reference destination,
1513 argument specified with the
1516 .IP \*[= -WF\0 win\(hyfile > <]
1517 Specifies the name of the file in which a link destination is defined,
1518 using the file naming semantics of the
1519 .CW MS\(hyWindows \*(rg
1520 32\(hybit operating system.
1521 When the PDF document is read on a machine
1522 where the operating system uses any of the
1523 .CW MS\(hyWindows \*(rg
1524 file systems, with long file name support, then
1525 .CWI win\(hyfile > <
1526 is used as the name of the file containing the reference destination,
1529 argument specified with the
1534 .XN -N mark-dest -- Marking a Reference Destination
1538 macro may be used to create active links to any Internet resource,
1541 or to any \(lqnamed destination\(rq,
1542 either within the same document, or in another PDF document.
1543 Although the PDF specification allows link destinations to be defined
1544 in terms of a page number, and an associated view specification,
1545 this style of reference is not currently supported by the
1547 macro, because it is not possible to adequately bind the specification
1548 for the destination with the intended reference context.
1550 References to Internet resources are interpreted in accordance with the
1552 standard for defining a
1554 hence the only prerequisite, for creating a link to any Internet resource,
1557 be properly specified, when declaring the reference;
1558 .XR add-weblink ). (
1559 In the case of references to \(lqnamed destinations\(rq in PDF documents,
1560 however, it is necessary to provide a mechanism for creating such
1561 \(lqnamed destinations\(rq.
1562 This may be accomplished, by invoking the
1572 .I "descriptive text ...\&" ] [
1574 This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1578 option is not specified, by the first word of
1579 .CWI descriptive \& \& \~\c
1581 (note that this imposes the restriction that,
1584 option is omitted, then
1587 .CWI descriptive \& \& \~\c
1591 Additionally, a reference view will be automatically defined,
1592 and associated with the reference mark,
1593 .XR pdfhref-view ), (
1595 .\" .CWI descriptive
1597 .\" is specified, or the
1600 option is specified, and no document cross reference map has been imported,
1602 then a cross reference mapping record,
1604 will be written to the
1607 this may be captured, and subsequently used to generate a cross reference map
1611 When a \(lqnamed destination\(rq reference mark is created, using the
1614 .CWB M \& \& \(rq \(lq
1615 operator, there is normally no visible effect in the formatted document; any
1616 .CWI descriptive \& \& \~\c
1618 which is specified will simply be stored in the cross reference map,
1619 for use when a link to the reference mark is created.
1620 This default behaviour may be changed, by specifying the
1622 option, which causes any specified
1623 .CWI descriptive \& \& \~\c
1625 to be \(lqechoed\(rq in the document text,
1626 at the point where the reference mark is placed,
1627 in addition to its inclusion in the cross reference map.
1629 .XN -N export-map -- Mapping a Destination for Cross Referencing
1631 Effective cross referencing of
1633 document formatted by
1635 requires multiple pass formatting.
1636 Details of how this multiple pass formatting may be accomplished,
1637 when working with the
1639 macros, will be discussed later,
1641 at this stage, the discussion will be restricted to the initial preparation,
1642 which is required at the time when the cross reference destinations are defined.
1644 The first stage, in the process of cross referencing a document,
1645 is the generation of a cross reference map.
1646 Again, the details of
1648 the cross reference map is generated will be discussed in
1649 .pdfhref F SECREF L -D do-xref -A ;
1651 however, it is important to recognise that
1653 content is included in the cross reference map is established
1654 when the reference destination is defined \(em it is derived
1655 from the reference data exported on the
1659 macro, when it is invoked with the
1660 .CWB M \& \& \(rq \(lq
1661 operator, and is controlled by whatever definition of the string
1663 is in effect, when the
1667 The initial default setting of
1671 .CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1673 which ensures that the cross reference map will contain
1674 at least a page number reference, supplemented by any
1675 .CWI descriptive \& \& \~\c
1677 which is specified for the reference mark, as defined by the
1680 .CWB M \& \& \(rq \(lq
1681 operator; this may be redefined by the user,
1682 to export additional cross reference information,
1683 or to modify the default format for cross reference links,
1686 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
1688 In the same manner as each document outline reference, defined by the
1691 .CWB O \& \& \(rq \(lq
1693 .XR add-outline ), (
1694 has a specific document view associated with it,
1695 each reference destination marked by
1698 .CWB M \& \& \(rq \(lq
1699 operator, requires an associated document view specification.
1701 The mechanism whereby a document view is associated with a reference mark
1702 is entirely analogous to that employed for outline references,
1703 .XR outline-view ), (
1706 string specification is used, in place of the
1707 .CW PDFBOOKMARK.VIEW
1709 Thus, the reference view is defined in terms of:\(en
1711 .IP \*[= PDFHREF.VIEW]
1713 establishing the position of the reference mark within the viewing window,
1714 and the magnification at which the document will be viewed,
1715 at the location of the marked reference destination;
1716 by default, it is defined by
1719 .CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
1722 which displays the reference destination at the top of the viewing window,
1723 with the magnification set to fit the page width to the width of the window.
1724 .IP \*[= PDFHREF.VIEW.LEADING]
1726 specifying additional spacing, to be placed between the top of the display
1727 window and the actual position at which the location of the reference
1728 destination appears within the window.
1729 This register is shared with the view specification for outline references,
1730 and thus has the same default initial setting,
1733 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
1736 as in the case of outline reference views.
1739 .CW PDFHREF.VIEW.LEADING
1740 does not represent true typographic \(lqleading\(rq,
1741 since any preceding text, set in the specified display space,
1742 will be visible at the top of the viewing window,
1743 when the reference is selected.
1746 Just as the view associated with outline references may be changed,
1748 .CW PDFBOOKMARK.VIEW ,
1749 so the view associated with marked reference destinations may be changed,
1753 .CW PDFHREF.VIEW.LEADING ;
1754 such changes will become effective for all reference destinations marked
1756 these definitions are changed.
1757 (Notice that, since the specification of
1758 .CW PDFHREF.VIEW.LEADING
1759 is shared by both outline reference views and marked reference views,
1760 if it is changed, then the views for
1762 reference types are changed accordingly).
1764 It may again be noted, that the
1766 register is used in the definition of
1768 just as it is in the definition of
1769 .CW PDFBOOKMARK.VIEW ;
1771 .pdfhref F SECREF L -D outline-view
1773 relating to its use, and indeed to page position computations in general,
1774 apply equally to marked reference views and to outline reference views.
1776 .XN -N link-named -- Linking to a Marked Reference Destination
1778 Any named destination, such as those marked by the
1781 .CWB M \& \& \(rq \(lq
1782 operator, may be referred to from any point in
1784 PDF document, using an
1786 such active links are created by again using the
1788 macro, but in this case, with the
1789 .CWB L \& \& \(rq \(lq
1791 This operator provides support for two distinct cases,
1792 depending on whether the reference destination is defined in
1793 the same document as the link,
1794 .XR link-intern ), (
1795 or is defined as a named destination in a different PDF document,
1796 .XR link-extern ). (
1798 .XN -N link-intern -- References within a Single PDF Document
1800 The general syntactic form for invoking the
1803 when creating a link to a named destination within the same PDF document is
1811 .BI prefix-text >] <
1813 .BI affixed-text >] <
1819 .I "descriptive text ...\&" ] [
1823 specifies the name of the link destination,
1824 as specified using the
1826 .CWB M \& \& \(rq \(lq
1827 operation; (it may be defined either earlier in the document,
1828 to create a backward reference, or later, to create a forward reference).
1830 .\" Here's a example of how to add an iconic annotation.
1832 .\".pdfnote -T "Internal Cross References" \
1833 .\" This description is rather terse, and could benefit from \
1834 .\" the inclusion of an example.
1837 .CWI descriptive \& \& \~\c
1839 arguments are specified, then they will be inserted into the
1841 output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
1843 this will be printed in the link colour specified by the string,
1844 .CW PDFHREF.TEXT.COLOUR ,
1845 which is described in
1846 .XR-NO-PREFIX set-colour .
1849 option is also specified, then the
1850 .CWI descriptive \& \& \~\c
1852 will be augmented, by prefacing it with page and section number indicators,
1853 in accordance with the reference formatting rules which are in effect,
1855 such indicators will be included within the active link region,
1856 and will also be printed in the link colour.
1862 .CWBI dest\(hyname > <
1866 .CWI descriptive \& \& \~\c
1869 .EM "but not both" ,
1873 .CWBI dest\(hyname > <
1874 option is omitted, then the first word of
1875 .CWI descriptive \& \& \~\c
1877 i.e.\~all text up to but not including the first space,
1878 will be interpreted as the
1879 .CWBI dest\(hyname > <
1880 for the link; this text will also appear in the running text of the document,
1881 within the active region of the link.
1882 Alternatively, if the
1884 .CWBI dest\(hyname > <
1888 .CWI descriptive \& \& \~\c
1891 then the running text which defines the reference,
1892 and its active region,
1893 will be derived from the reference description which is specified
1894 when the named destination is marked,
1896 and will be formatted according to the reference formatting rules
1897 which are in effect, when the reference is placed,
1899 in this case, it is not necessary to specify the
1901 option to activate automatic formatting of the reference \(em it is implied,
1902 by the omission of all
1903 .CWI descriptive \& \& \~\c
1909 .CWBI prefix\(hytext > <
1912 .CWBI affixed\(hytext > <
1913 options may be used to specify additional text
1914 which will be placed before and after the linked text respectively,
1915 with no intervening space.
1916 Such prefixed and affixed text will be printed in the normal text colour,
1917 and will not be included within the active region of the link.
1918 This feature is mostly useful for creating parenthetical references,
1919 or for placing punctuation adjacent to,
1920 but not included within,
1921 the text which defines the active region of the link.
1923 The operation of the
1925 macro, when used with its
1926 .CWB L \& \& \(rq \(lq
1927 operator to place a link to a named PDF destination,
1928 may best be illustrated by an example.
1929 However, since the appearance of the link will be influenced by
1930 factors established when the named destination is marked,
1932 and also by the formatting rules in effect when the link is placed,
1933 the presentation of a suitable exanple will be deferred,
1934 until the formatting mechanism has been explained,
1937 .XN -N link-extern -- References to Destinations in Other PDF Documents
1942 .CWB L \& \& \(rq \(lq
1943 operator is not restricted to creating reference links
1944 within a single PDF document.
1945 When the link destination is defined in a different document,
1946 then the syntactic form for invoking
1948 is modified, by the addition of options to specify the
1949 name and location of the PDF file in which the destination is defined.
1952 syntactic form becomes
1976 .BI prefix-text >] <
1978 .BI affixed-text >] <
1984 .I "descriptive text ...\&" ] [
1991 purposes: it both indicates to the
1993 macro that the specified reference destination
1994 is defined in an external PDF file,
1995 and it also specifies the normal path name,
1996 which is to be used to locate this file,
1997 when a user selects the reference.
2004 be specified when referring to a destination in an external PDF file,
2007 .CWBI dos\(hyfile > < ,
2009 .CWBI mac\(hyfile > < ,
2011 .CWBI unix\(hyfile > <
2014 .CWBI win\(hyfile > <
2015 options may be used to specify the location of the file
2016 containing the reference destination,
2017 in a variety of operating system dependent formats.
2018 These options assign their arguments to the
2024 keys of the generated
2026 respectively; thus when any of these options are specified,
2027 .EM "in addition to"
2031 option, and the document is read on the appropriate operating systems,
2032 then the path names specified by
2033 .CWBI dos\(hyfile > < ,
2034 .CWBI mac\(hyfile > < ,
2035 .CWBI unix\(hyfile > <
2037 .CWBI win\(hyfile > <
2040 of the path name specified by
2043 .CW MS\(hyDOS \*(rg,
2045 .CW Macintosh \*(rg,
2048 .CW MS\(hyWindows \*(rg
2049 operating systems, respectively; see the
2051 for further details.
2053 Other than the use of these additional options,
2054 which specify that the reference destination is in an external PDF file,
2055 the behaviour of the
2057 .CWB L \& \& \(rq \(lq
2061 option, remains identical to its behaviour
2064 .XR link-intern ), (
2065 with respect to the interpretation of other options,
2067 .CWI descriptive \& \& \~\c
2069 arguments, and the formatting of the displayed reference.
2071 Once again, since the appearance of the reference is determined by
2072 factors specified in the document reference map,
2073 and also by the formatting rules in effect when the reference is placed,
2074 the presentation of an example of the placing of
2075 a reference to an external destination will be deferred,
2076 until the formatting mechanism has been explained,
2079 .XN -N add-weblink -- Linking to Internet Resources
2081 In addition to supporting the creation of cross references
2082 to named destinations in PDF documents, the
2084 macro also has the capability to create active links to Internet resources,
2087 resource which may be specified by a Uniform Resource Identifier,
2088 (which is usually abbreviated to the acronym \(lqURI\(rq,
2089 and sometimes also referred to as a Uniform Resource Locator,
2092 Since the mechanism for creating a link to a URI differs somewhat
2093 from that for creating PDF references, the
2095 macro is invoked with the
2096 .CWB W \& \& \(rq \(lq
2097 (for \(lqweb\(hylink\(rq) operator, rather than the
2098 .CWB L \& \& \(rq \(lq
2099 operator; nevertheless, the invocation syntax is similar, having the form
2107 .BI prefix-text >] <
2109 .BI affixed-text >] <
2114 .I "descriptive text ...\&"
2119 modifier specifies the address for the target Internet resource,
2121 .EM "Uniform Resource Identifier"
2125 argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
2128 .CWBI prefix\(hytext > <
2131 .CWBI affixed\(hytext > <
2132 options have the same effect as in the case of local document links,
2133 .XR link-intern ). (
2135 Notice that it is not mandatory to include the
2138 in the link specification; if it
2140 specified, then it is not necessary for the URI to appear,
2141 in the running text of the document \(em the
2144 argument exactly defines the text
2145 which will appear within the \(lqhot\(hyspot\(rq region,
2146 and this need not include the URI.
2150 specification is omitted, then the
2157 representation of the URI, which
2159 therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
2160 For example, we could introduce a reference to
2161 .pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2162 in which the actual URI is concealed, by using mark up such as:\(en
2165 For example, we could introduce a reference to
2166 \&.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
2167 in which the actual URI is concealed,
2170 to refer the reader to the groff web site,
2171 making it obvious that the appropriate URI is
2172 .pdfhref W -A , \*[GROFF-WEBSITE]
2173 the requisite mark up might be:\(en
2176 to refer the reader to the groff web site,
2177 making it obvious that the appropriate URI is
2178 \&.pdfhref W -A , \*[GROFF-WEBSITE]
2179 the requisite mark up might be:\e(en
2182 .XN -N set-format -- Establishing a Format for References
2184 There are two principal aspects to be addressed,
2185 when defining the format to be used when displaying references.
2186 Firstly, it is desirable to provide a visual cue,
2187 to indicate that the text describing the reference is imbued
2188 with special properties \(em it is dynamically linked to the reference
2189 destination \(em and secondly, the textual content should
2190 describe where the link leads, and ideally,
2191 it should also describe the content of the reference destination.
2194 that a text region defines a dynamically linked reference,
2195 is most commonly provided by printing the text within the active
2196 region in a distinctive colour.
2197 This technique will be employed automatically by the
2201 \(em unless the user specifically chooses to adopt, and implement,
2202 some alternative strategy.
2204 .XN -N set-colour -- Using Colour to Demarcate Link Regions
2206 Typically, when a PDF document contains
2208 references to other locations, either within the same document,
2209 or even in other documents, or on the World Wide Web,
2210 it is usually desirable to make the regions
2211 where these active links are placed stand out from the surrounding text.
2213 .XN -N user-format -- Specifying Reference Text Explicitly
2215 .XN -N auto-format -- Using Automatically Formatted Reference Text
2217 .XN -N custom-format -- Customising Automatically Formatted Reference Text
2219 It is incumbent on the user,
2220 if employing automatic formatting of the displayed reference,
2222 to ensure that an appropriate reference definition
2223 is created for the reference destination,
2224 and is included in the reference map for the document
2225 in which the reference will appear;
2226 thus, it may be easiest to
2228 use manual formatting for external references.
2230 .XN Problematic Links
2232 Irrespective of whether a
2234 reference is placed using the
2235 .CWB L \& \& \(rq \(lq
2237 .CWB W \& \& \(rq \(lq
2238 operator, there may be occasions when the resulting link
2239 does function as expected.
2240 A number of scenarios, which are known to be troublesome,
2241 are described below.
2243 .XN -N page-trap -- Links with a Page Transition in the Active Region
2245 When a link is placed near the bottom of a page,
2246 it is possible that its active region, or \(lqhot\(hyspot\(rq,
2247 may extend on to the next page.
2248 In this situation, a page trap macro is required
2249 to intercept the page transition, and to restart the mapping of
2250 the \(lqhot\(hyspot\(rq boundary on the new page.
2254 macro package includes a suitable page trap macro, to satisfy this requirement.
2255 However, to avoid pre\(hyempting any other requirement the user may have for
2256 a page transition trap, this is
2258 installed as an active page trap,
2259 unless explicitly requested by the user.
2261 To enable proper handling of page transitions,
2262 which occur within the active regions of reference links,
2263 the user should:\(en
2267 Define a page transition macro, to provide whatever features may be required,
2268 when a page transition occurs \(em e.g.\& printing footnotes,
2269 adding page footers and headers, etc.
2270 This macro should end by setting the output position at the correct
2271 vertical page offset, where the printing of running text is to restart,
2272 following the page transition.
2274 Plant a trap to invoke this macro, at the appropriate vertical position
2275 marking the end of normal running text on each page.
2280 hook into this page transition trap, by invoking
2288 .CWBI macro-name > <
2289 is the name of the user supplied page trap macro,
2292 will correctly restart mapping of active link regions,
2293 at the start of each new page.
2298 It may be observed that this initialisation of the
2300 page transition hook is, typically, required only once
2302 document formatting begins.
2303 Users of document formatting macro packages may reasonably expect that
2304 this initialisation should be performed by the macro package itself.
2305 Thus, writers of such macro packages which include
2307 bindings, should provide appropriate initialisation,
2308 so relieving the end user of this responsibility.
2309 The following example, abstracted from the sample
2313 illustrates how this may be accomplished:\(en
2316 \&.\e" groff "ms" provides the "pg@bottom" macro, which has already
2317 \&.\e" been installed as a page transition trap. To ensure proper
2318 \&.\e" mapping of "pdfhref" links which overflow the bottom of any
2319 \&.\e" page, we need to install the "pdfhref" page transition hook,
2320 \&.\e" as an addendum to this macro.
2322 \&.pdfhref I -PT pg@bottom
2325 .XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
2327 .XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts
2329 It has been noted previously, that the
2339 macro, when used to create a document outline,
2340 .XR add-outline ), (
2341 do not immediately write their
2343 output to the PostScript\*(rg data stream;
2344 instead, they cache their output, in a
2346 diversion, in the case of the
2350 macros, or in an ordered collection of strings and numeric registers,
2351 in the case of the document outline,
2352 until a more appropriate time for copying it out.
2357 \(lqmeta\(hydata\(rq,
2358 this \(lqmore appropriate time\(rq is explicitly chosen by the user;
2359 in the case of document outline data,
2361 cached data may be implicitly written out as the document outline is compiled,
2364 be some remaining data, which must be explicitly flushed out, before the
2366 formatting process is allowed to complete.
2368 To allow the user to choose when cached
2370 data is to be flushed to the output stream, the
2372 macro package provides the
2374 macro, (to synchronise the cache and output states).
2375 In its simplest form, it is invoked without arguments, i.e.
2380 This form of invocation ensures that
2382 the \(lqmeta\(hydata cache\(rq, containing
2388 the \(lqoutline cache\(rq,
2389 containing any previously uncommitted document outline data,
2390 are flushed; ideally, this should be included in a
2392 \(lqend macro\(rq, to ensure that
2394 caches are flushed, before
2399 it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
2400 without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
2401 at a user specified time, prior to reaching the end of the document.
2402 This may be accomplished, by invoking the
2404 macro with an argument, i.e.
2409 to flush only the \(lqmeta\(hydata cache\(rq, or
2414 to flush only the \(lqoutline cache\(rq.
2416 The \(lqmeta\(hydata cache\(rq can normally be safely flushed
2417 in this manner, at any time
2419 output of the first page has started;
2420 (it may cause formatting problems,
2421 most notably the appearance of unwanted white space, if flushed earlier,
2422 or indeed, if flushed immediately after a page transition,
2423 but before the output of the content on the new page has commenced).
2424 Caution is required, however, when explicitly flushing the
2425 \(lqoutline cache\(rq, since if the outline is to be
2426 subsequently extended, then the first outline entry after flushing
2428 be specified at level 1.
2429 Nevertheless, such explicit flushing may occasionally be necessary;
2437 .CW ".pdfsync\ O" \(rq \(lq
2438 to ensure that the outline for the \(lqbody\(rq section of the document
2441 it commences the formatting of the table of contents section.
2444 .XN -N pdf-layout -- PDF Document Layout
2448 macros described in the preceding section,
2449 .XR pdf-features ), (
2450 provide no inherent document formatting capability of their own.
2452 they may be used in conjunction with any other
2454 macro package of the user's choice,
2455 to add such capability.
2457 In preparing this document, the standard
2459 macro package, supplied as a component of the GNU Troff distribution,
2461 To facilitate the use of the
2466 a binding macro package,
2469 The use of this binding macro package is described in the following section,
2471 it may also serve as an example to users of other standard
2476 macros may be employed with their chosen primary macro package.
2478 .XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
2480 The use of the binding macro package,
2482 allows for the use of the
2484 macros in conjunction with the
2494 .I "-options ...\&" ] [
2497 (Or use the PDF post-processor to avoid using ghostscript,
2505 input files may be marked up using any of the standard
2507 macros to specify document formatting,
2508 while PDF features may be added,
2511 macros described previously,
2512 .XR pdf-features ). (
2515 defines a number of convenient extensions to the
2517 macro set, to better accomodate the use of PDF features within the
2519 formatting framework,
2520 and to address a number of
2522 document layout issues,
2523 which require special handling when producing PDF documents.
2524 These additional macros,
2525 and the issues they are intended to address,
2526 are described below.
2528 .XN \F[C]ms\F[] Section Headings in PDF Documents
2536 macros, to specify section headings.
2538 there is no standard mechanism for generating a
2539 table of contents entry based on the text of the section heading;
2540 neither is there any recognised standard method for establishing a
2541 cross reference link to the section.
2551 to be used in conjunction with the
2555 .XN -N xn-macro -- The \F[C]XN\F[] Macro
2557 .XN The PDF Publishing Process
2559 .XN -N do-xref -- Resolving Cross References
2561 .XN -N create-map -- Creating a Document Reference Map
2563 .XN -N import-map -- Deploying a Document Reference Map
projects / platform / upstream / groff.git / blob