doc/format.ja.md in review-2.0.0.beta1 vs doc/format.ja.md in review-2.0.0

- old
+ new

@@ -1,29 +1,30 @@ # Re:VIEW フォーマットガイド -Re:VIEW フォーマットの文法について解説します。Re:VIEW -フォーマットは ASCII の EWB を基本としながら、一部に -RD や各種 Wiki の文法をとりいれて簡素化しています。 +Re:VIEW フォーマットの文法について解説します。Re:VIEW フォーマットはアスキー社（現カドカワ）の EWB を基本としながら、一部に RD や各種 Wiki の文法を取り入れて簡素化しています。 +このドキュメントは、Re:VIEW 2.0 に基づいています。 + ## 段落 -段落(本文)の間は英語の段落のように1行空けます。 +段落（本文）の間は1行空けて表現します。空けずに次の行を記述した場合は、1つの段落として扱われます。 例: ``` だんらくだんらく〜〜〜 この行も同じ段落 次の段落〜〜〜 ``` -2行以上空いている場合も1行空きと同様に処理します。 +* 2行以上空けても、1行空きと同じ意味になります。 +* 空行せずに改行して段落の記述を続ける際、英文の単語間スペースについては考慮されないことに注意してください。Re:VIEW は各行を単純に連結するだけであり、TeX のように前後の単語を判断してスペースを入れるようなことはしません。 -## 章・節・項・段(見出し) +## 章・節・項・段（見出し） -章・節・項・段など、見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」です。6 レベル以上は使えません。 +章・節・項・段といった見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」で表します。6 レベル以上は使えません。`=`のあとにはスペースを入れます。 例: ```review = 章のキャプション @@ -35,26 +36,27 @@ ==== 段のキャプション ===== 小段のキャプション ``` -見出しは行の先頭から始める必要があります。行頭に空白が入ると、ただの本文とみなされます。 +見出しは行の先頭から始める必要があります。行頭に空白を入れると、ただの本文と見なされます。 +また、見出しの前に文があると、段落としてつながってしまうことがあります。このようなときには空行を見出しの前に入れてください。 + ## コラムなど -節や項の見出しに `[column]` を追加するとコラムのキャプションになります。 +節や項の見出しに `[column]` を追加すると以降がコラムとして扱われ、見出しはコラムのキャプションになります。 例: ```review ===[column] コンパイラコンパイラ ``` -このとき、「=」と「[column]」は間を開けず、必ず続けて書かなければ -なりません。空白があってもいけません。 +このとき、「=」と「[column]」は間を空けず、必ず続けて書かなければなりません。 -次の節や項を待たずにコラムを終了する場合は、「===[/column]」を記述します。 +コラムは、そのコラムのキャプションの見出しと同等か上位のレベル（コラムキャプションが `===` であれば、`=`〜`===`）の見出しが登場するかファイル末尾に達した時点で終了します。これを待たずにコラムを終了する場合は、「`===[/column]`」と記述します（`=`の数はコラムキャプションと対応）。 例: ```review ===[column] コンパイラコンパイラ @@ -62,82 +64,119 @@ コラムの内容 ===[/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要素)になります。 +そして、その行以降、空白で始まる行が用語内容（HTML では dd 要素）になります。次の用語名か空行になるまで、1つの段落として結合されます。 -また、リスト内でも後述するインライン命令は有効です。 +## ブロック命令とインライン命令 +見出しと箇条書きは特別な記法でしたが、それ以外の Re:VIEW の命令はほぼ一貫した記法を採用しています。 + +ブロック命令は1〜複数行の段落に対して何らかのアクション（たいていは装飾）を行います。ブロック命令の記法は次のとおりです。 + +``` +//命令[オプション1][オプション2]…{ +対象の内容。本文と同じような段落の場合は空行区切り + … +//} +``` + +オプションを取らなければ単に `//命令{` という開始行になります。いずれにせよ、開始と終了は明確です。オプション内で「]」という文字が必要であれば、`\]` でリテラルを表現できます。 + +亜種として、一切段落を取らないブロック命令もごく少数あります。 + +``` +//命令[オプション1][オプション2]… +``` + +インライン命令は段落、見出し、ブロック内容、一部のブロックのオプション内で利用でき、文字列内の一部に対してアクション（装飾）を行います。 + +``` +@<命令>{対象の内容} +``` + +内容に「}」という文字が必要であれば、`\}` でリテラルを表現できます。 + +記法および処理の都合で、次のような制約があります。 + +* ブロック命令内には別のブロック命令をネストできません。 +* ブロック命令内には見出しや箇条書きを格納できません。 +* インライン命令には別のインライン命令をネストできません。 + ## ソースコードなどのリスト -ソースコードなどのリストには`//list`を使います。連番をつけたくない場合は先頭に``em``（embeddedの略）、行番号をつける場合は末尾に``num``を付加します。まとめると以下の4種類になります。 +ソースコードなどのリストには`//list`を使います。連番を付けたくない場合は先頭に `em`（embedded の略）、行番号を付ける場合は末尾に `num` を付加します。まとめると、以下の4種類になります。 -* ``//list[識別子][キャプション][言語指定]{ 〜 //}`` +* `//list[識別子][キャプション][言語指定]{ 〜 //}` * 通常のリスト。言語指定は省略できます。 -* ``//listnum[識別子][キャプション][言語指定]{ 〜 //}`` +* `//listnum[識別子][キャプション][言語指定]{ 〜 //}` * 通常のリストに行番号をつけたもの。言語指定は省略できます。 -* ``//emlist[キャプション][言語指定]{ 〜 //}`` +* `//emlist[キャプション][言語指定]{ 〜 //}` * 連番がないリスト。キャプションと言語指定は省略できます。 -* ``//emlistnum[キャプション][言語指定]{ 〜 //}`` - * 連番がないリストに行番号をつけたもの。キャプションと言語指定は省略できます。 +* `//emlistnum[キャプション][言語指定]{ 〜 //}` + * 連番がないリストに行番号を付けたもの。キャプションと言語指定は省略できます。 例: ```review //list[main][main()][c]{ ←「main」が識別子で「main()」がキャプション @@ -159,11 +198,11 @@ ``` 例: ```review -//emlist[][ruby]{ +//emlist[][c]{ printf("hello"); //} ``` 例: @@ -172,72 +211,60 @@ //emlistnum[][ruby]{ puts "hello world!" //} ``` +言語指定は、ハイライトを有効にしたときに利用されます。 +コードブロック内でもインライン命令は有効です。 -ブロック内でも後述するインライン命令は有効です。 +また本文中で「リスト X.X を見てください」のようにリストを指定する場合は、インライン命令 `@<list>` を使います。`//list` あるいは `//listnum` で指定した識別子を指定し、たとえば「`@<list>{main}`」と表記します。 -また本文中で「リスト X を見てください」のようにリストを指定 -する場合は、`//list` で指定した識別子を使って「`@<list>{main}`」 -と表記します。 +他章のリストを参照するには、後述の「章ID」を指定し、たとえば `@<list>{advanced|main}`（`advanced.re` ファイルの章にあるリスト `main` を参照する）と記述します。 ### ソースコード専用の引用 -ソースコードを引用する場合、ファイル名が必要です。 +ソースコードを引用するには次のように記述します。 例: ```review //source[/hello/world.rb]{ puts "hello world!" //} ``` -ソースコードの引用は、キャプションをつけた`//emlist`とあまり違いはありません。 -が、HTMLのCSSなどでは区別した表現ができます。 +ソースコードの引用は、キャプションを付けた `//emlist` とほぼ同じです。HTML の CSS などでは区別した表現ができます。 - -参照方法はlistと変わりません。 - -例: - -``` -..は@<list>{hello}をみてください。 -``` - ## 本文中でのソースコード引用 -本文中でソースコードを引用して記述します。 +本文中でソースコードを引用して記述するには、`code` を使います。 例: ```review @<code>{p = obj.ref_cnt} ``` ## コマンドラインのキャプチャ -コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。 +コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。インライン命令を使って入力箇所を強調するのもよいでしょう。 例: ``` //cmd{ -$ ls / +$ @<b>{ls /} //} ``` -ブロック内でも後述するインライン命令は有効です。 - ## 図 -図は `//image{ 〜 //}` で指定します。執筆中はアスキーアートで -代替しているため、ダミーのアスキーアートが入っていることがあり -ます。この部分は、組版時には単に無視してください。 +図は `//image{ 〜 //}` で指定します。後述するように、識別子に基づいて画像ファイルが探索されます。 +ブロック内の内容は単に無視されますが、アスキーアートや、図中の訳語などを入れておくといった使い道があります。 + 例: ``` //image[unixhistory][UNIX系OSの簡単な系譜]{ System V 系列 @@ -248,19 +275,18 @@ --------------> Linux //} ``` -3番目の引数として、画像の倍率・大きさを指定することができます。 -今のところ「scale=X」で倍率(X倍)が指定できます。 +3番目の引数として、画像の倍率・大きさを指定することができます。今のところ「scale=X」で倍率（X 倍）を指定でき、HTML、TeX ともに紙面（画面）幅に対しての倍率となります（0.5 なら半分の幅になります）。 -また本文中で「図 X を見てください」のように図を指定する場合は、 -`//image` で指定した識別子を用いて「`@<img>{unixhistory}`」と -記述します。`//image` と `@<img>` でつづりが違うので注意してください。 +※TeX において原寸からの倍率にしたいときには、`config.yml` に `image_scale2width: false` を指定してください。 -なお、後述しますが、インラインで図を出力するには`@<icon>`を使用します。 +また、本文中で「図 X.X を見てください」のように図を指定する場合は、インライン命令 `@<img>` を使います。`//image` で指定した識別子を用いて「`@<img>{unixhistory}`」のように記述します（`//image` と `@<img>` でつづりが違うので注意してください）。 +### 画像ファイルの探索 + 図として貼り込む画像ファイルは、次の順序で探索され、最初に発見されたものが利用されます。 ``` 1. <imgdir>/<builder>/<chapid>/<id>.<ext> 2. <imgdir>/<builder>/<chapid>-<id>.<ext> @@ -268,16 +294,20 @@ 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 が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。 +* `<imgdir>` はデフォルトでは images ディレクトリです。 +* `<builder>` は利用しているビルダ名（ターゲット名）で、たとえば `--target=html` としているのであれば、images/html ディレクトリとなります。 +* `<chapid>` は章 ID です。たとえば ch01.re という名前であれば「ch01」です。 +* `<id>` は //image[〜] の最初に入れた「〜」のことです（つまり、ID に日本語や空白交じりの文字を使ってしまうと、後で画像ファイル名の名前付けに苦労することになります！）。 +* `<ext>` は Re:VIEW が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。 +### インラインの画像挿入 + +段落途中などに画像を貼り込むには、インライン命令の `@<icon>{識別子}` を使います。ファイルの探索ルールは同じです。 + ## 番号が振られていない図 `//indepimage[ファイル名][キャプション]` で番号が振られていない画像ファイルを生成します。キャプションは省略できます。 例: @@ -292,12 +322,10 @@ ``` //numberlessimage[door_image_path][扉絵] ``` -※ただし、`//indepimage`と機能的にかぶっているので、将来は廃止され、`//indepimage`に統合される予定です。 - ## グラフ表現ツールを使った図 `//graph[ファイル名][コマンド名][キャプション]` で各種グラフ表現ツールを使った画像ファイルの生成ができます。キャプションは省略できます。 例: gnuplotの使用 @@ -310,15 +338,13 @@ コマンド名には、「`graphviz`」「`gnuplot`」「`blockdiag`」「`aafigure`」のいずれかを指定できます。ツールはそれぞれ別途インストールする必要があります。 ## 表 -表は `//table[識別子][キャプション]{ 〜 //}` です。ヘッダと内容を -分ける罫線は「`------`」で書き込んであります。 +表は `//table[識別子][キャプション]{ 〜 //}` という記法です。ヘッダと内容を分ける罫線は「`------------`」（12個以上の連続する `-` または `=`）を使います。 -カラム間は任意個数のタブで区切ります。また、カラム先頭の「`.`」は削除されるので、カラムの先頭文字が「`.`」の場合は「`.`」をもう一つ余計に付けてください。例えば「`.`」という内容のカラムは「`..`」と書きます。 -また、空のカラムは「`.`」と書けます。 +表の各列のセル間は「1つ」のタブで区切ります。また、列の先頭セルの「`.`」は削除されるので、先頭文字が「`.`」の場合は「`.`」をもう1つ余計に付けてください。たとえば「`.`」という内容のセルは「`..`」と書きます。 例: ``` //table[envvars][重要な環境変数]{ @@ -334,15 +360,29 @@ MANPATH manのソースを置いているディレクトリ DISPLAY X Window Systemのデフォルトディスプレイ //} ``` -本文中で「表 X を見てください」のように表を指定する場合は -`@<table>{envvars}` という表記を使います。 +本文中で「表 X.X を見てください」のように表を指定する場合はインライン命令 `@<table>` を使います。たとえば `@<table>{envvars}` となります。 -表内でも後述するインライン命令は有効です。 +表のセル内でもインライン命令は有効です。 +### 複雑な表 + +現時点では表のセルの結合や、中央寄せ・右寄せなどの表現はできません。 + +複雑な表については、画像を貼り込む `imgtable` ブロック命令を代わりに使用する方法もあります。`imgtable` の表は通常の表と同じく採番され、インライン命令 `@<table>` で参照できます。 + +例: + +``` +//imgtable[complexmatrix][複雑な表]{ +complexmatrixという識別子に基づく画像ファイルが貼り込まれる。 +探索ルールはimageと同じ +//} +``` + ## 引用 引用は「`//quote{ 〜 //}`」を使って記述します。 例: @@ -351,13 +391,29 @@ //quote{ 百聞は一見に如かず。 //} ``` -引用内でも後述するインライン命令は有効です。 -また、いまのところ引用内で別のブロック構文を使うことはできません。 +複数の段落を入れる場合は、空行で区切ります。 +## 囲み記事 + +技術書でよくある、コラムにするほどではないけれども本文から独立したちょっとした記事を入れるために、以下の命令があります。 + +* `//note[キャプション]{ 〜 //}` : ノート +* `//memo[キャプション]{ 〜 //}` : メモ +* `//tip[キャプション]{ 〜 //}` : Tips +* `//info[キャプション]{ 〜 //}` : 情報 +* `//warning[キャプション]{ 〜 //}` : 注意 +* `//important[キャプション]{ 〜 //}` : 重要 +* `//caution[キャプション]{ 〜 //}` : 警告 +* `//notice[キャプション]{ 〜 //}` : 注意 + +いずれも `[キャプション]` は省略できます。 + +内容には、空行で区切って複数の段落を記述可能です。 + ## 脚注 脚注は「`//footnote`」を使って記述します。 例: @@ -366,34 +422,31 @@ パッケージは本書のサポートサイトから入手できます@<fn>{site}。 各自ダウンロードしてインストールしておいてください。 //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][キャプション] ``` @@ -406,329 +459,308 @@ Computing Laboratory, The University of Kent at Canterbury , August 1991 //} ``` -本文中で参考文献を参照したい場合は次のようにしてください。 +本文中で参考文献を参照したい場合は、インライン命令 `@<bib>` を使い、次のようにします。 例: ``` -…という研究が知られています(@<bib>{lins}) +…という研究が知られています（@<bib>{lins}）。 ``` ## リード文 -リード文は `//lead{ 〜 //}` で指定します。 -歴史的経緯により`//read{ 〜 //}` でも使えます。 +リード文は `//lead{ 〜 //}` で指定します。歴史的経緯により、`//read{ 〜 //}` も使用可能です。 例: ``` //lead{ 本章ではまずこの本の概要について話し、 次にLinuxでプログラムを作る方法を説明していきます。 //} ``` -## TeX式 +空行区切りで複数の段落を記述することもできます。 +## TeX 式 + LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。 例: ``` //texequation{ \sum_{i=1}^nf_n(x) //} ``` -## 空白制御 +インライン命令では `@<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>` インラインタグは、誤った内容を入れると -構造化文書を容易に破壊し得ることに注意してください。 +## リンク -## その他の文法 +Web ハイパーリンクを記述するには、リンクに `@<href>`、アンカーに `//label` を使います。リンクの書式は `@<href>{URL, 文字表現}` で、「`, 文字表現`」を省略すると URL がそのまま使われます。URL 中に `,` を使いたいときには、`\,` とエスケープしてください。 -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 +@<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） -見出しを一意に特定できる場合は、"`|`"は不要です。 +Re:VIEW が出力する文字列(「第◯章」「図」「表」など）を、指定した言語に合わせて出力することができます。デフォルトは日本語です。 -``` -@<hd>{まずわ} -``` +ファイルが置かれているディレクトリに `locale.yml` というファイルを用意して、以下のように記述します（日本語の場合）。 -他の章を参照したい場合は、先頭に章のidを指定してください。 - 例: ``` -@<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 テンプレートを置き換えることができます。