From: Austin Ziegler <austin@...>
Date: 2002-10-23T13:46:43+09:00
Subject: Ruby.bah! (was Re: XMLParser, NQXML... and also RAA.succ)

On Wed, 23 Oct 2002 13:01:59 +0900, Sean Chittenden wrote:
> 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.

Okay. This hits on perhaps my biggest frustration with Ruby right
now. I *love* this language. It makes sense in a way that I haven't
really found any other language to make sense ... BUT!

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.

Ruby, on the other hand, has two going on three different formats,
if I'm understanding what Sean is saying correctly. 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.

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. I'm sure I've missed one
or two. What I've settled on is a variant of what Dave includes with
rdoc, that might be one of the two variants included with setup.rb
-- but I'm not quite sure.

As to multiples of other functionality providers, I don't have as
much of an issue, except for the database libraries.[1] But
packaging/installation systems and documentation systems are
fundamentals. rd and rd2 are too limited? Fine. The same cannot be
said of rdoc. rdoc even understands other languages (including
Fortran95?!?!) so that documentation can be embedded in those
languages and produced cleanly. It supports -- at least
experimentally and I haven't been able to get it to work yet --
automatic diagram creation. Dave is quite responsive to suggestions,
and rdoc comments are very readable in and of themselves without
being formatted as HTML or anything else. Want to create PDFs
instead of HTML files? Write the appropriate generator and/or
template.

I'm *still* baffled as to why I should choose any particular
package/installation getup. Perl has, for the most part,
standardized on 'perl Make' or something like that which creates a
makefile which may or may not use autoconf as necessary. Of course,
this part gets into another issue that may be unique only to the
Windows port because there's such a variety of compilers, but it
would be nice if the setup tools for extensions requiring
compile-time efforts could be made to recognise that the local
compiler may not be the same as the package provider's compiler --
the same with the build directory (Andy's build directory begins on
drive t:, did anyone notice? (:

Yes, something better than the current RAA with its link-only form
is needed. Yes, rubynet might be a good choice for defining such a
concept. I also think that Simon Cozens might be right that we might
also be best off starting from CPAN and search.cpan and slowly but
surely rubyfying so that we have a proper CRAN/rubynet/whatEVER!

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).
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.)

-austin
[1] Perl standardized on DBI a while back, and I think that all of
    the various database libraries should merge in with Ruby's DBI
    effort so that there's a single database interface. It's too
    messy to make portable code, otherwise.
-- Austin Ziegler, austin@halostatue.ca on 2002.10.23 at 00.45.43