Re: Converting README documentation to Markdown - Mailing list pgsql-hackers

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