RI Conceptional Showstopper Bug.

[Lothar Scholz]

Hello ,

at the moment i'm working on RI and RDOC integration into the
Arachno Ruby IDE. Unforunately - but not suprising - i found an
important problems.

Starting with another problem: Is the RDOC source code really
unmaintained at the moment, as i read on the ruby-core mailing
list ? I know Dave Thomas is writting his rails but such an
important piece of the Ruby environment should be maintained
by multiple persons.

The main conceptional problem behind RI is that it is just a trivial
flat file "database" without any way to remove items from this "database"
and without (almost) any relation between individual data files.
This is bad and IMHO one of the reasons why Ruby Gems do install RDOC
but not RI help on default. When using Ruby Gems we need a way to cleanup the
RI database for removed gems. Also if during development you generate RI doc
then you will soon find a lot of garbage in your RI database during the evolution
(renaming/removing of methods and classes) of your project.

Deleting everything and regenerating the Database is not easily possible as
many people use the one click installer and don't have the source code.
By the way this would not be a problem is Curt Hibbs fixes the RI problem that
everything is placed in the "site" part of the RI database directory tree.
The RI for the core and core extensions help belongs into the "system" directory.
Also the RI help in the one click installer is not complete. If FOX is bundled
for example then the RI files for Fox should also be available immediately. Same
for all the bundled libraries that come with 1.8 as REXML, DBI etc.

I think that code must be added to keep track of named sets of added files
instead of simply invoking "rdoc --ri-site" or "rdoc --ri-system". This
shouldn't be so hard and allows us to remove the data for one gems package/directory.

I would prefer a more complete solution that uses SQLite as a database but as long
as this is not bundled with ruby (BTW why isn't it ?) it is not an option.

I don't want to write more here until i get some feedback.

 

[Curt Hibbs]

Deleting everything and regenerating the Database is not easily possible as
many people use the one click installer and don't have the source code.
By the way this would not be a problem is Curt Hibbs fixes the RI problem that
everything is placed in the "site" part of the RI database directory tree.
The RI for the core and core extensions help belongs into the "system" directory.
Also the RI help in the one click installer is not complete. If FOX is bundled
for example then the RI files for Fox should also be available immediately. Same
for all the bundled libraries that come with 1.8 as REXML, DBI etc.

I can fix this (I just added a bug report for it).

Curt

 

[Lothar Scholz]

Hello ,

Looked further into it and the situation is more worse then i
expected. As RI does absolutely not handle the ruby key feature of
open classes. If i write somewere a

class File
def temp_dir; return "c:/myproject/temp"; end
end

The whole documentation for File is destroyed.
Even if i generate the data in a different directory, the File class
description is wrong as the "cdesc" files are not merged and we get 2
different class descriptions instead of one and it is unclear which is
selected (other then intuitive the pickup order is "system", "site",
"user" and not the otherway round so overridding is not possible).


Thinks like this are going to make me tired.
Easy of implementation seems to have always a higher priority then correctness
or fullfilling requirements. This is just one example, there are hundert
others out there in all the unfinished libraries and tools. This gives
a bad reputation to the whole language and community.

 

[Ryan Davis]

Starting with another problem: Is the RDOC source code really
unmaintained at the moment, as i read on the ruby-core mailing
list ? I know Dave Thomas is writting his rails but such an
important piece of the Ruby environment should be maintained
by multiple persons.

Theoretically, I am maintaining rdoc. Theory and practice are the
same, in theory. The amount of time I can dedicate to rdoc depends on
my workload on ruby2c and metaruby.

The main conceptional problem behind RI is that it is just a trivial
flat file "database" without any way to remove items from this
"database"
and without (almost) any relation between individual data files.

Remove? Explain?

I think that code must be added to keep track of named sets of
added files
instead of simply invoking "rdoc --ri-site" or "rdoc --ri-system".
This
shouldn't be so hard and allows us to remove the data for one gems
package/directory.

*nod*

Please file a feature request at: http://rubyforge.org/projects/rdoc/

 

[Ryan Davis]

Looked further into it and the situation is more worse then i
expected. As RI does absolutely not handle the ruby key feature of
open classes. If i write somewere a

Not true...

--promiscuous, -p When documenting a file that contains a
module
or class also defined in other files, show
all stuff for that module/class in each
files
page. By default, only show stuff
defined in
that particular file.

---- cat blah.rb
class Blah
##
# this is the main def method

def in_main_def
end
end
---- cat blah2.rb
class Blah

##
# This is in the open class

def in_open_class
end
end
---- rdoc -p -o rdoc -f ri

blah.rb: c.
blah2.rb: c.
Generating RI...

Files: 2
Classes: 2
Modules: 0
Methods: 2
Elapsed: 0.240s
]---- find rdoc/rdoc -type f
rdoc/rdoc/Blah/cdesc-Blah.yaml
rdoc/rdoc/Blah/in_main_def-i.yaml
rdoc/rdoc/Blah/in_open_class-i.yaml

class File
def temp_dir; return "c:/myproject/temp"; end
end

The whole documentation for File is destroyed.

What do you mean by this? Are you just referring to the cdesc data as
described below?

Even if i generate the data in a different directory, the File class
description is wrong as the "cdesc" files are not merged and we get 2
different class descriptions instead of one and it is unclear which is
selected (other then intuitive the pickup order is "system", "site",
"user" and not the otherway round so overridding is not possible).

Are you intending for rdoc to be run against the core + user code? Or
do you want rdoc to be run against user code that extends core
functionality and somehow folds into core + user code? Would the user
have their own copy of core? If not, how to deal with permission
issues? And if not, how to deal with multiple users on the same
system--surely userA would not want to see extensions to File made by
userB that were not available to him.

As for "pickup order" as described above, that sounds like a bug, or
at least a feature request. I don't know enough about it to be able
to estimate how hard and/or how correct such a request is and will
have to do more research into it. Please file a bug at http://
rubyforge.org/projects/rdoc/

Thinks like this are going to make me tired.
Easy of implementation seems to have always a higher priority then
correctness
or fullfilling requirements. This is just one example, there are
hundert
others out there in all the unfinished libraries and tools. This gives
a bad reputation to the whole language and community.

I might say the same thing about your spelling.

As far as "correctness or fulfilling requirements" goes, I think that
is a completely unnecessary (and rude) accusation. It was correct and
fulfilling requirements as far as rdoc's original intent went. While
rdoc tried to be for general use, ri did not. It was intended for
system documentation and has not, to my understanding, ever tried to
have a comparable feature-set to say, perldoc.

Lastly, I think it would be a much more constructive if you could
objectively state your problem and simply ask for input. Editorials
such as "Unforunately - but not suprising - i found an
important problems (sic)" and the whole paragraph quoted above do
very little to support your cause.

 

[Eric Hodel]

Hello ,

Looked further into it and the situation is more worse then i
expected. As RI does absolutely not handle the ruby key feature of
open classes.

I'm not sure this is a good thing. Library A extends String with a
handy method, but the user isn't using library A, and the user is
trying to use that handy method...

As it is, ri cannot tell you where a method came from, so throwing in
methods from extensions will lead to much frustration as you try to
track down which files you need to require to get which methods.

ri was designed to be clear and simple. I worry that extra
information may end up being too much or completely missed.

Thinks like this are going to make me tired.
Easy of implementation seems to have always a higher priority then
correctness
or fullfilling requirements.

ri's original requirements seem to have been something like "Create a
command-line tool to give handy access to documentation for core
Ruby". It performs exceedingly well at this.

I also don't believe you have a reason to complain about
'correctness' or 'fullfilling requirements' when you did not pay for
the product. People typically release for free what *they* need, and
understand it may need to be adapted by others to fit other needs.
At no time did they promise to support the product or rewrite it for
anybody else indefinitely. (But *sometimes* they do that because
they like/want to, especially when you can clearly and politely state
the thing you want.)

This is just one example, there are hundert
others out there in all the unfinished libraries and tools. This gives
a bad reputation to the whole language and community.

Like what? There's plenty of people who may be able to pitch in and
help out. I won't be so rude as to ask "so where's your patches"
because I realize that not everybody has copious amounts of free time
to submit patches to the proper places (or even know how to fix their
problems). From what I've seen on the mailing list, Ruby does not
have a bad reputation and those that think so generally go find some
"better" language anyway.

The Rubygarden wiki would be a good place to have a 'libraries
needing loving' page...

 

[Lothar Scholz]

Hello Eric,


EH> I'm not sure this is a good thing. Library A extends String with a
EH> handy method, but the user isn't using library A, and the user is
EH> trying to use that handy method...

Thats why we need tagged sets of documentation that can be added and
removed easily. Having a good command line documentation tool (or at
least any kind of documentation tool) is important.

EH> As it is, ri cannot tell you where a method came from, so throwing in
EH> methods from extensions will lead to much frustration as you try to
EH> track down which files you need to require to get which methods.

EH> ri was designed to be clear and simple. I worry that extra
EH> information may end up being too much or completely missed.

So it is a just an unprofessional toy. Low quality. You get what you
pay for: nothing.

Sorry but the world out there is not as simple. And i
think many people who look at ruby simply leave it because with an
attitude like this it really looks like a toy. It's not clear, not
simple and it does not work for me and for thousands of other people
who are think that lack of documentation is still a big missing
of ruby. So whats now ?

EH> ri's original requirements seem to have been something like "Create a
EH> command-line tool to give handy access to documentation for core
EH> Ruby". It performs exceedingly well at this.

No. This was not the requirement.

EH> I also don't believe you have a reason to complain about
EH> 'correctness' or 'fullfilling requirements' when you did not pay for
EH> the product. People typically release for free what *they* need,
EH> and understand it may need to be adapted by others to fit other needs.

I see this (and almost any things we both talked before on this list) very
different from you.

I think it is a huge failure of the ruby core team to accept a tool
of this low quality and put it as one of the core technologies into the
ruby core. But i'm too tired to talk about this issues again and again.
Maybe we should look at better working communities, for example Guido
still does not bundle pychecker (a good tool) with the language
runtime as it is not of high enough quality. I think the ruby people
should have the same high quality commitment as python.

The main problem is that if someone else jumps in it is 100'th of hours
of work, while a little bit better and more general implementation would
took just a few 10'th of hours. Thats whats so disappointing about all
this.

 

[James Britt]

Lothar Scholz wrote:
...

Sorry but the world out there is not as simple. And i
think many people who look at ruby simply leave it because with an
attitude like this it really looks like a toy. It's not clear, not
simple and it does not work for me and for thousands of other people
who are think that lack of documentation is still a big missing
of ruby. So whats now ?

Get together with the folks on the ruby-doc mailing list and help them
improve the situation. You can subscribe to the mailing list by
sending a request to (e-mail address removed), with a message body in
the following format:

subscribe your-name

Do not use an E-mail address for your-name. Use your actual name.




James Britt

--

http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com - Playing with Better Toys

 

[Eric Hodel]

Hello Eric,
EH> On 27 May 2005, at 22:15, Lothar Scholz wrote:

EH> As it is, ri cannot tell you where a method came from, so
throwing in
EH> methods from extensions will lead to much frustration as you
try to
EH> track down which files you need to require to get which methods.

EH> ri was designed to be clear and simple. I worry that extra
EH> information may end up being too much or completely missed.

So it is a just an unprofessional toy. Low quality. You get what you
pay for: nothing.

Sorry but the world out there is not as simple. And i
think many people who look at ruby simply leave it because with an
attitude like this it really looks like a toy.

It is not an attitude, it is reality. Please do not knock volunteer
efforts, it is unprofessional and highly offensive. This attitude of
"your work sucks" will not get people to fix anything.

It's not clear, not
simple and it does not work for me and for thousands of other people
who are think that lack of documentation is still a big missing
of ruby. So whats now ?

Complaining about the problem will not fix it. If things are missing/
broken/don't work like you want then file a bug and offer a solution
(http://rubyforge.org/projects/rdoc/). Simply complaining how things
suck is not going to get them fixed.

EH> ri's original requirements seem to have been something like
"Create a
EH> command-line tool to give handy access to documentation for core
EH> Ruby". It performs exceedingly well at this.

No. This was not the requirement.

Please, enlighten us. What was the requirement?

EH> I also don't believe you have a reason to complain about
EH> 'correctness' or 'fullfilling requirements' when you did not
pay for
EH> the product. People typically release for free what *they* need,
EH> and understand it may need to be adapted by others to fit other
needs.

I see this (and almost any things we both talked before on this
list) very
different from you.

I think it is a huge failure of the ruby core team to accept a tool
of this low quality and put it as one of the core technologies into
the
ruby core. But i'm too tired to talk about this issues again and
again.
Maybe we should look at better working communities, for example Guido
still does not bundle pychecker (a good tool) with the language
runtime as it is not of high enough quality. I think the ruby people
should have the same high quality commitment as python.

The main problem is that if someone else jumps in it is 100'th of
hours
of work, while a little bit better and more general implementation
would
took just a few 10'th of hours. Thats whats so disappointing about all
this.

What would you do if you had no ri or rdoc?

Please describe how ri and rdoc could be better here, or file a bug
(http://rubyforge.org/projects/rdoc/). I find it highly unlikely
that it will get fixed without at least a concrete description of the
problems.

 

[Sam Roberts]

Quoting (e-mail address removed), on Sat, May 28, 2005 at 08:56:49PM=
+0900:

I think it is a huge failure of the ruby core team to accept a tool
of this low quality and put it as one of the core technologies into the
ruby core. But i'm too tired to talk about this issues again and again.
Maybe we should look at better working communities, for example Guido
still does not bundle pychecker (a good tool) with the language
runtime as it is not of high enough quality. I think the ruby people
should have the same high quality commitment as python.

Yeah, but if there wasn't a good doc tool in the core, then you'd be
griping about that. ri needs work, we all know that, but whinging about
it isn't going to make it get done faster.

Dave put some energy and code back into ruby while working on his
commercial projects. What have you put back into ruby while working on
your IDE? I don't see anything on RAA from you, I hope you've been
contributing lots of patches.

Comparing maturity of ruby tools to languages that have existed for a
lot longer, and have a lot more commercial backing, is completely lame.

It's called "ruby", not "athena", it didn't leap forth into the world
=66rom the mind of matz fully grown, it is developing into something
beautiful through slow, hard work.

Cheers,
Sam

 

[Dave Thomas]

Looked further into it and the situation is more worse then i
expected. As RI does absolutely not handle the ruby key feature of
open classes. If i write somewere a

class File
def temp_dir; return "c:/myproject/temp"; end
end

The whole documentation for File is destroyed.

I'm surprised if this is the case: rdoc and ri go to some trouble to
handle this.

 

[Austin Ziegler]

I'm surprised if this is the case: rdoc and ri go to some trouble to
handle this.

On an individual run, rdoc and ri do handle this very well. On
multiple runs, I have experienced the same thing as Lothar. That is,
if I generate the system documentation, and then later run ri on
something that adds a method to File, File's documentation may be
corrupted.

ri works very well for initial deployment, but does not work well for
organic growth and management of documentation -- which is what Lothar
is *really* trying to say here, but apparently lacks the tact.

-austin
--=20
Austin Ziegler * (e-mail address removed)
* Alternate: (e-mail address removed)