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 <[email protected]>
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(-)
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
在 4/27/22 8:58 PM, 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.
>
> Signed-off-by: Akira Yokosawa <[email protected]>
> 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.
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.
> 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
--
Haowen Bai
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 <[email protected]>
LFTM
Reviewed-by: Alex Shi <[email protected]>
> 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(-)
>
> 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