Re: should GOOPS be built-in?

[Valentin Kamyshenko <val at kamysh dot materials dot kiev dot ua>]

>>>>> "Maciej" == Maciej Jennifer Stachowiak <mstachow@alum.mit.edu> writes:

Maciej> Lack of documentation is also a major problem. But I am unsure
Maciej> where to put the focus here. Obviously reference documentation
Maciej> for all Scheme-accessible procedures and syntax is essential,
Maciej> and thanks to Greg's work it's becoming a reality. But past
Maciej> that, what's most important to build the kind of community
Maciej> that Guile needs to be a successful project? Should additional
Maciej> docs be targetted at people using Guile from the Scheme level,
Maciej> either standalone or embedded in an app, at people who want to
Maciej> embed Guile in applications, or at people who are interested
Maciej> in hacking Guile itself? Should it be in tutorial or user's
Maciej> guide form, or perhaps some more sparse form still for
Maciej> internals docs?

When thinking about  the perspectives of Guile,  I see its place first
of all among such tools as tcl/tk, python, and perl.  It is fine, that
it is based on Scheme, which in its standard form  is a very condensed
language,  thus, in principle, all what  is needed for the beginner to
begin his work is to read R*RS. Thus,  "to sell" guile as an extension
language it is sufficient to explain what is  the module, how to write
SMOBs, how to call guile functions from C, and how to compile and link
the  program (or/and to load  modules dynamically).   This could be an
independent and self-contained part of  the documentation. The text by
Jim Blandy (data-rep.texi) seems   to be an excellent introduction  to
the subject, it even gives to  the reader an illusion of understanding
of "how it works"  -  which is an   important condition for  smth.  to
become popular    :).   I would   only  add  there  the  discussion of
ALLOW_INTS/DEFER_INTS pairs (by the way, REALLOW_INTS/REDEFER_INTS are
not mentioned in the documentation  at all - I  personally do not know
what do  they mean), and would   explain how to raise  different error
conditions.  Also, scm_must_alloc/scm_must_free must be described here
in more  details.  I believe, that all  the "building blocks" for such
introduction are already written.  What is not  written for this part,
but I believe it is  very important, is  a part, that I could  entitle
smth.  like "Suggestions  from  Experts".  It must warn  about typical
mistakes   when  writing   extensions    (like  what is   written   in
data-rep.texi    about interplay   between   garbage collecting    and
allocation), and include common  performance hints, even  trivial (use
try/catch instead of call/cc when  possible; do not use macroses, when
possible; we have uniform arrays and  shared arrays, that are good for
matrix calculations; and so on - this is what I'd really need).

When talking about   the "scheme level"   documentation, the situation
seems to  be more complicated.  First, I  think,  there is  no need to
write  yet another Scheme tutorial   for beginners, because there  are
excellent introductions,  that are available  on the  net (it would be
nice, however, if some of these texts were available at the guile http
site, if the licence agreement would allow it). 

There are evident gaps in the documentation, that  are to be filled as
soon   as possible,  especially  taking  into   account that they  are
guile-specific.  The two most important   issues, IMHO, are the module
system, and GOOPS. As far as it is concerned with the GOOPS manual, it
is pretty good, and will become better when the chapter on MOP will be
included in  it.  The introduction to  modules  was sent to  this list
about 1/2 year ago   (I'm very sorry: I   do not remember who was  the
author of  it).  I think, it  must be  included into the documentation
ASAP.

Finally,   the most important, and  the  most non-evident  part of the
documentation  must cover  somehow  the  features of  guile, that  are
specific for  it and/or are  not well described  in manuals. There are
many non-standard extensions,  that  were  introduced by  people,  who
knows "what they are stand for". It would be  ideal, if these features
were described from the point of view of their usefulness. Probably, I
will explain  this  better  by a simple   example. When  there   was a
discussion (about a year ago)  in the "guile-numerical" about  C-style
and  Fortran-style  matrices (the first  are   ordered "by  raws", the
seconds - "by   columns"), it appeared, that   `make-shared-array' was
designed specially with such kind of transformations in mind. When you
write
	(define A #2e(...))
	(define B (make-shared-array A (lambda (i j) (list j i)) ...))
there is no additional  overhead  in using  B  instead of A.  This was
absolutely not evident from the description,  but it is very important
for applications. I'm pretty sure, that the situation is quite similar
with majority of other  "non-standard"  functions, included in  guile:
they will become   useful  only  when  there  will  be some   kind  of
explanation of their existence, and more or less realistic examples of
their  use  (perhaps, my  example was  too  specific  - that  was just
because I   understood in that case   what  I am   talking about; more
interesting for me could be if somebody explain, why and when should I
use dynamic-wind :).

Thus,  what   I    think   would  be  useful  is     a  combination of
intermediate-level description of scheme with  a special emphasize  of
the guile specific features.

And, the  last.  I  think,  it  is  important to develop    a standard
procedure of  submitting applications to the  repository (not the core
patches)  - smth. similar to CPAN  or CTAN.  Note,  that in both cases
there  are special  tools for   preparing documentation simultaneously
with the application - *.dtx files in TeX, and .pod for Perl (I do not
know if it is used yet).  I think, smth.  similar must be admitted for
Guile applications from the very beginning.

--
Best regards,
	Valentin,
	(who, unfortunately, "says stuff" :).