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." 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. The non-whitespace changes introduced are: * Section/subsection markers: Basically all our files underline the main section with ==== and subsections with ----. This renders perfectly well with. Markdown so add these to the few that didn't have them. * The SSL readme starts a sentence with ">" which renders as quote, removing that fixes rendering and makes the plain text version better IMHO. * 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. * Some bulletlists characters are changed to match the syntax, which also makes them more consistent with all the other README files in the tree. In one case (SSL test readme) there were no bullets at all which is both inconsistent and renders poorly. * 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. * Text quoted with backticks, like `foo' is replaced with 'foo' to keep it from rendering like code. * Rather than indenting the whole original README for bsd_indent I added ``` to make it a code block, ie render without formatting. The README files in doc/ are left untouched as they contain lots of <foo> XML tags which all would need to be wrapped in backticks at the cost of plain text readability. Might not be controversial and in that case they can be done too, but I left them for now since they deviated from the least-changes-possible plan for the patchset. It can probably be argued thats lots of other READMEs can be skipped as well, like all the ones in test modules which have 4 lines saying the directory contains a test for the thing which the name of the directory already gave away. For completeness I left those in though, they for the most part go untouched. It's not perfect by any stretch, there are still for example cases where a * in the text turns on italic rendering which wasn't the intention if the author. Resisting the temptation to go overboard with changes is however a design goal, these are after all work documents and should be functional and practical. In order to make review a bit easier I've split the patch into two, one for the file renaming and one for the changes. Inspecting the 0002 diff by skipping whitespace shows the above discussed changes. Thoughts? -- Daniel Gustafsson [0] 20240405000935.2zujjc5t5e2jai4k@awork3.anarazel.de [1] CAG6XLEmGE95DdKqjk+Dd9vC8mfN7BnV2WFgYk_9ovW6ikN0YSg@mail.gmail.com [2] https://daringfireball.net/projects/markdown/