FAQ - Re:VIEW の使い方について

FAQ(よくある質問と回答)のこのセクションは、Re:VIEW の使用方法のポインタや、使う上での注意点などをまとめています。


Re:VIEW を動かすにはどのような環境が必要ですか?

Ruby インタプリタ 2.1 以上がインストールされた OS 環境であれば、基本的に動作します。TeX を使った PDF 生成を行う場合は、別途日本語 TeX 環境のセットアップが必要です。

推奨環境は Linux(特に Debian GNU/Linux 安定版 または Ubuntu 安定版)、および macOS です。

Windows でも、ネイティブ環境でのセットアップ、WSL(Windows Subsystem for Linux)でのセットアップの報告があります。

Re:VIEW はどうやってインストールしたらよいですか?

Ruby をセットアップ済みであれば、ターミナル(またはコマンドプロンプト)から以下のコマンドでインストールできます。

gem install review

プレビュー版をインストールするには以下のようにします。

gem install review --pre

OS の所定の手続きに従って、gem の bin フォルダにパスを通してください。

Gemfile を使っている場合は、以下の行を Gemfile に追加して bundle コマンドを実行します。

gem 'review'

Ruby はどうやってインストールしたらよいですか?

手順は OS によって異なります。

Debian GNU/Linux、Ubuntu の場合は以下のようにしてインストールできます。

apt-get install ruby

TeX 環境など完全な環境構築としては、以下のようにするのもよいでしょう。

apt-get install --no-install-recommends texlive-lang-japanese texlive-fonts-recommended texlive-latex-extra texlive-generic-extra lmodern fonts-lmodern tex-gyre fonts-texgyre texlive-pictures ghostscript gsfonts zip ruby-zip ruby-nokogiri mecab ruby-mecab mecab-ipadic-utf8 poppler-data cm-super graphviz gnuplot python-blockdiag python-aafigure

★TODO:macOS、Windows。TeXと合わせて独立ページにしたほうがいい?

Docker のイメージはありますか?

以下でセットアップできます。

docker pull vvakame/review

利用方法などは以下を参照してください。

基礎的なガイダンスを記した公式のドキュメントはありますか?

Re:VIEW の入門書はありませんか?

バグを見つけました。どうしたらよいですか?

GitHub の issue ページ https://github.com/kmuto/review/issues までお寄せください(日本語または英語)。

プロジェクト(作業フォルダ)を作るにはどうしたらよいですか?

review-init コマンドを使います。

review-init プロジェクト名

デフォルトでは doc サブフォルダが作成され、Re:VIEW のドキュメントがコピーされますが、不要なときには --without-doc オプションを付けます。

review-init --without-doc プロジェクト名

Re:VIEW 3 以降では、任意の Web サーバーからプロジェクトに適用する各種ファイルをダウンロードすることもできます。Web サーバー側では、zip 形式で初期プロジェクトのうち上書きあるいは新規作成したいフォルダおよびファイルをまとめておきます(アーカイブURLにはローカルファイルを指定することもできます)。

review-init -p アーカイブURL プロジェクト名

プロジェクトにどのようにコンテンツを置いたらよいですか?

review-init コマンド実行後、プロジェクトには次のようなフォルダおよびファイルが置かれます。

  • プロジェクト名と同名の「.re」拡張子付きファイル:空の初期ファイル。ここに内容を入れていく(catalog.yml を変更すれば、このファイルでなくてもよい)
  • config.yml:書名など各種メタ情報の設定ファイル
  • catalog.yml:目次構成ファイル。re ファイルを列挙して順序を決定する
  • doc:ドキュメント
  • Rakefile:rake コマンド用のルールファイル
  • libs:Rakefile ルールの実体など
  • images:画像を置くフォルダ
  • layouts:LaTeX や HTML のテンプレートレイアウト
  • style.css:EPUB/HTML のスタイルシート
  • sty:LaTeX のスタイルファイル

基本的なコンテンツの置き方は次のようになります。

Re:VIEW がバージョンアップしたときに設定を追従するにはどうしたらよいですか?

Re:VIEW 3 から review-update というコマンドが導入されました。このコマンドをプロジェクトフォルダ内で実行すると、config.yml や sty フォルダなどを最新バージョンに適したものに更新できます。

re ファイルを書くのに専用のエディタは必要ですか?

re ファイルは命令を含めてすべてテキストで表現されるので、UTF-8 文字エンコーディングをサポートし、プレインテキスト形式での読み込み・書き出しが可能なテキストエディタであれば OS・ソフトウェアを問わず何でも利用できます。

ただ、Re:VIEW 固有の命令を記入したり色分け表示したりといった支援モードが提供されているエディタを使ったほうが、執筆および編集には便利でしょう。

re ファイルでの執筆・編集を支援するエディタにはどのようなものがありますか?

Visual Studio Code を使ったところ、^H などのおかしな文字が入り、PDF の生成に失敗します!

Re:VIEW 側の問題ではないのですが、Visual Studio Code(VS Code)でバックスペースの文字が入ってしまうことがあるようです。設定と拡張機能によって対処する手段が示されています。

図版はどこに置くのですか? また、どのような形式に対応していますか?

図版の画像ファイルは、images フォルダに配置します。さらにサブフォルダで分けることもできます。このときの探索順序は次のようになっています。

1. images/<builder>/<chapid>/<id>.<ext>
2. images/<builder>/<chapid>-<id>.<ext>
3. images/<builder>/<id>.<ext>
4. images/<chapid>/<id>.<ext>
5. images/<chapid>-<id>.<ext>
6. images/<id>.<ext>

どの画像形式に対応するかは、使用するビルダに依存します。

  • HTMLBuilder (EPUBMaker、WEBMaker)、MARKDOWNBuilder: .png、.jpg、.jpeg、.gif、.svg
  • LATEXBuilder (PDFMaker): .ai、.eps、.pdf、.tif、.tiff、.png、.bmp、.jpg、.jpeg、.gif
  • それ以外のビルダ: .ai、.psd、.eps、.pdf、.tif、.tiff、.png、.bmp、.jpg、.jpeg、.gif、.svg

Re:VIEW 3 以降では、大文字の混ざった拡張子にも対応します。Re:VIEW 2 では「PNG」など大文字のファイル拡張子の場合はヒットしないので注意してください。

config.yml ファイルはどのような役目を持っていますか?

config.yml は、コンテンツの内容を除く、ほとんどの設定および Re:VIEW の制御を司るメタ情報ファイルです。

このプロジェクトが準拠するRe:VIEW バージョン、書名、著者名、刊行日付、見出しへの採番レベル、目次や奥付の有無、デバッグ状態遷移の有無、カバー画像、スタイルシート、LaTeX の使用スタイルなど、多くの設定があります。詳細については、展開された config.yml ファイルのコメントの説明を参照してください。代表的な設定のみを抽出した、config.yml.sample-simple もあります。

catalog.yml ファイルはどのような役目を持っていますか?

PDF(review-pdfmaker)と EPUB(review-epubmaker)、あるいは印刷版 PDF と 電子版 PDF のように出力方法によって若干異なる設定にしたいと思います。重複する内容の yml ファイルを作らずに済みませんか?

inherit を使うと、ベースの yml ファイルを読み込みつつ、設定の追加や変更ができます。

たとえば config.yml で次のようにしていたとします。

 
date: 2018-7-21
 

ここから電子 PDF 版用だけ別の日付にしたいとして、config-epdf.yml などの適当なファイル名で、inherit を使って config.yml を取り込み、設定値を上書きします。

inherit: ["config.yml"]
date: 2018-9-27

この config-epdf.yml を使うには、review-pdfmaker config-epdf.yml のように指定して実行するか、REVIEW_CONFIG_FILE 環境変数に config-epdf.yml を設定した上で rake コマンドを実行します。

ある設定を消したいときには、値として null を指定します。

「図」「リスト」などの一部の固定文字列は locale.yml ファイルで変えられるようですが、どのように書いたらよいですか?

日本語用にはまず locale: ja という行を入れた後、Re:VIEW の lib/erview/i18n.yml の定義を元に置き換えるものを定義します。たとえば図は image、リストは list が文字列定義名です。

locale: ja
image: 
list: リスト

EPUB に変換するにはどうしたらよいですか?

以下のようにして変換します。

rake epub

以下でも可能です(rake epub は中でこのコマンドを実行しています)。

review-epubmaker config.yml

LaTeX を使った PDF に変換するにはどうしたらよいですか?

以下のようにして変換します。

rake pdf

以下でも可能です(rake pdf は中でこのコマンドを実行しています)。

review-pdfmaker config.yml

Web ページに変換するにはどうしたらよいですか?

以下のようにして変換します。

rake web

以下でも可能です(rake web は中でこのコマンドを実行しています)。

review-webmaker config.yml

プレインテキストに変換するにはどうしたらよいですか?

以下のようにして変換します。

rake text

以下でも可能です(rake text は中でこのコマンドを実行しています)。

review-textmaker config.yml

校正ツールにかけるなどの理由で一切装飾のないプレインテキストが必要なときには、以下のようにします。

rake plaintext

または

review-textmaker -n config.yml

Re:VIEW の命令や記法に馴染めそうもありません。Markdown で記述できませんか?

md2reviewがあります。gem としても配布されているので、以下のようにインストールできます。

gem install md2review

変換は以下のようにします。

md2review mdファイル > reファイル

命令体系が異なるため、変換結果の re ファイルの手直しは必要です。

Markdown に変換することはできますか?

Markdown については実験的な対応をしたビルダを収録しています。rake ルールや1コマンドで全部を変換するような仕組みはないのですが、以下のようにして変換できます。

review-compile --target=markdown reファイル > mdファイル

@<code> などの頻出するインライン命令だけ Markdown 的に記述することはできませんか?

Re:VIEW では、インラインの命令は一貫した @<命令>{〜}とし、見出しや箇条書き以外の例外はこれ以上増やさないことに決めています。インライン命令の入力の煩雑さについては、エディタ支援環境に頼ったほうがよいでしょう。

それでも Markdown 的なリテラル文字でのインライン記法を使いたいときには、Compiler#text の挙動を置き換えることで一応実現できます。

以下の review-ext.rb をプロジェクトフォルダに設置すると、テキスト内のバッククォートで囲まれた範囲を @<code> 命令に内部で置換します。

module ReVIEW
  module CompilerOverride
    def text(str)
      super(str.gsub(/\`(.+?)\`/, '@<code>$\1$'))
    end
  end

  class Compiler
    prepend CompilerOverride
  end
end

これは推奨するものではなく、あくまでも実装事例です。利用および改良にあたってのヒントを提示しておきます。

  • {} ではなく $$ で囲んでいるのは、{} の文字をリテラルに使う可能性を考えたためです。リテラルな $ を含んでしまう場合は、a. || にする、b. そう使いたいものだけ @<code> を普通に使う、c. 内容を読んで {}$$|| かのどれを使うかまじめに判断するよう実装する のいずれかの対策が必要です。
  • バッククォートのエスケープは考慮していません。まじめに実装するか、途中で改行して開始終了の対応関係が存在しないように見せるかといった対策になります。
  • より Markdown っぽく複数の置換をしたくなるかもしれませんが、素朴に置換を追加すると、置換済みのものにさらに別の置換を重ねてしまうことになります。まじめに実装するには、済んだものはいったん退避しておくなどの複雑な処理が必要です。

pandoc で Re:VIEW の書式はサポートされますか?

現時点では実装の報告はありません。

Sphinx で Re:VIEW の書式はサポートされますか?

LaTeX を使いたくないのですが、ほかの PDF 作成方法はありませんか?

たとえば InDesign を使う方法と、CSS 組版を使う方法があります。

  • InDesign:IDGXML 形式に変換し、レイアウトデザイン向けに調整した上で、Adobe InDesign で半自動 DTP を行う。
  • CSS組版:EPUB に変換し、EPUB をそのまま PDF 変換する(VersaType ConverterEPUB to PDF変換ツール など)か、EPUB の HTML を結合し(Re:VIEW 3 から review-epub2html というコマンドを用意しています)、Web ブラウザ上で整形したものを PDF として保存する(Vivliostyle.js など)。後者については @at_grandpa 氏による、ひとそろいセットの Re:VIEW+CSS組版 執筆環境構築 が公開されています。

これらのいずれも困難であったり、あるいは手作業工程の DTP オペレータに引き渡すということであれば、Re:VIEW 原稿をプレインテキストに変換(rake text)して手作業でページを制作していくほうが妥当かもしれません。

表のセル区切りは、なぜ空白文字ではなく「タブ1つ」なのですか?

コード断片など、セル内で空白を文字として扱いたい場合があるからです。

なお、この区切り方は lib/review/builder.rb の次のメソッドで実装しているので、review-ext.rb などを使ってビルダの挙動を上書き(たとえば /\s{2,}/ など)すれば、空白文字による区切りも可能です。

    def table(lines, id = nil, caption = nil)
        …
        rows.push(line.strip.split(/\t+/).map { |s| s.sub(/\A\./, '') })

表のセルを連結するにはどうしたらよいですか?

別フォルダにあるソースコードファイルの一部を原稿内に取り込みたいと思います。動的に取り込む方法はありますか?

catalog.yml での最小単位は章単位ですが、節や項に分けることはできませんか?

現時点の Re:VIEW の実装では、章よりも小さく分割した単位でファイルを扱うことはできません。

ただし、#@mapfile(ファイル名) 命令と review-preproc コマンドを使って、分割ファイルを結合することはできます。

たとえば章ファイルでは次のようにしておき、

= 章見出し
#@mapfile(section1.re)
#@end

#@mapfile(section2.re)
#@end

節の内容となる section1.re と section2.re ファイルを別に用意します。

section1.re の内容

== 節1
ABC

section2.re の内容

== 節2
DEF

この状態で rake preproc あるいは review-preproc --replace 章ファイル を実行すると、章ファイルが次のように更新されます。

= 章見出し
#@mapfile(section1.re)
== 節1
ABC
#@end

#@mapfile(section2.re)
== 節2
DEF
#@end

実行するたびに #@mapfile#@end の中身が書き換えられます。

★取り込まれた内容に表やブロックがある場合は#1248を含むRe:VIEW 3.1で対応

見出しの一覧を出力することはできますか?

Re:VIEW に対応した日本語校正ツールはありますか?

変換途中で独自の処理を挟むことはできますか?

Re:VIEW の標準の命令処理を変えたり、新たな命令を追加したりすることはできますか?

review-ext.rb というファイルを使い、Re:VIEW のロジックを上書きできます。

索引を入れるにはどうしたらよいですか?

@<idx>@<hidx> インライン命令を使って索引を埋め込むことができます。ただし、埋め込んだ索引の抽出・整列・表示は、現時点では、LaTeX のみでの対応です。

プロジェクト直下がたくさんの re ファイルだらけでごちゃごちゃしてしまいました。サブフォルダにまとめて置くことはできますか?

Re:VIEW 3.0 から、config.yml の contentdir パラメータを使って re ファイルを保持するサブフォルダを指定することができます。指定のサブフォルダに格納できるのは re ファイルのみで、画像はプロジェクトフォルダ直下にある images フォルダに入れることに変わりはありません。

UML やグラフの生成ツールから動的に生成して配置することはできますか?

//graph ブロック命令を使い、Graphviz、Gnuplot、Blockdiag、aafigure、PlantUML のソースを記述して画像を生成できます。

インライン命令内で入れ子ができません!

Re:VIEW の言語解析ロジック上、および記法の複雑化を避けるため、インライン命令は入れ子にすることはできません。

複合した結果になる新たな命令を review-ext.rb で定義する必要があるかもしれません。

インライン命令内で「}」を文字として表現したいときにはどうしたらよいですか?

\} と記述します。なお、{ のほうはインライン命令内でそのまま利用できます。

よって、たとえば {} という内容を入れたいときには、@<tt>{{\}} のようになります。

インライン命令内の最後で「\」を文字として表現したいときにはどうしたらよいですか?

インライン命令内の \ は通常そのまま文字として扱われますが、唯一、命令の末尾に入るときだけ \} という表現と区別が付けられなくなります。

  • インライン命令内の文字列が単一の \ だけであれば、\\ と表現し、@<tt>{\\} と記述できます。
  • 複数の文字からなる文字列(たとえば C:\Users\)の場合は \\ ではうまくいきません。フェンス記法を使い、@<tt>|C:\Users\| または @<tt>$C:\Users\$ とします。

@<m>命令を使って TeX 式を記述したところ、「}」がたくさん登場して都度「}」とするのが大変です。何か対策はありますか?

|| または $$ で囲む、フェンス記法があります。フェンス記法内では \} のエスケープは不要です(逆に、|| の場合は |$$ の場合は $ の文字は文字列内で使用できなくなります)。

@<m>|\frac{1}{2}| または @<m>$\frac{1}{2}$ のようになります。

Re:VIEW は夏時間に対応していますか?

Ruby ライブラリおよび OS の対応範囲での対応となります。実際のところ、Re:VIEW の実装で「現在時刻」に基づく処理が発生するのは、以下の2箇所のみです。

  • review-init 実行時に config.yml ファイルに書き出す、date: および history: のパラメータの日付の生成
  • review-epubmaker 実行時に OPF メタファイルに書き出される modified タイムスタンプの生成(バージョン 2.5 まではローカルタイム(ただし不適切な時差表記)、バージョン 3 以降は UTC)

前者は日付だけなので、OS の時刻が正しく設定されていれば夏時間は影響しません。後者は「Re:VIEW バージョン 2.5 までを使用し」「夏時間からの時刻の巻き戻しの前後で2回の EPUB ビルドをして」「その2つの EPUB をリーダー上で更新する」ときに「リーダーが modified タイムスタンプを見て更新の有無を判断する」場合に、更新がうまくいかないかもしれません。要するに、まず発生することはない、ということです。

段落を空行区切りではなく、改行をもって区切りにすることはできませんか?

Re:VIEW は空行を何らかの意味区切りとするという暗黙の想定をしており、この挙動を変更することは推奨しません。ただ、段落を判定しているのは各ビルダの paragraph メソッドなので、これを書き換えれば改行で区切りとすることは可能です。以下に LATEXBuilder の場合の挙動変更例を提示します。

module ReVIEW
  module LATEXBuilderOverride
    def paragraph(lines)
      # blank→結合→blankではなく、行ごとに前後blankを入れて段落化する
      lines.each {|line| blank; puts line; blank}
    end
  end
  class LATEXBuilder
    prepend LATEXBuilderOverride
  end
end