コグノスケ

Asciidocをさらに活用

目次: Linux

前回（2022年9月3日の日記参照）、Asciidocのプレビュー環境の設定方法を紹介（Chrome or VSCode）しました。今回はさらにAsciidocの便利機能とそのプレビューを使えるようにします。

ちなみにこのプレビュー機能はVSCode限定となります。Chromeでも使えると便利なんですけどね……。

asciidoctor-diagramで他のツールと連携

Asciidocにはasciidoctor-diagramというextensionがあり、他のツール向けテキストを *.adoc内に記述すると、ツールと連携して自動的に画像を生成し、自動的に文書内に埋め込む機能があります。

例えばUMLをテキストで記述するPlatUMLと連携する場合は、

= Hello

== World

This is hello world.

[plantuml]
----
@startuml
A -> B : ccc
@enduml
----

このように [plantuml] の後にPlantUML向けのテキストを書きます。プレビューや他形式に変換した場合、PlantUMLのテキストの代わりにPlantUMLが出力した画像が表示されていることがわかると思います。

asciidoctor-diagramを使った出力例

各ツールを起動して画像に変換＆リネームしてAsciidocに画像表示の記述を書く方法と比べれば、利便性は天と地の差でしょう。

Rubyのインストール

AsciidoctorやextensionはRubyで実装されているため、Rubyをインストールする必要があります。

Rubyの公式サイト（サイトへのリンク）を見る限り、Windows向けインストールにはRubyInstallerというツール（サイトへのリンク）がおススメのようです。

c:\app>ruby --version

ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]

RubyInstallerはPATHの設定も自動的に行います。インストール後、コマンドプロンプトを起動してrubyを起動できればインストール成功です。

asciidoctor-diagramのインストール

Rubyをインストールしたら、asciidoctor-diagramをインストールします。同時にasciidoctorもインストールされます。

C:\app>gem install asciidoctor-diagram

Fetching asciidoctor-diagram-plantuml-1.2022.5.gem
Fetching asciidoctor-diagram-ditaamini-1.0.3.gem
Fetching asciidoctor-diagram-2.2.3.gem
Fetching asciidoctor-2.0.17.gem
Successfully installed asciidoctor-diagram-plantuml-1.2022.5
Successfully installed asciidoctor-diagram-ditaamini-1.0.3
Successfully installed asciidoctor-2.0.17
Successfully installed asciidoctor-diagram-2.2.3
Parsing documentation for asciidoctor-diagram-plantuml-1.2022.5
Installing ri documentation for asciidoctor-diagram-plantuml-1.2022.5
Parsing documentation for asciidoctor-diagram-ditaamini-1.0.3
Installing ri documentation for asciidoctor-diagram-ditaamini-1.0.3
Parsing documentation for asciidoctor-2.0.17
Installing ri documentation for asciidoctor-2.0.17
Parsing documentation for asciidoctor-diagram-2.2.3
Installing ri documentation for asciidoctor-diagram-2.2.3
Done installing documentation for asciidoctor-diagram-plantuml, asciidoctor-diagram-ditaamini, asciidoctor, asciidoctor-diagram after 4 seconds
4 gems installed

コマンドプロンプトからGemで一発インストール可能で便利です。asciidoctorはRubyのbinディレクトリの配下にスクリプトが配置されるようです。

c:\app>asciidoctor --version

Asciidoctor 2.0.17 [https://asciidoctor.org]
Runtime Environment (ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]) (lc:Windows-31J fs:UTF-8 in:UTF-8 ex:UTF-8)

インストール後、コマンドプロンプトからasciidoctorを起動できればインストール成功です。

Javaのインストール

今回はPlantUMLとの連携を試しますので、PlantUMLの環境も整えます。PlantUMLの実行にはJavaが必要です。

PlantUMLを実行するだけならJRE（Java Runtime Environment）で十分ですが、もし今後Java言語での開発を行う予定があれば、OpenJDKをインストールした方が良いです。私はJavaも使うので Oracle OpenJDKのダウンロードサイト からOpenJDKをダウンロードしました。現状の最新版は18.0.2.1でアーカイブのファイル名はopenjdk-18.0.2.1_windows-x64_bin.zipです。

ダウンロードしたzipファイルを展開すると、jdk-18.0.2.1のような名前のディレクトリがあるので適当な場所に移動（= インストールに相当）します。この際にディレクトリ名をリネームしても良いです。

JDKを適当な場所に配置したらPATHを設定します。例えばJDKをc:\app\jdkにインストールしたとすると、

JDKのPATH設定

こんな感じでPATHに追加します。

c:\app>java -version

openjdk version "18.0.2.1" 2022-08-18
OpenJDK Runtime Environment (build 18.0.2.1+1-1)
OpenJDK 64-Bit Server VM (build 18.0.2.1+1-1, mixed mode, sharing)

PATH追加後、コマンドプロンプトからjavaを起動できればインストール成功です。

VSCodeの設定

VSCode側のプレビュー設定も変更する必要があります。

まずはAsciiDocの設定ページを開いてasciidoctor_jsによるプレビュー生成を無効化します。asciidoctor_jsはasciidoctor-diagramに対応していないからです。プレビュー画面がエラー表示になるかもしれませんが、気にしないでください。

asciidoctor_jsによるプレビュー生成を無効化

次にasciidoctorがasciidoctor-diagramを使うように設定します。具体的には起動時のオプションに -r asciidoctor-diagramを追加します。

asciidoctor-diagramを追加

今までの設定がうまくいっているなら、プレビュー画面が更新されてPlantUMLのテキストの代わりにUMLの画像が表示されるはずです。

まとめ

手順として書いてみると思ったより長いですが、asciidoctor-diagramはなかなか便利です。描画ツールでUMLを書いて、画像にしてAsciidocに埋め込んで……みたいなウザい作業とはお別れです。

画像を使わずテキストで記述するので、差分取得も容易です。画像ファイルで往々にして発生する、原稿がどっか行って更新できなくなった、などのトラブルも防いでくれることでしょう。

MarkDownのその向こう

目次: Linux

簡単なドキュメントやメモはMarkDownで書くことが多いですが、気合を入れた文章にはやや不向きで、図表を入れ始めた辺りから表現力不足が辛くなってきます。

MarkDownで強行突破しても良いですが、より表現力がある主にドキュメント向けのマークアップテキスト……となると、太古から続くTeX、最近だとAsciiDoc、reST（reStructured Text）、Sphinx などが覇権を争っているようです。

私は良し悪しを語るほどマークアップテキストに詳しくないですし、特にAsciidocでなければダメってこともなくて、好きなものを使えば良いと思いますが、今回は訳あってAsciidocを使います。

Asciidocのプレビュー環境

マークアップテキストの読み書きは普段お使いのテキストエディタを使えば良いです。しかしプレビューはテキストエディタではできないことが多く、ちょっと困ります。Asciidocのプレビュー環境として、

• Google ChromeのAsciidoctor.js Live Preview
• VSCodeのAsciiDoc Extension

私はこの2つを使うことが多いです。下記に設定方法のメモを残しておきます。

Chrome + Asciidoctor.js Live Preview

ChromeウェブストアからAsciidoctorと検索するだけです。

Chrome AsciiDoctor.js Live Preview

あとはオプションの「オン」と「ファイルのURLへのアクセスを許可する」を有効にすると、

AsciiDoctor.jsのオプション

Chromeに *.adocのファイルをドラッグ＆ドロップなどして開けば、プレビュー画面が出るはずです。内容を更新すると自動的にプレビューも更新されます。

ChromeのAsciidocプレビュー画面

これでテキストエディタで編集しつつ、Chromeからローカルディスク上のAsciidocがプレビューできます。簡単で良いですね。

VSCode + AsciiDoc拡張機能

VSCodeのExtensionsからasciidocと検索するだけです。

AsciiDoc Extension

フォルダ内の *.adocファイルを開いて、Ctrl+Shift+Vを押すとプレビュー画面が出るはずです。2分割して右側に出せるので便利ですね。

VSCodeのAsciidocプレビュー画面

これでVSCodeからローカルディスク上のAsciidocを編集しながらプレビューできます。これも簡単ですね。

マンガ紹介

目次: マンガ紹介

久しぶりにお気に入りのマンガ紹介シリーズ。短めの完結作品を2つ。

赤髪の女商人（全3巻）

最近完結しました。転生ものではない、まっとう？な人生逆転劇です。紹介文には「理不尽はあっても救いはない」とあって不安を煽りますが、理性にあふれ話の通じる人ばかりで、イカレポンチや理不尽な行動をするヤカラは出てこないのでご安心ください（蛮族とすら商売を始めるのです）。読んでてイライラもなく、好きな作品です。あとは作品の尺の関係でしょうか……、展開が早くて一介の商人から王家お抱えまで超スピード出世します。爽快で面白いですね。

死んだ息子の遺品に息子の嫁が入っていた話（全2巻）

最初のページ目を見たときは不謹慎系のギャグマンガかな？と思いましたが、全く違いました。主人公はアンドロイドですがSF感はあまりなく、人情、良い話系が広がる良い作品です。終わり方も良かったです。2巻で完結していてちょっと短いかな……もっと読みたいな〜とは思いました。