Hi Darrick, On 7/22/22 19:46, Darrick J. Wong wrote:
Now that you say it, I forgot to document the LIBRARY section in man-pages(7). There's something about it, but I forgot to add a paragraph describing it in detail.That would've helped, since I scanned https://man7.org/linux/man-pages/man7/man-pages.7.html and didn't see much about what goes in this section...
These changes have been introduced after the last release was made, so even if I had documented it, it wouldn't have reached <man7.org>. I'd recommend you to install the man pages from source (`sudo make install`).
Regarding the EXAMPLES section, every page in man2 or man3 should have an example program, IMO. Consider that there are programmers that may find it easier to learn a function by experimenting with a working example of C code, rather than a dense textual description in a language that may not be native to the programmer.Frankly I'd rather push people to have example code over documenting that standard C library functions require the standard C library. :)
Agreed :)
That said, I don't always enjoy the textbook examples that have been slimmed down for manpages -- I prefer a link to a real implementation in (say) the test suite so that I can see code that (one would hope) exercises all the functionality exposed through the interface. But I guess that's really up to the manpage author to decide.
They're not exclusive. It's welcome to point to a (stable) link showing a more complex example after showing a simple example that fits the page.
There are many pages that lack examples, but that's not something I would consider a good thing.Some the suggestions you are making don't seem to be adhered to by the existing man pages, and more text is not always better.The next release of the man-pages is certainly going to be an important one. It may be hated by many, loved by many others. I hope overall I did a significant improvement in both improving the transmission of information and simplifying maintenance.I'm not convinced that having to open *two* manpages just to figure out how to call an ioctl is going to simplify maintenance unless the struct is shared across more than one manpage, but I've already made that point.
Well, I'd say it simplifies maintenance in the case that another page adds information about this type: when I receive a patch, I'm not grepping all of the pages to see if one already documents a type, to decide to move it to a separate page. It's likely to be forgotten, and the documentation about the type duplicated (and they are likely to get out of sync).
When I added the type pages, I found many types to be documented differently on different pages, needing to copy parts of every page to get the full picture, because none of them was complete. That's especially what I'm trying to avoid.
Still, there are many more important types to document in the type pages, and if you consider that this one is very unlikely to be shared in the long term, then I don't strongly oppose to it being in the same page as the ioctl that uses it for now.
(There isn't any magical way to #include a manpage within another manpage, is there?)
Oh, there is. It's the groff(7) .so request, which is basically the same as C's #include directive. We actually use it a lot in the man-pages, to create link pages (a page whose only content is a .so request, which basically means its contents are the same as another pages'). See for example:
$ cat man2/lstat.2 .so man2/stat.2Technically, it could be used differently, to include a man page as part of another page, but it hasn't been done ever, as it would probably complicate how man pages are stored, indexed, and searched in the filesystem (there's no </usr/share/man/include/> or </usr/inlucde/man/> directory or something like that).
Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
