14
Help us understand the problem. What are the problem?

posted at

updated at

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

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

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

180104-0016.png

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

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

180104-0017.png

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
14
Help us understand the problem. What are the problem?