linux-kernel - Re: [PATCH v4 04/10] man/man2/fsconfig.2: document "new" mount API

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]

Message-ID: <rvnb5wxpu2emzbs7iprqzxqom4yioguxsiyl4gfxcyr6hjfs3v@kqrfrrfsoa7s>
Date: Wed, 24 Sep 2025 10:52:57 +0200
From: Alejandro Colomar <alx@...nel.org>
To: Aleksa Sarai <cyphar@...har.com>
Cc: "Michael T. Kerrisk" <mtk.manpages@...il.com>, 
	Alexander Viro <viro@...iv.linux.org.uk>, Jan Kara <jack@...e.cz>, Askar Safin <safinaskar@...omail.com>, 
	"G. Branden Robinson" <g.branden.robinson@...il.com>, linux-man@...r.kernel.org, linux-api@...r.kernel.org, 
	linux-fsdevel@...r.kernel.org, linux-kernel@...r.kernel.org, 
	David Howells <dhowells@...hat.com>, Christian Brauner <brauner@...nel.org>
Subject: Re: [PATCH v4 04/10] man/man2/fsconfig.2: document "new" mount API

Hi Aleksa,

On Wed, Sep 24, 2025 at 04:41:16PM +1000, Aleksa Sarai wrote:
> On 2025-09-21, Alejandro Colomar <alx@...nel.org> wrote:
> > On Fri, Sep 19, 2025 at 11:59:45AM +1000, Aleksa Sarai wrote:
> > > +The list of valid
> > > +.I cmd
> > > +values are:
> > 
> > I think I would have this page split into one page per command.
> > 
> > I would keep an overview in this page, of the main system call, and the
> > descriptions of each subcommand would go into each separate page.
> > 
> > You could have a look at fcntl(2), which has been the most recent page
> > split, and let me know what you think.
> 
> To be honest, I think this makes the page less useful to most readers.
> 
> I get that you want to try to improve the "wall of text" problem but as
> a very regular reader of man-pages, I find indirections annoying every
> time I have to do deal with them. Maybe there is an argument for
> fcntl(2) to undergo this treatment (as it has a menagerie of disparate
> commands) but this applies even less to fsconfig(2) in my view.
> 
> If you feel strongly that fsconfig(2) needs this treatment, it would
> probably be better for you to do it instead. In particular, I would've
> expected to only have two extra pages if we went that route (one for
> FSCONFIG_SET_* commands and one for FSCONFIG_CMD_* commands) so I'm not
> quite sure what you'd like the copy to look like for 10 man-pages...

Okay, let's keep it as a single page for now.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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