From: conundrum / <conundrum@...>
Date: 2005-09-20T03:45:26+09:00
Subject: [ruby-list:41159] Re: RD と rdoc 	に関する newbie 	な質問

conundrumです。るびきちさん、直々の回答ありがとうございます。

まず、RD形式のリファレンスマニュアル、について。
------------------------------------------------

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

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

独自のRD拡張・・・ということは、rdoc形式というわけでもないってことですか。

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

ううっ！？
rdocで処理するものではなさそうってことはわかったのですが・・・
でもあの謎のファイル名 %A4%CF%A4%B8%A4%E1%A4%CB.rd とかって、
そのまま読むものっぽくないですよね。どこかからリンクされてるっぽい。
そうなると、何らかのブラウザが必要か、事前に処理が必要と思われ・・・
「そのまま読む」ものとは思いがたい。

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

ありがとうございます。これも取得して見てみましたが、rdoc で生成した
フレームを使ったHTMLではないんですよね。
るびきちさんがこういう紹介をしてくださったということは、
「RD版リファレンスマニュアル」の内容物を、上記のような「HTML形式」に
変換するための何らかのマジック、rdoc ではない方法が、きっとあるんですよね。


次に、RD/RDoc について
----------------------

>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で書いています。

なるほど了解いたしました。RDoc は RD を祖として、
現在では javaDoc や doxygen の Ruby版といった位置づけになっている、
と考えればいいように思えました。

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

自分もそう感じました。
プレーンテキストにちゃちゃっと書いて、ぱぱっとHTML化してくれるのは、
とても便利そう。少なくとも自分には、Wikiの該当機能をそこだけ抜き出して
localhost の上で使えるようにしてもらえているようで、とても魅力的に
感じます。
ので、早速インストールを試みたのですが、mswin32環境、cygwin環境共に、
下記のようなエラーに遭遇します。

$ pwd
/d/temp/download/languages/ruby/rdtool/rdtool-0.6.16

$ ls -aF
./           README.html*     bin/            setup.rb*
../          README.ja.html*  doc/            test/
.cvsignore*  README.rd*       lib/            test.rb*
HISTORY*     README.rd.ja*    makerdtool.rb*  utils/

$ ruby setup.rb
---> bin
<--- bin
---> lib
---> lib/rd
<--- lib/rd
<--- lib
---> bin
adjusting shebang: rdswap.rb
setup.rb:496:in `initialize': Permission denied - rdswap.rb (Errno::EACCES)
        from setup.rb:496:in `move_file'
        from setup.rb:1145:in `adjust_shebang'
        from setup.rb:1136:in `adjust_shebang'
        from setup.rb:1128:in `setup_dir_bin'
        from setup.rb:1127:in `setup_dir_bin'
        from setup.rb:1321:in `traverse'
        from setup.rb:1338:in `dive_into'
        from setup.rb:1319:in `traverse'
        from setup.rb:1313:in `exec_task_traverse'
        from setup.rb:1308:in `exec_task_traverse'
        from setup.rb:1123:in `exec_setup'
        from setup.rb:883:in `exec_setup'
        from setup.rb:704:in `invoke'
        from setup.rb:674:in `invoke'
        from setup.rb:1352

何がよくないのか、これをごらんになってピンとこられましたら、
情報をいただけませんでしょうか。

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

自分も、今年中には時間をつくって emacs使いになろうと決心しています。
RDindexって、xyzzyでも使えますか？

よろしくお願いします。

conundrum@hotmail.co.jp

_________________________________________________________________
無料でメールボックス250MBの 「MSN Hotmail」 
http://promotion.msn.co.jp/hotmail/fortune/input_un.asp