3 ms·

I'm surprised that no publishers are included in the "Companies and Organizations" list. Asciidoc is a supported tool for Manning authors and probably others.

gauravphoenix 6y ago
I just recently discovered Asciidot. I was browsing Micronaut's documentation and was impressed by it- how it allowed code lines/fragments to be annotated. Did some RE and discovered Asciidot. So far, I am pretty impressed. I hope more and more tooling will support it.
- derekp7 6y ago
  I love writing documentation in asciidoc (using asciidoctor actually). However I keep running into certain issues. For example, if a document includes pictures, and the file path has spaces in it, then you have issues. I believe you can replace spaces using HTML escapes if your output doc is HTML, however that falls apart if you want to make a PDF from the same source. I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.
  - pvorb 6y ago
    Another downside is that rendering larger documents to PDF will become incredibly slow. We have documented a REST API with AsciiDoc via Spring RestDocs and the build takes like 10 minutes for the PDF only. That doesn't include generating the snippets with RestDocs, which is rather fast. I suspect it has to do with AsciiDoctor being written in Ruby.
- pvorb 6y ago
  You aren't referring to this gem, right? ;-) https://github.com/aaronjanse/asciidots https://github.com/aaronjanse/asciidots
pjmlp 6y ago
Most publishers tend to work with more industrial formats like Docbook or DITA, plus there are nice WYSIWYG editors for them.
- webmaven 6y ago
  Asciidoc is meant to be semantically and syntactically equivalent (and thus, losslessly round-tripable) to DocBook.

gauravphoenix 6y ago

I just recently discovered Asciidot. I was browsing Micronaut's documentation and was impressed by it- how it allowed code lines/fragments to be annotated. Did some RE and discovered Asciidot. So far, I am pretty impressed. I hope more and more tooling will support it.

derekp7 6y ago
I love writing documentation in asciidoc (using asciidoctor actually). However I keep running into certain issues. For example, if a document includes pictures, and the file path has spaces in it, then you have issues. I believe you can replace spaces using HTML escapes if your output doc is HTML, however that falls apart if you want to make a PDF from the same source. I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.
- pvorb 6y ago
  Another downside is that rendering larger documents to PDF will become incredibly slow. We have documented a REST API with AsciiDoc via Spring RestDocs and the build takes like 10 minutes for the PDF only. That doesn't include generating the snippets with RestDocs, which is rather fast. I suspect it has to do with AsciiDoctor being written in Ruby.
pvorb 6y ago
You aren't referring to this gem, right? ;-) https://github.com/aaronjanse/asciidots https://github.com/aaronjanse/asciidots

pjmlp 6y ago

Most publishers tend to work with more industrial formats like Docbook or DITA, plus there are nice WYSIWYG editors for them.

webmaven 6y ago
Asciidoc is meant to be semantically and syntactically equivalent (and thus, losslessly round-tripable) to DocBook.