I read an article titled “Living the Future of Technical Writing” by Scott Chacon, the author of Pro Git, and it got me thinking a little about the techical writing process, and the formats I use to markup text.
I have no personal experience with asciidoc – most of the plain-text based markup I write is in markdown or reStructuredText. I like markdown, but sometimes it’s too simple and has ambiguously defined behaviors (like pre/code text in a list item). I like reStructuredText, but some aspects of it’s syntax leave a bad taste (the weird syntax for links and no spaces before number/bullet for lists to name a couple).
And so, reading this article made me want to find out if asciidoc improves on the issues I have with markdown and reStructuredText, and what kind of tooling I can use to manipulate it.
Some neat features specific to asciidoc:
- Admonitions (document call-outs for notes, tips, etc)
- Simple usage of italic, bold, and inline monospace – all embeddible within each other
- Custom inline styling (IE “[small]#small print#”)
- You can specify “curved” apostrophes and quotation marks
- Document Headers (which can include author, revision, and attributes)
- You can specify explicit id’s for section links
- You can specify parts of other ascii documents to include inline
- You can include content from URI’s
- You can specify manual page breaks
- You can specify checklists
- Ability to explicitly notate content as an extension of the previous list item
- Ability to link inline anchors
- Internal cross-references
- Callouts for code blocks
- Code blocks sourced from files
- Custom substitutions
- Commenting
Some things I can see already annoying me:
- For lists of greater than one level, you need to use n number of list markers where n is the level of indentation. Small thing, but it annoys me greatly that reStructuredText requires the list marker to not have space in front of it too. BUT at least asciidoc explicitly specifies that leading white space to lists is not relevant
- The syntax for extending list content might make things a little hard to read
- Subjectively, I feel like the link syntax isn’t as nice as markdowns – it’s about on par with how I feel about reStructuredText’s link syntax.
I might give this format a serious shot – there is asciidoctor.js, so I might be able to integrate it into my Metalsmith build! I’m certainly going to test it out, but who knows if it’ll go anywhere…