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]

Re: New manual plan



> I hope only the sections relevant to the C API will assume the reader
> understands C.

Sure.

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

Okay, I've gone back and forth on this myself.


Issue: what's the best way to document the (many) functions that are
written in C, and visible to Scheme via the SCM_PROC macros?  It's
silly to document them twice --- they're exactly the same function.
With the organization I posted, there's a consistent, easy-to-
understand answer.  Your info file will look like this:

 - Scheme Function:  eof-object? OBJ
 - C Function: SCM scm_eof_object_p (SCM OBJ)
     Return true iff OBJ is the end-of-file object.

And your printed manual will look like this:

  eof-object? obj					Scheme Function
  SCM scm_eof_object_p (SCM obj)			C Function
     Return true iff OBJ is the end-of-file object.

This is the formatting used in the Emacs Lisp manual and the GNU C
library manual, both of which I like a lot.


Second issue: the Scheme interface covers a lot of the same areas as
the C interface.  If you segregated them, in each section you would
need to cover list processing, I/O, exception handling, etc.  So you'd
essentially have "Part I: Scheme functions" with chapters
A,B,C,... and then "Part II: C functions" with the exact same sequence
of chapters.  Now, as a reader of the manual, I just want to get the
job done; I'm willing to do it at either level.  So having it indexed
primarily by the kind of interface, and then secondarily by the
purpose, is inverted.

When people come to the manual with a requirement like: "I want to do
foo in Scheme", they will indeed find more information than they need,
but I don't think it'll be too difficult for them to figure out which
ones are relevant to them.

I think there are points in both directions, but we need to make a
decision we can stick with now.


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

Yep.  All the general up-front stuff you need to write C code that
interfaces with Guile goes 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.

No problem.  Some chapters will only have Scheme functions in them;
others will only have C functions.  In cases where the relevant C
functions address a different aspect from the relevant Scheme
functions, we can segregate them into sections.