2011-12-18
■ [ruby][event] Rubyの次世代リファレンスマニュアルを構想する会をやりました
参加者のみなさまありがとうございました。
以下は議論のメモです。(まだぜんぜん整理できてなくて混沌としていますが…)
とりあえず1/31が「中間報告」なので、それまでに何か動いて見せられるようなものを作りたいと思います。ソースはgithubに置きます。
ゴール
1. 日英以外への翻訳をやりやすくしたい
* 何から始めれば良いかわかること
* 一時的に翻訳して終わりではなく、最新版に追従していくのを助ける手段があること
* 成果物が便利な形で利用できること(web, cli等)
2. 日英版を「統一」したい
* 現状は、リファレンスサイトに何か機能を追加する場合に
(例えば、ユーザがコメントを追加できる機能を実装するとか)
日本語チームと英語チームが別々に作業しなければならない
* 統一されていれば、日英以外の翻訳が出てきたときも
そのまま恩恵を受けられる
3. 今のWeb UIよりも便利にしたい
* たとえば、refeのように柔軟な検索ができるようにするとか
(Ar i で Array#include?とかArray#indexが引ける)
# myruremaがこの記法に対応してなかったので直さないと…
イメージ
http://doc.ruby-lang.org/ja/ に日本語リファレンスがあって、 http://doc.ruby-lang.org/en/ に英語リファレンスがあって、 セレクトボックスで他言語版に飛べて…みたいな感じ (参考：php.org)
現状
* 英語版は、Rubyソースコードにrdoc記法で書かれている * 日本語版は、bitclust記法で書かれている(るりまプロジェクト) * bitclustでは、メソッドの返り値の型とかがきっちり書かれている (メタデータ)
問題
* rdocベースで共通化すると：
るりまのメタデータは捨てることになる
* もったいない…
* bitclustベースで共通化すると：
rdoc記法をbitclust記法に変換しなければならない
* 結構大変そう
* rdocの<i>や<em>に対応するタグがbitclustにはない
方針
* rdocベースでも、bitclustベースでもないやり方
* るりまのメタデータを楽に有効利用できそうなやり方
* rdoc記法とbitclust記法に両対応したビューア(Railsで書かれたWebサイト)を作る
* 英語チームは、今まで通りrdocを書く
日本語チーム(るりまプロジェクト)は、今まで通りbitclust用のデータを書く
* それらのデータをバックエンドとするRailsアプリを作る
* どのようなデータを持てばいいか？
* まず、Rubyの全てのメソッドを列挙する
* それぞれについて、英語の説明、日本語の説明を対応づける
* それらをWebから見られるようにする
* るりまのメタデータ(返り値の型情報とか、どのバージョンから入ったとか)は、
言語によらず使い回せるはず
+-----------+
|Array#slice|--+-- 英語の説明
+-+---------+ | (rdocの当該エントリをHTML化したもの)
| +-- 日本語の説明
| | (るりまのエントリをHTML化したもの)
| +-- ○○語の説明
| (英語のエントリを翻訳したもの)
|
+--- メタデータ
(るりまのコンテンツから抽出したもの)
* bitclustの作る検索用データも、言語によらず使い回せる
* どの言語版でもrefe的検索が可能に
TODO
* 本当に上手く行くのか考える
* プロトタイプを作る
* バージョンの扱いについて考える
* ライブラリで上書きされるメソッドの扱いについて考える
今後のRubyリリース
* 1.9.4は出ない
* 1.8.8も出ない
* 1.8.7-pxxxは出るかも(1年後まで)
* 1.9.3-pxxx
(パッチレベルの更新)
* ドキュメントはほとんど変わらないはず
* 2.0.0-p0
(新バージョン)
* 「完全互換」? (まつもと定義)
* ライブラリが減る可能性あり (gem化)
-> #@until(2.0.0)
* るりまはいつ2.0対応の作業を開始する予定なのか？
feature freeze (Oct. 24 2012) から作業開始してもいいだろう
rdocの更新部分を翻訳しつつ、内容が実際の挙動と合って
なければレポートを送ったりしつつ
* いつ1.8.7を捨てるのか？
* サポートが切れたら (2013/06)
* 捨てると言っても、doc.ruby-lang.orgから削除する必要はないかも
* 例えば「最後に生成されたHTML」を置いておくだけなら
* どういうドキュメントが消せるのか？
#@until(1.8.7)
#@since(1.9.2)
#@else
... この部分
#@end
ユーザがコメントを書ける機能について
* るりま:
okkezさんの個人サーバで一時期やっていた
メンテが大変なので、disqusに移行しようと思ったところで
止まっている
* PHP:
Noteが書ける
英語のみ(英語以外書くなと書いてある)
イディオムとか落とし穴とか
コピペしてそのまま使えるものもあったり
* apidock.com
thanksの多いものが上に表示される
* jquery:
disqus
新規コメントは中止されてるんだが、なんでだろう
* メリット
* いいのがあれば本体のexampleに取り込むとか
他言語のドキュメント
* Python:
章立てされていて、本みたいになっている
TeX?
Sphinx
* Gauche:
TeX-info
章立てされている
* PHP.orgのいいところ
* サイドバーに同じクラスのメソッドが出る
* see alsoがある
- るりま/rdocでもあるやつはある
* ユーザが補足を書ける
* バグレポートへのリンクがある
* ドキュメントの間違いを指摘するためのリンクがある
* モジュールのカテゴリごとの一覧がある
- 旧Wikiにはあった
- るりまでもトップページに書けばいいかも
いろいろな機能
* ソースコードが参照できる(.c, .rb)
* バグ報告へのリンク
* ドキュメントの改善案の投稿フォームへのリンク
* ライブラリのカテゴリ分け
翻訳支援
* 何からやればいいか手順が明記されていること
* 上流の変更への追従が簡単であること
* rdocの変更の通知
夢
* 複数のCSSからテーマを切り替えられるとか * Pythonのdoctestみたいにして、rdoc部分のEXAMPLEを Ruby処理系のテストに役立てるとか
[ツッコミを入れる]