asciidoctor-pdfでかっこいいPDFを作る(3)

[asciidoctor-pdf を使ってPDFかっこいいPDFを作る(1)](https://qiita.com/kuboaki/items/67774c5ebd41467b83e2)、
[asciidoctor-pdf を使ってPDFかっこいいPDFを作る(2)](https://qiita.com/kuboaki/items/18403900a2d9fe7a52f4) の続きです。
設定を調整して見栄えのよいPDFを作成した手順を紹介しています。

追記（2021/07/12）
asciidoctor-pdf 本体でフォントの対応について見直してもらえたようです。
この記事の説明のうち、フォントに関する部分については、 [asciidoctor-pdfで日本語を含むPDFの出力を行う](https://qiita.com/mitsu48/items/34875bbc8ba00760fe27#_reference-e1f72ce5e5f3d9cef664) を参考にするとよいでしょう。
それ以外の体裁に関するテーマの設定は、まだ使えると思います（全部は確認していませんのであしからず）。

## 文書にソースコードを追加する

設定の効果を見るために、先にソースコードを含む文書を用意して、現状を確認します。
example06.adocを修正してexample07.adocを作ります。

```asciidoc: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を利用
（略）
```

[example07.adoc](https://github.com/kuboaki/beauty-pdf-using-asciidoctor-pdf/blob/master/example07.adoc)

asciidoctor-pdf コマンドを使って example07.pdf を作成します。

```console
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts example07.adoc
```

まったくシンタックスハイライトされていないのがわかります。

![180104-0016.png](https://qiita-image-store.s3.amazonaws.com/0/3221/a8edf3e0-e662-1722-e01e-a40986702c2e.png)

[example07.pdf](https://github.com/kuboaki/beauty-pdf-using-asciidoctor-pdf/blob/master/example07.pdf)


## フォーマッタにはRougeを選択

ソースコードのシンタックスハイライトには、 [Rouge](http://rouge.jneen.net/)  というフォーマッタを使うことにしました。これは、行番号の表示、開始行番号の指定を使いたかったためです。

わたしは gem を使ってインストールしました。

## テーマファイルを用意する

スタイル変更のベースになるテーマファイルを用意します。

インストールディレクトリの `lib/rouge/themes` にテーマファイルが置いてあります。一から作ると大変なので、テーマファイルから好みのものを選んでコピーし、これを直して使うことにします。

ここでは `rouge_custom.rb` という名前で保存します。
最初はコピーしたままから始め、少しずつ調整するとのがよいと思います。

[rouge_custom.rb](rouge_custom.rb)

## Rouge使うよう文書を修正する

Rougeのスタイルをカスタマイズした場合には、作成している文書にも修正が必要です。文書の冒頭に、 asciidoctor-pdf の場合に使うフォーマッタの指定と、カスタマイズしたテーマを使うことを宣言する属性を設定します。

```asciidoc:example07.adoc
（略）
ifdef::backend-pdf[]
:source-highlighter: rouge
:rouge-style: custom   // 属性を追加した
endif::[]

= {doctitle}
（略）
```

## シンタックスハイライトの効果を確認する

asciidoctor-pdf コマンドを使って example07_r.pdf を作成します。
次のように `-r` オプションでRougeのカスタムテーマファイルを指定します。

```console
$ 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
```

カスタムテーマファイルに指示した色でハイライトされています。また、指定した行番号から始まる行番号が振られています。

![180104-0017.png](https://qiita-image-store.s3.amazonaws.com/0/3221/bd9c497d-5da4-3c65-2be4-bb265677616a.png)

[example07_r.pdf](https://github.com/kuboaki/beauty-pdf-using-asciidoctor-pdf/blob/master/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 は、文書を作成したり保守したりするのに大変便利なツールだと思います。みなさんも、ぜひ使ってみることをオススメします。