Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <e65cac81-3f56-3ba0-6ce1-bc07e9d0617c@gmail.com>
Date:   Thu, 28 Apr 2022 10:43:38 +0800
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.7.0
Subject: Re: [PATCH] docs: vm/page_owner: Use literal blocks for param
 description
Content-Language: en-US
To:     Akira Yokosawa <akiyks@gmail.com>,
        Andrew Morton <akpm@linux-foundation.org>
Cc:     Shenghong Han <hanshenghong2019@email.szu.edu.cn>,
        Haowen Bai <baihaowen@meizu.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
References: <cfd3bcc0-b51d-0c68-c065-ca1c4c202447@gmail.com>
From:   Alex Shi <seakeel@gmail.com>
In-Reply-To: <cfd3bcc0-b51d-0c68-c065-ca1c4c202447@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk


On 4/27/22 20:58, Akira Yokosawa wrote:
> Subject: [PATCH] docs: vm/page_owner: Use literal blocks for param description
> 
> Sphinx generates hard-to-read lists of parameters at the bottom
> of the page.  Fix them by putting literal-block markers of "::"
> in front of them.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

LFTM

Reviewed-by: Alex Shi <alexs@kernel.org>

> Fixes: 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")
> Cc: Shenghong Han <hanshenghong2019@email.szu.edu.cn>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Haowen Bai <baihaowen@meizu.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Alex Shi <seakeel@gmail.com>
> ---
> Hello Andrew,
> 
> This is the first time I send a patch in your way.
> So I'm not sure this works as I intend.
> If anything goes wrong, please let me know.
> 
> This issue is in discussion in a linux-doc thread triggered by
> a post from Haowen Bai [1]. (Warning: The thread looks confused
> due to Haowen's unnecessary uses of In-Reply-To: headers.)
> Jon suggested the route via your tree, but he keeps posting
> to linux-doc.
> 
> [1]: https://lore.kernel.org/all/1650424016-7225-3-git-send-email-baihaowen@meizu.com/
> 
> Haowen's patch uses tables to improve the look of param lists.
> I suggested him using literal blocks instead, but I failed to
> hear any response. So I'm sending my version of the fix in your
> way.
> 
> I believe this fix is worth for 5.18-rcX.
> 
> Side note 1: I see another patch queued for -next around here, which
> has broken indents by white spaces.  You might want to fix or drop it.
> 
> Side note 2: page_owner.rst is not covered in MAINTAINERS.
> You might want to add an entry, maybe, under "PAGE TABLE CHECK".
> 
> Again, if there is anything I can do better, please let me know.
> 
> Best,
> 
>         Akira
> --
>  Documentation/vm/page_owner.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> index 65204d7f004f..7e0c3f574e78 100644
> --- a/Documentation/vm/page_owner.rst
> +++ b/Documentation/vm/page_owner.rst
> @@ -110,7 +110,7 @@ Usage
>     If you want to sort by the page nums of buf, use the ``-m`` parameter.
>     The detailed parameters are:
>  
> -   fundamental function:
> +   fundamental function::
>  
>  	Sort:
>  		-a		Sort by memory allocation time.
> @@ -122,7 +122,7 @@ Usage
>  		-s		Sort by stack trace.
>  		-t		Sort by times (default).
>  
> -   additional function:
> +   additional function::
>  
>  	Cull:
>  		--cull <rules>
> @@ -153,6 +153,7 @@ Usage
>  
>  STANDARD FORMAT SPECIFIERS
>  ==========================
> +::
>  
>  	KEY		LONG		DESCRIPTION
>  	p		pid		process ID
> 
> base-commit: af2d861d4cd2a4da5137f795ee3509e6f944a25b