Asciidoctor(asciidoctor.org)
asciidoctor.org
Asciidoctor
https://asciidoctor.org/
35 comments
> My personal wish is for a modern and first-class replacement for the various AsciiDoc-to-PDF flows.
Hear hear. (a.k.a. "+1", a.k.a "this")
Hear hear. (a.k.a. "+1", a.k.a "this")
Yup.
AsciiDoc was implemented in Python. AIUI, the project got neglected or abandoned, so someone re-implemented it in Ruby to create AsciiDoctor -- same markup, different rendering engine.
Some like it, some don't. I don't mind working with it, but I haven't used it in anger. It seems pretty good. It's richer and more expressive than Markdown, which is feeble and that's resulted in multiple subtly-different, incompatible implementations.
It compares with RST -- ReStructured Text, another lightweight, human-readable plain-text markup format that's used in several places.
The advantage of ADoc is that its model maps onto that of DocBook, so it's possible to render ADoc into DocBook and then use it with established DocBook toolchains.
I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy and it took me a long time -- at least months -- to learn to read it or write it fairly easily and fluidly.
ADoc you can learn in an afternoon and the source remains perfectly naked-eye readable.
The arguable weakness is that because DocBook is a tightly-specified format, you can formally validate a DocBook document. You know it will work and render to something, even if what comes out isn't quite what you wanted.
Whereas you can't verify an ADoc document. It's possible to write something that looks fine but isn't and which might produce wildly different output from what you intended. You just can't formally tell (i.e. in software) if it's going to work or not: anything will work and produce _something_.
An advantage for humans, but a big snag if you're trying to automate making PDFs or e-books or something from it. In most cases, if you're using some form of continuous integration or something, it's preferable that it will stop with an error and tell you than for it to churn out something totally bogus.
AsciiDoc was implemented in Python. AIUI, the project got neglected or abandoned, so someone re-implemented it in Ruby to create AsciiDoctor -- same markup, different rendering engine.
Some like it, some don't. I don't mind working with it, but I haven't used it in anger. It seems pretty good. It's richer and more expressive than Markdown, which is feeble and that's resulted in multiple subtly-different, incompatible implementations.
It compares with RST -- ReStructured Text, another lightweight, human-readable plain-text markup format that's used in several places.
The advantage of ADoc is that its model maps onto that of DocBook, so it's possible to render ADoc into DocBook and then use it with established DocBook toolchains.
I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy and it took me a long time -- at least months -- to learn to read it or write it fairly easily and fluidly.
ADoc you can learn in an afternoon and the source remains perfectly naked-eye readable.
The arguable weakness is that because DocBook is a tightly-specified format, you can formally validate a DocBook document. You know it will work and render to something, even if what comes out isn't quite what you wanted.
Whereas you can't verify an ADoc document. It's possible to write something that looks fine but isn't and which might produce wildly different output from what you intended. You just can't formally tell (i.e. in software) if it's going to work or not: anything will work and produce _something_.
An advantage for humans, but a big snag if you're trying to automate making PDFs or e-books or something from it. In most cases, if you're using some form of continuous integration or something, it's preferable that it will stop with an error and tell you than for it to churn out something totally bogus.
> same markup, different rendering engine.
The markup is actually significantly incompatible in my experience.
> I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy
Originally DocBook was a general SGML application, which meant you could use the short forms designed for manual input (and which provide better legibility). But, XML.
The markup is actually significantly incompatible in my experience.
> I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy
Originally DocBook was a general SGML application, which meant you could use the short forms designed for manual input (and which provide better legibility). But, XML.
I love adoc, but I really dislike the build tools (maybe because I don't work with Ruby).
My feeling is that part of the reason adoc is missing or a real PITA to configure for thrid-party software (e.g.: pandoc or hugo) is largely due to this.
Furthermore, I don't love the way math typesetting looks when you export to PDF (although, I guess I should just use XeTeX/LaTeX at that point).
I nearly wrote my master's thesis in adoc, and but for the build system, it was a lot of fun.
My feeling is that part of the reason adoc is missing or a real PITA to configure for thrid-party software (e.g.: pandoc or hugo) is largely due to this.
Furthermore, I don't love the way math typesetting looks when you export to PDF (although, I guess I should just use XeTeX/LaTeX at that point).
I nearly wrote my master's thesis in adoc, and but for the build system, it was a lot of fun.
Interesting. I have most of this and various toolchains installed as standard on my work boxes, so for me, for instance, to get a preview pain in Atom, I just added 2 packages and the Atom module and it worked. For Pandoc, even less -- I just installed Pandoc and bingo, I could convert to/from.
I feel sure that there must be some happy medium somewhere between the skeletal marked-up text formats of RST, ADoc and Markdown and the excessive complexity of (say) DocBook, but I don't know what it is, and if it exists, it might not be FOSS.
I used to do a lot of writing and editing for Wikipedia (before someone unjustly accused me of vandalism, and a couple of my bigger pieces were deleted -- after that, sod them, I just do minor copy-edits) and I was happier with MediaWiki markup, but I guess it's not very intuitive.
The professional FOSS documentation tools I've worked with are at one extreme -- the "Docs as Code" philosophy that holds that embracing programmers' tools such as Git and various programmers' editors mean getting a lot of power for little investment.
https://www.docslikecode.com/
The other extreme are powerful proprietary tools, often on Windows, such as MadCap Flare, which I haven't worked with.
I reckon there is space in the middle for something like Wikipedia with versioning and branches, but nobody's inclined to invest in the R&D. There are tools, they work, so why should they?
I feel sure that there must be some happy medium somewhere between the skeletal marked-up text formats of RST, ADoc and Markdown and the excessive complexity of (say) DocBook, but I don't know what it is, and if it exists, it might not be FOSS.
I used to do a lot of writing and editing for Wikipedia (before someone unjustly accused me of vandalism, and a couple of my bigger pieces were deleted -- after that, sod them, I just do minor copy-edits) and I was happier with MediaWiki markup, but I guess it's not very intuitive.
The professional FOSS documentation tools I've worked with are at one extreme -- the "Docs as Code" philosophy that holds that embracing programmers' tools such as Git and various programmers' editors mean getting a lot of power for little investment.
https://www.docslikecode.com/
The other extreme are powerful proprietary tools, often on Windows, such as MadCap Flare, which I haven't worked with.
I reckon there is space in the middle for something like Wikipedia with versioning and branches, but nobody's inclined to invest in the R&D. There are tools, they work, so why should they?
It was originally started so we could integrate Asciidoc parsing into GitHub's codebase without shelling out to Python (A good friend worked on Asciidoctor and I wrote another parser for reStructuredText around the same time that we never got around to implementing in the codebase). The project sort of took off from there and has flourished into this great toolkit.
I believe the Java implementation is current and well maintained: https://asciidoctor.org/docs/asciidoctorj/
It's not a separate Java implementation, it's just a Java wrapper for the Ruby library ("AsciidoctorJ provides Java bindings for the Asciidoctor RubyGem (asciidoctor) using JRuby").
I've now written a book using asciidoc and I am not a fan. It's full of oddities and minilanguages and special cases. For the main body of the work it was no quicker or easier than Markdown. For anything complex I wound up spending hours poring over the docs, stackoverflow, ancient forum posts, github issues trying to learn the magic incantations.
I would have greatly preferred LaTeX or DocBook, but the offered alternatives were Word or Google Docs.
I would have greatly preferred LaTeX or DocBook, but the offered alternatives were Word or Google Docs.
I have high hopes for asciidoctor as in the text processor/converter, and the sooner I can have one less thing I need TeX for, the better.
AsciiDoc the language though, like RST, has lost the popularity contest to Markdown I'd say - everyone around me knows what .md is, but ask about AsciiDoc and you're most likely to get "Ascii what?".
That doesn't make it objectively worse, but I think allowing Markdown syntax as input (with metadata/annotations where needed) would give the project a boost.
AsciiDoc the language though, like RST, has lost the popularity contest to Markdown I'd say - everyone around me knows what .md is, but ask about AsciiDoc and you're most likely to get "Ascii what?".
That doesn't make it objectively worse, but I think allowing Markdown syntax as input (with metadata/annotations where needed) would give the project a boost.
I've been using Python Sphinx for a number of years and mostly happy with it. The major limitation for me is it doesn't support "parts of a book." For whatever reason the maintainers have not been interested and ignored pull requests for it for years, saying it needed to be designed first. Then not responding to requests for feedback.
Not sure if moving a book to asciidoc is practical, but I've been considering it.
Not sure if moving a book to asciidoc is practical, but I've been considering it.
In case it's of interest, we wrote a system for converting Jupyter Notebooks to asciidoc, which we used to publish an O'Reilly book.
This is the book: https://www.amazon.com/Deep-Learning-Coders-fastai-PyTorch/d...
This is the nb->asciidoc convertor: https://github.com/fastai/fastdoc
These are the source notebooks: https://github.com/fastai/fastbook/
This is the book: https://www.amazon.com/Deep-Learning-Coders-fastai-PyTorch/d...
This is the nb->asciidoc convertor: https://github.com/fastai/fastdoc
These are the source notebooks: https://github.com/fastai/fastbook/
I got real excited and thought this was gunna be a website that let me create and draw pretty ASCII/ANSI art like back from the warez scene days.
I was hoping for a cowsay for medical advice.
That would be dope, I hope it could be added as an Easter egg in Asciidoctor cli.
Me too. Let's build it.
Wrote 3 technical books [1] with asciidoctor, love it!
Simple format, easy to include code, builds PDF, ePUB, mobi ...
[1] https://gumroad.com/tebeka
[1] https://gumroad.com/tebeka
Inclusions are absolutely stellar, I know some people dismiss Asciidoctor because it feels neither here not there kinda lang. It amazes me how pliable the tool actually is (for Rubyist off course), there are some things there that would make org-mode aficionados and LaTeX die-harts envy.
Asciidoctor being written in Ruby is both a blessing and a curse. You could off course use Opal transpiled Asciidoctor.js if you fancy that. It works very nicely in some situations, just don't expect it to do absolutely freaking everything. Maintainers are doing a fantastically good job considering how few they actually are and how much it requires. Ruby is fun to write but not fun to debug.
https://github.com/asciidoctor/asciidoctor.js
Also take a look at Antora if you love JS static site frameworks, it's for multi repo Git and is based on Asciidoctor.js
https://antora.org/
https://github.com/asciidoctor/asciidoctor.js
Also take a look at Antora if you love JS static site frameworks, it's for multi repo Git and is based on Asciidoctor.js
https://antora.org/
After writing a reasonable amount of asciidoc, I fgure i might just as well use LaTeX, possibly unless it's sufficiently simple, and I'm expecting people to read it directly. I've found juxtaposing somewhat-presentational markup, like meta-variables in input, particularly problematic, apart from continually having to look up how to do things.
That said, it seems to be the best of the genre that I've used and implemented over the decades.
That said, it seems to be the best of the genre that I've used and implemented over the decades.
What’s your toolchain look like for converting latex to HTML, possibly with raw HTML in the latex source? I’d love to use latex if not for that wrinkle.
Most likely https://ds26gte.github.io/tex2page/index.html but I wouldn't have raw HTML. I'm not sure how well Pandoc does with LaTeX input generally.
Edit: Fix the link.
Edit: Fix the link.
If curious see also
2019 https://news.ycombinator.com/item?id=18847326
2019 https://news.ycombinator.com/item?id=18847326
I've only played with it after finally giving up on using org files for source that others will read and ending up with markdown/pandoc/laTeX workflows, so I may be commenting from ignorance of its use cases. However, AsciiDoc felt a bit like methadone for WYSIWYG addicts---a useful tool to wean someone away from obsessive control of the minutiae of layout while writing toward unentangling the task and allowing the machine (possibly assisted by an editor/layout specialist) to deal with that stuff while the writer...well, writes.
That said, there's probably a huge niche for that, and if it improves adoption of markdown-like text formats, I'm in. I'm tired of having to explain to colleagues that no, that is my original, and yeah, the syntax is really obvious and no, no you don't have to learn LaTeX, here's my style files, no, honest you just have to run a script, hell, just throw your files in the share on my server, it'll email you the results, but, oh, for the, yeah, yeah, I'll get you a bloody Word version.
That said, there's probably a huge niche for that, and if it improves adoption of markdown-like text formats, I'm in. I'm tired of having to explain to colleagues that no, that is my original, and yeah, the syntax is really obvious and no, no you don't have to learn LaTeX, here's my style files, no, honest you just have to run a script, hell, just throw your files in the share on my server, it'll email you the results, but, oh, for the, yeah, yeah, I'll get you a bloody Word version.
I love asciidoc - it has the potential to disrupt Roam Research.
However, the primary language of development of asciidoctor is ruby. The nodejs port is autogenerated from Ruby and is killing adoption.
In a world where 99% of markdown adoption is through the frontend, this is a harsh reality.
None of the pastebin, hackmd guys want to adopt an autogenerated lib.
However, the primary language of development of asciidoctor is ruby. The nodejs port is autogenerated from Ruby and is killing adoption.
In a world where 99% of markdown adoption is through the frontend, this is a harsh reality.
None of the pastebin, hackmd guys want to adopt an autogenerated lib.
I evaluated formats for online docs for a Node.js library I was writing. Asciidoc(tor) was the only one I found that was available as JS lib (thanks to Asciidoctor.js), but more importantly, it could include marked sections from external code files within the docs.
This meant I could write code examples within unit tests, and include sections of those tests in the docs, keeping the docs in sync with the actual code and making sure the examples are still valid.
Does anyone know another doc format that supports this?
This meant I could write code examples within unit tests, and include sections of those tests in the docs, keeping the docs in sync with the actual code and making sure the examples are still valid.
Does anyone know another doc format that supports this?
All I want is one of those plain text formatting based languages that preserves newlines
so that you don't get a shopping list like this if you type the following in a HN comment with a newline between each:
eggs milk bacon toast
well, it exists, it's BBCode
so that you don't get a shopping list like this if you type the following in a HN comment with a newline between each:
eggs milk bacon toast
well, it exists, it's BBCode
ok language, worst tooling ecosystem ever
I'm not much of a Ruby guy, is it normal to keep your main application code in `/lib`?
Yes, for a standard Ruby package most application/library logic goes in there, and executables inside of `/bin` will call into that.
IMO AsciiDoc's advantage over Markdown, RST, LaTeX and others is its adoption of DocBook XML as an industrial-strength backing format. The combination of a pragmatic markup language and a proven, stable, and relatively media-independent translation target is unique and extremely useful.
I'm an enthusiastic believer in Asciidoc-the-language, but the tooling situation is confusing in parts, fragmented in others, and not really living up to its premises. This is exactly why I'm watching the asciidoc-wg project with great interest.
My personal wish is for a modern and first-class replacement for the various AsciiDoc-to-PDF flows. I'd bet on CSS Paged Media, although it's been a long haul. The current options (FO/XSLT, dblatex, and asciidoctor-pdf) all have pretty severe limitations.
If any of the AsciiDoc/AsciiDoctor devs are reading this, thank you 1,000,000 times for your efforts. It's an extremely complex project and I am grateful there's a community of talented people working on it.