On Tue, Jul 2, 2024 at 4:10 PM SeongJae Park <sj@xxxxxxxxxx> wrote: > > Hello Jiaqi, > > > On Mon, 1 Jul 2024 23:37:55 -0700 Jiaqi Yan <jiaqiyan@xxxxxxxxxx> wrote: > > > On Mon, Jul 1, 2024 at 11:18 PM Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx> wrote: > > > > > > On Mon, 1 Jul 2024 21:33:20 -0700 Jiaqi Yan <jiaqiyan@xxxxxxxxxx> wrote: > > > > > > > > > This seems a reasonable thing to do so there's probably some way in > > > > > > which to do it, but a bit of grepping failed to turn up examples in > > > > > > existing .rst files. Can someone please suggest? > > > > > > > > > > It seems I need to add some blank lines according to [1], especially > > > > > to add a blank line above the first list item: > > According to my understanding and testing on my machine, it seems we need blank > lines only before and after the blocks. Yes, as stated in [1], "The blank line above the first list item is required; blank lines between list items (such as below this paragraph) are optional." > > [...] > > > > Ah, sorry Andrew, I should sent out this diff, as there are more blank > > lines needed: > > > > diff --git a/Documentation/admin-guide/sysctl/vm.rst > > b/Documentation/admin-guide/sysctl/vm.rst > > index 75e22137d849..f48eaa98d22d 100644 > > --- a/Documentation/admin-guide/sysctl/vm.rst > > +++ b/Documentation/admin-guide/sysctl/vm.rst > > @@ -274,12 +274,15 @@ Correctable memory errors are very common on > > servers. Soft-offline is kernel's > > solution for memory pages having (excessive) corrected memory errors. > > > > For different types of page, soft-offline has different behaviors / costs. > > + > > So, this was needed to make 'make htmldocs' quiet on my machine. Absolutely. > > > - For a raw error page, soft-offline migrates the in-use page's content to > > a new raw page. > > + > > - For a page that is part of a transparent hugepage, soft-offline splits the > > transparent hugepage into raw pages, then migrates only the raw error page. > > As a result, user is transparently backed by 1 less hugepage, impacting > > memory access performance. > > + > > But above two blank lines were not really needed to make 'make htmldocs' calm, > at least on my setup. Many other documents also don't have this kind of blank > line. Yes, they are optional. > > > - For a page that is part of a HugeTLB hugepage, soft-offline first migrates > > the entire HugeTLB hugepage, during which a free hugepage will be consumed > > as migration target. Then the original hugepage is dissolved into raw > > @@ -296,8 +299,11 @@ the request to soft offline the pages. Its > > default value is 1. > > > > It is worth mentioning that after setting enable_soft_offline to 0, the > > following requests to soft offline pages will not be performed: > > + > > Interestingly, 'make htmldocs' didn't complain even if I don't put this blank In fact, without this blank line, even though make htmldocs doesn't throw ERROR or WARNING, the output html file is broken: there is no bullet point for the list items below. > line. But for consistency (see the beginning of sysctl/vm.rst), I think having > this would be good. Agreed. > > > - Request to soft offline pages from RAS Correctable Errors Collector. > > + > > - On ARM, the request to soft offline pages from GHES driver. > > + > > Again, same to the reason above, it seems above two blank lines are not really > needed. Yep, optional again. I mainly just want to be consistent. > > > - On PARISC, the request to soft offline pages from Page Deallocation Table. > > > > extfrag_threshold > > > > I have no strong opinion about these, though. Having four more blank lines > that might unnecessary is obviously no problem. > > > Thanks, > SJ
