最近のライティング環境2023夏(1)

ライティング環境を見直す2021春夏 (2021-06-19) | あーありがち

2021年に Asciidoctor を導入してみたが、やはり PlantUML 図を取り出すためだけに使っているような感じでイマイチ。

PlantUMLの出力を安定させる

2022-09 くらいから、環境によって PlantUML の色味が異なるという現象が発生していた。1

調べたら以前からこの現象は起きていたようだが、

PlantUMLの見た目を以前のデフォルト色に戻す - OITA: Oika’s Information Technological Activities

手元で確認できるようになってからいろいろ調べていくと、

  • PlantUML のバージョンアップで色味が変わった
  • 新しい構文への対応度合いも処理系によって異なる

といったことが目につくようになってきた。

とりあえず見た目については

skin rose
skinparam shadowing false

を問答無用で付けるようにした。新しめの構文で挙動が異なる部分については以下のように処理系を減らすことで対応とした。

Markdown部分を変えずに画像出力を改善

いちばん手間が掛かっていたのは SVG から PNG の変換だったんだけど、

  1. PlantUML 自体が PlantUML 構文以外の文法を与えても問題なく、かつ複数の図形を別々のファイルに出力する機能を持っていた
  2. SVG から PNG への変換をコマンドでサクッとやってくれるものを見つけた

結果、

  • asciidoctor + asciidoctor-diagram を経由する必要も変換ツールで手間暇掛ける必要もなくなった
  • PlantUML 処理系は Markdown Preview Enhancement が built-in jar なので、それとコマンドの PlantUML のバージョンが合っていれば挙動はブレない2

ということで、かなり快適になった。

Markdownを直接PlantUMLに食わせて画像出力できた

これすごい盲点だったので恥ずかしいんだけど、PlantUML ってそもそも構文的に PlantUML ファイル専用じゃなかった。@startuml と @enduml の間だけ処理するので。

そして実は公式のドキュメントで分かりやすいサンプルがないために見落としてしまいやすいんだけど、

Markdown with PlantUML

実は @startuml のあとにファイル名を指定する機能がある。

Frequently Asked Questions

The @startuml/@startditaa/@startjcckit is useful to determine the type of diagram (uml, ditaa, jcckit…), and because you can optionally put a filename after the @startXYZ. This also allows to have several diagrams inside the same file.

ということは、特に難しいことを考えずに

@startuml basename-of-diargam
skin rose
...
@enduml

って書いてあればよかった。あとは

plantuml -Tsvg markdown-file.md

でそれぞれの名前の付いた SVG が出力される。

これで画像入りのドキュメント生成に Asciidoctor を使う必要がなくなった。AsciiDoc は AsciiDoc でよさはあると思いつつ、日常的に Google Docs ターゲットのドキュメントを書く分には不要となった。

SVGからPNGへの変換は実は便利コマンドがあった

RazrFalcon/resvg: An SVG rendering library.

もう何年も前からあったんすね…。ただデフォルトだと背景が抜けたり大きさが小さすぎたりするので、こんな感じで使うことにした。

MarkdownからGoogle Docsは欲張らずに手作業で

2022年から Google Docs上で Markdown の行頭の記号を識別できる編集作業が走った瞬間に該当する行を変換する機能がある。

正直機能的にほんとにこれ Google さん本気出してますか？感はあるものの、まぁゆうて

だいたいの用途をカバーできている

という点ではよくできてると思う。ということで、Markdown のテキストを Google Docs にコピペしてちまちま変換することにしている。下手に docx とか経由せず 、デフォルトのスタイルに寄せつつ、フォントの種類、サイズ、行間くらいを調整してやればだいぶそれっぽくなるので、A4 1, 2枚程度の内容ならこれでいいやとなっている。

ドキュメントのスタイルは

How can I change the default styles for Google Docs? - Web Applications Stack Exchange

この辺りを参考に設定している。Google 本家のマニュアルはもっと頑張った方がいい。

  1. asciidoctor + asciidoctor-diagram と Markdown Preview Enhancement と Asciidoc と esa でなんか微妙に食い違うという状態。 ↩

  2. 以前は Asciidoc 拡張は Kroki を、asciidoctor-diagram は gem 経由で jar を使っていたので、コマンドラインで叩ける PlantUML と合わせると 4つの異なるバージョンを使っていたことになるが、これが 2つになった。 ↩

More