From: clemens.hintze@...
Date: 1999-08-18T13:11:35+02:00
Subject: [ruby-talk:00683] Re: Summary of discussion about RD (Re: Documenta tion about RD?)

On 18 Aug, Toshiro Kuwabara wrote:
> =begin
> == Pre-script
> Hello!
> 
> Thank you for your using RD and RDtool in testsupp-0.2!> \cle

Thank you for providing such a great tool, Tosh! :-))))

> But you made a mistake. HTML element like <B> ... </B> and <CENTER> 
> ... </CENTER> should not use in RD. RDtool-0.2.1 or after come not
> to escape "<", ">" and "&" to "&lt;", "&gt;" and "&amp;". RD have

I know, I have already realized that! :-( My fault! I have find, that
`rd2html' didn't escape `<...>' tags within my doc, I have silently
used them. It is already corrected in my current version. But I will
not issue a new release only because these thumbness of mine :-)

> not have "Emphasis" element yet. We have now discussed RD should have
> such element. 

That would be fine. I have already thought of that also. I had some
ideas but I didn't know, how to send them to you, as I had no mail
adress. Perhaps you could introduce it into the README?

Regarding my ideas, I find these of you all much better than my own, so
I will not mention them here, respectively I would adapt them to the
proposed syntax. :-)

Here are two of them:

	- May I propose to have a `rd2man' in future?

	- The latex section seems to numerate sections beginning with
	  `==� with 0, if there was no `= � section before. I think, if
	  there is no `= ' section, it should silently be cut down one
	  level. So the first occurence of `== ' should become `1.' but
	  not `0.1'. That should also be valid, if I would have a `=== '
	  section as highest level in my doc.

	  That means, the highest level in a RD doc should be regarded
	  as level one in a Latex doc!

	  Why could that be meaningful? Perhaps I would like to write
	  some documents together in a book-like document. But I should
	  also be able to separately handle them!

What do you think?

> 
> == RD current
> RD format is now under discussion. So, There is not explanation for the 
> details of RD in Ruby-Manual. And we don't have official document about
> RD either. "About RD Format" section of README.html of RDtool is likely
> to only one document about RD (but not official).

But then, it should be mentioned in the README of Ruby, about the fact,
that there *IS* a RD format for documenting Ruby. And where to get the
tools and infos!

> 
> We dicsuss about RD in ruby-list ML, Japanese Ruby ML. But if you have
> suggestions about RD format, you can also suggest them in this "ruby-talk"
> ML (maybe).

I will do it.

[...]

> For Example,
> :((!Em!)) ( or ((*Em*)) )
>   Emphasis. Like \em of LaTeX.

Would I use it as `((*This sentence is emphased*))'?

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

[...]

> : ((var))

Used like `(($_))'?

[...]

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

> : ((-Footnote-))
>   Footnote. Like \footnote of LaTeX. (We use "(--Footnote--)" now.)
> : (('verb')) ( or {{verb}}? )
>   Inline Verbatim. Like \verb of LaTeX.
> 
> 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!

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!

[...]

> === 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.

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

[...]

> == Post-script
> I put rdtool-0.2.2.tar.gz, newest release of RDtool, in in.coming. 
> gotoken send me a patch for LaTeX format, thanks! > gotoken
> and I fixed some bug in parser.

Thanks for the info! :-)))

> 
> Sorry of my poor English...

Nothing to forgive. Mine is also not better ;-))))

> =end
> ---
> Tosh

\cle