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