linux-kernel - Re: [PATCH 0/4] Slurp (squash) ext4 subdocs

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: <87bjqjh5dr.fsf@trenco.lwn.net>
Date: Thu, 19 Jun 2025 13:56:48 -0600
From: Jonathan Corbet <corbet@....net>
To: Bagas Sanjaya <bagasdotme@...il.com>, Linux Kernel Mailing List
 <linux-kernel@...r.kernel.org>, Linux Documentation
 <linux-doc@...r.kernel.org>, Linux ext4 <linux-ext4@...r.kernel.org>
Cc: Theodore Ts'o <tytso@....edu>, Andreas Dilger
 <adilger.kernel@...ger.ca>, "Darrick J. Wong" <djwong@...nel.org>, "Ritesh
 Harjani (IBM)" <ritesh.list@...il.com>, Bagas Sanjaya
 <bagasdotme@...il.com>
Subject: Re: [PATCH 0/4] Slurp (squash) ext4 subdocs

Bagas Sanjaya <bagasdotme@...il.com> writes:

> When a doc is included by other doc via include:: directive, Sphinx will
> pick the included doc and parse it independently from the including doc
> regardless if it is listed in the docs toctree. This, however, can
> exposes duplicate label warning that refers the label to itself (bug?)
> when the label is placed before any section heading, since Sphinx
> encounters the label twice, both when parsing the included and the
> including docs.
>
> This could be solved by removing the problematic label. However, when it
> is heavily referenced by other doc (e.g. via :ref: directive), this can
> be a churn. Furthermore, the include:: usage pattern in kernel docs is
> to use it to included a common doc part that is shared by many docs
> (e.g. isonum.txt). ext4 docs, though, is the opposite: splitting docs
> into multiple reST files (subdocs) and including them in three master
> docs (overview.rst, globals.rst, and dynamic.rst)
>
> Let's slurp (squash) the subdocs instead. This will make the master docs
> larger of course (although not as big as KVM API docs), but one can use
> cross-reference labels without hitting aforementioned warning bug. Also,
> docs directory structure is tidier with only 4 files (master docs and
> about.rst). As a bonus, also reduce toctree depth as to not spill the
> whole hierarchy.

"slurp" is not exactly a technical term that will make sense to readers
of the changelogs.

But, more importantly... Might it be that the current file structure
reflects the way the authors wanted to manage the docs?  It seems to me
that just organizing the existing files into a proper toctree would be
rather less churny and yield useful results, no?

jon