Markdown
asciidoctor
asciidoctor-pdf
Rouge

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

asciidoctorは快適なのだがPDFが…

asciidoctorを使うと文書作成が快適です。出力されるhtmlもまずまずの出来栄えだと思います。そして、asciidoctor-pdf を使うとPDFプリンタなどを使わなくても、直接PDFが得られます。素晴らしい。

ところが、初期設定のままでは出来栄えがあまりパッとしないのです。もうチョットなんとかならないかと思っていました。

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

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

180105-0001.png

前提

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

Qiitaのasciidoctor関連の記事

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

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

設定のヒント

この記事の設定のほとんどは、Asciidoctor PDF Theming Guide を参考にしています。

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

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

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

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 )を作成し、そこに文書や関連ファイルを作成しました。

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

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

PDFを作ってみる

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

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

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

180103-0001.png

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

$ asciidoctor -b html5 exapmle01.adoc

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

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

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

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

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

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

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

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

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

$ 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 オプションを使ってディレクトリを指定します。

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

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

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

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

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

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

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

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

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

$ 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

フォント設定を編集する

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

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

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+ 1mnM+ 1p Fallback に指定のフォントも、さきほど入手したフォントと同じ fonts ディレクトリにコピー(またはインストール)しておきます。これを忘れると、PDF作成時にフォントが見つからないというエラーになります。

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

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

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

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 の違いがわかるよう、次のように修正してみました。

example02.adoc
(略)
== はじめに

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

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

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

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

example02.adoc

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

$ 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

example02.pdf

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

章節の見出しを調整する

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

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を作ります。

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

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!: で番号がつかない設定に戻しています。

example03.adoc
(略)
:sectnums:

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

(略)
:sectnums!:

[appendix]
= 最初の付録

example03.adoc

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

$ 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

example03.pdf

長くなりましたので、タイトルページ、テーブルや図のキャプションなどについては、続きで。