[ruby-list:16168] Re: RD specification

Toshです。


> >[ruby-dev:3067]といえば、3067のごとけんさんの案では他のRDへの参照も
> >許してましたが、これはどうしましょう?
> >HTMLでやるとすると出力ファイル名に規則が必要そうですね。
> 3067 でなくて、[ruby-dev:3038] でしたね。後述します。

あぅ、3038でしたか。(^^;

> >> :強調
> >>    LaTeX の \em 相当。((!強調!))
> >> :コード
> >>    HTML の code 相当。((|while gets...|))
> >> :変数
> >>    HTML の var 相当。((変数))
> >> :キーボード
> >>    HTML の kbd 相当。((%ruby -v%))
> >> :見出し語
> >>    索引に載せる語。((:見出し語:))
> >> :リンク
> >>    HTML の a href= 相当。((<見出し語>))
> >> :脚注
> >>    LaTeX の \footnote 相当。((-脚注-))
> >> :そのまま
> >>    LaTeX の \verb 相当。((`そのまま')) もしくは {{そのまま}} 
> >
> >これだとかなり見やすいですね。強調は((*foo*))とかでもいいかも。
> そっちの方が((*English*))には合いそうですね。
> 
> >閉じカッコの前にもマークを入れるならカッコは一重でもいいのでは?
> 大丈夫かなぁ。ちょっと心配。

普通の文章にはたぶん大丈夫かと。
Rubyのコードはちょっと微妙なものもあるかも。('...'),("...")とか(/.../)
あたりはまずいですね。きっと。

> >リファレンスリストの標準変数の説明みたいに、「覚え方」が書けそうですね。(^^;
> >リンク、っていうのは、URLで指せるって事でしょうか?
> >リンク先の指定はどのように?
> えっと、これはHeadlineElementなどはその見出しそのものを書く
> ということを意図してました(plain2 の ((x...))のように)。つま
> りHTMLだと <a href="bar">foo</a> のように foo と bar を違う
> のにできますが、それを基本的には禁止するということです。

ふむふむ。同じ名前のHeadlineは書けない事になりますね。
@inputとかを使い出すと名前がかぶることがあるかも。
# rdtoolはwarning出すようにしないと。

> URL を書くときはたとえば ((<URL:http://...>)) のようなのを使っ
> た方がよいかと(パーザがどんどん巨大になってく気もするけど)。
> たとえば、HTMLでは普通
> <a href="http://www.netlab.co.jp/ruby/">ruby</a>
> と書くところを
> ruby((<URL:http://www.netlab.co.jp/ruby/>)) 
> と書くわけです。あ、もちろんここをrd2htmlしたら、デフォルトで
> ruby[<a href="http://www.netlab.co.jp/ruby/">http://www.netlab.co.jp/ruby/</a>]
> などとなって欲しいです。

なるほど。URLの場合と他の場合で処理を適当に変えてくれるんですね。
パーサはLinkElementとかで始めがURL:かどうかで場合分けするだけですので
そんなに複雑にはならないと思います。
# 現状が十分複雑との説も。(^^;

> あとは参考文献(SEE ALSO)かな。

LaTeXみたいにインラインで使うようにするのですか?
そうでないなら付加情報で与えてしまえば、これ以上のタグ(?)を導入しなくて
すみますが。

> >それとインラインの入れ子も許すようにしないといけなさそうですね。
> そうですね、入れ子にしないと使いにくいでしょう。

御意。

> >ふむふむ、確かにラベルが必要なのはほとんどの場合見出しとかですね。
> >LaTeXのラベルは何に付けられるんでしたっけ?
> >ドキュメントのあり方とかを考えるとインラインにはつけられない方が好ましい
> >かもしれないし、インラインのラベルは生RDを読むときには探しづらいってのも
> >ありますね。
> >Toshはインラインなラベルはなし、に賛成します。
> >> 問題は、リストのようなブロック要素にラベルをつける
> >> 方法ですが、
> >> * 自動生成したラベルを使う
> >> * 直前に置いた # で始まる行にラベルを書く
> >> のいずれかで済むような気もします。
> >: 自動生成したラベル
> >  は参照の方はどのように指定するのでしょうか?XMLのXPointer(でしたっけ?)
> >  みたいに?
> 
> これは前述のようになります。HTMLを使ってるとどこでもリンクが
> できるのですが、TeX や roff のような文書ではそのようなリンク
> は稀です。これを少し考察してみると、例えば LaTeX では、同じ
> 文書内の別の箇所を指すとき、See 4.5 Church-Rosser theorem と
> か、will be discussed in section 4.5 のように書くことが多い
> のですが、本質的には、紙の上に書かれた文書構造の要素を指さな
> いと追えないわけです。で、実際問題としてRDはHTMLなど他の形式
> に変換する前にコメントとして用をなさないといけないわけから、
> この「紙上の制約」があります(XMLのような汎用性は入らない)。
> だから、# を使ったラベルづけも無くせるようにした方が良いよう
> な気もします。つまり、ヘディングやキャプションのついてない箇
> 所を指すべきではないと思うのです。
> 
> >  # 構文要素にnameやidをつけられないとXPointerみたいのはつらそうですが。
> >  # もっともXMLも本や雑誌をちょっと眺めた程度の知識ですが。間違ってるかも。
> 
> RDに限って言えばidはインライン要素にはなくても良いでしょう。
> たぶん。

LaTeXはラベルで指定するけどRDはHeadlineのtitleやcaptionで、
ってことですね。逆に言うとリストを参照したいならリストに
caption付ける機能が無いとだめですね。
リストの前に#の行があったらcaptionにするとか。

> >: 直前に置いた#行。
> >  見出し(Headline)では同じ行の後ろにくっつけたい気もします。LaTeXみたいに。
> >  特別扱いになっちゃいそうですけど。
> > Figure:
> > # label
> > = Headline
> > 
> > = Headline # label
> 採用するならこっちの方が良さそうですね。

Headlineへの参照(ごとけんさんのおっしゃたように)はtitle
(例のHeadlineの部分)で指定でいいように思いました。
それで行くとキャプションをどうつけるか、何に付けられる事にするか、
ですね。

> >> >外に出すようにすると、例えば複数のライブラリのRDから得たauxをまとめて
> >> >一つの索引ファイルとして出力するスクリプトがあればお手軽にライブラリの
> >> >リファレンスができて便利かな、とか思いました。
> >> >それと、HTMLの最後に索引がついててもそれほど便利かなって思います。
> >> 了解です。索引の位置は各rd2*に任せることにしても、auxみたい
> >> なのは悪くないかも知れません。
> >あ、0.2.1はとりあえず中だけで全部処理にしちゃいました。やるなら
> >コマンドラインオプションでインデクスファイルを出力するか指定、でしょうかね?
> >自己完結するファイルでは外に出す必要はないですし。
> そうですね。まぁ複数ファイルを扱うようになったら拘らなくても
> いいかも。

RDの仕様でどうこう言うような問題でもないような気がして来ました。
# 自分で言い出しておいてなんですが。
RDtoolはそのうちそういうことをするかも、くらいですか。

> >> 強制改行は不要な気がして来ました。必要ならverbatimにするとか
> >> でしのげると思うんですが。
> >そいえば、HTMLではわりと<BR>とか使ってるのをみかけますが、LaTeXでは\\は
> >めったに使いませんね。ううむ。
> でしょ。

じゃ、とりあえずはなしで。
改行制御したい時はverbatimにするか、いさぎよくそこで段落を分けるかで。

> >> >> >あと、ちょっと思い付いただけのものですが、
> >> >> > {script-name: hogehoge.rb}
> >> >> > {author: Tosh}
> >> >> > {auther-mail-addr: [e-mail]}
> >> >> > {last-mod: 1999/08/13 23:41:00 JST}
> >> >> > {descript: ......}
> >> >> >のような感じで付加的な情報を与える機能があるとおもしろいかも。
> >> >> >RAAのためにここからスクリプトの情報を集めたり、
> >> >> >同じものをrd2htmlではHTMLのTITLEとかに使ったり、とか。
(ちょっと途中を省略)
> >> いっそのこと、ある規約にしたがって、Rubyのモジュールを吐き出
> >> すのもいいかも知れません。
> >Rubyのモジュールを吐き出すってのはどういうことですか?
> >「吐き出す」ってのはrd2xxxのoutputがRubyのモジュール、ってことでしょうか?
> >「Rubyのモジュール」は、
> > module Foo
> >   ...
> > end
> >のモジュール?
> そうです。そのモジュールです。中身は何も考えてませんが。

吐いたモジュールは何が使うのですか?

> >sample/rd2html.rbの「@input」には「@input(HTML)」みたいな形式も
> >あるようですけど、これはHTMLファイルを取り込むためのものですか? ＞まつもとさん
> これを見ておもいだしたけど、pod には
> 
> =begin html
> <br>Figure 1.<IMG SRC="figure1.png"><br>
> =end html
> 
> のような機能があります。このように埋め込みドキュメントの入れ
> 子を許した方が便利ですね。まぁ、デバイス依存のハンドリングだ
> けならこの機能はいらないかも知れませんが。

あると便利なのですし、別スレッドででているコメントRDもこれで
ぴったりとうまくいくのですが、あるといくらでも「一見して意味が
わからない(フォーマッタに通さないと読むに耐えない)RD」が書けそ
うなのが恐かったりします。(コメントRDも)
こういうのはRDの仕様にはいれないでおいて、その代わりにどうし
てもやりたい場合には他のツール(eRubyとか)と組み合わせると同じ
事ができる、というような逃げ道があればいいと思うのですが、
何かうまい案は無いですか?

# それにしてもこのスレッド、どんどんメールがでかくなってく・・・(^^;

---
Tosh