Better RDoc
Trans
now is a documentation tool better than RDoc (perhaps just improve
RDoc itself, but I suspect at this point it would be better to make a
fresh start).
RDoc has a number of weakness we can discuss, but the main thing that
is suffers (IMO) is trying to do double duty as an api index and a
reference manual at the same time. I think ri generation should be
split off as a separate tool. RI docs are great for api index, and
with a little love on the front-end RI browsing is usable via the
Console, Gnome, Fox, and even the Web. With RI out of the way, RDoc
can focus on helping developers generate good looking user manuals for
their projects. It would be nice to have html, tex and pdf target
formats, generate TOC and Index pages, be able to group parts of a
project into parts, sections, chapters, and so on, and support easier
customization (probably via eruby, but .css for html format of
course).
A project like this would bring huge benefits to Ruby and Ruby
projects all across the board.
T.
Gregory Brown
>
> I personally feel that the most important tool Ruby could use right
> now is a documentation tool better than RDoc (perhaps just improve
> RDoc itself, but I suspect at this point it would be better to make a
> fresh start).
I agree wholeheartedly, but I still feel like the lack of available
documentation is greater than the lack of quality documentation tools.
I think this would be an *awesome* summer of code project or something
like that, so long as serious efforts were made to plan it properly,
but for something like Ruby Mendicant, I think I'd be more useful for
my writing skills and ability to dive into undocumented code bases
than I would for building a documentation generation system.
I guess my point is that in my day to day work, I've felt the itch of
needing better documentation tools, but never really had an urge to
scratch it. That's why I don't think we'll see this as a candidate
for a project I can work on, but I definitely would back an effort to
do this, perhaps in Summer of Code or another way. It's a big project
that deserves funding, for sure.
-greg