From: Toshiro Kuwabara <toshirok@...3.so-net.ne.jp>
Date: 2000-03-03T17:40:37+09:00
Subject: [ruby-talk:01705] Re: Ruby 1.4 stable manual bug?

Hi,

In message "[ruby-talk:01683] Re: Ruby 1.4 stable manual bug?"
    on 00/03/02, Hugh Sasse Staff Elec Eng <hgs@dmu.ac.uk> writes:
>> I write them in HTML directly, having plan to move to RD
>> (Ruby Document format - simplified POD like text).
>	[...]
>> Patches, suggestions, document maintainers are always welcome.
>> 
>> 							matz.
>
>I have looked at the docs for "embed_doc" in syntax.html.  May I suggest
>the following (I did raise this on comp.lang.perl.misc, but got no
>answers. Maybe it is silly in some way?):

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 document is not completely up-to-date. We've already decided to 
add MethodList, new list syntax to write method reference.

>There exists a pod2man, so presumably a Ruby version will appear (if
>it hasn't already).  The main problem with pod is that you want to 
>keep the docs with the code, but you often need the manual information
>to come out in a different order.  So I suggest:
>
>=name <NAME>
>This block of text is associated with <NAME> and not displayed yet.
>=end
>
>=include <NAME>
>
>The block of text named with =name is displayed at this point.

I think, your suggestion is enough reasonable.
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. 

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

---
Tosh
Toshiro Kuwabara