Inline code was conspicuously missing in the comparison, which is more unwieldy in asciidoc (requires backtic and plus instead of just backtic). That’s probably the markdown feature I use most often.
Compare AsciiDoc and Markdown
61–70 of 137 posts
Re: Compare AsciiDoc and Markdown
#62Comparing AsciiDoc to Markdown (instead of for instance reSructured Text/reST) is clever, but I don't think there's any widespread controversy about the shortcomings of Markdown. So that's just an easy win.
I've seen this premise a lot (quoting from the article)
»The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.«
What relevant documentation markup languages have this issue?
If we already agree that documentation should be written as code, let's embrace it and not be scared of showing syntax. It's our tools that matter here - syntax highlighting, previewing, CI feedback.
I see much more that people writing markup languages get extremely motivated from their first victories with coding something.
Don't be afraid of showing people syntax -- Wikipedia got pretty far with a less-than-optimal markup language!
I think the real issue with AsciiDoc is something more along these lines: https://xkcd.com/927/
I'm working in a large organization where we are failing to streamline and spread documentation practices because of many different standards and practices popping up everywhere.
I like a lot how the Python community has centered around Sphinx and Read the Docs. It's great that for instance Sphinx support both Markdown and reST in that regards -- but then when things like Hugo/Docsy, AsciiDoc, Github Wikis, groovydoc etc. starts popping up, the unification of documentation practices in a large organization becomes harder -- and also of course across the specter of Open Source projects.
Re: Compare AsciiDoc and Markdown
#63I feel like this is the tech comparison equivalent of straw-manning.
Take xrefs for instance. They say that the Markdown is:
See [Usage](#_usage).
Usage
See >.
== Usage
Take me to [pookie](#pookie)
Usage
See [Usage](#_usage).
Re: Compare AsciiDoc and Markdown
#64Inline code was conspicuously missing in the comparison, which is more unwieldy in asciidoc (requires backtic and plus instead of just backtic). That’s probably the markdown feature I use most often.
You only need to use backtic and plus when you want to disable text substitutions (a concept that does not exist in Markdown).
Most of the time, using backtic is enough: `text`.
Re: Compare AsciiDoc and Markdown
#65I feel like this is the tech comparison equivalent of straw-manning. Take xrefs for instance. They say that the Markdown is: See [Usage](#_usage). Usage and that the AsciiDoc is: See >. == Usage I mean, clear win for AsciiDoc, right? So I Google "cross reference" "markdown and get this SO post as the first hit: https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this: Take…
You can click the "Edit this page" button and submit an improvement.
Having said that, the fact remains that you don't have a standard syntax to add an id on a section title (without using HTML directly).
Jekyll might does the right thing but Jekyll is not Markdown. Does it work elsewhere? If not then your document is not really portable.
Re: Compare AsciiDoc and Markdown
#66[deleted]
Re: Compare AsciiDoc and Markdown
#67The funny thing is that on their page markdown has better syntax highlighting than their own markup language
It's been a bit of a disappointment for me to discover that AsciiDoc's grammar is so complex that they didn't even describe it in a spec. Their spec is a collection of tests. This must be contributing a lot to the adoption difficulty (at least for resource-limited open-source projects). There's a good chance you will not find an AsciiDoc parser library for your favourite programming language.
The AsciiDoc Working Group has been formed to write a complete and comprehensive specification: https://asciidoc-wg.eclipse.org/
If you are interested in an AsciiDoc processor in Haskell, you can read: https://www.tweag.io/blog/2021-06-15-asciidoc-haskell-pandoc...
We had Guillem Marpons at the last AsciiDoc WG meeting and he was willing to work toward a spec-compliant implementation and help us with the spec.
Re: Compare AsciiDoc and Markdown
#68I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…
This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ... Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?
There’s no point using latex if your book has almost no formulas. If your book has a lot of them, then yes I would say using latex makes sense.
Re: Compare AsciiDoc and Markdown
#69Earlier quoted context omitted.
This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ... Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?
My guess: To convert it into an ebook.
You can convert latex into ebooks I believe, it’s just completely overkill most of the time.
Re: Compare AsciiDoc and Markdown
#70I feel like this is the tech comparison equivalent of straw-manning. Take xrefs for instance. They say that the Markdown is: See [Usage](#_usage). Usage and that the AsciiDoc is: See >. == Usage I mean, clear win for AsciiDoc, right? So I Google "cross reference" "markdown and get this SO post as the first hit: https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this: Take…
> I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally.
In a trivial example, Markdown's syntax looks more natural. It might well be the more appropriate syntax for a short README, which expects to be read as plain text at least as often as rendered to HTML.
In real use, i.e. when editing a non-trivial example, AsciiDoctor's multiple-star/dot syntax makes it easier to keep track of things.
You can also use the Markdown-style indentation instead anyway: https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#...