guile-lib things

[Andy Wingo]

Hey folks,

Some thoughts about guile-lib. If you're not interested,
(++! current-message). However, if you've written something for which
you'd like wide distribution, read on to see what the atmosphere is
around guile-lib distribution.

        First things first: guile-lib needs a mailing list (perhaps 2:
        -announce and -devel), a proper web page, and some documentation
        as to _where exactly is the canonical arch archive_, and where
        the tarballs are. Input from the smart folks on guile-* is
        useful, but let's not clutter up their inboxes.

Some of this is rambling...

I've been integrating some code from other people into guile-lib. It's
tricky. The conflict is the coherence of guile-lib versus the coherence
of the upstream code itself. If the package is being currently
maintained, such as SSAX, you can't really change much, because
otherwise maintainance will be a nightmare, and the authors might call
your version heretical or something. However, you can't *not* modify at
all, because you at least have to add module headers and exports.

Furthermore, if the original author provides a module name, you might
want the name to be different, so that it fits in with guile-lib[0]. To
a lesser degree, if the name of the upstream source file sucks, you
might want to change it. Then of course it needs a copyright block, and
an arch id, then you might want to give it a proper commentary, then you
might want to give the functions docstrings[1] instead of preceding
comments, and factor out the tests into a guile-lib testsuite, and then
rename some functions...

Of course we won't rename functions that belong to a package, though. We
have to do something to ensure the integrity of guile-lib, but we can't
violate the integrity of a package. For example, there is a function in
one SXML module, SRV:send-reply. The naming is ridiculous: there is no
SRV package, and all the function does is traverse a tree, printing out
the leaves (and executing thunks). But we can't change it, because it's
in a bunch of upstream docs, and users acquainted with the package would
be a bit confused. 

Besides that, the main conflict I feel is the integrity of the package
versus having a guile-lib that is self-documenting. If comments are in a
commentary block, they are much more useful[2]. Furthermore, if they are
marked up as texinfo, they can be processed into other forms (eg html,
plain text) via the (sxml texinfo ...) modules. However, transforming
the documentation within a module's comments into this form is a lot of
tedious work that ultimately isn't maintainable.

I wanted to lay these conflicts out on the table, so that the choices we
make as distributors/packagers/coders are more coherent (that word
again!), and so that we can discuss them. Perhaps they are indicative of
the fundamental problem of guile-lib: it's centralized. Compared to
something like asdf or CPAN, we're doing too much work. But then unlike
CL or Perl, Scheme doesn't have a standard module system. Thoughts on
how to decentralize, or the merits of decentralization, are certainly
welcome.

Well, that's it for my ramble! Keep hackin, folks.

Wingo.

[0] At one point, I wanted strictly taxonomic names for the modules. I 
    was wrong: code doesn't behave taxonomically, it behaves in a 
    certain quirky way depending on who wrote it / what package it comes
    from. So while you might classify _packages_ a certain way, the 
    code often deserves to be classified under the package name itself.
    I'm thinking of (sxml htmlprag) here.

[1] guile-1.6 doesn't "notice" docstrings at all when memoizing. 1.7 
    does, but keeps them in the memoized output still -- we need to put
    them in (object-documentation foo) if docs are present, and elide 
    them from the memoized output. Thus, at present, docstrings impose
    a performance penalty. A FIXME indeed!

[2] These docs are completely generated[3]:
    http://ambient.2y.net/wingo/software/guile-lib/

[3] http://ambient.2y.net/wingo/software/guile-lib/index.scm
-- 
Andy Wingo <address@hidden>