[ANN] RDoc 2.2.0 released

[Tony Strauss]

RDoc 2.2.0 now is available!

This version essentially aims to fix a number of bugs and to provide
some small enhancements. I've highlighted a few cool things about the
release in a blog post at
http://blogs.designingpatterns.com/urban-jungle/2008/09/19/rdoc-220-released/

Documentation: http://rdoc.rubyforge.org
Project Page (and download): http://rubyforge.org/projects/rdoc

This is the full change list:
=== 2.2.0 / 2008-09-19
This version includes some significant enhancements to ri. See RI.txt
for
documentation about ri.

* 5 Major Enhancements
* More extensive unit tests (special thanks to Chris Lowis for
contributing
a test).
* Made ri twice as fast for the most common use case of displaying
information for a class or a fully-qualified method
(i.e., ri Array#flatten, after ri has created a cache the first time
that
it runs).
* Made ri many times faster when searching for an unqualified method
(i.e.,
ri read, again after the first such search has populated ri's cache)
* Changed ri to do regular expression searches for unqualified
methods;
now, a regular expression for a method can be passed to ri on the
command-line.
* Added an interactive mode to ri (patch by Daniel Choi). Now, when
ri
is given a -i argument, it will allow the user to disambiguate
unqualified methods if more than one is present and also will allow
a
user to get information for a class' method.

* 8 Minor Enhancements
* RDoc now adds the package title to the web pages that it generates
for files and classes/modules, which helps them appear better in
search engine results.
* RDoc now automatically generates cross-reference links for classes
and
methods specified relative to the global namespace (i.e.,
::A::B::C#method).
* All built-in templates now output valid, strict XHTML.
* The documentation is slightly better organized (the markup details
were
merged into the RDoc module's documentation).
* Improved rdoc's HTML generation speed by about 20% (on Windows, the
boost seems larger).
* Provided an ri command-line option to control its caching behavior.
* Improved RDoc's documentation. Added RI.txt to document ri.
* Allow HTML templates distributed as gems to be loaded with the -T
option,
just like the standard templates in rdoc/generator/html (so an HTML
template lib/new_template.rb in a gem can be used with rdoc -T
new_template)

* 25 Bug fixes:
* Fixed prototype detection in C parser. Can process ruby 1.8 C files
again.
* Fixed the main page for frameless template. Patch by Marcin
Raczkowski.
* Fixed the main page for frame templates. Now, if no main page is
specified, RDoc will default to the README.
* Fixed missing stylesheet in generated chm. Patch by Gordon
Thiesfeld.
* Fixed the parsing of module names starting with '::'. Patch by
Giuseppe Bilotta.
* Fixed a case where RDoc first would encounter Foo::Bar and then
would
encounter class Foo. Previously, RDoc erroneously would have
considered
that both a Foo class and a Foo module existed.
* Fix a clase where RDoc would not generate correct cross-reference
links
to a class contained within a module of the same name (i.e.
RDoc::RDoc)
* Prevented RDoc from trying to parse binary files, which would
produce
garbage output.
* RDoc now correctly converts ' characters to apostrophes, opening
single
quotes, and closing single quotes in most cases (smart single
quotes).
* RDoc now correctly converts " characters to opening double quotes
and
and closing double quotes in most cases (smart double quotes).
* (c) correctly is converted into the copyright symbol.
* '&' characters in text now correctly are translated to HTML
character codes.
* Fixed missing stylesheet in generated chm. Patch by Gordon
Thiesfeld.
* Fixed broken method links in the built-in templates.
* RDoc properly links to files and classes in the one page HTML
template.
* The kilmer and hefss templates properly syntax highlight when
inlining
source code.
* The kilmer and hefss template class pages properly display methods
again.
* Fixed broken class, file, and method links in the frameless
template.
* Fixed the clipping of source code in the html and frameless
templates when
the source code cannot fit into the window; a scrollbar now will
allow
all of the source code to be viewed.
* Fixed the missing constant descriptions in the html and frameless
templates.
* Fixed the ri command-line options that customize the directories to
be
searched for documentation.
* Fixed the XML generator. Patch by Anthony Durity.
* Stopped the XML template from generating invalid XML due to
malformed
embedded ruby.
* Adding missing information about a class' constants to the XML
template.
* Fixed the horizontal rule markup (---) so that it correctly adds a
horizontal rule rather than suppressing all text that follows.

 

[Tony Strauss]

The formatting of the change list got messed up a little. The changes
also can be seen here:
http://rdoc.rubyforge.org/files/History_txt.html

 

[James Gray]

RDoc 2.2.0 now is available!

* 5 Major Enhancements
* More extensive unit tests (special thanks to Chris Lowis for
contributing
a test).
* Made ri twice as fast for the most common use case of displaying
information for a class or a fully-qualified method
(i.e., ri Array#flatten, after ri has created a cache the first
time
that
it runs).
* Made ri many times faster when searching for an unqualified method
(i.e.,
ri read, again after the first such search has populated ri's
cache)
* Changed ri to do regular expression searches for unqualified
methods;
now, a regular expression for a method can be passed to ri on the
command-line.
* Added an interactive mode to ri (patch by Daniel Choi). Now, when
ri
is given a -i argument, it will allow the user to disambiguate
unqualified methods if more than one is present and also will allow
a
user to get information for a class' method.

Wow, this sounds really great. Thanks!

Will this be merged with 1.9 before the feature freeze?

James Edward Gray II

 

[Trans]

Hi--

RDoc 2.2.0 now is available!

The --exclude patch did not make it? Was there something wrong with
it?

http://rubyforge.org/tracker/?func=3Ddetail&aid=3D11671&group_id=3D426&at=
id=3D1698

Also, I recently noted that ri's html output of constants was messed
up. Has that been addressed?

Thanks,
T.

 

[Eric Hodel]

Wow, this sounds really great. Thanks!

Will this be merged with 1.9 before the feature freeze?

That's the plan.

 

[Eric Hodel]

The --exclude patch did not make it? Was there something wrong with
it?

http://rubyforge.org/tracker/?func=detail&aid=11671&group_id=426&atid=1698

There's nothing wrong with it, just an oversight.

Also, I recently noted that ri's html output of constants was messed
up. Has that been addressed?

Example?

If my laptop cooperates, I'll have these both into RDoc for the 1.9.1
feature freeze.

 

[Trans]

26&atid...

There's nothing wrong with it, just an oversight.


Example?

See: http://redmine.ruby-lang.org/issues/show/549

If my laptop cooperates, I'll have these both into RDoc for the 1.9.1 =A0
feature freeze.

Awesome.

T.

 

[matt neuburg]

* Fixed prototype detection in C parser. Can process ruby 1.8 C files
again.

That's great news, because I downloaded the previous version of RDoc and
had it rebuild my ri documentation, because I wanted to obtain the new
yummy inheritance goodness where "ri File#read" was claimed to work at
last - but instead, because I am way back in the past using Ruby 1.8.6,
my documentation was completely mangled and has been lying dead on the
floor ever since.

Now, however, I have regenerated my ri documentation once again with
this new version of RDoc and things seem to be working just fine with
"ri". That's great! It's fast, and the new interactive mode is a great
help.

But there's just one thing. "ri File#read" still doesn't work ("Nothing
known about File.read"). Is this because the 1.8.6 source files are
faulty?

Thx - m.

 

[Tony Strauss]

Now, however, I have regenerated my ri documentation once again with
this new version of RDoc and things seem to be working just fine with
"ri". That's great! It's fast, and the new interactive mode is a great
help.

But there's just one thing. "ri File#read" still doesn't work ("Nothing
known about File.read"). Is this because the 1.8.6 source files are
faulty?

Thx - m.

I think that I'm able to reproduce the symptoms. This occurs for me
because the documentation that came with Ruby 1.8.7 is broken; the YAML
file describing the File class for ri has an empty superclass field.

There does seem to be some kind of bug with rdoc, however, because the
superclass still is missing when I generate ri files from the Ruby
source code with RDoc 2.2.0. I'll investigate why this is happening.

 

[matt neuburg]

I think that I'm able to reproduce the symptoms. This occurs for me
because the documentation that came with Ruby 1.8.7 is broken; the YAML
file describing the File class for ri has an empty superclass field.

Perhaps my focusing on "File" is a bit misleading; I presume that 1.8.6
just has deeper issues of its own, since when you say "ri File" under
1.8.6 what you get is a report on "ftools", not the built-in File class:

http://ruby-doc.org/core/

(click File in the Classes column)

But it is fixed in 1.8.7:

http://ruby-doc.org/core-1.8.7/index.html

There does seem to be some kind of bug with rdoc, however, because the
superclass still is missing when I generate ri files from the Ruby
source code with RDoc 2.2.0. I'll investigate why this is happening.

Cool, thanks so much for looking into this. I meant to report that I'm
not getting superclass information on any classes when I use "ri" (and
this has been true for a couple of versions now, I think). I don't know
what the expected behavior is here, though.

m.

 

[James Gray]

RDoc 2.2.0 now is available!

* 25 Bug fixes:

I found two issues when working with RDoc 2.1.0 yesterday. I haven't
tried the new RDoc but I don't see them listed in your changelog. The
problems I found were:

* RDoc should ignore magic comments as it ignores shebang lines. As
it is now, you have to make sure there's no space between the magic
comment and the file's documentation or RDoc will skip the latter in
favor of the former. Even then, the final output will begin with the
magic comment, which I don't really think is ideal.

* RDoc in correctly rendered the following comment:

# <tt>"\r\n"</tt>, <tt>"\n"</tt>, or <tt>"\r"</tt>

as:

"r\n", "n", or "r"

I will add these issues to RDoc's bug tracker in case that helps.

James Edward Gray II

 

[Eric Hodel]

That's great news, because I downloaded the previous version of RDoc
and
had it rebuild my ri documentation, because I wanted to obtain the new
yummy inheritance goodness where "ri File#read" was claimed to work at
last - but instead, because I am way back in the past using Ruby
1.8.6,
my documentation was completely mangled and has been lying dead on the
floor ever since.

Now, however, I have regenerated my ri documentation once again with
this new version of RDoc and things seem to be working just fine with
"ri". That's great! It's fast, and the new interactive mode is a great
help.

But there's just one thing. "ri File#read" still doesn't work
("Nothing
known about File.read"). Is this because the 1.8.6 source files are
faulty?

No, the source files are fine, since:

$ ruby -ve 'p File.superclass'
ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0]
IO

I will try to track it down again. I know I made it work once!

I will be eternally grateful if somebody can port a C grammar to racc,
regular expressions don't cut it.

 

[George]

I will be eternally grateful if somebody can port a C grammar to racc,
regular expressions don't cut it.

Hi Eric,

Does CAST cut it?

gem install cast

Documentation at http://cast.rubyforge.org/ .

Cheers,
George.

 

[Eric Hodel]

Hi Eric,

Does CAST cut it?

gem install cast

Documentation at http://cast.rubyforge.org/ .

I think it might. I'll keep it in the back of my mind until I have
the time to experiment.

 

[Tony Strauss]

The --exclude patch did not make it? Was there something wrong with
it?

Also, I recently noted that ri's html output of constants was messed
up. Has that been addressed?

RDoc 2.2.1 should fix both issues.

 

[Tony Strauss]

Cool, thanks so much for looking into this. I meant to report that I'm

not getting superclass information on any classes when I use "ri" (and
this has been true for a couple of versions now, I think). I don't know
what the expected behavior is here, though.

I think that we fixed this in RDoc 2.2.1. In order to see the fix,
however, you'll need to rebuild your system's Ruby documentation (again
). Please tell me if it still is broken!

 

[Tony Strauss]

as:

"r\n", "n", or "r"

I will add these issues to RDoc's bug tracker in case that helps.

Thanks! The issues might take a bit of time to fix, as rdoc's markup
engine is due for some refactoring.

 

[matt neuburg]

I think that we fixed this in RDoc 2.2.1. In order to see the fix,
however, you'll need to rebuild your system's Ruby documentation (again

Cool! I had some trouble updating the gem, apparently because rubygems
itself needed updating, but I got it sorted and then followed the
instructions on the blog (thanks for that). Now when I say

ri File#read

I am told about IO#read. Nice!

I am still not being told, as part of ri's output, who is the superclass
of the class I'm inquiring about. But maybe that is not part of what ri
is intended to display? In any case this is a lot better than what I was
seeing before.

Indeed, it would be nice if the list of known classes were hierarchical
(class -> subclass).

One other tiny suggestion. It would be nice, perhaps, if there were a
space after the comma after method names when they are listed. For
example, I'm seeing

...next,next!,oct,original_succ...

But it might be more legible as

...next, next!, oct, original_succ...

m.

 

[Eric Hodel]

Cool! I had some trouble updating the gem, apparently because rubygems
itself needed updating, but I got it sorted and then followed the
instructions on the blog (thanks for that). Now when I say

ri File#read

I am told about IO#read. Nice!

I am still not being told, as part of ri's output, who is the
superclass
of the class I'm inquiring about. But maybe that is not part of what
ri
is intended to display? In any case this is a lot better than what I
was
seeing before.

Indeed, it would be nice if the list of known classes were
hierarchical
(class -> subclass).

One other tiny suggestion. It would be nice, perhaps, if there were a
space after the comma after method names when they are listed. For
example, I'm seeing

...next,next!,oct,original_succ...

But it might be more legible as

...next, next!, oct, original_succ...

Can you file bugs in the tracker? This way they won't be forgotten.

 

[matt neuburg]

Can you file bugs in the tracker? This way they won't be forgotten.

Done. m.