ささだです。

　仕様のたたき台が出たらその後で議論、と思っていたんですが、もう決定にな
るんでしょうか。日記での仕様検討はあんまり読んでません。ML で議論する前
のたたき台作りだとばかり思っていたから。


　気になっていたのが、

・ドキュメントの構造
　http://www.typemiss.net/blog/kounoike/20060120-54
　この辺で出ている話。

・ライブラリに複数のクラス、モジュールがある場合は全部きちんと分ける？

・目次の作り方
　今は全部手作業ですが、自動化できるか？

・パラメータ（引数）、返り値の型はどう表現する？


の点です。


Minero Aoki wrote:
> 青木です。
> 
> 遅くなってすみません。
> 新リファレンスマニュアルの作業概要を書きます。
> 
> 作業はファイルフォーマットの変換から始めます。
> 組み込みライブラリ → 標準添付ライブラリの順番でやりましょう。
> 
> 変換作業では、ファイルごとに担当を決めて進めます。レポジトリに
> 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/


-- 
// SASADA Koichi at atdot dot net


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