The thing with Markdown is that it does most of what you need to do with it, until it doesn't, when you can bring Pandoc to bear and put full-on LaTeX in your Markdown and it will render it however you want. I wrote a dissertation this way with inlined Rmarkdown code. It was great.
Compare AsciiDoc and Markdown
101–110 of 137 posts
Re: Compare AsciiDoc and Markdown
#102The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”.
Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”.
Most of the big Markdown-using services (GitHub, GitLab, Reddit, Stack Overflow, etc.) implement this spec, so it is basically the Markdown spec, all but in name.
It can be found at https://spec.commonmark.org/
Re: Compare AsciiDoc and Markdown
#103The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”. Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”. Mo…
From what I remember, John McFarlane and his Pandoc project helped a lot in getting CommonMark adopted.
Github used to have its own "Github-flavored Markdown" before CommonMark came along.
Re: Compare AsciiDoc and Markdown
#104Earlier quoted context omitted.
RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain as web applications of it will commonly go for, where any indentation must be applied manually by th…
rST doesn't support nesting markup (bold and italic? nope. code styling in a link? nope.). It's decent for writing software docs, but not good at all (in my opinion) for writing blog posts or other prose.
Re: Compare AsciiDoc and Markdown
#105The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”. Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”. Mo…
From what I remember, John McFarlane and his Pandoc project helped a lot in getting CommonMark adopted. Github used to have its own "Github-flavored Markdown" before CommonMark came along.
Correct, he (jgm on GitHub) is still by far the biggest contributor to the spec: https://github.com/commonmark/commonmark-spec/graphs/contrib...
Re: Compare AsciiDoc and Markdown
#106The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”. Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”. Mo…
I'm not a Gruber fan but I think his actions in this case are totally defensible. Every month on HN there's a post about some OSS project mod stepping down due to abuse and insane expectations from the community.
Gruber wrote a tool that solved his own personal problem, shared it with the world because why not, and then made damn sure he wasn't going to have to deal with any fallout put on him for his sharing.
Re: Compare AsciiDoc and Markdown
#107Earlier quoted context omitted.
I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain as web applications of it will commonly go for, where any indentation must be applied manually by th…
rST doesn't support nesting markup (bold and italic? nope. code styling in a link? nope.). It's decent for writing software docs, but not good at all (in my opinion) for writing blog posts or other prose.
Code styling in a link sounds useful, but bold and italic generally shouldn't be combined[0].
Re: Compare AsciiDoc and Markdown
#108The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”. Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”. Mo…
I'm not a Gruber fan but I think his actions in this case are totally defensible. Every month on HN there's a post about some OSS project mod stepping down due to abuse and insane expectations from the community. Gruber wrote a tool that solved his own personal problem, shared it with the world because why not, and then made damn sure he wasn't going to have to deal with any fallout put on him for his sharing.
Gruber did the exact opposite than stepping down. Even now, he insists on controlling the name “Markdown”, despite having abandoned the project over 15 years ago.
It would be a bit like Tim Berners-Lee trying to police how people use “WWW” today. He might theoretically be within his legal rights, but he’d still be a jerk for doing so.
Re: Compare AsciiDoc and Markdown
#109The thing with Markdown is that it does most of what you need to do with it, until it doesn't, when you can bring Pandoc to bear and put full-on LaTeX in your Markdown and it will render it however you want. I wrote a dissertation this way with inlined Rmarkdown code. It was great.
I wrote my doctoral thesis (biology) this way (markdown + LaTeX + pandoc) and honestly, it was disappointing how much raw LaTeX I had to end up writing anyway. I had to rewrite all my tables & figures in LaTeX because it was easier than trying to figure out the odd layouts markdown + pandoc produced.
If I had to do something of similar scale and complexity from scratch today, I'd look for a better solution.
Re: Compare AsciiDoc and Markdown
#110As someone who's spent the last several years maintaining a couple large, vaguely complex documents (CP-CPS documents for certificate authorities), AsciiDoc has been a winner. It's simple enough to be readable in git diffs and be updated by non-tech folks like managers, but supports enough features that doing things like tables, nested lists, and certificate structure notation to be workable. And it's WAY more manageable using git to build and publish to PDFs (using Pandoc) than trying to use Word docs.