5 ms·
I love Markdown. I enjoy RST. I think, like programming, they have their own merits and use cases. Markdown is a lot less verbose in my opinion than RST. It's
by ajford 11y ago
I love Markdown. I enjoy RST. I think, like programming, they have their own merits and use cases.
Markdown is a lot less verbose in my opinion than RST. It's not intentional, nor is it insurmountable, but little things like inline code, hyperlinks, defined subsection levels, and many more all add up to a bit of cognitive load that I don't need for all situations. When I'm writing quick notes for a meeting, or trying to jot down something, RST is a bit much. Which perhaps isn't what this article is really harping on.
But when my quick notes to myself about a project turn long-winded and become more of functional docs, it can be a pain to rewrite that into rst.
I do, however, tend to use RST when I sit down to write documentation for a project. I even tend to use it when documenting firmware and hardware portions of projects. This of course due to the so far poor handling of images in Markdown.
So like I said above, they are tools. One may be better suited to something than the other. But thus is the nature of tools. Use the right tool for the right job whenever possible.
- parenthephobia 11y agoIf I need a level of control over the text that Markdown doesn't offer, I break out the HTML+CSS. I cheat by using made up context-specific semantic elements so I don't have class="foo" everywhere, and the result is pretty structured and not hard for a clueful novice to understand. It's also not that hard to move from Markdown to HTML incrementally, and generally unnecessary at all for long prose sections if you're not averse to having mixed HTML/Markdown source. To me, RST smells very much like XML for people who don't want to admit they're writing XML. It superficially has the appearance of being "normal" plain text writing, but that illusion is fragile if you're not familiar with the language. IMO, it's akin to COBOL or SQL in that way.
- dunham 11y agoit can be a pain to rewrite that into rst. If you just want to rewrite markdown into rst, "pandoc" will do the trick.
- ajford 11y agoTrue. But that's not always all that's needed. If I decide to flesh out an API section, it would be better to put the work in and use autodoc (which of course means I have to go make sure my docstrings are up to date). Build a TOC. A lot of things in RST are not in Markdown (the whole point of this article), and would have to be added to really take advantage of RST.
- chipsy 11y agoWhen I was confronted with this dilemma for the first time I attacked it by using multiple passes. My original draft is markdown. I pandoc it to DocBook. Then I add frills and edits in DocBook. I see the process as not being different from what's needed to do the writing - compiling notes and sketches and outlines into a coherent narrative.
- vq 11y agoI have a very similar process. I start of with an org document, do a couple of drafts and then pandoc to LaTeX, pull in the proper template and add the frills as you say.