[ruby-list:20017] Re: RD with method index (again)

新井です。

# 今年もよろしくお願いします。

>>> From: Toshiro Kuwabara <[e-mail]>
>>> Date: 30 Dec 1999 00:56:12 +0900
>>> Subject: [ruby-list:19988] Re: RD with method index (again)

> Toshです。

> # RD書く人は生のRDを見ているので、カッコを省略した形にするのはわかり
> # にくいかも？ それとも、カッコをつけたままのほうがわかりにくい？

> あと、リファレンスの方も対応するHeadlineと同じように修飾すべきなのか？
> ってのもありますね。例えばあらいさんの例だと、"((<ほげなHOGEの章>))"を
>   <A HREF="...">ほげな<CODE>HOGE</CODE>の章</A>
> というふうに出力すべきなのか。

((<ほげHOGE>))をそういう見出しが存在すれば((<ほげ(({HOGE}))>))
とみなしてくれるのはうれしいかもしれないですが必要って程でも
ないと思います。

# ちゃんとソースを見てないんですが、そもそも((<ほげ(({HOGE}))>))
# が許されない今の制限はどういう理由なんでしょう？

今切実に思うのは、RDtoolが報告するエラー情報がもっと詳細にな
ればいいなぁってところです(そうすればネストした括弧も恐くない)。

> >  トップレベルの定数:    --- const::Const (または、Const または Object::Const)
> 
> トップレベルの定数は"main::Const"では？

定数はクラスやモジュールで定義されるモノだからmainってことは
ないと思います。

HOGE = "hoge"
puts Object.constants
=> PLATFORM
   ENV
   ...
   HOGE
   ..

> >> リファレンスマニュアルみたいな用途を想定されていると思いますが、
> >> それ考えると"Class"をいちいち書くのが多少めんどくさいかもしれません。
> >
> >うーん、クラスの宣言も可ってのはどうです？

> この程度の処理だったら簡単にこの形式のドキュメントを
> "--- Class#method"に直すための補助ツールで実現できそうですが、
> このやり方がいいかどうかは、わかりませんね。

私が口走った「クラスの宣言」っていうのはとりあえず置いといて・・・

この辺りの便宜についてはもう少し様子見でもいいかと思います。
"--- Class#method" の慣習はあくまでも慣習なので従いたくなけ
ればクラス名省略しても(RDとしては)問題ないわけですし。

perldoc ならぬ rubydoc とかを考えたときこの程度のツールでは
クラス名は特に必要ないですね。
一方、大きめのリファレンスマニュアルのためには必要でして、どっ
ちにでも対応できるのは利点と言えます。

ただし、両者をマージしようとしたとき(小さいRDをあつめて1つの
RDドキュメントとして何かをしたいとき)にクラス名を書いてない
RDの存在が問題になるかも知れないですけど、それはそのときに考
えたい気もする(あまり先を考えすぎて実装が遅れるのもちょっと
嫌ですし)。

> >年越しになるとは思いますが、一旦暫定で作ってみてRubyのリファ
> >レンスマニュアルが書けるかどうか試してみようと思います。
> >html2texi使いまわせば簡単に変換できるかなと目論んでます。
> >
> ># これを先にやった方が議論が進むかも知れませんね。
> 
> それはありがたいです。

作りました。えっとどうしようかな。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"	=> "++++",

のような変換を行いました。見出しのレベルの意味が違ったり存在
しないレベルがあります。
# 「スーパークラス」とかの項を@nodeにしてもしょうがない。
# これはどうしようかなぁ(rd2texi)。

・オプションや用語集で、DESCLISTが使えなかったというのがありま
  した。

  :: label STRINGLINE

  なんてのがあるといいのかなと漠然と考えてます。

    :: -K (({-K((|c|))}))

      -> -Kc

  (記号が枯渇していく^^;)

・以下のようなのがありましたが、

  --- Array.[](index ...)

  ちょっとわかりにくい？

  -> Array.[index ...]
  という出力が得られますが

  -> Array[index ...]
  とした方が良かったですね。

・以下のようなのもありました

  --- ENV.delete(key)

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

・センタリングがない

  別に必要だとは思ってないです。

・((<substitute|label>))

  これ必要ですね。

他にもあるかも知れないですが、特に重要な問題はないと思われます。

> ただ、rubytk.rdを見ても思いましたが、やっぱり一番必要なのは複数ページの
> HTMLに分割して出力する機能ですね。(^^;;

あっこれ重要です。大きめのRDは変換に時間がかかるので小さいRD
を個別に変換できるとよいのですが。(中間ファイルが必要になる
けど私はそれでも構わない)

別件ですが、1つ気になってるのは

  * ITEM

    DESCRIPTION...

でITEMの後にWHITELINEを要求されるのですがこれは本来必要ない
ですよね？(DESCLISTは逆にWHITELINEを許さない)


begin 644 rdtool-0.5.5.patch.gz
M'XL("%:N;S@``W)D=&]O;"TP+C4N-2YP871C:`"M6.U;XD@2_PQ_10UX8]A`
M("C.R(+B#MRMM^K<JG?W`9`G0C-D)@2>)(SG*?>W7_5+DNZ\(#MW/FJ2[NI?
MO715=57/[/D<:MX&O%FP6CFUAM$R6G5OAK_-1;!T:H[]:'B/RK2Q),%B-4M3
M%6NUVAM`A7^2&?3)%)JG8)ZVS:-V@[Z<GA9U7=^/2^%NX\)?+1>@"8U6VVRU
M&Q^AV6@TBKT>U(Y;U0^@X_^/T.L5`8#^`<S('*SUVGF>!*O)/XCW:`7V4B,.
M61(WJ,)TY0;X4N'$`&7XA`R>"&Q\`K]<??[TV^]__WP_`'\S78!C?R/GQ1JG
M_-/OPTY,<-;YV^W@;.267P2B\75ENUJI5-EVZG2J4Y>(1^ZXJ)<S<="2(Y>!
MI:$,/_#L]1;G&20G3>'FB_<F8@J,01%WEF//RX`LKVP_B.UIXXA?81MRTJB>
M@'YB5LV&V)%0KOX5LQ2C%:*,7+04%8/-J8R1M9YB?<V<)).Y_H<XZ2$G]K)#
M2?K,=QS*[>HR96+&35*'&N;#!VJ8C\UJJR49)E(V-'>D\]KR?#+A4:'Q1Z3D
M-\?R?>B":SOAD.5]28Q\L]V9.F+/H3Y\T$;^6*]#]S_`48MZ@;\@\<%[_!)0
M!X?A.F8G&>1!,WZJ:.77=OMU9%14K%"V`Y-^<!D.F@J37&"QM@NE^<:=!O;*
M+8&%"!P&A\LEB4-:006/JF%\\3>/[Z`^>M+K53CL?+>\L]'H?:=.7PYCVJF%
M@1^JP(>>%L2%TG!<$A;A0?,N^F*X#R.-FF)4.:#PHY&)F(52^86)N,4GBK@=
MEE_HDBV%4K&[?QR<SE?AN^6@YGP?JMKPH3K^":F,I15,%QHEJ0S-:G.<0L=U
MT<<N21&\_(+$VTADXO@D8T7YA5MM*U:6E*U([$E.**LA%A!O6452?XIB4A>(
MO)[.H&!*8-"QBN1!TCJ#+-?!\SD*S7+"_5GG`FXNK@?=DF,]$J==?NFQ%W\H
M>!OL<[PMG74^?>[3Q$G1,9.SKT[]XFRL6@/D[/;_P,?,!'H"M\]RF:R7E&,P
MG_4EJ12;9Z:UP7*]L'S;WYW2!M<9IP8RP_%$5C/-!CV`S9-C<0)G\+PE\_O5
M@/,+^4;L<,_`W=!]35I+\!\7:VP#+^#7V\&?NZ5R:%U<A:8LOR3HMV*C"N(;
MD1,4-+RT^D.88LH87:B>\)-<-BI\F+ZI'T"A#$^6Y]KNEW/\H"COL#)"M8E'
MW"FIPN,F`(8'LQ7QW<,`R+_0\:%6.^M<9JA`O6"67ZH].JOI-Q8&GN$]YY=1
M*EU.N:82_6#!E@"Y7HF2[0@:1^TCQ#F)2[:3)JL0FN@WX3GH4&.TV4G.7E_`
M(_[&H7N'26C8&,,VM#C^O*+W;?8CI&&32ZA+A%R9/3!_AM#'(VG;<'G3']S<
M1R.L\(#^@`TB'H^4QA'5VVP<5YN\-"H4"B*E43[-,<_,;#R2H(\*A#G2<,F3
MQM,C77`TKE#)"@7XF:LBZ1")%(\EA$)WE]C$R9@QH?`F@\^V$<>2+94!T.``
M&>+QY>W4B/I-#:<(R4&-]<9?9$J8*:8LY)`CC-.K,D5$":\'][]^[E]=WMU?
M7]S^%AKU[O[V\N8O5Y<W`P6G4)"R]`2C(0C-C=8NQ[O=LUW'=LE$Q`M[:-P%
M*DSC+*_(V:Y<O]"97XADG)"JS0(NS(^9_HZKN36%RO*"4"EUG9FYCB4&?V*[
M$^:7.Y;2&&DV3FB,-)O8/LA5<L_WIH:_L.>!,K)QV9@VW7B8:(-+=T;%TZ$T
M\DOX.#B,3AF/!!O/A6&[/[C[%&XG%E7M0[458(59_0&SO0RYQ<RIG7>'#[5Q
MI<[I\=C";9Q\%ZUEZ`>2H'J"<^PT5:#;'S*6*HGTZGW53#)3_18510T.U?XJ
M1]5Z,2G*CH-HO@QVWA;P^9R#AT^F#QQL'-\^<,3B.RO@!XT)YG';_-AN27<#
M1RUVTM!'ZS3R)LNQ+5_X91>F"]N9H?K=(B@]V)3U&'&<00?H0ZICIU.R#K3O
MMF\'*R_:`?%ML*?<KOK$F5<47PN+M`QN-*H%1_K*EUE!X&EM'N>!MR$5>9A5
M%QGC4NPKLU0%V[4#&\WQ;Z+E%]T]D8S8(_%3ACO,3>Z71'\)HT`TF&PQIB)>
MVHG^DM.*?B*:8:3&;+-.%;,H@R08DLI?*,.%YUG/L)K#+W1/XV;!<6BV0Y_&
M&E1K]Y1.(36;5CV^'/C1/6=]37K?941B31<34?UI[YE31K#/-G%F\OIP2%6E
MI[0\B(<U)KS:KVA<V]B%G^P6PM!@&/+"3*$9%LWK$OL]1.(:V'L)P7F\Q4ZB
M9\'\%GVL1QC[66(GA)+)N_2LC@(IY9UL,E,GGG,2;//2D:YT<3Q!7+*Z0712
MF!]N^^)=9#86\>*4#J,=,J(]:OEVI/;0J7>E]Y@F)\7'!#^8YB6`1*JG&'&J
M/V5U`_XWCZ6R(>I`PRHZ=6D8^:#B&*GD'36M8:)CY2H6E-*%`._@F/.QXC&.
M0G8-R:I6VQ`IA$5U.@A@_YO.5(O/A<ZZMHRJH+@C'DH=K"0X#R`A.6M:L!*C
M34OS5"W(4I9]\PYG/TNK8@N;J/$5VUR<3)$L_#`*EQM*EE34S$H.\7[)R>O'
M=VV_2ZV<74S>TOP/.]@\YB7UR5'U5-K`L#&F7AQXA!ASVYU-+,<)UP*>'K8_
ML<ZU<(LC(23%XX8I%TB/@&+C*#84J.%S0:P937.^<G)`0=P.V0;V9@X9P^MK
ME]^I^(:/28TKVV(]=O/#4=4TL[1-8-J)>/U*!T'`#K\R%TIST@N2!;*-D7T0
;RWQTF0^_&$PQ@H)D'^F5TQ3_"_-2G'O-&P``
`
end

--
新井康司 (Koji Arai)