From: Eric Hodel <drbrain@...7.net>
Date: 2008-07-23T07:30:14+09:00
Subject: Re: [ANN] rdoc 2.1.0 Released


On Jul 22, 2008, at 02:56 AM, Marcin Raczkowski wrote:

> Eric Hodel wrote:
>> On Jul 21, 2008, at 14:05 PM, Marcin Raczkowski wrote:
>>> I started playing with new release and frameless template doesn't  
>>> work.
>>>
>>> simply adding FRAMELESS = trye to main html template causes  
>>> following error:
>>>
>>> I'm trying to find a source of the problem, but i'm not sure if  
>>> i'll be able to.
>>>
>>> otherwise great job :)
>> Yeah, I didn't finish frameless, since it got hard/boring and I  
>> didn't want to sit on other good stuff.
> Then why release broken?

Due to the many other improvements.  Remember:

>>>> 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 the RDoc 1.0.1.  Command- 
>>>> line tools
>>>> are largely unaffected, but internal APIs may shift rapidly.

RDoc contains many pieces that interact in a tightly coupled manner.   
Making changes in one area usually leads to some breakages in another  
area.  There are also almost no tests for RDoc, so I made some  
sacrifices for a net improvement.  For example:

> $ ri Hash#map
> ---------------------------------------------------------  
> Enumerable#map
>      enum.collect {| obj | block }  => array
>      enum.map     {| obj | block }  => array
> ------------------------------------------------------------------------
>      Returns a new array with the results of running block once for
>      every element in enum.
>
>         (1..4).collect {|i| i*i }   #=> [1, 4, 9, 16]
>         (1..4).collect { "cat"  }   #=> ["cat", "cat", "cat", "cat"]
> $

I think this is a rather wonderful feature, and people will care more  
about it than about broken templates.

If you don't like the things I've broken (and will continue to break)  
while I develop RDoc 2.x into a fine-tuned machine, you can stay with  
RDoc 1.0.1 that is bundled with ruby 1.8.

(In fact, I broke the templates in RDoc 2.0.  They're mostly fixed now.)

> And why didn't you at least add it to notes that this feature is  
> broken and if you have frameless template don't install it?

I can't see where I mentioned it in the release notes at all.  Because  
you have extra curiosity, you found it :)

> anyway i sent patch that fixes frameless, took me around 30 mins, it  
> uses "README" as default and if it isn't find provides helpfull info.
>
> I hope you find it usefull.

Yes, I am going to apply it.