Hi Branden, On 6/18/22 18:39, G. Branden Robinson wrote:
I think we're bumping into (1) inherent limitations of manual sectioning; (2) the growing diversity of implementation languages used in *nix development; and (3) long-standing practices of incomplete library documentation. Points (1) and (2) are coupled. A Perl programmer often doesn't need to see manual pages about C libraries, so the practices of (A) prefixing Perl-related man pages with a "perl" prefix in their names and (B) putting those man pages in a bespoke section called "3perl" have arisen. Neither is a wonderful solution because, as you note, they can require more typing. I therefore have some mild reservations about a different, new section suffix called "type". C isn't the only language that has types. So I think this practice pushes a problem to the future, where addressing it via the same means will become _more_ cumbersome. Imagine a future where we have section suffixes "perltypes" and "pythontypes". These problems aren't as bad as they could be because factor (3) rides to the rescue. Faced with a difficulty in placing documentation sensibly, fast-moving developers make the decision either to not write documentation in manual page format, or not to write it at all. In a fantasy world, albeit one where I'm curiously confined to the C language,
Oh, what a wonderful fantasy world! :D
I would document the data types and global non-function symbols
You were reading my mind, were you?Not that I plan to do it soon (first come the types, and that may take many, many years), but I do have a longstanding wish of documenting all symbols. I'd like to be able to do things such as `man IOV_MAX`. I still don't know how to implement that, but documenting headers in section 0 and then adding link pages with the names of the macros defined in them is one of the ideas. I'll be accepting suggestions, if you wish to propose them.
exposed by a library interface in a man page named for its header file. I would also include there a list of functions exposed by the library, possibly with some synoptic information.
I have a conflict with that. I like the idea of having all of the functions defined by a header listed (not documented) together, so that it may help discover similar functions better suited for a specific job, that one might not have known otherwise.
But I don't like the idea of duplicating documentation, including the synopsis, because that will mean more maintenance costs. See that I've been cleaning definitions of types in function pages after having them documented in type pages:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=cb3366169531510bcc7d445e15df68396291a05d> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=6c809df77b359bb3a9e06f32547e0aed155408be>Pages like string(3) work like a SEE ALSO, and we already have SEE ALSO. I've also considered having includes with the prototypes, which could be included from various pages, but that's something I'm willing to do, because having standalone pages is also much easier to handle.
stdio(3) and ncurses(3) are pretty good examples of how to do this, though in my opinion neither of them does enough to help the programmer organize the large number of provided functions in their brain. (ncurses has categorical pages, but unfortunately doesn't make them visible until you visit them, and its API, largely for historical reasons, has multiple orthogonal axes--sometimes you need a "w" prefix for window addressing, and sometimes you need a "w" infix or suffix to indicate the use of a wide character type in the argument list.)
Basically the same problems as SEE ALSO. You don't know what they're about, until it's too late :)
Nevertheless, I don't think moving things to "3type" is a choice that it will be painful to unwind later (should the need arise) in terms of user experience. Most people won't want to mess with typing "[-s] 3type" before the page name they want, so they won't. They therefore won't develop a habit they have to be trained out of later. Where "3type" can do the most good is probably in the manual section search order. So even if it's not an optimal solution, it can still be a good idea. I'd judge it like this: does the change bring order to chaos by improving topical coverage and/or discoverability? Does it impose technical debt?
I've already done it: <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=178eaf37e2e971cae88bd4d3f124ede0afbb1015> I think it was a good move.
I would ask that you not put "type" in full capitals. ;-)
Didn't.
In the abstract there is no problem with having all of these pages in man3 upstream, if you aim to reflect the section suffixes in the file names. There will be no name collisions.
I was thinking more about having them better organized. I prefer having many dirs with few files, rather than unreadable ls(1) output.
It's always easier to merge dirs rather than split dirs, although in this case, it's pretty much the same difficulty (low).
Historically there have been problems with file system performance when directories accumulate a lot of entries. As far as I know this isn't a problem on any modern, commonly-used file system. Further, my Git checkout says that the Linux man-pages project has only about 1,700 files in the man3 directory. The performance problems I've heard about arise when the number of dirents is greater by an order of magnitude or more. No matter how diligent you are as a technical writer, it's going to be hard to swell the man-pages corpus to that degree. :) If distributors need to change the arrangement to suit their performance requirements, they are better placed to do so. It is a choice that has most of its impact at run time anyway, and distribution packaging systems are well practiced at rearranging their upstreams' "make install" results.
Actually, I've been working hard on providing a very flexible Makefile that should work unmodified for as many distributors as possible. That's why I considered that having the Makefile install into separate dirs, and let the distributor merge them later, could be a good idea.
But since the smallest diff for the Makefile was to use a single one, I did that for now.
For development and maintenance of the man pages themselves, I think retaining the existing directory structure has the virtues of keeping things simpler and not confusing new contributors with an organizational distinction that doesn't communicate any new information.
I think it is easier with one dir, but for another reason: less typing/better autocomplete.
These are just my opinions--I'm not an oracle.
I tend to like your opinions. I'll keep asking your Oracle ;). Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
