1. はじめに

本文書は Asciidoc とその Ruby による実装である Asciidoctor を用いて Asciidoc 文書を執筆する環境を構築する手順を示します。実行環境は Windows、Linux、macOS の各 OS に対応しています。

この文書の手順より以下のことができるようになります。

Asciidoc 形式で執筆した文書を HTML/PDF 形式に変換する。

Asciidoc 文書変換用スクリプト

変換結果をリアルタイムにプレビューしながら、テキストエディターで文書を編集する。

Visual Studio Code 拡張設定

Asciidoc は表現力の高い文書をテキストファイルベースで執筆できるテキストプロセッサーです。他の軽量テキストプロセッサーが持たない文書間のインクルードやソースコードの挿入などの機能も有し、かつ簡潔です。特に技術文書の執筆には大きな力を発揮することでしょう。

Asciidoc の表現力を示すひとつの例は、このような脚注表現です。

一般的にこのようなテキストプロセッサーを用いた執筆環境を構築するためには多くの準備が必要となりますが、本文書の手順は極力初期導入するプロダクトを少なく、簡単に快適な執筆環境を整えられるよう考えられています。

具体的には文書の変換に、実行を JVM 環境だけに依存する AscidocrotjGradle を活用し、執筆環境については Visual Studio Code を用いることでリアルタイムに文書をプレビューしながら、最後にコマンド一つで PDF 化できるように準備してあります。

本文書がみなさんの執筆活動のお手伝いになれば幸いです。

1.1. 謝辞

本文書の手順の実装であるビルドスクリプトやテーマでは次のプロダクトと技術資料が使われています。

プロダクト名の隣にライセンスを併記しました。商用利用等で制限のあるプロダクトはありませんが、それぞれライセンスを確認してください。
Font
Asciidoc
Build Tool
Text Editor
Guide

素晴らしい成果を公開されているみなさまに感謝します。

2. Asciidoc 文書変換用スクリプトを使う準備

本手順で用いる Asciidoc 文書変換用スクリプトはビルドツールである Gradle を活用しており、実行するためには Java 実行環境が必要です。

Java 実行環境は、文書変換スクリプトを動作させる過程で唯一 OS 環境に手動で導入する必要があるプロダクトです。それ以外のものは Gradle によりプロジェクトとして独立した形で自動的に導入されます。

お使いのコンピューターのコマンドライン環境(macOS/Linux ではターミナル、Windows では cmd.exe か powershell.exe)で java -version コマンドを入力し、Java 8 以上のバージョンが表示されるようであれば既に準備は整っています。

macOS/Linux の場合
$ java -version
openjdk version "1.8.0_192"
OpenJDK Runtime Environment (Zulu 8.33.0.1-macosx) (build 1.8.0_192-b01)
OpenJDK 64-Bit Server VM (Zulu 8.33.0.1-macosx) (build 25.192-b01, mixed mode)
Windows の場合
C:¥> java -version
openjdk version "1.8.0_192"
OpenJDK Runtime Environment (AdoptOpenJDK)(build 1.8.0_192-b12)
OpenJDK 64-Bit Server VM (AdoptOpenJDK)(build 25.192-b12, mixed mode)
現在 Java 9 以降の環境で Asciidoctor の実行環境となる JRuby が(ビルドの範囲では動作に問題ないように見えるものの)実行時にワーニングを出力するため、本手順では Java 8 を使って解説しています。この問題は将来解消されるでしょう。

2.1. Java 実行環境の導入(macOS / Linux の場合)

もし macOS / Linux 環境に Java 実行環境がなければ SDKMAN を利用することで、ターミナルから簡単に導入することができます。

SDKMAN! is a tool for managing parallel versions of multiple Software Development Kits on most Unix based systems.

— SDKMAN
手順. SDKMAN を用いた Java の導入
$ curl -s "https://get.sdkman.io" | bash (1)
$ source "$HOME/.sdkman/bin/sdkman-init.sh" (2)
$ sdk list java (3)
=========================================
Available Java Versions
=========================================
     12.ea.20-open
     11.0.1-zulu
     11.0.1-open
     10.0.2-zulu
     10.0.2-open
     9.0.7-zulu
     9.0.4-open
     8.0.192-zulu (4)
     8.0.191-oracle
     7.0.181-zulu
     1.0.0-rc9-graal
     1.0.0-rc8-graal
     1.0.0-rc7-graal
$ sdk install java 8.0.192-zulu (4)
1 SDKMAN を導入します。
2 SDKMAN を環境に設定します。
3 導入できる Java のバージョンを一覧します。
4 8.0 系の最新バージョンを指定して Java を導入します。

また、Gradle は JAVA_HOME 環境変数に実行環境の Java のパスが設定されていることを期待していますので、.bash_profile で次のように JAVA_HOME を設定します。

手順. JAVA_HOME の設定
$ vi ~/.bash_profile (1)
export JAVA_HOME=~/.sdkman/candidates/java/current (2)
$ source ~/.bash_profile (3)
1 vi エディタで .bash_profile を開きます。
2 本ラインをファイルの最下部に追加し vi を保存終了します。
3 設定を適用します。

これで準備完了です。

SDKMAN について

SDKMAN は主に Java エコシステムの開発環境をコマンドラインから簡単に導入・設定するためにつくたれた管理ソフトウェアです。

たとえば簡単に各種 Java のバージョンを導入し切り替えることができます。

手順. SDKMAN による Java のバージョン切り替え
$ sdk install java 11.0.1-open (1)
$ sdk default java 11.0.1-open (2)
$ sdk default java 8.0.192-zulu (3)
1 Java 11 を導入
2 Java 11 をデフォルトに設定
3 Java 8 をデフォルトに設定

2.2. Java 実行環境の導入(Windows の場合)

もし Windows 環境に Java 実行環境がなければ AdoptOpenJDK プロジェクトが提供する OpenJDK のバイナリを導入すると良いでしょう。

Java™ is the world’s leading programming language and platform. The code for Java is open source and available at OpenJDK™. AdoptOpenJDK provides prebuilt OpenJDK binaries from a fully open source set of build scripts and infrastructure.

— AdoptOpenJDK

https://adoptopenjdk.net サイトにブラウザでアクセスし、OpenJDK 8 (LTS) - HotSpot を選択した後、zip ファイルをダウンロードしてください。

adopt

zip ファイルを任意の場所に展開します。ここでは C:\develop\runtime\openjdk8 に展開したとします。

導入先

Gradle は JAVA_HOME 環境変数に実行環境の Java のパスが設定されていることを期待していますので、エクスプローラー  PC(右クリック)  プロパティー  詳細設定  環境設定 からユーザー環境変数に JAVA_HOME を追加し、先ほど .zip を展開したパス(C:\develop\runtime\openjdk8 )を設定します。

環境変数
Gradle は JAVA_HOME 環境変数を元に Java の実行環境を探すため、java コマンドを使うための PATH 環境変数は設定しなくてもかまいません。

これで準備完了です。

3. Asciidoc から HTML/PDF 文書を作成する

3.1. サンプル文書の変換を試す

環境の準備ができましたので Asciidoc 文書を HTML/PDF に変換してみます。

変換に使うスクリプトは github のリポジトリに公開されており、リポジトリには HTML/PDF 変換に使うファイル一式と、文書サンプルとして "この文書" の Asciidoc ファイルが置かれています。まずはサンプル文書が正しく変換できるかを試してみましょう。

macOS / Linux の場合は次のようにします。

手順. PDF 変換ビルドスクリプトの取得と実行
$ curl -L -O https://github.com/h1romas4/asciidoctor-gradle-template/archive/master.zip (1)
$ unzip master.zip (2)
$ cd asciidoctor-gradle-template-master (3)
$ ./gradlew docs (4)
BUILD SUCCESSFUL in 19s (5)
2 actionable tasks: 2 executed
1 リポジトリのファイルをダウンロードします。
2 ダウンロードした .zip ファイルを展開します。
3 カレントディレクトリを展開したフォルダの中に移します。
4 Gradle のビルドを実行します。初回実行時はビルドに必要なファイルをダウンロードするため少し時間がかかります。次回は数秒で完了します。
5 BUILD SUCCESSFUL が出力されればビルド成功です。

Windows をお使いの場合は同等の操作をブラウザとエクスプローラーを使って行います。

  1. ブラウザを使って https://github.com/h1romas4/asciidoctor-gradle-template/archive/master.zip にアクセスしリポジトリのファイルを取得します。

  2. ダウンロードした .zip ファイルを右クリックし展開します。

  3. 展開したフォルダ内をエクスプローラーで表示した上で、アドレスバーに cmd.exe と入力し、このフォルダをカレントディレクトリとしてコマンドプロンプトを起動します。

    windows
  4. .\gradlew.bat docs と入力し Gradle ビルドを実行します。初回実行時はビルドに必要なファイルをダウンロードするため少し時間がかかります。次回は数秒で完了します。

  5. BUILD SUCCESSFUL が出力されればビルド成功です。

プロキシーサーバーの設定

もしお使いのコンピューターがプロキシーサーバー経由のインターネットアクセスを行う場合は、次のコマンドを ./gradlew docs をする前に入力してください。インターネットを使ったライブラリの取得が正しく行われるようになります。ホスト名(example.com) と ポート番号(8080)部分はそれぞれの環境に合わせてください。

手順. プロキシーサーバー設定(Windows)
set JAVA_OPTS=-DproxyHost=example.com -DproxyPort=8080
手順. プロキシーサーバー設定(macOS / Linux)
export JAVA_OPTS=-DproxyHost=example.com -DproxyPort=8080

Asciidoc から変換された文書は次の場所に格納されます。

docs/index.html
docs/index.pdf
pdf
図 1. PDF 文書
html
図 2. HTML 文書
文書を github 上に公開する場合は、プロジェクトのファイルを全てコミットし、GitHub Pages に docs フォルダを指定することで継続的に文書をパブリッシュすることができます。

3.2. テキストエディタで Asciidoc 文書を編集する

プロジェクトに配置された Asciidoc 文書は Visual Studio Code を利用してリアルタイムに変換結果をプレビューしながら編集できるように準備されています。

プロジェクトフォルダ(asciidoctor-gradle-template-master)を Visual Studio Code で開き、拡張機能の推奨事項から拡張を導入します。

拡張機能の推奨は .vscode/extention.json で設定されています。文書に応じて設定し、執筆メンバーの環境を揃えることができます。
  1. すべてインストール ボタンをクリックします。

    vscode
  2. 再読み込み ボタンをクリックします。

    vscode
  3. Asciidoc 文書(src/docs/asciidoc/index.adocなど)を Visual Studio Code のエクスプローラーから選択して開き、文書を開いたエディタ部右上に配置された Open Preview to the Sideアイコンをクリックすると、画面右側に Asciidoc 文書の変換がリアルタイムに確認できるプレビューが表示されます。

    vscode

なお、もしリアルタイムプレビューでソースコードのハイライトが動作しない場合は、Asciidoc 文書を開いた状態で F1 を押し、Change Preview Security Setting  Disable を選択してください。

vscode
vscode

本設定は、プレビュー画面で動作する Webview がインターネット上の外部リソースを評価できるようにセキュリティー権限を下げる設定です。

プロジェクト(ファイルが配置されたフォルダ)毎の設定となりますが、この設定をした後はこのプロジェクトで第三者の作成した未知の Asciidoc 文書を開かないようにしてください。外部に配置された悪意の JavaScript により、セキュリティーを侵害される可能性があります。理解の上、設定してください。

拡張がソースコードのハイライトを行うため、CDN に配置されたリソースを参照しているために発生している問題で、将来ローカルのリソースを参照するように修正され解決されると思われます。

3.3. 文書のファイル構成

文書は次のようなファイルで構成します。サンプル文書から執筆したい文書に合わせてカスタマイズしていくとよいでしょう。

文書を構成するファイル
src/docs/asciidoc/index.adoc (1)
src/docs/asciidoc/attribute.adoc (2)
src/docs/asciidoc/@css/*.css (3)
src/docs/asciidoc/@css/pdf-theme.yml (4)
src/docs/asciidoc/@font/* (5)
src/docs/asciidoc/Chapter{number}/index.adoc (6)
1 文書を作成する起点となる Asciidoc 文書です。大きな文書の場合はここから他の Asciidoc 文書を include して構成していきます。
2 文書設定をするためのファイルです。各文書から incliude します。
3 HTML 用のスタイルシートです。editor.css はエディタのリアルタイムプレビューが使うスタイルシートです。その他は HTML 文書変換用です。いずれも文書に合わせて修正することができます。
4 PDF 文書に変換する際に使われるスタイル定義です。文書に合わせて修正することができます。
5 PDF 文書に埋め込みされるフォントファイルです。pdf-theme.yml から参照されています。TrueType フォント .ttf が指定できます。
6 src/docs/asciidoc/index.adoc から参照される子文書です。後述の build.gradle による画像パス解決のためフォルダ名は Chapter{number} とします。

変換スクリプトとなる build.gradleattribute 設定でこれらのファイルパスや変換に必要な属性を設定しています。

build.gradle
asciidoctor {
    attributes(
        'build-gradle': file('build.gradle'),
        'sourcedir': 'src/',
        'stylesdir': '@style',
        'stylesheet': 'asciidoctor.css',
        'source-highlighter': 'coderay',
        'pdf-stylesdir': "@style",
        'pdf-fontsdir': "@font",
        'pdf-style': 'pdf'
    )
    sources {
        include 'index.adoc'
    }
}

src/docs/asciidoc/attribute.adoc ではエディタのリアルタイムプレビュー用の属性定義を行い、文書変換スクリプトでその値を上書きするように構成すると良いでしょう。

Asciidoctor で利用可能な属性は次から参照できます。

Attributes are one of the features that sets Asciidoctor apart from other lightweight markup languages. Attributes can activate features (behaviors, styles, integrations, etc) or hold replacement (i.e., variable) content.

— asciidoctor.org

また、文書に挿入する画像ファイルは images というフォルダ名内に配置され、その文書からの相対パスでリンクされることを期待しています。設定は次の部分で変更可能です。

src/docs/asciidoc/attribute.adoc
 ifndef::imagesdir[:imagesdir: ./images]
build.gradle
 copy {
     from 'src/docs/asciidoc/'
     include 'Chapter*/images/*' // 子文書のフォルダ名
     into 'docs'
 }

3.3.1. 文書中の相互参照

文書内の参照リンクは次のように指定できます。

<<_文書のファイル構成,章の冒頭>> (1)
<<Chapter01/index.adoc#_はじめに,はじめに>> (2)
1 同一 .adoc 内での内部参照
2 .adoc をまたいだドキュメント間参照

リンクの例

3.4. asciidoctorj-diagram

本変換ビルドスクリプトでは asciidoctorj-diagram が有効になっており、いくつかのダイアグラム表記を使うことができます。

3.4.1. PlantUML

PlantUML 形式のダイアグラムを .svg ベクター画像で文書に埋め込みます。

diag sequence sample1
diag sequence sample2
diag sequence sample3

That’s all. Happy coding!