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

91–100 of 137 posts

Re: Compare AsciiDoc and Markdown

#91

Post by zoomablemind »

baby wrote: post #68
jokteur wrote: post #38

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

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.

> There’s no point using latex if your book has almost no formulas...

In a book one often needs to keep track of local references (to figures, tables, sections, etc). How this could be reasonably done in markdown flavors?

Re: Compare AsciiDoc and Markdown

#93

Post by breuleux »

charles_f wrote: post #89
breuleux wrote: post #88

Earlier quoted context omitted.

I made a highly extensible markup language (inline macros, plugins, etc.) a while ago called Quaint[1] that I've been meaning to dive back into at some point. Out of curiosity, do you reckon it'd fit your use cases? [1] https://breuleux.github.io/quaint/index.html

My one comment: what I like about Markdown is that the "code" itself is readable, you don't have to effectively transform it to HTML, as is it almost looks like some text with a few characters here and there to emphasize things. Quaint's .q files look too much like source code to me, you wouldn't want to read them as is.

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.

Re: Compare AsciiDoc and Markdown

#94

Post by colejohnson66 »

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.

I’m sure there’s publishers that will take PDFs

Re: Compare AsciiDoc and Markdown

#95

Post by dalai »

zoomablemind wrote: post #91
baby wrote: post #68

Earlier quoted context omitted.

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.

> There’s no point using latex if your book has almost no formulas... In a book one often needs to keep track of local references (to figures, tables, sections, etc). How this could be reasonably done in markdown flavors?

Asciidoc already supports that. You don’t even need to differentiate in the syntax, it knows when you are referring to a table, a figure, a section, code listing, etc.

Re: Compare AsciiDoc and Markdown

#96

Post by icegreentea2 »

For the type of documentation that I do, I find that the single biggest win with AsciiDoc is it's table functionality.

Specifically the two things that are really nice is:

A) You can write out a table row over multiple lines. Default syntax/mode makes it really easy to do a cell per line.

B) You can embed (more) complex formatting easily into the table. So stuff like lists, block quote/code block, whatever.

Re: Compare AsciiDoc and Markdown

#97

Post by criddell »

colejohnson66 wrote: post #94
criddell wrote: post #90

Earlier quoted context omitted.

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.

I’m sure there’s publishers that will take PDFs

Even places that use Adobe's InDesign for typesetting tend to work from Word files. I asked because I'm wondering if that has started to change.

Re: Compare AsciiDoc and Markdown

#98

Post by SAI_Peregrinus »

MattBlissett wrote: post #52
joshspankit wrote: post #46

Earlier quoted context omitted.

Came here to say this. UTF-8/16 represents such a relief from the previous text-encoding nightmares that I run away from any tooling that does not use it. If anyone else was a web dev in the 90s, you know what I’m talking about.

AsciiDoctor supports Unicode just fine. We've integrated it with PO4A[0] and CrowdIn.com to support a translation workflow, and so far have one document in Chinese: [1]. Another (tiny) example is [2] with an emoji star, you can "Edit this page" and see the Unicode source. [0] https://po4a.org/ [1] https://docs.gbif.org/collections-idea-paper/zh/ [2] https://ipt.gbif.org/manual/en/ipt/2.5/data-hosting-centres#...

The issue is that the name strongly implies that it doesn't. If a system is named "Doesn'tSupportImportantThingSys" don't be surprised when people don't bother to check the documentation to find that it actually does support the important thing. They'll just skip it.

Re: Compare AsciiDoc and Markdown

#99

Post by mikl »

neetrain wrote: post #16

The worst part of AsciiDoc I think is its name. It sounds so archaic.

Yeah, as someone whose name contains non-ASCII characters, the association with ASCII is not exactly a positive one. I’ve wasted so much time dealing with data in non-Unicode encodings over my career that the mere word ASCII makes me want to punch something.

Re: Compare AsciiDoc and Markdown

#100

Post by gnull »

mogztter wrote: post #67
gnull wrote: post #20

Earlier quoted context omitted.

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.

I didn't know about the specification effort. It's great news!

I'm very impressed with what asciidoc-hs plans to do! Especially looking forward to LSP support and stuff like incomplete/incremental parsing.

Post reply on HN