Re: [Groff] Re: Available for small pdfmark project help

[Keith Marshall]

On Sunday 03 May 2009 22:49:31 address@hidden wrote:
> I am looking for clarification on how to incorporate bookmarks
> within a custom macro file that turns on the bookmark pane

That is created when you invoke the

  .pdfhref O n "bookmark text"

macro, (or its equivalent)

  .pdfbookmark n "bookmark text"

at least once in your document source.  (`n' represents bookmark 
nesting level; it *must* be `1' on first use, and may subsequently 
increment in steps of no more than `1', to add an arbitrary level
of nesting.  When a level deeper than `2' has been established, a 
return to any less deeply nested level is permitted in a single 
decrement, to a level no less than `1'.

> within adobe and other viewers,

My experience with anything other than Adobe Reader has been mixed; 
in general, I've found that other readers don't implement reference 
navigation well.

In Adobe Reader, you may *request* that the bookmark pane is made 
visible, when a document is opened, by invoking

  .pdfview /PageMode /UseOutlines

but you cannot force the reader to keep it so.

> and, creates a table of contents with  
> links to the referenced page within the same document.

To achieve that, you will need to create an auxiliary file, 
specifying the appropriate `pdfhref L' calls, and then source that 
into your document.  You will not be able to accomplish it using a 
naive TOC generation technique, such as is provided by the `ms' 
macros.

> A simple explanation of the process would suffice, and/or a simple
> sample file that I review would be helpful.

You will find that in sections 2.2 ... 2.4 of the pdfmark.pdf file,
included with groff since version 1.19.2.

> Also is appears to be a two step process, the first pass to create
> the TOC reference file, and then a second pass to include the TOC
> reference file.

No.  It is a *multiple* pass process; a *minimum* of *three* passes 
is required.  Use the pdfroff command to handle the details.

> I assume the second pass does all the necessary 
> cross-referencing required.

Wrong assumption.  With pdfroff, the *first* pass produces a 
cross-reference dictionary and a tentative cross-reference map, 
(nothing to do with a TOC), and no other output.  The second, and 
subsequent passes up to at most the fifth, reprocess the document 
source, with the cross-reference *dictionary* included, (but not 
the map), and regenerate both the dictionary and the map, (but 
still no output); only when two consecutive such passes produce 
identical copies of the cross-reference map, does processing 
progress to the output phase.

In the output phase, the final PDF document is assembled from up to 
three components:

- a front matter section, which precedes the TOC; this may *not*
  include any live cross reference links.

- a TOC section, generated by one further pass through the document
  source, with both the cross-reference dictionary and map included,
  but with the "pen-up" state in effect during processing of the
  body text.  This is intended to accommodate naive TOC generators,
  (such as provided by the `ms' macros); it is unlikely to satisfy
  your requirements, so you should suppress it, by invoking pdfroff
  with the `--no-toc-relocation' option, (which likely also makes
  the separate front matter component redundant).

- the document body section, generated by a final pass through the
  document source, again with cross-reference dictionary and map
  included, with "pen-down" for the body text and "pen-up" for TOC.

Note the distinction between the latter two components.  In the TOC 
component, the "pen-up" state persists while processing body text, 
with the "pen-down" state being asserted when processing the TOC; 
for the body component.  This is controlled by manipulating the 
OPMODE (PDFOPMODE) register; see spdf.tmac for an example of how 
the appropriate state is controlled by the `TC' macro, based on the 
PHASE register, set by pdfroff to be `1' for TOC production, and to 
`2' for body, (or to zero, if `--no-toc-relocation' is specified).

-- 

Regards,
Keith.