Re: All caps .TH page title

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4527 bytes --]

Hi Branden,

On 7/21/22 20:36, G. Branden Robinson wrote:
> Hi Alex,
> 
> 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.  From recent groff@ discussions, I guess that neither of
>> you are either.
> 
> Well, Ingo was more comfortable with it than I was.
> 
>> 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.
> 
> I've read every edition of the Unix manual from Version 1 (1971) to
> Version 7 (1979) and my surmise is that it was sheer inertia.  The
> Teletype machines that were used to set the original versions of the
> manual--remember, this is before troff even existed--might have been
> capable of boldface through overstriking, but was not used this way as
> far as I can tell in the V1 through V3 manual.
> 
> So this means that, for emphasis, you had regular type and underlined
> type and that was it.
> 
> Under such limitations, the use of full capitals for emphasis is not
> surprising.

That makes sense.

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

> 
>> Also, does it have any functional implications?  I'm especially
>> interested in knowing if that may affect in any way the ability of
>> man(1) to find a page when invoked as `man TIMESPEC` for example.
> 
> My understanding is that mandb(8) indexes based solely on the second
> argument to the `TH` macro call and (what it interprets as) the contents
> of the "Name" (or "NAME") section of the page.  It parses *roff itself
> as best it can to determine this.  So the fact that the _first_ argument
> to `TH` might be in full caps doesn't deter it.  (It might in fact have
> made mandb(8) authors' job easier if an "honest lettercase" practice had
> arisen back in the day--but it didn't).

Okay.

> 
> Since he's a mandb(8) author/maintainer, I would again defer to Colin
> Watson's knowledge and expertise in this area.

Added to CC, in case he wants to intervene.

> 
>> I'm not saying necessarily that I'd like to keep that behavior.  I
>> wouldn't mind breaking it, if it means that users will be able to
>> differentiate upper- and lowercase pages.  We're not in Windows (nor
>> MacOS), anyway.
> 
> True, although I would take a jaundiced view toward any software project
> that distinguished its man page names, whether internally or from
> others' solely by a difference in lettercase.

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

$ find man* -type f \
   | tr '[:upper:]' '[:lower:]' \
   | sort \
   | uniq -d \
   | while read f; do
	find man* -type f \
	| grep -i $f;
   done;
man2/_Exit.2
man2/_exit.2
man3/nan.3
man3/NAN.3


$ find man* -type f \
   | tr '[:upper:]' '[:lower:]' \
   | sort \
   | uniq -d \
   | while read f; do
	find man* -type f \
	| grep -i $f;
   done \
   | while read f; do
	echo ===$f===;
	head -n1 $f;
   done;
===man2/_Exit.2===
.so man2/_exit.2
===man2/_exit.2===
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
===man3/nan.3===
.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
===man3/NAN.3===
.so man3/INFINITY.3


At least, _Exit(2) and _exit(2) point to the same page.  nan(3) and 
NAN(3) don't, 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.


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.

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

Cheers,

Alex

> 
> Regards,
> Branden

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]