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

[tomas]

On Sat, May 10, 2003 at 01:01:44PM +0100, Neil Jerram wrote:
> >>>>> "tomas" == tomas  <address@hidden> writes:

[...]

> Not sure I understand.  Are you saying that the relationship between
> how one codes a primitive in C, and how one calls it in Scheme, should
> be clearly described?  If so, I agree.

Uh, sorry for my unclear wording. I meant to say that I don't see the need
for repetition as long as there is a way to guess the C name and usage from
the Scheme counterpart -- just document the exceptions. OTOH, having separate
docs for C and Scheme would be OK; I guess the transformation might be
script-supported.

>     >> That's what I'm thinking now, anyway.  I think (**) may be quite
>     >> controversial, so that at least needs a lot more discussion first.
> 
>     tomas> To take the other side of the controverse ;-)

[...]

> With ``recommended canonical way'' you've hit the nail on the head as
> far as I'm concerned.  The main point of my whole argument is that
> there are currently no recommended ways of using Guile, and that makes
> it (i) jolly difficult to document - especially for more inexperienced
> developers (ii) difficult to clearly define the API and so manage API
> changes between releases.

Yup. (In a way, it seems to be a fundamental Scheme characteristic,
do-it-yourself everywhere ;-)

> To consider your example ...  Although it might be most immediately
> natural to catch and dispatch errors at the C level, I would recommend
> a ``canonical'' organization like this: (I'm assuming here that the
> basic operation of mod_guile is to translate a mod_guile HTML page
> into vanilla HTML)
> 
> - Define primitives that wrap the applications' mechanisms for
>   reporting errors.  Now you can signal those errors from Scheme.
> 
> - Define a Scheme procedure that does the whole translation operation:
> 
>   (translate-page INPUT) -> OUTPUT
> 
>   This procedure can signal application errors as/when it needs to.
> 
> - From C, just call out to translate-page, and return its result to
>   Apache.
> 
> This may be a bit harder to begin with than writing everything in C.
> But once this structure is in place, your scope for rapidly adding
> further enhancements is much greater, because all the interesting code
> is in Scheme, not C.

Hmmm. There is more to an Apache module than just generating a HTML page.
(And actually, it's this ``more'' which really makes a module worthwile
wrt a CGI scripts, besides performance, that is):

As a request traverses different stages of processing within the web
server, it calls specialized hooks within the module, so the module
can handle authentication, path resolving and what not.

Now imagine I could catch script errors from within the C caller:
I could install a simple error handler in C to deliver the proper
error code to the client browser -- independently of my scripting
language.

[pooled/transaction oriented memory allocation model]

> Sounds interesting, and maybe not too hard.  Is the following
> possible?
> 
>     (let ((temp-heap (switch-to-new-heap)))
>       ; This tell Guile's memory allocator to allocate a new heap
>       ; and to make all memory allocations until further notice
>       ; from this heap.
> 
>       (do-transaction-processing)
>       ; During which all memory allocations come from the new heap.
> 
>       (gc-and-destroy-heap temp-heap)
>       ; Perform a GC, assert that temp-heap now has nothing in use,
>       ; destroy temp-heap and switch back to previous heap.
>       )

Wow, this is very tempting :-)

Regards
-- tomas