[ruby-list:41158] Re: RD と rdoc に関する newbie な質問

From: "conundrum /" <[e-mail]>
Subject: [ruby-list:41157] RD と rdoc に関する newbie な質問
Date: Mon, 19 Sep 2005 20:41:50 +0900

るびきちです。

> RD形式版リファレンスマニュアルに向き合っていました。
> RD版って書いてあったので、RDかぁと、
> るびきちさんの「Ruby 256倍 魔道編」を開き、読み始めました。
ありがとうございます＾＾

紛らわしいですが、リファレンスマニュアルのRDはただのRDではなく、独自の拡張RDです。
通常のRDとは別物と考えてください。

> rdoc なるものを見つけました。
> rdoc... これは RD の進化型なのだろうか... と

進化形・・・なのかな？
両者は一長一短です。

RD/RDocともに同様の目的で使うことができます。
RDもRDocの共通点は、Rubyのコメントにドキュメントを埋め込むことです。

Rubyでは

=begin
から
=end

までがコメントになります。
そのコメントの中でいろいろなマークアップが定義されています。

一方、RDocは # による1行コメントの後にドキュメントを埋め込んでいます。
そのため、両者を混在させることもできます。

# This is a test class.
class Test
  # This is a test function.
  def test
    # ...
  end
end

RDでも

=begin
This is a test class.
=end
class Test
=begin
--- Test#test
    This is a test function.
=end
  def test
    # ...
  end
end
  
というふうに書けますが、見辛いですよね(^^;

結局RDでドキュメントを埋め込むには、次の形がいいと思います。

=begin
This is a test class.

--- Test#test
    This is a test function.
=end
class Test
  def test
    # ...
  end
end
    
英語のドキュメントはRDocで、日本語のドキュメントはRDという風に使い分け
されていることもあります。
現在はRDocが埋め込みドキュメントの事実上標準となっています。
手軽なので自分もRDocで書いています。

それでもまだRDには使い道が残っています。
RDは書きやすく、読みやすい形式でありながら、rd2できちんとしたHTMLを生成してくれるので、
HTMLジェネレータとして使えます。
自分自身、RDをHTMLジェネレータとして使っていることが圧倒的に多いです。



> RD と rdoc って、ちがうもの
はい。

> RD と、るびきちさんのツールたちは、いまも「活き」てる
> で、「魔道編」の内容通り、いまも、別途インストールが必要
はい。

> RubyのRD形式版リファレンスマニュアルは、正確には rdoc 形式
これは違います。独自の拡張RDです。

> rdoc は、なんかすごいかっこいいHTMLを生成してくれるっぽい
デフォルトではフレームを使ったHTMLを生成してくれます。
rdocに-1オプションを付けると、1ページにまとめてくれます。

> RD版リファレンスマニュアルは、ダウンロード後にどう処遇したら
> よろしいんでしょう？
RDは比較的可読性が高いのでそのまま読みましょう（笑）。

分割されたHTMLドキュメントが欲しいならば、
http://elbereth-hp.hp.infoseek.co.jp/ruby.html
ここからダウンロードしましょう。

コマンドラインからドキュメントを調べたいのならば、refeもおすすめです。
http://i.loveruby.net/ja/prog/refe.html


P.S.
Rubyのライブラリドキュメントの形式が多様化しているので、
RDindexの後継となるツールを作成している途中です。


るびきち☆
http://www.rubyist.net/~rubikitch/