PDFBMToC (PDF bookmarks Table of Contents) v0.1 mark II 2020/09/29 for WPDOS 6
by Alfredo Fernndez Daz, mrwarper@yahoo.es

1. Summary, background
2. Features
3. Operation in more detail
4. Known problems and limitations
5. Revision history

1. Summary, background
~~~~~~~~~~~~~~~~~~~~~~
This macro should only be used when producing PDF files from WordPerfect
documents. It eases navigability of PDFs by including a collection of
'bookmarks' in the files produced when printing.

PDF and WordPerfect bookmarks are similar in that they allow quick access to
parts of the document, but operating in very different contexts, they are
unrelated and independent where document edition is concerned, hence this.

2. Features
~~~~~~~~~~~
-All Table of Contents items are exported as PDF bookmarks. (Except unclosed or
empty items, which are skipped.)
-If present, a previously generated PDF ToC is replaced automatically.
-Arbitrary WP page numberings do not prevent PDF bookmarks from working.
-PDF bookmarks text length is not limited by the macro.
-A brief summary of operation is shown in the status line when done.
-After operation, cursor position, and QuickMark if present, are restored.

3. Operation in more detail
~~~~~~~~~~~~~~~~~~~~~~~~~~~
PDFBMToC generates PDF bookmarks from bits of the document marked as 'Table of
Contents', whether an actual Table of Contents is generated and included inline
in the document itself or not. There is no need to generate a document Table of
Contents to have bookmarks in the PDF, and generating these does not generate
a ToC for the document. You must do this yourself if you so desire.

PDF bookmarks are created as Printer commands (using the 'pdfmark' extension of
the PS language). They are placed enclosed in a block bookmarked as 'PDF ToC'
at the beginning of the document, and should have no effect on the document
itself unless it is printed.

Printing a document including these Printer commands on a real printer will
probably print spurious text, or have other unpredictable results if the
printer is not PostScript-compatible, and should have no effects if it is,
because these commands are not intended for a real printer.

It is therefore recommended to save documents just before executing this macro,
print, and discard the changes, as this will prevent any problems with Printer
commands being left in.

4. Known problems and limitations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Non-ASCII characters in bookmarks text must be escaped and/or mapped to some
encoding that PostScript to PDF converters such as GhostScript or Adobe
Distiller will handle appropriately.

5. Revision history
~~~~~~~~~~~~~~~~~~~
2020/09/29:
-WP-arbitrary page numbering is translated to the sequential numbering expected
 by PDF conversion tools.
-"PDF bookmarks ToC begin" and "-end" comment lines delimit macro PostScript
 output.
-The whole "PDF ToC" bookmark block is removed from the document if no PDF ToC
 entries are created.

2020/09/22: Initial version.
