How to get ri/rdoc working for 1.8.1 on Windows?

ruby-talk
1

Part 1 is to chdir \Ruby\bin and delete the five *.bat files

Part 2 is to (still in \Ruby\bin) rename ri to ri.rb, rdoc to rdoc.rb,
erb to erb.rb, irb to irb.rb, and testrb to testrb.rb.

Part 3 is to chdir to \Ruby\lib and execute rdoc -R

Unfortunately, that part is still broken, and will eventually crash.
But it will leave you better off than you were before.

···

–
John W. Kennedy
Read the remains of Shakespeare’s lost play, now annotated!
http://pws.prserv.net/jwkennedy/Double%20Falshood.html

2

Part 1 is to chdir \Ruby\bin and delete the five *.bat files

Part 2 is to (still in \Ruby\bin) rename ri to ri.rb, rdoc to rdoc.rb,
erb to erb.rb, irb to irb.rb, and testrb to testrb.rb.

John:

This is great stuff. I’ll leave the stuff above to Curt & co, who are
doing the installer. The following it probably not what you want to do,
though:

Part 3 is to chdir to \Ruby\lib and execute rdoc -R

Unfortunately, that part is still broken, and will eventually crash.
But it will leave you better off than you were before.

RDoc should really be run in the Ruby source tree, not in the installed
libraries. The reasons are twofold. First, doing this means you won’t
document the stuff in the .c file, which includes extensions and (even
worse) the built-in classes (like String). Second, you will document
a lot of extraneous stuff that shouldn’t really be included. The reason
is that many librry include a boatload of helper files. These typically
are internal, and have no meaningful user-level interface. However, If
you just run RDoc on the lib/ directory, you’ll pick them all up.

In the source tree, however, there are control files (call .document)
that direct RDoc, telling what to include and what to exclude.

The real solution here is for the folks who bundle the installation to
run RDoc before creating the bundle, and then include the generated
documentation directories as part of the distributed bundle.

Cheers

Dave

···

On Apr 21, 2004, at 11:19, John W. Kennedy wrote:

3

Hello John,

Wednesday, April 21, 2004, 6:19:05 PM, you wrote:

Part 1 is to chdir \Ruby\bin and delete the five *.bat files

Part 2 is to (still in \Ruby\bin) rename ri to ri.rb, rdoc to rdoc.rb,
erb to erb.rb, irb to irb.rb, and testrb to testrb.rb.

Part 3 is to chdir to \Ruby\lib and execute rdoc -R

Unfortunately, that part is still broken, and will eventually crash.
But it will leave you better off than you were before.

Download and Install: http://www.ruby-ide.com/download.php SCNR.
But unfortunately i couldn't do something about the rdoc bug. Anybody
tried to do use the latest (maybe bugfree) CVS in a 1.8.1 environment.

···

--
Best regards,
Lothar mailto:mailinglists@scriptolutions.com

4

Dave, Thanks for the solution synopsis and recommendations. I’m going to
copy your response into our bug report to help make sure we get it right
next time.

Dave Thomas wrote:

···

On Apr 21, 2004, at 11:19, John W. Kennedy wrote:

Part 1 is to chdir \Ruby\bin and delete the five *.bat files

Part 2 is to (still in \Ruby\bin) rename ri to ri.rb, rdoc to rdoc.rb,
erb to erb.rb, irb to irb.rb, and testrb to testrb.rb.

John:

This is great stuff. I’ll leave the stuff above to Curt & co, who are
doing the installer. The following it probably not what you want to do,
though:

Part 3 is to chdir to \Ruby\lib and execute rdoc -R

Unfortunately, that part is still broken, and will eventually crash.
But it will leave you better off than you were before.

RDoc should really be run in the Ruby source tree, not in the installed
libraries. The reasons are twofold. First, doing this means you won’t
document the stuff in the .c file, which includes extensions and (even
worse) the built-in classes (like String). Second, you will document
a lot of extraneous stuff that shouldn’t really be included. The reason
is that many librry include a boatload of helper files. These typically
are internal, and have no meaningful user-level interface. However, If
you just run RDoc on the lib/ directory, you’ll pick them all up.

In the source tree, however, there are control files (call .document)
that direct RDoc, telling what to include and what to exclude.

The real solution here is for the folks who bundle the installation to
run RDoc before creating the bundle, and then include the generated
documentation directories as part of the distributed bundle.

Cheers

Dave

Incoming mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.662 / Virus Database: 425 - Release Date: 4/20/2004

5

“Dave Thomas” dave@pragprog.com wrote…

The real solution here is for the folks who bundle the installation to
run RDoc before creating the bundle, and then include the generated
documentation directories as part of the distributed bundle.

Any good way to handle libraries added on by each user after the
“installation”? Should we hope that each of those library authors runs rdoc
before distributing, and that their “install” scripts move all the doc stuff
around to the right places? Or that they at include the .document control
file?

This part may be harder to count on; what would you suggest for rdoc’ing
those cases?

Thanks!

6

Could someone tell me what this bug is??

Cheers

Dave

···

On Apr 21, 2004, at 14:40, Lothar Scholz wrote:

Download and Install: http://www.ruby-ide.com/download.php SCNR.
But unfortunately i couldn’t do something about the rdoc bug. Anybody
tried to do use the latest (maybe bugfree) CVS in a 1.8.1 environment.

7

The only issue is if libraries are distributed as binaries: if they’re
shipped in source form (either .c or .rb), then the library writers
should arrange to run RDoc on the source as part of the installation
process on the target machine. If there’s stuff that shouldn’t be
included, they can just use .document files to override the default
behavior.

Cheers

Dave

···

On Apr 21, 2004, at 13:44, Its Me wrote:

“Dave Thomas” dave@pragprog.com wrote…

The real solution here is for the folks who bundle the installation to
run RDoc before creating the bundle, and then include the generated
documentation directories as part of the distributed bundle.

Any good way to handle libraries added on by each user after the
“installation”? Should we hope that each of those library authors
runs rdoc
before distributing, and that their “install” scripts move all the doc
stuff
around to the right places? Or that they at include the .document
control
file?

8

If you install a package as a gem, you can get the RDoc installed.
Then you can view it. Example:

Download and install log4r, latest version.

$ gem -i log4r --gen-rdoc

Run documentation browser.

$ gem_server

Now open your browser to http://localhost:8808 and you will see

your installed gems and can view their RDoc output.

It doesn’t answer your question directly, but I hope it gives you a
taste of the future :slight_smile:

Gavin

···

On Thursday, April 22, 2004, 4:44:09 AM, Its wrote:

“Dave Thomas” dave@pragprog.com wrote…

The real solution here is for the folks who bundle the installation to
run RDoc before creating the bundle, and then include the generated
documentation directories as part of the distributed bundle.

Any good way to handle libraries added on by each user after the
“installation”? Should we hope that each of those library authors runs rdoc
before distributing, and that their “install” scripts move all the doc stuff
around to the right places? Or that they at include the .document control
file?

This part may be harder to count on; what would you suggest for rdoc’ing
those cases?

9

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution doesn’t work,
and that he is wondering whether anybody has tried to run the latest rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to work
fine?

It sure would be nice to see 1.8.2 be released soon, as this would give us
working online documentation (using rdoc/ri) on Unix at least. rdoc/ri in
1.8.1 is not even working there.

Cheers,

···

On Thu, Apr 22, 2004 at 05:50:40AM +0900, Dave Thomas wrote:

On Apr 21, 2004, at 14:40, Lothar Scholz wrote:

Download and Install: http://www.ruby-ide.com/download.php SCNR.
But unfortunately i couldn’t do something about the rdoc bug. Anybody
tried to do use the latest (maybe bugfree) CVS in a 1.8.1 environment.

Could someone tell me what this bug is??

–
Jos Backus / /// Sunnyvale, CA
_/ _/ _/
/ ///
_/ _/ _/ /
jos at catnook.com // /// require ‘std/disclaimer’

10

Not sure if this is related.

I just ran “rdoc -R” on my ruby/lib directory on Windows 2k (with rexml,
log4r, rbbr, foxtails, fox, borges installed in site_ruby, and the default
1.8.1 set elsewhere) . The standard pragprog build from January-ish.

After about 90 minutes ruby was trashing wildly, consuming just around 300MB
of memory. Very low CPU usage.

It then took an additional 20 minutes to process a single 132KB file “tk.rb”
in ruby/lib.

I euthanized it about 20 minutes later. I assume I lost whatever docs had
been generated (where should I look for them?).

I wish I could be more detailed but I could not figure things out any deeper
than this.

Should this be expected for a lib directory ~36M total in my ruby/lib? It
would be really nice to have full rdoc and ri access to all the stuff one
uses, even if some libraries come without rdoc run.

···

“Dave Thomas” dave@pragprog.com wrote

Could someone tell me what this bug is??

11

Hello Jos,

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution doesn't work,

I have my own 1.8.1 distribution :slight_smile:
So it's not the already mentioned "rdoc.bat" problem.

and that he is wondering whether anybody has tried to run the latest rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to work
fine?

It sure would be nice to see 1.8.2 be released soon, as this would give us
working online documentation (using rdoc/ri) on Unix at least. rdoc/ri in
1.8.1 is not even working there.

Last time i used it it died periodically with some "undefined method" errors.
I posted this to the Ruby Doc mailing list (and i wasn't the first one)
but it seems that Dave is not a member of this list

I tried it again two hours ago and couldn't reproduce it this time.
Maybe i find some time to look at it tomorrow.

···

--
Best regards,
Lothar mailto:mailinglists@scriptolutions.com

12

Does it also install it so ‘ri’ works? If not, can this be added?

Cheers

Dave

···

On Apr 21, 2004, at 17:56, Gavin Sinclair wrote:

If you install a package as a gem, you can get the RDoc installed.
Then you can view it. Example:

Download and install log4r, latest version.

$ gem -i log4r --gen-rdoc

Run documentation browser.

$ gem_server

Now open your browser to http://localhost:8808 and you will see

your installed gems and can view their RDoc output.

It doesn’t answer your question directly, but I hope it gives you a
taste of the future :slight_smile:

13

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution
doesn’t work,
and that he is wondering whether anybody has tried to run the latest
rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to
work
fine?

The latest RDoc is part of the Ruby source distribution, and so you’d
have a newer version of Ruby lying around anyway… :slight_smile:

It sure would be nice to see 1.8.2 be released soon, as this would
give us
working online documentation (using rdoc/ri) on Unix at least.
rdoc/ri in
1.8.1 is not even working there.

I’m not sure I understand this. On Unix, 1.8.1 and 1.9 both work just
fine: I use them every day. You just grab the latest, configure and
make install as normal, and RDoc is automatically run and the
documentation built.

This is very frustrating for me. I understand there are problems with
how the Windows installer was built, and it looks like Curt is going to
sort that out. Of the stuff in my control, what needs to be done to get
rdoc/ri working for folks who can’t currently use it?

Cheers

Dave

···

On Apr 21, 2004, at 18:45, Jos Backus wrote:

14

“Gavin Sinclair” gsinclair@soyabean.com.au wrote in message

Now open your browser to http://localhost:8808 and you will see

your installed gems and can view their RDoc output.

It doesn’t answer your question directly, but I hope it gives you a
taste of the future :slight_smile:

delicious!

reminds me of how jEdit integrates the documentation from all its plug-ins.

15

Hello Its,

Friday, April 23, 2004, 4:34:05 AM, you wrote:

I just ran “rdoc -R” on my ruby/lib directory on Windows 2k (with rexml,
log4r, rbbr, foxtails, fox, borges installed in site_ruby, and the default
1.8.1 set elsewhere) . The standard pragprog build from January-ish.

After about 90 minutes ruby was trashing wildly, consuming just around 300MB
of memory. Very low CPU usage.

It then took an additional 20 minutes to process a single 132KB file “tk.rb”
in ruby/lib.

I euthanized it about 20 minutes later. I assume I lost whatever docs had
been generated (where should I look for them?).

I wish I could be more detailed but I could not figure things out any deeper
than this.

Should this be expected for a lib directory ~36M total in my ruby/lib? It
would be really nice to have full rdoc and ri access to all the stuff one
uses, even if some libraries come without rdoc run.

I can only say that running against the ruby/lib (not including
site/lib) worked without problems in 7 min 24sec.

···

–
Best regards,
Lothar mailto:mailinglists@scriptolutions.com

16

Clearly there are some memory issues here: RDoc builds its data
structures in memory, then writes everything out at the end. This helps
it knit everything together. It could work incrementally, but then it
would be so good with libraries such as rational and mathn that modify
other classes.

Fundamentally, RDoc was never designed to run against all the .rb files
on a disk: I intended it to document the library files with external
interfaces, so the assumptions made let it work with 100’s of .rb
files, but not 1000’s.

Unfortunately, in the Windows world, the current distributions don’t
have the RDoc documentation installed, and at the same time they don’t
distribute the Ruby source that can be used to generate them. This is a
frustrating for us all: I’m proud of RDoc/ri, and I’ve put (literally)
many, many months of work into the tool and into adding documentation
to the Ruby core files. I’d like to see it “just work.”

Running it against lib/ really isn’t the answer. You’ll get some useful
stuff documented, but you’ll also document a whole lot of cruft:
private helper files and non-external APIs. The real answer, I’m
afraid, is patience. In a few days I’m sure we’ll see a distribution
with a working ri command. In the meantime, Curt has kindly posted a
URL for the ri documentation files generated for a 1.8 distribution.

Cheers

Dave

···

On Apr 22, 2004, at 21:34, Its Me wrote:

“Dave Thomas” dave@pragprog.com wrote

Could someone tell me what this bug is??

Not sure if this is related.

I just ran “rdoc -R” on my ruby/lib directory on Windows 2k (with
rexml,
log4r, rbbr, foxtails, fox, borges installed in site_ruby, and the
default
1.8.1 set elsewhere) . The standard pragprog build from January-ish.

17

Last time i used it it died periodically with some “undefined method”
errors.
I posted this to the Ruby Doc mailing list (and i wasn’t the first one)
but it seems that Dave is not a member of this list

No, I’m not. You can always e-mail me directly.

I tried it again two hours ago and couldn’t reproduce it this time.
Maybe i find some time to look at it tomorrow.

Thanks.

Cheers

Dave

···

On Apr 21, 2004, at 19:49, Lothar Scholz wrote:

18

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution
doesn’t work,
and that he is wondering whether anybody has tried to run the latest
rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to
work
fine?

The latest RDoc is part of the Ruby source distribution, and so you’d
have a newer version of Ruby lying around anyway… :slight_smile:

Of course :slight_smile: I was thinking along the lines of the minimum number of files
that would have to be updated in an existing 1.8.1 installation to make
rdoc/ri work. It turns out Lothar has his own distribution, which I wasn’t
aware of.

It sure would be nice to see 1.8.2 be released soon, as this would
give us
working online documentation (using rdoc/ri) on Unix at least.
rdoc/ri in
1.8.1 is not even working there.

I’m not sure I understand this. On Unix, 1.8.1 and 1.9 both work just
fine: I use them every day. You just grab the latest, configure and
make install as normal, and RDoc is automatically run and the
documentation built.

I’m thinking of people who don’t use CVS but package systems like, say, Cygwin
or the FreeBSD Ports collection. To verify, I just rebuilt 1.8.1 on FreeBSD
and get this error:

lizzy:/usr/local/src/ruby-1.8.1# rdoc -R
[snip]
array.c:
Generating RI…
/tmp/ruby/lib/ruby/1.8/yaml.rb:17:in require': No such file to load -- yaml/parser (LoadError) from /tmp/ruby/lib/ruby/1.8/yaml.rb:17 from /tmp/ruby/lib/ruby/1.8/rdoc/ri/ri_descriptions.rb:1:in require’
from /tmp/ruby/lib/ruby/1.8/rdoc/ri/ri_descriptions.rb:1
from /tmp/ruby/lib/ruby/1.8/rdoc/ri/ri_reader.rb:1:in require' from /tmp/ruby/lib/ruby/1.8/rdoc/ri/ri_reader.rb:1 from /tmp/ruby/lib/ruby/1.8/rdoc/generators/ri_generator.rb:46:in require’
from /tmp/ruby/lib/ruby/1.8/rdoc/generators/ri_generator.rb:46
from /tmp/ruby/lib/ruby/1.8/rdoc/rdoc.rb:194:in require' from /tmp/ruby/lib/ruby/1.8/rdoc/rdoc.rb:194:in document’
from /tmp/ruby/bin/rdoc:63
lizzy:/usr/local/src/ruby-1.8.1#

The same happens when using the FreeBSD port (obviously); CVS head otoh works
fine. So the moment a new stable release is available, places like the FreeBSD
Ports collection will be updated at some point and rdoc/ri will work.

This is very frustrating for me. I understand there are problems with
how the Windows installer was built, and it looks like Curt is going to
sort that out. Of the stuff in my control, what needs to be done to get
rdoc/ri working for folks who can’t currently use it?

Nothing, afaIac. It works fine for me. Thank you Dave :slight_smile: And thanks to Curt et
al. for updating the installer!

Cheers

Dave

Groetjes,

···

On Thu, Apr 22, 2004 at 11:16:02AM +0900, Dave Thomas wrote:

On Apr 21, 2004, at 18:45, Jos Backus wrote:
–
Jos Backus / /// Sunnyvale, CA
_/ _/ _/
/ ///
_/ _/ _/ /
jos at catnook.com // /// require ‘std/disclaimer’

19

Hello Jos,

Hallo Lothar,

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution doesn’t work,

I have my own 1.8.1 distribution :slight_smile:
So it’s not the already mentioned “rdoc.bat” problem.

Okay, didn’t know that.

and that he is wondering whether anybody has tried to run the latest rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to work
fine?

It sure would be nice to see 1.8.2 be released soon, as this would give us
working online documentation (using rdoc/ri) on Unix at least. rdoc/ri in
1.8.1 is not even working there.

Last time i used it it died periodically with some “undefined method” errors.
I posted this to the Ruby Doc mailing list (and i wasn’t the first one)
but it seems that Dave is not a member of this list

I see a different error with the stock 1.8.1, but HEAD works fine here now.

I tried it again two hours ago and couldn’t reproduce it this time.
Maybe i find some time to look at it tomorrow.

Dankeschön.

Tschüss,

···

On Thu, Apr 22, 2004 at 09:49:57AM +0900, Lothar Scholz wrote:

Jos Backus / /// Sunnyvale, CA
_/ _/ _/
/ ///
_/ _/ _/ /
jos at catnook.com // /// require ‘std/disclaimer’

20

Dave Thomas wrote:

Perhaps Lothar meant to say that rdoc in the 1.8.1 distribution
doesn’t work,
and that he is wondering whether anybody has tried to run the latest
rdoc from
CVS against a stock 1.8.1 install because the latest rdoc appears to
work
fine?

The latest RDoc is part of the Ruby source distribution, and so you’d
have a newer version of Ruby lying around anyway… :slight_smile:

It sure would be nice to see 1.8.2 be released soon, as this would
give us
working online documentation (using rdoc/ri) on Unix at least.
rdoc/ri in
1.8.1 is not even working there.

I’m not sure I understand this. On Unix, 1.8.1 and 1.9 both work just
fine: I use them every day. You just grab the latest, configure and
make install as normal, and RDoc is automatically run and the
documentation built.

This is very frustrating for me. I understand there are problems with
how the Windows installer was built, and it looks like Curt is going to
sort that out. Of the stuff in my control, what needs to be done to get
rdoc/ri working for folks who can’t currently use it?

A lot of this seems somewhat muddy to me as well. Here’s what I know:

  1. Our process for building the ruby installer for windows does run rdoc
    to create the ri database. Unfortunately, it turns out those files didn’t
    get copied into the installer. I zipped up these files so you can download
    them here:

    http://curthibbs.us/share.zip

Unzip this into your ruby install dir (you should then have a “share”
subdirectory in your ruby install dir).

  1. rdoc.bat in the bin directory has 4 bad paths in them (all near the top
    of the file). You don’t need to delete his batch file, just change the paths
    to your ruby install dir (“c:\ruby” by default).

  2. “rdoc” and “ri” in the bin directory are missing their “.rb”
    extensions – simply rename them.

When I do these three things, I can run rdoc and ri without any problems.
Let me know if this works for you.

Curt

···

On Apr 21, 2004, at 18:45, Jos Backus wrote: