Re: Documentation lacking

[Derry Bryson <dbguile at ta1 dot reno-onramp dot com>]

Eric Moore wrote:
> 
> >>>>> "Derry" == Derry Bryson <dbguile@ta1.reno-onramp.com> writes:
> 
> Derry> I can find no real documentation; I have looked at the
> Derry> documentation on the website, the documentation included with
> Derry> the latest release, and the documentation from CVS (guile-doc).
> 
> Guile doc is what you want.  Specifically,
> guile-doc/ref/guile-ref.texi
> 
> For where that's inadequate (which as everyone here will admit is too
> often the case) I reccomend asking here...
> 

I have looked at this and it is indeed much better than the docs
included with the released version.  I think it is a very good start and
I congratulate those who worked on it.  As you say, however, it is
lacking many areas.  For instance the section on modules is empty.

> Derry> What is the basis of the guile interpretation of scheme?  How
> Derry> does it evaluate scheme expressions?
> 
> I'm not entirely sure why you need to know this, if you mean the
> internal representation and evaluation code.
>
> If you want to know the API for evaluating scheme expressions from C,
> which is guile-ref.texi (or guile-ref.info) part IV, where it
> describes the gh_ interface.
>

If you are only using guile as a scheme interpreter to run your
scheme programs, perhaps you don't care about this.  However, in
my experience, it can be quite helpful to know how the underlying
system works especially in the areas of eval, data storage, and
garbage collection.  Some of this is already documented somewhat.

If you are intending to use guile as an embedded scheme interpreter, 
then I think you need much more information on how it works internally
in order to understand how to use it effectively.  Obviously, you need
to know how the garbage collector works so that you can protect data
created in your code.  You need to understand how the system works
so that you can design your code to take advantage of it.  Does the
system compile expressions to bytecode or some other internal (and
more efficient form)?  Should I just call gh_eval_str() or should
I should I call some function to precompile the expression for faster
execution later?
 
> Derry> I have found documentation on how it stores values, but not
> Derry> much else.  What is the precision of integer values?  Are they
> Derry> 32 bit or 30 bit (it would seem 30 bit) (this is quite a basic
> Derry> question, what about floats?).
> 
> Immediate integer values are 30 bits, but guile has support for
> bignums, so can support any number you can reperesent in C.  The C
> function: SCM gh_long2scm(long n); will convert a long into an SCM
> (the C representation of scheme data) which, if n < 2^30 will be an
> immediate, otherwise it will be converted into a bignum, gh_scm2long
> will convert it back.  Floats are represented as C doubles...

I was merely pointing out one area where the documentation was unclear
to me in an attempt to point out that one thing that is needed here is
a specification of how guile implements scheme.  Without this I find it
very difficult to conceptulize (sp?) how the whole thing works and hence
I don't know what to do or where to look for guidance on how to do 
something.

Sincerely,

Derry Bryson