Re: Converting README documentation to Markdown

On Fri, 28 Jun 2024 at 20:40, Peter Eisentraut <peter(at)eisentraut(dot)org> wrote:
> I have my "less" set up so that "less somefile.md" automatically renders
> the markdown. That's been pretty useful. But if that now keeps making
> a mess out of PostgreSQL's README files, then I'm going to have to keep
> fixing things, and I might get really mad. That's the worst that could
> happen. ;-)

Do you have reason to think that this is going to be a bigger issue
for Postgres READMEs than for any other markdown files you encounter?
Because this sounds like a generic problem you'd run into with your
"less" set up, which so far apparently has been small enough that it's
worth the benefit of automatically rendering markdown files.

> So I don't agree with "aspirational markdown". If we're going to do it,
> then I expect that the files are marked up correctly at all times.

I think for at least ~90% of our README files this shouldn't be a
problem. If you have specific ones in mind that contain difficult
markup/diagrams, then maybe we shouldn't convert those.

> Conversely, what's the best that could happen?

That your "less" would automatically render Postgres READMEs nicely.
Which you say has been pretty useful ;-) And maybe even show syntax
highlighting for codeblocks.

P.S. Now I'm wondering what your "less" is.