Hi Lennart, Lennart Jablonka wrote on Tue, Aug 22, 2023 at 05:56:51PM +0000: > Quoth Ingo Schwarze: >> Lennart Jablonka wrote: >>> G. Branden Robinson wrote:
>>>> 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. > I recognize the burden it would be on the maintainers. I do feel like > you’re exaggerating: How often does it change which man page a function > or whatever is documented in? In OpenBSD, i'd estimate such cases arise roughly every few weeks on average. Since OpenBSD is a relatively compact system focussing on stability and simplicity, i'd expect the rate being larger in more modularized, larger, and more feature-hungry systems. Besides, while the work involved in maintaining cross references among manual pages does not constitute the majority of work when maintaining manual pages, it is not insignificant either, in particular when it comes to larger libraries like OpenSSL or LibreSSL. Even with the current, simple scheme, i have spent many days of work on improving cross references, and i have watched others do similar work. > But then, I don’t work on man pages nearly as much as you do. >> Besides, "using putp (see terminfo(3))" looks ugly, is unnecessarily >> wordy, and causes a distraction of the reader for not benefit >> whatsoever. > Oh, but there is a benefit: If you print your collection of man pages, > calling it something like “OpenBSD Programmer’s Manual,” the man pages > will be sorted by their titles. If done well, you’ll also have a KWIC > index of the NAME lines, but it’s still easier to find the page you’re > looking for if you have the title directly. In particular when you care about locating information quickly and easily, putting it on dead trees is a very bad idea. KWIC was a great idea when invented more than 150 years ago and still quite useful when used for the AT&T UNIX manuals in the 1970ies (because they didn't have CRT displays at Bell Labs at first). Even though i did have a monochrome CRT when using HP200 machines in the 1980ies, i still used printed documentation because those machines had no hard disks and the floppies they used weren't even large enough to hold the complete operation system, let alone documentation, and swapping floppies and waiting for them to be read would have been awkward. But i'd say printed software documentation became obsolete roughly around 1990. Nowdays, i have a hard time taking KWIC seriously even as a crude workaround for a lack of semantic search and regular expression capabilities. > That’s not much of a concern today. Few projects today of those that > have many man pages collect them in one work. Groff does; man-pages > does. Stanley Lieber provides printed man pages for 9front.¹ > ¹ https://9front.org/propaganda/books That looks like a work of love, aesthetic enjoyment, and nostalgia to me. But making the text harder to read for users reading manuals at the command line or on the web and harder to maintain at the same time, to marginally help searchability of the printed version, which remains atrocious by today's standards either way - what a bad tradeoff... > An OpenBSD Programmer’s Manual? I’d like to see that, but I doubt > anyone will do it. Still, it is a concern. For those who feel > good about being able to print man pages, at least. Every user would have to print and re-print that over and over again, each time on freshly killed trees, at least twice a years. Some users are updating their OpenBSD systems as often as weekly... > You could observe project boundaries. Ncurses man pages could refer to > curs_terminfo(3X), Groff to putp(3) (were it to refer to putp at all). > That would work if it wasn’t too complicated for all those independent > man page authors. Except, of course, that someone integrating man > pages from a different project won’t want to change how those man pages > reference others. To go through ncurses’ man pages, changing “sscanf(3)” > to “sscanf (see scanf(3)).” Sure, it's not a big deal if different projects use different styles, including somewhat awkward, cumbersome, redundant and error-prone styles like "sscanf (see scanf(3))". My point is that you tried to tell people the simplest, most widespread way of always referencing the function most relevant in the context, which is also easiest to read, easiest to maintain, and least error-prone, is somehow bad, and that you labeled a somewhat idiosyncratic style that is unlikely to work well in practice as "the correct way". Trying to justify that, you also used the ill-defined and undefinable terminology "*the* name of a manual page" (which you snipped here). Yours, Ingo
