> > Markus and I are working on rubydoc which is now able to
> > automatically document the API and interface for libxml according
> > to the rubydoc DTD. ...
> [...]
> > With libxslt, I'm working on the rubydoc CLI that will merge in
> > hand written documentation (from an inline source or from an
> > external rubydoc XML file) with the auto-generated document to
> > form a > complete map of the source, regardless of whether or not
> > it is C module or written in Ruby.
> 
> Perl has ONE documentation format, POD. It's old, it's ugly, and
> it's a sumbitch to do anything "nice" with, but bedamned it WORKS.

Works, sure, but it's ugly... and on the scale of ugly as in it's
fugly ugly.  *pukes and puts bag over POD's head*

> Ruby, on the other hand, has two going on three different formats,
> if I'm understanding what Sean is saying correctly.

Sadly yes...  however there is a saving grace with rubydoc, it's
standard is XML and the other utilities export XML... which means that
anyone can write a stylesheet that'll convert rdoc->rubydoc or
rd->rubydoc.  These stylesheets will be included in the base rubydoc
installation.

> None of which, by the way, appear to be compatible. Right now, if I
> want documentation for a package, I have to keep rd2 and rdoc
> handy. I'd probably have to keep rubydoc's CLI handy, too, but it's
> currently vapour. I settled on rdoc for my personal documentation
> efforts because it Just Works.

rdoc's great and I actually plan on using it for embedded
documentation.  I have no interest in recreating the work of Dave,
only extending it and making things more generic and rubynet friendly
(wherein users can submit comments/patches, code, etc on either
rubynet.org or rubydoc.org and have the latest doc included on
download or available via a ruby(doc|net) --update [module] command).

> Similarly, there are no fewer than four packaging/installation
> systems available or soon to be available: RubyGems, setup.rb, rpkg,
> and (again, currently vapourous) rubynet.

:-/ Working on stuff by yourself and being in a perpetual state of
over commitment and everywhere-all-at-once kinda bites when you're
trying to design something "right" and aren't hacking it together.
Help wanted/appreciated.

> It supports -- at least experimentally and I haven't been able to
> get it to work yet -- automatic diagram creation.

Speaking of, does ruby have a DOT interface?  I've wanted to use this
for class diagramming on rubynet but haven't looked into it.

> else. Want to create PDFs instead of HTML files? Write the
> appropriate generator and/or template.

The joy of XSLT and flow objects.

> BTW, with respect to rubynet itself, I don't like the dot files. Why
> not use an XML file format or YAML, if you want something
> lighter-weight (I'm partial to YAML's simplicity, even though I'm
> happily using REXML for an application that I've written locally).

I'm not a yaml lover, personally.  Culturally I think YAML exists as
a counter movement to Java/XML and XMLs tendency to get bundled with
Java.  I can't say as I disagree with the dislike of the Java/M$
developer sentiment, Sun hasn't done much in the way of innovative
computing in a while and I wish would just curl up and flop.  Tandem
makes better hardware anyway.  :)

Here's the dilly with supporting multiple files and formats: I don't
know what your preference is.  Contrary to my sentiment about YAML,
I'll likely support a YAML interface for configuring packages just
because that's a format that some developers prefer.  I personally
favor having simple and small files each with a specific format.
Makes it easier to manipulate/create the files with sed(1) and
find(1).  I'm a die hard UNIX guy at heart, what can I say.  It
showing?

> IMO, there should be ONE file that describes a given project -- and
> it's up to the rubynet server(s) to parse that file into the
> appropriate meta-data. (Think PAD for Windows shareware or DIZ or
> even RSS for that matter.)

By the time the data hits the rubynet server, the data will be
serialized into an XML file.  The dot files are used only by an author
for describing their package, not for use in the rubynet system.  Once
things hit the rubynet system, it's XML.  Period.  For those that are
curious, binary data is MIME64 encoded in an element in the rubynet
file.

Think of rubynet as FreeBSD's ports + tar + CPAN.

http://lists.rubynet.org/lists/listinfo/rubynet-devel

-sc

-- 
Sean Chittenden