AsciiDocの概要

2018/01/25

AsciiDoctorの環境が整ったのでAsciiDocと戯れています。

せっかくなので、そもそもAsciiDocって何だっけ？というところを整理してみました。

特徴

AsciiDocは軽量マークアップ言語のひとつです。軽量マークアップ言語と言えばMarkdownが有名なので、Markdownと対比しながら特徴を見ていきます。

Markdown
- 2004年に発表された
- 元々はプレーンテキストをHTMLへ変換するために考案された
- 簡単で覚えやすくするため、ルールはシンプルである
AsciiDoc
- 2002年に発表された
- DocBookがベースになっていて、技術文書が主なターゲット
- 表現力に富んでいる

シンプルさのMarkdown、表現力のAsciiDocでしょうか。ちなみに、両者に記法の互換性はありません。残念．．．

マニュアルなど、ボリュームがある文章を書こうとすると素のMarkdownだと表現力が足りず、結局いろいろな独自拡張に頼る羽目になります。だったら標準で高い表現力を誇るAsciiDocを使えばいいんじゃない？というのが主な用途でしょうか。

Markdownに比べると記法は複雑ですが、最低限だけ覚えてあとはチートシートなんかに頼れば問題はなさそうです。

ツールチェーンは、Pythonで書かれたasciidocが元祖。最近はRubyで書かれたasciidoctorが普及しているようです。自分はAsciidoctorを使うことにしました。

エディターはテキストエディタであればなんでもOKですね。手軽に環境を整えるのであればAtomにasciidoc-previewとlanguage-asciidocを導入するのがよさそうです。プレビューとシンタックスハイライトができるようになるのでとりあえず不自由しなくなります。

拡張子については特別な取り決めはなく、.asciidoc, .adoc, .ascあたりがポピュラーで、長さとユニークさを考慮すると.adocがベター、ということのようです。（参考：AsciiDoc Recommended Practices | Asciidoctor）

Markdownに比べるとまだまだですが、Asciidoctorの登場に伴って日本語の情報も結構出てくるようになりました。

日本語の書籍はこの本くらいしかなさそうです。「ドキュメント作成システム構築ガイド」の書名の通り、ある程度ボリュームのある技術ドキュメントがターゲット。こういう用途にはMarkdownよりAsciiDocのほうがマッチしそうですね。

伊藤敬彦/吉村孝広技術評論社