Podcast (techcast): Play in new window | Download (Duration: 44:16 — 60.8MB) | Embed
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.
Topics
Formats Discussed
- AsciiDoc
- Markdown
- Multi-Markdown
- LaTeX and Docbook as intermediate formats
Tools
- 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
Editors
- The old classic vim is all you need
- Mou – mac side-by-side preview/content pane editor
- Markdown Pro – an alternative Markdown editor
- OxygenXML – if you’re in Docbook-land, it’s a WSYWIG editor for Docbook. HIGHLY recommended but costs $$$$.
- XmlMind – alternative, free tool for editing DocBook