asciidoctor-pdf を使ってPDFかっこいいPDFを作る(1)、
asciidoctor-pdf を使ってPDFかっこいいPDFを作る(2) の続きです。
設定を調整して見栄えのよいPDFを作成した手順を紹介しています。
追記（2021/07/12）
asciidoctor-pdf 本体でフォントの対応について見直してもらえたようです。
この記事の説明のうち、フォントに関する部分については、 asciidoctor-pdfで日本語を含むPDFの出力を行う を参考にするとよいでしょう。
それ以外の体裁に関するテーマの設定は、まだ使えると思います（全部は確認していませんのであしからず）。
文書にソースコードを追加する
設定の効果を見るために、先にソースコードを含む文書を用意して、現状を確認します。
example06.adocを修正してexample07.adocを作ります。
（略）
=== 第2部の最初の章の最初の節
第2部の最初の章の最初の節。第2部の最初の章の最初の節。第2部の最初の章の最初の節
==== 最初の章の最初の節の最初の項
第2部の最初の章の最初の節の最初の項。第2部の最初の章の最初の節の最初の項。第2部の最初の章の最初の節の最初の項。
<<sample-listing>> にプログラムリストのサンプルを示す。リストは include ディレクティブで取り込むこともできる。
[[sample-listing]]
.サンプルプログラム（C++）
[source,cpp,linenums,start=12,fontsize=3]
----
#include <iostream>
#include <string>
using namespace std;
// テンプレート関数
template <typename T>
T add(T x, T y){
return x + y;
}
int main(){
cout << add<int>(4, 3) << endl; // <1>
cout << add<string>("ABC", "DEF") << endl; // <2>
cout << add(1, 2) << endl; // 両方ともintの場合、型指定省略可能
return 0;
}
----
<1> 数値でadd関数を利用
<2> stringでaddを利用
（略）
asciidoctor-pdf コマンドを使って example07.pdf を作成します。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts example07.adoc
まったくシンタックスハイライトされていないのがわかります。
フォーマッタにはRougeを選択
ソースコードのシンタックスハイライトには、 Rouge というフォーマッタを使うことにしました。これは、行番号の表示、開始行番号の指定を使いたかったためです。
わたしは gem を使ってインストールしました。
テーマファイルを用意する
スタイル変更のベースになるテーマファイルを用意します。
インストールディレクトリの lib/rouge/themes にテーマファイルが置いてあります。一から作ると大変なので、テーマファイルから好みのものを選んでコピーし、これを直して使うことにします。
ここでは rouge_custom.rb という名前で保存します。
最初はコピーしたままから始め、少しずつ調整するとのがよいと思います。
Rouge使うよう文書を修正する
Rougeのスタイルをカスタマイズした場合には、作成している文書にも修正が必要です。文書の冒頭に、 asciidoctor-pdf の場合に使うフォーマッタの指定と、カスタマイズしたテーマを使うことを宣言する属性を設定します。
（略）
ifdef::backend-pdf[]
:source-highlighter: rouge
:rouge-style: custom // 属性を追加した
endif::[]
= {doctitle}
（略）
シンタックスハイライトの効果を確認する
asciidoctor-pdf コマンドを使って example07_r.pdf を作成します。
次のように -r オプションでRougeのカスタムテーマファイルを指定します。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts -r ./rouge_custom.rb example07.adoc -o example07_r.pdf
カスタムテーマファイルに指示した色でハイライトされています。また、指定した行番号から始まる行番号が振られています。
これで、だいぶ見栄えのするPDFになったのではないでしょうか。
さらに、ページのヘッダー・フッター、カバーページを設定すれば、よりかっこよくなるでしょう。
まだうまくいっていないこと
ここまでいろいろと試してみましたが、まだ、 asciidoctor-pdfが対応できていないことや、わたしが試した範囲でうまくいっていないことがあります。
- 脚注（footnote）は、記載したページの下端や章末に出力したいが、現在は書いたその場に挿入される
- 脚注を使わずに書く？
- 部や章の番号の書式に「第2部」「第3章」「第4節」のような形式が指定できない（自動採番はできている）
- 部番号は直接書き、章節は番号だけで済ませる
- 複雑な表組みは、asciidoctorでhtmlに出力できる場合でも、期待通りに整形できない
- 複雑な表は使わない、使うなら画像にして貼る
- SVGが期待通りの表示にならない（一部が表示されない、色がおかしいなど）
- 内部で使っている prawn-svg が "pure SVG" でないと正しく扱えないのが原因らしい
- 予めPNGなどに変換して使う
- 図表の番号が、文章全体の通番になってしまう
- 長い文章でなければ妥協してもよいだろう
- 図一覧、表一覧、ソースコード一覧などが作れない
- 長い文章でなければ妥協してもよいだろう
- ヘッダに章節名を出していると、部の扉のヘッダに前の節の名前が出力されてしまう
- Issueは書いてみた…
- プログラムを修正しないと直らないだろう
- 目次の挿入場所が固定されてしまう
- 献辞や前書きの後などに変更できない
開発は活発に行われているようなので、ここに挙げたことも、徐々に解決することでしょう。
まとめ
asciidoctor-pdfを使って見栄えのするPDFを作成する方法について紹介しました。
- 日本語のフォントを入手して使う
- テーマファイルを使って調整する
- 本文や見出しに使うフォントを変更する
- タイトルページを調整する
- キャプション、リードを調整する
- ソースコードを整形する
asciidoctorやasciidoctor-pdf は、文書を作成したり保守したりするのに大変便利なツールだと思います。みなさんも、ぜひ使ってみることをオススメします。