Hi Alex, At 2022-06-09T10:57:07+0200, Alejandro Colomar wrote: > I guess you remember the discussion a few months ago about pages of > the form statx-struct(3). I do! > I'm still not convinced by that, because it means more typing, and > because it breaks with existing practice. libbsd for example just > puts timespec(3) in the global 3 section, with no -struct. Also, some > other UNIX systems don't put -struct, but move the pages to 3TYPE, a > subsection of 3. I think I like that way most, and that also fixes > the concerns that Michael had about shadowing other more important > pages, because we can just tell man-db to specify that 3TYPE should be > one of the last things to check. What do you think about it? 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, I would document the data types and global non-function symbols 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. 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.) 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 think I'm going to move all type pages to 3TYPE. Also, I don't know > if I should use a separate directory for that or use man3 and just > change the extension. What would you do? I see that debian just puts > everything in man? and then only changes the file extension, but there > are other systems that also change dirs, right? What should we do > upstream? I would ask that you not put "type" in full capitals. ;-) 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. 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. 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. These are just my opinions--I'm not an oracle. Regards, Branden
Attachment:
signature.asc
Description: PGP signature
