Re: Converting README documentation to Markdown

> On 28 Jun 2024, at 09:38, Peter Eisentraut <peter@eisentraut.org> wrote:

> I've been thinking about this some more.  I think the most value here would be to just improve the plain-text formatting, so that there are consistent list styles, header styles, indentation, some of the ambiguities cleared up -- much of which your 0001 patch does.  You might as well be targeting markdown-like conventions with this; they are mostly reasonable.

(I assume you mean 0002).  I agree that the increased consistency is worthwhile
even if we don't officially convert to Markdown (ie only do 0002 and not 0001).

> I tend to think that actually converting all the README files to README.md could be a net negative for maintainability.  Because now you are requiring everyone who potentially wants to edit those to be aware of Markdown syntax

Fair enough, but we currently expect those editing to be aware of our syntax
which isn't defined at all (leading to the variations this patchset fixes).
I'm not sure whats best for maintainability but I do think the net change is
all that big.

> and manually check the rendering.

That however would be a new requirement, and I can see that being a deal-
breaker for introducing this.

Attached is a v2 which fixes a conflict, if there is no interest in Markdown
I'll drop 0001 and the markdown-specifics from 0002 to instead target increased
consistency.

--
Daniel Gustafsson