[ANN] rdoc 2.4.0 Released

rdoc version 2.4.0 has been released!

* <Project Page: http://rubyforge.org/projects/rdoc/>
* <Documentation: http://rdoc.rubyforge.org/>

RDoc is an application that produces documentation for one or more Ruby source files. RDoc includes the +rdoc+ and +ri+ tools for generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further API changes beyond what has been made to RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

See RDoc for a description of RDoc's markup and basic use.

Changes:

### 2.4.0 / 2009-02-24

* 9 Minor Enhancements
   * `ri -f html` is now XHTML-happy
   * Clarified RDoc::Markup link syntax. Bug #23517 by Eric Armstrong.
   * Number of threads to parse with is now configurable
   * Darkfish can now use alternate templates from $LOAD_PATH via -T
   * Removed F95 parser in favor of the rdoc-f95 gem
   * Moved HTML and XML generators to unmaintained
     * No gem will be provided as it's too difficult to make them work
     * Removed options --one-file, --style=, --inline-source, --promiscuous,
       --op-name
   * Removed support for --accessor, use regular documentation or
     the method directive instead. See RDoc::Parser::Ruby
   * Removed --ri-system as it is unused by Ruby's makefiles
   * Added method list to index.html

* 6 Bug Fixes
   * nodoc'd classes no longer appear in the index. Bug #23751 by Clifford
     Heath.
   * Fix 1.9 compatibility issues. Bug #23815 by paddor.
   * Darkfish now respects --charset
   * RDoc no longer attempts to be lazy when building HTML. This is a
     workaround. Bug #23893 by Stefano Crocco.
   * RDoc doesn't crash with def (blah).foo() end
   * RDoc doesn't crash with #define functions

* <Project Page: http://rubyforge.org/projects/rdoc/>
* <Documentation: http://rdoc.rubyforge.org/>

Eric Hodel wrote:

* 9 Minor Enhancements

...

  * Removed support for --accessor, use regular documentation or
    the method directive instead. See RDoc::Parser::Ruby

Ok, it's pretty minor and I can live without it, but .... "enhancement"?

Can the :method: directive emulate attr_reader, and really make the output doc look the same as if attr_reader had been used instead of some other class method? Is there a way to display "[R]", and group it with other attrs?

···

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

$ rdoc --version
rdoc 2.4.0
uh-oh! RDoc had a problem:
exit
run with --debug for full backtrace

$rdoc --debug --version
rdoc 2.4.0
exit
/usr/local/lib/ruby/1.8/optparse.rb:731:in `exit'
        /usr/local/lib/ruby/1.8/optparse.rb:731
        /usr/local/lib/ruby/1.8/optparse.rb:1260:in `call'
        /usr/local/lib/ruby/1.8/optparse.rb:1260:in `parse_in_order'
        /usr/local/lib/ruby/1.8/optparse.rb:1247:in `catch'
        /usr/local/lib/ruby/1.8/optparse.rb:1247:in `parse_in_order'
        /usr/local/lib/ruby/1.8/optparse.rb:1241:in `order!'
        /usr/local/lib/ruby/1.8/optparse.rb:1332:in `permute!'
        /usr/local/lib/ruby/1.8/optparse.rb:1353:in `parse!'

/usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/lib/rdoc/options.rb:410:in
`parse'

/usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/lib/rdoc/rdoc.rb:281:in
`document'
        /usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/bin/rdoc:15
        /usr/local/bin/rdoc:19:in `load'
        /usr/local/bin/rdoc:19

···

Eric Hodel <drbrain@segment7.net> wrote:

rdoc version 2.4.0 has been released!

--
matt neuburg, phd = matt@tidbits.com, Matt Neuburg’s Home Page
Leopard - http://www.takecontrolbooks.com/leopard-customizing.html
AppleScript - http://www.amazon.com/gp/product/0596102119
Read TidBITS! It's free and smart. http://www.tidbits.com

One more thing, removing the HTML and XML generators allows RDoc to build HTML output for the ruby 1.8 tree in under 200MB of memory.

···

On Feb 24, 2009, at 22:03, Eric Hodel wrote:

* Moved HTML and XML generators to unmaintained
   * No gem will be provided as it's too difficult to make them work
   * Removed options --one-file, --style=, --inline-source, --promiscuous,
     --op-name

hahaha, awesome!

Fixed.

···

On Feb 25, 2009, at 07:54, matt neuburg wrote:

Eric Hodel <drbrain@segment7.net> wrote:

rdoc version 2.4.0 has been released!

$ rdoc --version
rdoc 2.4.0
uh-oh! RDoc had a problem:
exit
run with --debug for full backtrace

Eric Hodel wrote:

* 9 Minor Enhancements

...

* Removed support for --accessor, use regular documentation or
   the method directive instead. See RDoc::Parser::Ruby

Ok, it's pretty minor and I can live without it, but .... "enhancement"?

I usually find deleting code is an enhancement :slight_smile:

Can the :method: directive emulate attr_reader, and really make the output doc look the same as if attr_reader had been used instead of some other class method? Is there a way to display "[R]", and group it with other attrs?

No.

I'm very strongly considering merging the attr-defined methods with regular methods. Present your counter-argument here.

···

On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:

Eric Hodel wrote:

Can the :method: directive emulate attr_reader, and really make the output doc look the same as if attr_reader had been used instead of some other class method? Is there a way to display "[R]", and group it with other attrs?

No.

I'm very strongly considering merging the attr-defined methods with regular methods. Present your counter-argument here.

Treating attrs the same as other methods does make sense in light of the uniform access principle, but practically speaking it seems a bit severe. Libraries like fxruby use the attribute section extensively, and it is useful because the methods that appear there not only have more of the attr-nature, but also are based on C++ public data members. It's a helpful bridge back to the Fox world. Plus, it gives you a way to scan the rdocs to see (i) what dials and switches can be adjusted on an object ([W] and [RW]), and (ii) what constitutes the visible state of the object ([R] and [RW]).

I guess :section: is a solution to this, but it will mean some work for library maintainers, and :section: is not widely used. I have 221 gems installed, and :section: appears only in rdoc, rubygems-update, and one file in merb. I do use :section: extensively in my own rdocs. How long will it take for all of the doc maintainers to respond to this change?

···

On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

Eric Hodel wrote:

Can the :method: directive emulate attr_reader, and really make the output doc look the same as if attr_reader had been used instead of some other class method? Is there a way to display "[R]", and group it with other attrs?

No.
I'm very strongly considering merging the attr-defined methods with regular methods. Present your counter-argument here.

Treating attrs the same as other methods does make sense in light of the uniform access principle, but practically speaking it seems a bit severe.

Yes, I was worried it would be too severe. In terms of an API for documentation generation it's easy to work provide uniform access.

Libraries like fxruby use the attribute section extensively, and it is useful because the methods that appear there not only have more of the attr-nature, but also are based on C++ public data members. It's a helpful bridge back to the Fox world. Plus, it gives you a way to scan the rdocs to see (i) what dials and switches can be adjusted on an object ([W] and [RW]), and (ii) what constitutes the visible state of the object ([R] and [RW]).

Would adding a :attr: directive be an acceptable alternative? This would allow the documentation to be rendered as intended without a command line flag.

···

On Feb 25, 2009, at 09:32, Joel VanderWerf wrote:

On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:

Eric Hodel wrote:

Would adding a :attr: directive be an acceptable alternative? This would allow the documentation to be rendered as intended without a command line flag.

The effect of the :attr: directive would be that any invocation of the specified class method was to be treated as an attr? Could a tag ("R" etc.) be specified along with the class method? And would the new rdoc still automatically recognize "attr_*" as attrs, without the explicit directive? Sounds great to me, but it would be good to hear from more library maintainers.

···

--
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

Eric Hodel wrote:

Would adding a :attr: directive be an acceptable alternative? This would allow the documentation to be rendered as intended without a command line flag.

The effect of the :attr: directive would be that any invocation of the specified class method was to be treated as an attr? Could a tag ("R" etc.) be specified along with the class method?

Yes, I think:

# :attr_reader: method_name

will be clearer than having R/W/RW in case the attr isn't visible to RDoc for some reason.

And would the new rdoc still automatically recognize "attr_*" as attrs, without the explicit directive? Sounds great to me, but it would be good to hear from more library maintainers.

Yes.

···

On Feb 25, 2009, at 11:17, Joel VanderWerf wrote: