On Sunday 03 May 2009 22:49:31 j...@sacredlabor.com 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.
