review 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7003949429e45e08f404dd70af9d6cbe419d6b74
-  data.tar.gz: 081d336549a9141b9172c1dd1f0cc673bce73bbf
+  metadata.gz: aaa0a3b0a265168c14172ed379cbf7410cdb7dc9
+  data.tar.gz: b598d3083be1ab3bc3380a9c5f27d258e4a66e4b
 SHA512:
-  metadata.gz: 2b74a8d6ff2b7258b7fbcb51b27f2417f066734a96ec86cd75cc0a3d15d91c9d958630e4ed88519d3a0cde307309a08f124231cd0409b093ba337a7fab0c1544
-  data.tar.gz: 2fa797cd9ff23cddc563440e07d03de0fd75a130ca73ea7b5192a03175e2e79135c7c6b75e33ae1413981f595b64e69029531f4e499a2119603e84d62f8596a8
+  metadata.gz: 18250a41bc4a1f1cf496dd882fd0acf2872488251200cb9b9188a0e371e3859725b446229d47896d6248f517368fd3da0df3062021465ab26d60f1a14a441541
+  data.tar.gz: 5c5f8250df19b7a18b2da44e2f030e8be7b2cd03fbfa15ac04b29dbb00067f8085dc9d26d7a3792726ae28ca7244b4c24bf6e83ea90dc87ef5f33d11911185e1

data/.gitignore

@@ -25,7 +25,7 @@ build/
 
 # for a library or gem, you might want to ignore these files since the code is
 # intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
+Gemfile.lock
 # .ruby-version
 # .ruby-gemset
 

data/.travis.yml

@@ -3,6 +3,7 @@ rvm:
   - 1.9.3
   - 2.0.0
   - 2.1.*
+  - 2.2.*
 
 branches:
   only:

data/ChangeLog

@@ -1,3 +1,90 @@
+Sat Feb 28 19:51:29 2015  KADO Masanori  <kdmsnr@gmail.com>
+
+	* Release 1.5.0.
+
+Sun Feb  1 20:17:22 2015  Kenshi Muto  <kmuto@debian.org>
+
+	* bin/review-epubmaker:
+	  Introduce structured YAML tree.
+
+	  Some epubmaker-specific configurations are moved under "epubmaker:".
+	  You can still keep to use parameters for compatibility,
+	  but you'll get a 'deprecated' warning message.
+	
+	epubmaker:
+	  ncxindent: ...
+	  flattoc: ...
+	  flattocindent: ...
+	  hook_beforeprocess: ...
+	  hook_afterfrontmatter: ...
+	  hook_afterbody: ...
+	  hook_afterbackmatter: ...
+	  hook_aftercopyimage] ...
+	  hook_prepack] ...
+	  rename_for_legacy: ...
+	  zip_stage1: ...
+	  zip_stage2: ...
+	  zip_addpath: ...
+	  verify_target_images: ...
+	  force_include_images: ...
+	  cover_linear: ...
+
+	* bin/review-pdfmaker:
+	  Introduce structured YAML tree and new hooks.
+
+	pdfmaker:
+	  hook_beforetexcompile: ... (before LaTeX compiling)
+	  hook_aftertexcompile: ... (after all of LaTeX compiling)
+	  hook_afterdvipdf: ... (after dvipdfm conversion)
+
+	  These hooks get two arguments. $1 is temporary build directory.
+	  $2 is the base directory (where you executed review-pdfmaker).
+
+Mon Jan 26 20:29:30 2015  Masayoshi Takahashi  <takahashimm@gmail.com>
+
+	* lib/review/i18n.rb:
+	  To initialize after loading config.yml, modifiy API I18n.setup
+	  and remove I18n.i18n.
+
+Tue Jan 13 19:26:04 2015  Masayoshi Takahashi  <takahashimm@gmail.com>
+
+	* lib/review/pdfmaker.rb:
+	  review-pdfmaker removes a PDF file if already exists
+
+	  As a PDF file can be re-generated from source files, review-pdfmaker
+	  remove the file when the file exists rather than exiting with error.
+	  review-epubmaker do the same way.
+
+Tue Dec  9 15:25:38 2014  Masayoshi Takahashi  <takahashimm@gmail.com>
+
+	* lib/review/configure.rb:
+	  update default value of "toc" as nil.
+	  If you need TOC page in body, you should add "toc: true" in config.yml (EPUB2/3, LaTeX).
+
+Tue Dec  9 10:27:21 2014  Masayoshi Takahashi  <takahashimm@gmail.com>
+
+	* bin/review-vol:
+	  add --yaml option to specify config.yml
+	  add a parameter `page_metric` in config.yml
+
+Sun Dec  7 16:57:01 2014  Masayoshi Takahashi  <takahashimm@gmail.com>
+
+	* lib/review/book/chapter.rb, test/test_book_chapter.rb:
+	  remove Chapter.intern_pathes.
+	  To get chapters, use Book::Base.load and Book::Base#chapter.
+
+Mon Nov 17 09:28:21 2014  Kenshi Muto  <kmuto@debian.org>
+
+	* lib/review/book/chapter.rb, lib/review/book/index.rb:
+	fix @<hd> to show appendix correctly with respecting
+	appendix_format yaml parameter.
+
+Wed Nov  5 19:11:02 2014  Kenshi Muto  <kmuto@debian.org>
+
+	* lib/review/idgxmlbuilder.rb, test/test_idgxmlbuilder.rb:
+	  stop providing a index from @<ttb>.
+	  That behavior just makes a confuse.
+
 Wed Oct 29 18:54:28 2014  KADO Masanori  <kdmsnr@gmail.com>
 
 	* Release 1.4.0.

data/bin/review-check

@@ -37,7 +37,7 @@ def main
     "inencoding" => "UTF-8",
     "outencoding" => "UTF-8"
   })
-  @book = ReVIEW::Book::Base.load_default
+  @book = ReVIEW::Book::Base.load
   @book.config = @config
 
   modes = nil
@@ -54,7 +54,7 @@ def main
     files = @book.chapters.map {|ent| ent.path }
   }
   opts.on('-s', '--section N', 'Check section N. (deprecated)') {|n|
-    ents = ReVIEW.env.parts[Integer(n) - 1] or
+    ents = @book.parts[Integer(n) - 1] or
         raise ReVIEW::ApplicationError, "section #{n} not exist"
     files = ents.map {|ent| ent.path }
   }

data/bin/review-compile

@@ -19,6 +19,7 @@ $LOAD_PATH.unshift((bindir + '../lib').realpath)
 require 'review'
 require 'review/compiler'
 require 'review/book'
+require 'review/i18n'
 require 'fileutils'
 require 'optparse'
 
@@ -143,8 +144,8 @@ def _main
 
   begin
     config["builder"] = target
+    ReVIEW::I18n.setup(config["language"])
 
-    compiler = ReVIEW::Compiler.new(load_strategy_class(target, check_only))
     case mode
     when :files
       if ARGV.empty?
@@ -152,37 +153,24 @@ def _main
         exit 1
       end
 
-      begin
-        ReVIEW::Book::Chapter.intern_pathes(ARGV).each do |chap|
-          chap.book.config = config # needs only at the first time
-          result = compiler.compile(chap)
-          if output_filename
-            write output_filename, result
-          else
-            puts result unless check_only
-          end
-        end
-      rescue => e
-        # PART
-        book = ReVIEW::Book::Base.load_default
-        book.config = config
-        part = book.parts_in_file.select do |part_item|
-          ARGV.map{|path| File.basename path}.include? part_item.path
-        end
-        if part.present?
-          result = compiler.compile(part.first)
-          if output_filename
-            write output_filename, result
-          else
-            puts result unless check_only
-          end
+      basedir = File.dirname(ARGV[0])
+      book = ReVIEW::Book::Base.load(basedir)
+      book.config = config # needs only at the first time
+      ARGV.each do |item|
+        chap_name = File.basename(item, '.*')
+        chap = book.chapter(chap_name)
+        compiler = ReVIEW::Compiler.new(load_strategy_class(target, check_only))
+        result = compiler.compile(chap)
+        if output_filename
+          write output_filename, result
         else
-          raise e
+          puts result unless check_only
         end
       end
     when :dir
-      book = basedir ? ReVIEW::Book.load(basedir) : ReVIEW::Book::Base.load_default
+      book = basedir ? ReVIEW::Book.load(basedir) : ReVIEW::Book::Base.load
       book.config = config
+      compiler = ReVIEW::Compiler.new(load_strategy_class(target, check_only))
       book.chapters.each do |chap|
         str = compiler.compile(chap)
         write "#{chap.name}#{compiler.strategy.extname}", str  unless check_only
@@ -190,9 +178,6 @@ def _main
       # PART
       book.parts_in_file.each do |part|
         str = compiler.compile(part)
-        if compiler.strategy.extname == ".tex"
-          str.gsub!(/\A\\chapter\{/, '\part{') # FIXME: UGLY...
-        end
         write "#{part.name}#{compiler.strategy.extname}", str  unless check_only
       end
     else

data/bin/review-index

@@ -41,7 +41,7 @@ def _main
     "inencoding" => "UTF-8",
     "outencoding" => "UTF-8"
   }
-  book = ReVIEW::Book::Base.load_default
+  book = ReVIEW::Book::Base.load
 
   opts = OptionParser.new
   opts.version = ReVIEW::VERSION

data/bin/review-init

@@ -20,11 +20,14 @@ require 'review/version'
 def main
   opts = OptionParser.new
   opts.version = ReVIEW::VERSION
-  opts.banner = "Usage: #{File.basename($0)} dirname"
+  opts.banner = "Usage: #{File.basename($0)} [option] dirname"
   opts.on('-h', '--help', 'print this message and quit.') {
     puts opts.help
     exit 0
   }
+  opts.on('-f', '--force', 'generate files (except *.re) if directory has already existed.') {
+    @force = true
+  }
   begin
     opts.parse!
   rescue OptionParser::ParseError => err
@@ -55,7 +58,7 @@ def main
 end
 
 def generate_dir(dir)
-  if File.exist? dir
+  if File.exist?(dir) && !@force
     puts "#{dir} already exists."
     exit
   end
@@ -64,13 +67,15 @@ def generate_dir(dir)
 end
 
 def generate_sample(dir)
-  File.open("#{dir}/#{File.basename(dir)}.re", "w") do |file|
-    file.write("= ")
+  if !@force
+    File.open("#{dir}/#{File.basename(dir)}.re", "w") do |file|
+      file.write("= ")
+    end
   end
 end
 
 def generate_layout(dir)
-  Dir.mkdir dir + '/layouts'
+  FileUtils.mkdir_p dir + '/layouts'
   File.open("#{dir}/layouts/layout.html.erb", "w") do |file|
     file.write <<-EOS
 <?xml version="1.0" encoding="UTF-8"?>
@@ -108,7 +113,7 @@ EOS
 end
 
 def generate_images_dir(dir)
-  Dir.mkdir dir + '/images'
+  FileUtils.mkdir_p dir + '/images'
 end
 
 def generate_cover_image(dir)
@@ -125,7 +130,7 @@ end
 
 def generate_texmacro(dir)
   texmacrodir = dir + '/sty'
-  Dir.mkdir texmacrodir
+  FileUtils.mkdir_p texmacrodir
   FileUtils.cp @review_dir + "/test/sample-book/src/sty/reviewmacro.sty", texmacrodir
 end
 

data/bin/review-vol

@@ -31,8 +31,12 @@ def main
 
   part_sensitive = false
   basedir = nil
+  yamlfile = nil
   opts = OptionParser.new
   opts.version = ReVIEW::VERSION
+  opts.on('--yaml=YAML', 'Read configurations from YAML file.') do |yaml|
+    yamlfile = yaml
+  end
   opts.on('-P', '--part-sensitive', 'Prints volume of each parts.') {
     part_sensitive = true
   }
@@ -57,8 +61,12 @@ def main
     exit 1
   end
 
-  book = basedir ? ReVIEW::Book.load(basedir) : ReVIEW::Book::Base.load_default
+  book = basedir ? ReVIEW::Book.load(basedir) : ReVIEW::Book::Base.load
   book.config = @config
+  if yamlfile
+    book.load_config(yamlfile)
+  end
+
   if part_sensitive
     sep = ""
     book.each_part do |part|

data/doc/catalog.ja.md

@@ -0,0 +1,53 @@
+# Re:VIEW カタログファイル ガイド
+
+Re:VIEW のカタログファイル catalog.ymlについて説明します。
+
+## カタログファイルとは
+
+Re:VIEW フォーマットで記述された各ファイルを特に一冊の本（例えばPDFやEPUB）にまとめる際に、どのようにそれらのファイルを構造化するかを指定するファイルです。
+現在はカタログファイルと言えばcatalog.ymlのことを指します。
+
+## catalog.ymlを用いた場合の設定方法
+
+catalog.yml内で、`PREDEF`（前付け）、`CHAPS`（本編）、`APPENDIX`（付録、連番あり）、`POSTDEF`（後付け、連番なし）を記述します。CHAPSのみ必須です。
+
+```yaml
+PREDEF:
+  - intro.re
+
+CHAPS:
+  - ch01.re
+  - ch02.re
+
+APPENDIX:
+  - appendix.re
+
+POSTDEF:
+  - postscript.re
+```
+
+本編に対して、「部」構成を加えたい場合、`CHAPS`を段階的にして記述します。部の指定については、タイトル名でもファイル名でもどちらでも使えます。
+
+```yaml
+CHAPS:
+  - ch01.re
+  - 第1部:
+    - ch02.re
+    - ch03.re
+  - pt02.re:
+    - ch04.re
+```
+
+（旧バージョンの利用者の方へ: `PART`という項目はありません。`CHAPS`に記述してください）
+
+## バージョン 1.3以前について
+
+`APPENDIX`は指定できません。`POSTDEF`を使ってください。
+
+## バージョン 1.2以前について
+
+1.2以前のRe:VIEWではカタログファイルとしてPREDEF, CHAPS, POSTDEF, PARTという独立した4つのファイルを使用していました。
+そのため、当時のバージョンを利用する際にはcatalog.ymlではなくそちらを記述する必要があります。
+
+現在のRe:VIEWはcatalog.ymlを用いた方法と旧バージョンが使用していたCHAPS, PREDEF, POSTDEF, PARTを用いた方法と両方をサポートしています。
+ただしcatalog.ymlが存在する場合、そちらが優先されます。

data/doc/catalog.md

@@ -0,0 +1,52 @@
+# Re:VIEW catalog.yml Guide
+
+This article describes Re:VIEW catalog file catalog.yml.
+
+## What's catalog.yml
+
+Catalog file shows the structure of files to generate books (such as PDF or EPUB) in Re:VIEW format.
+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.
+
+```yaml
+  PREDEF:
+    - intro.re
+  
+  CHAPS:
+    - ch01.re
+    - ch02.re
+  
+  APPENDIX:
+    - appendix.re
+  
+  POSTDEF:
+    - postscript.re
+```
+
+You can add parts in body to use `CHAPS` in a hierarchy. You can use both title name and file name to specify parts.
+
+```yaml
+  CHAPS:
+    - ch01.re
+    - TITLE_OF_PART1:
+      - ch02.re
+      - ch03.re
+    - pt02.re:
+      - ch04.re
+```
+
+(For old version user: there is no `PART`. You write them in `CHAPS`.)
+
+## About version 1.3 or earlier
+
+You can not use `APPENDIX`. Use `POSTDEF`.
+
+## 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.

data/doc/format.ja.md

@@ -0,0 +1,734 @@
+# Re:VIEW フォーマットガイド
+
+Re:VIEW フォーマットの文法について解説します。Re:VIEW
+フォーマットは ASCII の EWB を基本としながら、一部に
+RD や各種 Wiki の文法をとりいれて簡素化しています。
+
+## 段落
+
+段落(本文)の間は英語の段落のように1行空けます。
+
+例:
+
+```
+だんらくだんらく〜〜〜
+この行も同じ段落
+
+次の段落〜〜〜
+```
+
+2行以上空いている場合も1行空きと同様に処理します。
+
+## 章・節・項・段(見出し)
+
+章・節・項・段など、見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」です。6 レベル以上は使えません。
+
+例:
+
+```review
+= 章のキャプション
+
+== 節のキャプション
+
+=== 項のキャプション
+
+==== 段のキャプション
+
+===== 小段のキャプション
+```
+
+見出しは行の先頭から始める必要があります。行頭に空白が入ると、ただの本文とみなされます。
+
+## コラムなど
+
+節や項の見出しに `[column]` を追加するとコラムのキャプションになります。
+
+例:
+
+```review
+===[column] コンパイラコンパイラ
+```
+
+このとき、「=」と「[column]」は間を開けず、必ず続けて書かなければ
+なりません。空白があってもいけません。
+
+次の節や項を待たずにコラムを終了する場合は、「===[/column]」を記述します。
+
+例:
+
+```review
+===[column] コンパイラコンパイラ
+
+コラムの内容
+
+===[/column]
+```
+
+## 箇条書き
+
+箇条書き (HTML で言う ul) は「` *`」で表現します。
+ネストは「` **`」のように深さに応じて数を増やします。
+
+例:
+
+```
+* 第一の項目
+** 第一の項目のネスト
+* 第二の項目
+** 第二の項目のネスト
+* 第三の項目
+```
+
+箇条書きを書くには、行頭に1つ以上の空白を必ず入れるようにします。
+行頭に空白を入れず「*」を書くと、ただのテキストとみなされます。
+
+## 番号付き箇条書き
+
+番号付きの箇条書き (HTML で言う ol) は「` 1. 〜`」「` 2. 〜`」
+「` 3. 〜`」で示します。ネストはしません。
+
+例:
+
+
+```
+1. 第一の条件
+2. 第二の条件
+3. 第三の条件
+```
+
+番号付き箇条書きも、ただの箇条書きと同様、行頭に1つ以上の空白が必要です。
+
+## 用語リスト
+
+用語リスト (HTML で言う dl) は「:」と、続く空白で始まる行を使って示します。
+
+例:
+
+```review
+: Alpha
+    DEC の作っていた RISC CPU。
+    浮動小数点数演算が速い。
+: POWER
+    IBM とモトローラが共同製作した RISC CPU。
+    派生として POWER PC がある。
+: SPARC
+    Sun が作っている RISC CPU。
+    CPU 数を増やすのが得意。
+```
+
+頭の「`:`」それ自体はテキストではないので注意してください。
+その後に続く文字列が用語名(HTMLではdt要素)になります。
+
+用語リストの「`:`」ではじまる行は、行頭に空白があってもなくてもかまいません。
+そして、その行以降、空白で始まる行が用語内容(HTMLではdd要素)になります。
+
+また、リスト内でも後述するインライン命令は有効です。
+
+## ソースコードなどのリスト
+
+ソースコードなどのリストには`//list`を使います。連番をつけたくない場合は先頭に``em``（embeddedの略）、行番号をつける場合は末尾に``num``を付加します。まとめると以下の4種類になります。
+
+* ``//list[識別子][キャプション][言語指定]{ 〜 //}``
+  * 通常のリスト。言語指定は省略できます。
+* ``//listnum[識別子][キャプション][言語指定]{ 〜 //}``
+  * 通常のリストに行番号をつけたもの。言語指定は省略できます。
+* ``//emlist[キャプション][言語指定]{ 〜 //}``
+  * 連番がないリスト。キャプションと言語指定は省略できます。
+* ``//emlistnum[キャプション][言語指定]{ 〜 //}``
+  * 連番がないリストに行番号をつけたもの。キャプションと言語指定は省略できます。
+
+例:
+
+```review
+//list[main][main()][c]{    ←「main」が識別子で「main()」がキャプション
+int
+main(int argc, char **argv)
+{
+    puts("OK");
+    return 0;
+}
+//}
+```
+
+例:
+
+```review
+//listnum[hello][ハローワールド][ruby]{
+puts "hello world!"
+//}
+```
+
+例:
+
+```review
+//emlist[][ruby]{
+printf("hello");
+//}
+```
+
+例:
+
+```review
+//emlistnum[][ruby]{
+puts "hello world!"
+//}
+```
+
+
+
+ブロック内でも後述するインライン命令は有効です。
+
+また本文中で「リスト X を見てください」のようにリストを指定
+する場合は、`//list` で指定した識別子を使って「`@<list>{main}`」
+と表記します。
+
+### ソースコード専用の引用
+
+ソースコードを引用する場合、ファイル名が必要です。
+
+例:
+
+```review
+//source[/hello/world.rb]{
+puts "hello world!"
+//}
+```
+
+ソースコードの引用は、キャプションをつけた`//emlist`とあまり違いはありません。
+が、HTMLのCSSなどでは区別した表現ができます。
+
+
+参照方法はlistと変わりません。
+
+例:
+
+```
+..は@<list>{hello}をみてください。
+```
+
+## 本文中でのソースコード引用
+
+本文中でソースコードを引用して記述します。
+
+例:
+
+```review
+@<code>{p = obj.ref_cnt}
+```
+
+## コマンドラインのキャプチャ
+
+コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。
+
+例:
+
+```
+//cmd{
+$ ls /
+//}
+```
+
+ブロック内でも後述するインライン命令は有効です。
+
+## 図
+
+図は `//image{ 〜 //}` で指定します。執筆中はアスキーアートで
+代替しているため、ダミーのアスキーアートが入っていることがあり
+ます。この部分は、組版時には単に無視してください。
+
+例:
+
+```
+//image[unixhistory][UNIX系OSの簡単な系譜]{
+          System V 系列
+            +----------- SVr4 --> 各種商用UNIX（Solaris, AIX, HP-UX, ...）
+V1 --> V6 --|
+            +--------- 4.4BSD --> FreeBSD, NetBSD, OpenBSD, ...
+          BSD 系列
+
+                --------------> Linux
+//}
+```
+
+3番目の引数として、画像の倍率・大きさを指定することができます。
+今のところ「scale=X」で倍率(X倍)が指定できます。
+
+また本文中で「図 X を見てください」のように図を指定する場合は、
+`//image` で指定した識別子を用いて「`@<img>{unixhistory}`」と
+記述します。`//image` と `@<img>` でつづりが違うので注意してください。
+
+なお、後述しますが、インラインで図を出力するには`@<icon>`を使用します。
+
+図として貼り込む画像ファイルは、次の順序で探索され、最初に発見されたものが利用されます。
+
+```
+1. <imgdir>/<builder>/<chapid>/<id>.<ext>
+2. <imgdir>/<builder>/<chapid>-<id>.<ext>
+3. <imgdir>/<builder>/<id>.<ext>
+4. <imgdir>/<chapid>/<id>.<ext>
+5. <imgdir>/<chapid>-<id>.<ext>
+6. <imgdir>/<id>.<ext>
+```
+
+* ``<imgdir>`` はデフォルトでは images ディレクトリです。
+* ``<builder>`` は利用しているビルダ名 (ターゲット名) で、たとえば ``--target=html`` としているのであれば、images/html ディレクトリとなります。
+* ``<chapid>`` は re ファイルの名前に相当します。たとえば ch01.re という名前であれば「ch01」です。
+* ``<id>`` は //image[〜] の最初に入れた「〜」のことです (つまり、ID に日本語や空白交じりの文字を使ってしまうと、後で画像ファイル名の名付けに苦労することになります!)。
+* ``<ext>`` は Re:VIEW が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。
+
+## 番号が振られていない図
+
+`//indepimage[ファイル名][キャプション]` で番号が振られていない画像ファイルを生成します。キャプションは省略できます。
+
+例:
+
+```
+//indepimage[unixhistory2]
+```
+
+同様のことは、`//numberlessimage`でも使えます。
+
+例:
+
+```
+//numberlessimage[door_image_path][扉絵]
+```
+
+※ただし、`//indepimage`と機能的にかぶっているので、将来は廃止され、`//indepimage`に統合される予定です。
+
+## グラフ表現ツールを使った図
+
+`//graph[ファイル名][コマンド名][キャプション]` で各種グラフ表現ツールを使った画像ファイルの生成ができます。キャプションは省略できます。
+
+例: gnuplotの使用
+
+```
+//graph[sin_x][gnuplot]{
+plot sin(x)
+//}
+```
+
+コマンド名には、「`graphviz`」「`gnuplot`」「`blockdiag`」「`aafigure`」のいずれかを指定できます。ツールはそれぞれ別途インストールする必要があります。
+
+## 表
+
+表は `//table[識別子][キャプション]{ 〜 //}` です。ヘッダと内容を
+分ける罫線は「`------`」で書き込んであります。
+
+カラム間は任意個数のタブで区切ります。また、カラム先頭の「`.`」は削除されるので、カラムの先頭文字が「`.`」の場合は「`.`」をもう一つ余計に付けてください。例えば「`.`」という内容のカラムは「`..`」と書きます。
+また、空のカラムは「`.`」と書けます。
+
+例:
+
+```
+//table[envvars][重要な環境変数]{
+名前            意味
+-------------------------------------------------------------
+PATH            コマンドの存在するディレクトリ
+TERM            使っている端末の種類。linux・kterm・vt100など
+LANG            ユーザのデフォルトロケール。日本語ならja_JP.eucJPやja_JP.utf8
+LOGNAME         ユーザのログイン名
+TEMP            一時ファイルを置くディレクトリ。/tmpなど
+PAGER           manなどで起動するテキスト閲覧プログラム。lessなど
+EDITOR          デフォルトエディタ。viやemacsなど
+MANPATH         manのソースを置いているディレクトリ
+DISPLAY         X Window Systemのデフォルトディスプレイ
+//}
+```
+
+本文中で「表 X を見てください」のように表を指定する場合は
+`@<table>{envvars}` という表記を使います。
+
+表内でも後述するインライン命令は有効です。
+
+## 引用
+
+引用は「`//quote{ 〜 //}`」を使って記述します。
+
+例:
+
+```
+//quote{
+百聞は一見に如かず。
+//}
+```
+
+引用内でも後述するインライン命令は有効です。
+また、いまのところ引用内で別のブロック構文を使うことはできません。
+
+## 脚注
+
+脚注は「`//footnote`」を使って記述します。
+
+例:
+
+```
+パッケージは本書のサポートサイトから入手できます@<fn>{site}。
+各自ダウンロードしてインストールしておいてください。
+//footnote[site][本書のサポートサイト： http://i.loveruby.net/ja/stdcompiler ]
+```
+
+本文中の「`@<fn>{site}`」は脚注番号に置換され、「本書のサポート
+サイト……」という文は実際の脚注に変換されます。
+
+注意: PDFで、コラムや表など平文でないところで「`@<fn>{～}`」を使うには、`footnotetext`オプションを使う必要があります。
+
+### footnotetextオプション
+
+`footnotetext`オプションを使うには、YAMLファイルの`params`に「`--footnotetext`」を追加します。
+
+これでPDFのコラムや表のなかでも脚注が使えるようになります。
+
+ただし、通常の脚注(footnote)ではなく、footnotemarkとfootnotetextを使うため、
+本文と脚注が別ページに分かれる可能性があるなど、いろいろな制約があります。
+なお、採番が別々になるためfootnoteとfootnotemark/footnotetextを両立させることはできません。
+
+## 参考文献の定義
+
+参考文献は同一ディレクトリ内の bib.re に定義します。
+
+```
+//bibpaper[cite][キャプション]{..コメント..}
+```
+
+コメントが無い場合も定義可能です。
+
+```
+//bibpaper[cite][キャプション]
+```
+
+例:
+
+```
+//bibpaper[lins][Lins, 1991]{
+Refael D. Lins. A shared memory architecture for parallel study of
+algorithums for cyclic reference_counting. Technical Report 92,
+Computing Laboratory, The University of Kent at Canterbury , August
+1991
+//}
+```
+
+本文中で参考文献を参照したい場合は次のようにしてください。
+
+例:
+
+```
+…という研究が知られています(@<bib>{lins})
+```
+
+## リード文
+
+リード文は `//lead{ 〜 //}` で指定します。
+歴史的経緯により`//read{ 〜 //}` でも使えます。
+
+例:
+
+```
+//lead{
+本章ではまずこの本の概要について話し、
+次にLinuxでプログラムを作る方法を説明していきます。
+//}
+```
+
+## TeX式
+
+LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。
+
+例:
+
+```
+//texequation{
+\sum_{i=1}^nf_n(x)
+//}
+```
+
+## 空白制御
+
+出力される空白を制御するタグとしては、`//noindent`があります。
+
+
+* `//noindent` : その直後に来る段落冒頭のインデントをなくす(HTMLではnoindentクラスになる)
+
+
+以前あった「`//linebreak`」(改行)、「`//pagebreak`」(改ページ)は廃止になります。
+
+## コメント
+
+最終結果に出力されないコメントを記述したい場合は「`#@#`」を使ってください。
+
+例:
+
+```
+#@# ここで 1 行あける
+```
+
+また、修正が必要な警告的コメントには`#@warn(...)`を使ってください。
+
+例:
+
+```
+#@warn(あとで書く)
+```
+
+最終結果に出力するコメントを記述したい場合は、`//comment`または`@<comment>`を使った上で、review-compileコマンドに`--draft`オプションを追加してください。
+
+例:
+
+```
+@<comment>{あとで書く}
+```
+
+## 生データ行
+
+Re:VIEW のタグ範囲を越えて何か特別な行を挿入したい場合、`//raw` を使います。
+
+例:
+
+```
+//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
+```
+
+「|ビルダ名|そのまま出力させる内容」という書式です。
+
+ビルダ名には「`html`」「`latex`」「`idgxml`」「`top`」のいずれかが入り、(複数のビルダにまたがる指定が必要かは別として)「,」で区切って複数指定することも可能です。
+「バックスラッシュ+n」は改行に変換されます。
+該当のビルダを使用しているときのみ、内容が出力されます。
+
+例:
+
+```
+(HTMLビルダの場合:)
+<div class="special">
+ここは特別な行です。
+</div>
+
+(ほかのビルダの場合は単に無視されて何も出力されない)
+```
+
+`//raw` およびこの後に紹介する `@<raw>` インラインタグは、誤った内容を入れると
+構造化文書を容易に破壊し得ることに注意してください。
+
+## その他の文法
+
+Re:VIEW は任意のブロックを追加可能なので、本によって専用ブロックを
+使う場合があります。これまでに使った例を以下に示します。
+
+* `//prototype` : 関数プロトタイプ。『ふつうのLinuxプログラミング』で使用。
+* `//type` : 関数の型宣言。『ふつうのHaskellプログラミング』で使用。
+
+拡張文法は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
+```
+
+のようにすると、以下のような文法を追加できます。
+
+```
+//foo{
+A
+B
+C
+//}
+```
+
+```
+# 出力結果
+A,B,C
+```
+
+詳しいことについては、ここでは触れません。
+
+
+## 段落中で使う文法 (インライン命令)
+
+```
+@<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」を入れると改行に変換される。
+```
+
+## 著者用タグ (プリプロセッサ命令)
+
+これまでに説明したタグはすべて最終段階まで残り、見ために
+影響を与えます。それに対して以下のタグは著者が使うための
+専用タグであり、最終段階ではすべて消されてしまいます。
+
+```
+#@#:: コメント。この行には何を書いても無視される。
+#@warn(...):: 警告メッセージ。プリプロセス時にメッセージが出力される。
+#@require, #@provide:: キーワードの依存関係を宣言する。
+#@mapfile(ファイル名) 〜 #@end:: ファイルの内容をその場に展開する。
+#@maprange(ファイル名, 範囲名) 〜 #@end:: ファイル内の範囲をその場に展開する。
+#@mapoutput(コマンド) 〜 #@end:: コマンドを実行して、その出力結果を展開する。
+```
+
+## HTMLのレイアウト機能
+
+CHAPSファイルが置かれているディレクトリに layouts/layout.html.erb
+を置くとその html を ERB で評価します。
+
+例:
+
+```
+<html>
+  <head>
+    <title><%= title %></title>
+  </head>
+  <body>
+    <%= body %>
+    <hr/>
+  </body>
+</html>
+```
+
+## 部タイトル取得(目次生成機能)
+
+Version 1.2以前の場合、PART ファイルに定義してください。
+PART ファイルは CHAPS の部わけと対応しています。
+
+例:
+
+```
+CHAPS:
+  intro.re
+
+  start.re
+
+  end.re
+```
+
+```
+PART:
+  (序章なので空行)
+  はじまりの部
+  おわりの部
+```
+
+Version 1.3以降では、catalog.ymlが使えるようになりました。
+catalog.ymlの使い方については「Re:VIEW カタログファイルガイド」を参照してください。
+
+## 見出し参照
+
+見出し番号と見出しを生成します。
+見出しの階層は"`|`"で区切って指定してください。
+
+例:
+
+```
+@<hd>{はじめに|まずわ}
+```
+
+見出しを一意に特定できる場合は、"`|`"は不要です。
+
+```
+@<hd>{まずわ}
+```
+
+他の章を参照したい場合は、先頭に章のidを指定してください。
+
+例:
+
+```
+@<hd>{preface|はじめに|まずわ}
+```
+
+参照先にラベルが設定されている場合は、ラベルで参照します。
+
+```
+=={hajimeni} はじめに
+:
+=== まずわ
+:
+@<hd>{hajimeni|まずわ}
+```
+
+
+### コラム見出し参照
+
+コラムの見出しの参照は、`@<column>`を使います。
+
+例:
+
+```
+@<column>{Re:VIEWの用途いろいろ}
+```
+
+ラベルでの参照もできます。
+
+```
+==[column]{review-application} Re:VIEWの応用
+:
+@<column>{review-application}
+```
+
+## リンク
+
+Web ハイパーリンクを記述するには、リンクに `@<href>`、アンカーに `//label`
+を使います。リンクの書式は `@<href>{URL, 文字表現}` で、「`, 文字表現`」を
+省略すると URL がそのまま使われます。URL 中に `,` を使いたいときには、`\,`
+と表記してください。
+
+例:
+
+```
+@<href>{http://github.com/, GitHub}
+@<href>{http://www.google.com/}
+@<href>{#point1, ドキュメント内ポイント}
+@<href>{chap1.html#point1, ドキュメント内ポイント}
+//label[point1]
+```
+
+## 国際化(i18n)
+
+Re:VIEWが出力する文字列(「第◯章」「図」「表」など）を、指定した言語に
+合わせて出力することができます。デフォルトは日本語です。
+
+CHAPS などと同じディレクトリに locale.yml というファイルを用意して、
+以下のように記述します（日本語の場合）。
+
+例:
+
+```
+locale: ja
+```
+
+既存の表記を書き換えたい場合は、該当する項目を上書きします。
+既存の設定ファイルは lib/review/i18n.yml にあります。
+
+例:
+
+```
+locale: ja
+image: イメージ
+table: テーブル
+```