Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> * Fix some whitespace, punctuation and minor grammar
> * Add a missing sentence about the minimum ABI version,
>   to stay in line with the section next to it
> 
> Cc: Mickaël Salaün <mic@digikod.net>
> Cc: Tahera Fahimi <fahimitahera@gmail.com>
> Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> Signed-off-by: Günther Noack <gnoack@google.com>

Looks good, thanks!

I'm going to take this patch in my tree with the changes explained
below. You can send a v2 with the second patch according to the reviews.

As a side note, applying the patch series from this thread with b4
doesn't work because they apply to different repositories.

Dealing with duplicated doc in two repositories is not practical and
adds work to everyone...  Could we move the non-libc syscall man pages
to the kernel repository?

> ---
>  Documentation/userspace-api/landlock.rst | 4 ++--
>  include/uapi/linux/landlock.h            | 6 ++++--
>  2 files changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index d639c61cb472..ca8b325d53e5 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -329,11 +329,11 @@ non-sandboxed process, we can specify this restriction with
>  A sandboxed process can connect to a non-sandboxed process when its domain is
>  not scoped. If a process's domain is scoped, it can only connect to sockets
>  created by processes in the same scope.
> -Moreover, If a process is scoped to send signal to a non-scoped process, it can
> +Moreover, if a process is scoped to send signal to a non-scoped process, it can
>  only send signals to processes in the same scope.
>  
>  A connected datagram socket behaves like a stream socket when its domain is
> -scoped, meaning if the domain is scoped after the socket is connected , it can
> +scoped, meaning if the domain is scoped after the socket is connected, it can
>  still :manpage:`send(2)` data just like a stream socket.  However, in the same
>  scenario, a non-connected datagram socket cannot send data (with
>  :manpage:`sendto(2)`) outside its scope.
> diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
> index 33745642f787..048a2c77c4eb 100644
> --- a/include/uapi/linux/landlock.h
> +++ b/include/uapi/linux/landlock.h
> @@ -268,7 +268,7 @@ struct landlock_net_port_attr {
>   * ~~~~~~~~~~~~~~~~
>   *
>   * These flags enable to restrict a sandboxed process to a set of network
> - * actions. This is supported since the Landlock ABI version 4.
> + * actions. This is supported since Landlock ABI version 4.

If that's OK with you, I'll move this sentence to a standalone paragraph
like the one you added below:

+ * actions.
+ *
+ * This is supported since Landlock ABI version 4.

>   *
>   * The following access rights apply to TCP port numbers:
>   *
> @@ -291,11 +291,13 @@ struct landlock_net_port_attr {
>   * Setting a flag for a ruleset will isolate the Landlock domain to forbid
>   * connections to resources outside the domain.
>   *
> + * This is supported since Landlock ABI version 6.
> + *
>   * Scopes:
>   *
>   * - %LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET: Restrict a sandboxed process from
>   *   connecting to an abstract UNIX socket created by a process outside the
> - *   related Landlock domain (e.g. a parent domain or a non-sandboxed process).
> + *   related Landlock domain (e.g., a parent domain or a non-sandboxed process).
>   * - %LANDLOCK_SCOPE_SIGNAL: Restrict a sandboxed process from sending a signal
>   *   to another process outside the domain.
>   */
> -- 
> 2.48.1.262.g85cc9f2d1e-goog
> 
> 

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1846 bytes --]

Hey Mickaël!

On Tue, Feb 11, 2025 at 04:17:30PM +0100, Mickaël Salaün wrote:
> On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> > * Fix some whitespace, punctuation and minor grammar
> > * Add a missing sentence about the minimum ABI version,
> >   to stay in line with the section next to it
> > 
> > Cc: Mickaël Salaün <mic@digikod.net>
> > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > Signed-off-by: Günther Noack <gnoack@google.com>
> 
> Looks good, thanks!
> 
> I'm going to take this patch in my tree with the changes explained
> below. You can send a v2 with the second patch according to the reviews.
> 
> As a side note, applying the patch series from this thread with b4
> doesn't work because they apply to different repositories.
> 
> Dealing with duplicated doc in two repositories is not practical and
> adds work to everyone...  Could we move the non-libc syscall man pages
> to the kernel repository?

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


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

On Tue, Feb 11, 2025 at 04:27:04PM +0100, Alejandro Colomar wrote:
> Hey Mickaël!

Hey!

> 
> On Tue, Feb 11, 2025 at 04:17:30PM +0100, Mickaël Salaün wrote:
> > On Fri, Jan 24, 2025 at 03:44:44PM +0000, Günther Noack wrote:
> > > * Fix some whitespace, punctuation and minor grammar
> > > * Add a missing sentence about the minimum ABI version,
> > >   to stay in line with the section next to it
> > > 
> > > Cc: Mickaël Salaün <mic@digikod.net>
> > > Cc: Tahera Fahimi <fahimitahera@gmail.com>
> > > Cc: Tanya Agarwal <tanyaagarwal25699@gmail.com>
> > > Signed-off-by: Günther Noack <gnoack@google.com>
> > 
> > Looks good, thanks!
> > 
> > I'm going to take this patch in my tree with the changes explained
> > below. You can send a v2 with the second patch according to the reviews.
> > 
> > As a side note, applying the patch series from this thread with b4
> > doesn't work because they apply to different repositories.
> > 
> > Dealing with duplicated doc in two repositories is not practical and
> > adds work to everyone...  Could we move the non-libc syscall man pages
> > to the kernel repository?
> 
> 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.  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?

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

> 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3479 bytes --]

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1009 bytes --]

At 2025-02-11T17:13:21+0100, Alejandro Colomar wrote:
> 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.

Consider me a resource for this purpose as well.  I gave a talk on this
very subject at DebConf 5 (not a typo, that was 2005),[1] and have some
familiarity with the man(7) macro package, its history in various
Unices, its groff implementation, and the underlying language of the
formatter, troff/nroff, which were developed at the Bell Labs Computing
Science Research Center contemporaneously with, and by the same group
as, the Unix kernel.

Regards,
Branden

[1] https://web.archive.org/web/20071015000604/http://people.debian.org/~branden/talks/wtfm/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1594 bytes --]

Hi Branden,

On Tue, Feb 11, 2025 at 12:08:51PM -0600, G. Branden Robinson wrote:
> At 2025-02-11T17:13:21+0100, Alejandro Colomar wrote:
> > 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.
> 
> Consider me a resource for this purpose as well.  I gave a talk on this
> very subject at DebConf 5 (not a typo, that was 2005),[1] and have some
> familiarity with the man(7) macro package, its history in various
> Unices, its groff implementation, and the underlying language of the
> formatter, troff/nroff, which were developed at the Bell Labs Computing
> Science Research Center contemporaneously with, and by the same group
> as, the Unix kernel.

Yup!  Maybe we can prepare a talk together?  I mean two speakers.  You
certainly know things I don't, and I probably have other points of view
that are interesting.

I think we could meet IRL eventually to prepare something like this.
I'll probably be in the US a couple of times in 2025 (one C Committee
meeting, and OSS.us/LSS.us).  If you're interested, please send me an
email.

And if any kernel people reading this is interested in anything specific
from us man(7) people, please let us know!


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Mickaël Salaün]

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

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6507 bytes --]

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@kernel.org>
	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@kernel.org>

	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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Günther Noack]

Hello!

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. Only a small part of the .rst
documentation is about kernel internals.

If I understood that correctly, section 9 is supposed to be document things that
are relevant to kernel developers, right?  So it doesn't sound like the right
place for the documentation that we have?

—Günther

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1723 bytes --]

On Wed, Feb 26, 2025 at 08:24:22PM +0000, Günther Noack wrote:
> Hello!

Hello!

> 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?
Or does it cover other stuff?

> Only a small part of the .rst
> documentation is about kernel internals.

Hmmmm.  I expected it would be mostly for kernel internals, but it seems
my guess was wrong.  :)

> If I understood that correctly, section 9 is supposed to be document things that
> are relevant to kernel developers, right?  So it doesn't sound like the right
> place for the documentation that we have?

Yep, that suggestion was due to my wrong idea that the .rst docs were
mostly kernel internals.


Have a lovely night!
Alex

> 
> —Günther
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Günther Noack]

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@google.com/)

Documentation of user space APIs is not unusual in the kernel documentation,
there is the entire subdirectory Documentation/userspace-api for it.

—Günther

Re: [PATCH 1/2] landlock: Minor typo and grammar fixes in IPC scoping documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1365 bytes --]

Hello!

On Wed, Feb 26, 2025 at 10:38:05PM +0100, Günther Noack wrote:
> 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@google.com/)

Yeah, I've been looking at those that you've CCd me.  I just thought
that the user-space part of the documentation was minoritary, and that
it was part of a much larger documentation that would include many
internals.  But if most .rst docs are UAPI, then I think it should all
be burnt down to flames.  :-)

> Documentation of user space APIs is not unusual in the kernel documentation,
> there is the entire subdirectory Documentation/userspace-api for it.

Huh!  You're indeed right.  A great percentage of Documentation/ is the
UAPI.

	alx@debian:~/.../Documentation$ find * -type f \
					| xargs wc | tail -n1;
	 110625  453670 3990219 total
	alx@debian:~/.../Documentation$ find userspace-api/ -type f \
					| xargs wc | tail -n1;
	  96501  368382 3411766 total


If anyone wants to burn that and send the parts that are missing form
the manual pages, you're invited.  :-)


Have a lovely night!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]