review 3.1.0 → 5.0.0

data/doc/format.md

@@ -4,8 +4,7 @@ The document is a brief guide for Re:VIEW markup syntax.
 
 Re:VIEW is based on EWB of ASCII (now KADOKAWA), influenced RD and other Wiki system's syntax.
 
-This document explains about the format of Re:VIEW 3.0.
-
+This document explains about the format of Re:VIEW 5.0.
 
 ## Paragraph
 
@@ -24,7 +23,7 @@ Two empty lines or more are same as one empty line.
 
 ## Chapter, Section, Subsection (headings)
 
-Chapters, sections, subsections, subsubsections use `=`, `==`, `===`, `====`, `=====`.
+Chapters, sections, subsections, subsubsections use `=`, `==`, `===`, `====`, `=====`, and `======`.
 You should add one or more spaces after `=`.
 
 Usage:
@@ -39,6 +38,8 @@ Usage:
 ==== 4th level
 
 ===== 5th level
+
+====== 6th level
 ```
 
 Headings should not have any spaces before title; if line head has space, it is as paragraph.
@@ -96,11 +97,11 @@ Nested itemize is like ` **`, ` ***`.
 Usage:
 
 ```
-* 1st item
-** nested 1st item
-* 2nd item
-** nested 2nd item
-* 3rd item
+ * 1st item
+ ** nested 1st item
+ * 2nd item
+ ** nested 2nd item
+ * 3rd item
 ```
 
 In itemize, you must write one more space character at line head.
@@ -116,34 +117,34 @@ They aren't nested.
 Usage:
 
 ```
-1. 1st condition
-2. 2nd condition
-3. 3rd condition
+ 1. 1st condition
+ 2. 2nd condition
+ 3. 3rd condition
 ```
 
 The value of Number is ignored.
 
 ```
-1. 1st condition
-1. 2nd condition
-1. 3rd condition
+ 1. 1st condition
+ 1. 2nd condition
+ 1. 3rd condition
 ```
 
 You must write one more space character at line head like itemize.
 
 ## Definition List
 
-Definition list (dl in HTML) use `:` and indented lines.
+Definition list (dl in HTML) uses ` : ` and indented lines.
 
 Usage:
 
 ```review
-: Alpha
+ : Alpha
     RISC CPU made by DEC.
-: POWER
+ : POWER
     RSIC CPU made by IBM and Motolora.
     POWER PC is delivered from this.
-: SPARC
+ : SPARC
     RISC CPU made by SUN.
 ```
 
@@ -282,7 +283,6 @@ puts "hello world!"
 //}
 ```
 
-
 ### Quoting Source Code
 
 `//source` is for quoting source code. filename is mandatory.
@@ -337,7 +337,6 @@ You can use `//image{ ... //}` for figures.
 You can write comments or Ascii art in the block as an alternative description.
 When publishing, it's simply ignored.
 
-
 Usage:
 
 ```
@@ -353,6 +352,7 @@ V1 --> V6 --|
 ```
 
 The third option is used to define the scale of images.  `scale=X` is scaling for page width (`scale=0.5` makes image width to be half of page width).
+If you'd like to use different values for each builders, such as HTML and TeX, you can specify the target builders using `::`. Example: `html::style="transform: scale(0.5);",latex::scale=0.5`
 
 When you want to refer images such as "see figure 1.", you can use
 inline reference markup like `@<img>{unixhistory}`.
@@ -529,6 +529,19 @@ Some block commands are used for short column.
 
 The content is like paragraph; separated by empty lines.
 
+From Re:VIEW 5.0, it is also possible to include itemize, figures and tables in short columns.
+
+```
+//note{
+
+With ordered itemize.
+
+ 1. item1
+ 2. item2
+
+//}
+```
+
 ## Footnotes
 
 You can use `//footnote` to write footnotes.
@@ -544,9 +557,10 @@ You should get and install it before reading the book.
 `@<fn>{site}` in source are replaced by footnote marks, and the phrase "support site of .."
 is in footnotes.
 
-Note that In LATEXBuilder, you should use `footnotetext` option to use `@<fn>{...}` in columns and tables.
+Note that in LATEXBuilder, it is highly recommended to place `//footnote` after the end line of column (`==[/column]`) to avoid problems when using third party's style file.
 
 ### `footnotetext` option
+Note that in LATEXBuilder, you should use `footnotetext` option to use `@<fn>{...}` in `//note` or other short column blocks.
 
 By adding `footnotetext:true` in config.yml, you can use footnote in tables and short notes.
 
@@ -620,7 +634,7 @@ Usage:
 If you'd like to assign a number like 'Equation 1.1`, specify the identifier and caption.
 
 ```
-//texequationl[emc][The Equivalence of Mass and Energy]{
+//texequation[emc][The Equivalence of Mass and Energy]{
 \sum_{i=1}^nf_n(x)
 //}
 ```
@@ -680,8 +694,8 @@ imgmath_options:
   pdfcrop_cmd: "pdfcrop --hires %i %o"
   # imaging command.
   # %i: filename for input %o: filename for output %O: filename for output without the extension
-  # %p: page number
-  pdfcrop_pixelize_cmd: "pdftocairo -png -r 90 -f %p -l %p -singlefile %i %O"
+  # %p: page number, %t: format
+  pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O"
   # whether to generate a single PDF page for pdfcrop_pixelize_cmd.
   extract_singlepage: null
   # command line to generate a single PDF page file.
@@ -715,6 +729,17 @@ imgmath_options:
   pdfcrop_pixelize_cmd: "sips -s format png --out %o %i"
 ```
 
+To create PDF math images:
+
+```
+imgmath: true
+imgmath_options:
+  format: pdf
+  extract_singlepage: true
+  pdfextract_cmd: "pdftk A=%i cat A%p output %o"
+  pdfcrop_pixelize_cmd: "mv %i %o"
+```
+
 To set the same setting as Re:VIEW 2:
 
 ```
@@ -836,7 +861,7 @@ This word file is a CSV file with extension .csv. This first columns is the key,
 "i18n","""i""nternationalizatio""n"""
 ```
 
-Specify the word file path in `words_file` parameter of `config.yml`.
+Specify the word file path in `words_file` parameter of `config.yml`. You can specify multiple word files as `word_file: ["common.csv", "mybook.csv"]`.
 
 Usage:
 
@@ -941,6 +966,75 @@ this is a special line.
 
 (In other formats, it is just ignored.)
 
+### Nested itemize block
+
+Re:VIEW itemize blocks basically cannot express nested items. Also, none of itemize blocks allow to contain another itemize block or paragraph/image/table/list.
+
+As a workaround, Re:VIEW 4.2 provides an experimental `//beginchild` and `//endchild`. If you want to include something in an itemize block, enclose it with `//beginchild` and `//endchild`. It is also possible to create a multiple nest.
+
+```
+ * UL1
+
+//beginchild
+#@# child of UL1 start
+
+ 1. UL1-OL1
+
+//beginchild
+#@# child of UL1-OL1 start
+
+UL1-OL1-PARAGRAPH
+
+ * UL1-OL1-UL1
+ * UL1-OL1-UL2
+
+//endchild
+#@# child of UL1-OL1 end
+
+ 2. UL1-OL2
+
+ : UL1-DL1
+        UL1-DD1
+ : UL1-DL2
+        UL1-DD2
+
+//endchild
+#@# child of UL1 end
+
+ * UL2
+```
+
+Output:
+
+(In HTML:)
+
+```
+<ul>
+<li>UL1
+<ol>
+<li>UL1-OL1
+<p>UL1-OL1-PARAGRAPH</p>
+<ul>
+<li>UL1-OL1-UL1</li>
+<li>UL1-OL1-UL2</li>
+</ul>
+</li>
+
+<li>UL1-OL2</li>
+</ol>
+<dl>
+<dt>UL1-DL1</dt>
+<dd>UL1-DD1</dd>
+<dt>UL1-DL2</dt>
+<dd>UL1-DD2</dd>
+</dl>
+</li>
+
+<li>UL2</li>
+</ul>
+```
+
+(This is an experimental implementation. Names and behaviors may change in future versions.)
 
 ## Inline Commands
 
@@ -1091,13 +1185,11 @@ C
 A,B,C
 ```
 
-
 ## HTML/LaTeX Layout
 
 `layouts/layout.html.erb` and `layouts/layout.tex.erb` are used as layout file.
 You can use ERb tags in the layout files.
 
-
 Sample layout file(layout.html.erb):
 
 ```html

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 4.2 に基づいています。
 
 ## セットアップ
 
-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,28 +123,37 @@ 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 のサンプルについては以下を参照してください。
@@ -177,7 +194,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 +217,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 +249,9 @@ INFO: 新しいファイル /.../sty/gentombow.sty が作成されました。
 
 ## クレジット
 
-Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2019年2月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。
+Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2020年10月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。
 
-バグ・パッチの報告、開発者用メーリングリストなどについての情報は、
+バグ・パッチの報告、その他の情報は、
 
 * http://reviewml.org/
 * https://github.com/kmuto/review/wiki