Re: All caps .TH page title

[Colin Watson]

On Fri, Jul 22, 2022 at 01:16:49AM +0200, Alejandro Colomar wrote:
> On 7/21/22 20:36, G. Branden Robinson wrote:
> > At 2022-07-21T16:29:21+0200, Alejandro Colomar wrote:
> > > 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.

The above is not quite correct.  man-db doesn't index on the .TH section
at all, and I don't believe I've encountered the practice of doing so in
other indexers (I could be wrong, but I think that's something I would
have remembered if I'd noticed it).  Rather, it parses the "NAME" (or
"Name", or a number of localized variants) section of pages using the
man macro set for "foo \- description" lines and uses the left-hand side
of those for page names, or equivalently looks for .Nm requests in pages
using the mdoc macro set.

With the exception of handling localized variants of that section name,
which is a pretty ugly pile of special cases, I believe this to be
fairly traditional behaviour.  I can't say I would have done it that way
if I'd been designing the system from scratch since it really involves
far too much half-arsed parsing, but it seemed to be the usual thing to
do when I came on the scene.

Changing the arguments to .TH won't bother man-db at all.

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

man-db's man(1) performs case-insensitive lookups by default, which I've
found to be more useful behaviour.  Case-sensitive lookup can be
requested using the -I/--match-case option.

As far as I know this was an innovation when I introduced it in 2002, so
I don't know how widespread this behaviour is among man(1)
implementations.  You probably can't rely on it.

But in any case, as above, changing the arguments to .TH doesn't affect
this.  I haven't noticed it being widespread practice to spuriously
capitalize the name part of lines in the "NAME" section.

Cheers,

-- 
Colin Watson (he/him)                              [cjwatson@debian.org]