Re: Why no docs for ruby ?

On Thu, Oct 11, 2012 at 6:17 AM, Timothy Madden <[email protected]> wrote:
> On 10/11/2012 04:50 AM, Vincent Batts wrote:
>>
>> This is true. I just put a simple build up
>> http://slackware.com/~vbatts/ruby/ that just builds an addendum package
>> called 'ruby-doc'
>> I lobbied for this SlackBuild to be in /extra/, but we can't all get
>> what we want ;-)
>
> This is just so sad ... ! :(
>
> As I said, it seems unfair to me some languages have a proper package,
> others have only a trimmed package without documentation.

I am two ways about this, because I too wholly want the package "ruby"
to include all the pieces (including the documentation).
But one of the things that I like very much about python's
documentation strategy is that the documentation is not separate from
the code. Even within the language, you can query an object for it's
__doc__, so the pydoc utility needs only to lookup the path of the
library references and read the documentation straight from the
source, or even render a webserver that actively does the same.
Unfortunately, this process is duplicated in ruby. Rdoc parses and
renders new files, further one for `ri`, and another that is an html
structure. So when the documentation grew to be several orders larger
than the actual code it came from, and the Slackware discs were
crunched for precious space, we made a tough decision on where all to
shave the additional bits from. :-\

Although, I feel all this ought to be done on the fly, with the
exception of code the is compiled against the C API. I have had a
couple of discussions surrounding this with Eric Hodel on the ruby
development team (maintainer of rdoc), but at this point an on-the-fly
documentation reader would need to be net-new technology to be vetted
out, with the hopes that it could be rolled into the current standard
ruby documentation tooling.
To me it seems like it should be a very accomplishable project, and
plenty of merit in doing so, but it would have to take a place in my
queue of thoughts to be thought more about! :-)

Take care,
vb