review 3.2.0 → 5.1.0

data/doc/makeindex.ja.md

@@ -35,7 +35,7 @@ re ファイル内に、`@<idx>` または `@<hidx>` インラインタグを使
 
 [索引]
 ひ
-表示もする索引です....1
+表示もする索引....1
 ```
 
 ```
@@ -50,7 +50,7 @@ re ファイル内に、`@<idx>` または `@<hidx>` インラインタグを使
 
 
 ひ
- 表示もする索引です....1
+ 表示しない索引....1
 ```
 
 ## 読み辞書

data/doc/pdfmaker.ja.md

@@ -109,6 +109,48 @@ Re:VIEW 3.0 から review-jlreq.cls という別のクラスファイルも用
 
 その他の詳細な設定については、sty フォルダにある README.md を参照してください。
 
+### カスタムパラメータの引き渡し
+
+技術的な都合で、config.yml の YAML 設定から TeX のマクロへの変換はすべての設定について行われるわけではなく、ごく限られた値のみに制限しています。これは Re:VIEW 内部の `config.erb` ( https://github.com/kmuto/review/blob/master/templates/latex/config.erb ) の ERB スクリプトによって処理されており、この挙動を変更することは許容していません。
+
+任意の YAML 設定を TeX に引き渡すには、`config.erb` と同様に YAML から TeX への変換を行う固有の ERB スクリプトを作成して配置します。このためには、プロジェクトフォルダに `layouts` フォルダを作成し、そこに固有の ERB スクリプトを `config-local.tex.erb` という名前で置きます。
+
+`config-local.tex.erb` は `config.erb` の評価・埋め込みの後、評価・埋め込みされます。
+
+config.yml を次のようにして、これを TeX に渡したいとします。
+
+```
+mycustom:
+  mystring: HELLO_#1
+  mybool: true
+```
+
+`layouts/config-local.tex.erb` はたとえば次のようになります。
+
+```
+\def\mystring{<%= escape(@config['mycustom']['mystring']) %>}
+<%- if @config['mycustom']['mybool'] -%>
+\def\mybool{true}
+<%- end -%>
+```
+
+次のように展開されます。
+```
+ …
+\makeatother
+%% BEGIN: config-local.tex.erb
+\def\mystring{HELLO\textunderscore{}\#1}
+\def\mybool{true}
+%% END: config-local.tex.erb
+
+\usepackage{reviewmacro}
+ …
+```
+
+こうして定義されたマクロを sty ファイルなどで参照します。
+
+なお、ERB での YAML 解析、および TeX マクロの記述において誤りがあると、極めてわかりにくいエラーになることがあります。`--debug` オプション付きで実行して展開された `__REVIEW_BOOK__.tex` を確認して原因を調査するのがよいでしょう。
+
 ## Re:VIEW 2.0 以前の情報
 
 ### upLaTeX について
@@ -121,7 +163,7 @@ LaTeX コンパイラコマンドおよびオプションについて、Re:VIEW
 
 ```yaml
 texcommand: uplatex
-texoptions: "-interaction=nonstopmode -file-line-error"
+texoptions: "-interaction=nonstopmode -file-line-error -halt-on-error"
 texdocumentclass: ["jsbook", "uplatex,oneside"]
 dvicommand: dvipdfmx
 dvioptions: "-d 5"

data/doc/pdfmaker.md

@@ -84,6 +84,47 @@ Since Re:VIEW 3.0, review-jlreq.cls is also provided. This class file extends jl
 
 `review-init --latex-template=review-jlreq` command copies the review-jlreq.cls set to `sty` folder.
 
+### Handing over custom parameters
+
+For technical reasons, only a small part of the YAML parameters in config.yml is converted to TeX macros. Re:VIEW's internal `config.erb` ( https://github.com/ kmuto/review/blob/master/templates/latex/ config.erb ) ERB script manages this. You cannot change this script.
+
+If you want to give YAML parameters to TeX, you can use your own ERB script that do the YAML to TeX conversion. This is done by creating `layouts/config-local.tex.erb` in the project folder.
+
+After evaluation and embedding of `config.erb`, `config-local.tex. erb` will be evaluated and embedded as well. For example,
+
+`config.yml`:
+
+```
+mycustom:
+  mystring: HELLO_#1
+  mybool: true
+```
+
+`layouts/config-local.tex.erb`:
+
+```
+\def\mystring{<%= escape(@config['mycustom']['mystring']) %>}
+<%- if @config['mycustom']['mybool'] -%>
+\def\mybool{true}
+<%- end -%>
+```
+
+will be parsed:
+
+```
+ …
+\makeatother
+%% BEGIN: config-local.tex.erb
+\def\mystring{HELLO\textunderscore{}\#1}
+\def\mybool{true}
+%% END: config-local.tex.erb
+
+\usepackage{reviewmacro}
+ …
+```
+
+Refer to these macros in your sty file.
+
 ## Important Changes about LaTeX in Re:VIEW 2.0
 
 * Default LaTeX compiler is upLaTeX, not pLaTeX.
@@ -100,7 +141,7 @@ Default settings of Re:VIEW is below:
 
 ```yaml
 texcommand: uplatex
-texoptions: "-interaction=nonstopmode -file-line-error"
+texoptions: "-interaction=nonstopmode -file-line-error -halt-on-error"
 texdocumentclass: ["review-jsbook", "uplatex,twoside"]
 dvicommand: dvipdfmx
 dvioptions: "-d 5"

data/doc/quickstart.ja.md

@@ -8,11 +8,11 @@ Re:VIEW は GNU Lesser General Public License Version 2.1 に基づいて配布
 
 このドキュメントでは、Re:VIEW のセットアップから変換の例までを簡単に説明します。
 
-このドキュメントは、Re:VIEW 3.0 に基づいています。
+このドキュメントは、Re:VIEW 5.1 に基づいています。
 
 ## セットアップ
 
-Re:VIEW は Ruby 言語で記述されており、Linux/Unix 互換システムで動作します。macOS および Windows Cygwin でも動作可能です。Ruby gem あるいは Git のいずれかを使ってダウンロード・展開します。
+Re:VIEW は Ruby 言語で記述されており、Linux/Unix 互換システムで動作します。macOS および Windows でも動作可能です。Ruby gem あるいは Git のいずれかを使ってダウンロード・展開します。
 
 なお、Re:VIEW フォーマット自体は文字で表現されたタグが付いている以外は単なるテキストファイルなので、エディタ、OS については UTF-8 文字エンコーディングさえ使用できれば制限はありません。
 
@@ -34,7 +34,7 @@ Ruby gem の bin ディレクトリにパスを通すようにしておいてく
 $ gem update review
 ```
 
-Gemfile を使っている場合は、以下の行を Gemfile に追加して、`bundle`コマンドを実行します。
+Gemfile を使っている場合は、以下の行を Gemfile に追加して、`bundle` コマンドを実行します。
 
 ```Gemfile
 gem 'review'
@@ -58,29 +58,37 @@ review というディレクトリに展開されるので、review/bin にパ
 $ git pull
 ```
 
-## Re:VIEW ドキュメントの作成
+## Re:VIEW プロジェクトの作成
 
 ### 雛型の作成
-review-init コマンドを使って、雛型となる作業フォルダを作成できます。
+review-init コマンドを使って、雛型となるプロジェクトフォルダを作成できます。
 
 ```
-$ review-init ドキュメント名
+$ review-init プロジェクト名
 ```
 
-これで指定のドキュメント名のフォルダが用意され、中に次のようなファイルが置かれます。
+TeX を利用した PDF 作成を目的としているならば、雛型の作成時に、Web ブラウザによるウィザードモードで基本版面設計を行うことができます。これには `-w` オプションを付けます。
 
- * ドキュメント名を冠した「.re」拡張子を持つファイル（Re:VIEW フォーマットテキストファイル）
+```
+$ review-init -w プロジェクト名
+```
+
+「http://localhost:18000」に Web ブラウザでアクセスし、文字数×行数および余白を調整できます。
+
+これで指定のプロジェクト名のフォルダが用意され、中に次のようなファイルが置かれます。
+
+ * プロジェクト名を冠した「.re」拡張子を持つファイル（Re:VIEW フォーマットテキストファイル）
  * config.yml : 設定ファイル
+ * config-ebook.yml : 電子ブック用設定ファイル（ウィザードモード使用時）
  * catalog.yml : カタログファイル（目次構成）
  * Rakefile : rake コマンドのルールファイル
  * images : 画像の配置フォルダ
- * layouts : レイアウトファイルの配置フォルダ
  * style.css : サンプルスタイルシート
  * sty : スタイルファイル配置フォルダ（TeX 用）
  * doc : 本ドキュメントを含む使い方のドキュメント
  * lib : 主に rake コマンドの詳細ルールファイル
 
-review-init コマンドによらず、独自に作業フォルダを作成してもかまいません。
+review-init コマンドによらず、独自にプロジェクトフォルダを作成してもかまいません。
 
 ### Re:VIEW テキストの作成と変換
 
@@ -115,34 +123,53 @@ review-init コマンドによらず、独自に作業フォルダを作成し
 
 テキストファイルの文字エンコーディングには、UTF-8 を使用してください。
 
-### PDF 化と EPUB 化、プレインテキスト化
+### PDF 化と EPUB 化、プレインテキスト化、XML 化
+
+review-*maker コマンドで一括して変換作成ができます。
 
-review-pdfmaker コマンドで PDF ブックの作成、review-epubmaker コマンドで EPUB ファイルの作成、review-textmaker コマンドでプレインテキストの作成ができます。
+- review-pdfmaker コマンド：PDF ブックの作成
+- review-epubmaker コマンド：EPUB ファイルの作成
+- review-textmaker コマンド：プレインテキストの作成
+- review-idgxmlmaker コマンド：InDesign XML の作成
 
 PDF を作成するには、TeXLive2012 以上の環境が必要です。EPUB を作成するには、rubyzip gem あるいは zip コマンドが必要です（MathML も使いたいときには、 [MathML ライブラリ](http://www.hinet.mydns.jp/?mathml.rb)も必要です）。
 
 いずれのコマンドも、必要な設定情報を記した YAML 形式ファイルを引数に指定して実行します。review-init コマンドで作成した環境には、デフォルトで config.yml として用意されているので、これを利用します。
 
 ```bash
-$ review-pdfmaker config.yml     ←PDFの作成
-$ review-epubmaker config.yml    ←EPUBの作成
-$ review-textmaker config.yml    ←テキストの作成（装飾情報あり）
-$ review-textmaker -n config.yml ←テキストの作成（装飾情報なし）
+$ review-pdfmaker config.yml       ←PDFの作成
+$ review-pdfmaker config-ebook.yml ←電子ブック設定でのPDFの作成
+$ review-epubmaker config.yml      ←EPUBの作成
+$ review-textmaker config.yml      ←テキストの作成（装飾情報あり）
+$ review-textmaker -n config.yml   ←テキストの作成（装飾情報なし）
+$ review-idgxmlmaker config.yml    ←InDesign XMLの作成
 ```
 
 rake コマンドを利用できるなら、次のように実行することもできます。
 
 ```bash
 $ rake pdf  ←PDFの作成
+$ REVIEW_CONFIG_FILE=config-ebook.yml rake pdf ←電子ブック設定でのPDFの作成
 $ rake epub ←EPUBの作成
 $ rake text  ←テキストの作成（装飾情報あり）
 $ rake plaintext ←テキストの作成（装飾情報なし）
+$ rake idgxml ←InDesign XMLの作成
 ```
 
 config.yml のサンプルについては以下を参照してください。
 
 * [config.yml.sample](https://github.com/kmuto/review/blob/master/doc/config.yml.sample)
 
+#### Vivliostyle CLI を使った PDF 化
+
+TeX (`review-pdfmaker`、`rake pdf`) を利用する代わりに、[Vivliostyle CLI](https://github.com/vivliostyle/vivliostyle-cli) を使って PDF を作成することもできます。Re:VIEW が EPUB を作成したあと、VivliostyleCLI がそれを PDF に変換します。
+
+```bash
+$ rake vivliostyle:build    ← Vivliostyle を使って PDF を作成
+$ rake vivliostyle:preview  ← Chrome/Chromium ブラウザでプレビュー
+$ rake vivliostyle          ← vivliostyle:buildのショートカット
+```
+
 ### 章を増やす、カスタマイズする
 作成した PDF あるいは EPUB を見ると、先に作成した RE:VIEW フォーマットテキストファイルが「第1章」となっていることがわかります。
 
@@ -177,7 +204,7 @@ Re:VIEW の使用実例については、https://github.com/reviewml/review-samp
 $ review-compile --target text sample.re > sample.txt    ←テキストにする
 $ review-compile --target html sample.re > sample.html   ←HTMLにする
 $ review-compile --target latex sample.re > sample.tex   ←LaTeXにする
-$ review-compile --target idgxml sample.re > sample.xml  ←XMLにする
+$ review-compile --target idgxml sample.re > sample.xml  ←InDesign XMLにする
 $ review-compile --target markdown sample.re > sample.md ←Markdownにする
 ```
 
@@ -200,20 +227,23 @@ $ review-preproc --replace ファイル ←ファイルを更新したもので
 $ review-vol
 ```
 
-より細かな見出し一覧などを出したいときには、review-index コマンドを使うのもよいでしょう。
+より細かな見出し一覧などを出したいときには、review-index コマンドを使うとよいでしょう。
 
 ```bash
-$ review-index --level 掘り下げる見出しレベル数 -a
+$ review-index -l 掘り下げる見出しレベル数
+$ review-index -l 掘り下げる見出しレベル数 -d ←分量の詳細を表示
 ```
 
-## ドキュメントフォルダを新しい Re:VIEW バージョンに追従する方法
+review-vol と review-index では、文字数や行数、見込みページなど各値に大きな差が出ることがあります。これは、review-vol がごく簡単にファイルから概算しているのに対し、review-index は実際に内部でコンパイルして比較的精密に計量しているからです。
+
+## プロジェクトフォルダを新しい Re:VIEW バージョンに追従する方法
 
-Re:VIEW は定期的に更新されています。おおむね後方互換性を保持していますが、新しいバージョン固有の機能を利用したいときには、ドキュメントフォルダを新しいバージョンに更新する review-update コマンドを利用します。
+Re:VIEW は定期的に更新されています。おおむね後方互換性を保持していますが、新しいバージョン固有の機能を利用したいときには、プロジェクトフォルダを新しいバージョンに更新する review-update コマンドを利用します。
 
 ```bash
 $ review-update
-** review-update はプロジェクトを 3.0.0 に更新します **
-config.yml: 'review_version' を '3.0' に更新しますか? [y]/n ←Enterで実行
+** review-update はプロジェクトを 5.0.0 に更新します **
+config.yml: 'review_version' を '5.0' に更新しますか? [y]/n ←Enterで実行
 Rakefile は Re:VIEW バージョンのもの (/.../review/samples/sample-book/src/Rakefile) で置き換えられます。本当に進めますか? [y]/n
 lib/tasks/review.rake は Re:VIEW バージョンのもの (/.../review/samples/sample-book/src/lib/tasks/review.rake) で置き換えられます。本当に進めますか? [y]/n
 INFO: 新しいファイル /.../sty/plistings.sty が作成されました。
@@ -229,9 +259,9 @@ INFO: 新しいファイル /.../sty/gentombow.sty が作成されました。
 
 ## クレジット
 
-Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2019年2月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。
+Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2020年10月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。
 
-バグ・パッチの報告、開発者用メーリングリストなどについての情報は、
+バグ・パッチの報告、その他の情報は、
 
 * http://reviewml.org/
 * https://github.com/kmuto/review/wiki

data/doc/quickstart.md

@@ -9,7 +9,7 @@ Re:VIEW is free software under the terms of the GNU Lesser General Public Licens
 
 This article describes how to setup Re:VIEW and use it.
 
-The supported version of the article is Re:VIEW 3.0.
+The supported version of the article is Re:VIEW 5.1.
 
 ## Set up Re:VIEW
 
@@ -59,7 +59,7 @@ $ git pull
 
 ## Writing Re:VIEW Document
 
-### Generating template fiels
+### Generating template files
 
 After setup, you can use `review-init` command to generate Re:VIEW project directory.
 
@@ -72,14 +72,23 @@ $ ls hello
 Rakefile     catalog.yml  config.yml   hello.re     images/      layouts/     sty/         style.css
 ```
 
+If your purpose is to create a PDF using TeX, it is a good idea to use the wizard mode for basic layouting in a web browser. Add `-w` option to review-init.
+
+(notice: currently wizard UI supports only Japanese language)
+
+```bash
+$ review-init -w hello
+(access http://localhost:18000 on Web browser)
+```
+
 In `hello` directory, many files are generated.
 
 * `*.re` : Re:VIEW format file.
 * config.yml : configuration file
+* config-ebook.yml : configuration file for ebook (when using the wizard mode)
 * catalog.yml : catalog file (for TOC)
 * Rakefile : rule file for `rake` command
 * images : folder for images
-* layouts : forlder for layout files
 * style.css : sample stylesheet
 * sty : style files for LaTeX
 * doc : various documents (including this document)
@@ -116,33 +125,52 @@ The web site of Re:VIEW is @<tt>{https://reviewml.org/}.
 
 You should use UTF-8 as encodings in text files.
 
-### generating PDF, EPUB, and plain-text
+### generating PDF, EPUB, plain-text, and InDesign XML
+
+To convert files in the project, use review-*maker command.
 
-You can generate a PDF file with `review-pdfmaker` command.  Also you can generate an EPUB file with `review-epubmaker` command, and can generate an plain-text file with 'review-textmaker' command.
+- review-pdfmaker: generate PDF
+- review-epubmaker: generate EPUB
+- review-textmaker: genrate plaintext
+- review-idgxmlmaker: genrate InDesign XML
 
-To generate PDF, you should install TeXLive 2012 or later.  To generate EPUB, you should install zip command.
+To generate PDF, you should install TeXLive 2012 or later. To generate EPUB, you should install zip command.
 When you want to use MathML, you should install [MathML library](http://www.hinet.mydns.jp/?mathml.rb)
 
-Each maker need `config.yml`, configuration YAML files.  `review-init` command generates `config.yml` in default.
+Each maker need `config.yml`, configuration YAML files. `review-init` command generates `config.yml` in default.
 
 ```bash
-$ review-pdfmaker config.yml     ## generate PDF
-$ review-epubmaker config.yml    ## generate EPUB
-$ review-textmaker config.yml    ## generate text with decoration
-$ review-textmaker -n config.yml ## generate text without decoration
+$ review-pdfmaker config.yml       ## generate PDF
+$ review-pdfmaker config-ebook.yml ## generate PDF (for ebook)
+$ review-epubmaker config.yml      ## generate EPUB
+$ review-textmaker config.yml      ## generate text with decoration
+$ review-textmaker -n config.yml   ## generate text without decoration
+$ review-idgxmlmaker config.yml    ## generate InDesign XML
 ```
 
 You also can generate them with Rake.
 
 ```bash
 $ rake pdf       ## generate PDF
+$ REVIEW_CONFIG_FILE=config-ebook.yml rake pdf       ## generate PDF (for ebook)
 $ rake epub      ## generate EPUB
 $ rake text      ## generate text with decoration
 $ rake plaintext ## generate text without decoration
+$ rake idgxml    ## generate InDesign XML
 ```
 
 There is a sample YAML file [config.yml.sample](https://github.com/kmuto/review/blob/master/doc/config.yml.sample) in the same directory of this document.
 
+#### generate PDF using Vivliostyle CLI
+
+Instead of using TeX (`review-pdfmaker` or `rake pdf`), you can also create a PDF use [Vivliostyle CLI](https://github.com/vivliostyle/vivliostyle-cli). Re:VIEW creates EPUB first and then converts it to PDF with Vivliostyle CLI.
+
+```bash
+$ rake vivliostyle:build    ## build PDF using Viliostyle
+$ rake vivliostyle:preview  ## preview pages in Chrome/Chromium browser
+$ rake vivliostyle          ## shortcut of vivliostyle:build
+```
+
 ### add chapters and modify them
 
 `catalog.yml` file is a catalog of Re:VIEW format files.
@@ -164,7 +192,6 @@ POSTDEF:
 
 The first item in CHAPS is the first chapter, and the second item (if you add) is the second chapter. PREDEF is for front matter, APPENDIX is for appendix, and POSTDEF is for back matter.  You can see in detail with [catalog.md](https://github.com/kmuto/review/blob/master/doc/catalog.ja.md).
 
-
 ### more information
 
 For more information about Re:VIEW format, see [format.md](https://github.com/kmuto/review/blob/master/doc/format.md).
@@ -205,17 +232,20 @@ $ review-vol
 You can also use `review-index` command to generate header list.
 
 ```bash
-$ review-index --level <heading level> -a
+$ review-index --level <heading level>
+$ review-index --level <heading level> -d  ## show volumes also
 ```
 
+review-vol and review-index can have large differences in the number of characters, lines, and pages. While review-vol only estimates from the file, review-index actually compiles and calculates.
+
 ## how to update the document folder to the new Re:VIEW version
 
-Re:VIEW is updated regularly. We Re:VIEW team watch the backward compatibility carefully, but if you want to use the features in the new version, you can use review-update command to update the document folder.
+Re:VIEW is updated regularly. We Re:VIEW team watch the backward compatibility carefully, but if you want to use the features in the new version, you can use review-update command to update the project folder.
 
 ```bash
 $ review-update
-** review-update updates your project to 3.0.0 **
-config.yml: Update 'review_version' to '3.0'? [y]/n
+** review-update updates your project to 5.0.0 **
+config.yml: Update 'review_version' to '5.0'? [y]/n
 Rakefile will be overridden with Re:VIEW version (/.../review/samples/sample-book/src/Rakefile). Do you really proceed? [y]/n
 lib/tasks/review.rake will be overridden with Re:VIEW version (/.../review/samples/sample-book/src/lib/tasks/review.rake). Do you really proceed? [y]/n
 INFO: new file /.../sty/plistings.sty is created.
@@ -231,7 +261,7 @@ Finished.
 
 ## Copyright
 
-The original author of Re:VIEW is Minero Aoki. The current maintainer is Kenshi Muto(@kmuto), and committers are Masayoshi Takahashi and Masanori Kado (February 2019).
+The original author of Re:VIEW is Minero Aoki. The current maintainer is Kenshi Muto(@kmuto), and committers are Masayoshi Takahashi and Masanori Kado (March 2020).
 
 If you want to report bugs and patches, or to get more information, see: