I take as my starting point that the documentation should be sufficient
to allow a user to make use of all the features of guile without refering
to the source code at all. Cross-references to other documents are OK.
There is a lot of good stuff in guile that only has the status folk-lore
at present; it would be very nice if some of this was usable in the next
release.
Big Omissions
1) Dynamic loading. There are some cryptic notes, in the libguile directory
but it would be good to have them corrected and updated and in guile-ref.
Ideally they should also be in the tutorial. I would like to see an explicit
list of steps about how to set up some c-code so that it can be dynamically
loaded. This is supposed to be one of key selling points; and Tcl can do it
already :-). The scheme side of this is documented, but the c hooks are not.
2) Threads. The existing thread documentation is out of date, and bears little
resemblence to the current system. The high and low-level sections are just
copies of one another. with-thread is not mentioned. thread switching on IO is
not mentioned.
3) Blank sections. A quick scan through shows that following sections
are blank
Writing Guile Modules
Module Internals
First-Class Variables
First-Class Modules
Reflection
eval
Tag Values
Weak References
Internal Debugging Interface
Tcl/Tk interface. (Are we still going this way?)
Error Messages
Memory Allocation and Garbage Collection
Mixing gh and scm APIs
Scheme Data Representation (does JBs essay cover this ?)
Relationship between Scheme and C functions
I/O Internals
snarfing
Single-Step
Backtrace
Type Index (at least should point to definition of SCM)
Minor Glitches
libguile error messages is all in typewriter font. It has been like this
since 1.1 or earlier.
Julian Satchell