diff options
Diffstat (limited to 'contrib/pdfmark/pdfmark.ms')
-rw-r--r-- | contrib/pdfmark/pdfmark.ms | 2357 |
1 files changed, 2357 insertions, 0 deletions
diff --git a/contrib/pdfmark/pdfmark.ms b/contrib/pdfmark/pdfmark.ms new file mode 100644 index 00000000..936972c4 --- /dev/null +++ b/contrib/pdfmark/pdfmark.ms @@ -0,0 +1,2357 @@ +.\" vim: ft=groff +.CS +Portable Document Format +Publishing with GNU Troff +.AU Keith Marshall +.AI <keith.d.marshall@ntlworld.com> +.CE +.\" Set the PDF default document view attribute, to ensure that the document +.\" outline is visible, each time the document is opened in Acrobat Reader. +.\" +.pdfview /PageMode /UseOutlines +.\" +.\" Add document identification meta-data +.\" +.pdfinfo /Title Portable Document Format Publishing with GNU Troff +.pdfinfo /Author Keith Marshall +.pdfinfo /Subject Tips and Techniques for Exploiting PDF Features with GNU Troff +.pdfinfo /Keywords groff troff PDF pdfmark +.\" +.\" Set the default cross reference format to indicate section numbers, +.\" rather than page numbers, when we insert a reference pointer. +.\" +.ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$* +.\" +.\" Define a macro, to print reference links WITHOUT the usual "see" prefix. +.\" +.de XR-NO-PREFIX +.rn PDFHREF.PREFIX xx +.ds PDFHREF.PREFIX +.XR \\$@ +.rn xx PDFHREF.PREFIX +.. +.\" +.\" Define a string, +.\" to insert a Registered Trade Mark symbol as a superscript. +.\" +.ds rg \*{\(rg\*} +.\" +.\" Establish the page layout. +.\" +.nr PO 2.5c +.nr LL 17.0c +.nr LT 17.0c +.nr HY 0 +.nr FF 3 +.nr DI 5n +.\" +.\" Generate headers in larger point sizes, for NH levels < 4, +.\" with point size increasing by 1.5p, for each lesser NH level. +.\" +.nr GROWPS 4 +.nr PSINCR 1.5p +.\" +.de EM +.\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3" +.I \\$@ +.. +.de CWB +\\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4 +.. +.de CWI +\\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4 +.. +.de CWBI +\\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4 +.. +.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3 +.\" +.NH 1 +.\" When we use numbered section headings, we might like to automatically +.\" insert a table of contents entry, using the text of the heading itself. +.\" The "ms" macros don't provide any standard mechanism for doing this, +.\" but "spdf.tmac" adds the "XN" macro, which will do it for us. +.\" +.\" Here's a simple example of how we might use it. In this case, the word +.\" "Introduction" will appear both in the body of the document, as the text +.\" of the heading, and it will be added to the table of contents, which is +.\" subsequently "printed" using the "TC" macro; in both locations, it will +.\" be prefixed by the section number. +.\" +.\" As an additional side effect, any use of "XN" will cause the table of +.\" contents entry to be automatically reproduced, with the exception of its +.\" page number reference, as a PDF document outline entry. Thus, the use +.\" of "XN" to specify numbered section headings results in the automatic +.\" creation of a numbered PDF document outline. This automatic creation +.\" of the outline is completely transparent, and will occur regardless +.\" of whether the "TC" macro is subsequently invoked, or not. +.\" +.XN Introduction +.\" +.\" If using an old s.tmac, without the SN-NO-DOT extension, +.\" make sure we get SOMETHING in section number references. +.\" +.if !dSN-NO-DOT .als SN-NO-DOT SN +.LP +It might appear that it is a fairly simple matter to +produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq, +commonly known as PDF, using +.CW groff ) GNU\~Troff\~( +as the document formatter. +Indeed, +.CW groff 's +default output format is the native Adobe\*(rg\~PostScript\*(rg format, +which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg, +or GhostScript, expect as their input format. +Thus, the PDF production process would seem to entail simply +formatting the document source with +.CW groff , +to produce a PostScript\*(rg version of the document, +which can subsequently be processed by Acrobat\*(rg Distiller\*(rg +or GhostScript, to generate the final PDF document. +.LP +For many PDF production requirements, +the production cycle described above may be sufficient. +However, this is a limited PDF production method, +in which the resultant PDF document represents no more than +an on screen image of the printed form of the document, if +.CW groff 's +PostScript\*(rg output were printed directly. +.LP +The Portable Document Format provides a number of features, +which significantly enhance the experience of reading a document on screen, +but which are of little or no value to a document which is merely printed. +It +.EM is +possible to exploit these PDF features, which are described in the Adobe\*(rg +.\" +.de pdfmark-manual +.\" This is an example of a resource reference specified by URI ... +.\" We may need to refer often to the Adobe pdfmark Reference Manual, +.\" so we create the internet link definition using a macro, to make +.\" it reusable. +.\" +.\" Note also, that we protect the description of the reference by +.\" preceding it with "--", to avoid "invalid character in name" type +.\" error messages from groff (caused by the use of "\~"). +.\" +.pdfhref W -D http://partners.adobe.com/asn/acrobat/docs/pdfmark.pdf \ + -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual +.. +.pdfmark-manual , +with some refinement of the simple PDF production method, provided +appropriate \(lqfeature implementing\(rq instructions can be embedded into +.CW groff 's +PostScript\*(rg rendering of the document. +This, of course, implies that the original document source, which +.CW groff +will process to generate the PostScript\*(rg description of the document, +must include appropriate markup to exploit the desired PDF features. +It is this preparation of the +.CW groff +document source to exploit a number of these features, +which provides the principal focus of this document. +.LP +The markup techniques to be described have been utilised in the production of +the PDF version of this document itself. +This has been formatted using +.CW groff 's +.CW ms +macro package; +thus, usage examples may be found in the document source file, +.CW \n(.F , +to which comments have been added, +to help identify appropriate markup examples for implementing PDF features, +such as:\(en +.QS +.IP \(bu +Selecting a default document view, which defines how the document will appear +when opened in the reader application; for example, when this document is +opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet, +in the document view pane, while a document outline should appear to the left, +in the \(lqBookmarks\(rq pane. +.IP \(bu +Adding document identification \(lqmeta\(hydata\(rq, +which can be accessed, in Acrobat\*(rg\~Reader, +by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq. +.IP \(bu +Creating a document outline, which will be displayed in the \(lqBookmarks\(rq +pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any +section of the document, simply by clicking on the associated heading +in the outline view. +.IP \(bu +Embedding active links in the body of the document, such that readers may +quickly navigate to related material at another location within the same +document, or in another PDF document, or even to a related Internet resource, +specified by its URI. +.IP \(bu +Adding annotations, in the form of \(lqsticky notes\(rq, at strategic +points within the PDF document. +.QE +.LP +All of the techniques described have been tested on +.EM both +GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using +.CW groff +.CW 1.19.1 ,\c +.pdfhref L -D footnote1 -- \** +.FS +.pdfhref M footnote1 +Later versions should, and some earlier versions may, be equally suitable. +See +.pdfhref W http://groff.ffii.org +for information and availability of the latest version. +.FE +in association with +.CW AFPL +.CW GhostScript +.CW 8.14 .\c +.pdfhref L -D footnote2 -- \** +.FS +.pdfhref M footnote2 +Again, other versions may be suitable. +See +.pdfhref W http://ghostscript.com +for information and availability. +.FE +Other tools employed, which should be readily available on +.EM any +.SM +UNIX\(tm +.LG +or GNU/Linux system, are +.CW sed , +.CW awk +and +.CW make , +together with an appropriate text editor, for creating and marking up the +.CW groff +input files. +These additional utilities are not provided, as standard, +on the Microsoft\*(rg Windows\(tm platform, +but several third party implementations are available. +Some worth considering include the MKS\*(rg\~Toolkit,\** +.FS +A commercial offering; see +.pdfhref W http://mkssoftware.com/products/tk/default.asp +for information. +.FE +Cygwin,\** +.FS +A +.EM free +but comprehensive +.SM +POSIX +.LG +emulation environment and +.SM +UNIX\(tm +.LG +toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see +.pdfhref W http://cygwin.com +for information and download. +.FE +or MSYS.\** +.FS +Another free, but minimal suite of common +.SM +UNIX\(tm +.LG +tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from +.pdfhref W -A ; http://www.mingw.org +it +.EM does +include those tools listed above, +and is the package which was actually used when performing the Windows\(tm2000 +platform tests referred to in the text. +.FE +This list is by no means exhaustive, and should in no way be construed as an +endorsement of any of these packages, nor to imply that other similar packages, +which may be available, are in any way inferior to them. +.bp +.NH 1 +.\" We may wish a section heading to represent a named destination, +.\" so that we can create a linked reference to it, from some other +.\" part of the PDF document, (or even from another PDF document). +.\" +.\" Here we use the "-N" option of the "XN" macro, to create a named +.\" PDF link destination, at the location of the heading. Notice that +.\" we also use the "--" marker to separate the heading text from the +.\" preceding option specification; it is not strictly necessary in +.\" this case, but it does help to set off the heading text from the +.\" option specification. +.\" +.XN -N pdf-features -- Exploiting PDF Document Features +.LP +To establish a consistent framework for adding PDF features, a +.CW groff +macro package, named +.CW pdfmark.tmac , +has been provided. +Thus, to incorporate PDF features in a document, +the appropriate macro calls, as described below, may be placed in the +.CW groff +document source, which should then be processed with a +.CW groff +command of the form +.QP +.fam C +groff -Tps [-m +.I name "] -m" +.B pdfmark +.I options \& [- +.I "file ..." \& "...] " +.LP +It may be noted that the +.CW pdfmark +macros have no dependencies on, and no known conflicts with, +any other +.CW groff +macro package; thus, users are free to use any other macro package, +of their choice, to format their documents, while also using the +.CW pdfmark +macros to add PDF features. +.NH 2 +.XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator +.LP +All PDF features are implemented by embedding instances of the +.B \F[C]pdfmark\F[] +operator, as described in the Adobe\*(rg +.pdfmark-manual , +into +.CW groff 's +PostScript\*(rg output stream. +To facilitate the use of this operator, the +.CW pdfmark +macro package defines the primitive +.CW pdfmark +macro; it simply emits its argument list, +as arguments to a +.CW pdfmark +operator, in the PostScript\*(rg output stream. +.LP +.pdfhref M -N pdfmark-example +To illustrate the use of the +.CW pdfmark +macro, the following is a much simplified example of how a bookmark +may be added to a PDF document outline +.QP +.CW ".pdfmark \e" +.RS 4 +.nf +.fam C +/Count 2 \e +/Title (An Example of a Bookmark with Two Children) \e +/View [/FitH \en[PDFPAGE.Y]] \e +/OUT +.RE +.LP +In general, users should rarely need to use the +.CW pdfmark +macro directly. +In particular, the above example is too simple for general use; it +.EM will +create a bookmark, but it does +.EM not +address the issues of setting the proper value for the +.CW /Count +key, nor of computing the +.CW PDFPAGE.Y +value used in the +.CW /View +key. The +.CW pdfmark +macro package includes a more robust mechanism for creating bookmarks, +.\" +.\" Here is an example of how a local reference may be planted, +.\" using the automatic formatting feature of the "pdfhref" macro. +.\" +.\" This is a forward reference to the named destination "add-outline", +.\" which is defined below, using the "XN" wrapper macro, from the +.\" "spdf.tmac" macro package. The automatically formatted reference +.\" will be enclosed in parentheses, as specified by the use of +.\" "-P" and "-A" options. +.\" +.pdfhref L -P ( -A ), -D add-outline +.\" +which addresses these issues automatically. +Nevertheless, the +.CW pdfmark +macro may be useful to users wishing to implement more advanced PDF features, +than those currently supported directly by the +.CW pdfmark +macro package. +.NH 2 +.XN -N docview -- Selecting an Initial Document View +.LP +By default, +when a PDF document is opened, +the first page will be displayed, +at the default magnification set for the reader, +and outline and thumbnail views will be hidden. +When using a PDF reader, +such as Acrobat\*(rg\~Reader, +which supports the +.CW /DOCVIEW +class of the +.CW pdfmark +operator, +these default initial view settings may be overridden, +using the +.CW pdfview +macro. +For example +.QP +.CW ".pdfview /PageMode /UseOutlines" +.LP +will cause Acrobat\*(rg\~Reader to open the document outline view, +to the left of the normal page view, +while +.QP +.CW ".pdfview /PageMode /UseThumbs" +.LP +will open the thumbnail view instead. +.LP +Note that the two +.CW /PageMode +examples, above, are mutually exclusive \(em it is not possible to have +.EM both +outline and thumbnail views open simultaneously. +However, it +.EM is +permitted to add +.CW /Page +and +.CW /View +keys, to force the document to open at a page other than the first, +or to change the magnification at which the document is initially displayed; +see the +.pdfmark-manual +for more information. +.LP +It should be noted that the view controlling meta\(hydata, defined by the +.CW pdfview +macro, is not written immediately to the PostScript\*(rg output stream, +but is stored in an internal meta\(hydata \(lqcache\(rq, +(simply implemented as a +.CW groff +diversion). +This \(lqcached\(lq meta\(hydata must be written out later, by invoking the +.CW pdfsync +macro, +.\" +.\" Here is another example of how we may introduce a forward reference. +.\" This time we are using the shorter notation afforded by the "XR" macro +.\" provided by "spdf.tmac"; this example is equivalent to the native +.\" "pdfmark.tmac" form +.\" .pdfhref L -D pdfsync -P ( -A ). +.\" +.XR pdfsync ). ( +.\" +.NH 2 +.XN -N docinfo -- Adding Document Identification Meta-Data +.LP +In addition to the +.CW /DOCVIEW +class of meta\(hydata described above, +.XR docview ), ( +we may also wish to include document identification meta\(hydata, +which belongs to the PDF +.CW /DOCINFO +class. +.LP +To do this, we use the +.CW pdfinfo +macro. +As an example of how it is used, +the identification meta\(hydata attached to this document +was specified using a macro sequence similar to:\(en +.RS +.LD +.fam C +\&.pdfinfo /Title PDF Document Publishing with GNU Troff +\&.pdfinfo /Author Keith Marshall +\&.pdfinfo /Subject How to Exploit PDF Features with GNU Troff +\&.pdfinfo /Keywords groff troff PDF pdfmark +.DE +.RE +Notice that the +.CW pdfinfo +macro is repeated, once for each +.CW /DOCINFO +record to be placed in the document. +In each case, the first argument is the name of the applicable +.CW /DOCINFO +key, which +.EM must +be named with an initial solidus character; +all additional arguments are collected together, +to define the value to be associated with the specified key. +.LP +As is the case with the +.CW pdfview +macro, +.XR docview ), ( +the +.CW /DOCINFO +records specified with the +.CW pdfinfo +macro are not immediately written to the PostScript\*(rg output stream; +they are stored in the same meta\(hydata cache as +.CW /DOCVIEW +specifications, until this cache is explicitly flushed, +by invoking the +.CW pdfsync +macro, +.XR pdfsync ). ( +.NH 2 +.XN -N add-outline -- Creating a Document Outline +.LP +A PDF document outline comprises a table of references, +to \(lqbookmarked\(rq locations within the document. +When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader, +such as Adobe\*(rg Acrobat\*(rg Reader, +this table of \(lqbookmarks\(rq may be displayed in a document outline pane, +or \(lqBookmarks\(rq pane, to the left of the main document view. +Individual references in the outline view may then be selected, +by clicking with the mouse, +to jump directly to the associated marked location in the document view. +.LP +The document outline may be considered as a collection of \(lqhypertext\(rq +references to \(lqbookmarked\(rq locations within the document. +The +.CW pdfmark +macro package provides a single generalised macro, +.CW pdfhref , +for creating and linking to \(lqhypertext\(rq reference marks. +This macro will be described more comprehensively in a later section, +.XR pdfhref ); ( +the description here is restricted to its use for defining document outline entries. +.NH 3 +.XN -N basic-outline -- A Basic Document Outline +.LP +In its most basic form, the document outline comprises a structured list of headings, +each associated with a marked location, or \(lqbookmark\(rq, in the document text, +and a specification for how that marked location should be displayed, +when this bookmark is selected. +.LP +To create a PDF bookmark, the +.CW pdfhref +macro is used, +at the point in the document where the bookmark is to be placed, +in the form +.QP +.fam C +.B ".pdfhref O" +.I level > < +.I "descriptive text ..." +.LP +in which the reference class +.CWB O \& \& \(rq \(lq +stipulates that this is an outline reference. +.LP +Alternatively, for those users who may prefer to think of a document outline +simply as a collection of bookmarks, the +.CW pdfbookmark +macro is also provided \(em indeed, +.CW pdfhref +invokes it, when processing the +.CWB O \& \& \(rq \(lq +reference class operator. +It may be invoked directly, in the form +.QP +.fam C +.B .pdfbookmark +.I level > < +.I "descriptive text ..." +.LP +Irrespective of which of the above macro forms is employed, the +.CWI level > < +argument is required. +It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq +in the outline hierarchy, with one being the topmost level. +Its function may be considered analagous to the +.EM "heading level" +of the document's section headings, +for example, as specified with the +.CW NH +macro, if using the +.CW ms +macros to format the document. +.LP +All further arguments, following the +.CWI level > < +argument, are collected together, to specify the heading text which will appear +in the document's outline view. +Thus, the outline entry for this section of this document, +which has a level three heading, +might be specified as +.QP +.CW +\&.pdfhref O 3 \*(SN A Basic Document Outline +.LP +or, in the alternative form using the +.CW pdfbookmark +macro, as +.QP +.CW +\&.pdfbookmark 3 \*(SN A Basic Document Outline +.NH 3 +.XN Hierarchical Structure in a Document Outline +.LP +When a document outline is created, using the +.CW pdfhref +macro as described in +.\" +.\" Here is an example of how we can temporarily modify the format of +.\" a reference link, in this case to indicate only the section number +.\" of the link target, in the form "section #", (or, if we define +.\" "SECREF.BEGIN" before the call, its content followed by the +.\" section number). +.\" +.\" We first define a macro, which will get the reference data from +.\" pdfhref, as arguments, and will return the formatted output, as we +.\" require it, the string "PDFHREF.TEXT". +.\" +.de SECREF +.while \\n(.$ \{\ +. ie '\\$1'section' \{\ +. if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1 +. ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2 +. rm SECREF.BEGIN +. shift \\n(.$ +. \} +. el .shift +. \} +.. +.\" We now tell "pdfhref" to use our formatting macro, in place of +.\" its builtin default formatter, before we specify the reference. +.\" +.pdfhref F SECREF +.pdfhref L -A , -D basic-outline +.\" +.\" At this point, we would normally revert the "pdfhref" formatter +.\" to use its default, built in macro. However, in this particular +.\" case, we want to use our custom format one more time, before we +.\" revert it, so we will omit the reversion step this time. +.\" +and any entry is added at a nesting level greater than one, +then a hierarchical structure is automatically defined for the outline. +However, as was noted in the simplified +.pdfhref L -D pdfmark-example -- example +in +.pdfhref L -A , -D pdfmark-operator +.\" +.\" And now, we revert to default "pdfhref" formatting behaviour, +.\" by completing the call we delayed above. +.\" +.pdfhref F +.\" +the data required by the +.CW pdfmark +operator to create the outline entry may not be fully defined, +when the outline reference is defined in the +.CW groff +document source. +Specifically, when the outline entry is created, its +.CW /Count +key must be assigned a value equal to the number of its subordinate entries, +at the next inner level of the outline hierarchy; +typically however, +these subordinate entries will be defined +.EM later +in the document source, and the appropriate +.CW /Count +value will be unknown, when defining the parent entry. +.LP +To resolve this paradox, the +.CW pdfhref +macro creates the outline entry in two distinct phases \(em +a destination marker is placed in the PostScript\*(rg output stream immediately, +when the outline reference is defined, +but the actual outline entry is stored in an internal \(lqoutline cache\(rq, +until its subordinate hierarchy has been fully defined; +it can then be inserted in the output stream, with its +.CW /Count +value correctly assigned. +Effectively, to ensure integrity of the document outline structure, +this means that each top level outline entry, and +.EM all +of its subordinates, are retained in the cache, until the +.EM next +top level entry is defined. +.LP +One potential problem, which arises from the use of the \(lqoutline cache\(rq, +is that, at the end of any document formatting run, the last top level outline entry, +and any subordinates defined after it, will remain in the cache, and will +.EM not +be automatically written to the output stream. +To avoid this problem, the user should follow the guidelines given in +.\" +.\" Here is a more conventional example of how to temporarily change +.\" to the format used to display reference links. We will again use +.\" the "SECREF" format, which we defined above, but on this occasion +.\" we will immediately revert to the default format, after the link +.\" has been placed. +.\" +.pdfhref F SECREF +.pdfhref L -D pdfsync -A , +.pdfhref F +.\" +to synchronise the output state with the cache state, +.XR pdfsync ), ( +at the end of the +.CW groff +formatting run. +.NH 3 +.XN -N outline-view -- Associating a Document View with an Outline Reference +.LP +Each \(lqbookmark\(rq entry, in a PDF document outline, +is associated with a specific document view. +When the reader selects any outline entry, +the document view changes to display the document context +associated with that entry. +.LP +The document view specification, +to be associated with any document outline entry, +is established at the time when the outline entry is created. +However, rather than requiring that each individual use of the +.CW pdhref +macro, to create an outline entry, +should include its own view specification, +the actual specification assigned to each entry is derived from +a generalised specification defined in the string +.CW PDFBOOKMARK.VIEW , +together with the setting of the numeric register +.CW PDFHREF.VIEW.LEADING , +which determine the effective view specification as follows:\(en +.QS +.IP \*[= PDFBOOKMARK.VIEW] +Establishes the magnification at which the document will be viewed, +at the location of the \(lqbookmark\(rq; by default, it is defined by +.RS +.QP +.CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u" +.RE +.IP +which displays the associated document view, +with the \(lqbookmark\(rq location positioned at the top of the display window, +and with the magnification set to fit the page width to the width of the window. +.IP \*[= PDFHREF.VIEW.LEADING] +Specifies additional spacing, +to be placed between the top of the display window +and the actual location of the \(lqbookmark\(rq on the displayed page view. +By default, it is set as +.RS +.QP +.CW ".nr PDFHREF.VIEW.LEADING 5.0p" +.RE +.IP +Note that +.CW PDFHREF.VIEW.LEADING +does not represent true \(lqleading\(rq, in the typographical sense, +since any preceding text, set in the specified display space, +will be visible at the top of the document viewing window, +when the reference is selected. +.IP +Also note that the specification of +.CW PDFHREF.VIEW.LEADING +is shared by +.EM all +reference views defined by the +.CW pdfhref +macro; whereas +.CW PDFBOOKMARK.VIEW +is applied exclusively to outline references, +there is no independent +.CW PDFBOOKMARK.VIEW.LEADING +specification. +.QE +.LP +If desired, the view specification may be changed, by redefining the string +.CW PDFBOOKMARK.VIEW , +and possibly also the numeric register +.CW PDFHREF.VIEW.LEADING . +Any alternative definition for +.CW PDFBOOKMARK.VIEW +.EM must +be specified in terms of valid view specification parameters, +as described in the Adobe\*(rg +.pdfmark-manual . +.LP +Note the use of the register +.CW PDFPAGE.Y , +in the default definition of +.CW PDFBOOKMARK.VIEW +above. +This register is computed by +.CW pdfhref , +when creating an outline entry; +it specifies the vertical position of the \(lqbookmark\(rq, +in basic +.CW groff +units, relative to the +.EM bottom +edge of the document page on which it is defined, +and is followed, in the +.CW PDFBOOKMARK.VIEW +definition, by the +.CW grops +.CW u \(rq \(lq +operator, to convert it to PostScript\*(rg units on output. +It may be used in any redefined specification for +.CW PDFBOOKMARK.VIEW , +(or in the analogous definition of +.CW PDFHREF.VIEW , +described in +.XR-NO-PREFIX pdfhref-view ), +but +.EM not +in any other context, +since its value is undefined outside the scope of the +.CW pdfhref +macro. +.LP +Since +.CW PDFPAGE.Y +is computed relative to the +.EM bottom +of the PDF output page, +it is important to ensure that the page length specified to +.CW troff +correctly matches the size of the logical PDF page. +This is most effectively ensured, +by providing +.EM identical +page size specifications to +.CW groff , +.CW grops +and to the PostScript\*(rg to PDF converter employed, +and avoiding any page length changes within the document source. +.LP +Also note that +.CW PDFPAGE.Y +is the only automatically computed \(lqbookmark\(rq location parameter; +if the user redefines +.CW PDFBOOKMARK.VIEW , +and the modified view specification requires any other positional parameters, +then the user +.EM must +ensure that these are computed +.EM before +invoking the +.CW pdfhref +macro. +.NH 3 +.XN -N multipart-outline -- Outlines for Multipart Documents +.LP +When a document outline is created, using the +.CW pdfhref +macro, each reference mark is automatically assigned a name, +composed of a fixed stem followed by a serially generated numeric qualifier. +This ensures that, for each single part document, every outline reference +has a uniquely named destination. +.LP +As the overall size of the PDF document increases, +it may become convenient to divide it into smaller, +individually formatted PostScript\*(rg components, +which are then assembled, in the appropriate order, +to create a composite PDF document. +While this strategy may simplify the overall process of creating and +editing larger documents, it does introduce a problem in creating +an overall document outline, +since each individual PostScript\*(rg component will be assigned +duplicated sequences of \(lqbookmark\(rq names, +with each name ultimately referring to multiple locations in the composite document. +To avoid such reference naming conflicts, the +.CW pdfhref +macro allows the user to specify a \(lqtag\(rq, +which is appended to the automatically generated \(lqbookmark\(rq name; +this may be used as a discriminating mark, to distinguish otherwise +similarly named destinations, in different sections of the composite document. +.LP +To create a \(lqtagged\(rq document outline, +the syntax for invocation of the +.CW pdfhref +macro is modified, by the inclusion of an optional \(lqtag\(rq specification, +.EM before +the nesting level argument, i.e. +.QP +.fam C +.B ".pdfhref O" +.B -T \& [ +.I tag >] < +.I level > < +.I "descriptive text ..." +.LP +The optional +.CWI tag > < +argument may be composed of any characters of the user's choice; +however, its initial character +.EM "must not" +be any decimal digit, and ideally it should be kept short +\(em one or two characters at most. +.LP +By employing a different tag in each section, +the user can ensure that \(lqbookmark\(rq names remain unique, +throughout all the sections of a composite document. +For example, when using the +.CW spdf.tmac +macro package, which adds +.CW pdfmark +capabilities to the standard +.CW ms +package, +.XR using-spdf ), ( +the table of contents is collected into a separate PostScript\*(rg section +from the main body of the document. +In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq, +but in the \(lqTable\~of\~Contents\(rq section, a modified version of the +.CW TC +macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq, +invoking the +.CW pdfhref +macro as +.QP +.CW ".pdfhref O -T T 1 \e\e*[TOC]" +.LP +to tag the associated outline destination name with the single character suffix, +.CW T \(rq. \(lq +Alternatively, as in the case of the basic outline, +.XR basic-outline ), ( +this may equally well be specified as +.QP +.CW ".pdfbookmark -T T 1 \e\e*[TOC]" +.NH 3 +.XN Delegation of the Outline Definition +.LP +Since the most common use of a document outline +is to provide a quick method of navigating through a document, +using active \(lqhypertext\(rq links to chapter and section headings, +it may be convenient to delegate the responsibility of creating the outline +to a higher level macro, which is itself used to +define and format the section headings. +This approach has been adopted in the +.CW spdf.tmac +package, to be described later, +.XR using-spdf ). ( +.LP +When such an approach is adopted, +the user will rarely, if ever, invoke the +.CW pdfhref +macro directly, to create a document outline. +For example, the structure and content of the outline for this document +has been exclusively defined, using a combination of the +.CW NH +macro, from the +.CW ms +package, to establish the structure, and the +.CW XN +macro from +.CW spdf.tmac , +to define the content. +In this case, +the responsibility for invoking the +.CW pdfhref +macro, to create the document outline, +is delegated to the +.CW XN +macro. +.NH 2 +.XN -N pdfhref -- Adding Reference Marks and Links +.LP +.pdfhref F SECREF +.ds SECREF.BEGIN Section +.pdfhref L -D add-outline +.pdfhref F +has shown how the +.CW pdfhref +macro may be used to create a PDF document outline. +While this is undoubtedly a powerful capability, +it is by no means the only trick in the repertoire of this versatile macro. +.LP +The macro name, +.CW pdfhref , +which is a contraction of \(lqPDF HyperText Reference\(rq, +indicates that the general purpose of this macro is to define +.EM any +type of dynamic reference mark, within a PDF document. +Its generalised usage syntax takes the form +.QP +.fam C +.B .pdfhref +.BI class > < +.I "-options ...\&" ] [ +[--] +.I "descriptive text ...\&" ] [ +.LP +where +.CW <\f(CIclass\fP> +represents a required single character argument, +which defines the specific reference operation to be performed, +and may be selected from:\(en +.QS +.IP \*[= O] +Add an entry to the document outline. +This operation has been described earlier, +.XR add-outline ). ( +.IP \*[= M] +Place a \(lqnamed destination\(rq reference mark at the current output position, +in the current PDF document, +.XR mark-dest ). ( +.IP \*[= L] +Insert an active link to a named destination, +.XR link-named ), ( +at the current output position in the current PDF document, +such that when the reader clicks on the link text, +the document view changes to show the location of the named destination. +.IP \*[= W] +Insert an active link to a \(lqweb\(rq resource, +.XR add-weblink ), ( +at the current output position in the current PDF document. +This is effectively the same as using the +.CWB L \& \& \(rq \(lq +operator to establish a link to a named destination in another PDF document, +.XR link-extern ), ( +except that in this case, the destination is specified by a +\(lquniform resource identifier\(rq, or +.CW URI ; +this may represent any Internet or local resource +which can be specified in this manner. +.IP \*[= F] +Specify a user defined macro, to be called by +.CW pdfhref , +when formatting the text in the active region of a link, +.XR set-format ). ( +.IP \*[= I] +Initialise support for +.CW pdfhref +features. +The current +.CW pdfhref +implementation provides only one such feature which requires initialisation +\(em a helper macro which must be attached to a user supplied page trap handler, +in order to support mapping of reference \(lqhot\(hyspots\(rq +which extend through a page transition; +.XR page-trap ). ( +.QE +.NH 3 +.XN Optional Features of the \F[C]pdfhref\F[] Macro +.LP +The behaviour of a number of the +.CW pdfhref +macro operations can be modified, +by including +.EM "option specifiers" \(rq \(lq +after the operation specifying argument, +but +.EM before +any other arguments normally associated with the operation. +In +.EM all +cases, an option is specified by an +.EM "option flag" \(rq, \(lq +comprising an initial hyphen, +followed by one or two option identifying characters. +Additionally, +.EM some +options require +.EM "exactly one" +option argument; +for these options, the argument +.EM must +be specified, and it +.EM must +be separated from the preceding option flag by one or more +.EM spaces , +(tabs +.EM "must not" +be used). +It may be noted that this paradigm for specifying options +is reminiscent of most +.SM +UNIX\(tm +.LG +shells; however, in the case of the +.CW pdfhref +macro, omission of the space separating an option flag from its argument is +.EM never +permitted. +.LP +A list of +.EM all +general purpose options supported by the +.CW pdfhref +macro is given below. +Note that not all options are supported for all +.CW pdfhref +operations; the operations affected by each option are noted in the list. +For +.EM most +operations, if an unsupported option is specified, +it will be silently ignored; however, this behaviour should +not be relied upon. +.LP +The general purpose options, supported by the +.CW pdfhref +macro, are:\(en +.QS +.IP \*[= -N\0 name > <] +Allows the +.CWI name > < +associated with a PDF reference destination +to be defined independently from the following text, +which describes the reference. +This option affects only the +.CWB M \& \& \(rq \(lq +operation of the +.CW pdfhref +macro, +.XR mark-dest ). ( +.IP \*[= -E] +Also used exclusively with the +.CWB M \& \& \(rq \(lq +operator, the +.CWB -E +option causes any specified +.CWI descriptive \& \& \~\c +.CWI text +arguments, +.XR mark-dest ), ( +to be copied, or +.EM echoed , +in the body text of the document, +at the point where the reference mark is defined; +(without the +.CWB -E +option, such +.CWI descriptive \& \& \~\c +.CWI text +will appear +.EM only +at points where links to the reference mark are placed, +and where the standard reference display format, +.XR set-format ), ( +is used). +.IP \*[= -D\0 dest > <] +Specifies the +.CW URI , +or the destination name associated with a PDF active link, +independently of the following text, +which describes the link and demarcates the link \(lqhot\(hyspot\(rq. +This option affects the behaviour of the +.CW pdfhref +macro's +.CWB L \& \& \(rq \(lq +and +.CWB W \& \& \(rq \(lq +operations. +.IP +When used with the +.CWB L \& \& \(rq \(lq +operator, the +.CWI dest > < +argument must specify a PDF \(lqnamed destination\(rq, +as defined using +.CW pdfhref +with the +.CWB M \& \& \(rq \(lq +operator. +.IP +When used with the +.CWB W \& \& \(rq \(lq +operator, +.CWI dest > < +must specify a link destination in the form of a +\(lquniform resource identifier\(rq, or +.CW URI , +.XR add-weblink ). ( +.IP \*[= -F\0 file > <] +When used with the +.CWB L \& \& \(rq \(lq +.CW pdfhref +operator, +.CWI file > < +specifies an external PDF file in which the named destination +for the link reference is defined. +This option +.EM must +be specified with the +.CWB L \& \& \(rq \(lq +operator, +to create a link to a destination in a different PDF document; +when the +.CWB L \& \& \(rq \(lq +operator is used +.EM without +this option, the link destination is assumed to be defined +within the same document. +.IP \*[= -P\0 \(dqprefix\(hytext\(dq > <] +Specifies +.CWI \(dqprefix\(hytext\(dq > < +to be attached to the +.EM start +of the text describing an active PDF document link, +with no intervening space, but without itself being included in the +active area of the link \(lqhot\(hyspot\(rq; +it is effective with the +.CWB L \& \& \(rq \(lq +and +.CWB W \& \& \(rq \(lq +.CW pdfhref +operators. +.IP +Typically, this option would be used to insert punctuation before +the link \(lqhot\(hyspot\(rq. +Thus, there is little reason for the inclusion of spaces in +.CWI \(dqprefix\(hytext\(dq > < ; +however, if such space is required, then the enclosing double quotes +.EM must +be specified, as indicated. +.IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <] +Specifies +.CWI \(dqaffixed\(hytext\(dq > < +to be attached to the +.EM end +of the text describing an active PDF document link, +with no intervening space, but without itself being included in the +active area of the link \(lqhot\(hyspot\(rq; +it is effective with the +.CWB L \& \& \(rq \(lq +and +.CWB W \& \& \(rq \(lq +.CW pdfhref +operators. +.IP +Typically, this option would be used to insert punctuation after +the link \(lqhot\(hyspot\(rq. +Thus, there is little reason for the inclusion of spaces in +.CWI \(dqaffixed\(hytext\(dq > < ; +however, if such space is required, then the enclosing double quotes +.EM must +be specified, as indicated. +.IP \*[= -T\0 tag > <] +When specified with the +.CWB O \& \& \(rq \(lq +operator, +.CWI tag > < +is appended to the \(lqbookmark\(rq name assigned to the generated outline entry. +This option is +.EM required , +to distinguish between the series of \(lqbookmark\(rq names generated in +individual passes of the +.CW groff +formatter, when the final PDF document is to be assembled +from a number of separately formatted components; +.XR multipart-outline ). ( +.IP \*[= -X] +This +.CW pdfhref +option is used with either the +.CWB M \& \& \(rq \(lq +operator, or with the +.CWB L \& \& \(rq \(lq +operator. +.IP +When used with the +.CWB M \& \& \(rq \(lq +operator, +.XR mark-dest ), ( +it ensures that a cross reference record for the marked destination +will be included in the document reference map, +.XR export-map ). ( +.IP +When used with the +.CWB L \& \& \(rq \(lq +operator, +.XR link-named ), ( +it causes the reference to be displayed in the standard cross reference format, +.XR set-format ), ( +but substituting the +.CWI descriptive \& \& \~\c +.CWI text +specified in the +.CW pdfhref \& \(lq +.CW L \(rq +argument list, +for the description specified in the document reference map. +.IP \*[= --] +Marks the end of the option specifiers. +This may be used with all +.CW pdfhref +operations which accept options, to prevent +.CW pdfhref +from interpreting any following arguments as option specifiers, +even if they would otherwise be interpreted as such. +It is also useful when the argument list to +.CW pdfhref +contains special characters \(em any special character, +which is not legal in a +.CW groff +macro name, will cause a parsing error, if +.CW pdfhref +attempts to match it as a possible option flag; +using the +.CW -- \(rq \(lq +flag prevents this, so suppressing the +.CW groff +warning message, which would otherwise ensue. +.IP +Using this flag after +.EM all +sequences of macro options is recommended, +even when it is not strictly necessary, +if only for the entirely cosmetic benefit of visually separating +the main argument list from the sequence of preceding options. +.QE +.LP +In addition to the +.CW pdfhref +options listed above, a supplementary set of two character options are defined. +These supplementary options, listed below, are intended for use with the +.CWB L \& \& \(rq \(lq +operator, in conjunction with the +.CWB -F \& \& \~\c +.CWBI file > < +option, to specify alternate file names, +in formats compatible with the file naming conventions +of alternate operating systems; +they will be silently ignored, if used in any other context. +.LP +The supported alternate file name options, +which are ignored if the +.CWB -F \& \& \~\c +.CWBI file > < +option is not specified, are:\(en +.QS +.IP \*[= -DF\0 dos\(hyfile > <] +Specifies the name of the file in which a link destination is defined, +using the file naming semantics of the +.CW MS\(hyDOS \*(rg +operating system. +When the PDF document is read on a machine +where the operating system uses the +.CW MS\(hyDOS \*(rg +file system, then +.CWI dos\(hyfile > < +is used as the name of the file containing the reference destination, +overriding the +.CWI file > < +argument specified with the +.CWB -F +option. +.IP \*[= -MF\0 mac\(hyfile > <] +Specifies the name of the file in which a link destination is defined, +using the file naming semantics of the +.CW Apple \*(rg +.CW Macintosh \*(rg +operating system. +When the PDF document is read on a machine +where the operating system uses the +.CW Macintosh \*(rg +file system, then +.CWI mac\(hyfile > < +is used as the name of the file containing the reference destination, +overriding the +.CWI file > < +argument specified with the +.CWB -F +option. +.IP \*[= -UF\0 unix\(hyfile > <] +Specifies the name of the file in which a link destination is defined, +using the file naming semantics of the +.CW UNIX \(tm +operating system. +When the PDF document is read on a machine +where the operating system uses +.CW POSIX +file naming semantics, then +.CWI unix\(hyfile > < +is used as the name of the file containing the reference destination, +overriding the +.CWI file > < +argument specified with the +.CWB -F +option. +.IP \*[= -WF\0 win\(hyfile > <] +Specifies the name of the file in which a link destination is defined, +using the file naming semantics of the +.CW MS\(hyWindows \*(rg +32\(hybit operating system. +When the PDF document is read on a machine +where the operating system uses any of the +.CW MS\(hyWindows \*(rg +file systems, with long file name support, then +.CWI win\(hyfile > < +is used as the name of the file containing the reference destination, +overriding the +.CWI file > < +argument specified with the +.CWB -F +option. +.QE +.NH 3 +.XN -N mark-dest -- Marking a Reference Destination +.LP +The +.CW pdfhref +macro may be used to create active links to any Internet resource, +specified by its +.CW URI , +or to any \(lqnamed destination\(rq, +either within the same document, or in another PDF document. +Although the PDF specification allows link destinations to be defined +in terms of a page number, and an associated view specification, +this style of reference is not currently supported by the +.CW pdfhref +macro, because it is not possible to adequately bind the specification +for the destination with the intended reference context. +.LP +References to Internet resources are interpreted in accordance with the +.CW W3C +standard for defining a +.CW URI ; +hence the only prerequisite, for creating a link to any Internet resource, +is that the +.CW URI +be properly specified, when declaring the reference; +.XR add-weblink ). ( +In the case of references to \(lqnamed destinations\(rq in PDF documents, +however, it is necessary to provide a mechanism for creating such +\(lqnamed destinations\(rq. +This may be accomplished, by invoking the +.CW pdfhref +macro in the form +.QP +.fam C +.B ".pdfhref M" +.B -N \& [ +.I name >] < +.B -X ] [ +.B -E ] [ +.I "descriptive text ...\&" ] [ +.LP +This creates a \(lqnamed destination\(rq reference mark, with its name specified by +.CWI name > < , +or, if the +.CWB -N +option is not specified, by the first word of +.CWI descriptive \& \& \~\c +.CWI text \& \& ; +(note that this imposes the restriction that, +if the +.CWB -N +option is omitted, then +.EM "at least" +one word of +.CWI descriptive \& \& \~\c +.CWI text +.EM must +be specified). +Additionally, a reference view will be automatically defined, +and associated with the reference mark, +.XR pdfhref-view ), ( +.\" and, if any +.\" .CWI descriptive +.\" .CWI text +.\" is specified, or the +and, if the +.CWB -X +option is specified, and no document cross reference map has been imported, +.XR import-map ), ( +then a cross reference mapping record, +.XR export-map ), ( +will be written to the +.CW stdout +stream; +this may be captured, and subsequently used to generate a cross reference map +for the document, +.XR create-map ). ( +.LP +When a \(lqnamed destination\(rq reference mark is created, using the +.CW pdfhref +macro's +.CWB M \& \& \(rq \(lq +operator, there is normally no visible effect in the formatted document; any +.CWI descriptive \& \& \~\c +.CWI text +which is specified will simply be stored in the cross reference map, +for use when a link to the reference mark is created. +This default behaviour may be changed, by specifying the +.CWB -E +option, which causes any specified +.CWI descriptive \& \& \~\c +.CWI text +to be \(lqechoed\(rq in the document text, +at the point where the reference mark is placed, +in addition to its inclusion in the cross reference map. +.NH 4 +.XN -N export-map -- Mapping a Destination for Cross Referencing +.LP +Effective cross referencing of +.EM any +document formatted by +.CW groff +requires multiple pass formatting. +Details of how this multiple pass formatting may be accomplished, +when working with the +.CW pdfmark +macros, will be discussed later, +.XR do-xref ); ( +at this stage, the discussion will be restricted to the initial preparation, +which is required at the time when the cross reference destinations are defined. +.LP +The first stage, in the process of cross referencing a document, +is the generation of a cross reference map. +Again, the details of +.EM how +the cross reference map is generated will be discussed in +.pdfhref F SECREF L -D do-xref -A ; +.pdfhref F +however, it is important to recognise that +.EM what +content is included in the cross reference map is established +when the reference destination is defined \(em it is derived +from the reference data exported on the +.CW stderr +stream by the +.CW pdfhref +macro, when it is invoked with the +.CWB M \& \& \(rq \(lq +operator, and is controlled by whatever definition of the string +.CW PDFHREF.INFO +is in effect, when the +.CW pdfhref +macro is invoked. +.LP +The initial default setting of +.CW PDFHREF.INFO +is +.QP +.CW ".ds PDFHREF.INFO page \e\en% \e\e$*" +.LP +which ensures that the cross reference map will contain +at least a page number reference, supplemented by any +.CWI descriptive \& \& \~\c +.CWI text +which is specified for the reference mark, as defined by the +.CW pdfhref +macro, with its +.CWB M \& \& \(rq \(lq +operator; this may be redefined by the user, +to export additional cross reference information, +or to modify the default format for cross reference links, +.XR set-format ). ( +.NH 4 +.XN -N pdfhref-view -- Associating a Document View with a Reference Mark +.LP +In the same manner as each document outline reference, defined by the +.CW pdfhref +macro with the +.CWB O \& \& \(rq \(lq +operator, +.XR add-outline ), ( +has a specific document view associated with it, +each reference destination marked by +.CW pdfhref +with the +.CWB M \& \& \(rq \(lq +operator, requires an associated document view specification. +.LP +The mechanism whereby a document view is associated with a reference mark +is entirely analogous to that employed for outline references, +.XR outline-view ), ( +except that the +.CW PDFHREF.VIEW +string specification is used, in place of the +.CW PDFBOOKMARK.VIEW +specification. +Thus, the reference view is defined in terms of:\(en +.QS +.IP \*[= PDFHREF.VIEW] +A string, +establishing the position of the reference mark within the viewing window, +and the magnification at which the document will be viewed, +at the location of the marked reference destination; +by default, it is defined by +.RS +.QP +.CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u" +.RE +.IP +which displays the reference destination at the top of the viewing window, +with the magnification set to fit the page width to the width of the window. +.IP \*[= PDFHREF.VIEW.LEADING] +A numeric register, +specifying additional spacing, to be placed between the top of the display +window and the actual position at which the location of the reference +destination appears within the window. +This register is shared with the view specification for outline references, +and thus has the same default initial setting, +.RS +.QP +.CW ".nr PDFHREF.VIEW.LEADING 5.0p" +.RE +.IP +as in the case of outline reference views. +.IP +Again, notice that +.CW PDFHREF.VIEW.LEADING +does not represent true typographic \(lqleading\(rq, +since any preceding text, set in the specified display space, +will be visible at the top of the viewing window, +when the reference is selected. +.QE +.LP +Just as the view associated with outline references may be changed, +by redefining +.CW PDFBOOKMARK.VIEW , +so the view associated with marked reference destinations may be changed, +by redefining +.CW PDFHREF.VIEW , +and, if desired, +.CW PDFHREF.VIEW.LEADING ; +such changes will become effective for all reference destinations marked +.EM after +these definitions are changed. +(Notice that, since the specification of +.CW PDFHREF.VIEW.LEADING +is shared by both outline reference views and marked reference views, +if it is changed, then the views for +.EM both +reference types are changed accordingly). +.LP +It may again be noted, that the +.CW PDFPAGE.Y +register is used in the definition of +.CW PDFHREF.VIEW , +just as it is in the definition of +.CW PDFBOOKMARK.VIEW ; +all comments in +.pdfhref F SECREF L -D outline-view +.pdfhref F +relating to its use, and indeed to page position computations in general, +apply equally to marked reference views and to outline reference views. +.NH 3 +.XN -N link-named -- Linking to a Marked Reference Destination +.LP +Any named destination, such as those marked by the +.CW pdfhref +macro, using it's +.CWB M \& \& \(rq \(lq +operator, may be referred to from any point in +.EM any +PDF document, using an +.EM "active link" ; +such active links are created by again using the +.CW pdfhref +macro, but in this case, with the +.CWB L \& \& \(rq \(lq +operator. +This operator provides support for two distinct cases, +depending on whether the reference destination is defined in +the same document as the link, +.XR link-intern ), ( +or is defined as a named destination in a different PDF document, +.XR link-extern ). ( +.NH 4 +.XN -N link-intern -- References within a Single PDF Document +.LP +The general syntactic form for invoking the +.CW pdfhref +macro, +when creating a link to a named destination within the same PDF document is +.QP +.fam C +.B .pdfhref +.B L +.B -D \& [ +.BI dest-name >] < +.B -P \& [ +.BI prefix-text >] < +.B -A \& [ +.BI affixed-text >] < +\e +.br +\0\0\0 +.B -X ] [ +.B -- ] [ +.I "descriptive text ...\&" ] [ +.LP +where +.CWI dest-name > < +specifies the name of the link destination, +as specified using the +.CW pdfhref +.CWB M \& \& \(rq \(lq +operation; (it may be defined either earlier in the document, +to create a backward reference, or later, to create a forward reference). +.\" +.\" Here's a example of how to add an iconic annotation. +.\" +.\".pdfnote -T "Internal Cross References" \ +.\" This description is rather terse, and could benefit from \ +.\" the inclusion of an example. +.LP +If any +.CWI descriptive \& \& \~\c +.CWI text +arguments are specified, then they will be inserted into the +.CW groff +output stream, to define the text appearing in the \(lqhot\(hyspot\(rq +region of the link; +this will be printed in the link colour specified by the string, +.CW PDFHREF.TEXT.COLOUR , +which is described in +.XR-NO-PREFIX set-colour . +If the +.CWB -X +option is also specified, then the +.CWI descriptive \& \& \~\c +.CWI text +will be augmented, by prefacing it with page and section number indicators, +in accordance with the reference formatting rules which are in effect, +.XR set-format ); ( +such indicators will be included within the active link region, +and will also be printed in the link colour. +.LP +Note that +.EM either +the +.CWB -D \& \& \~\c +.CWBI dest\(hyname > < +option, +.EM or +the +.CWI descriptive \& \& \~\c +.CWI text +arguments, +.EM "but not both" , +may be omitted. +If the +.CWB -D \& \& \~\c +.CWBI dest\(hyname > < +option is omitted, then the first word of +.CWI descriptive \& \& \~\c +.CWI text \& \& , +i.e.\~all text up to but not including the first space, +will be interpreted as the +.CWBI dest\(hyname > < +for the link; this text will also appear in the running text of the document, +within the active region of the link. +Alternatively, if the +.CWB -D \& \& \~\c +.CWBI dest\(hyname > < +option +.EM is +specified, and +.CWI descriptive \& \& \~\c +.CWI text +is not, +then the running text which defines the reference, +and its active region, +will be derived from the reference description which is specified +when the named destination is marked, +.XR mark-dest ), ( +and will be formatted according to the reference formatting rules +which are in effect, when the reference is placed, +.XR set-format ); ( +in this case, it is not necessary to specify the +.CWB -X +option to activate automatic formatting of the reference \(em it is implied, +by the omission of all +.CWI descriptive \& \& \~\c +.CWI text +arguments. +.LP +The +.CWB -P \& \& \~\c +.CWBI prefix\(hytext > < +and +.CWB -A \& \& \~\c +.CWBI affixed\(hytext > < +options may be used to specify additional text +which will be placed before and after the linked text respectively, +with no intervening space. +Such prefixed and affixed text will be printed in the normal text colour, +and will not be included within the active region of the link. +This feature is mostly useful for creating parenthetical references, +or for placing punctuation adjacent to, +but not included within, +the text which defines the active region of the link. +.LP +The operation of the +.CW pdfhref +macro, when used with its +.CWB L \& \& \(rq \(lq +operator to place a link to a named PDF destination, +may best be illustrated by an example. +However, since the appearance of the link will be influenced by +factors established when the named destination is marked, +.XR mark-dest ), ( +and also by the formatting rules in effect when the link is placed, +the presentation of a suitable exanple will be deferred, +until the formatting mechanism has been explained, +.XR set-format ). ( +.NH 4 +.XN -N link-extern -- References to Destinations in Other PDF Documents +.LP +The +.CW pdfhref +macro's +.CWB L \& \& \(rq \(lq +operator is not restricted to creating reference links +within a single PDF document. +When the link destination is defined in a different document, +then the syntactic form for invoking +.CW pdfhref +is modified, by the addition of options to specify the +name and location of the PDF file in which the destination is defined. +Thus, the extended +.CW pdfhref +syntactic form becomes +.QP +.fam C +.B .pdfhref +.B L +.B -F +.BI file > < +.B -D \& [ +.BI dest-name >] < +\e +.br +\0\0\0 +.B -DF \& [ +.BI dos-file >] < +.B -MF \& [ +.BI mac-file >] < +.B -UF \& [ +.BI unix-file >] < +\e +.br +\0\0\0 +.B -WF \& [ +.BI win-file >] < +.B -P \& [ +.BI prefix-text >] < +.B -A \& [ +.BI affixed-text >] < +\e +.br +\0\0\0 +.B -X ] [ +.B -- ] [ +.I "descriptive text ...\&" ] [ +.LP +where the +.CWB -F \& \& \~\c +.CWBI file > < +option serves +.EM two +purposes: it both indicates to the +.CW pdfhref +macro that the specified reference destination +is defined in an external PDF file, +and it also specifies the normal path name, +which is to be used to locate this file, +when a user selects the reference. +.LP +In addition to the +.CWB -F \& \& \~\c +.CWBI file > < +option, which +.EM must +be specified when referring to a destination in an external PDF file, +the +.CWB -DF \& \& \~\c +.CWBI dos\(hyfile > < , +.CWB -MF \& \& \~\c +.CWBI mac\(hyfile > < , +.CWB -UF \& \& \~\c +.CWBI unix\(hyfile > < +and +.CWB -WF \& \& \~\c +.CWBI win\(hyfile > < +options may be used to specify the location of the file +containing the reference destination, +in a variety of operating system dependent formats. +These options assign their arguments to the +.CW /DosFile , +.CW /MacFile , +.CW /UnixFile +and +.CW /WinFile +keys of the generated +.CW pdfmark +respectively; thus when any of these options are specified, +.EM "in addition to" +the +.CWB -F \& \& \~\c +.CWBI file > < +option, and the document is read on the appropriate operating systems, +then the path names specified by +.CWBI dos\(hyfile > < , +.CWBI mac\(hyfile > < , +.CWBI unix\(hyfile > < +and +.CWBI win\(hyfile > < +will be searched, +.EM instead +of the path name specified by +.CWBI file > < , +for each of the +.CW MS\(hyDOS \*(rg, +.CW Apple \*(rg +.CW Macintosh \*(rg, +.CW UNIX \(tm +and +.CW MS\(hyWindows \*(rg +operating systems, respectively; see the +.pdfmark-manual , +for further details. +.LP +Other than the use of these additional options, +which specify that the reference destination is in an external PDF file, +the behaviour of the +.CW pdfhref +.CWB L \& \& \(rq \(lq +operator, with the +.CWB -F \& \& \~\c +.CWBI file > < +option, remains identical to its behaviour +.EM without +this option, +.XR link-intern ), ( +with respect to the interpretation of other options, +the handling of the +.CWI descriptive \& \& \~\c +.CWI text +arguments, and the formatting of the displayed reference. +.LP +Once again, since the appearance of the reference is determined by +factors specified in the document reference map, +and also by the formatting rules in effect when the reference is placed, +the presentation of an example of the placing of +a reference to an external destination will be deferred, +until the formatting mechanism has been explained, +.XR set-format ). ( +.NH 3 +.XN -N add-weblink -- Linking to Internet Resources +.LP +In addition to supporting the creation of cross references +to named destinations in PDF documents, the +.CW pdfhref +macro also has the capability to create active links to Internet resources, +or indeed to +.EM any +resource which may be specified by a Uniform Resource Identifier, +(which is usually abbreviated to the acronym \(lqURI\(rq, +and sometimes also referred to as a Uniform Resource Locator, +or \(lqURL\(rq). +.LP +Since the mechanism for creating a link to a URI differs somewhat +from that for creating PDF references, the +.CW pdfhref +macro is invoked with the +.CWB W \& \& \(rq \(lq +(for \(lqweb\(hylink\(rq) operator, rather than the +.CWB L \& \& \(rq \(lq +operator; nevertheless, the invocation syntax is similar, having the form +.QP +.fam C +.B .pdfhref +.B W +.B -D \& [ +.BI URI >] < +.B -P \& [ +.BI prefix-text >] < +.B -A \& [ +.BI affixed-text >] < +\e +.br +\0\0\0 +.B -- ] [ +.I "descriptive text ...\&" +.LP +where +.NH 3 +.XN -N set-format -- Establishing a Format for References +.LP +There are two principal aspects to be addressed, +when defining the format to be used when displaying references. +Firstly, it is desirable to provide a visual cue, +to indicate that the text describing the reference is imbued +with special properties \(em it is dynamically linked to the reference +destination \(em and secondly, the textual content should +describe where the link leads, and ideally, +it should also describe the content of the reference destination. +.LP +The visual cue, +that a text region defines a dynamically linked reference, +is most commonly provided by printing the text within the active +region in a distinctive colour. +This technique will be employed automatically by the +.CW pdfhref +macro \(em +.XR set-colour +\(em unless the user specifically chooses to adopt, and implement, +some alternative strategy. +.NH 4 +.XN -N set-colour -- Using Colour to Demarcate Link Regions +.LP +Typically, when a PDF document contains +.EM active +references to other locations, either within the same document, +or even in other documents, or on the World Wide Web, +it is usually desirable to make the regions +where these active links are placed stand out from the surrounding text. +.NH 4 +.XN -N user-format -- Specifying Reference Text Explicitly +.NH 4 +.XN -N auto-format -- Using Automatically Formatted Reference Text +.NH 4 +.XN -N custom-format -- Customising Automatically Formatted Reference Text +.LP +It is incumbent on the user, +if employing automatic formatting of the displayed reference, +.XR set-format ), ( +to ensure that an appropriate reference definition +is created for the reference destination, +and is included in the reference map for the document +in which the reference will appear; +thus, it may be easiest to +.EM always +use manual formatting for external references. +.NH 3 +.XN Problematic Links +.LP +Irrespective of whether a +.CW pdfhref +reference is placed using the +.CWB L \& \& \(rq \(lq +operator, or the +.CWB W \& \& \(rq \(lq +operator, there may be occasions when the resulting link +does function as expected. +A number of scenarios, which are known to be troublesome, +are described below. +.NH 4 +.XN -N page-trap -- Links with a Page Transition in the Active Region +.LP +When a link is placed near the bottom of a page, +it is possible that its active region, or \(lqhot\(hyspot\(rq, +may extend on to the next page. +In this situation, a page trap macro is required +to intercept the page transition, and to restart the mapping of +the \(lqhot\(hyspot\(rq boundary on the new page. +.LP +The +.CW pdfmark +macro package includes a suitable page trap macro, to satisfy this requirement. +However, to avoid pre\(hyempting any other requirement the user may have for +a page transition trap, this is +.EM not +installed as an active page trap, +unless explicitly requested by the user. +.LP +To enable proper handling of page transitions, +which occur within the active regions of reference links, +the user should:\(en +.QS +.nr ITEM 0 1 +.IP \n+[ITEM]. +Define a page transition macro, to provide whatever features may be required, +when a page transition occurs \(em e.g.\& printing footnotes, +adding page footers and headers, etc. +This macro should end by setting the output position at the correct +vertical page offset, where the printing of running text is to restart, +following the page transition. +.IP \n+[ITEM]. +Plant a trap to invoke this macro, at the appropriate vertical position +marking the end of normal running text on each page. +.KS +.IP \n+[ITEM]. +Initialise the +.CW pdfhref +hook into this page transition trap, by invoking +.RS +.IP +.fam C +.B "pdfhref I -PT" +.BI macro-name > < +.LP +where +.CWBI macro-name > < +is the name of the user supplied page trap macro, +to ensure that +.CW pdfhref +will correctly restart mapping of active link regions, +at the start of each new page. +.KE +.RE +.QE +.LP +It may be observed that this initialisation of the +.CW pdfhref +page transition hook is, typically, required only once +.EM before +document formatting begins. +Users of document formatting macro packages may reasonably expect that +this initialisation should be performed by the macro package itself. +Thus, writers of such macro packages which include +.CW pdfmark +bindings, should provide appropriate initialisation, +so relieving the end user of this responsibility. +The following example, abstracted from the sample +.CW ms +binding package, +.CW spdf.tmac , +illustrates how this may be accomplished:\(en +.DS I +.CW +\&.\e" groff "ms" provides the "pg@bottom" macro, which has already +\&.\e" been installed as a page transition trap. To ensure proper +\&.\e" mapping of "pdfhref" links which overflow the bottom of any +\&.\e" page, we need to install the "pdfhref" page transition hook, +\&.\e" as an addendum to this macro. +\&. +\&.pdfhref I -PT pg@bottom +.DE +.NH 2 +.XN -N add-note -- Annotating a PDF Document using Pop-Up Notes +.NH 2 +.XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts +.LP +It has been noted previously, that the +.CW pdfview +macro, +.XR docview ), ( +the +.CW pdfinfo +macro, +.XR docinfo ), ( +and the +.CW pdfhref +macro, when used to create a document outline, +.XR add-outline ), ( +do not immediately write their +.CW pdfmark +output to the PostScript\*(rg data stream; +instead, they cache their output, in a +.CW groff +diversion, in the case of the +.CW pdfview +and +.CW pdfinfo +macros, or in an ordered collection of strings and numeric registers, +in the case of the document outline, +until a more appropriate time for copying it out. +In the case of +.CW pdfview +and +.CW pdfinfo +\(lqmeta\(hydata\(rq, +this \(lqmore appropriate time\(rq is explicitly chosen by the user; +in the case of document outline data, +.EM some +cached data may be implicitly written out as the document outline is compiled, +but there will +.EM always +be some remaining data, which must be explicitly flushed out, before the +.CW groff +formatting process is allowed to complete. +.LP +To allow the user to choose when cached +.CW pdfmark +data is to be flushed to the output stream, the +.CW pdfmark +macro package provides the +.CW pdfsync +macro, (to synchronise the cache and output states). +In its simplest form, it is invoked without arguments, i.e. +.QP +.fam C +.B .pdfsync +.LP +This form of invocation ensures that +.EM both +the \(lqmeta\(hydata cache\(rq, containing +.CW pdfview +and +.CW pdfinfo +data, +.EM and +the \(lqoutline cache\(rq, +containing any previously uncommitted document outline data, +are flushed; ideally, this should be included in a +.CW groff +\(lqend macro\(rq, to ensure that +.EM both +caches are flushed, before +.CW groff +terminates. +.LP +Occasionally, +it may be desirable to flush either the \(lqmeta\(hydata cache\(rq, +without affecting the \(lqoutline cache\(rq, or vice\(hyversa, +at a user specified time, prior to reaching the end of the document. +This may be accomplished, by invoking the +.CW pdfsync +macro with an argument, i.e. +.QP +.fam C +.B ".pdfsync M" +.LP +to flush only the \(lqmeta\(hydata cache\(rq, or +.QP +.fam C +.B ".pdfsync O" +.LP +to flush only the \(lqoutline cache\(rq. +.LP +The \(lqmeta\(hydata cache\(rq can normally be safely flushed +in this manner, at any time +.EM after +output of the first page has started; +(it may cause formatting problems, +most notably the appearance of unwanted white space, if flushed earlier, +or indeed, if flushed immediately after a page transition, +but before the output of the content on the new page has commenced). +Caution is required, however, when explicitly flushing the +\(lqoutline cache\(rq, since if the outline is to be +subsequently extended, then the first outline entry after flushing +.EM must +be specified at level 1. +Nevertheless, such explict flushing may occasionally be necessary; +for example, the +.CW TC +macro in the +.CW spdf.tmac +package, +.XR using-spdf ), ( +invokes +.CW ".pdfsync\ O" \(rq \(lq +to ensure that the outline for the \(lqbody\(rq section of the document +is terminated, +.EM before +it commences the formatting of the table of contents section. +.bp +.NH 1 +.XN -N pdf-layout -- PDF Document Layout +.LP +The +.CW pdfmark +macros described in the preceding section, +.XR pdf-features ), ( +provide no inherent document formatting capability of their own. +However, +they may be used in conjunction with any other +.CW groff +macro package of the user's choice, +to add such capability. +.LP +In preparing this document, the standard +.CW ms +macro package, supplied as a component of the GNU Troff distribution, +has been employed. +To facilitate the use of the +.CW pdfmark +macros with the +.CW ms +macros, +a binding macro package, +.CW spdf.tmac , +has been created. +The use of this binding macro package is described in the following section, +.XR using-spdf ); ( +it may also serve as an example to users of other standard +.CW groff +macro packages, +as to how the +.CW pdfmark +macros may be employed with their chosen primary macro package. +.NH 2 +.XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package +.LP +The use of the binding macro package, +.CW spdf.tmac , +allows for the use of the +.CW pdfmark +macros in conjunction with the +.CW ms +macros, +simply by issuing a +.CW groff +command of the form +.QP +.fam C +groff -Tps +.B -mspdf +.I "-options ...\&" ] [ +file(s) ... +.LP +When using the +.CW spdf.tmac +package, the +.CW groff +input files may be marked up using any of the standard +.CW ms +macros to specify document formatting, +while PDF features may be added, +using any of the +.CW pdfmark +macros described previously, +.XR pdf-features ). ( +Additionally, +.CW spdf.tmac +defines a number of convenient extensions to the +.CW ms +macro set, to better accomodate the use of PDF features within the +.CW ms +formatting framework, +and to address a number of +.CW ms +document layout issues, +which require special handling when producing PDF documents. +These additional macros, +and the issues they are intended to address, +are described below. +.NH 3 +.XN \F[C]ms\F[] Section Headings in PDF Documents +.LP +Traditionally, +.CW ms +provides the +.CW NH +and +.CW SH +macros, to specify section headings. +However, +there is no standard mechanism for generating a +table of contents entry based on the text of the section heading; +neither is there any recognised standard method for establishing a +cross reference link to the section. +.LP +To address this +.CW ms +limitation, +.CW spdf.tmac +defines the +.CW XN +macro, +.XR xn-macro ), ( +to be used in conjunction with the +.CW NH +macro. +.NH 4 +.XN -N xn-macro -- The \F[C]XN\F[] Macro +.NH 1 +.XN The PDF Publishing Process +.NH 2 +.XN -N do-xref -- Resolving Cross References +.NH 3 +.XN -N create-map -- Creating a Document Reference Map +.NH 3 +.XN -N import-map -- Deploying a Document Reference Map +.TC |