Hi Alex! I've changed the Subject:.
At 2022-01-28T02:07:24+0100, Alejandro Colomar (man-pages) wrote:
[the new man(7) PDF bookmarks stuff]
> While I don't read man pages in PDF, I have written a few PDF
> documents using man(7), and for those, this feature is great.
Thanks!
> P.S.: I tried ms, as you recommended, but I'm not yet convinced by it.
It does have its quirks. I think, particularly for cover sheet stuff
("document description macros" as I term them in our ms(7) docs), it
blundered by using diversions to store material; really, storage of
string arguments was all that was required. My guess is that this
design choice was a hangover from the typewriter mentality.
The ordering of arguments to the text styling macros, still referred to
as "Highlighting" in our current docs, though I mean to change that, is
startling and can only be explained by historical development. If I
recall correctly, Unix V6 ms didn't accept more than one argument for
`B` and `I`. By V7 people had figured out that having an abutting
suffix in the previous font was a good idea. It took BSD to realize
that having an abutting _prefix_ argument was a good idea, too, but by
then arguments 1 and 2 already had meaning.
Thus the slightly absurd:
.F text post pre
...which reads terribly in maintenance.
Those are probably the two worst warts.
> I'll still use man(7) for a while, I think. My only problem with
> man(7) is .TH, which I can't remove :/
Well, you sort of can. You can call .TH with 2 dummy arguments and then
redefine the header and footer traps (PT and BT, respectively). If you
don't _need_ either or both of them, you can redefine them to nothing.
That way the information declared in the `TH` call will never show up
and your document won't even look much like a man page anymore.
I'm attaching a demonstration.
This exercise did cause me to notice a probable bug; you have to
redefine the page trap before calling `TH` because itself calls `PT`.
But in groff_man(7) we tell the reader to perform any macro
redefinitions _after_ calling `TH`, so if people follow the rules we
tell them, they can't escape having the default header on the first page
of the document.
And if you use -mandoc, even that won't suffice to escape the problem
because andoc.tmac relies upon seeing `TH` to know when to (re)load the
man(7) package. That's one reason we tell people to do their
redefinitions afterward--as I understand it, the other is "to
accommodate timid mandb(8) implementations", as we say in groff_man(7).
It's a problem. I guess people don't use this feature much or we'd have
heard about it. We need the page header to get called ASAP after
starting a new page, but not _from_ `TH`. Maybe an input trap will do
it...I'll have a look.
Regards,
Branden
not-a-man-page.man
Description: Unix manual page
signature.asc
Description: PGP signature
