From: Masaki Fukushima <fukusima@...>
Date: 1998-10-28T20:28:07+09:00
Subject: [ruby-list:10418] Re: Ruby Document Format

福嶋です。

Hiroshi Igarashi <igarashi@ueda.info.waseda.ac.jp> wrote:
> 私もRuby/GTKのAPI一覧をXMLで作りかけていたところです。
> GTKモジュールはクラスが100以上あって、おそらく拡張
> モジュールとしては最大級のものだと思います。そのAPI一覧を
> HTMLで書くのは無謀だと思いまして、XMLにしました。

すごいですね。私も Ruby/GTK のドキュメント欲しいです。
多分、自分の他にも XML で ruby の API を書いている人はいるとは思って
いましたが、まさか物理的にこんなに近くにいるとは思いませんでした。
# 例えば、廊下を2本はさんだ向こう側とか...  (^^)

> XML→他のフォーマット の変換方式は色々あるでしょうが
> まずソースとなるXML形式でのDTDをしっかり決めたいですね。
> もちろんXML以外でふさわしい形式があればそれでもいいのですが。

そうですね。まずは DTD を決めるのが先決だと思います。

私の考えた形式は短い例で示すと以下のようなものです。

  <class>
    <name>String</name>
    <desc>
      文字列クラス．
    </desc>
    <instance_methods>
      <method>
        <usage>each([rs]) {|line|...}</usage>
        <usage>each_line([rs]) {|line|...}</usage>
        <desc>
          文字列中の各行に対して繰り返します．行の区切りは
          <var>rs</var>で指定します．<var>rs</var>のデフォルト値は変数
          <r>$/</r>の値です．
        </desc>
      </method>
    </instance_methods>
  </class>

この DTD を設計した時の基本方針は、「ドキュメント作成者が少しでも
楽に書けること」です。 

具体的には

  o  <usage>each([rs]) {|line|...}</usage>

    と書くだけで、each がメソッド名、rs は引数名、line はブロックへの
    引数だと自動的に判断してほしい。これをわざわざドキュメント作成者が
    明示的にに示さなければならないのは面倒。そして HTML に変換する時
    にはその情報に従って、

      <code>each([<var>rs</var>]) {|<var>line</var>|...}</code>

    といったタグづけをして欲しい。

  o  <r>$/</r>
     <r>Fixnum</r>

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

などです。こういったことを実現するためには、

 Style Sheet + 汎用の XML アプリケーション(変換ツール含む)

では出来なそうに思えました。
# それとも私が知らないだけで、汎用の方法で可能なのでしょうか?

そういうわけで、今 HTML への変換ツールを作っています。
他の方の意見もぜひ聞いてみたいです。

---
福嶋正機