Messages in this thread |  | | From | Jonathan Corbet <> | | 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 |
| |
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
|  |