[PATCH v1 2/3] landlock: Slightly improve documentation and fix spelling

[Akira Yokosawa]

On Sat, 24 Sep 2022 20:29:24 +0700, Bagas Sanjaya wrote:
> On Fri, Sep 23, 2022 at 05:42:06PM +0200, Mickaël Salaün wrote:
>> Now that we have more than one ABI version, make limitation explanation
>> more consistent by replacing "ABI 1" with "ABI < 2".  This also
>> indicates which ABIs support such past limitation.
>> 
> 
> Hi,
> 
> I think grammar and reference link on userspace documentation can be
> improved, like:
> 
> ---- >8 ----
> 
> diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
> index 2cc502a75ef640..c49454900edb12 100644
> --- a/Documentation/admin-guide/cgroup-v1/memory.rst
> +++ b/Documentation/admin-guide/cgroup-v1/memory.rst
> @@ -1,3 +1,5 @@
> +.. _cgroup-v1-memory:
> +
>  ==========================
>  Memory Resource Controller
>  ==========================
> diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
> index 4c76fda076454c..dbeddb6851e6c9 100644
> --- a/Documentation/filesystems/overlayfs.rst
> +++ b/Documentation/filesystems/overlayfs.rst
> @@ -3,6 +3,8 @@
>  Written by: Neil Brown
>  Please see MAINTAINERS file for where to send questions.
>  
> +.. _overlayfs:
> +
>  Overlay Filesystem
>  ==================
>  
> diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst
> index d83395354250d9..cbc20658bd0c07 100644
> --- a/Documentation/filesystems/sharedsubtree.rst
> +++ b/Documentation/filesystems/sharedsubtree.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +.. _shared-subtrees:
> +
>  ===============
>  Shared Subtrees
>  ===============
[...]

> @@ -203,42 +204,40 @@ etc.).
>  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.
> -Documentation/filesystems/sharedsubtree.rst) but not with
> -Documentation/filesystems/overlayfs.rst.
> +Landlock can restrict access to file hierarchies, which means that these
> +access rights can be propagated with bind mounts (see
> +:ref:`shared-subtrees`) but not with :ref:`OverlayFS <overlayfs>`.

Wait!
Bagas, your suggestion is _against_ the preference of kernel documentation.
See https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#cross-referencing

Or do you have some good reason to add labels at the beginning of
rst docs?

        Thanks, Akira

[...]