Hello! On Wed, Feb 26, 2025 at 09:57:58PM +0100, Alejandro Colomar wrote: > On Wed, Feb 26, 2025 at 08:24:22PM +0000, Günther Noack wrote: > > On Wed, Feb 12, 2025 at 04:06:06PM +0100, Alejandro Colomar wrote: > > > 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. > > > > This is different to the BPF helpers; Landlock's existing man pages document > > user space APIs, and the largest part of the kernel-side .rst documentation for > > Landlock also covers only user space. > > Huh! Why does the kernel duplicate what's already in the manual pages? That duplication is *precisely* the problem we have in Landlock. :) (If you look at the patch series I've been sending with both the patches sent to linux-security-modules@ and linux-man@, you'll see the duplication, e.g. https://lore.kernel.org/all/20250226211814.31420-2-gnoack@xxxxxxxxxx/) Documentation of user space APIs is not unusual in the kernel documentation, there is the entire subdirectory Documentation/userspace-api for it. —Günther
