Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

["Mickaël Salaün" <mic@digikod.net>]

On Tue, Feb 11, 2025 at 04:27:04PM +0100, Alejandro Colomar wrote:
> Hey Mickaël!

Hey!

> 
> On Tue, Feb 11, 2025 at 04:17:30PM +0100, Mickaël Salaün wrote:
> > On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> > > * Fix some whitespace, punctuation and minor grammar
> > > * Add a missing sentence about the minimum ABI version,
> > >   to stay in line with the section next to it
> > > 
> > > Cc: Mickaël Salaün <mic@digikod.net>
> > > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > > Signed-off-by: Günther Noack <gnoack@google.com>
> > 
> > Looks good, thanks!
> > 
> > I'm going to take this patch in my tree with the changes explained
> > below. You can send a v2 with the second patch according to the reviews.
> > 
> > As a side note, applying the patch series from this thread with b4
> > doesn't work because they apply to different repositories.
> > 
> > Dealing with duplicated doc in two repositories is not practical and
> > adds work to everyone...  Could we move the non-libc syscall man pages
> > to the kernel repository?
> 
> Let me suggest the opposite: Could we move the kernel docs to manual
> pages in man9?  (As is the historic place for kernel docs.)
> (You could keep man9 in the kernel tree if you want, or could handle it
>  to the Linux man-pages project, if you want.)  That would help have a
> more clear separation between the two sets of documentation, and prevent
> duplication.

I didn't know about man9 but it's not clear to me what would be the
content.  Because I want new kernel features to come with proper tests
and documentation, it would be much easier to apply all these patches to
the same repository, at the same time.  Using the same repository should
also help to synchronize documentation with code changes.

One remaining issue would be that some generated documentation come from
the kernel source files, especially the UAPI headers, which also helps
maintaining the documentation in sync with the code.  What would you
suggest to improve the current workflow?

> 
> I personally don't like the idea of having man2 in the kernel tree.
> Michael Kerrisk already mentioned several reasons for why it's a bad
> idea in the past.  On top of them, I'd add that the build system of the
> Linux man-pages project is quite more powerful than the kernel one, and
> it would be an important regression to have to adapt to the kernel
> Makefiles in the manual pages.

For the Landlock syscalls case, could we move the syscall documentation
to man9?

> 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>