Asp Forum - [ANN] RDoc 2.2.0 released

Tony Strauss

9/19/2008 11:38:00 PM

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

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

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.
--
Posted via http://www.ruby-....

19 Answers

Tony Strauss

9/19/2008 11:43:00 PM

The formatting of the change list got messed up a little. The changes
also can be seen here:
http://rdoc.rubyforge.org/files/Histor...
--
Posted via http://www.ruby-....

James Gray

9/20/2008 1:33:00 AM

On Sep 19, 2008, at 6:38 PM, Tony Strauss wrote:

> 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

9/20/2008 2:14:00 AM

Hi--

On Sep 19, 7:38=A0pm, Tony Strauss <tony.stra...@designingpatterns.com>
wrote:
> 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=3D4...
id=3D1698

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

Thanks,
T.

Eric Hodel

9/20/2008 7:01:00 AM

On Sep 19, 2008, at 18:32 PM, James Gray wrote:
> On Sep 19, 2008, at 6:38 PM, Tony Strauss wrote:
>> 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?

That's the plan.

Eric Hodel

9/20/2008 7:03:00 AM

On Sep 19, 2008, at 19:14 PM, Trans wrote:
> On Sep 19, 7:38 pm, Tony Strauss <tony.stra...@designingpatterns.com>
> wrote:
>> 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=detail&aid=11671&group_id=426&...

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

9/20/2008 1:44:00 PM

On Sep 20, 3:03=A0am, Eric Hodel <drbr...@segment7.net> wrote:
> On Sep 19, 2008, at 19:14 PM, Trans wrote:
>
> > On Sep 19, 7:38 pm, Tony Strauss <tony.stra...@designingpatterns.com>
> > wrote:
> >> RDoc 2.2.0 now is available!
>
> > The --exclude patch did not make it? Was there something wrong with
> > it?
>
> > =A0http://rubyforge.org/tracker/?func=3Ddetail&aid=3D11671&gro...
26&atid...
>
> 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?

See: http://redmine.ruby-lang.org/issue...

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

Awesome.

T.

matt

9/20/2008 9:16:00 PM

Tony Strauss <tony.strauss@designingpatterns.com> wrote:

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

--
matt neuburg, phd = matt@tidbits.com, http://www.tidbits...
Leopard - http://www.takecontrolbooks.com/leopard-custom...
AppleScript - http://www.amazon.com/gp/product/...
Read TidBITS! It's free and smart. http://www.t...

Tony Strauss

9/21/2008 5:53:00 AM

matt neuburg wrote:
> 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.
--
Posted via http://www.ruby-....

matt

9/21/2008 3:54:00 PM

Tony Strauss <tony.strauss@designingpatterns.com> wrote:

> matt neuburg wrote:
> > 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.

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

(click File in the Classes column)

But it is fixed in 1.8.7:

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

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

--
matt neuburg, phd = matt@tidbits.com, http://www.tidbits...
Leopard - http://www.takecontrolbooks.com/leopard-custom...
AppleScript - http://www.amazon.com/gp/product/...
Read TidBITS! It's free and smart. http://www.t...

James Gray

9/21/2008 5:17:00 PM

On Sep 19, 2008, at 6:38 PM, Tony Strauss wrote:

> 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

comp.lang.ruby

[ANN] RDoc 2.2.0 released

Tony Strauss

Tony Strauss

James Gray

Trans

Eric Hodel

Eric Hodel

Trans

matt

Tony Strauss

matt

James Gray

x Login to ForumsZone