Skip to contentSkip to conversation

docs: vm/page_owner: Tweak literal block in STANDARD FORMAT SPECIFIERS

PATCH Applied Akira Yokosawa 1 participant 1 message May 6, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: vm/page_owner: Tweak literal block in STANDARD FORMAT SPECIFIERS

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 found.

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.

Cc Jiajian Ye <[email protected]>
Cc Chongxi Zhao <[email protected]>
Cc Yinan Zhang <[email protected]>
Cc Yixuan Cao <[email protected]>
Cc Yongqiang Liu <[email protected]>
Cc Yuhong Feng <[email protected]>
Cc Haowen Bai <[email protected]>
Cc Jonathan Corbet <[email protected]>

---
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/[email protected]/
[2]: https://lore.kernel.org/r/[email protected]/
[3]: https://lore.kernel.org/r/[email protected]/

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 –sort option:

in HTML, where the "–" 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(-)
Documentation/vm/page_owner.rst +4 -4
index 25622c715823..f5c954afe97c 100644
@@ -173,7 +173,7 @@ STANDARD FORMAT SPECIFIERS
 ==========================
 ::
 
-For --sort option:
+  For --sort option:
 
 	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
 
-For --curl option:
+  For --curl option:
 
 	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
Signature · 1 line
2.25.1