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:

quoted

quoted

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.

quoted

 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.

quoted

quoted

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/>