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

On 19 Aug, Toshiro Kuwabara wrote:
> 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:....>))?

[...]

> ?????
> 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'.

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

[...]
 
> uum, you will write such "((x ... x))" type brace as not InlineElement
> frequently?
> There is another suggestion. back-slash escaping like "((\x ... x))".

If that would deliver ((x ... x)) in the text/printout, that is more
than ok! :-) I only wants to have a way!

> 
>> > Well, we often use embedding document as `lines killer' in daily hack. 
>> > But current RD does not deal with such a hackish comment, all embedding
>> > document will be printed. Though it maybe right (pedantic) manner, 
>> > I feel too rigit. For example
>> > 
>> > =begin ignore
>> > Ahhhhhhh!! why doesn't callcc work as I intend?
>> > 
>> > p $ccccc
>> > p $aaaaa
>> > =end ignore
>> 
>> Ohhh! That makes sense, I think. I sometimes use that too!
> 
> Huum, so we need Comment-RD maybe.
> But I think "###" is better than "ignore" for Comment-RD.
> Ex.
> =begin ###
> .....
> =end ###
> 
> 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, 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.

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
:
:

[...]

> 
> ---
> Tosh
> 

\cle