Skip to contentSkip to conversation

docs: vm/page_owner: Use literal blocks for param description

PATCH Applied Akira Yokosawa 3 participants 3 messages Apr 27, 2022 – Apr 28, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

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

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.

Fixes 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")
Cc Shenghong Han <[email protected]>
Cc Andrew Morton <[email protected]>
Cc Haowen Bai <[email protected]>
Cc Jonathan Corbet <[email protected]>
Cc Alex Shi <[email protected]>

---
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/[email protected]/

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(-)
Documentation/vm/page_owner.rst +3 -2
index 65204d7f004f..7e0c3f574e78 100644
@@ -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

Signature · 1 line
2.25.1
#1 lore raw
Quoted 26 lines · Akira Yokosawa

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.

Fixes 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")
Cc Shenghong Han <[email protected]>
Cc Andrew Morton <[email protected]>
Cc Haowen Bai <[email protected]>
Cc Jonathan Corbet <[email protected]>
Cc Alex Shi <[email protected]>

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

Quoted 6 lines

[1]: https://lore.kernel.org/all/[email protected]/

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.

Dear Akira Yokosawa
Sorry for missing reply your mail, since I am out of work at that time. BTW, I'll try to work base on the newest Doc later.
Thank you for your suggestion and apply the typical format for  parameter description.

Quoted 49 lines

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(-)
Documentation/vm/page_owner.rst +3 -2
index 65204d7f004f..7e0c3f574e78 100644
@@ -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

Signature · 1 line
Haowen Bai
Reviewed-by on v1 1/1
#2 lore raw
In reply to Akira Yokosawa
Quoted 7 lines · Akira Yokosawa

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.

LFTM

Quoted 75 lines
Fixes 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")
Cc Shenghong Han <[email protected]>
Cc Andrew Morton <[email protected]>
Cc Haowen Bai <[email protected]>
Cc Jonathan Corbet <[email protected]>
Cc Alex Shi <[email protected]>

---
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/[email protected]/

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(-)
Documentation/vm/page_owner.rst +3 -2
index 65204d7f004f..7e0c3f574e78 100644
@@ -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