Ingo,
> Sent: Friday, February 14, 2020 10:46 AM
> > .am SH
> > .pdfbookmark 1 "\&\\$*"
> > ..
> > .am SS
> > .pdfbookmark 2 "\&\\$*"
> > ..
>
> Just don't do that. Never use low-level roff stuff in manual pages,
> don't even think about it. This makes your manual pages non-portable.
I'm not quite sure I follow. This code is at the beginning of the file;
thereafter, the markup is standard man(7). If I send my file to someone
else, it should work just fine. If I make the changes to an-old.tmac,
anyone to whom I send the file would need a nonstandard an-old.tmac for
the bookmarks to work.
What's far more nonstandard is my use of several forms of pdfhref to
link section references and www references. They need to be wrapped in
macros to handle output other than PDF. Is this bad? Having played
with the man page after adding them, it's tough to imagine not having
them. I was actually thinking of redoing my documentation for one
esoteric program in texinfo. I now think it will be OK with man.
> If you want bookmark support for PDF output from man(7) files, that
> needs to be done in the file an-old.tmac, but in a careful way that
> does not cause incompatibilities
I agree that an-old.tmac is the right place to do this; there's the
added advantage that the call to pdfbookmark can be made before the
heading text is output, eliminating the need to adjust the value of
PDFHREF.VIEW.LEADING. But it seems to me that the right way to do it is
in the distribution so that a man page that relies on it will work
anywhere.
> and that does not require including any other macro files. It may be
> tricky, but it may well be possible.
As it turns out, there is nothing tricky about it. I discovered that
the pdfmark macros are defined in pdf.tmac, so there's no need to load
pdfmark.tmac.
Mystery Messages
----------------
It turns out that the problem arises from the leading zero-width glyph
in my call of pdfmark:
.pdfbookmark 1 "\&\\$*"
changing this to
.pdfbookmark 1 "\\$*"
gets rid of the messages. The protection is unnecessary anyway, because
the macros already provide it. So just don't do it. Don't even think
about it.
However it's done, the bang for the buck seems pretty high.
Jeff
