From: Hugh Sasse Staff Elec Eng <hgs@...>
Date: 2000-03-03T11:02:01+00:00
Subject: [ruby-talk:01708] Re: Ruby 1.4 stable manual bug?

On Fri, 3 Mar 2000, Toshiro Kuwabara wrote:

> Hi,
> 
> 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.

> This document is not completely up-to-date. We've already decided to 
> add MethodList, new list syntax to write method reference.
>
[my suggestion trimmed] 
> 
> I think, your suggestion is enough reasonable.

Thank you.

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

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

> (But you should use "=begin <name>" instead of "=name <name>".
>  It is regarded as comment from both ruby and rdtool.
>  And use
>    =begin display
>    <name1>
>    <name2>
>    =end
>  or such like instead of "=include <name>".)
> 
> Comments, suggestions and questions about RD are always welcomed.

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?

   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.

   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?

   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?
> 
> ---
> Tosh
> Toshiro Kuwabara
> 
	Thank you,
	Hugh
	hgs@dmu.ac.uk