Re:VIEW Starterの新機能（2019年夏） #ReVIEW

（追記 2019-12-27: 2019年冬の新機能もご覧ください。）

はじめに

Re:VIEW Starterとは、主に書籍や技術同人誌を書くためのツールです。
初期設定がGUIで行えるので初心者でも楽に導入でき、最初から見栄えのいいデザインが用意されていて、かついろんなところに気が効いています。

Re:VIEW Starter (https://kauplan.org/reviewstarter/)

以前、Re:VIEW Starterを紹介したときは多くの方から反響をいただきました。
ありがとうございます。

技術系同人誌を書く人の味方「Re:VIEW Starter」の紹介
https://qiita.com/kauplan/items/d01e6e39a05be0b908a1

今回はその続編として、前回の紹介記事よりあとに実装された新機能を紹介します。
技術書典7も近いので¹、参考にしてください。

なお「Re:VIEW Starter」はちょっと長いので、以降では「Starter」と称しています。

等幅フォントをGUIで選択可能に

プログラムコードやターミナルの表示で使う等幅フォントを、GUIで選べるようになりました。

等幅フォントをプレビューしながら選べます。
各フォントの特徴も画面で簡単に説明しています。
プログラムコードとターミナルでそれぞれ別の等幅フォントを指定できます。

GUIで等幅フォントを選ぶ画面：

Tipsですが、Inconsolataフォントで「文字列をさらに狭める」というオプションを選ぶと、フォント幅が狭くなって1行にたくさん詰め込めます。
また半角文字と全角文字の幅がだいたい1:2になるので（厳密な1:2ではない）、出力結果などに使うといいでしょう。

もしプロジェクトをダウンロードしたあとに等幅フォントを変更したいなら、設定ファイル config-starter.yml の項目「program_ttfont:」や「terminal_ttfont:」を変更してください。

テキストの横に画像を表示する

テキストの横に画像を表示するブロックコマンド「//sideimage」を用意しました。
著者紹介でTwitterアイコンとともに使うといいでしょう。

//sideimage[tw-icon][20mm][side=L,sep=7mm,border=on]{
//noindent
@<strong>{カウプラン機関極東支部}

 * @<href>{https://twitter.com/_kauplan/, @_kauplan}
 * @<href>{https://kauplan.org/}
 * 技術書典7新刊「わかりみSQL」出します！@<br>{}
   レビュアーも募集中！

//}

表示例：

ブロックの中には箇条書きやプログラムコードを入れられますが、「途中で改ページされない」「画像下へのテキストの回り込みはできない」「脚注が使えない」という制限があります²。
詳しくはドキュメントを参照してください。

プログラムコードを枠線で囲む

プログラムコードを枠線で囲むオプションを用意しました。
プログラムコードが途中で改ページされるとき、枠線があったほうが少し読みやすくなります。

この機能を有効化するには、config-starter.ymlで「program_border: true」を設定してください。

節(Section)ごとに改ページする

節 (Section) ごとに改ページする機能を用意しました。
初心者向けの入門書だと、節ごとに改ページするのはよく見かけます。

設定方法は、config-starter.ymlで「section_newpage: true」を指定してください。

ただし、章ごとの最初の節では改ページしません。
これは意図した挙動であり、バグではないので注意してください。

節や項がページ先頭なら余白を入れない

節 (Section) や項 (Subsection) がページ先頭にきた場合、従来はタイトルの上に余白が入っていました。
しかしページ先頭の場合は、この余白はなくても問題ないはずです。

なので、Starterではデフォルトでこの余白を入れないようにしました。
config-starter.ymlの「section_notopmargin: true」をfalseにすると、入るように変更できます。

節や項がページ最下部で改ページされるのを防ぐ

LaTeXでは、ページ最下部の段落が最初の1行のみになるのを嫌います。
もしそうなりそうになったら、段落の直前で改ページします。

このせいで、節 (Section) や項 (Subsection) のタイトルが、十分なスペースがありそうなのに改ページされてしまうことがあります。

Starterでは、ページ最下部の段落が最初の1行のみになるのを許しています。
そのため、節や項のタイトルがページ最下部にきても改ページされず、余計なスペースが空かないようになっています。

この設定は、config-starter.ymlの「page_clubline: true」³で変更できます。

設定ファイル「config-starter.yml」を追加

Re:VIEW Starter独自の設定ファイル「config-starter.yml」を用意しました（これはRe:VIEWの設定ファイルconfig.ymlとは別です）。
今まではプロジェクト作成時にしか選択できなかった設定が、プロジェクト作成後も config-starter.yml で簡単に設定できるようになりました。

たとえば以下のような項目が設定できます。

chapter_decoration … 章 (Chapter) タイトルの装飾
chapter_align: … 章タイトルの左寄せ/右寄せ/中央揃え
chapter_oneline: … 章番号と章タイトルとの間で改行するかどうか
section_newpage: … 節 (Section) ごとに改ページする
section_decoration: … 節 (Section) タイトルの装飾
subsection_decoration: … 項 (Subsection) タイトルの装飾
program_fontsize: … プログラムコードのフォントサイズ
terminal_fontsize: … ターミナルのフォントサイズ
program_ttfont: … プログラムコードの等幅フォント
terminal_ttfont: … ターミナルの等幅フォント
image_position: … 画像位置に後続のテキストを流し込む

詳しくはconfig-starter.ymlの中を見てください。

キャプション直後の改ページを防ぐパラメータを導入

プログラムコードやターミナルには、キャプション（説明書き）がつけられます。
このキャプションの直後で改ページされると、キャプションとプログラムコードが別々のページになってしまうため、読みやすさが損なわれます。

キャプション直後で改ページされた例：

Starterではこの問題を防ぐよう対策をしていましたが、設定値に甘さがあったため、防ぎきれてはいませんでした。
現在は何度も実験をして設定値を決めたため、以前よりはずっと発生しにくくなっています。

それでも完全に防ぐのは難しいです。
これはフォントや行間などに依存するので、どの書籍でも通用するような完璧な設定値はありません。

そこで、この設定値を各自で調整できるようにしました。
config-starter.ymlで「caption_needspace: 4.8zh」という箇所を調整してください。

キャプション直後の改ページが発生するなら、この値を少し増やしてください。
十分なスペースがあるのに改ページされるなら、この値を少し減らしてください。

なおLaTeXでは、プログラムコードが1行だけで改ページされることはないらしく、そうなりそうになったらプログラムコードの前で全体を改ページするようです。
この挙動を変更する方法を知ってる人がいたら教えてください⁴。

フォントサイズを変更するコマンド

テキストのフォントサイズを変更するインラインコマンドを用意しました。

@<small>{...} … 文字を小さくする
@<xsmall>{...} … 文字をより小さくする
@<xxsmall>{...} … 文字をもっと小さくする
@<large>{...} … 文字を大きくする
@<xlarge>{...} … 文字をより大きくする
@<xxlarge>{...} … 文字をもっと大きくする

またテキストを強調する@<strong>{}の派生コマンドとして、フォントサイズを大きくするものを用意しました。

@<xstrong> … 文字を大きくする
@<xxstrong> … 文字をもっと大きくする

どのくらい小さくまたは大きくなるかは、次の画像を参考にしてください。

テキストを目立たせないための`@<weak>{}`

テキストを目立たせる「@<strong>{}」とは逆に、目立たせないための「@<weak>{}」を用意しました。
プログラムコードのおまじないを目立たせたくないときに使ってください。

ターミナルのカーソルを表示する

ターミナルのカーソルを表す「@<cursor>{}」を用意しました。

たとえば次の例では、「f」にカーソルが載っていることを表します。

//terminal{
function fib(n) {
  return n <= 1 ? n : @<cursor>{f}ib(n-1) : fib(n-2);
}
~
~
"fib.js" 3L, 74C written

表示例：

なおこの機能は、とある利用者からの要望により実装しました。
すべての要望に答えられるとは限りませんが、他にも要望があれば教えて下さい。
できる範囲で対応します。

折返しが右端まで達するようにする

Starterでは、プログラムコードの長い行を自動的に折り返してくれ、また折返し記号もつけてくれます。

しかし、一見すると右端まで到達してないのに折り返しているように見えることがあります。
たとえば次の例だと、もう1文字入るように見えませんか？

このような場合は、プログラムコードの表示幅をほんの少しだけ広げると、折返しが右端まで到達するようになります。
具体的にはstarter-config.ymlに「program_widen: 0.3mm」と設定すると、次の例のように右端まで達するようになりました。

ここで「program_widen: 0.3mm」という値は各自で調整してください。
1mmなんて大きな値は必要ないはずで、せいぜい0.5mmとかでいいはずです。

コンパイル時間を短縮するドラフトモードを実装

画像やスクリーンショットを多用する書籍だと、コンパイルに時間がかかります。
印刷用に高解像度の画像を使った場合はなおさらです。

そこでStarterでは、画像を枠線だけで表示する「ドラフトモード」を用意しました。
このモードでは画像を表示するかわりに枠線を表示するので、コンパイルが非常に速くなります（正確にいうと、LaTeXのコンパイル時間は変わらないけどそのあとのPDF生成が速くなります）。

ドラフトモードにするには、config-starter.yml で「draft: true」を設定するか、または環境変数「$STARTER_DRAFT」に何らかの値を入れてください。

### ドラフトモードにしてPDFを生成する
$ export STARTER_DRAFT=1  # ドラフトモードをonにする
$ rake pdf

$ unset STARTER_DRAFT     # ドラフトモードをoffにする

またドラフトモードの場合でも、//image[][][draft=off] のように指定すると、その画像はドラフトモードにならず通常通り表示されます。

ドラフトモードであっても、この画像↓は画像として表示する。
//image[ファイル名][画像の説明][scale=0.8,draft=off]

この機能は、締め切りが迫ったときには大活躍します。
今のうちに試してみるといいでしょう。

印刷用PDFとダウンロード用PDFを切り替える

印刷用PDFとダウンロード用PDFとで、仕様を少し変えたいことがあります。

印刷用PDFは白黒だけど、ダウンロード用PDFはカラーにしたい。
印刷用PDFは本文を見開きの外側に少し寄せるけど、ダウンロード用は本文をページ中央に置く。
印刷用PDFはリンク機能をオフにするけど、ダウンロード用PDFではオンにしたい。

このようなときは、環境変数「$STARTER_TARGET」を設定することで印刷用とダウンロード用を切り替えられます。

環境変数の値が「pbook」なら印刷用
環境変数の値が「ebook」ならダウンロード用
環境変数が空または未設定なら、config-starter.ymlの「target:」に従う

コンパイル方法：

### 印刷用PDFを生成
$ rake pdf   # または STARTER_TARGET=pbook rake pdf

### ダウンロード用PDFを生成
$ STARTER_TARGET=ebook rake pdf

この値は、LaTeXのスタイルファイルでは「\starter@target」で参照できます。
たとえばLaTeXのスタイルシート sty/starter.sty では、ダウンロード用PDFではカラーを使うようになっています。

%%% \starter@target を調べて各種変数を設定する
\iffalse
\else\ifstreq{\starter@target}{pbook}    % pbook (printing book) なら
  \def\starter@colormode{mono}           %   白黒
\else\ifstreq{\starter@target}{ebook}    % ebook (electric book) なら
  \def\starter@colormode{rgb}            %   カラー (RGB)
  %\def\starter@colormode{cmyk}          %   カラー (CMYK)
\else                                    % それら以外なら
  \def\starter@colormode{mono}           %   白黒
\fi

また sty/mytextsize.sty では、印刷用の場合だけ本文を見開きの外側に寄せています。

%% 奇数・偶数ページで余白幅を変える場合
%% （ただし pbook (printing book) の場合だけ）
\newcommand\if@pbook{         % \starter@target の値が pbook かどうかを調べる
  \def\@tempa{pbook}
  \ifx\starter@target\@tempa  % \starter@target は layouts/layout.tex.erb の先頭で定義される
}
\if@pbook
  \addtolength{\oddsidemargin}{1.5zw}   % 奇数ページで1.5文字分広げる
  \addtolength{\evensidemargin}{-1.5zw} % 偶数ページで1.5文字分狭める
\fi

LaTeXスタイルファイルから環境変数を参照する

LaTeXのスタイルファイルの中から、環境変数を参照できるようになりました。
とはいっても、変数名が「STARTER_」で始まる環境変数だけが対象です。

たとえば環境変数 $STARTER_FOO_BAR を設定すると、LaTeXのスタイルファイルでは「\STARTER@FOO@BAR」として参照できます。
もうお分かりだと思いますが、環境変数の「_」を「@」に変換した名前になります。

使い道は特に限定してないので、自由に使ってください。

細かなバグフィックス

Starterにもいくつかバグがあったので、修正しています。

たとえば、複数のプログラムコードを並べたときに2つめ以降のマージンが広がってしまうバグがありました。

これは解決策が長らく分からなかったのですが、TeXには直前の余白の幅や高さを表す「\lastskip」⁵なる素敵な機能があることが分かったため、解決することができました。
つまり直前に余白があれば、その分を差し引いて余白を追加しています。
CSSなら自動でやってくれることを手動でやっているわけですが、解決できてほんとよかった。

(La)TeXはちっとも思い通りに動いてくれないのでクソゲー感満載ですけど、諦めかけたころになってこういう機能が見つかったりするので、ムリゲーではないんですよね。
こういうところがまた腹が立ちます。

他にバグがあれば、教えてもらえると助かります。

（追記）プログラムコードの文字サイズを変更する

（追記 2019-08-27：紹介し忘れていたので追加しました。）

プログラムコードやターミナルの表示において、「ここだけ文字を小さくして長い行を収めたいなー」と思ったことはありませんか？
Starterならそれができます。

//list[][][] と //terminal[][][] の第3引数に、フォントサイズを指定できるようになりました。

fontsize=small … 小さくする（すでに小さくしている場合は影響なし）
fontsize=x-small … もっと小さくする
fontsize=xx-small … もっともっと小さくする（通常は使うべきではない）

表示例：

この例では //list を使っていますが、//terminal でも使えます。

実装が間に合わなかったもの

前回の記事では、「今後の計画」として「インライン命令の入れ子」の実装を挙げていました。
しかし残念ながら、技術書典7には間に合いそうにありません。

実は仮実装をしてみたのですが、Re:VIEWとの互換性をなるべくとりたいのに、Re:VIEWの細かい仕様が把握できないため、導入に踏み切れないのです。

Re:VIEWのインライン命令の仕様を把握するためにソースコードを読んでみたのですが、こう言っていいか分かりませんが、僕の頭では理解しかねるコードでした。
どうやら「@<x>{...}」と「@<x>$...$」と「@<x>|...|」の3つの書き方に対応するために複雑になっているようで、一時的にnull文字で置き換えてまた元に戻すとか、そんな感じになっていて正直理解できませんでした。

そういうわけで、Re:VIEWにおけるインライン命令の細かい仕様が分からないため、実装にはまだ時間が必要です。
僕としてはとても残念です。
期待していた方、申し訳ありません。

ユーザの感想

ユーザから感想をいただきました。ありがとうございます。
(https://twitter.com/konosumi/status/1162615784234860544)

今回の変更点かなり良かったです。技術書典6の頃から使い始めてるのですが、何より余計なことを考えなくて済むので、執筆とRe:VIEWの主要な文法を覚えることだけに集中すればRe:VIEW Starterで本ができます。 https://t.co/bZsAnFNtTO
— このすみ@技術書典7 (@konosumi) August 17, 2019

他にも感想お待ちしています。

まとめ

LaTeXの苦しみとRe:VIEWの機能不足は、Re:VIEW Starterが受けとめます。
皆さんは原稿を書くことに集中して、すてきな書籍や技術同人誌を生み出してください。

ご意見、ご要望、バグ報告はハッシュタグ #reviewstarter をつけてツイートしてください。

おまけ

こんな記事も書いてるので、よければ見てください。

はじめての表紙デザイン（技術系同人誌向け）
https://qiita.com/kauplan/items/2b2f1acbd8efe76c490b
PDFにノンブルをつける「PDFOperation」
https://qiita.com/kauplan/items/cf17e8d8446d70b5e973
Re:VIEW 2.5での改善点と残っている問題点
https://qiita.com/kauplan/items/5068e2a0da7847c2014e

原稿執筆時点である2019年8月のこと。 ↩
これらの制限は内部でLaTeXのminipage環境を使っているせいです。よい解決方法があれば教えて下さい。 ↩
「clubline」とは、ページ最後の段落が最初の1行だけになっていることを表す言葉だそうです。 ↩
\clubpenalty を 0 にすればいいかと思いましたが、試した限りはうまくいきませんでした。 ↩
実際には \addvskip を使っています。また \lastskip はLaTeXの本だと載ってないようで、TeXの本には載ってました。LaTeXじゃ足りなくてTeXにまで手を出さないといけないの、つらい。 ↩

Re:VIEW Starterの新機能（2019年夏）

はじめに

等幅フォントをGUIで選択可能に

テキストの横に画像を表示する

プログラムコードを枠線で囲む

節(Section)ごとに改ページする

節や項がページ先頭なら余白を入れない

節や項がページ最下部で改ページされるのを防ぐ

設定ファイル「config-starter.yml」を追加

キャプション直後の改ページを防ぐパラメータを導入

フォントサイズを変更するコマンド

テキストを目立たせないための@<weak>{}

ターミナルのカーソルを表示する

折返しが右端まで達するようにする

コンパイル時間を短縮するドラフトモードを実装

印刷用PDFとダウンロード用PDFを切り替える

LaTeXスタイルファイルから環境変数を参照する

細かなバグフィックス

（追記）プログラムコードの文字サイズを変更する

実装が間に合わなかったもの

ユーザの感想

まとめ

おまけ

テキストを目立たせないための`@<weak>{}`