Re: Converting README documentation to Markdown

From: Erik Wienhold <ewie(at)ewie(dot)name>
To: Daniel Gustafsson <daniel(at)yesql(dot)se>
Cc: PostgreSQL Developers <pgsql-hackers(at)lists(dot)postgresql(dot)org>, Andres Freund <andres(at)anarazel(dot)de>
Subject: Re: Converting README documentation to Markdown
Date: 2024-04-08 20:30:20
Message-ID: n5iei7cclf7f44k4rfpgrnhbftadsqmxp7yxsunegcgz32jjm3@2ennzuzdkchr
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: 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 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:
> 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>



In response to


Browse pgsql-hackers by date

  From Date Subject
Next Message Daniel Gustafsson 2024-04-08 20:42:00 Re: Converting README documentation to Markdown
Previous Message Tom Lane 2024-04-08 20:04:50 Re: psql's FETCH_COUNT (cursor) is not being respected for CTEs