linux-ext4 - Re: [PATCH] Documentation: document the design of iomap and how to port

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: <ZmVNblggFRgR8bnJ@infradead.org>
Date: Sat, 8 Jun 2024 23:36:30 -0700
From: Christoph Hellwig <hch@...radead.org>
To: "Darrick J. Wong" <djwong@...nel.org>
Cc: "Ritesh Harjani (IBM)" <ritesh.list@...il.com>,
	linux-ext4@...r.kernel.org, linux-xfs@...r.kernel.org,
	linux-fsdevel@...r.kernel.org, Dave Chinner <david@...morbit.com>,
	Matthew Wilcox <willy@...radead.org>,
	Christoph Hellwig <hch@...radead.org>,
	Christian Brauner <brauner@...nel.org>,
	Ojaswin Mujoo <ojaswin@...ux.ibm.com>, Jan Kara <jack@...e.cz>,
	Luis Chamberlain <mcgrof@...nel.org>
Subject: Re: [PATCH] Documentation: document the design of iomap and how to
 port

On Fri, Jun 07, 2024 at 05:17:07PM -0700, Darrick J. Wong wrote:
> From: Darrick J. Wong <djwong@...nel.org>
> 
> This is the fourth attempt at documenting the design of iomap and how to

The number of attempts should go out of the final commit version..

> port filesystems to use it.  Apologies for all the rst formatting, but
> it's necessary to distinguish code from regular text.

Maybe we should do this as a normal text file and not rst then?

> +.. SPDX-License-Identifier: GPL-2.0
> +.. _iomap:
> +
> +..
> +        Dumb style notes to maintain the author's sanity:
> +        Please try to start sentences on separate lines so that
> +        sentence changes don't bleed colors in diff.
> +        Heading decorations are documented in sphinx.rst.

Should this be in the document and not a README in the directory?

That being said starting every sentence on a new line makes the text
really hard to read.  To the point that I'll really need to go off
and reformat it before making it beyond the first few paragraphs.
I'll try to do that and will return to it later, sorry for just
dropping these procedural notes for now.