Does Ruby have a bundled documentation reader?
I'm guessing it might be rdoc, but we're not yet on speaking terms. Anyone willing to introduce me? <laughs>
James Edward Gray II
James Edward Gray II wrote:
Does Ruby have a bundled documentation reader?
I'm guessing it might be rdoc, but we're not yet on speaking terms. Anyone willing to introduce me? <laughs>
James Edward Gray II
In general, you can run 'ri' at the command line, along with the name of a class, module, or method, (and combinations) and see documentation (the documentation comes from running rdoc over the source code):
% ri String.center
---------------------------------------------------------- String#center
str.center(integer) => new_str
···
------------------------------------------------------------------------
If _integer_ is greater than the length of _str_, returns a new
+String+ of length _integer_ with _str_ centered between spaces;
otherwise, returns _str_.
"hello".center(4) #=> "hello"
"hello".center(20) #=> " hello "
% ri String
---------------------------------------------------------- Class: String
A +String+ object holds and manipulates an arbitrary sequence of
bytes, typically representing characters. String objects may be
created using +String::new+ or as literals.
Because of aliasing issues, users of strings should be aware of the
methods that modify the contents of a +String+ object. Typically,
methods with names ending in ``!'' modify their receiver, while
those without a ``!'' return a new +String+. However, there are
exceptions, such as +String#=+.
------------------------------------------------------------------------
Includes:
---------
Comparable(<, <=, ==, >, >=, between?), Enumerable(all?, any?,
collect, detect, each_with_index, entries, find, find_all, grep,
include?, inject, map, max, member?, min, partition, reject,
select, sort, sort_by, to_a, to_set, zip)
Class methods:
--------------
new
Instance methods:
-----------------
%, *, +, <<, <=>, ==, =~, , =, capitalize, capitalize!,
casecmp, center, chomp, chomp!, chop, chop!, concat, count, crypt,
delete, delete!, downcase, downcase!, dump, each, each_byte,
each_line, empty?, eql?, gsub, gsub!, hash, hex, include?, index,
initialize_copy, insert, inspect, intern, length, ljust, lstrip,
lstrip!, match, next, next!, oct, replace, reverse, reverse!,
rindex, rjust, rstrip, rstrip!, scan, size, slice, slice!, split,
squeeze, squeeze!, strip, strip!, sub, sub!, succ, succ!, sum,
swapcase, swapcase!, to_f, to_i, to_s, to_str, to_sym, tr, tr!,
tr_s, tr_s!, unpack, upcase, upcase!, upto
This sounds exactly like what I'm looking for, but when I tried it...
% ri String
No ri documentation found in:
/usr/local/share/ri/1.8/system
/usr/local/share/ri/1.8/site
/Users/james/.rdoc
Was rdoc run to create documentation?
So I tried:
% rdoc
Which scrolled a lot of source files. Unfortunately, it didn't change ri's response. What am I missing here?
Thanks.
James Edward Gray II
···
On Aug 27, 2004, at 7:34 PM, James Britt wrote:
James Edward Gray II wrote:
Does Ruby have a bundled documentation reader?
I'm guessing it might be rdoc, but we're not yet on speaking terms. Anyone willing to introduce me? <laughs>
James Edward Gray IIIn general, you can run 'ri' at the command line, along with the name of a class, module, or method, (and combinations) and see documentation
Did you install Ruby from source. If so, go into the lib directory and type sudo ri --system and it will install all the documentation.
Cheers
Dave
···
On Aug 27, 2004, at 20:43, James Edward Gray II wrote:
% ri String
No ri documentation found in:
/usr/local/share/ri/1.8/system
/usr/local/share/ri/1.8/site
/Users/james/.rdocWas rdoc run to create documentation?
So I tried:
% rdoc
Which scrolled a lot of source files. Unfortunately, it didn't change ri's response. What am I missing here?
Many people have a hard time generating the documentation from the
sources -- it takes a long time, rdoc often dies in the process (after
processing for several minutes) and you have to download the sources,
etc...
I thought some of them would benefit from a packaged version of ri/rdoc's
runtime plus pre-generated RI data files. If you have rpa-base installed
just
rpa install ri-rpa
will get the RPAfied ri with all the needed documentation.
Additionally, ri-rpa provides ri integration for other libraries
installed through rpa-base, as shown in
http://rpa-base.rubyforge.org/wiki/wiki.cgi?Rpa_Base_In_Action/Ri_Integration
You can find more information about rpa-base at
http://rpa-base.rubyforge.org/
and download it from there if you want.
···
On Sat, Aug 28, 2004 at 09:43:19AM +0900, James Edward Gray II wrote:
>In general, you can run 'ri' at the command line, along with the name
>of a class, module, or method, (and combinations) and see
>documentationThis sounds exactly like what I'm looking for, but when I tried it...
% ri String
No ri documentation found in:
/usr/local/share/ri/1.8/system
/usr/local/share/ri/1.8/site
/Users/james/.rdocWas rdoc run to create documentation?
--
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com
Hi --
···
On Sat, 28 Aug 2004, Dave Thomas wrote:
On Aug 27, 2004, at 20:43, James Edward Gray II wrote:
> % ri String
> No ri documentation found in:
> /usr/local/share/ri/1.8/system
> /usr/local/share/ri/1.8/site
> /Users/james/.rdoc
>
> Was rdoc run to create documentation?
>
> So I tried:
>
> % rdoc
>
> Which scrolled a lot of source files. Unfortunately, it didn't change
> ri's response. What am I missing here?Did you install Ruby from source. If so, go into the lib directory and
type sudo ri --system and it will install all the documentation.
Is that supposed to be rdoc --ri-system and/or rdoc --ri-site? I
couldn't find any ri that accepted a --system argument.
David
--
David A. Black
dblack@wobblini.net
Did you install Ruby from source.
I did, yes.
If so, go into the lib directory
Does /usr/local/lib/ruby/1.8/ sound about right?
Would it have a ton of files like:
...
irb
irb.rb
...
uri
uri.rb
...
?
and type sudo ri --system and it will install all the documentation.
The closest I could come up with was sudo rdoc --ri-system. That did a lot of work, and even changed ri's responses. Now I get:
% ri String
Nothing known about String
Thanks.
James Edward Gray II
···
On Aug 27, 2004, at 8:08 PM, Dave Thomas wrote:
I do wish folks would tell me when they see this happening: if there's a problem here I'd like to fix it.
If you run RDoc and it dies on you while processing the source tree, please post the message it produces, along with a description of what you were ding, and I'll work on it.
Cheers
Dave
···
On Aug 28, 2004, at 5:41, Mauricio Fernández wrote:
Many people have a hard time generating the documentation from the
sources -- it takes a long time, rdoc often dies in the process (after
processing for several minutes) and you have to download the sources,
etc...
--ri-system
Cheers
Dave
···
On Aug 27, 2004, at 21:35, David A. Black wrote:
Is that supposed to be rdoc --ri-system and/or rdoc --ri-site? I
couldn't find any ri that accepted a --system argument.
You want to go to the source distribution's lib/ directory.
Cheers
Dave
···
On Aug 27, 2004, at 22:46, James Edward Gray II wrote:
Does /usr/local/lib/ruby/1.8/ sound about right?
Dave Thomas wrote:
Many people have a hard time generating the documentation from the
sources -- it takes a long time, rdoc often dies in the process (after
processing for several minutes) and you have to download the sources,
etc...I do wish folks would tell me when they see this happening: if there's a problem here I'd like to fix it.
Dave,
When someone has a problem with rdoc, is there something that tells them
who to contact?
If you run RDoc and it dies on you while processing the source tree, please post the message it produces, along with a description of what you were ding, and I'll work on it.
People often (relatively speaking) post such problems to the ruby-doc
list. If no one there can help them then they are encouraged to post to
ruby-talk.
But as these sorts for questions come up semi-regularly, I'm putting
together a ruby-doc FAQ to help explain getting ri working. Is there a
specific way you would prefer to be reached if someone has a problem?
Also, if anyone has discovered quirks (and solutions) when installing
the ri data files on assorted OS, please let me know (jbritt AT ruby-doc
DOT org) so I can document them in the FAQ.
Thanks,
James
···
On Aug 28, 2004, at 5:41, Mauricio Fernández wrote:
When someone has a problem with rdoc, is there something that tells them
who to contact?
They can contact me, or mail to this list.
But as these sorts for questions come up semi-regularly, I'm putting
together a ruby-doc FAQ to help explain getting ri working. Is there a
specific way you would prefer to be reached if someone has a problem?
I'd really rather you didn't. Instead, I'd like to find out what issues folks have and then make things so that no FAQ is necessary.
Cheers
Dave
···
On Aug 28, 2004, at 21:00, James Britt wrote:
I'm still not getting along with rdoc and ri.
When I use your suggestion above, I see...
% rdoc --ri-system
unrecognized option `--ri-system'
For help on options, try 'rdoc --help'
Replacing --ri-system with --ri-site SEEMS to do the trick as near as I can tell. Please correct me if I'm wrong.
So, I went to the 1.8.1 source directory "lib" as you suggested in another message. Running rdoc there seems to get me some documentation, but not all of it. For example, String is missing a lot of methods and Array and Hash both list only one.
I tried backing up to the root directory of the source and building the documentation from there. That's the closest I've ever come to getting usable docs, but there are still some issues. Here's some example ri requests, after generating the docs this way:
% ri Array
---------------------------------------------------------- Module: Array
Arrays are ordered, integer-indexed collections of any object.
Array indexing starts at 0, as in C or Java. A negative index is
assumed to be relative to the end of the array---that is, an index
of -1 indicates the last element of the array, -2 is the next to
last element in the array, and so on.
···
On Aug 27, 2004, at 11:21 PM, Dave Thomas wrote:
On Aug 27, 2004, at 21:35, David A. Black wrote:
Is that supposed to be rdoc --ri-system and/or rdoc --ri-site? I
couldn't find any ri that accepted a --system argument.--ri-system
------------------------------------------------------------------------
% ri Array#push
Nothing known about Array#push
% ri Hash
----------------------------------------------------------- Module: Hash
Maps: Hash#to_yaml
------------------------------------------------------------------------
Any further tips are very much appreciated. I'm pretty frustrated with the docs process, I feel like this should be simple.
If it helps, I'm on Mac OS X.3.5 building Ruby 1.8.1.
Thanks.
James Edward Gray II
Dave Thomas wrote:
But as these sorts for questions come up semi-regularly, I'm putting
together a ruby-doc FAQ to help explain getting ri working. Is there a
specific way you would prefer to be reached if someone has a problem?I'd really rather you didn't. Instead, I'd like to find out what issues folks have and then make things so that no FAQ is necessary.
Well, these are already FAQs; what remains is what to tell people when they ask them. I haven't installed from source lately, but as I recall, rdoc/ri file were not installed by default. So, FAQ #1 is, How do I get ri working? Currently, it is not obvious to enough people, so they ask.
Some people, after trying to run rdoc to create the ri files, have problems. Sometimes it's because they ran rdoc on the wrong directory. If that's the case, then see FAQ #1. Sometimes there's some other issue. When they ask about this, should the response always be, "Contact Dave Thomas?"
I'm not saying you shouldn't be informed of problems, but what do people do while waiting for an answer? If there are known issues on certain platforms, or certain distributions, and known workarounds for these, why not simply pass them on while they are being taken care of, and forwarding the details to you?
Thanks,
James
···
On Aug 28, 2004, at 21:00, James Britt wrote:
I'm still not getting along with rdoc and ri.
[...]
Any further tips are very much appreciated. I'm pretty frustrated with
the docs process, I feel like this should be simple.If it helps, I'm on Mac OS X.3.5 building Ruby 1.8.1.
You might want to try to install the pre-generated RI data-files
distributed with ri-rpa. I know of another OSX user who was experiencing
problems with ri/rdoc and could get ri-rpa to work.
You can download rpa-base from http://rpa-base.rubyforge.org
and then just
$ rpa install ri-rpa
you can then test
$ ri-rpa Hash
Plz tell me if you experience any problem.
···
On Mon, Sep 06, 2004 at 03:59:21AM +0900, James Edward Gray II wrote:
--
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com
You are using an out-0of-date ri.
The new version is available with Ruby 1.8.2
Cheers
Dave
···
On Sep 5, 2004, at 13:59, James Edward Gray II wrote:
When I use your suggestion above, I see...
% rdoc --ri-system
unrecognized option `--ri-system'
I'm an OSX user and have no problems with ri/rdoc 
I just use the recent source.
Cheers
Dave
···
On Sep 5, 2004, at 14:24, Mauricio Fernández wrote:
On Mon, Sep 06, 2004 at 03:59:21AM +0900, James Edward Gray II wrote:
I'm still not getting along with rdoc and ri.
[...]
Any further tips are very much appreciated. I'm pretty frustrated with
the docs process, I feel like this should be simple.If it helps, I'm on Mac OS X.3.5 building Ruby 1.8.1.
You might want to try to install the pre-generated RI data-files
distributed with ri-rpa. I know of another OSX user who was experiencing
problems with ri/rdoc and could get ri-rpa to work.
That was it. You fixed my problem. I finally have Ruby doc available for easy access. Thanks much.
James Edward Gray II
···
On Sep 5, 2004, at 7:27 PM, Dave Thomas wrote:
On Sep 5, 2004, at 13:59, James Edward Gray II wrote:
When I use your suggestion above, I see...
% rdoc --ri-system
unrecognized option `--ri-system'
You are using an out-0of-date ri.
The new version is available with Ruby 1.8.2
I wanted to say thank you for trying to help me twice now. I wasn't completely ignoring your suggestions. I haven't gotten around to checking out rpa yet, but it's on my list. Thanks again.
James Edward Gray II
···
On Sep 5, 2004, at 2:24 PM, Mauricio Fernández wrote:
On Mon, Sep 06, 2004 at 03:59:21AM +0900, James Edward Gray II wrote:
I'm still not getting along with rdoc and ri.
[...]
Any further tips are very much appreciated. I'm pretty frustrated with
the docs process, I feel like this should be simple.If it helps, I'm on Mac OS X.3.5 building Ruby 1.8.1.
You might want to try to install the pre-generated RI data-files
distributed with ri-rpa. I know of another OSX user who was experiencing
problems with ri/rdoc and could get ri-rpa to work.
Ouch! It was in another branch of the same thread, over 1 week ago, but
I still have this moronic feeling 
Don't feel forced to try it out, plz interpret my accidental insistence
as a proof of idiocy rather than a deliberate attempt to force you to
install it
···
On Tue, Sep 07, 2004 at 12:38:10AM +0900, James Edward Gray II wrote:
>You might want to try to install the pre-generated RI data-files
>distributed with ri-rpa. I know of another OSX user who was
>experiencing
>problems with ri/rdoc and could get ri-rpa to work.I wanted to say thank you for trying to help me twice now. I wasn't
completely ignoring your suggestions. I haven't gotten around to
checking out rpa yet, but it's on my list. Thanks again.
--
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com