青木です。

遅くなってすみません。
新リファレンスマニュアルの作業概要を書きます。

作業はファイルフォーマットの変換から始めます。
組み込みライブラリ → 標準添付ライブラリの順番でやりましょう。

変換作業では、ファイルごとに担当を決めて進めます。レポジトリに
refm/api/ASSIGN というファイルが作ってあります。この表の該当
エントリに自分の SVN アカウント名を書いて、コミットした時点で
ファイルの担当が決まったものとします。忙しくて作業ができなくなっ
た場合は、また ASSIGN ファイルを書き換えてコミットしてもらえ
れば結構です。

現在、フォーマット変換が済んでいないファイル (ほぼすべて) には
*.off という拡張子がついてます。変換が終わったら svn mv で
「.off」のない名前に移動することで作業が完了したことを示します。
例えば _builtin/Dir.rd.off の変換が済んだら _builtin/Dir.rd
に移動します。

で、肝心のフォーマットですが、まず実例を見てもらうのがよいと思
います。例として _builtin/String.rd を変換してあるので、これ
を真似しながらやってください。参考のため、マニュアルも最後に
付けておきます。また、レポジトリの refm/api/FORMAT にも同じ
ものが入ってます。

また、ツール (bitclust) の bin/bc-convert.rb を使うと、簡単
な変換はすべて済ませられます。一度これを使って変換したあと、ざっ
と見て残りを手でいじるとよいでしょう。

  実行例
  % ruby -I./lib bin/bc-convert.rb String.rd.off > tmp
  % diff String.rd.off tmp

それ以外に、手で変換が必要になりそうなのは以下のところです。

  * 「= class String」などのレベル 1 ヘッダを新しい形式に変える
  * 「== Singleton Methods」「== Instance Methods」
    などのレベル 2 ヘッダを新しい形式に変える
  * 「メソッド一覧」は自動生成するので、すべて消す。
  * include と require を新しい文法に沿って書く
  * テキストがインデントしてたら全部下げる。
  * メソッドのシグネチャは Ruby の def と同じにする。
  * ハイパーリンクは文法がまだ決まってないのでいじらなくてよいです。
  * ((<ruby 1.x.x feature>)) はプリプロセッサの #@if に変換
  * 注釈 ((- ... -)) は消すか、プリプロセッサコメント #@# に変換

一通り変換が済んだら bitclust の bin/bc-list.rb でパースの
テストをしてみてください。

  実行例
  % ruby -I./lib bin/bc-list.rb String.rd.off
  #<BitClust::LibraryDescription:0x00002a96076618
   @classes=[#<class String>],
   @methods=
    [#<smethod String.new>,
     #<imethod String#+>,
     #<imethod String#*>,
     #<imethod String#%>,
     #<imethod String#==,>,>,<,<=>,
     #<imethod String#<<,concat>,
     #<imethod String#=~>,

これでちゃんと全部のエントリが表示されていれば OK です。
String.rd.off を String.rd に svn mv して作業を終えます。
どうせあとでまたちゃんとチェックするので、いまのところはだい
たい通っていればよいことにします。とにかく全部を変換するのが
先決です。

手順のまとめ

  1. 変換するファイルを決める (仮に _builtin/Hash とする)。
  2. refm/api/ASSIGN の _builtin/Hash の行に
     自分のアカウント名を書いてコミットする。
  3. bitclust の bin/bc-convert.rb で変換してみる。
  4. diff をとったりして変な変換をしていないか確認する。
  5. エディタでざっと見て残りを潰す。
     変な文章が目についたらついでに直してもよい。
  6. bitclust の bin/bc-list.rb にかけてチェックする。
  7. 大丈夫そうならコミット。
  8. Hash.rd.off を Hash.rd に svn mv して再度コミットする。


わからないことがあったらこの ML で聞いてください。ツールが
バグってる場合や、新しい機能が欲しいときも ML で聞いてください。

あと、コミットメールを早急に用意します。

--
青木峰郎



= リファレンスマニュアル記述フォーマット

ファイルのフォーマットは RD ベースです。
ただし、厳密にパースできるように制限を増やしてあります。

== ファイルの構造

新リファレンスではライブラリごとにファイルを分割します。
各ファイル (== ライブラリの記述) は以下のような構造をしています。

    require ライブラリ名
    require ライブラリ名
         ：
         ：

    <ライブラリのドキュメント>

    <レベル1ブロック>
    <レベル1ブロック>
         ：
         ：

ファイル冒頭では、そのライブラリが require しているライブラリ
を「require ライブラリ名」記述します。require はいくつ書いても
構いません。

続いてライブラリ自体のドキュメントを書きます。これは省略可能です。

最後に、以下に述べる「レベル 1 ブロック」を任意の回数記述します。
「レベル 1 ブロック」はクラスやモジュールの記述です。


== レベル 1 ブロック

レベル 1 ブロックはクラスやモジュールを記述します。
レベル 1 ブロックは以下のような構造をしています。

    = class クラス名 < スーパークラス名

    include モジュール名
    include モジュール名
         ：
         ：

    <クラスのドキュメント>

    <レベル2ブロック>
    <レベル2ブロック>
         ：
         ：

レベル 1 ヘッダ (「=」) には以下の種類があります。

  * class       クラス
  * module      モジュール
  * object      オブジェクト (ほぼ ARGF と ENV 専用)
  * reopen      既存クラスへのメソッドの追加
  * redefine    既存メソッドの再定義 (jcode, mathn など)

ヘッダの直後には、そのクラスやモジュールが include している
モジュールを「include モジュール名」で記述します。include は
いくつ書いても構いません。

続いてクラス自身のドキュメントを書きます。省略可能です。

最後に「レベル 2 ブロック」を任意の回数だけ書きます。
「レベル 2 ブロック」はメソッドのグループです。


== レベル 2 ブロック

レベル 2 ブロックは特定の種類のメソッドのグループを表現します。
レベル 2 ブロックは以下のような構造をしています。

    == Singleton Methods
    <メソッドエントリ>
    <メソッドエントリ>
          ：
          ：

レベル 2 ヘッダ (「==」) には以下の種類があります。

  * Singleton Methods
  * Private Singleton Methods
  * Instance Methods
  * Private Instance Methods
  * Module Functions
  * Constants
  * Special Variables


== メソッドエントリの文法

メソッドエントリは以下のような構造です。

    ---- メソッド名
    ---- メソッド名(引数)
    ---- メソッド名(引数) { .... }

    <メソッドのドキュメント>

引数の形式がいくつもある場合や、alias があるときは、上記の
ように「--- メソッド名」の行を連続して書いてください。

メソッドシグネチャは Ruby での def と同じように記述します。
旧リファレンスマニュアルでは「self + other」や
「self[key] = value」のような書きかたも許容されていましたが、
新マニュアルでは認められません。


== 通常のテキストの文法

ライブラリのドキュメント、クラスのドキュメント、メソッドの
ドキュメントでは以下に述べる共通の文法を使います。

=== 段落

通常の段落はインデントなしで書きます。

=== リスト

インデントするとリストになります。

[例]

   テキスト〜

       p Object.new
       p [1, 2, 3]

特殊な事情があってインデントが使えない場合は
以下の記法を使ってください。

    //emlist{
    リスト
    //}

    ※ 「//emlist{」と「//}」はインデントしない

=== 箇条書き

箇条書きはインデント + '*' です。インデントなしは不可。

[例]

   テキスト〜

     * 項目 1
     * 項目 2
     * 項目 3

=== 番号付きの箇条書き

番号付きの箇条書きはインデント + (1), (2), ... です。
インデントなしは不可。

[例]

   テキスト〜

     (1) 項目 1
     (2) 項目 2
     (3) 項目 3

=== ハイパーリンク

以下のようなハイパーリンク記法が使えます。

  * [[c:String]]       クラス String にリンク
  * [[m:String.new]]   メソッド String.new にリンク
  * [[m:String#dump]]  メソッド String#dump にリンク
  * [[m:String#[] ]]   メソッド String#[] にリンク
  * [[m:$~]]           特殊変数 $~ にリンク
  * [[lib:jcode]]      ライブラリ jcode にリンク
  * [[man:tr(1)]]      man ページ tr(1) にリンク
  * [[url:http://i.loveruby.net]]  URL http://i.loveruby.net にリンク

=== 削除された項目

RD の (({...})), ((|...|)) はサポートしません。
bc-convert.rb を使うと自動的にすべて削除されます。

脚注とコメントも廃止されました。コメントを書きたい場合は
プリプロセッサコメント「#@# ...」を使ってください。


== プリプロセッサ

各ファイルは事前に専用プリプロセッサで処理されます。プリプロセッサ
の命令はすべて行単位で、すべて「#@」で始まります。

=== #@#

「#@#」の行はコメントです。

=== #@include

「#@include(ファイル名)」で他のファイルをテキスト的に結合できます。
「ファイル名」は #@include の書かれているファイルからの相対パスを
探します。

[例]

  #@include(HTTP)
  #@include(HTTPHeader)
  #@include(HTTPRequest)
  #@include(HTTPResponse)

=== #@if

「#@if(条件) 〜 #@else 〜 #@end 」でバージョン依存コンパイルが
できます。例えば Ruby 1.8.0 以降にのみ適用される文章は以下
のように記述します。

[例]

  #@if (version >= "1.8.0")
  Ruby 1.8 以降では 〜〜
  #@end

いまのところ条件式の評価はテキトーなので、比較式 (>= とか == とか)
しか使えません。他の式が使いたいときは ML で相談してください。

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