pressing man(7) into service for non-man page documents

[G. Branden Robinson]

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