RE: Guile Impressions

[John Fitzgerald]

        > -----Original Message-----
        > From: Martin Grabmueller [SMTP:address@hidden
        > Sent: May 08, 2001 17:59
        > To:   address@hidden
        > Cc:   address@hidden
        > Subject:      Re: Guile Impressions
        > 
        > > From: John Fitzgerald <address@hidden>
        > > Date: Tue, 8 May 2001 10:13:54 +1200
        > 
        > > I'm aware that the issue of documentation is starting to be
        > > addressed.  This has been my main concern.  It appears to me to
be
        > > fragmented and mainly consists of a texinfo reference and sundry
        > > introductory papers.  The reference is far from complete and
info as
        > > a documentation tool is frustrating for a non-emacs person to
        > > navigate.  What is sorely lacking, though, is a guide to Guile;
a
        > > document which explains not what each function, procedure or
data
        > > structure does (that's the references job) but rather how,
where,
        > > when and why to do things in certain ways (to foster
understanding).
        > > If I wish to use Guile in my applications, then I need to be
aware
        > > of the design decisions I need to make.
        > 
        > As I see it, I think that the Reference Manual should include some
        > documentation you want to see.  Every section describing some
aspect
        > of Guile should start out with a description of the concepts
involved,
        > and how and when these concepts apply to a particular problem.
        > Unfortunately, we (I?) have only managed to work on the Scheme
part of
        > the Manual yet, and the part on Embedding and Extending is still
quite
        > rough.
        > 
        > Do you think that the Reference Manual is not the place for such
        > information, or is it only the missing documentation you are
disturbed
        > by?
        >
        I am frustrated by the missing documentation, and resorting to code
reading isn't the best way to answer queries as the answer often lies in the
dynamic behaviour for which you need to read and understand large regions of
the program.

        As I see it the two, Guide and Reference need to be separate
(logically if not physically) because they address different concerns.  The
Reference is there to precisely answer questions of syntax, function,
results, return values, etc of specific constructs.  It can, as you suggest,
explain the concepts as they relate to the mechanics of individual
components, but I would tend to move the descriptions of anything larger
into separate section and leave the reference section as a (probably
alphabetical) catalogue of standalone descriptions of the individual
components (much like a collection of man pages).  It is very much a hard
nosed technical reference.

        The Guide is orthogonal to this in that it describes how to use
those constructs in combination to achieve a given effect.  You often see
the word 'Gentle' in the title of such documents which indicates to me that
they are an introductory guide only.  But the idea is applicable
nevertheless, that the Guide should be much more of a discussion of how to
go about using the individual the API (in this case) to best effect along
with possible alternatives and common practice.

        > > Until yesterday, I thought that the gh_ interface was the way to
go.
        > > But it now appears that we would be better off using the scm_
        > > interface.  I have to admit to being confused, both by the
apparent
        > > change of emphasis and by the seemingly ad hoc nature of the
scm_
        > > interface (made worse by documentation issues).
        > 
        > Ad hoc?  Personally, I think that the SCM interface is quite nice
once
        > you get used to it.  Maybe it's the lack of documentation again?
        > 
        Quite possibly.  Approaching it from the necessity to grep
libguile/*.h to find applicable scm_ and SCM_ items then trying to decipher
the differences between some of them probably isn't the best, but from that
viewpoint it does appear to have grown haphazardly rather than have been
planned.

        >
        > > Personally, I would appreciate a clear statement of direction
from
        > > wiser heads than I in regard to which is the interface to use
into
        > > the future.  If it is the scm_ interface, then it seems some
work is
        > > required in consolidating and documenting it.
        > 
        > Hm.  A `clear statement' has not been reached yet by the
        > developers/maintainers, though I am not sure myself where the
actual
        > opinions differ, and where we need to reach consensus.
        > 
        That's fine, but be sure to make any consensus that is reached known
to the users.

        >
        > > Another of my concerns has recently been addressed in the form
of safe
        > > environments.  Opening up an application in the way that
providing it with
        > > Guile as an extension language allows often carries with it the
requirement
        > > to limit what the user can do within those extensions.
        > 
        > Have you been successful using safe modules?  If not, what have
been
        > the problems?
        >
        I haven't yet had time to play with them, but will need to do so.
They weren't available when I needed them previously and so unfortunately
Guile wasn't used.
         
        >
        > > That Guile is addressing this is excellent, but it feds into the
        > > bigger picture of modules.  I keep seeing disclaimers about the
        > > module system being revamped and that we shouldn't rely on the
        > > current mechanism remaining.  The provision of modules is fairly
        > > core, I would have thought, to the entire structure of Guile
        > > applications.  I feel that a robust, stable and well documented
        > > module system needs to be put in place ahead of the facilities
and
        > > features that could benefit from it.  I know the "new module
        > > mechanism" continues to be discussed, but it seems to me to be
being
        > > discussed somewhat half-heartedly and not actually moving
forward.
        > 
        > I hope this has been commented on sufficiently by thi already.
        >
        Yes, he has.

        > 
        > > My preferred platform is Unix, but I'm presently working with
MS-Windows.
        > > Guile is easy to install and use in the Linux environment, but
definitely
        > > not so on MS-Windows.  This is not a Guile failing but it would
be useful if
        > > the stable releases were accompanied by a pre-compiled
implementation for
        > > MS-Windows.  Guile is too valuable a tool for me not to try and
use it
        > > whenever it's applicable.
        > 
        > Some time ago, I wanted to add a bunch patches to Guile which make
        > compiling Guile under Windows possible, even with the dreaded
M$VC.  I
        > got distracted too many times, mainly because I can't test such
        > patches myself, and partly because there is simply no fun for me
with
        > this job.  Sorry.  But I hope to pick that up some day again.
        > Promised.  Hopefully.  Maybe.  Hmm.  If someone here is willing to
        > work on this, I can send a patch against guile-1.4, which would
        > probably need some work, and only results in an incomplete port
        > (mainly missing POSIX procedures).
        > 
        A pre-compiled Guile-1.4 was made available after my recent distress
call, so my particular need is now satisfied.  (I don't have the details on
me, but see the guile-user list, and once again a big thank you to the
provider.)  The problem with the MS-Windows platform in this regard is the
lack of a common tool train.  So in my case, although I got Guile compiled
and working standalone with gcc under cygwin, the resulting library could
not be linked with the output of Borland's C++Builder and even their format
conversion tool failed (surprise, surprise).

        >
        > > Coming as I do from a procedural language background, I need to
        > > translate the Scheme terminology to those I already know.
Sometimes
        > > I do find this difficult.  (I still have no idea what fluids are
all
        > > about.)  I would be one who'd appreciate a slightly less Scheme
        > > terminology ridden descriptions of some things.  So if you could
        > > bear this in mind, I'm sure Guile would become a friendlier
place to
        > > some.  (And yes, I do realise this is a problem with me, not
Scheme
        > > or Guile.)
        > 
        > Is this addressing mailing list language or the documentation?  If
the
        > first, just ask more aggressively, if the latter, please send us
        > suggestions where to improve.  Sometimes we live too much in the
        > Scheme world, maybe, and someone needs to get us back.
        > 
        It would be unreasonable of me to expect hardcore Schemers to
handicap themselves in their discussions by avoiding Scheme terminology.
Such terminology expedites communication, but the uninitiated need a "leg
up".  The difficulty posed to newcomers seems to be much greater in the
Scheme world than in others I live in because things seem to be almost
exclusively defined in Scheme terms.  Even in books with teach Scheme
programming, there is a distinct lack of non-Scheme descriptive text.
Perhaps what is needed is a glossary of terms like 'closure', 'fluid' and
'continuation' (to name some Scheme language ones) which we newbies can
refer to to get an plain English description.

        I have to add that one of the reasons I'm raising these issues is
not just for my own enlightenment, but so that the questions get answered
and are available to others in the future.  Please consider -- and this is a
general plea -- including them when maintaining the resources
(documentation, FAQs, code, etc) of the Guile project.



NOTICE: The information contained in this electronic mail message and any
attachments is confidential to Pavilion Technologies, Inc. or one of its
subsidiaries and may contain proprietary information or be legally
privileged. This message and any attachments are intended only for the
personal and confidential use of the designated recipient(s). If you are not
the intended recipient or an agent responsible for delivering it to the
intended recipient, you are hereby notified that you have recieved this
message in error, and that any review, dissemination, distribution or
copying of this message and any attachments is unauthorized and strictly
prohibited. If you have received this message in error, please notify me
immediately by telephone and electronic mail, and delete this message, any
attachments, and all copies thereof. Thank you very much