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
