review 3.0.0 → 4.2.0

data/doc/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2018 Minero Aoki, Kenshi Muto, Masayoshi Takahashi, Masanori Kado.
+Copyright (c) 2006-2019 Minero Aoki, Kenshi Muto, Masayoshi Takahashi, Masanori Kado.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/doc/config.yml.sample

@@ -5,7 +5,7 @@
 # このファイルはUTF-8エンコーディングで記述してください。
 
 # この設定ファイルでサポートするRe:VIEWのバージョン番号。
-review_version: 3.0
+review_version: 4.0
 
 # ほかの設定ファイルの継承を指定できる。同じパラメータに異なる値がある場合は、
 # 呼び出し元の値が優先される。
@@ -64,6 +64,8 @@ aut: ["青木峰郎", "武藤健志", "高橋征義", "角征典"]
 # a-trc, trc: 筆記・タイプ作業者
 # a-trl, trl: 翻訳者
 
+# contact: 連絡先
+
 # 刊行日(省略した場合は実行時の日付)
 # date: 2018-11-11
 # 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する
@@ -72,7 +74,7 @@ aut: ["青木峰郎", "武藤健志", "高橋征義", "角征典"]
 # 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。
 # history: [["2016-04-20 v1.0.0版発行", "2018-11-11 v3.0.0版発行"]]
 # 権利表記(配列で複数指定可)
-# rights: (C) 2016-2018 Re:VIEW Developers
+# rights: (C) 2016-2020 Re:VIEW Developers
 # description: 説明
 # subject: 短い説明用タグ(配列で複数指定可)
 # type: 書籍のカテゴリーなど(配列で複数指定可)
@@ -111,7 +113,7 @@ toclevel: 3
 secnolevel: 2
 
 # 本文中に目次ページを作成するか。省略した場合はnull (作成しない)
-# toc: true
+toc: true
 
 # EPUB2標準の目次(NCX)以外に物理目次ファイルを作成するか。省略した場合はnull (作成しない)
 # ePUB3においてはこの設定によらず必ず作成される
@@ -137,7 +139,10 @@ secnolevel: 2
 # creditfile: null
 
 # 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる
+# デフォルトの奥付における各項目の名前（「著　者」など）を変えたいときにはlocale.ymlで文字列を設定する（詳細はdoc/format.ja.mdを参照）
 # colophon: null
+# デフォルトの奥付における、各項目の記載順序
+# colophon_order: ["aut", "csl", "trl", "dsr", "ill", "cov", "edt", "pbl", "contact", "prt"]
 
 # 裏表紙データファイル (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル)
 # backcover: null
@@ -173,18 +178,34 @@ secnolevel: 2
 # reファイルを格納するディレクトリ。省略した場合は以下 (. はカレントディレクトリを示す)
 # contentdir: .
 
-# @<w>命令で使用する単語ファイルのパス
+# @<w>命令で使用する単語ファイルのパス。["common.csv", "mybook.csv"]のように配列指定も可
 # words_file: words.csv
 
-# review-vol向けのヒント情報
-# 1ページの行数文字数と1kbごとのページ数を用紙サイズで指定する(A5 or B5)
+# //table命令における列の区切り文字。tabs (1文字以上のタブ文字区切り。デフォルト), singletab (1文字のタブ文字区切り), spaces (1文字以上のスペースまたはタブ文字の区切り), verticalbar ("0個以上の空白 | 0個以上の空白"の区切り)
+# table_row_separator: tabs
+
+# 複数行から段落を結合する際、前後のUnicode文字種に基づき必要に応じて空白文字を挿入するか
+# 省略した場合はnull (挿入しない)。別途unicode-eaw gemファイルが必要
+# join_lines_by_lang: null
+
+# 図・表・コードリスト・数式のキャプション位置。
+# 値はtop（上）またはbottom（下）でデフォルトは以下のとおり
+# caption_position:
+#   image: bottom
+#   table: top
+#   list: top
+#   equation: top
+
+# review-toc向けのヒント情報
+# (文字幅を考慮した行数計測には、別途unicode-eaw gemファイルが必要)
+# ページあたりの行数文字数を用紙サイズで指定する(A5 or B5)
 # page_metric: A5
 #
 # あるいは、配列で指定することもできる
-# 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数、1kバイトごとのページ数
-# page_metric: [40,80,40,80,2]
+# 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数
+# page_metric: [40,34,29,34]
 
-# EPUBおよびWeb生成における数式の画像化指定
+# EPUB・Web、およびテキスト生成時における数式の画像化指定
 # TeXの数式を画像化するか。省略した場合はnull (作成しない)
 # imgmath: true
 
@@ -211,14 +232,20 @@ secnolevel: 2
   # pdfcrop_cmd: "pdfcrop --hires %i %o"
   # PDFから画像化するコマンドのコマンドライン。プレースホルダは
   # %i: 入力ファイル、%o: 出力ファイル、%O: 出力ファイルから拡張子を除いたもの
-  # %p: 対象ページ番号
-  # pdfcrop_pixelize_cmd: "pdftocairo -png -r 90 -f %p -l %p -singlefile %i %O"
+  # %p: 対象ページ番号、%t: フォーマット
+  # pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O"
   # pdfcrop_pixelize_cmdが複数ページの処理に対応していない場合に単ページ化するか
   # extract_singlepage: null
   # extract_singlepageがtrueの場合に単ページ化するコマンドのコマンドライン
   # pdfextract_cmd: "pdfjam -q --outfile %o %i %p"
   # converterにdvipngを指定したときのdvipngコマンドのコマンドライン
   # dvipng_cmd: "dvipng -T tight -z 9 -p %p -l %p -o %o %i"
+  #
+  # PDFで保存したいときにはたとえば以下のようにする
+  # format: pdf
+  # extract_singlepage: true
+  # pdfextract_cmd: "pdftk A=%i cat A%p output %o"
+  # pdfcrop_pixelize_cmd: "mv %i %o"
 
 # EPUBにおけるページ送りの送り方向、page-progression-directionの値("ltr"|"rtl"|"default")
 # direction: "ltr"
@@ -306,6 +333,8 @@ epubmaker:
   # @<href>タグでの外部リンクを禁止し、地の文にする(falseで禁止する)
   # externallink: true
   #
+  # 脚注に「戻る」リンクを追加する(trueで追加)。脚注の記号および戻るリンクの記号はlocale.ymlで変更可能
+  # back_footnote: null
   # epubmaker:階層を使うものはここまで
 
 # LaTeX用のスタイルファイル(styディレクトリ以下に置くこと)
@@ -320,7 +349,7 @@ epubmaker:
 # texcommand: "uplatex"
 #
 # LaTeXのコマンドに渡すオプションを指定する
-# texoptions: "-interaction=nonstopmode -file-line-error"
+# texoptions: "-interaction=nonstopmode -file-line-error -halt-on-error"
 #
 # LaTeX用のdvi変換コマンドを指定する(dvipdfmx)
 # dvicommand: "dvipdfmx"
@@ -365,6 +394,9 @@ pdfmaker:
   # 画像のscale=X.Xという指定を画像拡大縮小率からページ最大幅の相対倍率に変換する
   # image_scale2width: true
   #
+  # 画像のデフォルトのサイズを、版面横幅合わせではなく、原寸をそのまま利用する
+  # use_original_image_size: null
+  #
   # PDFやIllustratorファイル(.ai)の画像のBoudingBoxの抽出に指定のボックスを採用する
   # cropbox(デフォルト), mediabox, artbox, trimbox, bleedboxから選択する。
   # Illustrator CC以降のIllustratorファイルに対してはmediaboxを指定する必要がある
@@ -386,4 +418,6 @@ pdfmaker:
   # makeindex_mecab_opts: "-Oyomi"
   # 奥付を作成するか。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる
   colophon: true
+  # 表紙挿入時に表紙のページ番号名を「cover」とし、偶数ページ扱いにして大扉前に白ページが入るのを防ぐ。デフォルトはtrue
+  # use_cover_nombre: true
   # pdfmaker:階層を使うものはここまで

data/doc/config.yml.sample-simple

@@ -1,5 +1,5 @@
 # simple sample of config.yml
-review_version: 3.0
+review_version: 4.0
 
 # debug: true
 
@@ -20,9 +20,10 @@ aut: ["Masayoshi Takahashi"]
 # edt: null
 pbl: "Re:VIEW Publishing inc."
 prt: "Re:VIEW Printing inc."
+contact: "https://reviewml.org/"
 date: 2018-11-11
 history: [["2012-01-30"],["2016-04-20","2016-05-03"],["2018-11-11"]]
-rights: (C) 2016-2018 Re:VIEW Commiters, some rights reserved.
+rights: (C) 2016-2020 Re:VIEW Commiters, some rights reserved.
 description: sample config.yml file for Re:VIEW book
 urnid: urn:uid:http://reviewml.org/review-sample-book
 # isbn: null
@@ -65,6 +66,7 @@ epubmaker:
   htmlext: xhtml
   cover_linear: true
   externallink: true
+  # back_footnote: true
 
 ## for LaTeX
 

data/doc/format.ja.md

@@ -20,9 +20,9 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ
 * 2行以上空けても、1行空きと同じ意味になります。
 * 空行せずに改行して段落の記述を続ける際、英文の単語間スペースについては考慮されないことに注意してください。Re:VIEW は各行を単純に連結するだけであり、TeX のように前後の単語を判断してスペースを入れるようなことはしません。
 
-## 章・節・項・段（見出し）
+## 章・節・項・目・段（見出し）
 
-章・節・項・段といった見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」で表します。6 レベル以上は使えません。`=`のあとにはスペースを入れます。
+章・節・項・目といった見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」で表します。7 レベル以上は使えません。`=`のあとにはスペースを入れます。
 
 例:
 
@@ -33,9 +33,11 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ
 
 === 項のキャプション
 
-==== 段のキャプション
+==== 目のキャプション
 
-===== 小段のキャプション
+===== 段のキャプション
+
+====== 小段のキャプション
 ```
 
 見出しは行の先頭から始める必要があります。行頭に空白を入れると、ただの本文と見なされます。
@@ -262,11 +264,23 @@ puts "hello world!"
 
 ```review
 //source[/hello/world.rb]{
-puts "hello world!"
+puts "hello world!" # キャプションあり
+//}
+
+//source{
+puts "hello world!" # キャプションなし
+//}
+
+//source[/hello/world.rb][ruby]{
+puts "hello world!" # キャプションあり、ハイライトあり
+//}
+
+//source[][ruby]{
+puts "hello world!" # キャプションなし、ハイライトあり
 //}
 ```
 
-ソースコードの引用は、キャプションを付けた `//emlist` とほぼ同じです。HTML の CSS などでは区別した表現ができます。
+ソースコードの引用は、`//emlist` とほぼ同じです。HTML の CSS などでは区別した表現ができます。
 
 ## 本文中でのソースコード引用
 
@@ -310,7 +324,7 @@ V1 --> V6 --|
 //}
 ```
 
-3番目の引数として、画像の倍率・大きさを指定することができます。今のところ「scale=X」で倍率（X 倍）を指定でき、HTML、TeX ともに紙面（画面）幅に対しての倍率となります（0.5 なら半分の幅になります）。
+3番目の引数として、画像の倍率・大きさを指定することができます。今のところ「scale=X」で倍率（X 倍）を指定でき、HTML、TeX ともに紙面（画面）幅に対しての倍率となります（0.5 なら半分の幅になります）。3番目の引数をたとえば HTML と TeX で分けたい場合は、`html::style="transform: scale(0.5);",latex::scale=0.5` のように `::` でビルダを明示し、`,` でオプションを区切って指定できます。
 
 ※TeX において原寸からの倍率にしたいときには、`config.yml` に `image_scale2width: false` を指定してください。
 
@@ -503,14 +517,13 @@ complexmatrixという識別子に基づく画像ファイルが貼り込まれ
 
 本文中のインライン命令「`@<fn>{site}`」は脚注番号に置換され、「本書のサポートサイト……」という文は実際の脚注に変換されます。
 
-注意: TeX PDF において、コラムや表など平文でないところで「`@<fn>{～}`」を使うには、`footnotetext` オプションを使う必要があります。
+注意: TeX PDF において、コラムの中で脚注を利用する場合、`//footnote` 行はコラムの終わり（`==[/column]` など）の後ろに記述することをお勧めします。Re:VIEW の標準提供のコラム表現では問題ありませんが、サードパーティのコラムの実装によってはおかしな採番表現になることがあります。
 
 ### footnotetext オプション
+TeX PDF において、コラム以外の `//note` などの囲み記事の中で「`@<fn>{～}`」を使うには、`footnotetext` オプションを使う必要があります。
 
 `footnotetext` オプションを使うには、`config.yml` ファイルに`footnotetext: true` を追加します。
 
-これで PDF のコラムや表のなかでも脚注が使えるようになります。
-
 ただし、通常の脚注（footnote）ではなく、footnotemark と footnotetext を使うため、本文と脚注が別ページに分かれる可能性があるなど、いろいろな制約があります。また、採番が別々になるため、footnote と footnotemark/footnotetext を両立させることはできません。
 
 ## 参考文献の定義
@@ -636,8 +649,8 @@ imgmath_options:
   pdfcrop_cmd: "pdfcrop --hires %i %o"
   # PDFから画像化するコマンドのコマンドライン。プレースホルダは
   # %i: 入力ファイル、%o: 出力ファイル、%O: 出力ファイルから拡張子を除いたもの
-  # %p: 対象ページ番号
-  pdfcrop_pixelize_cmd: "pdftocairo -png -r 90 -f %p -l %p -singlefile %i %O"
+  # %p: 対象ページ番号、%t: フォーマット
+  pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O"
   # pdfcrop_pixelize_cmdが複数ページの処理に対応していない場合に単ページ化するか
   extract_singlepage: null
   # 単ページ化するコマンドのコマンドライン
@@ -671,6 +684,17 @@ imgmath_options:
   pdfcrop_pixelize_cmd: "sips -s format png --out %o %i"
 ```
 
+textmaker 向けに PDF 形式の数式ファイルを作成したいときには、たとえば以下のように設定します（ページの抽出には pdftk を利用）。
+
+```
+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"
+```
+
 Re:VIEW 2 以前の dvipng の設定に合わせるには、次のようにします。
 
 ```
@@ -778,7 +802,7 @@ Web ハイパーリンクを記述するには、リンクに `@`、アン
 "i18n","""i""nternationalizatio""n"""
 ```
 
-単語ファイルのファイルパスは、`config.yml` に `words_file: ファイルパス` で指定します。
+単語ファイルのファイルパスは、`config.yml` に `words_file: ファイルパス` で指定します。`word_file: ["common.csv", "mybook.csv"]` のように複数のファイルも指定可能です（同一のキーがあるときには後に指定したファイルの値が優先されます）。
 
 例:
 

data/doc/format.md

@@ -24,7 +24,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 +39,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 +98,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 +118,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.
 ```
 
@@ -353,6 +355,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}`.
@@ -544,9 +547,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.
 
@@ -680,8 +684,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 +719,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 +851,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:
 

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"