[ruby-list:16162] Re: RD specification

ごとけんです

In message "[ruby-list:16160] Re: RD specification"
    on 99/08/15, Toshiro Kuwabara <[e-mail]> writes:

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

3067 でなくて、[ruby-dev:3038] でしたね。後述します。

>> :強調
>>    LaTeX の \em 相当。((!強調!))
>> :コード
>>    HTML の code 相当。((|while gets...|))
>> :変数
>>    HTML の var 相当。((変数))
>> :キーボード
>>    HTML の kbd 相当。((%ruby -v%))
>> :見出し語
>>    索引に載せる語。((:見出し語:))
>> :リンク
>>    HTML の a href= 相当。((<見出し語>))
>> :脚注
>>    LaTeX の \footnote 相当。((-脚注-))
>> :そのまま
>>    LaTeX の \verb 相当。((`そのまま')) もしくは {{そのまま}} 
>
>これだとかなり見やすいですね。強調は((*foo*))とかでもいいかも。

そっちの方が((*English*))には合いそうですね。

>閉じカッコの前にもマークを入れるならカッコは一重でもいいのでは?

大丈夫かなぁ。ちょっと心配。

>リファレンスリストの標準変数の説明みたいに、「覚え方」が書けそうですね。(^^;
>リンク、っていうのは、URLで指せるって事でしょうか?
>リンク先の指定はどのように?

えっと、これはHeadlineElementなどはその見出しそのものを書く
ということを意図してました(plain2 の ((x...))のように)。つま
りHTMLだと <a href="bar">foo</a> のように foo と bar を違う
のにできますが、それを基本的には禁止するということです。

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>]
などとなって欲しいです。

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

>それとインラインの入れ子も許すようにしないといけなさそうですね。
># 現状は Document > Block > Inline
># 不等号は包含関係による順序関係。等号を含まないのでいんちきですが。

そうですね、入れ子にしないと使いにくいでしょう。

>どうせRDのインライン要素って使っているドキュメントがほとんどないですから
>いっそ無くしてしまうのも一つの手です。
>それに[ほげ:hoge]の形は[ruby-list:xxxx]とかもひっかかるのがちょっと
>気になります。(^^;

ですね。

>ふむふむ、確かにラベルが必要なのはほとんどの場合見出しとかですね。
>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はインライン要素にはなくても良いでしょう。
たぶん。

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

採用するならこっちの方が良さそうですね。

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

そうですね。まぁ複数ファイルを扱うようになったら拘らなくても
いいかも。

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

でしょ。

>> >> >あと、ちょっと思い付いただけのものですが、
>> >> > {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の代入やハッシュ式を真似て
>> > { key => value }
>> >のような形がいいのか、もしくはそれだと問題が起きそうだから全く
>> >別の形式にすべきなのでしょうか。
>> 
>> いっそのこと、ある規約にしたがって、Rubyのモジュールを吐き出
>> すのもいいかも知れません。
>
>Rubyのモジュールを吐き出すってのはどういうことですか?
>「吐き出す」ってのはrd2xxxのoutputがRubyのモジュール、ってことでしょうか?
>「Rubyのモジュール」は、
> module Foo
>   ...
> end
>のモジュール?

そうです。そのモジュールです。中身は何も考えてませんが。

>> >ところで、rd2html.rb(Ruby本体のsample/の)にある、「@input」とか
>> >はどうしましょう?あったほうが便利ですか?
>rdtoolみたいに複数のスクリプトファイルからなるスクリプトのドキュメント
>を書く時には便利ですね。
># というかrdtoolのドキュメントはそろそろ構成を変えないとだめっぽいですね。(^^;
># rd2latexもあるのにrd2htmlだけにRDの説明があるし。

(^^;;

>sample/rd2html.rbの「@input」には「@input(HTML)」みたいな形式も
>あるようですけど、これはHTMLファイルを取り込むためのものですか? ＞まつもとさん

これを見ておもいだしたけど、pod には

=begin html
<br>Figure 1.<IMG SRC="figure1.png"><br>
=end html

のような機能があります。このように埋め込みドキュメントの入れ
子を許した方が便利ですね。まぁ、デバイス依存のハンドリングだ
けならこの機能はいらないかも知れませんが。

-- gotoken