自分には絵心がない．
加えて図を作るときはパワポに毎回素材のファイルを探して貼って線をなるだけ真っ直ぐに書いて，オブジェクトと線が離れていたことに後で気づいて微修正・・・．苦痛が伴う．
しかし図による理解は100行の文章に勝る．(正確に描かれていると嬉しい．間違ってても無いよりはまし)
plantUMLというコーディングするように各図を作成できるツールがあるようだったから使ってみた．
※注意：この記事はArch Linux上でplantUMLを使う方法に焦点を当てているためWindowsユーザにはあまり役に立たないかもしれません．

きっかけ

サイボウズのNecoプロジェクトのスキルチェックシートを見ていて存在を知った．
図を作るときはよくもやっとするから気になった．
前置きはここまで．

環境

$ uname -a
Linux poppycompass 5.4.10-arch1-1 #1 SMP PREEMPT Thu, 09 Jan 2020 10:14:29 +0000 x86_64 GNU/Linux
$ java -version
openjdk version "1.8.0_232"
OpenJDK Runtime Environment (build 1.8.0_232-b09)
OpenJDK 64-Bit Server VM (build 25.232-b09, mixed mode)

インストール

$ pacman -Ss plantuml
community/plantuml 1.2019.13-1
    Component that allows to quickly write uml diagrams
community/plantuml-ascii-math 20171116-2
    Plantuml language extension to allow use AsciiMath or JLaTeXMath notation
$ sudo pacman -S plantuml
$ which plantuml
/usr/bin/plantuml

インストール終わり．
もう少し詳しく見てみると

$ file $(which plantuml)
/usr/bin/plantuml: POSIX shell script, ASCII text executable
$ cat $(which plantuml)
#!/bin/sh
exec /usr/bin/java -jar '/usr/share/java/plantuml/plantuml.jar' "$@"

$ plantuml test.txtすると引数をそのまま渡すだけのシンプルなシェルスクリプトのようだ．
plantuml -tpngとかつけることで出力フォーマットを指定可能．
現在サポートしているやつは以下の通り．

$ plantuml -h
(...snip...)
    -tpng               To generate images using PNG format (default)
    -tsvg               To generate images using SVG format
    -teps               To generate images using EPS format
    -tpdf               To generate images using PDF format
    -tvdx               To generate images using VDX format
    -txmi               To generate XMI file for class diagram
    -tscxml             To generate SCXML file for state diagram
    -thtml              To generate HTML file for class diagram
    -ttxt               To generate images with ASCII art
    -tutxt              To generate images with ASCII art using Unicode characters
    -tlatex             To generate images using LaTeX/Tikz format
    -tlatex:nopreamble  To generate images using LaTeX/Tikz format without preamble
    -o[utput] "dir"     To generate images in the specified directory
(...snip...)

.eps対応なのは有り難い．

hello world

簡単なhello.txtを作成して試す．

@startuml
Bob->Alice : hello world
@enduml

$ plantuml hello.txt && eog hello.png
eog hello.png部分は画像を表示するコマンド．好きな方法でよい．

f:id:poppycompass:20200131055103p:plain — plantuml(hello world)

後は好きな図を書くだけ．

文法

詳細は公式が詳しい．
配置図を見てどの要素で何が作られるのかを知ればあとはつなげていく作業．

ちょびっと自動化

makeを使って開発を少し楽する．
-guiオプションが動けばいいのかもしれないが，うまく起動しなかった．
公式サイトのトップ下にあるリアルタイムジェネレータも便利．

# Makefile
SRC = hello.txt
PICTURE = hello.png

all:
        make build
        make view

build: ${SRC}
        plantuml ${SRC} -o ${PICTURE}

view: ${SRC}
        eog -w ${PICTURE} &

今後は$ makeするだけでよい．

最終的に作りたかったもの

docker-composeを動かして複数コンテナに対する操作概要を描きたかった．

f:id:poppycompass:20200131055402p:plain — plantuml(installer)

ライブラリやツールを使っていることを示すときはそれらのロゴ画像を貼り付けた方がわかりやすいが，そこまで力を入れる必要がなければこれで十分と判断．
参考にコードは以下のとおり．

@startuml
:developer:
package "Host OS" {
  rectangle "terminal"
  [developer] --> [terminal]
  rectangle "main"
  [terminal]  --> [main]:$ docker-compose up -d --build
  rectangle "Docker"
  [main] --> [Docker]
}
node "container1" {
  rectangle "Ubuntu 16.04 64bit"
}
node "container2" {
  rectangle "Ubuntu 16.04 32bit"
}
node "container3" {
  rectangle "CentOS 7 64bit"
}
[Docker] --> container1:./install.sh
[Docker] --> container2:./install.sh
[Docker] --> container3:./install.sh
database "Log" {
}
container1 --> Log
container2 --> Log
container3 --> Log
skinparam database {
  backgroundColor LightYellow
}
@enduml

おまけ(失敗例)

先程の図の各コンテナからのログをユーザに返すといった意味合いで作ろうとしたらこうなった．

f:id:poppycompass:20200131055837p:plain — pluntuml(installer2)

スタートがどこかわかりにくい．
上から下へ，左から右へというルールの下で作っていくのが良さそう．
全自動だから線の引き方は経験で向き合う必要がありそうだ．

所感

概要図作成において深く考えなくても図が作れるから便利．
ただし，各要素は何を表現するために使うかのルールは持っておかないと自分も相手も混乱しそうだ．
しばらくはこれを使うことにする．

拾い物のコンパス

まともに書いたメモ

plantUMLを試してみる