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

追記4（2022/10/8）
> asciidoctor-pdf 2.0あたりでテーマファイルを指定する引数が変更されています。
> この記事で紹介しているテーマファイルの指定方法ではうまくかなくなっています。
> 対応方法については、このことを気づかせてくれた記事「 [asciidoctor-pdfでのテーマファイルの指定](https://qiita.com/hoshimin108/items/e8ebc7abe7a2473aab03)」を参照することをお勧めします。また、テーマの各パラメータにも変更があります。そちらは、asciidoctor-pdfのテーマファイルのリファレンスを見れば解決できるでしょう。

追記3（2021/07/12）
> この記事の説明は、asciidoctor-pdfの1.5.x までに対応したものです。
> それ以外の体裁に関するテーマの設定は、まだ使えると思います（全部は確認していませんのであしからず）。
> 
> asciidoctor-pdfの1.6以降では、 asciidoctor-pdf-cjk を使うのをやめて、代わりに　asciidcotor-pdf の-a scripts=cjk オプションを追加します。
>
> asciidoctor-pdfの1.5まで：
（asciidoctor-pdf-cjkをgemでインストールした上で）
>
> ```
> asciidoctor-pdf -r asciidoctor-pdf-cjk その他の引数…
> ```
> 
>
> asciidoctor-pdfの1.6以降
> （asciidoctor-pdf-cjkをgemはインストールせずに）
>
> ```
> asciidoctor-pdf -a scripts=cjk　その他の引数…
> ```
>
> 詳しくは、 [asciidoctor-pdfで日本語を含むPDFの出力を行う] (https://qiita.com/mitsu48/items/34875bbc8ba00760fe27#_reference-e1f72ce5e5f3d9cef664) を参考にするとよいでしょう。
>

追記2
> 技術書典8で頒布予定だったレシピ集Vol. 2「[Raspberry Pi もっと食べたいレシピ集](https://techbookfest.org/product/5698446992343040)」を[オンライン販売](https://raspimoku.booth.pm/)しています（ごめんなさい。その後オンライン販売は終了しました）。この本も、著者たちが asciidoctor を使って執筆し、 asciidoctor-pdf を使ってPDF出力したものを入稿しました。章題の体裁、ノンブルの挿入、アイコン付きの対話形式など、この記事では扱えていない体裁のアレンジにもチャレンジしています（それ記事にしろよ、自分！）。

追記1
> 技術書典6（い14）で 「[Raspberry Pi 今すぐ食べたいレシピ集](https://techbookfest.org/event/tbf06/circle/67700001)」も電子版は引き続き[販売](https://raspimoku.booth.pm/)しています。この本は、著者たちが asciidoctor を使って執筆し、 asciidoctor-pdf を使ってPDF出力したものを入稿しました。

## asciidoctorは快適なのだがPDFが…

asciidoctorを使うと文書作成が快適です。出力されるhtmlもまずまずの出来栄えだと思います。そして、asciidoctor-pdf を使うとPDFプリンタなどを使わなくても、直接PDFが得られます。素晴らしい。ところが、初期設定のままでは出来栄えがあまりパッとしないのです。もうチョットなんとかならないかと思っていました。

この記事では、設定を調整して見栄えのよいPDFを作成した手順を紹介します。

最終型は、こんな感じです。

![180105-0001.png](https://qiita-image-store.s3.amazonaws.com/0/3221/1a3f8a8d-85b8-93f6-a289-f4d80a655eb4.png)

* [最終的にできるPDF](https://github.com/kuboaki/beauty-pdf-using-asciidoctor-pdf/blob/master/example07_r.pdf)
* [最終的なテーマファイル(mystyle-theme.yml)](https://github.com/kuboaki/beauty-pdf-using-asciidoctor-pdf/blob/master/theme/mystyle-theme.yml)

## 前提

すでに諸兄が asciidoctor の素晴らしさについては言及しているので、asciidoctorそのものについては説明しません。次のリンクを参考にしてください。

[Qiitaのasciidoctor関連の記事](https://qiita.com/tags/asciidoctor)

この記事では、みなさんがある程度 asciidoctor は使える状況にあるとします。

また、rakeコマンドなどを使って楽に作成する方法についても、この記事では触れません。他の方の記事などを参考に各自でお願いします。

## 設定のヒント

この記事の設定のほとんどは、[Asciidoctor PDF Theming Guide](https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc) を参考にしています。

このページを読んで設定すれば、みなさんもお好みのページに近づけるのではないかと思います。

わたしの場合、いちばんのポイントは本文と章節の見出しに使う日本語フォントを変えることでした。

## プログラムのインストール

asciidoctor-pdf の [Prerequisites](http://asciidoctor.org/docs/asciidoctor-pdf/#prerequisites) を確認して、必要なプログラムをインストールします。

asciidoctor-pdf は、rubyのバージョンについて 2.3.0 以上を推奨しています。
わたしは、MacOS上のRuby 2.3.x と下記の環境を使いました。

* asciidoctor (1.5.6.1)
* asciidoctor-pdf (1.5.0.alpha.16)
  - クロスリファレンスの表記に図表番号を反映するには、このバージョン以降を使うこと
  - まだ新しいパッケージのため、 `gem install asciidoctor-pdf --pre` でインストールしました
* asciidoctor-pdf-cjk (0.1.3)
  - 日本語を使った文章向けの設定が入っています
* rouge (2.1.1)
  - ソースコードの整形用に使いました
  - 開始行番号が指定できるので、これにしました

asciidoctor-pdf は、インストール時に prawn がインストールしてあるか調べ、なければ prawn もインストールします。すでに別途使っている場合には、バージョンを確認しておきましょう。

自分の環境では下記のバージョンでした。

* prawn (2.2.2)
* prawn-svg (0.24.0)
* prawn-templates (0.0.4)

## 元になる文書を作成する

設定を調整する前に、asciidoctor でいう book の構造を持つ単純なサンプル文書を作成し、この文書からPDFが作成できることを確認しましょう。その後、設定を調整しながらこの文書の変化を見ようと思います。

ここでは、自分のホームディレクトリ（自分の場合 `/Users/kuboaki` ）の Documents フォルダにテスト用フォルダ（ `adoc-test` ）を作成し、そこに文書や関連ファイルを作成しました。

```console
$ cd ~/Documents/adoc-test
$ vim exapmle01.adoc
```

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

asciidoctor形式の文書を作る時（includeする文書も含め）、utf-8を使わないと変換時にエラーになります。

## PDFを作ってみる

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

```console
$ asciidoctor-pdf -r asciidoctor-pdf-cjk exapmle.adoc
```

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

日本語含む文書の場合、最低限 `-r asciidoctor-pdf-cjk` というオプションを指定します。このオプションがない状態で作成したPDFは、半角と全角が混じる段落があると次のような感じになり、あまりいただけないです。

![180103-0001.png](https://qiita-image-store.s3.amazonaws.com/0/3221/2712a6cb-553c-6204-b4bb-0bbf45fd1b8f.png)


この記事を読んでいる方はご存知でしょうが、次のようにしてhtmlファイルが作れます。

```console
$ asciidoctor -b html5 exapmle01.adoc
```

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

同じ文書ファイルから、HTML、PDFが作成できるのですが、比べてみると見かけがだいぶ異なっていることがわかると思います。

## asciidoctor-pdf用テーマファイルを作る

PDFが作成できることが確認できたので、少しずつスタイルを調整します。

まず、asciidoctor-pdfの配布ファイルの `data/themes` から `default-theme.yml` を複製して  `mystyle-theme.yml` を作ります。

```console
$ cp （asciidoctor-pdfのインストールディレクトリ)/data/theme/default-theme.yml mystyle-theme.yml
```

このテーマファイルを使ってPDFを作成できることを確認します。
テーマファイルを指定するときは、次のように `pdf-style`
 オプションを使います。

```console
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml example01.adoc -o example01_d.pdf
```

> 上記の指定方法は、asciidoctor-pdf 2.0以降では使えません。追記3や下記の記述を参考にしてください。
> ```console
> asciidoctor-pdf -a scripts=cjk -a pdf-theme=mystyle-theme.yml example01.adoc -o example01_d.pdf
> ```
> テーマファイルの置き場所の指定方オプションも2.0以降変わりました。詳細は、
> [テーマファイルの設定項目のDeprecatedになった項目](https://docs.asciidoctor.org/pdf-converter/2.0/whats-new/#deprecated:~:text=for%20PNG%20images.-,Deprecated,-The%20following%20features) を参照してください。

最後の `-o` オプションは出力するPDFファイルのファイル名を指定するためのものです。省略すると、入力ファイル名の拡張子を.pdfにしたものが作られます。

テーマファイルが別のディレクトリにあると次のようなエラーになります。

```console
$ mkdir theme
$ mv mystyle-theme.yml theme
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml example02.adoc
No such file or directory @ rb_sysopen - default-theme.yml
  Use --trace for backtrace
```

この場合、 `pdf-stylesdir` オプションを使ってディレクトリを指定します。

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

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

できたPDFは、最初のPDFと変わりがないと思います。ですが、テーマファイルを使って作成したので、ここからは少しずつスタイルを調整していけます。

## 別の日本語フォントを入手する

asciidoctor-pdf自身の配布ファイルの中には `Noto Serif` というゴシック系の日本語フォントが含まれていて、example01.pdfではこのフォントが使われています。これを、本文に明朝系を使い、見出しに角ゴシック系のフォントを使うように変更してみようと思います。

現在のところ、asciidoctor-pdfで使えるのTrueTypeフォントだけです。本文用はプロポーショナルな明朝体を、見出しには太字の設定が豊富でプロポーショナルなゴシック体を選んでおくとよいと思い、次のフォントを使うことにしました。

モノスペースのフォントは、ソースコードを扱うことを考えて、プログラマが使うような等幅フォントを選んでみました。

* 明朝体：[AozoraMincho （あおぞら明朝）](http://blueskis.wktk.so/AozoraMincho/)
* ゴシック体：[GenShinGothic-P（源真ゴシック-P）](http://jikasei.me/font/genshin/)
* モノスペース：[RictyDiminished](http://www.rs.tus.ac.jp/yyusa/ricty_diminished.html)

書体として normal、 bold、  italic、bold_italic が選べるとよいのですが、わたしにはそのような書体を持つ日本語TrueTypeフォントはみつけられませんでした。

わたしはこれらのフォントをシステムにインストールして使っていますが、PDFの作成に使うだけならば、フォントをシステムにインストールしなくてもかまいません。

ここでは、 `fonts` ディレクトリを作成して、ここにフォントを置いて使ってみます。

```console
$ ls fonts
AozoraMincho-bold.ttf   AozoraMinchoRegular.ttf         GenShinGothic-P-Normal.ttf
AozoraMincho-thin.ttf   GenShinGothic-P-Bold.ttf        GenShinGothic-P-Regular.ttf
AozoraMinchoBlack.ttf   GenShinGothic-P-ExtraLight.ttf  RictyDiminished-Bold.ttf
AozoraMinchoHeavy.ttf   GenShinGothic-P-Heavy.ttf       RictyDiminished-BoldOblique.ttf
AozoraMinchoLight.ttf   GenShinGothic-P-Light.ttf       RictyDiminished-Oblique.ttf
AozoraMinchoMedium.ttf  GenShinGothic-P-Medium.ttf      RictyDiminished-Regular.ttf
``` 

## フォント設定を編集する

テーマファイル中のフォントの設定を編集します。

追記：
> Asciidoctor-pdf 2.0 では、フォントの扱いもすこし変わっています。また、基本的なCJK用のフォントも同梱されるようになりました。次のように書いておけば、defaultの設定に対する差分を書けば済むようになりました。
> ```yaml:mystyle-theme.yml
> extends: default
> font:
>   catalog:
>     AozoraMincho:
>  （略）
>  ```


`catalog` の下に設定用のフォントファミリ名を作成し、その下にスタイルごとに使用するフォントファイル名を指定します。基本的には `default.yml` の記述を活かし、そこに追加した日本語フォントの設定を追加します。

```yaml:mystyle-theme.yml
font:
  catalog:
    AozoraMincho:
      normal: AozoraMinchoRegular.ttf
      italic: AozoraMinchoMedium.ttf
      bold: AozoraMinchoHeavy.ttf
      bold_italic: AozoraMinchoBlack.ttf
    GenShinGothic-P:
      normal: GenShinGothic-P-Normal.ttf
      italic: GenShinGothic-P-Regular.ttf
      bold: GenShinGothic-P-Medium.ttf
      bold_italic: GenShinGothic-P-Bold.ttf
    RictyDiminished:
      normal: RictyDiminished-Regular.ttf
      italic: RictyDiminished-Oblique.ttf
      bold: RictyDiminished-Bold.ttf
      bold_italic: RictyDiminished-BoldOblique.ttf
    M+ 1mn:
      normal: mplus1mn-regular-ascii-conums.ttf
      bold: mplus1mn-bold-ascii.ttf
      italic: mplus1mn-italic-ascii.ttf
      bold_italic: mplus1mn-bold_italic-ascii.ttf
    M+ 1p Fallback:
      normal: mplus1p-regular-fallback.ttf
      bold: mplus1p-regular-fallback.ttf
      italic: mplus1p-regular-fallback.ttf
      bold_italic: mplus1p-regular-fallback.ttf
  fallbacks:
    - M+ 1p Fallback
（略）
```

当初は、italicや斜体がないフォントでは normal と同じ書体を選べばよいかと考えました。しかし、ここでいうitalicは、強調したい場合のスタイルの指定です。これを normal と同じスタイルにしてしまっては強調になりません。そこで（見てくれは多少犠牲にして）、italicや bold_italic には、太さの異なる同じ書体を設定してみました。

その後に続く `M+ 1mn` は、ソースコードのコメントに使う callout の丸数字などのために用意してあるフォントの指定です。
`fallbacks` は、選択中のフォントに出力対象の文字が見つからないとき、代用フォントとして使うフォントの設定です。上の設定では、 `M+ 1p Fallback`  に指定のフォント、つまり  `mplus1p-regular-fallback.ttf` が使われます。

`M+ 1mn` と  `M+ 1p Fallback`  に指定のフォントも、さきほど入手したフォントと同じ fonts ディレクトリにコピー（またはインストール）しておきます。これを忘れると、PDF作成時にフォントが見つからないというエラーになります。

```console
$ cp （asciidoctor-pdfのインストールディレクトリ)/data/fonts/mplus*.ttf fonts
```

次に、再び `mystyle-theme.yml` を編集します。本文のフォントに `Noto Serif` が指定してあるので、これを今回入手した `AozoraMincho` に置き換えます。

ついでに、本文を左寄せにし、フォントサイズを10ポイント、行送りを1.5行に変更しました。

```yaml:mystyle-theme.yml
（略）
base:
  align: left
  font_color: 333333
  font_family: AozoraMincho # Noto Serif
  font_size: 10
  line_height_length: 15
  line_height: $base_line_height_length / $base_font_size
  font_size_large: round($base_font_size * 1.25)
  font_size_small: round($base_font_size * 0.85)
  font_size_min: $base_font_size * 0.75
  font_style: normal
  border_color: eeeeee
  border_radius: 4
  border_width: 0.5
（略）
```

## フォントの変更を確認する

フォント設定の変更の効果があるかどうか確認します。
example01.adocを修正してexample02.adocを作ります。
normal、 italic、 bold、 bold_italic の違いがわかるよう、次のように修正してみました。

```asciidoc:example02.adoc
（略）
== はじめに

normal: ここに「はじめに」にあたる文章を書く。

// italicによる強調は「_」で囲む
italic: _ここに「はじめに」にあたる文章を書く。_

// boldによる強調は「*」で囲む
bold: *ここに「はじめに」にあたる文章を書く。*

// bold_italicによる強調は「*_」で囲む
bold_italic: *_ここに「はじめに」にあたる文章を書く。_*
（略）
```

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

asciidoctor-pdf コマンドを使って再びPDFを作成します。今回は、 `pdf-fontsdir` を使ってフォントを置いたディレクトリを指定します。

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

このディレクトリの指定に `~` を使いたくなりますが、どうもホームディレクトリ名には展開されないようです。

作成したPDFに使われているフォントが「あおぞら明朝」に変わりました。「はじめに」の本文は、原稿の中でitalicによって強調している箇所が「あおぞら明朝」の太字を使って代用できているのがわかります。

![180104-0003.png](https://qiita-image-store.s3.amazonaws.com/0/3221/8251283a-61ec-67c2-9992-3de238aef8d6.png)


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


また、「最初の章」の本文をみると、行間が拡がって読みやすくなっています。

## 章節の見出しを調整する

章や節の見出しに使うフォントを角ゴシック系のフォントに変更し、フォントサイズ、行送り、色などを調整します。
フォントサイズは、個別に指定せず、本文のフォントサイズ（`$base_font_size` ）を元に計算しています。

```yaml:mystyle-theme.yml
（略）
heading:
  align: left
  font_color: 2D466B
  font_family: GenShinGothic-P
  font_style: bold
  # h1 is used for part titles (book doctype only)
  h1_font_size: floor($base_font_size * 2.4)
  h2_font_size: floor($base_font_size * 2.4)
  h3_font_size: round($base_font_size * 1.7)
  h4_font_size: round($base_font_size * 1.4) 
  h5_font_size: $base_font_size
  h6_font_size: $base_font_size_small
  line_height: 1.4
  margin_top: $vertical_rhythm * 0.9
  margin_bottom: $vertical_rhythm * 0.9
（略）
```

## 見出しの変更を確認する

見出しを変更した効果があることを確認します。
example02.adocを修正してexample03.adocを作ります。

ついでに、章、節、目次などが日本語になるよう、文書の冒頭でこれらのラベルを設定します。

```asciidoc:example03.adoc
:encoding: utf-8
:lang: ja
:author: 著者名
:doctitle: サンプル文書のタイトル: 文書のサブタイトル
:doctype: book
:toc: left
:chapter-label:
:figure-caption: 図
:example-caption: 例
:table-caption: 表
:appendix-caption: 付録
:toc-title: 目次
:listing-caption: リスト
（略）
```

また、章節には通し番号がつくよう、 第1部の前に `:sectnums:` を設定します。その後、付録の前で `:sectnums!:` で番号がつかない設定に戻しています。

```asciidoc:example03.adoc
（略）
:sectnums:

= ここが第1部のタイトル

（略）
:sectnums!:

[appendix]
= 最初の付録
```

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

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

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

作成したPDFを表示すると、見出しに使われてるフォントが「源真ゴシック-P」に変わり、章節番号がついています。また、目次や付録のページでは、見出しが日本語に変わっています。


![180104-0005.png](https://qiita-image-store.s3.amazonaws.com/0/3221/81a28fd7-04f5-beb8-c92d-b12c0f8e6f9d.png)

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

長くなりましたので、タイトルページ、テーブルや図のキャプションなどについては、[続き](https://qiita.com/kuboaki/items/18403900a2d9fe7a52f4)で。