From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 1999-08-15T21:40:30+09:00
Subject: [ruby-list:16160] Re: RD specification

Toshです。

> >インラインのverbatimの方が便利かも。Rubyのスクリプトをインラインに
> >はさみたいときにも使えますし。
> 確かに。ただ、\verb+...+ みたいのはたぶん正規表現では書けま
> せんね。あと、他のインライン要素とは構文を分けないといけない
> でしょうね。

ふむふむ。
# そいやインライン要素のパースはちょっと怪しげなコードです。もちょっと
# うまいやり方、と言うかきれいに書きたいところですが・・・。

>> # blade で [ruby-dev:3067] をみたら「字面」が処理されてるよ

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

> >インライン要素は結構ほしい機能とかたくさんでてきそうですが、
> >開始と終了の記号をかなり慎重に決めないとあっという間に可読性
> >が損なわれそうです。RDは可読性が嬉しいところなので、汎用の
> >ものを用意するにしても今の思想に従うにしてもなるべく慎重に
> >進めたいところです。
> これなんですけど、まつもとさんも「ジャマにならなければ、現在
> の仕様とは違うある程度汎用的なインラインかっこの導入は構わな
> いと思います。plain2の((x ..))とかいうのも嫌いじゃない」とおっ
> しゃっている[ruby-list:16134]ので、podのL<...>かplain2の
> ((x...))程度のモノなら導入しませんか?? さすがにSGMLみたいの
> はさすがに可読性が下がりそうなのでやめたいですが。まぁやるな
> らplain2のかな。確かに読みやすいし、平文を書くのにも不自由し
> なさそうだし。
> そこで少し考えて見ました。plain2では、((x...))の一文字目は英
> 文字なんだけど、これを記号文字にしたらだいぶ読みやすいんでは
> ないかと思います。あと、内容の前後に呼応する記号を書くと言う
> ことを考えて見ました。
> 
> :強調
>    LaTeX の \em 相当。((!強調!))
> :コード
>    HTML の code 相当。((|while gets...|))
> :変数
>    HTML の var 相当。((変数))
> :キーボード
>    HTML の kbd 相当。((%ruby -v%))
> :見出し語
>    索引に載せる語。((:見出し語:))
> :リンク
>    HTML の a href= 相当。((<見出し語>))
> :脚注
>    LaTeX の \footnote 相当。((-脚注-))
> :そのまま
>    LaTeX の \verb 相当。((`そのまま')) もしくは {{そのまま}} 

これだとかなり見やすいですね。強調は((*foo*))とかでもいいかも。
閉じカッコの前にもマークを入れるならカッコは一重でもいいのでは?
リファレンスリストの標準変数の説明みたいに、「覚え方」が書けそうですね。(^^;
リンク、っていうのは、URLで指せるって事でしょうか?
リンク先の指定はどのように?

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

> > [構文要素:ラベル]と
> > {構文要素:ラベル}ってことですよね?
> >
> >それで構わないと思います。
> >構文要素に何を許すかにちょっと議論の余地がありますが。
> んー、どうしましょう。インライン要素は((x...))型に統一して、
> その同義語として「[ホゲ:hoge]を参照」みたいにしますか??  

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

> ところでインラインなラベルって本当にいるんでしょうか?? 
> plain2だと、参照を意味する ((x...)) は LaTeX の \section や 
> \table などに相当する箇所に対してしか使えません(この場合、見
> 出しやcaptionが((x...))の...に入る)が、それで十分な気がしま
> す。甘い?? んで、引用の順序が変わりますが、

ふむふむ、確かにラベルが必要なのはほとんどの場合見出しとかですね。
LaTeXのラベルは何に付けられるんでしたっけ?
ドキュメントのあり方とかを考えるとインラインにはつけられない方が好ましい
かもしれないし、インラインのラベルは生RDを読むときには探しづらいってのも
ありますね。
Toshはインラインなラベルはなし、に賛成します。

> 問題は、リストのようなブロック要素にラベルをつける
> 方法ですが、
> * 自動生成したラベルを使う
> * 直前に置いた # で始まる行にラベルを書く
> のいずれかで済むような気もします。

: 自動生成したラベル
  は参照の方はどのように指定するのでしょうか?XMLのXPointer(でしたっけ?)
  みたいに?
  # 構文要素にnameやidをつけられないとXPointerみたいのはつらそうですが。
  # もっともXMLも本や雑誌をちょっと眺めた程度の知識ですが。間違ってるかも。
: 直前に置いた#行。
  見出し(Headline)では同じ行の後ろにくっつけたい気もします。LaTeXみたいに。
  特別扱いになっちゃいそうですけど。
 
 Figure:
 # label
 = Headline
 
 = Headline # label

> >外に出すようにすると、例えば複数のライブラリのRDから得たauxをまとめて
> >一つの索引ファイルとして出力するスクリプトがあればお手軽にライブラリの
> >リファレンスができて便利かな、とか思いました。
> >それと、HTMLの最後に索引がついててもそれほど便利かなって思います。
> 了解です。索引の位置は各rd2*に任せることにしても、auxみたい
> なのは悪くないかも知れません。

あ、0.2.1はとりあえず中だけで全部処理にしちゃいました。やるなら
コマンドラインオプションでインデクスファイルを出力するか指定、でしょうかね?
自己完結するファイルでは外に出す必要はないですし。


> 強制改行は不要な気がして来ました。必要ならverbatimにするとか
> でしのげると思うんですが。

そいえば、HTMLではわりと<BR>とか使ってるのをみかけますが、LaTeXでは\\は
めったに使いませんね。ううむ。

> >> >: スクリプトに埋め込まないRDの決まり事
> >.rdだと.rbと似ていて紛らわしいかも。
> >もっとも=begin,=endがつくならruby *.rdとしても問題は起きませんが。
> =begin =end は残して、.rd ってことにしません??

サフィックスは慣習上のものですから、あわてて決める必要もなさそうです。
このままほっとくと .rdになるのはほぼ間違いないですけど。(^^;

> # しかし授業で .rb を .rd としてた学生が結構いたのを思い出した(^^;;;

(^^;
Toshはファイル名を見た時に、ちょっと悩む時があります。(^^;
# なんだかんだでローカルでは .rdになってる・・・。

> >> >あと、ちょっと思い付いただけのものですが、
> >> > {script-name: hogehoge.rb}
> >> > {author: Tosh}
> >> > {auther-mail-addr: toshirok@yb3.so-net.ne.jp}
> >> > {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」とか
> >はどうしましょう?あったほうが便利ですか?
> ># そういえば、rd2html.rbの@inputの処理にバグを見付けて、それを
> >直そうとしたのがそもそものきっかけでした。(^^)
>
> ドキュメントを書く道具としてなら、あると便利かも知れませんね。
> LaTeXの\includeみたいな使い方をするというのはありそうです。

rdtoolみたいに複数のスクリプトファイルからなるスクリプトのドキュメント
を書く時には便利ですね。
# というかrdtoolのドキュメントはそろそろ構成を変えないとだめっぽいですね。(^^;
# rd2latexもあるのにrd2htmlだけにRDの説明があるし。

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

---
Tosh