My guest is Andres Almiray, who has been on our podcast way back in episode 41 discussing Groovy Griffon. I’ve invited him back again, discussing text-based documentation markup formats with me. I’ve been a user of Markdown in various incarnations for a while now, but when I saw him tweet about his interest in AsciiDoctor, a ruby-based tool to convert the newer asciidoc format to various output formats, I was interested.
- The AsciiDoctor tool
- Pandoc – convert anything to anything (mostly)
- RevealJS – fantastic HTML5 slide tool
Major features of AsciiDoc
- TOC automatically defined – include sections in order = right TOC
- Inclusion of documents
- Can embed production code into your documentation (he’s using it in the Griffon Guide) – this can be in the test sources for example… They build docs when test cases are green…
- Can re-arrange indentation
- Can include lines n:m
- Code comments – specify tags – they get included as annotations – include this tag – that portion of tagged code can be included only
AsciiDoctor – custom extensions
- One specifically targeting Java – know you are including a Java class file – or method name – extension parses code, builds AST, then includes the code even if the method moves around
- Caliphs and callouts – nice highlights inside snippets – reference into captions.
- AsciiDoc Can write document as it were a book – target a book layout – sections and parts, etc… Not built in to the Markdown format – must use a tool like Pandoc for this.
- Javadoc support – from AsciiDoctor – a JavaDoc doclet to convert JavaDocs to printable documentation
Text Transformation Tools
- Markdown via Pandoc to PDF, Word, Docbook for manuals (supports printable slide counts, etc).
- Markdown support in Reveal.JS for slide content.
- AsciiDoctor support to convert to DocBook format for publisher output
- Gaiden – a markdown static website content tool
- Grain – supports Markdown and Asciidoc and converts to static content
- jBake (asciidoc) – compares to jeckyll for markdown (ruby) – a multi-format (Markdown, AsciiDoc and HTML) content site generator