青木です。

ものすごく遅くなってすみません。
ようやく時間が作れそうなので返信します。

  In mail "[ruby-reference-manual:9] Re: 参加希望"
  Kazuhiro NISHIYAMA <zn@m...> wrote:

> 西山和広です。

> > = Rubyリファレンスマニュアルの不便な点
> > 
> >   * 組み込みと標準添付と C API のリファレンスがバラバラ。
> >     いま C API は見ることすらできないし。
> >     かなりたくさん書いたので、データだけでも救出したいんだけど。
> 
> 見ることすらできないというのはRDPに置いてあったという
> ことでしょうか?

そうです。


> >   * ウェブ上でメソッドを検索したい。
> 
> どういう検索方法を想定しているのでしょうか?
> 
> ブラウザの検索機能に頼るので良ければメソッド一覧ページが
> ありますが。

ReFe 相当の検索を求めています。当然継承関係も含めて。

ついでに言えば、Eiffel の flat みたく、継承したメソッドも含めて
あるクラスにあるメソッドを一覧表示するモードも欲しいなあと思う
のですが、これは理想的な状態での話なので当面は考えません。


> >   * Rwiki だとページ名が変えにくい。
> 
> ページ名変更機能がありますが、そういうのではなく
> mediawikiのようにredirectが欲しいということでしょうか?

む、その機能は知りませんでした。どうすれば使えますか？


> >   * Rwiki だと日本語ページの URL が汚い。
> 
> これはRWikiとは関係なく、ページ名の規則の問題だと
> 思います。

同意できません。そういう操作をあっさり許すのは RWiki の責任です。
日本語ページと URL の結び付きを決めてるのも RWiki です。例えば
ID 方式の Wiki では少なくとも URL は汚くならないでしょう。また
実際に RWiki で URL とキャプションを分離しようとすると面倒なのは
否めません。


> > = その他リファレンスマニュアルについて思うこと
> > 
> >   * 「Ruby 言語仕様」をどうにかしたい。書くか、捨てるか。
> 
> 編集用Wikiと公開用のstaticなページを分けるときに
> 書きかけのものは公開用に反映しないということが
> 出来ると良いかもしれないと思いました。

Subversion バックエンドが使えるなら、書きかけのは別ブランチで
やれば済むのかもしれませんね。


> >   * ((|...|)) タグがウザい。
> >     引数なんて自動的に検出できるんだから自動で付ければよい。
> 
> MethodListは自動で付けていますが、他にどこで自動的に
> 検出できるのでしょうか?

ドキュメント本体です。例えば Array#index の場合、

Array#index
--- index(val)
--- index {|item| ...}          ruby 1.9 feature

    最初の形式では、val と == で等しい最初の要素の位置を返
    します。

    ruby 1.9 feature:
    二番目の形式では、ブロックが真を返した最初の要素の位置を返します。
    ブロック引数には、要素が順に渡されます。

    等しい要素がひとつもなかった時には nil を返します。

val が引数なので、解説中で「val」が出てきたら高確率で引数の val
と考えられます。それなら自動的に ((|val|)) にしてしまってもよい
でしょう。TMail のリファレンスとかでやってますが、まず外れません。


> >   * 「Ruby 1.x feature」のタグ付けが統一されておらず見苦しい。
> 
> 現状は
> * 個別のMethodListの末尾(別名が増えた場合など)
> * 説明の先頭(メソッド自体が増えた場合など)
> * 説明の途中の段落の頭(メソッドの仕様変更など)
> というパターンになっていると思っていたのですが、
> どのあたりが統一されていないと感じるのでしょうか?

そのパターン分けが細かすぎて嫌だということです。表記は Ruby 1.8 先端の
仕様に統一して、「Ruby 1.x feature」は本体末尾のみに記述するべきだと
思います。あるいは、いまと逆に古いバージョンの仕様のほうを互換性情報と
して述べるか。

あと、個人的に開発版の仕様は書くべきでないと思ってます。書くとしても、
デフォルトで見せるのは不適切。

理想的には、ドキュメントのうち別バージョンの解説をしている部分を自動的に
隠したり抜き出したりできるといいなあと思います。そうすると Ruby のバー
ジョンに対応するドキュメントを動的に生成できるし。


> >   * (ReFe) どのファイルがリファレンスなのか自動判別しにくい。
> 
> 現状はページの先頭に`###nonref'というものが入っているページが
> ありますが、完全ではなさそうな気がします。

ReFe 作者＆メンテナとして断言しますが、ものすごく抜けてます。
もうヒューリスティックに判定するのはウンザリしました。


> >   * (ReFe) パースしにくい。フォーマットを統一してほしい。
> 
> パースしやすいフォーマットを提案してほしいです。

上記のも含めて言うと、RD 前提なら最低でも以下は満たしたいです。

  * あるファイルがリファレンスであると確実に判定できること
  * キャプションのレベルを揃えること
  * 「インスタンスメソッド」「特異メソッド」などのキャプションを統一すること
  * self[key] にしてみたり [](key) にしてみたりしないこと
  * スーパークラス、include しているモジュールの記述を一定させること

理想的には以下も追加。

  * 「Ruby 1.x feature」をメソッドシグネチャの横に書かないこと
  * 「Ruby 1.x feature」がブロックとして抜き出せること


--
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/