linux-kernel - Re: [PATCH v5 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

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 for Android: free password hash cracker in your pocket

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

Message-ID: <87r0vh9n17.fsf@meer.lwn.net>
Date:   Thu, 26 Jan 2023 11:19:16 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Mike Rapoport <rppt@...nel.org>
Cc:     Andrew Morton <akpm@...ux-foundation.org>,
        Bagas Sanjaya <bagasdotme@...il.com>,
        David Hildenbrand <david@...hat.com>,
        Johannes Weiner <hannes@...xchg.org>,
        Lorenzo Stoakes <lstoakes@...il.com>,
        "Matthew Wilcox (Oracle)" <willy@...radead.org>,
        Mel Gorman <mgorman@...e.de>, Michal Hocko <mhocko@...nel.org>,
        Mike Rapoport <rppt@...nel.org>,
        Vlastimil Babka <vbabka@...e.cz>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-mm@...ck.org,
        Michal Hocko <mhocko@...e.com>
Subject: Re: [PATCH v5 1/1] docs/mm: Physical Memory: add structure,
 introduction and nodes description

Mike Rapoport <rppt@...nel.org> writes:

> From: "Mike Rapoport (IBM)" <rppt@...nel.org>
>
> Add structure, introduction and Nodes section to Physical Memory
> chapter.
>
> As the new documentation references core-api/dma-api and mm/page_reclaim,
> add page labels to those documents.
>
> Reviewed-by: Bagas Sanjaya <bagasdotme@...il.com>
> Reviewed-by: Lorenzo Stoakes <lstoakes@...il.com>
> Acked-by: Michal Hocko <mhocko@...e.com>
> Acked-by: Vlastimil Babka <vbabka@...e.cz>
> Signed-off-by: Mike Rapoport (IBM) <rppt@...nel.org>

I've gone ahead and applied this, but I do have one little gripe...

>  Documentation/core-api/dma-api.rst   |   2 +
>  Documentation/mm/page_reclaim.rst    |   2 +
>  Documentation/mm/physical_memory.rst | 347 +++++++++++++++++++++++++++
>  3 files changed, 351 insertions(+)
>
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 829f20a193ca..c847a5b0a0d3 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -1,3 +1,5 @@
> +.. _dma_api:
> +

Top-of-file labels like this one...

>  ============================================
>  Dynamic DMA mapping using the generic device
>  ============================================
> diff --git a/Documentation/mm/page_reclaim.rst b/Documentation/mm/page_reclaim.rst
> index 50a30b7f8ac3..3fccde066436 100644
> --- a/Documentation/mm/page_reclaim.rst
> +++ b/Documentation/mm/page_reclaim.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +.. _page_reclaim:

...and this one really just add noise without bringing any value.
Something like:

> +Reclaim control
> +~~~~~~~~~~~~~~~
> +
> +See also :ref:`Page Reclaim <page_reclaim>`.

Can also just be "See also Documentation/mm/page_reclaim.rst".  The
right things will happen in the HTML output, readers of the plain-text
will know immediately where to go, and we don't have to add the label
clutter.

</gripe> :)

Thanks,

jon