ruby-list

Toshです。
# ちょっと忙しいのでしばらくレスポンスが悪くなるかも知れません。

In message "[ruby-list:20160] Re: RD with method index (again)"
    on 00/01/11, Koji Arai <JCA02266@nifty.ne.jp> writes:
>RDtoolに関するこれまでの議論をまとめます。
>さらに追加で書き込みがあるので、あんまりまとめになってないか
>もしれません(中間報告程度に考えてください)。

わざわざどうもありがとうございました。

>なお、.rd2rc、フィルタに関する議論は省略させて頂きました(使っ
>たことないので話を理解できなかった)

あれは、ほっぽっといてよいです。RDそのものとはあまり関係もありませんし、
あれの話が絡んで来ると混乱するかも知れませんし。

>= ペンディング
>* メソッド用の見出し(MethodList/DeclareList ?)
>   --- Class#method(arg)
>       ((<Class#method>))
>  * [ruby-list:19934]以降あまり進展はない(^^;
>  * [ruby-list:20017]にお試しのパッチあり(rdtool-0.5.7にも適用化)
>  * 出力時、メソッド名部分は自動で<CODE></CODE>で囲んでくれるとな
>    お良い(と新井は思う)。

同意。ついでに、パラメタも<VAR></VAR>するとなお。

>     --- Class.[](arg)
>         ((<Class.[]>))...
>    は、
>     Class[arg]
>       Class[] ...
>    という出力を得られれば良い(クラスメソッドの[]の表記では"."は省略)

今のリファレンスでは self[arg] って形になってます。
どっちがよろしいでしょうか？

>  * ベースラインを下げすぎるためインデントが深くなる
>    (今出ているMethodListの問題点はこれだけ？)
>    ベースラインを特別に
>      --- Class#method
>       |<- BaseLine
>    とする？

これですが、考えてみるとEnumListの"(1)"というのも"---"と同じ幅です。
しかもおそらくMethodListよりEnumListの方が多重ネストされることが
多いと思われます。
したがって、「"---"というのは特に問題ではない。Baselineも特別
扱いは必要ないだろう。」というのが僕の意見となりました。

>  * 演算子"|"や"/"などは、RDtoolで特別扱いされる予定なので
>    ((<"Array#/">)) などと""でラベルを囲む(未実装)

((< ...>))の中の特殊文字はもうちょっと増えそうですね。なるべく早いうちに
決めたいです。
# なにしろとにかく決まらないと「ドキュメント拡充プロジェクト」みたいな
# ものにいっこうに手が付けられないですし。

>  * MethodListはネストしない?(実装もそうするのか?)

どうでしょう？実装上は別にわざわざ制限を付ける理由もないかと思います。
まぁ、MethodListを入れ子にして書く人はまずいないでしょうが。

>* 参照文字列と参照先の判定
>  Toshさんの意図に反して<A NAME="label">substitute</A>の表現の案
>  [ruby-list:20025]として書きます。
>     : インスタンス, Instance
>  の参照を
>     ((<インスタンス|インスタンス, Instance>))は、...
>  と書きたくはないと言うことです。

僕もこういうのはいやです。

>  (1) 判定を甘くする(一意である限り先頭文字が一致すればOK)
>      (新井はあまり好きじゃないです。ドキュメントを書き足して
>      行くうちに。一意じゃなくなるかも知れないから)


まずあらいさんの指摘された(1)の問題点ですが、こういう問題が起こりうる
ことについては納得できます。ただし、この「前方一致の判定」というのが、
上の例の場合の", instance"であるとか、(MethodListのためにこの用途は必
要なくなってしまいましたが)メソッドのパラメタといった、「本来冗長な部
分を省略可能に」するためのものであって、「面倒だからはじめの部分だけを
書けばいい様に」するものではないということを言っておきます。つまり、判
定を甘くしようともラベルとしての機能を十分に果たすくらいに長く書く必要
はあるということです。その上で「ドキュメントを書き足していくうちに一意
じゃなくなった」とすれば、それはもともと見出しのつけかたに問題があるの
でしょう(たぶん)。上の例だと「インスタンス変数のスコープ」みたいな見出
しをつける可能性があるなら、あらかじめ回避できるように手をうっとけって
ことですね。それが、どういう「手」かはこの場合ちょっと謎ですが。まぁ、
リファレンスのパス指定みたいなのが導入されたらあらかじめ"((<Glossary::
インスタンス>))"と書け、ってことでしょうか。

>  (2) :: label substitute
>       ((<label>))がリファレンス文字列になるDESCLIST
>      出力-> substitute
>             labelがリファレンス文字列になるDESCLIST
>      というのがあると良いかも(あまり深く考えてはいない)

このタイプのラベルというのはシンプルな解決策な分、上の「条件を甘く」
みたいなものよりRobustだろうとは思います。ただ、ラベルって管理が結構
面倒なんですよね。LaTeXとかでもまず名前をつけるのに一苦労って感じに。
今までラベル宣言みたいなものは無しでやってきたので、ここまできたら
なるべく無しで済ませたいっていうのもあります。Rubyには変数宣言はない、
RDにもラベルの宣言はない、って感じでしょうか。(^^;;

しかし、それに代わるものが「条件を甘く」であるかどうかは、わかりません。
「条件を甘く」も結構問題ありそうなので、他にいい解決策があれば、と思う
のですが。

=begin 余談
「元のRDフォーマットにあるものは他のフォーマットに出力したときにも見え
る」っていうのが、「書きやすさ読みやすさ」にとって結構重要なポイントか
もしれない、と最近考えています。一種のWYSIWYGでしょうか。
LaTeX等では\index{...}みたいなものはカッコの中身は出力にはでませんが、
RDの((:...:))では表示されます。
しかしこのことは、守ろうとすると結構大きな制約になりますので、すべてに
これが適用すべきとまでは思ってません。既に((<subst|label>))みたいなの
で一部崩れています。でもなるべくなら人間がぱっとみて「人間にとって意味
のありそうなデータ(文字列)」は「実際に意味のあるデータ」であって欲しい
と思ってます。
=end 余談おしまい

>* 見出しにインラインを許す
>  (上記「判定を甘くする案」とは別問題のように思えるので分けました)

あ、違う問題です。「判定をあまくすることで」両方解決できるか、と考えて
いたのでついまぎらわしい表現になりました。

>  = ほげ((*HOGE*))
>  や
>  = ほげHOGE
>  に対するリファレンスは、
>
>  (1) ((<ほげ((*HOGE*))>))	# そのまま書く
>  (2) ((<ほげ ((*HOGE*)) >))	# 空白は無視
>  (3) ((<ほげHOGE>))		# インラインは無視(出力は見出しにあわせる?)
>
>  (1), (2), (3), (2)+(3) のどれが良いか？

難しい問題ですよね。
(2)のバリエーションとして、
  (2') ((< ほげ((* HOGE *)) >)) === ((<ほげ((*HOGE*))>))
のように、「リファレンスに限らず、インラインの中身はstripされる」ってのも
あります。
そもそも「一致の条件をどうするか」って問題なので、(1), (2), (3)ってのは
解決策ってものでもないですから。
根本的な問題は上の例の場合
  ((<ほげ((*HOGE*))>)) === ((<ほ((*げHO*))GE>)) (as Reference)
になるのか？とかそういうことです。

>  ところで、インラインの中でも((<>)), ((--))は特殊なのでこれ
>  を見出しの中に書くのは許さない方が良いように思えます。
>  それ以外の(見ためを変えることを意図した)インラインは見出し
>  や((<>))の中でも許すべきでしょう。

同意します。

>* HTMLの複数ページ出力
>  (1) RDtoolによる自動分割(分割の目安はユーザが指定するか？)
>  (2) "=begin"..."=end"で囲まれてるところをページ(ノード)の単位に。
>  (3) .rd -> .html とファイル単位に対応させる

これはRDtool側の問題ですね。まぁ、どれが便利か、ってとこでしょうか。
(2)はややRDの仕様的には好ましくないとは思ってます。柔軟ではあるけど。

>= 実装されるもの、されたもの
>* RDtoolのエラー出力を詳細にする
>  よろしくToshさん(^^
>  (一番必要なのはエラーのあった行の行番号出力だと思います)

行番号出力は一番必要なのですが、一番やっかいっぽいです。(^^;;
普通はどうやるんでしょ？Rubyのソースとか読んでみますか。
# readlinesとかで全部読み込んじゃってから処理、みたいなのが問題？

>* DESCLIST の後にWHITELINEを許す
>  よろしくToshさん(^^

はい。(^^;;

>* パーサのチューニング
>  [ruby-list:20055]
>
>* RDの個別コンパイル[ruby-list:20068]
>  rb2ro, rdld を使用する(これはまだお試し?)

お試し、ですね。最終的にどうなるのかは不明です。
それほど一般的に使われるようなものでもないですし。
例えば、*.roを配布ってのもあまりいい考えではないですし。

>* WHITELINE(空白類だけの行)は、BLANKLINE(改行のみの行)と区別
>  がなくなった。(これは、かなり嬉しい。rdtool-0.5.5以降の目玉 ^^)

人によって「嬉しさ」の基準って結構違うものだなぁ、やっぱ
「嬉しいドキュメントフォーマットであるべきRD」ってのは難しい
ものだ、と改めて実感しました。(^^;;

>= 昔から議論されてるもので必要とされているもの
>* リファレンス先が複数ある場合
>  ((<file/label>))として参照先を特定する

「別ファイルへのリファレンス」の方がわかりやすいかと。

>以上、未だ勘違いがあるようならご指摘願います。

とりててて問題はないと思います。僕の知る限りでは。

---
Tosh
Toshiro Kuwabara

Thread

Prev Next

In This Thread

Prev Next

[#19998] benchmark.rb — gotoken@... (GOTO Kentaro)

[#20003] REQ: String#gsub — Tomoyuki Kosimizu <greentea@...2.so-net.ne.jp>

[#20018] ruby-1.4.3.tar.gz の日付 — Tadashige Morii <m_tada@...>

[#20028] xmltree — "Masatoshi SEKI" <m_seki@...>

[#20035] DocBook 4.0: ClassSynopsis — Yasushi Shoji <yashi@...>

[#20041] Re: xmltree — "Masatoshi SEKI" <m_seki@...>

[#20046] 1/0 — "Shigeo Kobayashi" <shigeo@...>

[#20053] == === case — "Shigeo Kobayashi" <shigeo@...>

[#20057] mirror.rb in Ruby Book — Takashi SATO <turmite@...>

[#20059] 改行がリダイレクトされない ruby1.4.3cygwin? — 中村暁史 Nakamura Akifumi <BXQ04723@...>

[#20077] Range expansion? — Akinori MUSHA aka knu <knu@...>

[#20083] non-block IO with TCPSocket — dn <daisuke@...>

[#20087] Re: a instance of Struct subclass on the block parameter (Re: Range expansion?) — Kazuhiro Yoshida <moriq.kazuhiro@...>

[#20097] Re: [REQ] ruby-math (Re: coerce) — Toyofuku <toyofuku@...>

[#20118] media watch 2000.01.08 — Noritsugu Nakamura <nnakamur@...>

[#20120] タブの出力について — 鮎川夏生 <natuki@...>

[#20123] TMail and Racc and RDtool — Masaki Suketa<CQN02273@...>

[#20131] String to Time — Yukihiko Eda <yuki-e@...>

[#20133] おききしたーいでーす — akimaru <akimaru@...>

[#20145] BUG? Parse Error and and — Tomoyuki Kosimizu <greentea@...2.so-net.ne.jp>

[#20150] Ruby BUG ?? — Sakae Kobayashi <sakae@...>

[#20162] proxy ftp — "Kikutani, Makoto" <kikutani@...>

[#20174] Ruby-book erratum — "K.Kodama" <kdm@...>

[#20175] class Polynomial — "K.Kodama" <kdm@...>

[#20176] Re: Complex#divmod — Masato KIYAMA <masato@...>

[#20178] [Gtk 0.22] Gtk::DrawingArea cannot pack in Gtk::VBox — h-isikaw@...

[#20184] [book] 付録 A — Kazuhiro Nishiyama <nishiyama@...1.tiki.ne.jp>

[#20185] [book] 8,9,10 章 — Kazuhiro Nishiyama <nishiyama@...1.tiki.ne.jp>

[#20186] [book] — Kazuhiro Nishiyama <nishiyama@...1.tiki.ne.jp>

[#20187] Hash#index, Hash#indexes — Kazuhiro Nishiyama <nishiyama@...1.tiki.ne.jp>

[#20188] slashdot - The 2000 Beanies — Yasushi Shoji <yashi@...>

[#20191] thread について — Yasushi Abe (阿部靖司) <yasushi@...>

[#20192] timeout.rb の Thread.abort_on_exception = true — Matsuo Hisanori <hisanori@...>

[#20203] Gtk::ItemFactory の代替品を作ってみました — dellin <ogu@...>

[#20210] Ruby 強調表示定義ファイル for 秀丸 — Ayanosuke <aya@...>

[#20211] %Ruby — Shugo Maeda <shugo@...>

[#20215] racc debianized — akira yamada / やまだあきら <akira@...>

[#20219] catching exceptions in rb_eval_string() — OZAWA Sakuro <crouton@...>

[#20221] while TRUE と loop の違いを教えてください — Sakae Kobayashi <sakae@...>

[#20235] simple-chat-server.rb don't work on lynx — M_HANA <M_HANA@...0.sapporo-soft.ac.jp>

[#20237] Ruby/Tk multi interpreter — nagai@...

[#20240] eRuby banner — OZAWA Sakuro <crouton@...>

[#20243] (rd2) nl in Japanese chars — gotoken@... (GOTO Kentaro)

[#20246] Q: Singleton Class and Singleton Method — Tomoyuki Kosimizu <greentea@...2.so-net.ne.jp>

[#20249] FTP.open err for Windows95 — "Y Kataoka" <kataoka@...>

[#20274] RAA script — akira yamada / やまだあきら <akira@...>

[#20279] [ 雑談 ] メーリングリスト抜けますです〜 — Atsuko Yoshida <atsuko@...>

[#20284] ruby と論文と知名度 — Noritsugu Nakamura <nnakamur@...>

[#20300] net/http.rb — TAKAHASHI Masayoshi <maki@...>

[#20301] notify_observers in observer.rb — Matsuo Hisanori <hisanori@...>

[#20310] ワイルドカード有りのファイルの存在を調べたいのですが — 関口久之 <sekiguci@...>

[#20318] gtk: how to copy clist item into clipboard. — OZAWA Sakuro <crouton@...>

[#20320] TMail is too strict? — Shugo Maeda <shugo@...>

[#20337] — Norihito Shinzan <kabbalah@...>

[#20339] Telnet (login failed) — Kentaro Inagaki / 稲垣 健太郎 <inagaki@...>

[#20341] ftp.ruby-lang.org ([book][CD-ROM]README.txt) — SUGIHARA Hiroshi <maili31s@...>

[#20342] How to build ruby(current) with cygwin — KORIYAMA Naohiro <kory@...2.so-net.ne.jp>

[#20344] E-mail アドレスの確認・ DNS の MX など — ogino@...

[#20348] Ruby/LAPACK working group — gotoken@... (GOTO Kentaro)

[#20349] パスワードの crypt とチェック — Ayanosuke <aya@...>

[#20350] [PATCH] Ruby/Tk — Koji Arai <JCA02266@...>

[#20355] personal web server(win98) で ruby の cgi を実行したい — Hiroshi Saito <HiroshiSaito@...>

[#20363] media watch 2000.01.24 — Noritsugu Nakamura <nnakamur@...>

[#20369] divmod() — Yasushi Abe <yasushi@...>

[#20385] Re: class Polynomial — Toyofuku <toyofuku@...>

[#20393] eRuby で掲示板作ってみました — Noriyuki Okamoto <okamoto@...>

[#20394] ruby-1.4.3 port to HPUX 11.00 — matz@... (Yukihiro Matsumoto)

[#20400] Ruby win Icon — たむら けんいち<ken-ichi.tamura@...>

[#20409] Ruby/Gtk のバージョンを取得したい — dellin <ogu@...>

[#20413] File::open() マニュアル — とみたまさひろ <tommy@...>

[#20414] 3 桁毎にカンマを入れる — 堀川 久 <vzw00011@...>

[#20433] クラスメソッド呼び出しの parse error — Yoshiki Wada <wada@...>

[#20438] cygwin 版 Ruby での BLT 利用について — otokita@...

[#20445] Anquete for Object Day 2000 — Tomoyuki Kosimizu <greentea@...2.so-net.ne.jp>

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

Thread

In This Thread

[#20339] Telnet (login failed) — Kentaro Inagaki / 稲垣健太郎 <inagaki@...>

[#20400] Ruby win Icon — たむら　けんいち<ken-ichi.tamura@...>

[#20414] 3 桁毎にカンマを入れる — 堀川　久 <vzw00011@...>