Converting README documentation to Markdown

Over in [0] I asked whether it would be worthwhile converting all our README
files to Markdown, and since it wasn't met with pitchforks I figured it would
be an interesting excercise to see what it would take (my honest gut feeling
was that it would be way too intrusive). Markdown does brings a few key
features however so IMHO it's worth attempting to see:

* New developers are very used to reading/writing it
* Using a defined format ensures some level of consistency
* Many users and contributors new *as well as* old like reading documentation
nicely formatted in a browser
* The documentation now prints really well
* pandoc et.al can be used to render nice looking PDF's
* All the same benefits as discussed in [0]

The plan was to follow Grubers original motivation for Markdown closely:

"The idea is that a Markdown-formatted document should be publishable
as-is, as plain text, without looking like it’s been marked up with
tags or formatting instructions."

This translates to making the least amount of changes to achieve a) retained
plain text readability at todays level, b) proper Markdown rendering, not
looking like text files in a HTML window, and c) absolutly no reflows and
minimal impact on git blame.

Turns out we've been writing Markdown for quite some time, so it really didn't
take much at all. I renamed all the files .md and with almost just changing
whitespace achieved what I think is pretty decent results. The rendered
versions can be seen by browsing the tree below:

https://github.com/danielgustafsson/postgres/tree/markdown

The whitespace changes are mostly making sure that code (anything which is to
be rendered without styling really) is indented from column 0 with tab or 4
spaces (depending on what was already used in the file) and has a blank line
before and after. This is the bulk of the changes. The non-whitespace changes
introduced are:

* Section/subsection markers: Basically all our files underline the main
section with ==== and subsections with ----. This renders perfectly well with.
Markdown so add these to the few that didn't have them.

* The SSL readme starts a sentence with ">" which renders as quote, removing
that fixes rendering and makes the plain text version better IMHO.

* In the regex README there are two file references using * as a wildcard, but
the combination of the two makes Markdown render the text between them in
italics. Wrapping these in backticks solves it, but I'm not a fan since we
don't do that elsewhere. A solution which avoids backticks would ne nice.

* Some bulletlists characters are changed to match the syntax, which also makes
them more consistent with all the other README files in the tree. In one
case (SSL test readme) there were no bullets at all which is both
inconsistent and renders poorly.

* Anything inside <> is rendered as a link if it matches, so in cases where <X>
is used to indicatee "replace with X" I added whitespace like "< X >" which
might be a bit ugly, but works. When referencing header files with <time.h>
the <> are removed to just say the header name, which seemed like the least bad
option there.

* Text quoted with backticks, like `foo' is replaced with 'foo' to keep it from
rendering like code.

* Rather than indenting the whole original README for bsd_indent I added ``` to
make it a code block, ie render without formatting.

The README files in doc/ are left untouched as they contain lots of <foo> XML
tags which all would need to be wrapped in backticks at the cost of plain text
readability. Might not be controversial and in that case they can be done too,
but I left them for now since they deviated from the least-changes-possible
plan for the patchset. It can probably be argued thats lots of other READMEs
can be skipped as well, like all the ones in test modules which have 4 lines
saying the directory contains a test for the thing which the name of the
directory already gave away. For completeness I left those in though, they for
the most part go untouched.

It's not perfect by any stretch, there are still for example cases where a * in
the text turns on italic rendering which wasn't the intention if the author.
Resisting the temptation to go overboard with changes is however a design goal,
these are after all work documents and should be functional and practical.

In order to make review a bit easier I've split the patch into two, one for the
file renaming and one for the changes. Inspecting the 0002 diff by skipping
whitespace shows the above discussed changes.

Thoughts?

--
Daniel Gustafsson

[0] 20240405000935(dot)2zujjc5t5e2jai4k(at)awork3(dot)anarazel(dot)de
[1] CAG6XLEmGE95DdKqjk+Dd9vC8mfN7BnV2WFgYk_9ovW6ikN0YSg(at)mail(dot)gmail(dot)com
[2] https://daringfireball.net/projects/markdown/