Is there a tar.gz that corresponds to
http://www.ruby-doc.org/docs/rdoc/1.9/
which I’m just not seeing?
If not…how can I get my grubby little hands on a download of it, so I
can stop wasting bandwidth and use it locally?
···
–
(-, /\ / / //
I don’t know about a tarball, but you can generate it yourself.
Assuming you have the Ruby source, it’s not hard.
$ cd
$ rdoc
$ doc/index.html
If you’re not happy with the results of that process, it’s worth
mentioning here so any issues can be dealt with.
Cheers,
Gavin
···
On Wednesday, February 18, 2004, 1:59:55 AM, Gavin wrote:
Is there a tar.gz that corresponds to
http://www.ruby-doc.org/docs/rdoc/1.9/
which I’m just not seeing?
If not…how can I get my grubby little hands on a download of it, so I
can stop wasting bandwidth and use it locally?
Gavin Kistner wrote:
Is there a tar.gz that corresponds to
http://www.ruby-doc.org/docs/rdoc/1.9/
which I’m just not seeing?
http://www.ruby-doc.org/downloads/stdlib/
It’s linked from the ruby-doc.org downloads page:
Ruby-Doc.org: Documenting the Ruby Language
under “The 1.8 Standard Library RDoc HTML”
Please note that the version numbers on the archive files refer to the
version of the bundle, not the version of Ruby.
James
Gavin Sinclair wrote:
I don’t know about a tarball, but you can generate it yourself.
Assuming you have the Ruby source, it’s not hard.$ cd
$ rdoc
$ doc/index.htmlIf you’re not happy with the results of that process, it’s worth
mentioning here so any issues can be dealt with.
Oh, excellent 
Building now. OK…here’s a not-happy moment:
After many, many minutes of generating all the code, only at the very
end does rdoc inform me that ‘doc’ already exists, but it doesn’t want
to overwrite, so I have to start over and specify a directory.
Suggestions:
-
Do the check at the beginning?
-
Allow interactive input to let the user type in the name of a
directory here-and-now? -
Cache the parsed information somewhere so a subsequent run doesn’t
have to re-‘compile’ everything?
I’ll let you know if it’s everything I hoped for once this second run is
complete 
Thanks,
···
–
(-, /\ / / //
James Britt wrote:
Is there a tar.gz that corresponds to
http://www.ruby-doc.org/docs/rdoc/1.9/
which I’m just not seeing?
Er, while that’s certainly good stuff, the particular docs I’m looking
for (and building right now per the ‘other’ Gavin’s suggestion) are the
builtin classes, not the standard library. Things like Time and Hash and
Struct and such.
(The similarity of these two concepts has confused me for a moment more
than once in the past.)
···
–
(-, /\ / / //
Gavin Kistner wrote:
After many, many minutes of generating all the code, only at the very
end does rdoc inform me that ‘doc’ already exists, but it doesn’t want
to overwrite, so I have to start over and specify a directory.
Nooooooooooooooooooooooooo!
And the second time I specified a directory in a location that the user
running rdoc didn’t have access to.
Grrrrrrrr…
···
–
(-, /\ / / //
Gavin Kistner wrote:
James Britt wrote:
Er, while that’s certainly good stuff, the particular docs I’m looking
for (and building right now per the ‘other’ Gavin’s suggestion) are the
builtin classes, not the standard library. Things like Time and Hash and
Struct and such.
Um, er, duh.
I ran Rdoc on CVS source. I can tar it, though, and provide a link.
(The similarity of these two concepts has confused me for a moment more
than once in the past.)
Understandable.
James
I guess it’s generally safest to just plonk it in ‘./rdoc’, which you
must be able to access since you (presumably) unpacked the source code
right where you are anyway.
Once it’s there, you can take the risk with other directories.
Good points, though. RDoc should definitely check its output
directory as early as possible.
Gavin
···
On Wednesday, February 18, 2004, 3:20:02 AM, Gavin wrote:
Gavin Kistner wrote:
After many, many minutes of generating all the code, only at the very
end does rdoc inform me that ‘doc’ already exists, but it doesn’t want
to overwrite, so I have to start over and specify a directory.
Nooooooooooooooooooooooooo!
And the second time I specified a directory in a location that the user
running rdoc didn’t have access to.
Grrrrrrrr…
James Britt wrote:
Gavin Kistner wrote:
James Britt wrote:
Er, while that’s certainly good stuff, the particular docs I’m looking
for (and building right now per the ‘other’ Gavin’s suggestion) are
the builtin classes, not the standard library. Things like Time and
Hash and Struct and such.Um, er, duh.
Try here:
But, note one and all, that the preferred way to get these files is to
grab the actual Ruby source and run rdoc.
James
James Britt wrote:
Try here:
Ruby-Doc.org: Documenting the Ruby LanguageBut, note one and all, that the preferred way to get these files is to
grab the actual Ruby source and run rdoc.
And then to go to http://www.rubygarden.org/ruby?OnlineDocumentationIssues
to record any comments you have about the quality of the documentation!
Getting this stuff done is an evolutionary process, which can be sped up
greatly by simple feedback saying “this needs to be done”.
Gavin
James Britt wrote:
Am I missing somewhere in there which has the builtin (aka Core API)
library rdoc? 'cause I don’t see it.
I’m repeatedly failing to find this data on my own. If I do:
rdoc time.c
in the source directory, I get a listing of all of Time’s methods, but
none of the documentation for those methods which is present in:
http://www.ruby-doc.org/docs/rdoc/1.9/classes/Time.html
Indeed, none of the ‘time*’ files that I can find in the source
directory seem to generate such output. (The above url lists time.c and
lib/time.rb as the location files, but rdoc’ing both of those together
doesn’t get me descriptions of the methods.)
In fact…here we go:
The start of
http://www.ruby-doc.org/docs/rdoc/1.9/classes/Time.html#M000185
says:
“Creates a new time object with the value given by …”
But when I search for that phrase in the entire source directory, I get
nothing:
root# grep -r ‘a new time object’ /usr/local/src/ruby-1.8.1/*
root#
So the question remains…where is ruby-doc.org getting its information?
A custom version of the source with all comments included?
Customized files meticulously self-documented?
···
–
(-, /\ / / //
Look in the source file for time.c: can you see comments containing the
documentation in front of the C methods that implement the class’s
public interface? If not, you’re probably looking at an old version of
the source.
Cheers
Dave
···
On Feb 18, 2004, at 8:39, Gavin Kistner wrote:
I’m repeatedly failing to find this data on my own. If I do:
rdoc time.c
in the source directory, I get a listing of all of Time’s methods, but
none of the documentation for those methods which is present in:
http://www.ruby-doc.org/docs/rdoc/1.9/classes/Time.html
That was the case, where ‘old’ is 1.8.1, and not a 1.9 snapshot.
Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
methods of Time now. I’m still fighting to find out what file(s) are
causing rdoc to crash when writing the output) Thanks
While I’ve got you here…is there a way to get rdoc to document
multiple call sequences for a method in a .rb file? I tried mimicking
the style seen in time.c:
/*
- call-seq:
-
Time.at( aTime ) => time -
Time.at( seconds [, microseconds] ) => time
But putting that same sort of code in myfile.rb:
call-seq:
MutableTime.foo( a )
MutableTime.foo( b )
…failed to produce the same results.
···
On Feb 18, 2004, at 8:32 AM, Dave Thomas wrote:
Look in the source file for time.c: can you see comments containing
the documentation in front of the C methods that implement the class’s
public interface? If not, you’re probably looking at an old version of
the source.
Gavin Kistner wrote:
Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
methods of Time now. I’m still fighting to find out what file(s) are
causing rdoc to crash when writing the output) Thanks
Amazingly, I’m still fighting this. Here’s the latest output (using rdoc
from 1.8.1 on the latest snapshot sources):
ruby-snapshot_20040218] root# rdoc --op rdoc *.c *.rb
array.c:
[...]
instruby.rb: .....
mdoc2man.rb: c....
mkconfig.rb:
rubytest.rb:
runruby.rb:
Generating HTML…
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:334:in find_symbol' *** malloc: vm_allocate(size=2147483648) failed (error code=3) *** malloc[1195]: error: Can't allocate region *** malloc: vm_allocate(size=2147483648) failed (error code=3) *** malloc[1195]: error: Can't allocate region : undefined method find_local_symbol’ for #RDoc::AnyMethod:0x3cb118
(NoMethodError)
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1015:in
find_symbol' from /usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:116:in handle_special_CROSSREF’
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:226:in send' from /usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:226:in convert_special’
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:223:in
each_name_of' from /usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/inline.rb:32:in each’
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/inline.rb:32:in
each_name_of' from /usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:223:in convert_special’
… 24 levels…
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1168:in
generate_html' from /usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1092:in generate’
from /usr/local/lib/ruby/1.8/rdoc/rdoc.rb:210:in `document’
from /usr/local/bin/rdoc:63
That was the case, where ‘old’ is 1.8.1, and not a 1.9 snapshot.
Yes, unfortunately 1.8.1 just missed the boat on the core API documentation
front. Still, that means it should be tried and tested in time for
1.8.2.
Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
methods of Time now. I’m still fighting to find out what file(s) are
causing rdoc to crash when writing the output) Thanks
Thanks for the persistence. We need to shake these problems out.
While I’ve got you here…is there a way to get rdoc to document
multiple call sequences for a method in a .rb file? I tried mimicking
the style seen in time.c:
/*
- call-seq:
Time.at( aTime ) => timeTime.at( seconds [, microseconds] ) => time
But putting that same sort of code in myfile.rb:
call-seq:
MutableTime.foo( a )
MutableTime.foo( b )
…failed to produce the same results.
No, it’s a C workaround. RDoc can’t parse an adequate method header
from C code, because default parameters are done indirectly, and maybe
other reasons.
I’d rather all methods look the same in RDoc output, and that the
‘sameness’ be modelled on the way Ruby is parsed. I can see the
benefit in the case of Time.at, above, but…
(OTOH, I’m grateful that RDoc can understand C at all…)
Cheers,
Gavin
···
On Thursday, February 19, 2004, 3:02:29 AM, Gavin wrote:
That was the case, where ‘old’ is 1.8.1, and not a 1.9 snapshot.
The 1.8 branch in CVS has them too.
While I’ve got you here…is there a way to get rdoc to document
multiple call sequences for a method in a .rb file? I tried mimicking
the style seen in time.c:
Not currently. Is that something that would be generally useful?
Cheers
Dave
···
On Feb 18, 2004, at 10:02, Gavin Kistner wrote:
Hmmmm, ugly. I’ll let Dave read the entrails, but I’ll just suggest
that you use the latest RDoc version. Yes, that means building Ruby
all over again, unless you roll your own RDoc installer
There’s been significant work on the software as well as the
documentation since 1.8.1, I believe.
Gavin
···
On Thursday, February 19, 2004, 3:39:56 AM, Gavin wrote:
Gavin Kistner wrote:
Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
methods of Time now. I’m still fighting to find out what file(s) are
causing rdoc to crash when writing the output) Thanks
Amazingly, I’m still fighting this. Here’s the latest output (using rdoc
from 1.8.1 on the latest snapshot sources):
[errors snipped]
I don’t know about the rest of your problems, but the above seem to me
to be an interpreter problem.
In the meantime, you probably don’t want to document the .rb files in
the main ruby directory. Just type
rdoc --op rdoc
and let it work out what to document.
Cheers
Dave
···
On Feb 18, 2004, at 10:39, Gavin Kistner wrote:
ruby-snapshot_20040218] root# rdoc --op rdoc *.c *.rb
array.c: [...] instruby.rb: ..... mdoc2man.rb: c.... mkconfig.rb: rubytest.rb: runruby.rb:Generating HTML…
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:334:in `find_symbol’
*** malloc: vm_allocate(size=2147483648) failed (error code=3)
*** malloc[1195]: error: Can’t allocate region
*** malloc: vm_allocate(size=2147483648) failed (error code=3)
*** malloc[1195]: error: Can’t allocate region
The 1.8 branch in CVS has them too.
Hrm. Not the .gz returned by
http://www.ruby-lang.org/cgi-bin/download-1.8.1.mrb, FWIW
While I’ve got you here…is there a way to get rdoc to document
multiple call sequences for a method in a .rb file? I tried mimicking
the style seen in time.c:Not currently. Is that something that would be generally useful?
Mostly, no
However, for times where a method does all sorts of weird type checking
and variable parameters (notably #new methods that have varied call
methods), yes, I think it would.
For example, I have:
Can be called in one of five ways:
* MutableTime.new( ) – same as #now
* MutableTime.new( someString ) – same as #parse
* MutableTime.new( someSeconds ) – same as #at
* MutableTime.new( year, month, … ) – same as #local
* MutableTime.new( aTimeOrMutableTime ) – creates a new
MutableTime based off of
the supplied Time or MutableTime object
def initialize( dateString_Seconds_Time_orYear = nil , *dateTimePieces )
The comments work reasonably well, but to help avoid confusion I feel
the need to create horrific variable names in the actual method itself.
···
On Feb 18, 2004, at 10:14 AM, Dave Thomas wrote:
On Feb 18, 2004, at 10:02, Gavin Kistner wrote:
–
(-, /\ / / //
Gavin Kistner wrote:
Amazingly, I’m still fighting this. Here’s the latest output (using rdoc
from 1.8.1 on the latest snapshot sources):
For the record, I’m happy to report that getting the latest stable
snapshot, building that, and running the new version of rdoc against
those new sources finally produced the builtins documentation I was
looking for. Yay!
(And as an added bonus, something about the source tree or rdoc
algorithm causes it to process FAR less files, taking <5 minutes, as
opposed to the >20 that it was taking during the failed attempts.)
···
–
(-, /\ / / //