contrib/pdfmark/pdfmark.ms.in

   1 .ig
   2 @ pdfmark.ms.in
   3
   4 Copyright (c) 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
   5
   6 Copyright (C) 2004 - 2006 Free Software Foundation, Inc.
   7 written by Keith Marshall <keith.d.marshall@ntlworld.com>
   8
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.1 or
  11 any later version published by the Free Software Foundation; with no
  12 Front-Cover Texts, no Back-Cover Texts, and the following Invariant
  13 Sections:--
  14
  15     a)  This "Legal Matters" section, extending from the start of
  16         the document, to the end of the enclosing ".ig" section.
  17
  18     b)  The two lines below starting with `.AU' and `.AI'.
  19
  20 You should have received a copy of the Free Documentation License
  21 as part of the file COPYING; also located in the main directory of the
  22 source package of this program.
  23 ..
  24 .
  25 .CS
  26 Portable Document Format
  27 Publishing with @T_ROFF@
  28 .AU Keith Marshall
  29 .AI <keith.d.marshall@ntlworld.com>
  30 .CE
  31 .\"
  32 .\" Specify the Internet address for our web site.
  33 .\" Currently, there are two available addresses; a copy is maintained at ...
  34 .\"
  35 .ds ROFF-WEBSITE @ROFF_WEBURL@
  36 .\"
  37 .\" Set the PDF default document view attribute, to ensure that the document
  38 .\" outline is visible, each time the document is opened in Acrobat Reader.
  39 .\"
  40 .pdfview /PageMode /UseOutlines
  41 .\"
  42 .\" Initialise the outline view to show only three heading levels,
  43 .\" with additional subordinate level headings folded.
  44 .\"
  45 .nr PDFOUTLINE.FOLDLEVEL 3
  46 .\"
  47 .\" Add document identification meta-data
  48 .\"
  49 .pdfinfo /Title     Portable Document Format Publishing with @T_ROFF@
  50 .pdfinfo /Author    Keith Marshall
  51 .pdfinfo /Subject   Tips and Techniques for Exploiting PDF Features with @T_ROFF@
  52 .pdfinfo /Keywords  @T_ROFF@ @T_TROFF@ troff PDF pdfmark
  53 .\"
  54 .\" Set the default cross reference format to indicate section numbers,
  55 .\" rather than page numbers, when we insert a reference pointer.
  56 .\"
  57 .ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
  58 .\"
  59 .\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
  60 .\"
  61 .de XR-NO-PREFIX
  62 .rn PDFHREF.PREFIX xx
  63 .ds PDFHREF.PREFIX
  64 .XR \\$@
  65 .rn xx PDFHREF.PREFIX
  66 ..
  67 .\"
  68 .\" Define a string,
  69 .\" to insert a Registered Trade Mark symbol as a superscript.
  70 .\"
  71 .ds rg \*{\(rg\*}
  72 .\"
  73 .\" Establish the page layout.
  74 .\"
  75 .nr PO  2.5c
  76 .nr LL 17.0c
  77 .nr LT 17.0c
  78 .nr HY  0
  79 .nr FF  3
  80 .nr DI  5n
  81 .\"
  82 .\" Generate headers in larger point sizes, for NH levels < 4,
  83 .\" with point size increasing by 1.5p, for each lesser NH level.
  84 .\"
  85 .nr GROWPS 4
  86 .nr PSINCR 1.5p
  87 .\"
  88 .de EM
  89 .\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
  90 .I \\$@
  91 ..
  92 .de CWB
  93 \\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
  94 ..
  95 .de CWI
  96 \\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
  97 ..
  98 .de CWBI
  99 \\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
 100 ..
 101 .ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
 102 .\"
 103 .NH 1
 104 .\" When we use numbered section headings, we might like to automatically
 105 .\" insert a table of contents entry, using the text of the heading itself.
 106 .\" The "ms" macros don't provide any standard mechanism for doing this,
 107 .\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
 108 .\"
 109 .\" Here's a simple example of how we might use it.  In this case, the word
 110 .\" "Introduction" will appear both in the body of the document, as the text
 111 .\" of the heading, and it will be added to the table of contents, which is
 112 .\" subsequently "printed" using the "TC" macro; in both locations, it will
 113 .\" be prefixed by the section number.
 114 .\"
 115 .\" As an additional side effect, any use of "XN" will cause the table of
 116 .\" contents entry to be automatically reproduced, with the exception of its
 117 .\" page number reference, as a PDF document outline entry.  Thus, the use
 118 .\" of "XN" to specify numbered section headings results in the automatic
 119 .\" creation of a numbered PDF document outline.  This automatic creation
 120 .\" of the outline is completely transparent, and will occur regardless
 121 .\" of whether the "TC" macro is subsequently invoked, or not.
 122 .\"
 123 .XN Introduction
 124 .\"
 125 .\" If using an old s.tmac, without the SN-NO-DOT extension,
 126 .\" make sure we get SOMETHING in section number references.
 127 .\"
 128 .if !dSN-NO-DOT .als SN-NO-DOT SN
 129 .LP
 130 It might appear that it is a fairly simple matter to
 131 produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
 132 commonly known as PDF, using
 133 .CW @T_ROFF@
 134 as the document formatter.
 135 Indeed,
 136 .CW @L_ROFF@ 's
 137 default output format is the native Adobe\*(rg\~PostScript\*(rg format,
 138 which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
 139 or GhostScript, expect as their input format.
 140 Thus, the PDF production process would seem to entail simply
 141 formatting the document source with
 142 .CW @L_ROFF@ ,
 143 to produce a PostScript\*(rg version of the document,
 144 which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
 145 or GhostScript, to generate the final PDF document.
 146 .LP
 147 For many PDF production requirements,
 148 the production cycle described above may be sufficient.
 149 However, this is a limited PDF production method,
 150 in which the resultant PDF document represents no more than
 151 an on screen image of the printed form of the document, if
 152 .CW @L_ROFF@ 's
 153 PostScript\*(rg output were printed directly.
 154 .LP
 155 The Portable Document Format provides a number of features,
 156 which significantly enhance the experience of reading a document on screen,
 157 but which are of little or no value to a document which is merely printed.
 158 It
 159 .EM is
 160 possible to exploit these PDF features, which are described in the Adobe\*(rg
 161 .\"
 162 .de pdfmark-manual
 163 .\" This is an example of a resource reference specified by URI ...
 164 .\" We may need to refer often to the Adobe pdfmark Reference Manual,
 165 .\" so we create the internet link definition using a macro, to make
 166 .\" it reusable.
 167 .\"
 168 .\" Note also, that we protect the description of the reference by
 169 .\" preceding it with "--", to avoid "invalid character in name" type
 170 .\" error messages from groff (caused by the use of "\~").
 171 .\"
 172 .pdfhref W -D http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/pdf_creation_apis_and_specs/pdfmarkReference.pdf \
 173     -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
 174 ..
 175 .pdfmark-manual ,
 176 with some refinement of the simple PDF production method, provided
 177 appropriate \(lqfeature implementing\(rq instructions can be embedded into
 178 .CW @L_ROFF@ 's
 179 PostScript\*(rg rendering of the document.
 180 This, of course, implies that the original document source, which
 181 .CW @L_ROFF@
 182 will process to generate the PostScript\*(rg description of the document,
 183 must include appropriate markup to exploit the desired PDF features.
 184 It is this preparation of the
 185 .CW @L_ROFF@
 186 document source to exploit a number of these features,
 187 which provides the principal focus of this document.
 188 .LP
 189 The markup techniques to be described have been utilised in the production of
 190 the PDF version of this document itself.
 191 This has been formatted using
 192 .CW @L_ROFF@ 's
 193 .CW ms
 194 macro package;
 195 thus, usage examples may be found in the document source file,
 196 .CW \n(.F ,
 197 to which comments have been added,
 198 to help identify appropriate markup examples for implementing PDF features,
 199 such as:\(en
 200 .QS
 201 .IP \(bu
 202 Selecting a default document view, which defines how the document will appear
 203 when opened in the reader application; for example, when this document is
 204 opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
 205 in the document view pane, while a document outline should appear to the left,
 206 in the \(lqBookmarks\(rq pane.
 207 .IP \(bu
 208 Adding document identification \(lqmeta\(hydata\(rq,
 209 which can be accessed, in Acrobat\*(rg\~Reader,
 210 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
 211 .IP \(bu
 212 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
 213 pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
 214 section of the document, simply by clicking on the associated heading
 215 in the outline view.
 216 .IP \(bu
 217 Embedding active links in the body of the document, such that readers may
 218 quickly navigate to related material at another location within the same
 219 document, or in another PDF document, or even to a related Internet resource,
 220 specified by its URI.
 221 .IP \(bu
 222 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
 223 points within the PDF document.
 224 .QE
 225 .LP
 226 All of the techniques described have been tested on
 227 .EM both
 228 GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
 229 .CW groff
 230 .CW 1.19.1 ,\c
 231 .pdfhref L -D footnote1 -- \**
 232 .FS
 233 .pdfhref M footnote1
 234 Later versions should, and some earlier versions may, be equally suitable.
 235 See
 236 .pdfhref W \*[ROFF-WEBSITE]
 237 for information and availability of the latest version.
 238 .FE
 239 in association with
 240 .CW AFPL
 241 .CW GhostScript
 242 .CW 8.14 .\c
 243 .pdfhref L -D footnote2 -- \**
 244 .FS
 245 .pdfhref M footnote2
 246 Again, other versions may be suitable.
 247 See
 248 .pdfhref W http://ghostscript.com
 249 for information and availability.
 250 .FE
 251 Other tools employed, which should be readily available on
 252 .EM any
 253 .SM
 254 UNIX\(tm
 255 .LG
 256 or GNU/Linux system, are
 257 .CW sed ,
 258 .CW awk
 259 and
 260 .CW make ,
 261 together with an appropriate text editor, for creating and marking up the
 262 .CW @L_ROFF@
 263 input files.
 264 These additional utilities are not provided, as standard,
 265 on the Microsoft\*(rg Windows\(tm platform,
 266 but several third party implementations are available.
 267 Some worth considering include the MKS\*(rg\~Toolkit,\**
 268 .FS
 269 A commercial offering; see
 270 .pdfhref W http://mkssoftware.com/products/tk/default.asp
 271 for information.
 272 .FE
 273 Cygwin,\**
 274 .FS
 275 A
 276 .EM free
 277 but comprehensive
 278 .SM
 279 POSIX
 280 .LG
 281 emulation environment and
 282 .SM
 283 UNIX\(tm
 284 .LG
 285 toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
 286 .pdfhref W http://cygwin.com
 287 for information and download.
 288 .FE
 289 or MSYS.\**
 290 .FS
 291 Another free, but minimal suite of common
 292 .SM
 293 UNIX\(tm
 294 .LG
 295 tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
 296 .pdfhref W -A ; http://www.mingw.org
 297 it
 298 .EM does
 299 include those tools listed above,
 300 and is the package which was actually used when performing the Windows\(tm2000
 301 platform tests referred to in the text.
 302 .FE
 303 This list is by no means exhaustive, and should in no way be construed as an
 304 endorsement of any of these packages, nor to imply that other similar packages,
 305 which may be available, are in any way inferior to them.
 306 .bp
 307 .NH 1
 308 .\" We may wish a section heading to represent a named destination,
 309 .\" so that we can create a linked reference to it, from some other
 310 .\" part of the PDF document, (or even from another PDF document).
 311 .\"
 312 .\" Here we use the "-N" option of the "XN" macro, to create a named
 313 .\" PDF link destination, at the location of the heading.  Notice that
 314 .\" we also use the "--" marker to separate the heading text from the
 315 .\" preceding option specification; it is not strictly necessary in
 316 .\" this case, but it does help to set off the heading text from the
 317 .\" option specification.
 318 .\"
 319 .XN -N pdf-features -- Exploiting PDF Document Features
 320 .LP
 321 To establish a consistent framework for adding PDF features, a
 322 .CW @L_ROFF@
 323 macro package, named
 324 .CW pdfmark.tmac ,
 325 has been provided.
 326 Thus, to incorporate PDF features in a document,
 327 the appropriate macro calls, as described below, may be placed in the
 328 .CW @L_ROFF@
 329 document source, which should then be processed with a
 330 .CW @L_ROFF@
 331 command of the form
 332 .QP
 333 .fam C
 334 @L_ROFF@ -Tps [-m
 335 .I name "] -m"
 336 .B pdfmark
 337 .I options \& [-
 338 .I "file ..." \& "...] "
 339 .LP
 340 It may be noted that the
 341 .CW pdfmark
 342 macros have no dependencies on, and no known conflicts with,
 343 any other
 344 .CW @L_ROFF@
 345 macro package;  thus, users are free to use any other macro package,
 346 of their choice, to format their documents, while also using the
 347 .CW pdfmark
 348 macros to add PDF features.
 349 .NH 2
 350 .XN -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
 351 .LP
 352 All PDF features are implemented by embedding instances of the
 353 .B \F[C]pdfmark\F[]
 354 operator, as described in the Adobe\*(rg
 355 .pdfmark-manual ,
 356 into
 357 .CW @L_ROFF@ 's
 358 PostScript\*(rg output stream.
 359 To facilitate the use of this operator, the
 360 .CW pdfmark
 361 macro package defines the primitive
 362 .CW pdfmark
 363 macro; it simply emits its argument list,
 364 as arguments to a
 365 .CW pdfmark
 366 operator, in the PostScript\*(rg output stream.
 367 .LP
 368 .pdfhref M -N pdfmark-example
 369 To illustrate the use of the
 370 .CW pdfmark
 371 macro, the following is a much simplified example of how a bookmark
 372 may be added to a PDF document outline
 373 .QP
 374 .CW ".pdfmark \e"
 375 .RS 4
 376 .nf
 377 .fam C
 378 /Count 2 \e
 379 /Title (An Example of a Bookmark with Two Children) \e
 380 /View  [/FitH \en[PDFPAGE.Y]] \e
 381 /OUT
 382 .RE
 383 .LP
 384 In general, users should rarely need to use the
 385 .CW pdfmark
 386 macro directly.
 387 In particular, the above example is too simple for general use; it
 388 .EM will
 389 create a bookmark, but it does
 390 .EM not
 391 address the issues of setting the proper value for the
 392 .CW /Count
 393 key, nor of computing the
 394 .CW PDFPAGE.Y
 395 value used in the
 396 .CW /View
 397 key. The
 398 .CW pdfmark
 399 macro package includes a more robust mechanism for creating bookmarks,
 400 .\"
 401 .\" Here is an example of how a local reference may be planted,
 402 .\" using the automatic formatting feature of the "pdfhref" macro.
 403 .\"
 404 .\" This is a forward reference to the named destination "add-outline",
 405 .\" which is defined below, using the "XN" wrapper macro, from the
 406 .\" "spdf.tmac" macro package.  The automatically formatted reference
 407 .\" will be enclosed in parentheses, as specified by the use of
 408 .\" "-P" and "-A" options.
 409 .\"
 410 .pdfhref L -P ( -A ), -D add-outline
 411 .\"
 412 which addresses these issues automatically.
 413 Nevertheless, the
 414 .CW pdfmark
 415 macro may be useful to users wishing to implement more advanced PDF features,
 416 than those currently supported directly by the
 417 .CW pdfmark
 418 macro package.
 419 .NH 2
 420 .XN -N docview -- Selecting an Initial Document View
 421 .LP
 422 By default,
 423 when a PDF document is opened,
 424 the first page will be displayed,
 425 at the default magnification set for the reader,
 426 and outline and thumbnail views will be hidden.
 427 When using a PDF reader,
 428 such as Acrobat\*(rg\~Reader,
 429 which supports the
 430 .CW /DOCVIEW
 431 class of the
 432 .CW pdfmark
 433 operator,
 434 these default initial view settings may be overridden,
 435 using the
 436 .CW pdfview
 437 macro.
 438 For example
 439 .QP
 440 .CW ".pdfview /PageMode /UseOutlines"
 441 .LP
 442 will cause Acrobat\*(rg\~Reader to open the document outline view,
 443 to the left of the normal page view,
 444 while
 445 .QP
 446 .CW ".pdfview /PageMode /UseThumbs"
 447 .LP
 448 will open the thumbnail view instead.
 449 .LP
 450 Note that the two
 451 .CW /PageMode
 452 examples, above, are mutually exclusive \(em it is not possible to have
 453 .EM both
 454 outline and thumbnail views open simultaneously.
 455 However, it
 456 .EM is
 457 permitted to add
 458 .CW /Page
 459 and
 460 .CW /View
 461 keys, to force the document to open at a page other than the first,
 462 or to change the magnification at which the document is initially displayed;
 463 see the
 464 .pdfmark-manual
 465 for more information.
 466 .LP
 467 It should be noted that the view controlling meta\(hydata, defined by the
 468 .CW pdfview
 469 macro, is not written immediately to the PostScript\*(rg output stream,
 470 but is stored in an internal meta\(hydata \(lqcache\(rq,
 471 (simply implemented as a
 472 .CW @L_ROFF@
 473 diversion).
 474 This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
 475 .CW pdfsync
 476 macro,
 477 .\"
 478 .\" Here is another example of how we may introduce a forward reference.
 479 .\" This time we are using the shorter notation afforded by the "XR" macro
 480 .\" provided by "spdf.tmac"; this example is equivalent to the native
 481 .\" "pdfmark.tmac" form
 482 .\"     .pdfhref L -D pdfsync -P ( -A ).
 483 .\"
 484 .XR pdfsync ). (
 485 .\"
 486 .NH 2
 487 .XN -N docinfo -- Adding Document Identification Meta-Data
 488 .LP
 489 In addition to the
 490 .CW /DOCVIEW
 491 class of meta\(hydata described above,
 492 .XR docview ), (
 493 we may also wish to include document identification meta\(hydata,
 494 which belongs to the PDF
 495 .CW /DOCINFO
 496 class.
 497 .LP
 498 To do this, we use the
 499 .CW pdfinfo
 500 macro.
 501 As an example of how it is used,
 502 the identification meta\(hydata attached to this document
 503 was specified using a macro sequence similar to:\(en
 504 .DS I
 505 .CW
 506 \&.pdfinfo /Title     PDF Document Publishing with GNU Troff
 507 \&.pdfinfo /Author    Keith Marshall
 508 \&.pdfinfo /Subject   How to Exploit PDF Features with GNU Troff
 509 \&.pdfinfo /Keywords  @T_ROFF@ @T_TROFF@ PDF pdfmark
 510 .DE
 511 Notice that the
 512 .CW pdfinfo
 513 macro is repeated, once for each
 514 .CW /DOCINFO
 515 record to be placed in the document.
 516 In each case, the first argument is the name of the applicable
 517 .CW /DOCINFO
 518 key, which
 519 .EM must
 520 be named with an initial solidus character;
 521 all additional arguments are collected together,
 522 to define the value to be associated with the specified key.
 523 .LP
 524 As is the case with the
 525 .CW pdfview
 526 macro,
 527 .XR docview ), (
 528 the
 529 .CW /DOCINFO
 530 records specified with the
 531 .CW pdfinfo
 532 macro are not immediately written to the PostScript\*(rg output stream;
 533 they are stored in the same meta\(hydata cache as
 534 .CW /DOCVIEW
 535 specifications, until this cache is explicitly flushed,
 536 by invoking the
 537 .CW pdfsync
 538 macro,
 539 .XR pdfsync ). (
 540 .NH 2
 541 .XN -N add-outline -- Creating a Document Outline
 542 .LP
 543 A PDF document outline comprises a table of references,
 544 to \(lqbookmarked\(rq locations within the document.
 545 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
 546 such as Adobe\*(rg Acrobat\*(rg Reader,
 547 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
 548 or \(lqBookmarks\(rq pane, to the left of the main document view.
 549 Individual references in the outline view may then be selected,
 550 by clicking with the mouse,
 551 to jump directly to the associated marked location in the document view.
 552 .LP
 553 The document outline may be considered as a collection of \(lqhypertext\(rq
 554 references to \(lqbookmarked\(rq locations within the document.
 555 The
 556 .CW pdfmark
 557 macro package provides a single generalised macro,
 558 .CW pdfhref ,
 559 for creating and linking to \(lqhypertext\(rq reference marks.
 560 This macro will be described more comprehensively in a later section,
 561 .XR pdfhref ); (
 562 the description here is restricted to its use for defining document outline entries.
 563 .NH 3
 564 .XN -N basic-outline -- A Basic Document Outline
 565 .LP
 566 In its most basic form, the document outline comprises a structured list of headings,
 567 each associated with a marked location, or \(lqbookmark\(rq, in the document text,
 568 and a specification for how that marked location should be displayed,
 569 when this bookmark is selected.
 570 .LP
 571 To create a PDF bookmark, the
 572 .CW pdfhref
 573 macro is used,
 574 at the point in the document where the bookmark is to be placed,
 575 in the form
 576 .QP
 577 .fam C
 578 .B ".pdfhref O"
 579 .I level > <
 580 .I "descriptive text ..."
 581 .LP
 582 in which the reference class
 583 .CWB O \& \& \(rq \(lq
 584 stipulates that this is an outline reference.
 585 .LP
 586 Alternatively, for those users who may prefer to think of a document outline
 587 simply as a collection of bookmarks, the
 588 .CW pdfbookmark
 589 macro is also provided \(em indeed,
 590 .CW pdfhref
 591 invokes it, when processing the
 592 .CWB O \& \& \(rq \(lq
 593 reference class operator.
 594 It may be invoked directly, in the form
 595 .QP
 596 .fam C
 597 .B .pdfbookmark
 598 .I level > <
 599 .I "descriptive text ..."
 600 .LP
 601 Irrespective of which of the above macro forms is employed, the
 602 .CWI level > <
 603 argument is required.
 604 It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
 605 in the outline hierarchy, with one being the topmost level.
 606 Its function may be considered analagous to the
 607 .EM "heading level"
 608 of the document's section headings,
 609 for example, as specified with the
 610 .CW NH
 611 macro, if using the
 612 .CW ms
 613 macros to format the document.
 614 .LP
 615 All further arguments, following the
 616 .CWI level > <
 617 argument, are collected together, to specify the heading text which will appear
 618 in the document's outline view.
 619 Thus, the outline entry for this section of this document,
 620 which has a level three heading,
 621 might be specified as
 622 .QP
 623 .CW
 624 \&.pdfhref O 3 \*(SN A Basic Document Outline
 625 .LP
 626 or, in the alternative form using the
 627 .CW pdfbookmark
 628 macro, as
 629 .QP
 630 .CW
 631 \&.pdfbookmark 3 \*(SN A Basic Document Outline
 632 .NH 3
 633 .XN Hierarchical Structure in a Document Outline
 634 .LP
 635 When a document outline is created, using the
 636 .CW pdfhref
 637 macro as described in
 638 .\"
 639 .\" Here is an example of how we can temporarily modify the format of
 640 .\" a reference link, in this case to indicate only the section number
 641 .\" of the link target, in the form "section #", (or, if we define
 642 .\" "SECREF.BEGIN" before the call, its content followed by the
 643 .\" section number).
 644 .\"
 645 .\" We first define a macro, which will get the reference data from
 646 .\" pdfhref, as arguments, and will return the formatted output, as we
 647 .\" require it, the string "PDFHREF.TEXT".
 648 .\"
 649 .de SECREF
 650 .while \\n(.$ \{\
 651 .   ie '\\$1'section' \{\
 652 .      if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
 653 .      ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
 654 .      rm SECREF.BEGIN
 655 .      shift \\n(.$
 656 .      \}
 657 .   el .shift
 658 .   \}
 659 ..
 660 .\" We now tell "pdfhref" to use our formatting macro, in place of
 661 .\" its builtin default formatter, before we specify the reference.
 662 .\"
 663 .pdfhref F SECREF
 664 .pdfhref L -A , -D basic-outline
 665 .\"
 666 .\" At this point, we would normally revert the "pdfhref" formatter
 667 .\" to use its default, built in macro.  However, in this particular
 668 .\" case, we want to use our custom format one more time, before we
 669 .\" revert it, so we will omit the reversion step this time.
 670 .\"
 671 and any entry is added at a nesting level greater than one,
 672 then a hierarchical structure is automatically defined for the outline.
 673 However, as was noted in the simplified
 674 .pdfhref L -D pdfmark-example -- example
 675 in
 676 .pdfhref L -A , -D pdfmark-operator
 677 .\"
 678 .\" And now, we revert to default "pdfhref" formatting behaviour,
 679 .\" by completing the call we delayed above.
 680 .\"
 681 .pdfhref F
 682 .\"
 683 the data required by the
 684 .CW pdfmark
 685 operator to create the outline entry may not be fully defined,
 686 when the outline reference is defined in the
 687 .CW @L_ROFF@
 688 document source.
 689 Specifically, when the outline entry is created, its
 690 .CW /Count
 691 key must be assigned a value equal to the number of its subordinate entries,
 692 at the next inner level of the outline hierarchy;
 693 typically however,
 694 these subordinate entries will be defined
 695 .EM later
 696 in the document source, and the appropriate
 697 .CW /Count
 698 value will be unknown, when defining the parent entry.
 699 .LP
 700 To resolve this paradox, the
 701 .CW pdfhref
 702 macro creates the outline entry in two distinct phases \(em
 703 a destination marker is placed in the PostScript\*(rg output stream immediately,
 704 when the outline reference is defined,
 705 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
 706 until its subordinate hierarchy has been fully defined;
 707 it can then be inserted in the output stream, with its
 708 .CW /Count
 709 value correctly assigned.
 710 Effectively, to ensure integrity of the document outline structure,
 711 this means that each top level outline entry, and
 712 .EM all
 713 of its subordinates, are retained in the cache, until the
 714 .EM next
 715 top level entry is defined.
 716 .LP
 717 One potential problem, which arises from the use of the \(lqoutline cache\(rq,
 718 is that, at the end of any document formatting run, the last top level outline entry,
 719 and any subordinates defined after it, will remain in the cache, and will
 720 .EM not
 721 be automatically written to the output stream.
 722 To avoid this problem, the user should follow the guidelines given in
 723 .\"
 724 .\" Here is a more conventional example of how to temporarily change
 725 .\" to the format used to display reference links.  We will again use
 726 .\" the "SECREF" format, which we defined above, but on this occasion
 727 .\" we will immediately revert to the default format, after the link
 728 .\" has been placed.
 729 .\"
 730 .pdfhref F SECREF
 731 .pdfhref L -D pdfsync -A ,
 732 .pdfhref F
 733 .\"
 734 to synchronise the output state with the cache state,
 735 .XR pdfsync ), (
 736 at the end of the
 737 .CW @L_ROFF@
 738 formatting run.
 739 .NH 3
 740 .XN -N outline-view -- Associating a Document View with an Outline Reference
 741 .LP
 742 Each \(lqbookmark\(rq entry, in a PDF document outline,
 743 is associated with a specific document view.
 744 When the reader selects any outline entry,
 745 the document view changes to display the document context
 746 associated with that entry.
 747 .LP
 748 The document view specification,
 749 to be associated with any document outline entry,
 750 is established at the time when the outline entry is created.
 751 However, rather than requiring that each individual use of the
 752 .CW pdhref
 753 macro, to create an outline entry,
 754 should include its own view specification,
 755 the actual specification assigned to each entry is derived from
 756 a generalised specification defined in the string
 757 .CW PDFBOOKMARK.VIEW ,
 758 together with the setting of the numeric register
 759 .CW PDFHREF.VIEW.LEADING ,
 760 which determine the effective view specification as follows:\(en
 761 .QS
 762 .IP \*[= PDFBOOKMARK.VIEW]
 763 Establishes the magnification at which the document will be viewed,
 764 at the location of the \(lqbookmark\(rq; by default, it is defined by
 765 .RS
 766 .QP
 767 .CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
 768 .RE
 769 .IP
 770 which displays the associated document view,
 771 with the \(lqbookmark\(rq location positioned at the top of the display window,
 772 and with the magnification set to fit the page width to the width of the window.
 773 .IP \*[= PDFHREF.VIEW.LEADING]
 774 Specifies additional spacing,
 775 to be placed between the top of the display window
 776 and the actual location of the \(lqbookmark\(rq on the displayed page view.
 777 By default, it is set as
 778 .RS
 779 .QP
 780 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
 781 .RE
 782 .IP
 783 Note that
 784 .CW PDFHREF.VIEW.LEADING
 785 does not represent true \(lqleading\(rq, in the typographical sense,
 786 since any preceding text, set in the specified display space,
 787 will be visible at the top of the document viewing window,
 788 when the reference is selected.
 789 .IP
 790 Also note that the specification of
 791 .CW PDFHREF.VIEW.LEADING
 792 is shared by
 793 .EM all
 794 reference views defined by the
 795 .CW pdfhref
 796 macro; whereas
 797 .CW PDFBOOKMARK.VIEW
 798 is applied exclusively to outline references,
 799 there is no independent
 800 .CW PDFBOOKMARK.VIEW.LEADING
 801 specification.
 802 .QE
 803 .LP
 804 If desired, the view specification may be changed, by redefining the string
 805 .CW PDFBOOKMARK.VIEW ,
 806 and possibly also the numeric register
 807 .CW PDFHREF.VIEW.LEADING .
 808 Any alternative definition for
 809 .CW PDFBOOKMARK.VIEW
 810 .EM must
 811 be specified in terms of valid view specification parameters,
 812 as described in the Adobe\*(rg
 813 .pdfmark-manual .
 814 .LP
 815 Note the use of the register
 816 .CW PDFPAGE.Y ,
 817 in the default definition of
 818 .CW PDFBOOKMARK.VIEW
 819 above.
 820 This register is computed by
 821 .CW pdfhref ,
 822 when creating an outline entry;
 823 it specifies the vertical position of the \(lqbookmark\(rq,
 824 in basic
 825 .CW @L_ROFF@
 826 units, relative to the
 827 .EM bottom
 828 edge of the document page on which it is defined,
 829 and is followed, in the
 830 .CW PDFBOOKMARK.VIEW
 831 definition, by the
 832 .CW @L_D_PS@
 833 .CW u \(rq \(lq
 834 operator, to convert it to PostScript\*(rg units on output.
 835 It may be used in any redefined specification for
 836 .CW PDFBOOKMARK.VIEW ,
 837 (or in the analogous definition of
 838 .CW PDFHREF.VIEW ,
 839 described in
 840 .XR-NO-PREFIX pdfhref-view ),
 841 but
 842 .EM not
 843 in any other context,
 844 since its value is undefined outside the scope of the
 845 .CW pdfhref
 846 macro.
 847 .LP
 848 Since
 849 .CW PDFPAGE.Y
 850 is computed relative to the
 851 .EM bottom
 852 of the PDF output page,
 853 it is important to ensure that the page length specified to
 854 .CW troff
 855 correctly matches the size of the logical PDF page.
 856 This is most effectively ensured,
 857 by providing
 858 .EM identical
 859 page size specifications to
 860 .CW @L_ROFF@ ,
 861 .CW @L_D_PS@
 862 and to the PostScript\*(rg to PDF converter employed,
 863 and avoiding any page length changes within the document source.
 864 .LP
 865 Also note that
 866 .CW PDFPAGE.Y
 867 is the only automatically computed \(lqbookmark\(rq location parameter;
 868 if the user redefines
 869 .CW PDFBOOKMARK.VIEW ,
 870 and the modified view specification requires any other positional parameters,
 871 then the user
 872 .EM must
 873 ensure that these are computed
 874 .EM before
 875 invoking the
 876 .CW pdfhref
 877 macro.
 878 .NH 3
 879 .XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
 880 .LP
 881 When a document incorporates many subheadings,
 882 at deeply nested levels,
 883 it may be desirable to \(lqfold\(rq the outline
 884 such that only the major heading levels are initially visible,
 885 yet making the inferior subheadings accessible,
 886 by allowing the reader to expand the view of any heading branch on demand.
 887 .LP
 888 The
 889 .CW pdfmark
 890 macros support this capability,
 891 through the setting of the
 892 .CW PDFOUTLINE.FOLDLEVEL
 893 register.
 894 This register should be set to the number of heading levels
 895 which it is desired to show in expanded form, in the
 896 .EM initial
 897 document outline display;
 898 all subheadings at deeper levels will still be added to the outline,
 899 but will not become visible until the outline branch containing them is expanded.
 900 'ne 5
 901 For example, the setting used in this document:
 902 .QS
 903 .LD
 904 .fam C
 905 \&.\e" Initialise the outline view to show only three heading levels,
 906 \&.\e" with additional subordinate level headings folded.
 907 \&.\e"
 908 \&.nr PDFOUTLINE.FOLDLEVEL 3
 909 .DE
 910 .QE
 911 .LP
 912 results in only the first three levels of headings being displayed
 913 in the document outline,
 914 .EM until
 915 the reader chooses to expand the view,
 916 and so reveal the lower level headings in any outline branch.
 917 .LP
 918 The initial default setting of
 919 .CW PDFOUTLINE.FOLDLEVEL ,
 920 if the document author does not choose to change it,
 921 is 10,000.
 922 This is orders of magnitude greater than the maximum heading level
 923 which is likely to be used in any document;
 924 thus the default behaviour will be to show document outlines fully expanded,
 925 to display all headings defined,
 926 at all levels within each document.
 927 .LP
 928 The setting of
 929 .CW PDFOUTLINE.FOLDLEVEL
 930 may be changed at any time;
 931 however, the effect of each such change may be difficult to predict,
 932 since it is applied not only to outline entries which are defined
 933 .EM after
 934 the setting is changed,
 935 but also to any entries which remain in the outline cache,
 936 .EM at
 937 this time.
 938 Therefore, it is recommended that
 939 .CW PDFOUTLINE.FOLDLEVEL
 940 should be set
 941 .EM once ,
 942 at the start of each document;
 943 if it
 944 .EM is
 945 deemed necessary to change it at any other time,
 946 the outline cache should be flushed,
 947 .XR pdfsync ), (
 948 .EM immediately
 949 before the change,
 950 which should immediately preceed a level one heading.
 951 .NH 3
 952 .XN -N multipart-outline -- Outlines for Multipart Documents
 953 .LP
 954 When a document outline is created, using the
 955 .CW pdfhref
 956 macro, each reference mark is automatically assigned a name,
 957 composed of a fixed stem followed by a serially generated numeric qualifier.
 958 This ensures that, for each single part document, every outline reference
 959 has a uniquely named destination.
 960 .LP
 961 As the overall size of the PDF document increases,
 962 it may become convenient to divide it into smaller,
 963 individually formatted PostScript\*(rg components,
 964 which are then assembled, in the appropriate order,
 965 to create a composite PDF document.
 966 While this strategy may simplify the overall process of creating and
 967 editing larger documents, it does introduce a problem in creating
 968 an overall document outline,
 969 since each individual PostScript\*(rg component will be assigned
 970 duplicated sequences of \(lqbookmark\(rq names,
 971 with each name ultimately referring to multiple locations in the composite document.
 972 To avoid such reference naming conflicts, the
 973 .CW pdfhref
 974 macro allows the user to specify a \(lqtag\(rq,
 975 which is appended to the automatically generated \(lqbookmark\(rq name;
 976 this may be used as a discriminating mark, to distinguish otherwise
 977 similarly named destinations, in different sections of the composite document.
 978 .LP
 979 To create a \(lqtagged\(rq document outline,
 980 the syntax for invocation of the
 981 .CW pdfhref
 982 macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
 983 .EM before
 984 the nesting level argument, i.e.
 985 .QP
 986 .fam C
 987 .B ".pdfhref O"
 988 .B -T \& [
 989 .I tag >] <
 990 .I level > <
 991 .I "descriptive text ..."
 992 .LP
 993 The optional
 994 .CWI tag > <
 995 argument may be composed of any characters of the user's choice;
 996 however, its initial character
 997 .EM "must not"
 998 be any decimal digit, and ideally it should be kept short
 999 \(em one or two characters at most.
1000 .LP
1001 By employing a different tag in each section,
1002 the user can ensure that \(lqbookmark\(rq names remain unique,
1003 throughout all the sections of a composite document.
1004 For example, when using the
1005 .CW spdf.tmac
1006 macro package, which adds
1007 .CW pdfmark
1008 capabilities to the standard
1009 .CW ms
1010 package,
1011 .XR using-spdf ), (
1012 the table of contents is collected into a separate PostScript\*(rg section
1013 from the main body of the document.
1014 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
1015 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
1016 .CW TC
1017 macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
1018 invoking the
1019 .CW pdfhref
1020 macro as
1021 .QP
1022 .CW ".pdfhref O -T T 1 \e\e*[TOC]"
1023 .LP
1024 to tag the associated outline destination name with the single character suffix,
1025 .CW T \(rq. \(lq
1026 Alternatively, as in the case of the basic outline,
1027 .XR basic-outline ), (
1028 this may equally well be specified as
1029 .QP
1030 .CW ".pdfbookmark -T T 1 \e\e*[TOC]"
1031 .NH 3
1032 .XN Delegation of the Outline Definition
1033 .LP
1034 Since the most common use of a document outline
1035 is to provide a quick method of navigating through a document,
1036 using active \(lqhypertext\(rq links to chapter and section headings,
1037 it may be convenient to delegate the responsibility of creating the outline
1038 to a higher level macro, which is itself used to
1039 define and format the section headings.
1040 This approach has been adopted in the
1041 .CW spdf.tmac
1042 package, to be described later,
1043 .XR using-spdf ). (
1044 .LP
1045 When such an approach is adopted,
1046 the user will rarely, if ever, invoke the
1047 .CW pdfhref
1048 macro directly, to create a document outline.
1049 For example, the structure and content of the outline for this document
1050 has been exclusively defined, using a combination of the
1051 .CW NH
1052 macro, from the
1053 .CW ms
1054 package, to establish the structure, and the
1055 .CW XN
1056 macro from
1057 .CW spdf.tmac ,
1058 to define the content.
1059 In this case,
1060 the responsibility for invoking the
1061 .CW pdfhref
1062 macro, to create the document outline,
1063 is delegated to the
1064 .CW XN
1065 macro.
1066 .NH 2
1067 .XN -N pdfhref -- Adding Reference Marks and Links
1068 .LP
1069 .pdfhref F SECREF
1070 .ds SECREF.BEGIN Section
1071 .pdfhref L -D add-outline
1072 .pdfhref F
1073 has shown how the
1074 .CW pdfhref
1075 macro may be used to create a PDF document outline.
1076 While this is undoubtedly a powerful capability,
1077 it is by no means the only trick in the repertoire of this versatile macro.
1078 .LP
1079 The macro name,
1080 .CW pdfhref ,
1081 which is a contraction of \(lqPDF HyperText Reference\(rq,
1082 indicates that the general purpose of this macro is to define
1083 .EM any
1084 type of dynamic reference mark, within a PDF document.
1085 Its generalised usage syntax takes the form
1086 .QP
1087 .fam C
1088 .B .pdfhref
1089 .BI class > <
1090 .I "-options ...\&" ] [
1091 [--]
1092 .I "descriptive text ...\&" ] [
1093 .LP
1094 where
1095 .CW <\f(CIclass\fP>
1096 represents a required single character argument,
1097 which defines the specific reference operation to be performed,
1098 and may be selected from:\(en
1099 .QS
1100 .IP \*[= O]
1101 Add an entry to the document outline.
1102 This operation has been described earlier,
1103 .XR add-outline ). (
1104 .IP \*[= M]
1105 Place a \(lqnamed destination\(rq reference mark at the current output position,
1106 in the current PDF document,
1107 .XR mark-dest ). (
1108 .IP \*[= D]
1109 Specify the content of a PDF document reference dictionary entry;
1110 typically, such entries are generated automatically,
1111 by transformation of the intermediate output resulting from the use of
1112 .CW pdfhref
1113 .CWB M \& \& \(rq, \(lq
1114 with the
1115 .CWB -X \& \& \(rq \(lq
1116 modifier,
1117 .XR create-map ); (
1118 however, it is also possible to specify such entries manually,
1119 .XR user-format ). (
1120 .IP \*[= L]
1121 Insert an active link to a named destination,
1122 .XR link-named ), (
1123 at the current output position in the current PDF document,
1124 such that when the reader clicks on the link text,
1125 the document view changes to show the location of the named destination.
1126 .IP \*[= W]
1127 Insert an active link to a \(lqweb\(rq resource,
1128 .XR add-weblink ), (
1129 at the current output position in the current PDF document.
1130 This is effectively the same as using the
1131 .CWB L \& \& \(rq \(lq
1132 operator to establish a link to a named destination in another PDF document,
1133 .XR link-extern ), (
1134 except that in this case, the destination is specified by a
1135 \(lquniform resource identifier\(rq, or
1136 .CW URI ;
1137 this may represent any Internet or local resource
1138 which can be specified in this manner.
1139 .IP \*[= F]
1140 Specify a user defined macro, to be called by
1141 .CW pdfhref ,
1142 when formatting the text in the active region of a link,
1143 .XR set-format ). (
1144 .IP \*[= Z]
1145 Define the absolute position on the physical PDF output page,
1146 where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
1147 Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
1148 for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
1149 specified directly by the user;
1150 rather, appropriate
1151 .CW pdfhref
1152 .CWB Z \& \& \(rq \(lq
1153 specifications are inserted automatically into the document reference map
1154 during the PDF document formatting process,
1155 .XR create-map ). (
1156 .IP \*[= I]
1157 Initialise support for
1158 .CW pdfhref
1159 features.
1160 The current
1161 .CW pdfhref
1162 implementation provides only one such feature which requires initialisation
1163 \(em a helper macro which must be attached to a user supplied page trap handler,
1164 in order to support mapping of reference \(lqhot\(hyspots\(rq
1165 which extend through a page transition;
1166 .XR page-trap ). (
1167 .QE
1168 .NH 3
1169 .XN Optional Features of the \F[C]pdfhref\F[] Macro
1170 .LP
1171 The behaviour of a number of the
1172 .CW pdfhref
1173 macro operations can be modified,
1174 by including
1175 .EM "option specifiers" \(rq \(lq
1176 after the operation specifying argument,
1177 but
1178 .EM before
1179 any other arguments normally associated with the operation.
1180 In
1181 .EM all
1182 cases, an option is specified by an
1183 .EM "option flag" \(rq, \(lq
1184 comprising an initial hyphen,
1185 followed by one or two option identifying characters.
1186 Additionally,
1187 .EM some
1188 options require
1189 .EM "exactly one"
1190 option argument;
1191 for these options, the argument
1192 .EM must
1193 be specified, and it
1194 .EM must
1195 be separated from the preceding option flag by one or more
1196 .EM spaces ,
1197 (tabs
1198 .EM "must not"
1199 be used).
1200 It may be noted that this paradigm for specifying options
1201 is reminiscent of most
1202 .SM
1203 UNIX\(tm
1204 .LG
1205 shells; however, in the case of the
1206 .CW pdfhref
1207 macro, omission of the space separating an option flag from its argument is
1208 .EM never
1209 permitted.
1210 .LP
1211 A list of
1212 .EM all
1213 general purpose options supported by the
1214 .CW pdfhref
1215 macro is given below.
1216 Note that not all options are supported for all
1217 .CW pdfhref
1218 operations; the operations affected by each option are noted in the list.
1219 For
1220 .EM most
1221 operations, if an unsupported option is specified,
1222 it will be silently ignored; however, this behaviour should
1223 not be relied upon.
1224 .LP
1225 The general purpose options, supported by the
1226 .CW pdfhref
1227 macro, are:\(en
1228 .QS
1229 .IP \*[= -N\0 name > <]
1230 Allows the
1231 .CWI name > <
1232 associated with a PDF reference destination
1233 to be defined independently from the following text,
1234 which describes the reference.
1235 This option affects only the
1236 .CWB M \& \& \(rq \(lq
1237 operation of the
1238 .CW pdfhref
1239 macro,
1240 .XR mark-dest ). (
1241 .IP \*[= -E]
1242 Also used exclusively with the
1243 .CWB M \& \& \(rq \(lq
1244 operator, the
1245 .CWB -E
1246 option causes any specified
1247 .CWI descriptive \& \& \~\c
1248 .CWI text
1249 arguments,
1250 .XR mark-dest ), (
1251 to be copied, or
1252 .EM echoed ,
1253 in the body text of the document,
1254 at the point where the reference mark is defined;
1255 (without the
1256 .CWB -E
1257 option, such
1258 .CWI descriptive \& \& \~\c
1259 .CWI text
1260 will appear
1261 .EM only
1262 at points where links to the reference mark are placed,
1263 and where the standard reference display format,
1264 .XR set-format ), (
1265 is used).
1266 .IP \*[= -D\0 dest > <]
1267 Specifies the
1268 .CW URI ,
1269 or the destination name associated with a PDF active link,
1270 independently of the following text,
1271 which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
1272 This option affects the behaviour of the
1273 .CW pdfhref
1274 macro's
1275 .CWB L \& \& \(rq \(lq
1276 and
1277 .CWB W \& \& \(rq \(lq
1278 operations.
1279 .IP
1280 When used with the
1281 .CWB L \& \& \(rq \(lq
1282 operator, the
1283 .CWI dest > <
1284 argument must specify a PDF \(lqnamed destination\(rq,
1285 as defined using
1286 .CW pdfhref
1287 with the
1288 .CWB M \& \& \(rq \(lq
1289 operator.
1290 .IP
1291 When used with the
1292 .CWB W \& \& \(rq \(lq
1293 operator,
1294 .CWI dest > <
1295 must specify a link destination in the form of a
1296 \(lquniform resource identifier\(rq, or
1297 .CW URI ,
1298 .XR add-weblink ). (
1299 .IP \*[= -F\0 file > <]
1300 When used with the
1301 .CWB L \& \& \(rq \(lq
1302 .CW pdfhref
1303 operator,
1304 .CWI file > <
1305 specifies an external PDF file in which the named destination
1306 for the link reference is defined.
1307 This option
1308 .EM must
1309 be specified with the
1310 .CWB L \& \& \(rq \(lq
1311 operator,
1312 to create a link to a destination in a different PDF document;
1313 when the
1314 .CWB L \& \& \(rq \(lq
1315 operator is used
1316 .EM without
1317 this option, the link destination is assumed to be defined
1318 within the same document.
1319 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
1320 Specifies
1321 .CWI \(dqprefix\(hytext\(dq > <
1322 to be attached to the
1323 .EM start
1324 of the text describing an active PDF document link,
1325 with no intervening space, but without itself being included in the
1326 active area of the link \(lqhot\(hyspot\(rq;
1327 it is effective with the
1328 .CWB L \& \& \(rq \(lq
1329 and
1330 .CWB W \& \& \(rq \(lq
1331 .CW pdfhref
1332 operators.
1333 .IP
1334 Typically, this option would be used to insert punctuation before
1335 the link \(lqhot\(hyspot\(rq.
1336 Thus, there is little reason for the inclusion of spaces in
1337 .CWI \(dqprefix\(hytext\(dq > < ;
1338 however, if such space is required, then the enclosing double quotes
1339 .EM must
1340 be specified, as indicated.
1341 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
1342 Specifies
1343 .CWI \(dqaffixed\(hytext\(dq > <
1344 to be attached to the
1345 .EM end
1346 of the text describing an active PDF document link,
1347 with no intervening space, but without itself being included in the
1348 active area of the link \(lqhot\(hyspot\(rq;
1349 it is effective with the
1350 .CWB L \& \& \(rq \(lq
1351 and
1352 .CWB W \& \& \(rq \(lq
1353 .CW pdfhref
1354 operators.
1355 .IP
1356 Typically, this option would be used to insert punctuation after
1357 the link \(lqhot\(hyspot\(rq.
1358 Thus, there is little reason for the inclusion of spaces in
1359 .CWI \(dqaffixed\(hytext\(dq > < ;
1360 however, if such space is required, then the enclosing double quotes
1361 .EM must
1362 be specified, as indicated.
1363 .IP \*[= -T\0 tag > <]
1364 When specified with the
1365 .CWB O \& \& \(rq \(lq
1366 operator,
1367 .CWI tag > <
1368 is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
1369 This option is
1370 .EM required ,
1371 to distinguish between the series of \(lqbookmark\(rq names generated in
1372 individual passes of the
1373 .CW @L_ROFF@
1374 formatter, when the final PDF document is to be assembled
1375 from a number of separately formatted components;
1376 .XR multipart-outline ). (
1377 .IP \*[= -X]
1378 This
1379 .CW pdfhref
1380 option is used with either the
1381 .CWB M \& \& \(rq \(lq
1382 operator, or with the
1383 .CWB L \& \& \(rq \(lq
1384 operator.
1385 .IP
1386 When used with the
1387 .CWB M \& \& \(rq \(lq
1388 operator,
1389 .XR mark-dest ), (
1390 it ensures that a cross reference record for the marked destination
1391 will be included in the document reference map,
1392 .XR export-map ). (
1393 .IP
1394 When used with the
1395 .CWB L \& \& \(rq \(lq
1396 operator,
1397 .XR link-named ), (
1398 it causes the reference to be displayed in the standard cross reference format,
1399 .XR set-format ), (
1400 but substituting the
1401 .CWI descriptive \& \& \~\c
1402 .CWI text
1403 specified in the
1404 .CW pdfhref \& \(lq
1405 .CW L \(rq
1406 argument list,
1407 for the description specified in the document reference map.
1408 .IP \*[= --]
1409 Marks the end of the option specifiers.
1410 This may be used with all
1411 .CW pdfhref
1412 operations which accept options, to prevent
1413 .CW pdfhref
1414 from interpreting any following arguments as option specifiers,
1415 even if they would otherwise be interpreted as such.
1416 It is also useful when the argument list to
1417 .CW pdfhref
1418 contains special characters \(em any special character,
1419 which is not valid in a
1420 .CW @L_ROFF@
1421 macro name, will cause a parsing error, if
1422 .CW pdfhref
1423 attempts to match it as a possible option flag;
1424 using the
1425 .CW -- \(rq \(lq
1426 flag prevents this, so suppressing the
1427 .CW @L_ROFF@
1428 warning message, which would otherwise ensue.
1429 .IP
1430 Using this flag after
1431 .EM all
1432 sequences of macro options is recommended,
1433 even when it is not strictly necessary,
1434 if only for the entirely cosmetic benefit of visually separating
1435 the main argument list from the sequence of preceding options.
1436 .QE
1437 .LP
1438 In addition to the
1439 .CW pdfhref
1440 options listed above, a supplementary set of two character options are defined.
1441 These supplementary options, listed below, are intended for use with the
1442 .CWB L \& \& \(rq \(lq
1443 operator, in conjunction with the
1444 .CWB -F \& \& \~\c
1445 .CWBI file > <
1446 option, to specify alternate file names,
1447 in formats compatible with the file naming conventions
1448 of alternate operating systems;
1449 they will be silently ignored, if used in any other context.
1450 .LP
1451 The supported alternate file name options,
1452 which are ignored if the
1453 .CWB -F \& \& \~\c
1454 .CWBI file > <
1455 option is not specified, are:\(en
1456 .QS
1457 .IP \*[= -DF\0 dos\(hyfile > <]
1458 Specifies the name of the file in which a link destination is defined,
1459 using the file naming semantics of the
1460 .CW MS\(hyDOS \*(rg
1461 operating system.
1462 When the PDF document is read on a machine
1463 where the operating system uses the
1464 .CW MS\(hyDOS \*(rg
1465 file system, then
1466 .CWI dos\(hyfile > <
1467 is used as the name of the file containing the reference destination,
1468 overriding the
1469 .CWI file > <
1470 argument specified with the
1471 .CWB -F
1472 option.
1473 .IP \*[= -MF\0 mac\(hyfile > <]
1474 Specifies the name of the file in which a link destination is defined,
1475 using the file naming semantics of the
1476 .CW Apple \*(rg
1477 .CW Macintosh \*(rg
1478 operating system.
1479 When the PDF document is read on a machine
1480 where the operating system uses the
1481 .CW Macintosh \*(rg
1482 file system, then
1483 .CWI mac\(hyfile > <
1484 is used as the name of the file containing the reference destination,
1485 overriding the
1486 .CWI file > <
1487 argument specified with the
1488 .CWB -F
1489 option.
1490 .IP \*[= -UF\0 unix\(hyfile > <]
1491 Specifies the name of the file in which a link destination is defined,
1492 using the file naming semantics of the
1493 .CW UNIX \(tm
1494 operating system.
1495 When the PDF document is read on a machine
1496 where the operating system uses
1497 .CW POSIX
1498 file naming semantics, then
1499 .CWI unix\(hyfile > <
1500 is used as the name of the file containing the reference destination,
1501 overriding the
1502 .CWI file > <
1503 argument specified with the
1504 .CWB -F
1505 option.
1506 .IP \*[= -WF\0 win\(hyfile > <]
1507 Specifies the name of the file in which a link destination is defined,
1508 using the file naming semantics of the
1509 .CW MS\(hyWindows \*(rg
1510 32\(hybit operating system.
1511 When the PDF document is read on a machine
1512 where the operating system uses any of the
1513 .CW MS\(hyWindows \*(rg
1514 file systems, with long file name support, then
1515 .CWI win\(hyfile > <
1516 is used as the name of the file containing the reference destination,
1517 overriding the
1518 .CWI file > <
1519 argument specified with the
1520 .CWB -F
1521 option.
1522 .QE
1523 .NH 3
1524 .XN -N mark-dest -- Marking a Reference Destination
1525 .LP
1526 The
1527 .CW pdfhref
1528 macro may be used to create active links to any Internet resource,
1529 specified by its
1530 .CW URI ,
1531 or to any \(lqnamed destination\(rq,
1532 either within the same document, or in another PDF document.
1533 Although the PDF specification allows link destinations to be defined
1534 in terms of a page number, and an associated view specification,
1535 this style of reference is not currently supported by the
1536 .CW pdfhref
1537 macro, because it is not possible to adequately bind the specification
1538 for the destination with the intended reference context.
1539 .LP
1540 References to Internet resources are interpreted in accordance with the
1541 .CW W3C
1542 standard for defining a
1543 .CW URI ;
1544 hence the only prerequisite, for creating a link to any Internet resource,
1545 is that the
1546 .CW URI
1547 be properly specified, when declaring the reference;
1548 .XR add-weblink ). (
1549 In the case of references to \(lqnamed destinations\(rq in PDF documents,
1550 however, it is necessary to provide a mechanism for creating such
1551 \(lqnamed destinations\(rq.
1552 This may be accomplished, by invoking the
1553 .CW pdfhref
1554 macro in the form
1555 .QP
1556 .fam C
1557 .B ".pdfhref M"
1558 .B -N \& [
1559 .I name >] <
1560 .B -X ] [
1561 .B -E ] [
1562 .I "descriptive text ...\&" ] [
1563 .LP
1564 This creates a \(lqnamed destination\(rq reference mark, with its name specified by
1565 .CWI name > < ,
1566 or, if the
1567 .CWB -N
1568 option is not specified, by the first word of
1569 .CWI descriptive \& \& \~\c
1570 .CWI text \& \& ;
1571 (note that this imposes the restriction that,
1572 if the
1573 .CWB -N
1574 option is omitted, then
1575 .EM "at least"
1576 one word of
1577 .CWI descriptive \& \& \~\c
1578 .CWI text
1579 .EM must
1580 be specified).
1581 Additionally, a reference view will be automatically defined,
1582 and associated with the reference mark,
1583 .XR pdfhref-view ), (
1584 .\" and, if any
1585 .\" .CWI descriptive
1586 .\" .CWI text
1587 .\" is specified, or the
1588 and, if the
1589 .CWB -X
1590 option is specified, and no document cross reference map has been imported,
1591 .XR import-map ), (
1592 then a cross reference mapping record,
1593 .XR export-map ), (
1594 will be written to the
1595 .CW stdout
1596 stream;
1597 this may be captured, and subsequently used to generate a cross reference map
1598 for the document,
1599 .XR create-map ). (
1600 .LP
1601 When a \(lqnamed destination\(rq reference mark is created, using the
1602 .CW pdfhref
1603 macro's
1604 .CWB M \& \& \(rq \(lq
1605 operator, there is normally no visible effect in the formatted document; any
1606 .CWI descriptive \& \& \~\c
1607 .CWI text
1608 which is specified will simply be stored in the cross reference map,
1609 for use when a link to the reference mark is created.
1610 This default behaviour may be changed, by specifying the
1611 .CWB -E
1612 option, which causes any specified
1613 .CWI descriptive \& \& \~\c
1614 .CWI text
1615 to be \(lqechoed\(rq in the document text,
1616 at the point where the reference mark is placed,
1617 in addition to its inclusion in the cross reference map.
1618 .NH 4
1619 .XN -N export-map -- Mapping a Destination for Cross Referencing
1620 .LP
1621 Effective cross referencing of
1622 .EM any
1623 document formatted by
1624 .CW @L_ROFF@
1625 requires multiple pass formatting.
1626 Details of how this multiple pass formatting may be accomplished,
1627 when working with the
1628 .CW pdfmark
1629 macros, will be discussed later,
1630 .XR do-xref ); (
1631 at this stage, the discussion will be restricted to the initial preparation,
1632 which is required at the time when the cross reference destinations are defined.
1633 .LP
1634 The first stage, in the process of cross referencing a document,
1635 is the generation of a cross reference map.
1636 Again, the details of
1637 .EM how
1638 the cross reference map is generated will be discussed in
1639 .pdfhref F SECREF L -D do-xref -A ;
1640 .pdfhref F
1641 however, it is important to recognise that
1642 .EM what
1643 content is included in the cross reference map is established
1644 when the reference destination is defined \(em it is derived
1645 from the reference data exported on the
1646 .CW stderr
1647 stream by the
1648 .CW pdfhref
1649 macro, when it is invoked with the
1650 .CWB M \& \& \(rq \(lq
1651 operator, and is controlled by whatever definition of the string
1652 .CW PDFHREF.INFO
1653 is in effect, when the
1654 .CW pdfhref
1655 macro is invoked.
1656 .LP
1657 The initial default setting of
1658 .CW PDFHREF.INFO
1659 is
1660 .QP
1661 .CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
1662 .LP
1663 which ensures that the cross reference map will contain
1664 at least a page number reference, supplemented by any
1665 .CWI descriptive \& \& \~\c
1666 .CWI text
1667 which is specified for the reference mark, as defined by the
1668 .CW pdfhref
1669 macro, with its
1670 .CWB M \& \& \(rq \(lq
1671 operator; this may be redefined by the user,
1672 to export additional cross reference information,
1673 or to modify the default format for cross reference links,
1674 .XR set-format ). (
1675 .NH 4
1676 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
1677 .LP
1678 In the same manner as each document outline reference, defined by the
1679 .CW pdfhref
1680 macro with the
1681 .CWB O \& \& \(rq \(lq
1682 operator,
1683 .XR add-outline ), (
1684 has a specific document view associated with it,
1685 each reference destination marked by
1686 .CW pdfhref
1687 with the
1688 .CWB M \& \& \(rq \(lq
1689 operator, requires an associated document view specification.
1690 .LP
1691 The mechanism whereby a document view is associated with a reference mark
1692 is entirely analogous to that employed for outline references,
1693 .XR outline-view ), (
1694 except that the
1695 .CW PDFHREF.VIEW
1696 string specification is used, in place of the
1697 .CW PDFBOOKMARK.VIEW
1698 specification.
1699 Thus, the reference view is defined in terms of:\(en
1700 .QS
1701 .IP \*[= PDFHREF.VIEW]
1702 A string,
1703 establishing the position of the reference mark within the viewing window,
1704 and the magnification at which the document will be viewed,
1705 at the location of the marked reference destination;
1706 by default, it is defined by
1707 .RS
1708 .QP
1709 .CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
1710 .RE
1711 .IP
1712 which displays the reference destination at the top of the viewing window,
1713 with the magnification set to fit the page width to the width of the window.
1714 .IP \*[= PDFHREF.VIEW.LEADING]
1715 A numeric register,
1716 specifying additional spacing, to be placed between the top of the display
1717 window and the actual position at which the location of the reference
1718 destination appears within the window.
1719 This register is shared with the view specification for outline references,
1720 and thus has the same default initial setting,
1721 .RS
1722 .QP
1723 .CW ".nr PDFHREF.VIEW.LEADING 5.0p"
1724 .RE
1725 .IP
1726 as in the case of outline reference views.
1727 .IP
1728 Again, notice that
1729 .CW PDFHREF.VIEW.LEADING
1730 does not represent true typographic \(lqleading\(rq,
1731 since any preceding text, set in the specified display space,
1732 will be visible at the top of the viewing window,
1733 when the reference is selected.
1734 .QE
1735 .LP
1736 Just as the view associated with outline references may be changed,
1737 by redefining
1738 .CW PDFBOOKMARK.VIEW ,
1739 so the view associated with marked reference destinations may be changed,
1740 by redefining
1741 .CW PDFHREF.VIEW ,
1742 and, if desired,
1743 .CW PDFHREF.VIEW.LEADING ;
1744 such changes will become effective for all reference destinations marked
1745 .EM after
1746 these definitions are changed.
1747 (Notice that, since the specification of
1748 .CW PDFHREF.VIEW.LEADING
1749 is shared by both outline reference views and marked reference views,
1750 if it is changed, then the views for
1751 .EM both
1752 reference types are changed accordingly).
1753 .LP
1754 It may again be noted, that the
1755 .CW PDFPAGE.Y
1756 register is used in the definition of
1757 .CW PDFHREF.VIEW ,
1758 just as it is in the definition of
1759 .CW PDFBOOKMARK.VIEW ;
1760 all comments in
1761 .pdfhref F SECREF L -D outline-view
1762 .pdfhref F
1763 relating to its use, and indeed to page position computations in general,
1764 apply equally to marked reference views and to outline reference views.
1765 .NH 3
1766 .XN -N link-named -- Linking to a Marked Reference Destination
1767 .LP
1768 Any named destination, such as those marked by the
1769 .CW pdfhref
1770 macro, using it's
1771 .CWB M \& \& \(rq \(lq
1772 operator, may be referred to from any point in
1773 .EM any
1774 PDF document, using an
1775 .EM "active link" ;
1776 such active links are created by again using the
1777 .CW pdfhref
1778 macro, but in this case, with the
1779 .CWB L \& \& \(rq \(lq
1780 operator.
1781 This operator provides support for two distinct cases,
1782 depending on whether the reference destination is defined in
1783 the same document as the link,
1784 .XR link-intern ), (
1785 or is defined as a named destination in a different PDF document,
1786 .XR link-extern ). (
1787 .NH 4
1788 .XN -N link-intern -- References within a Single PDF Document
1789 .LP
1790 The general syntactic form for invoking the
1791 .CW pdfhref
1792 macro,
1793 when creating a link to a named destination within the same PDF document is
1794 .QP
1795 .fam C
1796 .B .pdfhref
1797 .B L
1798 .B -D \& [
1799 .BI dest-name >] <
1800 .B -P \& [
1801 .BI prefix-text >] <
1802 .B -A \& [
1803 .BI affixed-text >] <
1804 \e
1805 .br
1806 \0\0\0
1807 .B -X ] [
1808 .B -- ] [
1809 .I "descriptive text ...\&" ] [
1810 .LP
1811 where
1812 .CWI dest-name > <
1813 specifies the name of the link destination,
1814 as specified using the
1815 .CW pdfhref
1816 .CWB M \& \& \(rq \(lq
1817 operation; (it may be defined either earlier in the document,
1818 to create a backward reference, or later, to create a forward reference).
1819 .\"
1820 .\" Here's a example of how to add an iconic annotation.
1821 .\"
1822 .\".pdfnote -T "Internal Cross References" \
1823 .\"   This description is rather terse, and could benefit from \
1824 .\"   the inclusion of an example.
1825 .LP
1826 If any
1827 .CWI descriptive \& \& \~\c
1828 .CWI text
1829 arguments are specified, then they will be inserted into the
1830 .CW @L_ROFF@
1831 output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
1832 region of the link;
1833 this will be printed in the link colour specified by the string,
1834 .CW PDFHREF.TEXT.COLOUR ,
1835 which is described in
1836 .XR-NO-PREFIX set-colour .
1837 If the
1838 .CWB -X
1839 option is also specified, then the
1840 .CWI descriptive \& \& \~\c
1841 .CWI text
1842 will be augmented, by prefacing it with page and section number indicators,
1843 in accordance with the reference formatting rules which are in effect,
1844 .XR set-format ); (
1845 such indicators will be included within the active link region,
1846 and will also be printed in the link colour.
1847 .LP
1848 Note that
1849 .EM either
1850 the
1851 .CWB -D \& \& \~\c
1852 .CWBI dest\(hyname > <
1853 option,
1854 .EM or
1855 the
1856 .CWI descriptive \& \& \~\c
1857 .CWI text
1858 arguments,
1859 .EM "but not both" ,
1860 may be omitted.
1861 If the
1862 .CWB -D \& \& \~\c
1863 .CWBI dest\(hyname > <
1864 option is omitted, then the first word of
1865 .CWI descriptive \& \& \~\c
1866 .CWI text \& \& ,
1867 i.e.\~all text up to but not including the first space,
1868 will be interpreted as the
1869 .CWBI dest\(hyname > <
1870 for the link; this text will also appear in the running text of the document,
1871 within the active region of the link.
1872 Alternatively, if the
1873 .CWB -D \& \& \~\c
1874 .CWBI dest\(hyname > <
1875 option
1876 .EM is
1877 specified, and
1878 .CWI descriptive \& \& \~\c
1879 .CWI text
1880 is not,
1881 then the running text which defines the reference,
1882 and its active region,
1883 will be derived from the reference description which is specified
1884 when the named destination is marked,
1885 .XR mark-dest ), (
1886 and will be formatted according to the reference formatting rules
1887 which are in effect, when the reference is placed,
1888 .XR set-format ); (
1889 in this case, it is not necessary to specify the
1890 .CWB -X
1891 option to activate automatic formatting of the reference \(em it is implied,
1892 by the omission of all
1893 .CWI descriptive \& \& \~\c
1894 .CWI text
1895 arguments.
1896 .LP
1897 The
1898 .CWB -P \& \& \~\c
1899 .CWBI prefix\(hytext > <
1900 and
1901 .CWB -A \& \& \~\c
1902 .CWBI affixed\(hytext > <
1903 options may be used to specify additional text
1904 which will be placed before and after the linked text respectively,
1905 with no intervening space.
1906 Such prefixed and affixed text will be printed in the normal text colour,
1907 and will not be included within the active region of the link.
1908 This feature is mostly useful for creating parenthetical references,
1909 or for placing punctuation adjacent to,
1910 but not included within,
1911 the text which defines the active region of the link.
1912 .LP
1913 The operation of the
1914 .CW pdfhref
1915 macro, when used with its
1916 .CWB L \& \& \(rq \(lq
1917 operator to place a link to a named PDF destination,
1918 may best be illustrated by an example.
1919 However, since the appearance of the link will be influenced by
1920 factors established when the named destination is marked,
1921 .XR mark-dest ), (
1922 and also by the formatting rules in effect when the link is placed,
1923 the presentation of a suitable exanple will be deferred,
1924 until the formatting mechanism has been explained,
1925 .XR set-format ). (
1926 .NH 4
1927 .XN -N link-extern -- References to Destinations in Other PDF Documents
1928 .LP
1929 The
1930 .CW pdfhref
1931 macro's
1932 .CWB L \& \& \(rq \(lq
1933 operator is not restricted to creating reference links
1934 within a single PDF document.
1935 When the link destination is defined in a different document,
1936 then the syntactic form for invoking
1937 .CW pdfhref
1938 is modified, by the addition of options to specify the
1939 name and location of the PDF file in which the destination is defined.
1940 Thus, the extended
1941 .CW pdfhref
1942 syntactic form becomes
1943 .QP
1944 .fam C
1945 .B .pdfhref
1946 .B L
1947 .B -F
1948 .BI file > <
1949 .B -D \& [
1950 .BI dest-name >] <
1951 \e
1952 .br
1953 \0\0\0
1954 .B -DF \& [
1955 .BI dos-file >] <
1956 .B -MF \& [
1957 .BI mac-file >] <
1958 .B -UF \& [
1959 .BI unix-file >] <
1960 \e
1961 .br
1962 \0\0\0
1963 .B -WF \& [
1964 .BI win-file >] <
1965 .B -P \& [
1966 .BI prefix-text >] <
1967 .B -A \& [
1968 .BI affixed-text >] <
1969 \e
1970 .br
1971 \0\0\0
1972 .B -X ] [
1973 .B -- ] [
1974 .I "descriptive text ...\&" ] [
1975 .LP
1976 where the
1977 .CWB -F \& \& \~\c
1978 .CWBI file > <
1979 option serves
1980 .EM two
1981 purposes: it both indicates to the
1982 .CW pdfhref
1983 macro that the specified reference destination
1984 is defined in an external PDF file,
1985 and it also specifies the normal path name,
1986 which is to be used to locate this file,
1987 when a user selects the reference.
1988 .LP
1989 In addition to the
1990 .CWB -F \& \& \~\c
1991 .CWBI file > <
1992 option, which
1993 .EM must
1994 be specified when referring to a destination in an external PDF file,
1995 the
1996 .CWB -DF \& \& \~\c
1997 .CWBI dos\(hyfile > < ,
1998 .CWB -MF \& \& \~\c
1999 .CWBI mac\(hyfile > < ,
2000 .CWB -UF \& \& \~\c
2001 .CWBI unix\(hyfile > <
2002 and
2003 .CWB -WF \& \& \~\c
2004 .CWBI win\(hyfile > <
2005 options may be used to specify the location of the file
2006 containing the reference destination,
2007 in a variety of operating system dependent formats.
2008 These options assign their arguments to the
2009 .CW /DosFile ,
2010 .CW /MacFile ,
2011 .CW /UnixFile
2012 and
2013 .CW /WinFile
2014 keys of the generated
2015 .CW pdfmark
2016 respectively; thus when any of these options are specified,
2017 .EM "in addition to"
2018 the
2019 .CWB -F \& \& \~\c
2020 .CWBI file > <
2021 option, and the document is read on the appropriate operating systems,
2022 then the path names specified by
2023 .CWBI dos\(hyfile > < ,
2024 .CWBI mac\(hyfile > < ,
2025 .CWBI unix\(hyfile > <
2026 and
2027 .CWBI win\(hyfile > <
2028 will be searched,
2029 .EM instead
2030 of the path name specified by
2031 .CWBI file > < ,
2032 for each of the
2033 .CW MS\(hyDOS \*(rg,
2034 .CW Apple \*(rg
2035 .CW Macintosh \*(rg,
2036 .CW UNIX \(tm
2037 and
2038 .CW MS\(hyWindows \*(rg
2039 operating systems, respectively; see the
2040 .pdfmark-manual ,
2041 for further details.
2042 .LP
2043 Other than the use of these additional options,
2044 which specify that the reference destination is in an external PDF file,
2045 the behaviour of the
2046 .CW pdfhref
2047 .CWB L \& \& \(rq \(lq
2048 operator, with the
2049 .CWB -F \& \& \~\c
2050 .CWBI file > <
2051 option, remains identical to its behaviour
2052 .EM without
2053 this option,
2054 .XR link-intern ), (
2055 with respect to the interpretation of other options,
2056 the handling of the
2057 .CWI descriptive \& \& \~\c
2058 .CWI text
2059 arguments, and the formatting of the displayed reference.
2060 .LP
2061 Once again, since the appearance of the reference is determined by
2062 factors specified in the document reference map,
2063 and also by the formatting rules in effect when the reference is placed,
2064 the presentation of an example of the placing of
2065 a reference to an external destination will be deferred,
2066 until the formatting mechanism has been explained,
2067 .XR set-format ). (
2068 .NH 3
2069 .XN -N add-weblink -- Linking to Internet Resources
2070 .LP
2071 In addition to supporting the creation of cross references
2072 to named destinations in PDF documents, the
2073 .CW pdfhref
2074 macro also has the capability to create active links to Internet resources,
2075 or indeed to
2076 .EM any
2077 resource which may be specified by a Uniform Resource Identifier,
2078 (which is usually abbreviated to the acronym \(lqURI\(rq,
2079 and sometimes also referred to as a Uniform Resource Locator,
2080 or \(lqURL\(rq).
2081 .LP
2082 Since the mechanism for creating a link to a URI differs somewhat
2083 from that for creating PDF references, the
2084 .CW pdfhref
2085 macro is invoked with the
2086 .CWB W \& \& \(rq \(lq
2087 (for \(lqweb\(hylink\(rq) operator, rather than the
2088 .CWB L \& \& \(rq \(lq
2089 operator; nevertheless, the invocation syntax is similar, having the form
2090 .QP
2091 .fam C
2092 .B .pdfhref
2093 .B W
2094 .B -D \& [
2095 .BI URI >] <
2096 .B -P \& [
2097 .BI prefix-text >] <
2098 .B -A \& [
2099 .BI affixed-text >] <
2100 \e
2101 .br
2102 \0\0\0
2103 .B -- ] [
2104 .I "descriptive text ...\&"
2105 .LP
2106 where the optional
2107 .CWB -D
2108 .CWBI URI > <
2109 modifier specifies the address for the target Internet resource,
2110 in any appropriate
2111 .EM "Uniform Resource Identifier"
2112 format, while the
2113 .CWI descriptive
2114 .CWI text
2115 argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
2116 region, and the
2117 .CWB -P
2118 .CWBI prefix\(hytext > <
2119 and
2120 .CWB -A
2121 .CWBI affixed\(hytext > <
2122 options have the same effect as in the case of local document links,
2123 .XR link-intern ). (
2124 .LP
2125 Notice that it is not mandatory to include the
2126 .CWB -D
2127 .CWBI URI > <
2128 in the link specification; if it
2129 .EM is
2130 specified, then it is not necessary for the URI to appear,
2131 in the running text of the document \(em the
2132 .CWI descriptive
2133 .CWI text
2134 argument exactly defines the text
2135 which will appear within the \(lqhot\(hyspot\(rq region,
2136 and this need not include the URI.
2137 However, if the
2138 .CWB -D \& \& \~\c
2139 .CWBI URI > <
2140 specification is omitted, then the
2141 .CWI descriptive
2142 .CWI text
2143 argument
2144 .EM must
2145 be an
2146 .EM exact
2147 representation of the URI, which
2148 .EM will ,
2149 therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
2150 For example, we could introduce a reference to
2151 .pdfhref W -D \*[ROFF-WEBSITE] -A , the @T_ROFF@ web site
2152 in which the actual URI is concealed, by using mark up such as:\(en
2153 .DS I
2154 .CW
2155 For example, we could introduce a reference to
2156 \&.pdfhref W -D \*[ROFF-WEBSITE] -A , the @T_ROFF@ web site
2157 in which the actual URI is concealed,
2158 .DE
2159 Alternatively,
2160 to refer the reader to the @T_ROFF@ web site,
2161 making it obvious that the appropriate URI is
2162 .pdfhref W -A , \*[ROFF-WEBSITE]
2163 the requisite mark up might be:\(en
2164 .DS I
2165 .CW
2166 to refer the reader to the @T_ROFF@ web site,
2167 making it obvious that the appropriate URI is
2168 \&.pdfhref W -A , \*[ROFF-WEBSITE]
2169 the requisite mark up might be:\e(en
2170 .DE
2171 .NH 3
2172 .XN -N set-format -- Establishing a Format for References
2173 .LP
2174 There are two principal aspects to be addressed,
2175 when defining the format to be used when displaying references.
2176 Firstly, it is desirable to provide a visual cue,
2177 to indicate that the text describing the reference is imbued
2178 with special properties \(em it is dynamically linked to the reference
2179 destination \(em and secondly, the textual content should
2180 describe where the link leads, and ideally,
2181 it should also describe the content of the reference destination.
2182 .LP
2183 The visual cue,
2184 that a text region defines a dynamically linked reference,
2185 is most commonly provided by printing the text within the active
2186 region in a distinctive colour.
2187 This technique will be employed automatically by the
2188 .CW pdfhref
2189 macro \(em
2190 .XR set-colour
2191 \(em unless the user specifically chooses to adopt, and implement,
2192 some alternative strategy.
2193 .NH 4
2194 .XN -N set-colour -- Using Colour to Demarcate Link Regions
2195 .LP
2196 Typically, when a PDF document contains
2197 .EM active
2198 references to other locations, either within the same document,
2199 or even in other documents, or on the World Wide Web,
2200 it is usually desirable to make the regions
2201 where these active links are placed stand out from the surrounding text.
2202 .NH 4
2203 .XN -N user-format -- Specifying Reference Text Explicitly
2204 .NH 4
2205 .XN -N auto-format -- Using Automatically Formatted Reference Text
2206 .NH 4
2207 .XN -N custom-format -- Customising Automatically Formatted Reference Text
2208 .LP
2209 It is incumbent on the user,
2210 if employing automatic formatting of the displayed reference,
2211 .XR set-format ), (
2212 to ensure that an appropriate reference definition
2213 is created for the reference destination,
2214 and is included in the reference map for the document
2215 in which the reference will appear;
2216 thus, it may be easiest to
2217 .EM always
2218 use manual formatting for external references.
2219 .NH 3
2220 .XN Problematic Links
2221 .LP
2222 Irrespective of whether a
2223 .CW pdfhref
2224 reference is placed using the
2225 .CWB L \& \& \(rq \(lq
2226 operator, or the
2227 .CWB W \& \& \(rq \(lq
2228 operator, there may be occasions when the resulting link
2229 does function as expected.
2230 A number of scenarios, which are known to be troublesome,
2231 are described below.
2232 .NH 4
2233 .XN -N page-trap -- Links with a Page Transition in the Active Region
2234 .LP
2235 When a link is placed near the bottom of a page,
2236 it is possible that its active region, or \(lqhot\(hyspot\(rq,
2237 may extend on to the next page.
2238 In this situation, a page trap macro is required
2239 to intercept the page transition, and to restart the mapping of
2240 the \(lqhot\(hyspot\(rq boundary on the new page.
2241 .LP
2242 The
2243 .CW pdfmark
2244 macro package includes a suitable page trap macro, to satisfy this requirement.
2245 However, to avoid pre\(hyempting any other requirement the user may have for
2246 a page transition trap, this is
2247 .EM not
2248 installed as an active page trap,
2249 unless explicitly requested by the user.
2250 .LP
2251 To enable proper handling of page transitions,
2252 which occur within the active regions of reference links,
2253 the user should:\(en
2254 .QS
2255 .nr ITEM 0 1
2256 .IP \n+[ITEM].
2257 Define a page transition macro, to provide whatever features may be required,
2258 when a page transition occurs \(em e.g.\& printing footnotes,
2259 adding page footers and headers, etc.
2260 This macro should end by setting the output position at the correct
2261 vertical page offset, where the printing of running text is to restart,
2262 following the page transition.
2263 .IP \n+[ITEM].
2264 Plant a trap to invoke this macro, at the appropriate vertical position
2265 marking the end of normal running text on each page.
2266 .KS
2267 .IP \n+[ITEM].
2268 Initialise the
2269 .CW pdfhref
2270 hook into this page transition trap, by invoking
2271 .RS
2272 .IP
2273 .fam C
2274 .B "pdfhref I -PT"
2275 .BI macro-name > <
2276 .LP
2277 where
2278 .CWBI macro-name > <
2279 is the name of the user supplied page trap macro,
2280 to ensure that
2281 .CW pdfhref
2282 will correctly restart mapping of active link regions,
2283 at the start of each new page.
2284 .KE
2285 .RE
2286 .QE
2287 .LP
2288 It may be observed that this initialisation of the
2289 .CW pdfhref
2290 page transition hook is, typically, required only once
2291 .EM before
2292 document formatting begins.
2293 Users of document formatting macro packages may reasonably expect that
2294 this initialisation should be performed by the macro package itself.
2295 Thus, writers of such macro packages which include
2296 .CW pdfmark
2297 bindings, should provide appropriate initialisation,
2298 so relieving the end user of this responsibility.
2299 The following example, abstracted from the sample
2300 .CW ms
2301 binding package,
2302 .CW spdf.tmac ,
2303 illustrates how this may be accomplished:\(en
2304 .DS I
2305 .CW
2306 \&.\e" @T_ROFF@ "ms" provides the "pg@bottom" macro, which has already
2307 \&.\e" been installed as a page transition trap.  To ensure proper
2308 \&.\e" mapping of "pdfhref" links which overflow the bottom of any
2309 \&.\e" page, we need to install the "pdfhref" page transition hook,
2310 \&.\e" as an addendum to this macro.
2311 \&.
2312 \&.pdfhref I -PT pg@bottom
2313 .DE
2314 .NH 2
2315 .XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
2316 .NH 2
2317 .XN -N pdfsync -- Synchronising Output and \F[C]pdfmark\F[] Contexts
2318 .LP
2319 It has been noted previously, that the
2320 .CW pdfview
2321 macro,
2322 .XR docview ), (
2323 the
2324 .CW pdfinfo
2325 macro,
2326 .XR docinfo ), (
2327 and the
2328 .CW pdfhref
2329 macro, when used to create a document outline,
2330 .XR add-outline ), (
2331 do not immediately write their
2332 .CW pdfmark
2333 output to the PostScript\*(rg data stream;
2334 instead, they cache their output, in a
2335 .CW @L_ROFF@
2336 diversion, in the case of the
2337 .CW pdfview
2338 and
2339 .CW pdfinfo
2340 macros, or in an ordered collection of strings and numeric registers,
2341 in the case of the document outline,
2342 until a more appropriate time for copying it out.
2343 In the case of
2344 .CW pdfview
2345 and
2346 .CW pdfinfo
2347 \(lqmeta\(hydata\(rq,
2348 this \(lqmore appropriate time\(rq is explicitly chosen by the user;
2349 in the case of document outline data,
2350 .EM some
2351 cached data may be implicitly written out as the document outline is compiled,
2352 but there will
2353 .EM always
2354 be some remaining data, which must be explicitly flushed out, before the
2355 .CW @L_ROFF@
2356 formatting process is allowed to complete.
2357 .LP
2358 To allow the user to choose when cached
2359 .CW pdfmark
2360 data is to be flushed to the output stream, the
2361 .CW pdfmark
2362 macro package provides the
2363 .CW pdfsync
2364 macro, (to synchronise the cache and output states).
2365 In its simplest form, it is invoked without arguments, i.e.
2366 .QP
2367 .fam C
2368 .B .pdfsync
2369 .LP
2370 This form of invocation ensures that
2371 .EM both
2372 the \(lqmeta\(hydata cache\(rq, containing
2373 .CW pdfview
2374 and
2375 .CW pdfinfo
2376 data,
2377 .EM and
2378 the \(lqoutline cache\(rq,
2379 containing any previously uncommitted document outline data,
2380 are flushed; ideally, this should be included in a
2381 .CW @L_ROFF@
2382 \(lqend macro\(rq, to ensure that
2383 .EM both
2384 caches are flushed, before
2385 .CW @L_ROFF@
2386 terminates.
2387 .LP
2388 Occasionally,
2389 it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
2390 without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
2391 at a user specified time, prior to reaching the end of the document.
2392 This may be accomplished, by invoking the
2393 .CW pdfsync
2394 macro with an argument, i.e.
2395 .QP
2396 .fam C
2397 .B ".pdfsync M"
2398 .LP
2399 to flush only the \(lqmeta\(hydata cache\(rq, or
2400 .QP
2401 .fam C
2402 .B ".pdfsync O"
2403 .LP
2404 to flush only the \(lqoutline cache\(rq.
2405 .LP
2406 The \(lqmeta\(hydata cache\(rq can normally be safely flushed
2407 in this manner, at any time
2408 .EM after
2409 output of the first page has started;
2410 (it may cause formatting problems,
2411 most notably the appearance of unwanted white space, if flushed earlier,
2412 or indeed, if flushed immediately after a page transition,
2413 but before the output of the content on the new page has commenced).
2414 Caution is required, however, when explicitly flushing the
2415 \(lqoutline cache\(rq, since if the outline is to be
2416 subsequently extended, then the first outline entry after flushing
2417 .EM must
2418 be specified at level 1.
2419 Nevertheless, such explicit flushing may occasionally be necessary;
2420 for example, the
2421 .CW TC
2422 macro in the
2423 .CW spdf.tmac
2424 package,
2425 .XR using-spdf ), (
2426 invokes
2427 .CW ".pdfsync\ O" \(rq \(lq
2428 to ensure that the outline for the \(lqbody\(rq section of the document
2429 is terminated,
2430 .EM before
2431 it commences the formatting of the table of contents section.
2432 .bp
2433 .NH 1
2434 .XN -N pdf-layout -- PDF Document Layout
2435 .LP
2436 The
2437 .CW pdfmark
2438 macros described in the preceding section,
2439 .XR pdf-features ), (
2440 provide no inherent document formatting capability of their own.
2441 However,
2442 they may be used in conjunction with any other
2443 .CW @L_ROFF@
2444 macro package of the user's choice,
2445 to add such capability.
2446 .LP
2447 In preparing this document, the standard
2448 .CW ms
2449 macro package, supplied as a component of the @T_ROFF@ distribution,
2450 has been employed.
2451 To facilitate the use of the
2452 .CW pdfmark
2453 macros with the
2454 .CW ms
2455 macros,
2456 a binding macro package,
2457 .CW spdf.tmac ,
2458 has been created.
2459 The use of this binding macro package is described in the following section,
2460 .XR using-spdf ); (
2461 it may also serve as an example to users of other standard
2462 .CW @L_ROFF@
2463 macro packages,
2464 as to how the
2465 .CW pdfmark
2466 macros may be employed with their chosen primary macro package.
2467 .NH 2
2468 .XN -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
2469 .LP
2470 The use of the binding macro package,
2471 .CW spdf.tmac ,
2472 allows for the use of the
2473 .CW pdfmark
2474 macros in conjunction with the
2475 .CW ms
2476 macros,
2477 simply by issuing a
2478 .CW @L_ROFF@
2479 command of the form
2480 .QP
2481 .fam C
2482 @L_ROFF@ -Tps
2483 .B -mspdf
2484 .I "-options ...\&" ] [
2485 file(s) ...
2486 .LP
2487 When using the
2488 .CW spdf.tmac
2489 package, the
2490 .CW @L_ROFF@
2491 input files may be marked up using any of the standard
2492 .CW ms
2493 macros to specify document formatting,
2494 while PDF features may be added,
2495 using any of the
2496 .CW pdfmark
2497 macros described previously,
2498 .XR pdf-features ). (
2499 Additionally,
2500 .CW spdf.tmac
2501 defines a number of convenient extensions to the
2502 .CW ms
2503 macro set, to better accomodate the use of PDF features within the
2504 .CW ms
2505 formatting framework,
2506 and to address a number of
2507 .CW ms
2508 document layout issues,
2509 which require special handling when producing PDF documents.
2510 These additional macros,
2511 and the issues they are intended to address,
2512 are described below.
2513 .NH 3
2514 .XN \F[C]ms\F[] Section Headings in PDF Documents
2515 .LP
2516 Traditionally,
2517 .CW ms
2518 provides the
2519 .CW NH
2520 and
2521 .CW SH
2522 macros, to specify section headings.
2523 However,
2524 there is no standard mechanism for generating a
2525 table of contents entry based on the text of the section heading;
2526 neither is there any recognised standard method for establishing a
2527 cross reference link to the section.
2528 .LP
2529 To address this
2530 .CW ms
2531 limitation,
2532 .CW spdf.tmac
2533 defines the
2534 .CW XN
2535 macro,
2536 .XR xn-macro ), (
2537 to be used in conjunction with the
2538 .CW NH
2539 macro.
2540 .NH 4
2541 .XN -N xn-macro -- The \F[C]XN\F[] Macro
2542 .NH 1
2543 .XN The PDF Publishing Process
2544 .NH 2
2545 .XN -N do-xref -- Resolving Cross References
2546 .NH 3
2547 .XN -N create-map -- Creating a Document Reference Map
2548 .NH 3
2549 .XN -N import-map -- Deploying a Document Reference Map
2550 .TC
2551 .\" s-ts-mode