Hi,

In message "[ruby-talk:01708] Re: Ruby 1.4 stable manual bug?"
    on 00/03/03, Hugh Sasse Staff Elec Eng <hgs / dmu.ac.uk> writes:
>> I've written a document of RD format, here.
>>   <URL:http://www2.pos.to/~tosh/ruby/rdtool/rd-draft.rd>
>> and this is HTML version.
>>   <URL:http://www2.pos.to/~tosh/ruby/rdtool/rd-draft.html>
>
>This looks interesting.  I will put comments at the end.

Thanks.

>> But We, and RD, cannot accept your idea because it is not fit
>> with RD's policy and its goal.
>> 
>> We decided to use the syntax like plain text for RD. And we think
>> it is wishable for RD to seem as same as plain text. RD format should
>> be ordered same as it is desplayed because this rule is simple. 
>
>There is definately something to be said for simplicity. The only other
>thing that occurs to me is that "plain text" is slightly different for you
>and for me :-) -- what do you think about a language directive in RD,
>which pod also doesn't have, so one can set the RD reader to Japanese,
>English, Esperanto or whatever?  It would then simply pick out the
>appropriate parts, and display those as plain text.

Sorry, I might confuse you by my breif, too breif, explanation possiblly.

RD's target, i.e. user, is a man such like:
  * He is a Ruby Programmer. He love Ruby, he also love programing.
  * He doesn't like writting documents. Ofcourse, he understand how 
    his users need documents. But, he love programing so much that
    , he think , he have no time to write document.
  * He knows HTML. He also knows LaTeX system. At least, he can write
    HTML formated document by his hands. But he don't like HTML. He 
    think HTML is too complicated for him to write documents of his
    Ruby script.

RD's goal is "to make him write documents". So RD must be attractive
for him, a lazy Ruby hacker.:-)

Why he don't like HTML? Why he think HTML doesn't fit for writting
document of his Ruby script?
I think that because:
  * He is enough lazy, so he want not to write such like "<HTML>...</HTML>"
    or something. When he write document, he want to write document itself,
    not to write something like HTML tag. He want to concentrate to his
    document itself.
  * HTML can easily split document and bury it into its tag syntax, I
    think. While he own his script, add new future to it and fix bugs of
    it, his document is still alive. He must fix his document again and
    again. So, HTML doesn't fit with documentation of his script.

RD have to help him. So, RD's directive is:
  :easy to read, easy to write
    * He must read his document which he wrote 3 month ago, when he
      up-to-date it. He don't need to read so detail, but he must
      grasp it and find out where he must change. He read RD itself,
      not HTML formatted document which rdtool generates. So, 
      "easy to read" is a great point for "easy to write".
    * It is why we select "plain text like" format for RD. I think,
      we (and "he") are familiar with plain text, so we grasp easily
      structures of documents in "plain text like" format.
    * I think, the appearance of plain text format represents structure
      of document. (NOTE: this "appearance" doesn't mean "decoration". )
      If you write a block indented, such like:
         class Foo
           def bar
           ...
           end
         end
      it will mean "this block is a cited text block or program code".
      And if you write lines with mark like "*", such like:
         * A list
           * ...
      it will mean "a list, unordered list". We use such notation again
      and again in our real life, in books, in lecture notebooks and in
      our daily memos. So, we can understand easily structure of document
      in plain-text.
  :easy to learn, keep it simple
    He wants not to study so much about mark-up language. Ofcourse,
    LaTeX is good system, but it is too complicated for his usage.
    LaTeX is something like a programing language. He doesn't want such
    system. He want "to write document"! So we will keep RD simple.
    He doesn't want more. He doesn't want fully-automated documentation
    system. He doesn't want publishing-level printing system. He only
    wants simple but easy-to-write document format.

OK, now return to your suggestion.
"Order" is very big point for document structure. If you read the last
chapter of a book first, and read first chapter last, you will be
confused, maybe. When he fix 3-month-ago document, he will read RD and
will be confused, because that RD is written with defferent order from 
HTML file which rdtool generates from that RD.
Especially plain-text-like format is sensitive to order, so your suggestion
is not fit with RD, I think. 

Different man hopes different thing. Each writes document with different
style from other. Natural language is much more diffcult than programing
language, so each learns his own style of writting for natural language.
I understand how different they (we) think what is "wishable". But we
can't stuff everything into RD. So, I want each users to write his own
script which help him to write RD in your style, instead of
fully-featured RD.

>> If you want to write RD document like your idea, you can write easily
>> a script to convert your style of document into canonical RD.
>
>I could use the <<< include feature for some of this.

Yes. 

>Having looked at the document, there are a few things I am not clear
>about.
>   Headline:  What is the intended difference in meaning between "=" and
>      "+"?  Is it always to be treated as a font size difference?  Are
>      "=" "==" and "===" be regarded as structure like HTML's <H1> <H2>
>      and <H3>, and is it forbidden to render these as different sizes?

Yes simply section size difference. "=" is bigger, "+" is smaller.
HTML equivalent is:
  =		H1
  ==		H2
  ===		H3
  ==== 		H4
  +		H5
  ++ 		H6

We don't decide "decoration". So it is free to render it with any size,
any font face and any color.

>   Inlines: Examples of how these might be rendered would be helpful.
>      I suggest you show them embedded in a Textblock.  Oh, I have
>      just looked at the rd form of the document, and this is clear.

Oh, thank you for idea.
Now we decide we can use Inline at term of DescList. So, I must fix
Inline section of this document. I fix that point at the same time.

>   Given that the indentation is used for structure, is it intended that
>   a Textblock at the Baseline level of indent should never have its lines
>   folded when displayed, or is folding permitted?

OK. When it desplayed, RD doesn't restrict such "decoration" anyhow.
We decide only that RD's "appearance" represents structure of document.
We don't decide about output of RD formatter. But HTML have its own rule,
LaTeX also have its own rule, so output of RD formatter must be equivalent
of original RD in symantics.

>   You have the sentence: "RD is one of them, but RD will be a standard
>   one."  I am not sure what you mean by this.  Is it that several
>   document standards can be supported in one file, or will there be
>   dialects of RD for different situations?

Well, this means ...
ruby, Ruby interpreter, regards embeded document with very simple way.
it simply ignore text between "=begin" and "=end". So, if you want, you
can embed other format document, for exsample HTML, in your Ruby script. 
... So, "RD is one of them". OK?

Suggestions and Questions are always welcome. :-)

---
Tosh
Toshiro Kuwabara