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

Message-ID: <20250612010942.GJ6179@frogsfrogsfrogs>
Date: Wed, 11 Jun 2025 18:09:42 -0700
From: "Darrick J. Wong" <djwong@...nel.org>
To: Bagas Sanjaya <bagasdotme@...il.com>
Cc: Jonathan Corbet <corbet@....net>,
	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

On Thu, Jun 12, 2025 at 07:07:00AM +0700, Bagas Sanjaya wrote:
> On Wed, Jun 11, 2025 at 11:05:17AM -0600, Jonathan Corbet wrote:
> > "Darrick J. Wong" <djwong@...nel.org> writes:
> > 
> > > On Tue, Jun 10, 2025 at 04:11:59PM +0700, Bagas Sanjaya wrote:
> > >> Sphinx reports htmldocs warnings on ext4 atomic block writes docs:
> > >> 
> > >> Documentation/filesystems/ext4/atomic_writes.rst:5: WARNING: duplicate label atomic_writes, other instance in Documentation/filesystems/ext4/atomic_writes.rst
> > >> Documentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate label atomic_write_bdev_support, other instance in Documentation/filesystems/ext4/atomic_writes.rst
> > >> 
> > >> These warnings reference duplicated cross-reference labels to themselves in
> > >> the same doc, which are because atomic_writes.rst is transcluded in
> > >> overview.rst via include:: directive, thus the culprit docs get processed
> > >> twice.
> > >
> > > <confused> How is that possible?  atomic_writes.rst is only "include::"d
> > > once in overview.rst.  Is the file implicitly included through some
> > > other means?
> > 
> > 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?

> > This could be "fixed" by removing the .rst extension from the included
> > file.  But, since there is no use of the atomic_writes label to begin
> > with, it's better to just take it out.  The other fix, removing a cross
> > reference, is not entirely ideal, but there is little text between the
> > label and the reference.
> 
> So removing the labels looks good to you, right?

I don't care that much either way, but if sphinx is going to include
every rst file implicitly then maybe we just get rid of the explicit
includes?

> Confused...

Me too.

--D

> 
> -- 
> An old man doll... just what I always wanted! - Clara