[PATCH] docs: vm/page_owner: Use literal blocks for param description

From: Akira Yokosawa <akiyks@gmail.com>
To: Andrew Morton <akpm@linux-foundation.org>
Cc: Shenghong Han <hanshenghong2019@email.szu.edu.cn>,
	Haowen Bai <baihaowen@meizu.com>,
	Jonathan Corbet <corbet@lwn.net>, Alex Shi <seakeel@gmail.com>,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH] docs: vm/page_owner: Use literal blocks for param description
Date: Wed, 27 Apr 2022 21:58:19 +0900	[thread overview]
Message-ID: <cfd3bcc0-b51d-0c68-c065-ca1c4c202447@gmail.com> (raw)

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>
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
-- 
2.25.1

