doc/format.rdoc in review-0.9.0 vs doc/format.rdoc in review-1.0.0
- old
+ new
@@ -7,11 +7,11 @@
== 段落
段落(本文)の間は英語の段落のように1行空けます。ただし、組版に
まわすときは前処理して1段落を1行に変更してあります。
-[例]
+例:
だんらくだんらく〜〜〜
この行も同じ段落
次の段落〜〜〜
@@ -20,11 +20,11 @@
== 章・節・項・段(見出し)
章・節・項・段など、見出しは「=」「==」「===」「====」「=====」です。6 レベル以上は使えません。
-[例]
+例:
= 章のキャプション
== 節のキャプション
@@ -38,37 +38,49 @@
== コラムなど
節や項の見出しに [column] を追加するとコラムのキャプションになります。
-[例]
+例:
===[column] コンパイラコンパイラ
このとき、「=」と「[column]」は間を開けず、必ず続けて書かなければ
なりません。空白があってもいけません。
+次の節や項を待たずにコラムを終了する場合は、「===[/column]」を記述します。
+
+例:
+
+ ===[column] コンパイラコンパイラ
+
+ コラムの内容
+
+ ===[/column]
+
== 箇条書き
箇条書き (HTML で言う ul) は「*」で表現します。
-ネストはしません。
+ネストは「**」のように深さに応じて数を増やします。
-[例]
+例:
* 第一の項目
+ ** 第一の項目のネスト
* 第二の項目
+ ** 第二の項目のネスト
* 第三の項目
箇条書きを書くには、行頭に1つ以上の空白を必ず入れるようにします。
行頭に空白を入れず「*」を書くと、ただのテキストとみなされます。
== 番号付き箇条書き
番号付きの箇条書き (HTML で言う ol) は「1. 〜」「2. 〜」
「3. 〜」で示します。ネストはしません。
-[例]
+例:
1. 第一の条件
2. 第二の条件
3. 第三の条件
@@ -76,11 +88,11 @@
== 用語リスト
用語リスト (HTML で言う dl) は「:」と、続く空白で始まる行を使って示します。
-[例]
+例:
: Alpha
DEC の作っていた RISC CPU。
浮動小数点数演算が速い。
: POWER
@@ -103,22 +115,22 @@
ソースコードリストにはキャプションの付くリストとキャプションの付かないリストがあります。
連番つきリストは「//list[識別子][キャプション]{ 〜 //}」で、
連番なしリストは「//emlist[キャプション]{ 〜 //}」です。
//emlistのキャプションは省略できます。
-[例]
+例:
//list[main][main()]{ ←「main」が識別子で「main()」がキャプション
int
main(int argc, char **argv)
{
puts("OK");
return 0;
}
//}
-[例]
+例:
//emlist{
printf("hello");
//}
@@ -130,11 +142,11 @@
=== ソースコード専用の引用
ソースコードを引用する場合、ファイル名が必要です。
-[例]
+例:
//source[/hello/world.rb]{
puts "hello world!"
//}
@@ -143,45 +155,45 @@
== 行番号付き連番ありリスト
連番ありのリスト(list)で自動的に行番号がつきます。
-[例]
+例:
//listnum[hello][ハローワールド]{
puts "hello world!"
//}
参照方法はlistと変わりません。
-[例]
+例:
..は@<list>{hello}をみてください。
== 行番号付き連番なしリスト
連番なしのリスト(emlist)で自動的に行番号がつきます。
-[例]
+例:
//emlistnum{
puts "hello world!"
//}
== 本文中でのソースコード引用
本文中でソースコードを引用して記述します。
-[例]
+例:
@<code>{p = obj.ref_cnt}
== コマンドラインのキャプチャ
コマンドラインの操作を示すときは //cmd{ 〜 //} を使います。
-[例]
+例:
//cmd{
$ ls /
//}
@@ -191,20 +203,20 @@
図は //image{ 〜 //} で指定します。執筆中はアスキーアートで
代替しているため、ダミーのアスキーアートが入っていることがあり
ます。この部分は、組版時には単に無視してください。
-[例]
+例:
//image[unixhistory][UNIX系OSの簡単な系譜]{
- System V 系列
- +----------- SVr4 --> 各種商用UNIX（Solaris, AIX, HP-UX, ...）
+ System V 系列
+ +----------- SVr4 --> 各種商用UNIX（Solaris, AIX, HP-UX, ...）
V1 --> V6 --|
- +--------- 4.4BSD --> FreeBSD, NetBSD, OpenBSD, ...
- BSD 系列
-
- --------------> Linux
+ +--------- 4.4BSD --> FreeBSD, NetBSD, OpenBSD, ...
+ BSD 系列
+
+ --------------> Linux
//}
3番目の引数として、画像の倍率・大きさを指定することができます。
今のところ「scale=X」で倍率(X倍)が指定できます。
@@ -216,33 +228,45 @@
== 番号が振られていない図
//indepimage[ファイル名][キャプション] で番号が振られていない画像ファイルを生成します。キャプションは省略できます。
-[例]
+例:
//indepimage[unixhistory2]
同様のことは、//numberlessimageでも使えます。
-[例]
+例:
//numberlessimage[door_image_path][扉絵]
-※ただし、//indepimageと機能的にかぶっているので、将来は廃止され、//indexpimageに統合される予定です。
+※ただし、//indepimageと機能的にかぶっているので、将来は廃止され、//indepimageに統合される予定です。
+== グラフ表現ツールを使った図
+
+//graph[ファイル名][コマンド名][キャプション] で各種グラフ表現ツールを使った画像ファイルの生成ができます。キャプションは省略できます。
+
+例: gnuplotの使用
+
+ //graph[sin_x][gnuplot]{
+ plot sin(x)
+ //}
+
+コマンド名には、「graphviz」「gnuplot」「blockdiag」「aafigure」のいずれかを指定できます。ツールはそれぞれ別途インストールする必要があります。
+
== 表
表は //table[識別子][キャプション]{ 〜 //} です。ヘッダと内容を
分ける罫線は「------」で書き込んであります。
カラム間は任意個数のタブで区切ります。また、カラム先頭の「.」は削
除されるので、カラムの先頭文字が「.」の場合は「.」をもう一つ余計に
付けてください。例えば「.」という内容のカラムは「..」と書きます。
また、空のカラムは「.」と書けます。
-[例]
+例:
//table[envvars][重要な環境変数]{
名前 意味
-------------------------------------------------------------
PATH コマンドの存在するディレクトリ
@@ -263,11 +287,11 @@
== 引用
引用は「//quote{ 〜 //}」を使って記述します。
-[例]
+例:
//quote{
百聞は一見に如かず。
//}
@@ -276,11 +300,11 @@
== 脚注
脚注は「//footnote」を使って記述します。
-[例]
+例:
パッケージは本書のサポートサイトから入手できます@<fn>{site}。
各自ダウンロードしてインストールしておいてください。
//footnote[site][本書のサポートサイト： http://i.loveruby.net/ja/stdcompiler ]
@@ -292,42 +316,42 @@
参考文献は同一ディレクトリ内の bib.re に定義します。
//bibpaper[site][キャプション]{..コメント..}
コメントが無い場合も定義可能です。
//bibpaper[site][キャプション]
-[例]
+例:
//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)
//}
@@ -343,20 +367,46 @@
以前は「//comment」というタグがありましたが、廃止されます。
最終結果に出力されないコメントを記述したい場合は「#@#」を使ってください。
-[例]
+例:
#@# ここで 1 行あける
また、修正が必要な警告的コメントには#@warn(...)を使ってください。
-[例]
+例:
#@warn(あとで書く)
+== 生データ行
+
+ReVIEW のタグ範囲を越えて何か特別な行を挿入したい場合、//raw を使います。
+
+例:
+
+ //raw[|html|<div class="special">\nここは特別な行です。\n</div>]
+
+「|ビルダ名|そのまま出力させる内容」という書式です。
+
+ビルダ名には「html」「latex」「idgxml」「top」のいずれかが入り、(複数のビルダにまたがる指定が必要かは別として)「,」で区切って複数指定することも可能です。
+「バックスラッシュ+n」は改行に変換されます。
+該当のビルダを使用しているときのみ、内容が出力されます。
+
+例:
+
+ (HTMLビルダの場合:)
+ <div class="special">
+ ここは特別な行です。
+ </div>
+
+ (ほかのビルダの場合は単に無視されて何も出力されない)
+
+//raw およびこの後に紹介する @<raw> インラインタグは、誤った内容を入れると
+構造化文書を容易に破壊し得ることに注意してください。
+
== その他の文法
ReVIEW は任意のブロックを追加可能なので、本によって専用ブロックを
使う場合があります。これまでに使った例を以下に示します。
@@ -387,11 +437,11 @@
@<br>{}:: 段落中改行。
@<m>{a + \alpha}:: TeXインライン式。
@<icon>{samplephoto}:: インライン画像。
@<uchar>{2460}:: Unicode文字の出力。引数は16進数で指定する。
@<href>{http://www.google.com/}:: リンク。URLで指定できる
-@<raw>{@<foo>{bar\}}:: そのまま出力する。「}」は「\」でエスケープする。
+@<raw>{|ビルダ名|<span>★</span>}:: そのまま出力する。「}」は「バックスラッシュ+}」でエスケープする。ビルダ名は「html」「latex」「idgxml」「top」のいずれかで、「,」で区切って複数指定することも可能。該当のビルダを使用時のみ、出力される。内容に「バックスラッシュ+n」を入れると改行に変換される。
== 著者用タグ (プリプロセッサ命令)
これまでに説明したタグはすべて最終段階まで残り、見ために
影響を与えます。それに対して以下のタグは著者が使うための
@@ -407,22 +457,16 @@
== HTMLのレイアウト機能
CHAPSファイルが置かれているディレクトリに layouts/layout.erb
を置くとその html を ERB で評価します。
-[例]
+例:
<html>
<head>
<title><%= title %></title>
</head>
-[例]
-
- <html>
- <head>
- <title><%= title %></title>
- </head>
<body>
<%= body %>
<hr/>
</body>
</html>
@@ -430,11 +474,11 @@
== 部タイトル取得(目次生成機能)
PART ファイルに定義してください。
PART ファイルは CHAPS の部わけと対応しています。
-[例]
+例:
CHAPS:
intro.re
start.re
@@ -449,29 +493,50 @@
== 見出し参照
見出し番号と見出しを生成します。
見出しの階層は"|"で区切って指定してください。
-[例]
+例:
@<hd>{はじめに|まずわ}
他の章を参照したい場合は、先頭に章のidを指定してください。
-[例]
+例:
@<hd>{preface|はじめに|まずわ}
== リンク
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)
+
+ReVIEWが出力する文字列(「第◯章」「図」「表」など）を、指定した言語に
+合わせて出力することができます。デフォルトは日本語です。
+
+CHAPS などと同じディレクトリに locale.yaml というファイルを用意して、
+以下のように記述します（日本語の場合）。
+
+例:
+
+ locale: ja
+
+既存の表記を書き換えたい場合は、該当する項目を上書きします。
+既存の設定ファイルは lib/review/i18n.yaml にあります。
+
+例:
+
+ locale: ja
+ image: イメージ
+ table: テーブル