linux-kernel - Resend: [PATCH] Documentation/vm/page_owner.rst: Fix syntax error and Describe details using table

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Sat, 30 Apr 2022 18:25:29 +0800
From:   "Shenghong Han" 
        <hanshenghong2019@...il.szu.edu.cn>
To:     "Akira Yokosawa" <akiyks@...il.com>,
        "Jonathan Corbet" <corbet@....net>
Cc:     "akpm" <akpm@...ux-foundation.org>,
        "baihaowen" <baihaowen@...zu.com>,
        "seakeel" <seakeel@...il.com>,
        "linux-doc" <linux-doc@...r.kernel.org>,
        "linux-kernel" <linux-kernel@...r.kernel.org>,
        "caoyixuan2019" <caoyixuan2019@...il.szu.edu.cn>,
        "yejiajian2018" <yejiajian2018@...il.szu.edu.cn>,
        "yuhongf" <yuhongf@....edu.cn>
Subject: Resend: [PATCH] Documentation/vm/page_owner.rst: Fix syntax error and Describe details using table

The one reply archived at "https://lore.kernel.org/linux-doc/tencent_088763F35CE233FB6C9CEB80@qq.com/"(On 2022/04/30 16:13) is broken-looking. 

Apologize for that!

Resend that reply:

0) If you have received a similar reply, please refer to the latest reply.

1) Accidentally used Chinese Input Method Editor, leaving full-width symbols during the test, causing the double dashes of "--" changed into "long single dash" which should not have occurred.

2) In the current document, the "STANDARD FORMAT SPECIFIERS" table does not correctly use the format of the rst document, so in the website https://www.kernel.org/doc/html/latest/vm/page_owner.html, it does not look good. Therefore, the "STANDARD FORMAT SPECIFIERS" has been adjusted using the format of the rst table. *This* is the main purpose.

3) In version 1 before(On 2022/04/30 1:19), the sentence look like:"Table 1 xxx(some explaination)." and "Table 2 xxx(some explaination).", in these 2 "long" sentences, using "." instead of ":".Honestly, complex sentence is unnecessary. When I tried to modify the sentence, I ignore the strict distinction between "." and ":".In short, This modification is unnecessary.

4) Apologize again for the troubles that my clumsy behaviors have caused.

Thanks, 

Shenghong Han

------------------ Original ------------------
From:  "Akira Yokosawa"<akiyks@...il.com>;
Date:  Sat, Apr 30, 2022 02:40 PM
To:  "Shenghong Han"<hanshenghong2019@...il.szu.edu.cn>; "Jonathan Corbet"<corbet@....net>;
Cc:  "akpm"<akpm@...ux-foundation.org>; "baihaowen"<baihaowen@...zu.com>; "seakeel"<seakeel@...il.com>; "linux-doc"<linux-doc@...r.kernel.org>; "linux-kernel"<linux-kernel@...r.kernel.org>; "caoyixuan2019"<caoyixuan2019@...il.szu.edu.cn>; "yejiajian2018"<yejiajian2018@...il.szu.edu.cn>; "yuhongf"<yuhongf@....edu.cn>;
Subject:  Re: [PATCH] Documentation/vm/page_owner.rst: Fix syntax error and Describe details using table

On 2022/04/30 3:19,
Shenghong Han wrote:
> Some syntax errors exist in "page_owner.rst". Thanks to Akira Yokosawa and
> Haowen Bai for tips to help improve the documentation.
>
> We try to fix them. Hope that the Documentation is showed as we expect.
>
> Signed-off-by: Shenghong Han <hanshenghong2019@...il.szu.edu.cn>
> Fixes: edc93abbcc6d ("tools/vm/page_owner_sort.c: support sorting blocks by multiple keys")
>
> ---
> Thanks Jonathan's suggestion.
>
> This fix is a simpler than before.
> And yes, It has built in my machine.
>
> Best,
>
> Shenghong Han
> ---
> ---
>  Documentation/vm/page_owner.rst | 15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> index 25622c715..0ecb4a739 100644
> --- a/Documentation/vm/page_owner.rst
> +++ b/Documentation/vm/page_owner.rst
> @@ -171,11 +171,12 @@ Usage
> 
>  STANDARD FORMAT SPECIFIERS
>  ==========================
> -::
> 
> -For --sort option:
> +1) For --sort option.
> 
> + ==== ========== ===========
>  KEY LONG DESCRIPTION
> + ==== ========== ===========
>  p pid process ID
>  tg tgid thread group ID
>  n name task command name
> @@ -183,14 +184,18 @@ 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:
> +2) 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
> -        ator            allocator       memory allocator for pages
> + ator allocator memory allocator for pages
> + ==== ========== ===========

So, I have actually tested this.

Are you OK with the look of

  1) For --sort option.

and

  2) For --curl option.

in generated HTML or PDF docs?

In literal blocks, you would see double dashes of "--".
Now they are converted to so-called endash, which is a single dash
slightly longer than a normal hyphen.  It looks confusing to me.

To remedy this, you need inline literal markers of

  1) For ``--sort`` option.

and

  2) For ``--curl`` option.

By the way, this patch changes ":" to "." at the end of them.
Are they intentional changes?  If so, why?

        Thanks, Akira