Re: Converting README documentation to Markdown

On 2024-04-08 21:29 +0200, Daniel Gustafsson wrote:
> 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."

+1 for keeping the plaintext readable.

> 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.

I've only peeked at a couple of those READMEs, but they look alright so
far (at least on GitHub). Should we settle on a specific Markdown
flavor[1]? Because I'm never sure if some markups only work on
specific code-hosting sites. Maybe also a guide on writing Markdown
that renders properly, especially with regard to escaping that may be
necessary (see below).

> The non-whitespace changes introduced are:
>
> [...]
>
> * 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.

Escaping does the trick: regc_\*.c

> [...]
>
> * 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.

Can be escaped as well: \<X>

[1] https://markdownguide.offshoot.io/extended-syntax/#lightweight-markup-languages

--
Erik