RD でも書いてみようか 【第 3 回】 RD as a ruby document format

書いた人:mput

はじめに

これまでの連載をみても明らかなように、RD は一般的な文章を書くために使うことができます。実際に、RD を使って毎日の日記を書いている人も rubyist の中にはそれなりに存在します。しかし、多くの人にとって、RD の一番馴染み深い使い道は「ドキュメントを読み書きすること」でしょう。ライブラリについてきた README.rd を読まないと使い方が分からないとか、そういうケースは意外に多いものです。今回は、ドキュメント用フォーマットとしての RD の側面に光を当ててみたいと思います。

メソッドリスト

Ruby ドキュメントとしての顕著な記法のひとつにメソッドリストがあります。これはメソッドの名前とその役割をペアにして記述したもので、以下のような外見をしています。

--- Thread.exclusive { ... }
    ブロックから出るまで、どれかひとつのスレッドしか動かないようにする。こ
    れは「このメソッドを実行したスレッドしか動かさない」というふうに勘違い
    しやすいですが、違います。ブロックの中で Thread.pass を呼んで、メソッ
    ド切り替えを起こしてみると良く分かります。
       require 'thread'
       3.times {|i| Thread.start(i) {|i| loop { puts i; sleep 1 } } }
       Thread.exclusive do
          loop do
             puts 3
             sleep 1
             Thread.pass # <---------- (A)
          end
       end
    (A)の Thread.pass で、上で作った三つのスレッドのどれか((-たぶん2-))に
    実行が切り替わりますが、今度はそのスレッドから他のスレッドに処理が移ら
    なくなるのが観測できるでしょう。

    教訓: Thread.exclusive と Thread.pass を混ぜると痛い目に遭う

見てのとおり "--- " ではじまっている行がメソッドの名前で、以下インデントをそろえてこのメソッドの解説が書いてあります。このメソッドには引数がないのですが、引数のあるメソッドの場合

--- Hash#fetch(key1) {|key2| ... }
    引数のあるメソッドの例。ブロック引数も書けます

このように、それっぽい場所に引数を書けばよいです。また、引数が省略できる場合は

--- Date.new([y [, m [, d [, s]]]])
    引数が省略できます。全部省略したら今日の日付になるようです

のように、省略できる部分を[]で括って示すことができます。

多くの場合、拡張ライブラリに付属してくるリファレンスマニュアルにはこのようなメソッドリストがいくつも並んでいることでしょう。

ドキュメントでよく使うインライン

引数

ドキュメント内では、一般の文章とは違ったインラインがいくつか使われます。代表的なのは引数をあらわすインライン ((|引数名|)) で、メソッドリストとともに使われる場合が多いものです。例を見てみましょう。

--- Enumerable#inject([k]) {|i, j| ... }
    ((|j|)) に self の各要素を次々に代入しながら、ブロックを逐次的に
    実行します。((|i|)) には直前に実行したときのブロックの値が代入さ
    れます。一番最後のブロックが実行された後のブロックの値がこのメソッ
    ドの戻り値になります。

    引数 ((|k|)) が与えられれば、最初のブロック実行のときにこれが
    ((|i|)) に代入されます。そうでない場合は self の最初の要素が
    ((|i|)) に、その次の要素が ((|j|)) に代入された状態からスタートし
    て、以下順に繰り返されます。

    例: Ruby ホームページの中で何回 "ruby" が書かれているか調べる
       require 'open-uri'
       URI("http://www.ruby-lang.org/en/").read.inject(0) {|r, i|
          r + (/ruby/i.match(i) ? 1  : 0)
       }

この文章の中で i とか j とか k とかの変数は例示のためにたまたま付けた変数であり、その名前に特に意味はありません。特に意味がないことを明示するために、これらの変数は ((|名前|)) のような形でマークアップしてあります。

コード

他によく使うものとして、プログラムコードを文中に埋め込む際に使う (({...})) があります。これは以下のように使うことが多いでしょう。

 --- Zlib::GZipWriter#finish
     gzip ファイルの終わりに到達したことにして、ストリームを閉じる。
     このメソッドを呼ぶ前に、 GZipWriter がラップしている IO オブ
     ジェクトに対して (({close})) が呼ばれると、gzipファイルが壊れ
     ます。 (({close})) するまえに必ず (({finish})) してください

入力

また、まれに使われるインラインとしては、ユーザーの入力を表す ((%...%)) があります。 これはユーザーに操作を求めるときに使います。

インストールするには ((%sudo ruby setup.rb%)) としてください

などと使うのが一般的です。HTML でいうと <kbd> ですね。

次回予告

というわけで、これまで 3 回にわけて RD の基本的な書き方を紹介してきました。

次回は、RD の文法そのものではなく、RD を処理して HTML やプレーンテキストに変換する処理系のお話をしたいと思います。おたのしみに。

RD でも書いてみようか連載一覧

Last modified:2005/09/20 13:37:04
Keyword(s):
References:[Rubyist Magazine 0009 号] [0009 号 巻頭言] [各号目次] [prep-0009]