Hi Mickaël, On Tue, Feb 11, 2025 at 08:24:21PM +0100, Mickaël Salaün wrote: > > 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. 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 <alx@xxxxxxxxxx> 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 <alx@xxxxxxxxxx> 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. > > 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. 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/>
Attachment:
signature.asc
Description: PGP signature
