3 ms·
I would strongly recommend using Asciidoc over Restructured Text. Even though Asciidoctor is written in Ruby which IMO is much worse than even Python, the actua
by IshKebab 2y ago
I would strongly recommend using Asciidoc over Restructured Text. Even though Asciidoctor is written in Ruby which IMO is much worse than even Python, the actual RST codebase is a total incomprehensible mess. You can extend it with custom processing etc, but... fuck, I really want to never have to do that again.
Asciidoc just seems to be much higher quality in general.
- jszymborski 2y agoI echo your sentiments, but sadly the Asciidoc python compiler (as far as I can tell) is deprecated and no longer supported. I think that leaves Asciidoctor as the only mature compiler. There's a spec being drafted, so hopefully that will spur some more action. For my purposes, Asciidoc is the best markup with the worst tooling, and Markdown is the worst markup with the best tooling.
- 60secs 2y agothe toc macro on asciidoc is sublime :table-caption!: :toc: macro :sectlinks: toc::[]
- FartinMowler 2y agoI run asciidoctor's Docker container. It does what I want it to do without leaving a mess behind on my laptop.
- IshKebab 2y agoThe trouble with that is it becomes a pain in CI. Nested Docker isn't fun.
- IshKebab 2y agoYeah a nice Rust or Go-based implementation of Asciidoc would be fantastic. Having to deal with Ruby and Gems is not fun. That's a mountain of work though and even if there is a spec, at this point it's complex enough and the Ruby implementation is enough of a de facto spec that I'm doubtful you'll ever make it past "this behaves differently to Asciidoctor" territory. Btw a more recent alternative is https://github.com/jgm/djot https://github.com/jgm/djot which actually does have multiple implementations and looks like a way better option than Markdown, but maybe not as powerful as Asciidoctor still. I haven't tried it.
- YakBizzarro 2y agoOh yes, I could mot agree more. We moved from Antora/asciidoc to mkdocs/markdown. Overall the situation improved (better HTML, faster builds, syntax highlighting of code,...) but I miss how good writing in asciidoc was
- __mharrison__ 2y agoExcept no one uses asciidoc either, and trying to manipulate it with Python is painful. Sadly (or not, depending on your opinion), the world has converged on md.
- IshKebab 2y agoMarkdown is definitely far more popular, but I see more book-length specification type documents written in Asciidoc. For example the RISC-V spec, or Ferrocene's Rust spec.
- __mharrison__ 2y agoI've written and published books (both physical and ebooks) with rST, asciidoc, and md. No format is perfect, but of those three md works best for me.