Re: [PATCH 3/3] man/man7/landlock.7: wfix

[Alejandro Colomar <alx@kernel.org>]

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

Hi Štěpán,

On 2026-07-13T13:48:55+0200, Štěpán Němec wrote:
> On Fri, 10 Jul 2026 18:48:36 +0200 Alejandro Colomar wrote:
[...]
> > I've added to CC the landlock maintainers, so that they review the text.
> > They maintain the same text in the kernel, so it's better to have it
> > coordinated.
> 
> Thanks, I did not realize that.
> 
> I see now that the texts have already diverged and the
> equivalent paragraph in the kernel docs
> (Documentation/userspace-api/landlock.rst) now reads
> 
>   Each time a thread enforces a ruleset on itself, it updates its Landlock domain
>   with a new layer of policy.  This complementary policy is stacked with any
>   other rulesets potentially already restricting this thread.  A sandboxed thread
>   can then safely add more constraints to itself with a new enforced ruleset.
> 
> (Wording introduced by linux commit dad2f2071516
> (2024-10-15; "landlock: Fix grammar issues in documentation").)
> 
> FWIW I see little point in this kind of duplication, given
> that the kernel docs are as readily available to anyone
> interested as the man pages are;

Not so much; the manual pages are available for anyone on a terminal
without internet connection.  The kernel docs are only available if you
have the kernel sources or internet.

So, the manual pages are necessary.  What I wonder is if the kernel
documentation is necessary.  I think they could drop it (the duplicated
part of it), and refer to the manual page.  However, I trust they know
what's best for them.

> OTOH it seems that the
> duplication is only partial here (i.e., the documents
> differ, with only isolated verbatim overlaps), so perhaps
> the rationale is that the different documents target
> slightly different audiences (I'm not sure I'd agree).

Yup; still, referring to the manual pages instead of duplicating that
part in the kernel might (or might not) be a good idea.

> Anyway, here is a patch simply adjusting the man page text
> to match the kernel docs (I still believe "potentially" is
> more distracting than useful there, but it is an improvement
> on the original.):

Thanks!  This sounds like an improvement that doesn't need to be
reviewed by the kernel maintainers.  I've applied it.


Cheers,
Alex

> 
> ----------------------------------- 8< --------------------------------
> Subject: [PATCH] man/man7/landlock.7: wfix
> 
> Use the current wording of the equivalent paragraph in
> Linux kernel Documentation/userspace-api/landlock.rst.
> 
> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
> ---
>  man/man7/landlock.7 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
> index 293374ed9b46..f0a9b6db4bc8 100644
> --- a/man/man7/landlock.7
> +++ b/man/man7/landlock.7
> @@ -296,8 +296,8 @@ .SS Scope flags
>  .SS Layers of file path access rights
>  Each time a thread enforces a ruleset on itself,
>  it updates its Landlock domain with a new layer of policy.
> -Indeed, this complementary policy is composed with the
> -potentially other rulesets already restricting this thread.
> +This complementary policy is stacked with any
> +other rulesets potentially already restricting this thread.
>  A sandboxed thread can then safely add more constraints to itself with a
>  new enforced ruleset.
>  .P
> 
> base-commit: 794e74fd54156f767801eb60a0d79a496c73e505
> -- 
> 2.55.0

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

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