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
