Date:   Fri, 22 Jul 2022 10:46:02 -0700
From:   "Darrick J. Wong" <djwong@...nel.org>
To:     Alejandro Colomar <alx.manpages@...il.com>
Cc:     Theodore Ts'o <tytso@....edu>, 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.

On Fri, Jul 22, 2022 at 04:32:45PM +0200, Alejandro Colomar wrote:
> 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.

I think you and I missed that discussion:
https://lore.kernel.org/linux-man/20210911160117.552617-1-alx.manpages@gmail.com/ 

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

I still think it's redundant to say that you have to link against the
standard C library -- it's a standard feature on Linux, and you have to
pass -nolibc to opt out of it.  Libraries that have to be opted-into
(e.g. -lpthread) should be documented here, but not stuff that's enabled
by default.

Oh well, you're the maintainer, it is your prerogative.

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

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

> 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. :)

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.

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

(There isn't any magical way to #include a manpage within another
manpage, is there?)

--D

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

Powered by blists - more mailing lists