linux-kernel - Re: [PATCH] Documentation: ext4: atomic_writes: Remove cross-reference labels

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] [day] [month] [year] [list]

Message-ID: <87ldpxm9oj.fsf@trenco.lwn.net>
Date: Thu, 12 Jun 2025 06:22:20 -0600
From: Jonathan Corbet <corbet@....net>
To: "Darrick J. Wong" <djwong@...nel.org>, Bagas Sanjaya <bagasdotme@...il.com>
Cc: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>, Linux
 Documentation <linux-doc@...r.kernel.org>, Linux ext4
 <linux-ext4@...r.kernel.org>, Theodore Ts'o <tytso@....edu>, Andreas
 Dilger <adilger.kernel@...ger.ca>, "Ritesh Harjani (IBM)"
 <ritesh.list@...il.com>
Subject: Re: [PATCH] Documentation: ext4: atomic_writes: Remove
 cross-reference labels

"Darrick J. Wong" <djwong@...nel.org> writes:

>> > Sphinx wants to snarf up every .rst file it sees, regardless of whether
>> > it is explicitly made part of the document tree.  So it will pick up
>> > atomic_writes.rst separately from the include.
>
> Does that mean that overview.rst doesn't need to include the other files
> at all?

Not quite.  Sphinx does what is arguably the least useful thing possible
- it picks up and parses the file, but does not place it in the TOC
tree.  It will normally warn in such cases, at least.  So if this file
is not brought in with an "include" directive, it needs to appear in a
table of contents somewhere.

jon