/contrib/groff/contrib/pdfmark/pdfmark.ms

Large files files are truncated, but you can click here to view the full file

   1.\" vim: ft=groff
   2.CS
   3Portable Document Format
   4Publishing with GNU Troff
   5.AU Keith Marshall
   6.AI <keith.d.marshall@ntlworld.com>
   7.CE
   8.\"
   9.\" Specify the Internet address for the groff web site.
  10.\" Currently, there are two available addresses; a copy is maintained at ...
  11.\"
  12.ds GROFF-WEBSITE http://www.gnu.org/software/groff
  13.\"
  14.\" ... but the official home site is at ...
  15.\"
  16.ds GROFF-WEBSITE http://groff.ffii.org
  17.\"
  18.\" Set the PDF default document view attribute, to ensure that the document
  19.\" outline is visible, each time the document is opened in Acrobat Reader.
  20.\"
  21.pdfview /PageMode /UseOutlines
  22.\"
  23.\" Initialise the outline view to show only three heading levels,
  24.\" with additional subordinate level headings folded.
  25.\"
  26.nr PDFOUTLINE.FOLDLEVEL 3
  27.\"
  28.\" Add document identification meta-data
  29.\"
  30.pdfinfo /Title     Portable Document Format Publishing with GNU Troff
  31.pdfinfo /Author    Keith Marshall
  32.pdfinfo /Subject   Tips and Techniques for Exploiting PDF Features with GNU Troff
  33.pdfinfo /Keywords  groff troff PDF pdfmark
  34.\"
  35.\" Set the default cross reference format to indicate section numbers,
  36.\" rather than page numbers, when we insert a reference pointer.
  37.\"
  38.ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
  39.\"
  40.\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
  41.\"
  42.de XR-NO-PREFIX
  43.rn PDFHREF.PREFIX xx
  44.ds PDFHREF.PREFIX
  45.XR \\$@
  46.rn xx PDFHREF.PREFIX
  47..
  48.\"
  49.\" Define a string,
  50.\" to insert a Registered Trade Mark symbol as a superscript.
  51.\"
  52.ds rg \*{\(rg\*}
  53.\"
  54.\" Establish the page layout.
  55.\"
  56.nr PO  2.5c
  57.nr LL 17.0c
  58.nr LT 17.0c
  59.nr HY  0
  60.nr FF  3
  61.nr DI  5n
  62.\"
  63.\" Generate headers in larger point sizes, for NH levels < 4,
  64.\" with point size increasing by 1.5p, for each lesser NH level.
  65.\"
  66.nr GROWPS 4
  67.nr PSINCR 1.5p
  68.\"
  69.de EM
  70.\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
  71.I \\$@
  72..
  73.de CWB
  74\\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
  75..
  76.de CWI
  77\\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
  78..
  79.de CWBI
  80\\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
  81..
  82.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
  83.\"
  84.NH 1
  85.\" When we use numbered section headings, we might like to automatically
  86.\" insert a table of contents entry, using the text of the heading itself.
  87.\" The "ms" macros don't provide any standard mechanism for doing this,
  88.\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
  89.\"
  90.\" Here's a simple example of how we might use it.  In this case, the word
  91.\" "Introduction" will appear both in the body of the document, as the text
  92.\" of the heading, and it will be added to the table of contents, which is
  93.\" subsequently "printed" using the "TC" macro; in both locations, it will
  94.\" be prefixed by the section number.
  95.\"
  96.\" As an additional side effect, any use of "XN" will cause the table of
  97.\" contents entry to be automatically reproduced, with the exception of its
  98.\" page number reference, as a PDF document outline entry.  Thus, the use
  99.\" of "XN" to specify numbered section headings results in the automatic
 100.\" creation of a numbered PDF document outline.  This automatic creation
 101.\" of the outline is completely transparent, and will occur regardless
 102.\" of whether the "TC" macro is subsequently invoked, or not.
 103.\"
 104.XN Introduction
 105.\"
 106.\" If using an old s.tmac, without the SN-NO-DOT extension,
 107.\" make sure we get SOMETHING in section number references.
 108.\"
 109.if !dSN-NO-DOT .als SN-NO-DOT SN
 110.LP
 111It might appear that it is a fairly simple matter to
 112produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
 113commonly known as PDF, using
 114.CW groff ) GNU\~Troff\~(
 115as the document formatter.
 116Indeed,
 117.CW groff 's
 118default output format is the native Adobe\*(rg\~PostScript\*(rg format,
 119which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
 120or GhostScript, expect as their input format.
 121Thus, the PDF production process would seem to entail simply
 122formatting the document source with
 123.CW groff ,
 124to produce a PostScript\*(rg version of the document,
 125which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
 126or GhostScript, to generate the final PDF document.
 127.LP
 128For many PDF production requirements,
 129the production cycle described above may be sufficient.
 130However, this is a limited PDF production method,
 131in which the resultant PDF document represents no more than
 132an on screen image of the printed form of the document, if
 133.CW groff 's
 134PostScript\*(rg output were printed directly.
 135.LP
 136The Portable Document Format provides a number of features,
 137which significantly enhance the experience of reading a document on screen,
 138but which are of little or no value to a document which is merely printed.
 139It
 140.EM is
 141possible to exploit these PDF features, which are described in the Adobe\*(rg
 142.\"
 143.de pdfmark-manual
 144.\" This is an example of a resource reference specified by URI ...
 145.\" We may need to refer often to the Adobe pdfmark Reference Manual,
 146.\" so we create the internet link definition using a macro, to make
 147.\" it reusable.
 148.\"
 149.\" Note also, that we protect the description of the reference by
 150.\" preceding it with "--", to avoid "invalid character in name" type
 151.\" error messages from groff (caused by the use of "\~").
 152.\"
 153.pdfhref W -D http://partners.adobe.com/asn/acrobat/docs/pdfmark.pdf \
 154    -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
 155..
 156.pdfmark-manual ,
 157with some refinement of the simple PDF production method, provided
 158appropriate \(lqfeature implementing\(rq instructions can be embedded into
 159.CW groff 's
 160PostScript\*(rg rendering of the document.
 161This, of course, implies that the original document source, which
 162.CW groff
 163will process to generate the PostScript\*(rg description of the document,
 164must include appropriate markup to exploit the desired PDF features.
 165It is this preparation of the
 166.CW groff
 167document source to exploit a number of these features,
 168which provides the principal focus of this document.
 169.LP
 170The markup techniques to be described have been utilised in the production of
 171the PDF version of this document itself.
 172This has been formatted using
 173.CW groff 's
 174.CW ms
 175macro package;
 176thus, usage examples may be found in the document source file,
 177.CW \n(.F ,
 178to which comments have been added,
 179to help identify appropriate markup examples for implementing PDF features,
 180such as:\(en
 181.QS
 182.IP \(bu
 183Selecting a default document view, which defines how the document will appear
 184when opened in the reader application; for example, when this document is
 185opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
 186in the document view pane, while a document outline should appear to the left,
 187in the \(lqBookmarks\(rq pane.
 188.IP \(bu
 189Adding document identification \(lqmeta\(hydata\(rq,
 190which can be accessed, in Acrobat\*(rg\~Reader,
 191by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
 192.IP \(bu
 193Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
 194pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
 195section of the document, simply by clicking on the associated heading
 196in the outline view.
 197.IP \(bu
 198Embedding active links in the body of the document, such that readers may
 199quickly navigate to related material at another location within the same
 200document, or in another PDF document, or even to a related Internet resource,
 201specified by its URI.
 202.IP \(bu
 203Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
 204points within the PDF document.
 205.QE
 206.LP
 207All of the techniques described have been tested on
 208.EM both
 209GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
 210.CW groff
 211.CW 1.19.1 ,\c
 212.pdfhref L -D footnote1 -- \**
 213.FS
 214.pdfhref M footnote1
 215Later versions should, and some earlier versions may, be equally suitable.
 216See
 217.pdfhref W \*[GROFF-WEBSITE]
 218for information and availability of the latest version.
 219.FE
 220in association with
 221.CW AFPL
 222.CW GhostScript
 223.CW 8.14 .\c
 224.pdfhref L -D footnote2 -- \**
 225.FS
 226.pdfhref M footnote2
 227Again, other versions may be suitable.
 228See
 229.pdfhref W http://ghostscript.com
 230for information and availability.
 231.FE
 232Other tools employed, which should be readily available on
 233.EM any
 234.SM
 235UNIX\(tm
 236.LG
 237or GNU/Linux system, are
 238.CW sed ,
 239.CW awk
 240and
 241.CW make ,
 242together with an appropriate text editor, for creating and marking up the
 243.CW groff
 244input files.
 245These additional utilities are not provided, as standard,
 246on the Microsoft\*(rg Windows\(tm platform,
 247but several third party implementations are available.
 248Some worth considering include the MKS\*(rg\~Toolkit,\**
 249.FS
 250A commercial offering; see
 251.pdfhref W http://mkssoftware.com/products/tk/default.asp
 252for information.
 253.FE
 254Cygwin,\**
 255.FS
 256A
 257.EM free
 258but comprehensive
 259.SM
 260POSIX
 261.LG
 262emulation environment and
 263.SM
 264UNIX\(tm
 265.LG
 266toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
 267.pdfhref W http://cygwin.com
 268for information and download.
 269.FE
 270or MSYS.\**
 271.FS
 272Another free, but minimal suite of common
 273.SM
 274UNIX\(tm
 275.LG
 276tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
 277.pdfhref W -A ; http://www.mingw.org
 278it
 279.EM does 
 280include those tools listed above,
 281and is the package which was actually used when performing the Windows\(tm2000
 282platform tests referred to in the text.
 283.FE
 284This list is by no means exhaustive, and should in no way be construed as an
 285endorsement of any of these packages, nor to imply that other similar packages,
 286which may be available, are in any way inferior to them.
 287.bp
 288.NH 1
 289.\" We may wish a section heading to represent a named destination,
 290.\" so that we can create a linked reference to it, from some other 
 291.\" part of the PDF document, (or even from another PDF document).
 292.\"
 293.\" Here we use the "-N" option of the "XN" macro, to create a named
 294.\" PDF link destination, at the location of the heading.  Notice that
 295.\" we also use the "--" marker to separate the heading text from the
 296.\" preceding option specification; it is not strictly necessary in
 297.\" this case, but it does help to set off the heading text from the
 298.\" option specification.
 299.\"
 300.XN -N pdf-features -- Exploiting PDF Document Features
 301.LP
 302To establish a consistent framework for adding PDF features, a
 303.CW groff
 304macro package, named
 305.CW pdfmark.tmac ,
 306has been provided.
 307Thus, to incorporate PDF features in a document,
 308the appropriate macro calls, as described below, may be placed in the
 309.CW groff
 310document source, which should then be processed with a
 311.CW groff
 312command of the form
 313.QP
 314.fam C
 315groff -Tps [-m
 316.I name "] -m"
 317.B pdfmark
 318.I options \& [-
 319.I "file ..." \& "...] "
 320.LP
 321It may be noted that the
 322.CW pdfmark
 323macros have no dependencies on, and no known conflicts with,
 324any other
 325.CW groff
 326macro package;  thus, users are free to use any other macro package,
 327of their choice, to format their documents, while also using the
 328.CW pdfmark
 329macros to add PDF features.
 330.NH 2
 331.XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
 332.LP
 333All PDF features are implemented by embedding instances of the
 334.B \F[C]pdfmark\F[]
 335operator, as described in the Adobe\*(rg
 336.pdfmark-manual ,
 337into
 338.CW groff 's
 339PostScript\*(rg output stream.
 340To facilitate the use of this operator, the
 341.CW pdfmark
 342macro package defines the primitive
 343.CW pdfmark
 344macro; it simply emits its argument list,
 345as arguments to a
 346.CW pdfmark
 347operator, in the PostScript\*(rg output stream.
 348.LP
 349.pdfhref M -N pdfmark-example
 350To illustrate the use of the
 351.CW pdfmark
 352macro, the following is a much simplified example of how a bookmark
 353may be added to a PDF document outline
 354.QP
 355.CW ".pdfmark \e"
 356.RS 4
 357.nf
 358.fam C
 359/Count 2 \e
 360/Title (An Example of a Bookmark with Two Children) \e
 361/View  [/FitH \en[PDFPAGE.Y]] \e
 362/OUT
 363.RE
 364.LP
 365In general, users should rarely need to use the
 366.CW pdfmark
 367macro directly.
 368In particular, the above example is too simple for general use; it
 369.EM will
 370create a bookmark, but it does
 371.EM not
 372address the issues of setting the proper value for the
 373.CW /Count
 374key, nor of computing the
 375.CW PDFPAGE.Y
 376value used in the
 377.CW /View
 378key. The
 379.CW pdfmark
 380macro package includes a more robust mechanism for creating bookmarks,
 381.\"
 382.\" Here is an example of how a local reference may be planted,
 383.\" using the automatic formatting feature of the "pdfhref" macro.
 384.\"
 385.\" This is a forward reference to the named destination "add-outline",
 386.\" which is defined below, using the "XN" wrapper macro, from the
 387.\" "spdf.tmac" macro package.  The automatically formatted reference
 388.\" will be enclosed in parentheses, as specified by the use of
 389.\" "-P" and "-A" options.
 390.\"
 391.pdfhref L -P ( -A ), -D add-outline
 392.\"
 393which addresses these issues automatically.
 394Nevertheless, the
 395.CW pdfmark
 396macro may be useful to users wishing to implement more advanced PDF features,
 397than those currently supported directly by the
 398.CW pdfmark
 399macro package.
 400.NH 2
 401.XN -N docview -- Selecting an Initial Document View
 402.LP
 403By default,
 404when a PDF document is opened,
 405the first page will be displayed,
 406at the default magnification set for the reader,
 407and outline and thumbnail views will be hidden.
 408When using a PDF reader,
 409such as Acrobat\*(rg\~Reader,
 410which supports the
 411.CW /DOCVIEW
 412class of the
 413.CW pdfmark
 414operator,
 415these default initial view settings may be overridden,
 416using the
 417.CW pdfview
 418macro.
 419For example
 420.QP
 421.CW ".pdfview /PageMode /UseOutlines"
 422.LP
 423will cause Acrobat\*(rg\~Reader to open the document outline view,
 424to the left of the normal page view,
 425while
 426.QP
 427.CW ".pdfview /PageMode /UseThumbs"
 428.LP
 429will open the thumbnail view instead.
 430.LP
 431Note that the two
 432.CW /PageMode
 433examples, above, are mutually exclusive \(em it is not possible to have
 434.EM both
 435outline and thumbnail views open simultaneously.
 436However, it
 437.EM is
 438permitted to add
 439.CW /Page
 440and
 441.CW /View
 442keys, to force the document to open at a page other than the first,
 443or to change the magnification at which the document is initially displayed;
 444see the
 445.pdfmark-manual
 446for more information.
 447.LP
 448It should be noted that the view controlling meta\(hydata, defined by the
 449.CW pdfview
 450macro, is not written immediately to the PostScript\*(rg output stream,
 451but is stored in an internal meta\(hydata \(lqcache\(rq,
 452(simply implemented as a
 453.CW groff
 454diversion).
 455This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
 456.CW pdfsync
 457macro,
 458.\"
 459.\" Here is another example of how we may introduce a forward reference.
 460.\" This time we are using the shorter notation afforded by the "XR" macro
 461.\" provided by "spdf.tmac"; this example is equivalent to the native
 462.\" "pdfmark.tmac" form
 463.\"     .pdfhref L -D pdfsync -P ( -A ).
 464.\"
 465.XR pdfsync ). (
 466.\"
 467.NH 2
 468.XN -N docinfo -- Adding Document Identification Meta-Data
 469.LP
 470In addition to the
 471.CW /DOCVIEW
 472class of meta\(hydata described above,
 473.XR docview ), (
 474we may also wish to include document identification meta\(hydata,
 475which belongs to the PDF
 476.CW /DOCINFO
 477class.
 478.LP
 479To do this, we use the
 480.CW pdfinfo
 481macro.
 482As an example of how it is used,
 483the identification meta\(hydata attached to this document
 484was specified using a macro sequence similar to:\(en
 485.DS I
 486.CW
 487\&.pdfinfo /Title     PDF Document Publishing with GNU Troff
 488\&.pdfinfo /Author    Keith Marshall
 489\&.pdfinfo /Subject   How to Exploit PDF Features with GNU Troff
 490\&.pdfinfo /Keywords  groff troff PDF pdfmark
 491.DE
 492Notice that the
 493.CW pdfinfo
 494macro is repeated, once for each
 495.CW /DOCINFO
 496record to be placed in the document.
 497In each case, the first argument is the name of the applicable
 498.CW /DOCINFO
 499key, which
 500.EM must
 501be named with an initial solidus character;
 502all additional arguments are collected together,
 503to define the value to be associated with the specified key.
 504.LP
 505As is the case with the
 506.CW pdfview
 507macro,
 508.XR docview ), (
 509the
 510.CW /DOCINFO
 511records specified with the
 512.CW pdfinfo
 513macro are not immediately written to the PostScript\*(rg output stream;
 514they are stored in the same meta\(hydata cache as
 515.CW /DOCVIEW
 516specifications, until this cache is explicitly flushed,
 517by invoking the
 518.CW pdfsync
 519macro,
 520.XR pdfsync ). (
 521.NH 2
 522.XN -N add-outline -- Creating a Document Outline
 523.LP
 524A PDF document outline comprises a table of references,
 525to \(lqbookmarked\(rq locations within the document.
 526When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
 527such as Adobe\*(rg Acrobat\*(rg Reader,
 528this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
 529or \(lqBookmarks\(rq pane, to the left of the main document view.
 530Individual references in the outline view may then be selected,
 531by clicking with the mouse,
 532to jump directly to the associated marked location in the document view.
 533.LP
 534The document outline may be considered as a collection of \(lqhypertext\(rq
 535references to \(lqbookmarked\(rq locations within the document.
 536The
 537.CW pdfmark
 538macro package provides a single generalised macro,
 539.CW pdfhref ,
 540for creating and linking to \(lqhypertext\(rq reference marks.
 541This macro will be described more comprehensively in a later section,
 542.XR pdfhref ); (
 543the description here is restricted to its use for defining document outline entries.
 544.NH 3
 545.XN -N basic-outline -- A Basic Document Outline
 546.LP
 547In its most basic form, the document outline comprises a structured list of headings,
 548each associated with a marked location, or \(lqbookmark\(rq, in the document text,
 549and a specification for how that marked location should be displayed,
 550when this bookmark is selected.
 551.LP
 552To create a PDF bookmark, the
 553.CW pdfhref
 554macro is used,
 555at the point in the document where the bookmark is to be placed,
 556in the form
 557.QP
 558.fam C
 559.B ".pdfhref O"
 560.I level > <
 561.I "descriptive text ..."
 562.LP
 563in which the reference class
 564.CWB O \& \& \(rq \(lq
 565stipulates that this is an outline reference.
 566.LP
 567Alternatively, for those users who may prefer to think of a document outline
 568simply as a collection of bookmarks, the
 569.CW pdfbookmark
 570macro is also provided \(em indeed,
 571.CW pdfhref
 572invokes it, when processing the
 573.CWB O \& \& \(rq \(lq
 574reference class operator.
 575It may be invoked directly, in the form
 576.QP
 577.fam C
 578.B .pdfbookmark
 579.I level > <
 580.I "descriptive text ..."
 581.LP
 582Irrespective of which of the above macro forms is employed, the
 583.CWI level > <
 584argument is required.
 585It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
 586in the outline hierarchy, with one being the topmost level.
 587Its function may be considered analagous to the
 588.EM "heading level"
 589of the document's section headings,
 590for example, as specified with the
 591.CW NH
 592macro, if using the
 593.CW ms
 594macros to format the document.
 595.LP
 596All further arguments, following the
 597.CWI level > <
 598argument, are collected together, to specify the heading text which will appear
 599in the document's outline view.
 600Thus, the outline entry for this section of this document,
 601which has a level three heading,
 602might be specified as
 603.QP
 604.CW
 605\&.pdfhref O 3 \*(SN A Basic Document Outline
 606.LP
 607or, in the alternative form using the
 608.CW pdfbookmark
 609macro, as
 610.QP
 611.CW
 612\&.pdfbookmark 3 \*(SN A Basic Document Outline
 613.NH 3
 614.XN Hierarchical Structure in a Document Outline
 615.LP
 616When a document outline is created, using the
 617.CW pdfhref
 618macro as described in
 619.\"
 620.\" Here is an example of how we can temporarily modify the format of
 621.\" a reference link, in this case to indicate only the section number
 622.\" of the link target, in the form "section #", (or, if we define
 623.\" "SECREF.BEGIN" before the call, its content followed by the
 624.\" section number).
 625.\"
 626.\" We first define a macro, which will get the reference data from
 627.\" pdfhref, as arguments, and will return the formatted output, as we
 628.\" require it, the string "PDFHREF.TEXT".
 629.\"
 630.de SECREF
 631.while \\n(.$ \{\
 632.   ie '\\$1'section' \{\
 633.      if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
 634.      ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
 635.      rm SECREF.BEGIN
 636.      shift \\n(.$
 637.      \}
 638.   el .shift
 639.   \}
 640..
 641.\" We now tell "pdfhref" to use our formatting macro, in place of
 642.\" its builtin default formatter, before we specify the reference.
 643.\"
 644.pdfhref F SECREF
 645.pdfhref L -A , -D basic-outline
 646.\"
 647.\" At this point, we would normally revert the "pdfhref" formatter
 648.\" to use its default, built in macro.  However, in this particular
 649.\" case, we want to use our custom format one more time, before we
 650.\" revert it, so we will omit the reversion step this time.
 651.\"
 652and any entry is added at a nesting level greater than one,
 653then a hierarchical structure is automatically defined for the outline.
 654However, as was noted in the simplified
 655.pdfhref L -D pdfmark-example -- example
 656in
 657.pdfhref L -A , -D pdfmark-operator
 658.\"
 659.\" And now, we revert to default "pdfhref" formatting behaviour,
 660.\" by completing the call we delayed above.
 661.\"
 662.pdfhref F
 663.\"
 664the data required by the
 665.CW pdfmark
 666operator to create the outline entry may not be fully defined,
 667when the outline reference is defined in the
 668.CW groff
 669document source.
 670Specifically, when the outline entry is created, its
 671.CW /Count
 672key must be assigned a value equal to the number of its subordinate entries,
 673at the next inner level of the outline hierarchy;
 674typically however,
 675these subordinate entries will be defined
 676.EM later
 677in the document source, and the appropriate
 678.CW /Count
 679value will be unknown, when defining the parent entry.
 680.LP
 681To resolve this paradox, the
 682.CW pdfhref
 683macro creates the outline entry in two distinct phases \(em
 684a destination marker is placed in the PostScript\*(rg output stream immediately,
 685when the outline reference is defined,
 686but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
 687until its subordinate hierarchy has been fully defined;
 688it can then be inserted in the output stream, with its
 689.CW /Count
 690value correctly assigned.
 691Effectively, to ensure integrity of the document outline structure,
 692this means that each top level outline entry, and
 693.EM all
 694of its subordinates, are retained in the cache, until the
 695.EM next
 696top level entry is defined.
 697.LP
 698One potential problem, which arises from the use of the \(lqoutline cache\(rq,
 699is that, at the end of any document formatting run, the last top level outline entry,
 700and any subordinates defined after it, will remain in the cache, and will 
 701.EM not
 702be automatically written to the output stream.
 703To avoid this problem, the user should follow the guidelines given in
 704.\"
 705.\" Here is a more conventional example of how to temporarily change
 706.\" to the format used to display reference links.  We will again use
 707.\" the "SECREF" format, which we defined above, but on this occasion
 708.\" we will immediately revert to the default format, after the link
 709.\" has been placed.
 710.\"
 711.pdfhref F SECREF
 712.pdfhref L -D pdfsync -A ,
 713.pdfhref F
 714.\"
 715to synchronise the output state with the cache state,
 716.XR pdfsync ), (
 717at the end of the
 718.CW groff
 719formatting run.
 720.NH 3
 721.XN -N outline-view -- Associating a Document View with an Outline Reference
 722.LP
 723Each \(lqbookmark\(rq entry, in a PDF document outline,
 724is associated with a specific document view.
 725When the reader selects any outline entry,
 726the document view changes to display the document context
 727associated with that entry.
 728.LP
 729The document view specification,
 730to be associated with any document outline entry,
 731is established at the time when the outline entry is created.
 732However, rather than requiring that each individual use of the
 733.CW pdhref
 734macro, to create an outline entry,
 735should include its own view specification,
 736the actual specification assigned to each entry is derived from
 737a generalised specification defined in the string
 738.CW PDFBOOKMARK.VIEW ,
 739together with the setting of the numeric register
 740.CW PDFHREF.VIEW.LEADING ,
 741which determine the effective view specification as follows:\(en
 742.QS
 743.IP \*[= PDFBOOKMARK.VIEW]
 744Establishes the magnification at which the document will be viewed,
 745at the location of the \(lqbookmark\(rq; by default, it is defined by
 746.RS
 747.QP
 748.CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
 749.RE
 750.IP
 751which displays the associated document view,
 752with the \(lqbookmark\(rq location positioned at the top of the display window,
 753and with the magnification set to fit the page width to the width of the window.
 754.IP \*[= PDFHREF.VIEW.LEADING]
 755Specifies additional spacing,
 756to be placed between the top of the display window
 757and the actual location of the \(lqbookmark\(rq on the displayed page view.
 758By default, it is set as
 759.RS
 760.QP
 761.CW ".nr PDFHREF.VIEW.LEADING 5.0p"
 762.RE
 763.IP
 764Note that
 765.CW PDFHREF.VIEW.LEADING
 766does not represent true \(lqleading\(rq, in the typographical sense,
 767since any preceding text, set in the specified display space,
 768will be visible at the top of the document viewing window,
 769when the reference is selected.
 770.IP
 771Also note that the specification of
 772.CW PDFHREF.VIEW.LEADING
 773is shared by
 774.EM all
 775reference views defined by the
 776.CW pdfhref
 777macro; whereas
 778.CW PDFBOOKMARK.VIEW
 779is applied exclusively to outline references,
 780there is no independent
 781.CW PDFBOOKMARK.VIEW.LEADING
 782specification.
 783.QE
 784.LP
 785If desired, the view specification may be changed, by redefining the string
 786.CW PDFBOOKMARK.VIEW ,
 787and possibly also the numeric register
 788.CW PDFHREF.VIEW.LEADING .
 789Any alternative definition for
 790.CW PDFBOOKMARK.VIEW
 791.EM must
 792be specified in terms of valid view specification parameters,
 793as described in the Adobe\*(rg
 794.pdfmark-manual .
 795.LP
 796Note the use of the register
 797.CW PDFPAGE.Y ,
 798in the default definition of
 799.CW PDFBOOKMARK.VIEW
 800above.
 801This register is computed by
 802.CW pdfhref ,
 803when creating an outline entry;
 804it specifies the vertical position of the \(lqbookmark\(rq,
 805in basic
 806.CW groff
 807units, relative to the
 808.EM bottom
 809edge of the document page on which it is defined,
 810and is followed, in the
 811.CW PDFBOOKMARK.VIEW
 812definition, by the
 813.CW grops
 814.CW u \(rq \(lq
 815operator, to convert it to PostScript\*(rg units on output.
 816It may be used in any redefined specification for
 817.CW PDFBOOKMARK.VIEW ,
 818(or in the analogous definition of
 819.CW PDFHREF.VIEW ,
 820described in
 821.XR-NO-PREFIX pdfhref-view ),
 822but
 823.EM not
 824in any other context,
 825since its value is undefined outside the scope of the
 826.CW pdfhref
 827macro.
 828.LP
 829Since
 830.CW PDFPAGE.Y
 831is computed relative to the
 832.EM bottom
 833of the PDF output page,
 834it is important to ensure that the page length specified to
 835.CW troff
 836correctly matches the size of the logical PDF page.
 837This is most effectively ensured,
 838by providing
 839.EM identical
 840page size specifications to
 841.CW groff ,
 842.CW grops
 843and to the PostScript\*(rg to PDF converter employed,
 844and avoiding any page length changes within the document source.
 845.LP
 846Also note that
 847.CW PDFPAGE.Y
 848is the only automatically computed \(lqbookmark\(rq location parameter;
 849if the user redefines
 850.CW PDFBOOKMARK.VIEW ,
 851and the modified view specification requires any other positional parameters,
 852then the user
 853.EM must
 854ensure that these are computed
 855.EM before
 856invoking the
 857.CW pdfhref
 858macro.
 859.NH 3
 860.XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
 861.LP
 862When a document incorporates many subheadings,
 863at deeply nested levels,
 864it may be desirable to \(lqfold\(rq the outline
 865such that only the major heading levels are initially visible,
 866yet making the inferior subheadings accessible,
 867by allowing the reader to expand the view of any heading branch on demand.
 868.LP
 869The
 870.CW pdfmark
 871macros support this capability,
 872through the setting of the
 873.CW PDFOUTLINE.FOLDLEVEL
 874register.
 875This register should be set to the number of heading levels
 876which it is desired to show in expanded form, in the
 877.EM initial
 878document outline display;
 879all subheadings at deeper levels will still be added to the outline,
 880but will not become visible until the outline branch containing them is expanded.
 881'ne 5
 882For example, the setting used in this document:
 883.QS
 884.LD
 885.fam C
 886\&.\e" Initialise the outline view to show only three heading levels,
 887\&.\e" with additional subordinate level headings folded.
 888\&.\e"
 889\&.nr PDFOUTLINE.FOLDLEVEL 3
 890.DE
 891.QE
 892.LP
 893results in only the first three levels of headings being displayed
 894in the document outline,
 895.EM until
 896the reader chooses to expand the view,
 897and so reveal the lower level headings in any outline branch.
 898.LP
 899The initial default setting of
 900.CW PDFOUTLINE.FOLDLEVEL ,
 901if the document author does not choose to change it,
 902is 10,000.
 903This is orders of magnitude greater than the maximum heading level
 904which is likely to be used in any document;
 905thus the default behaviour will be to show document outlines fully expanded,
 906to display all headings defined,
 907at all levels within each document.
 908.LP
 909The setting of
 910.CW PDFOUTLINE.FOLDLEVEL
 911may be changed at any time;
 912however, the effect of each such change may be difficult to predict,
 913since it is applied not only to outline entries which are defined
 914.EM after
 915the setting is changed,
 916but also to any entries which remain in the outline cache,
 917.EM at
 918this time.
 919Therefore, it is recommended that
 920.CW PDFOUTLINE.FOLDLEVEL
 921should be set
 922.EM once ,
 923at the start of each document;
 924if it
 925.EM is
 926deemed necessary to change it at any other time,
 927the outline cache should be flushed,
 928.XR pdfsync ), (
 929.EM immediately
 930before the change,
 931which should immediately preceed a level one heading.
 932.NH 3
 933.XN -N multipart-outline -- Outlines for Multipart Documents
 934.LP
 935When a document outline is created, using the
 936.CW pdfhref
 937macro, each reference mark is automatically assigned a name,
 938composed of a fixed stem followed by a serially generated numeric qualifier.
 939This ensures that, for each single part document, every outline reference
 940has a uniquely named destination.
 941.LP
 942As the overall size of the PDF document increases,
 943it may become convenient to divide it into smaller,
 944individually formatted PostScript\*(rg components,
 945which are then assembled, in the appropriate order,
 946to create a composite PDF document.
 947While this strategy may simplify the overall process of creating and
 948editing larger documents, it does introduce a problem in creating
 949an overall document outline,
 950since each individual PostScript\*(rg component will be assigned
 951duplicated sequences of \(lqbookmark\(rq names,
 952with each name ultimately referring to multiple locations in the composite document.
 953To avoid such reference naming conflicts, the
 954.CW pdfhref
 955macro allows the user to specify a \(lqtag\(rq,
 956which is appended to the automatically generated \(lqbookmark\(rq name;
 957this may be used as a discriminating mark, to distinguish otherwise
 958similarly named destinations, in different sections of the composite document.
 959.LP
 960To create a \(lqtagged\(rq document outline,
 961the syntax for invocation of the
 962.CW pdfhref
 963macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
 964.EM before
 965the nesting level argument, i.e.
 966.QP
 967.fam C
 968.B ".pdfhref O"
 969.B -T \& [
 970.I tag >] <
 971.I level > <
 972.I "descriptive text ..."
 973.LP
 974The optional
 975.CWI tag > <
 976argument may be composed of any characters of the user's choice;
 977however, its initial character
 978.EM "must not"
 979be any decimal digit, and ideally it should be kept short
 980\(em one or two characters at most.
 981.LP
 982By employing a different tag in each section,
 983the user can ensure that \(lqbookmark\(rq names remain unique,
 984throughout all the sections of a composite document.
 985For example, when using the
 986.CW spdf.tmac
 987macro package, which adds
 988.CW pdfmark
 989capabilities to the standard
 990.CW ms
 991package,
 992.XR using-spdf ), (
 993the table of contents is collected into a separate PostScript\*(rg section
 994from the main body of the document.
 995In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
 996but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
 997.CW TC
 998macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
 999invoking the
1000.CW pdfhref
1001macro as
1002.QP
1003.CW ".pdfhref O -T T 1 \e\e*[TOC]"
1004.LP
1005to tag the associated outline destination name with the single character suffix,
1006.CW T \(rq. \(lq
1007Alternatively, as in the case of the basic outline,
1008.XR basic-outline ), (
1009this may equally well be specified as
1010.QP
1011.CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1012.NH 3
1013.XN Delegation of the Outline Definition
1014.LP
1015Since the most common use of a document outline
1016is to provide a quick method of navigating through a document,
1017using active \(lqhypertext\(rq links to chapter and section headings,
1018it may be convenient to delegate the responsibility of creating the outline
1019to a higher level macro, which is itself used to
1020define and format the section headings.
1021This approach has been adopted in the
1022.CW spdf.tmac
1023package, to be described later,
1024.XR using-spdf ). (
1025.LP
1026When such an approach is adopted,
1027the user will rarely, if ever, invoke the
1028.CW pdfhref
1029macro directly, to create a document outline.
1030For example, the structure and content of the outline for this document
1031has been exclusively defined, using a combination of the
1032.CW NH
1033macro, from the
1034.CW ms
1035package, to establish the structure, and the
1036.CW XN
1037macro from
1038.CW spdf.tmac ,
1039to define the content.
1040In this case,
1041the responsibility for invoking the
1042.CW pdfhref
1043macro, to create the document outline,
1044is delegated to the
1045.CW XN
1046macro.
1047.NH 2
1048.XN -N pdfhref -- Adding Reference Marks and Links
1049.LP
1050.pdfhref F SECREF
1051.ds SECREF.BEGIN Section
1052.pdfhref L -D add-outline
1053.pdfhref F
1054has shown how the
1055.CW pdfhref
1056macro may be used to create a PDF document outline.
1057While this is undoubtedly a powerful capability,
1058it is by no means the only trick in the repertoire of this versatile macro.
1059.LP
1060The macro name,
1061.CW pdfhref ,
1062which is a contraction of \(lqPDF HyperText Reference\(rq,
1063indicates that the general purpose of this macro is to define
1064.EM any
1065type of dynamic reference mark, within a PDF document.
1066Its generalised usage syntax takes the form
1067.QP
1068.fam C
1069.B .pdfhref
1070.BI class > <
1071.I "-options ...\&" ] [
1072[--]
1073.I "descriptive text ...\&" ] [
1074.LP
1075where
1076.CW <\f(CIclass\fP>
1077represents a required single character argument,
1078which defines the specific reference operation to be performed,
1079and may be selected from:\(en
1080.QS
1081.IP \*[= O]
1082Add an entry to the document outline.
1083This operation has been described earlier,
1084.XR add-outline ). (
1085.IP \*[= M]
1086Place a \(lqnamed destination\(rq reference mark at the current output position,
1087in the current PDF document,
1088.XR mark-dest ). (
1089.IP \*[= D]
1090Specify the content of a PDF document reference dictionary entry;
1091typically, such entries are generated automatically,
1092by transformation of the intermediate output resulting from the use of
1093.CW pdfhref
1094.CWB M \& \& \(rq, \(lq
1095with the
1096.CWB -X \& \& \(rq \(lq
1097modifier,
1098.XR create-map ); (
1099however, it is also possible to specify such entries manually,
1100.XR user-format ). (
1101.IP \*[= L]
1102Insert an active link to a named destination,
1103.XR link-named ), (
1104at the current output position in the current PDF document,
1105such that when the reader clicks on the link text,
1106the document view changes to show the location of the named destination.
1107.IP \*[= W]
1108Insert an active link to a \(lqweb\(rq resource,
1109.XR add-weblink ), (
1110at the current output position in the current PDF document.
1111This is effectively the same as using the
1112.CWB L \& \& \(rq \(lq
1113operator to establish a link to a named destination in another PDF document,
1114.XR link-extern ), (
1115except that in this case, the destination is specified by a
1116\(lquniform resource identifier\(rq, or
1117.CW URI ;
1118this may represent any Internet or local resource
1119which can be specified in this manner.
1120.IP \*[= F]
1121Specify a user defined macro, to be called by
1122.CW pdfhref ,
1123when formatting the text in the active region of a link,
1124.XR set-format ). (
1125.IP \*[= Z]
1126Define the absolute position on the physical PDF output page,
1127where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
1128Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
1129for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
1130specified directly by the user;
1131rather, appropriate
1132.CW pdfhref
1133.CWB Z \& \& \(rq \(lq
1134specifications are inserted automatically into the document reference map
1135during the PDF document formatting process,
1136.XR create-map ). (
1137.IP \*[= I]
1138Initialise support for
1139.CW pdfhref
1140features.
1141The current
1142.CW pdfhref
1143implementation provides only one such feature which requires initialisation
1144\(em a helper macro which must be attached to a user supplied page trap handler,
1145in order to support mapping of reference \(lqhot\(hyspots\(rq
1146which extend through a page transition;
1147.XR page-trap ). (
1148.QE
1149.NH 3
1150.XN Optional Features of the \F[C]pdfhref\F[] Macro
1151.LP
1152The behaviour of a number of the
1153.CW pdfhref
1154macro operations can be modified,
1155by including
1156.EM "option specifiers" \(rq \(lq
1157after the operation specifying argument,
1158but
1159.EM before
1160any other arguments normally associated with the operation.
1161In
1162.EM all
1163cases, an option is specified by an
1164.EM "option flag" \(rq, \(lq
1165comprising an initial hyphen,
1166followed by one or two option identifying characters.
1167Additionally,
1168.EM some
1169options require
1170.EM "exactly one"
1171option argument;
1172for these options, the argument
1173.EM must
1174be specified, and it
1175.EM must
1176be separated from the preceding option flag by one or more
1177.EM spaces ,
1178(tabs
1179.EM "must not"
1180be used).
1181It may be noted that this paradigm for specifying options
1182is reminiscent of most
1183.SM
1184UNIX\(tm
1185.LG
1186shells; however, in the case of the
1187.CW pdfhref
1188macro, omission of the space separating an option flag from its argument is
1189.EM never
1190permitted.
1191.LP
1192A list of
1193.EM all
1194general purpose options supported by the
1195.CW pdfhref
1196macro is given below.
1197Note that not all options are supported for all
1198.CW pdfhref
1199operations; the operations affected by each option are noted in the list.
1200For
1201.EM most
1202operations, if an unsupported option is specified,
1203it will be silently ignored; however, this behaviour should
1204not be relied upon.
1205.LP
1206The general purpose options, supported by the
1207.CW pdfhref
1208macro, are:\(en
1209.QS
1210.IP \*[= -N\0 name > <]
1211Allows the
1212.CWI name > <
1213associated with a PDF reference destination
1214to be defined independently from the following text,
1215which describes the reference.
1216This option affects only the
1217.CWB M \& \& \(rq \(lq
1218operation of the
1219.CW pdfhref
1220macro,
1221.XR mark-dest ). (
1222.IP \*[= -E]
1223Also used exclusively with the
1224.CWB M \& \& \(rq \(lq
1225operator, the
1226.CWB -E
1227option causes any specified
1228.CWI descriptive \& \& \~\c
1229.CWI text
1230arguments,
1231.XR mark-dest ), (
1232to be copied, or
1233.EM echoed ,
1234in the body text of the document,
1235at the point where the reference mark is defined;
1236(without the
1237.CWB -E
1238option, such
1239.CWI descriptive \& \& \~\c
1240.CWI text
1241will appear
1242.EM only
1243at points where links to the reference mark are placed,
1244and where the standard reference display format,
1245.XR set-format ), (
1246is used).
1247.IP \*[= -D\0 dest > <]
1248Specifies the
1249.CW URI ,
1250or the destination name associated with a PDF active link,
1251independently of the following text,
1252which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1253This option affects the behaviour of the
1254.CW pdfhref
1255macro's
1256.CWB L \& \& \(rq \(lq
1257and
1258.CWB W \& \& \(rq \(lq
1259operations.
1260.IP
1261When used with the
1262.CWB L \& \& \(rq \(lq
1263operator, the
1264.CWI dest > <
1265argument must specify a PDF \(lqnamed destination\(rq,
1266as defined using
1267.CW pdfhref
1268with the
1269.CWB M \& \& \(rq \(lq
1270operator.
1271.IP
1272When used with the
1273.CWB W \& \& \(rq \(lq
1274operator,
1275.CWI dest > <
1276must specify a link destination in the form of a
1277\(lquniform resource identifier\(rq, or
1278.CW URI ,
1279.XR add-weblink ). (
1280.IP \*[= -F\0 file > <]
1281When used with the
1282.CWB L \& \& \(rq \(lq
1283.CW pdfhref
1284operator,
1285.CWI file > <
1286specifies an external PDF file in which the named destination
1287for the link reference is defined.
1288This option
1289.EM must
1290be specified with the
1291.CWB L \& \& \(rq \(lq
1292operator,
1293to create a link to a destination in a different PDF document;
1294when the
1295.CWB L \& \& \(rq \(lq
1296operator is used
1297.EM without
1298this option, the link destination is assumed to be defined
1299within the same document.
1300.IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1301Specifies
1302.CWI \(dqprefix\(hytext\(dq > <
1303to be attached to the
1304.EM start
1305of the text describing an active PDF document link,
1306with no intervening space, but without itself being included in the
1307active area of the link \(lqhot\(hyspot\(rq;
1308it is effective with the
1309.CWB L \& \& \(rq \(lq
1310and
1311.CWB W \& \& \(rq \(lq
1312.CW pdfhref
1313operators.
1314.IP
1315Typically, this option would be used to insert punctuation before
1316the link \(lqhot\(hyspot\(rq.
1317Thus, there is little reason for the inclusion of spaces in
1318.CWI \(dqprefix\(hytext\(dq > < ;
1319however, if such space is required, then the enclosing double quotes
1320.EM must
1321be specified, as indicated.
1322.IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1323Specifies
1324.CWI \(dqaffixed\(hytext\(dq > <
1325to be attached to the
1326.EM end
1327of the text describing an active PDF document link,
1328with no intervening space, but without itself being included in the
1329active area of the link \(lqhot\(hyspot\(rq;
1330it is effective with the
1331.CWB L \& \& \(rq \(lq
1332and
1333.CWB W \& \& \(rq \(lq
1334.CW pdfhref
1335operators.
1336.IP
1337Typically, this option would be used to insert punctuation after
1338the link \(lqhot\(hyspot\(rq.
1339Thus, there is little reason for the inclusion of spaces in
1340.CWI \(dqaffixed\(hytext\(dq > < ;
1341however, if such space is required, then the enclosing double quotes
1342.EM must
1343be specified, as indicated.
1344.IP \*[= -T\0 tag > <]
1345When specified with the
1346.CWB O \& \& \(rq \(lq
1347operator,
1348.CWI tag > <
1349is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1350This option is
1351.EM required ,
1352to distinguish between the series of \(lqbookmark\(rq names generated in
1353individual passes of the
1354.CW groff
1355formatter, when the final PDF document is to be assembled
1356from a number of separately formatted components;
1357.XR multipart-outline ). (
1358.IP \*[= -X]
1359This
1360.CW pdfhref
1361option is used with either the
1362.CWB M \& \& \(rq \(lq
1363operator, or with the
1364.CWB L \& \& \(rq \(lq
1365operator.
1366.IP
1367When used with the
1368.CWB M \& \& \(rq \(lq
1369operator,
1370.XR mark-dest ), (
1371it ensures that a cross reference record for the marked destination
1372will be included in the document reference map,
1373.XR export-map ). (
1374.IP
1375When used with the
1376.CWB L \& \& \(rq \(lq
1377operator,
1378.XR link-named ), (
1379it causes the reference to be displayed in the standard cross reference format,
1380.XR set-format ), (
1381but substituting the
1382.CWI descriptive \& \& \~\c
1383.CWI text
1384specified in the
1385.CW pdfhref \& \(lq
1386.CW L \(rq
1387argument list,
1388for the description specified in the document reference map.
1389.IP \*[= --]
1390Marks the end of the option specifiers.
1391This may be used with all
1392.CW pdfhref
1393operations which accept options, to prevent
1394.CW pdfhref
1395from interpreting any following arguments as option specifiers,
1396even if they would otherwise be interpreted as such.
1397It is also useful when the argument list to
1398.CW pdfhref
1399contains special characters \(em any special character,
1400which is not legal in a
1401.CW groff
1402macro name, will cause a parsing error, if
1403.CW pdfhref
1404attempts to match it as a possible option flag;
1405using the
1406.CW -- \(rq \(lq
1407flag prevents this, so suppressing the
1408.CW groff
1409warning message, which would otherwise ensue.
1410.IP
1411Using this flag after
1412.EM all
1413sequences of macro options is recommended,
1414even when it is not strictly necessary,
1415if only for the entirely cosmetic benefit of visually separating
1416the main argument list from the sequence of preceding options.
1417.QE
1418.LP
1419In addition to the
1420.CW pdfhref
1421options listed above, a supplementary set of two character options are defined.
1422These supplementary options, listed below, are intended for use with the
1423.CWB L \& \& \(rq \(lq
1424operator, in conjunction with the
1425.CWB -F \& \& \~\c
1426.CWBI file > <
1427option, to specify alternate file names,
1428in formats compatible with the file naming conventions
1429of alternate operating systems;
1430they will be silently ignored, if used in any other context.
1431.LP
1432The supported alternate file name options,
1433which are ignored if the
1434.CWB -F \& \& \~\c
1435.CWBI file > <
1436option is not specified, are:\(en
1437.QS
1438.IP \*[= -DF\0 dos\(hyfile > <]
1439Specifies the name of the file in which a link destination is defined,
1440using the file naming semantics of the
1441.CW MS\(hyDOS \*(rg
1442operating system.
1443When the PDF document is read on a machine
1444where the operating system uses the
1445.CW MS\(hyDOS \*(rg
1446file system, then
1447.CWI dos\(hyfile > <
1448is used as the name of the file containing the reference destination,
1449overriding the
1450.CWI file > <
1451argument specified with the
1452.CWB -F
1453option.
1454.IP \*[= -MF\0 mac\(hyfile > <]
1455Specifies the name of the file in which a link destination is defined,
1456using the file naming semantics of the
1457.CW Apple \*(rg
1458.CW Macintosh \*(rg
1459operating system.
1460When the PDF document is read on a machine
1461where the operating system uses the
1462.CW Macintosh \*(rg
1463file system, then
1464.CWI mac\(hyfile > <
1465is used as the name of the file containing the reference destination,
1466overriding the
1467.CWI file > <
1468argument specified with the
1469.CWB -F
1470option.
1471.IP \*[= -UF\0 unix\(hyfile > <]
1472Specifies the name of the file in which a link destination is defined,
1473using the file naming semantics of the
1474.CW UNIX \(tm
1475operating system.
1476When the PDF document is read on a machine
1477where the operating system uses
1478.CW POSIX
1479file naming semantics, then
1480.CWI unix\(hyfile > <
1481is used as the name of the file containing the reference destination,
1482overriding the
1483.CWI file > <
1484argument specified with the
1485.CWB -F
1486option.
1487.IP \*[= -WF\0 win\(hyfile > <]
1488Specifies the name of the file in which a link destination is defined,
1489using the file naming semantics of the
1490.CW MS\(hyWindows \*(rg
149132\(hybit operating system.
1492When the PDF document is read on a machine
1493where the operating system uses any of the
1494.CW MS\(hyWindows \*(rg
1495file systems, with long file name support, then
1496.CWI win\(hyfile > <
1497is used as the name of the file containing the reference destination,
1498overriding the
1499.CWI file > <
1500argument specified with the
1501.CWB -F
1502option.
1503.QE
1504.NH 3
1505.XN -N mark-dest -- Marking a Reference Destination
1506.LP
1507The
1508.CW pdfhref
1509macro may be used to create active links to any Internet resource,
1510specified by its
1511.CW URI ,
1512or to any \(lqnamed destination\(rq,
1513either within the same document, or in another PDF document.
1514Although the PDF specification allows link destinations to be defined
1515in terms of a page number, and an associated view specification,
1516this style of reference is not currently supported by the
1517.CW pdfhref
1518macro, because it is not possible to adequately bind the specification
1519for the destination with the intended reference context.
1520.LP
1521References to Internet resources are interpreted in accordance with the
1522.CW W3C
1523standard for defining a
1524.CW URI ;
1525hence the only prerequisite, for creating a link to any Internet resource,
1526is that the
1527.CW URI
1528be properly specified, when declaring the reference;
1529.XR add-weblink ). (
1530In the case of references to \(lqnamed destinations\(rq in PDF documents,
1531however, it is necessary to provide a mechanism for creating such
1532\(lqnamed destinations\(rq.
1533This may be accomplished, by invoking the
1534.CW pdfhref
1535macro in the form
1536.QP
1537.fam C
1538.B ".pdfhref M"
1539.B -N \& [
1540.I name >] <
1541.B -X ] [
1542.B -E ] [
1543.I "descriptive text ...\&" ] [
1544.LP
1545This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1546.CWI name > < ,
1547or, if the
1548.CWB -N
1549option is not specified, by the first word of
1550.CWI descriptive \& \& \~\c
1551.CWI text \& \& ;
1552(note that this imposes the restriction that,
1553if the
1554.CWB -N
1555option is omitted, then
1556.EM "at least"
1557one word of
1558.CWI descriptive \& \& \~\c
1559.CWI text
1560.EM must
1561be specified).
1562Additionally, a reference view will be automatically defined,
1563and associated with the reference mark,
1564.XR pdfhref-view ), (
1565.\" and, if any
1566.\" .CWI descriptive
1567.\" .CWI text
1568.\" is specified, or the
1569and, if the
1570.CWB -X
1571option is specified, and no document cross reference map has been imported,
1572.XR import-map ), (
1573then a cross reference mapping record,
1574.XR export-map ), (
1575will be written to the
1576.CW stdout
1577stream;
1578this may be captured, and subsequently used to generate a cross reference map
1579for the document,
1580.XR create-map ). (
1581.LP
1582When a \(lqnamed destination\(rq reference mark is created, using the
1583.CW pdfhref
1584macro's
1585.CWB M \& \& \(rq \(lq
1586operator, there is normally no visible effect in the formatted document; any
1587.CWI descriptive \& \& \~\c
1588.CWI text
1589which is specified will simply be stored in the cross reference map,
1590for use when a link to the reference mark is created.
1591This default behaviour may be changed, by specifying the
1592.CWB -E
1593option, which causes any specified
1594.CWI descriptive \& \& \~\c
1595.CWI text
1596to be \(lqechoed\(rq in the document text,
1597at the point where the reference mark is placed,
1598in addition to its inclusion in the cross reference map.
1599.NH 4
1600.XN -N export-map -- Mapping a Destination for Cross Referencing
1601.LP
1602Effective cross referencing of
1603.EM any
1604document formatted by
1605.CW groff
1606requires multiple pass formatting.
1607Details of how this multiple pass formatting may be accomplished,
1608when working with the
1609.CW pdfmark
1610macros, will be discussed later,
1611.XR do-xref ); (
1612at this stage, the discussion will be restricted to the initial preparation,
1613which is required at the time when the cross reference destinations are defined.
1614.LP
1615The first stage, in the process of cross referencing a document,
1616is the generation of a cross reference map.
1617Again, the details of
1618.EM how
1619the cross reference map is generated will be discussed in
1620.pdfhref F SECREF L -D do-xref -A ;
1621.pdfhref F
1622however, it is important to recognise that
1623.EM what
1624content is included in the cross reference map is established
1625when the reference destination is defined \(em it is derived
1626from the reference data exported on the
1627.CW stderr
1628stream by the
1629.CW pdfhref
1630macro, when it is invoked with the
1631.CWB M \& \& \(rq \(lq
1632operator, and is controlled by whatever definition of the string
1633.CW PDFHREF.INFO
1634is in effect, when the
1635.CW pdfhref
1636macro is invoked.
1637.LP
1638The initial default setting of
1639.CW PDFHREF.INFO
1640is
1641.QP
1642.CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1643.LP
1644which ensures that the cross reference map will contain
1645at least a page number reference, supplemented by any
1646.CWI descriptive \& \& \~\c
1647.CWI text
1648which is specified for the reference mark, as defined by the
1649.CW pdfhref
1650macro, with its
1651.CWB M \& \& \(rq \(lq
1652operator; this may be redefined by the user,
1653to export additional cross reference information,
1654or to modify the defaul…

Large files files are truncated, but you can click here to view the full file