Re: man Macro Package and pdfmark

[Ingo Schwarze]

Hi Jeff,

Jeff Conrad wrote on Fri, Feb 14, 2020 at 08:14:15PM -0800:
> Ingo Schwarze wrote:
>> Jeff Conrad wrote:

>>> .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.

It's non-portable because that other person might use a man(7) formatter
that doesn't support .am or .pdfbookmark, or not in the same way as groff.

> 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.

Of course groff improvements will only take effect for users once
a groff release is made and integrated into their operating system.
But that's the case for any change of any software.

> 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?

Yes, that is very evil.  Never try to be clever in manual page source
code.  Strictly stick to what man(7) documents.

Individual manual pages are not the place to develop new formatting
features.

Yours,
  Ingo