Portable Document FormatPublishing with GNU TroffKeith Marshall<keith.d.marshall@ntlworld.com>A G N U M A N U A L
-i-Table of Contents1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. Exploiting PDF Document Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.1. The pdfmark Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2. Selecting an Initial Document View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.3. Adding Document Identification Meta-Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4. Creating a Document Outline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4.1. A Basic Document Outline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4.2. Hierarchical Structure in a Document Outline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.4.3. Associating a Document View with an Outline Reference. . . . . . . . . . . . . . . . . . . . . . . . . . 52.4.4. Folding the Outline to Conceal Less Significant Headings. . . . . . . . . . . . . . . . . . . . . . . . . . 62.4.5. Outlines for Multipart Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4.6. Delegation of the Outline Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.5. Adding Reference Marks and Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.5.1. Optional Features of the pdfhref Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.5.2. Marking a Reference Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.5.2.1. Mapping a Destination for Cross Referencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.5.2.2. Associating a Document View with a Reference Mark. . . . . . . . . . . . . . . . . . . . . . . . . 112.5.3. Linking to a Marked Reference Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5.3.1. References within a Single PDF Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5.3.2. References to Destinations in Other PDF Documents. . . . . . . . . . . . . . . . . . . . . . . . . . 122.5.4. Linking to Internet Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.5.5. Establishing a Format for References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.5.5.1. Using Colour to Demarcate Link Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.5.5.2. Specifying Reference Text Explicitly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5.5.3. Using Automatically Formatted Reference Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5.5.4. Customizing Automatically Formatted Reference Text. . . . . . . . . . . . . . . . . . . . . . . . . 142.5.6. Problematic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5.6.1. Links with a Page Transition in the Active Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6. Annotating a PDF Document using Pop-Up Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.7. Synchronizing Output and pdfmark Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153. PDF Document Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1. Using pdfmark Macros with the ms Macro Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1.1. ms Section Headings in PDF Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1.1.1. The XN Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164. The PDF Publishing Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1. Resolving Cross References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1.1. Creating a Document Reference Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1.2. Deploying a Document Reference Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1. IntroductionIt might appear that it is a fairly simple matter to produce documents in Adobe® “Portable Document Format”,commonly known as PDF, using GNU Troff (groff) as the document formatter. Indeed, groff’s default outputformat is the native Adobe® PostScript® format, which PDF producers such as Adobe® Acrobat® Distiller,® orGhostScript, expect as their input format. Thus, the PDF production process would seem to entail simply formatting thedocument source with groff, to produce a PostScript® version of the document, which can subsequently be processedby Acrobat® Distiller® or GhostScript, to generate the final PDF document.For many PDF production requirements, the production cycle described above may be sufficient. However, this is alimited PDF production method, in which the resultant PDF document represents no more than an on screen image ofthe printed form of the document, if groff’s PostScript® output were printed directly.The Portable Document Format provides a number of features, which significantly enhance the experience of reading adocument on screen, but which are of little or no value to a document which is merely printed. It is possible to exploitthese PDF features, which are described in the Adobe®“pdfmark Reference Manual”, with some refinement of thesimple PDF production method, provided appropriate “feature implementing” instructions can be embedded into groff’s PostScript® rendering of the document. This, of course, implies that the original document source, whichgroff will process to generate the PostScript® description of the document, must include appropriate markup toexploit the desired PDF features. It is this preparation of the groff document source to exploit a number of thesefeatures, which provides the principal focus of this document.The markup techniques to be described have been utilized in the production of the PDF version of this document itself.This has been formatted using groff’s ms macro package; thus, usage examples may be found in the document sourcefile, pdfmark.ms, to which comments have been added, to help identify appropriate markup examples forimplementing PDF features, such as:–•Selecting a default document view, which defines how the document will appear when opened in thereader application; for example, when this document is opened in Acrobat® Reader, it should displaythe top of the cover sheet, in the document view pane, while a document outline should appear to theleft, in the “Bookmarks” pane.•Adding document identification “meta-data”, which can be accessed, in Acrobat® Reader, byinspecting the “File/Document Properties/Summary”.•Creating a document outline, which will be displayed in the “Bookmarks” pane of Acrobat® Reader,such that readers may quickly navigate to any section of the document, simply by clicking on theassociated heading in the outline view.•Embedding active links in the body of the document, such that readers may quickly navigate torelated material at another location within the same document, or in another PDF document, or evento a related Internet resource, specified by its URI.•Adding annotations, in the form of “sticky notes”, at strategic points within the PDF document.All of the techniques described have been tested on both GNU/Linux, and on Microsoft® Windows™2000 operatingplatforms, using groff 1.19.1,1 in association with AFPL GhostScript 8.14.2 Other tools employed, whichshould be readily available on any Unix™ or GNU/Linux system, are sed, awk and make, together with anappropriate text editor, for creating and marking up the groff input files. These additional utilities are not provided,as standard, on the Microsoft® Windows™ platform, but several third party implementations are available. Some worthconsidering include the MKS® Toolkit,3 Cygwin,4 or MSYS.5 This list is by no means exhaustive, and should in no waybe construed as an endorsement of any of these packages, nor to imply that other similar packages, which may beavailable, are in any way inferior to them. 1.Later versions should, and some earlier versions may, be equally suitable. See http://www.gnu.org/software/groff for informationand availability of the latest version.2.Again, other versions may be suitable. See http://ghostscript.com for information and availability.3.A commercial offering; see http://mkssoftware.com/products/tk/default.asp for information.4.A free but comprehensive POSIX emulation environment and Unix™ toolkit for 32-bit Microsoft® Windows™ platforms; seehttp://cygwin.com for information and download.5.Another free, but minimal suite of common Unix™ tools for 32-bit Microsoft®Windows™, available for download fromhttps://mingw.osdn.io;it does include those tools listed above, and is the package which was actually used when performing theWindows™2000 platform tests referred to in the text.
-2-2. Exploiting PDF Document FeaturesTo establish a consistent framework for adding PDF features, a groff macro package, named pdfmark.tmac, hasbeen provided. Thus, to incorporate PDF features in a document, the appropriate macro calls, as described below, maybe placed in the groff document source, which should then be processed with a groff command of the form6groff [-Tps|-Tpdf] [-m name] -m pdfmark [-options ...] file ...It may be noted that the pdfmark macros have no dependencies on, and no known conflicts with, any other groffmacro package; thus, users are free to use any other macro package, of their choice, to format their documents, whilealso using the pdfmark macros to add PDF features.2.1. The pdfmark OperatorAll PDF features are implemented by embedding instances of the pdfmark operator, as described in the Adobe®“pdfmark Reference Manual”, into groff’s PostScript® output stream. To facilitate the use of this operator, thepdfmark macro package defines the primitive pdfmark macro; it simply emits its argument list, as arguments to apdfmark operator, in the PostScript® output stream.To illustrate the use of the pdfmark macro, the following is a much simplified example of how a bookmark may beadded to a PDF document outline.pdfmark \/Count 2 \/Title (An Example of a Bookmark with Two Children) \/View [/FitH \n[PDFPAGE.Y]] \/OUTIn general, users should rarely need to use the pdfmark macro directly. In particular, the above example is too simplefor general use; it will create a bookmark, but it does not address the issues of setting the proper value for the /Countkey, nor of computing the PDFPAGE.Y value used in the /View key. The pdfmarkmacro package includes a morerobust mechanism for creating bookmarks, (see section 2.4, “Creating a Document Outline”), which addresses theseissues automatically.Nev ertheless, the pdfmark macro may be useful to users wishing to implement more advancedPDF features, than those currently supported directly by the pdfmark macro package.2.2. Selecting an Initial Document ViewBy default, when a PDF document is opened, the first page will be displayed, at the default magnification set for thereader, and outline and thumbnail views will be hidden. When using a PDF reader, such as Acrobat® Reader, whichsupports the /DOCVIEW class of the pdfmark operator, these default initial view settings may be overridden, using thepdfview macro. For example.pdfview /PageMode /UseOutlineswill cause Acrobat® Reader to open the document outline view, to the left of the normal page view, while.pdfview /PageMode /UseThumbswill open the thumbnail view instead.Note that the two /PageMode examples, above, are mutually exclusive — it is not possible to have both outline andthumbnail views open simultaneously. Howev er, it is permitted to add /Page and /Viewkeys, to force the documentto open at a page other than the first, or to change the magnification at which the document is initially displayed; see the“pdfmark Reference Manual”for more information.It should be noted that the viewcontrolling meta-data, defined by the pdfview macro, is not written immediately tothe PostScript® output stream, but is stored in an internal meta-data “cache”, (simply implemented as a groffdiversion). This “cached“ meta-data must be written out later, by inv oking the pdfsync macro, (see section 2.7,“Synchronizing Output and pdfmarkContexts”). 6.Note that, if any -Tdev option is specified, it should be either -T ps, or -T pdf; any other explicit choice is unlikely to becompatible with -m pdfmark, and will have an unpredictable (possibly erroneous) effect on the output. If no -Tdev option isspecified, (in which case -T ps is implicitly assumed), or if -T ps is explicitly specified, then the output will be produced inPostScript® format, and will require conversion to PDF, (e.g. by using GhostScript tools); explicit specification of -T pdf willresult in direct output in PDF format, thus obviating the need for conversion.
-3-2.3. Adding Document Identification Meta-DataIn addition to the /DOCVIEWclass of meta-data described above,(see section 2.2, “Selecting an Initial DocumentView”), we may also wish to include document identification meta-data, which belongs to the PDF /DOCINFO class.To do this, we use the pdfinfo macro. As an example of how it is used, the identification meta-data attached to thisdocument was specified using a macro sequence similar to:–.pdfinfo /TitlePDF Document Publishing with GNU Troff.pdfinfo /AuthorKeith Marshall.pdfinfo /SubjectHow to Exploit PDF Features with GNU Troff.pdfinfo /Keywordsgroff troff PDF pdfmarkNotice that the pdfinfo macro is repeated, once for each /DOCINFO record to be placed in the document. In eachcase, the first argument is the name of the applicable /DOCINFO key, which must be named with an initial soliduscharacter; all additional arguments are collected together, to define the value to be associated with the specified key.As is the case with the pdfviewmacro, (see section 2.2, “Selecting an Initial Document View”), the /DOCINFOrecords specified with the pdfinfo macro are not immediately written to the PostScript® output stream; they arestored in the same meta-data cache as /DOCVIEW specifications, until this cache is explicitly flushed, by invoking thepdfsync macro, (see section 2.7, “Synchronizing Output and pdfmarkContexts”). 2.4. Creating a Document OutlineA PDF document outline comprises a table of references, to “bookmarked” locations within the document. When thedocument is viewed in an “outline aware” PDF document reader, such as Adobe® Acrobat® Reader, this table of“bookmarks” may be displayed in a document outline pane, or “Bookmarks” pane, to the left of the main documentview. Individual references in the outline view may then be selected, by clicking with the mouse, to jump directly to theassociated marked location in the document view.The document outline may be considered as a collection of “hypertext” references to “bookmarked” locations within thedocument. The pdfmark macro package provides a single generalized macro, pdfhref,for creating and linking to“hypertext” reference marks.This macro will be described more comprehensively in a later section, (see section 2.5,“Adding Reference Marks and Links”); the description here is restricted to its use for defining document outline entries. 2.4.1. A Basic Document OutlineIn its most basic form, the document outline comprises a structured list of headings, each associated with a markedlocation, or “bookmark”, in the document text, and a specification for how that marked location should be displayed,when this bookmark is selected.To create a PDF bookmark, the pdfhref macro is used, at the point in the document where the bookmark is to beplaced, in the form.pdfhref O <level> descriptive text ...in which the reference class “O” stipulates that this is an outline reference.Alternatively, for those users who may prefer to think of a document outline simply as a collection of bookmarks, thepdfbookmark macro is also provided — indeed, pdfhref invokes it, when processing the “O” reference classoperator. It may be invoked directly, in the form.pdfbookmark <level> descriptive text ...Irrespective of which of the above macro forms is employed, the <level> argument is required. It is a numericargument, defining the nesting level of the “bookmark” in the outline hierarchy, with one being the topmost level. Itsfunction may be considered analagous to the heading level of the document’s section headings, for example, asspecified with the NH macro, if using the ms macros to format the document.All further arguments, following the <level> argument, are collected together, to specify the heading text which willappear in the document’s outline view. Thus, the outline entry for this section of this document, which has a level threeheading, might be specified as
-4-.pdfhref O 3 2.4.1. A Basic Document Outlineor, in the alternative form using the pdfbookmark macro, as.pdfbookmark 3 2.4.1. A Basic Document Outline2.4.2. Hierarchical Structure in a Document OutlineWhen a document outline is created, using the pdfhrefmacro as described insection 2.4.1,and anyentry is added atanesting levelgreater than one, then a hierarchical structure is automatically defined for the outline.However, aswasnoted in the simplifiedexampleinsection 2.1,the data required by the pdfmark operator to create the outline entrymay not be fully defined, when the outline reference is defined in the groff document source. Specifically, when theoutline entry is created, its /Count key must be assigned a value equal to the number of its subordinate entries, at thenext inner level of the outline hierarchy; typically however, these subordinate entries will be defined later in thedocument source, and the appropriate /Count value will be unknown, when defining the parent entry.To resolve this paradox, the pdfhref macro creates the outline entry in two distinct phases — a destination marker isplaced in the PostScript® output stream immediately, when the outline reference is defined, but the actual outline entryis stored in an internal “outline cache”, until its subordinate hierarchy has been fully defined; it can then be inserted inthe output stream, with its /Count value correctly assigned. Effectively, to ensure integrity of the document outlinestructure, this means that each top level outline entry, and all of its subordinates, are retained in the cache, until the nexttop level entry is defined.One potential problem, which arises from the use of the “outline cache”, is that, at the end of any document formattingrun, the last top level outline entry, and any subordinates defined after it, will remain in the cache, and will notbeautomatically written to the output stream.To avoid this problem, the user should followthe guidelines giveninsection 2.7,tosynchronize the output state with the cache state, (see section 2.7, “Synchronizing Output and pdfmarkContexts”), at the end of the groff formatting run.2.4.3. Associating a Document View with an Outline ReferenceEach “bookmark” entry, in a PDF document outline, is associated with a specific document view. When the readerselects any outline entry, the document view changes to display the document context associated with that entry.The document view specification, to be associated with any document outline entry, is established at the time when theoutline entry is created. However, rather than requiring that each individual use of the pdhref macro, to create anoutline entry, should include its own view specification, the actual specification assigned to each entry is derived from ageneralized specification defined in the string PDFBOOKMARK.VIEW, together with the setting of the numeric registerPDFHREF.VIEW.LEADING, which determine the effective view specification as follows:–PDFBOOKMARK.VIEWEstablishes the magnification at which the document will be viewed, at the location of the“bookmark”; by default, it is defined by.ds PDFBOOKMARK.VIEW /FitH \\n[PDFPAGE.Y] uwhich displays the associated document view, with the “bookmark” location positioned at the top ofthe display window, and with the magnification set to fit the page width to the width of the window.PDFHREF.VIEW.LEADINGSpecifies additional spacing, to be placed between the top of the display window and the actuallocation of the “bookmark” on the displayed page view. By default, it is set as.nr PDFHREF.VIEW.LEADING 5.0pNote that PDFHREF.VIEW.LEADING does not represent true “leading”, in the typographical sense,since any preceding text, set in the specified display space, will be visible at the top of the documentviewing window, when the reference is selected.Also note that the specification of PDFHREF.VIEW.LEADING is shared by all reference viewsdefined by the pdfhref macro; whereas PDFBOOKMARK.VIEW is applied exclusively to outlinereferences, there is no independent PDFBOOKMARK.VIEW.LEADING specification.
-5-If desired, the view specification may be changed, by redefining the string PDFBOOKMARK.VIEW, and possibly alsothe numeric register PDFHREF.VIEW.LEADING. Any alternative definition for PDFBOOKMARK.VIEW must bespecified in terms of valid view specification parameters, as described in the Adobe®“pdfmark Reference Manual”.Note the use of the register PDFPAGE.Y, in the default definition of PDFBOOKMARK.VIEW above. This register iscomputed by pdfhref, when creating an outline entry; it specifies the vertical position of the “bookmark”, in basicgroff units, relative to the bottom edge of the document page on which it is defined, and is followed, in thePDFBOOKMARK.VIEW definition, by the grops “u” operator, to convert it to PostScript® units on output. It may beused in any redefined specification for PDFBOOKMARK.VIEW, (or in the analogous definition of PDFHREF.VIEW,described insection 2.5.2.2, “Associating a Document Viewwith a Reference Mark”), but not in any other context,since its value is undefined outside the scope of the pdfhref macro.Since PDFPAGE.Y is computed relative to the bottom of the PDF output page, it is important to ensure that the pagelength specified to troff correctly matches the size of the logical PDF page. This is most effectively ensured, byproviding identical page size specifications to groff, grops and to the PostScript® to PDF converter employed, andavoiding any page length changes within the document source.Also note that PDFPAGE.Y is the only automatically computed “bookmark” location parameter; if the user redefinesPDFBOOKMARK.VIEW, and the modified view specification requires any other positional parameters, then the usermust ensure that these are computed before invoking the pdfhref macro.2.4.4. Folding the Outline to Conceal Less Significant HeadingsWhen a document incorporates many subheadings, at deeply nested levels, it may be desirable to “fold” the outline suchthat only the major heading levels are initially visible, yet making the inferior subheadings accessible, by allowing thereader to expand the view of any heading branch on demand.The pdfmark macros support this capability, through the setting of the PDFOUTLINE.FOLDLEVEL register. Thisregister should be set to the number of heading levels which it is desired to show in expanded form, in the initialdocument outline display; all subheadings at deeper levels will still be added to the outline, but will not become visibleuntil the outline branch containing them is expanded. For example, the setting used in this document:.\" Initialize the outline view to show only three heading levels,.\" with additional subordinate level headings folded..\".nr PDFOUTLINE.FOLDLEVEL 3results in only the first three levels of headings being displayed in the document outline, until the reader chooses toexpand the view, and so reveal the lower level headings in any outline branch.The initial default setting of PDFOUTLINE.FOLDLEVEL, if the document author does not choose to change it, is10,000. This is orders of magnitude greater than the maximum heading level which is likely to be used in anydocument; thus the default behaviour will be to show document outlines fully expanded, to display all headings defined,at all levels within each document.The setting of PDFOUTLINE.FOLDLEVEL may be changed at any time; however, the effect of each such change maybe difficult to predict, since it is applied not only to outline entries which are defined after the setting is changed, butalso to any entries which remain in the outline cache, at this time.Therefore, it is recommended thatPDFOUTLINE.FOLDLEVEL should be set once, at the start of each document; if it is deemed necessary to change it atany other time, the outline cache should be flushed, (see section 2.7, “Synchronizing Output and pdfmarkContexts”), immediately before the change, which should immediately preceed a level one heading.2.4.5. Outlines for Multipart DocumentsWhen a document outline is created, using the 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 partdocument, every outline reference has a uniquely named destination.As the overall size of the PDF document increases, it may become convenient to divide it into smaller, individuallyformatted PostScript® components, which are then assembled, in the appropriate order, to create a composite PDFdocument. While this strategy may simplify the overall process of creating and editing larger documents, it does
-6-introduce a problem in creating an overall document outline, since each individual PostScript® component will beassigned duplicated sequences of “bookmark” names, with each name ultimately referring to multiple locations in thecomposite document. To avoid such reference naming conflicts, the pdfhref macro allows the user to specify a “tag”,which is appended to the automatically generated “bookmark” name; this may be used as a discriminating mark, todistinguish otherwise similarly named destinations, in different sections of the composite document.To create a “tagged” document outline, the syntax for invocation of the pdfhref macro is modified, by the inclusionof an optional “tag” specification, before the nesting level argument, i.e..pdfhref O [-T <tag>] <level> descriptive text ...The optional <tag> argument may be composed of any characters of the user’s choice; however, its initial charactermust not be any decimal digit, and ideally it should be kept short — one or two characters at most.By employing a different tag in each section, the user can ensure that “bookmark” names remain unique, throughout allthe sections of a composite document. For example, when using the spdf.tmac macro package, which addspdfmark capabilities to the standard ms package, (see section 3.1, “Using pdfmark Macros with the msMacroPackage”), the table of contents is collected into a separate PostScript ® section from the main body of the document. Inthe “body” section, the document outline is “untagged”, but in the “Table of Contents” section, a modified version ofthe TC macro adds an outline entry for the start of the “Table of Contents”, invoking the pdfhref macro as.pdfhref O -T T 1 \\*[TOC]to tag the associated outline destination name with the single character suffix, “T”. Alternatively,asinthe case of thebasic outline, (see section 2.4.1, “ABasic Document Outline”), this may equally well be specified as .pdfbookmark -T T 1 \\*[TOC]2.4.6. Delegation of the Outline DefinitionSince the most common use of a document outline is to provide a quick method of navigating through a document,using active “hypertext” links to chapter and section headings, it may be convenient to delegate the responsibility ofcreating the outline to a higher level macro, which is itself used to define and format the section headings. Thisapproach has been adopted in the spdf.tmac package, to be described later, (see section 3.1, “Using pdfmarkMacros with the msMacro Package”).When such an approach is adopted, the user will rarely,ifever, inv oke the pdfhref macro directly, to create adocument outline. For example, the structure and content of the outline for this document has been exclusively defined,using a combination of the NH macro, from the ms package, to establish the structure, and the XN macro fromspdf.tmac, to define the content. In this case, the responsibility for invoking the pdfhref macro, to create thedocument outline, is delegated to the XN macro.2.5. Adding Reference Marks and LinksSection 2.4 has shown how the pdfhref macro may be used to create a PDF document outline. While this isundoubtedly a powerful capability, it is by no means the only trick in the repertoire of this versatile macro.The macro name, pdfhref, which is a contraction of “PDF HyperText Reference”, indicates that the general purposeof this macro is to define any type of dynamic reference mark, within a PDF document. Its generalized usage syntaxtakes the form.pdfhref <class> [-options ...] [--] [descriptive text ...]where <class> represents a required single character argument, which defines the specific reference operation to beperformed, and may be selected from:–OAdd an entry to the document outline.This operation has been described earlier,(see section 2.4,“Creating a Document Outline”). MPlace a “named destination” reference mark at the current output position, in the current PDFdocument, (see section 2.5.2, “Marking a Reference Destination”). DSpecify the content of a PDF document reference dictionary entry; typically, such entries aregenerated automatically, by transformation of the intermediate output resulting from the use ofpdfhref “M”, with the “-X”modifier,(see section 4.1.1, “Creating a Document Reference Map”);
-7-however, itisalso possible to specify such entries manually,(see section 2.5.5.2, “SpecifyingReference TextExplicitly”). LInsert an active link to a named destination, (see section 2.5.3, “Linking to a Marked ReferenceDestination”), at the current output position in the current PDF document, such that when the readerclicks on the link text, the document viewchanges to showthe location of the named destination. WInsert an active link to a “web” resource, (see section 2.5.4, “Linking to Internet Resources”), at thecurrent output position in the current PDF document.This is effectively the same as using the “ L”operator to establish a link to a named destination in another PDF document, (see section 2.5.3.2,“References to Destinations in Other PDF Documents”), except that in this case, the destination isspecified by a “uniform resource identifier”, or URI; this may represent any Internet or local resourcewhich can be specified in this manner.FSpecify a user defined macro, to be called by pdfhref,when formatting the text in the active regionof a link, (see section 2.5.5, “Establishing a Format for References”). ZDefine the absolute position on the physical PDF output page, where the “hot-spot” associated withan active link is to be placed. Invoked in pairs, marking the starting and ending PDF page co-ordinates for each link “hot-spot”, this operator is rarely, if ever, specified directly by the user; rather,appropriate pdfhref “Z”specifications are inserted automatically into the document reference mapduring the PDF document formatting process, (see section 4.1.1, “Creating a Document ReferenceMap”). IInitialize support for pdfhref features. The current pdfhrefimplementation provides only onesuch feature which requires initialization — a helper macro which must be attached to a usersupplied page trap handler,inorder to support mapping of reference “hot-spots” which extendthrough a page transition; (see section 2.5.6.1, “Links with a Page Transition in the Active Region”). 2.5.1. Optional Features of the pdfhref MacroThe behaviour of a number of the pdfhref macro operations can be modified, by including “option specifiers” afterthe operation specifying argument, but before any other arguments normally associated with the operation. In all cases,an option is specified by an “option flag”, comprising an initial hyphen, followed by one or two option identifyingcharacters. Additionally, some options require exactly one option argument; for these options, the argument must bespecified, and it must be separated from the preceding option flag by one or more spaces, (tabs must not be used). Itmay be noted that this paradigm for specifying options is reminiscent of most Unix™ shells; however, in the case of thepdfhref macro, omission of the space separating an option flag from its argument is never permitted.A list of all general purpose options supported by the pdfhref macro is given below. Note that not all options aresupported for all pdfhref operations; the operations affected by each option are noted in the list. For most operations,if an unsupported option is specified, it will be silently ignored; however, this behaviour should not be relied upon.The general purpose options, supported by the pdfhref macro, are:–-N <name>Allows the <name> associated with a PDF reference destination to be defined independently fromthe following text, which describes the reference. This option affects only the “M” operation of thepdfhrefmacro, (see section 2.5.2, “Marking a Reference Destination”). -EAlso used exclusively with the “M”operator,the-Eoption causes anyspecifieddescriptive textarguments, (see section 2.5.2, “Marking a Reference Destination”), to becopied, or echoed, in the body text of the document, at the point where the reference mark is defined;(without the -E option, such descriptive text will appear onlyat points where links to thereference mark are placed, and where the standard reference display format, (see section 2.5.5,“Establishing a Format for References”), is used). -D <dest>Specifies the URI, or the destination name associated with a PDF active link, independently of thefollowing text, which describes the link and demarcates the link “hot-spot”. This option affects thebehaviour of the pdfhref macro’s “L” and “W” operations.
-8-When used with the “L” operator, the <dest> argument must specify a PDF “named destination”,as defined using pdfhref with the “M” operator.When used with the “W” operator, <dest> must specify a link destination in the form of a “uniformresource identifier”, or URI,(see section 2.5.4, “Linking to Internet Resources”). -F <file>When used with the “L” pdfhref operator, <file> specifies an external PDF file in which thenamed destination for the link reference is defined. This option must be specified with the “L”operator, to create a link to a destination in a different PDF document; when the “L” operator is usedwithout this option, the link destination is assumed to be defined within the same document.-P <"prefix-text">Specifies <"prefix-text"> to be attached to the start of the text describing an active PDFdocument link, with no intervening space, but without itself being included in the active area of thelink “hot-spot”; it is effective with the “L” and “W” pdfhref operators.Typically, this option would be used to insert punctuation before the link “hot-spot”. Thus, there islittle reason for the inclusion of spaces in <"prefix-text">; howev er, if such space is required,then the enclosing double quotes must be specified, as indicated.-A <"affixed-text">Specifies <"affixed-text"> to be attached to the end of the text describing an active PDFdocument link, with no intervening space, but without itself being included in the active area of thelink “hot-spot”; it is effective with the “L” and “W” pdfhref operators.Typically, this option would be used to insert punctuation after the link “hot-spot”. Thus, there islittle reason for the inclusion of spaces in <"affixed-text">; howev er, if such space is required,then the enclosing double quotes must be specified, as indicated.-T <tag>When specified with the “O” operator, <tag> is appended to the “bookmark” name assigned to thegenerated outline entry. This option is required, to distinguish between the series of “bookmark”names generated in individual passes of the groffformatter,when the final PDF document is to beassembled from a number of separately formatted components; (see section 2.4.5, “Outlines forMultipart Documents”). -XThis pdfhref option is used with either the “M” operator, or with the “L” operator.When used with the “M”operator,(see section 2.5.2, “Marking a Reference Destination”), it ensuresthat a cross reference record for the marked destination will be included in the document referencemap, (see section 2.5.2.1, “Mapping a Destination for Cross Referencing”).When used with the “ L”operator,(see section 2.5.3, “Linking to a Marked Reference Destination”),it causes the reference to be displayed in the standard cross reference format, (see section 2.5.5,“Establishing a Format for References”), but substituting the descriptive text specified in the“pdfhref L” argument list, for the description specified in the document reference map.--Marks the end of the option specifiers. This may be used with all pdfhref operations which acceptoptions, to prevent pdfhref from interpreting any following arguments as option specifiers, even ifthey would otherwise be interpreted as such. It is also useful when the argument list to pdfhrefcontains special characters — any special character, which is not valid in a groff macro name, willcause a parsing error, if pdfhref attempts to match it as a possible option flag; using the “--” flagprevents this, so suppressing the groff warning message, which would otherwise ensue.Using this flag after all sequences of macro options is recommended, even when it is not strictlynecessary, if only for the entirely cosmetic benefit of visually separating the main argument list fromthe sequence of preceding options.In addition to the pdfhref options listed above, a supplementary set of two character options are defined. Thesesupplementary options, listed below, are intended for use with the “L” operator, in conjunction with the -F <file>option, to specify alternate file names, in formats compatible with the file naming conventions of alternate operatingsystems; they will be silently ignored, if used in any other context.
-9-The supported alternate file name options, which are ignored if the -F <file> option is not specified, are:–-DF <dos-file>Specifies the name of the file in which a link destination is defined, using the file naming semanticsof the MS-DOS® operating system. When the PDF document is read on a machine where theoperating system uses the MS-DOS® file system, then <dos-file> is used as the name of the filecontaining the reference destination, overriding the <file> argument specified with the -F option.-MF <mac-file>Specifies the name of the file in which a link destination is defined, using the file naming semanticsof the Apple® Macintosh® operating system. When the PDF document is read on a machinewhere the operating system uses the Macintosh® file system, then <mac-file> is used as thename of the file containing the reference destination, overriding the <file> argument specified withthe -F option.-UF <unix-file>Specifies the name of the file in which a link destination is defined, using the file naming semanticsof the Unix™operating system. When the PDF document is read on a machine where the operatingsystem uses POSIX file naming semantics, then <unix-file> is used as the name of the filecontaining the reference destination, overriding the <file> argument specified with the -F option.-WF <win-file>Specifies the name of the file in which a link destination is defined, using the file naming semanticsof the MS-Windows® 32-bit operating system. When the PDF document is read on a machinewhere the operating system uses any of the MS-Windows® file systems, with long file namesupport, then <win-file> is used as the name of the file containing the reference destination,overriding the <file> argument specified with the -F option.2.5.2. Marking a Reference DestinationThe pdfhref macro may be used to create active links to any Internet resource, specified by its URI, or to any “nameddestination”, either within the same document, or in another PDF document. Although the PDF specification allowslink destinations to be defined in terms of a page number, and an associated view specification, this style of reference isnot currently supported by the pdfhref macro, because it is not possible to adequately bind the specification for thedestination with the intended reference context.References to Internet resources are interpreted in accordance with the W3C standard for defining a URI; hence the onlyprerequisite, for creating a link to any Internet resource, is that the URIbe properly specified, when declaring thereference; (see section 2.5.4, “Linking to Internet Resources”). Inthe case of references to “named destinations” inPDF documents, however, itisnecessary to provide a mechanism for creating such “named destinations”.This may beaccomplished, by invoking the pdfhref macro in the form.pdfhref M [-N <name>] [-X] [-E] [descriptive text ...]This creates a “named destination” reference mark, with its name specified by <name>, or, if the -N option is notspecified, by the first word of descriptive text; (note that this imposes the restriction that, if the -N option isomitted, then at least one word of descriptive text mustbe specified). Additionally,areference viewwill beautomatically defined, and associated with the reference mark, (see section 2.5.2.2, “Associating a Document ViewwithaReference Mark”), and, if the -Xoption is specified, and no document cross reference map has been imported, (seesection 4.1.2, “Deploying a Document Reference Map”), then a cross reference mapping record, (see section 2.5.2.1,“Mapping a Destination for Cross Referencing”), will be written to the stdoutstream; this may be captured, andsubsequently used to generate a cross reference map for the document, (see section 4.1.1, “Creating a DocumentReference Map”).When a “named destination” reference mark is created, using the pdfhref macro’s “M” operator, there is normally novisible effect in the formatted document; any descriptive text which is specified will simply be stored in thecross reference map, for use when a link to the reference mark is created. This default behaviour may be changed, byspecifying the -E option, which causes any specified descriptive text to be “echoed” in the document text, at thepoint where the reference mark is placed, in addition to its inclusion in the cross reference map.
-10-2.5.2.1. Mapping a Destination for Cross ReferencingEffective cross referencing of any document formatted by groff requires multiple pass formatting. Details of howthis multiple pass formatting may be accomplished, when working with the pdfmarkmacros, will be discussed later,(see section 4.1, “Resolving Cross References”); 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.The first stage, in the process of cross referencing a document, is the generation of a cross reference map.Again, thedetails of howthe cross reference map is generated will be discussed insection 4.1;howev er, itisimportant torecognize that what content is included in the cross reference map is established when the reference destination isdefined — it is derived from the reference data exported on the stderr stream by the pdfhref macro, when it isinvoked with the “M” operator, and is controlled by whatever definition of the string PDFHREF.INFO is in effect, whenthe pdfhref macro is invoked.The initial default setting of PDFHREF.INFO is.ds PDFHREF.INFO page \\n% \\$*which ensures that the cross reference map will contain at least a page number reference, supplemented by anydescriptive text which is specified for the reference mark, as defined by the pdfhref macro, with its “M”operator; this may be redefined by the user,toexport additional cross reference information, or to modify the defaultformat for cross reference links, (see section 2.5.5, “Establishing a Format for References”). 2.5.2.2. Associating a Document View with a Reference MarkIn the same manner as each document outline reference, defined by the pdfhref macro with the “O”operator,(seesection 2.4, “Creating a Document Outline”), has a specific document viewassociated with it, each referencedestination marked by pdfhref with the “M”operator,requires an associated document viewspecification.The mechanism whereby a document viewisassociated with a reference mark is entirely analogous to that employedfor outline references, (see section 2.4.3, “Associating a Document Viewwith an Outline Reference”), except that the PDFHREF.VIEW string specification is used, in place of the PDFBOOKMARK.VIEW specification. Thus, the referenceview is defined in terms of:–PDFHREF.VIEWA string, establishing the position of the reference mark within the viewing window, and themagnification at which the document will be viewed, at the location of the marked referencedestination; by default, it is defined by.ds PDFHREF.VIEW /FitH \\n[PDFPAGE.Y] uwhich displays the reference destination at the top of the viewing window, with the magnification setto fit the page width to the width of the window.PDFHREF.VIEW.LEADINGA numeric register, specifying additional spacing, to be placed between the top of the displaywindow and the actual position at which the location of the reference destination appears within thewindow. This register is shared with the view specification for outline references, and thus has thesame default initial setting,.nr PDFHREF.VIEW.LEADING 5.0pas in the case of outline reference views.Again, notice that PDFHREF.VIEW.LEADING does not represent true typographic “leading”, sinceany preceding text, set in the specified display space, will be visible at the top of the viewingwindow, when the reference is selected.Just as the view associated with outline references may be changed, by redefining PDFBOOKMARK.VIEW, so the viewassociated with marked reference destinations may be changed, by redefining PDFHREF.VIEW, and, if desired,PDFHREF.VIEW.LEADING; such changes will become effective for all reference destinations marked after thesedefinitions are changed. (Notice that, since the specification of PDFHREF.VIEW.LEADING is shared by both outlinereference views and marked reference views, if it is changed, then the views for both reference types are changedaccordingly).
-11-It may again be noted, that the PDFPAGE.Y register is used in the definition of PDFHREF.VIEW, just as it is in thedefinition of PDFBOOKMARK.VIEW; all comments in section 2.4.3 relating to its use, and indeed to page positioncomputations in general, apply equally to marked reference views and to outline reference views.2.5.3. Linking to a Marked Reference DestinationAny named destination, such as those marked by the pdfhref macro, using it’s “M” operator, may be referred to fromany point in any PDF document, using an active link; such active links are created by again using the pdfhref macro,but in this case, with the “L”operator.This operator provides support for twodistinct cases, depending on whether thereference destination is defined in the same document as the link, (see section 2.5.3.1, “References within a Single PDFDocument”), or is defined as a named destination in a different PDF document, (see section 2.5.3.2, “References toDestinations in Other PDF Documents”). 2.5.3.1. References within a Single PDF DocumentThe general syntactic form for invoking the pdfhref macro, when creating a link to a named destination within thesame PDF document is.pdfhref L [-D <dest-name>] [-P <prefix-text>] [-A <affixed-text>] \[-X] [--] [descriptive text ...]where <dest-name> specifies the name of the link destination, as specified using the pdfhref “M” operation; (itmay be defined either earlier in the document, to create a backward reference, or later, to create a forward reference).If any descriptive text arguments are specified, then they will be inserted into the groff output stream, todefine the text appearing in the “hot-spot” region of the link; this will be printed in the link colour specified by thestring, PDFHREF.TEXT.COLOUR,which is described insection 2.5.5.1, “Using Colour to Demarcate Link Regions”.If the -X option is also specified, then the descriptive textwill be augmented, by prefacing it with page andsection number indicators, in accordance with the reference formatting rules which are in effect, (see section 2.5.5,“Establishing a Format for References”); such indicators will be included within the active link region, and will also beprinted in the link colour.Note that either the -D <dest-name> option, or the descriptive text arguments, but not both, may be omitted.If the -D <dest-name> option is omitted, then the first word of descriptive text, i.e. all text up to but notincluding the first space, will be interpreted as the <dest-name> for the link; this text will also appear in the runningtext of the document, within the active region of the link. Alternatively, if the -D <dest-name> option is specified,and descriptive textis not, then the running text which defines the reference, and its active region, will bederivedfrom the reference description which is specified when the named destination is marked, (see section 2.5.2,“Marking a Reference Destination”), and will be formatted according to the reference formatting rules which are ineffect, when the reference is placed, (see section 2.5.5, “Establishing a Format for References”); in this case, it is notnecessary to specify the -X option to activate automatic formatting of the reference — it is implied, by the omission ofall descriptive text arguments.The -P <prefix-text> and -A <affixed-text> options may be used to specify additional text which will beplaced before and after the linked text respectively, with no intervening space. Such prefixed and affixed text will beprinted in the normal text colour, and will not be included within the active region of the link. This feature is mostlyuseful for creating parenthetical references, or for placing punctuation adjacent to, but not included within, the textwhich defines the active region of the link.The operation of the pdfhref macro, when used with its “L”operator to place a link to a named PDF destination, maybest be illustrated by an example. However, since the appearance of the link will be influenced by factors establishedwhen the named destination is marked, (see section 2.5.2, “Marking a Reference Destination”), and also by theformatting rules in effect when the link is placed, the presentation of a suitable example will be deferred, until theformatting mechanism has been explained, (see section 2.5.5, “Establishing a Format for References”). 2.5.3.2. References to Destinations in Other PDF DocumentsThe pdfhref macro’s “L” operator is not restricted to creating reference links within a single PDF document. Whenthe link destination is defined in a different document, then the syntactic form for invoking pdfhref is modified, bythe addition of options to specify the name and location of the PDF file in which the destination is defined. Thus, theextended pdfhref syntactic form becomes
-12-.pdfhref L -F <file> [-D <dest-name>] \[-DF <dos-file>] [-MF <mac-file>] [-UF <unix-file>] \[-WF <win-file>] [-P <prefix-text>] [-A <affixed-text>] \[-X] [--] [descriptive text ...]where the -F <file> option serves two purposes: it both indicates to the pdfhref macro that the specified referencedestination is defined in an external PDF file, and it also specifies the normal path name, which is to be used to locatethis file, when a user selects the reference.In addition to the -F <file> option, which must be specified when referring to a destination in an external PDF file,the -DF <dos-file>, -MF <mac-file>, -UF <unix-file> and -WF <win-file> options may be used tospecify the location of the file containing the reference destination, in a variety of operating system dependent formats.These options assign their arguments to the /DosFile, /MacFile, /UnixFile and /WinFile keys of thegenerated pdfmark respectively; thus when any of these options are specified, in addition to the -F <file> option,and the document is read on the appropriate operating systems, then the path names specified by <dos-file>,<mac-file>, <unix-file> and <win-file> will be searched, instead of the path name specified by <file>,for each of the MS-DOS®, Apple® Macintosh®, Unix™and MS-Windows®operating systems, respectively; seethe “pdfmark Reference Manual”, for further details.Other than the use of these additional options, which specify that the reference destination is in an external PDF file, thebehaviour of the pdfhref “L” operator, with the -F <file> option, remains identical to its behaviour withoutthisoption, (see section 2.5.3.1, “References within a Single PDF Document”), with respect to the interpretation of otheroptions, the handling of the descriptive textarguments, and the formatting of the displayed reference.Once again, since the appearance of the reference is determined by factors specified in the document reference map, andalso by the formatting rules in effect when the reference is placed, the presentation of an example of the placing of areference to an external destination will be deferred, until the formatting mechanism has been explained, (see section2.5.5, “Establishing a Format for References”). 2.5.4. Linking to Internet ResourcesIn addition to supporting the creation of cross references to named destinations in PDF documents, the pdfhrefmacro also has the capability to create active links to Internet resources, or indeed to any resource which may bespecified by a Uniform Resource Identifier, (which is usually abbreviated to the acronym “URI”, and sometimes alsoreferred to as a Uniform Resource Locator, or “URL”).Since the mechanism for creating a link to a URI differs somewhat from that for creating PDF references, the pdfhrefmacro is invoked with the “W” (for “web-link”) operator, rather than the “L” operator; nevertheless, the invocationsyntax is similar, having the form.pdfhref W [-D <URI>] [-P <prefix-text>] [-A <affixed-text>] \[--] descriptive text ...where the optional -D <URI> modifier specifies the address for the target Internet resource, in any appropriate UniformResource Identifier format, while the descriptive text argument specifies the text which is to appear in the “hot-spot” region, and the -P <prefix-text> and -A <affixed-text>options have the same effect as in the case oflocal document links, (see section 2.5.3.1, “References within a Single PDF Document”).Notice that it is not mandatory to include the -D <URI> in the link specification; if it is specified, then it is notnecessary for the URI to appear, in the running text of the document — the descriptive text argument exactlydefines the text which will appear within the “hot-spot” region, and this need not include the URI. However, if the-D <URI> specification is omitted, then the descriptive text argument must be an exact representation of theURI, which will,therefore, appear as the entire content of the “hot-spot”.Forexample, we could introduce a referencetothe groffweb site,inwhich the actual URI is concealed, by using mark up such as:– For example, we could introduce a reference to.pdfhref W -D http://www.gnu.org/software/groff -A , the groff web sitein which the actual URI is concealed,Alternatively,torefer the reader to the groffweb site, making it obvious that the appropriate URI ishttp://www.gnu.org/software/groff,the requisite mark up might be:–
-13-to refer the reader to the groff web site,making it obvious that the appropriate URI is.pdfhref W -A , http://www.gnu.org/software/groffthe requisite mark up might be:\(en2.5.5. Establishing a Format for ReferencesThere 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 specialproperties — it is dynamically linked to the reference destination — and secondly, the textual content should describewhere the link leads, and ideally, it should also describe the content of the reference destination.The visual cue, that a text region defines a dynamically linked reference, is most commonly provided by printing thetext within the active region in a distinctive colour. This technique will be employed automatically by the pdfhrefmacro — see section 2.5.5.1, “Using Colour to Demarcate Link Regions” — unless the user specifically chooses toadopt, and implement, some alternative strategy.2.5.5.1. Using Colour to Demarcate Link RegionsTypically, when a PDF document contains active references to other locations, either within the same document, or evenin other documents, or on the World Wide Web, it is usually desirable to make the regions where these active links areplaced stand out from the surrounding text.2.5.5.2. Specifying Reference Text Explicitly2.5.5.3. Using Automatically Formatted Reference Text2.5.5.4. Customizing Automatically Formatted Reference TextIt is incumbent on the user,ifemploying automatic formatting of the displayed reference, (see section 2.5.5,“Establishing a Format for References”), to ensure that an appropriate reference definition is created for the referencedestination, and is included in the reference map for the document in which the reference will appear; thus, it may beeasiest to always use manual formatting for external references.2.5.6. Problematic LinksIrrespective of whether a pdfhref reference is placed using the “L” operator, or the “W” operator, there may beoccasions when the resulting link does function as expected. A number of scenarios, which are known to betroublesome, are described below.2.5.6.1. Links with a Page Transition in the Active RegionWhen a link is placed near the bottom of a page, it is possible that its active region, or “hot-spot”, may extend on to thenext page. In this situation, a page trap macro is required to intercept the page transition, and to restart the mapping ofthe “hot-spot” boundary on the new page.The pdfmark macro package includes a suitable page trap macro, to satisfy this requirement. However, to avoid pre-empting any other requirement the user may have for a page transition trap, this is not installed as an active page trap,unless explicitly requested by the user.To enable proper handling of page transitions, which occur within the active regions of reference links, the usershould:–1. Define a page transition macro, to provide whatever features may be required, when a page transitionoccurs — e.g. printing footnotes, adding page footers and headers, etc. This macro should end bysetting the output position at the correct vertical page offset, where the printing of running text is torestart, following the page transition.2. Plant a trap to invoke this macro, at the appropriate vertical position marking the end of normalrunning text on each page.
-14-3. Initialize the pdfhref hook into this page transition trap, by invokingpdfhref I -PT <macro-name>where <macro-name> is the name of the user supplied page trap macro, to ensure that pdfhrefwill correctly restart mapping of active link regions, at the start of each new page.It may be observed that this initialization of the pdfhref page transition hook is, typically, required only once beforedocument formatting begins. Users of document formatting macro packages may reasonably expect that thisinitialization should be performed by the macro package itself. Thus, writers of such macro packages which includepdfmark bindings, should provide appropriate initialization, so relieving the end user of this responsibility. Thefollowing example, abstracted from the sample ms binding package, spdf.tmac, illustrates how this may beaccomplished:–.\" groff "ms" provides the "pg@bottom" macro, which has already.\" been installed as a page transition trap.To ensure proper.\" mapping of "pdfhref" links which overflow the bottom of any.\" page, we need to install the "pdfhref" page transition hook,.\" as an addendum to this macro...pdfhref I -PT pg@bottom2.6. Annotating a PDF Document using Pop-Up Notes2.7. Synchronizing Output and pdfmark ContextsIt has been noted previously, that the pdfviewmacro, (see section 2.2, “Selecting an Initial Document View”), the pdfinfomacro, (see section 2.3, “Adding Document Identification Meta-Data”), and the pdfhrefmacro, whenused to create a document outline, (see section 2.4, “Creating a Document Outline”), do not immediately write their pdfmark output to the PostScript® data stream; instead, they cache their output, in a groff diversion, in the case ofthe pdfview and pdfinfo macros, or in an ordered collection of strings and numeric registers, in the case of thedocument outline, until a more appropriate time for copying it out. In the case of pdfview and pdfinfo “meta-data”, this “more appropriate time” is explicitly chosen by the user; in the case of document outline data, some cacheddata may be implicitly written out as the document outline is compiled, but there will always be some remaining data,which must be explicitly flushed out, before the groff formatting process is allowed to complete.To allow the user to choose when cached pdfmark data is to be flushed to the output stream, the pdfmark macropackage provides the pdfsync macro, (to synchronize the cache and output states). In its simplest form, it is invokedwithout arguments, i.e..pdfsyncThis form of invocation ensures that both the “meta-data cache”, containing pdfview and pdfinfo data, and the“outline cache”, containing any previously uncommitted document outline data, are flushed; ideally, this should beincluded in a groff “end macro”, to ensure that both caches are flushed, before groff terminates.Occasionally, it may be desirable to flush either the “meta-data cache”, without affecting the “outline cache”, or vice-versa, at a user specified time, prior to reaching the end of the document. This may be accomplished, by invoking thepdfsync macro with an argument, i.e..pdfsync Mto flush only the “meta-data cache”, or.pdfsync Oto flush only the “outline cache”.The “meta-data cache” can normally be safely flushed in this manner, at any time after output of the first page hasstarted; (it may cause formatting problems, most notably the appearance of unwanted white space, if flushed earlier, orindeed, if flushed immediately after a page transition, but before the output of the content on the new page hascommenced). Caution is required, however, when explicitly flushing the “outline cache”, since if the outline is to besubsequently extended, then the first outline entry after flushing must be specified at level 1. Nev ertheless, such explicitflushing may occasionally be necessary; for example, the TC macro in the spdf.tmac package, (see section 3.1,
-15-“Using pdfmark Macros with the msMacro Package”), invokes“ .pdfsync O” to ensure that the outline for the“body” section of the document is terminated, before it commences the formatting of the table of contents section.
-16-3. PDF Document LayoutThe pdfmarkmacros described in the preceding section, (see section 2, “Exploiting PDF Document Features”),provide no inherent document formatting capability of their own. However, theymay be used in conjunction with anyother groff macro package of the user’s choice, to add such capability.In preparing this document, the standard ms macro package, supplied as a component of the GNU Troff distribution,has been employed. To facilitate the use of the pdfmark macros with the ms macros, a binding macro package,spdf.tmac, has been created. The use of this binding macro package is described in the following section, (seesection 3.1, “Using pdfmark Macros with the msMacro Package”); it may also serveasanexample to users of otherstandard groff macro packages, as to how the pdfmark macros may be employed with their chosen primary macropackage.3.1. Using pdfmark Macros with the ms Macro PackageThe use of the binding macro package, spdf.tmac, allows for the use of the pdfmark macros in conjunction withthe ms macros, simply by issuing a groff command of the form7groff [-Tps|-Tpdf] [-m spdf [-options ...] file ...When using the spdf.tmac package, the groff input files may be marked up using any of the standard ms macrosto specify document formatting, while PDF features may be added, using any of the pdfmarkmacros describedpreviously,(see section 2, “Exploiting PDF Document Features”). Additionally, spdf.tmac defines a number ofconvenient extensions to the ms macro set, to better accomodate the use of PDF features within the ms formattingframework, and to address a number of ms document layout issues, which require special handling when producingPDF documents. These additional macros, and the issues they are intended to address, are described below.3.1.1. ms Section Headings in PDF DocumentsTraditionally, ms provides the NH and SH macros, to specify section headings. However, there is no standardmechanism for generating a table of contents entry based on the text of the section heading; neither is there anyrecognized standard method for establishing a cross reference link to the section.To address this ms limitation, spdf.tmac defines the XN macro, (see section 3.1.1.1, “The XNMacro”), to be used inconjunction with the NH macro.3.1.1.1. The XN Macro 7.Once again, as noted in footnote6tosection 2, “Exploiting PDF Document Features”,donot specify any -Tdev option, other than-T ps, or -T pdf; specify -T pdf, if you wish to avoid the conversion of PostScript® output to PDF, which will be required if youspecify -T ps, or if you omit the -Tdev option entirely.
-17-4. The PDF Publishing Process4.1. Resolving Cross References4.1.1. Creating a Document Reference Map4.1.2. Deploying a Document Reference Map