Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 2831 insertions, 0 deletions

diff --git a/contrib/pdfmark/pdfmark.ms b/contrib/pdfmark/pdfmark.ms
new file mode 100644
index 0000000..0d7d28c
--- /dev/null
+++ b/contrib/pdfmark/pdfmark.ms
@@ -0,0 +1,2831 @@
+.ig
+pdfmark.ms
+
+This file is part of groff, the GNU roff type-setting system.
+
+Copyright (C) 2004-2021 Free Software Foundation, Inc.
+written by Keith Marshall <keith.d.marshall@ntlworld.com>
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.
+
+A copy of the Free Documentation License is included as a file called
+FDL in the main directory of the groff source package.
+..
+.
+.CS
+Portable Document Format
+Publishing with GNU Troff
+.AU Keith Marshall
+.AI <keith.d.marshall@ntlworld.com>
+.CE
+.
+.\" Specify the Internet address for the groff web site.
+.\"
+.ds GROFF-WEBSITE http://www.gnu.org/software/groff
+.
+.\" Set the PDF default document view attribute, to ensure that the document
+.\" outline is visible, each time the document is opened in Acrobat Reader.
+.\"
+.pdfview /PageMode /UseOutlines
+.\"
+.\" Initialize the outline view to show only three heading levels,
+.\" with additional subordinate level headings folded.
+.\"
+.nr PDFOUTLINE.FOLDLEVEL 3
+.
+.\" Add document identification meta-data
+.\"
+.pdfinfo /Title     Portable Document Format Publishing with GNU Troff
+.pdfinfo /Author    Keith Marshall
+.pdfinfo /Subject   Tips and Techniques for Exploiting PDF Features with GNU Troff
+.pdfinfo /Keywords  groff troff PDF pdfmark
+.
+.\" Set the default cross reference format to indicate section numbers,
+.\" rather than page numbers, when we insert a reference pointer.
+.\"
+.ds PDFHREF.INFO section \\*[SN-NO-DOT] \\$*
+.
+.\" Define a macro, to print reference links WITHOUT the usual "see" prefix.
+.\"
+.de XR-NO-PREFIX
+.rn PDFHREF.PREFIX xx
+.ds PDFHREF.PREFIX
+.XR \\$@
+.rn xx PDFHREF.PREFIX
+..
+.
+.\" Define a string, to insert a Registered Trade Mark symbol as
+.\" a superscript...
+.\"
+.ds rg \*{\(rg\*}
+.\"
+.\" ...and use it to define strings, representing frequently used
+.\" registered trade marks.
+.\"
+.ds Adobe "Adobe\Z'\\$1'\*(rg\"
+.ds Acrobat "Acrobat\Z'\\$1'\*(rg\"
+.ds Distiller "Distiller\Z'\\$1'\*(rg\"
+.ds PostScript "PostScript\Z'\\$1'\*(rg\"
+.\"
+.ds Microsoft "Microsoft\Z'\\$1'\*(rg\"
+.
+.\" Establish the page layout.
+.\"
+.nr PO  2.5c
+.nr LL 17.0c
+.nr LT 17.0c
+.nr DI  5n
+.nr HY  0
+.
+.\" Within the table of contents, the width of the right-hand margin,
+.\" in which space is reserved for the display of page numbers, and the
+.\" appearance of the leaders which precede it, are controlled by:-
+.\"
+.char \[TC-LEADER] \h'0.8n'.
+.nr TC-MARGIN \w'00000'
+.
+.\" Generate headers in larger point sizes, for NH levels < 4,
+.\" with point size increasing by 1.5p, for each lesser NH level.
+.\"
+.nr GROWPS 4
+.nr PSINCR 1.5p
+.
+.
+.\" Implement an interface with the FS macro (from s.tmac) to facilitate
+.\" placement of footnote reference marks, with each serving as an active
+.\" pdfhref link to the associated footnote itself.
+.\"
+.de pdf:fn.mark nr
+.\" Macro to replace original duty performed by "\**"; must be invoked
+.\" at point of footnote mark placement, e.g. by FS, BEFORE recording of
+.\" the associated text within the footnote diversion is commenced.
+.\"
+.ie \\n[.$] \{\
+.   pdfhref L -D pdf:fn\\$1 -- \\$2
+.   pdfhref M -N pdf:fn\\$1r
+.   \}
+.\"
+.\" s.tmac does not publicly expose its auto-incrementing footnote index;
+.\" to avoid a dependency on an undocumented internal feature, we create
+.\" our own counter, while keeping the internal index synchronized, by
+.\" interpolating a renamed "\**", each time we increment our counter.
+.\"
+.el .\\$0 \\n+[pdf:fn.index.count] \\*[pdf:fn.index]
+.nr pdf:fn.index.count 0 1
+.rn * pdf:fn.index
+.ds * \c
+.
+.\" For versions of s.tmac which support the FS-MARK callback hook, it
+.\" is sufficient for us to answer the callback request.
+.\"
+.\" FIXME: in time, we may be able to unconditionally assume that this
+.\" callback hook will be supported...
+.\"
+.ie d FS-MARK .als FS-MARK pdf:fn.mark
+.el \{\
+.\" ...but in the interim, we may need to redefine s.tmac's FS macro,
+.\" (actually the @FS internal macro, rather than FS itself), to gain
+.\" an effect equivalent to taking control of FS-MARK, to achieve the
+.\" placement of a footnote mark as an active pdfhref link.
+.\"
+.rn @FS pdf:fn.record
+.de @FS
+.pdf:fn.mark
+.pdf:fn.record
+..
+.\}
+.\" Override s.tmac's (undocumented) footnote output hook; this emulates
+.\" the default output style for \n[FF] == 3 footnotes, with the footnote
+.\" number formatted as a pdfhref link back to the position at which the
+.\" footnote marker appears, within the document text.
+.\"
+.de FP
+.LP
+.nr pdf:fn.tag.width (u;2*\\n[FI])
+.ds pdf:fn.tag \s'-1.5p'\\$1.\s'+1.5p'
+.pdfhref M -N pdf:fn\\$1
+.in +\\n[pdf:fn.tag.width]u
+.ti -\\n[pdf:fn.tag.width]u
+.nr pdf:fn.tag.width -\\w'\\*[pdf:fn.tag]'u
+.pdfhref L -D pdf:fn\\$1r -A \\h'\\n[pdf:fn.tag.width]u'\c -- \\*[pdf:fn.tag]
+..
+.de pdfhref-nobreak
+.\" FIXME: I've only noticed this anomaly when planting pdfhref links
+.\" within footnotes; if the start of the link text is placed near the
+.\" line length limit, and all of it is moved to the start of the next
+.\" line, the "hot-spot" region is computed to be one line higher than
+.\" it should be; ending the preceding input line with "\c", and then
+.\" invoking pdfhref via this wrapper, works around this issue.
+.\"
+.ie \\n[.l]-\\n[.i]-\\n[.k]-\\w'\\$\\n[.$]' \&
+.el \p
+.pdfhref \\$*
+..
+.
+.\" Define a local macro to facilitate choice of style for emphasis;
+.\" by default, make it equivalent to the ms standard "I" macro.
+.\"
+.de EM
+.\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
+.I \\$@
+..
+.\" Also, define variations on the ms standard "CW" macro, to add
+.\" bold, italic, and both styles to constant width text; note that
+.\" each of these accept two additional arguments, in comparison to
+.\" standard "CW", such that \$1 specifies the text which is to be
+.\" styled, \$2 and \$3 specify inner after/before bracketting, to
+.\" set as regular "CW" text,  while \$4 and \$5 become equivalent
+.\" to \$2 and \$3 of standard "CW", acting as outer bracketting.
+.\"
+.de CWB
+\\$5\fC\\$3\fP\f(CB\\$1\fP\fC\\$2\fP\\$4
+..
+.de CWI
+\\$5\fC\\$3\fP\f(CI\\$1\fP\fC\\$2\fP\\$4
+..
+.de CWBI
+\\$5\fC\\$3\fP\f[CBI]\\$1\fP\fC\\$2\fP\\$4
+..
+.\" Finally, augment this group with a variant string, which may be
+.\" used to set constant width tags on "IP" paragraphs, with \$1 set
+.\" as if by "CWB", followed by an optional suffix set as if by "CWBI",
+.\" and with the suffix bracketted by \$3 after and \$4 before, each
+.\" set in the regular "CW" style.
+.\"
+.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
+.
+.\" Additionally, add a cross-reference convenience macro, emulating
+.\" the style of the "ms" font change macros...
+.\"
+.\"  .XR <dest-name> [<affixed> [<prefix>]]
+.\"
+.\" ...such that, when invoked with one, two, or three arguments, this
+.\" expands to the equivalent of:
+.\"
+.\"  .pdfhref L -D <dest-name> [-A <affixed> [-P <prefix>]]
+.\"
+.\" to place a pdfhref reference link, to a named destination, within
+.\" the same document, using the reference text which is predefined in
+.\" the reference dictionary entry associated with the destination.
+.\"
+.de XR
+.if \\n(.$ \{\
+.   if \\n[OPMODE] \{\
+.         ds xr!argv -D "\\$1"
+.         if \\n(.$>1 .as xr!argv " -A "\\$2"
+.         if \\n(.$>2 .as xr!argv " -P "\\$3"
+.         pdfhref L \\*[xr!argv]
+.         rm xr!argv
+.      \}
+.   \}
+..
+.
+.NH 1
+.\" Conventionally, in "ms", NH precedes text which is to be set as a
+.\" numbered section heading, but it makes no provision for automatic
+.\" reference to that heading in a table of contents, or (in the case
+.\" of PDF document production) in a document outline.  Both of these
+.\" limitations may be mitigated, by using the XN macro, (provided by
+.\" spdf.tmac), which sets its arguments, both as text to be included
+.\" in the section heading,  as printed, and as an assocated document
+.\" outline reference;  it will also make this same text available to
+.\" the user-specified callback macro,  XH-UPDATE-TOC, whereby it may
+.\" be used, e.g. to construct a table of contents entry.
+.\"
+.\" Within the table of contents, structural layout will be achieved,
+.\" under the direction of the following spacing control constants:
+.\"
+.ds XNVS1 0.50v  \" leading for top level
+.ds XNVS2 0.15v  \" leading at nesting level increment
+.ds XNVS3 0.30v  \" leading following nested group
+.\"
+.\" Note that one TOC related callback hook is shared by both XH and
+.\" XN; its is called XH-UPDATE-TOC, regardless of whether called by
+.\" XH or by XN; when called by XN, it is invoked with arguments:
+.\"
+.\"  .XH-UPDATE-TOC <outline-level> <section-number> <text> ...
+.\"
+.de XH-UPDATE-TOC
+.\" This implementation of XH-UPDATE-TOC utilizes the rudimentary ms
+.\" mechanism for formatting a table of contents, using XS and XE to
+.\" bracket individual entries.
+.   XS
+.   \" A local register, tc*hl, is used to track the outline level
+.   \" of each TOC entry, as it is added; it is not defined, until
+.   \" the first entry is recorded...
+.   \"
+.      if r tc*hl \{\
+.         \" ...after which, we use it to establish indentation,
+.         \" to reflect changes in outline level.
+.         \"
+.            ie \\$1>1 \{\
+.               \" When at any outline level greater than one,
+.               \" any level increment will be offset by XNVS2
+.               \" units of vertical space...
+.               \"
+.                  ie \\$1>\\n[tc*hl] .sp \\*[XNVS2]
+.
+.               \" ...whereas any decrement will be offset by
+.               \" XNVS3 units.
+.               \"
+.                  el .if \\n[tc*hl]>\\$1 .sp \\*[XNVS3]
+.               \}
+.
+.         \" ...but every top-level entry, after the first, is
+.         \" offset by XNVS1 units.
+.         \"
+.            el .sp \\*[XNVS1]
+.         \}
+.
+.   \" \$1 becomes the effective outline level for the current table
+.   \" of contents entry, but we must ensure that it is one or more.
+.   \"
+.      ie \\$1 .nr tc*hl \\$1
+.      el .nr tc*hl 1
+.
+.   \" The current outline level determines the indentation at which
+.   \" we place the section number reference...
+.   \"
+.      nop \h'\\n[tc*hl]-1m'\\$2\c
+.
+.   \" ...after which we discard \$1 and \$2,  allowing us to append
+.   \" all remaining arguments, ensuring that there is at least 0.5n
+.   \" of following space, before the first leader dot.
+.   \"
+.      shift 2
+.      nop \h'1.5n'\\$*\h'0.5n'
+.   XE
+..
+.XN Introduction
+.\"
+.\" If using an old s.tmac, without the SN-NO-DOT extension, ensure
+.\" that we get SOMETHING in section number references.
+.\"
+.if !d SN-NO-DOT .als SN-NO-DOT SN
+.LP
+It might appear that it is a fairly simple matter to
+produce documents in \*[Adobe]\~\(lqPortable\~Document\~Format\(rq,
+commonly known as PDF, using
+.CW groff ) GNU\~Troff\~(
+as the document formatter.
+Indeed,
+.CW groff 's
+default output format is the native \*[Adobe]\~\*[PostScript] format,
+which PDF producers such as \*[Adobe] \*[Acrobat] \*[Distiller ,]
+or GhostScript, expect as their input format.
+Thus, the PDF production process would seem to entail simply
+formatting the document source with
+.CW groff ,
+to produce a \*[PostScript] version of the document,
+which can subsequently be processed by \*[Acrobat] \*[Distiller]
+or GhostScript, to generate the final PDF document.
+.LP
+For many PDF production requirements,
+the production cycle described above may be sufficient.
+However, this is a limited PDF production method,
+in which the resultant PDF document represents no more than
+an on screen image of the printed form of the document, if
+.CW groff 's
+\*[PostScript] output were printed directly.
+.LP
+The Portable Document Format provides a number of features,
+which significantly enhance the experience of reading a document on screen,
+but which are of little or no value to a document which is merely printed.
+It
+.EM is
+possible to exploit these PDF features, which are described in the \*[Adobe]
+.de pdfmark-manual pdfmark-manual
+.\" This is an example of a resource reference specified by URI ...
+.\" We may need to refer often to the Adobe pdfmark Reference Manual,
+.\" so we create the internet link definition using a macro, to make
+.\" it reusable.
+.\"
+.\" Note also, that we protect the description of the reference by
+.\" preceding it with "--", to avoid "invalid character in name" type
+.\" error messages from groff (caused by the use of "\~").
+.\"
+.pdfhref W -D https://www.adobe.com/go/acrobatsdk_pdfmark \
+    -P \(lq -A \(rq\\$1 -- pdfmark\~Reference\~Manual
+.pdfmark-manual ,
+with some refinement of the simple PDF production method, provided
+appropriate \(lqfeature implementing\(rq instructions can be embedded into
+.CW groff 's
+\*[PostScript] rendering of the document.
+This, of course, implies that the original document source, which
+.CW groff
+will process to generate the \*[PostScript] description of the document,
+must include appropriate markup to exploit the desired PDF features.
+It is this preparation of the
+.CW groff
+document source to exploit a number of these features,
+which provides the principal focus of this document.
+.LP
+The markup techniques to be described have been utilized in the production of
+the PDF version of this document itself.
+This has been formatted using
+.CW groff 's
+.CW ms
+macro package;
+thus, usage examples may be found in the document source file,
+.CW \n(.F ,
+to which comments have been added,
+to help identify appropriate markup examples for implementing PDF features,
+such as:\(en
+.QS
+.IP \(bu
+Selecting a default document view, which defines how the document will appear
+when opened in the reader application; for example, when this document is
+opened in \*[Acrobat]\~Reader, it should display the top of the cover sheet,
+in the document view pane, while a document outline should appear to the left,
+in the \(lqBookmarks\(rq pane.
+.IP \(bu
+Adding document identification \(lqmeta\(hydata\(rq,
+which can be accessed, in \*[Acrobat]\~Reader,
+by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
+.IP \(bu
+Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
+pane of \*[Acrobat]\~Reader, such that readers may quickly navigate to any
+section of the document, simply by clicking on the associated heading
+in the outline view.
+.IP \(bu
+Embedding active links in the body of the document, such that readers may
+quickly navigate to related material at another location within the same
+document, or in another PDF document, or even to a related Internet resource,
+specified by its URI.
+.IP \(bu
+Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
+points within the PDF document.
+.QE
+.LP
+All of the techniques described have been tested on
+.EM both
+GNU/Linux, and on \*[Microsoft] Windows\(tm2000 operating platforms, using
+.CW groff
+.CW 1.19.1 ,\**
+.FS
+Later versions should, and some earlier versions may, be equally suitable.
+See\c
+.pdfhref-nobreak W \*[GROFF-WEBSITE]
+for information and availability of the latest version.
+.FE
+in association with
+.CW AFPL
+.CW GhostScript
+.CW 8.14 .\**
+.FS
+Again, other versions may be suitable.
+See\c
+.pdfhref-nobreak W http://ghostscript.com
+for information and availability.
+.FE
+\&
+Other tools employed, which should be readily available on
+.EM any
+Unix\(tm
+or GNU/Linux system, are
+.CW sed ,
+.CW awk
+and
+.CW make ,
+together with an appropriate text editor, for creating and marking up the
+.CW groff
+input files.
+These additional utilities are not provided, as standard,
+on the \*[Microsoft] Windows\(tm platform,
+but several third party implementations are available.
+Some worth considering include the MKS\*(rg\~Toolkit,\**
+.FS
+A commercial offering; see\c
+.pdfhref-nobreak W http://mkssoftware.com/products/tk/default.asp
+for information.
+.FE
+Cygwin,\**
+.FS
+A
+.EM free
+but comprehensive
+.SM
+POSIX
+.LG
+emulation environment and
+Unix\(tm
+toolkit for \%32\(hybit \*[Microsoft] Windows\(tm platforms; see\c
+.pdfhref-nobreak W http://cygwin.com
+for information and download.
+.FE
+or MSYS.\**
+.FS
+Another free, but minimal suite of common
+Unix\(tm
+tools for \%32\(hybit \*[Microsoft] Windows\(tm, available for download from\c
+.pdfhref-nobreak W -A ; https://mingw.osdn.io
+it
+.EM does 
+include those tools listed above,
+and is the package which was actually used when performing the Windows\(tm2000
+platform tests referred to in the text.
+.FE
+\&
+This list is by no means exhaustive, and should in no way be construed as an
+endorsement of any of these packages, nor to imply that other similar packages,
+which may be available, are in any way inferior to them.
+.bp
+.
+.NH 1
+.\" We may wish a section heading to represent a named destination,
+.\" so that we can create a linked reference to it, from some other 
+.\" part of the PDF document, (or even from another PDF document).
+.\"
+.\" Here we use the "-N" option of the "XN" macro, to create a named
+.\" PDF link destination, at the location of the heading.  Notice that
+.\" we also use the "--" marker to separate the heading text from the
+.\" preceding option specification; it is not strictly necessary in
+.\" this case, but it does help to set off the heading text from the
+.\" option specification.
+.\"
+.XN -N pdf-features -- Exploiting PDF Document Features
+.LP
+To establish a consistent framework for adding PDF features, a
+.CW groff
+macro package, named
+.CW pdfmark.tmac ,
+has been provided.
+Thus, to incorporate PDF features in a document,
+the appropriate macro calls, as described below, may be placed in the
+.CW groff
+document source, which should then be processed with a
+.CW groff
+command of the form\**
+.FS
+.pdfhref M pdf-features-fn
+.nr pdf-features-fn \n[fn*text-num]
+Note that,
+if any
+.CW -T \^\c
+.CWI dev
+option is specified,
+it should be either
+.CW -T \^\c
+.CW ps ,
+or
+.CW -T \^\c
+.CW pdf ;
+any other explicit choice is unlikely to be compatible with
+.CW -m \|\|\c
+.CW pdfmark ,
+and will have an unpredictable
+(possibly erroneous)
+effect on the output.
+If no
+.CW -T \^\c
+.CWI dev
+option is specified,
+(in which case
+.CW -T \^\c
+.CW ps
+is implicitly assumed),
+or if
+.CW -T \^\c
+.CW ps
+is explicitly specified,
+then the output will be produced in \*[PostScript] format,
+and will require conversion to PDF,
+(e.g. by using GhostScript tools);
+explicit specification of
+.CW -T \^\c
+.CW pdf
+will result in direct output in PDF format,
+thus obviating the need for conversion.
+.FE
+.QP
+.fam C
+groff [-Tps\h'0.2p'|\h'0.2p'-Tpdf] [-m\F[]\|\|\FC\c
+.I name ]
+-m\F[]\|\|\FC\c
+.B pdfmark
+.I options \F[]\|\|\FC\c [-
+.I file \F[]\|\|\FC\c "...] "
+\&...
+.LP
+It may be noted that the
+.CW pdfmark
+macros have no dependencies on, and no known conflicts with,
+any other
+.CW groff
+macro package;  thus, users are free to use any other macro package,
+of their choice, to format their documents, while also using the
+.CW pdfmark
+macros to add PDF features.
+.
+.NH 2
+.XN -S -N pdfmark-operator -- The \F[C]pdfmark\F[] Operator
+.LP
+All PDF features are implemented by embedding instances of the
+.B \F[C]pdfmark\F[]
+operator, as described in the \*[Adobe]
+.pdfmark-manual ,
+into
+.CW groff 's
+\*[PostScript] output stream.
+To facilitate the use of this operator, the
+.CW pdfmark
+macro package defines the primitive
+.CW pdfmark
+macro; it simply emits its argument list,
+as arguments to a
+.CW pdfmark
+operator, in the \*[PostScript] output stream.
+.LP
+.pdfhref M -N pdfmark-example
+To illustrate the use of the
+.CW pdfmark
+macro, the following is a much simplified example of how a bookmark
+may be added to a PDF document outline
+.QP
+.CW ".pdfmark \e"
+.RS 4
+.nf
+.fam C
+/Count 2 \e
+/Title (An Example of a Bookmark with Two Children) \e
+/View  [/FitH \en[PDFPAGE.Y]] \e
+/OUT
+.RE
+.LP
+In general, users should rarely need to use the
+.CW pdfmark
+macro directly.
+In particular, the above example is too simple for general use; it
+.EM will
+create a bookmark, but it does
+.EM not
+address the issues of setting the proper value for the
+.CW /Count
+key, nor of computing the
+.CW PDFPAGE.Y
+value used in the
+.CW /View
+key. The
+.CW pdfmark
+macro package includes a more robust mechanism for creating bookmarks,
+.\"
+.\" Here is an example of how a local reference may be planted,
+.\" using the automatic formatting feature of the "pdfhref" macro.
+.\"
+.\" This is a forward reference to the named destination "add-outline",
+.\" which is defined below, using the "XN" wrapper macro, from the
+.\" "spdf.tmac" macro package.  The automatically formatted reference
+.\" will be enclosed in parentheses, as specified by the use of
+.\" "-P" and "-A" options.
+.\"
+.pdfhref L -P ( -A ), -D add-outline
+.\"
+which addresses these issues automatically.
+Nevertheless, the
+.CW pdfmark
+macro may be useful to users wishing to implement more advanced PDF features,
+than those currently supported directly by the
+.CW pdfmark
+macro package.
+.
+.NH 2
+.XN -N docview -- Selecting an Initial Document View
+.LP
+By default,
+when a PDF document is opened,
+the first page will be displayed,
+at the default magnification set for the reader,
+and outline and thumbnail views will be hidden.
+When using a PDF reader,
+such as \*[Acrobat]\~Reader,
+which supports the
+.CW /DOCVIEW
+class of the
+.CW pdfmark
+operator,
+these default initial view settings may be overridden,
+using the
+.CW pdfview
+macro.
+For example
+.QP
+.CW ".pdfview /PageMode /UseOutlines"
+.LP
+will cause \*[Acrobat]\~Reader to open the document outline view,
+to the left of the normal page view,
+while
+.QP
+.CW ".pdfview /PageMode /UseThumbs"
+.LP
+will open the thumbnail view instead.
+.LP
+Note that the two
+.CW /PageMode
+examples, above, are mutually exclusive \(em it is not possible to have
+.EM both
+outline and thumbnail views open simultaneously.
+However, it
+.EM is
+permitted to add
+.CW /Page
+and
+.CW /View
+keys, to force the document to open at a page other than the first,
+or to change the magnification at which the document is initially displayed;
+see the
+.pdfmark-manual
+for more information.
+.LP
+It should be noted that the view controlling meta\(hydata, defined by the
+.CW pdfview
+macro, is not written immediately to the \*[PostScript] output stream,
+but is stored in an internal meta\(hydata \(lqcache\(rq,
+(simply implemented as a
+.CW groff
+diversion).
+This \(lqcached\(lq meta\(hydata must be written out later, by invoking the
+.CW pdfsync
+macro,
+.\"
+.\" Here is another example of how we may introduce a forward reference.
+.\" This time we are using the shorter notation afforded by the "XR" macro
+.\" provided by "spdf.tmac"; this example is equivalent to the native
+.\" "pdfmark.tmac" form
+.\"     .pdfhref L -D pdfsync -P ( -A ).
+.\"
+.XR pdfsync ). (
+.
+.NH 2
+.XN -N docinfo -- Adding Document Identification Meta-Data
+.LP
+In addition to the
+.CW /DOCVIEW
+class of meta\(hydata described above,
+.XR docview ), (
+we may also wish to include document identification meta\(hydata,
+which belongs to the PDF
+.CW /DOCINFO
+class.
+.LP
+To do this, we use the
+.CW pdfinfo
+macro.
+As an example of how it is used,
+the identification meta\(hydata attached to this document
+was specified using a macro sequence similar to:\(en
+.DS I
+.CW
+\&.pdfinfo /Title     PDF Document Publishing with GNU Troff
+\&.pdfinfo /Author    Keith Marshall
+\&.pdfinfo /Subject   How to Exploit PDF Features with GNU Troff
+\&.pdfinfo /Keywords  groff troff PDF pdfmark
+.DE
+Notice that the
+.CW pdfinfo
+macro is repeated, once for each
+.CW /DOCINFO
+record to be placed in the document.
+In each case, the first argument is the name of the applicable
+.CW /DOCINFO
+key, which
+.EM must
+be named with an initial solidus character;
+all additional arguments are collected together,
+to define the value to be associated with the specified key.
+.LP
+As is the case with the
+.CW pdfview
+macro,
+.XR docview ), (
+the
+.CW /DOCINFO
+records specified with the
+.CW pdfinfo
+macro are not immediately written to the \*[PostScript] output stream;
+they are stored in the same meta\(hydata cache as
+.CW /DOCVIEW
+specifications, until this cache is explicitly flushed,
+by invoking the
+.CW pdfsync
+macro,
+.XR pdfsync ). (
+.
+.NH 2
+.XN -N add-outline -- Creating a Document Outline
+.LP
+A PDF document outline comprises a table of references,
+to \(lqbookmarked\(rq locations within the document.
+When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
+such as \*[Adobe] \*[Acrobat] Reader,
+this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
+or \(lqBookmarks\(rq pane, to the left of the main document view.
+Individual references in the outline view may then be selected,
+by clicking with the mouse,
+to jump directly to the associated marked location in the document view.
+.LP
+The document outline may be considered as a collection of \(lqhypertext\(rq
+references to \(lqbookmarked\(rq locations within the document.
+The
+.CW pdfmark
+macro package provides a single generalized macro,
+.CW pdfhref ,
+for creating and linking to \(lqhypertext\(rq reference marks.
+This macro will be described more comprehensively in a later section,
+.XR pdfhref ); (
+the description here is restricted to its use for defining document outline entries.
+.
+.NH 3
+.XN -N basic-outline -- A Basic Document Outline
+.LP
+In its most basic form, the document outline comprises a structured list of headings,
+each associated with a marked location, or \(lqbookmark\(rq, in the document text,
+and a specification for how that marked location should be displayed,
+when this bookmark is selected.
+.LP
+To create a PDF bookmark, the
+.CW pdfhref
+macro is used,
+at the point in the document where the bookmark is to be placed,
+in the form
+.QP
+.fam C
+.B ".pdfhref O"
+.I level > <
+.I "descriptive text ..."
+.LP
+in which the reference class
+.CWB O \& \& \(rq \(lq
+stipulates that this is an outline reference.
+.LP
+Alternatively, for those users who may prefer to think of a document outline
+simply as a collection of bookmarks, the
+.CW pdfbookmark
+macro is also provided \(em indeed,
+.CW pdfhref
+invokes it, when processing the
+.CWB O \& \& \(rq \(lq
+reference class operator.
+It may be invoked directly, in the form
+.QP
+.fam C
+.B .pdfbookmark
+.I level > <
+.I "descriptive text ..."
+.LP
+Irrespective of which of the above macro forms is employed, the
+.CWI level > <
+argument is required.
+It is a numeric argument, defining the nesting level of the \(lqbookmark\(rq
+in the outline hierarchy, with one being the topmost level.
+Its function may be considered analagous to the
+.EM "heading level"
+of the document's section headings,
+for example, as specified with the
+.CW NH
+macro, if using the
+.CW ms
+macros to format the document.
+.LP
+All further arguments, following the
+.CWI level > <
+argument, are collected together, to specify the heading text which will appear
+in the document's outline view.
+Thus, the outline entry for this section of this document,
+which has a level three heading,
+might be specified as
+.QP
+.CW
+\&.pdfhref O 3 \*(SN A Basic Document Outline
+.LP
+or, in the alternative form using the
+.CW pdfbookmark
+macro, as
+.QP
+.CW
+\&.pdfbookmark 3 \*(SN A Basic Document Outline
+.
+.NH 3
+.XN Hierarchical Structure in a Document Outline
+.LP
+When a document outline is created, using the
+.CW pdfhref
+macro as described in
+.\"
+.\" Here is an example of how we can temporarily modify the format of
+.\" a reference link, in this case to indicate only the section number
+.\" of the link target, in the form "section #", (or, if we define
+.\" "SECREF.BEGIN" before the call, its content followed by the
+.\" section number).
+.\"
+.\" We first define a macro, which will get the reference data from
+.\" pdfhref, as arguments, and will return the formatted output, as we
+.\" require it, the string "PDFHREF.TEXT".
+.\"
+.de SECREF
+.while \\n(.$ \{\
+.   ie '\\$1'section' \{\
+.      if !dSECREF.BEGIN .ds SECREF.BEGIN \\$1
+.      ds PDFHREF.TEXT \\*[SECREF.BEGIN]\~\\$2
+.      rm SECREF.BEGIN
+.      shift \\n(.$
+.      \}
+.   el .shift
+.   \}
+..
+.\" We now tell "pdfhref" to use our formatting macro, in place of
+.\" its builtin default formatter, before we specify the reference.
+.\"
+.pdfhref F SECREF
+.pdfhref L -A , -D basic-outline
+.\"
+.\" At this point, we would normally revert the "pdfhref" formatter
+.\" to use its default, built in macro.  However, in this particular
+.\" case, we want to use our custom format one more time, before we
+.\" revert it, so we will omit the reversion step this time.
+.\"
+and any entry is added at a nesting level greater than one,
+then a hierarchical structure is automatically defined for the outline.
+However, as was noted in the simplified
+.pdfhref L -D pdfmark-example -- example
+in
+.pdfhref L -A , -D pdfmark-operator
+.\"
+.\" And now, we revert to default "pdfhref" formatting behaviour,
+.\" by completing the call we delayed above.
+.\"
+.pdfhref F
+.\"
+the data required by the
+.CW pdfmark
+operator to create the outline entry may not be fully defined,
+when the outline reference is defined in the
+.CW groff
+document source.
+Specifically, when the outline entry is created, its
+.CW /Count
+key must be assigned a value equal to the number of its subordinate entries,
+at the next inner level of the outline hierarchy;
+typically however,
+these subordinate entries will be defined
+.EM later
+in the document source, and the appropriate
+.CW /Count
+value will be unknown, when defining the parent entry.
+.LP
+To resolve this paradox, the
+.CW pdfhref
+macro creates the outline entry in two distinct phases \(em
+a destination marker is placed in the \*[PostScript] output stream immediately,
+when the outline reference is defined,
+but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
+until its subordinate hierarchy has been fully defined;
+it can then be inserted in the output stream, with its
+.CW /Count
+value correctly assigned.
+Effectively, to ensure integrity of the document outline structure,
+this means that each top level outline entry, and
+.EM all
+of its subordinates, are retained in the cache, until the
+.EM next
+top level entry is defined.
+.LP
+One potential problem, which arises from the use of the \(lqoutline cache\(rq,
+is that, at the end of any document formatting run, the last top level outline entry,
+and any subordinates defined after it, will remain in the cache, and will 
+.EM not
+be automatically written to the output stream.
+To avoid this problem, the user should follow the guidelines given in
+.\"
+.\" Here is a more conventional example of how to temporarily change
+.\" to the format used to display reference links.  We will again use
+.\" the "SECREF" format, which we defined above, but on this occasion
+.\" we will immediately revert to the default format, after the link
+.\" has been placed.
+.\"
+.pdfhref F SECREF
+.pdfhref L -D pdfsync -A ,
+.pdfhref F
+.\"
+to synchronize the output state with the cache state,
+.XR pdfsync ), (
+at the end of the
+.CW groff
+formatting run.
+.
+.NH 3
+.XN -N outline-view -- Associating a Document View with an Outline Reference
+.LP
+Each \(lqbookmark\(rq entry, in a PDF document outline,
+is associated with a specific document view.
+When the reader selects any outline entry,
+the document view changes to display the document context
+associated with that entry.
+.LP
+The document view specification,
+to be associated with any document outline entry,
+is established at the time when the outline entry is created.
+However, rather than requiring that each individual use of the
+.CW pdhref
+macro, to create an outline entry,
+should include its own view specification,
+the actual specification assigned to each entry is derived from
+a generalized specification defined in the string
+.CW PDFBOOKMARK.VIEW ,
+together with the setting of the numeric register
+.CW PDFHREF.VIEW.LEADING ,
+which determine the effective view specification as follows:\(en
+.QS
+.IP \*[= PDFBOOKMARK.VIEW]
+Establishes the magnification at which the document will be viewed,
+at the location of the \(lqbookmark\(rq; by default, it is defined by
+.RS
+.QP
+.CW ".ds PDFBOOKMARK.VIEW /FitH \e\en[PDFPAGE.Y] u"
+.RE
+.IP
+which displays the associated document view,
+with the \(lqbookmark\(rq location positioned at the top of the display window,
+and with the magnification set to fit the page width to the width of the window.
+.IP \*[= PDFHREF.VIEW.LEADING]
+Specifies additional spacing,
+to be placed between the top of the display window
+and the actual location of the \(lqbookmark\(rq on the displayed page view.
+By default, it is set as
+.RS
+.QP
+.CW ".nr PDFHREF.VIEW.LEADING 5.0p"
+.RE
+.IP
+Note that
+.CW PDFHREF.VIEW.LEADING
+does not represent true \(lqleading\(rq, in the typographical sense,
+since any preceding text, set in the specified display space,
+will be visible at the top of the document viewing window,
+when the reference is selected.
+.IP
+Also note that the specification of
+.CW PDFHREF.VIEW.LEADING
+is shared by
+.EM all
+reference views defined by the
+.CW pdfhref
+macro; whereas
+.CW PDFBOOKMARK.VIEW
+is applied exclusively to outline references,
+there is no independent
+.CW PDFBOOKMARK.VIEW.LEADING
+specification.
+.QE
+.LP
+If desired, the view specification may be changed, by redefining the string
+.CW PDFBOOKMARK.VIEW ,
+and possibly also the numeric register
+.CW PDFHREF.VIEW.LEADING .
+Any alternative definition for
+.CW PDFBOOKMARK.VIEW
+.EM must
+be specified in terms of valid view specification parameters,
+as described in the \*[Adobe]
+.pdfmark-manual .
+.LP
+Note the use of the register
+.CW PDFPAGE.Y ,
+in the default definition of
+.CW PDFBOOKMARK.VIEW
+above.
+This register is computed by
+.CW pdfhref ,
+when creating an outline entry;
+it specifies the vertical position of the \(lqbookmark\(rq,
+in basic
+.CW groff
+units, relative to the
+.EM bottom
+edge of the document page on which it is defined,
+and is followed, in the
+.CW PDFBOOKMARK.VIEW
+definition, by the
+.CW grops
+.CW u \(rq \(lq
+operator, to convert it to \*[PostScript] units on output.
+It may be used in any redefined specification for
+.CW PDFBOOKMARK.VIEW ,
+(or in the analogous definition of
+.CW PDFHREF.VIEW ,
+described in
+'ne 2v
+.XR-NO-PREFIX pdfhref-view ),
+but
+.EM not
+in any other context,
+since its value is undefined outside the scope of the
+.CW pdfhref
+macro.
+.LP
+Since
+.CW PDFPAGE.Y
+is computed relative to the
+.EM bottom
+of the PDF output page,
+it is important to ensure that the page length specified to
+.CW troff
+correctly matches the size of the logical PDF page.
+This is most effectively ensured,
+by providing
+.EM identical
+page size specifications to
+.CW groff ,
+.CW grops
+and to the \*[PostScript] to PDF converter employed,
+and avoiding any page length changes within the document source.
+.LP
+Also note that
+.CW PDFPAGE.Y
+is the only automatically computed \(lqbookmark\(rq location parameter;
+if the user redefines
+.CW PDFBOOKMARK.VIEW ,
+and the modified view specification requires any other positional parameters,
+then the user
+.EM must
+ensure that these are computed
+.EM before
+invoking the
+.CW pdfhref
+macro.
+.
+.NH 3
+.XN -N outline-folding -- Folding the Outline to Conceal Less Significant Headings
+.LP
+When a document incorporates many subheadings,
+at deeply nested levels,
+it may be desirable to \(lqfold\(rq the outline
+such that only the major heading levels are initially visible,
+yet making the inferior subheadings accessible,
+by allowing the reader to expand the view of any heading branch on demand.
+.LP
+The
+.CW pdfmark
+macros support this capability,
+through the setting of the
+.CW PDFOUTLINE.FOLDLEVEL
+register.
+This register should be set to the number of heading levels
+which it is desired to show in expanded form, in the
+.EM initial
+document outline display;
+all subheadings at deeper levels will still be added to the outline,
+but will not become visible until the outline branch containing them is expanded.
+'ne 5
+For example, the setting used in this document:
+.QS
+.LD
+.fam C
+\&.\e" Initialize the outline view to show only three heading levels,
+\&.\e" with additional subordinate level headings folded.
+\&.\e"
+\&.nr PDFOUTLINE.FOLDLEVEL 3
+.DE
+.QE
+.LP
+results in only the first three levels of headings being displayed
+in the document outline,
+.EM until
+the reader chooses to expand the view,
+and so reveal the lower level headings in any outline branch.
+.LP
+The initial default setting of
+.CW PDFOUTLINE.FOLDLEVEL ,
+if the document author does not choose to change it,
+is 10,000.
+This is orders of magnitude greater than the maximum heading level
+which is likely to be used in any document;
+thus the default behaviour will be to show document outlines fully expanded,
+to display all headings defined,
+at all levels within each document.
+.LP
+The setting of
+.CW PDFOUTLINE.FOLDLEVEL
+may be changed at any time;
+however, the effect of each such change may be difficult to predict,
+since it is applied not only to outline entries which are defined
+.EM after
+the setting is changed,
+but also to any entries which remain in the outline cache,
+.EM at
+this time.
+Therefore, it is recommended that
+.CW PDFOUTLINE.FOLDLEVEL
+should be set
+.EM once ,
+at the start of each document;
+if it
+.EM is
+deemed necessary to change it at any other time,
+the outline cache should be flushed,
+.XR pdfsync ), (
+.EM immediately
+before the change,
+which should immediately preceed a level one heading.
+.
+.NH 3
+.XN -N multipart-outline -- Outlines for Multipart Documents
+.LP
+When a document outline is created, using the
+.CW pdfhref
+macro, each reference mark is automatically assigned a name,
+composed of a fixed stem followed by a serially generated numeric qualifier.
+This ensures that, for each single part document, every outline reference
+has a uniquely named destination.
+.LP
+As the overall size of the PDF document increases,
+it may become convenient to divide it into smaller,
+individually formatted \*[PostScript] components,
+which are then assembled, in the appropriate order,
+to create a composite PDF document.
+While this strategy may simplify the overall process of creating and
+editing larger documents, it does introduce a problem in creating
+an overall document outline,
+since each individual \*[PostScript] component will be assigned
+duplicated sequences of \(lqbookmark\(rq names,
+with each name ultimately referring to multiple locations in the composite document.
+To avoid such reference naming conflicts, the
+.CW pdfhref
+macro allows the user to specify a \(lqtag\(rq,
+which is appended to the automatically generated \(lqbookmark\(rq name;
+this may be used as a discriminating mark, to distinguish otherwise
+similarly named destinations, in different sections of the composite document.
+.LP
+To create a \(lqtagged\(rq document outline,
+the syntax for invocation of the
+.CW pdfhref
+macro is modified, by the inclusion of an optional \(lqtag\(rq specification,
+.EM before
+the nesting level argument, i.e.
+.QP
+.fam C
+.B ".pdfhref O"
+.B -T \& [
+.I tag >] <
+.I level > <
+.I "descriptive text ..."
+.LP
+The optional
+.CWI tag > <
+argument may be composed of any characters of the user's choice;
+however, its initial character
+.EM "must not"
+be any decimal digit, and ideally it should be kept short
+\(em one or two characters at most.
+.LP
+By employing a different tag in each section,
+the user can ensure that \(lqbookmark\(rq names remain unique,
+throughout all the sections of a composite document.
+For example, when using the
+.CW spdf.tmac
+macro package, which adds
+.CW pdfmark
+capabilities to the standard
+.CW ms
+package,
+.XR using-spdf ), (
+the table of contents is collected into a separate \*[PostScript] section
+from the main body of the document.
+In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
+but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
+.CW TC
+macro adds an outline entry for the start of the \(lqTable\~of\~Contents\(rq,
+invoking the
+.CW pdfhref
+macro as
+.QP
+.CW ".pdfhref O -T T 1 \e\e*[TOC]"
+.LP
+to tag the associated outline destination name with the single character suffix,
+.CW T \(rq. \(lq
+Alternatively, as in the case of the basic outline,
+.XR basic-outline ), (
+this may equally well be specified as
+.QP
+.CW ".pdfbookmark -T T 1 \e\e*[TOC]"
+.
+.NH 3
+.XN Delegation of the Outline Definition
+.LP
+Since the most common use of a document outline
+is to provide a quick method of navigating through a document,
+using active \(lqhypertext\(rq links to chapter and section headings,
+it may be convenient to delegate the responsibility of creating the outline
+to a higher level macro, which is itself used to
+define and format the section headings.
+This approach has been adopted in the
+.CW spdf.tmac
+package, to be described later,
+.XR using-spdf ). (
+.LP
+When such an approach is adopted,
+the user will rarely, if ever, invoke the
+.CW pdfhref
+macro directly, to create a document outline.
+For example, the structure and content of the outline for this document
+has been exclusively defined, using a combination of the
+.CW NH
+macro, from the
+.CW ms
+package, to establish the structure, and the
+.CW XN
+macro from
+.CW spdf.tmac ,
+to define the content.
+In this case,
+the responsibility for invoking the
+.CW pdfhref
+macro, to create the document outline,
+is delegated to the
+.CW XN
+macro.
+.
+.NH 2
+.XN -N pdfhref -- Adding Reference Marks and Links
+.LP
+.pdfhref F SECREF
+.ds SECREF.BEGIN Section
+.pdfhref L -D add-outline
+.pdfhref F
+has shown how the
+.CW pdfhref
+macro may be used to create a PDF document outline.
+While this is undoubtedly a powerful capability,
+it is by no means the only trick in the repertoire of this versatile macro.
+.LP
+The macro name,
+.CW pdfhref ,
+which is a contraction of \(lqPDF HyperText Reference\(rq,
+indicates that the general purpose of this macro is to define
+.EM any
+type of dynamic reference mark, within a PDF document.
+Its generalized usage syntax takes the form
+.QP
+.fam C
+.B .pdfhref
+.BI class > <
+.I "-options ...\&" ] [
+[--]
+.I "descriptive text ...\&" ] [
+.LP
+where
+.CW <\f(CIclass\fP>
+represents a required single character argument,
+which defines the specific reference operation to be performed,
+and may be selected from:\(en
+.QS
+.IP \*[= O]
+Add an entry to the document outline.
+This operation has been described earlier,
+.XR add-outline ). (
+.IP \*[= M]
+Place a \(lqnamed destination\(rq reference mark at the current output position,
+in the current PDF document,
+.XR mark-dest ). (
+.IP \*[= D]
+Specify the content of a PDF document reference dictionary entry;
+typically, such entries are generated automatically,
+by transformation of the intermediate output resulting from the use of
+.CW pdfhref
+.CWB M \& \& \(rq, \(lq
+with the
+.CWB -X \& \& \(rq \(lq
+modifier,
+.XR create-map ); (
+however, it is also possible to specify such entries manually,
+.XR user-format ). (
+.IP \*[= L]
+Insert an active link to a named destination,
+.XR link-named ), (
+at the current output position in the current PDF document,
+such that when the reader clicks on the link text,
+the document view changes to show the location of the named destination.
+.IP \*[= W]
+Insert an active link to a \(lqweb\(rq resource,
+.XR add-weblink ), (
+at the current output position in the current PDF document.
+This is effectively the same as using the
+.CWB L \& \& \(rq \(lq
+operator to establish a link to a named destination in another PDF document,
+.XR link-extern ), (
+except that in this case, the destination is specified by a
+\(lquniform resource identifier\(rq, or
+.CW URI ;
+this may represent any Internet or local resource
+which can be specified in this manner.
+.IP \*[= F]
+Specify a user defined macro, to be called by
+.CW pdfhref ,
+when formatting the text in the active region of a link,
+.XR set-format ). (
+.IP \*[= Z]
+Define the absolute position on the physical PDF output page,
+where the \(lqhot\(hyspot\(rq associated with an active link is to be placed.
+Invoked in pairs, marking the starting and ending PDF page co\(hyordinates
+for each link \(lqhot\(hyspot\(rq, this operator is rarely, if ever,
+specified directly by the user;
+rather, appropriate
+.CW pdfhref
+.CWB Z \& \& \(rq \(lq
+specifications are inserted automatically into the document reference map
+during the PDF document formatting process,
+.XR create-map ). (
+.IP \*[= I]
+Initialize support for
+.CW pdfhref
+features.
+The current
+.CW pdfhref
+implementation provides only one such feature which requires initialization
+\(em a helper macro which must be attached to a user supplied page trap handler,
+in order to support mapping of reference \(lqhot\(hyspots\(rq
+which extend through a page transition;
+.XR page-trap ). (
+.QE
+.
+.NH 3
+.XN -S -- Optional Features of the \F[C]pdfhref\F[] Macro
+.LP
+The behaviour of a number of the
+.CW pdfhref
+macro operations can be modified,
+by including
+.EM "option specifiers" \(rq \(lq
+after the operation specifying argument,
+but
+.EM before
+any other arguments normally associated with the operation.
+In
+.EM all
+cases, an option is specified by an
+.EM "option flag" \(rq, \(lq
+comprising an initial hyphen,
+followed by one or two option identifying characters.
+Additionally,
+.EM some
+options require
+.EM "exactly one"
+option argument;
+for these options, the argument
+.EM must
+be specified, and it
+.EM must
+be separated from the preceding option flag by one or more
+.EM spaces ,
+(tabs
+.EM "must not"
+be used).
+It may be noted that this paradigm for specifying options
+is reminiscent of most
+Unix\(tm
+shells; however, in the case of the
+.CW pdfhref
+macro, omission of the space separating an option flag from its argument is
+.EM never
+permitted.
+.LP
+A list of
+.EM all
+general purpose options supported by the
+.CW pdfhref
+macro is given below.
+Note that not all options are supported for all
+.CW pdfhref
+operations; the operations affected by each option are noted in the list.
+For
+.EM most
+operations, if an unsupported option is specified,
+it will be silently ignored; however, this behaviour should
+not be relied upon.
+.LP
+The general purpose options, supported by the
+.CW pdfhref
+macro, are:\(en
+.QS
+.IP \*[= -N\0 name > <]
+Allows the
+.CWI name > <
+associated with a PDF reference destination
+to be defined independently from the following text,
+which describes the reference.
+This option affects only the
+.CWB M \& \& \(rq \(lq
+operation of the
+.CW pdfhref
+macro,
+.XR mark-dest ). (
+.IP \*[= -E]
+Also used exclusively with the
+.CWB M \& \& \(rq \(lq
+operator, the
+.CWB -E
+option causes any specified
+.CWI descriptive \& \& \~\c
+.CWI text
+arguments,
+.XR mark-dest ), (
+to be copied, or
+.EM echoed ,
+in the body text of the document,
+at the point where the reference mark is defined;
+(without the
+.CWB -E
+option, such
+.CWI descriptive \& \& \~\c
+.CWI text
+will appear
+.EM only
+at points where links to the reference mark are placed,
+and where the standard reference display format,
+.XR set-format ), (
+is used).
+.IP \*[= -D\0 dest > <]
+Specifies the
+.CW URI ,
+or the destination name associated with a PDF active link,
+independently of the following text,
+which describes the link and demarcates the link \(lqhot\(hyspot\(rq.
+This option affects the behaviour of the
+.CW pdfhref
+macro's
+.CWB L \& \& \(rq \(lq
+and
+.CWB W \& \& \(rq \(lq
+operations.
+.IP
+When used with the
+.CWB L \& \& \(rq \(lq
+operator, the
+.CWI dest > <
+argument must specify a PDF \(lqnamed destination\(rq,
+as defined using
+.CW pdfhref
+with the
+.CWB M \& \& \(rq \(lq
+operator.
+.IP
+When used with the
+.CWB W \& \& \(rq \(lq
+operator,
+.CWI dest > <
+must specify a link destination in the form of a
+\(lquniform resource identifier\(rq, or
+.CW URI ,
+.XR add-weblink ). (
+.IP \*[= -F\0 file > <]
+When used with the
+.CWB L \& \& \(rq \(lq
+.CW pdfhref
+operator,
+.CWI file > <
+specifies an external PDF file in which the named destination
+for the link reference is defined.
+This option
+.EM must
+be specified with the
+.CWB L \& \& \(rq \(lq
+operator,
+to create a link to a destination in a different PDF document;
+when the
+.CWB L \& \& \(rq \(lq
+operator is used
+.EM without
+this option, the link destination is assumed to be defined
+within the same document.
+.IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
+Specifies
+.CWI \(dqprefix\(hytext\(dq > <
+to be attached to the
+.EM start
+of the text describing an active PDF document link,
+with no intervening space, but without itself being included in the
+active area of the link \(lqhot\(hyspot\(rq;
+it is effective with the
+.CWB L \& \& \(rq \(lq
+and
+.CWB W \& \& \(rq \(lq
+.CW pdfhref
+operators.
+.IP
+Typically, this option would be used to insert punctuation before
+the link \(lqhot\(hyspot\(rq.
+Thus, there is little reason for the inclusion of spaces in
+.CWI \(dqprefix\(hytext\(dq > < ;
+however, if such space is required, then the enclosing double quotes
+.EM must
+be specified, as indicated.
+.IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
+Specifies
+.CWI \(dqaffixed\(hytext\(dq > <
+to be attached to the
+.EM end
+of the text describing an active PDF document link,
+with no intervening space, but without itself being included in the
+active area of the link \(lqhot\(hyspot\(rq;
+it is effective with the
+.CWB L \& \& \(rq \(lq
+and
+.CWB W \& \& \(rq \(lq
+.CW pdfhref
+operators.
+.IP
+Typically, this option would be used to insert punctuation after
+the link \(lqhot\(hyspot\(rq.
+Thus, there is little reason for the inclusion of spaces in
+.CWI \(dqaffixed\(hytext\(dq > < ;
+however, if such space is required, then the enclosing double quotes
+.EM must
+be specified, as indicated.
+.IP \*[= -T\0 tag > <]
+When specified with the
+.CWB O \& \& \(rq \(lq
+operator,
+.CWI tag > <
+is appended to the \(lqbookmark\(rq name assigned to the generated outline entry.
+This option is
+.EM required ,
+to distinguish between the series of \(lqbookmark\(rq names generated in
+individual passes of the
+.CW groff
+formatter, when the final PDF document is to be assembled
+from a number of separately formatted components;
+.XR multipart-outline ). (
+.IP \*[= -X]
+This
+.CW pdfhref
+option is used with either the
+.CWB M \& \& \(rq \(lq
+operator, or with the
+.CWB L \& \& \(rq \(lq
+operator.
+.IP
+When used with the
+.CWB M \& \& \(rq \(lq
+operator,
+.XR mark-dest ), (
+it ensures that a cross reference record for the marked destination
+will be included in the document reference map,
+.XR export-map ). (
+.IP
+When used with the
+.CWB L \& \& \(rq \(lq
+operator,
+.XR link-named ), (
+it causes the reference to be displayed in the standard cross reference format,
+.XR set-format ), (
+but substituting the
+.CWI descriptive \& \& \~\c
+.CWI text
+specified in the
+.CW pdfhref \& \(lq
+.CW L \(rq
+argument list,
+for the description specified in the document reference map.
+.IP \*[= --]
+Marks the end of the option specifiers.
+This may be used with all
+.CW pdfhref
+operations which accept options, to prevent
+.CW pdfhref
+from interpreting any following arguments as option specifiers,
+even if they would otherwise be interpreted as such.
+It is also useful when the argument list to
+.CW pdfhref
+contains special characters \(em any special character,
+which is not valid in a
+.CW groff
+macro name, will cause a parsing error, if
+.CW pdfhref
+attempts to match it as a possible option flag;
+using the
+.CW -- \(rq \(lq
+flag prevents this, so suppressing the
+.CW groff
+warning message, which would otherwise ensue.
+.IP
+Using this flag after
+.EM all
+sequences of macro options is recommended,
+even when it is not strictly necessary,
+if only for the entirely cosmetic benefit of visually separating
+the main argument list from the sequence of preceding options.
+.QE
+.LP
+In addition to the
+.CW pdfhref
+options listed above, a supplementary set of two character options are defined.
+These supplementary options, listed below, are intended for use with the
+.CWB L \& \& \(rq \(lq
+operator, in conjunction with the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option, to specify alternate file names,
+in formats compatible with the file naming conventions
+of alternate operating systems;
+they will be silently ignored, if used in any other context.
+.LP
+The supported alternate file name options,
+which are ignored if the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option is not specified, are:\(en
+.QS
+.IP \*[= -DF\0 dos\(hyfile > <]
+Specifies the name of the file in which a link destination is defined,
+using the file naming semantics of the
+.CW MS\(hyDOS \*(rg
+operating system.
+When the PDF document is read on a machine
+where the operating system uses the
+.CW MS\(hyDOS \*(rg
+file system, then
+.CWI dos\(hyfile > <
+is used as the name of the file containing the reference destination,
+overriding the
+.CWI file > <
+argument specified with the
+.CWB -F
+option.
+.IP \*[= -MF\0 mac\(hyfile > <]
+Specifies the name of the file in which a link destination is defined,
+using the file naming semantics of the
+.CW Apple \*(rg
+.CW Macintosh \*(rg
+operating system.
+When the PDF document is read on a machine
+where the operating system uses the
+.CW Macintosh \*(rg
+file system, then
+.CWI mac\(hyfile > <
+is used as the name of the file containing the reference destination,
+overriding the
+.CWI file > <
+argument specified with the
+.CWB -F
+option.
+.IP \*[= -UF\0 unix\(hyfile > <]
+Specifies the name of the file in which a link destination is defined,
+using the file naming semantics of the
+.CW Unix \(tm
+operating system.
+When the PDF document is read on a machine
+where the operating system uses
+.CW POSIX
+file naming semantics, then
+.CWI unix\(hyfile > <
+is used as the name of the file containing the reference destination,
+overriding the
+.CWI file > <
+argument specified with the
+.CWB -F
+option.
+.IP \*[= -WF\0 win\(hyfile > <]
+Specifies the name of the file in which a link destination is defined,
+using the file naming semantics of the
+.CW MS\(hyWindows \*(rg
+32\(hybit operating system.
+When the PDF document is read on a machine
+where the operating system uses any of the
+.CW MS\(hyWindows \*(rg
+file systems, with long file name support, then
+.CWI win\(hyfile > <
+is used as the name of the file containing the reference destination,
+overriding the
+.CWI file > <
+argument specified with the
+.CWB -F
+option.
+.QE
+.
+.NH 3
+.XN -N mark-dest -- Marking a Reference Destination
+.LP
+The
+.CW pdfhref
+macro may be used to create active links to any Internet resource,
+specified by its
+.CW URI ,
+or to any \(lqnamed destination\(rq,
+either within the same document, or in another PDF document.
+Although the PDF specification allows link destinations to be defined
+in terms of a page number, and an associated view specification,
+this style of reference is not currently supported by the
+.CW pdfhref
+macro, because it is not possible to adequately bind the specification
+for the destination with the intended reference context.
+.LP
+References to Internet resources are interpreted in accordance with the
+.CW W3C
+standard for defining a
+.CW URI ;
+hence the only prerequisite, for creating a link to any Internet resource,
+is that the
+.CW URI
+be properly specified, when declaring the reference;
+.XR add-weblink ). (
+In the case of references to \(lqnamed destinations\(rq in PDF documents,
+however, it is necessary to provide a mechanism for creating such
+\(lqnamed destinations\(rq.
+This may be accomplished, by invoking the
+.CW pdfhref
+macro in the form
+.QP
+.fam C
+.B ".pdfhref M"
+.B -N \& [
+.I name >] <
+.B -X ] [
+.B -E ] [
+.I "descriptive text ...\&" ] [
+.LP
+This creates a \(lqnamed destination\(rq reference mark, with its name specified by
+.CWI name > < ,
+or, if the
+.CWB -N
+option is not specified, by the first word of
+.CWI descriptive \& \& \~\c
+.CWI text \& \& ;
+(note that this imposes the restriction that,
+if the
+.CWB -N
+option is omitted, then
+.EM "at least"
+one word of
+.CWI descriptive \& \& \~\c
+.CWI text
+.EM must
+be specified).
+Additionally, a reference view will be automatically defined,
+and associated with the reference mark,
+.XR pdfhref-view ), (
+.\" and, if any
+.\" .CWI descriptive
+.\" .CWI text
+.\" is specified, or the
+and, if the
+.CWB -X
+option is specified, and no document cross reference map has been imported,
+.XR import-map ), (
+then a cross reference mapping record,
+.XR export-map ), (
+will be written to the
+.CW stdout
+stream;
+this may be captured, and subsequently used to generate a cross reference map
+for the document,
+.XR create-map ). (
+.LP
+When a \(lqnamed destination\(rq reference mark is created, using the
+.CW pdfhref
+macro's
+.CWB M \& \& \(rq \(lq
+operator, there is normally no visible effect in the formatted document; any
+.CWI descriptive \& \& \~\c
+.CWI text
+which is specified will simply be stored in the cross reference map,
+for use when a link to the reference mark is created.
+This default behaviour may be changed, by specifying the
+.CWB -E
+option, which causes any specified
+.CWI descriptive \& \& \~\c
+.CWI text
+to be \(lqechoed\(rq in the document text,
+at the point where the reference mark is placed,
+in addition to its inclusion in the cross reference map.
+.
+.NH 4
+.XN -N export-map -- Mapping a Destination for Cross Referencing
+.LP
+Effective cross referencing of
+.EM any
+document formatted by
+.CW groff
+requires multiple pass formatting.
+Details of how this multiple pass formatting may be accomplished,
+when working with the
+.CW pdfmark
+macros, will be discussed later,
+.XR do-xref ); (
+at this stage, the discussion will be restricted to the initial preparation,
+which is required at the time when the cross reference destinations are defined.
+.LP
+The first stage, in the process of cross referencing a document,
+is the generation of a cross reference map.
+Again, the details of
+.EM how
+the cross reference map is generated will be discussed in
+.pdfhref F SECREF L -D do-xref -A ;
+.pdfhref F
+however, it is important to recognize that
+.EM what
+content is included in the cross reference map is established
+when the reference destination is defined \(em it is derived
+from the reference data exported on the
+.CW stderr
+stream by the
+.CW pdfhref
+macro, when it is invoked with the
+.CWB M \& \& \(rq \(lq
+operator, and is controlled by whatever definition of the string
+.CW PDFHREF.INFO
+is in effect, when the
+.CW pdfhref
+macro is invoked.
+.LP
+The initial default setting of
+.CW PDFHREF.INFO
+is
+.QP
+.CW ".ds PDFHREF.INFO page \e\en% \e\e$*"
+.LP
+which ensures that the cross reference map will contain
+at least a page number reference, supplemented by any
+.CWI descriptive \& \& \~\c
+.CWI text
+which is specified for the reference mark, as defined by the
+.CW pdfhref
+macro, with its
+.CWB M \& \& \(rq \(lq
+operator; this may be redefined by the user,
+to export additional cross reference information,
+or to modify the default format for cross reference links,
+.XR set-format ). (
+.
+.NH 4
+.XN -N pdfhref-view -- Associating a Document View with a Reference Mark
+.LP
+In the same manner as each document outline reference, defined by the
+.CW pdfhref
+macro with the
+.CWB O \& \& \(rq \(lq
+operator,
+.XR add-outline ), (
+has a specific document view associated with it,
+each reference destination marked by
+.CW pdfhref
+with the
+.CWB M \& \& \(rq \(lq
+operator, requires an associated document view specification.
+.LP
+The mechanism whereby a document view is associated with a reference mark
+is entirely analogous to that employed for outline references,
+.XR outline-view ), (
+except that the
+.CW PDFHREF.VIEW
+string specification is used, in place of the
+.CW PDFBOOKMARK.VIEW
+specification.
+Thus, the reference view is defined in terms of:\(en
+.QS
+.IP \*[= PDFHREF.VIEW]
+A string,
+establishing the position of the reference mark within the viewing window,
+and the magnification at which the document will be viewed,
+at the location of the marked reference destination;
+by default, it is defined by
+.RS
+.QP
+.CW ".ds PDFHREF.VIEW /FitH \e\en[PDFPAGE.Y] u"
+.RE
+.IP
+which displays the reference destination at the top of the viewing window,
+with the magnification set to fit the page width to the width of the window.
+.IP \*[= PDFHREF.VIEW.LEADING]
+A numeric register,
+specifying additional spacing, to be placed between the top of the display
+window and the actual position at which the location of the reference
+destination appears within the window.
+This register is shared with the view specification for outline references,
+and thus has the same default initial setting,
+.RS
+.QP
+.CW ".nr PDFHREF.VIEW.LEADING 5.0p"
+.RE
+.IP
+as in the case of outline reference views.
+.IP
+Again, notice that
+.CW PDFHREF.VIEW.LEADING
+does not represent true typographic \(lqleading\(rq,
+since any preceding text, set in the specified display space,
+will be visible at the top of the viewing window,
+when the reference is selected.
+.QE
+.LP
+Just as the view associated with outline references may be changed,
+by redefining
+.CW PDFBOOKMARK.VIEW ,
+so the view associated with marked reference destinations may be changed,
+by redefining
+.CW PDFHREF.VIEW ,
+and, if desired,
+.CW PDFHREF.VIEW.LEADING ;
+such changes will become effective for all reference destinations marked
+.EM after
+these definitions are changed.
+(Notice that, since the specification of
+.CW PDFHREF.VIEW.LEADING
+is shared by both outline reference views and marked reference views,
+if it is changed, then the views for
+.EM both
+reference types are changed accordingly).
+.LP
+It may again be noted, that the
+.CW PDFPAGE.Y
+register is used in the definition of
+.CW PDFHREF.VIEW ,
+just as it is in the definition of
+.CW PDFBOOKMARK.VIEW ;
+all comments in
+.pdfhref F SECREF L -D outline-view
+.pdfhref F
+relating to its use, and indeed to page position computations in general,
+apply equally to marked reference views and to outline reference views.
+.
+.NH 3
+.XN -N link-named -- Linking to a Marked Reference Destination
+.LP
+Any named destination, such as those marked by the
+.CW pdfhref
+macro, using it's
+.CWB M \& \& \(rq \(lq
+operator, may be referred to from any point in
+.EM any
+PDF document, using an
+.EM "active link" ;
+such active links are created by again using the
+.CW pdfhref
+macro, but in this case, with the
+.CWB L \& \& \(rq \(lq
+operator.
+This operator provides support for two distinct cases,
+depending on whether the reference destination is defined in 
+the same document as the link,
+.XR link-intern ), (
+or is defined as a named destination in a different PDF document,
+.XR link-extern ). (
+.
+.NH 4
+.XN -N link-intern -- References within a Single PDF Document
+.LP
+The general syntactic form for invoking the
+.CW pdfhref
+macro,
+when creating a link to a named destination within the same PDF document is
+.QP
+.fam C
+.B .pdfhref
+.B L
+.B -D \& [
+.BI dest-name >] <
+.B -P \& [
+.BI prefix-text >] <
+.B -A \& [
+.BI affixed-text >] <
+\e
+.br
+\0\0\0
+.B -X ] [
+.B -- ] [
+.I "descriptive text ...\&" ] [
+.LP
+where
+.CWI dest-name > <
+specifies the name of the link destination,
+as specified using the
+.CW pdfhref
+.CWB M \& \& \(rq \(lq
+operation; (it may be defined either earlier in the document,
+to create a backward reference, or later, to create a forward reference).
+.\"
+.\" Here's a example of how to add an iconic annotation.
+.\"
+.\".pdfnote -T "Internal Cross References" \
+.\"   This description is rather terse, and could benefit from \
+.\"   the inclusion of an example.
+.LP
+If any
+.CWI descriptive \& \& \~\c
+.CWI text
+arguments are specified, then they will be inserted into the
+.CW groff
+output stream, to define the text appearing in the \(lqhot\(hyspot\(rq
+region of the link;
+this will be printed in the link colour specified by the string,
+.CW PDFHREF.TEXT.COLOUR ,
+which is described in
+.XR-NO-PREFIX set-colour .
+If the
+.CWB -X
+option is also specified, then the
+.CWI descriptive \& \& \~\c
+.CWI text
+will be augmented, by prefacing it with page and section number indicators,
+in accordance with the reference formatting rules which are in effect,
+.XR set-format ); (
+such indicators will be included within the active link region,
+and will also be printed in the link colour.
+.LP
+Note that
+.EM either
+the
+.CWB -D \& \& \~\c
+.CWBI dest\(hyname > <
+option,
+.EM or
+the
+.CWI descriptive \& \& \~\c
+.CWI text
+arguments,
+.EM "but not both" ,
+may be omitted.
+If the
+.CWB -D \& \& \~\c
+.CWBI dest\(hyname > <
+option is omitted, then the first word of
+.CWI descriptive \& \& \~\c
+.CWI text \& \& ,
+i.e.\~all text up to but not including the first space,
+will be interpreted as the
+.CWBI dest\(hyname > <
+for the link; this text will also appear in the running text of the document,
+within the active region of the link.
+Alternatively, if the
+.CWB -D \& \& \~\c
+.CWBI dest\(hyname > <
+option
+.EM is
+specified, and
+.CWI descriptive \& \& \~\c
+.CWI text
+is not,
+then the running text which defines the reference,
+and its active region,
+will be derived from the reference description which is specified
+when the named destination is marked,
+.XR mark-dest ), (
+and will be formatted according to the reference formatting rules
+which are in effect, when the reference is placed,
+.XR set-format ); (
+in this case, it is not necessary to specify the
+.CWB -X
+option to activate automatic formatting of the reference \(em it is implied,
+by the omission of all
+.CWI descriptive \& \& \~\c
+.CWI text
+arguments.
+.LP
+The
+.CWB -P \& \& \~\c
+.CWBI prefix\(hytext > <
+and
+.CWB -A \& \& \~\c
+.CWBI affixed\(hytext > <
+options may be used to specify additional text
+which will be placed before and after the linked text respectively,
+with no intervening space.
+Such prefixed and affixed text will be printed in the normal text colour,
+and will not be included within the active region of the link.
+This feature is mostly useful for creating parenthetical references,
+or for placing punctuation adjacent to,
+but not included within,
+the text which defines the active region of the link.
+.LP
+The operation of the
+.CW pdfhref
+macro, when used with its
+.CWB L \& \& \(rq \(lq
+operator to place a link to a named PDF destination,
+may best be illustrated by an example.
+However, since the appearance of the link will be influenced by
+factors established when the named destination is marked,
+.XR mark-dest ), (
+and also by the formatting rules in effect when the link is placed,
+the presentation of a suitable example will be deferred,
+until the formatting mechanism has been explained,
+.XR set-format ). (
+.
+.NH 4
+.XN -N link-extern -- References to Destinations in Other PDF Documents
+.LP
+The
+.CW pdfhref
+macro's
+.CWB L \& \& \(rq \(lq
+operator is not restricted to creating reference links
+within a single PDF document.
+When the link destination is defined in a different document,
+then the syntactic form for invoking
+.CW pdfhref
+is modified, by the addition of options to specify the
+name and location of the PDF file in which the destination is defined.
+Thus, the extended
+.CW pdfhref
+syntactic form becomes
+.QP
+.fam C
+.B .pdfhref
+.B L
+.B -F
+.BI file > <
+.B -D \& [
+.BI dest-name >] <
+\e
+.br
+\0\0\0
+.B -DF \& [
+.BI dos-file >] <
+.B -MF \& [
+.BI mac-file >] <
+.B -UF \& [
+.BI unix-file >] <
+\e
+.br
+\0\0\0
+.B -WF \& [
+.BI win-file >] <
+.B -P \& [
+.BI prefix-text >] <
+.B -A \& [
+.BI affixed-text >] <
+\e
+.br
+\0\0\0
+.B -X ] [
+.B -- ] [
+.I "descriptive text ...\&" ] [
+.LP
+where the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option serves
+.EM two
+purposes: it both indicates to the
+.CW pdfhref
+macro that the specified reference destination
+is defined in an external PDF file,
+and it also specifies the normal path name,
+which is to be used to locate this file,
+when a user selects the reference.
+.LP
+In addition to the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option, which
+.EM must
+be specified when referring to a destination in an external PDF file,
+the
+.CWB -DF \& \& \~\c
+.CWBI dos\(hyfile > < ,
+.CWB -MF \& \& \~\c
+.CWBI mac\(hyfile > < ,
+.CWB -UF \& \& \~\c
+.CWBI unix\(hyfile > <
+and
+.CWB -WF \& \& \~\c
+.CWBI win\(hyfile > <
+options may be used to specify the location of the file
+containing the reference destination,
+in a variety of operating system dependent formats.
+These options assign their arguments to the
+.CW /DosFile ,
+.CW /MacFile ,
+.CW /UnixFile
+and
+.CW /WinFile
+keys of the generated
+.CW pdfmark
+respectively; thus when any of these options are specified,
+.EM "in addition to"
+the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option, and the document is read on the appropriate operating systems,
+then the path names specified by
+.CWBI dos\(hyfile > < ,
+.CWBI mac\(hyfile > < ,
+.CWBI unix\(hyfile > <
+and
+.CWBI win\(hyfile > <
+will be searched,
+.EM instead
+of the path name specified by
+.CWBI file > < ,
+for each of the
+.CW MS\(hyDOS \*(rg,
+.CW Apple \*(rg
+.CW Macintosh \*(rg,
+.CW Unix \(tm
+and
+.CW MS\(hyWindows \*(rg
+operating systems, respectively; see the
+.pdfmark-manual ,
+for further details.
+.LP
+Other than the use of these additional options,
+which specify that the reference destination is in an external PDF file,
+the behaviour of the
+.CW pdfhref
+.CWB L \& \& \(rq \(lq
+operator, with the
+.CWB -F \& \& \~\c
+.CWBI file > <
+option, remains identical to its behaviour
+.EM without
+this option,
+.XR link-intern ), (
+with respect to the interpretation of other options,
+the handling of the
+.CWI descriptive \& \& \~\c
+.CWI text
+arguments, and the formatting of the displayed reference.
+.LP
+Once again, since the appearance of the reference is determined by
+factors specified in the document reference map,
+and also by the formatting rules in effect when the reference is placed,
+the presentation of an example of the placing of
+a reference to an external destination will be deferred,
+until the formatting mechanism has been explained,
+.XR set-format ). (
+.
+.NH 3
+.XN -N add-weblink -- Linking to Internet Resources
+.LP
+In addition to supporting the creation of cross references
+to named destinations in PDF documents, the
+.CW pdfhref
+macro also has the capability to create active links to Internet resources,
+or indeed to
+.EM any
+resource which may be specified by a Uniform Resource Identifier,
+(which is usually abbreviated to the acronym \(lqURI\(rq,
+and sometimes also referred to as a Uniform Resource Locator,
+or \(lqURL\(rq).
+.LP
+Since the mechanism for creating a link to a URI differs somewhat
+from that for creating PDF references, the
+.CW pdfhref
+macro is invoked with the
+.CWB W \& \& \(rq \(lq
+(for \(lqweb\(hylink\(rq) operator, rather than the
+.CWB L \& \& \(rq \(lq
+operator; nevertheless, the invocation syntax is similar, having the form
+.QP
+.fam C
+.B .pdfhref
+.B W
+.B -D \& [
+.BI URI >] <
+.B -P \& [
+.BI prefix-text >] <
+.B -A \& [
+.BI affixed-text >] <
+\e
+.br
+\0\0\0
+.B -- ] [
+.I "descriptive text ...\&"
+.LP
+where the optional
+.CWB -D
+.CWBI URI > <
+modifier specifies the address for the target Internet resource,
+in any appropriate
+.EM "Uniform Resource Identifier"
+format, while the
+.CWI descriptive
+.CWI text
+argument specifies the text which is to appear in the \(lqhot\(hyspot\(rq
+region, and the
+.CWB -P
+.CWBI prefix\(hytext > <
+and
+.CWB -A
+.CWBI affixed\(hytext > <
+options have the same effect as in the case of local document links,
+.XR link-intern ). (
+.LP
+Notice that it is not mandatory to include the
+.CWB -D
+.CWBI URI > <
+in the link specification; if it
+.EM is
+specified, then it is not necessary for the URI to appear,
+in the running text of the document \(em the
+.CWI descriptive
+.CWI text
+argument exactly defines the text
+which will appear within the \(lqhot\(hyspot\(rq region,
+and this need not include the URI.
+However, if the
+.CWB -D \& \& \~\c
+.CWBI URI > <
+specification is omitted, then the
+.CWI descriptive
+.CWI text
+argument
+.EM must
+be an
+.EM exact
+representation of the URI, which
+.EM will ,
+therefore, appear as the entire content of the \(lqhot\(hyspot\(rq.
+For example, we could introduce a reference to
+.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
+in which the actual URI is concealed, by using mark up such as:\(en
+.DS I
+.CW
+For example, we could introduce a reference to
+\&.pdfhref W -D \*[GROFF-WEBSITE] -A , the groff web site
+in which the actual URI is concealed,
+.DE
+Alternatively,
+to refer the reader to the groff web site,
+making it obvious that the appropriate URI is
+.pdfhref W -A , \*[GROFF-WEBSITE]
+the requisite mark up might be:\(en
+.DS I
+.CW
+to refer the reader to the groff web site,
+making it obvious that the appropriate URI is
+\&.pdfhref W -A , \*[GROFF-WEBSITE]
+the requisite mark up might be:\e(en
+.DE
+.
+.NH 3
+.XN -N set-format -- Establishing a Format for References
+.LP
+There are two principal aspects to be addressed,
+when defining the format to be used when displaying references.
+Firstly, it is desirable to provide a visual cue,
+to indicate that the text describing the reference is imbued
+with special properties \(em it is dynamically linked to the reference
+destination \(em and secondly, the textual content should
+describe where the link leads, and ideally,
+it should also describe the content of the reference destination.
+.LP
+The visual cue,
+that a text region defines a dynamically linked reference,
+is most commonly provided by printing the text within the active
+region in a distinctive colour.
+This technique will be employed automatically by the
+.CW pdfhref
+macro \(em
+.XR set-colour
+\(em unless the user specifically chooses to adopt, and implement,
+some alternative strategy.
+.
+.NH 4
+.XN -N set-colour -- Using Colour to Demarcate Link Regions
+.LP
+Typically, when a PDF document contains
+.EM active
+references to other locations, either within the same document,
+or even in other documents, or on the World Wide Web,
+it is usually desirable to make the regions
+where these active links are placed stand out from the surrounding text.
+.
+.NH 4
+.XN -N user-format -- Specifying Reference Text Explicitly
+.
+.NH 4
+.XN -N auto-format -- Using Automatically Formatted Reference Text
+.
+.NH 4
+.XN -N custom-format -- Customizing Automatically Formatted Reference Text
+.LP
+It is incumbent on the user,
+if employing automatic formatting of the displayed reference,
+.XR set-format ), (
+to ensure that an appropriate reference definition
+is created for the reference destination,
+and is included in the reference map for the document
+in which the reference will appear;
+thus, it may be easiest to
+.EM always
+use manual formatting for external references.
+.
+.NH 3
+.XN Problematic Links
+.LP
+Irrespective of whether a
+.CW pdfhref
+reference is placed using the
+.CWB L \& \& \(rq \(lq
+operator, or the
+.CWB W \& \& \(rq \(lq
+operator, there may be occasions when the resulting link
+does function as expected.
+A number of scenarios, which are known to be troublesome,
+are described below.
+.
+.NH 4
+.XN -N page-trap -- Links with a Page Transition in the Active Region
+.LP
+When a link is placed near the bottom of a page,
+it is possible that its active region, or \(lqhot\(hyspot\(rq,
+may extend on to the next page.
+In this situation, a page trap macro is required
+to intercept the page transition, and to restart the mapping of
+the \(lqhot\(hyspot\(rq boundary on the new page.
+.LP
+The
+.CW pdfmark
+macro package includes a suitable page trap macro, to satisfy this requirement.
+However, to avoid pre\(hyempting any other requirement the user may have for
+a page transition trap, this is
+.EM not
+installed as an active page trap,
+unless explicitly requested by the user.
+.LP
+To enable proper handling of page transitions,
+which occur within the active regions of reference links,
+the user should:\(en
+.QS
+.nr ITEM 0 1
+.IP \n+[ITEM].
+Define a page transition macro, to provide whatever features may be required,
+when a page transition occurs \(em e.g.\& printing footnotes,
+adding page footers and headers, etc.
+This macro should end by setting the output position at the correct
+vertical page offset, where the printing of running text is to restart,
+following the page transition.
+.IP \n+[ITEM].
+Plant a trap to invoke this macro, at the appropriate vertical position
+marking the end of normal running text on each page.
+.KS
+.IP \n+[ITEM].
+Initialize the
+.CW pdfhref
+hook into this page transition trap, by invoking
+.RS
+.IP
+.fam C
+.B "pdfhref I -PT"
+.BI macro-name > <
+.LP
+where
+.CWBI macro-name > <
+is the name of the user supplied page trap macro,
+to ensure that
+.CW pdfhref
+will correctly restart mapping of active link regions,
+at the start of each new page.
+.KE
+.RE
+.QE
+.LP
+It may be observed that this initialization of the
+.CW pdfhref
+page transition hook is, typically, required only once
+.EM before
+document formatting begins.
+Users of document formatting macro packages may reasonably expect that
+this initialization should be performed by the macro package itself.
+Thus, writers of such macro packages which include
+.CW pdfmark
+bindings, should provide appropriate initialization,
+so relieving the end user of this responsibility.
+The following example, abstracted from the sample
+.CW ms
+binding package,
+.CW spdf.tmac ,
+illustrates how this may be accomplished:\(en
+.DS I
+.CW
+\&.\e" groff "ms" provides the "pg@bottom" macro, which has already
+\&.\e" been installed as a page transition trap.  To ensure proper
+\&.\e" mapping of "pdfhref" links which overflow the bottom of any
+\&.\e" page, we need to install the "pdfhref" page transition hook,
+\&.\e" as an addendum to this macro.
+\&.
+\&.pdfhref I -PT pg@bottom
+.DE
+.
+.NH 2
+.XN -N add-note -- Annotating a PDF Document using Pop-Up Notes
+.
+.NH 2
+.XN -S -N pdfsync -- Synchronizing Output and \F[C]pdfmark\F[] Contexts
+.LP
+It has been noted previously, that the
+.CW pdfview
+macro,
+.XR docview ), (
+the
+.CW pdfinfo
+macro,
+.XR docinfo ), (
+and the
+.CW pdfhref
+macro, when used to create a document outline,
+.XR add-outline ), (
+do not immediately write their
+.CW pdfmark
+output to the \*[PostScript] data stream;
+instead, they cache their output, in a
+.CW groff
+diversion, in the case of the
+.CW pdfview
+and
+.CW pdfinfo
+macros, or in an ordered collection of strings and numeric registers,
+in the case of the document outline,
+until a more appropriate time for copying it out.
+In the case of
+.CW pdfview
+and
+.CW pdfinfo
+\(lqmeta\(hydata\(rq,
+this \(lqmore appropriate time\(rq is explicitly chosen by the user;
+in the case of document outline data,
+.EM some
+cached data may be implicitly written out as the document outline is compiled,
+but there will
+.EM always
+be some remaining data, which must be explicitly flushed out, before the
+.CW groff
+formatting process is allowed to complete.
+.LP
+To allow the user to choose when cached
+.CW pdfmark
+data is to be flushed to the output stream, the
+.CW pdfmark
+macro package provides the
+.CW pdfsync
+macro, (to synchronize the cache and output states).
+In its simplest form, it is invoked without arguments, i.e.
+.QP
+.fam C
+.B .pdfsync
+.LP
+This form of invocation ensures that
+.EM both
+the \(lqmeta\(hydata cache\(rq, containing
+.CW pdfview
+and
+.CW pdfinfo
+data,
+.EM and 
+the \(lqoutline cache\(rq,
+containing any previously uncommitted document outline data,
+are flushed; ideally, this should be included in a
+.CW groff
+\(lqend macro\(rq, to ensure that
+.EM both
+caches are flushed, before
+.CW groff
+terminates.
+.LP
+Occasionally,
+it may be desirable to flush either the \(lqmeta\(hydata cache\(rq,
+without affecting the \(lqoutline cache\(rq, or vice\(hyversa,
+at a user specified time, prior to reaching the end of the document.
+This may be accomplished, by invoking the
+.CW pdfsync
+macro with an argument, i.e.
+.QP
+.fam C
+.B ".pdfsync M"
+.LP
+to flush only the \(lqmeta\(hydata cache\(rq, or
+.QP
+.fam C
+.B ".pdfsync O"
+.LP
+to flush only the \(lqoutline cache\(rq.
+.LP
+The \(lqmeta\(hydata cache\(rq can normally be safely flushed
+in this manner, at any time
+.EM after
+output of the first page has started;
+(it may cause formatting problems,
+most notably the appearance of unwanted white space, if flushed earlier,
+or indeed, if flushed immediately after a page transition,
+but before the output of the content on the new page has commenced).
+Caution is required, however, when explicitly flushing the
+\(lqoutline cache\(rq, since if the outline is to be
+subsequently extended, then the first outline entry after flushing
+.EM must
+be specified at level 1.
+Nevertheless, such explicit flushing may occasionally be necessary;
+for example, the
+.CW TC
+macro in the
+.CW spdf.tmac
+package,
+.XR using-spdf ), (
+invokes
+.CW ".pdfsync\ O" \(rq \(lq
+to ensure that the outline for the \(lqbody\(rq section of the document
+is terminated,
+.EM before
+it commences the formatting of the table of contents section.
+.bp
+.
+.NH 1
+.XN -N pdf-layout -- PDF Document Layout
+.LP
+The
+.CW pdfmark
+macros described in the preceding section,
+.XR pdf-features ), (
+provide no inherent document formatting capability of their own.
+However,
+they may be used in conjunction with any other
+.CW groff
+macro package of the user's choice,
+to add such capability.
+.LP
+In preparing this document, the standard
+.CW ms
+macro package, supplied as a component of the GNU Troff distribution,
+has been employed.
+To facilitate the use of the
+.CW pdfmark
+macros with the
+.CW ms
+macros,
+a binding macro package,
+.CW spdf.tmac ,
+has been created.
+The use of this binding macro package is described in the following section,
+.XR using-spdf ); (
+it may also serve as an example to users of other standard
+.CW groff
+macro packages,
+as to how the
+.CW pdfmark
+macros may be employed with their chosen primary macro package.
+.
+.NH 2
+.XN -S -N using-spdf -- Using \F[C]pdfmark\F[] Macros with the \F[C]ms\F[] Macro Package
+.LP
+The use of the binding macro package,
+.CW spdf.tmac ,
+allows for the use of the
+.CW pdfmark
+macros in conjunction with the
+.CW ms
+macros,
+simply by issuing a
+.CW groff
+command of the form\**
+.FS
+Once again,
+.pdfhref L -D pdf-features-fn -- as noted in footnote\*{\n[pdf-features-fn]\*}
+to
+.XR-NO-PREFIX pdf-features ,
+do not specify any
+.CW -T \^\c
+.CWI dev
+option,
+other than
+.CW -T \^\c
+.CW ps ,
+or
+.CW -T \^\c
+.CW pdf ;
+specify
+.CW -T \^\c
+.CW pdf ,
+if you wish to avoid the conversion of \*[PostScript] output to PDF,
+which will be required if you specify
+.CW -T \^\c
+.CW ps ,
+or if you omit the
+.CW -T \^\c
+.CWI dev
+option entirely.
+.FE
+.QP
+.fam C
+groff [-Tps\h'0.2p'|\h'0.2p'-Tpdf] [-m\F[]\|\|\FC\c
+.B spdf
+.I options \F[]\|\|\FC\c [-
+.I file \F[]\|\|\FC\c "...] "
+\&...
+.LP
+When using the
+.CW spdf.tmac
+package, the
+.CW groff
+input files may be marked up using any of the standard
+.CW ms
+macros to specify document formatting,
+while PDF features may be added,
+using any of the
+.CW pdfmark
+macros described previously,
+.XR pdf-features ). (
+Additionally,
+.CW spdf.tmac
+defines a number of convenient extensions to the
+.CW ms
+macro set, to better accomodate the use of PDF features within the
+.CW ms
+formatting framework,
+and to address a number of
+.CW ms
+document layout issues,
+which require special handling when producing PDF documents.
+These additional macros,
+and the issues they are intended to address,
+are described below.
+.
+.NH 3
+.XN -S -- \F[C]ms\F[] Section Headings in PDF Documents
+.LP
+Traditionally,
+.CW ms
+provides the
+.CW NH
+and
+.CW SH
+macros, to specify section headings.
+However,
+there is no standard mechanism for generating a
+table of contents entry based on the text of the section heading;
+neither is there any recognized standard method for establishing a
+cross reference link to the section.
+.LP
+To address this
+.CW ms
+limitation,
+.CW spdf.tmac
+defines the
+.CW XN
+macro,
+.XR xn-macro ), (
+to be used in conjunction with the
+.CW NH
+macro.
+.
+.NH 4
+.XN -S -N xn-macro -- The \F[C]XN\F[] Macro
+.bp
+.
+.NH 1
+.XN The PDF Publishing Process
+.
+.NH 2
+.XN -N do-xref -- Resolving Cross References
+.
+.NH 3
+.XN -N create-map -- Creating a Document Reference Map
+.
+.NH 3
+.XN -N import-map -- Deploying a Document Reference Map
+.TC
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+.\" vim: filetype=groff: