Re: All caps .TH page title

[Ingo Schwarze]

Hi,

Colin Watson wrote on Fri, Jul 22, 2022 at 01:22:57AM +0100:

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

FWIW, the mandoc(1) implementation of the indexes uses the following
to derive names for a page:

 * the first component of the file name,
   including of hard, soft, and .so links
 * in man(7) pages, the first argument of the .TH macro        <<=====
 * in man(7) pages, any words preceding the first "-" or "\-"
   in the NAME section
 * in mdoc(7) pages, the first argument of the .Dt macro       <<=====
 * in mdoc(7) pages, arguments of .Nm macros in the NAME section
 * in mdoc(7) pages, arguments of .Nm macros in the SYNOPSIS
 * in mdoc(7) pages, first arguments of .Fo and .Fn macros in the SYNOPSIS

The last two - mdoc(7) SYNOPSIS content - are only used for man -k
searches explicitly specifying the Nm search key.  All others are also
used for plain man(1) name lookup.

In mandoc the following are used as section names:

 * if the directory name starts with "man" or "cat", the rest of it
 * the file name suffix, starting after the last dot
 * in man(7) pages, the second argument of the .TH macro
 * in mdoc(7) pages, the second argument of the .Dt macro

The above rules often cause pages to end up with more than on name
and and more than one section.  For example, a file called

  man3p/strcpy.3

containing

  .TH strlcat 3bsd
  .SH NAME
  wcslcpy, wcslcat \- yadayada

can be found with any of the following commands, and several more:

  man 3bsd strcpy
  man 3 strlcat
  man wcslcat
  man 3p wcslcpy

As a special case, if the .TH or .Dt argument agrees with one among
the other names but differs in case, it is not used, because
mandoc assumes the other name is likely correctly cased while
the name in the .TH or .Dt macro may have been converted to all caps.

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

In the mandoc implementation, plain man(1) follows the tradition of
being case-sensitive, but i must admit examples of manual pages with
names that differ only in case are hard to find indeed, so it might
make sense to change this and make it agree with man-db.

In the mandoc implementation of apropos(1), searches use case-insensitive
extended regular expressions by default (which originally was a
proposal coming from FreeBSD).  If the regular expression operator '~'
is explicitly specified, the search becomes case-sensitive.  If the -i
option is given, it becomes case-insensitive again.  The substring-search
operator '=' always remains case-insensitive no matter what.

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

Indeed, doing that would be very bad style, not least because it would
make the correct capitalization of the name hard to find for the
human reader of the manual page.

Yours,
  Ingo