Hi Ingo,
At 2025-09-05T21:52:10+0200, Ingo Schwarze wrote:
> 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).Ah, I get you now. > > 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? Nope. > 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? Or Andries Brouwer, or Federico Lucifredi? > 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. I'm not much concerned with qualities of character here, just one episode of judgment. And even that's an auxiliary issue; you and Colin are benevolently conspiring to clean up a minor mess, and I don't intend to impede either of you. :) > > 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). Certainly. That's a key part of my point. man(1) users as such have little reason to read groff_man(7) unless they have strong opinions about details of rendering, and almost none to read groff_man_style(7). > 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. I share this premise. > Using different names for things that should better not be different > in the first place is not productive. Agreed. Except as I pointed out, file names, arguments to `TH` and `Dd` calls, and, shall we say (since you dislike the term "topic") "head words" in "Name" sections _are_ all different things. Is there frequent correspondence between them? Yes. But close relation is not identity. > 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). ...and why I present the distinction between "names" and "topics" only in groff_man(7) and groff_man_style(7). > > 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. I suspect you're mistaken here. The luminaries of the Bell Labs CSRC certainly understood the difference between upper- and lowercase, therefore we know they distinguished `TH` arguments from `SH "NAME"` head words. They also understood that while file names could be multivalued (consider hard links), and so too could a page's head words, they evidently decided that `TH`'s first argument would not be (within a given document). As evidence, I cite, for instance, the "TROFF(1)" page of the Seventh Edition Unix Programmer's Manual. https://archive.org/details/bitsavers_attunix7thersManualSeventhEditionJanuary1979Volume_30031831/page/217/mode/1up Two topics, one identifier. > There is no logical reason why they should be different. I disagree, and claim not only potential but actual difference. > > 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. Yes. Equivalently, which head words or topics. > 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. The sequencing of names within a document is irrelevant to the question of the nomenclature selected _for_ those names. Well, I suppose it matters a little bit for `Nm`, because that macro's interface is optimized for pages that document only one topic. That, however, is a lacuna of mdoc(7)--one you seem to embrace--not of the common principles underlying man page organization. > 3. Use the first of these names for .Dd or .TH, too, > and as the filename as well. A good rule of thumb, but as you've pointed out, it can fail if the "name" contains a slash. > 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. I would agree that there are bigger fish to fry, but you're much more aggressive than I about asserting rules that should not be violated. > > groff_man_style(7): > [...] > > The identifier is intended to (with the section) uniquely > > identify a page on the system; > > That's a blantant lie. Certainly not. Observe. > $ 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 Apply your own rules. Why is the first argument to `TH` not "GLS"? Why, when I peruse the version of the page apparently corresponding to FreeBSD Ports 8.2-RELEASE, does the "NAME" section not match, either? https://manpage.me/index.cgi?apropos=0&q=gls&sektion=1&manpath=FreeBSD+Ports+8.2-RELEASE&arch=default&format=html > 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. No, it isn't. Ever worked with an SQL database? Identifiers can be contextualized and namespaced. "Identifier" does not necessarily imply "unique identifier". That said, I'd agree that the "gls" example exhibits a suboptimal system configuration. How does the user know what the resolution order is for the multiple matches? Why does "gls" show up first, complete with its (to the *BSD nose) odious and excessive GNU baggage, and not the shiny, clean, elegant, minimal, mdoc(7)-adumbrated document? > 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. If the rule is merely a convention, I suggest not articulating it as a rule and then not thundering about it being violated. That is why we use different words for "convention" and "rule". I'd say instead that a couple of axes of distinction are available, and their use should be encouraged where appropriate. First, man pages can be distinguished by suffixes on the section number. This practice goes back at least to AT&T Unix System III (1980); recall that the functions of the standard I/O library were then documented in a "3S" section, presumably to remind the reader that, in those days, that library ("libS.a") required explicit linkage (I guess?) and didn't come in with the leaner, meaner, and older (and all-but-nameless?) default C library. The advent of ANSI C has made this history murky. Second, they can be distinguished in the identifier itself; for example, groff supports prefixing of commands with "g" to avoid collisions with other *roff installations. This prefix is reflected in the relevant man pages, and has been for many, many years. $ head -n 6 src/roff/troff/troff.1.man '\" t .TH @g@troff @MAN1EXT@ "@MDATE@" "groff @VERSION@" .SH Name @g@troff \- GNU .I roff typesetter and document formatter > > 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. I don't find it collegial to repeatedly accuse one of your fellow developers of lying. Is it not more likely that I'm simply mistaken? > 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. Define "page name". Is that the set of arguments to each (argumentful) `Nm` call in an mdoc(7) document? Or is it the argument to a `Dt` call? You cannot assert a total identity here; see the example below. > 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. I would disagree, however, I think I may discern where you're coming from here. I was surprised to observe that the following URL did not work... https://manpage.me/index.cgi?apropos=0&q=strlcat&sektion=3&manpath=OpenBSD+6.2&arch=default&format=html ...but this one did. https://manpage.me/index.cgi?apropos=0&q=strlcpy&sektion=3&manpath=OpenBSD+6.2&arch=default&format=html So am I to understand that on an OpenBSD system, "man strlcat" will just fail? That seems like a defect.[1] > 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. Uh, what if you need to document multiple commands or functions in one document? I'll grant, mdoc(7) seems to have planned for that contingency poorly. Not that I think that will stop you from trumpeting its superiority to man(7) in every conceivable application. > When documentating a user interface containing such gratuitious > differences, the last thing one should do is retroactively invent > rationalizations of the gratuitious quirks, I dispute that I am retroactively inventing justifications, but rather attempting to infer sometimes unarticulated properties and design criteria from concrete evidence, namely the corpus of historical Unix manuals, on the assumption that the people who prepared these manuals were not idiots or psychotics. > and even less so invent objectively wrong claims as to what these > quirks do, when in fact, they do nothing whatsoever. On my Debian-based system using man-db man(1), "man strlcat" works just fine to bring up a page identifying itself as "STRLCPY(3bsd)", which is installed as "/usr/share/man/man3/strlcpy.3bsd.gz". If mandoc(1) man(1) can't do the same, I'm not surprised that you're irritable. (I'm teasing.[1][4]) > > 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. Again, I am assuming that people other than myself are _not_ drooling morons, a notion that seems to come to you only with difficulty. Why is it stupid for one document (be it written with the man(7) or mdoc(7) macros) to present `strlcat` and `strlcpy` together? If it isn't stupid, why do you regard the distinction between these identifiers as vaporous, or the product of hallucination or contrivance on my part? Why doesn't the (presumably man.cgi(8)-based) man page search engine at manpages.me correctly resolve the following query? https://manpage.me/index.cgi?apropos=0&q=strlcat&sektion=3&manpath=OpenBSD+6.2&arch=default&format=html > 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. Perhaps you, as mandoc(1) maintainer, should pay more attention to them yourself. The distinction might explain the (presumably erstwhile) bug in man.cgi(8) that I think I am perceiving. > 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. I'm not inclined to defend the wisdom of ncurses's man pages' file naming practice, though over time I have come to discern (you might prefer the term "retroactively invent") potential reasons why the present scheme was undertaken.[2] Given time, and a receptive attitude on the part of Thomas Dickey, I'd like to make some reforms in that area, though. Since he still uses RCS, however, I'm apprehensive of his openness to file renames. Regards, Branden [1] Spoiler alert: the "man" from my copy of mandoc 1.14.6 (in a Termux environment on an Android tablet) doesn't fail in this way. Possibly the feature is broken in the version of man.cgi(8) that the "manpage.me" site is using, or that site is using some other engine altogether...but it sure does _look_ like man.cgi(8)'s presentation.[4] [2] The file naming scheme of ncurses for its man pages closely apes exhibits of Unix System V curses available to me. I suppose this has do with Eric Raymond deciding that the content of the pages wasn't really under copyright (a claim he made about the terminfo type description collection in source form), or that copyright encumbrances could be removed through a process he described as "reverse nroff[ing]", of which the only evidence I recall involves a would guess--sed(1)-driven procedure replacing man(7)'s font style macros with troff(1) font selection escape sequences.[3] When we consider the arguably growing consensus that the intake procedures of LLMs for "generative AI" similarly achieve the laundering of copyright through something analogous to the massive matrix multiplications of Markov manipulations,[5] Raymond may well prove to have been a man ahead of his time. [3] To reach this conclusion, I inspected diffs between ncurses 1.8.1, ncurses 1.8.5, and the curses-related man pages of Solaris 2.3, all of which are available on the Web. I invite anyone to undertake the same procedure and share their findings--and to correct me if I seem to be mistaken! Further background: https://invisible-island.net/ncurses/ncurses-license.html [4] https://mandoc.bsd.lv/man/man.cgi.8.html Blissfully, searching for "strlcat" works _there_. [5] On the one hand, https://apnews.com/article/anthropic-copyright-authors-settlement-training-f294266bc79a16ec90d2ddccdf435164 ...but on the other, out-of-court settlements are not constitutive of legal precedent.
signature.asc
Description: PGP signature
