Hi Mickaël,

On Tue, Feb 11, 2025 at 08:24:21PM +0100, Mickaël Salaün wrote:

quoted

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.

Well, I think I should develop what I said.  I think the quality of
generated documentation isn't good, compared to hand-written
documentation.  I wouldn't recommend in general generating man(7) pages,
just like I wouldn't recommend generating .rst documents.

However, given the assumption that you're going to generate the
documentation anyway from comments (which is what I recommend against),
generating man(7) source isn't worse than generating .rst docs.  I
personally don't like in-source comments either, so writing only man(7)
source is fine --I don't have the problem of keeping it up to date with
the comments; there's no duplication--.  If you're committed to
in-source comments, and your internal APIs change so often that it
wouldn't be reasonable to write documentation by hand (other than the
in-source comments), then it makes sense to generate man(7) pages in
the man9 section.

I'm going to release today the next version of the Linux man-pages
project, and have refreshed the bpf-helpers(7) manual page from Linux
source.  The process is pretty easy:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=ebfa53a052e70a1252051ba3ad99c3b5a87da42d>
	commit ebfa53a052e70a1252051ba3ad99c3b5a87da42d
	Author: Alejandro Colomar [off-list ref]
	Date:   Wed Feb 12 15:46:18 2025 +0100

	    man/man7/bpf-helpers.7: Refresh page from Linux v6.13
	    
	    Scripted change:
	    
		    $ ~/src/linux/linux/v6.13/scripts/bpf_doc.py \
		    | rst2man \
		    >man7/bpf-helpers.7;
	    
	    Signed-off-by: Alejandro Colomar [off-list ref]

	diff --git a/man/man7/bpf-helpers.7 b/man/man7/bpf-helpers.7
	[...]

So you could really use man9 for internal Landlock stuff.  Even if I
think generated documentation isn't ideal, it's better than nothing.
Being able to use man(1) for reading kernel documentation would still be
a nice feature.

And while I can't run all the linters that I run on hand-written docs on
generated pages (because generated source necessarily triggers many
false positives), I could still run some, which would trigger some
accidents in the docs, and would also detect bugs in the software
translating the docs from one language to another.

So, I'd still recommend you considering man9.

quoted

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.

I'm working hard on making it easier to contribute to the Linux
man-pages project.  Adding consistency to the existing pages makes it
easier to just look at the surrounding documentation and deduce how to
document some new feature.  The source is today much more
self-consistent than it was 5 years ago.

Also, me being paid to work on the project means significantly less time
to review something.  If I can do anything else to make it easier to
write man(7) and/or contribute via email, please let me know.

Yes, tools like b4(1) may not be ideal for working in two different
repos, but I expect that if you report that to Konstantin, he'll
probably have ideas for that.  I don't think that should be impossible
to fix.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>