[ruby-talk:00697] Re: Summary of discussion about RD (Re: Docum enta tion about RD?)

Hi,

[...]
> >> >>Also used for email addresses?
> >> > 
> >> > Yes. ((<URL:mailto:[e-mail]>)) is also legal URL. 
> >> 
> >> I mean something like: ((<[e-mail]>)) :-)
> > 
> > That is not enough because Headline like "== [e-mail]" is not
> > illegal. Even if Nobody wrote such RD maybe.
> 
> That problem I don't understand. What would be the problem if I want to
> write something like...
> 
> =begin
> You can contact me under ((<[e-mail]>)). Please feel free to
> write me, whenever you want! :-)
> =end
> 
> Why have I to write ((<URL:mailto:....>))?

Oh, my explanation was too short.
Now I try to explain more details of this probrem.

In gotoken's idea, "((<...>))" has tree features (means).
(1) Reference to Headlines and Term part of DescList.
(2) Link with URL.
(3) Reference to Bibliography.
And we don't use Label for (1). we use Title of Headline ("== Title < this")
and Term of DescListItem (": Term < this") instead of Label. For Example,
if you want to refer to Headline ("== Title <this"), write like 
"((<Title < this>))". 
And we use "((<...>))" for (2) too. this type of reference is to point 
resorces on the Net. we use "((<URL:...>))" for that.
Furthermore we can use "((<...>))" for (3) too! we use "((<REF:HF90>))"
to refer to Bibliography.
in [ruby-list:16204], gotoken said,
> For Example, you write such as "((<REF:HF90>))", it is displayed
>"[HF90]" in LaTeX, and it links "[HF90]" of
>=References
>
> [HF80] Hoge FOO ``Mr. Annonymous'', Bar Press 123pp (1980)
> [HF90] Hoge FOO ``Mr. Annonymous, again'' Bar Press 132pp (1990)
>
>in HTML.
This usage of "((<...>))" has just begun to discuss now.

This explanation is right? > gotoken

Well,so this "((<[e-mail]>))" maybe refers Headline like
"== [e-mail]", usage (1).
This is a problem of "((<mail address>))".
But we can regard String which contains "@" and "." and not contains /\s/
as Mail Address probably. Do you think this rule "valid"? and "wished"?

[...]
> 
> > ?????
> > Sorry, I don't understand.
> > \cle think which is better? "((x ... x))" or "(x .. x)"?
> > (gotoken like "((x ... x))", and Tosh like "(x ... x)".)
> 
> Sorry if I was confusing you! That seems to be happen all the time
> along if I try to express myself in English :-))
> 
> I mean that `((x...x))' is more appropriate.
> 
> Every document description language try to use seldom used
> constructions for commands. In TeX we have the `\' as command
> indicator, as it is not often used in text. In the *roff family we use a
> `.' as first character of a line, because it is *very* seldom, that
> a `.' occurs as first character in a line.
> 
> Under that point of view, I would think, using `((x' is more seldom than
> `(x'.

I see. Almost all think "((x ...x))" is better. We choose "((x ... x))".
OK?

> Furthermore in future (if necessary) we could also have commands like
> e.g. ((word .... word)), if we have no non-alphanumeric characters
> available anymore! ;-)))

I can't agree with this suggestion. Maybe, if non-alphanumeric 
character runs out, we want so much feature that RD cannot accept
them.

> [...]
>  
> > uum, you will write such "((x ... x))" type brace as not InlineElement
> > frequently?
> > There is another suggestion. back-slash escaping like "((\x ...
> If that would deliver ((x ... x)) in the text/printout, that is more
> than ok! :-) I only wants to have a way!

I see.
But if nobody use "((x ... x))" for Literal Meaning frequently, I think 
using Inline Verbatim, "(('...'))", is not so bad idea.
What do you think?

[...]
> Hmm... Why not saying that *every* `=begin <anything>' has to be
> ignored by the rdtool? Only plain `=begin' would be accepted. So other
> tools could use that feature also, to embed information in multiline
> comments.

I think this feature of your suggestion is useful and powerful,
but too powerful. if we allow this feature, we also come to allow
"=begin html" maybe. I'm afraid that such a powerful feature may
cause some trouble.
I will try to think more and more deep about your suggestion, and
make a decision after.

> [...]
> 
> > 
> > I think, RD should be a format for man and not for formatter.
> > So man can read raw-RD (preformmated RD) easily. embeding HTML in RD
> > is on the assumption of existence of formmater script. So embeding
> > HTML ( or LaTeX or roff ) is not acceptable in RD.
> > I wish that RD will NOT become like POD.
> 
> After thinking more about that, I think I can understand what you mean!
> ;-)))
> > 
> > For Example, if you use embeding-other-language in your RD document and
> > you want to support all of HTML, LaTeX and man, you have to write like 
> > this:
> 
> [...]
> 
> > 
> > Do you think it is enough simple?
> 
> You have convinced me! That is surely not simple!
> 
> > I think,
> > when users of your script read your script and look such a document, 
> > they will think it is difficult even only to find Ruby script part 
> > in ".rb" script file. And a man who try to read raw-RD will take more
> > and more trouble.
> 
> You're right.
> 
> > 
> > I suggest altanative idea. we use "@input" instead of "=begin xxx" and
> > "=end xxx", like "@input filename". Document writer make "filename.html",
> > "filename.tex" and "filename.man". Formatter choose one of them with 
> > output format. For Example, rd2html choose "filename.html" and rd2latex
> > choose "filename.tex".
> > This feature is simple. So it will not make RD complicated.
> 
> THIS is a nice and fancy idea :-))) I agree that would be far better,
> than what I have proposed. But please don't name it `@input'! It seems
> not to fit into RD style, IMHO.

"@input" originated from sample/rd2html.rb.
If you disagree with "@input", I give another choice, "<<< filename".
this is like a way of output to File instance, "$> << var", and also
like a way of shell redirection, "< filename".

But "@input" or "<<< filename" feature has a problem. If you use it,
you have to make file even if you want to insert one-line of HTML.:-(

> And again, please think about to only take into consideration multiline
> comments that begin with plain `=begin'! I think that could be
> important. Perhaps in future we will have other tools that also like to
> use the multiline comment style.
> 
> As RD is most important, plain `=begin' is reserved for `rdtool'. But
> please free other kinds for usage of other tools! That means, please
> ignore every of the comments below e.g.:
> 
> =begin testcase
> ...
> ...
> =end
> 
> =begin used algorithm
> ...
> ...
> =end

But do we use "=begin <someting>" only for multiline comment? OK?
Even if we use "@input" instead of "=begin html", we should think
about extention in feature.

And gotoken suggested to use pair of "=begin <something>" and 
"=end <something>" in [ruby-list:16142].

I think we need more and more dicussion about it...

---
Tosh