Re: Doc organization (Re: Around again, and docs lead role)

[Bill Schottstaedt]

> I still contend, though, that if the Guile docs had been clearer, more
> complete and more "canonical" when you started writing Snd (or perhaps
> adding Guile to Snd), you might naturally have written more of Snd in
> Scheme and therefore created a more extensible, maintainable and
> generally hackable program.  What do you think?

My original intention was to write the whole thing in Common Lisp (it's
part of a package of CL programs developed over the last 30 years or so),
but I didn't trust any of the CL-based GUI libraries, and didn't like
tcl, so (this being the mid-90's on an SGI), I opted for C/Motif (and
later added Gtk).  Craig Borezsky told me about Guile; this was before
version 1.3.4 -- Jim Blandy was the head of the group, and I liked the
way he thought (I must say I miss his influence...).  The code was
the documentation, so I followed my nose.  It's too late now to
invert the entire Snd program (it's currently about 220000 lines of
C and 75000 lines of Scheme), and I don't think it's needed anyway.

My take on Guile (which seems to me to have stalled out over the last
few years) is that the current developers think of it as an extended
shell-based interpreter, whereas I think of it as a way of extending a
C program -- I can't see any moral choice here.  So it's a "vision
thing" -- if I had time, I'd think about things like ratios, C-level
continuations (these almost work already), error handling cleanups
(Guile itself should never call exit or abort as a response to an
error -- this is a serious bug!), some nice way to reach into the
current scheme environment and pluck out scheme-level stuff (there's
code for this in Snd's snd-run.c which works for nearly every case
(not define* args), but it's not very pretty, and I wrote it only by
laboriously working through all the kinds of environments I could
find), an optimizer (snd-run.c easily beats Guile by factors of 10 or
20), etc.

>    Bill> -- the tricky part is good error handling which Guile flubs
>    Bill> miserably anyway).
>
> It does?  Can you give more details here?

It's a long story.  Here's a short portion: if you try to piggy-back
on the built-in error types, you are at the mercy of silly problems
like the fact that simple_format exits if it gets an extra argument!
And the error output is ugly.  And it's hard to redirect it or add
info -- and I'm still not sure about backtraces.

> I think that one of Guile's current problems is managing API changes
>  between releases.  If we can reasonably shrink the official API, it
>  makes the problem easier.

Agreed, but I think this can be done without removing functionality.
(This problem was the reason for the "xen" macros -- I almost never
call any scm/gh thing directly -- once written, however, it made it
easy to add Ruby).  I complained earlier about the API changes only in the
context of a heated exchange about scm_num2int, which I still think
is broken.

> I don't follow this.  What is wrong with the following?
>
> In C:
>   scm_call_1 (scm_c_lookup ("my-func"), str);
> In Scheme:
>   (define (my-func str)
>     (catch #t

Leaving aside questions of speed and simplicity?  (Snd is a sound
editor which means I'm dealing with gobs of data -- no time to go
through all the leisurely consing and unboxing and name lookups and
whatnot that Scheme indulges in -- speed is essential in this
context).  But, I guess the basic problem is that I already have what
I want in C, and I want a way to make it available programmatically at
"run time"; I thought that was the whole idea of Guile.  There are
already plenty of scripting languages and Scheme interpreters.

> Thanks for your input.  (And please don't worry - everything I've said
> is only suggestions - there are no plans to implement any of it yet
> (if ever).)

And I apologize for the loaded word "subvert" -- as soon as I clicked
"send" I wished I had used "change" or something.

If only I had the time, I'd write something about how I'm using
Guile (there's a section in Snd's grfsnd.html, but it's only
a tiny start) -- I think Guile is a great start on a C extension
library.