Hi Branden,
G. Branden Robinson wrote on Fri, Sep 05, 2025 at 12:20:50PM -0500:
> Overwhelming support among those
I didn't mean support by any group of people, but support by existing
terminology ("file name", NAME section, .Nm macro).
> how the man(1) and mandoc(1) feature pending
> withdrawal got introduced in the first place.
Hard to say given that i still don't know at all who invented it
nor when. Do you? All i know is it was probably invented later
than 4.4BSD-Lite2 (1995) and earlier than man-1.5e (1998).
Given that both man-1.5 and man-db had it in 2001, maybe John Eaton
invented it? But that's pure speculatulation on my part. I know
absolutely nothing about John Eaton's character and have no idea
whether he catered to the kind of folks you allude to, or was of
the kind himself.
> The _writer_ of a man page by contrast is better served by telling
> unlike things apart.
Maybe, but the man(1) user interface is mostly for users (not even
primarily for programmers, let alone for documentation authors).
Besides, according to my experience, when there are discrepancies
between the different kinds of names, in most cases they are purely
accidental. It isn't even rare that they merely stem from people
simply not understandig how to name and organize manual pages
properly.
Using different names for things that should better not be different
in the first place is not productive. That's why OpenBSD only documents
the different kinds of manual page names in the mandoc.db(5) manual
page, an extremely technical manual page that's really only needed
by people who want to work on the source code of makewhatis(8)
and apropos(1).
> A man page's file name, its identifier as specified in the first
> argument to a `TH` call (mdoc(7): the only one to a `Dt` call),
> and the list of topics enumerated in a "Name" section and which
> can therefore be used in man page cross references are all distinct,
Yes, and that is a design defect of the man(7) and mdoc(7) languages,
purely a historical accident. There is no logical reason why they
should be different.
> and a page author what specifying each does and does not accomplish.
That rule is extremely simple.
1. Decide which names your page is intended to document.
Those are the names that will be listed in the NAME section.
2. Decide on the order you want to document the names in.
Use the same order in all sections, in particular in NAME,
SYNOPSIS, and DESCRIPTION. Choosing a good order is a non-
trivial didactical, structural, and logical task.
3. Use the first of these names for .Dd or .TH, too,
and as the filename as well.
At least in OpenBSD, only a small minority of manual pages violate
rule 3. And at least 90% of this small minority violate rule 3
purely out of historical accident and should be cleaned up.
Many have been cleaned up already, and the reason for some to still
linger is mainly that it's not a particularly important task.
Inconsistent names are at worst *additional* names, and having
additional (legacy) names around almost never harms users in a
significant way.
> groff_man_style(7):
[...]
> The identifier is intended to (with the section) uniquely
> identify a page on the system;
That's a blantant lie.
$ grep -F -e .Dt -e .TH $(man -w ls) | cut -b1-65
/usr/local/man/man1/gls.1:.TH LS "1" "August 2025" "GNU coreutils
/usr/share/man/man1/ls.1:.Dt LS 1
There is nothing wrong whatsoever with having two manual pages
in the same section with the same "identifier", and in that sense,
the term "identifier" is badly misleading. Technically, even having
two manual pages with the same "identifier" in the same directory
is possible, with different content - admittedly, that would violate
rule 3 above, but that rule is merely a convention.
> The man(1) librarian makes access to man pages convenient by
> resolving topics to man page identifiers.
That lie is more outrageous than the previous one. Mandoc most
definitely does nothing of the kind, and i would be very surprised
if man-db did anything of the kind.
What is really going on is that man(1) resolves page names
to absolute file names. And what you call "identifier" is just
one kind of a page name, and the distinction of NAME section names
and .Dt/.TH names is completely irrelevant to both users and
documentation authors.
That two things superficially appear different does not mean that
they have any reason for being diffirent. In fact, it is not unusual
that one of them simply arose from a misdesign. If i were to
redesign the mdoc(7) language from scratch (which i certainly
won't do because it is good enough such that it does not need
a redesign from scratch), i would simple remove the "name" argument
from .Dt, it is completely useless and merely duplicates .Nm.
When documentating a user interface containing such gratuitious
differences, the last thing one should do is retroactively invent
rationalizations of the gratuitious quirks, and even less so invent
objectively wrong claims as to what these quirks do, when in fact,
they do nothing whatsoever.
> I don't insist that you guys make such fine distinctions in your man(1)
> programs, but I maintain that a command of the anatomy of a man page
> document is important for people composing them.
Absolutely not. You are inventing distinctions out of thin air
that have no relevance whatsoever, for nobody at all, no even for
manual page authors. The only people who have to pay attention to
these points are the implementors and maintainers of makewhatis(8)
and apropos(1) programs, and only in so far as they have to make
sure that all names are found, no matter where they appear,
and that all names (from file names, .Dt/.TH, and NAME/.Nm)
are treated equally.
> [2] https://github.com/ThomasDickey/ncurses-snapshots/tree/master/man
Gratuitiously introducting large herds of bogus names like these
filenames is ugly because it unnecessarily pollutes the name space -
then again, beyond the ugliness and beyond wasting very small amounts
of space in the databases, it doesn't cause any particular harm.
Yours,
Ingo
