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

[Christoph Hellwig <hch@infradead.org>]

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.