AsciiDoc と PlantUML (仮)

GitLab CE が AsciiDoc ドキュメントへの PlantUML埋め込み に対応しました。また、AsciiDoc JebBrains Plugin を使えば、IntelliJ Idea で AsciiDoc をプレビューすることができます。(しかも、PlantUML に対応しています)

今まで難しかった設計書の管理を GitLab CE/EE でできそうな気がしてきました。まだどこかの開発で使ったという話ではありませんが、調べてみた結果を掲載します。また、マニュアルを書くのにもとても役に立ちそうです。

はじめに

AsciiDoc とは?

AsciiDoc は公式サイトでこのように書かれています。記事やドキュメントや書籍などを書くためのフォーマットで、HTMLやPDFやEPUBなどに出力できます。

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

Markdown や Wiki 記法のようにテキストに装飾するスタイルで書いておくと、整形してくれます。

sample.adoc

= タイトル

* リスト1
* リスト2

CAUTION: Markdown よりすごいです!

こんな感じになります。

Markdown はどちらかというと簡単にメモを取るためのもので、あまり機能がありません。GitBook のような仕組みもあり、できないわけじゃないのですが、AsciiDoc の方が表現力が豊かです。

HTML/DocBook への変換は Ruby で動く Asciidoctor というソフトウェアを使います。PDF への変換は Asciidoctor PDF を、EPUB3 への変換は Asciidoctor EPUB3 を使います。

PlantUML

PlantUML はその名前の通り UML を書くためのソフトウェアですが、テキストで書くというのが特徴です。

UML 図にもよりますが、クラス図は Java のクラスによく似た書き方ができます。

@startuml
class Animal {
  run()
}

class Cat extends Animal {
}
@enduml

PlantUML Web Server にアクセスして上のテキストを入力すると、以下の画像に変換できます。

画像への変換は Java で動く PlantUML を使います。

書く・プレビューする

AsciiDoc ドキュメントには PlantUML の図を埋め込むことができます。公式には Asciidoctor Diagram を使うことになりますが、GitLab CE/EE も対応しています。

• Asciidoctor Diagram - AsciiDoc ドキュメントに PlantUML の図を埋め込む拡張です。PlantUML 以外にも様々な形式が使えます。
• PlantUML & GitLab - GitLab CE//EE は AsciiDoc 内に PlantUML を埋め込むことができます。
• AsciiDoc JetBrains Plugin - JetBrains 社の開発環境の IntelliJ Idea や WebStorm 用の AsiiDoc をプレビューをすることができます。(Asciidoctor と Asciidoctor Diagram を内蔵しているようです)

Asciidoc Diagram

Asciidoc Diagram はいろいろな図形出力に対応した Asciidoc 拡張です。[plantuml] をつけたブロックを書き、asciidoctor-diagram を拡張として読み込むだけで利用することができます。

sample.adoc

[plantuml]
----
class Animal {
  run()
}

class Cat extends Animal {
}
----

# インストール
$ gem install asciidoctor asciidoctor-pdf asciidoctor-diagram
# HTML 変換
$ asciidoctor asciidoctor -r asciidoctor-diagram -o sample.html sample.adoc
# PDF 変換
$ asciidoctor asciidoctor -r asciidoctor-pdf -r asciidoctor-diagram -b pdf -o sample.pdf sample.adoc

[plantuml,generated-file-name,generated-image-format] と、ファイル名や画像フォーマットを指定することができます。画像フォーマットは標準で png ですが、svg を指定することもできます。

PlantUML & GitLab

GitLab CE/EE では、PlantUML Web Server と組み合わせることにより、AsciiDoc 内に書かれた PlantUML をプレビューすることができます。設定方法はPlantUML & GitLab を見てください。((残念ながら GitLab.com では提供されていないようです)

Asciidoctor Diagram と同じように書けますが、ブロックの書き方が -- (ハイフン二つ) しか受け入れないようです。

sample.adoc

[plantuml]
--
class Animal {
  run()
}

class Cat extends Animal {
}
--

また、画像フォーマットの指定方法が異なり、[plantuml, format="generated-image-format", id="generated-id", width="generated-image-width"] と指定します。標準が png で svg が指定できるのは同様です。

AsciiDoc JetBrains Plugin

JetBrains 社の統合開発環境の IntelliJ Idea や WebStorm では AsciiDoc のプレビューをする AsciiDoc JetBrains Plugin が用意されています。Asciidoctor Diagram を内蔵しており、Asciidoctor Diagram と使い方は変わりません。

違い

Asciidoctor Diagram と GitLab CE/EE ではちょっとだけ PlantUML 図を埋め込む方法が異なります。Asciidoc Diagram 用に書くと GitLab CE/EE ではうまく表示されないと言ったことがあります。ですので、どちらでも使えるような書き方を調べました。

ブロックの指定

ブロックの指定方法の違いを見るために、ハイフンの数やピリオドを使う書き方を用意しました。

block.adoc

.ハイフン二つ
[plantuml]
--
class Test {
}
--

.ハイフン四つ
[plantuml]
----
class Test {
}
----

.ピリオド四つ
[plantuml]
....
class Test {
}
....

環境	ハイフン二つ	ハイフン四つ	ピリオド四つ
Asciidoc Diagram	○	○	○
GitLab CE/EE	○
AsciiDoc JetBrains Plugin	○	○	○

GitLab CE/EE ではハイフン二つ以外は使えないようです。また、ハイフン二つではブロックのタイトルも消えているので、ちょっと悲しいことになりました。

SVG での出力

SVG 形式で出力する時の指定の違いを見るために、Asciidoc Diagram と GitLab CE/EE のそれぞれで書いてみました。

svg.adoc

.Asciidoc Diagram 形式
[plantuml,diagramname,svg]
--
class Test {
}
--

.GitLab CE/EE 形式
[plantuml,format="svg"]
--
class Test {
}
--

環境	Asciidoc Diagram 形式	GitLab CE/EE 形式
Asciidoc Diagram	○	○
GitLab CE/EE	△ (PNG)	○
AsciiDoc JetBrains Plugin (Java FX)	△	△
AsciiDoc JetBrains Plugin (Swing)

• AsciiDoc JetBrains Plugin (Java FX) は表示が崩れました
• AsciiDoc JetBrains Plugin (Swing) は画像を表示できませんでした (AsciiDoc JetBrains Plugin の設定で、どちらのプレビューエンジンを使うかどうかを設定できます)

まとめ

ひとまず GitLab CE/EE で使えるように書いておけば、Asciidoctor Diagram で PlantUML 図の出力ができるようです。また、AsciiDoc JetBrains Plugin は SVG ではきちんと表示することができませんでしたので、理由がない限り PNG を使ったほうが良さそうです。

[plantuml]
--
class Test {
}
--

つまり、こういうことですね。

• ブロックの指定はハイフン二つで
• 画像形式は指定無しで PNG

印刷で PNG だと気になる場合は SVG にします。

[plantuml,format="svg"]
--
class Test {
}
--

ただし、AsciiDoc JetBrains Plugin では表示が崩れるようになります。IntelliJ Idea でプレビューしながら書くということができなくなるのが残念です。

おまけ

AsciiDoc Diagram は PlantUML 以外も使える

AsciiDoc Diagram は PlantUML 専用というわけではなく、たくさんの記法が使えます。詳しくは AsciiDoc Diagram の Diagram Type の一覧を見てください。

これらは Asciidoctor Diagram の機能なので、GitLab CE/EE ではプレビューできないのがちょっと残念です...

PlantUML は結構いろいろ書ける

PlantUML は UML 専用と思われがちですが、他の図も書くことができます。(書きたいかどうかは別として) ワイヤーフレームやガントチャートも書くことができます。

また、PlantUML は画像の生成に Graphviz を使っているようです。ですので、Graphviz/DOT の記法がそのまま使えますので、凝った図も書くことができます。

AsciiDoc Diagram ほど多種多様ではありませんが、UML 以外も埋め込めるのは地味に嬉しいです。GitLab CE/EE でプレビューしたい場合は Graphviz や ditaa を Asciidoctor Diagram で使うのではなく、PlantUML 経由でこれらを使うことをおすすめします。

=== Wireframe
[plantuml]
--
salt
{
  Just plain text
  [This is my button]
  ()  Unchecked radio
  (X) Checked radio
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^
}
--


=== Ditaa
[plantuml]
--
ditaa(--no-shadows, scale=0.8)
/--------\   +-------+
|cAAA    +---+Version|
|  Data  |   |   V3  |
|  Base  |   |cRED{d}|
|     {s}|   +-------+
\---+----/
--


=== Gantt Diagram
[plantuml]
--
[Prototype design] lasts 15 days
[Test prototype] lasts 10 days
--


=== Graphviz/DOT
[plantuml]
--
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
}
--

GitLab CE/EE だとこんな感じです。

Asciidoctor Diagram は (おそらく) 内蔵している PlantUML のバージョンが古く、ditaa や Gant Diagram には対応していないようです。(AsciiDoc JetBrains Plugin も同様)

追記

SVG で日本語が使える使えないの話もあって、もうちょっとなんとかしないといけないのですが、時間切れで今回はここまでです。

追記その二

IntelliJ IDEA での AsciiDoc のプレビューで SVG だと表示が崩れる件は、JavaFX の WebView の問題なんだそうです。ちょっと解決は大変そうですね...