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

[Akira Yokosawa <akiyks@gmail.com>]

Hi,
On Sat, 30 Apr 2022 18:25:29 +0800,
Shenghong Han wrote:
> 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.
I don't see any "full-width" symbols in your patch.

> 
> 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,
Now that the web page catches up v5.18-rc5, how does it look to
you?

"the current document" is always changing, so it doesn't mean
anything...

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

> 4) Apologize again for the troubles that my clumsy behaviors have> caused.
Looks like you have still a lot to improve...

Akira

> 
> Thanks, 
> 
> Shenghong Han
>  
> ------------------ Original ------------------
> From:  "Akira Yokosawa"<akiyks@gmail.com>;
> Date:  Sat, Apr 30, 2022 02:40 PM
> To:  "Shenghong Han"<hanshenghong2019@email.szu.edu.cn>; "Jonathan Corbet"<corbet@lwn.net>;
> Cc:  "akpm"<akpm@linux-foundation.org>; "baihaowen"<baihaowen@meizu.com>; "seakeel"<seakeel@gmail.com>; "linux-doc"<linux-doc@vger.kernel.org>; "linux-kernel"<linux-kernel@vger.kernel.org>; "caoyixuan2019"<caoyixuan2019@email.szu.edu.cn>; "yejiajian2018"<yejiajian2018@email.szu.edu.cn>; "yuhongf"<yuhongf@szu.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@email.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