asciidoctorで日本語の本文とPlantUMLのクラス図が入った文書をPDFに変換してみた #asciidoctor

Plain-text diagrams take shape in Asciidoctor! | Asciidoctorという記事を見かけて、asciidoctorでPlantUMLのクラス図入りの文書をHTMLに出来ることを知りました。さらに日本語の本文を入れてPDFに変換できたのでメモしておきます。

サンプルソースは
hnakamur/asciidoctor-ditaa-graphviz-plantuml-example
に置きました。

AsciiDocのサンプルファイルは
https://github.com/hnakamur/asciidoctor-ditaa-graphviz-plantuml-example/blob/master/sample.adoc

サンプルPDFは
https://hnakamur.github.io/asciidoctor-ditaa-graphviz-plantuml-example/sample.pdf
です。

AsciiDocについて

AsciiDocについてはAsciiDocのブログ記事がわかりやすかったです。
本家のページはAsciiDoc Home Page。WikipediaのLightweight markup language - Wikipedia, the free encyclopediaというページにMarkdownやreSTなどの記法との対比表があります。

セットアップ

VLゴシックフォントをインストール

ダウンロードページからVLGothic-20130607.tar.bz2をダウンロードして展開し、
Finderで*.ttlファイルをOSXのFont Bookアプリにドラッグ＆ドロップします。
ファイルは~/Library/Fonts/にコピーされます。

graphvizとplantumlのインストール

Homebrewでインストールします。

brew install graphviz
brew install plantuml

サンプルの実行手順

試した環境はOS X 10.8.5です。予め、rubyとbundlerとjavaがインストール済みです。私が試したのはruby 2.1.2, bundler 1.6.2, java 1.8.0_05です。javaはJava SE - Downloads | Oracle Technology Network | OracleからJDK 8u5をダウンロード、インストールしました。

git clone --recursive https://github.com/hnakamur/asciidoctor-ditaa-graphviz-plantuml-example
cd asciidoctor-ditaa-graphviz-plantuml-example
bundle
make pdf
open sample.pdf

日本語の本文をPDF化する方法について

Promisesの薄い本 · Issue #7 · azu/azuを参考にさせていただきました。ありがとうございます！

PDF化にはasciidoctor/asciidoctor-fopubを使用しました。Gemfileに書いてbundleでインストールを試みたのですができませんでした。asciidoctor-fopubのREADMEに書いてあるようにダウンロードして使う想定のようです。
https://github.com/hnakamur/asciidoctor-ditaa-graphviz-plantuml-example ではgit submoduleとして追加しました。

asciidocからasciidoctorでdocbook形式に変換し、その結果をasciidoctor-fopubでpdfに変換します。

https

all: pdf

pdf:
    bundle exec ./asciidoctor -b docbook -d book sample.adoc
    ./asciidoctor-fopub/fopub sample.xml \
        -param body.font.family VL-PGothic-Regular \
        -param dingbat.font.family VL-PGothic-Regular \
        -param monospace.font.family VL-PGothic-Regular \
        -param sans.font.family VL-PGothic-Regular \
        -param title.font.family VL-PGothic-Regular

asciidoctorスクリプトの改変について

Plain-text diagrams take shape in Asciidoctor! | Asciidoctorの記事で紹介した文書では

の図をasciidoctor/asciidoctor-diagramという拡張によって扱っています。Enable the extensionsに説明があるのですが具体的にどう使うかは書かれていないので、今回はasciidoctor/asciidoctorに含まれるbin/asciidoctorを書き換えて試してみました。

オリジナルは

https

#!/usr/bin/env ruby

$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')

if RUBY_VERSION < '1.9'
  require 'rubygems'
end
require 'asciidoctor'
require 'asciidoctor/cli/options'
require 'asciidoctor/cli/invoker'

invoker = Asciidoctor::Cli::Invoker.new(ARGV)
invoker.invoke!
exit invoker.code

となっていますが、これをコピーしてrequire 'asciidoctor-diagram'の行を追加したものを https://github.com/hnakamur/asciidoctor-ditaa-graphviz-plantuml-example/blob/c4420c15a745aaec2f97907455a6cacfa9f8933c/asciidoctor としてサンプルに含めてあります。

(番外編) ちなみにasciidoctor-pdfも試しましたが今のところイマイチでした

asciidoctor/asciidoctor-fopubの前にopendevise/asciidoctor-pdfというのを見つけたので、そちらも試してみました。そのままでは日本語フォントが使えなかったので、forkして
Register 'VL PGothic' and 'VL Gothic' fonts for Japanese · 7ba4b79 · hnakamur/asciidoctor-pdfという変更を加えて試してみました。

題材はazu/promises-bookを使わせていただきました。手順は asciidoctor-pdfによるPDF作成 (試行錯誤中) で出力結果のPDFは http://hnakamur.github.io/promises-book/index-created-by-asciidoctor-pdf.pdf です。
目次の行が重なりまくってしまっているのと、本文中にバッククォートでコード片を囲っている箇所が多数あるのですが、閉じるバッククォートの後の日本語がいわゆるトーフ（白抜きの□）になっている箇所が何箇所か発生していました。

現時点ではasciidoctorでPDF生成はasciidoctor/asciidoctor-fopubを使うほうがよさそうです。