/contrib/groff/contrib/pdfmark/pdfmark.ms
Unknown | 2531 lines | 2531 code | 0 blank | 0 comment | 0 complexity | c01bc1e55d1cbc0917956cb7adad1ae2 MD5 | raw file
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