Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:18 as permitted sender) client-ip=2620:137:e000::1:18;
Message-ID: <fdfecc82-d41e-6d8a-738d-4beb6faa27fb@gmail.com>
Date:   Fri, 6 May 2022 22:09:31 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.8.1
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: [PATCH -next] docs: vm/page_owner: Tweak literal block in STANDARD
 FORMAT SPECIFIERS
To:     Andrew Morton <akpm@linux-foundation.org>
Cc:     Shenghong Han <hanshenghong2019@email.szu.edu.cn>,
        Jiajian Ye <yejiajian2018@email.szu.edu.cn>,
        Chongxi Zhao <zhaochongxi2019@email.szu.edu.cn>,
        Yinan Zhang <zhangyinan2019@email.szu.edu.cn>,
        Yixuan Cao <caoyixuan2019@email.szu.edu.cn>,
        Yongqiang Liu <liuyongqiang13@huawei.com>,
        Yuhong Feng <yuhongf@szu.edu.cn>,
        Haowen Bai <baihaowen@meizu.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Content-Language: en-US
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

A semantic conflict between commit 5603f9bdea68 ("docs: vm/page_owner:
use literal blocks for param description") and a change queued for v5.19
authored by Jiajian Ye ("tools/vm/page_owner_sort.c: support sorting
blocks by multiple keys") results in a warning from "make htmldocs"
saying:

  [...]/vm/page_owner.rst:176: WARNING: Literal block expected; none foun=
d.

This is because a literal block in ReST ends at a line which has the
same indent as the paragraph preceding it.  In this case the one with
no indent.

Indent the two "For --xxxx option:" lines by two columns and make the
whole section a literal block.

While at it, fix indents by white spaces of "ator" keys.

Reported-by: Shenghong Han <hanshenghong2019@email.szu.edu.cn>
Signed-of-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jiajian Ye <yejiajian2018@email.szu.edu.cn>
Cc: Chongxi Zhao <zhaochongxi2019@email.szu.edu.cn>
Cc: Yinan Zhang <zhangyinan2019@email.szu.edu.cn>
Cc: Yixuan Cao <caoyixuan2019@email.szu.edu.cn>
Cc: Yongqiang Liu <liuyongqiang13@huawei.com>
Cc: Yuhong Feng <yuhongf@szu.edu.cn>
Cc: Haowen Bai <baihaowen@meizu.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
Hi Andrew,

This is kind of a follow-up fix of commit 5603f9bdea68 ("docs:
vm/page_owner: use literal blocks for param description"), which I
sent the other day [1] as a fix against v5.18-rc1 and merged into
v5.18-rc5.

The fix in mainline results in a minor semantic conflict with your
tree destined for v5.19, and causes another warning from "make html".
Shenghong Han submitted a patch around the key lists using the ReST
table construct [2] based on Haowen Bai's earlier attempt [3], but
it seems the effort has stalled.

Hence I'm submitting this patch against your tree as a resolution
of the semantic conflict, with additional indent fixes as were done
in [2].

[1]: https://lore.kernel.org/r/cfd3bcc0-b51d-0c68-c065-ca1c4c202447@gmail=
=2Ecom/
[2]: https://lore.kernel.org/r/20220429181926.10658-1-hanshenghong2019@em=
ail.szu.edu.cn/
[3]: https://lore.kernel.org/r/1650956829-31013-3-git-send-email-baihaowe=
n@meizu.com/

Note: By making the whole section a literal block, excessive inline
literal markers around --sort and --curl options can be avoided.

For example, in a normal ReST paragraph,

  For --sort option:

will be converted by Sphinx to

  For =E2=80=93sort option:

in HTML, where the "=E2=80=93" is an "endash" symbol.

Such conversions could be prevented by putting inline literal markers
around:

  For ``--sort`` option:

However, it would degrade the readability of the .rst file as
plain-text.  In this particular case, making the whole section
a literal block should be a better option, at long as the section
consists only of those key lists.

        Thanks, Akira
--
 Documentation/vm/page_owner.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owne=
r.rst
index 25622c715823..f5c954afe97c 100644
--- a/Documentation/vm/page_owner.rst
+++ b/Documentation/vm/page_owner.rst
@@ -173,7 +173,7 @@ STANDARD FORMAT SPECIFIERS
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
 ::
=20
-For --sort option:
+  For --sort option:
=20
 	KEY		LONG		DESCRIPTION
 	p		pid		process ID
@@ -183,9 +183,9 @@ For --sort option:
 	T		txt		full text of block
 	ft		free_ts		timestamp of the page when it was released
 	at		alloc_ts	timestamp of the page when it was allocated
-        ator            allocator       memory allocator for pages
+	ator		allocator	memory allocator for pages
=20
-For --curl option:
+  For --curl option:
=20
 	KEY		LONG		DESCRIPTION
 	p		pid		process ID
@@ -193,4 +193,4 @@ For --curl option:
 	n		name		task command name
 	f		free		whether the page has been released or not
 	st		stacktrace	stack trace of the page allocation
-        ator            allocator       memory allocator for pages
+	ator		allocator	memory allocator for pages
--=20
2.25.1