Toshです。

In message "[ruby-list:20017] Re: RD with method index (again)"
    on 00/01/03, Koji Arai <JCA02266 / nifty.ne.jp> writes:
>((<ほげHOGE>))をそういう見出しが存在すれば((<ほげ(({HOGE}))>))
>とみなしてくれるのはうれしいかもしれないですが必要って程でも
>ないと思います。
>
># ちゃんとソースを見てないんですが、そもそも((<ほげ(({HOGE}))>))
># が許されない今の制限はどういう理由なんでしょう?

理由は、「僕がどういう仕様にしていいか判断がつかなかったので、ほったら
かしになっている」です。(^^;;

ラベルが
  == ほげHOGE
でリファレンスが
  ((<ほげ(({HOGE}))>))
だったら、上のラベルへの参照とみなしていいのか、とか。逆に
  == ほげ(({HOGE}))
に対して
  ((<ほげHOGE>))
だったら、どうか?とか。

identityの一致と言うものをどのように考えるのかが決まらなかったので
とりあえず保留にしておいて、一番単純なモノだけを実装してあります。

ここらへんのことを議論にフィードバックしなかったのはさぼってたからです。

>> トップレベルの定数は"main::Const"では?
>
>定数はクラスやモジュールで定義されるモノだからmainってことは
>ないと思います。
>
>HOGE = "hoge"
>puts Object.constants
>=> PLATFORM
>   ENV
>   ...
>   HOGE
>   ..

あ、勘違いしていました。すみません。

>> >> リファレンスマニュアルみたいな用途を想定されていると思いますが、
>> >> それ考えると"Class"をいちいち書くのが多少めんどくさいかもしれません。
>> >
>> >うーん、クラスの宣言も可ってのはどうです?
>私が口走った「クラスの宣言」っていうのはとりあえず置いといて・・・
>
>この辺りの便宜についてはもう少し様子見でもいいかと思います。
>"--- Class#method" の慣習はあくまでも慣習なので従いたくなけ
>ればクラス名省略しても(RDとしては)問題ないわけですし。

了解です。

>perldoc ならぬ rubydoc とかを考えたときこの程度のツールでは
>クラス名は特に必要ないですね。
>一方、大きめのリファレンスマニュアルのためには必要でして、どっ
>ちにでも対応できるのは利点と言えます。
>
>ただし、両者をマージしようとしたとき(小さいRDをあつめて1つの
>RDドキュメントとして何かをしたいとき)にクラス名を書いてない
>RDの存在が問題になるかも知れないですけど、それはそのときに考
>えたい気もする(あまり先を考えすぎて実装が遅れるのもちょっと
>嫌ですし)。

同意します。まだ暗中模索って感じですしね。

>作りました。えっとどうしようかな。in.comingに
>  ruby-man.rd.gz
>を置かせてもらいましたが、docにでも移動してください>まつも
>とさん(ドキュメントのRAAってあり?)

見てみました。
今の段階でもこれだけのサイズのドキュメントにもなんとか対応できる
感じですね。すばらしい。

# クラス階層は自動生成できればうれしいかも。

>お試しで MethodList を実装してみたのでRDへのパッチをこのメー
>ルの最後につけます。

こっちはまだちゃんと見ていないのでまた後で。

>ruby-man.rdの中身ですが、texinfoからrdへの変換を行ったので多
>少構成が変わってます。
>
>あと、
>
>  "chapter"		=> "=",
>  "section"		=> "==",
>  "subsection"		=> "===",
>  "subsubsection"	=> "====",
>  "appendix"		=> "=",
>  "appendixsec"		=> "==",
>  "appendixsubsec"	=> "===",
>  "appendixsubsubsec"	=> "====",
>  "chapheading"		=> "+",
>  "majorheading"	=> "+",
>  "heading"		=> "++",
>  "subheading"		=> "+++",
>  "subsubheading"	=> "++++",
>
>のような変換を行いました。見出しのレベルの意味が違ったり存在
>しないレベルがあります。

見出しレベルは6つだと足りないでしょうか?

># 「スーパークラス」とかの項を@nodeにしてもしょうがない。
># これはどうしようかなぁ(rd2texi)。

HTMLで複数ページ出力するようになると、
  {HTMLのページ} <--> {Texinfoの@node}
の対応ですよね?

HTMLの複数ページ出力では、今のところ考えているのは
  * ユーザーの指定したレベルのHeadlineより上でページ分割。
    
    たとえば、"2"とかだと、"=", "=="の部分でページ分割。
    (ちょっと説明しづらい。Texinfoだと"="を"@chapter"とかに翻訳する
    ときに、その前に"@node"を置く事に、って感じでしょうか。)

  * "=begin"..."=end"で囲まれてるところをページ(ノード)の単位に。
    個人的には"=begin" ... "=end"にあまり意味を与えたくないものの、
    これだと結構柔軟に対応できそうなので、便利です。

>・オプションや用語集で、DESCLISTが使えなかったというのがありま
>  した。
>
>  :: label STRINGLINE
>
>  なんてのがあるといいのかなと漠然と考えてます。

これは、普通のDescListはなぜ使えなかったのでしょうか?

>・以下のようなのがありましたが、
>
>  --- Array.[](index ...)
>
>  ちょっとわかりにくい?
>
>  -> Array.[index ...]
>  という出力が得られますが
>
>  -> Array[index ...]
>  とした方が良かったですね。

>・以下のようなのもありました
>
>  --- ENV.delete(key)
>
>  "." は、「クラスメソッド」ということになってましたが、
>  "ENV"はクラスでもモジュールでもなかった(rd2texiとか作ると
>  「クラスメソッド」とかの分類になるなぁ。とりあえず気にしな
>  いでおこう)

ENVのようなのはかなり特殊なのでしょうがないでしょう。

>・センタリングがない
>
>  別に必要だとは思ってないです。

これからもたぶん無いと思います。

>・((<substitute|label>))
>
>  これ必要ですね。

必要なのですが、リファレンスは今後変更が大きそうなので、ちょっと落ち着
くまで実装はサボってます。

>> ただ、rubytk.rdを見ても思いましたが、やっぱり一番必要なのは複数ページの
>> HTMLに分割して出力する機能ですね。(^^;;
>
>あっこれ重要です。大きめのRDは変換に時間がかかるので小さいRD
>を個別に変換できるとよいのですが。(中間ファイルが必要になる
>けど私はそれでも構わない)

個別変換ですか。Marshal使ってTreeを出力してしまうとか。
考えておきます。

ただ、0.5.5にはIncludeもあるので、RDファイル自体の分割はできます。
<<< ruby-man-array.rd
とかすると、Texinfoの@inputと同じようにそこにRDファイルの内容が
そのまま書かれているのと同じように振舞います。
「個別に変換」とはちょっと違いますが、それなりに役に立つはずです。

>別件ですが、1つ気になってるのは
>
>  * ITEM
>
>    DESCRIPTION...
>
>でITEMの後にWHITELINEを要求されるのですがこれは本来必要ない
>ですよね?(DESCLISTは逆にWHITELINEを許さない)

問題をちょっと把握できてないので、的外れな事を書くかも知れません。

  : ITEM
    DESCRIPTION...

の場合、DecsListの一行目は特別扱いなのでItemListとは違います。
ITEMの部分はDescListのTermになって、2行目以降に継続する方法はありません。
ItemListの場合は一行目から普通のリスト内ブロックなので
  * ITEM
    DESCRIPTION...
と書くと、"ITEM"と"DESCRIPTION..."は同じTextBlockとみなされるはずです。
違うTextBlockにしたい時は間にWHITELINEが必要です。
あらいさんの問題ってこういうことでしょうか?

後半部分ですが、DescListの場合も
  :ITEM
   
   DESCLIST

は許されるようになってると思います。手元の簡単なテストではこれを通しま
した。ただ、リストにはルールの衝突が残っているので、大規模なドキュメント
になるとRaccが先読みしきれずにエラーがでるかもしれません。
もしそうでしたら、それはバグです。
# この衝突はなんとかしたいのですが、いまだに直し方がわからない。

---
Tosh
Toshiro Kuwabara