mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Aleksa Sarai <cyphar@cyphar.com>
To: Alejandro Colomar <alx@kernel.org>
Cc: "Michael T. Kerrisk" <mtk.manpages@gmail.com>,
	 Alexander Viro <viro@zeniv.linux.org.uk>,
	Jan Kara <jack@suse.cz>, Askar Safin <safinaskar@zohomail.com>,
	 "G. Branden Robinson" <g.branden.robinson@gmail.com>,
	linux-man@vger.kernel.org, linux-api@vger.kernel.org,
	 linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org,
	 David Howells <dhowells@redhat.com>,
	Christian Brauner <brauner@kernel.org>
Subject: Re: [PATCH v4 04/10] man/man2/fsconfig.2: document "new" mount API
Date: Wed, 24 Sep 2025 16:41:16 +1000	[thread overview]
Message-ID: <2025-09-24-sterile-elderly-drone-sum-LHA7Fs@cyphar.com> (raw)
In-Reply-To: <e4jtqbymqguq64zup5qr6rnppwjyveqdzvqdbnz3c7v55zplbs@6bpdfbv6sh7d>

[-- Attachment #1: Type: text/plain, Size: 1400 bytes --]

On 2025-09-21, Alejandro Colomar <alx@kernel.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...

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

  reply	other threads:[~2025-09-24  6:41 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-09-19  1:59 [PATCH v4 00/10] man2: " Aleksa Sarai
2025-09-19  1:59 ` [PATCH v4 01/10] man/man2/mount_setattr.2: move mount_attr struct to mount_attr(2type) Aleksa Sarai
2025-09-19 16:04   ` Alejandro Colomar
2025-09-19  1:59 ` [PATCH v4 02/10] man/man2/fsopen.2: document "new" mount API Aleksa Sarai
2025-09-19 16:24   ` Alejandro Colomar
2025-09-19 21:19     ` Aleksa Sarai
2025-09-21  1:33       ` Aleksa Sarai
2025-09-21  8:39         ` Alejandro Colomar
2025-09-19  1:59 ` [PATCH v4 03/10] man/man2/fspick.2: " Aleksa Sarai
2025-09-21  8:53   ` Alejandro Colomar
2025-09-21 14:55     ` Aleksa Sarai
2025-09-21 15:17       ` Alejandro Colomar
2025-09-22  0:25   ` Askar Safin
2025-09-19  1:59 ` [PATCH v4 04/10] man/man2/fsconfig.2: " Aleksa Sarai
2025-09-21  9:26   ` Alejandro Colomar
2025-09-24  6:41     ` Aleksa Sarai [this message]
2025-09-24  8:52       ` Alejandro Colomar
2025-09-19  1:59 ` [PATCH v4 05/10] man/man2/fsmount.2: " Aleksa Sarai
2025-09-21 23:08   ` Askar Safin
2025-09-22  1:10     ` Askar Safin
2025-09-19  1:59 ` [PATCH v4 06/10] man/man2/move_mount.2: " Aleksa Sarai
2025-09-19  1:59 ` [PATCH v4 07/10] man/man2/open_tree.2: " Aleksa Sarai
2025-09-21  9:47   ` Alejandro Colomar
2025-09-22 10:09     ` Aleksa Sarai
2025-09-22 13:22       ` Alejandro Colomar
2025-09-24  1:34         ` Aleksa Sarai
2025-09-19  1:59 ` [PATCH v4 08/10] man/man2/mount_setattr.2: mirror opening sentence from fsopen(2) Aleksa Sarai
2025-09-21  9:50   ` Alejandro Colomar
2025-09-21 10:03     ` Aleksa Sarai
2025-09-21 10:19       ` Alejandro Colomar
2025-09-19  1:59 ` [PATCH v4 09/10] man/man2/open_tree{,_attr}.2: document new open_tree_attr() API Aleksa Sarai
2025-09-21  9:55   ` Alejandro Colomar
2025-09-24  6:31     ` Aleksa Sarai
2025-09-24  8:51       ` Alejandro Colomar
2025-09-19  1:59 ` [PATCH v4 10/10] man/man2/{fsconfig,mount_setattr}.2: add note about attribute-parameter distinction Aleksa Sarai
2025-09-19 12:23   ` Aleksa Sarai
2025-09-21  9:59   ` Alejandro Colomar
2025-09-22  1:06   ` Askar Safin
2025-09-21  2:43 ` [PATCH v4 00/10] man2: document "new" mount API Askar Safin
2025-09-21  9:58   ` Aleksa Sarai
2025-09-24 11:11     ` Aleksa Sarai

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=2025-09-24-sterile-elderly-drone-sum-LHA7Fs@cyphar.com \
    --to=cyphar@cyphar.com \
    --cc=alx@kernel.org \
    --cc=brauner@kernel.org \
    --cc=dhowells@redhat.com \
    --cc=g.branden.robinson@gmail.com \
    --cc=jack@suse.cz \
    --cc=linux-api@vger.kernel.org \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    --cc=safinaskar@zohomail.com \
    --cc=viro@zeniv.linux.org.uk \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®