/contrib/groff/contrib/pdfmark/pdfmark.ms
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 2531 lines · 2531 code · 0 blank · 0 comment · 0 complexity · c01bc1e55d1cbc0917956cb7adad1ae2 MD5 · raw file
Large files are truncated click here to view the full file
- .\" 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 defaul…