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

[Neil Jerram <neil@ossau.uklinux.net>]

>>>>> "Ricard" == Ricard Mira <ricardmm@tiscali.es> writes:

    Ricard> Thanks.  I think that I need to learn more about Guile in
    Ricard> order to be able to propose something sound, but I can
    Ricard> give my opinion as a user.

    Ricard> As a user who is learning Scheme to customize and extend
    Ricard> Guile-using programs, I expect the Guile documentation to
    Ricard> contain a section for each programming language (C and
    Ricard> Scheme for sure; translated languages maybe).  Then I need
    Ricard> to read just the Scheme section (and maybe also a general
    Ricard> introduction).

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.

    Ricard> Neil, are your half-formed thoughts the same as my
    Ricard> half-formed thoughts? :-)

Not obviously, no, but it may be that there is some underlying overlap
between them.

My latest thinking is that we could be a lot more concrete, even
proscriptive, about what Guile is for and how people should use it,
and that if we did so it would be a lot easier to clearly assess the
state of the documentation and to finish it off.  (Right now, IMO, a
it is difficult even to describe the documentation status.)

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.)

If we did this, I think the natural high level documentation structure
would then be:

- Scheme reference documentation - more or less like the current Part
  IV, but Scheme only, not C.

- Task-based documentation describing everything needed for aspects of
  interfacing with C code:

  - writing and exporting primitives (in modules)

  - smobs, GC, lifetimes etc.

  - Guile initialization from within a library

  - how to call out to a Scheme-defined procedure

  - how to look up a Scheme-defined variable

  - how to evaluate user-supplied code and catch errors

  - (anything else that I've missed).

Which has something in common with your thoughts.

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

Regards,
        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user