linux-kernel - Re: [PATCH 2/2] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

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]

Message-ID: <20250910155021.418ac199@foz.lan>
Date: Wed, 10 Sep 2025 15:50:41 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Michal Koutný <mkoutny@...e.com>, Bagas Sanjaya
 <bagasdotme@...il.com>, Mauro Carvalho Chehab <mchehab@...nel.org>, Linux
 Kernel Mailing List <linux-kernel@...r.kernel.org>, Linux Documentation
 <linux-doc@...r.kernel.org>, Linux cgroups <cgroups@...r.kernel.org>, Tejun
 Heo <tj@...nel.org>, Johannes Weiner <hannes@...xchg.org>, Andrea Righi
 <arighi@...dia.com>, Johannes Bechberger <me@...tlynerdless.de>, Changwoo
 Min <changwoo@...lia.com>, Shashank Balaji <shashank.mahadasyam@...y.com>,
 Ingo Molnar <mingo@...nel.org>, Jake Rice <jake@...erice.dev>, Cengiz Can
 <cengiz@...nel.wtf>
Subject: Re: [PATCH 2/2] Documentation: cgroup-v2: Replace manual table of
 contents with contents:: directive

Em Wed, 10 Sep 2025 07:24:45 -0600
Jonathan Corbet <corbet@....net> escreveu:

> Michal Koutný <mkoutny@...e.com> writes:
> 
> > On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@...il.com> wrote:  
> >> manually-arranged table of contents (as reST comments) gets out-of-sync
> >> with actual toctree as not all of these are added to it.  
> >
> > Is this true? I generated HTML with this patch and the resulting ToC
> > matches what's in the comment.
> >  
> >> Replace it with automatically-generated table of contents via contents::
> >> directive.  
> >
> > Mauro, what's the best practice wrt consistent ToC and having it in
> > plaintext form?  
> 
> I fairly routinely get patches fixing manual TOCs that are not updated
> to match changes elsewhere.  We have a nice system that can manage the
> TOC automatically for us, it seems best to me to use it.

Agreed. If you use:


	.. toctree::
	   :maxdepth: 1
	   :glob:

	   * 

There won't be the need of manually updating the TOC tree.

That's said, I guess very few documents currently use grub:
	$ git grep :glob: Documentation/|wc -l
	7

Also, it has some drawbacks, as you can't control anymore the order 
where the docs will be placed. So, if this is important, you may need
to do something different, or maybe use things like (untested):

	.. toctree::
	   :maxdepth: 1
	   :glob:

	   pre*
	   main*
	   post*

> That said, if having the TOC in the plain-text version of the document
> is deemed to be important, then it needs to be kept and manually
> maintained.

Agreed.


Thanks,
Mauro