3 ms·

I can only recommend not to use Markdown for larger projects like books (at least not scientific or tech books). Markdown simply doesn't provide the structural

I can only recommend not to use Markdown for larger projects like books (at least not scientific or tech books). Markdown simply doesn't provide the structural elements you'd need. AsciiDoc is a much better fit.

invalidname 3y ago
100%. The major tech publishers (O'Reilly, Manning) use Asciidoc and for good reason. The tooling today is absolutely fantastic too. I'm writing my new book with IntelliJ IDEA and it's such a pleasant experience. My last two publishers required Word which was a nightmare. I maintain some docs in markdown which is OK but pretty limited when it comes to the advanced stuff.
iainctduncan 3y ago
How is asciidoc compared to sphinx? I've found sphinx really good so far.
- invalidname 3y ago
  I'm not a Python guy so never worked with Sphinx and never really heard of anyone using it for something like a book. It looks like it suffers from the same problems that MD suffers from. Building a markup language is really easy. That's why we have so many and multiple independent implementations of markdown. The problem is that last mile to get production and mostly printing right. That's super hard and even asciidoctor doesn't get it perfectly. These Manning does use asciidoc for writing, it's great for that. But when you need to create a book they move it to docbook and then typeset using the traditional typesetting programs. Despite all the work it's 95% of the way for the sublime book experience. I'd say every other alternative is 90% of the way at best. To get a sense of what you need to do to create a professional book without that typesetting work check out this post https://medium.com/sketch-app-sources/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410 https://medium.com/sketch-app-sources/using-sketch-and-ascii...
- MilStdJunkie 3y ago
  Asciidoc is a lightweight markup language, Sphinx is a document processor. I imagine what you're primarily asking is "how does Asciidoc compare to ReStructuredText?". ReStructuredText has a ton of functionality, but it slips behind Asciidoc in a few areas. On paper, we passed by RsT because leadership didn't like the Python-forward tooling and high setup workload . . but we had other reasons on the publications side of things: less XML interoperability, worse print options, worse tables, weirder directives, syntax inconsistencies, no established spec or working group (at the time). Being built on DocBook is a great insurance policy for Asciidoc, as DocBook has been around approximately forever and opens lots of doors to other XML specifications via XSL or something more sane.
dredmorbius 3y ago
My view is: - Use tools sufficient to your needs. - Don't be a slave to your tools or any given toolchain. For reasonably simple books, Markdown is sufficient. If all you're dealing with is text, paragraphs, chapters (and perhaps sub-chapter and super-chapter sections), and perhaps a few additional features: italicised and bold text, lists, and simple tables, you'll be more than fine with Markdown. I've typeset numerous books (my own work, from plain text, typed in) in this manner. The default output is fairly generic, but it's more than adequate for simple use. Much of the styling can be enhanced without abandoning Markdown simply with a more-advanced stylesheet. And if you do find that you're exceeding the (surprisingly adequate) capabilities of Markdown, or another lightweight markup language, then it's also straightforward to migrate to LaTeX or DocBook and incrementally augment the work from there. As with the advice to buy cheap tools and upgrade the ones that break, starting with a sufficiently reasonable base is often a good way to get a project rolling. Keep in mind that people wrote books with paper and typewriters, or quill and ink, long before advanced typesetting tools were available. The fact that we can now typeset-as-we-write doesn't mean we must.
jmhammond 3y ago
Check out PreText for these!

invalidname 3y ago

100%. The major tech publishers (O'Reilly, Manning) use Asciidoc and for good reason. The tooling today is absolutely fantastic too. I'm writing my new book with IntelliJ IDEA and it's such a pleasant experience. My last two publishers required Word which was a nightmare. I maintain some docs in markdown which is OK but pretty limited when it comes to the advanced stuff.

iainctduncan 3y ago

How is asciidoc compared to sphinx? I've found sphinx really good so far.

invalidname 3y ago
I'm not a Python guy so never worked with Sphinx and never really heard of anyone using it for something like a book. It looks like it suffers from the same problems that MD suffers from. Building a markup language is really easy. That's why we have so many and multiple independent implementations of markdown. The problem is that last mile to get production and mostly printing right. That's super hard and even asciidoctor doesn't get it perfectly. These Manning does use asciidoc for writing, it's great for that. But when you need to create a book they move it to docbook and then typeset using the traditional typesetting programs. Despite all the work it's 95% of the way for the sublime book experience. I'd say every other alternative is 90% of the way at best. To get a sense of what you need to do to create a professional book without that typesetting work check out this post https://medium.com/sketch-app-sources/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410 https://medium.com/sketch-app-sources/using-sketch-and-ascii...
MilStdJunkie 3y ago
Asciidoc is a lightweight markup language, Sphinx is a document processor. I imagine what you're primarily asking is "how does Asciidoc compare to ReStructuredText?". ReStructuredText has a ton of functionality, but it slips behind Asciidoc in a few areas. On paper, we passed by RsT because leadership didn't like the Python-forward tooling and high setup workload . . but we had other reasons on the publications side of things: less XML interoperability, worse print options, worse tables, weirder directives, syntax inconsistencies, no established spec or working group (at the time). Being built on DocBook is a great insurance policy for Asciidoc, as DocBook has been around approximately forever and opens lots of doors to other XML specifications via XSL or something more sane.

dredmorbius 3y ago

My view is: - Use tools sufficient to your needs. - Don't be a slave to your tools or any given toolchain. For reasonably simple books, Markdown is sufficient. If all you're dealing with is text, paragraphs, chapters (and perhaps sub-chapter and super-chapter sections), and perhaps a few additional features: italicised and bold text, lists, and simple tables, you'll be more than fine with Markdown. I've typeset numerous books (my own work, from plain text, typed in) in this manner. The default output is fairly generic, but it's more than adequate for simple use. Much of the styling can be enhanced without abandoning Markdown simply with a more-advanced stylesheet. And if you do find that you're exceeding the (surprisingly adequate) capabilities of Markdown, or another lightweight markup language, then it's also straightforward to migrate to LaTeX or DocBook and incrementally augment the work from there. As with the advice to buy cheap tools and upgrade the ones that break, starting with a sufficiently reasonable base is often a good way to get a project rolling. Keep in mind that people wrote books with paper and typewriters, or quill and ink, long before advanced typesetting tools were available. The fact that we can now typeset-as-we-write doesn't mean we must.

jmhammond 3y ago

Check out PreText for these!