0013 号 巻頭言

初稿：2006-02-20

リファレンスマニュアル整備について

Rubyist Magazine 第 13 号をお届けする。

今号は、咳さんこと関将俊さんのインタビュー「Rubyist Hotlinks 【第 13 回】 関将俊さん」、Rails でのテストについて、基本的な書き方からコツやカバレッジツールの紹介までを行う「RubyOnRails を使ってみる 【第 6 回】 テストの書き方」、「滝川クリステルプラグイン」「高橋メソッドプラグイン」「コード表示プラグイン」といった役に立ったり立たなかったりするプラグインを参考に qwikWeb のプラグインの作り方を説明する「qwikWeb の仕組み 【第 2 回】 qwikWeb のプラグインを作ってみよう」、コメントのつけ方からインターフェース設計まで触れつつ、DSL を用いた衝撃の添削が炸裂する「あなたの Ruby コードを添削します 【第 3 回】 dbf.rb」、open-uri と並び HTTP でのアクセスを Ruby で書く際には欠かせない net/http を紹介する「標準添付ライブラリ紹介 【第 7 回】 net/http」、「よい言語」という評判は聞くけれど実際に使われている場面にはなかなか出会えないマイナーな言語である Dylan を紹介する「Rubyist のための他言語探訪 【第 6 回】 Dylan」、連載最後を飾るのは YAML 版 XPath ともいえる YPath とその実装について紹介する「プログラマーのための YAML 入門 (探索編)」、ついにまつもとさんをマージした YARV について、分岐の概略とコンパイルの実際から最適化まで説明する「YARV Maniacs 【第 7 回】 YARV 命令セット (4) 分岐」、韓国と九州の Rubyist を紹介する (そういえば coderace の話は進んでなくてすみません……) 「世界の Rubyist」、先日発売された Ruby の入門書、『Ruby プログラミング基礎講座』の「書籍紹介」と「読者プレゼント」、そして「0013-RubyNews」と「0013-RubyEventCheck」など、いつものように盛りだくさんの内容となっている。

「0013-RubyNews」でも触れられているとおり、先日、島根県の鷺の湯温泉にて、Ruby 温泉ミーティングが開催された。 「ミーティング」といっても事前にプログラムが決められているわけではなく、全国各地にいる普段会い難いひとたちといっしょに会って温泉にでも入ろう、という程度の気楽な集まりである。 それでも、20 名近くのものが集まり、プレゼンの発表を行ったり温泉に入ったり剣を振ったりと盛況であった。

その中で、リファレンスマニュアルについて話をした。 Ruby のリファレンスマニュアルは、現在 http://www.ruby-lang.org/ja/man/ 上で整備が行われている。 日々行われる Ruby の変更に、それなりに追随していっているとは思うが、必要十分にメンテナンスが進んでいるとは言いがたい。 とりわけ、Ruby 本体にもともと含まれているライブラリではなく、標準添付されているライブラリについて、ドキュメントが整っていないものもある。 そのせいか、Ruby のドキュメントへの批判をよく聞く。

仕様の変更に追随するべく現状のマニュアル整備を続けていく、ということはとても重要なことである。 まめに更新されている方々には本当に頭が下がる。 しかし、現在マニュアルが不十分なものについては、今の努力では追いつかないかもしれない。 このような現状を打破するには、組織だった動きが有効であるだろう。 そしてそれは、個々のユーザの自助努力に任せることではなく、日本 Ruby の会のような曲がりなりにも多くの人数を抱えている団体の行うべきことだろう。

そこで、Ruby の会で組織的にリファレンスマニュアルの整備を行うことを考えた。 まだ「考えた。」だけで、その後も何ら具体的な行動を行っていないのだが、そのとき話した内容を、ここにまとめておく。

まず、現在「ruby 1.7 feature」「ruby 1.8 feature」というのが残っている問題について。 これは現状では不要であるが、Ruby 1.6 のリファレンスがないために残っている。 そこで、1.6 版の最終版として、どこかの時点で凍結したものを用意し、入手できるようにしておく。 そして、今後編集していく本体の方からはすべての「ruby 1.7 feature」「ruby 1.8 feature」を削除すればよいだろう。

なお、1.9 feature については、そのまま残しても構わないが、無理につけ加える必要もないので、必要に応じてつけていくことになるだろう。 まずは 1.8 の安定版のマニュアルを作ることを優先するべき、という判断の元、1.9 への対応については今後の課題とする。

標準添付ライブラリは、前述の通り、現状ではリンクのみで済ませているものもある。 とはいえ、便利のためにすべて取り込むようにする。

文書のフォーマットについては、引き続き RD 形式を使用する。 rdoc やその他のフォーマットの使用を検討する提案もあったが、すでにあるリファレンスが RD 形式となっていること、ツールも rdtool や refe 等それなりに揃っていることが理由である。

もっとも、現状のフォーマットには問題もある。 話題になったものとしては、既存のクラスにメソッドを追加するようなライブラリが上手く記述できない、ということがあった。 これについては、何かしら上手い記述方法を考える必要がある。

ページ名というか URL については、原則として英語で記述した方がよい、という意見があった。 現状では日本語を URL エンコードしたURL が使われているものがあるが、そこからの移行を考える必要がある。

作業環境としては、現在ドキュメント用の ML があるが、マニュアル整備に特化した作業を集中的に行うのであれば、別途独立した ML を立ち上げ、そこをメインとした方が 良いだろう。 おおまかなスケジュールとしては、以下のような形を想定している。

  • 2 月中に ML を立ち上げ、フォーマットと概要を決め、参加者を募る。
  • 3 月中に記述方法等の編集方針を固め、担当をアサインし、見直しと追加作業を行う。
  • 4 月中にいったん原稿を締め切る。足りない部分、作業ができなさそうな部分についてはリアサイン等を行う。
  • 5 月中に全体締切
  • 6 月にはβ版を作成し、内容についてレビューを行う。
  • 7 月中に正式に公開する。

これは、Ruby の会発足 2 年目のうちに成果を出せるように、というスケジュールである。 別に合わせる必要性はないが、区切りとしては妥当だろう。

ライセンスについては、現在の配布条件よりも、Creative Commons 等の広く使われているものにした方がよいかもしれない。 これも別途検討の必要があるだろう。

方針はおおむね以上である。 これはあくまで温泉ミーティングで行われた議論を元に整理したものであって、今後の活動等については Ruby の会 ML と rubyist ML に話を通しつつ、決めていくことになる。 Ruby の会内外のみなさまのご協力をお願いしたい。

(るびま編集長　高橋征義)