Hello Alejandro, Alejandro Colomar wrote on Tue, Sep 23, 2025 at 12:50:54PM +0200:
> Michael Kerrisk reported to me that he preferred the old proc(5) page, > where everything under /proc was in a single page. > > The rationale is that it was possible to search through that page with > less(1), and you didn't need to know where it was what you were > searching for. > > He proposed reverting the splits of proc(5), I agree that is indeed approaching the task at the wrong level. Showing multiple manual pages at the same time is a job for the manual page viewer man(1), not for the manual page formatter, for example nroff(1) or mandoc(1). For example, with the mandoc implementation of man(1): $ man true false shows the true(1) manual page, followed by a separating line: ------------------------------------------------------------------------------ followed by the false(1) manual page. The entire output is shown in a single less(1) instance as if it were a single output file, with no need to type ":n" to get to the next manual page. Consequently, it is trivial to search for strings across the whole output, across all pages, with just the less "/" command, or to perform semantic searches across all pages with just the less ":t" command. At the same time, even flipping through the pages page-by-page becomes slightly easier because /^- n n n ? ENTER n n n is slightly less typing effort than: :n :n :n :p :p :p > which I refuse to do, but > I think he has a point. I refuse to do so, because I agree with > something Doug complained about, which is that some of the pages we have > are not really pages, but rather entire books, and for me it has > important maintenance costs (plus, it's easier for me to find stuff with > small pages; but that seems to be subjective, depending on your > specific needs and experience). Keeping pages down to a reasonable size also helps users because making head or tail of a gigantic page is hard, and reading a page of a reasonable size is much easier. Stuff like https://man.openbsd.org/rpc.3 https://man.openbsd.org/PEM_read_bio_PrivateKey.3 https://man.openbsd.org/compress.3 places serious strain on user's eyes, including because the place where any particular function is discussed in the SYNOPSIS and DESCRIPTION and RETURN VALUES is then so far apart. > Right now, the only way for searching something across several pages is > going to /usr/share/man/, and doing a manual search there. This was > already true in the general case, before the split of pages. For > example, if one wanted (or wants) to know where FD_CLOEXEC is specified, $ man -ak Dv=FD_CLOEXEC puts me into less(1), where i type :tFD_CLOEXEC or /FD_CLOEXEC to my heart's content. [...] > (We may want for example an FD_CLOEXEC.2const manual page to link to the > canonical page for it, but I'm not yet decided, because that could mean > lots and lots of new link pages. I'm open to comments about that.) You could simply add FD_CLOEXEC as a name to the NAME section that you consider canonical for defining FD_CLOEXEC, such that users can simply type "man FD_CLOEXEC". We don't to that in OpenBSD because when semantic search is available, "man FD_CLOEXEC" provides little benefit over "man -ak Dv=FD_CLOEXEC" or "man -ak any=FD_CLOEXEC", so just as you consider additional links in the file system excessively noisy, we consider even (less noisy) additional name section entries too noisy. Don't forget that defined constants are significantly more numerous in some APIs than function names, so there is a real danger to cause readers to miss the forest among all the additional trees. > My idea is having a proc(7) page that would essentially be built as: > > $ find man5/ | grep proc | sort | sed 's/^/.so /' > man7/proc.7; I'd very strongly advise against that, for more than one reason. Neither of the two manual page formats is well-suited for concatenating input files and formatting them in a single run of the formatter. Doing that tends to cause lots of unexpected and hard to diagnose issues. Instead, such a job should be done by man(1): let the formatter format each page individually, then concatenate the results, *never* concatenate the source code. Also, this would result in massive multiplication of installed text (wasting space) and in massive degradation of apropos(1) usefulness as proc(7) would appear in each and every search result with a semantic seach tool like mandoc apropos(1) - or showing up in almost no search results with non-semantic seach tools like man-db because the man-db implementation of database generation cannot handle concatenated manual pages. Manual pages using fragment concatenation are most notorious for causing all kinds of trouble. IIRC, zsh(1) used to be a particularly egregious example (i hope i don't misremeber which shell that was, sorry to them if i do), but even they stopped concatenating at some point unless i'm mistaken. [...] > What do you think? I expect you will be very surpised in how many different ways such a scheme will bite you if, God forbid, you ever try it for real. Yours, Ingo
