review 1.4.0 → 1.5.0

data/doc/catalog.rdoc

@@ -1,49 +0,0 @@
-= Re:VIEW カタログファイル ガイド
-
-Re:VIEW のカタログファイル catalog.ymlについて説明します。
-
-== カタログファイルとは
-
-Re:VIEW フォーマットで記述された各ファイルを特に一冊の本（例えばpdfやepub）にまとめる際に、どのようにそれらのファイルを構造化するかを指定するファイルです。
-現在はカタログファイルと言えばcatalog.ymlのことを指します。
-
-== catalog.ymlを用いた場合の設定方法
-
-catalog.yml内で、PREDEF（前付け）、CHAPS（本編）、APPENDIX（付録）、POSTDEF（後付け）を記述します。CHAPSのみ必須です。
-
-  PREDEF:
-    - intro.re
-  
-  CHAPS:
-    - ch01.re
-    - ch02.re
-  
-  APPENDIX:
-    - appendix.re
-  
-  POSTDEF:
-    - postscript.re
-
-本編に対して、「部」構成を加えたい場合、CHAPSを段階的にして記述します。部の指定については、タイトル名でもファイル名でもどちらでも使えます。
-
-  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/format.rdoc

@@ -1,618 +0,0 @@
-= Re:VIEW フォーマット
-
-Re:VIEW フォーマットの文法について解説します。Re:VIEW
-フォーマットは ASCII の EWB を基本としながら、一部に
-RD や各種 Wiki の文法をとりいれて簡素化しています。
-
-== 段落
-
-段落(本文)の間は英語の段落のように1行空けます。
-
-例:
-
-    だんらくだんらく〜〜〜
-    この行も同じ段落
-
-    次の段落〜〜〜
-
-2行以上空いている場合も1行空きと同様に処理します。
-
-== 章・節・項・段(見出し)
-
-章・節・項・段など、見出しは「=」「==」「===」「====」「=====」です。6 レベル以上は使えません。
-
-例:
-
-    = 章のキャプション
-
-    == 節のキャプション
-
-    === 項のキャプション
-
-    ==== 段のキャプション
-
-    ===== 小段のキャプション
-
-見出しは行の先頭から始める必要があります。行頭に空白が入ると、ただの本文とみなされます。
-
-== コラムなど
-
-節や項の見出しに [column] を追加するとコラムのキャプションになります。
-
-例:
-
-    ===[column] コンパイラコンパイラ
-
-このとき、「=」と「[column]」は間を開けず、必ず続けて書かなければ
-なりません。空白があってもいけません。
-
-次の節や項を待たずにコラムを終了する場合は、「===[/column]」を記述します。
-
-例:
-
-    ===[column] コンパイラコンパイラ
-
-    コラムの内容
-
-    ===[/column]
-
-== 箇条書き
-
-箇条書き (HTML で言う ul) は「*」で表現します。
-ネストは「**」のように深さに応じて数を増やします。
-
-例:
-
-  * 第一の項目
-  ** 第一の項目のネスト
-  * 第二の項目
-  ** 第二の項目のネスト
-  * 第三の項目
-
-箇条書きを書くには、行頭に1つ以上の空白を必ず入れるようにします。
-行頭に空白を入れず「*」を書くと、ただのテキストとみなされます。
-
-== 番号付き箇条書き
-
-番号付きの箇条書き (HTML で言う ol) は「1. 〜」「2. 〜」
-「3. 〜」で示します。ネストはしません。
-
-例:
-
-  1. 第一の条件
-  2. 第二の条件
-  3. 第三の条件
-
-番号付き箇条書きも、ただの箇条書きと同様、行頭に1つ以上の空白が必要です。
-
-== 用語リスト
-
-用語リスト (HTML で言う dl) は「:」と、続く空白で始まる行を使って示します。
-
-例:
-
-    : Alpha
-        DEC の作っていた RISC CPU。
-        浮動小数点数演算が速い。
-    : POWER
-        IBM とモトローラが共同製作した RISC CPU。
-        派生として POWER PC がある。
-    : SPARC
-        Sun が作っている RISC CPU。
-        CPU 数を増やすのが得意。
-
-頭の「:」それ自体はテキストではないので注意してください。
-その後に続く文字列が用語名(HTMLではdt要素)になります。
-
-用語リストの「:」ではじまる行は、行頭に空白があってもなくてもかまいません。
-そして、その行以降、空白で始まる行が用語内容(HTMLではdd要素)になります。
-
-また、リスト内でも後述するインライン命令は有効です。
-
-== ソースコードなどのリスト
-
-ソースコードリストにはキャプションの付くリストとキャプションの付かないリストがあります。
-連番つきリストは「//list[識別子][キャプション]{ 〜 //}」で、
-連番なしリストは「//emlist[キャプション]{ 〜 //}」です。
-//emlistのキャプションは省略できます。
-
-例:
-
-  //list[main][main()]{    ←「main」が識別子で「main()」がキャプション
-  int
-  main(int argc, char **argv)
-  {
-      puts("OK");
-      return 0;
-  }
-  //}
-
-例:
-
-  //emlist{
-  printf("hello");
-  //}
-
-ブロック内でも後述するインライン命令は有効です。
-
-また本文中で「リスト X を見てください」のようにリストを指定
-する場合は、//list で指定した識別子を使って「@<list>{main}」
-と表記します。
-
-=== ソースコード専用の引用
-
-ソースコードを引用する場合、ファイル名が必要です。
-
-例:
-
-  //source[/hello/world.rb]{
-   puts "hello world!"
-  //}
-
-ソースコードの引用は、キャプションをつけた//emlistとあまり違いはありません。
-が、HTMLのCSSなどでは区別した表現ができます。
-
-== 行番号付き連番ありリスト
-
-連番ありのリスト(list)で自動的に行番号がつきます。
-
-例:
-
-  //listnum[hello][ハローワールド]{
-   puts "hello world!"
-  //}
-
-参照方法はlistと変わりません。
-
-例:
-
-  ..は@<list>{hello}をみてください。
-
-== 行番号付き連番なしリスト
-
-連番なしのリスト(emlist)で自動的に行番号がつきます。
-
-例:
-
-  //emlistnum{
-   puts "hello world!"
-  //}
-
-== 本文中でのソースコード引用
-
-本文中でソースコードを引用して記述します。
-
-例:
-
-  @<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>
-
-== 部タイトル取得(目次生成機能)
-
-PART ファイルに定義してください。
-PART ファイルは CHAPS の部わけと対応しています。
-
-例:
-
-CHAPS:
-  intro.re
-  
-  start.re
-
-  end.re
-
-PART:
-  (序章なので空行)
-  はじまりの部
-  おわりの部
-
-== 見出し参照
-
-見出し番号と見出しを生成します。
-見出しの階層は"|"で区切って指定してください。
-
-例:
-
-  @<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: テーブル