History

私もリファレンスを書いてみたいわ！という方のためのチュートリアルです。このエントリは定期的に見直されるべきです。

1. ダウンロード

リポジトリからファイルを取ってきます。以下のコマンドを実行すると、カレントディレクトリにそれぞれrubydocとbitclustというディレクトリが作成されます。事前にruremaディレクトリを作成した上で、それぞれのコマンドを実行してもよいでしょう。

  • Subversionの場合：

    $ svn co http://jp.rubyist.net/svn/rurema/doctree/trunk rubydoc
$ svn co http://jp.rubyist.net/svn/rurema/bitclust/trunk bitclust

  • Git(git-svn)の場合：

    $ git svn clone http://jp.rubyist.net/svn/rurema/doctree/trunk  -r HEAD rubydoc
$ git svn clone http://jp.rubyist.net/svn/rurema/bitclust/trunk -r HEAD bitclust

取ってきたら、bitclust/bin/にパスを通しておいてください。

2. データベースの作成

BitClustは、一つのリファレンスファイルから各バージョンごとのリファレンスを自動生成する仕組みになっています。

まず、以下のコマンドでデータベースのディレクトリを作ります。(エンコーディングはいまのところeuc-jp限定です。)

$ cd refm/api
$ bitclust.rb -d ./db-1.8.7 init version=1.8.7 encoding=euc-jp

次に、以下のコマンドでデータベースを更新します。これには数分かかることがあります。

$ bitclust.rb -d ./db-1.8.7 update --stdlibtree=src

データベースのディレクトリ名は、ここではdb-1.8.7/としましたが、好きな名前を付けて構いません。

1.8.6や1.9.2など、Rubyの他のバージョンのリファレンスを書きたい場合は、versionを変えて上記の手順を繰り返して下さい。

3. リファレンスの記述

リファレンスの元になるデータは、doctree/の中に入っているテキストファイルです。ディレクトリ構成は以下のようになっています。

  • doctree/
    • refm/
      • api/
        • src/
          • ここに標準添付ライブラリのリファレンスが含まれます。
          • _builtin/
            • 組み込みライブラリのリファレンスが含まれます。
      • capi/
        • Rubyの拡張ライブラリ用のC APIのリファレンスが含まれます。
      • doc/
        • トップページや「Ruby言語仕様」など、その他のリファレンスが含まれます。優先順位は低めです。
      • old/
        • 旧リファレンスマニュアルの雑多なコンテンツのコピーです。Webからは見られません。
    • faq/
      • 旧リファレンスマニュアルの、Ruby FAQのデータのコピーです。いまのところ、Webからは見られません。

リファレンスはRDに似た書式で書かれています。テキストファイルなので、中身を見れば、なんとなく書き方が分かると思います。正確な書式についてはReferenceManualFormatDigestを参照してください。

さて、では実際にリファレンスを編集してみましょう。

TODO

4. プレビュー

$ bc-tohtml.rb doctree/refm/api/src/_builtin/Array --target=Array#pop --ruby=1.9.2 > /tmp/a.html

5. パッチを送る

るりまプロジェクトは Redmine でチケット管理を行っています。まずはアカウントを作成してください。

ログインすると、「新しいチケット」というメニューが増えて、チケットを新規作成できるようになります。

各項目は以下のように設定してください。

題名
どのメソッドやライブラリに関する修正かわかるようなタイトルをつけて下さい。
説明
変更内容を書いてください。
カテゴリ
普通の修正依頼の場合は、docを選べばOKです。リンク切れの報告の場合はdoc:brokenlinkにしてください。
ruby_version
Rubyの特定のバージョンに限る場合は、1.8.6, 1.8.7, 1.9.1, あるいは 1.8 や 1.9 などと書きます。分かる場合だけで構いません。
ファイル
ここにパッチファイルを添付します。

その他の項目は、デフォルトのままで構いません。