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

71–80 of 137 posts

Re: Compare AsciiDoc and Markdown

#71

Post by GordonS »

StevePerkins wrote: post #57
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 ?

LaTeX is pretty imposing for non-academic newbies. And if you're not writing a book that includes a bibliography or a lot of complex math equations, then it's arguably overkill. On the other hand, if you already know the gist of Markdown, then you could pick up reStructuredText or AsciiDoc in less than an hour. They're more feature-rich than markdown, without adding too much squeeze for the juice.

I like to use Markdown for authoring (it's a lot simpler than LaTeX!), but use Pandoc to convert to PDF (which uses a LaTeX template).

If needed, you can also sprinkle the Markdown with LaTeX, such as to enforce page breaks at specific points.

Re: Compare AsciiDoc and Markdown

#72

Post by enriquto »

bloak wrote: post #47
oneeyedpigeon wrote: post #35

Earlier quoted context omitted.

Particularly when the syntax bakes in things like support for converting certain ASCII sequences into Unicode characters [0] [0] https://docs.asciidoctor.org/asciidoc/latest/text/quotation-...

Yes, I finally got around to adding some "quail" stuff to my .emacs so that I can directly type various kinds of quotation mark and dash rather than rely on complex conversion rules that sometimes go wrong. The lack of first-class support for balanced quotation marks seems to be a major problem for computers. I think a lot of computer code, particularly scripts, would be easier to read and less buggy if the languages…

> Yes, I finally got around to adding some "quail" stuff to my .emacs

Why into .emacs and not into the global keyboard configuration? Don't you ever write text outside of emacs?

Re: Compare AsciiDoc and Markdown

#73

Post by chrismorgan »

StevePerkins wrote: post #56
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…

I think it would easier to build a website with a more feature-rich alternative, than it would be to push that clunky syntax onto end-users. reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages. If you need more than this, then you should probably bite the bullet and just use LaTeX or some other markup.

> I think it would easier to build a website with a more feature-rich alternative, than it would be to push that clunky syntax onto end-users.

The we always have with us. Anything extensively indentation-based is doomed as a general-purpose web markup language (where you’re typing in that markup language—WYSIWYG/WYSIWYM editors are another matter), because all “enhancements” will behave differently and will be at least a little painful.

> reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages.

I think that’s the wrong framing. All three have roughly the same goals, just Markdown is… worse. And yeah, I’m going to stick with that. Markdown is a low-quality hack that unfortunately (in my mind) gained popularity, a textbook case of “worse is better”, because its dodgy HTML foundation and simple processing model made it far easier to adopt (with many painful incompatibilities between implementations) than something like reStructuredText which is actually sound but takes a lot more effort to implement, so that there’s really only one implementation of it.

reStructuredText and AsciiDoc are full-featured presentation-agnostic markup languages. Markdown is itself fairly minimally-featured, which works out because it’s tied to HTML, which carries the burden of supporting more extensive functionality (though not very well).

LaTeX is a full-featured presentation-locked markup language. It is not at all suitable as an alternative for the likes of reStructuredText, as reStructuredText is much more flexible on presentation options. With something like Sphinx, you can target HTML, LaTeX, Windows’ old-style help, man pages, and more.

Re: Compare AsciiDoc and Markdown

#75

Post by dctoedt »

raspyberr wrote: post #27

There's something about org-mode markup syntax that's really nice.

For years I've been maintaining my course materials in org-mode and exporting to HTML each semester. I'm in the middle of consolidating the materials into a PDF book via LaTeX export for students to print out if they want. I really like the typeset look of the resulting PDF, even though there are no equations or formulas (I'm a part-time law professor). I'm doing just-in-time learning of the necessary LaTeX via Stack Exchange; it's crude, but effective.

To be sure, the Emacs dependency is something of an entry barrier for org-mode. It helps that I've been using Emacs and various text formatters — Scribe, Final Word, and now pandoc — going back some 40 years.

Re: Compare AsciiDoc and Markdown

#76

Post by encryptluks2 »

brospars wrote: post #17
encryptluks2 wrote: post #5

Earlier quoted context omitted.

I disagree... Markdown is no longer a single unified version. There are multiple implementation, extensions, etc. The original Markdown spec by itself isn't that useful and there is a reason so many extensions have been made for it. It can maintain simplicity while still adding new features. Pandoc has some great examples of Markdown extensions that are really useful.

The core features are pretty much universal and used in a lot of apps (chats, forums, git repositories, project management). Custom flavors maybe not rendered correctly at times but this doesn't make documents unreadable

The core features used in a lot of apps include different flavors, like GitHub Markdown and others. The closest thing you have to a unified Markdown is CommonMark and even that is forked for GFM. Yes, headers, bold and italics text, and lists are nice but there is a lot more to take into account when you are trying to supplement docs that other extensions add.

Re: Compare AsciiDoc and Markdown

#77

Post by Sr_developer »

jokteur wrote: post #38
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…

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 ?

LaTeX books are ugly.

We need an open source alternative to https://www.princexml.com/samples/

Or at least one not that expensive.

Re: Compare AsciiDoc and Markdown

#78

Post by nobleach »

Finnucane wrote: post #74
neetrain wrote: post #16

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

You want archaic? It could be worse. It could be EbcdicDoc.

Wow, using Perl scripts to convert output from my AS/400's DB2 instance into ASCII so that I could import them into Oracle 8i and display them on an ASP page... that was a memory I had hoped to forget.

Re: Compare AsciiDoc and Markdown

#79

Post by bloak »

enriquto wrote: post #72
bloak wrote: post #47

Earlier quoted context omitted.

Yes, I finally got around to adding some "quail" stuff to my .emacs so that I can directly type various kinds of quotation mark and dash rather than rely on complex conversion rules that sometimes go wrong. The lack of first-class support for balanced quotation marks seems to be a major problem for computers. I think a lot of computer code, particularly scripts, would be easier to read and less buggy if the languages…

> Yes, I finally got around to adding some "quail" stuff to my .emacs Why into .emacs and not into the global keyboard configuration? Don't you ever write text outside of emacs?

Yes, good question. One reason is that I haven't found a convenient portable way of modifying Linux keyboard configurations. Another is that sometimes I'm SSH-ing in from a machine that isn't even Linux.

I have used xkbcomp to replace a character I don't need with one I do, but the recipe tends to require maintenance and I don't know how to program dead keys with that approach. Perhaps there's a better way nowadays.

Re: Compare AsciiDoc and Markdown

#80

Post by 29athrowaway »

evacchi wrote: post #23
29athrowaway wrote: post #3

The point of Markdown is having a very tiny set of features: headers, paragraphs, lists, links, pre-formatted text, etc. You can learn this in minutes. Having Markdown with more features is against what makes Markdown useful: minimalism.

true, but please notice that you can use asciidoc as a larger subset of md

Which is not something I want. If I wanted something more complex I would use TeX.
Post reply on HN