Re: Converting README documentation to Markdown

From: Daniel Gustafsson <daniel(at)yesql(dot)se>
To: Erik Wienhold <ewie(at)ewie(dot)name>
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:42:00
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

> On 8 Apr 2024, at 22:30, Erik Wienhold <ewie(at)ewie(dot)name> wrote:
> On 2024-04-08 21:29 +0200, Daniel Gustafsson wrote:

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

Probably, but if we strive for maintained textual readability with avoiding
most of the creative markup then we're probably close to the original version.
But I agree, it should be evaluated.

> Maybe also a guide on writing Markdown
> that renders properly, especially with regard to escaping that may be
> necessary (see below).

That's a good point, if we opt for an actual format there should be some form
of documentation about that format, especially if we settle for using a
fraction of the capabilities of the format.

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

Right, but that makes the plaintext version less readable than the backticks I

> Can be escaped as well: \<X>

..and same with this one. It's all very subjective though.

Daniel Gustafsson

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Dmitry Koval 2024-04-08 20:43:21 Re: Add SPLIT PARTITION/MERGE PARTITIONS commands
Previous Message Erik Wienhold 2024-04-08 20:30:20 Re: Converting README documentation to Markdown