AsciiDocを全力で勧める 4つの理由
AsciiDoc は Markdown と同じ軽量マークアップ言語の一種です。仕様書などの文書を書く上ではMarkdownより利点・メリットがあると感じていて、もともと Markdown で仕様書などを書いていましたが、今は AsciiDoc へ移行しました。
今では、
- メモ、README など簡単なテキスト、ブログ記事書き
=> Markdown - 仕様書などある程度分量のある文書
=> AsciiDoc
というすみ分けをしています。
Markdown と AsciiDoc を使ってみてわかった、AsciiDoc の良いところを 4つ記載します。
仕様が明確
AsciiDoc は仕様が明確です。どういう表現があるのか、どういう書き方をすれば良いか、公式のユーザガイドを見れば全て記載があります。
Markdown は方言が多いため、一言で Markdown 対応のツールと言っても対応している表現、対応していない表現があったりして扱いにくいです。
その点、AsciiDoc は仕様が明確に決まっているので、プレビューや PDF 化などの周辺ツールも整備しやすくなっているのだと思います。
良くある書き方は多くの方がチートシート作成されているのでそれを見れば良いですが、細かい調整をしたいとなった時はとりあえず公式ページ見れば良いので安心感があります。
テーブルの表現が豊富
AsciiDoc の利点として、テーブルの表現力を上げないわけにはいかないでしょう。
それくらいAsciiDoc のテーブルの表現力は高いです。
私が仕様書を Markdown から AsciiDoc へ移行したのも、このテーブルの機能を使いたかったというのが一番大きいです。
単純な例では、下記のように ‘<‘、’^’、’>’ で、カラムごとに左寄せ、中央寄せ、右寄せなどのアラインメントが指定できます。
|
1 2 3 4 5 6 |
[cols="<,^,>", options="header,autowidth"] |============================ |左寄せ|中央寄せ|右寄せ |l|c|r |============================ |
さらに複雑な例だと、
|
1 2 3 4 5 6 7 8 9 10 11 12 |
[cols="^e,m,>s", options="autowidth"] |============================ |強調(イタリック) |等幅 | 強調(太字) | a | b | c .2+>.^|2行右中央 <|セル左寄せ | 2.+^.| 2列中央 2.2+^.^| 2x2中央 | d | セル内で + 改行 + 可能 |============================ |
e で強調(イタリック)、m で等幅、s で強調(太字)。アラインメントと組み合わせ可。
2.2 などでセルを列数.行数連結し、+^.^ で中央寄せなど。
更に通常の AsciiDoc 文章と同じく + でセル内で改行できます。
これで頭の中のテーブルをそのまま書き出せると思います。
仕様書などのドキュメントだと、「ユーザ設定可能値一覧」「エラーメッセージ一覧」のような結構規模の大きなテーブルを作ることもあると思います。そういったテーブルを作る時には AsciiDoc のテーブル機能は大いに役立つはずです。
詳細は、公式のユーザガイド 23. Tables をご覧あれ。機能の豊富さに驚くと思います。CSV で記述したりすることもできます。
UMLやフローチャートなどの図形の差し込みが簡単
これは AsciiDoc というより、Asciidoctor という AsciiDoc => HTML のコンバータの機能ですが、AsciiDoc 内に PlantUML や mermaid.js などのソースを直接記述し、レンダリングする事ができます。
例えば、下記のような記述でクラス図を直接ドキュメント内に埋め込むことができます。
|
1 2 3 4 5 6 7 8 9 10 |
.PlantUMLの例 [plantuml] .... class 会社員 class 技術社員 class 会社 会社員 <|-- 技術社員 会社 -> 会社員 : 給与を払う .... |
AsciiDoc や Markdown などの軽量マークアップ言語で仕様書を書く利点として、テキストファイルで文書を管理することで差分確認などが行いやすくなる、ということがあるかと思います。
その際、図形などの画像ファイルはバイナリ管理で諦めることも多いかと思いますが、AsciiDoc であれば、UML やフローチャートなどの直接 AsciiDoc 内にテキストとして埋め込めてしまうのでまとめて管理できます。
この辺りの方法は別記事に書いてます。
AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
また、PlantUML、mermaid.js 以外に Graphviz などの図形も同じ方法を使えます。対応している図形ライブラリはAsciidoctor Diagramのページ に一覧が記載されています。
include で外部ファイルを読み込める
地味な機能ですが、個人的に超便利機能だと思っています。
include::ファイル名 で別のファイルの内容をその場に展開できます。
公式では System Macros の一種として解説があります。
使用例としては、PlantUML の図形だけ別ファイルにする
|
1 2 3 4 5 |
[plantuml] .... include::sample.puml[] .... |
CSV を AsciiDoc 内でテーブルとして扱う
|
1 2 3 4 5 6 |
[format="csv",cols="^,<,<,>,<",options="header"] |=================================================== 項番,パラメータ名,範囲,デフォルト値,詳細 include::parameters.csv[] |=================================================== |
ソースコードファイルを直接 AsciiDoc に埋め込む
|
1 2 3 4 5 |
[source,python] ------------------------------------------- \include::test.py[] ------------------------------------------- |
などなど。文書が大きくなってくると、ファイル分割したいなと思うときもあるかもしれません。そういう場面でも使えるかと思います。
さいごに
お気に入り軽量マークアップ言語 AsciiDoc の利点を書いてみました。
AsciiDoc は、まだまだ普及率は高くないかもしれませんが、Atomや Visual Studio Code でのプレビュー環境、asciidoctor-pdf などの PDF 化環境なども整ってきていますので十分に実用できるものになっていると思います。
私は実際に AsciiDoc で仕様書を書いて PDF 化してクライアントと共有したりしています。
やっぱりテキストベース環境は良いですよ。慣れたテキストエディタで操作できるので、仕様書書きもそんなに苦になりません。
AsciiDoc 導入を検討の際は、下記ページに環境のインストール方法など書いてますので是非ご覧ください。
AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
最後まで読んでいただきありがとうございます。 このブログを「いいな」と感じていただけましたら、Twiter にてフォローいただけるとうれしいです。ブログ更新情報などもお届けします。
Follow @ryuta461
この記事をシェアする