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 05:13:21PM +0100, Alejandro Colomar wrote:
> Hi!
> 
> On Tue, Feb 11, 2025 at 04:53:44PM +0100, Mickaël Salaün wrote:
> > > 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.
> 
> The official name of man9 is "Kernel Developer's Manual".
> In-scope in man9 are internal kernel APIs, and in general anything that
> is of interest to kernel developers but not to user-space developers.
> 
> >  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?
> 
> For generated documentation, I'd really avoid that.  Currently, in the
> man-pages we only have bpf-helpers(7), and I'd very much not follow that
> for other pages.

OK, kernel doc in man9 would not be a good fit then.

> 
> For APIs that change often, that may make sense, but in general, APIs
> shouldn't change significantly enough to prefer generated docs.
> 
> > > 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?
> 
> man9 is for internal kernel APIs.  Here's intro(9) in different systems,
> which documents what should go into man9, and what shouldn't:
> 
> <https://man.netbsd.org/intro.9>
> <https://man.openbsd.org/intro.9>
> <https://man.freebsd.org/cgi/man.cgi?query=intro&apropos=0&sektion=9&manpath=FreeBSD+14.2-RELEASE+and+Ports&arch=default&format=html>
> 
> Debian had a project which documented some Linux kernel internals in
> man9, but it was eventually dropped.  I don't know who maintained that,
> and what was the history about it.
> 
> If Landlock has internal documentation that only matters to kernel
> developers, yes, that would be in-scope for man9.  The user-facing docs
> are more relevant in man2 and man7, though.
> 
> I would be happy to take all the landlock docs in the form of man9 pages
> if you handle them to the Linux man-pages project.  I can do the work of
> transforming the .rst docs into man(7) pages; that's fine by me.
> 
> If there's consensus in the kernel of moving to man9 docs, I'd be happy
> to help with that.  I fear that some maintainers may fear man(7) pages.
> If you need me to give any talks to explain how to write man(7) source
> code, and show that it's easier than it looks like, I could do that
> (Günther already suggested me to do so :).  Maybe I should give a talk
> at Plumbers.

It would be interesting to get the point of view of other kernel
maintainers but I guess a lot of them would have the same: to lower the
bar of contributions.

> 
> 
> Cheers,
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>