review 2.0.0.beta1 → 2.0.0

data/doc/catalog.ja.md

@@ -1,15 +1,16 @@
 # Re:VIEW カタログファイル ガイド
 
-Re:VIEW のカタログファイル catalog.ymlについて説明します。
+Re:VIEW のカタログファイル catalog.yml について説明します。
+
+このドキュメントは、Re:VIEW 2.0 に基づいています。
 
 ## カタログファイルとは
 
-Re:VIEW フォーマットで記述された各ファイルを特に一冊の本（例えばPDFやEPUB）にまとめる際に、どのようにそれらのファイルを構造化するかを指定するファイルです。
-現在はカタログファイルと言えばcatalog.ymlのことを指します。
+カタログファイルは、Re:VIEW フォーマットで記述された各ファイルを1冊の本（たとえば PDF や EPUB）にまとめる際に、どのようにそれらのファイルを構造化するかを指定するファイルです。現在はカタログファイルと言えば catalog.yml のことを指します。
 
-## catalog.ymlを用いた場合の設定方法
+## catalog.yml を用いた場合の設定方法
 
-catalog.yml内で、`PREDEF`（前付け）、`CHAPS`（本編）、`APPENDIX`（付録、連番あり）、`POSTDEF`（後付け、連番なし）を記述します。CHAPSのみ必須です。
+catalog.yml 内で、`PREDEF`（前付け）、`CHAPS`（本編）、`APPENDIX`（付録、連番あり）、`POSTDEF`（後付け、連番なし）を記述します。CHAPS のみ必須です。
 
 ```yaml
 PREDEF:
@@ -26,7 +27,7 @@ POSTDEF:
   - postscript.re
 ```
 
-本編に対して、「部」構成を加えたい場合、`CHAPS`を段階的にして記述します。部の指定については、タイトル名でもファイル名でもどちらでも使えます。
+本編に対して、「部」構成を加えたい場合、`CHAPS` を段階的にして記述します。部の指定については、タイトル名でもファイル名でもどちらでも使えます。
 
 ```yaml
 CHAPS:
@@ -38,16 +39,7 @@ CHAPS:
     - ch04.re
 ```
 
-（旧バージョンの利用者の方へ: `PART`という項目はありません。`CHAPS`に記述してください）
-
-## バージョン 1.3以前について
-
-`APPENDIX`は指定できません。`POSTDEF`を使ってください。
-
-## バージョン 1.2以前について
-
-1.2以前のRe:VIEWではカタログファイルとしてPREDEF, CHAPS, POSTDEF, PARTという独立した4つのファイルを使用していました。
-そのため、当時のバージョンを利用する際にはcatalog.ymlではなくそちらを記述する必要があります。
+## 古いバージョンについて
+1.2 以前の Re:VIEW ではカタログファイルとして PREDEF, CHAPS, POSTDEF, PART という独立した4つのファイルを使用していました。古いカタログファイルを変換するツールとして、`review-catalog-converter` を提供しています。
 
-現在のRe:VIEWはcatalog.ymlを用いた方法と旧バージョンが使用していたCHAPS, PREDEF, POSTDEF, PARTを用いた方法と両方をサポートしています。
-ただしcatalog.ymlが存在する場合、そちらが優先されます。
+このコマンドにドキュメントのパスを指定して実行後、生成された catalog.yml の内容が正しいか確認してください。

data/doc/catalog.md

@@ -9,7 +9,7 @@ Now we use catalog.yml as catalog file.
 
 ## How to write catalog.yml
 
-In catalog.yaml, you can write `PREDEF`(frontmatter), `CHAPS`(bodymatter), `APPENDIX`(appendix) and `POSTDEF`(backmater). `CHAPS` is required.
+In catalog.yml, you can write `PREDEF`(frontmatter), `CHAPS`(bodymatter), `APPENDIX`(appendix) and `POSTDEF`(backmater). `CHAPS` is required.
 
 ```yaml
   PREDEF:
@@ -40,13 +40,9 @@ You can add parts in body to use `CHAPS` in a hierarchy. You can use both title
 
 (For old version user: there is no `PART`. You write them in `CHAPS`.)
 
-## About version 1.3 or earlier
+## About earlier version
 
-You can not use `APPENDIX`. Use `POSTDEF`.
+In version 1.x, Re:VIEW use 4 files PREDEF, CHAPS, POSTDEF, PART as catalog files.
 
-## About version 1.2 or earlier
-
-Before version 1.2 or earlier, Re:VIEW use 4 files PREDEF, CHAPS, POSTDEF, PART as catalog files.
-So you must use these files instead of catalog.yml when you use these versions of Re:VIEW.
-
-Current Re:VIEW supports both catalog.yml and old catalog files. When there are both files, catalog.yml is used.
+You can convert there files with `review-catalog-converter`.
+When using it, you should compare with these files and the generated file `catalog.yml`.

data/doc/config.yml.sample

@@ -0,0 +1,319 @@
+# review-epubmaker向けの設定ファイルの例。
+# yamlファイルをRe:VIEWファイルのある場所に置き、
+# 「review-epubmaker yamlファイル」を実行すると、<bookname>.epubファイルが
+# 生成されます。
+# このファイルはUTF-8エンコーディングで記述してください。
+
+# この設定ファイルでサポートするRe:VIEWのバージョン番号。
+# major versionが違うときにはエラーを出す。
+review_version: 2.0
+
+# ほかの設定ファイルの継承を指定できる。同じパラメータに異なる値がある場合は、
+# 呼び出し元の値が優先される。
+# A.yml、B.ymlのパラメータを継承する例。A.ymlとB.ymlに同じパラメータがある
+# 場合、B.ymlの値が優先される。さらに今このファイルに同じパラメータがあるなら、
+# その値がB.ymlよりも優先される。
+# 同様にA.yml、B.yml内でさらにinherit:パラメータを使うこともできる。
+# inherit: ["A.yml", "B.yml"]
+
+# ブック名(ファイル名になるもの。ASCII範囲の文字を使用)
+bookname: book
+# 記述言語。省略した場合はja
+language: ja
+
+# 書名
+# 読みを入れる例 booktitle: {name: "Re:VIEW EPUBサンプル", file-as: "リビューイーパブサンプル"}
+booktitle: Re:VIEWサンプル書籍
+
+# 著者名。「, 」で区切って複数指定できる
+# 読みを入れる例 aut: [{name: "青木峰郎", file-as: "アオキミネロウ"}, {name: "武藤健志", file-as: "ムトウケンシ"}, {name: "高橋征義", file-as: "タカハシマサヨシ"}, {name: "角征典", file-as: "カドマサノリ"}]
+aut: ["青木峰郎", "武藤健志", "高橋征義", "角征典"]
+
+# 以下はオプション
+# 以下はオプション(autと同じように配列書式で複数指定可能)。
+# 読みの指定はaut:の例を参照。
+# a-が付いているものはcreator側、
+# 付いていないものはcontributor側(二次協力者)に入る
+# a-adp, adp: 異なるメディア向けに作り直した者
+# a-ann, ann: 注釈記述者
+# a-arr, arr: アレンジした者
+# a-art, art: グラフィックデザインおよび芸術家
+# a-asn, asn: 関連・かつての所有者・関係者
+# a-aqt, aqt: 大きく引用された人物
+# a-aft, aft: 後書き・奥付の責任者
+# a-aui, aui: 序論・序文・前書きの責任者
+# a-ant, ant: 目録責任者
+# a-bkp, bkp: メディア制作責任者
+# a-clb, clb: 限定参加または補足者
+# a-cmm, cmm: 解釈・分析・考察者
+# a-dsr, dsr: デザイナ
+# a-edt, edt: 編集者
+# a-ill, ill: イラストレータ
+# a-lyr, lyr: 歌詞作成者
+# a-mdc, mdc: メタデータセットの一次的責任者
+# a-mus, mus: 音楽家
+# a-nrt, nrt: 語り手
+# a-oth, oth: その他
+# a-pht, pht: 撮影責任者
+# a-pbl, pbl: 出版社（発行所）
+# a-prt, prt: 印刷所
+# a-red, red: 項目の枠組起草者
+# a-rev, rev: 評論者
+# a-spn, spn: 援助者
+# a-ths, ths: 監督者
+# a-trc, trc: 筆記・タイプ作業者
+# a-trl, trl: 翻訳者
+
+# 刊行日(省略した場合は実行時の日付)
+# date: 2016-04-20
+# 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する
+# 複数指定する場合は次のように記述する
+# [["初版第1刷の日付", "初版第2刷の日付"], ["第2版第1刷の日付"]]
+# 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。
+# history: [["2016-04-20 v1.0.0版発行"]]
+# 権利表記(配列で複数指定可)
+# rights: (C) 2016 Re:VIEW Developers
+# description: 説明
+# subject: 短い説明用タグ(配列で複数指定可)
+# type: 書籍のカテゴリーなど(配列で複数指定可)
+# format: メディアタイプおよび特徴(配列で複数指定可)
+# source: 出版物生成の重要なリソース情報(配列で複数指定可)
+# relation: 補助的リソース(配列で複数指定可)
+# coverage: 内容の範囲や領域(配列で複数指定可)
+
+# デバッグフラグ。nullでないときには一時ファイルをカレントディレクトリに作成し、削除もしない
+debug: null
+
+# 固有IDに使用するドメイン。指定しない場合には、時刻に基づくランダムUUIDが入る
+# urnid: urn:uid:http://example.com/book-title/
+#
+# ISBN。省略した場合はurnidが入る
+# isbn: null
+#
+# HTMLファイルの拡張子(省略した場合はhtml)
+# htmlext: html
+#
+# CSSファイル(配列で複数指定可)
+stylesheet: ["sample.css"]
+
+# ePUBのバージョン (2か3)
+# epubversion: 2
+#
+# HTMLのバージョン (4か5。epubversionを3にしたときには5にする)
+# htmlversion: 4
+
+# 目次として抽出する見出しレベル
+toclevel: 3
+
+# 採番の設定。採番させたくない見出しには「==[nonum]」のようにnonum指定をする
+#
+# 本文でセクション番号を表示する見出しレベル
+secnolevel: 2
+
+# 以下のsecnolevelはまだ未実装。
+# 前付でセクション番号を表示する見出しレベル(未実装)
+# pre_secnolevel: 0
+#
+# 後付(付録)でセクション番号を表示する見出しレベル(未実装)
+# post_secnolevel: 1
+#
+# 部番号を表示する見出しレベル(未実装)
+# part_secnolevel: 1
+
+# 本文中に目次ページを作成するか。省略した場合はnull (作成しない)
+# toc: true
+
+# EPUB2標準の目次(NCX)以外に物理目次ファイルを作成するか。省略した場合はnull (作成しない)
+# ePUB3においてはこの設定によらず必ず作成される
+# mytoc: true
+
+# 表紙にするHTMLファイル。ファイル名を指定すると表紙として入る
+# cover: null
+#
+# 表紙に配置し、書籍の影絵にも利用する画像ファイル。省略した場合はnull (画像を使わない)。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg)
+# coverimage: null
+#
+# 表紙の後に大扉ページを作成するか。省略した場合はnull (作成しない)
+# titlepage: null
+#
+# 自動生成される大扉ページを上書きするファイル。ファイル名を指定すると大扉として入る
+# titlefile: null
+#
+# 原書大扉ページにするHTMLファイル。ファイル名を指定すると原書大扉として入る
+# originaltitlefile: null
+#
+# 権利表記ページファイル。ファイル名を指定すると権利表記として入る
+# creditfile: null
+
+# 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる
+# colophon: null
+
+# 裏表紙ファイル (画像はcoversまたはimagesに配置する)。ファイル名を指定すると裏表紙として入る
+# backcover: null
+
+# プロフィールページファイル。ファイル名を指定すると著者紹介として入る
+# profile: null
+# プロフィールページの目次上の見出し
+# profiletitle: 著者紹介
+
+# 広告ファイル。ファイル名を指定すると広告として入る
+# advfile: null
+
+# 取り込む画像が格納されているディレクトリ。省略した場合は以下
+# imagedir: images
+
+# 取り込むフォントが格納されているディレクトリ。省略した場合は以下
+# fontdir: fonts
+
+# imagedir内から取り込まれる対象となるファイル拡張子。省略した場合は以下
+# image_ext: ["png", "gif", "jpg", "jpeg", "svg", "ttf", "woff", "otf"]
+
+# fontdir内から取り込まれる対象となるファイル拡張子。省略した場合は以下
+# font_ext: ["ttf", "woff", "otf"]
+
+# ソースコードハイライトを利用する (pygmentsには外部gemが必要)
+# highlight:
+#   html: "pygments"
+#   latex: "listings"
+
+# カタログファイル名を指定する
+# catalogfile: catalog.yml
+
+# 1ページの行数文字数と1kbごとのページ数を用紙サイズで指定する(A5 or B5)。
+# page_metric: A5
+#
+# あるいは、配列で指定することもできる
+# 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数、1kバイト毎のページ数
+# page_metric: [40,80,40,80,2]
+
+# ページ送りの送り方向、page-progression-directionの値("ltr"|"rtl"|"default")
+# direction: "ltr"
+
+# EPUBのOPFへの固有の追加ルール
+# <package>要素に追加する名前空間
+# opf_prefix: {ebpaj: "http://www.ebpaj.jp/"}
+# 追加する<meta>要素のプロパティとその値
+# opf_meta: {"ebpaj:guide-version": "1.1.3"}
+
+# 以下のパラメータを有効にするときには、
+# epubmaker:
+#    パラメータ: 値
+#    パラメータ: 値
+#   ...
+# という構成にする必要がある(インデントさせる)
+
+epubmaker:
+  # HTMLファイルの拡張子
+  htmlext: xhtml
+  #
+  # 目次を要素の階層表現にしない。省略した場合(null)は階層化する。
+  # 特に部扉が入るなどの理由で、構成によっては階層化目次でepubcheckに
+  # パスしない目次ができるが、そのようなときにはこれをtrueにする
+  # flattoc: null
+  #
+  # 目次のインデントレベルをスペース文字で表現する(flattocがtrueのときのみ)
+  # flattocindent: true
+  #
+  # NCX目次の見出しレベルごとの飾り(配列で設定)。EPUB3ではNCXは作られない
+  # ncxindent:
+  #- 
+  #- - 
+  # フックは、各段階で介入したいときのプログラムを指定する。自動で適切な引数が渡される
+  # プログラムには実行権限が必要
+  # ファイル変換処理の前に実行するプログラム。スタイルシートのコンパイルをしたいときなどに利用する。
+  # 渡される引数1=作業用展開ディレクトリ
+  # hook_beforeprocess: null
+  #
+  # 前付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+  # 渡される引数1=作業用展開ディレクトリ
+  # hook_afterfrontmatter: null
+  #
+  # 本文の変換後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+  # 渡される引数1=作業用展開ディレクトリ
+  # hook_afterbody: null
+  #
+  # 後付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+  # 渡される引数1=作業用展開ディレクトリ
+  # hook_afterbackmatter: null
+  #
+  # 画像およびフォントをコピーした後に実行するプログラム。別の画像やフォントを追加したいときなどに利用する。
+  # 渡される引数1=作業用展開ディレクトリ
+  # hook_aftercopyimage: null
+  #
+  # ePUB zipアーカイブ直前に実行するプログラム。メタ情報などを加工したいときなどに利用する。
+  # 渡される引数1=ePUB準備ディレクトリ
+  # hook_prepack: null
+  #
+  # 変換したHTMLファイルおよびCSSを解析して厳密に使用している画像ファイルだけを取り込むか。デフォルトはnull(imagesディレクトリすべてを取り込む)
+  # なお、フォント、カバー、広告についてはこの設定によらずディレクトリ内のものがすべて取り込まれる
+  # verify_target_images: null
+  #
+  # verify_target_imagesがtrueの状態において、解析で発見されなくても強制的に取り込むファイルの相対パスの配列
+  # force_include_images: []
+  #
+  # Re:VIEWファイル名を使わず、前付にpre01,pre02...、本文にchap01,chap02l...、後付にpost01,post02...という名前付けルールにするか
+  # rename_for_legacy: null
+  #
+  # ePUBアーカイブの非圧縮実行
+  # zip_stage1: "zip -0Xq"
+  #
+  # ePUBアーカイブの圧縮実行
+  # zip_stage2: "zip -Xr9Dq"
+  #
+  # ePUBアーカイブに追加するパス(デフォルトはmimetype、META-INF、OEBPS)
+  # zip_addpath: null
+  #
+  # EPUBで表紙をコンテンツに含めるか。デフォルトでは作成されない。yesにするとiBooks等でも最初に表紙が表示されるようになる
+  # cover_linear: null
+  #
+  # @<href>タグでの外部リンクを禁止し、地の文にする(falseで禁止する)
+  # externallink: true
+  #
+  # epubmaker:階層を使うものはここまで
+
+# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと)
+# texstyle: samplemacro
+#
+# LaTeX用のdocumentclassを指定する
+# texdocumentclass: ["jsbook", "uplatex,oneside"]
+#
+# LaTeX用のコマンドを指定する
+# texcommand: "uplatex"
+#
+# LaTeXのコマンドに渡すオプションを指定する
+# texoptions: null
+#
+# LaTeX用のdvi変換コマンドを指定する(dvipdfmx)
+# dvicommand: "dvipdfmx"
+#
+# LaTeX用のdvi変換コマンドのオプションを指定する
+# dvioptions: "-d 5"
+
+# 以下のパラメータを有効にするときには、
+# pdfmaker:
+#    パラメータ: 値
+#    パラメータ: 値
+#   ...
+# という構成にする必要がある(インデントさせる)
+#
+pdfmaker:
+  #
+  # TeXコンパイル前に実行するプログラム。変換後のTeXソースを調整したいときに使用する。
+  # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+  # hook_beforetexcompile: null
+  #
+  # TeXコンパイル後に実行するプログラム。索引作業をして再度コンパイルしたいときなどに使用する。
+  # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+  # hook_aftertexcompile: null
+  #
+  # PDF(book.pdf)作成後に実行するプログラム。PDFに加工を施したいときに使用する。
+  # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+  # hook_afterdvipdf: null
+  #
+  # 画像のscale=X.Xという指定を画像拡大縮小率からページ最大幅の相対倍率に変換します。
+  # image_scale2width: true
+  #
+  # 奥付を作成するか。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる
+  colophon: true
+  # pdfmaker:階層を使うものはここまで
+

data/doc/customize_epub.ja.md

@@ -0,0 +1,42 @@
+# EPUB ローカルルールへの対応方法
+Re:VIEW の review-epubmaker が生成する EPUB ファイルは IDPF 標準に従っており、EpubCheck を通過する正規のものです。
+
+しかし、ストアによってはこれに固有のローカルルールを設けていることがあり、それに合わせるためには別途 EPUB ファイルに手を入れる必要があります。幸い、ほとんどのルールは EPUB 内のメタ情報ファイルである OPF ファイルにいくつかの情報を加えることで対処できます。
+
+Re:VIEW の設定ファイルは config.yml を使うものとします。
+
+## 電書協ガイドライン
+* http://ebpaj.jp/counsel/guide
+
+電書協ガイドラインの必須属性を満たすには、次の設定を config.yml に加えます。
+
+```yaml
+opf_prefix: {ebpaj: "http://www.ebpaj.jp/"}
+opf_meta: {"ebpaj:guide-version": "1.1.3"}
+```
+
+これは次のように展開されます。
+
+```xml
+<package …… prefix="ebpaj: http://www.ebpaj.jp/">
+ ……
+    <meta property="ebpaj:guide-version">1.1.3</meta>
+```
+
+ただし、Re:VIEW の生成する EPUB は、ファイルやフォルダの構成、スタイルシートの使い方などにおいて電書協ガイドラインには準拠していません。
+
+## iBooks ストア
+デフォルトでは、iBooks で EPUB を見開きで開くと、左右ページの間に影が入ります。
+これを消すには、次のように指定します。
+
+```yaml
+opf_prefix: {ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"}
+opf_meta: {"ibooks:binding": "false"}
+```
+
+すでにほかの定義があるときには、たとえば次のように追加してください。
+
+```yaml
+opf_prefix: {ebpaj: "http://www.ebpaj.jp/", ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"}
+opf_meta: {"ebpaj:guide-version": "1.1.3", "ibooks:binding": "false"}
+```

data/doc/format.ja.md

@@ -1,12 +1,12 @@
 # Re:VIEW フォーマットガイド
 
-Re:VIEW フォーマットの文法について解説します。Re:VIEW
-フォーマットは ASCII の EWB を基本としながら、一部に
-RD や各種 Wiki の文法をとりいれて簡素化しています。
+Re:VIEW フォーマットの文法について解説します。Re:VIEW フォーマットはアスキー社（現カドカワ）の EWB を基本としながら、一部に RD や各種 Wiki の文法を取り入れて簡素化しています。
+
+このドキュメントは、Re:VIEW 2.0 に基づいています。
 
 ## 段落
 
-段落(本文)の間は英語の段落のように1行空けます。
+段落（本文）の間は1行空けて表現します。空けずに次の行を記述した場合は、1つの段落として扱われます。
 
 例:
 
@@ -17,11 +17,12 @@ RD や各種 Wiki の文法をとりいれて簡素化しています。
 次の段落〜〜〜
 ```
 
-2行以上空いている場合も1行空きと同様に処理します。
+* 2行以上空けても、1行空きと同じ意味になります。
+* 空行せずに改行して段落の記述を続ける際、英文の単語間スペースについては考慮されないことに注意してください。Re:VIEW は各行を単純に連結するだけであり、TeX のように前後の単語を判断してスペースを入れるようなことはしません。
 
-## 章・節・項・段(見出し)
+## 章・節・項・段（見出し）
 
-章・節・項・段など、見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」です。6 レベル以上は使えません。
+章・節・項・段といった見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」で表します。6 レベル以上は使えません。`=`のあとにはスペースを入れます。
 
 例:
 
@@ -37,11 +38,13 @@ RD や各種 Wiki の文法をとりいれて簡素化しています。
 ===== 小段のキャプション
 ```
 
-見出しは行の先頭から始める必要があります。行頭に空白が入ると、ただの本文とみなされます。
+見出しは行の先頭から始める必要があります。行頭に空白を入れると、ただの本文と見なされます。
+
+また、見出しの前に文があると、段落としてつながってしまうことがあります。このようなときには空行を見出しの前に入れてください。
 
 ## コラムなど
 
-節や項の見出しに `[column]` を追加するとコラムのキャプションになります。
+節や項の見出しに `[column]` を追加すると以降がコラムとして扱われ、見出しはコラムのキャプションになります。
 
 例:
 
@@ -49,10 +52,9 @@ RD や各種 Wiki の文法をとりいれて簡素化しています。
 ===[column] コンパイラコンパイラ
 ```
 
-このとき、「=」と「[column]」は間を開けず、必ず続けて書かなければ
-なりません。空白があってもいけません。
+このとき、「=」と「[column]」は間を空けず、必ず続けて書かなければなりません。
 
-次の節や項を待たずにコラムを終了する場合は、「===[/column]」を記述します。
+コラムは、そのコラムのキャプションの見出しと同等か上位のレベル（コラムキャプションが `===` であれば、`=`〜`===`）の見出しが登場するかファイル末尾に達した時点で終了します。これを待たずにコラムを終了する場合は、「`===[/column]`」と記述します（`=`の数はコラムキャプションと対応）。
 
 例:
 
@@ -64,78 +66,115 @@ RD や各種 Wiki の文法をとりいれて簡素化しています。
 ===[/column]
 ```
 
+より下位の見出しを使うことでコラム内に副見出しを入れることができますが、それが必要になるほど長いコラムはそもそも文章構造に問題がある可能性があります。
+
+このほか、次のような見出しオプションがあります。
+
+* `[nonum]` : これを指定している章・節・項・段には連番を振りません。見出しは目次に含まれます。
+* `[nodisp]` : これを指定している章・節・項・段の見出しは変換結果には表示されず、連番も振りません。ただし、見出しは目次に含まれます。
+* `[notoc]` : これを指定している章・節・項・段には連番を振りません。見出しは目次に含まれません。
+
 ## 箇条書き
 
-箇条書き (HTML で言う ul) は「` *`」で表現します。
-ネストは「` **`」のように深さに応じて数を増やします。
+箇条書き（HTML で言う ul、ビュレット箇条書きともいう）は「` *`」で表現します。ネストは「` **`」のように深さに応じて数を増やします。
 
 例:
 
 ```
-* 第一の項目
-** 第一の項目のネスト
-* 第二の項目
-** 第二の項目のネスト
-* 第三の項目
+ * 第1の項目
+ ** 第1の項目のネスト
+ * 第2の項目
+ ** 第2の項目のネスト
+ * 第3の項目
 ```
 
-箇条書きを書くには、行頭に1つ以上の空白を必ず入れるようにします。
-行頭に空白を入れず「*」を書くと、ただのテキストとみなされます。
+箇条書きには行頭に1つ以上の空白が必要です。行頭に空白を入れず「*」と書くと、ただのテキストと見なされるので注意してください。
+
+通常の段落との誤った結合を防ぐため、箇条書きの前後には空行を入れることをお勧めします（他の箇条書きも同様）。
 
 ## 番号付き箇条書き
 
-番号付きの箇条書き (HTML で言う ol) は「` 1. 〜`」「` 2. 〜`」
-「` 3. 〜`」で示します。ネストはしません。
+番号付きの箇条書き（HTML で言う ol）は「` 1. 〜`」「` 2. 〜`」「` 3. 〜`」のように示します。ネストはサポートしていません。
 
 例:
 
-
 ```
-1. 第一の条件
-2. 第二の条件
-3. 第三の条件
+ 1. 第1の条件
+ 2. 第2の条件
+ 3. 第3の条件
 ```
 
 番号付き箇条書きも、ただの箇条書きと同様、行頭に1つ以上の空白が必要です。
 
 ## 用語リスト
 
-用語リスト (HTML で言う dl) は「:」と、続く空白で始まる行を使って示します。
+用語リスト（HTML で言う dl）は空白→「:」→空白、で始まる行を使って示します。
 
 例:
 
 ```review
-: Alpha
+ : Alpha
     DEC の作っていた RISC CPU。
     浮動小数点数演算が速い。
-: POWER
+ : POWER
     IBM とモトローラが共同製作した RISC CPU。
     派生として POWER PC がある。
-: SPARC
+ : SPARC
     Sun が作っている RISC CPU。
     CPU 数を増やすのが得意。
 ```
 
-頭の「`:`」それ自体はテキストではないので注意してください。
-その後に続く文字列が用語名(HTMLではdt要素)になります。
+「`:`」それ自体はテキストではないので注意してください。その後に続く文字列が用語名（HTML での dt 要素）になります。
+
+そして、その行以降、空白で始まる行が用語内容（HTML では dd 要素）になります。次の用語名か空行になるまで、1つの段落として結合されます。
+
+## ブロック命令とインライン命令
+
+見出しと箇条書きは特別な記法でしたが、それ以外の Re:VIEW の命令はほぼ一貫した記法を採用しています。
+
+ブロック命令は1〜複数行の段落に対して何らかのアクション（たいていは装飾）を行います。ブロック命令の記法は次のとおりです。
+
+```
+//命令[オプション1][オプション2]…{
+対象の内容。本文と同じような段落の場合は空行区切り
+ …
+//}
+```
+
+オプションを取らなければ単に `//命令{` という開始行になります。いずれにせよ、開始と終了は明確です。オプション内で「]」という文字が必要であれば、`\]` でリテラルを表現できます。
+
+亜種として、一切段落を取らないブロック命令もごく少数あります。
+
+```
+//命令[オプション1][オプション2]…
+```
+
+インライン命令は段落、見出し、ブロック内容、一部のブロックのオプション内で利用でき、文字列内の一部に対してアクション（装飾）を行います。
+
+```
+@<命令>{対象の内容}
+```
 
-用語リストの「`:`」ではじまる行は、行頭に空白があってもなくてもかまいません。
-そして、その行以降、空白で始まる行が用語内容(HTMLではdd要素)になります。
+内容に「}」という文字が必要であれば、`\}` でリテラルを表現できます。
 
-また、リスト内でも後述するインライン命令は有効です。
+記法および処理の都合で、次のような制約があります。
+
+* ブロック命令内には別のブロック命令をネストできません。
+* ブロック命令内には見出しや箇条書きを格納できません。
+* インライン命令には別のインライン命令をネストできません。
 
 ## ソースコードなどのリスト
 
-ソースコードなどのリストには`//list`を使います。連番をつけたくない場合は先頭に``em``（embeddedの略）、行番号をつける場合は末尾に``num``を付加します。まとめると以下の4種類になります。
+ソースコードなどのリストには`//list`を使います。連番を付けたくない場合は先頭に `em`（embedded の略）、行番号を付ける場合は末尾に `num` を付加します。まとめると、以下の4種類になります。
 
-* ``//list[識別子][キャプション][言語指定]{ 〜 //}``
+* `//list[識別子][キャプション][言語指定]{ 〜 //}`
   * 通常のリスト。言語指定は省略できます。
-* ``//listnum[識別子][キャプション][言語指定]{ 〜 //}``
+* `//listnum[識別子][キャプション][言語指定]{ 〜 //}`
   * 通常のリストに行番号をつけたもの。言語指定は省略できます。
-* ``//emlist[キャプション][言語指定]{ 〜 //}``
+* `//emlist[キャプション][言語指定]{ 〜 //}`
   * 連番がないリスト。キャプションと言語指定は省略できます。
-* ``//emlistnum[キャプション][言語指定]{ 〜 //}``
-  * 連番がないリストに行番号をつけたもの。キャプションと言語指定は省略できます。
+* `//emlistnum[キャプション][言語指定]{ 〜 //}`
+  * 連番がないリストに行番号を付けたもの。キャプションと言語指定は省略できます。
 
 例:
 
@@ -161,7 +200,7 @@ puts "hello world!"
 例:
 
 ```review
-//emlist[][ruby]{
+//emlist[][c]{
 printf("hello");
 //}
 ```
@@ -174,17 +213,17 @@ puts "hello world!"
 //}
 ```
 
+言語指定は、ハイライトを有効にしたときに利用されます。
 
+コードブロック内でもインライン命令は有効です。
 
-ブロック内でも後述するインライン命令は有効です。
+また本文中で「リスト X.X を見てください」のようにリストを指定する場合は、インライン命令 `@<list>` を使います。`//list` あるいは `//listnum` で指定した識別子を指定し、たとえば「`@<list>{main}`」と表記します。
 
-また本文中で「リスト X を見てください」のようにリストを指定
-する場合は、`//list` で指定した識別子を使って「`@<list>{main}`」
-と表記します。
+他章のリストを参照するには、後述の「章ID」を指定し、たとえば `@<list>{advanced|main}`（`advanced.re` ファイルの章にあるリスト `main` を参照する）と記述します。
 
 ### ソースコード専用の引用
 
-ソースコードを引用する場合、ファイル名が必要です。
+ソースコードを引用するには次のように記述します。
 
 例:
 
@@ -194,21 +233,11 @@ puts "hello world!"
 //}
 ```
 
-ソースコードの引用は、キャプションをつけた`//emlist`とあまり違いはありません。
-が、HTMLのCSSなどでは区別した表現ができます。
-
-
-参照方法はlistと変わりません。
-
-例:
-
-```
-..は@<list>{hello}をみてください。
-```
+ソースコードの引用は、キャプションを付けた `//emlist` とほぼ同じです。HTML の CSS などでは区別した表現ができます。
 
 ## 本文中でのソースコード引用
 
-本文中でソースコードを引用して記述します。
+本文中でソースコードを引用して記述するには、`code` を使います。
 
 例:
 
@@ -218,23 +247,21 @@ puts "hello world!"
 
 ## コマンドラインのキャプチャ
 
-コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。
+コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。インライン命令を使って入力箇所を強調するのもよいでしょう。
 
 例:
 
 ```
 //cmd{
-$ ls /
+$ @<b>{ls /}
 //}
 ```
 
-ブロック内でも後述するインライン命令は有効です。
-
 ## 図
 
-図は `//image{ 〜 //}` で指定します。執筆中はアスキーアートで
-代替しているため、ダミーのアスキーアートが入っていることがあり
-ます。この部分は、組版時には単に無視してください。
+図は `//image{ 〜 //}` で指定します。後述するように、識別子に基づいて画像ファイルが探索されます。
+
+ブロック内の内容は単に無視されますが、アスキーアートや、図中の訳語などを入れておくといった使い道があります。
 
 例:
 
@@ -250,14 +277,13 @@ V1 --> V6 --|
 //}
 ```
 
-3番目の引数として、画像の倍率・大きさを指定することができます。
-今のところ「scale=X」で倍率(X倍)が指定できます。
+3番目の引数として、画像の倍率・大きさを指定することができます。今のところ「scale=X」で倍率（X 倍）を指定でき、HTML、TeX ともに紙面（画面）幅に対しての倍率となります（0.5 なら半分の幅になります）。
+
+※TeX において原寸からの倍率にしたいときには、`config.yml` に `image_scale2width: false` を指定してください。
 
-また本文中で「図 X を見てください」のように図を指定する場合は、
-`//image` で指定した識別子を用いて「`@<img>{unixhistory}`」と
-記述します。`//image` と `@<img>` でつづりが違うので注意してください。
+また、本文中で「図 X.X を見てください」のように図を指定する場合は、インライン命令 `@<img>` を使います。`//image` で指定した識別子を用いて「`@<img>{unixhistory}`」のように記述します（`//image` と `@<img>` でつづりが違うので注意してください）。
 
-なお、後述しますが、インラインで図を出力するには`@<icon>`を使用します。
+### 画像ファイルの探索
 
 図として貼り込む画像ファイルは、次の順序で探索され、最初に発見されたものが利用されます。
 
@@ -270,11 +296,15 @@ V1 --> V6 --|
 6. <imgdir>/<id>.<ext>
 ```
 
-* ``<imgdir>`` はデフォルトでは images ディレクトリです。
-* ``<builder>`` は利用しているビルダ名 (ターゲット名) で、たとえば ``--target=html`` としているのであれば、images/html ディレクトリとなります。
-* ``<chapid>`` は re ファイルの名前に相当します。たとえば ch01.re という名前であれば「ch01」です。
-* ``<id>`` は //image[〜] の最初に入れた「〜」のことです (つまり、ID に日本語や空白交じりの文字を使ってしまうと、後で画像ファイル名の名付けに苦労することになります!)。
-* ``<ext>`` は Re:VIEW が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。
+* `<imgdir>` はデフォルトでは images ディレクトリです。
+* `<builder>` は利用しているビルダ名（ターゲット名）で、たとえば `--target=html` としているのであれば、images/html ディレクトリとなります。
+* `<chapid>` は章 ID です。たとえば ch01.re という名前であれば「ch01」です。
+* `<id>` は //image[〜] の最初に入れた「〜」のことです（つまり、ID に日本語や空白交じりの文字を使ってしまうと、後で画像ファイル名の名前付けに苦労することになります！）。
+* `<ext>` は Re:VIEW が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。
+
+### インラインの画像挿入
+
+段落途中などに画像を貼り込むには、インライン命令の `@<icon>{識別子}` を使います。ファイルの探索ルールは同じです。
 
 ## 番号が振られていない図
 
@@ -294,8 +324,6 @@ V1 --> V6 --|
 //numberlessimage[door_image_path][扉絵]
 ```
 
-※ただし、`//indepimage`と機能的にかぶっているので、将来は廃止され、`//indepimage`に統合される予定です。
-
 ## グラフ表現ツールを使った図
 
 `//graph[ファイル名][コマンド名][キャプション]` で各種グラフ表現ツールを使った画像ファイルの生成ができます。キャプションは省略できます。
@@ -312,11 +340,9 @@ plot sin(x)
 
 ## 表
 
-表は `//table[識別子][キャプション]{ 〜 //}` です。ヘッダと内容を
-分ける罫線は「`------`」で書き込んであります。
+表は `//table[識別子][キャプション]{ 〜 //}` という記法です。ヘッダと内容を分ける罫線は「`------------`」（12個以上の連続する `-` または `=`）を使います。
 
-カラム間は任意個数のタブで区切ります。また、カラム先頭の「`.`」は削除されるので、カラムの先頭文字が「`.`」の場合は「`.`」をもう一つ余計に付けてください。例えば「`.`」という内容のカラムは「`..`」と書きます。
-また、空のカラムは「`.`」と書けます。
+表の各列のセル間は「1つ」のタブで区切ります。また、列の先頭セルの「`.`」は削除されるので、先頭文字が「`.`」の場合は「`.`」をもう1つ余計に付けてください。たとえば「`.`」という内容のセルは「`..`」と書きます。
 
 例:
 
@@ -336,10 +362,24 @@ DISPLAY         X Window Systemのデフォルトディスプレイ
 //}
 ```
 
-本文中で「表 X を見てください」のように表を指定する場合は
-`@<table>{envvars}` という表記を使います。
+本文中で「表 X.X を見てください」のように表を指定する場合はインライン命令 `@<table>` を使います。たとえば `@<table>{envvars}` となります。
+
+表のセル内でもインライン命令は有効です。
+
+### 複雑な表
+
+現時点では表のセルの結合や、中央寄せ・右寄せなどの表現はできません。
+
+複雑な表については、画像を貼り込む `imgtable` ブロック命令を代わりに使用する方法もあります。`imgtable` の表は通常の表と同じく採番され、インライン命令 `@<table>` で参照できます。
 
-表内でも後述するインライン命令は有効です。
+例:
+
+```
+//imgtable[complexmatrix][複雑な表]{
+complexmatrixという識別子に基づく画像ファイルが貼り込まれる。
+探索ルールはimageと同じ
+//}
+```
 
 ## 引用
 
@@ -353,8 +393,24 @@ DISPLAY         X Window Systemのデフォルトディスプレイ
 //}
 ```
 
-引用内でも後述するインライン命令は有効です。
-また、いまのところ引用内で別のブロック構文を使うことはできません。
+複数の段落を入れる場合は、空行で区切ります。
+
+## 囲み記事
+
+技術書でよくある、コラムにするほどではないけれども本文から独立したちょっとした記事を入れるために、以下の命令があります。
+
+* `//note[キャプション]{ 〜 //}` : ノート
+* `//memo[キャプション]{ 〜 //}` : メモ
+* `//tip[キャプション]{ 〜 //}` : Tips
+* `//info[キャプション]{ 〜 //}` : 情報
+* `//warning[キャプション]{ 〜 //}` : 注意
+* `//important[キャプション]{ 〜 //}` : 重要
+* `//caution[キャプション]{ 〜 //}` : 警告
+* `//notice[キャプション]{ 〜 //}` : 注意
+
+いずれも `[キャプション]` は省略できます。
+
+内容には、空行で区切って複数の段落を記述可能です。
 
 ## 脚注
 
@@ -368,30 +424,27 @@ DISPLAY         X Window Systemのデフォルトディスプレイ
 //footnote[site][本書のサポートサイト： http://i.loveruby.net/ja/stdcompiler ]
 ```
 
-本文中の「`@<fn>{site}`」は脚注番号に置換され、「本書のサポート
-サイト……」という文は実際の脚注に変換されます。
+本文中のインライン命令「`@<fn>{site}`」は脚注番号に置換され、「本書のサポートサイト……」という文は実際の脚注に変換されます。
 
-注意: PDFで、コラムや表など平文でないところで「`@<fn>{～}`」を使うには、`footnotetext`オプションを使う必要があります。
+注意: TeX PDF において、コラムや表など平文でないところで「`@<fn>{～}`」を使うには、`footnotetext` オプションを使う必要があります。
 
-### footnotetextオプション
+### footnotetext オプション
 
-`footnotetext`オプションを使うには、YAMLファイルの`params`に「`--footnotetext`」を追加します。
+`footnotetext` オプションを使うには、`config.yml` ファイルに`footnotetext: true` を追加します。
 
-これでPDFのコラムや表のなかでも脚注が使えるようになります。
+これで PDF のコラムや表のなかでも脚注が使えるようになります。
 
-ただし、通常の脚注(footnote)ではなく、footnotemarkとfootnotetextを使うため、
-本文と脚注が別ページに分かれる可能性があるなど、いろいろな制約があります。
-なお、採番が別々になるためfootnoteとfootnotemark/footnotetextを両立させることはできません。
+ただし、通常の脚注（footnote）ではなく、footnotemark と footnotetext を使うため、本文と脚注が別ページに分かれる可能性があるなど、いろいろな制約があります。また、採番が別々になるため、footnote と footnotemark/footnotetext を両立させることはできません。
 
 ## 参考文献の定義
 
-参考文献は同一ディレクトリ内の bib.re に定義します。
+参考文献は同一ディレクトリ内の `bib.re` ファイルに定義します。
 
 ```
-//bibpaper[cite][キャプション]{..コメント..}
+//bibpaper[cite][キャプション]{…コメント…}
 ```
 
-コメントが無い場合も定義可能です。
+コメントは省略できます。
 
 ```
 //bibpaper[cite][キャプション]
@@ -408,18 +461,17 @@ Computing Laboratory, The University of Kent at Canterbury , August
 //}
 ```
 
-本文中で参考文献を参照したい場合は次のようにしてください。
+本文中で参考文献を参照したい場合は、インライン命令 `@<bib>` を使い、次のようにします。
 
 例:
 
 ```
-…という研究が知られています(@<bib>{lins})
+…という研究が知られています（@<bib>{lins}）。
 ```
 
 ## リード文
 
-リード文は `//lead{ 〜 //}` で指定します。
-歴史的経緯により`//read{ 〜 //}` でも使えます。
+リード文は `//lead{ 〜 //}` で指定します。歴史的経緯により、`//read{ 〜 //}` も使用可能です。
 
 例:
 
@@ -430,7 +482,9 @@ Computing Laboratory, The University of Kent at Canterbury , August
 //}
 ```
 
-## TeX式
+空行区切りで複数の段落を記述することもできます。
+
+## TeX 式
 
 LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。
 
@@ -442,293 +496,271 @@ LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。
 //}
 ```
 
-## 空白制御
+インライン命令では `@<m>{〜}` を使います。インライン命令の式中に「}」を含む場合、`\}` とエスケープする必要があることに注意してください（`{` はエスケープ不要）。
 
-出力される空白を制御するタグとしては、`//noindent`があります。
+LaTeX の数式が正常に整形されるかどうかは処理系に依存します。たとえば TeX PDF であれば問題なく利用できるでしょうが、EPUB では MathML 変換を有効にしても妥当な結果にならないことがあります。確実を期すならば、画像で表現するほうが適切です。
 
+## 字下げの制御
 
-* `//noindent` : その直後に来る段落冒頭のインデントをなくす(HTMLではnoindentクラスになる)
+段落の行頭字下げを制御するタグとして、`//noindent` があります。HTML では `noindent` が `class` 属性に設定されます。
 
+## 見出し参照
+章に対する参照は、次の3つのインライン命令を利用できます。章 ID は、各章のファイル名から拡張子を除いたものです。たとえば `advanced.re` であれば `advanced` が章 ID です。
 
-以前あった「`//linebreak`」(改行)、「`//pagebreak`」(改ページ)は廃止になります。
-
-## コメント
+* `@<chap>{章ID}` : 「第17章」のような、章番号を含むテキストに置換されます。
+* `@<title>{章ID}` : その章の章題に置換されます。
+* `@<chapref>{章ID}` : 『第17章「さらに進んだ話題」』のように、章番号とタイトルを含むテキストに置換されます。
 
-最終結果に出力されないコメントを記述したい場合は「`#@#`」を使ってください。
+節や項といったより下位の見出しを参照するには、`@<hd>` インライン命令を利用します。見出しの階層を「`|`」で区切って指定します。
 
 例:
 
 ```
-#@# ここで 1 行あける
+@<hd>{はじめに|まずは}
 ```
 
-また、修正が必要な警告的コメントには`#@warn(...)`を使ってください。
+他の章を参照したい場合は、先頭に章 ID を指定してください。
 
 例:
 
 ```
-#@warn(あとで書く)
+@<hd>{preface|はじめに|まずは}
 ```
 
-最終結果に出力するコメントを記述したい場合は、`//comment`または`@<comment>`を使った上で、review-compileコマンドに`--draft`オプションを追加してください。
-
-例:
+参照先にラベルが設定されている場合は、見出しの代わりに、ラベルで参照します。
 
 ```
-@<comment>{あとで書く}
+=={hajimeni} はじめに
+…
+=== まずは
+…
+@<hd>{hajimeni|まずは}
 ```
 
-## 生データ行
+### コラム見出し参照
 
-Re:VIEW のタグ範囲を越えて何か特別な行を挿入したい場合、`//raw` を使います。
+コラムの見出しの参照は、インライン命令 `@<column>` を使います。
 
 例:
 
 ```
-//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
+@<column>{Re:VIEWの用途いろいろ}
 ```
 
-「|ビルダ名|そのまま出力させる内容」という書式です。
-
-ビルダ名には「`html`」「`latex`」「`idgxml`」「`top`」のいずれかが入り、(複数のビルダにまたがる指定が必要かは別として)「,」で区切って複数指定することも可能です。
-「バックスラッシュ+n」は改行に変換されます。
-該当のビルダを使用しているときのみ、内容が出力されます。
-
-例:
+ラベルでの参照も可能です。
 
 ```
-(HTMLビルダの場合:)
-<div class="special">
-ここは特別な行です。
-</div>
-
-(ほかのビルダの場合は単に無視されて何も出力されない)
+==[column]{review-application} Re:VIEWの応用
+…
+@<column>{review-application}
 ```
 
-`//raw` およびこの後に紹介する `@<raw>` インラインタグは、誤った内容を入れると
-構造化文書を容易に破壊し得ることに注意してください。
-
-## その他の文法
-
-Re:VIEW は任意のブロックを追加可能なので、本によって専用ブロックを
-使う場合があります。これまでに使った例を以下に示します。
+## リンク
 
-* `//prototype` : 関数プロトタイプ。『ふつうのLinuxプログラミング』で使用。
-* `//type` : 関数の型宣言。『ふつうのHaskellプログラミング』で使用。
+Web ハイパーリンクを記述するには、リンクに `@<href>`、アンカーに `//label` を使います。リンクの書式は `@<href>{URL, 文字表現}` で、「`, 文字表現`」を省略すると URL がそのまま使われます。URL 中に `,` を使いたいときには、`\,` とエスケープしてください。
 
-拡張文法はreview-ext.rbというファイルで指定できます。
-例えば、
+例:
 
 ```
-# review-ext.rb
-ReVIEW::Compiler.defblock :foo, 0..1
-class ReVIEW::HTMLBuilder
-  def foo(lines, caption = nil)
-    puts lines.join(",")
-  end
-end
+@<href>{http://github.com/, GitHub}
+@<href>{http://www.google.com/}
+@<href>{#point1, ドキュメント内ポイント}
+@<href>{chap1.html#point1, ドキュメント内ポイント}
+//label[point1]
 ```
 
-のようにすると、以下のような文法を追加できます。
+## コメント
 
-```
-//foo{
-A
-B
-C
-//}
-```
+最終結果に出力されないコメントを記述するには、「`#@#`」を使います。行末までがコメントとして無視されます。
+
+例:
 
 ```
-# 出力結果
-A,B,C
+#@# FIXME: あとで調べておくこと
 ```
 
-詳しいことについては、ここでは触れません。
-
+最終結果に出力するコメントを記述したい場合は、`//comment` または `@<comment>` を使ったうえで、review-compile コマンドに `--draft` オプションを付けて実行します。
 
-## 段落中で使う文法 (インライン命令)
+例:
 
 ```
-@<list>{program}:: 「リスト1.5」のような文字列に置換される。
-@<img>{unixhistory}:: 「図1.3」のような文字列に置換される。
-@<table>{ascii}:: 「表1.2」のような文字列に置換される。
-@<fn>{site}:: 脚注番号に置換される。
-@<kw>{信任状, credential}:: キーワード。太字などにして強調してください。
-@<chap>{advanced}:: 「第17章」のような、章番号を含むテキストに置換される。
-@<title>{advanced}:: その章の章題に置換される。
-@<chapref>{advanced}:: 『第17章「さらに進んだ話題」』のように、章番号とタイトルを含むテキストに置換される。
-@<bou>{ふさわしい}:: 傍点。
-@<ruby>{直截, ちょくせつ}:: ルビ。
-@<ami>{重点ポイント}:: 文字に対するアミかけ。
-@<b>{どうしても}:: 太字 (ボールド)。
-@<i>{どうしても}:: イタリック。
-@<strong>{どうしても}:: 強調。
-@<em>{どうしても}:: 強調。
-@<tt>{foo($bar)}:: テキストをテレタイプ文字(等幅フォント)で出力する。
-@<tti>{FooClass}:: テキストをテレタイプ文字(等幅フォント)のイタリックで出力する。
-@<ttb>{BarClass}:: テキストをテレタイプ文字(等幅フォント)の太字で出力する。
-@<u>{下線}:: 下線。
-@<br>{}::  段落中改行。
-@<m>{a + \alpha}:: TeXインライン式。
-@<icon>{samplephoto}:: インライン画像。
-@<uchar>{2460}:: Unicode文字の出力。引数は16進数で指定する。
-@<href>{http://www.google.com/}:: リンク。URLで指定できる
-@<raw>{|ビルダ名|<span>★</span>}:: そのまま出力する。「}」は「バックスラッシュ+}」でエスケープする。ビルダ名は「html」「latex」「idgxml」「top」のいずれかで、「,」で区切って複数指定することも可能。該当のビルダを使用時のみ、出力される。内容に「バックスラッシュ+n」を入れると改行に変換される。
+@<comment>{あとで書く}
 ```
 
-## 著者用タグ (プリプロセッサ命令)
+## 生データ行
+
+Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//raw` ブロック命令または `@<raw>` インライン命令を使います。
 
-これまでに説明したタグはすべて最終段階まで残り、見ために
-影響を与えます。それに対して以下のタグは著者が使うための
-専用タグであり、最終段階ではすべて消されてしまいます。
+例:
 
 ```
-#@#:: コメント。この行には何を書いても無視される。
-#@warn(...):: 警告メッセージ。プリプロセス時にメッセージが出力される。
-#@require, #@provide:: キーワードの依存関係を宣言する。
-#@mapfile(ファイル名) 〜 #@end:: ファイルの内容をその場に展開する。
-#@maprange(ファイル名, 範囲名) 〜 #@end:: ファイル内の範囲をその場に展開する。
-#@mapoutput(コマンド) 〜 #@end:: コマンドを実行して、その出力結果を展開する。
+//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
 ```
 
-## HTMLのレイアウト機能
+ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。
 
-CHAPSファイルが置かれているディレクトリに layouts/layout.html.erb
-を置くとその html を ERB で評価します。
+ビルダ名には「`html`」「`latex`」「`idgxml`」「`top`」のいずれかが入り、(複数のビルダにまたがる指定が必要かは別として)「,」で区切って複数指定することも可能です。「バックスラッシュ+n」は改行に変換されます。該当のビルダを使用しているときのみ、内容が出力されます。
 
 例:
 
 ```
-<html>
-  <head>
-    <title><%= title %></title>
-  </head>
-  <body>
-    <%= body %>
-    <hr/>
-  </body>
-</html>
+（HTMLビルダの場合:）
+<div class="special">
+ここは特別な行です。
+</div>
+
+（ほかのビルダの場合は単に無視されて何も出力されない）
 ```
 
-## 部タイトル取得(目次生成機能)
+インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。
 
-Version 1.2以前の場合、PART ファイルに定義してください。
-PART ファイルは CHAPS の部わけと対応しています。
+`//raw` および `@<raw>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。
 
-例:
+## インライン命令
+主なインライン命令を次に示します。
 
-```
-CHAPS:
-  intro.re
+### 書体
+書体については、適用するスタイルシートなどによって異なることがあります。
 
-  start.re
+* `@<kw>{〜}`, `@<kw>{キーワード, 補足}` : キーワード。通常は太字になることを想定しています。2つめの記法では、たとえば `@<kw>{信任状, credential}` と表記したら「信任状（credential）」のようになります。
+* `@<bou>{〜}` : 傍点が付きます。
+* `@<ami>{〜}` : 文字に対して網がかかります。
+* `@<u>{〜}` : 下線を引きます。
+* `@<b>{〜}` : 太字にします。
+* `@<i>{〜}` : イタリックにします。和文の場合、処理系によってはイタリックがかからないこともあります。
+* `@<strong>{〜}` : 強調（太字）にします。
+* `@<em>{〜}` : 強調にします。
+* `@<tt>{〜}` : 等幅にします。
+* `@<tti>{〜}` : 等幅＋イタリックにします。
+* `@<ttb>{〜}` : 等幅＋太字にします。
+* `@<code>{〜}` : 等幅にします（コードの引用という性質）。
+* `@<tcy>{〜}` : 縦書きの文書において文字を縦中横にします。
 
-  end.re
-```
+### 参照
+* `@<chap>{章ファイル名}` : 「第17章」のような、章番号を含むテキストに置換されます。
+* `@<title>{章ファイル名}` : その章の章題に置換されます。
+* `@<chapref>{章ファイル名}` : 『第17章「さらに進んだ話題」』のように、章番号とタイトルを含むテキストに置換されます。
+* `@<list>{識別子}` : リストを参照します。
+* `@<img>{識別子}` : 図を参照します。
+* `@<table>{識別子}` : 表を参照します。
+* `@<hd>{ラベルまたは見出し}` : 節や項を参照します。
+* `@<column>{ラベルまたは見出し}` : コラムを参照します。
 
-```
-PART:
-  (序章なので空行)
-  はじまりの部
-  おわりの部
-```
+### その他
+* `@<ruby>{親文字, ルビ}` : ルビを振ります。たとえば `@<ruby>{愕然, がくぜん}` のように表記します。
+* `@<br>{}` : 段落途中で改行します。濫用は避けたいところですが、表のセル内や箇条書き内などで必要になることもあります。
+* `@<uchar>{番号}` : Unicode文字を出力します。引数は16進数で指定します。
+* `@<href>{URL}`, `@<href>{URL, 文字表現}` : ハイパーリンクを作成します（後述）。
+* `@<icon>{識別子}` : インラインの画像を出力します。
+* `@<m>{数式}` : インラインの数式を出力します。
+* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。
 
-Version 1.3以降では、catalog.ymlが使えるようになりました。
-catalog.ymlの使い方については「Re:VIEW カタログファイルガイド」を参照してください。
+## 著者用タグ（プリプロセッサ命令）
 
-## 見出し参照
+これまでに説明したタグはすべて最終段階まで残り、見た目に影響を与えます。それに対して以下のタグは著者が使うための専用タグであり、変換結果からは除去されます。
 
-見出し番号と見出しを生成します。
-見出しの階層は"`|`"で区切って指定してください。
+* `#@#` : コメント。この行には何を書いても無視されます。
+* `#@warn(〜)` : 警告メッセージ。プリプロセス時にメッセージが出力されます。
+* `#@require`, `#@provide` : キーワードの依存関係を宣言します。
+* `#@mapfile(ファイル名) 〜 #@end` : ファイルの内容をその場に展開します。
+* `#@maprange(ファイル名, 範囲名) 〜 #@end` : ファイル内の範囲をその場に展開します。
+* `#@mapoutput(コマンド) 〜 #@end` : コマンドを実行して、その出力結果を展開します。
 
-例:
+コメントを除き、プリプロセッサ `review-preproc` コマンドとの併用を前提とします。
 
-```
-@<hd>{はじめに|まずわ}
-```
-
-見出しを一意に特定できる場合は、"`|`"は不要です。
+## 国際化（i18n）
 
-```
-@<hd>{まずわ}
-```
+Re:VIEW が出力する文字列(「第◯章」「図」「表」など）を、指定した言語に合わせて出力することができます。デフォルトは日本語です。
 
-他の章を参照したい場合は、先頭に章のidを指定してください。
+ファイルが置かれているディレクトリに `locale.yml` というファイルを用意して、以下のように記述します（日本語の場合）。
 
 例:
 
 ```
-@<hd>{preface|はじめに|まずわ}
+locale: ja
 ```
 
-参照先にラベルが設定されている場合は、ラベルで参照します。
+既存の表記を書き換えたい場合は、該当する項目を上書きします。既存の設定ファイルは Re:VIEW の `lib/review/i18n.yml` にあります。
+
+例:
 
 ```
-=={hajimeni} はじめに
-:
-=== まずわ
-:
-@<hd>{hajimeni|まずわ}
+locale: ja
+list: 実行例
 ```
 
+### Re:VIEW カスタムフォーマット
 
-### コラム見出し参照
+`locale.yml` ファイルでは、章番号などに以下の Re:VIEW カスタムフォーマットを使用可能です。
 
-コラムの見出しの参照は、`@<column>`を使います。
+* `%pA` : アルファベット（大文字）A, B, C, ...
+* `%pa` : アルファベット（小文字）a, b, c, ...
+* `%pAW` : アルファベット（大文字・いわゆる全角）Ａ, Ｂ, Ｃ, ...
+* `%paW` : アルファベット（小文字・いわゆる全角）ａ, ｂ, ｃ, ...
+* `%pR` : ローマ数字（大文字）I, II, III, ...
+* `%pr` : ローマ数字（小文字）i, ii, iii, ...
+* `%pRW` : ローマ数字（大文字・単一文字表記）Ⅰ, Ⅱ, Ⅲ, ...
+* `%pJ` : 漢数字 一, 二, 三, ...
+* `%pdW' : アラビア数字（0〜9まではいわゆる全角、10以降半角）１, ２, ... 10, ...
+* `%pDW' : アラビア数字（すべて全角）１, ２, ... １０, ...
 
 例:
 
 ```
-@<column>{Re:VIEWの用途いろいろ}
+locale: ja
+  part: 第%pRW部
+  appendix: 付録%pA
 ```
 
-ラベルでの参照もできます。
+## その他の文法
 
-```
-==[column]{review-application} Re:VIEWの応用
-:
-@<column>{review-application}
-```
+拡張文法は `review-ext.rb` というファイルで指定できます。
 
-## リンク
+たとえば、
 
-Web ハイパーリンクを記述するには、リンクに `@<href>`、アンカーに `//label`
-を使います。リンクの書式は `@<href>{URL, 文字表現}` で、「`, 文字表現`」を
-省略すると URL がそのまま使われます。URL 中に `,` を使いたいときには、`\,`
-と表記してください。
+```ruby
+# review-ext.rb
+ReVIEW::Compiler.defblock :foo, 0..1
+class ReVIEW::HTMLBuilder
+  def foo(lines, caption = nil)
+    puts lines.join(",")
+  end
+end
+```
 
-例:
+のような内容のファイルを用意すると、以下のような文法を追加できます。
 
 ```
-@<href>{http://github.com/, GitHub}
-@<href>{http://www.google.com/}
-@<href>{#point1, ドキュメント内ポイント}
-@<href>{chap1.html#point1, ドキュメント内ポイント}
-//label[point1]
+//foo{
+A
+B
+C
+//}
 ```
 
-## 国際化(i18n)
-
-Re:VIEWが出力する文字列(「第◯章」「図」「表」など）を、指定した言語に
-合わせて出力することができます。デフォルトは日本語です。
-
-CHAPS などと同じディレクトリに locale.yml というファイルを用意して、
-以下のように記述します（日本語の場合）。
-
-例:
-
 ```
-locale: ja
+# 出力結果
+A,B,C
 ```
 
-既存の表記を書き換えたい場合は、該当する項目を上書きします。
-既存の設定ファイルは lib/review/i18n.yml にあります。
+詳しいことについては、ここでは触れません。
+
+## HTML および LaTeX のレイアウト機能
+
+ファイルが置かれているディレクトリに layouts/layout.html.erb を置くと、デフォルトの HTML テンプレートの代わりにその HTML が使われます（erb 記法で記述します）。
 
 例:
 
 ```
-locale: ja
-image: イメージ
-table: テーブル
+<html>
+  <head>
+    <title><%= @config["booktitle"] %></title>
+  </head>
+  <body>
+    <%= @body %>
+    <hr/>
+  </body>
+</html>
 ```
+
+同様に、layouts/layout.tex.erb で、デフォルトの LaTeX テンプレートを置き換えることができます。