From: Robert Feldt <feldt@...>
Date: 2001-02-08T18:40:45+09:00
Subject: [ruby-talk:10555] Re: Programming Ruby is now an Open Content Publication

On Thu, 8 Feb 2001, Dave Thomas wrote:

> 
> Thanks to some wonderful flexibility on the part of Addison Wesley,
> Programming Ruby is now an Open Publication document. This means we
> can release the sources and derived content for general use.
> 
> I'm trying to work out how to handle updates to the LaTeX, but in the
> meantime the XML and HTML sources of the reference material are
> available for download at
> 
>    http://www.pragmaticprogrammer.com/ruby/downloads/refman.html
> 
This is great news. I'd also like to see the format of this used in other
Ruby projects. Maybe we can introduce a very simple doc format where you'd
write for example:

   *
	arr * anInteger -> anArray
	arr * aString -> anOtherString
   Repetition-With a String argument, equivalent to
   %c{arr.join(aString)}. Otherwise, returns a new array built by
   concatenating the anInteger copies of arr.
   %c{[1, 2, 3] * 3 -> [1, 2, 3, 1, 2, 3, 1, 2, 3]}

which is then translated to the xml format used in the lib reference:

   <method name="*" ref="_st">
   <callseq>
               <obj>arr</obj> * <obj>anInteger</obj>
   <returns><obj>anArray</obj></returns><br/>
           <obj>arr</obj> * <obj>aString</obj>
   <returns><obj>anOtherString</obj></returns>
   </callseq>
   <desc>
       Repetition-With a <classname>String</classname> argument,
       equivalent to
       <code><obj>arr</obj>.join(aString)</code>. Otherwise, returns a new
       array built by concatenating the <obj>anInteger</obj> copies of
       <obj>arr</obj>.
       <p/>
       <codefragment>
       <table>
       <tr>
       <td><code>[<nbsp/>1,<nbsp/>2,<nbsp/>3<nbsp/>]<nbsp/>*<nbsp/>3</code> 
       </td> <td>-></td>

<td><code>[1,<nbsp/>2,<nbsp/>3,<nbsp/>1,<nbsp/>2,<nbsp/>3,<nbsp/>1,<nbsp/>2,<nbsp/>3]</code></td>
</tr>
       </table>
       </codefragment>
    </desc>
    </method>

which can then be transformed to HTML, Latex or what-have-you...

Or is RD the way to go? I haven't used it myself and my impression is that
it is not in wide-spread use? Am I wrong? If your not using RD whats your
problem with it?

The translator would make lots of assumptions and would parse the Ruby
or C code while processing the docs to know the type of method (instance
or class) and so on.

Regards,

Robert - who would like to doc his Ruby extensions and projects better but
don't know what way to go...