[baby]

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 asciidoc because it provides callouts, sidebars, captions, figures, cross references, LaTeX (via hard-to-use plugins), themes, fonts, etc. when converting to pdf or epub, etc.

[qznc]

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.

[chrismorgan]

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 <textarea> as web applications of it will commonly go for, where any indentation must be applied manually by the writer. So I’d say it’d be good to get a new syntax construct for fenced, rather than indented, directives. For example, this is what reStructuredText has:

  .. directive-name:: first-line-options
     :subsequent-options: and their values
     :and-more: if you want

     Then the directive’s body.

And here’s a strawman fenced syntax:

  ```directive-name:: first-line-options
  :subsequent-options: and their values
  :and-more: if you want

  Then the directive’s body.
  ```

Of course, once you’re touching something like that you’d want to touch more things to make it all consistent again, but it’d all be perfectly possible. (Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.)

As it stands, reStructuredText is based around having visually-pretty source: monospacedly-aligned tables, indentation for hierarchy, that sort of thing. (Headings feel like the only major thing that doesn’t use very significant whitespace.) I almost always like this, but there are definitely some situations when it’d be nice not to work that way.

Would you go all-in on fenced things rather than indented things? I dunno. Probably.

[StevePerkins]

I think it would easier to build a website with a more feature-rich <textarea> 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.

[chrismorgan]

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

The <textarea> 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 <textarea> “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.

[uranusjr]

> And here’s a strawman fenced syntax:

You might find MyST interesting! Personally I’m counting on it to succeed (after painfully realising reStructuredText never will )

https://myst-parser.readthedocs.io/en/latest/

[leotaku]

> Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.

It's fine, you have to press the key right next to the backspace key plus shift. Not exactly ergonomic, but easy to discover on basically any standard QWERTZ keyboard. I'd definitely like a fenced alternative. I'm okay with indentation-based code, but somehow I really dislike using it in my writing.

[CodesInChaos]

What makes it annoying to use is that it's a deadkey

[nerdponx]

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.

[chrismorgan]

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.

[zelphirkalt]

I think it might be a complicated thing to add cleanly for all possible use-cases in the implementation. I remember, how knots in my head formed, when I thought about implementing nested inline markup in a markdown parser. For example if you have nestings like: A B C b c a (where the upper case letter marks the start and lower case letter the end of a markup)

The main implementation of reStructuredText is a custom parser, which might be a hassle to modify to accomodate all cases of nesting, including duplicate ones like: A B A text b a a.

But perhaps all the difficulty in this stems from making the symbols used for starting an inline markup the same as for ending it. Otherwise it would be trivial to count opening and closing "parentheses".

[tasuki]

Code styling in a link sounds useful, but bold and italic generally shouldn't be combined[0].

[0]: https://practicaltypography.com/bold-or-italic.html

[rowanG077]

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

[eevilspock]

RestructuredText was chosen over Asciidoc for the Linux Kernel Documentation:

  - https://lwn.net/Articles/692704/

  - https://www.kernel.org/doc/html/latest/#other-documentation

Back in 2016.

There is a lot of comparison made in that decision.

[wyuenho]

Here's a comparison.

https://hyperpolyglot.org/lightweight-markup

Aside, I still don't understand why restructuedText never took off. The language is so expressive and well-documented, there are anchored references and tables, you can write you academic papers in it and just generate PDFs from it afterwards. There are so many constructs that Markdown and friends don't have.

[wenc]

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.

[jokteur]

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 ?

[41b696ef1113]

Having written my fair share of Latex, I will chime in that I despise the language. Verbose, too many special characters I need to escape (copy and pasting text becomes a chore), slow to compile, mystery number of compilation steps, and horrible debugability.

None of these are showstoppers, but quite a few paper cuts that leave me reaching for Latex only as a last resort. There are tooling and workflows one can adopt to minimize the pain, but it requires a lot of setup if I just want to get some text on a page.

I have stupidly optimistic hopes that something like [Skribilo](https://www.nongnu.org/skribilo/) would take over in this space, but I know that is foolhardy. Would require a generation of physicists and mathematicians to give up their hard-won Latex knowledge.

[StevePerkins]

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.

[GordonS]

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.

[zelphirkalt]

The answer is in my opinion the following:

You use LaTeX when you have to for some specific thing, perhaps equations, but at other times, you can stick with the simpler syntax of (AsciiDoc|reStructuredText|Org-Mode).

That's what I do at least.

[baby]

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.

[zoomablemind]

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

[dalai]

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.

[zelphirkalt]

And in reStructuredText you can make any place in your document a "source" and any place a "sink" of a reference. Is it the same in AsciiDoc, or are only special things like listings etc. referencable?

[qznc]

My guess: To convert it into an ebook.

[baby]

You can convert latex into ebooks I believe, it’s just completely overkill most of the time.

[Sr_developer]

LaTeX books are ugly.

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

Or at least one not that expensive.

[GiovanniP]

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

TeXmacs: https://www.texmacs.org

As far as I know e.g. this book https://www.editions-ellipses.fr/accueil/4856-le-petit-pytho... has been written with TeXmacs, and antoher is in preparation by the same author. Also, Joris van der Hoeven has written a guide to TeXmacs ("The Jolly Writer") using TeXmacs

[breuleux]

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

[charles_f]

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.

[breuleux]

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.

[charles_f]

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]: https://github.com/breuleux/quaint-doc/blob/master/content/i... [3]: https://raw.githubusercontent.com/breuleux/earl-grey/master/...

[breuleux]

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.

[criddell]

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.

[baby]

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

[colejohnson66]

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

[criddell]

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.

[hutrdvnj]

What tools are you using to write a book in asciidoc?