Received-SPF: pass (google.com: domain of linux-ext4+bounces-2834-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
Date: Sat, 8 Jun 2024 23:36:30 -0700
From: Christoph Hellwig <hch@infradead.org>
To: "Darrick J. Wong" <djwong@kernel.org>
Cc: "Ritesh Harjani (IBM)" <ritesh.list@gmail.com>,
	linux-ext4@vger.kernel.org, linux-xfs@vger.kernel.org,
	linux-fsdevel@vger.kernel.org, Dave Chinner <david@fromorbit.com>,
	Matthew Wilcox <willy@infradead.org>,
	Christoph Hellwig <hch@infradead.org>,
	Christian Brauner <brauner@kernel.org>,
	Ojaswin Mujoo <ojaswin@linux.ibm.com>, Jan Kara <jack@suse.cz>,
	Luis Chamberlain <mcgrof@kernel.org>
Subject: Re: [PATCH] Documentation: document the design of iomap and how to
 port
Message-ID: <ZmVNblggFRgR8bnJ@infradead.org>
References: <20240608001707.GD52973@frogsfrogsfrogs>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20240608001707.GD52973@frogsfrogsfrogs>

On Fri, Jun 07, 2024 at 05:17:07PM -0700, Darrick J. Wong wrote:
> From: Darrick J. Wong <djwong@kernel.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.