Date:   Fri, 22 Jul 2022 16:32:45 +0200
From:   Alejandro Colomar <alx.manpages@...il.com>
To:     Theodore Ts'o <tytso@....edu>
Cc:     "Darrick J. Wong" <djwong@...nel.org>,
        Jeremy Bongio <bongiojp@...il.com>, linux-ext4@...r.kernel.org,
        linux-man@...r.kernel.org
Subject: Re: [PATCH v2] Add manpage for get/set fsuuid ioctl for ext4
 filesystem.

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/>

Download attachment "OpenPGP_signature" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists