contrib/pdfmark/pdfmark.tmac

   1 .ig
   2
   3 pdfmark.tmac
   4
   5 Copyright (C) 2004-2018 Free Software Foundation, Inc.
   6      Written by Keith Marshall (keith.d.marshall@ntlworld.com)
   7
   8 This file is part of groff.
   9
  10 groff is free software; you can redistribute it and/or modify it under
  11 the terms of the GNU General Public License as published by the Free
  12 Software Foundation, either version 3 of the License, or
  13 (at your option) any later version.
  14
  15 groff is distributed in the hope that it will be useful, but WITHOUT ANY
  16 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  17 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  18 for more details.
  19
  20 You should have received a copy of the GNU General Public License
  21 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 Author's Note
  24 =============
  25
  26 While I have written this macro package from scratch, much of my
  27 inspiration has come from discussion on the groff mailing list
  28 (mailto:groff@gnu.org).  I am particularly indebted to:
  29
  30    Kees Zeelenberg, for an earlier macro package he posted,
  31    a study of which helped me to get started.
  32
  33    Carlos J. G. Duarte and Werner Lemberg, whose discussion
  34    on computation of the bounding boxes for link "hot-spots"
  35    forms the basis of such computations in this package.
  36 ..
  37 .if !\n(.g .ab These pdfmark macros require groff.
  38 .\"
  39 .\" Check if we have already been loaded -- do not reload
  40 .if d pdfmark .nx
  41 .\"
  42 .\" ======================================================================
  43 .\" Module PDFMARK: Insert Arbitrary PDFMARK Code in the Postscript Stream
  44 .\" ======================================================================
  45 .\"
  46 .\" PDFMARK output may be disabled, by zeroing the PDFOPMODE register,
  47 .\" ( which mimics a more generic OPMODE, if it is defined ).
  48 .\"
  49 .if rOPMODE .aln PDFOPMODE OPMODE
  50 .\"
  51 .\" but if OPMODE wasn't defined,
  52 .\" then make the default PDFMARK mode ENABLED.
  53 .\"
  54 .if !rPDFOPMODE .nr PDFOPMODE 1
  55 .\"
  56 .\" PDFMARK output must be constrained to a maximum line length limit,
  57 .\" for strict compliance with the Postscript DSC.  This limit is defined
  58 .\" in register "PDFMARK.FOLDWIDTH.MAX".  This is user definable, up to a
  59 .\" ceiling value of 255, which is also its default value;  this limit
  60 .\" is enforced for each PDFMARK, by macro "pdf*pdfmark.limit".
  61 .\"
  62 .de pdf*pdfmark.limit
  63 .\" ----------------------------------------------------------------
  64 .\" Usage:
  65 .\"   .pdf*pdfmark.limit  REGISTER-NAME  DEFAULT-MAXIMUM-VALUE
  66 .\" ----------------------------------------------------------------
  67 .\"
  68 .\" If a register named REGISTER-NAME has not been defined, then
  69 .\" define it now, with default value = DEFAULT-MAXIMUM-VALUE.
  70 .\"
  71 .if !r\\$1 .nr \\$1 \\$2
  72 .\"
  73 .\" But when it has already been defined, ensure that its value does
  74 .\" not exceed DEFAULT-MAXIMUM-VALUE; if value does exceed this ceiling,
  75 .\" then redefine it, to enforce the limit.
  76 .\"
  77 .if (\\n[\\$1] > \\$2) .nr \\$1 \\$2
  78 ..
  79 .\" The "pdfmark" macro is responsible for emitting the appropriate
  80 .\" Postscript code.
  81 .\"
  82 .de pdfmark
  83 .\" ----------------------------------------------------------------
  84 .\" Usage:
  85 .\"   .pdfmark  text of pdfmark instruction
  86 .\" Macro supplies the required opening "[" and closing "pdfmark"
  87 .\" operator; DO NOT include them in the instruction text!
  88 .\" ----------------------------------------------------------------
  89 .\"
  90 .if \\n[PDFOPMODE] \{\
  91 .\"
  92 .\" Strict DSC compliance forbids emission of ps:exec lines which
  93 .\" exceed 255 characters in length.  We will allow the user to specify
  94 .\" an alternative lesser limit ...
  95 .\"
  96 .   pdf*pdfmark.limit PDFMARK.FOLDWIDTH.MAX 255
  97 .\"
  98 .\" ... and we will also support a second lesser limit, which will be
  99 .\" applied to literal text parenthetically embedded within the PDFMARK.
 100 .\"
 101 .   pdf*pdfmark.limit PDFMARK.FOLDWIDTH \\n[PDFMARK.FOLDWIDTH.MAX]
 102 .\"
 103 .\" We will push out the entire PDFMARK in one chunk, provided it fits
 104 .\" within this limit.
 105 .\"
 106 .   length pdf:length "[\\$* pdfmark\"
 107 .   ie !(\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH]) \{\
 108 .   \"
 109 .   \" This PDFMARK is suitable for single chunk output ...
 110 .   \"
 111 .      nop \!x X ps:exec [\\$* pdfmark
 112 .      \}
 113 .   el \{\
 114 .   \" ... but, when the limit would be violated, then we must
 115 .   \" recompose the specified PDFMARK, spreading it over as many
 116 .   \" continuation lines as are necessary.
 117 .   \"
 118 .      als pdf*compose pdf*compose.first
 119 .      while \\n(.$ \{\
 120 .         pdf*compose \\$1
 121 .         shift
 122 .         \}
 123 .   \"
 124 .   \" Complete the PDFMARK recomposition, by appending a
 125 .   \" "pdfmark" operator, and push it out to the intermediate
 126 .   \" output stream, (excluding its final line break).
 127 .   \"
 128 .      pdf*compose pdfmark
 129 .      pdf*pdfmark.dispatch
 130 .   \"
 131 .   \" And clean up when done.
 132 .   \"
 133 .      rm pdf*compose pdf*pdfmark.post
 134 .      rm pdf:compose.test pdf:composed.literal
 135 .      \}
 136 .   rr pdf:length
 137 .   \}
 138 ..
 139 .\" When a PDFMARK exceeds the specified output record length limit,
 140 .\" then we decompose it, subsequently using the dynamically overloaded
 141 .\" macro, "pdf*compose", to reassemble it into as many continuation
 142 .\" records as it may require.
 143 .\"
 144 .\" Each call to "pdf*compose" uses macro "pdf*length.increment" to
 145 .\" keep track of the current output record length, so ensuring that
 146 .\" the active maximum length limit is not violated.
 147 .\"
 148 .de pdf*length.increment
 149 .\" ----------------------------------------------------------------
 150 .\" Usage:
 151 .\"   .pdf*length.increment  NEXT-ADDITION
 152 .\" ----------------------------------------------------------------
 153 .\"
 154 .ie d pdf:composed.line \
 155 .   length pdf:length "\\*[pdf:composed.line] \\$*\"
 156 .el .length pdf:length "\\$*\"
 157 ..
 158 .\" The first call to "pdf*compose" for each PDFMARK is directed
 159 .\" to "pdf*compose.first";  this initialises the local strings
 160 .\" and macros used to compose the eventual PDFMARK output.
 161 .\"
 162 .de pdf*compose.first
 163 .\" ----------------------------------------------------------------
 164 .\" Usage:
 165 .\"   .als  pdf*compose  pdf*compose.first
 166 .\"   .     pdf*compose  TOKEN
 167 .\" ----------------------------------------------------------------
 168 .\"
 169 .\" Ensure that the output record accumulator will be initialised
 170 .\" on posting of the first composed PDFMARK record.
 171 .\"
 172 .als pdf*pdfmark.post pdf*pdfmark.post.first
 173 .\"
 174 .\" The first token passed to "pdf*compose" should not be a
 175 .\" literal, but be prepared to handle one, just in case.
 176 .\"
 177 .ds pdf:compose.test \\$1
 178 .substring pdf:compose.test 0 0
 179 .ie '('\\*[pdf:compose.test]' \{\
 180 .\"
 181 .\" We found a literal, even though we didn't expect it;
 182 .\" if it's a single element literal, we can just handle it
 183 .\" as if it is a regular token anyway.
 184 .\"
 185 .   ds pdf:compose.test "\\$\\n(.$\"
 186 .   substring pdf:compose.test -1
 187 .   if !')'\\*[pdf:compose.test]' \{\
 188 .   \"
 189 .   \" But when it is the first of a literal sequence,
 190 .   \" then we need to set up "pdf*compose" to handle it.
 191 .   \"
 192 .      ds pdf:composed.literal "[\\$*\"
 193 .      als pdf*compose pdf*compose.literal
 194 .      \}
 195 .   \}
 196 .el .ds pdf:compose.test )
 197 .if ')'\\*[pdf:compose.test]' \{\
 198 .\"
 199 .\" In the normal case, we start each new PDFMARK with a
 200 .\" regular token; save it as the first in the composed output
 201 .\" line sequence, and set up "pdf*compose" to collect
 202 .\" the rest of the sequence.
 203 .\"
 204 .   ds pdf:composed.line "[\\$*\"
 205 .   als pdf*compose pdf*compose.next
 206 .   \}
 207 ..
 208 .\" Subsequent calls to "pdf*compose", while collecting
 209 .\" regular tokens, are then directed to "pdf*compose.next".
 210 .\"
 211 .de pdf*compose.next
 212 .\" ----------------------------------------------------------------
 213 .\" Usage:
 214 .\"   .als  pdf*compose  pdf*compose.next
 215 .\"   .     pdf*compose  TOKEN
 216 .\" ----------------------------------------------------------------
 217 .\"
 218 .\" This first checks to ensure that the supplied token really is
 219 .\" a regular token, and not the first element in a literal.
 220 .\"
 221 .ds pdf:compose.test \\$1
 222 .substring pdf:compose.test 0 0
 223 .ie '('\\*[pdf:compose.test]' \{\
 224 .\"
 225 .\" The supplied token represents the first element of a literal,
 226 .\" but it may be a single element literal, which we simply handle
 227 .\" as a regular token anyway.
 228 .\"
 229 .   ds pdf:compose.test "\\$\\n(.$\"
 230 .   substring pdf:compose.test -1
 231 .   if !')'\\*[pdf:compose.test]' \{\
 232 .   \"
 233 .   \" The supplied token is the first of a sequence of elements
 234 .   \" which collectively define a literal, so start collecting a
 235 .   \" composite literal token, and change the "pdf*compose"
 236 .   \" state, to collect and append the remaining elements.
 237 .   \"
 238 .      ds pdf:composed.literal "\\$*\"
 239 .      als pdf*compose pdf*compose.literal
 240 .      \}
 241 .   \}
 242 .el .ds pdf:compose.test )
 243 .if ')'\\*[pdf:compose.test]' \{\
 244 .\"
 245 .\" The supplied token IS a regular token; add it, but ensure that
 246 .\" the active maximum record length limit is honoured.
 247 .\"
 248 .   pdf*length.increment "\\$*\"
 249 .   ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
 250 .   \"
 251 .   \" Adding this token would cause the current PDFMARK record, in
 252 .   \" groff's intermediate output file, to overflow the active record
 253 .   \" length limit, so post the current record and start another.
 254 .   \"
 255 .      pdf*pdfmark.dispatch
 256 .      ds pdf:composed.line "\\$*\"
 257 .      \}
 258 .   el \{\
 259 .   \"
 260 .   \" This token will fit in the current PDFMARK record, without
 261 .   \" violating the active length limit, so simply add it.
 262 .   \"
 263 .      ie d pdf:composed.line .as pdf:composed.line " \\$*\"
 264 .      el .ds pdf:composed.line "\\$*\"
 265 .      \}
 266 .   \}
 267 ..
 268 .\" While assembling a multiple token literal sequence into a single
 269 .\" literal token, successive calls to "pdf*compose" are directed
 270 .\" to "pdf*compose.literal".
 271 .\"
 272 .de pdf*compose.literal
 273 .\" ----------------------------------------------------------------
 274 .\" Usage:
 275 .\"   .als  pdf*compose  pdf*compose.literal
 276 .\"   .     pdf*compose  TOKEN
 277 .\" ----------------------------------------------------------------
 278 .\"
 279 .\" First, check to ensure that the current token can be appended to
 280 .\" the accumulated literal, without extending it beyond the maximum
 281 .\" allowed literal token length.
 282 .\"
 283 .length pdf:length "\\*[pdf:composed.literal] \\$*\"
 284 .ie (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH] - 2)) \{\
 285 .\"
 286 .\" If it has grown too long, then it must be folded across two
 287 .\" physical PDFMARK output records, so check if we can accommodate
 288 .\" the portion collected so far within the current output record.
 289 .\"
 290 .   pdf*length.increment "\\*[pdf:composed.literal]\"
 291 .   if (\\n[pdf:length] > (\\n[PDFMARK.FOLDWIDTH.MAX] - 2)) \{\
 292 .   \"
 293 .   \" The current output record CAN'T accommodate the currently
 294 .   \" composed portion of the literal, so flush out the current
 295 .   \" record, to make way for the accumulated literal, and mark
 296 .   \" the dispatch mode as "wrapped", for the fragments of the
 297 .   \" folded literal string, which are to follow.
 298 .   \"
 299 .      pdf*pdfmark.dispatch
 300 .      ds pdf*pdfmark.dispatch.wrapped
 301 .      \}
 302 .   ie d pdf:composed.line \{\
 303 .   \"
 304 .   \" If we DIDN'T need to flush the current output record,
 305 .   \" then we can simply append the accumulated literal to it...
 306 .   \"
 307 .      as pdf:composed.line " \\*[pdf:composed.literal]\"
 308 .      \}
 309 .   el \{\
 310 .   \"
 311 .   \" otherwise, when the current record has been flushed, or is
 312 .   \" empty, then we promote the accumulated literal, to make it
 313 .   \" the next output record...
 314 .   \"
 315 .      rn pdf:composed.literal pdf:composed.line
 316 .      \}
 317 .\"
 318 .\" Now, to complete the fold, flush out any accumulated partial
 319 .\" output record, and continue accumulating the literal, starting
 320 .\" with the current token.
 321 .\"
 322 .   pdf*pdfmark.dispatch
 323 .   ds pdf:composed.literal "\\$*\"
 324 .   \}
 325 .el \{\
 326 .\"
 327 .\" Alternatively, when we HAVEN'T identified a need to fold the
 328 .\" current output record, then we simply append the current token
 329 .\" to the accumulated literal token buffer string.
 330 .\"
 331 .   as pdf:composed.literal " \\$*\"
 332 .   \}
 333 .\"
 334 .\" Having ensured that we have sufficient space, in which to
 335 .\" append the current token to the currently accumulated literal,
 336 .\" we check its rightmost character, to see if is the closing
 337 .\" parenthesis, which completes the literal.
 338 .\"
 339 .ds pdf:compose.test \\$\\n(.$
 340 .substring pdf:compose.test -1
 341 .if ')'\\*[pdf:compose.test]' \{\
 342 .\"
 343 .\" The literal has been completely collected, so we may now append
 344 .\" it to the current output record, as a single literal token, but
 345 .\" subject to the constraint that it must not extend the output
 346 .\" record beyond the maximum permitted length.
 347 .\"
 348 .   pdf*length.increment "\\*[pdf:composed.literal]\"
 349 .   ie (\\n[pdf:length] > \\n[PDFMARK.FOLDWIDTH.MAX]) \{\
 350 .   \"
 351 .   \" So, when the literal cannot be accommodated within the maximum
 352 .   \" length constraint, then we flush the current record, and start
 353 .   \" a new one, with the literal token as its first entry.
 354 .   \"
 355 .      pdf*pdfmark.dispatch
 356 .      rn pdf:composed.literal pdf:composed.line
 357 .      \}
 358 .   el \{\
 359 .   \"
 360 .   \" When the literal CAN be accommodated within the maximum length
 361 .   \" constraint, then ...
 362 .   \"
 363 .      ie d pdf:composed.line \{\
 364 .      \"
 365 .      \" When an output record has already been instantiated, we
 366 .      \" append the literal token to it, and discard the accumulator
 367 .      \" string, which is no longer required.
 368 .      \"
 369 .         as pdf:composed.line " \\*[pdf:composed.literal]\"
 370 .         rm pdf:composed.literal
 371 .         \}
 372 .      el \{\
 373 .      \"
 374 .      \" But when no output record yet exists, then we simply
 375 .      \" reassign the accumulated literal token, to instantiate a
 376 .      \" new output record.
 377 .      \"
 378 .         rn pdf:composed.literal pdf:composed.line
 379 .         \}
 380 .      \}
 381 .\"
 382 .\" Finally, since we have completed the accumulation of the literal, we
 383 .\" revert to the "unwrapped" mode of operation for "pdf*pdfmark.dispatch",
 384 .\" and restore the normal "pdf*compose" action, for collection of the next
 385 .\" token (if any).
 386 .\"
 387 .   rm pdf*pdfmark.dispatch.wrapped
 388 .   als pdf*compose pdf*compose.next
 389 .   \}
 390 ..
 391 .\" While composing a multiple record PDFMARK, each composed record
 392 .\" must be added to the collection, whenever the partially composed
 393 .\" output record has been filled;  this is handled when necessary,
 394 .\" by calling the "pdf*pdfmark.dispatch" macro.
 395 .\"
 396 .de pdf*pdfmark.dispatch
 397 .\" ----------------------------------------------------------------
 398 .\" Usage:
 399 .\"   .pdf*pdfmark.dispatch
 400 .\" ----------------------------------------------------------------
 401 .\"
 402 .if d pdf:composed.line \{\
 403 .\"
 404 .\" This is simply a wrapper around the overloaded "pdf*pdfmark.post"
 405 .\" macro, ensuring that an output record has actually been collected
 406 .\" before attempting to post it; it then cleans up after posting, to
 407 .\" ensure that each collected record is posted only once.
 408 .\"
 409 .   if d pdf*pdfmark.dispatch.wrapped \{\
 410 .   \"
 411 .   \" When dispatching an excessively long literal string, which
 412 .   \" must be wrapped over multiple records, this mode is active
 413 .   \" for all but the closing record; we must escape the newline
 414 .   \" at the end of each such unclosed literal record.
 415 .   \"
 416 .      as pdf:composed.line " \\\\\\\\\"
 417 .      \}
 418 .   pdf*pdfmark.post
 419 .   rm pdf:composed.line
 420 .   \}
 421 ..
 422 .\" For each PDFMARK, the first call of "pdf*pdfmark.post" is directed
 423 .\" to the "pdf*pdfmark.post.first" macro;  this initialises the state
 424 .\" of the "pdf:composed" macro, for assembly of a new PDFMARK.
 425 .\"
 426 .de pdf*pdfmark.post.first
 427 . nop \!x X ps:exec \\*[pdf:composed.line]
 428 .\"
 429 .\" Subsequent calls to "pdf*pdfmark.post" are redirected to the
 430 .\" alternative "pdf*pdfmark.post.next" macro, which simply appends
 431 .\" additional PDFMARK records to the "pdf:composed" macro.
 432 .\"
 433 .als pdf*pdfmark.post pdf*pdfmark.post.next
 434 ..
 435 .de pdf*pdfmark.post.next
 436 . nop \!+\\*[pdf:composed.line]
 437 ..
 438 .\" "pdf*end" is a dummy macro.  It is required to mark the end
 439 .\" of each individual fragment which is added to "pdf:composed";
 440 .\" other than this, it does nothing.
 441 .\"
 442 .de pdf*end
 443 ..
 444 .\"
 445 .\" Some supporting macros defer actual pdfmark output until an
 446 .\" appropriate time for it to be written; the "pdfsync" macro
 447 .\" provides a mechanism for flushing such deferred output;
 448 .\" it should be called from an end macro, and at any other time
 449 .\" when it may be deemed necessary to flush pdfmark context.
 450 .\"
 451 .de pdfsync
 452 .\" ----------------------------------------------------------------
 453 .\" Usage:
 454 .\"   .pdfsync buffer ...
 455 .\" Arguments indicate which "buffer(s)" to flush:
 456 .\"   O -> bookmark (outline) cache
 457 .\"   M -> document metadata diversion
 458 .\" If no argument, flush ALL buffers
 459 .\" ----------------------------------------------------------------
 460 .\"
 461 .ie \\n(.$ \{\
 462 .   while \\n(.$ \{\
 463 .      if '\\$1'O' .pdf:bm.sync 1
 464 .      if '\\$1'M' \{\
 465 .         if dpdf:metadata .pdf:metadata
 466 .         rm pdf:metadata
 467 .         \}
 468 .      shift
 469 .      \}
 470 .   \}
 471 .el .pdfsync O M
 472 ..
 473 .\"
 474 .\" some helper functions ...
 475 .\"
 476 .\" "pdf:warn" and "pdf:error" write diagnostic messages to stderr
 477 .\"
 478 .de pdf:warn
 479 .\" ----------------------------------------------------------
 480 .\" Usage:
 481 .\"   .pdf:warn text of message
 482 .\" ----------------------------------------------------------
 483 .\"
 484 .tm \\n(.F:\\n(.c: macro warning: \\$*
 485 ..
 486 .de pdf:error
 487 .\" ----------------------------------------------------------
 488 .\" Usage:
 489 .\"   .pdf:error text of message
 490 .\" ----------------------------------------------------------
 491 .\"
 492 .tm \\n(.F:\\n(.c: macro error: \\$*
 493 ..
 494 .\" "pdf:pop", assisted by "pdf*pop", allows us to retrieve register,
 495 .\" or string values, from a string masquerading as a data queue,
 496 .\" or as a stack.
 497 .\"
 498 .de pdf:pop
 499 .\" ----------------------------------------------------------------
 500 .\" Usage:
 501 .\"   .pdf:pop <type> <to-name> <from-name>
 502 .\"   $1 = nr for numeric register, ds for string
 503 .\"   $2 = name of register or string to be assigned
 504 .\"   $3 = name of string, from which data is to be retrieved
 505 .\" ----------------------------------------------------------------
 506 .\"
 507 .pdf*pop \\$* \\*[\\$3]
 508 ..
 509 .de pdf*pop
 510 .ds pdf:stack \\$3
 511 .\\$1 \\$2 \\$4
 512 .shift 4
 513 .ie \\n(.$ .ds \\*[pdf:stack] \\$*
 514 .el .rm \\*[pdf:stack]
 515 .rm pdf:stack
 516 ..
 517 .\"
 518 .\"
 519 .\" ===========================================================
 520 .\" Module PDFINFO: Insert MetaData Entries into a PDF Document
 521 .\" ===========================================================
 522 .\"
 523 .\" N.B.
 524 .\"   Output from the macros in this module is deferred, until
 525 .\"   subsequent invocation of .pdfsync, or .pdfexit
 526 .\"
 527 .\" ."pdfinfo" provides a general purpose form of metadata entry ...
 528 .\" it allows arbitrary text to be associated with any specified
 529 .\" metadata field name.
 530 .\"
 531 .de pdfinfo
 532 .\" -------------------------------------------------------------------
 533 .\" Usage:
 534 .\"   .pdfinfo /FieldName field content ...
 535 .\" Examples:
 536 .\"   .pdfinfo /Title   A PDF Document
 537 .\"   .pdfinfo /Author  Keith Marshall
 538 .\" -------------------------------------------------------------------
 539 .\"
 540 .ds pdf:meta.field \\$1
 541 .shift
 542 .da pdf:metadata
 543 \!.pdfmark \\*[pdf:meta.field] (\\$*) /DOCINFO
 544 .di
 545 .rm pdf:meta.field
 546 ..
 547 .\"
 548 .\" Macro "pdfview" defines a special form of metadata entry ...
 549 .\" it uses the /DOCVIEW pdfmark, to specify the initial (default) view,
 550 .\" when the document is opened.
 551 .\"
 552 .de pdfview
 553 .\" -------------------------------------------------------------------
 554 .\" Usage:
 555 .\"   .pdfview view parameters ...
 556 .\" Examples:
 557 .\"   .pdfview /PageMode /UseOutlines
 558 .\"   .pdfview /Page 2 /View [/FitH \n(.p u]
 559 .\" -------------------------------------------------------------------
 560 .\"
 561 .da pdf:metadata
 562 \!.pdfmark \\$* /DOCVIEW
 563 .di
 564 ..
 565 .\"
 566 .\"
 567 .\" =====================================================================
 568 .\" Module PDFNOTE: Insert "Sticky Note" Style Comments in a PDF Document
 569 .\" =====================================================================
 570 .\"
 571 .\" "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" set the preferred size for
 572 .\" display of the "sticky note" pane, when opened.  Acrobat Reader
 573 .\" seems not to honour these -- perhaps GhostScript doesn't encode
 574 .\" them correctly!  Anyway, let's set some suitable default values,
 575 .\" in case the user has a set up which does work as advertised.
 576 .\"
 577 .nr PDFNOTE.WIDTH  3.5i
 578 .nr PDFNOTE.HEIGHT 2.0i
 579 .\"
 580 .\" "pdf:bbox" defines the expression used to set the size and location
 581 .\" of the bounding rectangle for display of notes and link "hot-spots".
 582 .\" This is defined, such that a note is placed at troff's current text
 583 .\" position on the current page, with its displayed image size defined
 584 .\" by the "PDFNOTE.WIDTH" and "PDFNOTE.HEIGHT" registers, while the
 585 .\" bounds for a link "hot-spot" are matched to the text region which
 586 .\" defines the "hot-spot".
 587 .\"
 588 .ds pdf:bbox \\n[pdf:llx] u \\n[pdf:lly] u \\n[pdf:urx] u \\n[pdf:ury] u
 589 .\"
 590 .\" Getting line breaks into the text of a PDFNOTE is tricky -- we need
 591 .\" to get a "\n" into the Postscript stream, but three levels of "\" are
 592 .\" swallowed, when we invoke "pdfnote".  The following definition of "PDFLB",
 593 .\" (for LineBreak), is rather ugly, but does allow us to use
 594 .\"
 595 .\"    .pdfnote  Some text.\*[PDFLB]Some more text, on a new line.
 596 .\"
 597 .ds PDFLB \\\\\\\\\\\\\\\\n
 598 .\"
 599 .de pdfnote
 600 .\" ----------------------------------------------------------------------
 601 .\" Usage:
 602 .\"   .pdfnote [-T "Text for Title"] Text of note ...
 603 .\" ----------------------------------------------------------------------
 604 .\"
 605 .if \\n[PDFOPMODE] \{\
 606 .\"
 607 .\" First, compute the bounding rectangle,
 608 .\" for this PDFNOTE instance
 609 .\"
 610 .   mk pdf:ury
 611 .   nr pdf:llx \\n(.k+\\n(.o+\\n[.in]
 612 .   nr pdf:lly \\n[pdf:ury]-\\n[PDFNOTE.HEIGHT]
 613 .   nr pdf:urx \\n[pdf:llx]+\\n[PDFNOTE.WIDTH]
 614 .   ds pdf:note.instance /Rect [\\*[pdf:bbox]]
 615 .\"
 616 .\" Parse any specified (recognisable) PDFNOTE options
 617 .\"
 618 .   while dpdf:note\\$1 \{\
 619 .      pdf:note\\$1 \\$@
 620 .      shift \\n[pdf:note.argc]
 621 .      \}
 622 .\"
 623 .\" Emit the note, and clean up
 624 .\"
 625 .   pdfmark \\*[pdf:note.instance] /Contents (\\$*) /ANN
 626 .   rm pdf:note.instance
 627 .   rr pdf:note.argc
 628 .   \}
 629 ..
 630 .de pdf:note-T
 631 .nr pdf:note.argc 2
 632 .as pdf:note.instance " /Title (\\$2)
 633 ..
 634 .\"
 635 .\"
 636 .\" =====================================================================
 637 .\" Module PDFBOOKMARK: Add an Outline Reference in the PDF Bookmark Pane
 638 .\" =====================================================================
 639 .\"
 640 .\" "PDFBOOKMARK.VIEW" controls how the document will be displayed,
 641 .\" when the user selects a bookmark.  This default setting will fit
 642 .\" the page width to the viewing window, with the bookmarked entry
 643 .\" located at the top of the viewable area.
 644 .\"
 645 .ds PDFBOOKMARK.VIEW /FitH \\n[PDFPAGE.Y] u
 646 .\"
 647 .\" "PDFOUTLINE.FOLDLEVEL" controls how the document outline will be
 648 .\" displayed.  It is a number, defining the maximum heading level
 649 .\" which will be visible, without outline expansion by the user, in
 650 .\" the initial view of the document outline.  Assuming that no sane
 651 .\" document will ever extend to 10,000 levels of nested headings,
 652 .\" this initial default value causes outlines to be fully expanded.
 653 .\"
 654 .nr PDFOUTLINE.FOLDLEVEL 10000
 655 .\"
 656 .\" The actual job of creating an outline reference
 657 .\" is performed by the "pdfbookmark" macro.
 658 .\"
 659 .de pdfbookmark
 660 .\" ------------------------------------------------------------------
 661 .\" Usage:
 662 .\"   .pdfbookmark [-T tag] level "Text of Outline Entry"
 663 .\"
 664 .\"   $1 = nesting level for bookmark (1 is top level)
 665 .\"   $2 = text for bookmark, (in PDF viewer bookmarks list)
 666 .\"   $3 = suffix for PDF internal bookmark name (optional)
 667 .\" ------------------------------------------------------------------
 668 .\"
 669 .ie '\\n(.z'' \{\
 670 .\"
 671 .\" When we are at the top diversion level, i.e. actually emitting text
 672 .\" to the output device stream, then we compute the location of, and
 673 .\" plant this bookmark immediately.
 674 .\"
 675 .   if \\n[PDFOPMODE] \{\
 676 .   \"
 677 .   \" Make the bookmark name "untagged" by default,
 678 .   \" then parse any specified options, to set a "tag", if required
 679 .   \"
 680 .      ds pdf:href-T
 681 .      while dpdf:href.opt\\$1 \{\
 682 .         pdf:href.opt\\$1 \\$@
 683 .         shift \\n[pdf:href.argc]
 684 .         \}
 685 .      rr pdf:href.argc
 686 .   \"
 687 .   \" If we found "--" to mark the end of the options, discard it
 688 .   \"
 689 .      if '\\$1'--' .shift
 690 .   \"
 691 .   \" Synchronise the bookmark cache
 692 .   \" to the requested bookmark nesting level
 693 .   \"
 694 .      pdf:bm.sync \\$1
 695 .      shift
 696 .   \"
 697 .   \" Increment the bookmark serialisation index
 698 .   \" in order to generate a uniquely serialised bookmark name,
 699 .   \" ( which we return in the string "PDFBOOKMARK.NAME" ),
 700 .   \" and insert this bookmark into the cache
 701 .   \"
 702 .      pdf:href.sety
 703 .      nr pdf:bm.nr +1
 704 .      ds PDFBOOKMARK.NAME pdf:bm\\n[pdf:bm.nr]\\*[pdf:href-T]
 705 .      ds pdf:bm\\n[pdf:bm.nr] /Dest /\\*[PDFBOOKMARK.NAME]
 706 .      pdfmark \\*[pdf:bm\\n[pdf:bm.nr]] /View [\\*[PDFBOOKMARK.VIEW]] /DEST
 707 .      as pdf:bm\\n[pdf:bm.nr] " /Title (\\$*)
 708 .      pdf:href.options.clear
 709 .      rr PDFPAGE.Y
 710 .      \}
 711 .   \}
 712 .el \{\
 713 .\"
 714 .\" But when we are collecting a diversion which will be written out later,
 715 .\" then we must defer bookmark placement, until we emit the diversion.
 716 .\" (don't rely on $0 == pdfbookmark here; it may be a volatile alias).
 717 .\"
 718 .   nop \!.pdfbookmark \\$@
 719 .   \}
 720 ..
 721 .\"
 722 .\" Macro "pdf:bm.sync" is called for each bookmark created,
 723 .\" to establish a cache entry at the appropriate nesting level.
 724 .\" It will flush ALL previous cache content, when called to
 725 .\" add a new bookmark at level 1, or if simply called at
 726 .\" level 1, without adding any bookmark.
 727 .\"
 728 .de pdf:bm.sync
 729 .\" ------------------------------------------------------------------
 730 .\" Usage:
 731 .\"   .pdf:bm.sync  level
 732 .\"   $1 = nesting level of current bookmark, or 1 to flush cache
 733 .\" ------------------------------------------------------------------
 734 .\"
 735 .\" First validate the bookmark nesting level
 736 .\" adjusting it if required
 737 .\"
 738 .if \\$1>\\n[pdf:bm.nl] .nr pdf:bm.nl +1
 739 .ie \\$1>\\n[pdf:bm.nl] \{\
 740 .   pdf:warn adjusted level \\$1 bookmark; should be <= \\n[pdf:bm.nl]
 741 .   \}
 742 .el .nr pdf:bm.nl \\$1
 743 .if \\n[pdf:bm.nl]<1 \{\
 744 .   pdf:warn bad arg (\\$1) in \\$0 \\$1; \\$0 1 forced
 745 .   nr pdf:bm.nl 1
 746 .   \}
 747 .\"
 748 .\" If reverting from a higher to a lower nesting level,
 749 .\" cyclicly adjust cache counts for each pending higher level
 750 .\"
 751 .if \\n[pdf:bm.lc]>=\\n[pdf:bm.nl] \{\
 752 .   nr pdf:bm.lc +1
 753 .   if !rpdf:bm.c\\n[pdf:bm.lc].c .nr pdf:bm.c\\n[pdf:bm.lc].c 0
 754 .   while \\n[pdf:bm.lc]>\\n[pdf:bm.nl] \{\
 755 .      as pdf:bm.c\\n[pdf:bm.lc] " \\n[pdf:bm.c\\n[pdf:bm.lc].c]
 756 .      rr pdf:bm.c\\n[pdf:bm.lc].c
 757 .      nr pdf:bm.lc -1
 758 .      \}
 759 .   \}
 760 .\"
 761 .\" Update the cache level,
 762 .\" flushing when we are at level 1
 763 .\"
 764 .nr pdf:bm.lc \\n[pdf:bm.nl]
 765 .ie \\n[pdf:bm.nl]=1 \{\
 766 .   while \\n[pdf:bm.ic]<\\n[pdf:bm.nr] .pdf:bm.emit 0
 767 .   rr pdf:bm.rc
 768 .   \}
 769 .el .nr pdf:bm.c\\n[pdf:bm.nl].c +1
 770 ..
 771 .\" Macro "pdf:bm.emit" is called, when the cache is at level 1.
 772 .\" This flushes ALL pending bookmarks from the cache, i.e. the
 773 .\" preceding level 1 bookmark, and any nested dependents,
 774 .\" which it may have.
 775 .\"
 776 .de pdf:bm.emit
 777 .\" ------------------------------------------------------------------
 778 .\" Usage:
 779 .\"   .pdf:bm.emit  flag
 780 .\"   $1 = reference counting flag, used to control recursion
 781 .\" ------------------------------------------------------------------
 782 .\"
 783 .\" First check for nested dependents,
 784 .\" and append the "dependent count" to the bookmark, as required.
 785 .\"
 786 .nr pdf:bm.ic +1
 787 .nr pdf:bm.lc +1
 788 .pdf:pop nr pdf:bm.rc pdf:bm.c\\n[pdf:bm.lc]
 789 .if \\n[pdf:bm.rc] \{\
 790 .   ds pdf:bm.fold
 791 .   if \\n[pdf:bm.lc]>\\n[PDFOUTLINE.FOLDLEVEL] .ds pdf:bm.fold -
 792 .   as pdf:bm\\n[pdf:bm.ic] " /Count \\*[pdf:bm.fold]\\n[pdf:bm.rc]
 793 .   rm pdf:bm.fold
 794 .   \}
 795 .pdfmark \\*[pdf:bm\\n[pdf:bm.ic]] /OUT
 796 .rm pdf:bm\\n[pdf:bm.ic]
 797 .\"
 798 .\" For ALL dependents, if any,
 799 .\" recursively flush out any higher level dependents,
 800 .\" which they themselves may have
 801 .\"
 802 .while \\n[pdf:bm.rc] \{\
 803 .   nr pdf:bm.rc -1
 804 .   pdf:bm.emit \\n[pdf:bm.rc]
 805 .   \}
 806 .\"
 807 .\" Finally,
 808 .\" unwind the recursive call stack, until we return to the top level.
 809 .\"
 810 .nr pdf:bm.rc \\$1
 811 .nr pdf:bm.lc -1
 812 ..
 813 .nr pdf:bm.nr 0
 814 .nr pdf:bm.nl 1
 815 .nr pdf:bm.lc 0
 816 .nr pdf:bm.ic 0
 817 .\"
 818 .\"
 819 .\" =============================================================
 820 .\" Module PDFHREF: Create Hypertext References in a PDF Document
 821 .\" =============================================================
 822 .\"
 823 .\" "PDFHREF.VIEW" controls how the document will be displayed,
 824 .\" when the user follows a link to a named reference.
 825 .\"
 826 .ds PDFHREF.VIEW     /FitH \\n[PDFPAGE.Y] u
 827 .\"
 828 .\" This default setting will fit the page width to the viewing
 829 .\" window, with the bookmarked entry located close to the top
 830 .\" of the viewable area.  "PDFHREF.VIEW.LEADING" controls the
 831 .\" actual distance below the top of the viewing window, where
 832 .\" the reference will be positioned; 5 points is a reasonable
 833 .\" default offset.
 834 .\"
 835 .nr PDFHREF.VIEW.LEADING  5.0p
 836 .\"
 837 .\" Yuk!!!
 838 .\" PDF view co-ordinates are mapped from the bottom left corner,
 839 .\" of the page, whereas page printing co-ordinates are mapped
 840 .\" conventionally, from top left.
 841 .\"
 842 .\" Macro "pdf:href.sety" transforms the vertical position of the
 843 .\" last printed baseline, from the printing co-ordinate domain to
 844 .\" the PDF view domain.
 845 .\"
 846 .de pdf:href.sety
 847 .\" ----------------------------------------------------------------
 848 .\" Usage:
 849 .\"   .pdf:href.sety
 850 .\" ----------------------------------------------------------------
 851 .\"
 852 .\" This computation yields the vertical view co-ordinate
 853 .\" in groff's basic units; don't forget to append grops' "u"
 854 .\" conversion operator, when writing the pdfmark!
 855 .\"
 856 .nr PDFPAGE.Y \\n(.p-\\n(nl+\\n[PDFHREF.VIEW.LEADING]
 857 ..
 858 .\" When we create a link "hot-spot" ...
 859 .\" "PDFHREF.LEADING" sets the distance above the top of the glyph
 860 .\" bounding boxes, in each line of link text, over which the link
 861 .\" hot-spot will extend, while "PDFHREF.HEIGHT" sets the hot-spot
 862 .\" height, PER LINE of text occupied by the reference.
 863 .\"
 864 .\" Since most fonts specify some leading space within the bounding
 865 .\" boxes of their glyphs, a better appearance may be achieved when
 866 .\" NEGATIVE leading is specified for link hot-spots;  indeed, when
 867 .\" the default 10pt Times font is used, -1.0 point seems to be a
 868 .\" reasonable default value for "PDFHREF.LEADING" -- it may be
 869 .\" changed, if desired.
 870 .\"
 871 .\" "PDFHREF.HEIGHT" is initially set as one vertical spacing unit;
 872 .\" note that it is defined as a string, so it will adapt to changes
 873 .\" in the vertical spacing.  Changing it is NOT RECOMMENDED.
 874 .\"
 875 .nr PDFHREF.LEADING -1.0p
 876 .ds PDFHREF.HEIGHT   1.0v
 877 .\"
 878 .\" PDF readers generally place a rectangular border around link
 879 .\" "hot-spots".  Within text, this looks rather ugly, so we set
 880 .\" "PDFHREF.BORDER" to suppress it -- the three zeroes represent
 881 .\" the border parameters in the "/Border [0 0 0]" PDFMARK string,
 882 .\" and may be changed to any valid form, as defined in Adobe's
 883 .\" PDFMARK Reference Manual.
 884 .\"
 885 .ds PDFHREF.BORDER   0 0 0
 886 .\"
 887 .\" "PDFHREF.COLOUR" (note British spelling) defines the colour to
 888 .\" be used for display of link "hot-spots".  This will apply both
 889 .\" to borders, if used, and, by default to text; however, actual
 890 .\" text colour is set by "PDFHREF.TEXT.COLOUR", which may be reset
 891 .\" independently of "PDFHREF.COLOUR", to achieve contrasting text
 892 .\" and border colours.
 893 .\"
 894 .\" "PDFHREF.COLOUR" must be set to a sequence of three values,
 895 .\" each in the range 0.0 .. 1.0, representing the red, green, and
 896 .\" blue components of the colour specification in the RGB colour
 897 .\" domain, which is shared by "groff" and the PDF readers.
 898 .\"
 899 .ds PDFHREF.COLOUR   0.35 0.00 0.60
 900 .defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR]
 901 .\"
 902 .\" "PDFHREF.TEXT.COLOUR", on the other hand, is simply defined
 903 .\" using any "groff" colour name -- this default maps it to the
 904 .\" same colour value as "PDFHREF.COLOUR".
 905 .\"
 906 .ds PDFHREF.TEXT.COLOUR  pdf:href.colour
 907 .\"
 908 .\" Accommodate users who prefer the American spelling, COLOR, to
 909 .\" the British spelling, COLOUR.
 910 .\"
 911 .als PDFHREF.COLOR       PDFHREF.COLOUR
 912 .als PDFHREF.TEXT.COLOR  PDFHREF.TEXT.COLOUR
 913 .\"
 914 .\" All PDF "Hypertext" reference capabilities are accessed
 915 .\" through the "pdfhref" macro
 916 .\"
 917 .de pdfhref
 918 .\" -----------------------------------------------------------------
 919 .\" Usage:
 920 .\"   .pdfhref <subcommand [options ...] [parameters ...]> ...
 921 .\" -----------------------------------------------------------------
 922 .\"
 923 .if \\n[PDFOPMODE] \{\
 924 .\"
 925 .\" Loop over all subcommands specified in the argument list
 926 .\"
 927 .   while \\n(.$ \{\
 928 .   \"
 929 .   \" Initially, assume each subcommand will complete successfully
 930 .   \"
 931 .      nr pdf:href.ok 1
 932 .   \"
 933 .   \" Initialise -E and -X flags in the OFF state
 934 .   \"
 935 .      nr pdf:href-E 0
 936 .      nr pdf:href-X 0
 937 .   \"
 938 .   \" Handle the case where subcommand is specified as "-class",
 939 .   \" setting up appropriate macro aliases for subcommand handlers.
 940 .   \"
 941 .      if dpdf*href\\$1       .als pdf*href      pdf*href\\$1
 942 .      if dpdf*href\\$1.link  .als pdf*href.link pdf*href\\$1.link
 943 .      if dpdf*href\\$1.file  .als pdf*href.file pdf*href\\$1.file
 944 .   \"
 945 .   \" Repeat macro alias setup
 946 .   \" for the case where the subcommand is specified as "class",
 947 .   \" (without a leading hyphen)
 948 .   \"
 949 .      if dpdf*href-\\$1      .als pdf*href      pdf*href-\\$1
 950 .      if dpdf*href-\\$1.link .als pdf*href.link pdf*href-\\$1.link
 951 .      if dpdf*href-\\$1.file .als pdf*href.file pdf*href-\\$1.file
 952 .   \"
 953 .   \" Process one subcommand ...
 954 .   \"
 955 .      ie dpdf*href \{\
 956 .      \"
 957 .      \" Subcommand "class" is recognised ...
 958 .      \" discard the "class" code from the argument list,
 959 .      \" set the initial argument count to swallow all arguments,
 960 .      \" and invoke the selected subcommand handler.
 961 .      \"
 962 .         shift
 963 .         nr pdf:argc \\n(.$
 964 .         pdf*href \\$@
 965 .      \"
 966 .      \" When done,
 967 .      \" discard all arguments actually consumed by the handler,
 968 .      \" before proceeding to the next subcommand (if any).
 969 .      \"
 970 .         shift \\n[pdf:argc]
 971 .      \}
 972 .      el \{\
 973 .      \"
 974 .      \" Subcommand "class" is not recognised ...
 975 .      \" issue a warning, and discard the entire argument list,
 976 .      \" so aborting this "pdfhref" invocation
 977 .      \"
 978 .         pdf:warn \\$0: undefined reference class '\\$1' ignored
 979 .         shift \\n(.$
 980 .         \}
 981 .   \"
 982 .   \" Clean up temporary reference data,
 983 .   \" to ensure it doesn't propagate to any future reference
 984 .   \"
 985 .      rm pdf*href pdf:href.link pdf:href.files
 986 .      rr pdf:href-E pdf:href-X
 987 .      pdf:href.options.clear
 988 .      \}
 989 .   rr pdf:href.ok
 990 .   \}
 991 ..
 992 .\"
 993 .\" Macros "pdf:href.flag" and "pdf:href.option"
 994 .\" provide a generic mechanism for switching on flag type options,
 995 .\" and for decoding options with arguments, respectively
 996 .\"
 997 .de pdf:href.flag
 998 .\" ----------------------------------------------------------------------
 999 .\" ----------------------------------------------------------------------
1000 .nr pdf:href\\$1 1
1001 .nr pdf:href.argc 1
1002 ..
1003 .de pdf:href.option
1004 .\" ----------------------------------------------------------------------
1005 .\" ----------------------------------------------------------------------
1006 .ds pdf:href\\$1 \\$2
1007 .nr pdf:href.argc 2
1008 ..
1009 .\"
1010 .\" Valid PDFHREF options are simply declared
1011 .\" by aliasing option handlers to "pdf:href.option",
1012 .\" or to "pdf:href.flag", as appropriate
1013 .\"
1014 .als pdf:href.opt-A pdf:href.option   \" affixed text
1015 .als pdf:href.opt-D pdf:href.option   \" destination name
1016 .als pdf:href.opt-E pdf:href.flag     \" echo link descriptor
1017 .als pdf:href.opt-F pdf:href.option   \" remote file specifier
1018 .als pdf:href.opt-N pdf:href.option   \" reference name
1019 .als pdf:href.opt-P pdf:href.option   \" prefixed text
1020 .als pdf:href.opt-T pdf:href.option   \" bookmark "tag"
1021 .als pdf:href.opt-X pdf:href.flag     \" cross reference
1022 .\"
1023 .\" For references to another document file
1024 .\" we also need to support OS dependent file name specifiers
1025 .\"
1026 .als pdf:href.opt-DF pdf:href.option  \" /DOSFile specifier
1027 .als pdf:href.opt-MF pdf:href.option  \" /MacFile specifier
1028 .als pdf:href.opt-UF pdf:href.option  \" /UnixFile specifier
1029 .als pdf:href.opt-WF pdf:href.option  \" /WinFile specifier
1030 .\"
1031 .\" Macro "pdf:href.options.clear" ensures that ALL option
1032 .\" argument strings are deleted, after "pdfhref" has completed
1033 .\" all processing which depends on them
1034 .\"
1035 .de pdf:href.options.clear
1036 .\" -----------------------------------------------------------------
1037 .\" Usage:
1038 .\"   .pdf:href.options.clear [option ...]
1039 .\" -----------------------------------------------------------------
1040 .\"
1041 .\" When an option list is specified ...
1042 .\"
1043 .ie \\n(.$ \{\
1044 .   \"
1045 .   \" then loop through the list,
1046 .   \" deleting each specified option argument string in turn
1047 .   \"
1048 .   while \\n(.$ \{\
1049 .      if dpdf:href-\\$1 .rm pdf:href-\\$1
1050 .      shift
1051 .      \}
1052 .   \}
1053 .\"
1054 .\" ... but when no list is specified,
1055 .\" then recurse, to clear all known option argument strings
1056 .\"
1057 .el .pdf:href.options.clear A D F N P T DF MF UF WF
1058 ..
1059 .\"
1060 .\" "PDFHREF.INFO" establishes the content of the cross reference
1061 .\" data record, which is exported via the "stderr" stream, when a
1062 .\" cross reference anchor is created using a "pdfhref" macro request
1063 .\" of the form
1064 .\"
1065 .\"    .pdfhref M -N name -X text ...
1066 .\"
1067 .\"    .ds PDFHREF.INFO \\*[PDFHREF.NAME] reference data ...
1068 .\"
1069 .ds PDFHREF.INFO page \\n% \\$*
1070 .\"
1071 .\" Macro "pdf*href-M" is the handler invoked by "pdfhref", when
1072 .\" called with the "M" reference class specifier, to create a
1073 .\" named cross reference mark, and to emit a cross reference
1074 .\" data record, as specified by "PDFHREF.INFO".
1075 .\"
1076 .de pdf*href-M
1077 .\" -----------------------------------------------------------------
1078 .\" Usage:
1079 .\"   .pdfhref M [-X] [-N name | -D name] [-E] descriptive text ...
1080 .\" -----------------------------------------------------------------
1081 .\"
1082 .\" Initially, declare the -D and -N string options as empty,
1083 .\" so we avoid warning messages when we try to use them, and find
1084 .\" that they are undefined.
1085 .\"
1086 .ds pdf:href-D
1087 .ds pdf:href-N
1088 .\"
1089 .\" Parse, interpret, and strip any specified options from the
1090 .\" argument list.  (Note that only options with a declared handler
1091 .\" will be processed; there is no provision for detecting invalid
1092 .\" options -- anything which is not recognised is assumed to start
1093 .\" the "descriptive text" component of the argument list).
1094 .\"
1095 .while dpdf:href.opt\\$1 \{\
1096 .   pdf:href.opt\\$1 \\$@
1097 .   shift \\n[pdf:href.argc]
1098 .   \}
1099 .\"
1100 .\" If we found "--", to mark the end of the options,
1101 .\" then we should discard it.
1102 .\"
1103 .if '\\$1'--' .shift
1104 .\"
1105 .\" All PDF reference markers MUST be named. The name may have been
1106 .\" supplied using the "-N Name" option, (or the "-D Name" option);
1107 .\" if not, deduce it from the first "word" in the "descriptive text",
1108 .\" if any, and set the marker -- if we still can't identify the name
1109 .\" for the destination, then this marker will not be created.
1110 .\"
1111 .pdf*href.set \\*[pdf:href-N] \\*[pdf:href-D] \\$1
1112 .\"
1113 .\" If we specified a cross reference, with the "-X" option, and the
1114 .\" reference mark has been successfully created, then we now need to
1115 .\" write the cross reference info to the STDERR stream
1116 .\"
1117 .if \\n[pdf:href-X] .pdf*href.export \\*[PDFHREF.INFO]
1118 .\"
1119 .\" Irrespective of whether this marker is created, or not,
1120 .\" the descriptive text will be copied to the groff output stream,
1121 .\" provided the "-E" option was specified
1122 .\"
1123 .if \\n[pdf:href-E] \&\\$*
1124 ..
1125 .\"
1126 .de pdf*href.set
1127 .\" ----------------------------------------------------------------------
1128 .\" ----------------------------------------------------------------------
1129 .pdf*href.map.init
1130 .ie \\n(.$ \{\
1131 .   \"
1132 .   \" a marker name has been supplied ...
1133 .   \" if we are formatting for immediate output,
1134 .   \" emit PDFMARK code to establish the associated view
1135 .   \"
1136 .   ie '\\n(.z'' \{\
1137 .      pdf:href.sety
1138 .      pdfmark /Dest /\\$1 /View [\\*[PDFHREF.VIEW]] /DEST
1139 .      ds PDFHREF.NAME \\$1
1140 .      rr PDFPAGE.Y
1141 .      \}
1142 .   \"
1143 .   \" but, when formatting a diversion ...
1144 .   \" delay output of the PDFMARK code, until the diversion
1145 .   \" is eventually written out
1146 .   \"
1147 .   el \!.\\$0 \\$@
1148 .   \"
1149 .   \" check if we also need to emit cross reference data
1150 .   \" (caller will do this if "pdf:href-X" is set, but it is
1151 .   \"  not necessary, when "pdf:href.map" already exists)
1152 .   \"
1153 .   if dpdf:href.map .nr pdf:href-X 0
1154 .   \}
1155 .el \{\
1156 .   \" marker is unnamed ...
1157 .   \" issue error message; do not emit reference data
1158 .   \"
1159 .   pdf:warn pdfhref destination marker must be named
1160 .   nr pdf:href-X 0
1161 .   \}
1162 ..
1163 .de pdf*href.export
1164 .\"
1165 .\" Called ONLY by "pdf*href-M",
1166 .\" this macro ensures that the emission of exported reference data
1167 .\" is synchronised with the placement of the reference mark,
1168 .\" especially when the mark is defined within a diversion.
1169 .\"
1170 .ie '\\n(.z'' .tm gropdf-info:href \\*[PDFHREF.NAME] \\$*
1171 .el \!.\\$0 \\$@
1172 ..
1173 .\"
1174 .\" Macro "pdf*href-D" is invoked when "pdfhref" is called
1175 .\" with the "D" reference class specifier; it provides a
1176 .\" standardised mechanism for interpreting reference data
1177 .\" exported by the "M" reference class, and may be used
1178 .\" to directly define external reference data, without the
1179 .\" use of "M" reference class designators in the source
1180 .\" document.
1181 .\"
1182 .de pdf*href-D
1183 .ds pdf:href-N
1184 .\"
1185 .\" Parse, interpret, and strip any specified options from the
1186 .\" argument list.  (Note that only options with a declared handler
1187 .\" will be processed; there is no provision for detecting invalid
1188 .\" options -- anything which is not recognised is assumed to start
1189 .\" the "descriptive text" component of the argument list).
1190 .\"
1191 .while dpdf:href.opt\\$1 \{\
1192 .   pdf:href.opt\\$1 \\$@
1193 .   shift \\n[pdf:href.argc]
1194 .   \}
1195 .\"
1196 .\" If we found "--", to mark the end of the options,
1197 .\" then we should discard it.
1198 .\"
1199 .if '\\$1'--' .shift
1200 .\"
1201 .ie '\\*[pdf:href-N]'' \{\
1202 .   pdf:warn pdfhref defined reference requires a name
1203 .   \}
1204 .el \{\
1205 .   ds pdf:href(\\*[pdf:href-N]).info \\$*
1206 .   \}
1207 ..
1208 .\"
1209 .\" Macro "pdf*href-F" is invoked when "pdfhref" is called
1210 .\" with the "F" reference class specifier; it allows the user
1211 .\" to provide an alternative interpreter macro, which will be
1212 .\" called when a "PDFHREF.INFO" record is retrieved to define
1213 .\" the text of a cross reference link "hot spot".
1214 .\"
1215 .de pdf*href-F
1216 .\" ----------------------------------------------------------------
1217 .\" Usage:
1218 .\"   .pdfhref F [macro-name]
1219 .\" ----------------------------------------------------------------
1220 .\"
1221 .\" Set macro specified by "macro-name" as the format interpreter
1222 .\" for parsing "PDFHREF.INFO" records; if "macro-name" is omitted,
1223 .\" or is specified as the reserved name "default", then use the
1224 .\" default format parser, "pdf*href.format", defined below.
1225 .\"
1226 .if '\\$1'default' .shift \\n(.$
1227 .ie \\n(.$ .als pdf*href.format \\$1
1228 .el .als pdf*href.format pdf*href.default
1229 .nr pdf:argc 1
1230 ..
1231 .\" The default reference formatting macro is defined below.
1232 .\" It parses the "PDFHREF.INFO" record specific to each reference,
1233 .\" recognising the keywords "file", "page" and "section", when they
1234 .\" appear in initial key/value pairs, replacing the key/value pair
1235 .\" with "PDFHREF.FILEREF", "PDFHREF.PAGEREF" or "PDFHREF.SECTREF"
1236 .\" respectively; any additional data in the "PDFHREF.INFO" record
1237 .\" is enclosed in typographic double quotes, and the parsed record
1238 .\" is appended to "PDFHREF.PREFIX", to be returned as the formatted
1239 .\" reference text.
1240 .\"
1241 .\" Default definitions for the reference strings "PDFHREF.PREFIX",
1242 .\" "PDFHREF.FILEREF", "PDFHREF.PAGEREF" and "PDFHREF.SECTREF" are
1243 .\" provided, in the English language.  Users may substitute any
1244 .\" desired alternative definitions, for example, when formatting
1245 .\" documents in other languages.  In each case, "\\$1" may be used
1246 .\" in the substitution, to represent the "value" component of the
1247 .\" respective key/value pair specified in the "PDFHREF.INFO" record.
1248 .\"
1249 .ds PDFHREF.PREFIX   see
1250 .ds PDFHREF.PAGEREF  page \\$1,
1251 .ds PDFHREF.SECTREF  section \\$1,
1252 .ds PDFHREF.FILEREF  \\$1
1253 .\"
1254 .de pdf*href.format
1255 .\" -----------------------------------------------------------------
1256 .\" Usage: (to be called ONLY by "pdfhref")
1257 .\"   .pdf*href.format cross reference data ...
1258 .\" -----------------------------------------------------------------
1259 .\"
1260 .\" This macro is responsible for defining the strings "PDFHREF.TEXT"
1261 .\" and "PDFHREF.DESC", which are used by the "pdfhref" macro, as the
1262 .\" basis for generating the text content of a link "hot spot"; (any
1263 .\" user specified alternate formatter MUST do likewise).
1264 .\"
1265 .\" Note that "PDFHREF.TEXT" defines the overall format for the "link
1266 .\" text", while "PDFHREF.DESC" is the descriptive component thereof.
1267 .\"
1268 .\" This default implementation, subject to user customisation of the
1269 .\" "internationalisation" strings defined above, formats "hot spots"
1270 .\" of the style
1271 .\"
1272 .\"    see page N, section S, "descriptive text ..."
1273 .\"
1274 .ds PDFHREF.TEXT \\*[PDFHREF.PREFIX]
1275 .while d\\$0.\\$1 \{\
1276 .   \\$0.\\$1 "\\$2"
1277 .   shift 2
1278 .   \}
1279 .\"
1280 .\" Retrieve the descriptive text from the cross reference data,
1281 .\" ONLY IF no overriding description has been set by the calling
1282 .\" "pdfhref" macro invocation.
1283 .\"
1284 .if \\n(.$ .if !dPDFHREF.DESC .ds PDFHREF.DESC \\$*
1285 .\"
1286 .\" Augment "PDFHREF.TEXT" so the descriptive text will be included
1287 .\" in the text of the formatted reference
1288 .\"
1289 .if dPDFHREF.DESC .as PDFHREF.TEXT " \(lq\\\\*[PDFHREF.DESC]\(rq
1290 .\"
1291 .\" Finally, suppress any leading spaces,
1292 .\" which may have been included in the PDFHREF.TEXT definition.
1293 .\"
1294 .ds PDFHREF.TEXT \\*[PDFHREF.TEXT]
1295 ..
1296 .de pdf*href.format.file
1297 .\" ----------------------------------------------------------------------
1298 .\" Include a file identifier in a formatted reference.
1299 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1300 .\" reference data includes an initial file identifier tuple.
1301 .\" ----------------------------------------------------------------------
1302 .\"
1303 .as PDFHREF.TEXT " \\*[PDFHREF.FILEREF]
1304 ..
1305 .de pdf*href.format.page
1306 .\" ----------------------------------------------------------------------
1307 .\" Include a page number in a formatted reference.
1308 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1309 .\" reference data includes an initial page number tuple.
1310 .\" ----------------------------------------------------------------------
1311 .\"
1312 .as PDFHREF.TEXT " \\*[PDFHREF.PAGEREF]
1313 ..
1314 .de pdf*href.format.section
1315 .\" ----------------------------------------------------------------------
1316 .\" Include a section number in a formatted reference.
1317 .\" This is invoked ONLY by "pdf*href.format", and ONLY IF the
1318 .\" reference data includes an initial section number tuple.
1319 .\" ----------------------------------------------------------------------
1320 .\"
1321 .as PDFHREF.TEXT " \\*[PDFHREF.SECTREF]
1322 ..
1323 .\"
1324 .\" Make "pdf*href.format" the default cross reference formatter
1325 .\"
1326 .als pdf*href.default pdf*href.format
1327 .\"
1328 .\"
1329 .\" Macro "pdf*href" provides a generic mechanism for placing link
1330 .\" "hot-spots" in a PDF document.  ALL "pdfhref" class macros which
1331 .\" create "hot-spots" are aliased to this macro; each must also have
1332 .\" an appropriately aliased definition for "pdf*href.template".
1333 .\"
1334 .de pdf*href
1335 .\" ------------------------------------------------------------------
1336 .\" Usage:
1337 .\"   .pdf*href class [options ...] [link text ...]
1338 .\" ------------------------------------------------------------------
1339 .\"
1340 .\" First, we initialise an empty string, which will be affixed to
1341 .\" the end of the "link text".  (This is needed to cancel the effect
1342 .\" of a "\c" escape, which is placed at the end of the "link text"
1343 .\" to support the "-A" option -- any text supplied by the user, when
1344 .\" the "-A" option is specified, will replace this empty string).
1345 .\"
1346 .ds pdf:href-A
1347 .\"
1348 .\" Now we interpret, and remove any specified options from the
1349 .\" argument list.  (Note that only options with a declared handler
1350 .\" will be processed;  there is no provision for detecting invalid
1351 .\" options -- anything which is not recognised is assumed to start
1352 .\" the "link text" component of the argument list).
1353 .\"
1354 .while dpdf:href.opt\\$1 \{\
1355 .   pdf:href.opt\\$1 \\$@
1356 .   shift \\n[pdf:href.argc]
1357 .   \}
1358 .\"
1359 .\" If we found "--", to mark the end of the options, then we should
1360 .\" discard it.
1361 .\"
1362 .if '\\$1'--' .shift
1363 .\"
1364 .\" All PDF link classes REQUIRE a named destination.  This may have
1365 .\" been supplied using the "-D Name" option, but, if not, deduce it
1366 .\" from the first "word" in the "link text", if any -- if we still
1367 .\" can't identify the destination, then set "pdf:href.ok" to zero,
1368 .\" so this link will not be created.
1369 .\"
1370 .if !dpdf:href-D .pdf:href.option -D \\$1
1371 .if '\\*[pdf:href-D]'' \{\
1372 .   pdf:error pdfhref has no destination
1373 .   nr pdf:href.ok 0
1374 .   \}
1375 .\"
1376 .\" Some PDF link classes support a "/File (FilePathName)" argument.
1377 .\"
1378 .if dpdf*href.file \{\
1379 .   \"
1380 .   \" When this is supported, it may be specified by supplying
1381 .   \" the "-F FileName" option, which is captured in "pdf:href-F".
1382 .   \"
1383 .   if dpdf:href-F \{\
1384 .      \"
1385 .      \" the /File key is present, so set up the link specification
1386 .      \" to establish the reference to the specified file
1387 .      \"
1388 .      als pdf*href.link pdf*href.file
1389 .      ds pdf:href.files /File (\\*[pdf:href-F])
1390 .      \"
1391 .      \" in addition to the /File key,
1392 .      \" there may also be platform dependent alternate file names
1393 .      \"
1394 .      if dpdf:href-DF .as pdf:href.files " /DOSFile (\\*[pdf:href-DF])
1395 .      if dpdf:href-MF .as pdf:href.files " /MacFile (\\*[pdf:href-MF])
1396 .      if dpdf:href-UF .as pdf:href.files " /UnixFile (\\*[pdf:href-UF])
1397 .      if dpdf:href-WF .as pdf:href.files " /WinFile (\\*[pdf:href-WF])
1398 .      \}
1399 .   \" In some cases, the "/File" key is REQUIRED.
1400 .   \" We will know it is missing, if "pdf*href.link" is not defined.
1401 .   \"
1402 .   if !dpdf*href.link \{\
1403 .   \"
1404 .   \" When a REQUIRED "/File" key specification is not supplied,
1405 .   \" then complain, and set "pdf:href.ok" to abort the creation
1406 .   \" of the current reference.
1407 .   \"
1408 .      pdf:error pdfhref: required -F specification omitted
1409 .      nr pdf:href.ok 0
1410 .      \}
1411 .   \" Now, we have no further use for "pdf*href.file".
1412 .   \"
1413 .   rm pdf*href.file
1414 .   \}
1415 .\"
1416 .\" Now, initialise a string, defining the PDFMARK code sequence
1417 .\" to create the reference, using the appropriate type indicators.
1418 .\"
1419 .ds pdf:href.link /Subtype /Link \\*[pdf*href.link]
1420 .\"
1421 .\" And now, we have no further use for "pdf*href.link".
1422 .\"
1423 .rm pdf*href.link
1424 .\"
1425 .\" If the user specified any "link prefix" text, (using the "-P text"
1426 .\" option), then emit it BEFORE processing the "link text" itself.
1427 .\"
1428 .if dpdf:href-P \&\\*[pdf:href-P]\c
1429 .ie \\n[pdf:href.ok] \{\
1430 .   \"
1431 .   \" This link is VALID (so far as we can determine) ...
1432 .   \" Modify the "link text" argument specification, as required,
1433 .   \" to include any pre-formatted cross reference information
1434 .   \"
1435 .   ie \\n(.$ \{\
1436 .      \"
1437 .      \" One or more "link text" argument(s) are present,
1438 .      \" so, set the link description from the argument(s) ...
1439 .      \"
1440 .      ds PDFHREF.DESC \\\\$*
1441 .      ie \\n[pdf:href-X] \{\
1442 .         \"
1443 .         \" ... and, when the "-X" flag is set,
1444 .         \" also include formatted location information,
1445 .         \" derived from the cross reference record.
1446 .         \"
1447 .         pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
1448 .         \}
1449 .      el \{\
1450 .         \" ... but, when the "-X" flag is NOT set,
1451 .         \" use only the argument(s) as the entire content
1452 .         \" of the "link text"
1453 .         \"
1454 .         rn PDFHREF.DESC PDFHREF.TEXT
1455 .         \}
1456 .      \}
1457 .   el \{\
1458 .      \" No "link text" arguments are present,
1459 .      \" so, format the cross reference record to define
1460 .      \" the content of the "link text".
1461 .      \"
1462 .      pdf*href.format \\*[pdf:href(\\*[pdf:href-D]).info]
1463 .      \}
1464 .   \" Apply border and colour specifications to the PDFMARK string
1465 .   \" definition, as required.
1466 .   \"
1467 .   if dPDFHREF.BORDER .as pdf:href.link " /Border [\\*[PDFHREF.BORDER]]
1468 .   if dPDFHREF.COLOUR .as pdf:href.link " /Color  [\\*[PDFHREF.COLOUR]]
1469 .   \"
1470 .   \" Emit the "link text", in its appropriate colour, marking the
1471 .   \" limits of its bounding box(es), as the before and after output
1472 .   \" text positions.
1473 .   \"
1474 .   pdf*href.mark.begin "\\*[pdf:href.link]"
1475 .   if dPDFHREF.COLOUR .defcolor pdf:href.colour rgb \\*[PDFHREF.COLOUR]
1476 .   nop \&\m[\\*[PDFHREF.TEXT.COLOUR]]\\*[PDFHREF.TEXT]\m[]\c
1477 .   pdf*href.mark.end
1478 .   \"
1479 .   \" Clean up the temporary registers and strings, used to
1480 .   \" compute the "hot-spot" bounds, and format the reference,
1481 .   \"
1482 .   rm PDFHREF.DESC PDFHREF.TEXT
1483 .   \}
1484 .\"
1485 .\" But when we identify an INVALID link ...
1486 .\" We simply emit the "link text", with no colour change, no border,
1487 .\" and no associated "hot-spot".
1488 .\"
1489 .el \&\\$*\c
1490 .\"
1491 .\" And then, if the user specified any affixed text, (using the
1492 .\" "-A text" option), we tack it on at the end.
1493 .\"
1494 .nop \&\\*[pdf:href-A]
1495 ..
1496 .de pdf*href.map.init
1497 .\" ----------------------------------------------------------------------
1498 .\" ----------------------------------------------------------------------
1499 .\"
1500 .if dpdf:href.map-1 \{\
1501 .   \"
1502 .   \" We have a reference map, but we haven't started to parse it yet.
1503 .   \" This must be the first map reference in pass 2, so we need to
1504 .   \" "kick-start" the parsing process, by loading the first indexed
1505 .   \" sub-map into the global map.
1506 .   \"
1507 .   rn pdf:href.map-1 pdf:href.map
1508 .   als pdf:href.map.internal pdf:href.map
1509 .   nr pdf:href.map.index 1 1
1510 .   \}
1511 .als pdf*href.map.init pdf*href.mark.idle
1512 ..
1513 .\"
1514 .\" "pdf*href-Z" is used to add link co-ordinate entries to the
1515 .\" "pdf:href.map".  Primarily, it is used by the "pdfroff" formatter,
1516 .\" to pass link co-ordinate data from one "groff" formatting pass to
1517 .\" the next, and is not generally useful to the end user.
1518 .\"
1519 .de pdf*href-Z
1520 .\" ----------------------------------------------------------------------
1521 .\" Usage:
1522 .\"   .pdfhref Z page-index x-displacement y-displacement
1523 .\" Where:
1524 .\"   page-index      is the reference mark's page number
1525 .\"   x-displacement  is its offset from the left edge of the page
1526 .\"   y-displacement  is its offset from the top edge of the page
1527 .\" ( both displacement values are expressed in basic groff units, )
1528 .\" ( and measured perpendicular to their respective page edges.   )
1529 .\" ----------------------------------------------------------------------
1530 .\"
1531 .ie \\n(.$=3 .ds pdf:href.map-\\n+[pdf*href-Z.index] \\$*
1532 .el .pdf:error pdfhref Z operator expects exactly three arguments
1533 ..
1534 .\" Initialise the auto-incrementing "pdf*href-Z.index" register,
1535 .\" to ensure that sub-map numbering starts at 1.
1536 .\"
1537 .nr pdf*href-Z.index 0 1
1538 .\"
1539 .de pdf*href.map.read
1540 .\" ----------------------------------------------------------------------
1541 .\" Usage: (internal use only):
1542 .\"   .pdf*href.map.read co-ordinate name list ...
1543 .\" ----------------------------------------------------------------------
1544 .\"
1545 .\" Reads values from "pdf:href.map" to each named register, in turn
1546 .\" Reading to "null" discards the corresponding value in "pdf:href.map"
1547 .\"
1548 .while \\n(.$ \{\
1549 .   \"
1550 .   \" Loop over all registers named in the argument list,
1551 .   \" assigning values from "pdf:href.map" to each in turn.
1552 .   \"
1553 .   pdf:pop nr pdf:\\$1 pdf:href.map.internal
1554 .   if !dpdf:href.map.internal \{\
1555 .      \"
1556 .      \" We ran out of map references in the current sub-map,
1557 .      \" so move on to the next indexed sub-map, if any.
1558 .      \"
1559 .      if dpdf:href.map-\\n+[pdf:href.map.index] \{\
1560 .         rn pdf:href.map-\\n[pdf:href.map.index] pdf:href.map
1561 .         als pdf:href.map.internal pdf:href.map
1562 .         \}
1563 .      \}
1564 .   \"
1565 .   \" Proceed to the next named co-ordinate, (if any), specified
1566 .   \" in the argument list.
1567 .   \"
1568 .   shift
1569 .   \}
1570 .\"
1571 .\" Discard any assignments to a register named "null"
1572 .\"
1573 .rr pdf:null
1574 ..
1575 .de pdf*href.mark.begin
1576 .\" ----------------------------------------------------------------------
1577 .\" ----------------------------------------------------------------------
1578 .pdf*href.map.init
1579 .ie dpdf:href.map \{\
1580 .   \"
1581 .   \" Once we have established a document reference map,
1582 .   \" then this, and all subsequent calls to "pdf*href.mark.begin",
1583 .   \" may be redirected to the reference mark resolver, and the
1584 .   \" "pdf*href.mark.end" macro has nothing further to do.
1585 .   \"
1586 .   pdf*href.mark.resolve \\$@
1587 .   als pdf*href.mark.begin pdf*href.mark.resolve
1588 .   als pdf*href.mark.end pdf*href.mark.idle
1589 .   \}
1590 .el \{\
1591 .   \" Since we don't yet have a document reference map, the
1592 .   \" reference mark resolver will not work, in this pass of the
1593 .   \" formatter;  this, and all subsequent calls to "pdf*href.mark.begin",
1594 .   \" may be redirected to "pdf*href.mark.end", which is responsible
1595 .   \" for emitting the reference mark data to be incorporated into
1596 .   \" the reference map in a subsequent formatting pass.
1597 .   \"
1598 .   pdf*href.mark.end
1599 .   als pdf*href.mark.begin pdf*href.mark.end
1600 .   \}
1601 ..
1602 .de pdf*href.mark.resolve
1603 .\" ----------------------------------------------------------------------
1604 .\" ----------------------------------------------------------------------
1605 .ie '\\n(.z'' \{\
1606 .   ds pdf:href.link \\$1
1607 .   nr pdf:urx \\n(.o+\\n(.l
1608 .   pdf*href.map.read spg llx ury epg urx.end lly.end
1609 .   ie \\n[pdf:spg]=\\n[pdf:epg] \{\
1610 .      \"
1611 .      \" This link is entirely contained on a single page ...
1612 .      \" emit the text, which defines the content of the link region,
1613 .      \" then make it active.
1614 .      \"
1615 .      pdf*href.mark.emit 1 \\n[pdf:urx.end]
1616 .      if \\n[pdf:lly]<\\n[pdf:lly.end] \{\
1617 .         \"
1618 .         \" This link spans multiple output lines; we must save its
1619 .         \" original end co-ordinates, then define a new intermediate
1620 .         \" end point, to create a PDFMARK "hot-spot" extending from
1621 .         \" the start of the link to the end if its first line.
1622 .         \"
1623 .         nr pdf:ury +1v
1624 .         nr pdf:llx \\n(.o+\\n[.in]
1625 .         nr pdf:lly \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1626 .         if \\n[pdf:ury]<\\n[pdf:lly] \{\
1627 .            nr pdf:lly +\\*[PDFHREF.HEIGHT]-1v
1628 .            pdf*href.mark.emit 2
1629 .            nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1630 .            \}
1631 .         pdf*href.mark.emit 0 \\n[pdf:urx.end]
1632 .         \}
1633 .      pdf*href.mark.flush
1634 .      \}
1635 .   el \{\
1636 .      \" This link is split across a page break, so ...
1637 .      \" We must mark the "hot-spot" region on the current page,
1638 .      \" BEFORE we emit the link text, as we will have moved off
1639 .      \" this page, by the time the text has been output.
1640 .      \"
1641 .      \" First step: define the region from the start of the link,
1642 .      \" to the end of its first line.
1643 .      \"
1644 .      pdf*href.mark.emit 1 \\n[pdf:urx]
1645 .      \"
1646 .      \" All additional regions MUST align with the left margin.
1647 .      \"
1648 .      nr pdf:llx \\n(.o+\\n[.in]
1649 .      \"
1650 .      \" If the current page can accommodate more than the current line,
1651 .      \" then it will include a second active region for this link; this
1652 .      \" will extend from just below the current line to the end of page
1653 .      \" trap, if any, or the bottom of the page otherwise, and occupy
1654 .      \" the full width of the page, between the margins.
1655 .      \"
1656 .      nr pdf:ury +1v
1657 .      pdf*href.mark.emit 3
1658 .      \"
1659 .      \" We now need a page transition trap, to map the active link
1660 .      \" region(s), which overflow on to the following page(s); (the
1661 .      \" handler for this trap MUST have been previously installed).
1662 .      \"
1663 .      ie dpdf*href.mark.hook \{\
1664 .         \"
1665 .         \" The page transition trap handler has been installed,
1666 .         \" so we may activate both it, and also the appropriate
1667 .         \" termination handler, to deactivate it when done.
1668 .         \"
1669 .         als pdf*href.mark.hook pdf*href.mark.trap
1670 .         \"
1671 .         \" Now we set up "pdf:epg" to count the number of page breaks
1672 .         \" which this link will span, and emit the link text, leaving
1673 .         \" the page trap macro to map active regions on intervening
1674 .         \" pages, which are included in the link.
1675 .         \"
1676 .         nr pdf:epg -\\n[pdf:spg] 1
1677 .         \}
1678 .      el \{\
1679 .         \" There was no handler initialised for the page trap,
1680 .         \" so we are unable to map the active regions for this link;
1681 .         \" we may discard the remaining map data for this link,
1682 .         \" and issue a diagnostic.
1683 .         \"
1684 .         pdf:error pdfhref: link dissociated at page break (trap not initialised)
1685 .         if dPDFHREF.BROKEN.COLOR \{\
1686 .            \"
1687 .            \" The user may opt to have such broken links highlighted.
1688 .            \" We use "PDFHREF.BROKEN.COLOUR" to specify this requirement,
1689 .            \" but the user may prefer the American spelling, so we will
1690 .            \" handle both as equivalent.
1691 .            \"
1692 .            als PDFHREF.BROKEN.COLOUR PDFHREF.BROKEN.COLOR
1693 .            \}
1694 .         if dPDFHREF.BROKEN.COLOUR \{\
1695 .            if dPDFHREF.COLOUR .als PDFHREF.COLOUR PDFHREF.BROKEN.COLOUR
1696 .            \}
1697 .         \}
1698 .      \}
1699 .   \}
1700 .el \!.\\$0 \\$@
1701 ..
1702 .\"
1703 .\" Macro "pdf*href.mark.emit" is called only by "pdf*href".  It is
1704 .\" responsible for emitting the PDFMARK code, to establish the
1705 .\" "hot-spot" region associated with a document or resource link.
1706 .\"
1707 .de pdf*href.mark.emit
1708 .\" ----------------------------------------------------------------------
1709 .\" Usage:
1710 .\"   .pdf*href.mark.emit <action> [<end-urx>]
1711 .\"     <action> == 0 --> normal operation -- link height = 1 line
1712 .\"     <action> == 1 --> start of link -- add leading above text
1713 .\"     <action> == 2 --> overtall link -- set intermediate baseline
1714 .\"     <action> == 3 --> split link -- break at bottom of page
1715 .\" ----------------------------------------------------------------------
1716 .\"
1717 .if \\$1=1 \{\
1718 .   \"
1719 .   \" Initialising a new link region ...
1720 .   \" Some different versions of "groff" disagree about the vertical
1721 .   \" displacement of "opminy", as emitted by "\O1|\h'-\w"|"u'\O2\c",
1722 .   \" relative to the current text baseline.  Therefore, recompute
1723 .   \" the link displacement, independently of "opminy".
1724 .   \"
1725 .   mk pdf:ury.base
1726 .   while \\n[pdf:ury.base]<\\n[pdf:ury] .nr pdf:ury.base +1v
1727 .   nr pdf:ury.base -1m+\\n[PDFHREF.LEADING]
1728 .   \"
1729 .   \" adjust the end-point vertical displacement by the same offset,
1730 .   \" and then relocate the link starting point to its new displacement,
1731 .   \" as established by this base line relative computation.
1732 .   \"
1733 .   nr pdf:lly.end +\\n[pdf:ury.base]-\\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1734 .   rnn pdf:ury.base pdf:ury
1735 .   \}
1736 .if \\$1<2 \{\
1737 .   \"
1738 .   \" Link segment fits on a single line ...
1739 .   \" Set its height and end-point horizontal displacement accordingly.
1740 .   \"
1741 .   nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1742 .   if \\n[pdf:lly]>=\\n[pdf:lly.end] .nr pdf:urx \\$2
1743 .   \}
1744 .ie \\$1=3 \{\
1745 .   \"
1746 .   \" Link segment extends beyond the next page break ...
1747 .   \" Recompute truncated height, to just fit portion on current page,
1748 .   \" recursing to emit it, and leaving page trap mechanism to place
1749 .   \" continuation region(s) on following page(s).
1750 .   \"
1751 .   nr pdf:lly (\\n[.t]u-\\n[.V]u)/1v
1752 .   if \\n[pdf:lly]>0 \{\
1753 .      nr pdf:lly \\n[pdf:ury]+\\n[pdf:lly]v-1v+\\*[PDFHREF.HEIGHT]
1754 .      pdf*href.mark.emit 2
1755 .      \}
1756 .   \}
1757 .el \{\
1758 .   \" Link region size and placement has been fully specified ...
1759 .   \" Emit it.
1760 .   \"
1761 .   pdfmark \\*[pdf:href.link] /Rect [\\*[pdf:bbox]] /ANN
1762 .   \}
1763 ..
1764 .\"
1765 .\" When "pdf*href" emits a link for which the "hot-spot" spans a
1766 .\" page break, then we need to provide a "hook" in to the page break
1767 .\" trap, so we can map the "hot-spot" regions which are to be placed
1768 .\" on either side of the page break.
1769 .\"
1770 .\" Macro "pdf*href.mark.idle" is a dummy macro, which provide this
1771 .\" "hook" for normal page breaks, where there is no link "hot-spot"
1772 .\" crossing the break.
1773 .\"
1774 .de pdf*href.mark.idle
1775 .\" ----------------------------------------------------------------------
1776 .\" Usage:
1777 .\"   Called only as an internal hook, by a page trap macro.
1778 .\"   Expects no arguments, and does nothing.
1779 .\" ----------------------------------------------------------------------
1780 ..
1781 .\"
1782 .\" Macro "pdf*href.mark.trap" is the active "hook", which is substituted
1783 .\" for "pdf*href,mark.idle" at those page breaks which are crossed by
1784 .\" a link "hot-spot".
1785 .\"
1786 .de pdf*href.mark.trap
1787 .\" ----------------------------------------------------------------------
1788 .\" Usage:
1789 .\"   Called only as an internal hook, by a page trap macro.
1790 .\"   Expects no arguments.  Maps residual link "hot-spot" regions,
1791 .\"   which spill beyond any page break.  Not to be invoked directly
1792 .\"   by the user, nor by any user supplied macro.
1793 .\" ----------------------------------------------------------------------
1794 .\"
1795 .mk pdf:ury
1796 .nr pdf:ury +1v-1m-\\n[PDFHREF.LEADING]
1797 .ie \\n-[pdf:epg] \{\
1798 .   \"
1799 .   \" The link "hot-spot" extends across more than one page break,
1800 .   \" so, for each page which is completely contained within the
1801 .   \" extent of the link, simply mark the entire text area on the
1802 .   \" page as a "hot-spot".
1803 .   \"
1804 .   pdf*href.mark.emit 3
1805 .   \}
1806 .el \{\
1807 .   \" The link "hot-spot" ends on the page which immediately follows
1808 .   \" the current page transition, so we may now finalise this link.
1809 .   \"
1810 .   nr pdf:lly \\n[pdf:ury]+\\*[PDFHREF.HEIGHT]
1811 .   if \\n[pdf:lly.end]>\\n[pdf:lly] \{\
1812 .      \"
1813 .      \" The "hot-spot" extends beyond the first line of text,
1814 .      \" on its final page; compute and emit "hot-spot" region to cover
1815 .      \" the full with of the text area, including all but the last
1816 .      \" line of the link text.
1817 .      \"
1818 .      while \\n[pdf:lly.end]>\\n[pdf:lly] .nr pdf:lly +1v
1819 .      nr pdf:lly -1v
1820 .      pdf*href.mark.emit 2
1821 .      \"
1822 .      \" Now, adjust the vertical "hot-spot" mapping reference,
1823 .      \" to identify the correct position for the last line of
1824 .      \" text, over which the "hot-spot" extends.
1825 .      \"
1826 .      nr pdf:ury \\n[pdf:lly.end]-\\*[PDFHREF.HEIGHT]
1827 .      \}
1828 .   \"
1829 .   \" We now have exactly one final line of text, over which we must
1830 .   \" emit a "hot-spot" region;  map it, terminate page trap processing
1831 .   \" for this "hot-spot", and clean up the "hot-spot" mapping context.
1832 .   \"
1833 .   pdf*href.mark.emit 0 \\n[pdf:urx.end]
1834 .   als pdf*href.mark.hook pdf*href.mark.idle
1835 .   pdf*href.mark.flush
1836 .   \}
1837 ..
1838 .de pdf*href.mark.flush
1839 .\" ----------------------------------------------------------------------
1840 .\" ----------------------------------------------------------------------
1841 .rr pdf:spg pdf:epg
1842 .rr pdf:llx pdf:lly pdf:urx pdf:ury
1843 .if dPDFHREF.COLOR .als PDFHREF.COLOUR PDFHREF.COLOR
1844 .rr pdf:urx.end pdf:lly.end
1845 ..
1846 .de pdf*href.mark.end
1847 .\" ----------------------------------------------------------------------
1848 .\" ----------------------------------------------------------------------
1849 \O1\Z'|'\O2\c
1850 ..
1851 .\" Macro "pdf*href-I" is used for one time initialisation of special
1852 .\" "pdfhref" features; (currently, only the above page trap hook is
1853 .\" supported, but it is implemented with one level of indirection, to
1854 .\" accommodate possible future expansion).
1855 .
1856 .de pdf*href-I
1857 .\" ----------------------------------------------------------------------
1858 .\" Usage:
1859 .\"   .pdfhref I -<option> <optarg> [-<option> <optarg>] ...
1860 .\" ----------------------------------------------------------------------
1861 .\"
1862 .\" Loop over all arguments, in pairs ...
1863 .
1864 .while \\n(.$ \{\
1865 .   \"
1866 .   \" handing them off to their respective initialisers,
1867 .   \" when suitable initialisers exist, or complaining otherwise.
1868 .   \"
1869 .   ie dpdf*href\\$1.init .pdf*href\\$1.init \\$2
1870 .   el .pdf*error pdfhref:init: unknown feature '\\$1'
1871 .   shift 2
1872 .   \}
1873 ..
1874 .\" Before we can use the page break "hook", we need to initialise it
1875 .\" as an addendum to a regular page break trap. To ensure that we don't
1876 .\" compromise the user's page trap setup, we leave the onus for this
1877 .\" initialisation with the user, but we provide the "pdf*href-PT.init"
1878 .\" macro, (invoked by ".pdfhref I -PT <macro-name>"), to implement a
1879 .\" suitable initialisation action.
1880 .
1881 .de pdf*href-PT.init
1882 .\" ----------------------------------------------------------------------
1883 .\" Usage:
1884 .\"   .pdfhref I -PT <macro-name>
1885 .\"     <macro-name> == name of user's page break trap macro
1886 .\" ----------------------------------------------------------------------
1887 .\"
1888 .\" Initially, map the page break hook to its default, do nothing helper.
1889 .
1890 .als pdf*href.mark.hook pdf*href.mark.idle
1891 .ie !\\n(.$ \{\
1892 .   \"
1893 .   \" Don't have enough arguments to specify a page trap macro name,
1894 .   \" so simply plant "pdf*href.mark.hook" as a top of page trap.
1895 .   \"
1896 .   wh 0 pdf*href.mark.hook
1897 .   \}
1898 .el \{\
1899 .   \" Page trap macro name is specified in "\\$1" ...
1900 .   \"
1901 .   ie d\\$1 \{\
1902 .      \"
1903 .      \" When this page trap macro already exists, then we simply
1904 .      \" append a call to "pdf*href.mark.hook" to it.
1905 .      \"
1906 .      am \\$1 pdf*href.mark.idle
1907 .         pdf*href.mark.hook
1908 .         pdf*href.mark.idle
1909 .      \}
1910 .   el \{\
1911 .      \" However, when the specified page trap macro does not yet
1912 .      \" exist, then we create it, and plant it as a top of page
1913 .      \" trap.
1914 .      \"
1915 .      de \\$1 pdf*href.mark.idle
1916 .         pdf*href.mark.hook
1917 .         pdf*href.mark.idle
1918 .      wh 0 \\$1
1919 .      \}
1920 .   \}
1921 ..
1922 .
1923 .\" "pdf*href-L" is the generic handler for creating references to
1924 .\" named destinations in PDF documents.  It supports both local
1925 .\" references, to locations within the same document, through its
1926 .\" "pdf*href-L.link" attribute, and also references to locations
1927 .\" in any other PDF document, through "pdf*href-L.file".
1928 .\"
1929 .als pdf*href-L      pdf*href
1930 .ds  pdf*href-L.link /Dest /\\\\*[pdf:href-D]
1931 .ds  pdf*href-L.file /Action /GoToR \\\\*[pdf:href.files] \\*[pdf*href-L.link]
1932 .\"
1933 .\" "pdf*href-O" is the "official" handler for creating PDF
1934 .\" document outlines.  It is simply an alias to "pdfbookmark",
1935 .\" which may also be invoked directly, if preferred.  Neither
1936 .\" a "pdf*href-O.link" nor a "pdf*href-O.file" attribute is
1937 .\" required.
1938 .\"
1939 .als pdf*href-O      pdfbookmark
1940 .\"
1941 .\" "pdf*href-W" is the generic handler for creating references to
1942 .\" web resources, (or any resource specified by a uniform resource
1943 .\" identifier).  Such resource links are fully specified by the
1944 .\" "pdf*href-W.link" attribute.
1945 .\"
1946 .als pdf*href-W      pdf*href
1947 .ds  pdf*href-W.link /Action << /Subtype /URI /URI (\\\\*[pdf:href-D]) >>
1948 .\"
1949 .\" Local Variables:
1950 .\" mode: nroff
1951 .\" End:
1952 .\" vim: filetype=groff:
1953 .\" pdfmark.tmac: end of file