モデルプロジェクトのための最低限 rd
rd とは
rd とは ruby script に埋め込むドキュメントの形式である. rd 形式はテキストファイルとしても読みやすく, 容易に html に変換できるので, ちょっとした文書やメモの作成にも有用である. 地球流体電脳倶楽部 dcmodel プロジェクトでは, 作業メモ・各種手引き を rd 形式で作成している.
この文書は, emacs で html ファイルは書けるけど rd は知らない人が 30 分でとりあえず rd 形式のメモ書き・文書作成ができるようにするためのガイドである.
作業の流れ
rd を使うための手順は以下の通りである.
- rd 関連資源のインストールと環境設定
- 自分の手元の計算機で rd を使う場合は, 必要な資源をインストールし, 環境設定を行う.
- dennou サーバなど, 既に rd がインストールされた計算機を使う場合は 次の「rd ファイルの作成」へ進む.
- rd ファイルの作成
- rd 形式のファイルを emacs 等のエディタで作成する.
- html への変換
- rd2 コマンドで html ファイルを作成する.
- Makefile.rd2html を取って来てあれば make 一発でできる.
rd 関連資源のインストールと環境設定
rd 関連資源のインストール
rd を使うためには ruby, rdtools, rd2html-ext をインストールする必要がある. また， 場合によっては rd2-filter.patch を当てる必要があるだろう.
ソースからインストールする場合
以下のリンク先のサイトからソースをダウンロードし, インストールする.
Debian GNU/Linux 3.1 (sarge) で使う場合
apt を使ってインストールができる. 指定するパッケージは以下の通りである.
# apt-get install ruby rdtool librd-ruby1.8 librd-html-ext-ruby1.8 rdtool-elisp
環境設定
Makefile.rd2html とスタイルシート
dcmodel プロジェクトでは, rd2 コマンドで html ファイルを作成するための Makefile (Makefile.rd2html) と, 作成した html ファイル用のスタイルシートを用意している. これらを使うならばそれぞれ
より取得する.
それぞれの使い方は Makefile.rd2html を用いて html へ変換する方法, スタイルシートについて を参照.
rd-mode.el
emacs で rd 形式のファイルを作成する場合, rd-mode.el を使用すると便利である. rd mode では以下のようなことができる.
URL の入力 M-x rd-insert-url (ショートカット C-c C-u) 参照の入力 M-x rd-insert-ref (ショートカット C-c C-i r) ラベルの一覧 M-x rd-show-label-list
rd-mode.el は rdtool に含まれている. しかるべきディレクトリへ格納し, 設定を行う. debian の場合は rdtool-elisp パッケージをインストールすると使えるようになる.
rd ファイルの作成
早く覚えるためには
rd に限らないが, 早く覚えるコツは「真似をすること」, 「自分の手で試行すること」である.
真似をするには, 他の人が作ったrd 形式ファイルを見るのが良い. 今あなたが見ているこの html ファイルを作成するもとになった ファイル <URL:http://www.gfd-dennou.org/library/dcmodel/doc/TEBIKI.dcmodel-rd-guide.rd> を参考にするのも良いだろう.
また, 自分でどんどん試してみることが重要である. 「こういう書き方はできるのだろうか?」 と疑問に思ったら, 書いて html に変換して自分の目で確認する, という事を 繰り返すのが良いだろう.
rd 形式ファイルのファイル名
ファイル名には拡張子 .rd をつける.
rd 形式ファイルの概観
rd 形式で作成したメモ書きのファイルは以下のようになっている.
=begin = 大見出し(たいてい, 文書のタイトル) # 履歴情報 (新しい更新履歴を上に追記していくこと) # * 2006/06/07 (小高正嗣) 構成を変更 # * 2005/06/21 (石渡正樹) dcmodel 用に変更 == 中見出しその 1 本文あれやこれや. * 箇条書き * 入れ子の箇条書き * 入れ子の箇条書き * 箇条書き == 中見出しその 2 本文あれやこれや. === 小見出しその 1 本文あれやこれや. … =end
以下, rd の文法に関して必要最低限の少し詳しい説明を記述する. 上の例で「書き方は大体わかったぜ!」という人は以下は 読まずにどんどん rd 形式のファイルを書き, 次の html への変換 を行うとよい. 凝った rd 形式のファイルを書きたい人は より高度な使い方 を参照するとよい.
本文の書き方
最初に "=begin" を, 最後に "=end" を書く. "=begin" と "=end" の間にはほぼ何を書いても良い. 多くの場合, 書いた文章はそのまま html に変換される. しかし, いくつか注意するべき点もある.
- html に変換した時, 改行は有効にならない.
- 段落を変える時には空行を入れる.
見出し
見出しを作るには, = または + を先頭の文字にしてスペースを あけて見出しの名前を書く. 見出しのレベルは = または + の 文字数によって決められる. 以下に例を示す.
= 大見出し <h1></h1> に変換される
== 中見出し <h2></h2> に変換される
=== 小見出し <h3></h3> に変換される
==== もっと小さい見出し <h4></h4> に変換される
+ もっと小さい見出し <h5></h5> に変換される.
本文より小さいフォントになるので使わない方が良い.
++ もっと小さい見出し <h6></h6> に変換される.
本文より小さいフォントになるので使わない方が良い.
大見出しは HTML ファイルに変換された際, <title></title> にも転用されるため, 必ずファイルの先頭で書くこと. また, 1 つのファイルに 2 つ以上用いないこと.
履歴情報
ファイルの履歴情報に関しては, rd ファイルの先頭に以下のように記述する. '#' はコメントアウトのマーカで, 行頭にこの文字を書くことで HTML に変換される際にその行は無視される. 陽に HTML に表示したい場合は '#' をはずしても良い.
# 履歴情報 (新しい更新履歴を上に追記していくこと) # * 2006/06/07 (小高正嗣) 構成を変更 # * 2001/03/14 (森川靖大) RD フォーマットに変換 # * 1999/11/21 (石渡正樹) 作成
このように記述しておくことで, 後述の Makefile.rd2html を用いて html に変換 した際, 履歴情報の一部が自動的に HTML ファイルの最下端に表示される.
dcmodel Development Group / GFD Dennou Staff dcstaff@xxxxx.xxx Last Updated: 2006/06/07, Since: 1999/11/21
箇条書き
番号無しの箇条書きリストを作るには, * を先頭の文字にしてスペースを 開けて項目を記述する. 箇条書きを入れ子にする (箇条書きの中に箇条書きを書くこと) には 字下げする.
番号付きの箇条書きリストを作るには, ( ) 付きの数字を先頭に書く.
以下に例を示す.
箇条書きの書き方例 * 項目 1 * 項目 2 * 項目 2-1 * 項目 2-2 * 項目 3 (1) 項目 1 (2) 項目 2
打ち込んだまま出力する
打ち込んだ通りにそのまま出力させるには字下げする. 本文の書き方でも書いたように, 通常改行は無視されてしまうので コマンドの出力結果やプログラムソースを入力する場合には 困ってしまう. その場合は以下のように書く.
=begin … 普通の本文. そのまま出力する部分. (字下げしてある) そのまま出力する部分. (字下げしてある) 普通の本文. (字下げをやめた) … =end
前の行よりも深く字下げされている部分がそのまま出力される. 字下げの深さがもとに戻った時に, そのまま出力される部分 も終了する.
ファイル内参照
html に変換した時に, ファイル内の別の場所を参照することもできる. 例えば, 以下のように rd ファイルを作って html に変換すると ( ( < モデル A の説明 > ) ) と書かれた部分は 「モデル A の説明」の見出しへハイパーリンクされる.
=begin … == モデル A の説明 … == 補足 … ((<モデル A の説明>)) に書かれているように… … =end
ハイパーリンク
ハイパーリンクを作成する例は以下の通り.
URL を文字列として表示
((<URL:http://www.gfd-dennou.org>))
こうすると, html に変換した時に URL がハイパーリンクされ, <URL:http://www.gfd-dennou.org> のように URL がそのまま 表示される.
表示する文字列を明示的に指定
((<地球流体電脳倶楽部|URL:http://www.gfd-dennou.org>))
こうすると, 'URL:' 以降に記述される URL がハイパーリンクされ, 地球流体電脳倶楽部 のように表示される.
html への変換
作成した rd 形式のファイルを html に変換するには rd2 コマンドを使う. しかし, rd2 コマンドを使う際には多数のオプションを付けたくなるものであり 初心者にはちょっととっつきづらい. 細かい設定がなされた Makefile.rd2html を取得して使うのが良い.
Makefile.rd2html を用いて html へ変換する方法
手順は以下の通りである.
- <URL:/library/dcmodel/doc/sample_Makefile/Makefile.rd2html> を取ってくる.
- Makefile.rd2html を Makefile という名前に変更する.
- その Makefile を rd 形式のファイルが置いてあるディレクトリに置く.
- make する.
これで, 文法エラーが無ければ rd 形式のファイルから html ファイルが作られる. 以上の手順を実際にコマンドラインで実行した例は以下の通りである.
% cd (rd ファイルが存在するディレクトリ) % wget http://www.gfd-dennou.org/library/dcmodel/doc/sample_Makefile/Makefile.rd2html % mv Makefile.rd2html Makefile % make
この方法で作成された html ファイルをブラウザで表示させると, あなたが今見ているこのページとは見てくれが全く違ったもの になる. このページと全く同じように表示させるためには スタイルシートと Makefile の設定が必要である. 詳しくは スタイルシートについて を参照せよ.
また, Makefile.rd2html では, 目次を作成する・履歴の入ったフッタを作成する・ 電脳倶楽部トップページへのハイパーリンクを作成する等々の凝ったことも やっている. それらの詳細が知りたければ, Makefile.rd2html の中身を解読すること.
rd2 コマンドの起動例
rd 形式のファイルから html ファイルへの変換には rd2 コマンドを用いる Makefile.rd2html の内部では, rd2 コマンドを起動している.
以下は, コマンドラインで直接 rd2 コマンドを起動して html ファイルを生成する 場合の非常に簡単な場合の例である.
$ rd2 --r rd/rd2html-ext-lib --out-code=euc sample.rd > sample.html
rd2 コマンドには, 上記の例には書いていないオプションも存在する. 詳しくは, rd2 コマンドの help モード
$ rd2 -h
や rdtool, rd2html-ext ソースに付属のドキュメントや 参考文献 を参照のこと.
スタイルシートについて
rd2 コマンドでは html のスタイルシートファイルを --with-css オプションで指定することができる.
Makefile.rd2html では, スタイルシートとして <URL:http://www.gfd-dennou.org/library/dcmodel/htmltools/dcmodel.css> が使われている. 今あなたが見ているページも dcmodel.css を使用している.
この dcmodel.css を手元のマシンで使いたい場合には, 以下のようにする.
- dcmodel.css を取得する.
-
CSS = /library/dcmodel/htmltools/dcmodel.css
の行を, 手元のマシンで dcmodel.css を格納した path にあわせて変更する.
目次の自動生成
文書が大きくってくると, 目次があると便利である. Makefile.rd2html では以下の RDHINDEX の値を設定することで, ファイル中の 見出し を 自動解析し, ファイルの先頭に このような目次 を挿入する.
RDHINDEX = 1
デフォルトは 0 になっており, 1 〜 3 まで設定できる. 1 ならば「中見出し」 ('==' のレベル) のみ, 3 ならば「中見出し」から「もっと小さい見出し」 ('==', '===', '====' のレベル) の目次を挿入する.
より高度な使い方
定義文の書き方
語句の説明・定義を記述するには以下の書式を用いる.
=begin :語句 A 語句 Aの説明文 :語句 B * 語句 Bの説明その1 * 語句 Bの説明その2 =end
メソッドの説明の書き方
rd はもともと ruby script のドキュメントを記述するためのものである ので, ruby のメソッドを説明するための書式も用意されている. 例は以下の通り
=begin
--- Array.new([size[, vall]])
引数 size の大きさを持つ入れ過と生成します.
=end
Inline (文字に関する各種修飾)いろいろ
- 強調:
- ((*強調*)) => 強調
- 画像挿入(rd2html-ext の「--ref-extension」オプションを有効にすること):
- ((<IMG|"IMG:http://hoge">)) => IMG
- プログラムのコード片:
-
(({while gets})) =>
while gets - 脚注:
- ((-footnote-)) => *1
- キーボード操作:
- ((%ruby -v %)) => ruby -v
- 変数あるいはプログラムの引数:
- ((|var|)) => var
- 任意のHTML inline要素を入れる (rd2html-ext の「--native-inline」オプションを有効にすること):
- ((:<font color=Lime>黄緑</font>:)) => 黄緑
- フォーマット抑制. RD フォーマットで RD についての文章を書く:
- (('verb')) => verb
- ファイルのインクルード:
-
<<< インクルードファイル名(拡張子(.rd, .rb)を除いて指定)
あるいはコンパイル時に $ rd2 a.rd b.rb c.rd > test.html とすると順番にインクルードされる.
html 片の挿入
上記 の [HTML inline 要素を入れる] よりも複雑な html 片を入れたい時や, rd2html-ext がインストールされていない時に用いる. コンパイルオプション 「--with-part=html:include」 が必要.
=end =begin html <p><table border="1"><tr><td>表の</td><td>挿入</td></tr></table></p> =end html =begin
オプションあれこれ
rd2 コマンドのオプション
- --enable-br:
- TextBlockでの改行は出力HTMLではBR要素に置き換えられる
- --head-element, --with-part=head:head :
- 任意のHTML片をHEAD要素内に指定することができる (はずだそうだが, うまくいかなかったという報告もある.)
rd2html-ext の オプション
- --headline-secno:
- 見出しに自動的に節番号を付ける.
参考文献
Footnotes
*1footnote