From: Jonathan Corbet <corbet@lwn.net>
To: Shenghong Han <hanshenghong2019@email.szu.edu.cn>,
akpm@linux-foundation.org
Cc: akiyks@gmail.com, baihaowen@meizu.com, seakeel@gmail.com,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Shenghong Han <hanshenghong2019@email.szu.edu.cn>,
Yixuan Cao <caoyixuan2019@email.szu.edu.cn>,
Yinan Zhang <zhangyinan2019@email.szu.edu.cn>,
Chongxi Zhao <zhaochongxi2019@email.szu.edu.cn>,
Jiajian Ye <yejiajian2018@email.szu.edu.cn>,
Yuhong Feng <yuhongf@szu.edu.cn>
Subject: Re: [PATCH] Documentation/vm/page_owner.rst: Fix syntax error and Describe details using table
Date: Fri, 29 Apr 2022 11:29:19 -0600 [thread overview]
Message-ID: <87wnf73ij4.fsf@meer.lwn.net> (raw)
In-Reply-To: <20220429171844.9673-1-hanshenghong2019@email.szu.edu.cn>
Shenghong Han <hanshenghong2019@email.szu.edu.cn> writes:
> 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.
You *have* built the docs and know that they render as expected, right?
> Signed-off-by: Shenghong Han <hanshenghong2019@email.szu.edu.cn>
> Fixes: edc93abbcc6d ("tools/vm/page_owner_sort.c: support sorting blocks by multiple keys")
>
> Co-developed-by: Yixuan Cao <caoyixuan2019@email.szu.edu.cn>
> Co-developed-by: Yinan Zhang <zhangyinan2019@email.szu.edu.cn>
> Co-developed-by: Chongxi Zhao <zhaochongxi2019@email.szu.edu.cn>
> Co-developed-by: Jiajian Ye <yejiajian2018@email.szu.edu.cn>
> Co-developed-by: Yuhong Feng <yuhongf@szu.edu.cn>
As I mentioned the last time I saw a version of this work, if it really
took this many people to develop this one patch, then we need signoff
lines from all of them.
> ---
> Hello Andrew,
>
> In Commit 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the
> documentation") and Commit edc93abbcc6d ("tools/vm/page_owner_sort.c:
> support sorting blocks by multiple keys"), some incorrect syntax
> are used, which laeds to "build warning after merge of the mm tree".
> Apologize for that!
>
> This issue is trying to fix it.
>
> Best,
>
> Shenghong Han
> ---
> ---
> Documentation/vm/page_owner.rst | 67 ++++++++++++++++++++++-----------
> 1 file changed, 44 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/vm/page_owner.rst b/Documentation/vm/page_owner.rst
> index 25622c715..f900ab99d 100644
> --- a/Documentation/vm/page_owner.rst
> +++ b/Documentation/vm/page_owner.rst
> @@ -171,26 +171,47 @@ Usage
>
> STANDARD FORMAT SPECIFIERS
> ==========================
> -::
> -
> -For --sort option:
> -
So the simplest fix, of course, would be to just put some leading white
space before the "For" lines. Then the literal block would be
syntactically correct.
> - 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
> - ator allocator memory allocator for pages
> +
> +1) `Table 1`_ for the ``--sort`` option.
> +
> +.. table:: Table 1
> + :name: Table 1
This seems like rather more markup than is really needed? What is the
point of these tags?
> + +--------+--------------+----------------------------------------------+
> + | KEY | LONG | DESCRIPTION |
> + +========+==============+==============================================+
> + | p | pid | process ID |
> + +--------+--------------+----------------------------------------------+
...and this seems over the top. I saw a version of this that used the
simpler format:
> + ==== ========== ===========
> KEY LONG DESCRIPTION
> + ==== ========== ===========
> p pid process ID
That's just as easy to read and much easier to maintain, is there a
reason you moved away from it?
Thanks,
jon
next prev parent reply other threads:[~2022-04-29 17:29 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-29 17:18 [PATCH] Documentation/vm/page_owner.rst: Fix syntax error and Describe details using table Shenghong Han
2022-04-29 17:29 ` Jonathan Corbet [this message]
2022-04-29 18:19 Shenghong Han
2022-04-30 0:57 ` Akira Yokosawa
2022-04-30 6:40 ` Akira Yokosawa
2022-04-30 8:13 ` Shenghong Han
2022-04-30 8:29 ` Akira Yokosawa
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wnf73ij4.fsf@meer.lwn.net \
--to=corbet@lwn.net \
--cc=akiyks@gmail.com \
--cc=akpm@linux-foundation.org \
--cc=baihaowen@meizu.com \
--cc=caoyixuan2019@email.szu.edu.cn \
--cc=hanshenghong2019@email.szu.edu.cn \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=seakeel@gmail.com \
--cc=yejiajian2018@email.szu.edu.cn \
--cc=yuhongf@szu.edu.cn \
--cc=zhangyinan2019@email.szu.edu.cn \
--cc=zhaochongxi2019@email.szu.edu.cn \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.