From: Dave Thomas <Dave@...>
Date: 2001-02-27T22:58:41+09:00
Subject: [ruby-talk:11688] Re: small ri patch

Robert Feldt <feldt@ce.chalmers.se> writes:

> Since ri now supports abbreviations via prefix matching we should be able
> to give abbreviations of length 1. Patch is below.

Thanks

> Another thought on ri: I proposed some time ago that we should base a
> simple documentation format on the formats used by Dave&Andy in the book
> and now (in another form) in ri. I still think this would be a good
> thing. Anyone else got ideas on this? Would it suffice if I/we do a simple
> parser outputting stuff the way ri documentation is formatted? (Or is 
> too much info lost there to get back to XML?) Would also
> be good with a short list of advice on how to write docs the "pickaxe
> way". Dave?

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?


Dave