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

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 2531 lines · 2531 code · 0 blank · 0 comment · 0 complexity · c01bc1e55d1cbc0917956cb7adad1ae2 MD5 · raw file

Large files are truncated click here to view the full file

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