linux-kernel - Re: [PATCH] Documentation: Add a source tree map overview

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: <aDz92QNc3ZSVkdx3@archie.me>
Date: Mon, 2 Jun 2025 08:26:49 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Randy Dunlap <rdunlap@...radead.org>,
	William Raezer <wraezer@...il.com>, linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, corbet@....net
Subject: Re: [PATCH] Documentation: Add a source tree map overview

On Sun, Jun 01, 2025 at 09:50:14AM -0700, Randy Dunlap wrote:
> Hi,
> 
> On 6/1/25 9:22 AM, William Raezer wrote:
> > Hello,
> > 
> 
> Please wrap email lines at around 72-75 characters each.
> 
> > My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.
> 
> This looks somewhat useful, although I was expecting more of a graphic presentation
> of the tree structure. But that would cause trouble with the role of each subdirectory.
> (and one can always use `tree` for that)

I was expecting tree output either.

> 
> > As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
> > 
> > The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
> > 
> > I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.
> 
> Patches should generally be inline as email text, not as attachments.
> This is up to the maintainer to decide about...
> and gmail is not good as maintaining whitespace in emails.
> (I don't see any whitespace problems in the current patch.)

tl;dr: see Documentation/process/submitting-patches.rst.

> 
> I get a warning when building with this patch applied:
> 
> Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]

make htmldocs.

> 
> Also, when I look at source-map.html with a web browser, no parts of
> the source-map are shown. (tested with multiple browsers)

Do you mean toctree in the sidebar?

Thanks.

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

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)