linux-kernel - Re: [PATCH v2 27/29] docs: userspace-api: landlock.rst: avoid using ReST :doc:`foo` markup

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <7ebe5a4d-8835-6737-c006-3d065e50dc8a@digikod.net>
Date:   Wed, 23 Jun 2021 14:26:43 +0200
From:   Mickaël Salaün <mic@...ikod.net>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     linux-kernel@...r.kernel.org, linux-security-module@...r.kernel.org
Subject: Re: [PATCH v2 27/29] docs: userspace-api: landlock.rst: avoid using
 ReST :doc:`foo` markup


On 16/06/2021 08:27, Mauro Carvalho Chehab wrote:
> The :doc:`foo` tag is auto-generated via automarkup.py.
> So, use the filename at the sources, instead of :doc:`foo`.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>  Documentation/userspace-api/landlock.rst | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)

Acked-by: Mickaël Salaün <mic@...ux.microsoft.com>

Like others, I think it would be nice to explain the reason of this
change in the commit message, and why it is better than the current way
to do it.

> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 62c9361a3c7f..f35552ff19ba 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -145,7 +145,8 @@ Bind mounts and OverlayFS
>  
>  Landlock enables to restrict access to file hierarchies, which means that these
>  access rights can be propagated with bind mounts (cf.
> -:doc:`/filesystems/sharedsubtree`) but not with :doc:`/filesystems/overlayfs`.
> +Documentation/filesystems/sharedsubtree.rst) but not with
> +Documentation/filesystems/overlayfs.rst.
>  
>  A bind mount mirrors a source file hierarchy to a destination.  The destination
>  hierarchy is then composed of the exact same files, on which Landlock rules can
> @@ -170,8 +171,8 @@ Inheritance
>  
>  Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain
>  restrictions from its parent.  This is similar to the seccomp inheritance (cf.
> -:doc:`/userspace-api/seccomp_filter`) or any other LSM dealing with task's
> -:manpage:`credentials(7)`.  For instance, one process's thread may apply
> +Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with
> +task's :manpage:`credentials(7)`.  For instance, one process's thread may apply
>  Landlock rules to itself, but they will not be automatically applied to other
>  sibling threads (unlike POSIX thread credential changes, cf.
>  :manpage:`nptl(7)`).
> @@ -278,7 +279,7 @@ Memory usage
>  ------------
>  
>  Kernel memory allocated to create rulesets is accounted and can be restricted
> -by the :doc:`/admin-guide/cgroup-v1/memory`.
> +by the Documentation/admin-guide/cgroup-v1/memory.rst.
>  
>  Questions and answers
>  =====================
> @@ -303,7 +304,7 @@ issues, especially when untrusted processes can manipulate them (cf.
>  Additional documentation
>  ========================
>  
> -* :doc:`/security/landlock`
> +* Documentation/security/landlock.rst
>  * https://landlock.io
>  
>  .. Links
>