Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Compare AsciiDoc and Markdown

docs.asciidoctor.org

Post reply on HN
Print view View original

121–130 of 137 posts

Re: Compare AsciiDoc and Markdown

#121

Post by rowanG077 »

nerdponx wrote: post #104
chrismorgan wrote: post #44

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

Bold and italic at the same time? What is the devils work?

Re: Compare AsciiDoc and Markdown

#123

Post by breuleux »

charles_f wrote: post #120
breuleux wrote: post #93

Earlier quoted context omitted.

Could you be more specific as to what looks too much like source code? The most common difference between the two would be *multi word emphasis* vs _[multi word emphasis]. The former may be less conspicuous, but both read fine to me.

Sure. What I mean is that quaint files (e.g. [1] and [2]) look like simplified HTML ; you're defining functions, div hierarchy, formatting and such. I cannot comfortably read the .q, I have to read the rendered HTML. On the other hand, this [3] looks like a text file with ASCII formatting ; the fact that it compiles to HTML is almost incidental. [1]: https://github.com/breuleux/blog/blob/master/content/about.q [2]: h…

I mean, okay, I can see that, but they're not really equivalent examples, are they? The README isn't setting up a carousel, dealing with custom styles, or embedding an interactive example. There isn't really any way to implement these two Quaint examples that won't look like code. [1] or [2] are more representative of using Quaint like Markdown, although in that situation it's less clear what the advantages are, because there's not a lot in there that Markdown would do poorly.

[1] https://raw.githubusercontent.com/breuleux/blog/master/conte...

[2] https://raw.githubusercontent.com/breuleux/blog/master/conte...

In any case, it does appear the discoverability of straightforward examples leaves something to be desired, so thank you for making me realize that.

To me the advantages of Quaint is that I can easily define custom operators to do nonstandard things unobtrusively. For instance, if for some reason I want to emphasize some words in italic orange, I can easily set it up so that e.g. /xyz would highlight xyz in italic orange. Silly example, but there are a lot of valid use cases.

Re: Compare AsciiDoc and Markdown

#124

Post by dikei »

noname120 wrote: post #51
dikei wrote: post #41

I much prefer Asciidoctor to Markdown when writing documents that's longer than a single A4 page, since it has the ability to combine multiple files into a single document if needed.

Have you considered using pandoc[1]? pandoc file1.md file2.md .... -o final.md or pandoc file1.md file2.md .... -o final.pdf [1] https://pandoc.org/

That's just concatenation though.

Asciidoctor has very good support for `include`, so you can include a file in the middle of another file. Furthermore, you can even do partial include where you only include a section of another the file in the current file.

I have setups where each of my files can work as a standalone document with proper Title and Appendix. These files can be compiled into another file where all the individual title are change to sub-title, and all the appendices are group together into one section.

Re: Compare AsciiDoc and Markdown

#125

Post by chrismorgan »

nerdponx wrote: post #104
chrismorgan wrote: post #44

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

Yeah, nesting inline markup is definitely something I’d want to add. Note that code styling in a link is actually possible, just convoluted:

  Using |foo|__.

  .. |foo| replace:: substitution with the ``replace`` directive
  __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
Funny thing is that, from what I recollect of investigating this matter a decade ago, there was never any fundamental objection to nested inline markup in reStructuredText, it just… hasn’t happened.

Re: Compare AsciiDoc and Markdown

#126

Post by mrehler »

As of today, there are so many incredible tools for Markdown — like Brett Terpstra’s Marked 2 and Christian Tietze’s Tableflip right off the bat — that make it so much more versatile. Obviously there are flaws, but if you find yourself working mostly in the same syntax all the time (I’m a MultiMarkdown man myself) it’s easy to make sure all your tools play well with one another.

Re: Compare AsciiDoc and Markdown

#127

Post by dragonwriter »

encryptluks2 wrote: post #4
taftster wrote: post #2

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms). I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL. The problem is simply that github, gitlab, and friends adopted Markdown and so…

There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter. AsciiDoctor is already written in Ruby, which is probably what they use on the backend for Markdown conversion. Hugo supports it as well, and I'm sure there are other static site generators. I agree 100% about documentation on Confluence or Sharepoint. Seriously, will not even work at a company that is heavily invested in…

> There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter

Github already supports AsciiDoc via AsciiDoctor.

Re: Compare AsciiDoc and Markdown

#128

Post by MilStdJunkie »

subpixel wrote: post #42

“it also fulfills the objective of ensuring your content is maximally reusable” This is a bit of a trap when it comes to teams chasing the goal of modular documentation. AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable. But unlike code which, say, might use a method that is available bc another file has been included/imported, a…

The Conditional Content piece of 'component content" is one that's consistently ignored by every Big Iron vendor that I've ever talked to.

Which is 100% nuclear stupid, because, as you point out, you can't do component content without conditional content. And once you start doing conditional content, you need to have a damn good idea of what your whole product architecture looks like: what works with what, which packages are packages, obsolescence, blah blah blabbity blah. At industry conferences this makes me mad enough to spit, and all those goobers are suckering these writer teams into paying $7000 per person per (EDIT)month (!!) for a system that's going to be nothing but heartache in thirty six months.

Luckily, Asciidoc does have conditional directives, but the include directive is wayyyyy too primitive for what it's being used for right now (also as you point out). The `ainclude` directive is in extension right now, and it will probably be brought into core as a subdoc directive.

Having said that, it really is the best game in town, for generating both modern HTML alongside old-timey PDFs and DocBook XML, all from the same source.

Re: Compare AsciiDoc and Markdown

#129

Post by baby »

criddell wrote: post #90
baby wrote: post #36

I 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…

Did you do everything yourself? I'm wondering because I've always assumed that everybody you hand your book to down the line (editor and publisher) is going to want to use Word.

My publisher (manning publications) uses asciidoc. But I think they convert the whole thing to something else at the very end of the process.

Re: Compare AsciiDoc and Markdown

#130

Post by wenc »

qznc wrote: post #39
baby wrote: post #36

I 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…

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 have significant experience with both. I've written complex documentation in RsT (Sphinx) and Markdown (Azure Devops, Jupyter, and RMarkdown).

For basic use cases (sections, lists, text formatting), they're both similar in functionality, but Markdown has the advantage of having lightweight, memorable syntax. I would argue that Markdown's syntax is also aesthetically more pleasing (RsT uses a lot of punctuation).

For advanced use cases however (long docs, with math/code listings, complex cross refs, footnotes, callouts, etc.), RsT feels more powerful out of the box. I'm sure Markdown has extensions that can help it achieve similar functionality, but it almost feels like Markdown wasn't designed for advanced use cases.

To use a very imperfect analogy, Markdown to me feels like Microsoft Word (easy to get started on), whereas RsT feels like LaTeX (very code-centric). Although either can be used for any use case, Markdown seems like the right choice for most web-centric use cases, whereas RsT seems slightly more suitable to complex documentation.

Post reply on HN