Perldoc Equivalent?

  • Thread starter James Edward Gray II
  • Start date
J

James Edward Gray II

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
 
J

James Britt

James said:
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
 
J

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

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
 
D

Dave Thomas

% 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.

Cheers

Dave
 
D

David A. Black

Hi --

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
 
J

James Edward Gray II

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
 
M

Mauricio Fernández

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?

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.
 
D

Dave Thomas

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.

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
 
J

James Britt

Dave said:
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
 
D

Dave Thomas

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
 
J

James Britt

Dave said:
On Aug 28, 2004, at 21:00, James Britt wrote:


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
 
J

James Edward Gray II

--ri-system

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.

------------------------------------------------------------------------

% 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
 
M

Mauricio Fernández

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.
 
D

Dave Thomas

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



Cheers

Dave
 
D

Dave Thomas

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.

I'm an OSX user and have no problems with ri/rdoc :)

I just use the recent source.


Cheers

Dave
 
J

James Edward Gray II

You are using an out-0of-date ri.

The new version is available with Ruby 1.8.2

That was it. You fixed my problem. I finally have Ruby doc available
for easy access. Thanks much.

James Edward Gray II
 
J

James Edward Gray II

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.

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
 
M

Mauricio Fernández

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.

Ouch! It was in another branch of the same thread, over 1 week ago, but
I still have this moronic feeling :p
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 :)
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads

ri and rdoc....like perldoc? 7
Whyday Fun and Games 8
Mac OS X TK 1
Need Solaris Help 18
Windows Ruby Version Check 10
RDoc Accents 8
Mac OS X TK 27
Requesting Japanese Translation 8

Members online

Forum statistics

Threads
473,755
Messages
2,569,536
Members
45,013
Latest member
KatriceSwa

Latest Threads

Top