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

[Neil Jerram]

>>>>> "rm" == rm  <address@hidden> writes:

    rm> This is pretty much the position i'm in -- writing C
    rm> extensions for Guile (currently Guile bindings for the neon
    rm> http/WebDAV client library.  Should be out as soon as Tomas
    rm> made my crap working and recovered from RFC shock :) I myself
    rm> (and probably many others) really need more information on the
    rm> C side of Guile. A lot of if not most of my code deals with
    rm> data conversion from Scheme <--> C and verso.  Right now i'm
    rm> looking for _the_ Guile way of converting a SCM real number to
    rm> a C IEEE float (any help?).

I'm afraid I don't know how to do this, but data conversion is
definitely in the set of C API operations that I think should be
documented.

    rm> Even in my very humble attempts in coding i had to build/manipulate
    rm> modules/environments from C. Evaluating user code in a save environment
    rm> is absolutely neccessary as well a catching errors in user-provided
    rm> Scheme code (callbacks, in the case of the neon bindings).

Absolutely, but this is possible and much easier to do from Scheme,
isn't it?

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

    rm> Not enough time to comment on that right now (but i have to 
    rm> admit that i hate it when languages try to be too pedagogic ...)

But it isn't pedagogy just for the sake of it.  I anticipate big
benefits in documentation and elsewhere, e.g. in the management of
updates between releases.

    rm> I thought a lot about this problem recently (unfortunately with no
    rm> clear outcome :-/) 
    rm> Maybe a 3-book approach:

    rm>  - Guile for the scripter (user of an embedded Guile using application
    rm>    who want's to write scripts -- Scheme only).

    rm>  - Guile for the embedder/extender: people like my who write bindings
    rm>    or pplications that use Guile (focus on memory management and
    rm>    data conversion etc.).

    rm>  - Guile hacker: for people working on the Guile core.

Yes, exactly, except that in practice the last of these may never
happen - and that isn't actually so bad, because for core hacking you
will probably need to read the code anyway.  In fact, the best
documentation for core hacking is probably extensive commenting in
difficult areas of the source.

    rm> Just my 0.002$

Thank you!

        Neil