From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 1999-08-18T14:48:16+09:00
Subject: [ruby-talk:00680] Summary of discussion about RD (Re: Documentation about RD?)

=begin
== Pre-script
Hello!

Thank you for your using RD and RDtool in testsupp-0.2!> \cle
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
not have "Emphasis" element yet. We have now discussed RD should have
such element. 

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

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

== Summary of discussion about RD
Following is the summary(?) of discussion about RD format in "ruby-list" ML.
It based on explanation in "About RD Format" section of RDtool. And it has not
been decided yet.

=== More InlineElement
First, We need more InlineElement such as "emphasis" and "reference"
And we also need general brace for InlineElement. But RD format must
be neat and simple, so brace of InlineElement must be also simple.

Mr.Goto (gotoken) suggested plain2 like general brace in [ruby-list:16148].
That suggestion is that we use "((x ...))" for general brace, but we
use mark([^\w\s]) for "x" while plain2 use alphabet([\w]) for "x". And
we will write "x" before close-brace like "((x ... x))".

For Example,
:((!Em!)) ( or ((*Em*)) )
  Emphasis. Like \em of LaTeX.
: ((|while gets...|))
  Code. like <code>...</code> of HTML.
: ((var))
  Var. Like <var>...</var> of HTML.
: ((%ruby -v%))
  Keyboard. Like <kbd>...<kbd> of HTML.
: ((:Term:))
  Term of Index. Like \index of LaTeX.
: ((<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.
: ((-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.

=== Label and Reference
Second, we need the way to refer some document element. First suggestion about
label and reference is "[elements:label]" for label and "{elements:label}" for
reference to label. This type of label and reference is like HTML <A NAME ...>
and <A HREF ...>. But Mr.Goto suggested not to support of Inline-Label in 
[ruby-list:16148]. i.e. Like LaTeX, we should use reference only to refer
specific BlockElement such as HeadlineElement and ListElement.

In Goto's Idea, we use title of Headline or caption of List etc. instead of
label. I think it is good idea.

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

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.

=== The way to give additional infomations to RD formatter
We need the way to give additional infomations about script and document to
RD formatter. i.e. script infomation such as "script name", "version" and
"auther", or document infomation such as "title" and "author", should be
able to be written in RD. Tosh suggested following type of format in 
[ruby-list:16129].
 {script-name: foo.rb}
 {author: Tosh}
 {auther-mail-addr: toshirok@yb3.so-net.ne.jp}
 {last-mod: 1999/08/13 23:41:00 JST}
 {descript: ......}

Mr.Goto suggested to use Ruby Module for RD formatter output(?) in 
[ruby-list:16148]. But we havn't decided any more.

=== not-script-embeded RD
We will use ".rd" suffix for RD which is not embeded in Ruby script file.

=== NOTICE
These suggestion has not decided yet. So they will be changed and if you
disagree with these idea, you can suggest altanative ideas, and such 
ideas may be welcomed.:-)

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

Sorry of my poor English...
=end
---
Tosh