2532 lines
72 KiB
Plaintext
2532 lines
72 KiB
Plaintext
.\" vim: ft=groff
|
|
.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.
|
|
.\" Currently, there are two available addresses; a copy is maintained at ...
|
|
.\"
|
|
.ds GROFF-WEBSITE http://www.gnu.org/software/groff
|
|
.\"
|
|
.\" ... but the official home site is at ...
|
|
.\"
|
|
.ds GROFF-WEBSITE http://groff.ffii.org
|
|
.\"
|
|
.\" 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
|
|
.\"
|
|
.\" Initialise 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\*}
|
|
.\"
|
|
.\" Establish the page layout.
|
|
.\"
|
|
.nr PO 2.5c
|
|
.nr LL 17.0c
|
|
.nr LT 17.0c
|
|
.nr HY 0
|
|
.nr FF 3
|
|
.nr DI 5n
|
|
.\"
|
|
.\" 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
|
|
.\"
|
|
.de EM
|
|
.\".I "\s'+0.3'\\$1\s0" "\\$2" "\\$3"
|
|
.I \\$@
|
|
..
|
|
.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
|
|
..
|
|
.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
|
|
.\"
|
|
.NH 1
|
|
.\" When we use numbered section headings, we might like to automatically
|
|
.\" insert a table of contents entry, using the text of the heading itself.
|
|
.\" The "ms" macros don't provide any standard mechanism for doing this,
|
|
.\" but "spdf.tmac" adds the "XN" macro, which will do it for us.
|
|
.\"
|
|
.\" Here's a simple example of how we might use it. In this case, the word
|
|
.\" "Introduction" will appear both in the body of the document, as the text
|
|
.\" of the heading, and it will be added to the table of contents, which is
|
|
.\" subsequently "printed" using the "TC" macro; in both locations, it will
|
|
.\" be prefixed by the section number.
|
|
.\"
|
|
.\" As an additional side effect, any use of "XN" will cause the table of
|
|
.\" contents entry to be automatically reproduced, with the exception of its
|
|
.\" page number reference, as a PDF document outline entry. Thus, the use
|
|
.\" of "XN" to specify numbered section headings results in the automatic
|
|
.\" creation of a numbered PDF document outline. This automatic creation
|
|
.\" of the outline is completely transparent, and will occur regardless
|
|
.\" of whether the "TC" macro is subsequently invoked, or not.
|
|
.\"
|
|
.XN Introduction
|
|
.\"
|
|
.\" If using an old s.tmac, without the SN-NO-DOT extension,
|
|
.\" make sure we get SOMETHING in section number references.
|
|
.\"
|
|
.if !dSN-NO-DOT .als SN-NO-DOT SN
|
|
.LP
|
|
It might appear that it is a fairly simple matter to
|
|
produce documents in Adobe\*(rg\~\(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\*(rg\~PostScript\*(rg format,
|
|
which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
|
|
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\*(rg version of the document,
|
|
which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
|
|
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\*(rg 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\*(rg
|
|
.\"
|
|
.de 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 http://partners.adobe.com/asn/acrobat/docs/pdfmark.pdf \
|
|
-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\*(rg rendering of the document.
|
|
This, of course, implies that the original document source, which
|
|
.CW groff
|
|
will process to generate the PostScript\*(rg 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 utilised 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\*(rg\~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\*(rg\~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\*(rg\~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\*(rg Windows\(tm2000 operating platforms, using
|
|
.CW groff
|
|
.CW 1.19.1 ,\c
|
|
.pdfhref L -D footnote1 -- \**
|
|
.FS
|
|
.pdfhref M footnote1
|
|
Later versions should, and some earlier versions may, be equally suitable.
|
|
See
|
|
.pdfhref W \*[GROFF-WEBSITE]
|
|
for information and availability of the latest version.
|
|
.FE
|
|
in association with
|
|
.CW AFPL
|
|
.CW GhostScript
|
|
.CW 8.14 .\c
|
|
.pdfhref L -D footnote2 -- \**
|
|
.FS
|
|
.pdfhref M footnote2
|
|
Again, other versions may be suitable.
|
|
See
|
|
.pdfhref W http://ghostscript.com
|
|
for information and availability.
|
|
.FE
|
|
Other tools employed, which should be readily available on
|
|
.EM any
|
|
.SM
|
|
UNIX\(tm
|
|
.LG
|
|
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\*(rg Windows\(tm platform,
|
|
but several third party implementations are available.
|
|
Some worth considering include the MKS\*(rg\~Toolkit,\**
|
|
.FS
|
|
A commercial offering; see
|
|
.pdfhref W http://mkssoftware.com/products/tk/default.asp
|
|
for information.
|
|
.FE
|
|
Cygwin,\**
|
|
.FS
|
|
A
|
|
.EM free
|
|
but comprehensive
|
|
.SM
|
|
POSIX
|
|
.LG
|
|
emulation environment and
|
|
.SM
|
|
UNIX\(tm
|
|
.LG
|
|
toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
|
|
.pdfhref W http://cygwin.com
|
|
for information and download.
|
|
.FE
|
|
or MSYS.\**
|
|
.FS
|
|
Another free, but minimal suite of common
|
|
.SM
|
|
UNIX\(tm
|
|
.LG
|
|
tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
|
|
.pdfhref W -A ; http://www.mingw.org
|
|
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
|
|
.QP
|
|
.fam C
|
|
groff -Tps [-m
|
|
.I name "] -m"
|
|
.B pdfmark
|
|
.I options \& [-
|
|
.I "file ..." \& "...] "
|
|
.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 -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\*(rg
|
|
.pdfmark-manual ,
|
|
into
|
|
.CW groff 's
|
|
PostScript\*(rg 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\*(rg 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\*(rg\~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\*(rg\~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\*(rg 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\*(rg 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\*(rg Acrobat\*(rg 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 generalised 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\*(rg 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 synchronise 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 generalised 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\*(rg
|
|
.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\*(rg 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
|
|
.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\*(rg 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" Initialise 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\*(rg 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\*(rg 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\*(rg 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 generalised 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]
|
|
Initialise support for
|
|
.CW pdfhref
|
|
features.
|
|
The current
|
|
.CW pdfhref
|
|
implementation provides only one such feature which requires initialisation
|
|
\(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 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
|
|
.SM
|
|
UNIX\(tm
|
|
.LG
|
|
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 legal 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 recognise 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 exanple 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 -- Customising 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].
|
|
Initialise 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 initialisation 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 initialisation should be performed by the macro package itself.
|
|
Thus, writers of such macro packages which include
|
|
.CW pdfmark
|
|
bindings, should provide appropriate initialisation,
|
|
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 -N pdfsync -- Synchronising 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\*(rg 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 synchronise 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 explict 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 -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
|
|
.QP
|
|
.fam C
|
|
groff -Tps
|
|
.B -mspdf
|
|
.I "-options ...\&" ] [
|
|
file(s) ...
|
|
.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 \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 recognised 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 -N xn-macro -- The \F[C]XN\F[] Macro
|
|
.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
|