use-syntax / transformer doc bugs

[Andy Wingo]

Some bugs:

scm:eval-transformer was removed in HEAD without a corresponding 
ChangeLog entry in ice-9. This is confusing when digging into history.

The documentation on module transformers and the "system transformer"
is a bit shaky. For one, there doesn't seem to be a system transformer
any more. Second, the purpose of the module transformer isn't well
documented; for example, it's always #f unless syncase is loaded
(afaict). One should note that it is for implementing alternate syntax
packages, notably syncase, but also including language translation. (Is 
that right?)

It's not clear from the docs that what (use-syntax (foo bar)) actually
does is uses the (foo bar) module, then installs the procedure bound to
`bar' as (module-transformer (current-module)). That seems like a bit of
a hack, but whatever. It should be noted that the user should only call
`use-syntax' for a module that actually implements a transformer, not
for modules that just export syntax. Also, it should cross-reference to
the paragraph describing the idea of a syntax transformer.

(And why are #:export and #:export-syntax different if they don't act
differently?)

In guile 1.6.4, (define-module (foo) #:use-syntax (ice-9 syncase)) won't
work because of this in boot-9.scm:1756:

          (case (car kws)
            ((#:use-module #:use-syntax)
             [...]
               (and (eq? (car kws) 'use-syntax)

This is fixed in HEAD, but it would be nice if we could
s/'use-syntax/#:use-syntax/ in the 1.6 branch. Although strictly
speaking it might introduce incompatibilities with existing programs.
You can always get around it with (use-syntax (ice-9 syncase)). It
should be noted somewhere, at least.

Regards,
-- 
Andy Wingo <address@hidden>
http://ambient.2y.net/wingo/