Hi Lennart,
Lennart Jablonka wrote on Mon, Aug 21, 2023 at 12:45:01AM +0000:
> Quoth G. Branden Robinson:
>> At 2023-08-19T20:08:06+0000, Lennart Jablonka wrote:
>> (I observe that ncurses doesn't actually _provide_ a terminfo(3) page,
You can't really say that in general, it appears to be operating system
dependent. For example, on OpenBSD-current, i get:
schwarze@isnote $ man -ks 3 terminfo
termcap, tgetent, tgetflag, tgetnum, tgetstr, tgoto, tputs(3)
- direct curses interface to the terminfo capability database
terminfo, del_curterm, mvcur, putp, restartterm, set_curterm, setterm,
setupterm, tigetflag, tigetnum, tigetstr, tparm, tputs, vid_attr,
vid_puts, vidattr, vidputs(3) - curses interfaces to terminfo database
The same applies to NetBSD:
https://man.bsd.lv/NetBSD-9.2/terminfo.3
but apparently not to FreeBSD. So really, it varies.
>> which is silly.
Actually, it isn't. Strictly speaking, OpenBSD policy would dictate
deleting the name terminfo(3) from the putp(3) manual page because
there is no such thing as public API function called terminfo()
that a program could call:
schwarze@isnote $ man -k Fn=terminfo
man: nothing appropriate
schwarze@isnote $ objdump -t /usr/lib/libcurses.so.14.0 | grep putp
000000000004b8b0 g F .text 000000000000001a putp
schwarze@isnote $ objdump -t /usr/lib/libcurses.so.14.0 | grep terminfo
0000000000000000 l df *ABS* 0000000000000000 home_terminfo.c
000000000001cb7a l O .rodata 0000000000000007 _nc_get_token.terminfo_punct
00000000000297b0 g F .text 00000000000000cf _nc_home_terminfo
>> Or rather, the page is there, but it doesn't bother to mention its own
>> name in its NAME section so that makewhatis/mandb can find it.
While this situation only occurs in a minority of manual pages,
it is not completely out of the ordinary. There are several pages
with this property.
Also, please be careful about your terminology. There is no such thing
as "the" name of a manual page. Many manual pages - likely even the
majority of them - have more than one name, and there are five
different categories of manual page names:
* file namess - traditional implementations of man(1) search for
manual page names in the file system, so these are the only names
they support. Yet, using hard or symbolic links, a manual page
can easily have multiple file names, and many operating systems
and portable software packages use that feature by creating hard
or soft links to manual pages.
mandoc(1) doesn't have any such limitation, but recognizes some
manual page names from the file content in addition to from the
file names.
* header names, i.e. those contained in .TH or .Dt macros.
There is always exactly one header name per page. Even if you wanted
to define "the" name of a manual page, this would be by far the worst
choice because traditionally, it is all caps, so it traditionally
provides incomplete information. We are currently in the process
of deprecating putting all caps here, but that process is going to
take a long time to complete.
Traditional implementations of man(1) do not take header names into
account when locating man pages. mandoc(1), however, does.
* NAME section names - traditional implementations of man(1) do not
take these into account when locating man pages. mandoc(1),
however, does. Many pages have several such names.
* the first NAME section name, which sometimes is considered more
important than the other NAME section names, but it's not really
"the" name of a manual page either. In a typical library
development lifecycle, library developers introduce a function,
use it for years, then realize the design is defincient and can be
improved upon, so they invent another, related function and document
it in the exiting manual page. Again years later, the original
function may become deprecated, but remains documented because some
existing software still uses it. So you end up with a manual page
where the first NAME section name is deprecated.
This is not at all uncommon.
* synopsis names, i.e. names appearing in the SYNOPSIS, for example
using the mdoc(7) .Nm or .Fn or .Fo macros. Even though man(1)
does not take these into account when locating manual pages, at
least not traditionally and not when run with default options,
these are undoubtedly names because the mandoc implementation
of apropos(1) can search for them using the "Nm" search directive.
>> Guess I'll be sending a patch.)
I'm not sure what the policies of the specific upstream project you
are considering to send a patch to are, but please take the above
into account and do not confuse them by using misleading language
in the rationale that you provide to them with your patch.
> Wait, man-db does’t use a man page’s title to look it up at all?
> That seems bad.
Well, as far as i am aware, it uses all filenames of the page
for loookup, as *all* traditional implementations of man(1) do
it, in particular AT&T UNIX man, all CSRG BSD mans up to and
including 4.4BSD-Lite2, man-1.6 (still used by Illumos and Solaris
last time i looked), man-db, FreeBSD man, NetBSD man.
The odd one out really is the mandoc implementation of man(1)
which does use header and NAME section names for lookup.
It is used by default in OpenBSD, Alpine Linux, Void Linux,
and Termux, and users can optionally switch to it in Arch Linux,
openSUSE, and Fedora.
>> Until it does, read "terminfo(3)" as "putp(3)". It's brings
>> up the relevant page and is quicker to type anyway.
Good advice.
> That conflicts with my sense of aesthetic. References should use
> the man page title. The correct way to refer to putp’s man page
> is something like “Print stuff using putp (see terminfo(3)).”
Absolutely not. It is very widespread practice to refer to a page
by any of its names that can be found by man(1). Best practice,
in any particular instance of a reference, is to use the name that
is most logical. So pointing to putp(3) is actually better in the
example you are constructing above because this makes more sense to the
reader and is easier to understand. The user has no reason to care
which other function may or may no be documented in the same page.
Besides, that is likely an operating-system specific implementation
detail and often even changes over time within an operating system.
I have personally merged and split manual pages many times in the past,
and it would be a maintenance nightmare if performing such a merge or
split would require changing all cross-references to the manual pages
involved in the split or merge. On Linux, the inconvenience would
be even more dire than on BSD systems because you would have to deal
with many different package maintainers, some of whom may be slow to
respond, let alone roll a new release for their package, so in Linux,
your policy would render manual page maintenance next to unworkable.
Besides, "using putp (see terminfo(3))" looks ugly, is unnecessarily
wordy, and causes a distraction of the reader for not benefit
whatsoever.
Yours,
Ingo
