Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by LukeShu on Friday November 04, 2022 @01:16PM
(#33470288)
For a long time reStructuredText was "the Python thing", the way POD is "the Perl thing", where it's the "only" choice in that ecosystem, but you didn't really see it outside of that ecosystem. But nowadays (thanks to Sphinx?) reStructuredText is also used for big systems-y projects, including the Linux kernel docs and Envoy proxy.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by kzrdude on Friday November 04, 2022 @02:02PM
(#33471184)
rST is nice for making complete documents, but for smaller things it just is not practical. For one-off things (like github comments) or smaller wikis, markdown is just more practical. rST has bigger reliance on a mildly smart editor than markdown has, just to handle indentation.
The upside of rST is that it's just more complete, it has more document elements available. Markdown is often written without thought to having a readable plain text document, but rST is often very readable in plain text too.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by ilyt on Friday November 04, 2022 @01:48PM
(#33470910)
Markdown have a bit of fragmentation problem. CommonMark and Github variant have been nice steps forward, but for code I'd like to have some more extensions rolled in as another standard. For code docs in particular ability to just embed text diagrams would be great, you can hack around that with PlantUML but then you need to have stuff that supports it...
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by NoThisIsMe on Friday November 04, 2022 @01:50PM
(#33470949)
What is "regular markup"?
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by keybored on Friday November 04, 2022 @05:46PM
(#33474284)
Markup not of the lightweight kind.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by euroderf on Friday November 04, 2022 @03:03PM
(#33472019)
Does any of them make it easy to (a) define & use footnotes, and then (b) render the footnotes flexibly as a default, for example as either (b.1) end-of-page (in page-oriented physical formats) or (b.2) in Tufte-style side notes (in unpaged online formats) ?
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by xtiansimon on Sunday November 06, 2022 @09:39AM
(#33493078)
"Nesting things should be tablestakes in a markup language."
This is my beef with Markdown. Automatically numbered lists always break for me--every time. And Markdown doesn't support decimal numbered lists (1, 2, 2.1, 2.2).
I can ignore spacing, because every markdown has bad spacing (space before and after a formatted block or header or list), but I loath the inflexibility of numbered lists.
That said, for my projects I use Markdown, because its so simple--necessary and (mostly) sufficient.
Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be tablestakes in a markup language.
I don’t know much about RestructuredText (no, I won’t play these silly free-caps games) but it doesn’t look that nice to me for whatever reason. It looks the closest to regular markup to me except they have replaced things like brackets with backticks.
And finally I am glad that I never have to use some Wiki lightweight markup variant with silly syntax like using X numbers of apostrophes for emphasis or whatever.