[ruby-talk:11755] Re: small ri patch

On Tue, 27 Feb 2001, Dave Thomas wrote:

> If people want to write using rhe original LaTeX, I'd be happy to
> release our style files. That's pretty clean. For example, from Array:
> 
>     \begin{method}{reverse}{\self.reverse \returns{\obj{anArray}}}{A}
>       Returns a new array using \self's elements in reverse order.
>       \begin{ruby}[comment]
>         [ "a", "b", "c" ].reverse
>         [ 1 ].reverse
>       \end{ruby}
>     \end{method}
> 
> To generate stuff for ri, I have a Ruby program and some XSL that
> converts the above to:
> 
>  <method name="reverse">
>    <callseq>
>       <i>arr</i>.reverse -> <i>anArray</i>
>    </callseq>
>    <desc>
>    <p/>
>       Returns a new array using <i>arr</i>'s elements in reverse order.
>    <p/>
>    <verbatim>
>      <MULTI><m1><code>[ "a", "b", "c" ].reverse</code></m1><m2><code>["c", "b", "a"]</code></m2></MULTI>
>      <MULTI><m1><code>[ 1 ].reverse</code></m1><m2><code>[1]</code></m2></MULTI>
>    </verbatim>
>    </desc>
>  </method>
> 
> However, it you wanted to use this as a general format, I'd want to
> step back a bit, and instead use something like
> 
>  <method name="reverse">
>    <callseq>
>       <obj>arr</obj>.reverse <returns><obj>anArray</obj></returns>
>    </callseq>
>    <desc>
>       Returns a new array using <obj>arr</obj>'s elements in reverse order.
>       <code show_output_as="comments">
>         [ "a", "b", "c" ].reverse
>         [ 1 ].reverse
>       </code>
>    </desc>
>  </method>
> 
> This would be usable to generate decent HTML and ri stuff.
> 
> Was this the kind of thing you were looking for?
> 
I was thinking specifying a very simple text format that can output the
latex your scripts need to generate all the nice stuff (HTML,ri etc). Like
for the one above:

reverse
	anArray
Returns a new array using %c{arr}'s elements in reverse order.
%c{
	["a", "b", "c"].reverse -> ["c", "b", "a"]
	[1].reverse -> [1]
}

General idea is to make lots of assumptions in this simple text format so
that people need only write the minimum possible and still get nice
docs. If we can make writing docs easier we might get more of it...

Also see ruby-talk:10555.

If you can specify the latex output (or other output) your scripts need I
can do the parser... Any ideas on whats the simplest possible and easiest
usable format of course welcome!

Regards,

Robert