Re: man Macro Package and pdfmark

[Deri]

On Saturday, 15 February 2020 23:45:16 GMT Jeff Conrad wrote:
> > Sent: Saturday, February 15, 2020 8:01 AM
> > 
> > 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.
> > 
> > > What's far more nonstandard ...
> > 
> > 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.
> 
> I neglected to mention that the page is for a very specialized command
> and is unlikely to exist in other than PDF format except on my system.
> Everyone using it so far is running Windows, so no one is likely to say
> "man <program>".  It's in man(7) format mainly as a convenience.  It's
> obvious, perhaps, that it should not be distributed for installation in
> a normal man directory (unless perhaps already formatted).
> 
> Perhaps man(7) format wasn't the best choice, but it was a quick (and
> perhaps dirty) way to provided some documentation that might not
> otherwise have been provided.  A couple of people mentioned the lack of
> bookmarks, which does seem pretty lame for 2020.  Perhaps a better
> alternative would be to rewrite the page in texinfo to avoid confusion,
> though in this context, I'm not sure the effort is justified.  And I
> suppose someone might complain that there's no info, which I don't have
> and cannot test.
> 
> Many of my man pages include extensions like those in an-ext.tmac; some
> have the same names but behave differently.  Some of these go back 30
> years when an-ext.tmac didn't exist, so I really didn't have a choice.
> Perhaps that's now not good, but I don't have a great urge to go back
> and update everything.  In most cases, this works to no great evil
> because most of the commands are only for my use.  But I guess I should
> be careful to provide formatted versions the few times I send them to
> others.
> 
> Anyway, thanks for the observation, which I might have not thought of
> (one person did ask about a Linux port).  Using the MKS environment, I
> sometimes forget that most *nix environments have diverged considerably
> from mine in the last 15 years (the MKS man command doesn't appear to
> format anything, expecting formatted files to reside in */cat? directories
> as on most Unix systems long ago).
> 
> Jeff

Hi Jeff,

Given your use case, wanting to provide a pdf which documents a specialsed 
command for 
windows users, you might like to try running it through the attached program as 
a pre-
processor before calling groff. I.E.:-

pdfman <your_man_page.file> | groff -Tpdf -k -mandoc > your_man_page.pdf

(Add your extra personal macros as required).

You can see an example of the sort of documents this produces by pointing your 
browser at:-

http://chuzzlewit.co.uk/WebManPDF.pl/man:/7/groff_mdoc

I hope this is useful.

Cheers 

Deri

pdfman
Description: Perl program