lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Fri, 22 Jul 2022 09:55:24 -0400
From:   "Theodore Ts'o" <tytso@....edu>
To:     "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
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.

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.   (And that's especially necessary for stat(2), BTW!)

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?

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.

https://www.npr.org/sections/13.7/2014/02/03/270680304/this-could-have-been-shorter

      	     	       	       		- Ted

Powered by blists - more mailing lists