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

On Wed, 23 Oct 2002 14:07:46 +0900, Sean Chittenden wrote:
>> 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*

Yeah, well, I said that. Just not as ... eloquently. It does work
and there's only one standard to deal with.

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

In some ways, though, I still think that this is probably the wrong
approach. IMO, either rdoc or rd needs to die. Ideally, rdoc will
pick up the ability to parse rd comments cleanly (perhaps spitting
out warnings) so that there only needs to be one primary
documentation tool.

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

Okay ... so ... what's the point of rubydoc? IMO, rdoc is quite
sufficient to produce the necessary documentation for the code. Is
rubydoc intended to massage that documentation into a nicer format
that could, theoretically, look good in PDF?

Don't get me wrong -- I'm not overly enamoured of the default rdoc
template, but at the moment I'm just too lazy to change it for my
own purposes and (later) offer it as a replacement template.

I have to be honest and say that I don't *get* why rubydoc *as a
tool* is necessary. If you're going to make it an aggregator so that
the user can have the equivalent of a single interface like users of
the ActiveState Perl package do ... that's cool. If you're going to
make it a super-duper version of ri with Rimport, even better! (See?
I forgot another Ruby documentation tool.) But if it's just going to
be Yet Another Documentation Tool, I've got to say that I don't see
the point.

IMO, rubydoc should be a shell and transformation agent on top of
rdoc, not a whole new documentation system. But that's just IMO.

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

That's not a criticism, Sean. However, I can't at the moment really
provide any assistance with the code side -- job searches tend to
take a lot of time, and I have my own coding projects that I'm
attacking (including a bit of boring I18N work that I'm WAAAAY
behind on, and a Palm OS project that I need to finish so I can
start selling it, but I also need to read more in Applied
Cryptography so I can build a decent software key system that's not
too nasty to deal with). I have joined rubynet-devel, though, so I
can possibly provide some design commentary.

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

Look at rdoc; there's a dot/ directory in the distribution. I'm not
exactly sure the best way to use it -- part of the problem could be
that I use Ruby from Windows, and I don't have dot itself installed
(: As I said above, rdoc should be the documentation system for
Ruby; rubydoc should be a way of transforming rdoc output into ri
database information (a la Rimport), creating a unified API
reference for Ruby and all the modules installed on the user's
system, etc.

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

Certainly -- and this is probably what rubydoc should do. (Of
course, I've now tried rdoc's CHM -- Windows HTMLHelp -- output and
have had mixed results with it. It seems to ignore #:nodoc:
directives; I may look at that to provide a patch for Dave when he
gets back, like another patch that I've made to a patch that he made
in response to a patch that I gave him.)

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

I think that your cultural analysis is correct. I still think that
YAML is a useful lightweight format.

> Here's the dilly with supporting multiple files and formats: I
> don't know what your preference is.

One format, one file. Period. Don't give me the option of multiple
formats and files to describe a single package. I picked YAML
because it appears to be close to the .rubynet_ format that you
specified. Perhaps as follows (note that I use '...' when there
could be other attributes or I'm eliding):

    --- !rubynet.com/rubynet
    - project:
        - name:
        - status:
        - comment:
        - copyright:
        - description:
        - download_name:
        - location:
        - download_urls:
            - ...
        - homepage:
        - licenses:
            - licence: url
        - version:
            - major:
            - minor:
            - micro:
    - authors:
        - author:
            - name: 
            - email:
            - ...:
    - build:
        - append_files:
        - ...:
    - categories:
        - primary:
        - secondary:
            - cat1
            - cat2
    - dependencies:
        - ruby:
            - version:
        - libs:
            - required:
                - ...
            - optional:
                - ...
        - dependency:
            - name:
            - version:
            - version_rule:
            - ...
    - files:
        - doc:
            - package.html
        - site_lib:
            - MyPackage:
                - test.rb

IMO, in a single file, this provides everything that you would have
in the multiple file form -- and it's easier to edit. XML would be
appropriate, too. I'll re-present this on rubynet-devel with further
commentary in a couple of days, but I think that there are mistakes
being made in the design as expressed by the package information
files.

> 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?

As I said before, one format and one file. Too many options or files
will make the project unmaintainable. If you keep the existing
dot-rubynet files, I can guarantee that I won't be packaging things
that way -- it's too much work for me, the maintainer. (Ideally,
even, you would have a cross-platform GUI- or TUI-based interface
for building and maintaining the file.)

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

Blechhhh. base64 encoding is evil unless it's unavoidable. It adds
an unnecessary 30% or more to the size of the file. It also seems
that here, you're planning on mixing metadata and content -- which I
consider a major no-no when it comes to data modeling. Frankly, I
think that this is a task for which XML is uniquely UNSUITED. Sure,
XPath helps here, but XML will *never* match the power of a properly
coded relational database for this sort of problem space.

-austin
-- Austin Ziegler, austin@halostatue.ca on 2002.10.23 at 02.32.37