tmtms-review 1.0.0

data/doc/format_idg.rdoc

@@ -0,0 +1,180 @@
+= ReVIEW フォーマット InDesign XML 形式拡張
+
+ReVIEW フォーマットから、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[数値]
+という特別な書式を代わりに使います。
+
+== ロー指定
+現時点で ReVIEW はブロックの入れ子処理ができないため、ロー指定で 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/libepubmaker/sample.yaml

@@ -0,0 +1,90 @@
+# YAMLファイルのサンプル
+# このファイルはUTF-8エンコーディングで記述してください
+
+# ブック名(ファイル名になるもの。ASCII範囲の文字を使用)
+bookname: sample
+# 記述言語
+language: ja
+# 書名
+title: ReVIEW EPUBのサンプル
+
+# 固有IDに使用するドメイン。指定しない場合には、時刻に基づくランダムUUIDが入る
+# urnid: urn:uid:http://example.com/some-book-title/1.0.2/
+
+# isbn: ISBN。省略した場合はランダム生成したUUIDが入る
+
+# 著者名。複数人いる場合はYAMLの配列形式で指定できる
+aut: Kenshi Muto
+
+# 以下はオプション(配列書式で複数指定可能)。a-が付いているものはcreator側、
+# 付いていないものはcontributor側(二次協力者)に入る
+# a-adp, adp: 異なるメディア向けに作り直した者
+# a-ann, ann: 注釈記述者
+# a-arr, arr: アレンジした者
+# a-art, art: グラフィックデザインおよび芸術家
+# a-asn, asn: 関連・かつての所有者・関係者
+# a-aqt, aqt: 大きく引用された人物
+# a-aft, aft: 後書き・奥付の責任者
+# a-aui, aui: 序論・序文・前書きの責任者
+# a-ant, ant: 目録責任者
+# a-bkp, bkp: メディア制作責任者
+# a-clb, clb: 限定参加または補足者
+# a-cmm, cmm: 解釈・分析・考察者
+# a-dsr, dsr: デザイナ
+# a-edt, edt: 編集者
+# a-ill, ill: イラストレータ
+# a-lyr, lyr: 歌詞作成者
+# a-mdc, mdc: メタデータセットの一次的責任者
+# a-mus, mus: 音楽家
+# a-nrt, nrt: 語り手
+# a-oth, oth: その他
+# a-pht, pht: 撮影責任者
+# a-prt, prt: 出版社
+# a-red, red: 項目の枠組起草者
+# a-rev, rev: 評論者
+# a-spn, spn: 援助者
+# a-ths, ths: 監督者
+# a-trc, trc: 筆記・タイプ作業者
+# a-trl, trl: 翻訳者
+
+# rights: 権利表記
+# date: 刊行日(省略した場合は実行時の日付)
+# description: 説明
+# subject: 短い説明用タグ。配列で複数指定可
+# type: 書籍のカテゴリーなど(複数指定可)
+# format: メディアタイプおよび特徴(複数指定可)
+# source: 出版物生成の重要なリソース情報(複数指定可)
+# relation: 補助的リソース(複数指定可)
+# coverage: 内容の範囲や領域(複数指定可)
+
+# htmlext: HTMLファイルの拡張子(省略した場合はhtml)
+# cover: カバーページのファイル名(省略した場合はbookname.xhtmlになる)
+#
+# coverimage: カバー用画像
+#
+# CSSファイル(配列で複数指定することも可)
+#stylesheet: stylesheet.css
+
+# 目次として抽出するレベル
+toclevel: 3
+# セクション番号を表示するレベル
+secnolevel: 2
+# NCX目次の見出しレベルごとの飾り(配列で設定)
+ncxindent:
+- 
+- - 
+
+# EPUB標準の目次以外に目次を作成するか
+mytoc:
+# mytocがtrueの場合に作成する目次ファイル名(省略するとtoc.xhtml)
+# tocfile: toc.xhtml
+
+# 表紙の後に権利表記ページを作成するか。デフォルトでは作成されない。ファイル名を指定するとそのファイルが使われる(data配列にも指定しておく必要がある)
+# titlepage: title.xhtml
+
+# 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.xhtmlとしてコピーされる(data配列にも指定しておく必要がある)
+# colophon: true
+# pubhistory: 奥付履歴
+
+# XHTML生成後に実行するプログラム。$1:HTMLの生成されたディレクトリ $2:ReVIEWファイルのあるディレクトリ $3:起動時指定のyamlファイル名
+# posthook: hook.sh

data/doc/quickstart.rdoc

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