Re: Converting README documentation to Markdown

> On 23 Sep 2024, at 13:58, Peter Eisentraut <peter(at)eisentraut(dot)org> wrote:

> I went through this file by file and checked the results of a markdown-to-HTML conversion using cmark and looking at the raw output source files.

Thanks for reviewing!

I thought the consensus of the thread was to skip Markdown compatibility and
only go for more consistency in the current format, so I didn't check any such
results when proposing that version. I've checked with the Markdown rendering
preview in VSCode for this.

Placing the goalposts in the right place seems useful, should we aim for
Markdown, or a consistent look-and-feel regardless of markdown compatibility.

> A lot of the changes are obvious and make sense. But there are a number of cases of code within lists or nested lists or both that need further careful investigation. I'm attaching a fixup patch where I tried to improve some of this (and a few other things I found along the way). Some of the more complicated ones, such as src/backend/storage/lmgr/README-SSI, will need to be checked again and even more carefully to make sure that the meaning is not altered by these patches.

Agreed. Checking it I don't see any such cases but more careful looking is
needed.

> One underlying problem that I see is that markdown assumes four-space tabs, but a standard editor configuration (and apparently your editor) uses 8 tabs. But then, if you have a common situation like
>
> ```
> 1. Run this code
>
> <tab>$ sudo kill
> ```
>
> then that's incorrect (the code line will not be inside the list), because it should be
>
> ```
> 1. Run this code
>
> <tab><tab>$ sudo kill
> ```
>
> or
>
> ```
> 1. Run this code
>
> <8 spaces>$ sudo kill
> ```
>
> So we need to think about a way to make this more robust for future people editing. Maybe something in .gitattributes or some editor settings. Otherwise, it will be all over the places after a while.

Maybe we can add some form of pandoc target for rendering as as way to test
locally before pushing? (For those with pandoc installed, but we already have
the infrastructure in meson to use pandoc so it could be convenient perhaps).

> (There are also a couple of places where apparently you changed whitespace that wasn't necessary to be changed.)

It was to make the files look and feel consistent, I've tried to reduce that in
the attached.

> Apart from this, I don't changing the placeholders like <foo> to < foo >. In some cases, this really decreases readability. Maybe we should look for different approaches there.

Agreed. I took a stab at some of them in the attached. The usage in
src/test/isolation/README is seemingly the hardest to replace and I'm not sure
how we should proceed there.

> Maybe there are some easy changes that could be extracted from this patch, but the whitespace and list issue needs more consideration.

If we want to reduce the size of this I think the changes which add a line of
whitespace could be broken out and committed separately. One random example
from the diff being:

***
Outer join identity 3 (discussed above) complicates this picture
a bit. In the form
+
A leftjoin (B leftjoin C on (Pbc)) on (Pab)
+
all of the Vars in clauses Pbc and Pab will have empty varnullingrels,
but if we start with
***

Personally I consider those changes a win for readability on their own
regardless of any progress towards Markdown.

The attached has your changed rolled into 0001 and any new changes in 0002 for
ease of skimming the diffs.

--
Daniel Gustafsson