Hi Ted, On 7/22/22 15:55, Theodore Ts'o wrote:
On Fri, Jul 22, 2022 at 12:03:23PM +0200, Alejandro Colomar (man-pages) wrote:SEE ALSO ioctl(2) at the end of an ioctl_XXX manpage like this one.Okay. Then may I ask for an EXAMPLES section with a program that unequivocally shows users how to use it?I'll note that existing ioctl man pages don't have an explicit statement that a libc is required --- nor do we do this for open(2), stat(2), etc.
That's because there hasn't been a man-pages release in around a year.If you see the man-pages git repo, you'll see that (almost) all man pages in sections 2 and 3 have a new LIBRARY section.
ioctl(2) pages now have this LIBRARY section: <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/ioctl_fat.2> This was based on FreeBSD's man pages: <https://www.freebsd.org/cgi/man.cgi?query=stat&apropos=0&sektion=2&manpath=FreeBSD+13.1-RELEASE+and+Ports&arch=default&format=html>
(And that's especially necessary for stat(2), BTW!)
stat(2) now says <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/stat.2#n22>:
LIBRARY
Standard C library (libc, -lc)
If you would like to improve on that, I'm open to ideas, or patches from
programmers who know the syscalls much better than I do.
Many of the ioctl man pages (or other system call man pages, for that matter) also don't have an EXAMPLES section, either. Perhaps it would be useful to have a discussion over what the standards are for man pages in section 2, and when we need to state things that seem to be rather obvious (like "you must have a C library") and when there should be things like an EXAMPLES section?
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.
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.
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.
https://www.npr.org/sections/13.7/2014/02/03/270680304/this-could-have-been-shorter
Sorry, but I'm not able to read that page. It prompts the usual GPDR notice, and doesn't give me the option to reject cookies (only accept).
Anyway, I guess what it says. I hope I wasn't too much verbose with my many changes.
Cheers, Alex -- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
