[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Doc organization (Re: Around again, and docs lead role)
From: |
Neil Jerram |
Subject: |
Re: Doc organization (Re: Around again, and docs lead role) |
Date: |
07 May 2003 22:06:57 +0100 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 |
>>>>> "Ricard" == Ricard Mira <address@hidden> 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
- Doc organization (Re: Around again, and docs lead role), Ricard Mira, 2003/05/03
- Re: Doc organization (Re: Around again, and docs lead role),
Neil Jerram <=
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Wolfgang Jaehrling, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/08
- Re: Doc organization (Re: Around again, and docs lead role), David Van Horn, 2003/05/09
- Re: Doc organization (Re: Around again, and docs lead role), Neil Jerram, 2003/05/10
- Re: Doc organization (Re: Around again, and docs lead role), Rob Browning, 2003/05/15
- Re: Doc organization (Re: Around again, and docs lead role), Paul Jarc, 2003/05/15