This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
jimb@red-bean.com writes: > > It should assume that the reader understands C and Unix, but not > Scheme. I hope only the sections relevant to the C API will assume the reader understands C. > > The manual will be organized by the function performed. Scheme > functions, scm_ functions, and gh_ functions will not be segregated > into their own sections; they will be listed side by side, and > distinguished by giving an appropriate category to @deffn. > I think this is a bad plan. If you want to write a C extension or app, the avaiable Scheme functions are not very interesting to you. Conversely, if you are writing a Guile script, the whole gh_ API is utterly irrelevant to you, and the scm_ API is only marginally relevant in those parts that happen to be directly exported to Scheme. I expect people to want to have a handy reference to _only_ the APIs of interest to a particular project, thus I think separate Scheme interface and C interface references would be useful. > > - interpreter definition > Exhaustive docs of everything you can do with the interpreter. > - scripting definition - ditto > - C-level definition > Note that this does not include specs for all the scm_ and gh_ > functions. Those go in the chapters for their functions. I think some of the gh_ functions, namely the ones for basic setup (gh_enter), calling back to scheme code (gh_eval_str) and converting between Scheme and C types logically belong here. > - Guile's dynamic typing system > - How GC works, and how to play nice with conservative GC > - the relationship between the C and Scheme views of primitive > Scheme functions > - snarfing > > Then, chapters on each group of functions Guile provides: lists, > vectors, I/O, etc. Follow the plan of R5RS, and extend it to handle > Guile's new offerings. Document gh_ and scm_ functions side-by-side > with the corresponding Scheme-level functionality. Again I think this will be problematic due to the parts of each API that have no counterpart in the others. Other than this point, I think this is a good plan. - Maciej