review 1.4.0 → 1.5.0

data/doc/quickstart.md

@@ -0,0 +1,252 @@
+# Re:VIEW Quick Start Guide
+
+Re:VIEW is a toolset to convert from Re:VIEW format documents into various formats.
+
+Re:VIEW uses original lightweight markup language like EWB, RD or Wiki.  Its syntax is simple but powerful for writing IT documents.
+When you write your documents in Re:VIEW format, you can convert them with Re:VIEW tools into LaTeX, HTML, EPUB, InDesign, Text, and so on.
+
+Re:VIEW is free software under the terms of the GNU Lesser General Public License Version 2.1, so you can use, modify and redistribute it. This license has no relations with your documents using Re:VIEW, so your documents are not forced to use this license. When you want to distribute Re:VIEW software itself or the system including Re:VIEW software, you should read COPYING file carefully.
+
+This article describes how to setup Re:VIEW and use it.
+
+## Set up Re:VIEW
+
+Re:VIEW is a software in Ruby and worked in Linux/Unix, Mac OS X, and Cygwin. You can install Re:VIEW with RubyGems, Git or Subversion.
+
+Note that Re:VIEW format is tagged text file, so you can write it on any editors and OSes.
+
+### using RubyGmes
+
+Re:VIEW is released as RubyGems.
+
+* https://rubygems.org/gems/review
+
+Add this line to your application's Gemfile:
+
+```Gemfile
+gem 'review'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install review
+```
+
+### using Git
+
+You can get latest Re:VIEW sources from GitHub.
+
+```bash
+$ git clone git://github.com/kmuto/review.git
+```
+
+You can use Re:VIEW to add `review/bin` directory to `$PATH` variable.
+
+You can update the sources as follows:
+
+```bash
+$ git pull
+```
+
+### using Subversion
+
+For non git users and environments, Re:VIEW is also distributed with Subversion.
+
+```bash
+$ svn co https://kmuto.jp/svn/review/trunk review
+```
+
+You can use Re:VIEW to add `review/bin` directory to `$PATH` variable.
+
+You can update the sources as follows:
+
+```bash
+$ svn up
+```
+
+# writing Re:VIEW documents and converting them
+
+After setup, you can use `review-init` command to generate Re:VIEW project directory.
+
+To generate `hello` project:
+
+```bash
+$ review-init hello
+$ cd hello
+$ ls hello
+Rakefile     catalog.yml  config.yml   hello.re     images/      layouts/     sty/         style.css
+```
+
+In `hello` directory, many files are generated. `*.re` files are Re:VIEW format file.
+If you make `hello` project, a file `hello.re` is generated.
+
+`catalog.yml` file is a catalog of Re:VIEW format files.
+
+```bash
+$ cat catalog.yml
+PREDEF:
+
+CHAPS:
+  - hello.re
+
+APPENDIX:
+
+POSTDEF:
+```
+
+The first item in CHAPS is the first chapter, and the second item (if you add) is the second chapter. PREDEF is for front matter, APPENDIX is for appendix, and POSTDEF is for back matter.
+
+If you create new `*.re` files as new chapters, you should add the name of files into `catalog.yml`.
+
+Now you can edit `hello.re`. A simple example of Re:VIEW format text is as follows.
+
+
+```review
+= my first Re:VIEW
+
+//lead{
+"Hello, Re:VIEW."
+//}
+
+== What's Re:VIEW
+
+@<b>{Re:VIEW} is a converter from simple markup documents into various formats.
+
+You can generate documents as follows:
+
+ * text with tagging
+ * LaTeX
+ * HTML
+ * XML
+
+You can install Re:VIEW with:
+
+ 1. RubyGems
+ 2. Git
+ 3. Subversion
+
+For more information, see @<tt>{https://github.com/kmuto/review/wiki/}.
+```
+
+You should use UTF-8 as encodings in text files.
+
+To convert hello.re, you can use `review-compile` command.
+
+```bash
+$ review-compile --target html hello.re > hello.html  ## generating HTML
+$ review-compile --target latex hello.re > hello.tex  ## generating LaTeX
+$ review-compile --target idgxml hello.re > hello.xml ## generating XML for InDesing
+```
+
+You can convert all `*.re` files in `catalog.yml` with `-a` option.
+
+```
+$ review-compile --target html -a  ## convert all files into HTML
+```
+
+You can get HTML file as follows:
+
+```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" />
+  <link rel="stylesheet" type="text/css" href="style.css" />
+  <meta name="generator" content="Re:VIEW" />
+  <title>my first Re:VIEW</title>
+</head>
+<body>
+<h1><a id="h1"></a>第1章　my first Re:VIEW</h1>
+<div class="lead">
+<p>&quot;Hello, Re:VIEW.&quot;</p>
+</div>
+
+<h2><a id="h1-1"></a>1.1　What's Re:VIEW</h2>
+<p><b>Re:VIEW</b> is a converter from simple markup documents into various formats.</p>
+<p>You can generate documents as follows:</p>
+<ul>
+<li>text with tagging</li>
+<li>LaTeX</li>
+<li>HTML</li>
+<li>XML</li>
+</ul>
+<p>You can install Re:VIEW with:</p>
+<ol>
+<li>RubyGems</li>
+<li>Git</li>
+<li>Subversion</li>
+</ol>
+<p>For more information, see <tt>https://github.com/kmuto/review/wiki/</tt>.</p>
+
+</body>
+</html>
+```
+
+For more information about Re:VIEW format, see [format.rdoc](https://github.com/kmuto/review/blob/master/doc/format.rdoc).
+
+review-compile and other commands in Re:VIEW has `--help` option to output help.  `review-compile` has many options, so you may see them.
+
+If you don't want to type `--target` every time, you can use symbolic links to `review-compile`. You can use new commands `review2html` and so on.
+
+```bash
+$ cd path/to/review/bin
+$ ln -s review-compile review2text
+$ ln -s review-compile review2html
+$ ln -s review-compile review2latex
+$ ln -s review-compile review2idgxml
+```
+
+## preprocessor and other commands
+
+With Re:VIEW tags such as `#@mapfile`, `#@maprange` and `#@mapoutput`, you can include content of files or result of command execution. To do so, you use `review-preproc` command.
+
+```bash
+$ review-preproc hello_orig.re > hello.re   ## redirect stdout into file
+
+## also:
+$ review-preproc --replace hello.re   ## update files overwriting
+```
+
+You can use `review-vol` command to know the volume of the document.
+
+```bash
+$ review-vol
+```
+
+You can also use `review-index` command to generate header list.
+
+```bash
+$ review-index --level <heading level> -a
+```
+
+## generating PDF and EPUB
+
+You can generate PDF and EPUB as:
+
+```bash
+$ review-pdfmaker config.yml  ## generate PDF
+$ review-epubmaker config.yml ## generate EPUB
+```
+
+To generate PDF, you should install TeXLive 2012 or later.  To generate EPUB, you should install zip command.
+When you want to use MathML, you should install [MathML library](http://www.hinet.mydns.jp/?mathml.rb)
+
+`review-pdfmaker` and `review-epubmaker` need `config.yml`, configuration YAML files. There is a sample YAML file [sample.yml](https://github.com/kmuto/review/blob/master/doc/sample.yml) in the same directory of this document.
+
+
+## Copyright
+
+The original author of Re:VIEW is Minero Aoki. The current maintainer is Kenshi Muto(@kmuto), and committers are Masayoshi Takahashi and Masanori Kado (2015/01).
+
+If you want to report bugs and patches, or to get more information, see:
+
+* https://github.com/kmuto/review/wiki

data/doc/sample.yml

@@ -6,62 +6,230 @@
 
 # ブック名(ファイル名になるもの。ASCII範囲の文字を使用)
 bookname: review-sample
+
 # 書名
 booktitle: Re:VIEW EPUBサンプル
-# 著者
-aut: 執筆者
+
+# 著者名。「, 」で区切って複数指定できる
+aut: ["Minero Aoki", "Kenshi Muto", "Masayoshi Takahashi", "Masanori Kado"]
+
 # 以下はオプション
-# prt: 出版社
-# asn: Associated name
-# ant: Bibliographic antecedent
-# clb: 貢献者
-# csl: 監修者
-# edt: 編集者
-# dsr: デザイナ
-# ill: イラストレータ
-# pht: 撮影者
-# trl: 翻訳者
-# date: 刊行日
-# rights: 権利表記
-# description: ブックの説明
-#
-# coverfile: カバーページのbody要素内に挿入する内容を記述したファイル名
-#
-# coverimage: カバー用画像。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg)
+# 以下はオプション(autと同じように配列書式で複数指定可能)。
+# 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: 内容の範囲や領域(配列で複数指定可)
+
+
+# デバッグフラグ。nullでないときには一時ファイルをカレントディレクトリに作成し、削除もしない
+debug: null
+
+# htmlext: HTMLファイルの拡張子(省略した場合はhtml)
 #
-# 固有IDに使用するドメイン。指定しない場合には、時刻に基づくランダムUUIDが入る
-# urnid: urn:uid:http://example.com/some-book-title/1.0.2/
-# CSSファイル (yamlファイルおよびRe:VIEWファイルを置いたディレクトリにあること)
-stylesheet: stylesheet.css
-# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと)
-# texstyle: samplemacro
-# LaTeX用のdocumentclassを指定する
-# texdocumentclass: ["jsarticle", "b5paper,oneside"]
-# LaTeX用のコマンドを指定する(platex or lualatex)
-# texcommand: "platex"
-# 目次として抽出するレベル
+# CSSファイル(配列で複数指定可)
+# stylesheet: ["stylesheet.css"]
+
+# ePUBのバージョン (2か3)
+# epubversion: 2
+# HTMLのバージョン (4か5。epubversionを3にしたときには5にする)
+# htmlversion: 4
+
+# 目次として抽出する見出しレベル
 toclevel: 3
-# セクション番号を表示するレベル
+
+# 採番の設定。採番させたくない見出しには「==[nonum]」のようにnonum指定をする
+# 
+# 本文でセクション番号を表示する見出しレベル
 secnolevel: 2
-# EPUBのバージョン(現時点では2または3。デフォルトは2)
-epubversion: 2
-# HTMLのバージョン(現時点では4または5。デフォルトは4。epubversionを3にした場合は自動で5に設定される)
-htmlversion: 4
-# 表紙を出力するか
-titlepage: true
-# 目次を出力するか
-toc: true
-# EPUB標準の目次以外に目次を作成するか
-mytoc: null
+
+# 付録の連番のスタイル。null(アラビア数字1〜。デフォルト)、alpha(英字A〜)、roman(ローマ数字I〜)
+# appendix_format: null
+
+# 以下のsecnolevelはまだ未実装。
+# 前付でセクション番号を表示する見出しレベル(未実装)
+# pre_secnolevel: 0
+# 後付(付録)でセクション番号を表示する見出しレベル(未実装)
+# post_secnolevel: 1
+# 部番号を表示する見出しレベル(未実装)
+# part_secnolevel: 1
+
+# EPUB2標準の目次以外に物理目次ファイルを作成するか。省略した場合はnull (作成しない)
+# ePUB3においてはこの設定によらず必ず作成される
+# mytoc: true
+
+# 表紙にするHTMLファイル。ファイル名を指定すると表紙として入る
+# cover: null
+# 表紙に配置し、書籍の影絵にも利用する画像ファイル。省略した場合はnull (画像を使わない)。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg)
+# coverimage: null
+# 表紙の後に大扉ページを作成するか。省略した場合はnull (作成しない)
+# titlepage: null
+# 自動生成される大扉ページを上書きするファイル。ファイル名を指定すると大扉として入る
+# titlefile: null
+# 原書大扉ページにするHTMLファイル。ファイル名を指定すると原書大扉として入る
+# originaltitlefile: null
+# 権利表記ページファイル。ファイル名を指定すると権利表記として入る
+# creditfile: null
+
 # 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる
-colophon: null
-# XHTML生成後に実行するプログラム。$1:HTMLの生成されたディレクトリ $2:Re:VIEWファイルのあるディレクトリ $3:起動時指定のyamlファイル名
-# posthook: hook.sh
-# EPUBで表紙をコンテンツに含めるか。デフォルトでは作成されない。yesにするとiBooks等でも最初に表紙が表示されるようになる
-cover_linear: null
+# colophon: true
+
+# 裏表紙ファイル (画像はcoversまたはimagesに配置する)。ファイル名を指定すると裏表紙として入る
+# backcover: null
+
+# プロフィールページファイル。ファイル名を指定すると著者紹介として入る
+# profile: null
+# プロフィールページの目次上の見出し
+# profiletitle: 著者紹介
+
+# 広告ファイル。ファイル名を指定すると広告として入る
+# advfile: null
+
+# 取り込む画像が格納されているディレクトリ。省略した場合は以下
+# imagedir: images
+
+# 取り込むフォントが格納されているディレクトリ。省略した場合は以下
+# fontdir: fonts
+
+# imagedir内から取り込まれる対象となるファイル拡張子。省略した場合は以下
+# image_ext: ["png", "gif", "jpg", "jpeg", "svg", "ttf", "woff", "otf"]
+
+# fontdir内から取り込まれる対象となるファイル拡張子。省略した場合は以下
+# font_ext: ["ttf", "woff", "otf"]
+
 # review-compileに渡すパラメータ
 params: --stylesheet=sample.css
 # Pygmentsカラーリングを利用する (pygments外部gemが必要)
 # pygments: true
-# デバッグフラグ。nullでないときには一時ファイルをカレントディレクトリに作成し、削除もしない
-debug: null
+
+# カタログファイル名を指定する
+# catalogfile: catalog.yml
+# 1ページの行数文字数と1kbごとのページ数を用紙サイズで指定する(A5 or B5)。
+# page_metric: A5
+# あるいは、配列で指定することもできる
+# 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数、1kバイト毎のページ数
+# page_metric: [40,80,40,80,2]
+
+# 以下のパラメータを有効にするときには、
+# epubmaker:
+#    パラメータ: 値
+#    パラメータ: 値
+#   ...
+# という構成にする必要がある(インデントさせる)
+
+# epubmaker:
+# 目次を要素の階層表現にしない。省略した場合(null)は階層化する。
+# 特に部扉が入るなどの理由で、構成によっては階層化目次でepubcheckに
+# パスしない目次ができるが、そのようなときにはこれをtrueにする
+#  flattoc: null
+# 目次のインデントレベルをスペース文字で表現する(flattocがtrueのときのみ)
+#  flattocindent: true
+# NCX目次の見出しレベルごとの飾り(配列で設定)。EPUB3ではNCXは作られない
+#  ncxindent:
+#- 
+#- - 
+# フックは、各段階で介入したいときのプログラムを指定する。自動で適切な引数が渡される
+# プログラムには実行権限が必要
+# ファイル変換処理の前に実行するプログラム。スタイルシートのコンパイルをしたいときなどに利用する。
+# 渡される引数1=作業用展開ディレクトリ
+#  hook_beforeprocess: null
+# 前付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+# 渡される引数1=作業用展開ディレクトリ
+#  hook_afterfrontmatter: null
+# 本文の変換後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+# 渡される引数1=作業用展開ディレクトリ
+#  hook_afterbody: null
+# 後付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。
+# 渡される引数1=作業用展開ディレクトリ
+#  hook_afterbackmatter: null
+# 画像およびフォントをコピーした後に実行するプログラム。別の画像やフォントを追加したいときなどに利用する。
+# 渡される引数1=作業用展開ディレクトリ
+#  hook_aftercopyimage: null
+# ePUB zipアーカイブ直前に実行するプログラム。メタ情報などを加工したいときなどに利用する。
+# 渡される引数1=ePUB準備ディレクトリ
+#  hook_prepack: null
+# 変換したHTMLファイルおよびCSSを解析して厳密に使用している画像ファイルだけを取り込むか。デフォルトはnull(imagesディレクトリすべてを取り込む)
+# なお、フォント、カバー、広告についてはこの設定によらずディレクトリ内のものがすべて取り込まれる
+#  verify_target_images: null
+#  verify_target_imagesがtrueの状態において、解析で発見されなくても強制的に取り込むファイルの相対パスの配列
+#  force_include_images: []
+# Re:VIEWファイル名を使わず、前付にpre01,pre02...、本文にchap01,chap02l...、後付にpost01,post02...という名前付けルールにするか
+#  rename_for_legacy: null
+# ePUBアーカイブの非圧縮実行
+#  zip_stage1: "zip -0Xq"
+# ePUBアーカイブの圧縮実行
+#  zip_stage2: "zip -Xr9Dq"
+# ePUBアーカイブに追加するパス(デフォルトはmimetype、META-INF、OEBPS)
+#  zip_addpath: null
+# EPUBで表紙をコンテンツに含めるか。デフォルトでは作成されない。yesにするとiBooks等でも最初に表紙が表示されるようになる
+#  cover_linear: null
+#
+# epubmaker:階層を使うものはここまで
+
+# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと)
+# texstyle: samplemacro
+# LaTeX用のdocumentclassを指定する
+# texdocumentclass: ["jsarticle", "b5paper,oneside"]
+# LaTeX用のコマンドを指定する(platex or lualatex)
+# texcommand: "platex"
+# LaTeX用のオプションを指定する(default: "-kanji=#{kanji}")
+# texoptions: "-kanji=utf-8"
+# LaTeX用のdvi変換コマンドを指定する(dvipdfmx)
+# dvicommand: "dvipdfmx"
+# LaTeX用のdvi変換コマンドのオプションを指定する
+# dvioptions: "-d 5"
+
+# 以下のパラメータを有効にするときには、
+# pdfmaker:
+#    パラメータ: 値
+#    パラメータ: 値
+#   ...
+# という構成にする必要がある(インデントさせる)
+#
+# pdfmaker:
+# TeXコンパイル前に実行するプログラム。変換後のTeXソースを調整したいときに使用する。
+# 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+#   hook_beforetexcompile: null
+# TeXコンパイル後に実行するプログラム。索引作業をして再度コンパイルしたいときなどに使用する。
+# 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+#   hook_aftertexcompile: null
+# PDF(book.pdf)作成後に実行するプログラム。PDFに加工を施したいときに使用する。
+# 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ
+#   hook_afterdvipdf: null
+#
+# pdfmaker:階層を使うものはここまで