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

6568 ワード
Markdown Rouge asciidoctor-pdf asciidoctor Markdown テキストリンク

asciidoctor-pdf を使ってPDFかっこいいPDFを作る(1)、
asciidoctor-pdf を使ってPDFかっこいいPDFを作る(2) の続きです。
設定を調整して見栄えのよいPDFを作成した手順を紹介しています。

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

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

設定の効果を見るために、先にソースコードを含む文書を用意して、現状を確認します。
example06.adocを修正してexample07.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を利用
（略）

example07.adoc

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

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

example07.pdf

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

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

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

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

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

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

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

rouge_custom.rb

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

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

example07.adoc
（略）
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

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

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 は、文書を作成したり保守したりするのに大変便利なツールだと思います。みなさんも、ぜひ使ってみることをオススメします。