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

[tomas]

On Wed, May 07, 2003 at 10:06:57PM +0100, Neil Jerram wrote:

[...]

> Interesting.  It was my idea to document the whole Guile API in the
> current unified way, covering both C and Scheme together, but I have
> been wondering about whether that was a good decision.  In many cases
> it seems to result in adding a subsection saying "And there are also
> these related C functions and macros ...", which feels unsatisfactory.

There have been good answers to this elsewhere. As long as there is
a (not necessarily exhaustive) good correspondence between C functions
and Guile (with a way to know when to expect what), I'm fine.

[...]

> Specifically, I think we should (**) promote doing as much programming
> as possible in Scheme, and restrict documentation of the C API to the
> parts needed for interfacing Scheme to C code.  (To give a concrete
> example from another thread, I see no need for people to write C code
> that uses scm_internal_catch.)

[...]

> That's what I'm thinking now, anyway.  I think (**) may be quite
> controversial, so that at least needs a lot more discussion first.

To take the other side of the controverse ;-)

There have been comments on this elsewhere already, mentioning
mod-guile. I won't repeat those. What seemed missing to me (or
I was asleep while reading, actually this happens .-)

Embedding Guile in applications like Apache or PostgreSQL[1] poses
some constraints: Guile won't be the only embedded language. Those
applications bring along services for error handling, which you
better use (e.g. aborting a transaction/erroring out in an HTTP
request/response cycle), for consistency. So it might be most
natural to catch errors at the C level. If that is not desirable
from a Guile POV, then there should be at least a ``recommended
canonical way'' (say: a C function calling a Guile wrapper
calling...). And this might be provided as convenience library.
But then, it could be provided in the first place :-)

I'd even go a step further: for the embedded scripting language
to play really nicely in those two cases, it'd be desirable to
be able to adapt the garbage collector to the transaction-based
memory model: much of the memory used just lives for a transaction,
and that's why they allocate memory in `pools', which just disappear
after the transaction is done. But this might be just wishful
thinking...

--------
[1] I'm talking of embedding Guile in the PostgreSQL server, not
    of a libpq interface