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

[Neil Jerram]

>>>>> "Rob" == Rob Browning <address@hidden> writes:

    Rob> Neil Jerram <address@hidden> writes:
    >> 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.)

    Rob> I'm not sure how commonly this is an issue, but how hard
    Rob> would this be on people who are just writing C code (say
    Rob> perhaps for a shared lib or an object file that was intended
    Rob> to be used by apache (or whatever) as a dynamic module,
    Rob> i.e. mod_guile)?

Well yes, this is exactly what we need to establish.  But, to take
mod_guile as an example, surely it's much easier to pass the whole
page out to Scheme and process it there, than to do processing mostly
in C?

    Rob> In particular, are there cases where it's hard to support
    Rob> having (finding) any .scm file,

There probably are - for example embedded OSs with no filesystem - but
I doubt that it is a priority to cater for them.

To me, if defeats the whole object of Guile if catering for this case
means that it is harder to improve Guile and its docs for the other
99% of cases.  To avoid this happening, I suggest that we could solve
this problem by a mechanism that links Scheme code into a library or
executable at build time.  This could be something like unexec (in
which case the source would already have been read and stored in tree
code), or it could be a linker tool that just dumps plain source code
into the binary - as though it was a big const char[], but more
convenient to use at build time.

    Rob> and if so, in those cases, what's the preferred solution --
    Rob> embedded scheme strings that are evaled at runtime, or when
    Rob> you need something with more dynamic content, building the
    Rob> scheme form representing your function (or whatever) and then
    Rob> calling eval on that?

Embedded Scheme is OK for small code fragments, otherwise as just
suggested above.  As far as dynamic content is concerned, is there any
kind of dynamic Scheme content that can't be generated and then eval'd
by a chunk of static Scheme code?  (I don't think so, if it could be
generated by a chunk of static C code.)

    Rob> I'm not sure this applies to scm_internal_catch, but just
    Rob> wanted to make sure we had thought about the likelihood of
    Rob> such a situation.

Absolutely.  What I've half-proposed is quite radical, so it's crucial
to think it through carefully.

To throw out another example: libguile currently has a set of
old-fashioned primitives for manipulating object properties
(scm_set_object_properties_x etc.).  These should be deprecated in
favour of the make-object-property mechanism, but it's currently hard
to do this because the functions are part of the C API and so might be
being used by someone's C code.  If, on the other hand, these
primitives were officially provided only on the Scheme level, it would
be trivial to replace them with Scheme implementations written using
make-object-property.

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

    Rob> I think one counter argument would be "where do people who want to
    Rob> write C extensions to Guile go for documentation?".

C extensions are covered by the documentation I've suggested, I
believe.  Specifically, that doc would describe how to write and
export C primitives, validate and convert parameters between C and
Scheme forms etc., how to create smobs, handle lifetime issues, ...

    Rob> As an example, if you want to write a big complex smob for something
    Rob> that's a heterogeneous collection of both C and scheme data, you may
    Rob> well need to use any number of scm_* functions to manipulate the
    Rob> smob's data structures from the C side, and you'd certainly want to
    Rob> have documentation for those functions.

Absolutely.  I think that data substructure manipulation functions
like scm_cons, SCM_CAR and SCM_CDR, should be included in the
documented C API.

    Rob> If it weren't for the fact that it could be a lot of extra work
    Rob> (unless we could somehow automate much of the process), it seems like
    Rob> a solution would be to have one main section that was Scheme oriented,
    Rob> with a structure and composition similar to what you described, and
    Rob> one main section which was "Guile from the C side".

Now that I've been involved for some time, I'm pretty sure that any
extra work will be insignificant compared to the long term cost of not
having the right overall focus and structure.  So I wouldn't worry
about the work yet.

    Rob> Of course there would be a lot of duplicated text between the sections
    Rob> since, for example, you'd have to document scm_list_p and list? in
    Rob> separate sections with essentially the same text.

True, but I think it might make sense in context anyway.

Thanks for your thoughts,

        Neil