[PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Haowen Bai]

After make htmldocs, the table which is made of tab will
display all by one line. so we make a standard table for STANDARD
FORMAT SPECIFIERS description.

Signed-off-by: Haowen Bai <baihaowen@meizu.com>
---
 Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
index 422d5fa99e84..a8505e3a3044 100644
--- a/Documentation/vm/page_owner.rst
+++ b/Documentation/vm/page_owner.rst
@@ -174,22 +174,28 @@ STANDARD FORMAT SPECIFIERS
 
 For --sort option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	st		stacktrace	stack trace of the page allocation
-	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
+        ====            ==========      ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ==========      ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        n               name            task command name
+        st              stacktrace      stack trace of the page allocation
+        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
+        ====            ==========      ============================================
 
 For --curl option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	f		free		whether the page has been released or not
-	st		stacktrace	stack trace of the page allocation
+        ====            ===========     ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ===========     ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        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
+        ====            ===========     ============================================
-- 
2.7.4

Re: [PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Bagas Sanjaya]

On 4/20/22 10:06, Haowen Bai wrote:
> After make htmldocs, the table which is made of tab will
> display all by one line. so we make a standard table for STANDARD
> FORMAT SPECIFIERS description.
> 
> Signed-off-by: Haowen Bai <baihaowen@meizu.com>
> ---
>  Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
>  1 file changed, 20 insertions(+), 14 deletions(-)
> 

I guess this patch can be factored into its own single-patch series,
so the zh_CN patch at [1/2] can depend on it, right?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 4/20/22 10:06, Haowen Bai wrote:
>> After make htmldocs, the table which is made of tab will
>> display all by one line. so we make a standard table for STANDARD
>> FORMAT SPECIFIERS description.
>> 
>> Signed-off-by: Haowen Bai <baihaowen@meizu.com>
>> ---
>>  Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
>>  1 file changed, 20 insertions(+), 14 deletions(-)
>> 
>
> I guess this patch can be factored into its own single-patch series,
> so the zh_CN patch at [1/2] can depend on it, right?

I'm not quite sure what that would buy for anybody ... ?  Arguably the
two patches could have appeared in the opposite order, but nothing will
break with it done this way.

jon

Re: [PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Akira Yokosawa]

Hi,

Wed, 20 Apr 2022 11:06:56 +0800,
baihaowen wrote:
> After make htmldocs, the table which is made of tab will
> display all by one line. so we make a standard table for STANDARD
> FORMAT SPECIFIERS description.
> 
> Signed-off-by: Haowen Bai <baihaowen@meizu.com>
> ---
>  Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
>  1 file changed, 20 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> index 422d5fa99e84..a8505e3a3044 100644
> --- a/Documentation/vm/page_owner.rst
> +++ b/Documentation/vm/page_owner.rst
> @@ -174,22 +174,28 @@ STANDARD FORMAT SPECIFIERS
>  
>  For --sort option:
>  
> -	KEY		LONG		DESCRIPTION
> -	p		pid		process ID
> -	tg		tgid		thread group ID
> -	n		name		task command name
> -	st		stacktrace	stack trace of the page allocation
> -	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
> +        ====            ==========      ============================================
> +        KEY             LONG            DESCRIPTION
> +        ====            ==========      ============================================
> +        p               pid             process ID
> +        tg              tgid            thread group ID
> +        n               name            task command name
> +        st              stacktrace      stack trace of the page allocation
> +        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
> +        ====            ==========      ============================================
>  
>  For --curl option:
>  
> -	KEY		LONG		DESCRIPTION
> -	p		pid		process ID
> -	tg		tgid		thread group ID
> -	n		name		task command name
> -	f		free		whether the page has been released or not
> -	st		stacktrace	stack trace of the page allocation
> +        ====            ===========     ============================================
> +        KEY             LONG            DESCRIPTION
> +        ====            ===========     ============================================
> +        p               pid             process ID
> +        tg              tgid            thread group ID
> +        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
> +        ====            ===========     ============================================

This patch looks like against akpm's tree (or linux-next).
So it is not applicable to docs-next of Jonathan's tree at the
moment.

You need to wait until docs-next catches up akpm's tree.

Patch 1/2 should wait until the English doc is updated,
I suppose.

By the way, I don't think the list of options need tables.
Literal blocks should suffice.

I mean, How about the simpler changes:

>  For --sort option:
   For --sort option::

>  For --curl option:
   For --curl option::

Thoughts?

       Thanks, Akira

> -- 
> 2.7.4

Re: [PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> This patch looks like against akpm's tree (or linux-next).
> So it is not applicable to docs-next of Jonathan's tree at the
> moment.
>
> You need to wait until docs-next catches up akpm's tree.

The alternative is to send the fix to the same maintainer who accepted
the work being changed; that will usually lead to better (and quicker)
results.

Thanks,

jon

[PATCH 1/2] docs/zh_CN: sync with original text Documentation/vm/page_owner.rst

[Haowen Bai]

As the tools/vm/page_owner_sort added some feature and original text
updated, sync the translation of zh_CN as below.

Commit 8bd16bc0a081 ("tools/vm/page_owner_sort.c: support sorting blocks
by multiple keys") add sorting blocks by multiple keys usage
description.

Commit 78a0b94f3829 ("tools/vm/page_owner_sort.c: support for multi-value
selection in single argument") add multi-value selection in single
argument usage description.

Commit c89b3ad2dea2 ("doc/vm/page_owner.rst: remove content related to -c
option") remove  -c option usage description.

Commit 9c8a0a8e599f ("tools/vm/page_owner_sort.c: support for user-defined
culling rules") add user-defined culling rules usage description.

Commit 8ea8613a616a ("tools/vm/page_owner_sort.c: support for selecting by
PID, TGID or task command name") add selecting by PID, TGID or task
command name usage description.

Commit 194d52d771b8 ("tools/vm/page_owner_sort: support for sorting by
task command name") add sorting by task command name usage description.

Signed-off-by: Haowen Bai <baihaowen@meizu.com>
---
 Documentation/translations/zh_CN/vm/page_owner.rst | 61 +++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/Documentation/translations/zh_CN/vm/page_owner.rst b/Documentation/translations/zh_CN/vm/page_owner.rst
index 9e951fabba9d..c692e81c724e 100644
--- a/Documentation/translations/zh_CN/vm/page_owner.rst
+++ b/Documentation/translations/zh_CN/vm/page_owner.rst
@@ -103,14 +103,73 @@ page owner在默认情况下是禁用的。所以，如果你想使用它，你
 		-m		按总内存排序
 		-p		按pid排序。
 		-P		按tgid排序。
+		-n		按任务名称排序。
 		-r		按内存释放时间排序。
 		-s		按堆栈跟踪排序。
 		-t		按时间排序（默认）。
+		--sort <order>	指定排序顺序。排序语法是 [+|-]key[,[+|-]key[,...]]. 从
+						**标准格式说明符** 部分选择一个键。"+" 是可选的，因为默认方向是增加数字或字典顺序。
+						允许混合使用缩写键和全称键。
+
+		Examples:
+				./page_owner_sort <input> <output> --sort=n,+pid,-tgid
+				./page_owner_sort <input> <output> --sort=at
 
    其它函数:
 
 	Cull:
-		-c		通过比较堆栈跟踪而不是总块来进行剔除。
+		--cull <rules>
+				指定筛选规则。筛选语法是 key[,key[,...]]。在**标准格式说明符**部分选择一个多字母键
+
+		<rules> 是逗号分隔列表形式的单个参数，它提供了一种指定单个筛选规则的方法。下面的**标准格式说明
+				符**部分描述了可识别的关键字。<rules> 可以由键 k1,k2, ... 顺序指定，如下面的
+				STANDARD SORT KEYS 部分所述。允许混合使用缩写形式和完整形式的键。
 
+		Examples:
+				./page_owner_sort <input> <output> --cull=stacktrace
+				./page_owner_sort <input> <output> --cull=st,pid,name
+				./page_owner_sort <input> <output> --cull=n,f
 	Filter:
 		-f		过滤掉内存已被释放的块的信息。
+
+	Select:
+		--pid <pidlist>		通过 pid 进行选择。这将选择进程 ID 号出现在 <pidlist> 中的块。
+		--tgid <tgidlist>	通过 tgid 进行选择。这将选择线程组 ID 号出现在 <tgidlist> 中的块。
+		--name <cmdlist>	按任务名称选择。这将选择任务名称出现在 <cmdlist> 中的块。
+
+		<pidlist>、<tgidlist>、<cmdlist>是逗号分隔列表形式的单参数，它提供了一种指定单个选择规则的方法。
+
+
+		Examples:
+				./page_owner_sort <input> <output> --pid=1
+				./page_owner_sort <input> <output> --tgid=1,2,3
+				./page_owner_sort <input> <output> --name name1,name2
+
+标准格式说明符
+==============
+
+--sort 选项:
+
+        ======          ==========      ===================
+        缩写键          全称键          描述
+        ======          ==========      ===================
+        p               pid             进程 ID
+        tg              tgid            线程组 ID
+        n               name            任务名称
+        st              stacktrace      页面分配的调用栈
+        T               txt             块的全文
+        ft              free_ts         页面被释放的时间戳
+        at              alloc_ts        页面分配的时间戳
+        ======          ==========      ===================
+
+--curl 选项:
+
+        ======          ==========      ==================
+        缩写键          全称键          描述
+        ======          ==========      ==================
+        p               pid             进程 ID
+        tg              tgid            线程组 ID
+        n               name            任务名称
+        f               free            该页面是否已被释放
+        st              stacktrace      页面分配的调用栈
+        ======          ==========      ==================
-- 
2.7.4

[PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Haowen Bai]

After make htmldocs, the table which is made of tab will
display all by one line. so we make a standard table for STANDARD
FORMAT SPECIFIERS description.

Signed-off-by: Haowen Bai <baihaowen@meizu.com>
---
 Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
index 422d5fa99e84..a8505e3a3044 100644
--- a/Documentation/vm/page_owner.rst
+++ b/Documentation/vm/page_owner.rst
@@ -174,22 +174,28 @@ STANDARD FORMAT SPECIFIERS
 
 For --sort option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	st		stacktrace	stack trace of the page allocation
-	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
+        ====            ==========      ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ==========      ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        n               name            task command name
+        st              stacktrace      stack trace of the page allocation
+        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
+        ====            ==========      ============================================
 
 For --curl option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	f		free		whether the page has been released or not
-	st		stacktrace	stack trace of the page allocation
+        ====            ===========     ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ===========     ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        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
+        ====            ===========     ============================================
-- 
2.7.4

[PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Haowen Bai]

After make htmldocs, the table which is made of tab will
display all by one line. so we make a standard table for STANDARD
FORMAT SPECIFIERS description.

Signed-off-by: Haowen Bai <baihaowen@meizu.com>
---
 Documentation/vm/page_owner.rst | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
index 422d5fa99e84..a8505e3a3044 100644
--- a/Documentation/vm/page_owner.rst
+++ b/Documentation/vm/page_owner.rst
@@ -174,22 +174,28 @@ STANDARD FORMAT SPECIFIERS
 
 For --sort option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	st		stacktrace	stack trace of the page allocation
-	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
+        ====            ==========      ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ==========      ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        n               name            task command name
+        st              stacktrace      stack trace of the page allocation
+        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
+        ====            ==========      ============================================
 
 For --curl option:
 
-	KEY		LONG		DESCRIPTION
-	p		pid		process ID
-	tg		tgid		thread group ID
-	n		name		task command name
-	f		free		whether the page has been released or not
-	st		stacktrace	stack trace of the page allocation
+        ====            ===========     ============================================
+        KEY             LONG            DESCRIPTION
+        ====            ===========     ============================================
+        p               pid             process ID
+        tg              tgid            thread group ID
+        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
+        ====            ===========     ============================================
-- 
2.7.4

Re: [PATCH 2/2] doc/vm/page_owner.rst: Fix table display confusion

[Alex Shi]

On 4/24/22 11:38, Akira Yokosawa wrote:
> This patch looks like against akpm's tree (or linux-next).
> So it is not applicable to docs-next of Jonathan's tree at the
> moment.
> 
> You need to wait until docs-next catches up akpm's tree.
> 
> Patch 1/2 should wait until the English doc is updated,
> I suppose.
> 
> By the way, I don't think the list of options need tables.
> Literal blocks should suffice.
> 
> I mean, How about the simpler changes:
> 
>>  For --sort option:
>    For --sort option::
> 
>>  For --curl option:
>    For --curl option::
> 
> Thoughts?


Hi haowen,

Don't ignore review suggestions, Akira is right here, then
you don't repeat the same issue many times:

$ g am \[PATCH\ 2_2\]\ doc_vm_page_owner.rst\:\ Fix\ table\ display\ confusion\ -\ Haowen\ Bai\ \<baihaowen@meizu.com\>\ -\ 2022-04-26\ 1507.eml 

Applying: doc/vm/page_owner.rst: Fix table display confusion

.git/rebase-apply/patch:21: indent with spaces.

        ====            ==========      ============================================

.git/rebase-apply/patch:22: indent with spaces.

        KEY             LONG            DESCRIPTION

.git/rebase-apply/patch:23: indent with spaces.

        ====            ==========      ============================================

.git/rebase-apply/patch:24: indent with spaces.

        p               pid             process ID

.git/rebase-apply/patch:25: indent with spaces.

        tg              tgid            thread group ID

warning: squelched 15 whitespace errors

warning: 20 lines add whitespace errors.