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. 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. Cheers, Alex -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
