Re: RDoc not ignoring sections of file

Gavin Sinclair wrote:

> On Thursday, March 11, 2004, 12:38:02 AM, jbritt wrote:
>>Dave Thomas, the creator/maintainer of RDoc, is not (to my knowledge) a
>>member of the ruby-doc list.  You might do well to post to either 
>>ruby-talk or ruby-core.
> 
> 
> That's good practical advice for reporting an actual problem, but I
> think it's good to run RDoc-related issues by here as well, for a
> couple of reasons.
> 
> Firstly, more often than not it's a matter of the user not being sure
> how to accomplish something.  That can be easily corrected here, and
> the archives will be the richer for it.  Of course the same logic
> applies to other lists as well, but this *is* a documentation-related
> list.

If Ian's rdoc markup has stopped working because he's using a new 
version of Ruby, it's either a bug or a deliberate change in behavior. 
I'm guessing it's a bug, in which case the owner of the code should be told.

If it's a case of improper use or a syntax error, then sure, this list 
is a reasonable place to track such matters (though I'm not sure if 
there are reliable archives anyplace).

> 
> Secondly, Dave is very busy, RDoc is a big project, and the lines of
> reporting are not always clear (sourceforge?, direct mail?, a mailing
> list?).  

Everybody on this list is very busy.  I've seen Dave respond to RDoc/ri 
bug reports on ruby-talk and ruby-core, so I figure they're good 
avenues.  I tend to prefer public discussions of these things so that 
there is a record someplace. (And ruby-talk might be the better choice 
because of Google groups archives and searching.)

> This list can provide a valuable service by being a first
> line of support for RDoc, taking some heat off Dave.  Only a little,
> but the spread of knowledge is valuable, I think.  What do others
> think?

In general, community groups help distribute the work load for FAQs, bug 
reports, coding quandaries, and so on.  I tend to think of ruby-doc as 
being focused first on the creation/organization of documentation, and 
the development of documentation tools as secondary.

> 
> As an aside, I think a great boost for RDoc would be for someone to
> take over maintenance (to whatever extent is appropriate).  That's my
> opinion, not necessarily Dave's.  But Dave takes a "show me the patch"
> attitude to feature suggestions nowadays, so he obviously welcomes
> contributions.

Previous offers to assist with rdoc/ri were met with little enthusiasm.

When Dave has technical concerns or wants input on some design issue he 
tends to go to ruby-core, then ruby-talk.  (Fortunately, a number of the 
ruby-doc folks are also subscribed to ruby-core.)

I'm pretty sure that if anybody in the Ruby community needs help with 
something they know how and where to ask, so I wouldn't worry about the 
RDoc work load.

James