Asciidocとは
Asciidoc は軽量マークアップ言語のひとつです。Markdown のように人が読める形で構文を記述して組版ができます。Markdown を使用している人であれば、少ない学習コストで表現の高い組版ができます。技術文書をかくのに非常に便利です。
Asciidoc の特徴
- 目次を自動生成できる
- 外部のファイルをインクルードできる
- CSVを取り込んで表にできる
- ソースコードをインポートできる
Asciidoc を使用するには
Asciidoc をネットで調べると、一番ヒットするのが Ruby で Asciidoctor をインストールして、エディタと連携する方法です。本来であれば、Tex のように文書を出力するためにコンパイルが必要ですが、エディタと連携することでリアルタイムでプレビューできるようになります。
今回紹介する方法では、Ruby をインストールしません。組版をするためだけに Ruby をインストールするのも大変ですし、他のソフトウェアとの兼ね合いやメンテナンスの手間も発生します。今回使用する方法は、VSCode のプラグインを一つ導入するだけです。詳しい仕組みまでわかりませんが、バックボーンで動いているのは、Asciidoc の JS 版のようです。
単純な方法なので、複数台のPCでドキュメントを共有した場合でも、環境による差異が出にくくなります。
どうやってテキストエディタでダイアグラムを組むか
テキストでダイアグラムを組む場合、PlantUML や Graphize といったツールを使用します。このツールを使用する際も、ソフトウェアのインストールやダイアグラムの出力にコンパイルが必要になります。
VScodeと連携してリアルタイムにプレビューをすることもできますが、Asciidoc と連携するためにはいろいろと設定も必要です。
今回紹介する方法では、kroki を使用します。日本語での情報があまりないので詳しくは分かりませんが、Rest でダイアグラムの画像を返す API のようです。この API を利用して、PlantUML と Graphize が利用できるようになります。こちらの JS 版を使用してダイアグラムを出力しているようです。(詳しくは分からないので、知ってる人がいたらむしろ教えて欲しいです。)
やり方
VSCodeでAsciidocのプラグインをインストールします。
他にもいくつか Asciidoc のプラグインがありますが、これをインストールします。インストールしたら、Extention Settings からプラグインの設定画面を開いて、Use_Kroki にチェックを入れます。これだけです。
使い方
VSCodeで新規ファイルを作成します。右下のところにどのファイル形式が表示されている箇所をクリックする。どのファイル形式で開くか選択できるので、Asciidoc を選択する。
以下のようにテキストを入力してプレビューを押す。
[plantuml,alice-bob,svg,role=sequence]
....
alice -> bob
....
[graphviz]
....
digraph foo {
node [style=rounded]
node1 [shape=box]
node2 [fillcolor=yellow, style="rounded,filled", shape=diamond]
node3 [shape=record, label="{ a | b | c }"]
node1 -> node2 -> node3
}
....
プレビューを表示させると、ダイアグラムが表示される。
プラグインの解説によれば、PDFのエクスポートも可能です。
PDFのエクスポートした場合、作成したダイアログの大きさはデフォルトで出力される。画像のサイズについては、作図するコンポーネント側で画像サイズを調整することになる。簡単にやり方を記載すると以下のようになるが、詳しい内容は各コンポーネントについて調べて頂きたい。
.uniuni
[plantuml,./test.svg,svg]
----
scale 3 # scaleで倍率を調整できる。
... (以下、テキスト)
----
[graphviz]
----
digraph foo {
size="10!" # 横幅を指定。サイズを直接指定する際は、数字に! をつける。
....（以下、テキスト）
}
----
PDFに出力した形でベストな記述と、プレビューで見たときに整っている記述が違ってくるので、そこは割り切って使うことになる。厳密さをもとめるのであれば、一旦画像を出力して表示する形式にすることをお勧めする。