Re: Converting README documentation to Markdown

On 10.09.24 14:50, Daniel Gustafsson wrote:
>> On 1 Jul 2024, at 12:22, Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:
>
>> 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.
>
> Since there doesn't seem to be much interest in going all the way to Markdown,
> the attached 0001 is just the formatting changes for achieving (to some degree)
> consistency among the README's. This mostly boils down to using a consistent
> amount of whitespace around code, using the same indentation on bullet lists
> and starting sections the same way. Inspecting the patch with git diff -w
> reveals that it's not much left once whitespace is ignored. There might be a
> few markdown hunks left which I'll hunt down in case anyone is interested in
> this.

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.

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.

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.
(There are also a couple of places where apparently you changed
whitespace that wasn't necessary to be changed.)

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.

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