2020/2/29 by @kmuto
Re:VIEW 4.1 での変更点¶
Re:VIEW 4.1 において Re:VIEW 4.0 から変更した点について解説します。
2020年2月29日に、令和最初の版となる「Re:VIEW 4.1.0」をリリースしました。
このバージョン 4.1 では、前回リリースの 4.0 で発見された不具合の修正を行うとともに、いくつかの改良を施しています。
既知の問題¶
現時点では報告はありません。
既存プロジェクトのバージョンアップ追従¶
既存のプロジェクトを更新するには、Re:VIEW 4.1 をインストール後、プロジェクトフォルダ内で review-update コマンドを実行してください。
$ review-update
** review-update はプロジェクトを 4.1.0 に更新します **
プロジェクト/sty/review-base.sty は Re:VIEW バージョンのもの (/var/lib/gems/2.5.0/gems/review-4.1.0/templates/latex/review-jsbook/review-base.sty) で置き換えられます。本当に進めますか? [y]/n
プロジェクト/sty/review-jsbook.cls は Re:VIEW バージョンのもの (/var/lib/gems/2.5.0/gems/review-4.1.0/templates/latex/review-jsbook/review-jsbook.cls) で置き換えられます。本当に進めますか? [y]/n
完了しました。
続いて、リリースノートをベースに、新規に導入した機能や変更点について理由を挙げながら解説します。
新機能¶
表のセル区切りの文字を table_row_separator パラメータで変更できるようにしました¶
これまで Re:VIEW の表のセル区切りは「1つ以上の物理タブ」としていましたが、他のマークアップ言語で作った表をなるべくそのまま配置したいといったケースを考慮して、config.yml への設定パラメータを追加しました。
パラメータに指定可能な値は、tabs (1個以上のタブ、デフォルト)、singletab (1文字のタブ文字区切り)、spaces (1文字以上のスペースまたはタブ文字の区切り)、 verticalbar ("0個以上の空白 | 0個以上の空白" の区切り) です。
実際には spaces あるいは verticalbar あたりが使いそうなものでしょうか。ただ、スペース文字区切りにすると当然セル内にスペース文字を入れることができなくなる（厳密には @<embed>{ } を入れるといった方法もありますが）ので、設計思想的にはセルの区切りとしてはタブを使うことを推奨しています。
当初は任意の正規表現にしようかと思っていたのですが、「将来的に文法ジェネレータによるパーサに置き換えるときに任意表現が混ざると辛い」ということで限定しました。もっと別のものにしたいときには適宜 review-ext.rb を使って Builder#table_row_separator_regexp を置き換えればよいでしょう。
PDFMaker, EPUBMaker, WEBMaker, TEXTMaker, IDGXMLMaker: 全ファイルでなく変換対象ファイルを指定するための -y（または--only）オプションを追加しました¶
業務では類似の場面に特製の処理をしており、汎用実装は難しいかなと思っていたことなのですが、maker のロジックを眺めていたらわりと簡単にできそうなことに気付き、実装してみました。
review-pdfmaker -y ch01.re,ch02.re config.yml のように特定の re ファイルだけを指定してビルド対象にできます。rake の場合も REVIEW_PDF_OPTIONS="-y ch01.re,ch02.re" rake pdf というように環境変数経由で指定できます。.reは省略できるので、-y ch01,ch02 でも構いません。
章番号や相互参照などはそのまま保たれているので、大規模な書籍の中からある章を集中的に作業するときなどには特に便利に使えるでしょう。
config.yml のコメント行を含めないようにする --without-config-comment オプションを review-init に追加しました¶
Re:VIEW の機能拡張とともに config.yml の説明コメントがどんどん長くなっており、必須設定項目が見辛くなっています。
本質的な解決ではありませんが、ひとまず review-init コマンドにオプションを追加し、コメント行を除いた config.yml を書き出せるようにしました。
PDFMaker: pdfmaker セクションに use_original_image_size パラメータを新設しました。デフォルトでは //image, //indepimage, //imgtable で挿入する画像において、metrics の指定がないときには版面の横幅に合うよう拡縮しますが、use_original_image_size パラメータを true に設定すると、拡縮なしで原寸のまま配置します¶
なんでそもそもこうだったんだっけ、という気もしていますが、Re:VIEW の //image 等で入れた図版は版面の横幅に合わせるようになっており、メトリクスオプションの scale や width で版面横幅比に基づく拡縮をする、というのがデフォルトの挙動です。たぶん画像の解像度や貼り付けたときの大きさなどを気にしない人が多い、という想定からこうされたのかな……という推測をしています。
しかし業務案件においては、図版は紙面・版面サイズを考えた上で実寸で配置するのが普通です。実際私の業務案件でも、//image などのところは置き換えて、版面合わせなどをしないようにしていました。
最近は図版の作り方にも慣れたユーザーも増えてきたようなので、版面幅合わせをしないようにするパラメータを今回導入しました。
use_original_image_size: true
デフォルト値は null (横幅合わせをする) です。
非互換の変更¶
PDFMaker: config.yml の image_scale2width パラメータを、直下から pdfmaker セクションの下に属するように変更しました¶
影響がいろいろありそうなので少しずつですが、Maker 固有のものはその Maker のセクション下に移動していこうかなと思っています。
ただ、Maker のセクションにあるパラメータは、その Maker が呼ばれたときに、直下にあった既存のパラメータを上書きするという処理になっているので、実のところごっそり移動しても影響はほとんどないのかも、という気もしてきました。
バグ修正¶
PDFMaker: Re:VIEW 3 系のプロジェクトとの後方互換処理の誤りを修正しました¶
3 系のプロジェクトでの後方互換向けに covermatter の定義処理を加えたら、コンパイルエラーが発生するようになってしまっていました。
TeX力が足りないですね……。ロジックをちょっと書き換えました。
PDFMaker: review-jlreq を LuaLaTeX でコンパイルしたときのエラーを修正しました¶
LuaLaTeX だと PDF 系のメタ情報の書き方がいろいろ違っていました。まだ LuaLaTeX は実験程度だったので、実行検証が甘かったです。後述の「その他」にあるとおり、upLaTeX や LuaLaTeX でサンプルをビルドテストすることで、今後の互換性破壊を防ぐようにしました。
PDFMaker: 索引が目次に含まれない問題を修正しました¶
索引機能を有効にしたときに、TeX のコンパイルが1回不足していたため、索引はできたけれどもそれが目次には含まれていない、という現象が発生していました。索引があるときには都合2回のコンパイルを実行するように変更しました。
RSTBuilder: メソッドの引数の誤りで変換に失敗する問題を修正しました¶
4.0 でビルダまわりのリファクタリングをしたときに、RSTBuilder だけ漏れがあり、エラーになっていました。リソースの問題で、コアビルダ以外は見過ごしが発生しがちですね……。
IDGXMLBuilder: 表に関する警告を出すときの誤りを修正しました¶
4.0 でのリファクタリングで、警告処理部分に修正漏れがありました。警告が出ずにランタイムエラーが出て判明、というよくあるパターンです。
IDGXMLMaker: フィルタプログラムにエラーが発生したときの処理の誤りを修正しました¶
これも同じですね。
PDFMaker: media=ebook のときに、見出し等に @<code> や @<tt> のようなコード書体の命令を使うとビルドに失敗する問題を修正しました¶
4.0 でコード折り返しを入れて、見出しに入れることや目次にそれが入ることにも対応できていたのですが、media=ebook だと hyperref パッケージの機能でこれが PDF しおり (ブックマーク) に入ったときに展開に失敗してしまう、という問題です (しかもエラーがまたわかりにくい……)。
しおりに入る危なそうなマクロは、しおりの文字列を前処理する \pdfstringdefPreHook 内ですべて単なる文字列に置換する、という対処をとりました。
PDFMaker: MeCab がインストールされていないときにエラーになるのを警告に変更しました¶
もともと警告にしていたつもりだったのですが、エラーに遷移してしまっていたようです。
IDGXMLBuilder: //imgtable が正しく動作しなかったのを修正しました¶
4.0 のリファクタリングでの対処漏れでした。
PDFMaker: 索引が1つも登録されていない状態で makeindex を有効にするとエラーになるのを修正しました¶
普通は索引を入れてから有効にする、という手順をやっていたので気付いていませんでした。Maker の -y オプションを追加していたら発見したという経緯です。
PDFMaker: 説明箇条書き (:) の見出しに脚注を入れると消えてしまうのを修正しました¶
TeX の description の \item[] に展開したときに、[] 内でボックスが作られるので、そこに脚注のテキストを入れてしまうと脚注が出ないことになります。手元で使っていたときも説明箇条書き見出し内に脚注があるパターンはあったのですが、いずれも InDesign 案件で、この現象に気付いていませんでした。
とりあえず、説明箇条書き見出し内の脚注は footnotemark/footnotetext で対処するようにしました。
review-index: @<w> が見出しに使われているときにエラーになるのを修正しました¶
review-index は簡略化版の目次パーサを使っており、外部参照をするようなインラインがうまく動作しません。ひとまず @<w> について対処しました。
なお、review-vol も同じ目次パーサを使っており、こちらは今度はインライン命令がそのまま見出しに出てしまうという、またビミョーな実装状態になっています。
外部参照やインライン命令の解決をまじめにやるには、簡略化していない正規のパーサを使うように書き換える必要があり、将来TODOとしました (#1485)。
機能強化¶
PDFMaker: 問題報告の解析に役立つよう、提供する cls、sty ファイルについてバージョンを付けるようにしました¶
実行にはあまり関係がないことですが、エラービルドログにも示されるので、解析のときにはこういうのが役立ちますね。
Dockerfile を更新しました¶
デファクトスタンダードな vvakame/review の Dockerfile にほぼ準拠した形で更新しました。
IDGXMLMaker: フィルタプログラムの標準エラー出力を警告扱いで出力するようにしました¶
4.0 から導入した IDGXMLMaker ですが、フィルタプログラムの標準エラー出力を捨てていたので何が起きたのかよくわからない……という問題がありました (問題のないコンテンツとフィルタで使っていたのを移植したので、問題があったときのテストが不足)。エラー出力を拾うようにしました。
.gitignore ファイルに 〜-idgxml フォルダ を追加しました¶
IDGXMLMaker が作成する一時フォルダなので、コミット対象から外すようにしています。
//source 命令は全ビルダでオプションを省略できるようになりました¶
IDGXMLMaker だけ、//source のオプション省略ができませんでした。ほかに合わせて省略できるようにしました。
Ruby 2.7 をテスト対象に加えました¶
新たにリリースされた Ruby 2.7 もテスト対象にしました。互換性保持のため、まだ当分は固有の新機能を使うことはありません (Rubocop さんがまたうるさくなりそうですが……)。
word_files パラメータは配列で複数の単語 CSV ファイルを受け付けるようになりました¶
@<w> の展開文字列を列挙する word_files パラメータはこれまで単一ファイルしか指定できませんでした。共通+書籍固有 みたいに複数ファイルを指定したい、ということで、配列も指定できるようになりました。
同じ単語が複数ファイルに存在する場合は、後に指定にしたファイルの内容で上書きされます。
EPUBMaker: 見出しが1つもない .re ファイルについて警告を出すようにしました¶
EPUB においては、目次を内部で構築する都合上、ファイル内に見出しが必ず1つは必要です。
見出しを入れたくないときには、=[notoc] (目次に入れない) や =[nodisp] (目次に入れず表示もしない) を使用してください。
ドキュメント¶
奥付に関係する contact （連絡先）および colophon_order （項目の掲載順序）についてのドキュメントを設定ファイルサンプル config.yml.sample に追加しました¶
これらの機能は実は昔から機能としては用意していたのですが、ドキュメント化していませんでした。
やっぱり YAML ファイルの設定インターフェイスがほしいような……と思いつつ、コメント部分の保持などが難しいんですよねぇ。
quickstart.ja.md, quickstart.md を Re:VIEW 4 の内容に更新しました¶
3 系のままだったので更新しました。
サンプル syntax-book を更新しました¶
機能拡張したことなどに合わせて、ビルドテストを兼ねて厄介そうなパターンをいくつか追加しました。
README.md を更新しました¶
maker まわりや年数などの更新です。
図版のビルダ固有オプション :: の記法を format.ja.md, format.md に記載しました¶
これも機能は昔からあったけれどもドキュメント化していませんでした。使い方としてはこんな感じです。
//image[fig1][0.5倍にした図です][html::style="transform: scale(0.5);",latex::scale=0.5]
その他¶
Rubocop 0.78.0 の指摘に対応しました¶
いつものとおりです。Rubocop は新しいバージョンで機能が追加されるのはいいのですが、古いバージョンのパラメータをすぐ obsolete 化して非互換にしてしまうのはいかがなものか……。
LaTeX の実行環境がある場合、PDF のビルドテストをより厳密に実行するようにしました¶
サンプル: sample-book・syntax-book
クラス: review-jsbook・review-jlreq
コンパイラ: upLaTeX・LuaLaTeX
出力: print・ebook
という全組み合わせでサンプルのコンパイルを実行し、ビルドエラーがないことを確認できるテストユニットを加えました。CI には LaTeX 実行環境はないので無視されるだけですが、手元で勘に頼らずに全組み合わせを確認できるようになったので、今後の安全なスタイルファイル改善に役立つはずです。
ビルドテストを Travis CI から GitHub Actions に切り替えました¶
Travis CI が不安定でまた非常に遅くなるなどいろいろと開発の障害になっていたため、@takahashim さんにより GitHub Actions への切り替え作業が行われました。これまでの Travis CI だとごく些末な PR でもマージの判断に20分近くのビルド待ちを要していたのですが、今の GitHub Actions だと2分かからず完了するので、とても便利になりました。
IDGXMLBuilder のコードリストの処理をリファクタリングしました¶
IDGXML のコードリストまわりは歴史的経緯でほかのビルダよりもだいぶゴチャゴチャしていたのですが、いろいろと整理をしました。
サンプル syntax-book に入っていた review-ext.rb はもう不要なので削除しました¶
@<balloon> 命令が一部のビルダにない時代の互換性のために入れていたものですが、すでに全ビルダに入っているので削除しました。
IDGXMLMaker, TextMaker のテストを追加しました¶
サンプルドキュメントに対しての Maker 実行が成功するかどうかを確認するようにしました。
Index 関連の処理をリファクタリングしました¶
この Index は索引ではなくて、ChapterIndex とか ImageIndex などの採番管理のほうのクラスのことです。作りがごちゃごちゃしていたのがだいぶ整理されました。
なお、将来的に Index まわりは大きく変わる予定です。
現状は各ビルダが「参照された時点」で初めて相手先のファイルを見にいくという仕組みになっており、Index の種類によって何度も繰り返されています。これを今後 IndexBuilder というものを導入して、これがプロジェクト全体を最初に探索して Index を記録管理し、各ビルダはその記録に照会をかける、という目論見です。進捗については @takahashim さんいかがでしょう、ということで…… (#1384)。
jsclasses パッケージを 2020/02/02 バージョンに更新しました¶
新しい LaTeX2e での実装変更で、日本語フォントまわりにも影響が生じることになりました。新旧両方の LaTeX2e に対応した jsclasses のバージョンが発表されたため、Re:VIEW 内包のコピーも追従更新しました。Re:VIEW にとっては具体的には jsbook.cls が更新の対象です。
終わりに¶
今回の Re:VIEW 4.1 では、新機能をいくつか入れはしていますが、4.0 の不具合の修正やテストの拡充などの安定性を重視しています。バージョン4はもとより、バージョン2、3系を使い続けている方も、ぜひ導入してお使いいただければと思います！