Re: All caps .TH page title

[G. Branden Robinson]

[Colin and Ingo dropped from CC since I know they read the groff list]

Hi Alex,

At 2022-07-22T01:16:49+0200, Alejandro Colomar wrote:
> On 7/21/22 20:36, G. Branden Robinson wrote:
> > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> > > I've never been convinced about the page title being in all caps
> > > in the .TH line.
[...]
> > > I'd like to know why this has been the case historically, and any
> > > opinions you might have about me changing the man-pages to use the
> > > same caps as the actual identifier that I'm documenting (most of
> > > the time that would mean lowercase).  Basically, the same rules as
> > > within .SH NAME.
[...]
> > After that--the V4 manual was the first to be typeset with
> > troff--the practice of full-capping the page titles in the headers
> > was retained.
> > 
> > How deliberate a choice this was is not something I can answer.  The
> > decision was made in 1972.  You could ask some of the surviving
> > principal Bell Labs CSRC figures on the TUHS mailing list.
> 
> Is Doug one of them?  I've seem him on the groff@ list from time to
> time.  I added the groff@ list, in case this is of interest to someone
> there.

Yes, Doug McIlroy follows both the groff and TUHS lists.

> Heh!  You've never tried to clone the Linux man-pages in Windows or MacOS,
> it seems :p

No, can't say I've had the...pleasure.

> At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and
> NAN(3) don't, though!

Pretty gross.  A useful counterexample of good practice, though.

> We can't blame the writers, since the identifiers have those names in
> C.  Luckily, man(1) shows you the right page if you specify the right
> string.

Yes, and at least they're closely related and from the same project.

This is the only man page I know of that documents only simple (i.e.,
not function-like) C preprocessor macros.  You're more conversant with
libc-ish man pages so you may know of others, but this is the sort of
content that, as a user, I would prefer to find in, say, a "math.h(3)"
man page.  Having these constants in a page by themselves does little to
situate them within the context of the C math library API.  But I know I
have suggested this to you before.  ;-)

I observe that the most popular simple macro of all, NULL, has no man
page.

> I feel a need to fix this lack of precision in the page titles.
> Unless someone opposes to it with some strong reason, which I don't
> expect.

You never know.  But keep in mind that a strong objection is not the
same thing as a strong reason.

> It'll take some time to do it, but if no-one speaks in a reasonable
> time, I'll start doing it :).

We should all practice our scowling faces for anyone who dares to
promulgate man pages named "lS", "prIntf", or similar.

Regards,
Branden

signature.asc
Description: PGP signature