| Summary:
Some participants were interested in asciidoc and its toolchain asciidoctor because they are
- trying to find out whether industry may finally settle on a single standard, there is lots of formats that solve similar use cases (asciidoc, LaTeX, doxia, sphinx, ...)
- tyring to find out whether asciidoc can make it less painful for developers to write documentation (it is after all important to maintain documentation, but developers don't seem to like doing so)
- we are using MS Word, which is painful, we'd like to find something else which also makes management happy.
The following topics were discussed:
- asciidoc tool integration (for example for maven, gradle, intelliJ, idea)
- asciidoc syntax
- asciidoctorj - makes it possible to use asciidoctor from Java
- inclusion of source code snippets (from other files) into an asciidoc document including syntax highlighting and indenting them properly
- setting asciidoc inclusion tags in a source code file
- inclusion of variables into an asciidoc document
- drawing ascii-art images (which will then be rendered as proper image in the final output)
- how to generate the final output (in separate build scripts)
- how to generate a table of contents for the document
- asciidoclet as a replacement for javadoc
- asciidoc is easier markup than javadoc
- can also do syntax highlighting (in javadoc you need a separate plugin for that)
- output formats: the default output format is HTML. asciidoc PDF is still incubating, only works on ruby for now; should eventually allow you to create PDF.
- asciidoc plugin system
Yakov has written books in asciidoc. O'Reilly have a server for asciidoc. Authors can generate the book in several formats with the help of this server. Write once - publish in different formats. Yakov presented parts of his new book (also entirely written with asciidoc) "Java for Kids", which will be published with no starch press. The build builds the book and deploys the source to github.
Other questions asked:
- Could there be some way to generate documentation from the tests for example? Because the tests do show how the program works.
- How sensitive is asciidoc for syntax in diagrams? Will it for example complain about lines which don't connect/are crooked?
- What if you documentation requires screenshots from a website? It may be possible to create extensions to take automated screenshots from java programs.
|
