はじめに
Re:VIEWは、1つのソースファイルからePubとPDFの両方を生成できるツールです。技術書典でお世話になった人も多いでしょう。
しかし使ってみた人はわかると思いますが、Re:VIEWは使いづらかったり分かりにくいところが多々あります。そこでいくつかpull requestやissueを出して、何点かはRe:VIEW 2.5で改善されました。
この記事ではそれらの改善点を紹介します。
（なおこの記事が書かれたのは2018年5月ですが、6月には次の新しいバージョンが出ると思われます。）
Re:VIEW 2.5の改善点
ヘルプを表示するオプションが追加
(https://github.com/kmuto/review/pull/932)
Re:VIEW 2.5から、reviewコマンドにヘルプを表示するオプションが追加されました。「えっ、いまさら？」と言われそうですが、そうなんです、今まではなかったんです。
$ review --help
usage: review <command> [<args>]
Re:VIEW commands are:
init : generate Re:VIEW project directory.
preproc : preprocess Re:VIEW document file.
compile : convert Re:VIEW document file.
epubmaker : build EPUB.
webmaker : build web pages.
pdfmaker : build PDF with LaTeX.
textmaker : build text files.
vol : show volume of Re:VIEW document.
check : check there are no REJECT words in the document.
index : show heading list.
validate : validate Re:VIEW document files.
version : show Re:VIEW version.
--help : show this message.
reviewコマンドの引数をわざと省略すると、エラーメッセージがわりにヘルプが表示されます。今まではこのような方法でしか、ヘルプを表示できませんでした。2.5からは、ずっと素直な方法でヘルプが表示されます。
ヘルプメッセージにサブコマンドの説明が追加
(https://github.com/kmuto/review/issues/933)
Re:VIEW 2.5から、ヘルプメッセージにサブコマンドの説明がつくようになりました。「えっ、いまさら？」と言われそうですが、そうなんです、今まではついてなかったんです。
2.4までのヘルプメッセージ：
$ review
usage: review <command> [<args>]
ReVIEW commands are:
init
preproc
compile
epubmaker
pdfmaker
vol
check
index
validate
これじゃ、サブコマンドが何をするのか分かりませんね。2.4までこの状態だったことに驚きます。
バージョンを表示するサブコマンドが追加
(https://github.com/kmuto/review/pull/932)
Re:VIEW 2.5から、reviewコマンドにバージョンを表示するサブコマンドがつきました。「えっ、いまさら？」と言われそうですが、そうなんです、今まではなかったんです。
$ review version
2.5.0
review --versionじゃなくてreview versionです。間違えないようにしましょう。
Rakefileの中身が専用ファイルに移動
(https://github.com/kmuto/review/issues/921)
Re:VIEW 2.4までは、すべてのRakeタスクがRakefileに書かれていました。2.5では、これがlib/tasks/review.rakeに移動され、Rakefileはそれを読み込むだけになりました。ちょうど、Railsと同じやり方ですね。
こうすることで、独自のRakeタスクを追加してもRe:VIEWのバージョンアップがしやすくなりました。Re:VIEWはバージョンアップのしやすさをあまり考慮してるようには見えないのですが、2.5で少し改善されました。
(LaTeX) スタイルファイルを複数指定可能に
(https://github.com/kmuto/review/pull/908)
config.yml中の「texstyle:」オプションに配列を指定することで、スタイルファイルを複数指定できるようになりました。
# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと)
texstyle: [reviewmacro, mystyle]
こうすることで、reviewmacro.styを変更することなく、自作マクロの追加や既存マクロの変更を別のスタイルファイルにできます。これでRe:VIEWのバージョンアップがしやすくなります。
従来は、自作マクロの追加や既存マクロの変更は、実質的にreviewmacro.styに書くしかなく、そのせいでRe:VIEWのバージョンアップがしにくくなっていました。その問題が解消されました。
しかし自作マクロを追加するためには、新規スタイルファイル（たとえばsty/mystyle.css）を用意し、それをconfig.ymlの「texstyle:」に指定する必要があります。分かってしまえば大した手間ではありませんが、分かってない場合はやり方を調べる必要があり、Re:VIEW初心者には難易度が高いです。
この点を改善するには、あらかじめ空のsty/mystyle.cssが用意されていればいいだけですが、提案したものの却下されました。「分かっている人にとっては簡単なことでも分かってない人には難しい」というのが、開発チームには理解されませんでした。Re:VIEWの使いにくさはこういう細かい点の積み重ねです。
(LaTeX) A5のときの奥付の罫線を修正
(https://github.com/kmuto/review/pull/907)
Re:VIEWでは奥付を作成する機能があります。しかしこの奥付の罫線は14cm固定だったため、B5だとちょうどいい長さですが、A5だと長すぎでした。
2.4での奥付(A5)： 
これが2.5で修正されました。
2.5での奥付(A5)： 
これが今まで問題になってなかったようなので、恐らくですが、Re:VIEWをA5で使ってる人はほとんどいないのでしょう。
(LaTeX) ソースコードの表示で、キャプションなしだと空きスペースが広すぎたのを修正
(https://github.com/kmuto/review/pull/913)
連番なしのリスト//emlist[]{ ... //}をキャプションなしで使った場合、2.4では本文との間のスペースが空きすぎていました。
サンプルの原稿：
(A)キャプションあり
//emlist[フィボナッチ数列]{
def fib(n)
return n <= 1 ? n : fib(n-1)+fib(n-2)
end
//}
(B)キャプションなし（言語指定なし）（@<code>{//emlist{ ... //\}}）
//emlist{
def fib(n)
return n <= 1 ? n : fib(n-1)+fib(n-2)
end
//}
(C)キャプションなし（言語指定つき）（@<code>{//emlist[][ruby] ... //\}}）
//emlist[][ruby]{
def fib(n)
return n <= 1 ? n : fib(n-1)+fib(n-2)
end
//}
これをRe:VIEW 2.4でPDFへ変換すると、次のようになります。本文とコードとの間のスペースが、(A)だと適切、(B)だとちょっと広い気もするけど許容範囲内、(C)はスペースが少し空きすぎです。
この問題が2.5で修正されました。
ところでこのバグは、修正してもらうまでが大変でした。見たら分かるように明らかにバグですが、pull reqを出しても
- 『「たとえ当時のが間違った値だったとしても過去の版に影響を及ぼさないように注意し、及ぶなら大々的にアピール」という組版ソフトの原則があります』
- 『システムのlayout.tex.erbでこのアキ調整を入れると、既存の標準レイアウトでやっていたコンテンツはいろいろ変わってしまう可能性』
などと言われて対応してもらえなかったのに、別の人が指摘したらすんなり修正されました。『過去の版に影響を及ぼさないように注意』じゃなかったの？『既存の標準レイアウトでやっていたコンテンツはいろいろ変わってしまう可能性』はどこいった？こんなあからさまに違う対応をとられると、ちょっと・・・ね。
(LaTeX) 原稿ファイルが存在しないときのエラーメッセージが改善
(https://github.com/kmuto/review/issues/953)
catalog.ymlに指定された原稿ファイルが存在しない場合、当然ですがエラーになります。そのときのエラーメッセージが、2.4では分かりにくかったのが、2.5で改善されました。
2.4の場合：
$ rake pdf
review-pdfmaker config.yml
compiling chap1.tex
WARN: review-pdfmaker: compile error in chap1.tex (TypeError)
WARN: review-pdfmaker: no implicit conversion of nil into String
ERROR: review-pdfmaker: compile error, No PDF file output.
rake aborted!
Command failed with status (1): [review-pdfmaker config.yml...]
...
2.5の場合：
$ rake pdf
review-pdfmaker config.yml
E, [2018-04-18T23:50:25.305243 #11962] ERROR -- : review-pdfmaker: file not found in catalog.yml: ./chap1.re
rake aborted!
Command failed with status (1): [review-pdfmaker config.yml...]
...
全般的に、Re:VIEWはエラーメッセージが分かりにくく、初心者泣かせです。それが少しだけ改善されました。
(LaTeX) 存在しない画像ファイルを参照したときのエラーメッセージが改善
(https://github.com/kmuto/review/issues/954)
@<img>{...}で画像を参照したとき、その画像が存在しない場合、エラーになります。そのときのエラーメッセージが、2.4では分かりにくかったのが、2.5で改善されました。
2.4の場合：
$ rake pdf
review-pdfmaker config.yml
compiling chap01.tex
WARN: review-pdfmaker: compile error in chap01.tex (ReVIEW::ApplicationError)
WARN: review-pdfmaker: chap01.re:6: error: not found key 'cover2' for ReVIEW::Book::IndepImageIndex
ERROR: review-pdfmaker: compile error, No PDF file output.
rake aborted!
...
2.5の場合：
$ rake pdf
review-pdfmaker config.yml
compiling chap01.tex
W, [2018-04-19T00:05:29.770974 #12145] WARN -- : review-pdfmaker: compile error in chap01.tex (ReVIEW::ApplicationError)
W, [2018-04-19T00:05:29.771088 #12145] WARN -- : review-pdfmaker: chap01.re:6: error: unknown image: cover2
E, [2018-04-19T00:05:29.771639 #12145] ERROR -- : review-pdfmaker: compile error, No PDF file output.
rake aborted!
...
全般的に、Re:VIEWはエラーメッセージが分かりにくく、初心者泣かせです。それが少しだけ改善されました。
2.5で残っている改善点
Re:VIEW 2.5でも直っていないバグ、2.5に間に合わなかった修正を紹介します。
ブロックの入れ子ができない
Re:VIEWの文法上の制約で、ブロックを入れ子にできません。たとえばノートや註釈を表すブロックの中に//emlist{ ... //}を入れてみましょう。
//note[ゼロ除算に注意]{
`x / y`という式において、`y`がゼロだとエラーになります。
//emlist[][ruby]{
x, y = 1, 0
puts( x/y ) #=> エラー
//}
//}
このような文章はよくあると思いますが、これをrake pdfでコンパイルすると、エラーになります。
$ rake pdf
review-pdfmaker config.yml
compiling mybook.tex
W, [2018-05-28T22:13:52.103566 #24393] WARN -- : review-pdfmaker: compile error in mybook.tex (ReVIEW::ApplicationError)
W, [2018-05-28T22:13:52.103643 #24393] WARN -- : review-pdfmaker: mybook.re:13: error: block end seen but not opened
E, [2018-05-28T22:13:52.103729 #24393] ERROR -- : review-pdfmaker: compile error, No PDF file output.
rake aborted!
このくらい対応してくれてもよさそうですが、現在のRe:VIEWでは未対応です。入れ子ブロックの構文解析は技術的には難しくないはずですが、何か事情があるのかもしれません。
(LaTeX) フォントサイズを指定しても反映されない
(https://github.com/kmuto/review/issues/912)
LaTeXでデフォルトのフォントサイズを10ptから変更したい場合、たとえば9ptという指定をします。
\documentclass[dvipdfmx,uplatex,a5j,9pt]{jsbook}
これと同等のことをRe:VIEWで行うには、config.ymlに以下のように指定します。
# LaTeX用のdocumentclassを指定する
texdocumentclass: ["jsbook", "uplatex,oneside,a5j,9pt"]
この方法はこちら↓でも紹介されている、由緒正しい方法です。
[ReVIEW Tips] 本文フォントの大きさを変えたい - Qiita
しかしこの設定をしても、実際にはフォントサイズが変わりません。
これはA5サイズのPDFを生成したいときに、大変困ります。実際に試してみると、こうなります↓。ちょっと分かりづらいですが、フォントサイズが10ptのままで変わっていません。
こうなってしまう原因は、Re:VIEWが余計なパッケージを読み込んでいるせいです。具体的には、option指定なしでgeometryパッケージを読み込んでいるせいです。
これを修正するには、Re:VIEWのgemからlayout.tex.erbファイルをlayoutsディレクトリにコピーして、geometryパッケージを読み込んでいる行の先頭に「%」をつけてコメントアウトします。
（とはいっても面倒くさいので、review initの代わりにreviewstarterを使うのがいいでしょう。）
ほんとはRe:VIEW自体で対応してほしいのですが、今までの対応からみると、互換性を理由に却下されることでしょう。Re:VIEWのフォント問題で苦しんでる人は他にもいますが（たとえばこちら↓）、今後も後を断たないと思われます。
そもそも、本文の「幅を広げたい」「高さを高くしたい」だけなら、本文の幅や高さを指定するかわりに上下左右の余白を狭くすればいいだけなので、LaTeXの標準機能で対応できます。本文の幅と高さを指定したいならgeometryパッケージを読み込む必要がありますが、そんな必要が本当にあるのかをまず考えるべきです。
原稿ファイルがトップディレクトリにしか置けない
(https://github.com/kmuto/review/issues/920)
ソフトウェア開発では、ソースファイルは専用のディレクトリにまとめて置かれます。たとえば、
- Javaのプロジェクトなら
srcディレクトリに、 - Rubyのプロジェクトなら
libディレクトリに、
ソースファイルが置かれるのが一般的です。これはソースファイルが1つだけでも変わりません。
しかしRe:VIEWプロジェクトでは、原稿ファイルがトップディレクトリに置かれ、専用のディレクトリが用意されていません。そのため、原稿ファイルが散らかってしまいます。別の言い方をすると、ソフトウェア開発での常識がRe:VIEWには活かされていません。
たとえば、とある技術系同人誌の原稿ファイルは次のようになっています。チャプターごとに分かれた原稿ファイル（ファイル名が「*.re」）が、トップディレクトリに散らかっていることがわかります。
$ ls -F
01-writing.re images/
04-attendEvent.re layouts/
05-thinkScript.re locale.yml
07-howToOrder.re material/
08-preparations.re out.pdf
09-morning.re output.re
10-eventTips.re postscript.re
11-afterevent.re preface.re
13-booth.re prepare.re
14-Meetup.re prepare_ykichinmiya.re
15-aboutMoney.re prh.yml
16-tempTopix.re sample/
Rakefile sec-cover.re
assets/ sec-image-win7.re
book-style.re sec-image.re
c93-onestop-techbook.pdf sec-nombre.re
catalog.yml sec-windows7-installation.re
codes/ sec-word-intro.re
config.yml sty/
contributors.re style-web.scss
epub_style.scss style.scss
frontcover.re writing.re
できることなら、原稿ファイルを入れるための専用ディレクトリがreview initコマンドで作られるといいのですが、そうはなっていません。
そこで、原稿ファイルを入れる専用のディレクトリを作ることを提案したのですが、『ほかの人にどの程度実用性があるのか』『章ごと管理を使いたいというケースのほうがあるのではないか』『そもそも私自身は必要性を感じていないので、あまりモチベーションがわかないんですよねぇ』などと言われて中々受け入れられず、説得に苦労しました。
Re:VIEWの次のバージョンではconfig.ymlに「contentdir:」オプションが新たに用意され、原稿ファイルを置くディレクトリを指定できるようになるはずです。すんなり通っていれば2.5に間に合ったはずなので、残念です。
(LaTeX) キャプションとソースコードの間で改ページされることがある
Re:VIEWでは//list[label][キャプション][lang]{ ... //}を使ってソースコードにキャプションをつけられます。このとき、キャプションとソースコードとの間で改ページされることがあります。
あまり望ましいことではないので、ソースコードと離さずにキャプションをつけてほしいです。
(LaTeX) ソースコードにおける上と下のpaddingが広すぎる
さきほどの画像を見たら分かると思いますが、Re:VIEWの標準デザインではソースコードの上と下のpaddingが広すぎます。そのため、先頭と末尾にあたかも空行が入っているかのように見えます。また少しでもページ数を減らしたいときは、このpaddingが憎たらしく見えます。
これを修正するには、Re:VIEWが用意しているLaTeXマクロを上書きし、\vspace*{-1.0zw}のようなマイナスの高さのスペースを入れます。
%% sty/reviewstyle.sty に追加
\renewenvironment{reviewemlist}{%
\medskip%
\begin{shaded}%
\vspace*{-1.0zw}
\small%
\setlength{\baselineskip}{1.3zw}%
\begin{alltt}%
}{%
\end{alltt}%
\vspace*{-1.0zw}%
\end{shaded}%
}
\renewenvironment{reviewlist}{%
\begin{shaded}%
\vspace*{-1.0zw}%
\small%
\setlength{\baselineskip}{1.3zw}%
\begin{alltt}%
}{%
\end{alltt}%
\vspace*{-1.0zw}%
\end{shaded}%
\par\vspace*{0.5zw}%
}
\renewenvironment{reviewsource}{%
\begin{shaded}%
\vspace*{-1.0zw}%
\small%
\setlength{\baselineskip}{1.3zw}%
\begin{alltt}%
}{%
\end{alltt}%
\vspace*{-1.0zw}%
\end{shaded}%
\par\vspace*{0.5zw}%
}
\renewenvironment{reviewcmd}{%
\color{white}%
%\medskip%
\small%
\begin{shadedb}%
\vspace*{-1.0zw}%
\setlength{\baselineskip}{1.3zw}%
\begin{alltt}%
}{%
\end{alltt}%
\vspace*{-1.0zw}%
\end{shadedb}%
}
こうすると、次のようにpaddingが狭くなります。
これも標準で対応してほしいですが、『過去の版に影響を及ぼ』してしまうし『既存の標準レイアウトでやっていたコンテンツはいろいろ変わってしまう』ので、対応されることはないでしょう。
終わりに
冒頭の繰り返しになりますが、Re:VIEWは使いづらい点や分かりにくい点が多々あります。そのうち自分でpull reqやissueを出して改善された点を説明しました。また現在も残っている問題点や、次のバージョンで修正されるであろう点も説明しました。
しかし説明した内容を見れば分かりますが、フォントサイズの変更が反映されないとか、ヘルプメッセージにサブコマンドの説明がないとか、Re:VIEWは基本的な機能に問題が多いです。これでバージョン2.4や2.5なんですよね。まあ、バージョンが上がるごとに少しずつ良くなっていくんじゃないでしょうか。新しいバージョンに期待しましょう。
おまけ
Re:VIEWの強みは、1つの原稿ファイルからePubとPDFの両方を生成できることです。しかしePubがいらなくてPDFだけを生成するなら、その強みは活きてこず、欠点のほうが目立ちます。Re:VIEWに限界を感じたら、他のツールも試してみてはどうでしょう。
またRe:VIEWを使う場合は、review initのかわりにreviewstarterを使うと、トラブルが少なくて済みます。特に初心者の人にはお勧めです。