Asp Forum - Re: [ANN] darkfish-rdoc 1.1.5

Eric Hodel

9/26/2008 10:14:00 PM

On Sep 25, 2008, at 23:23 PM, ged@FaerieMUD.org wrote:

> Version 1.1.5 of Darkfish-Rdoc has been released.
>
> Darkfish is a complete frameless replacement for the default HTML
> generator for Rdoc, the API documentation-extraction system for Ruby.

I love you.

From the README:

> Because of the way Rdoc and Rubygems work, there's currently no way
> to make the
> Darkfish generator available to Rdoc from the command line 'rdoc'
> tool if you
> have it installed as a gem, but if you install it as a regular Ruby
> library
> (via 'rake install'), you can do this:
>
> $ rdoc -w 4 -SHN -f darkfish -m README README lib
>
> I'm trying to figure out how to resolve this for the gem.
> Suggestions welcomed.

I've added code to RubyGems itself to help gem authors automatically
pull in extensions, but it'll take another release of RDoc to
implement it.

Would you consider allowing RDoc to replace its current HTML generator
with Darkfish? (I did a cursory review, and it seems nice, I will
need to refactor the Numeric.extend to avoid pollution, though.)

9 Answers

Trans

9/26/2008 11:38:00 PM

On Sep 26, 6:14=A0pm, Eric Hodel <drbr...@segment7.net> wrote:
> On Sep 25, 2008, at 23:23 PM, g...@FaerieMUD.org wrote:
>
> > Version 1.1.5 of Darkfish-Rdoc has been released.
>
> > Darkfish is a complete frameless replacement for the default HTML =A0
> > generator for Rdoc, the API documentation-extraction system for Ruby.
>
> I love you.
>
> =A0From the README:
>
> > Because of the way Rdoc and Rubygems work, there's currently no way =A0
> > to make the
> > Darkfish generator available to Rdoc from the command line 'rdoc' =A0
> > tool if you
> > have it installed as a gem, but if you install it as a regular Ruby =A0
> > library
> > (via 'rake install'), you can do this:
>
> > $ rdoc -w 4 -SHN -f darkfish -m README README lib
>
> > I'm trying to figure out how to resolve this for the gem. =A0
> > Suggestions welcomed.
>
> I've added code to RubyGems itself to help gem authors automatically =A0
> pull in extensions, but it'll take another release of RDoc to =A0
> implement it.
>
> Would you consider allowing RDoc to replace its current HTML generator =
=A0
> with Darkfish? =A0(I did a cursory review, and it seems nice, I will =A0
> need to refactor the Numeric.extend to avoid pollution, though.)

I you do replace it, please keep the old one available under a
different name.

Thanks,
T.

Aria Stewart

9/26/2008 11:53:00 PM

>
> I you do replace it, please keep the old one available under a
> different name.

Pluggable, please!

Aria Stewart
aredridel@nbtsc.org

Eric Hodel

9/27/2008 12:12:00 AM

On Sep 26, 2008, at 16:52, Aria Stewart <aredridel@nbtsc.org> wrote:
>> I you do replace it, please keep the old one available under a
>> different name.
>
> Pluggable, please!

I would package the old one as a gem.

Michael Granger

9/27/2008 4:02:00 AM

On Sep 26, 2008, at 3:14 PM, Eric Hodel wrote:
> On Sep 25, 2008, at 23:23 PM, ged@FaerieMUD.org wrote:
>
>>
> I love you.

Aw, I'm pretty fond of you, too! :)

> From the README:
>
>> Because of the way Rdoc and Rubygems work, there's currently no way
>> to make the
>> Darkfish generator available to Rdoc from the command line 'rdoc'
>> tool if you
>> have it installed as a gem, but if you install it as a regular Ruby
>> library
>> (via 'rake install'), you can do this:
>>
>> $ rdoc -w 4 -SHN -f darkfish -m README README lib
>>
>> I'm trying to figure out how to resolve this for the gem.
>> Suggestions welcomed.
>
> I've added code to RubyGems itself to help gem authors automatically
> pull in extensions, but it'll take another release of RDoc to
> implement it.

Yay!

> Would you consider allowing RDoc to replace its current HTML
> generator with Darkfish? (I did a cursory review, and it seems
> nice, I will need to refactor the Numeric.extend to avoid pollution,
> though.)

Of course! It still generates invalid HTML under a few circumstances I
noticed recently, so I'd like to clean those up, but feel free to use
it however you'd like.

--
Michael Granger <ged@FaerieMUD.org>
Rubymage, Architect, Believer
The FaerieMUD Consortium <http://www.FaerieMU...

hemant

9/27/2008 8:08:00 AM

On Sat, Sep 27, 2008 at 9:32 AM, Michael Granger <ged@faeriemud.org> wrote:
> On Sep 26, 2008, at 3:14 PM, Eric Hodel wrote:
>>
>> On Sep 25, 2008, at 23:23 PM, ged@FaerieMUD.org wrote:
>>
>>>
>> I love you.
>
> Aw, I'm pretty fond of you, too! :)
>
>> From the README:
>>
>>> Because of the way Rdoc and Rubygems work, there's currently no way to
>>> make the
>>> Darkfish generator available to Rdoc from the command line 'rdoc' tool if
>>> you
>>> have it installed as a gem, but if you install it as a regular Ruby
>>> library
>>> (via 'rake install'), you can do this:
>>>
>>> $ rdoc -w 4 -SHN -f darkfish -m README README lib
>>>
>>> I'm trying to figure out how to resolve this for the gem. Suggestions
>>> welcomed.
>>
>> I've added code to RubyGems itself to help gem authors automatically pull
>> in extensions, but it'll take another release of RDoc to implement it.
>
> Yay!
>
>> Would you consider allowing RDoc to replace its current HTML generator
>> with Darkfish? (I did a cursory review, and it seems nice, I will need to
>> refactor the Numeric.extend to avoid pollution, though.)
>
> Of course! It still generates invalid HTML under a few circumstances I
> noticed recently, so I'd like to clean those up, but feel free to use it
> however you'd like.
>

Few small suggestions:

1. Shouldn't that search box go on the top, rather than at the bottom?
2. I would really love different image/icon for public class methods
and public instance methods, if you would agree.

Gregory Brown

9/27/2008 7:09:00 PM

On Fri, Sep 26, 2008 at 8:12 PM, Segment 7 <drbrain@segment7.net> wrote:
> On Sep 26, 2008, at 16:52, Aria Stewart <aredridel@nbtsc.org> wrote:
>>>
>>> I you do replace it, please keep the old one available under a
>>> different name.
>>
>> Pluggable, please!
>
> I would package the old one as a gem.

Do it!

--
Technical Blaag at: http://blog.majesticseacr... | Non-tech
stuff at: http://metametta.bl...

Trans

9/27/2008 7:47:00 PM

On Sep 27, 3:08=A0pm, "Gregory Brown" <gregory.t.br...@gmail.com> wrote:
> On Fri, Sep 26, 2008 at 8:12 PM, Segment 7 <drbr...@segment7.net> wrote:
> > On Sep 26, 2008, at 16:52, Aria Stewart <aredri...@nbtsc.org> wrote:
>
> >>> I you do replace it, please keep the old one available under a
> >>> different name.
>
> >> Pluggable, please!
>
> > I would package the old one as a gem.
>
> Do it!

Why another gem? What's wrong with with having a few choices built-in?

T.

Eric Hodel

9/27/2008 8:29:00 PM

On Sep 27, 2008, at 12:47, Trans <transfire@gmail.com> wrote:

> On Sep 27, 3:08 pm, "Gregory Brown" <gregory.t.br...@gmail.com> wrote:
>> On Fri, Sep 26, 2008 at 8:12 PM, Segment 7 <drbr...@segment7.net>
>> wrote:
>>> On Sep 26, 2008, at 16:52, Aria Stewart <aredri...@nbtsc.org> wrote:
>>
>>>>> I you do replace it, please keep the old one available under a
>>>>> different name.
>>
>>>> Pluggable, please!
>>
>>> I would package the old one as a gem.
>>
>> Do it!
>
> Why another gem? What's wrong with with having a few choices built-in?

Choice for users means maintenance burden for maintainers. I would
like RDoc to get smaller, not bigger. By moving the current HTML
generator out of RDoc I can push the support burden to people who want
to live in the past. (The HTML generator could use a giant
refactoring, but that would break backwards compatibility, and there's
still the XML generator to maintain. Since Darkfish sits on top of the
XML generator there is less code, less maintenance and a superior
template to serve as an example for others.)

If 10% of users use a feature I really want to remove it so the people
who find it important can maintain it. Everyone can get better support
this way, as they are working on what they are passionate about.

Trans

9/27/2008 11:38:00 PM

On Sep 27, 4:28=A0pm, Eric Hodel <drbr...@segment7.net> wrote:
> On Sep 27, 2008, at 12:47, Trans <transf...@gmail.com> wrote:
>
> > On Sep 27, 3:08 pm, "Gregory Brown" <gregory.t.br...@gmail.com> wrote:
> >> On Fri, Sep 26, 2008 at 8:12 PM, Segment 7 <drbr...@segment7.net> =A0
> >> wrote:
> >>> On Sep 26, 2008, at 16:52, Aria Stewart <aredri...@nbtsc.org> wrote:
>
> >>>>> I you do replace it, please keep the old one available under a
> >>>>> different name.
>
> >>>> Pluggable, please!
>
> >>> I would package the old one as a gem.
>
> >> Do it!
>
> > Why another gem? What's wrong with with having a few choices built-in?
>
> Choice for users means maintenance burden for maintainers. I would =A0
> like RDoc to get smaller, not bigger. By moving the current HTML =A0
> generator out of RDoc I can push the support burden to people who want =
=A0
> to live in the past. =A0(The HTML generator could use a giant =A0
> refactoring, but that would break backwards compatibility, and there's =
=A0
> still the XML generator to maintain. Since Darkfish sits on top of the =
=A0
> XML generator there is less code, less maintenance and a superior =A0
> template to serve as an example for others.)
>
> If 10% of users use a feature I really want to remove it so the people =
=A0
> who find it important can maintain it. Everyone can get better support =
=A0
> this way, as they are working on what they are passionate about.

In that case you may as well toss it. No one will maintain it.

T.

comp.lang.ruby

Re: [ANN] darkfish-rdoc 1.1.5

Eric Hodel

Trans

Aria Stewart

Eric Hodel

Michael Granger

hemant

Gregory Brown

Trans

Eric Hodel

Trans

x Login to ForumsZone