この記事は KLab Engineer Advent Calendar 2020 23日目の記事です。
Advent Calendar は去年に続き参加する mizusawa-k です。
個人的な事情で遅刻となってしまいましたが、Advent Calendar 最終日には間に合ってよかったです。
よろしくお願いします。

はじめに

私は年に二回程度KLabの有志で技術書典に出すための技術同人誌の記事を書いており、先日も明日から開催される技術書典10の新刊に向けて原稿を書いていたのですが、そうした原稿の作成ツールとしてRe:VIEWを利用しています。

Re:VIEWはテキスト形式のreファイルで原稿を記述し、pdfやEPUBなどの複数の形式で出力することが出来る書籍作成ソフトですが、そのRe:VIEWを使って原稿を執筆したり、はじめてRe:VIEWを使って執筆している人をサポートしたりする時に私自身が少し困ることとして、コードリストや画像、脚注といった要素の参照でビルドエラーが起きた時にどのreファイルのどこで起きているのかわかりにくい、特定しづらいということがありました。

そこで、今回の記事では、技術同人誌を執筆してきていてよくある or よくあると考えられるビルドエラーとしてコードリストや画像、脚注の指定ミスをした時のエラーログを確認してみたいと思います。

検証環境

今回、実際に使用している環境は下記です。

Re:VIEW： 5.0.0
OS: macOS Mojave(10.14.6)

ビルドエラーの仕込み

ビルドエラーの仕込みのために用意したreファイル

用意したreファイルの内容は、下記の記述をまとめたmizusawa-k.reというファイルです。コードリスト、画像、脚注の指定ミスといった確認したいエラーを出すのに必要な最小限の要素で構成されています。

コードリストの指定ミスがあった場合に出てくるエラーログを確認するために用意した記述は以下です。

# @# ビルドエラーを出すときのみ、下記を有効にする
# @# 以下の@<list>{MissingTestCodeList}は、テスト用のコードリストを示したものです。

# @# ビルドエラーを出さないときのみ、下記を有効にする
以下の@<list>{TestCodeList}は、テスト用のコードリストを示したものです。

# @# 下記は常に有効にする
//list[TestCodeList][テスト用のコードリスト]{
# include <stdio.h>

main()
{
  printf("Hello World\n");
}
//}

画像の指定ミスがあった場合に出てくるエラーログを確認するために用意した記述は以下です。

# @# ビルドエラーを出すときのみ、下記を有効にする
# @# //image[MissingTestImage][テスト用の画像][scale=0.4]{
# @# //}

# @# ビルドエラーを出さないときのみ、下記を有効にする
//image[TestImage][テスト用の画像][scale=0.4]{
//}

脚注の指定ミスがあった場合に出てくるエラーログを確認するために用意した記述は以下です。

# @# ビルドエラーを出すときのみ、下記を有効にする
# @# Re:VIEW@<fn>{MissingReview}はテキスト形式のファイルで記事を書いて、pdfやEPUBなどの複数の形式で出力出来る書籍作成ソフトです。

# @# ビルドエラーを出さないときのみ、下記を有効にする
Re:VIEW@<fn>{Review}はテキスト形式のファイルで記事を書いて、pdfやEPUBなどの複数の形式で出力出来る書籍作成ソフトです。

# @# 下記は常に有効にする
//footnote[Review][これはテスト用の脚注@@<href>{https://github.com/kmuto/review}]

ビルドエラーが出ないときのログを確認する

ビルドエラーを確認するときにはpdfのビルドが必要ですが、まずその前にエラーが出ない、pdfがきちんと作れるときのログを確認します。

私は普段、pdfを作るコマンドとしてはrakeコマンドを利用しているので、今回pdfを作る時にもrakeコマンドを利用したいと思います。
rakeコマンドを使う前の準備としては、不要なログが出ないようにするためにcatalog.ymlには先ほどのmizusawa-k.re以外のチャプターのreファイルは含めないようにしておきます。また、参照していない画像も不要なログが長くなる原因ですので適宜消しておきます。

今回、pdf出力を行う時に使用するrakeコマンドは下記の内容になります。

$ rake pdf

実際に、正常にpdfがビルドできるときのログを確認してみたところ、以下のような内容になっていました。コマンド実行をしてからpdf出力が問題なく行われ、実行が完了されるまでの全てのログが以下になります。

article mizusawa-k$ rake pdf
review-pdfmaker config.yml
WARN review-pdfmaker: major version of configuration file is different.
INFO review-pdfmaker: compiling preface.tex
INFO review-pdfmaker: compiling mizusawa-k.tex
INFO review-pdfmaker: compiling contributors.tex
INFO review-pdfmaker: extractbb dl-qr.png mizusawa-k/TestImage.png
INFO review-pdfmaker: uplatex -interaction=nonstopmode -file-line-error -halt-on-error __REVIEW_BOOK__.tex
INFO review-pdfmaker: uplatex -interaction=nonstopmode -file-line-error -halt-on-error __REVIEW_BOOK__.tex
INFO review-pdfmaker: uplatex -interaction=nonstopmode -file-line-error -halt-on-error __REVIEW_BOOK__.tex
INFO review-pdfmaker: dvipdfmx -d 5 -z 9 __REVIEW_BOOK__.dvi

ビルドエラーログの確認結果

準備ができ、きちんとpdfが作れているときのログも確認できたので、一つずつエラーを出していきます。

未定義のコードリスト参照エラー

未定義のコードリスト参照エラーでは、コマンドの実行以降のログ14行の中の6行目に、「MissingTestCodeListというコードリストが見当たらない」ということを示すログが続いていました。

INFO review-pdfmaker: compiling mizusawa-k.tex
WARN review-pdfmaker: compile error in mizusawa-k.tex (ReVIEW::ApplicationError)
WARN review-pdfmaker: mizusawa-k.re:8: error: unknown list: MissingTestCodeList

存在しない画像参照エラー

存在しない画像参照エラーでは、コマンドの実行以降のログ385行の中の6行目に、下記のように「MissingTestImageという画像が見当たらない」ということを示すログが続いていました。

INFO review-pdfmaker: compiling mizusawa-k.tex
WARN review-pdfmaker: mizusawa-k.re:29: image not bound: MissingTestImage
INFO review-pdfmaker: compiling contributors.tex

未定義の脚注参照エラー

未定義の脚注参照エラーでは、コマンドの実行以降のログ14行の中の6行目に、下記のように「MissingReviewという脚注が見当たらない」ということを示すログが続いていました。

INFO review-pdfmaker: compiling mizusawa-k.tex
WARN review-pdfmaker: compile error in mizusawa-k.tex (ReVIEW::ApplicationError)
WARN review-pdfmaker: mizusawa-k.re:38: error: unknown footnote: MissingReview

まとめ

この記事では、Re:VIEWでよくやってしまうと思われるコードリストや画像、脚注といった指定で未定義のものを指定してしまったときのビルドエラーログを確認しました。
Re:VIEWでビルドエラーが起きるのは大抵の場合、コードリストや画像などの参照が間違っているケースです。
この記事でわかった結論としては、今回の検証環境のような場合は

compiling <.re拡張子を含まないReファイルの名前>.tex

の後の行を見ると、参照が間違っているのがコードリストなのか画像なのか、はたまた脚注なのか。またその間違っている参照がどういう名前で定義されているのかということがわかるだろう、ということです。

結果として、コマンドの実行直後からログをきちんと順番に見ていればそんなに分かりづらいログでもなかった気もしますし、こういった検証をせずともすでにどこかでエラーログを載せている方もいそうではありますが、ビルドエラーがtexのコンパイルのタイミングで起きていたことや、どのreファイルをコンパイルしているか示すログの直後にエラーが出力されていたかということは、今回のような非常に小さい規模のreファイルの検証でなければわかりづらかった気がします。

このように簡単なものではありますが、意図していなかった発見もあり、また今後Re:VIEWで複数のreファイルで作られる本の原稿を自分自身書いたり、書いている人のサポートをする時もこれまでほど困らずに済みそうなのでよかったです。

本日、25日のKLab Engineer Advent Calendar はスペシャルなゲストのようです。お楽しみに。