review 1.4.0 → 1.5.0

data/doc/format_idg.ja.md

@@ -0,0 +1,203 @@
+# Re:VIEW フォーマット InDesign XML 形式拡張
+
+Re:VIEW フォーマットから、Adobe 社の DTP ソフトウェア「InDesign」
+で読み込んで利用しやすい XML 形式に変換できます (通常の XML とほぼ同じ
+ですが、文書構造ではなく見た目を指向した形態になっています)。
+現時点では idgxmlbuilder.rb と topbuilder.rb のみが拡張に対応しています。
+実際には出力された XML を InDesign のスタイルに割り当てるフィルタをさらに
+作成・適用する必要があります。
+
+## 章・節・項・段
+
+従来の`[column]`のほかに、オプションを追加しています。
+
+* `[nonum]` : これを指定している章・節・項・段には連番を振りません。
+* `[circle]`: 「・」を先頭に付けた小さな見出し(連番なし)を作成します。
+* `[world]`: Real Worldコラム。
+* `[hood]`: Under the Hoodコラム。
+* `[edition]`: Editionコラム。
+* `[insideout]`: インサイドアウトコラム。
+
+## 書式ブロック
+
+`//insn[タイトル]{ 〜 //}` または `//box[タイトル]{ 〜 //}` で書式を指定します。
+
+## ノート
+
+`//note{ 〜 //}` または `//note[タイトル]{ 〜 //}` で注意文章を指定します。
+
+## メモ
+
+`//memo{ 〜 //}` または `//memo[タイトル]{ 〜 //}` でメモ文章を指定します。
+
+## ヒント
+
+`//tip{ 〜 //}` または `//tip[タイトル]{ 〜 //}` でヒント(Tip)文章を指定します。
+
+## 参照ブロック
+
+`//info{ 〜 //}` または `//info[タイトル]{ 〜 //}` で参照文章を指定します。
+
+## プランニング
+
+`//planning{ 〜 //}` または `//planning[タイトル]{ 〜 //}` でプランニング文章を指定します。
+
+## ベストプラクティス
+
+`//best{ 〜 //}` または `//best[タイトル]{ 〜 //}` でベストプラクティス文章を
+指定します。
+
+## ここが重要 (キーワード)
+
+`//important[タイトル]{ 〜 //}` で重要項目を指定します。
+
+## セキュリティ
+
+`//security{ 〜 //}` または `//security[タイトル]{ 〜 //}` でセキュリティ文章を
+指定します。
+
+## 警告
+
+`//caution{ 〜 //}` または `//caution[タイトル]{ 〜 //}` で警告文章を指定します。
+
+## エキスパートに訊く
+
+`//expert{ 〜 //}` で「エキスパートに訊く」を指定します (rawで`<expert>〜</expert>`
+を使うほうがよいかもしれません)。
+QとAは`@<b>{Q}：〜` と `@<b>{A}：〜` で示します。
+
+## 注意
+
+`//notice{ 〜 //}` または `//notice[タイトル]{ 〜 //}` で注意を指定します。
+
+## ワンポイント
+
+`//point{ 〜 //}` または `//point[タイトル]{ 〜 //}` でワンポイントを指定します。
+
+## トラブルシューティング
+
+`//shoot{ 〜 //}` または `//shoot[タイトル]{ 〜 //}` でトラブルシューティングを
+指定します。
+
+## 用語解説
+
+`//term{ 〜 //}` で用語解説を指定します(ただし、ブロック指定ができないので
+実質的にはrawで`<term>〜</term>`を通常使うことになるでしょう)。
+
+## リンク
+
+`//link{ 〜 //}` または `//link[タイトル]{ 〜 //}` で他の章やファイルなどへの
+参照内容を指定します。
+
+## 練習問題
+
+`//practice{ 〜 //}` で練習問題を指定します。
+
+## 参考
+
+`//reference{ 〜 //}` で参考情報を指定します。
+
+## 相互参照
+
+`//label[〜]`でラベルを定義し、`@<labelref>{〜}`で参照します。
+XMLとしては`<label id='〜' />`と`<labelref idref='〜' />`というタグに
+置き換えられます。
+実際にどのような相互参照関係にするかは、処理系に依存します。
+想定の用途では、章や節の番号およびタイトルを記憶し、labelrefの出現箇所
+に"「節(あるいは章)番号　タイトル」"という文字列を配置します。
+
+`@<chapref>`の展開形式を、`--chapref="前装飾文字列,中間装飾文字列,後装飾文字列"`
+でコンパイル実行時に指定できます。デフォルトは`",「,」"`です。たとえば
+"`第2章「コンパイラ」`" のように普通は展開されます。
+`"「,　,」"`と指定すると、"`「第2章　コンパイラ」`" に展開されます。
+
+## 丸数字
+
+`@<maru>{数値}` で丸数字を出力します。
+
+## キートップ
+
+`@<keytop>{キー文字}` でキーボードマークを出力します。
+
+## 吹き出し
+
+`@<balloon>{〜}` でコード内などでの吹き出しを作成します。吹き出しは右に寄せ
+られ、記入した箇所から吹き出しまで線が引かれます。
+`@<>`オペレータは入れ子ができないため、丸数字を使いたいときには`@maru[数値]`
+という特別な書式を代わりに使います。
+
+## ロー指定
+
+現時点で Re:VIEW はブロックの入れ子処理ができないため、ロー指定で XML
+エレメントを指定しなければならないこともあります。
+
+インラインの`@<raw>{ 〜 }`の他に、単一行の`//raw[〜]`、ブロック版の `//rawblock{ 〜 //}` でも、フォーマット処理をせずにそのままの文字列が出力できます。
+
+## キャプションなし表
+
+`//table{ 〜 //}` のように id もキャプションも付けないブロックを利用できます。
+この場合、その表の連番付けを飛ばします。
+
+## 表セル幅の指定
+
+`//tsize[1列目の幅,2列目の幅,...]` で、続く `//table` の表の列幅を指定します
+(単位mm)。これを利用するときには、review2idgxml を実行する際、オプション
+`--table=表幅` を付ける必要があります (表幅の単位は mm)。列幅指定の個数が
+実際の列数に満たない場合、残りの列は均等分割したものとなります。列幅の
+合計が表幅を超えるとエラーになります。
+
+## DTP 命令指定
+
+`@<dtp>{ 〜 }` で InDesign 向けに「`<? dtp 〜 ?>`」型の XML インストラクション
+を埋め込みます。処理系に渡す任意の文字列を指定できますが、次のような文字列
+を特殊文字指定できます。
+
+* maru	番号リストの各段落先頭で使い、このリスト段落の番号は丸数字であることを示す
+* return  改行記号文字
+* autopagenumber	現ページ番号
+* nextpageunmber	次ページ番号
+* previouspagenumber	前ページ番号
+* sectionmarker	セクションマーカー
+* bulletcharacter	ビュレット (ナカグロ)
+* copyrightsymbol	著作権記号
+* degreesymbol	度記号
+* ellipsischaracter	省略記号
+* forcedlinebreak	強制改行
+* discretionarylinebreak	任意の改行
+* paragraphsymbol	段落記号
+* registeredtrademark	登録商標記号
+* sectionsymbol	セクション記号
+* trademarksymbol	商標記号
+* rightindenttab	右インデントタブ
+* indentheretab	「ここまでインデント」タブ
+* zerowidthnonjoiner	結合なし
+* emdash	EMダッシュ
+* endash	ENダッシュ
+* discretionaryhyphen	任意ハイフン
+* nonbreakinghyphen	分散禁止ハイフン
+* endnestedstyle	先頭文字スタイルの終了文字
+* doubleleftquote	左二重引用符
+* doublerightquote	右二重引用符
+* singleleftquote	左用符
+* singlerightquote	右引用符
+* singlestraightquote	半角一重左用符
+* doublestraightquote	半角二重引用符
+* emspace	EMスペース
+* enspace	ENスペース
+* flushspace	フラッシュスペース
+* hairspace	極細スペース
+* nonbreakingspace	分散禁止スペース
+* fixedwidthnonbreakingspace	分散禁止スペース（固定幅）
+* textvariable	全角スペース
+* thinspace	細いスペース
+* figurespace	数字の間隔
+* punctuationspace	句読点等の間隔
+* sixthspace	1/6スペース
+* quarterspace	1/4スペース
+* thirdspace	1/3スペース
+* columnbreak	改段
+* framebreak	改フレーム
+* pagebreak	改ページ
+* oddpagebreak	奇数改ページ
+* evenpagebreak	偶数改ページ
+* footnotesymbol	脚注記号

data/doc/{quickstart.rdoc → quickstart.ja.md}

@@ -1,4 +1,4 @@
-= Re:VIEWクイックスタートガイド
+# Re:VIEWクイックスタートガイド
 
 Re:VIEW は、EWB や RD あるいは Wiki に似た簡易フォーマットで記述したテキストファイルを、目的に応じて各種の形式に変換するツールセットです。
 
@@ -8,181 +8,215 @@ Re:VIEW は GNU Lesser General Public License Version 2.1 に基づいて配布
 
 このドキュメントでは、Re:VIEW のセットアップから変換の例までを簡単に説明します。
 
-== セットアップ
+## セットアップ
 
 Re:VIEW は Ruby 言語で記述されており、Linux/Unix 互換システムで動作します。Mac OS X および Windows Cygwin でも動作可能です。Ruby gem、Git、Subversion のいずれかを使ってダウンロード・展開します。
 
 なお、Re:VIEW フォーマット自体は文字で表現されたタグが付いている以外は単なるテキストファイルなので、エディタ、OS についてはまったく制限はありません。
 
-=== Ruby gemを使う場合
+### RubyGems を使う場合
 
 機能セットがまとまった区切りごとに、Re:VIEW の開発チームが Re:VIEW の gem を更新しています。
 
 次のように Re:VIEW の gem をインストールします。
 
-  gem install review
+```bash
+$ gem install review
+```
 
 Ruby gem の bin ディレクトリにパスを通すようにしておいてください。
 
 インストール後、最新の gem に追従するには次のようにします。
 
-  gem update review
+```bash
+$ gem update review
+```
 
-=== Gitを使う場合
+### Gitを使う場合
 
 Re:VIEW は GitHub で開発されており、バージョン管理ツールの Git を使って最新の Re:VIEW コードを入手できます。Git は分岐が容易なので、独自のカスタマイズを施すのにも向いています。
 
 初めて取得するときには、次のようにします (コピーを作っています)。
 
-  git clone git://github.com/kmuto/review.git
+```bash
+$ git clone git://github.com/kmuto/review.git
+```
 
 review というディレクトリに展開されるので、review/bin にパスを通すようにしておいてください。
 
 最新の開発に追従するには次のようにします。
 
-  git pull
+```bash
+$ git pull
+```
 
-=== Subversionを使う場合
+### Subversionを使う場合
 
 Git の最新コピーは、別のバージョン管理ツールの Subversion 向けにも提供しています (古い環境では Subversion のクライアントしか入っていないことがあります)。
 
 初めて取得するときには、次のようにします (コピーを作っています)。
 
-  svn co https://kmuto.jp/svn/review/trunk review
+```bash
+$ svn co https://kmuto.jp/svn/review/trunk review
+```
 
 review というディレクトリに展開されるので、review/bin にパスを通すようにしておいてください。
 
 最新の開発に追従するには次のようにします。
 
-  svn up
+```
+$ svn up
+```
 
-= Re:VIEW テキストの作成と変換
+# Re:VIEW テキストの作成と変換
 
 セットアップを終えたら、Re:VIEW フォーマットのテキストを作り、変換できるようになります。次に Re:VIEW フォーマットテキストの簡単な例を示します。これを sample.re といった名前で保存します (拡張子も自由ですが、.re 拡張子を推奨します)。
 
-  = はじめてのRe:VIEW
-  
-  //lead{
-  「Hello, Re:VIEW.」
-  //}
-  
-  == Re:VIEWとは
-  
-  @<b>{Re:VIEW}は、EWBやRDあるいはWikiに似た簡易フォーマットで記述したテキストファイルを、目的に応じて各種の形式に変換するツールセットです。
-  
-  平易な文法ながらも、コンピュータ関係のドキュメント作成のための多くの機能を備えており、次のような形式に変換できます。
-  
-   * テキスト（指示タグ付き）
-   * LaTeX
-   * HTML
-   * XML
-  
-  現在入手手段としては次の3つがあります。
-  
-   1. Ruby gem
-   2. Git
-   3. Subversion
-  
-  ホームページは@<tt>{https://github.com/kmuto/review/wiki/}です。
+
+```review
+= はじめてのRe:VIEW
+
+//lead{
+「Hello, Re:VIEW.」
+//}
+
+== Re:VIEWとは
+
+@<b>{Re:VIEW}は、EWBやRDあるいはWikiに似た簡易フォーマットで記述したテキストファイルを、目的に応じて各種の形式に変換するツールセットです。
+
+平易な文法ながらも、コンピュータ関係のドキュメント作成のための多くの機能を備えており、次のような形式に変換できます。
+
+ * テキスト（指示タグ付き）
+ * LaTeX
+ * HTML
+ * XML
+
+現在入手手段としては次の3つがあります。
+
+ 1. Ruby gem
+ 2. Git
+ 3. Subversion
+
+ホームページは@<tt>{https://github.com/kmuto/review/wiki/}です。
+```
 
 テキストファイルの文字エンコーディングには、UTF-8 を使うことをお勧めします。Re:VIEW は日本語文字エンコーディングとして UTF-8、EUC-JP、Shift_JIS、JIS を扱うことができ、入力ファイルについては自動判別、出力ファイルについても選択可能 (デフォルトは UTF-8) ですが、入力・出力のいずれにおいても、使用可能な文字についての制限が少ない UTF-8 が最適です。
 
 次に、章構成ファイルの CHAPS ファイルを同じディレクトリに用意します。このファイルには、Re:VIEW フォーマットファイルの名前を格納します。
 
-  sample.re
+* sample.re
 
 CHAPS ファイルの1行目に書いたものが第1章、2行目に書いたものが第2章、……と構成されます (CHAPS に似たものとして、前付けを列挙する PREDEF ファイル、後付けを列挙する POSTDEF ファイルがあります。これらを「カタログファイル」と呼びます)。
 
 sample.re から目的の形式に変換するには、review-compile コマンドを使います。
 
-  review-compile --target text sample.re > sample.txt   ←テキストにする
-  review-compile --target html sample.re > sample.html  ←HTMLにする
-  review-compile --target latex sample.re > sample.tex  ←LaTeXにする
-  review-compile --target idgxml sample.re > sample.xml ←XMLにする
+```bash
+$ review-compile --target text sample.re > sample.txt   ←テキストにする
+$ review-compile --target html sample.re > sample.html  ←HTMLにする
+$ review-compile --target latex sample.re > sample.tex  ←LaTeXにする
+$ review-compile --target idgxml sample.re > sample.xml ←XMLにする
+```
 
 上記では各ファイル個別に変換することを想定して、標準出力をリダイレクトする書式を掲載していますが、-a オプションを付ければ、CHAPS、PREDEF、POSTDEF に従ってすべてのファイルを変換できます。
 
-  review-compile --target html -a ←すべてのファイルをHTMLにする
+```
+$ review-compile --target html -a ←すべてのファイルをHTMLにする
+```
 
 sample.re を HTML に変換すると、次のようになります。
 
-  <?xml version="1.0" encoding="UTF-8"?>
-  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-  <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ops="http://www.idpf.org/2007/ops" xml:lang="ja">
-  <head>
-    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
-    <meta http-equiv="Content-Style-Type" content="text/css" />
-    <meta name="generator" content="Re:VIEW" />
-    <title>はじめてのRe:VIEW</title>
-  </head>
-  <body>
-  <h1><a id="h1" />第1章　はじめてのRe:VIEW</h1>
-  <div class="lead">
-  <p>「Hello, Re:VIEW.」</p>
-  </div>
-  
-  <h2><a id="h1-1" />1.1　Re:VIEWとは</h2>
-  <p><b>Re:VIEW</b>は、EWBやRDあるいはWikiに似た簡易フォーマットで記述したテキストファイルを、目的に応じて各種の形式に変換するツールセットです。</p>
-  <p>平易な文法ながらも、コンピュータ関係のドキュメント作成のための多くの機能を備えており、次のような形式に変換できます。</p>
-  <ul>
-  <li>テキスト（指示タグ付き）</li>
-  <li>LaTeX</li>
-  <li>HTML</li>
-  <li>XML</li>
-  </ul>
-  <p>現在入手手段としては次の3つがあります。</p>
-  <ol>
-  <li>Ruby gem</li>
-  <li>Git</li>
-  <li>Subversion</li>
-  </ol>
-  <p>ホームページは<tt>https://github.com/kmuto/review/wiki/</tt>です。</p>
-  </body>
-  </html>
-
-Re:VIEW フォーマットについての詳細は、 {format.rdoc}[https://github.com/kmuto/review/blob/master/doc/format.rdoc] を参照してください。
-
-review-compile を含め、ほとんどのコマンドは --help オプションを付けるとオプションについてのヘルプが表示されます。review-compile には多数のオプションがあるので確認してください。
-
-なお、--target で毎回指定するのは面倒なので、review-compile に対するシンボリックリンクを作成しておくとよいでしょう。「review2...」のコマンド名で呼び出せるようになります。
-
-  cd Re:VIEWのインストールされたパス/bin
-  ln -s review-compile review2text
-  ln -s review-compile review2html
-  ln -s review-compile review2latex
-  ln -s review-compile review2idgxml
-
-== プリプロセッサ、ボリューム表示
-
-#@mapfile、#@maprange、#@mapoutput のタグを使って、指定のファイルの内容あるいはコマンドの実行結果を挿入できます。挿入・更新を行うには、プリプロセッサとなる review-preproc コマンドを使います。
-
-  review-preproc ファイル > 結果ファイル ←標準出力をリダイレクト
-   または
-  review-preproc --replace ファイル ←ファイルを更新したもので上書き
+```html
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ops="http://www.idpf.org/2007/ops" xml:lang="ja">
+<head>
+  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+  <meta http-equiv="Content-Style-Type" content="text/css" />
+  <meta name="generator" content="Re:VIEW" />
+  <title>はじめてのRe:VIEW</title>
+</head>
+<body>
+<h1><a id="h1" />第1章　はじめてのRe:VIEW</h1>
+<div class="lead">
+<p>「Hello, Re:VIEW.」</p>
+</div>
+
+<h2><a id="h1-1" />1.1　Re:VIEWとは</h2>
+<p><b>Re:VIEW</b>は、EWBやRDあるいはWikiに似た簡易フォーマットで記述したテキストファイルを、目的に応じて各種の形式に変換するツールセットです。</p>
+<p>平易な文法ながらも、コンピュータ関係のドキュメント作成のための多くの機能を備えており、次のような形式に変換できます。</p>
+<ul>
+<li>テキスト（指示タグ付き）</li>
+<li>LaTeX</li>
+<li>HTML</li>
+<li>XML</li>
+</ul>
+<p>現在入手手段としては次の3つがあります。</p>
+<ol>
+<li>Ruby gem</li>
+<li>Git</li>
+<li>Subversion</li>
+</ol>
+<p>ホームページは<tt>https://github.com/kmuto/review/wiki/</tt>です。</p>
+</body>
+</html>
+```
+
+Re:VIEW フォーマットについての詳細は、 [format.rdoc](https://github.com/kmuto/review/blob/master/doc/format.rdoc) を参照してください。
+
+review-compile を含め、ほとんどのコマンドは `--help` オプションを付けるとオプションについてのヘルプが表示されます。`review-compile` には多数のオプションがあるので確認してください。
+
+なお、`--target` で毎回指定するのは面倒なので、`review-compile` に対するシンボリックリンクを作成しておくとよいでしょう。「review2...」のコマンド名で呼び出せるようになります。
+
+```bash
+$ cd Re:VIEWのインストールされたパス/bin
+$ ln -s review-compile review2text
+$ ln -s review-compile review2html
+$ ln -s review-compile review2latex
+$ ln -s review-compile review2idgxml
+```
+
+## プリプロセッサ、ボリューム表示
+
+`#@mapfile`、`#@maprange`、`#@mapoutput` のタグを使って、指定のファイルの内容あるいはコマンドの実行結果を挿入できます。挿入・更新を行うには、プリプロセッサとなる review-preproc コマンドを使います。
+
+```bash
+$ review-preproc ファイル > 結果ファイル ←標準出力をリダイレクト
+
+## または
+$ review-preproc --replace ファイル ←ファイルを更新したもので上書き
+```
 
 各章の分量などを表示するには、review-vol コマンドを使います。
 
-  review-vol
+```bash
+$ review-vol
+```
 
 より細かな見出し一覧などを出したいときには、review-index コマンドを使うのもよいでしょう。
 
-  review-index --level 掘り下げる見出しレベル数 -a
+```bash
+$ review-index --level 掘り下げる見出しレベル数 -a
+```
 
-== PDF 化と EPUB 化
+## PDF 化と EPUB 化
 
 review-pdfmaker コマンドで PDF ブックの作成、review-epubmaker コマンドで EPUB ファイルの作成ができます。
 
-PDF を作成するには、pTeXLive2009 以上の環境が必要です。EPUB を作成するには、zip コマンドが必要です (MathML も使いたいときには、 {MathML ライブラリ}[http://www.hinet.mydns.jp/?mathml.rb]も必要です)。
+PDF を作成するには、TeXLive2012 以上の環境が必要です。EPUB を作成するには、zip コマンドが必要です (MathML も使いたいときには、 [MathML ライブラリ](http://www.hinet.mydns.jp/?mathml.rb)も必要です)。
 
-いずれのコマンドも、必要な設定情報を記した YAML ファイルを引数に指定して実行します。YAML ファイルのサンプルは、 {sample.yml}[https://github.com/kmuto/review/blob/master/doc/sample.yml] としてこのドキュメントと同じディレクトリに収録しています。
+いずれのコマンドも、必要な設定情報を記した YAML ファイルを引数に指定して実行します。YAML ファイルのサンプルは、 [sample.yml](https://github.com/kmuto/review/blob/master/doc/sample.yml) としてこのドキュメントと同じディレクトリに収録しています。
 
-  review-pdfmaker YAMLファイル  ←PDFの作成
-  review-epubmaker YAMLファイル ←EPUBの作成
+```bash
+$ review-pdfmaker YAMLファイル  ←PDFの作成
+$ review-epubmaker YAMLファイル ←EPUBの作成
+```
 
-== クレジット
+## クレジット
 
 Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2014年3月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。
 
 バグ・パッチの報告、開発者用メーリングリストなどについての情報は、
-https://github.com/kmuto/review/wiki
+
+* https://github.com/kmuto/review/wiki
+
 を参照してください。