Re: [Groff] groff 1.19.2 with pdfref

[Keith MARSHALL]

Rüdiger Härtel wrote, quoting me:
>> IIRC, 1.19.2 installs a `pdfroff' command, and associated macros
>> in `pdfmark.tmac', which provide pretty much all that Kees
>> Zeelenberg's original package did, and more.  There's also an
>> `spdf.tmac', which defines rudimentary bindings for the `ms'
>> macros.
>
> I know about these macros. But the macros from Kees redefined and 
> enhanced the .NH and .SH macros so that I didn't need to write an 
> extra .XS and .XE. That is what stops me from using it.

Well, modifying NH and SH is a rather perilous thing to do; they
both use self modifying code, so your changes may be trashed, as
soon as you call them.  For `spdf.tmac', I deliberately chose the
safer, (and easier to implement), option of leaving them unchanged,
and adding an extra XN macro, for use on the following line, so
original `ms' source:

  .NH 1
  This is my Numbered Heading

is easily transformed, (perhaps by filtering through `sed'), into:

  .NH 1
  .XN This is my Numbered Heading

and the `.XN' takes care of creating the numbered bookmark entry,
and also generating a matching `.XS' .. `.XE' entry.

> I also wonder why do I have to do this extra step. Even with plain 
> ms I need XS and XE to get a TOC. The other way round - have 
> separate argument to NH/SH to disable printing a header in TOC - 
> would make more sense to me.

That's just the way traditional `ms' worked; we don't want to change
that, so we don't break compatibility with existing documents.

>> You might like to try these, as an alternative.
>
> No. We have a few user manual that already make use of Kees macros 
> and we don't want to switch. I would think about it if the above 
> mentioned feature is available.

Well, because of the self modifying nature of NH and SH, (and many
other macros in `ms'), redefining, and even appending to them is, as
I said above, a perilous exercise.  It probably meant that Kees had
to include some hackery, relying on undocumented internal behaviour,
which makes his macros fragile, and prone to breakage when the core
package is upgraded to a new version; this is what you appear to be
seeing, since your upgrade to 1.19.2.

> Since I only have limited knowledge of writing groff macros at the 
> time writing I cannot do it myself :(

And I'm sorry, but I simply don't have time to look into it myself.
As a short term solution, all I can suggest is that you find a copy
of `s.tmac' from a groff version which did work with Kees' macros,
save that in `${prefix}/share/groff/site-tmac', preferably with a
different name, say `s-old.tmac', then format your documents with:

  groff -U -ms-old -M. -mspdfref test.t2 > test.ps
  ps2pdf test.ps

For the longer term, I'd suggest that you consider filtering your
existing documents, (with sed), to add `.XN ' at the start of each
line following `.NH', (and also to add `.XH ' at the start of each
line following `.SH', with the caveat: adapting `XN' to also provide
`XH' is still on my TO DO list, so if you make heavy use of `.SH'
for headings you want to bookmark, then you'll have to ask me to
raise its priority).  With that accomplished, then you can use:

  pdfroff -mspdf test.t2 > test.pdf

HTH,
Keith.