達人出版会日記

ITエンジニア向けの技術系電子書籍の制作と販売を行う達人出版会のブログです。

ReVIEW記法 基本文法最速マスター

今日はソニーリーダーの話じゃなくて、当社で発売している本の方の話題です。

達人出版会が発行しているドキュメントは、今のところ全てReVIEW記法という記法を使って書かれています。ReVIEWのアプリ（というか単純なコマンドライン用のコマンド）を使えば、EPUBやLaTeXに自動変換できたり、InDesignを使って印刷用原稿にすることもできます。実際、高橋が執筆した『Rubyレシピブック第3版』などは、ReVIEWを使って書いた原稿から、InDesignによって印刷用に使われています。

ReVIEW記法の真面目な紹介はサイトの方にある程度書いてありますが、簡単なチュートリアルということで、はてなっぽく書いてみます。というか「はてな記法 基本文法最速マスター」を参考にしてます。

基礎

プレーンテキスト

多くのWiki記法や簡易マークアップ言語と同じ様に、特別な記法(後述)を使った表現以外は全てそのまま出力されます。

特に、ASCIIに含まれない日本語文字などは、何も考えずに書けばそのまま表現することができます。以下がそのサンプルです。

ReVIEW記法は簡単に書けて便利に使えます。

ReVIEW記法では、空行が一つの段落(paragraph)として扱われます。また、行末の改行は無視されます。段落ではない改行のためには、改行インライン記法が用意されています。

これは1行目に表示されます。@<br>{}これは2行目に表示されます。@<br>{}
これは3行目に表示されます。ソースでの改行(\n)などは無視されます。

これ段落の区切りが入って、１行空いて５行目に表示されます。

一般的には素直に段落ごとに書かれることを前提として表現されるので、原則としては改行インライン記法は使わないことを強くお勧めします。はっきりいって微妙な記法である改行インライン記法ですが、これも「改行とかほいほい書くな」という強い意志を感じさせてくれます。感じてください。

なお、テキスト中の改行文字は取り剥がされて、削除されます。英単語などを改行をまたがって書くときには、まちがって単語などが連結しないよう、気をつけてください。ピリオドまでの一文はそのまま改行を入れずに書くことになります。

著者用マークアップ

最終的には出力されない、原稿のみに書く記法として、著者用マークアップ記法があります。

#@# コメント。この行には何を書いても無視されます。
#@warn(警告です。プリプロセス時にメッセージが出力されることがあります。)

著者用マークアップはまだまだ洗練されてないですね。単純なコメントとして使うのが無難な感じです。

文字列修飾

ReVIEW記法には「@<」で始まるインライン記法がいくつかあります。これを使えば、単語を強調したり、ハイパーリンクが書けたりします。

@<em>{どうしても}必要になります。

(↑太字になります。)

@<kw>{ReVIEW}を使います。

(↑キーワードを書く際に使います。強調されたりします。)

@<href>{http://www.google.com/}

(↑URLを書いて、ハイパーリンクを実現します。)

@<code>{x = obj.x.to_s}

(↑ソースコードの引用です。)

ここに書いていないものでも多数の記法があります。今後も拡張されそうな気がします。とはいえ、あんまり駆使しすぎるとうるさくなるので、必要に応じてどうぞ。

数式

ReVIEWの数式は、@インライン記法を使って書きます。

式は、@<m>{y = \alpha x ^ 2 + \beta x + \gamma}となります。

まだ実験的な実装な気もするので、svgなどの図にしておいた方が安心かも。

脚注

脚注は@と//footnoteを使います。@{識別子}で脚注の入る場所を、//footnoteで脚注の中身を記述します。

現在のReVIEW処理系はRuby@<fn>{ruby}で記述されています。

//footnote[ruby][まつもとゆきひろさんが開発されているスクリプト言語]

脚注がどの位置にどう表示されるかは、出力用に変換されるフォーマットによって異なります。これも原則としては、あまり使い過ぎず、極力本文を上から順に読んで理解できるようにしておいた方がいろんな意味でお勧めです。

見出し

ReVIEWでは、5つのレベルの見出しが用意されています。

= ç« 
== 節
=== é …
==== 段
===== 小段(という名前でいいんでしたっけ? まあ、段より小さいカタマリです)

さらに、見出しにはタグが指定できます。現在仕様で決められているのは「column」タグです。

===[column] ちょっと便利な使い方

便利なようでそれほど便利じゃない、でもちょっとだけ便利な使い方です。

この辺りはRuby方面ではよく知られている記法であるRD、RDocに共通している感じですね。やっぱり手軽に書けるのが便利です。

リンク

ReVIEWではURLなどを使って、他のコンテンツへのハイパーリンクを書くことができます。URLで他のコンテンツなどをリンクするには、@記法を使います。

達人出版会のサイトは @<href>{http://tatsu-zine.com/} にあります。
@<href>{http://d.hatena.ne.jp/tatsu-zine/,達人出版会日記} もご覧ください。

@記法を使った部分は、HTMLでは普通のリンクに、LaTeXでもPDFに変換するとクリックするとブラウザを開くようなリンクになります。ただし、URLが長い場合、そのまま表示しようとすると横を突き抜けてしまって残念な見栄えになることが散見されます。これは何とかしたいのですが。

テキスト以外のメディア

画像の表示

画像の表示には、//image記法を使います。

//image[capture12][画面キャプチャその12]

こうすると、画像ディレクトリ/ファイル名-capture12.{jpg|png}が埋めこまれます。外部への画像ファイルを(URLなどを使って)文書に埋め込む方法はありません。

また、インラインに画像を含めるには、@記法を使います。

きっと@<icon>{capture12}←こんな顔をしていたはず。

画像のフォーマットはPNGかJPEGを使うのが無難でしょう。出力フォーマットによっては他の形式の画像もサポートしていることがあります。

整形済みテキストブロック

記号として解釈される文字列や改行を含めるには、整形済みブロックを使います。

emlistブロックを使うと、連番がふられない、キャプションもないの整形済みブロックになります。

//emlist{
def fact(n)
  return 1 if n == 1
  n * fact(n-1)
end
//}

listブロックを使うと、連番がふられる、キャプションつきの整形済みブロックになります。引数の一つ目はこのブロックの識別子（ID）に、二つ目はキャプション用の文字列になります。

//list[fact][factメソッド定義]{
def fact(n)
  return 1 if n == 1
  n * fact(n-1)
end
//}

sourceブロックを使うと、連番がふられない、キャプションつきの整形済みブロックになります。

//source[fact.rb]{
def fact(n)
  return 1 if n == 1
  n * fact(n-1)
end
//}

sourceブロックはあんまり使ったことがありません。emlistかlistがあれば何とかなります。

（追記：上記の例で、ブロックの終端が「//}」ではなく「}」と書かれてました。すみません。現在は修正済みです。）

引用ブロック

//quote記法を使うと、他のコンテンツから引用したものであることを表現できます。

//quote{
「おい地獄さ行ぐんだで！」
　二人はデッキの手すりに寄りかかって、蝸牛が背のびをしたように延びて、海を抱え込んでいる函館の街を見ていた。
（小林多喜二『蟹工船』）
//}

これは普通に多用します。

コマンドラインブロック

コマンドラインには、ソースコード用のブロックとは別に//cmd記法を使います。

//cmd{
$ ruby -v
ruby 1.9.2p0 (2010-08-18 revision 29036)
//}

プログラミング系以外はあんまり使わないかもしれません。

表組み

本文中で表を指示するには、//table記法を使います。

  //table[envvars][重要な環境変数]{
  名前            意味
  -------------------------------------------------------------
  PATH            コマンドの存在するディレクトリ
  TERM            使っている端末の種類。linux・kterm・vt100など
  LANG            ユーザのデフォルトロケール。
  LOGNAME         ユーザのログイン名
  //}

リスト

箇条書き（リスト）は、番号がつくものとつかないものの二つあります。番号がつかないものは「*」で、番号がつくものは「1.」とか「2.」とかのように記述します。数字はでたらめでもちゃんと連番し直して表示します。

 * 水星
 * 金星
 * 地球
 * 火星

 1. 水星
 2. 金星
 3. 地球
 4. 火星

用語リストも書けます。が、これは記法に難があるというか、定義部の記法はどこまでどうするのか、みたいな問題もあるので、あんまり多用しないほうがいいかもしれません（と言いつつ、私は結構使っています）。

: foo
    困った時によく使われる名前。変数名やメソッド名として。
: bar
    上に同じ
: hoge
    日本ローカルのようだが、上と同じような目的に使われている。

リード文ブロック

章の頭にあるリード文には、//lead記法を使います。

//lead{
本章ではインストールの仕方を紹介します。
//}

リード文は歴史的事情により//readとも書けます。が、//leadだけ知っていれば十分でしょう。



とりあえずこんなところでしょうか。ソースにどう書けば最終出力結果はどうなるのか、というのがいまいち分かりづらいかも。出力結果の画像とかがないとイメージしづらいですね……余力と機会があればまた今度。