[Groff] Re: [Fwd: pdfmark troubles]

[Keith MARSHALL]

The following is my reply to a private enquiry from Zvezdan Petkovic,
reproduced here with his permission:--

> I'm trying to use pdfmark.
> I used to use my own macros, but pdfmark offers more and I can basically
> directly replace my .URILINK and .PDFMARKINFO macros with .pdfhref and
> .pdfinfo requests.

Nice to get some feedback, from an end user :-)

> The .pdfinfo replacement went well.

Good.

> However, all I get is a blue text enclosed in two black bars instead of
> the real URI links.

The .pdfhref mechanism requires *at least two* groff passes, to compute
link positions, and properly resolve references.  The two black bars you
see are emitted in all but the final pass, to mark the bounds from which
the link position is computed -- more on this below.

> After attempting in vain on my existing document I
> decided to make a simple tryme.ms document to demonstrate the problem.
> Please, find attached tryme.ms, tryme.ps, tryme.pdf, and out files.
> The out file will show you how the pdf file was produced with make (I
> also did a trace).  Notice that sed script didn't change anything in
> this simple file.  PostScript file will show you that the proper
> /Link incantations are missing from it.
> I do not know why.
> It must be something simple.
> Please, point me in the right direction.

Hmm.  You are trying to perform the entire PDF formatting process from
scratch, and I will freely admit that I haven't yet gotten around to
documenting the necessary steps for doing that.  :-(

The simplest method of converting your `tryme.ms' to `tryme.pdf' is to
use pdfroff.  This command:--

   pdfroff -ww -ms -mpdfmark tryme.ms > tryme.pdf

is sufficient to process your input file, producing the desired output.

If you want to understand how pdfroff works, you can examine the script,
(it's just Bourne shell scripting), for the full details.  Here's a very
brief outline:--

1) first, a preliminary groff pass is performed, to collect reference
   data, (based on marks planted by .pdfhref M calls), and to map the
   positions of links, placed by .pdfhref L or .pdfhref W calls.  All
   such reference data is emitted on stdout, which is redirected to a
   temporary file; regular postprocessor output is suppressed.

2) the .pdfhref M info, from the first pass temporary output file is
   filtered into a reference dictionary file, where it is represented
   by a succession of .pdfhref D calls;  a simple awk filter converts
   the raw groff output format to the required .pdfhref D form.

3) a further preformatting groff pass is performed, as in step(1), but
   prefixing the generated reference dictionary to the input file list,
   and a second copy of the reference dictionary is generated.

4) the two generated reference dictionaries are compared, and if not
   identical, (inclusion of the reference data may result in a layout
   change), step(3) is repeated until two successive dictionary
   generations are identical; if more that four passes are required,
   the process aborts, requiring the user to resolve a layout
   instability, (but I've never seen this happen).

5) once consistency of the reference dictionary has been established,
   a linkage map is generated, and appended to it, in the form of
   .pdfhref Z calls;  these are also generated by filtering the
   temporary output stream, again with a simple awk filter, picking
   out the `grohtml-info' records you see in your `out' file -- there
   is one such record for each of those black bars you noted, and each
   successive pair is translated to a single .pdfhref Z call in the
   linkage map.

6) the final PDF production groff pass is performed, prefixing the
   combined reference dictionary and linkage map to the list of input
   files, and piping the grops output stream directly to GhostScript,
   to produce the finished PDF document; it's the processing of the
   .pdfhref Z calls, before any .pdfhref L or .pdfhref W call, that
   inhibits the emission of `grohtml-info' records, (and their
   associated black bars), and activates the emission of the /Link
   pdfmarks in the PostScript stream, in their place.

(Actually, in the alpha of pdfroff, *two* finishing groff passes are
performed, to facilitate the relocation of TOC entries generated by
mechanisms such as ms's .XS, .XA and .XE macros.  However, I plan to
tidy this up, when I get around to providing a better TOC generating
mechanism).

HTH.  With your permission, I'd like to copy this to the groff list,
together with just your `tryme.ms' and `out' attachments, as it may be
of more general interest.

Best regards,
Keith.

tryme.ms
Description: Binary data

out
Description: Binary data