2018年07月01日
_ [reviewml] Re:VIEW 3.0.0preview1リリース
終盤の猛烈なtakahashimさんの追い上げで、Re:VIEW 3.0.0preview1を6月30日にリリースしました。
preview1という名のとおり、正式版とするにはいくぶん躊躇するところがあるため、Rubygems経由のインストールは「gem install review:3.0.0preview1」のようにバージョン指定する必要があります。→「gem install review --pre」を使うべき、というtakahashimさんのご指示がありました。gemのオプション、マジムズい。
ただ、近日にはこのpreview1をベースに正式版としていくことは決定していますので、まったく誰にも使っていただけないまま次期正式版になって問題が噴出というのは避けたいところです。ということで、クリティカルでない範囲で試して、問題があればissue報告をお願いします（たとえば入稿が来週なのに……みたいなときにやるべきではないですね！）。
特に、
- config.ymlで「review_version: 2.0」のプロジェクトバージョンになっているのに、TeX PDFの結果が変わってしまった
- 「review_version: 3.0」でのTeX PDFの新レイアウトを試してみたらおかしなことが起きた
- 以下の新機能や非互換の変更で奇妙な挙動がある
あたりは重点的に収集・解決したいところです。
3.0.0preview1のニュースリリースには多くの新機能・変更記載がありますが、端的でよくわからない部分もあるかと思いますので、ちょっと解説してみます。
contentdirパラメータで、reファイルをサブフォルダに配置してそのフォルダを指定できるようにしました
たとえば原稿reファイル群を「genko」サブフォルダに入れて、config.ymlで
contentdir: genko
と指定する、という感じです。注意点として、画像の置き場所であるimagesは作業フォルダ/genko/imagesに変わるわけではなく、作業フォルダ/imagesであり続けます。
//graph命令でPlantUMLをサポートしました
Java実装のPlantUMLというUML描画ツールからの生成をサポートしてみました。//graph内にPlntUMLの記法で書いておくと、EPUBやPDFのビルド時にPlantUMLで描画されて画像として埋め込まれます。
javaコマンドへのパスが通っていて、plantuml.jarが作業フォルダ直下にあることを前提としています。
CSV形式の単語ファイルから指定キーに対応する値を展開する、@<w>および@<wb>命令を追加しました
チームのコミッタでもある角さん謹製のもともと翻訳向けに使われていた命令を取り込みました。本来はもっといろいろ機能が細かかったのですが、使い方を選びすぎるきらいがあったので簡略化しています。
作業フォルダにCSV、たとえばwords.csvという名前で中身は
"LGPL","Lesser General Public License" "i18n","""i""nternationalizatio""n"""
のように書いておいて、config.ymlに
words_file: words.csv
としておくと、
@<w>{LGPL}, @<wb>{i18n}
というインライン記法で@<w>や@<wb>の内容が展開されます。wbは太字扱いになります。展開は文字列のエスケープをするくらいで多重展開をするわけではないので、あくまでも単純な文字列置換としての使い方に留めましょう。角さんは人名や判断の割れる語の展開に使っていることが多かったです。
words_fileは絶対パスで書くこともできるので、プロジェクトを横断して使うといった用途もできるでしょう。
catalog.ymlにある*.reファイルが存在しない場合エラーになるようにしました
とりあえず仮で書いておく、ができなくなったけどまぁ存在しないまま通ってしまうのも気持ち悪いか、という感じです。
LATEXBuilder: LaTeXでルビを表現できるようpxrubricaパッケージを読み込むようにしました
TeX PDFのみに関係します。これまでもルビについてはlayout.tex.erbでコメントで入れてはいましたが、pxrubricaパッケージは標準的なTeXLiveに収録されているので、後述する「バージョン3のTeXレイアウトを使う」場合はデフォルトで有効にしました（バージョン2設定のプロジェクトの場合は、引き続きlayout.tex.erbなりreviewmacro.styなりに書く必要があります）。
1点注意として、pxrubricaパッケージ自体にバージョンによる差異があり、Debian Stretch+TeXLive2016ベースのvvakame/review Dockerだと古いpxrubricaパッケージになります。ルビの配置の仕方のセットアップとして新しいpxrubricaなら「\rubysetup{J}」、古いpxrubricaなら「\rubysetup{g}」とすることでエラーを回避していますが、TeXLiveあるいはpxrubricaのバージョンによって若干の結果差異が生じることにはなります。
LATEXBuilder: 複数のLaTeXレイアウトファイルから選択できるようにしました
これもTeX PDFのみに関係します。今のところ、用意しているレイアウトは「review-jsbook（旧来互換性重視・jsbookベース）」「review-jlreq（実験実装、jlreqベース）」です。 review-initでプロジェクトを作成する際に「--latex-template review-jsbook」「--latex-template review-jlreq」のようにオプションを付けて指定します。何も付けない場合はデフォルトのreview-jsbookが使われます。
review-jsbookは2系への互換性保持用としての提供としてほぼ現状で固定させ、新たな改良は入れない予定です。今後jsbookベースの新たなものを作るとしても、別のレイアウト名を付けることになるでしょう。
review-jlreqは「日本語組版の要件」に従ったjlreq.clsというTeXレイアウトを使ったもので、古いTeXLiveだとこれがそもそも入っていません。GitHubからインストールするのが妥当です。
review-jlreqもあくまでも実験的なもので、まだ不具合・実装していない機能など多数あります。ただ、これまでのreview-jsbookで引きずっていた古い実装などを捨ててもう少しモダンなやり方にしてみるなどの挑戦があるので、独自のレイアウトを作る際の参考にはなるかもしれません。詳細はtemplates/latex/review-jlreq/README.mdを参照してみてください。
@<balloon>を標準サポートタグとしました
目的としては、コードに説明を加える（ふきだしなり線をひっぱるなり）ためのものです。もともとInDesignで紙面デザインに応じて上書き・スクリプトで調整を行うことを前提としており、TeXやHTMLにおいてもデフォルトの実装は単に「←〜」とするだけです。
後工程なりreview-ext.rbなりで上書きしていただければと思います。
LATEXBuilder: @<uchar>でUnicode文字を直接出力できるようにしました
というか、upLaTeXでuchar使うと余計に困ることになるので、コンパイラ設定を見て直に出すかを判定するようにしました。
しかし、upLaTeXだと文字によっては見た目が悪くなって
gsub('ç', "\\c{c}").gsub('č', '\\u{c}').gsub('í', "\\\\'{i}")
みたいな後処理が必要になることもありますね……。このあたりは必ずしも一括でそうすることが適正とは言えないこともあるので難しいです。
RakefileのオプションでCONFIG_FILEを上書きできるようにしました
リリース直前につっこまれた機能です。以下の環境変数で、右の既定値を置き換えられます。
- REVIEW_BOOK: book（book.pdfとかbook.epubになる）
- REVIEW_CONFIG_FILE: config.yml
- REVIEW_CATALOG_FILE: catalog.yml
- REVIEW_WEBROOT: webroot
特にconfig.ymlからinheritさせてconfig-epub.ymlとかconfig-ebook.ymlとか作っているときにわざわざRakefileにルール加えなくて済むのでよさそうです。
review_versionの値が3以上のときには、LaTeXの@<m>によるインラインの数式の前後にスペース文字を入れないようにしました
そもそもなんでこれ前後に入れていたんだっけ……という感じですが、旧来だと「@<m>{式}。」が「式<スペース>。」となってまずい、ということに気付きました。こういうケースでない限りは、ちょうどグルー調整になるのであまり変わった気がしないかもしれません。
HTMLビルダにおいて、//list, //listnumで識別子に基づくハイライト言語の自動検出をやめました（ハイライト言語は命令の3つめのオプションで指定してください）
ハイライトはもともといろいろと危険な実装だったのですが、list系だけ識別子から変にがんばってハイライタを決めるという実装になっているのは、メリットよりもデメリットが上回っていると判断しました。
個人的にはハイライトは@<b>などのインライン命令との相性がとても悪い（ハイライトしてから戻そうにも、インライン命令の文字がハイライタを混乱させるし、位置判定も困難）ので、何か抜本的な策はないものかと悩んでいます。
お仕事で作っているのはすごくがんばってこのあたりの処理をしたりしていますが、完全カスタムで汎用性がまったくないので取り込めない……。
LATEXBuilder: layout.tex.erbを整理・再構成しました
ここで「複数のLaTeXレイアウトファイルから選択できるようにしました」などでの話と絡んできますが、review_version: 3が指定されているときに、新しいlayout.tex.erbを使うようになりました。
正確には、review_versionが2以下の場合には互換性のためのreview/templates/latex-compat2/layout.tex.erbが使われ、3以上の場合は新しいreview/templates/latex/layout.tex.erbが使われます。
新しいlayout.tex.erbでは、config.ymlのパラメータを文字列あるいはフラグの形でTeXのマクロ表現に変えたもの（これはreview/templatex/latex/config.erbが処理）を取り込み、あとはすべてerbではなくそのTeXマクロに基づいて表示や条件分岐などを行います。
また、layout.tex.erb自体は表紙、大扉、前付、本文、付録、後付などに対応するマクロを呼び出すだけにして、マクロ実体はreview-jsbook等のレイアウト定義スタイルファイル側に委ねる形としました。これまでerbでベタにさまざまに条件分岐などをしていたのに比べると、layout.tex.erbはかなりすっきりした形態になっています。
\documentclass[<%= @documentclassoption %>]{<%= @documentclass %>}
<%= latex_config %>
<%- if @config['texstyle'] -%>
<%- [@config['texstyle']].flatten.each do |x| -%>
\usepackage{<%= x %>}
<%- end -%>
<%- end -%>
\begin{document}
%% coverpage
\ifdefined\reviewcoverpagecont
\reviewcoverpagecont
\fi
...
%% mainmatter hook
\ifdefined\reviewmainmatterhook
\reviewmainmatterhook
\fi
%% chapters body
\ifdefined\reviewchapterfiles
\reviewchapterfiles
\fi
...
\end{document}
この新しいlayout.tex.erbの仕掛けに合わせて、review-jsbookなどの新しいレイアウト群は以下のポリシーに従って作業フォルダのstyサブフォルダにコピーされるようになっています。
- reviewmacro.sty: 以下を束ねるスタイルファイル。よってconfig.ymlのほうは従来どおり「texstyle: reviewmacro」（あるいはtexstyle: ["reviewmacro"]）でよい
- review-base.sty: layout.tex.erbが要求するマクロに対応する基本定義
- review-style.sty: 見た目に対する定義（定義上review-base.styと区分しきれていないものあり）
- review-custom.sty: ユーザーが必要に応じて定義（空の内容）
今後新しいレイアウトを作る、Re:VIEW 3系に移植する、というときには、review-base、review-styleを参考にerbではなくTeXマクロを参照したり定義したりする形で作っていくことになります。LuaLaTeXなどupLaTeX以外のTeXエンジンを使うことが楽になったり、挙動書き換えが簡単になったりというメリットもあれば、TeXのマクロおよび挙動についての知識がそれなりに必要になるのでハードルが上がったデメリットもあるかとは思います。
config.ymlからの変換については単純文字列でよいのかどうか、情報渡しが不足していないかなど、検討の余地はありますので、レイアウト作成をしてみている方々の意見をお待ちしています。
なお、従来どおり、作業フォルダに独自のlayouts/layout.tex.erbを置くことで上書き可能です。erbが呼び出すのはlayout.tex.erbのみ、と覚えておいてください。
今のところスタイルファイルのコピーはreview-init時のみですが、既存プロジェクトの更新についても今後考えていくことにはなっています。とはいえ、作業フォルダにコピーしたというのはRe:VIEWのスタイルがいろいろ変わっていったとしても、ローカルの作業プロジェクトは固定しておけるという意図もあったりはするので、無闇な追従を勧めるものではない、となりそうです。
LATEXBuilder: LaTeXのコードリストをreviewlistblock環境で囲むようにしました
review_version: 3の場合に有効にしている機能です。今のところjsbook・jlreqのどちらのRe:VIEWレイアウトでも環境定義は空っぽにしている（つまり何もしない）のですが、今後の展開としてはたとえばキャプション付き/キャプションなしのリストがあったときに、その前後のアキを現状のような気味の悪いやり方をせずとも対処できるようになります。
LATEXBuilder: LaTeXのコードリスト環境をjlistingからplistingsパッケージに変更しました
日本語を含むリストのハイライトに、ライセンスがMITで使いやすいplistingsを採用しました。挙動的にはさほど変わった感じがしないかもしれません。
LATEXBuilder: PDF生成時にリンクの枠線について、標準では消すようにしました
技術書典で使う人が多くなって、紙印刷の用途がほとんどだなーということで、TeX PDF内のハイパーリンクの赤い囲みを消すようにしました。戻したい方はreview-custom.styに\hypersetupの定義を書いていくことになります。
review-jlreqのほうではdocumentclassのパラメータに書けるようにしたいなぁと妄想中。
LATEXBuilder: インライン文字装飾のLaTeXへの変換結果を\textbfではなく\reviewboldのように抽象化した名前にしました
これもreview_version: 3の場合に有効な機能です。review-jsbookのデフォルトでは\reviewbold→\textbfに展開しているので、今までと変わりません。たとえば
\renewcommand\reviewbold[1]{\textsc\textgt #1}
みたいにreview-custom.styで上書きできます。同様に\reviewit、reviewtt、reviewtti、reviewttb、reviewcodeなどがあります。
LATEXBuilder: LaTeXの表紙（coverパラメータ）と大扉（titlepageパラメータ）は独立した設定となりました
もともとEPUBでは独立だったんですが、TeXのlayout.tex.erbでcoverを指定しないとtitlepageも出ない、というロジックで書かれていたのをやっぱり独立させることにしました。実際の影響は少ない……と思いたい。
review-preproc: --finalオプションを削除しました
まぁ使わないよねということで。
LATEXBuilder: キャプションブロックの出力についてreviewminicolumnを使わずreviewnote等を使うようにしました
review_version: 3で有効化する機能です。
仕事だと全部再定義していたのであまり気にしていなかったけど、実際汎用のものを作ろうとするとやっぱり困りますよね。
Ruby 2.3以下で実行時のログ表示が冗長になるのを修正しました
loggerを実装いただいて以来、ちょっと冗長になったなーと思ってたのは、実はバグだったらしいという衝撃の真実。
Version 2.5.0で削除したusepackageパラメータを、互換性のために戻しました
クリーンアップはありがたいのですが、昔のlayout.tex.erbをローカルで使っている人の互換性を派手に壊してしまったのでrevertしました。
HTMLBuilder: @<m>や//texequation{...//}でのログ出力を抑制するようにしました
式作成に成功しても延々ビルドログが流れるのは邪魔なので抑制に。
LATEXBuilder: リストのキャプションが空の場合の出力を修正しました
キャプションが空なのになぜ指定するんだろう、と疑問だったのですが、自動補完だったり、ハイライトを使ったりすると余分な空行が入ってしまうという話。対策としては「空」の判定を変えただけ。
MeCabのロードパスを修正しました
Debian Stretchだと'MeCab'なのだけど、gemなどでは'mecab'という非互換がある模様。両方試すようにしました。
Windowsでも//graph命令が動作するようにしました
Re:VIEW開発検証用にWindowsマシンを買ったので、このほかにもいろいろ改良をしています。しかしファイルロックまわりが謎いところがありますな……。
画像ファイルやフォントファイルの拡張子が大文字・小文字どちらでも利用できるようにしました
なぜ大文字拡張子を付けるのか……。主張？
review-pdfmaker: pdfmakerで実行したコマンド情報を出力するようにしました
とりあえず「INFO: 〜」で出してみています。
IDGXMLBuilder: =[notoc]および=[nodisp]をサポートしました
なぜかこのビルダだけ実装を忘れていました。最近制作した書籍でエラーになって気付いたもの。
PDFMaker: psdファイルもコピーするようにしました
コピーはしますが、今のところまだ具体的にTeX PDF内に取り込むようにはしてません。なので、psdしかないとエラーになっちゃうと思います。graphicxpsdというパッケージと、ImageMagickかmacOSのsipsが必要。
具体的なアクションは、次のDebianバージョンでgraphicxpsd入りのTeXLiveが収録されるまで待つ、かもしれません。しかしどっちにしても--shell-escapeを付けないと動かないとなるとちょっと腰が引ける……。
PDFMaker: config.ymlのtexoptionsのデフォルト値を変更してLaTeX実行中に入力待ちにしないようにしました
これまではTeXコンパイル時にエラーになったときに即座に止まっていたのですが、「texoptions: -interaction=nonstopmode -file-line-error」にしたことで、ひとまず無停止で進めてエラーを返却、という挙動にしました。実際、入力待ちにしたところでユーザーにはどうしようもないですし。
LATEXBuilder: LaTeXなどのログメッセージを正常時には出力しないようにしました
これまでpdfmakerを実行するとひたすらビルドログが出ていたのですが、上記のいろいろな出力抑制と併せて、エラー時のみの出力となりました。
debugパラメータがtrueでも何も出さないのは若干わかりにくいかも……とは思いつつ、今の実装ロジックだと抑制有無をするのが難しそうだな（全然別の2つの方法を併記することになる）という印象です。
MARKDOWNBuilder: サポートするコマンドを追加しました
実際Re:VIEWからMarkdownを吐きたい、という人はどれだけいるのかというのはさておき……。dtpインライン命令のコメント挿入、noteなどの囲みやflushrightのdiv表現、sub・sup・u・kw・iconのインライン表現、//noindentのnoindent属性付きp化、かな。
ほとんどMarkdownではなくてHTMLなのではという気もして参ります。
image_finder.rb: シンボリックリンクされたディレクトリをサポートしました
imagesの探索にシンボリックリンクがあると駄目らしい（実ファイル・実ディレクトリを使っているのが普通なので気付かなかった）ので、その修正です。
Rakefileの依存関係にcatalog.ymlなどのファイルを追加しました
「rake」でビルドするときにreファイルだけでなくいろいろなファイルの更新を見てくれるようになりました。
//graph命令の各外部ツールについての説明を追加しました
PlantUMLのサポートを記していたらほかのものもいろいろ扱いが難しいな、ということでgraph命令がサポートしているツールや注意事項などをdoc/format.ja.mdおよびdoc/format.mdにまとめてみました。
@<w>, @<wb>命令の説明を追加しました
前掲のwとwbの説明もdoc/format.ja.mdおよびdoc/format.mdに記載しました。
LaTeXから生成するPDFの圧縮レベルオプション指定（-z 9、最大圧縮）をconfig.ymlのサンプルに記載しました
dvipdfmxで遅い場合は、サイズは大きくなるかもだけど値を小さくしてみると効果があるようです。
dvicommandパラメータの文字列でdvipdfmxクラスオプションを付けるかどうか判定するようにしました
ニュースリリースから漏れてたんですが、#1065の修正。
これまではdvipdfmxを常にドキュメントクラスオプションに明示指定したlayout.tex.erbでしたが、これだとそれは不必要なlualatexなどで困ります。そこで、新しいlayout.tex.erbではドキュメントクラスオプションは完全にconfig.ymlから取るようにしました。とはいえ、このままでは既存のupLaTeX系のプロジェクトでエラーが起きてしまいます。
そこで、config.ymlのdvicommandに「dvipdfmx」が含まれていたら「dvipdfmx」をドキュメントクラスオプションに加える、という挙動にしました（当然ながらすでにdocumentoptionにdvipdfmxがあったら重複しないように何もしません）。
逆に、lualatexなどでdvipdfmxを使いたくない、という場合はお手数ですが「dvicommand: null」などを設定してもらうことになります。
では、Re:VIEW 3.0.0preview1の使用報告、お待ちしております。