[ruby-talk:00686] Re: Summary of discussion about RD (Re: Documenta tion about RD?)

Hi, 

# Don't call me Mr. Goto please ;-)

In message "[ruby-talk:00683] Re: Summary of discussion about RD (Re: Documenta tion about RD?)"
    on 99/08/18, [e-mail] <[e-mail]> writes:

>> For Example,
>> :((!Em!)) ( or ((*Em*)) )
>>   Emphasis. Like \em of LaTeX.
>
>Would I use it as `((*This sentence is emphased*))'?

Yes. I think it should be allowd. 

>I would propose only to use `*', as it would free `!' for another
>meaning later. Furthermore `*' is more a catchup for the eye.

You are right. And Tosh?

>> : ((var))
>
>Used like `(($_))'?

Yes. Also ((@foo)). I intended ((var)) for just analogy to
<VAR>file</VAR>, that is *NOT* for ruby's variable but *IS* for
variable word in explanation. So, it can be used like as
`((%ruby -v ((foo.rb))%))'


>> : ((<Identity or URL>))
>>   Link, Reference. Like <a href="...">...</a> of HTML.
>>   we will use title of HeadlineElement or caption of ListElement for "Identity"
>>   to refer without "Label".
>>   And will use "((<URL:http://www.netlab.co.jp/ruby/>))" to refer resource on
>>   the Net.
>
>Also used for email addresses?

Yes. ((<URL:mailto:[e-mail]>)) is also legal URL. 

>> Tosh suggested to use "(x ... x)" instead of "((x ...x))". Tosh think 
>> "(x ... x)" is more simple and more naturally embeded in plain text.
>> But Mr.Goto is afraid that "(x ... x)" is so simple that it may cause
>> some trouble.
>
>I think you are right, but Goto also :-) The `((x..x))' syntax seems to
>be more error prone!

Shall we elect? :-)

>May I suggest another thing? If there is a text like 
>
>	`(( This is text ))' or `(( This is text))'
>
>you could treat that *not* as inline-element, and remove *one* leading
>whitespace! I.e. it would become `((This is text ))' or `((This is
>text))' respectively!

Hmm, What do you ame by this feature? But whitespece treating should
be decide. Japanese guys maybe not sensitive this problem :-)

>> === Comment-RD and HTML-embeding in RD
>> Some want to use RD as multi-line comment. Mr.Fukuma suggested it in 
>> [ruby-list:16136]. And Mr.Goto suggested to use
>> "=begin some_tag ... =end some_tag" for mutli-line comment.
>
>I don't understand that proposal.

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

>> Mr.Goto also suggested HTML-embeding like Perl. i.e. use following type of 
>> "=begin ... =end" to embed HTML (or Markup Language).
>>  =begin html
>>  <br>Figure 1.<IMG SRC="figure1.png"><br>
>>  =end html
>> It is suggested in [ruby-list:16162].
>> 
>> Tosh think comment-RD and HTML-embeding make RD complicated.
>
>It would make the tool a bit more complicate, but it could improve the
>abilities to document something. I thing, if it is decided to have
>`=begin html' we also should get `=begin man', `=begin latex' and so
>on.
>
>Perhaps simply insert them into the corresponding result?

I think so. I just intended it like `#ifdef .. #end' without
`#else'. But I agree it causes to be too complicated and, probably,
makes difficult to read the document.

>> Sorry of my poor English...
>
>Nothing to forgive. Mine is also not better ;-))))

Maybe, we are developing a kind of Pidgin language :-)

-- gotoken