Hi Ingo and Colin, At 2025-09-05T17:50:10+0200, Ingo Schwarze wrote: > G. Branden Robinson wrote on Sun, Aug 31, 2025 at 11:06:43PM -0500: > > [1] I admit that "topic" is my own invention. groff_man(7) presents > > the distinction between a "title" and a "topic". > > I hate that terminology. > > The mandoc manual pages just call arguments you can pass to man(1) > for lookup "names", plain and simple. [...] > Looks like overwhelming support for calling this "name" to me.
At 2025-09-05T17:49:03+0100, Colin Watson wrote:
> I also prefer "name". man-db's man(1) does use "page" in a couple of
> places and "item" in another when referring to the argument, but I am
> inclined to canonicalize all of those to "name".
Overwhelming support among those who are pounding out "man" commands in
a terminal window, frustrated with some problem they're working on and
in a state of desperation, sure. (I note in passing that indulging high
LOC/day hackers of the "give me what I want, not what I ask for"
school[1] might explain how the man(1) and mandoc(1) feature pending
withdrawal got introduced in the first place.)
The _writer_ of a man page by contrast is better served by telling
unlike things apart. 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, and a page author what specifying each does and does not
accomplish.
groff_man_style(7):
Notes
[...]
• What’s the difference between a man page topic and identifier?
A single man page may document several related but distinct
topics. For example, printf(3) and fprintf(3) are often
presented together. Moreover, multiple programming languages
have functions named “printf”, and may document these in a man
page. The identifier is intended to (with the section) uniquely
identify a page on the system; it may furthermore correspond
closely to the file name of the document.
The man(1) librarian makes access to man pages convenient by
resolving topics to man page identifiers. Thus, you can type
“man fprintf”, and other pages can refer to it, without knowing
whether the installed document uses “printf”, “fprintf”, or even
“c_printf” as its identifier.
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.
(Maybe I should add "(but need not)" between "may" and "furthermore"
above. Working on ncurses's man pages confronted me squarely with this
distinction.[2])
Regards,
Branden
[1] https://mcraeblog.com/2018/02/15/the-knee/
[2] https://github.com/ThomasDickey/ncurses-snapshots/tree/master/man
signature.asc
Description: PGP signature
