いがらしです。

「[ruby-list:10418] Re: Ruby Document Format」で 、
Masaki Fukushima <fukusima / goto.info.waseda.ac.jp>さんは書きました：

> 福嶋です。
> すごいですね。私も Ruby/GTK のドキュメント欲しいです。

ドキュメントと呼べるほどのものになるには、だいぶ時間が
かかると思います。とりあえずGTK本家にある各メソッドが
実装されているか否かを一覧できるものが欲しくて始めました。
本家のドキュメントにも記述がないものが多いので
困っています。GTK付属のInfo文書(あとヘッダファイル)以外に
APIを一覧できるものはないでしょうか？

> 多分、自分の他にも XML で ruby の API を書いている人はいるとは思って
> いましたが、まさか物理的にこんなに近くにいるとは思いませんでした。
> # 例えば、廊下を2本はさんだ向こう側とか...  (^^)

はい、確かに廊下を2本はさんだところにいます(^_^)
廊下ですれ違ったことがあったかも知れませんね。

>   o  <usage>each([rs]) {|line|...}</usage>
> 
>     と書くだけで、each がメソッド名、rs は引数名、line はブロックへの
>     引数だと自動的に判断してほしい。これをわざわざドキュメント作成者が
>     明示的にに示さなければならないのは面倒。そして HTML に変換する時
>     にはその情報に従って、
> 
>       <code>each([<var>rs</var>]) {|<var>line</var>|...}</code>
> 
>     といったタグづけをして欲しい。

タグ内のテキストをさらに解析するのはXML的にはちょっと
反則っぽい気がします(勉強不足ではっきりしたことは言えませんが)。
それに説明文中の引数名もvarタグで囲みたいと思っても、
そちらまで自動でやるのは難しそうです。

きちんと引数(あるいはメソッドのsignature)を情報として明示して、
説明文中ではそれを参照するようにするのがたぶん筋なのでしょう。
上のcodeタグで囲まれた出力は、明示された引数情報を基に
生成すると。もっとも記述するのがかなり面倒になってしまいますが...。

>   o  <r>$/</r>
>      <r>Fixnum</r>
> 
>     とか書いたら、HTML に変換する時には自動的に variable.html#slash や
>     Fixnum.html にリンクを張って欲しい。

XSLなどでは各要素の処理規則中にスクリプトが書けるので、
そこでそれなりの処理をすればできるのでは？
私の方ではincludeしたモジュールやスーパークラスへのリンクを
張ることはできています。

> などです。こういったことを実現するためには、
> 
>  Style Sheet + 汎用の XML アプリケーション(変換ツール含む)
> 
> では出来なそうに思えました。
> # それとも私が知らないだけで、汎用の方法で可能なのでしょうか?

出力形式に依存したXSLやXML Treeのvisitorを書く必要は
ありますが、ライブラリやツールは汎用のもので
実現できるのではないでしょうか。


必要に駆られて始めたものの付け焼き刃的な知識しかないので、
こうすべきだという提案ができなくてすみません。
＃今日IBMのXML for Javaをとってきて、
＃初めてvalidationを体験しました^_^;)

---------------
いがらし ひろし