Hacker News Reader

Comment by keybored | Hacker News Reader

Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable.

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.

View on HN

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.

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.

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) ?

"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.

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...

What is "regular markup"?

Markup not of the lightweight kind.

Reply on news.ycombinator.com