These all feel like issues that power-users have, not an issue that lil' ol' me is going to run into while jotting down journal entries, or yelling at people on the internet with emphasis.
lifthrasiir · 55m ago
Guaranteed, reST is more feature-complete and extension-friendly, but it is simply unusable for me because it wasn't designed for agglutinative languages like Korean. Markdown is much better in this case (though CommonMark has an annoying edge case [1]).
What do you mean not designed for Korean? If there's some situation where RST isn't parsing inline markup, you can write the role explicitly like this:
this is **bold** text
this is :strong:`bold` text
bluGill · 1h ago
My only problem with rst is that several useful the extentions are not updated. I have some great rst documentation, but part of that is I importing doxygen, dolphin, and other extentions that are useful but saddly not updated on the same schedule as the main tool. I end up many versions back just because it is all that is compatible.
still markdown just isn't powerful enough for anything non trivial.
lifthrasiir · 41m ago
The original spirit of Markdown was to use HTML elements (or custom elements if you like) for whatever is missing from Markdown. That's surprisingly versatile in hindsight, but the specification didn't fully anticipate what happens to Markdown contents inside such elements. Some implementations supported them, some didn't, some used the `markdown` pseudo-attribute, and so on. And it was even less clear how block syntaxes work inside HTML elements. (CommonMark defines a very lengthy list of rules for them [1].) Markdown could have been extensible... if it did have a sensible specification from beginning.
For books or significant document sets I definitely agree with the author on this. The builtin features for glossary and index are also nice. The extensibility is amazing. Some people are even doing formal requirements and lifecycle management in RST these days!!
This looks kind of useful for creating good contexts about project requirements
betaby · 39m ago
'asciidoc' is the middle ground.
klodolph · 2m ago
I think of it less like the middle ground, and more like the best of the three
asciidoc > rst > markdown
It’s just that the available tooling goes the opposite way,
markdown tooling > rst tooling > asciidoc tooling
I end up using HTML for anything serious instead, because it has better tooling support than any of the three, and is also more flexible. It’s just more verbose, which is fine.
ajross · 50m ago
Everyone who works seriously with editing and formatting documentation for presentation prefers RST.
Markdown is for the people, almost never full time doc jockeys, who need to WRITE that documentation.
[1] https://talk.commonmark.org/t/foo-works-but-foo-fails/2528
still markdown just isn't powerful enough for anything non trivial.
[1] https://spec.commonmark.org/0.31.2/#html-blocks
https://www.sphinx-needs.com/
asciidoc > rst > markdown
It’s just that the available tooling goes the opposite way,
markdown tooling > rst tooling > asciidoc tooling
I end up using HTML for anything serious instead, because it has better tooling support than any of the three, and is also more flexible. It’s just more verbose, which is fine.
Markdown is for the people, almost never full time doc jockeys, who need to WRITE that documentation.