review 2.1.0 → 2.2.0

data/doc/config.yml.sample

@@ -172,9 +172,9 @@ secnolevel: 2
 # fontdir内から取り込まれる対象となるファイル拡張子。省略した場合は以下
 # font_ext: ["ttf", "woff", "otf"]
 
-# ソースコードハイライトを利用する (pygmentsには外部gemが必要)
+# ソースコードハイライトを利用する (rouge,pygmentsには外部gemが必要)
 # highlight:
-#   html: "pygments"
+#   html: "rouge"
 #   latex: "listings"
 
 # カタログファイル名を指定する

data/doc/config.yml.sample-simple

@@ -51,7 +51,7 @@ colophon: true
 ## Syntax Highlighting
 
 highlight:
-  html: "pygments"
+  html: "rouge"
   latex: "listings"
 
 ## for HTML

data/doc/format.ja.md

@@ -221,6 +221,20 @@ puts "hello world!"
 
 他章のリストを参照するには、後述の「章ID」を指定し、たとえば `@<list>{advanced|main}`（`advanced.re` ファイルの章にあるリスト `main` を参照する）と記述します。
 
+### 行番号の指定
+
+行番号を指定した番号から始めるには、`//firstlinenum`を使います。
+
+例:
+
+```review
+//firstlinenum[100]
+//listnum[hello][ハローワールド][ruby]{
+puts "hello world!"
+//}
+```
+
+
 ### ソースコード専用の引用
 
 ソースコードを引用するには次のように記述します。
@@ -366,6 +380,20 @@ DISPLAY         X Window Systemのデフォルトディスプレイ
 
 表のセル内でもインライン命令は有効です。
 
+### 表の列幅
+
+LaTeX および IDGXML のビルダを利用する場合、表の各列の幅を `//tsize` ブロック命令で指定できます。
+
+```
+//tsize[|ビルダ|1列目の幅,2列目の幅,……]
+```
+
+* 列の幅は mm 単位で指定します。
+* IDGXML の場合、3列のうち1列目だけ指定したとすると、省略した残りの2列目・3列目は紙面版面の幅の残りを等分した幅になります。1列目と3列目だけを指定する、といった指定方法はできません。
+* LaTeX の場合、すべての列について漏れなく幅を指定する必要があります。
+* LaTeX の場合、「`//tsize[|latex||p{20mm}cr|]`」のように LaTeX の table マクロの列情報パラメータを直接指定することもできます。
+* その他のビルダ (HTML など) においては、この命令は単に無視されます。
+
 ### 複雑な表
 
 現時点では表のセルの結合や、中央寄せ・右寄せなどの表現はできません。
@@ -589,7 +617,9 @@ Web ハイパーリンクを記述するには、リンクに `@<href>`、アン
 
 ## 生データ行
 
-Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//raw` ブロック命令または `@<raw>` インライン命令を使います。
+Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//raw` ブロック命令や`//embed`ブロック命令、または `@<raw>` インライン命令や `@<embed>` インライン命令を使います。
+
+### `//raw`行
 
 例:
 
@@ -597,9 +627,9 @@ Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、
 //raw[|html|<div class="special">\nここは特別な行です。\n</div>]
 ```
 
-ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。
+ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。
 
-ビルダ名には「`html`」「`latex`」「`idgxml`」「`top`」のいずれかが入り、(複数のビルダにまたがる指定が必要かは別として)「,」で区切って複数指定することも可能です。「バックスラッシュ+n」は改行に変換されます。該当のビルダを使用しているときのみ、内容が出力されます。
+ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。
 
 例:
 
@@ -614,7 +644,55 @@ Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、
 
 インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。
 
-`//raw` および `@<raw>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。
+### `//embed`ブロック
+
+例:
+
+```
+//embed{
+<div class="special">
+ここは特別なブロックとして扱われます。
+</div>
+//}
+
+//embed[html,markdown]{
+<div class="special">
+ここはHTMLとMarkdownでは特別なブロックとして扱われます。
+</div>
+//}
+```
+
+`//embed`ブロック命令はブロック内の文字列をそのまま文書中に埋め込みます。エスケープされる文字はありません。
+
+オプションとして、ビルダ名を指定できます。ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。異なるビルダを使用している場合は無視されます。
+
+オプションを省略した場合、すべてのビルダで文字列が埋め込まれます。
+
+例:
+
+HTMLビルダを使用している場合:
+
+```html
+<div class="special">
+ここは特別なブロックとして扱われます。
+</div>
+
+<div class="special">
+ここはHTMLとMarkdownでは特別なブロックとして扱われます。
+</div>
+```
+
+LaTeXビルダを使用している場合:
+
+```tex
+<div class="special">
+ここは特別なブロックとして扱われます
+</div>
+
+```
+
+
+`//raw`、`//embed`、`@<raw>` および `@<embed>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。
 
 ## インライン命令
 主なインライン命令を次に示します。
@@ -653,7 +731,10 @@ Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、
 * `@<href>{URL}`, `@<href>{URL, 文字表現}` : ハイパーリンクを作成します（後述）。
 * `@<icon>{識別子}` : インラインの画像を出力します。
 * `@<m>{数式}` : インラインの数式を出力します。
-* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。
+* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}`は`}`に、`\\`は`\`に、`\n`は改行に置き換えられます。
+* `@<embed>{|ビルダ|〜}` : 生の文字列を埋め込みます。`\}`は`}`に、`\\`は`\`に置き換えられます（`\n`はそのままです）。
+* `@<idx>{文字列}` : 文字列を出力するとともに、索引として登録します。索引の使い方については、makeindex.ja.md を参照してください。
+* `@<hidx>{文字列}` : 索引として登録します (idx と異なり、紙面内に出力はしません)。`親索引文字列<<>>子索引文字列` のように親子関係にある索引も定義できます。
 
 ## 著者用タグ（プリプロセッサ命令）
 

data/doc/format.md

@@ -252,6 +252,20 @@ such as `@<list>{main}`.
 
 When you refer a list in the other chapter, you can use an ID with chapter ID, such like `@<list>{advanced|main}`, to refer a list `main` in `advanced.re`.
 
+### define line number of first line in code block
+
+If you want to start with specified number as line number, you can use `firstlinenum` command.
+
+Usage:
+
+```review
+//firstlinenum[100]
+//listnum[hello][helloworld][ruby]{
+puts "hello world!"
+//}
+```
+
+
 ### Quoting Source Code
 
 `//source` is for quoting source code. filename is mandatory.
@@ -411,6 +425,19 @@ When you want to write "see table X", you can write `@<table>{envvars}`.
 
 You can use inline markup in the tables.
 
+### Column width of table
+When using LaTeX or IDGXML builder, you can specify each column width of the table with `//tsize` block command.
+
+```
+//tsize[|builder|width-of-column1,width-of-column2,...]
+```
+
+* The collumn width is specified in mm.
+* For IDGXML, if only 1st of the three columns is specified, the remaining 2nd and 3rd columns will be the width of the remainder of the live area width equally divided. It is not possible to specify that only the 1st and 3rd columns are specified.
+* For LaTeX, you have to specify all column widths.
+* For LaTeX, you can also directly specify the column parameter of LaTeX table macro like `//tsize[|latex||p{20mm}cr|]`.
+* In other builders such as HTML, this command is simply ignored.
+
 ### Complex Table
 
 If you want to use complex tables, you can use `imgtable` block command with an image of the table.  `imgtable` supports numbering and `@<table>`.
@@ -661,7 +688,9 @@ Usage:
 
 ## Raw Data Block
 
-When you want to write non-Re:VIEW line, use `//raw`.
+When you want to write non-Re:VIEW line, use `//raw` or `//embed`.
+
+### `//raw` block
 
 Usage:
 
@@ -688,6 +717,39 @@ this is a special line.
 
 Note: `//raw` and `@<raw>` may break structured document easily.
 
+### `//embed` block
+
+Usage:
+
+```
+//embed{
+<div class="special">
+this is a special line.
+</div>
+//}
+
+//embed[html,markdown]{
+<div class="special">
+this is a special line.
+</div>
+//}
+```
+
+In above line, `html` and `markdown` is a builder name that handle raw data.
+
+Output:
+
+(In HTML:)
+
+```
+<div class="special">
+this is a special line.
+</div>
+```
+
+(In other formats, it is just ignored.)
+
+
 ## Inline Commands
 
 ### Styles
@@ -730,7 +792,10 @@ Note: `//raw` and `@<raw>` may break structured document easily.
 @<href>{http://www.google.com/, google}:: hyper link(URL)
 @<icon>{samplephoto}:: inline image
 @<m>{a + \alpha}:: TeX inline equation
-@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`.
+@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline.
+@<embed>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`.
+@<idx>{string}:: output a string and register it as an index. See makeindex.md.
+@<hidx>{string}:: register a string as an index. A leveled index is expressed like `parent<<>>child`
 ```
 
 ## Commands for Authors (pre-processor commands)

data/doc/makeindex.ja.md

@@ -0,0 +1,95 @@
+# 索引の使い方
+インラインタグ `@<idx>` および `@<hidx>` を用いて、索引単語を埋め込むことができます。索引を整列するにはその索引単語の「読み」が必要ですが、LaTeX ビルダにおいては、用意した辞書や形態素解析を使い、読み順に整列して紙面化します。
+
+## 注意
+* LaTeX の mendex コマンドの実装に依存しているため、 現時点では英語または日本語以外の挙動は不明です。
+* 形態素解析は、外部ソフトウェアの MeCab (http://taku910.github.io/mecab/)、その辞書である IPA 辞書、MeCab の Ruby バインドである mecab に依存しています。
+* LaTeX ビルダ以外のビルダでは、埋め込んだ索引を利用する手法を提供していません。後述のヒントを参照してください。
+* LaTeX ビルダでの索引生成機能は、デフォルトで無効にしています。設定 YAML ファイルで明示的に有効にする必要があります。
+
+## MeCab のセットアップ
+形態素解析による自動読みを使用する場合、MeCab  (http://taku910.github.io/mecab/) およびその辞書、Ruby バインドライブラリの mecab をインストールしておく必要があります。
+
+Debian GNU/Linux あるいは Ubuntu の環境では、次のようにパッケージをインストールします。
+
+```
+apt install mecab mecab-ipadic-utf8 ruby-mecab
+```
+
+MeCab 標準の辞書としては IPA 辞書と Juman 辞書がありますが、本機能の自動読みのためには「-Oyomi」オプションがサポートされている必要があり、これに対応しているのは IPA 辞書のみです。
+
+## 設定
+review-pdfmaker での索引作成を有効にするため、config.yml (別の設定ファイルを使う場合はその YAML ファイル) に、次のように追加します。
+
+```
+pdfmaker:
+  makeindex: true
+```
+
+re ファイル内に、`@<idx>` または `@<hidx>` インラインタグを使って索引を埋め込みます。`@<idx>` は、指定の文字列をそのまま紙面に出力するとともに索引とします。`@<hidx>` (hidden index) は、指定の文字列を索引とするのみで、紙面には出力しません。`@<hidx>` の場合は文字列内を `<<>>` で区切り、`親索引語<<>>子索引語`、`親索引語<<>>子索引語<<>>孫索引語`  とレベル分けした索引を指定できます。
+
+```
+@<idx>{表示もする索引}です
+  ↓
+表示もする索引です
+
+[索引]
+ひ
+表示もする索引です....1
+```
+
+```
+@<hidx>{表示しない索引}です@<hidx>{親<<>>子}
+  ↓
+です
+
+[索引]
+お
+ 親
+   子................1
+
+
+ひ
+ 表示もする索引です....1
+```
+
+## 読み辞書
+形態素解析は万能ではなく、特に短い単語は音読み・訓読みの違いで期待と異なる結果になりやすく、また辞書に載っていない専門的な単語は読みを解釈できずにおかしな結果になります。
+
+内部で使用している mendex プログラムに与える読み辞書を用意すれば、まずその辞書でのマッチングを試み、マッチングしなかったときに形態素解析を試みる、という手順をとることができます。また、MeCab を利用できない環境でも、すべての索引単語を解決できる読み辞書を用意すれば、索引機能を利用できます。
+
+辞書は次のように熟語と読みのペアをタブまたはスペースで区切ったテキストファイルとして作成します。
+
+```
+漢字  かんじ
+読み  よみ
+α    あるふぁ
+```
+
+このファイルを config.yml 設定ファイルで指定します (以下では my.dic を指定)。
+
+```
+pdfmaker:
+  makeindex: true
+  makeindex_dic: my.dic
+```
+
+なお、mendex のアルゴリズム上、辞書や形態素解析の適用は常にうまくいくとは限りません。たとえば「表 (ひょう、おもて)」のように 2 通りの読み方があるような語を使い分けたいというときには、review-pdfmaker のフック機能を使い、LaTeX のソースファイルに変換したところで LaTeX の索引命令に読みを明示する (たとえば `\index{おもて@表}`) といった対処が必要になるでしょう。LaTeX の索引命令の詳細については、mendex コマンドのオンラインマニュアルを参照してください。
+
+## カスタマイズ
+`pdfmaker:` 以下に記述可能な YAML 設定を以下にまとめます。
+
+* `makeindex`: `true` で索引を作成 (デフォルト: `null`＝作成しない)
+* `makeindex_command`: 索引作成の支援コマンド (デフォルト: `mendex`)
+* `makeindex_options`: 支援コマンドのオプション (デフォルト: `-f -r -I utf8`)
+* `makeindex_sty`: 支援コマンドで使うスタイルファイル (デフォルト: `null`)
+* `makeindex_dic`: 支援コマンドで使う読み辞書ファイル (デフォルト: `null`)
+* `makeindex_mecab`: MeCab による形態素解析を試みる (デフォルト: `true`＝使用する)
+* `makeindex_mecab_opts`: MeCab で読みを取得するオプション (デフォルト: `-Oyomi`)
+
+たとえば索引ページの見た目の表現は mendex コマンドのデフォルトのものが使われますが、設定をファイルで用意し、`makeindex_sty` にそのファイルを指定すれば変更できます。設定については mendex コマンドのオンラインマニュアルを参照してください。
+
+## ヒント
+「注意」で述べたとおり、LaTeX ビルダ以外のビルダでそれを活用する方法は提供していません。というのも、ほかのビルダでは、索引を読み順に並べ替えたり、それを表現したりといった方法についての一般的な解が存在しないからです。
+
+EPUB (HTML ビルダ) では `<!-- IDX:索引文字列 -->` のコメントで、IDGXML ビルダでは `<index value="索引文字列">` の XML 要素で、それぞれ索引は埋め込まれます。たとえばこれらを拾い出して、独自の辞書読み・整列ツール (LaTeX の mendex コマンドを流用するなど) を用意する方法が考えられるでしょう。

data/doc/makeindex.md

@@ -0,0 +1,97 @@
+# How to use index
+You can embed an index with using inline tags `@<idx>` and `@<hidx>`. In order to sort the index containing Kanji, "syllabary" of the Kanji is necessary. LaTeX builder can sort and layout them using a dictionary or morphological analysis.
+
+## Notice
+* Since it depends on mendex of LaTeX, it may work only in English or Japanese at present.
+* Morphological analysis relies on external software MeCab (http://taku910.github.io/mecab/), IPA dictionary, and mecab Ruby binding.
+* Other builders don't provide a method to use indexes. (see the hint.)
+* The index generation is disabled by default. You have to explicitly enable in the onfiguration YAML file.
+
+## Setting up MeCab
+When using morphological analytics, it is necessary to install MeCab (http://taku910.github.io/mecab/), its dictionary, and mecab of Ruby binding library.
+
+On Debian GNU/Linux or Ubuntu:
+
+```
+apt install mecab mecab-ipadic-utf8 ruby-mecab
+```
+
+There are 2 standard dictionaries for MeCab, "IPA" and "Juman", but use "IPA". Because only IPA supports "-Oyomi" option.
+
+## Configuration
+To enable index generation in review-pdfmaker, add a configuration to config.yml.
+
+```
+pdfmaker:
+  makeindex: true
+```
+
+Embed the indexes in Re:VIEW re files using inline tags `@<idx>` or `@<hidx>`.
+`@<idx>` outputs the word and sets it as an index. `@<hidx>` (hidden index) only indexes the word (no output). By separating strings with `<<>>` in `@<hidx>`, like `parentindex<<>>childindex` or `parentindex<<>>childindex<<>>grandchildindex`, you can define a leveled index.
+
+```
+I @<idx>{display} it.
+  ↓
+I display it.
+
+[Index]
+D
+display....1
+```
+
+```
+I @<hidx>{display} it.@<hidx>{Country<<>>Japan}
+  ↓
+I it.
+
+[Index]
+C
+ Country
+   Japan....1
+
+
+D
+ display....1
+```
+
+## Dictionary for Kanji
+Morphological analysis is not a silver bullet. It frequently misreads.
+By providing a dictionary, mendex program will try to match the word with priority. Also even in environments where MeCab can't be used, you can use the index generation by using a dictionary to resolve Kanji words.
+
+Dictionary file is a text file in which Kanji and Kana pairs are separated by tabs or spaces.
+
+```
+漢字  かんじ
+読み  よみ
+α    あるふぁ
+```
+
+Specify the above file (e.g. my.dic) in config.yml.
+
+```
+pdfmaker:
+  makeindex: true
+  makeindex_dic: my.dic
+```
+
+Due to mendex's algorithm, automatic Kanji sorting will not always succeed.
+In complicated case, you will need to modify a LaTeX source using review-pdfmaker's hook feature. See online manual of mendex for details.
+
+## Customize
+The following is an index setting that can be described under `pdfmaker:` in config.yml.
+
+* `makeindex`: if `true`, generate index page (default: `null` = don't generate)
+* `makeindex_command`: command path of the index tool (default: `mendex`)
+* `makeindex_options`: options of the index tool (default: `-f -r -I utf8`)
+* `makeindex_sty`: style file path of the index tool (default: `null`)
+* `makeindex_dic`: dictionary file path of the index tool (default: `null`)
+* `makeindex_mecab`: use MeCab (default: `true` = yes, I use)
+* `makeindex_mecab_opts`: options of MeCab (default: `-Oyomi`)
+
+For example, if you want to change the appearance of the index page, specify the style file to `makeindex_sty`. See online manual of mendex for details.
+
+## Hint
+The builders other than LaTeX builder don't provide a method to use indexes. Because the targets of other builders don't have a general way of sorting or outputting indexes.
+
+In EPUB (HTML builder), the index is embeded as `<!-- IDX:indexword -->` comment. In IDGXML builder, it is embeded as `<index value="indexword">` XML element.
+You can probably pick up them and prepare your own tool to sort (by using LaTeX mendex command, e.g.) and output.