7 ms·

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/configu

by baby 5y ago

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.

jokteur 5y ago
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 ?
- qznc 5y ago
  My guess: To convert it into an ebook.
  - baby 5y ago
    You can convert latex into ebooks I believe, it’s just completely overkill most of the time.
- StevePerkins 5y ago
  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 5y ago
    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.
- baby 5y ago
  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 5y ago
    > 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 5y ago
      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 5y ago
        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?
- Sr_developer 5y ago
  LaTeX books are ugly. We need an open source alternative to https://www.princexml.com/samples/ https://www.princexml.com/samples/ Or at least one not that expensive.
  - GiovanniP 5y ago
    > We need an open source alternative to https://www.princexml.com/samples/ https://www.princexml.com/samples/ TeXmacs: https://www.texmacs.org https://www.texmacs.org As far as I know e.g. this book https://www.editions-ellipses.fr/accueil/4856-le-petit-python-aide-memoire-pour-python-3-9782340017863.html 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
- 41b696ef1113 5y ago
  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/ 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.
- zelphirkalt 5y ago
  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.
qznc 5y ago
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 5y ago
  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.
  - leotaku 5y ago
    > 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.
breuleux 5y ago
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 https://breuleux.github.io/quaint/index.html
- charles_f 5y ago
  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 5y ago
    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 5y ago
      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 https://github.com/breuleux/blog/blob/master/content/about.q [2]: https://github.com/breuleux/quaint-doc/blob/master/content/index.q https://github.com/breuleux/quaint-doc/blob/master/content/i... [3]: https://raw.githubusercontent.com/breuleux/earl-grey/master/README.md https://raw.githubusercontent.com/breuleux/earl-grey/master/...
      - breuleux 5y ago
        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/content/oexprs.q https://raw.githubusercontent.com/breuleux/blog/master/conte... [2] https://raw.githubusercontent.com/breuleux/blog/master/content/my-own-language.q 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 5y ago
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.
- colejohnson66 5y ago
  I’m sure there’s publishers that will take PDFs
  - criddell 5y ago
    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.
- baby 5y ago
  My publisher (manning publications) uses asciidoc. But I think they convert the whole thing to something else at the very end of the process.
hutrdvnj 5y ago
What tools are you using to write a book in asciidoc?

by baby 5y ago

jokteur 5y ago

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 ?

qznc 5y ago
My guess: To convert it into an ebook.
- baby 5y ago
  You can convert latex into ebooks I believe, it’s just completely overkill most of the time.
StevePerkins 5y ago
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 5y ago
  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.
baby 5y ago
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 5y ago
  > 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 5y ago
    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 5y ago
      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?
Sr_developer 5y ago
LaTeX books are ugly. We need an open source alternative to https://www.princexml.com/samples/ https://www.princexml.com/samples/ Or at least one not that expensive.
- GiovanniP 5y ago
  > We need an open source alternative to https://www.princexml.com/samples/ https://www.princexml.com/samples/ TeXmacs: https://www.texmacs.org https://www.texmacs.org As far as I know e.g. this book https://www.editions-ellipses.fr/accueil/4856-le-petit-python-aide-memoire-pour-python-3-9782340017863.html 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
41b696ef1113 5y ago
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/ 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.
zelphirkalt 5y ago
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.

qznc 5y ago

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 5y ago
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.
- leotaku 5y ago
  > 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.

breuleux 5y ago

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 https://breuleux.github.io/quaint/index.html

charles_f 5y ago
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 5y ago
  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 5y ago
    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 https://github.com/breuleux/blog/blob/master/content/about.q [2]: https://github.com/breuleux/quaint-doc/blob/master/content/index.q https://github.com/breuleux/quaint-doc/blob/master/content/i... [3]: https://raw.githubusercontent.com/breuleux/earl-grey/master/README.md https://raw.githubusercontent.com/breuleux/earl-grey/master/...
    - breuleux 5y ago
      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/content/oexprs.q https://raw.githubusercontent.com/breuleux/blog/master/conte... [2] https://raw.githubusercontent.com/breuleux/blog/master/content/my-own-language.q 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 5y ago

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.

colejohnson66 5y ago
I’m sure there’s publishers that will take PDFs
- criddell 5y ago
  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.
baby 5y ago
My publisher (manning publications) uses asciidoc. But I think they convert the whole thing to something else at the very end of the process.

hutrdvnj 5y ago

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