Around again, and docs lead role

Around again, and docs lead role

[Neil Jerram]

Sorry that I've been out of the loop for so long.  I should soon have
some time to contribute again.

That said... is there anyone out there who'd be interested in taking
over the lead role on Guile documentation?

I have three reasons for asking this:

- I don't expect to have a _lot_ of time for Guile soon, and the docs
  would benefit from someone with more time available.

- I have other Guile interests that I'd like to spend some of that
  time on.

- A new pair of eyes could take a fresh look at the higher-level doc
  issues such as overall organization, what kind of docs we need
  (e.g. the cookbook idea) etc.

Any takers?

(Whatever happens, I will still be involved in small ways like
assessing and applying patches that people send in.  I think there are
a few such patches pending for some time, and hope to get to them
soon.)

        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Thamer Al-Harbash]

On Sat, 26 Apr 2003, Neil Jerram wrote:

> Sorry that I've been out of the loop for so long.  I should soon have
> some time to contribute again.
>
> That said... is there anyone out there who'd be interested in taking
> over the lead role on Guile documentation?

My two cents:

It's a two man job. We need one honest to goodness guile
developer who has spent a fair amount of time writing the guile
code (recently) actually write up a series of drafts, and one
person to edit and make sure the documentation is readable.

I'd be willing to do edit, review, and fill in the smaller
parts. I know enough texinfo to do this comfortably. I don't
think anyone but a developer should actually be writing the
documentation. guile is a fairly complicated piece of software.

-- 
Thamer Al-Harbash            http://www.whitefang.com/
	(if (> pressure too-much-pressure)
		'flame 'work)


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "Thamer" == Thamer Al-Harbash <tmh@whitefang.com> writes:

    Thamer> My two cents:

    Thamer> It's a two man job. We need one honest to goodness guile
    Thamer> developer who has spent a fair amount of time writing the guile
    Thamer> code (recently) actually write up a series of drafts, and one
    Thamer> person to edit and make sure the documentation is readable.

    Thamer> I'd be willing to do edit, review, and fill in the smaller
    Thamer> parts. I know enough texinfo to do this comfortably. I don't
    Thamer> think anyone but a developer should actually be writing the
    Thamer> documentation. guile is a fairly complicated piece of software.

Hi Thamer,

Thanks for this response.  It's slightly at cross purposes to what I
was intending, but I think that in itself highlights that we need a
better overall picture of the current docs state, and an overall plan
for how to finish them.

More from me later in the week, but please feel free to contribute
more of your own assessment and thoughts.

        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "Ricard" == Ricard Mira <ricardmm@tiscali.es> writes:

    Ricard> Thamer Al-Harbash wrote:
    >> I'd be willing to do edit, review, and fill in the smaller
    >> parts. I know enough texinfo to do this comfortably. I don't
    >> think anyone but a developer should actually be writing the
    >> documentation. guile is a fairly complicated piece of software.

    Ricard> I am learning Guile Scheme and don't know C, but I think I
    Ricard> could help keep the documentation understandable.

Thanks Ricard; please see also my reply to Thamer.  What are your
views so far about the existing docs?  (I'm finishing for
a cold hard assessment here, not compliments.)

        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "Ricard" == Ricard Mira <ricardmm@tiscali.es> writes:

    Ricard> Neil Jerram wrote:
    >> Thanks Ricard; please see also my reply to Thamer.  What are your
    >> views so far about the existing docs?  (I'm finishing for
    >> a cold hard assessment here, not compliments.)

    Ricard> IMHO, the overall organization of the documentation isn't
    Ricard> clear.  But I know that documenting Guile is difficult,
    Ricard> because there are many different things to consider (C and
    Ricard> Scheme, Scheme and translated languages, applications and
    Ricard> Guile, etc.).

Indeed.  This also makes it difficult to assess the overall status of
the docs, and in particular how close we are to being "finished".

    Ricard> I am thinking about these issues.

That's great.  I've been thinking about these over the last couple of
days as well, but I'll save my half-formed thoughts for the moment so
as not to prejudice yours.

    Ricard> Also, I believe that "Part V: Guile Modules" should
    Ricard> disappear, because features should be documented according
    Ricard> to their functionality, not according to their origin or
    Ricard> implementation (SLIB, SRFIs, etc.).

Possibly yes.  I think it might be useful to keep a dividing line
between core Guile and available add-ons (e.g. SLIB and JACAL), but it
may well be that the dividing line we have now is not in the right
place.  Bear in mind that in some mythical future there will be lots
of Guile-using applications - already there are e.g. Gnucash,
Lilypond, TeXmacs - that might provide useful library functions.  I
think it will be desirable at least to include pointers in the Guile
manual to those applications' documentation, so we need somewhere to
put those pointers.

Best regards,
        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Robert Uhl]

Ricard Mira <ricardmm@tiscali.es> writes:
> 
> IMHO, the overall organization of the documentation isn't clear.

My own problem has been a feeling that it's not complete.  At least,
trying to figure out the C bindings has been...interesting.  But other
than that it's been decent.  Of course, I did have to learn Scheme from
SICP; it'd be nice were there an intro to Scheme itself somewhere.

> Also, I believe that "Part V: Guile Modules" should disappear, because
> features should be documented according to their functionality, not
> according to their origin or implementation (SLIB, SRFIs, etc.).

OTOH, it's nice to know what's part of guile itself and what's not, at
least to some of us.  Could go either way, I guess.

-- 
Robert Uhl <ruhl@4dv.net>
Xristus usstôþ!  Sunjaba usstôþ!


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[rm]

On Fri, May 02, 2003 at 10:40:12PM -0600, Robert Uhl wrote:
> Ricard Mira <ricardmm@tiscali.es> writes:
> > 
> > IMHO, the overall organization of the documentation isn't clear.
> 
> My own problem has been a feeling that it's not complete.  At least,
> trying to figure out the C bindings has been...interesting.  

I had similar experiences. The existing documentation *is* very good,
but i was astonished to find a few undocumentes jewels (well, actually 
pretty neccessary stuff:) in  the header files ...
I started writing up some info last night but i'm not shure whether
the lack of documentation actually manifests some public vs. private
API issue.

>                                                             But other
> than that it's been decent.  Of course, I did have to learn Scheme from
> SICP; it'd be nice were there an intro to Scheme itself somewhere.

Hmm, there a a handfull of pretty good Scheme intros available, why
bother duplicating these efforts (better: write a Guile-specific addendum
for one of these).

> 
> > Also, I believe that "Part V: Guile Modules" should disappear, because
> > features should be documented according to their functionality, not
> > according to their origin or implementation (SLIB, SRFIs, etc.).
> 
> OTOH, it's nice to know what's part of guile itself and what's not, at
> least to some of us.  Could go either way, I guess.

Yes. And it would be _very_ helpfull if the documentation would mention
what modules need to be "used" for certain functions [(ice-9 regexp) for
regular expressions ...).

Another question: there's some very good information in the guile-workbook
CVS module. But sometimes it's hard to tell whether a piece is documenting
an existing fact of Guile or rather proposing a new impementation.

 Ralf Mattes

> 
> -- 
> Robert Uhl <ruhl@4dv.net>
> Xristus usstôþ!  Sunjaba usstôþ!
> 
> 
> _______________________________________________
> Guile-user mailing list
> Guile-user@gnu.org
> http://mail.gnu.org/mailman/listinfo/guile-user


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Robert Uhl]

rm@fabula.de writes:
>
> > My own problem has been a feeling that it's not complete.  At least,
> > trying to figure out the C bindings has been...interesting.
> 
> I had similar experiences.  The existing documentation *is* very good,
> but i was astonished to find a few undocumented jewels (well, actually
> pretty neccessary stuff:) in the header files...

Yup--exactly the problem I've had.  There are a few things (which I
cannot recall anymore) which have been right royal bears without docs.
Most of 'em I've solved by digging through headers, figuring them out
once, and then copy-pasting from then on.  Not the most elegant way to
handle things, for certain:-}

> > But other than that it's been decent.  Of course, I did have to
> > learn Scheme from SICP; it'd be nice were there an intro to Scheme
> > itself somewhere.
> 
> Hmm, there a a handfull of pretty good Scheme intros available, why
> bother duplicating these efforts (better: write a Guile-specific
> addendum for one of these).

Well, most of them seem to either be print books (which cost dough), or
written specifically for some incompatible dialect.  The bigger issue is
that I imagine most of us want Guile to become the extension package of
choice, even more popular than Perl or Python.  To be successful at
that, it's useful to have a tutorial, particularly when the language is
as odd as a Lisp dialect can seem as first.  Those unfamiliar with
Scheme who happen upon Guile are likely to skip past, scared away by the
parentheses and lack of a thorough introduction.

-- 
Robert Uhl <ruhl@4dv.net>
Il Crist ais resüstà!  El ais vairamaing resüstà!


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Thamer Al-Harbash]

On Sat, 3 May 2003, Robert Uhl wrote:

> Well, most of them seem to either be print books (which cost dough):

Not always. The Prentice Hall book is available on-line in its entirety.

http://www.scheme.com/tspl2d/

It's about as good as the C K&R book. All one should need
initially.

> To be successful at
> that, it's useful to have a tutorial, particularly when the language is
> as odd as a Lisp dialect can seem as first.  Those unfamiliar with
> Scheme who happen upon Guile are likely to skip past, scared away by the
> parentheses and lack of a thorough introduction.

I propose placing a link from the guile page to an on-line copy
of the Prentice Hall book which is reproduced there with the
permission of the publisher.

-- 
Thamer Al-Harbash            http://www.whitefang.com/
	(if (> pressure too-much-pressure)
		'flame 'work)


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[David Allouche]

On Sat, May 03, 2003 at 07:15:04PM -0400, Thamer Al-Harbash wrote:
> On Sat, 3 May 2003, Robert Uhl wrote:
> 
> > Well, most of them seem to either be print books (which cost dough):
> 
> Not always. The Prentice Hall book is available on-line in its entirety.
> 
> http://www.scheme.com/tspl2d/

Nice.

There are also:

http://mitpress.mit.edu/sicp/full-text/book/book.html
http://www.htdp.org/
http://www.cs.utexas.edu/users/wilson/schintro/schintro_toc.html

-- 
                                                            -- DDAA


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[rm]

On Sat, May 03, 2003 at 04:21:03PM -0600, Robert Uhl wrote:
> rm@fabula.de writes:
> > I had similar experiences.  The existing documentation *is* very good,
> > but i was astonished to find a few undocumented jewels (well, actually
> > pretty neccessary stuff:) in the header files...
> 
> Yup--exactly the problem I've had.  There are a few things (which I
> cannot recall anymore) 

In german we call it "Verdraengung" (repression) :-)

> which have been right royal bears without docs.
> Most of 'em I've solved by digging through headers, figuring them out
> once, and then copy-pasting from then on.  Not the most elegant way to
> handle things, for certain:-}

Well, it's a nice way to get comfortable living in the guts of guile,
but scares application programmers who 'just' need guile as an embedded
language.

> > > But other than that it's been decent.  Of course, I did have to
> > > learn Scheme from SICP; it'd be nice were there an intro to Scheme
> > > itself somewhere.
> > 
> > Hmm, there a a handfull of pretty good Scheme intros available, why
> > bother duplicating these efforts (better: write a Guile-specific
> > addendum for one of these).
> 
> Well, most of them seem to either be print books (which cost dough), or
> written specifically for some incompatible dialect.  

??? "Teach yourself Scheme in fixnum day" is free and takes greate care
*not* to be dialect specific. SICP is available online as well ...

> The bigger issue is
> that I imagine most of us want Guile to become the extension package of
> choice, even more popular than Perl or Python.  To be successful at
> that, it's useful to have a tutorial, particularly when the language is
> as odd as a Lisp dialect can seem as first.  Those unfamiliar with
> Scheme who happen upon Guile are likely to skip past, scared away by the
> parentheses and lack of a thorough introduction.

I don't know. Somehow i have the feeling that a Scheme based scripting
language will never be as popular as Perl or Python etc. (and i'm not
even shure i want that). My first encounter with Scheme was ScruptFu
(the Gimp's scripting language). There were a handfull of rather simple
intros and close to no real documentation -- still i somehow managed to
get my filter written (the anoying part where the missing features of
the dialect -- anyone for a Guile/Gimp???).


Ralf Mattes


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Robert Uhl]

Thamer Al-Harbash <tmh@whitefang.com> writes:
> 
> > To be successful at that, it's useful to have a tutorial,
> > particularly when the language is as odd as a Lisp dialect can seem
> > as first.  Those unfamiliar with Scheme who happen upon Guile are
> > likely to skip past, scared away by the parentheses and lack of a
> > thorough introduction.
> 
> I propose placing a link from the guile page to an on-line copy of the
> Prentice Hall book which is reproduced there with the permission of
> the publisher.

It's my opinion (and I could be _quite_ wrong on this) that users don't
really care about the language/implementation distinction.  They use
Perl; they use Python; they use Common Lisp; they use Guile.  They don't
want to have to keep in mind `this is the core of the language, while
that is an implementation-specific add-on.'  And really, they're kind of
right: just as there is a commonality between Common Lisp and Scheme, so
too there is a commonality between e.g. guile, gambit and SCM--but from
the user's point of view, they're not-quite-compatible & thus different.

What users want, I believe, is not an `introduction to Scheme,' but
rather an `introduction to guile.'  The former tells them about a
language; the latter tells them how to solve their problems.  I'm not
saying that viewpoint is necessarily right or wrong, but it's my
perception of what is in fact the case.

-- 
Robert Uhl <ruhl@4dv.net>
Christ is Risen!  Truly He is Risen!


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Robert Uhl]

rm@fabula.de writes:
>
> > Well, most of them seem to either be print books (which cost dough),
> > or written specifically for some incompatible dialect.
> 
> ??? "Teach yourself Scheme in fixnum day" is free and takes greate
> care *not* to be dialect specific.  SICP is available online as well
> ...

But that introduces the _language_, not the _implementation_.  Most
users don't care about the language, but rather about how to solve their
problems.  Or at least that's what I think.  What's really needed is an
`introduction to problem solving with guile,' which teaches Scheme
(necessarily) and guile's extensions thereto (necessarily), and doesn't
particularly distinguish--because, I feel, most users don't really care.

> I don't know.  Somehow i have the feeling that a Scheme based
> scripting language will never be as popular as Perl or Python etc.

Probably not.  But not necessarily.  After all, elisp has done pretty
well, driven by the killer app emacs; if more and more apps use guile as
an extension language, then people will become accustomed to extending
apps in Scheme, and we'll all reap the benefits.

OTOH, were Python a little more advanced (i.e. an exact analogue of
Scheme, incl. macros and all) and a _lot_ faster, I'd probably be
tempted to go with it despite its warts.

-- 
Robert Uhl <ruhl@4dv.net>
Cristo Resucitado!  En Verdad Resucitado!


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Thien-Thi Nguyen]

   From: Robert Uhl <ruhl@4dv.net>
   Date: 04 May 2003 15:42:15 -0600

   most users don't really care.

people only care when things go wrong and then they care a lot.

thi


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "Ricard" == Ricard Mira <ricardmm@tiscali.es> writes:

    Ricard> Thanks.  I think that I need to learn more about Guile in
    Ricard> order to be able to propose something sound, but I can
    Ricard> give my opinion as a user.

    Ricard> As a user who is learning Scheme to customize and extend
    Ricard> Guile-using programs, I expect the Guile documentation to
    Ricard> contain a section for each programming language (C and
    Ricard> Scheme for sure; translated languages maybe).  Then I need
    Ricard> to read just the Scheme section (and maybe also a general
    Ricard> introduction).

Interesting.  It was my idea to document the whole Guile API in the
current unified way, covering both C and Scheme together, but I have
been wondering about whether that was a good decision.  In many cases
it seems to result in adding a subsection saying "And there are also
these related C functions and macros ...", which feels unsatisfactory.

    Ricard> Neil, are your half-formed thoughts the same as my
    Ricard> half-formed thoughts? :-)

Not obviously, no, but it may be that there is some underlying overlap
between them.

My latest thinking is that we could be a lot more concrete, even
proscriptive, about what Guile is for and how people should use it,
and that if we did so it would be a lot easier to clearly assess the
state of the documentation and to finish it off.  (Right now, IMO, a
it is difficult even to describe the documentation status.)

Specifically, I think we should (**) promote doing as much programming
as possible in Scheme, and restrict documentation of the C API to the
parts needed for interfacing Scheme to C code.  (To give a concrete
example from another thread, I see no need for people to write C code
that uses scm_internal_catch.)

If we did this, I think the natural high level documentation structure
would then be:

- Scheme reference documentation - more or less like the current Part
  IV, but Scheme only, not C.

- Task-based documentation describing everything needed for aspects of
  interfacing with C code:

  - writing and exporting primitives (in modules)

  - smobs, GC, lifetimes etc.

  - Guile initialization from within a library

  - how to call out to a Scheme-defined procedure

  - how to look up a Scheme-defined variable

  - how to evaluate user-supplied code and catch errors

  - (anything else that I've missed).

Which has something in common with your thoughts.

That's what I'm thinking now, anyway.  I think (**) may be quite
controversial, so that at least needs a lot more discussion first.

Regards,
        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "rm" == rm  <rm@fabula.de> writes:

    rm> I started writing up some info last night but i'm not shure
    rm> whether the lack of documentation actually manifests some
    rm> public vs. private API issue.

Now, no, it just manifests lack of documentation, I'm afraid :-)

In the future, though, I do think it would be nice to reach a
situation where

         documented <=> public and supported API

    rm> Hmm, there a a handfull of pretty good Scheme intros
    rm> available, why bother duplicating these efforts (better: write
    rm> a Guile-specific addendum for one of these).

Tricky one, but I think if we get the rest of the GUile docs right,
and bring more users on board, the need (or not) for this will become
clearer.

    rm> Yes. And it would be _very_ helpfull if the documentation
    rm> would mention what modules need to be "used" for certain
    rm> functions [(ice-9 regexp) for regular expressions ...).

Completely agree; it's just a bug if the necessary use-module isn't
documented.  Patches welcome!

    rm> Another question: there's some very good information in the
    rm> guile-workbook CVS module. But sometimes it's hard to tell
    rm> whether a piece is documenting an existing fact of Guile or
    rm> rather proposing a new impementation.

IMO the starting assumption should be that workbook stuff is not
implemented and so not valid as documentation.  If you can identify
any text that is valid, then ideally, please convert it to a patch
against the manual.

Regards,
        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Rob Browning]

Neil Jerram <neil@ossau.uklinux.net> writes:

> Specifically, I think we should (**) promote doing as much programming
> as possible in Scheme, and restrict documentation of the C API to the
> parts needed for interfacing Scheme to C code.  (To give a concrete
> example from another thread, I see no need for people to write C code
> that uses scm_internal_catch.)

I'm not sure how commonly this is an issue, but how hard would this be
on people who are just writing C code (say perhaps for a shared lib or
an object file that was intended to be used by apache (or whatever) as
a dynamic module, i.e. mod_guile)?

In particular, are there cases where it's hard to support having
(finding) any .scm file, and if so, in those cases, what's the
preferred solution -- embedded scheme strings that are evaled at
runtime, or when you need something with more dynamic content,
building the scheme form representing your function (or whatever) and
then calling eval on that?  I'm not sure this applies to
scm_internal_catch, but just wanted to make sure we had thought about
the likelihood of such a situation.

> That's what I'm thinking now, anyway.  I think (**) may be quite
> controversial, so that at least needs a lot more discussion first.

I think one counter argument would be "where do people who want to
write C extensions to Guile go for documentation?".

As an example, if you want to write a big complex smob for something
that's a heterogeneous collection of both C and scheme data, you may
well need to use any number of scm_* functions to manipulate the
smob's data structures from the C side, and you'd certainly want to
have documentation for those functions.

If it weren't for the fact that it could be a lot of extra work
(unless we could somehow automate much of the process), it seems like
a solution would be to have one main section that was Scheme oriented,
with a structure and composition similar to what you described, and
one main section which was "Guile from the C side".

Of course there would be a lot of duplicated text between the sections
since, for example, you'd have to document scm_list_p and list? in
separate sections with essentially the same text.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Doc organization (Re: Around again, and docs lead role)

[rm]

THANKS, Rob!

On Thu, May 08, 2003 at 11:21:12AM -0500, Rob Browning wrote:
> Neil Jerram <neil@ossau.uklinux.net> writes:
> 
> > Specifically, I think we should (**) promote doing as much programming
> > as possible in Scheme, and restrict documentation of the C API to the
> > parts needed for interfacing Scheme to C code.  (To give a concrete
> > example from another thread, I see no need for people to write C code
> > that uses scm_internal_catch.)
> 
> I'm not sure how commonly this is an issue, but how hard would this be
> on people who are just writing C code (say perhaps for a shared lib or
> an object file that was intended to be used by apache (or whatever) as
> a dynamic module, i.e. mod_guile)?

This is pretty much the position i'm in -- writing C extensions for
Guile (currently Guile bindings for the neon http/WebDAV client library.
Should be out as soon as Tomas made my crap working and recovered from
RFC shock :) I myself (and probably many others) really need more 
information on the C side of Guile. A lot of if not most of my code 
deals with data conversion from Scheme <--> C and verso. 
Right now i'm looking for _the_ Guile way of converting a SCM real number
to a C IEEE float (any help?).


> In particular, are there cases where it's hard to support having
> (finding) any .scm file, and if so, in those cases, what's the
> preferred solution -- embedded scheme strings that are evaled at
> runtime, 

now, that would be _really_ clumsy.

> or when you need something with more dynamic content,
> building the scheme form representing your function (or whatever) and
> then calling eval on that?  I'm not sure this applies to
> scm_internal_catch, but just wanted to make sure we had thought about
> the likelihood of such a situation.

Even in my very humble attempts in coding i had to build/manipulate
modules/environments from C. Evaluating user code in a save environment
is absolutely neccessary as well a catching errors in user-provided
Scheme code (callbacks, in the case of the neon bindings).

> > That's what I'm thinking now, anyway.  I think (**) may be quite
> > controversial, so that at least needs a lot more discussion first.

Not enough time to comment on that right now (but i have to 
admit that i hate it when languages try to be too pedagogic ...)

> 
> I think one counter argument would be "where do people who want to
> write C extensions to Guile go for documentation?".

> As an example, if you want to write a big complex smob for something
> that's a heterogeneous collection of both C and scheme data, you may
> well need to use any number of scm_* functions to manipulate the
> smob's data structures from the C side, and you'd certainly want to
> have documentation for those functions.
> 
> If it weren't for the fact that it could be a lot of extra work
> (unless we could somehow automate much of the process), it seems like
> a solution would be to have one main section that was Scheme oriented,
> with a structure and composition similar to what you described, and
> one main section which was "Guile from the C side".

I thought a lot about this problem recently (unfortunately with no
clear outcome :-/) 
Maybe a 3-book approach:

 - Guile for the scripter (user of an embedded Guile using application
   who want's to write scripts -- Scheme only).

 - Guile for the embedder/extender: people like my who write bindings
   or pplications that use Guile (focus on memory management and
   data conversion etc.).

 - Guile hacker: for people working on the Guile core.

> Of course there would be a lot of duplicated text between the sections
> since, for example, you'd have to document scm_list_p and list? in
> separate sections with essentially the same text.


Just my 0.002$

   Ralf Mattes

> -- 
> Rob Browning
> rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
> Previously @cs.utexas.edu
> GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4
> 
> 
> _______________________________________________
> Guile-user mailing list
> Guile-user@gnu.org
> http://mail.gnu.org/mailman/listinfo/guile-user


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

State of Docs [was] Re: Around again, and docs lead role

[rm]

On Wed, May 07, 2003 at 11:52:46PM +0100, Neil Jerram wrote:
> >>>>> "rm" == rm  <rm@fabula.de> writes:
> 
>     rm> I started writing up some info last night but i'm not shure
>     rm> whether the lack of documentation actually manifests some
>     rm> public vs. private API issue.
> 
> Now, no, it just manifests lack of documentation, I'm afraid :-)
> In the future, though, I do think it would be nice to reach a
> situation where
> 
>          documented <=> public and supported API

Yes. Right now, whenever i stumble upon a usefull but undocumented
part of the Guile API i'm somehow reluctant to use it since i fear
that it's not as stable as the documented part.
Who to consult in such a case? Guile-devel or Guile-user?


>     rm> Hmm, there a a handfull of pretty good Scheme intros
>     rm> available, why bother duplicating these efforts (better: write
>     rm> a Guile-specific addendum for one of these).
> 
> Tricky one, but I think if we get the rest of the GUile docs right,
> and bring more users on board, the need (or not) for this will become
> clearer.

Yes, i would assume that it's up to those who write the documentation
for guile-embedding applications to provide helpfull intros/tutorials.
After all: most general Scheme tutorials will present things like
'my-fact' or 'is-prime?' while users probably want to read about
'print-in-blue' or 'image-blur' ....

>     rm> Yes. And it would be _very_ helpfull if the documentation
>     rm> would mention what modules need to be "used" for certain
>     rm> functions [(ice-9 regexp) for regular expressions ...).
> 
> Completely agree; it's just a bug if the necessary use-module isn't
> documented.  Patches welcome!

Ok, next time i find one ...
BTW, in case i have a documentation patch: where to send it to?
Post it here?

>     rm> Another question: there's some very good information in the
>     rm> guile-workbook CVS module. But sometimes it's hard to tell
>     rm> whether a piece is documenting an existing fact of Guile or
>     rm> rather proposing a new impementation.
> 
> IMO the starting assumption should be that workbook stuff is not
> implemented and so not valid as documentation.  If you can identify
> any text that is valid, then ideally, please convert it to a patch
> against the manual.

Finally, a proposal: I think it would be rather helpfull if the
documentation for C functions as well as CPP makros would include
the type specifier. So, instead of:

 scm_make_vector (k, fill)

give

 scm_c_make_vector (unsigned long int k, SCM fill)

Not having the parameter types is sometimes missleading, esp. if
the same parameter name sometimes stands for a C value and sometimes
for a SCM value (see for ex.: 'scm_vector_set_x vector k obj',  where 'k'
stands for SCM value).
I'm willing to take over that job and update the relevant parts over
the next few weeks if people find this helpfull.

Thanks,

    Ralf
    


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "Rob" == Rob Browning <rlb@defaultvalue.org> writes:

    Rob> Neil Jerram <neil@ossau.uklinux.net> writes:
    >> Specifically, I think we should (**) promote doing as much programming
    >> as possible in Scheme, and restrict documentation of the C API to the
    >> parts needed for interfacing Scheme to C code.  (To give a concrete
    >> example from another thread, I see no need for people to write C code
    >> that uses scm_internal_catch.)

    Rob> I'm not sure how commonly this is an issue, but how hard
    Rob> would this be on people who are just writing C code (say
    Rob> perhaps for a shared lib or an object file that was intended
    Rob> to be used by apache (or whatever) as a dynamic module,
    Rob> i.e. mod_guile)?

Well yes, this is exactly what we need to establish.  But, to take
mod_guile as an example, surely it's much easier to pass the whole
page out to Scheme and process it there, than to do processing mostly
in C?

    Rob> In particular, are there cases where it's hard to support
    Rob> having (finding) any .scm file,

There probably are - for example embedded OSs with no filesystem - but
I doubt that it is a priority to cater for them.

To me, if defeats the whole object of Guile if catering for this case
means that it is harder to improve Guile and its docs for the other
99% of cases.  To avoid this happening, I suggest that we could solve
this problem by a mechanism that links Scheme code into a library or
executable at build time.  This could be something like unexec (in
which case the source would already have been read and stored in tree
code), or it could be a linker tool that just dumps plain source code
into the binary - as though it was a big const char[], but more
convenient to use at build time.

    Rob> and if so, in those cases, what's the preferred solution --
    Rob> embedded scheme strings that are evaled at runtime, or when
    Rob> you need something with more dynamic content, building the
    Rob> scheme form representing your function (or whatever) and then
    Rob> calling eval on that?

Embedded Scheme is OK for small code fragments, otherwise as just
suggested above.  As far as dynamic content is concerned, is there any
kind of dynamic Scheme content that can't be generated and then eval'd
by a chunk of static Scheme code?  (I don't think so, if it could be
generated by a chunk of static C code.)

    Rob> I'm not sure this applies to scm_internal_catch, but just
    Rob> wanted to make sure we had thought about the likelihood of
    Rob> such a situation.

Absolutely.  What I've half-proposed is quite radical, so it's crucial
to think it through carefully.

To throw out another example: libguile currently has a set of
old-fashioned primitives for manipulating object properties
(scm_set_object_properties_x etc.).  These should be deprecated in
favour of the make-object-property mechanism, but it's currently hard
to do this because the functions are part of the C API and so might be
being used by someone's C code.  If, on the other hand, these
primitives were officially provided only on the Scheme level, it would
be trivial to replace them with Scheme implementations written using
make-object-property.

    >> That's what I'm thinking now, anyway.  I think (**) may be quite
    >> controversial, so that at least needs a lot more discussion first.

    Rob> I think one counter argument would be "where do people who want to
    Rob> write C extensions to Guile go for documentation?".

C extensions are covered by the documentation I've suggested, I
believe.  Specifically, that doc would describe how to write and
export C primitives, validate and convert parameters between C and
Scheme forms etc., how to create smobs, handle lifetime issues, ...

    Rob> As an example, if you want to write a big complex smob for something
    Rob> that's a heterogeneous collection of both C and scheme data, you may
    Rob> well need to use any number of scm_* functions to manipulate the
    Rob> smob's data structures from the C side, and you'd certainly want to
    Rob> have documentation for those functions.

Absolutely.  I think that data substructure manipulation functions
like scm_cons, SCM_CAR and SCM_CDR, should be included in the
documented C API.

    Rob> If it weren't for the fact that it could be a lot of extra work
    Rob> (unless we could somehow automate much of the process), it seems like
    Rob> a solution would be to have one main section that was Scheme oriented,
    Rob> with a structure and composition similar to what you described, and
    Rob> one main section which was "Guile from the C side".

Now that I've been involved for some time, I'm pretty sure that any
extra work will be insignificant compared to the long term cost of not
having the right overall focus and structure.  So I wouldn't worry
about the work yet.

    Rob> Of course there would be a lot of duplicated text between the sections
    Rob> since, for example, you'd have to document scm_list_p and list? in
    Rob> separate sections with essentially the same text.

True, but I think it might make sense in context anyway.

Thanks for your thoughts,

        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "rm" == rm  <rm@fabula.de> writes:

    rm> This is pretty much the position i'm in -- writing C
    rm> extensions for Guile (currently Guile bindings for the neon
    rm> http/WebDAV client library.  Should be out as soon as Tomas
    rm> made my crap working and recovered from RFC shock :) I myself
    rm> (and probably many others) really need more information on the
    rm> C side of Guile. A lot of if not most of my code deals with
    rm> data conversion from Scheme <--> C and verso.  Right now i'm
    rm> looking for _the_ Guile way of converting a SCM real number to
    rm> a C IEEE float (any help?).

I'm afraid I don't know how to do this, but data conversion is
definitely in the set of C API operations that I think should be
documented.

    rm> Even in my very humble attempts in coding i had to build/manipulate
    rm> modules/environments from C. Evaluating user code in a save environment
    rm> is absolutely neccessary as well a catching errors in user-provided
    rm> Scheme code (callbacks, in the case of the neon bindings).

Absolutely, but this is possible and much easier to do from Scheme,
isn't it?

    >> > That's what I'm thinking now, anyway.  I think (**) may be quite
    >> > controversial, so that at least needs a lot more discussion first.

    rm> Not enough time to comment on that right now (but i have to 
    rm> admit that i hate it when languages try to be too pedagogic ...)

But it isn't pedagogy just for the sake of it.  I anticipate big
benefits in documentation and elsewhere, e.g. in the management of
updates between releases.

    rm> I thought a lot about this problem recently (unfortunately with no
    rm> clear outcome :-/) 
    rm> Maybe a 3-book approach:

    rm>  - Guile for the scripter (user of an embedded Guile using application
    rm>    who want's to write scripts -- Scheme only).

    rm>  - Guile for the embedder/extender: people like my who write bindings
    rm>    or pplications that use Guile (focus on memory management and
    rm>    data conversion etc.).

    rm>  - Guile hacker: for people working on the Guile core.

Yes, exactly, except that in practice the last of these may never
happen - and that isn't actually so bad, because for core hacking you
will probably need to read the code anyway.  In fact, the best
documentation for core hacking is probably extensive commenting in
difficult areas of the source.

    rm> Just my 0.002$

Thank you!

        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: State of Docs [was] Re: Around again, and docs lead role

[Neil Jerram]

>>>>> "rm" == rm  <rm@fabula.de> writes:

    rm> Yes. Right now, whenever i stumble upon a usefull but undocumented
    rm> part of the Guile API i'm somehow reluctant to use it since i fear
    rm> that it's not as stable as the documented part.
    rm> Who to consult in such a case? Guile-devel or Guile-user?

guile-devel, I'd say.  Although arguably you will always get the
answer yes, as the current position (I think) is that everything
exported by libguile is part of the API and therefore usable.

    rm> Yes, i would assume that it's up to those who write the documentation
    rm> for guile-embedding applications to provide helpfull intros/tutorials.
    rm> After all: most general Scheme tutorials will present things like
    rm> 'my-fact' or 'is-prime?' while users probably want to read about
    rm> 'print-in-blue' or 'image-blur' ....

Agreed.

    rm> BTW, in case i have a documentation patch: where to send it to?
    rm> Post it here?

Strictly, bug-guile@gnu.org.  But I don't think it would get lost if
you sent it to guile-devel instead.

    rm> Finally, a proposal: I think it would be rather helpfull if the
    rm> documentation for C functions as well as CPP makros would include
    rm> the type specifier. So, instead of:

    rm>  scm_make_vector (k, fill)

    rm> give

    rm>  scm_c_make_vector (unsigned long int k, SCM fill)

    rm> Not having the parameter types is sometimes missleading,
    rm> esp. if the same parameter name sometimes stands for a C value
    rm> and sometimes for a SCM value (see for ex.: 'scm_vector_set_x
    rm> vector k obj', where 'k' stands for SCM value).  I'm willing
    rm> to take over that job and update the relevant parts over the
    rm> next few weeks if people find this helpfull.

I may be wrong, but I don't think there's any ambiguity in the current
docs.  Wherever a type specifier is omitted, it should be understood
as SCM.  (The reason for this is a makeinfo restriction: makeinfo
can't handle a @deffn followed by a @deftypefnx.)

I think the real problem is that, in many cases, the C level function
like scm_c_make_vector isn't documented.  I completely agree that it
should be, and that its type specifiers should be shown explicitly.

Does this make sense?

        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Rob Browning]

Neil Jerram <neil@ossau.uklinux.net> writes:

> To me, if defeats the whole object of Guile if catering for this case
> means that it is harder to improve Guile and its docs for the other
> 99% of cases.  To avoid this happening, I suggest that we could solve
> this problem by a mechanism that links Scheme code into a library or
> executable at build time.  This could be something like unexec (in
> which case the source would already have been read and stored in tree
> code), or it could be a linker tool that just dumps plain source code
> into the binary - as though it was a big const char[], but more
> convenient to use at build time.

That could be interesting.  To some extent how we decide to handle
compilation will factor in here.

If you thought large static scm fragments, were likely to be common, I
guess one thing that might make hacking easier would be an easy way to
do something equivalent to #include <foo.scm>, i.e. a way you could
hack the scheme part as a scheme file, but then have the code end up
incorporated in and evaled by the .so file.  Of course I guess anyone
could hack something like that up if they needed to with a makefile
and appropriate use of "cat"...

Actually, I've been playing around with code that would make something
like this possible (as a dumb example):

  (define (double x)
    (c-syntax
      (if ("SCM_INUMP" x)
          (return (* x x))
          (return ("scm_apply" ("scm_lookup" "+") x x)))))

and that already works for

  (%function "main" int ((int argc) ((%array (* char)) argv))
    ("printf" "Hello world\\n"))

etc. (i.e. a C s-expression representation), but I'm not sure how
likely it is that anyone else would find it amusing.  I can think of a
few possible uses for such a construction (g-wrap, auto-ffi,
"c-side"-macros, scm-to-C-compiler-back-end, c equiv of inline-asm),
but I'm still not sure it's really worthwhile.  I might comment more
later if I remain intrigued...

> Embedded Scheme is OK for small code fragments, otherwise as just
> suggested above.  As far as dynamic content is concerned, is there any
> kind of dynamic Scheme content that can't be generated and then eval'd
> by a chunk of static Scheme code?  (I don't think so, if it could be
> generated by a chunk of static C code.)

Not sure.  As long as you're not limited to eval_str -- i.e. as long
as you have eval_form, then perhaps not.

> Absolutely.  I think that data substructure manipulation functions
> like scm_cons, SCM_CAR and SCM_CDR, should be included in the
> documented C API.

Sure, but I was wondering what else might be needed.  Of course I'm
not sure I have a clear idea of what kind of things might be
omitted...

> Now that I've been involved for some time, I'm pretty sure that any
> extra work will be insignificant compared to the long term cost of not
> having the right overall focus and structure.  So I wouldn't worry
> about the work yet.

Focus is good.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[tomas]

On Wed, May 07, 2003 at 10:06:57PM +0100, Neil Jerram wrote:

[...]

> Interesting.  It was my idea to document the whole Guile API in the
> current unified way, covering both C and Scheme together, but I have
> been wondering about whether that was a good decision.  In many cases
> it seems to result in adding a subsection saying "And there are also
> these related C functions and macros ...", which feels unsatisfactory.

There have been good answers to this elsewhere. As long as there is
a (not necessarily exhaustive) good correspondence between C functions
and Guile (with a way to know when to expect what), I'm fine.

[...]

> Specifically, I think we should (**) promote doing as much programming
> as possible in Scheme, and restrict documentation of the C API to the
> parts needed for interfacing Scheme to C code.  (To give a concrete
> example from another thread, I see no need for people to write C code
> that uses scm_internal_catch.)

[...]

> That's what I'm thinking now, anyway.  I think (**) may be quite
> controversial, so that at least needs a lot more discussion first.

To take the other side of the controverse ;-)

There have been comments on this elsewhere already, mentioning
mod-guile. I won't repeat those. What seemed missing to me (or
I was asleep while reading, actually this happens .-)

Embedding Guile in applications like Apache or PostgreSQL[1] poses
some constraints: Guile won't be the only embedded language. Those
applications bring along services for error handling, which you
better use (e.g. aborting a transaction/erroring out in an HTTP
request/response cycle), for consistency. So it might be most
natural to catch errors at the C level. If that is not desirable
from a Guile POV, then there should be at least a ``recommended
canonical way'' (say: a C function calling a Guile wrapper
calling...). And this might be provided as convenience library.
But then, it could be provided in the first place :-)

I'd even go a step further: for the embedded scripting language
to play really nicely in those two cases, it'd be desirable to
be able to adapt the garbage collector to the transaction-based
memory model: much of the memory used just lives for a transaction,
and that's why they allocate memory in `pools', which just disappear
after the transaction is done. But this might be just wishful
thinking...

--------
[1] I'm talking of embedding Guile in the PostgreSQL server, not
    of a libpq interface


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Bill Schottstaedt]

>  (To give a concrete
> example from another thread, I see no need for people to write C code
> that uses scm_internal_catch.)

I use scm_internal_stack_catch a lot (and can't see any need for
Guile to remove it...) -- I pass closures/functions/user scheme code
around in C, as well as providing a "listener" where anything
might happen -- this would be clumsy to implement with some
callback to scheme (and no easier to write in scheme than in
C -- the tricky part is good error handling which Guile flubs
miserably anyway).  Why try to force people to write
scheme?  It seems to me that you're defeating the whole purpose
of Guile just to simplify its documentation.

Or to put it another way, if you don't have the C-level catch mechanism,
you better not use scm_apply or anything related to it.  That leaves
scm_num2int?


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[David Van Horn]

Rob Browning wrote:

> Actually, I've been playing around with code that would make something
> like this possible (as a dumb example):
> 
>   (define (double x)
>     (c-syntax
>       (if ("SCM_INUMP" x)
>           (return (* x x))
>           (return ("scm_apply" ("scm_lookup" "+") x x)))))
> 
> and that already works for
> 
>   (%function "main" int ((int argc) ((%array (* char)) argv))
>     ("printf" "Hello world\\n"))
> 
> etc. (i.e. a C s-expression representation), but I'm not sure how
> likely it is that anyone else would find it amusing.  I can think of a
> few possible uses for such a construction (g-wrap, auto-ffi,
> "c-side"-macros, scm-to-C-compiler-back-end, c equiv of inline-asm),
> but I'm still not sure it's really worthwhile.  I might comment more
> later if I remain intrigued...

Are you familiar with the Gambit-C FFI?  This allows you to write, eg.

   (define fmod (c-lambda (double double) double "fmod"))

Type checking and conversion are done for you.  I think it's a rather nice tool.

   Gambit-C: Interface to C
   http://www.iro.umontreal.ca/~gambit/doc/gambit-c.html#SEC27

PLT Scheme supports a subset of this, namely `c-lambda' and `c-declare'.

   MzScheme Compiler Manual: Foreign-Function Interface to C
   http://download.plt-scheme.org/doc/203/html/mzc/mzc-Z-H-2.html#%_chap_2

A Gambit-C style back-end to FFIGEN would be rather useful, especially if
three Schemes supported the emitted code.  I believe there has been some work
done to this end, but I can't seem to find mention of it beyond the to-do list
of FFIGEN.

   FFIGEN
   http://www.ccs.neu.edu/home/lth/ffigen/

-d



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: State of Docs

[Kevin Ryde]

Neil Jerram <neil@ossau.uklinux.net> writes:
>
> The reason for this is a makeinfo restriction: makeinfo
> can't handle a @deffn followed by a @deftypefnx.

Perhaps we can lobby for that to be relaxed.  I see something like

	@deftypefn {Scheme Procedure} {} foo ...

comes out with an unattractive extra space

	- Scheme Procedure:  foo ...

perhaps just getting rid of that would do the trick.


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "Rob" == Rob Browning <rlb@defaultvalue.org> writes:

    Rob> Neil Jerram <neil@ossau.uklinux.net> writes:
    >> To avoid this happening, I suggest that we could solve this
    >> problem by a mechanism that links Scheme code into a library or
    >> executable at build time.  This could be something like unexec
    >> (in which case the source would already have been read and
    >> stored in tree code), or it could be a linker tool that just
    >> dumps plain source code into the binary - as though it was a
    >> big const char[], but more convenient to use at build time.

    Rob> That could be interesting.  To some extent how we decide to
    Rob> handle compilation will factor in here.

Yes.

    Rob> If you thought large static scm fragments, were likely to be
    Rob> common, I guess one thing that might make hacking easier
    Rob> would be an easy way to do something equivalent to #include
    Rob> <foo.scm>, i.e. a way you could hack the scheme part as a
    Rob> scheme file, but then have the code end up incorporated in
    Rob> and evaled by the .so file.  Of course I guess anyone could
    Rob> hack something like that up if they needed to with a makefile
    Rob> and appropriate use of "cat"...

#include <foo.scm> would be very nice, but we'll probably need
something more dynamic as well.  I don't see what you mean by cat
though.

    Rob> Actually, I've been playing around with code that would make something
    Rob> like this possible (as a dumb example):

    Rob>   (define (double x)
    Rob>     (c-syntax
    Rob>       (if ("SCM_INUMP" x)
    Rob>           (return (* x x))
    Rob>           (return ("scm_apply" ("scm_lookup" "+") x x)))))

I don't see how this helps - please explain.

    Rob> Sure, but I was wondering what else might be needed.  Of course I'm
    Rob> not sure I have a clear idea of what kind of things might be
    Rob> omitted...

I don't have a very clear idea myself yet.  The main category in my
mind so far is almost all primitives - e.g. scm_catch, scm_setgid,
scm_set_object_properties_x - some exceptions being those concerned
with dissecting and constructing data - e.g. scm_cons, scm_list_p,
SCM_CAR, scm_vector.

Regards,
        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "tomas" == tomas  <tomas@fabula.de> writes:

    >> Interesting.  It was my idea to document the whole Guile API in the
    >> current unified way, covering both C and Scheme together, but I have
    >> been wondering about whether that was a good decision.  In many cases
    >> it seems to result in adding a subsection saying "And there are also
    >> these related C functions and macros ...", which feels unsatisfactory.

    tomas> There have been good answers to this elsewhere. As long as
    tomas> there is a (not necessarily exhaustive) good correspondence
    tomas> between C functions and Guile (with a way to know when to
    tomas> expect what), I'm fine.

Not sure I understand.  Are you saying that the relationship between
how one codes a primitive in C, and how one calls it in Scheme, should
be clearly described?  If so, I agree.

    >> That's what I'm thinking now, anyway.  I think (**) may be quite
    >> controversial, so that at least needs a lot more discussion first.

    tomas> To take the other side of the controverse ;-)

    tomas> There have been comments on this elsewhere already, mentioning
    tomas> mod-guile. I won't repeat those. What seemed missing to me (or
    tomas> I was asleep while reading, actually this happens .-)

    tomas> Embedding Guile in applications like Apache or PostgreSQL[1] poses
    tomas> some constraints: Guile won't be the only embedded language. Those
    tomas> applications bring along services for error handling, which you
    tomas> better use (e.g. aborting a transaction/erroring out in an HTTP
    tomas> request/response cycle), for consistency. So it might be most
    tomas> natural to catch errors at the C level. If that is not desirable
    tomas> from a Guile POV, then there should be at least a ``recommended
    tomas> canonical way'' (say: a C function calling a Guile wrapper
    tomas> calling...). And this might be provided as convenience library.
    tomas> But then, it could be provided in the first place :-)

With ``recommended canonical way'' you've hit the nail on the head as
far as I'm concerned.  The main point of my whole argument is that
there are currently no recommended ways of using Guile, and that makes
it (i) jolly difficult to document - especially for more inexperienced
developers (ii) difficult to clearly define the API and so manage API
changes between releases.

To consider your example ...  Although it might be most immediately
natural to catch and dispatch errors at the C level, I would recommend
a ``canonical'' organization like this: (I'm assuming here that the
basic operation of mod_guile is to translate a mod_guile HTML page
into vanilla HTML)

- Define primitives that wrap the applications' mechanisms for
  reporting errors.  Now you can signal those errors from Scheme.

- Define a Scheme procedure that does the whole translation operation:

  (translate-page INPUT) -> OUTPUT

  This procedure can signal application errors as/when it needs to.

- From C, just call out to translate-page, and return its result to
  Apache.

This may be a bit harder to begin with than writing everything in C.
But once this structure is in place, your scope for rapidly adding
further enhancements is much greater, because all the interesting code
is in Scheme, not C.

    tomas> I'd even go a step further: for the embedded scripting language
    tomas> to play really nicely in those two cases, it'd be desirable to
    tomas> be able to adapt the garbage collector to the transaction-based
    tomas> memory model: much of the memory used just lives for a transaction,
    tomas> and that's why they allocate memory in `pools', which just disappear
    tomas> after the transaction is done. But this might be just wishful
    tomas> thinking...

Sounds interesting, and maybe not too hard.  Is the following
possible?

    (let ((temp-heap (switch-to-new-heap)))
      ; This tell Guile's memory allocator to allocate a new heap
      ; and to make all memory allocations until further notice
      ; from this heap.

      (do-transaction-processing)
      ; During which all memory allocations come from the new heap.

      (gc-and-destroy-heap temp-heap)
      ; Perform a GC, assert that temp-heap now has nothing in use,
      ; destroy temp-heap and switch back to previous heap.
      )

Regards,
        Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Doc organization (Re: Around again, and docs lead role)

[tomas]

On Sat, May 10, 2003 at 01:01:44PM +0100, Neil Jerram wrote:
> >>>>> "tomas" == tomas  <tomas@fabula.de> writes:

[...]

> Not sure I understand.  Are you saying that the relationship between
> how one codes a primitive in C, and how one calls it in Scheme, should
> be clearly described?  If so, I agree.

Uh, sorry for my unclear wording. I meant to say that I don't see the need
for repetition as long as there is a way to guess the C name and usage from
the Scheme counterpart -- just document the exceptions. OTOH, having separate
docs for C and Scheme would be OK; I guess the transformation might be
script-supported.

>     >> That's what I'm thinking now, anyway.  I think (**) may be quite
>     >> controversial, so that at least needs a lot more discussion first.
> 
>     tomas> To take the other side of the controverse ;-)

[...]

> With ``recommended canonical way'' you've hit the nail on the head as
> far as I'm concerned.  The main point of my whole argument is that
> there are currently no recommended ways of using Guile, and that makes
> it (i) jolly difficult to document - especially for more inexperienced
> developers (ii) difficult to clearly define the API and so manage API
> changes between releases.

Yup. (In a way, it seems to be a fundamental Scheme characteristic,
do-it-yourself everywhere ;-)

> To consider your example ...  Although it might be most immediately
> natural to catch and dispatch errors at the C level, I would recommend
> a ``canonical'' organization like this: (I'm assuming here that the
> basic operation of mod_guile is to translate a mod_guile HTML page
> into vanilla HTML)
> 
> - Define primitives that wrap the applications' mechanisms for
>   reporting errors.  Now you can signal those errors from Scheme.
> 
> - Define a Scheme procedure that does the whole translation operation:
> 
>   (translate-page INPUT) -> OUTPUT
> 
>   This procedure can signal application errors as/when it needs to.
> 
> - From C, just call out to translate-page, and return its result to
>   Apache.
> 
> This may be a bit harder to begin with than writing everything in C.
> But once this structure is in place, your scope for rapidly adding
> further enhancements is much greater, because all the interesting code
> is in Scheme, not C.

Hmmm. There is more to an Apache module than just generating a HTML page.
(And actually, it's this ``more'' which really makes a module worthwile
wrt a CGI scripts, besides performance, that is):

As a request traverses different stages of processing within the web
server, it calls specialized hooks within the module, so the module
can handle authentication, path resolving and what not.

Now imagine I could catch script errors from within the C caller:
I could install a simple error handler in C to deliver the proper
error code to the client browser -- independently of my scripting
language.

[pooled/transaction oriented memory allocation model]

> Sounds interesting, and maybe not too hard.  Is the following
> possible?
> 
>     (let ((temp-heap (switch-to-new-heap)))
>       ; This tell Guile's memory allocator to allocate a new heap
>       ; and to make all memory allocations until further notice
>       ; from this heap.
> 
>       (do-transaction-processing)
>       ; During which all memory allocations come from the new heap.
> 
>       (gc-and-destroy-heap temp-heap)
>       ; Perform a GC, assert that temp-heap now has nothing in use,
>       ; destroy temp-heap and switch back to previous heap.
>       )

Wow, this is very tempting :-)

Regards
-- tomas


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "Bill" == Bill Schottstaedt <bil@ccrma.Stanford.EDU> writes:

    Bill> I use scm_internal_stack_catch a lot (and can't see any need
    Bill> for Guile to remove it...) -- I pass closures/functions/user
    Bill> scheme code around in C, as well as providing a "listener"
    Bill> where anything might happen -- this would be clumsy to
    Bill> implement with some callback to scheme (and no easier to
    Bill> write in scheme than in C

Yes, I see.  I think one could express what this code does nicely in
Scheme, but the maturity of the Snd code and the build time support
for Ruby as well as Guile would make the exercise hard and
unrewarding.  In this context, my suggestion is a bit like saying
"well if I were you I wouldn't start from here."

I still contend, though, that if the Guile docs had been clearer, more
complete and more "canonical" when you started writing Snd (or perhaps
adding Guile to Snd), you might naturally have written more of Snd in
Scheme and therefore created a more extensible, maintainable and
generally hackable program.  What do you think?

    Bill> -- the tricky part is good error handling which Guile flubs
    Bill> miserably anyway).

It does?  Can you give more details here?

    Bill> Why try to force people to write scheme?  It seems to me
    Bill> that you're defeating the whole purpose of Guile just to
    Bill> simplify its documentation.

Because:

- I believe that is the point of Guile: higher level languages lower
  your "hacktivation energy", to use an old quote

- I believe (therefore) that people will be more productive that way

- I think that promoting a canonical "way of using Guile" will help me
  (or someone else) to complete Guile's documentation clearly, which I
  think will attract more developers to using and improving Guile

- I think that one of Guile's current problems is managing API changes
  between releases.  If we can reasonably shrink the official API, it
  makes the problem easier.

    Bill> Or to put it another way, if you don't have the C-level
    Bill> catch mechanism, you better not use scm_apply or anything
    Bill> related to it.  That leaves scm_num2int?

I don't follow this.  What is wrong with the following?

In C:
   scm_call_1 (scm_c_lookup ("my-func"), str);

In Scheme:
   (define (my-func str)
     (catch #t
       (lambda ()
         ... whatever ...)
       (lambda (key . args)
         ... handle errors ...)))

Thanks for your input.  (And please don't worry - everything I've said
is only suggestions - there are no plans to implement any of it yet
(if ever).)

        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Viktor Pavlenko]

>>>>> "NJ" == Neil Jerram <neil@ossau.uklinux.net> writes:

    NJ> I don't follow this.  What is wrong with the following?

    NJ> In C:
    NJ>    scm_call_1 (scm_c_lookup ("my-func"), str);

    NJ> In Scheme:
    NJ>    (define (my-func str)
    NJ>      (catch #t
    NJ>        (lambda ()
    NJ>          ... whatever ...)
    NJ>        (lambda (key . args)
    NJ>          ... handle errors ...

... and tell the calling C function about the error somehow...

    NJ>                               )))

But the exception mechanism is much more advanced.

I use scm_internal_catch to convert guile exceptions to C++, and try
{...} catch () { scm_throw(); } in gsubr to convert C++ exceptions to
guile. I call guile and C++ procedures from one another and, since
it's a C++ program that uses guile as extension, have to deal only
with C++ exceptions. A guile script would receive just guile errors.

IMO, error handling mechanism in guile's C API is great, it just needs
some docs and examples.

Re. encouraging people to do more things in Scheme, I agree, but not
by taking away a possibility to do it in C.

Just my opinion.

-- 
Viktor


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Bill Schottstaedt]

> I still contend, though, that if the Guile docs had been clearer, more
> complete and more "canonical" when you started writing Snd (or perhaps
> adding Guile to Snd), you might naturally have written more of Snd in
> Scheme and therefore created a more extensible, maintainable and
> generally hackable program.  What do you think?

My original intention was to write the whole thing in Common Lisp (it's
part of a package of CL programs developed over the last 30 years or so),
but I didn't trust any of the CL-based GUI libraries, and didn't like
tcl, so (this being the mid-90's on an SGI), I opted for C/Motif (and
later added Gtk).  Craig Borezsky told me about Guile; this was before
version 1.3.4 -- Jim Blandy was the head of the group, and I liked the
way he thought (I must say I miss his influence...).  The code was
the documentation, so I followed my nose.  It's too late now to
invert the entire Snd program (it's currently about 220000 lines of
C and 75000 lines of Scheme), and I don't think it's needed anyway.

My take on Guile (which seems to me to have stalled out over the last
few years) is that the current developers think of it as an extended
shell-based interpreter, whereas I think of it as a way of extending a
C program -- I can't see any moral choice here.  So it's a "vision
thing" -- if I had time, I'd think about things like ratios, C-level
continuations (these almost work already), error handling cleanups
(Guile itself should never call exit or abort as a response to an
error -- this is a serious bug!), some nice way to reach into the
current scheme environment and pluck out scheme-level stuff (there's
code for this in Snd's snd-run.c which works for nearly every case
(not define* args), but it's not very pretty, and I wrote it only by
laboriously working through all the kinds of environments I could
find), an optimizer (snd-run.c easily beats Guile by factors of 10 or
20), etc.

>    Bill> -- the tricky part is good error handling which Guile flubs
>    Bill> miserably anyway).
>
> It does?  Can you give more details here?

It's a long story.  Here's a short portion: if you try to piggy-back
on the built-in error types, you are at the mercy of silly problems
like the fact that simple_format exits if it gets an extra argument!
And the error output is ugly.  And it's hard to redirect it or add
info -- and I'm still not sure about backtraces.

> I think that one of Guile's current problems is managing API changes
>  between releases.  If we can reasonably shrink the official API, it
>  makes the problem easier.

Agreed, but I think this can be done without removing functionality.
(This problem was the reason for the "xen" macros -- I almost never
call any scm/gh thing directly -- once written, however, it made it
easy to add Ruby).  I complained earlier about the API changes only in the
context of a heated exchange about scm_num2int, which I still think
is broken.

> I don't follow this.  What is wrong with the following?
>
> In C:
>   scm_call_1 (scm_c_lookup ("my-func"), str);
> In Scheme:
>   (define (my-func str)
>     (catch #t

Leaving aside questions of speed and simplicity?  (Snd is a sound
editor which means I'm dealing with gobs of data -- no time to go
through all the leisurely consing and unboxing and name lookups and
whatnot that Scheme indulges in -- speed is essential in this
context).  But, I guess the basic problem is that I already have what
I want in C, and I want a way to make it available programmatically at
"run time"; I thought that was the whole idea of Guile.  There are
already plenty of scripting languages and Scheme interpreters.

> Thanks for your input.  (And please don't worry - everything I've said
> is only suggestions - there are no plans to implement any of it yet
> (if ever).)

And I apologize for the loaded word "subvert" -- as soon as I clicked
"send" I wished I had used "change" or something.

If only I had the time, I'd write something about how I'm using
Guile (there's a section in Snd's grfsnd.html, but it's only
a tiny start) -- I think Guile is a great start on a C extension
library.




_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Mikael Djurfeldt]

Bill Schottstaedt <bil@ccrma.Stanford.EDU> writes:

> My take on Guile (which seems to me to have stalled out over the last
> few years) is that the current developers think of it as an extended
> shell-based interpreter

Maybe this is totally out of context and misplaced---I just happened
to pass by your message and haven't followed this thread.

I include below the stated goals of Guile.  Even though I'm not a
particularly active developer right now, these are goals that I
support strongly, and I think most of the other developers do as well,
most notably Marius.  Even though we might have different biases with
regard to the goals, I don't think you need to worry that any of the
goals will get dropped.

My contribution to this discussion would be that there is no single
"canonical" way of using Guile.  Rather, there is a small handful of
canonical ways (which are reflected in the goals below).  Which way
you want to use Guile is very much dependent upon your situation, and
it is a classic mistake to believe that your own perspective on things
is of generic applicability.  Therefore, it is not the role of Guile
to restrict Guile usage to a particular pattern.  We should instead
support the different ways in which people want to use Guile.

Personally, I started out having the framework of my applications
written in C++.  From this I've progressively moved toward doing more
and more on the Scheme level, and now I very much believe in using
"Guile as an integration platform".  But there are still things I need
to do on the C++ level, because it's just the hell of a lot of
computations (one run can take 2 days).  Since I still want to
simplify my work in this "low level layer" using "Guile as an
extension language library", an extensive C API is essential to me.
It is very easy to miss to realize this need if you haven't been in
the situation of simultaneously having hard performance requirements
and complex input/output data in your algorithm.

I therefore think that many of the ideas that were discussed before
initiating work on the current manual were very good: that the manual
should present Guile from a small set of viewpoints connected to the
small set of canonical ways to use Guile.  (Just to repeat things that
everybody know:) The reason why this was thought possible is that we
don't need to document Scheme primitives doubly because of a strict
correspondence between Scheme level and C level names.  The C API
section then only need to document the C specific portion.

Mikael

workbook/policy/goals.text
----------------------------------------------------------------------
This file states the goals of Guile.

* Goals of Guile

Guile is many things to many people.  It has multiple ways to approach
it: as a C library that provides an extension language, as a
programming language in its own right, as a interface to the operating
system, as an interactive shell, as a platform that integrates many
independent subsystems, or as the basis for other languages.

These different roles have a lot in common, but there are also some
opposing forces that need to be balanced.

Not everything of what is outlined below has been realized yet.  The
things that are missing will receive high priority from the
maintainers of Guile.  One thing that is not mentioned below because
it goes without saying is documentation.  It is of course a goal of
Guile to have high quality documentation.

More information about the current status of Guile and planned changed
can be found in the file "plans.text".

** Guile as an extension language library

Guile's primary aim is to provide a good extension language which is
easy to add to an application written in C for the GNU system.  This
means that it must export the features of a higher level language in a
way that makes it easy not to break them from C code.

For example, one important feature of Guile is automatic garbage
collection.  The C interface to the garbage collector makes it easy to
use its services for the data structures of the application itself.

** Guile as a programming language

It is an aim to support easy programming using Guile.  This includes
providing the powerful features of the programming language Scheme,
like garbage collection, dynamic types, hygienic macros and higher
order functions.

This also includes things that go beyond standard Scheme, like a
module system to manage multiple name spaces, a system for object
oriented programming, support for comfortable multi-threading, and
internationalization features like Unicode support.

To make it useful, Guile offers good performance.

** Guile as an interface to the operating system

Guile supports most of the POSIX system calls.  Most of Scsh is
available to Guile users and Guile programs.  Beyond POSIX, Guile also
makes available important system libraries like the graphical toolkit
Gtk+.

** Guile as an interactive shell

Guile provides a command line interface with readline support.  The
interactive features of the programming language allow you to
incrementally alter a running system.  A integrated debugger allows
you to analyze such a running system in great detail.

Guile provides online documentation for most of its features.

Guile can also be controlled from Emacs.  This allows you to update
the definition of a function or some other object in a Guile process
with the touch of a few keys.  You have access to the documentation in
a context sensitive way.  It also integrates the debugger nicely into
your editing environment.

** Guile as an integration platform

With all the features describes above, Guile allows the implementation
of well behaved modules.  When most of an application is implemented
as modules with generality and re-usability in mind, Guile will be the
platform where the integration and reusing will take place.

Thus, Guile makes it easy to factor your application into well
separated modules and then finish it off by combining them with a thin
layer of Scheme code.

Guile has support for writing modules in C or other compiled
languages.

** Guile as a basis for other languages

Scheme is a very powerful language, which makes it possible
to implement other languages by translating them into Scheme.

By writing translators that convert various popular scripting
languages into Scheme, we can enable users to choose their favorite
languages for extending any program that provides extensibility using
Guile.


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Rob Browning]

Neil Jerram <neil@ossau.uklinux.net> writes:

>     Rob> hack something like that up if they needed to with a makefile
>     Rob> and appropriate use of "cat"...
>
> #include <foo.scm> would be very nice, but we'll probably need
> something more dynamic as well.  I don't see what you mean by cat
> though.

I hadn't thought very hard about it, but I meant that instead of
#include <foo.scm> in file foo.c (which would still require some
non-scheme code in foo.scm) you could do something primitive like
this:

  foo-real.c: foo-pre.c foo.scm foo-post.c
  	cat foo-pre.c > foo-real.c.tmp
  	echo 'startup_eval_code = "' >> foo-real.c.tmp
  	cat foo.scm >> foo-real.c.tmp
  	echo '";' >> foo-real.c.tmp
  	cat foo-post.c >> foo-real.c.tmp
  	mv foo-real.c.tmp foo-real.c

very ugly, of course (really too ugly), but something that could be
done right now.  I suppose you could also use perl, sed, etc. with
similar effect.
        
>     Rob> Actually, I've been playing around with code that would
>     Rob> make something like this possible (as a dumb example):
>
>     Rob>   (define (double x)
>     Rob>     (c-syntax
>     Rob>       (if ("SCM_INUMP" x)
>     Rob>           (return (* x x))
>     Rob>           (return ("scm_apply" ("scm_lookup" "+") x x)))))
>
> I don't see how this helps - please explain.

Well in one possible approach you'd be able to write a file that
contained both scheme and this "inline C" code.  That file would then
be compiled to object code via C.  In that arrangement, you wouldn't
need a separate file or a giant unwieldy C string for any large
embedded Scheme fragments. i.e. as a psuedo-example:

  (define (show-c-+ x y)
    (simple-format #t "In C (+ ~A ~A) would yield ~A\n"
                   x y
                   (c-style-int-+ x y)))

  (define (c-style-int-+ x y)
    (c-syntax
      (auto int c_x ("scm_num2int" 1 x %function-name))
      (auto int c_y ("scm_num2int" 1 y %function-name))
      (return ("scm_int2num" (+ c_x c_y)))))

Of course that's not the primary reason I've been playing around with
this, but it's another effect.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

Re: Doc organization (Re: Around again, and docs lead role)

[Paul Jarc]

Rob Browning <rlb@defaultvalue.org> wrote:
>   	echo 'startup_eval_code = "' >> foo-real.c.tmp
>   	cat foo.scm >> foo-real.c.tmp
>   	echo '";' >> foo-real.c.tmp

Just to be pedantic:
echo 'char const startup_eval_code[] = "\' >> foo-real.c.tmp
sed 's/\(["\\]\)/\\\1/g;s/$/\\n\\/' < foo.scm >> foo-real.c.tmp
echo '";' >> foo-real.c.tmp


paul


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Max Techter]

Mikael Djurfeldt <djurfeldt@nada.kth.se> writes:

> Bill Schottstaedt <bil@ccrma.Stanford.EDU> writes:
> 
> > My take on Guile (which seems to me to have stalled out over the last
> > few years) is that the current developers think of it as an extended
> > shell-based interpreter
> 
> Maybe this is totally out of context and misplaced---
snip 

        I don`t think so, Mikael. 

        Part of this thread stayed on documentation issues.

 
        I promised, to use my current first dive 
        into scheme and guile to produce 

        * critical remarks on the documentation 

        * a proposal for changes concerning the
          overall-layout of the documentation

        
        As I got it, 
        Neil thinks that "high level questions" about 
        documentation structure have to be dealt with. 

        
        Your mentioning of once formulated goals 
        for the guile project fits quite well. 


        
> I include below the stated goals of Guile.  Even though I'm not a
> particularly active developer right now, these are goals that I
> support strongly, and I think most of the other developers do as well,
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
snip 


        If this is the case, the introductory parts of the
        manual should directly reflect these goals, as you
        state below.
        (I would say the guile tutorial should do so too) 

        This would have accelerated my efforts to grasp the 
        guile concept and scope quite a bit. 
       
        
> My contribution to this discussion would be that there is no single
> "canonical" way of using Guile.  Rather, there is a small handful of
> canonical ways (which are reflected in the goals below).  
snip 


> I therefore think that many of the ideas that were discussed before
> initiating work on the current manual were very good: that the manual
> should present Guile from a small set of viewpoints connected to the
> small set of canonical ways to use Guile.
snip 


        I cut out your thoughts on the C API, 
        because I have no opinion on this issue yet.


> workbook/policy/goals.text
> ----------------------------------------------------------------------
> This file states the goals of Guile.
> 
> * Goals of Guile
> 

> ** Guile as an extension language library
> 

> ** Guile as a programming language
> 

> ** Guile as an interface to the operating system
> 

> ** Guile as an interactive shell
> 

> ** Guile as an integration platform
> 

> ** Guile as a basis for other languages
> 


        As a newbie I agree with Mikael's reasoning and
        conclusions.
        
        What goes against using this structure for the
        introduction part of the manual?
        
        Then --if possible-- reflecting it in the tutorial
        and maybe it could even be used as a pattern for
        subsequent parts of the manual.  I am not sure about
        this, but I bet most of the existing (and valuable)
        stuff of the documentation could be fitted in such a
        layout.

        It would be a structure a guile newbie could hang on
        to (I miss such a lifeline in the current manual),
        when coping with all those "strange new scheme and
        guile" concepts at once.


        
regards max.

PS:
        We would have to change the order: 
        
                programming language 
                        and 
                interactive interpreter 
        
        comes first, then 

                interface to os

        then the 
        
                advanced concepts: 
                        extension, integration, ...
                (already mentioned --in short-- at the top of cause) 


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: Doc organization (Re: Around again, and docs lead role)

[Thien-Thi Nguyen]

   From: rm@fabula.de
   Date: Thu, 8 May 2003 19:50:58 +0200

   Right now i'm looking for _the_ Guile way of converting a SCM real
   number to a C IEEE float (any help?).

below is one way (floating point stuff near the end).
see autoconf info pages for WORDS_BIGENDIAN.
improvements welcome (see "TODO").

thi


[cc trimmed]

__________________________________________________
/* binconv.c */

/*	Copyright (C) 2003 Free Software Foundation, Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this software; see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307 USA
 *
 * As a special exception, the Free Software Foundation gives permission
 * for additional uses of the text contained in its release of GUILE.
 *
 * The exception is that, if you link the GUILE library with other files
 * to produce an executable, this does not by itself cause the
 * resulting executable to be covered by the GNU General Public License.
 * Your use of that executable is in no way restricted on account of
 * linking the GUILE library code into it.
 *
 * This exception does not however invalidate any other reasons why
 * the executable file might be covered by the GNU General Public License.
 *
 * This exception applies only to the code released by the
 * Free Software Foundation under the name GUILE.  If you copy
 * code from other Free Software Foundation releases into a copy of
 * GUILE, as the General Public License permits, the exception does
 * not apply to the code that you add in this way.  To avoid misleading
 * anyone as to the status of such modified files, you must delete
 * this exception notice from them.
 *
 * If you write modifications of your own for GUILE, it is your choice
 * whether to permit this exception to apply to your modifications.
 * If you do not wish that, delete this exception notice.  */

\f

#include <stdio.h>
#include <string.h>
#include "libguile/_scm.h"
#include "libguile/validate.h"
#include "libguile/numbers.h"
#include "libguile/strings.h"
#include "libguile/modsup.h"

\f
/* Forward declarations on this page.  */

static void correct_strncpy (int cbep, unsigned char *dest,
                             unsigned char *source, size_t n);

static SCM system_big_endian_p (void);
extern void scm_init_database_binconv_module (void);

\f
/* Support macros.  */

#ifdef WORDS_BIGENDIAN
#define BEP SCM_BOOL_T
#define CBEP 1
#else
#define BEP SCM_BOOL_F
#define CBEP 0
#endif

#define SET_CBEP_MAYBE(cvar,scmvar) \
  cvar = SCM_UNBNDP (scmvar) ? CBEP : SCM_NFALSEP (scmvar)

\f
/* Support funcs.  */

static
void
correct_strncpy (int cbep,
                 unsigned char *dest, unsigned char *source,
                 size_t n)
{
  if (cbep == CBEP)
    strncpy (dest, source, n);
  else
    {
      int i;
      unsigned char *p = source + n - 1;

      for (i = 0; i < n; i++)
        *dest++ = *p--;
    }
}

\f
/* TODO:
   - Replace (ash 1 {16,32,64}) w/ small-table lookup.
   - Reduce scm_* usage; manipulate actual number representation.  */

MDEFLOCEXP (system_big_endian_p, "system-big-endian?", 0, 0, 0, (),
            "Return @code{#t} if the native encoding of numbers is\n"
            "big-endian for the machine running Guile, @code{#f} if\n"
            "the native encoding is little-endian.")
#define FUNC_NAME s_system_big_endian_p
{
  return BEP;
}
#undef FUNC_NAME

MDEFLOCEXP (ibs2integer, "integer-byte-string->integer", 2, 1, 0,
            (SCM s, SCM signed_p, SCM big_endian_p),
            "Convert the machine-format number encoded in string @var{s}\n"
            "to an exact integer.  The string must contain either 2, 4, or\n"
            "8 characters.  If @var{signed?} is true, then the string is\n"
            "decoded as a two's-complement number, otherwise it is decoded\n"
            "as an unsigned integer.  If @var{big-endian?} is true, then\n"
            "the first character's ASCII value provides the most significant\n"
            "eight bits of the number, otherwise the first character provides\n"
            "the least-significant eight bits, and so on.  The default value\n"
            "of big-endian? is the result of @code{system-big-endian?}.")
#define FUNC_NAME s_ibs2integer
{
  int len, i, cbep;
  SCM ans, tem;
  unsigned char *p;

  SCM_VALIDATE_ROSTRING (1, s);
  SET_CBEP_MAYBE (cbep, big_endian_p);
  len = SCM_ROLENGTH (s);
  if (! (2 == len || 4 == len || 8 == len))
    scm_misc_error (FUNC_NAME, "string length not 2, 4 or 8: ~S",
                    scm_listify (s, SCM_UNDEFINED));

  ans = SCM_INUM0;
  p = SCM_CHARS (s);
  if (! cbep)                           /* little endian */
    for (i = 0; i < len; i += 2)
      {
        tem = scm_ash (SCM_MAKINUM (((unsigned int) p[i]) +
                                    ((unsigned int) p[1+i] << 8)),
                       SCM_MAKINUM (i * 8));
        ans = scm_sum (ans, tem);
      }
  else                                  /* big endian */
    for (i = 0; i < len; i += 2)
      {
        tem = scm_ash (SCM_MAKINUM (((unsigned int) p[1+i]) +
                                    ((unsigned int) p[i] << 8)),
                       SCM_MAKINUM ((len - i - 2) * 8));
        ans = scm_sum (ans, tem);
      }

  if (SCM_NFALSEP (signed_p))
    {
      int opg = 8 * len;                /* "one position greater" than msb */

      if (SCM_NFALSEP (scm_logbit_p (SCM_MAKINUM (opg - 1), ans)))
        {
          /* For 4-bit signed, 0xF <=> -1 <=> (- 0xF 0x10).  */
          tem = scm_ash (SCM_MAKINUM (1), SCM_MAKINUM (opg));
          ans = scm_difference (ans, tem);
        }
    }

  return ans;
}
#undef FUNC_NAME

MDEFLOCEXP (integer2ibs, "integer->integer-byte-string", 3, 2, 0,
            (SCM n, SCM size, SCM signed_p, SCM big_endian_p, SCM dest),
            "Convert the exact integer @var{n} to a machine-format number\n"
            "encoded in a string of length @var{size}, which must be 2, 4,\n"
            "or 8. If @var{signed?} is true, then the number is encoded with\n"
            "two's complement, otherwise it is encoded as an unsigned bit\n"
            "stream.  If @var{big-endian?} is true, then the most significant\n"
            "eight bits of the number are encoded in the first character of\n"
            "the resulting string, otherwise the least-significant bits are\n"
            "encoded in the first character, and so on.  The default value of\n"
            "@var{big-endian?} is the result of @code{system-big-endian?}.\n\n"
            "If @var{dest} is provided, it must be a mutable string of\n"
            "length @var{size}; in that case, the encoding of @var{n} is\n"
            "written into @var{dest}, and @var{dest} is returned as the\n"
            "result.  If @var{dest} is not provided, the result is a newly\n"
            "allocated string.  If @var{n} cannot be encoded in a string of\n"
            "the requested size and format, an error is thrown.  If @var{dest}\n"
            "is provided and it is not of length @var{size}, an error is\n"
            "thrown.")
#define FUNC_NAME s_integer2ibs
{
  int len, i, cbep, cs, cnegp;
  SCM tem;
  unsigned char *p;

  cs = SCM_NFALSEP (signed_p);
  cnegp = SCM_NFALSEP (scm_negative_p (n));
  if (cnegp && ! cs)
    scm_misc_error (FUNC_NAME,
                    "cannot encode negative number unsigned: ~S",
                    scm_listify (n, SCM_UNDEFINED));
  SET_CBEP_MAYBE (cbep, big_endian_p);
  if (SCM_UNBNDP (dest))
    dest = scm_make_string (size, SCM_UNDEFINED);
  SCM_VALIDATE_RWSTRING (5, dest);
  len = SCM_ROLENGTH (dest);
  if (! (2 == len || 4 == len || 8 == len))
    scm_misc_error (FUNC_NAME, "string length not 2, 4 or 8: ~S",
                    scm_listify (dest, SCM_UNDEFINED));
  if (SCM_INUM (size) > SCM_ROLENGTH (dest))
    scm_misc_error (FUNC_NAME, "size and dest mismatch: ~S",
                    scm_listify (dest, SCM_UNDEFINED));

  if (cnegp)
    {
      /* For 4-bit signed, -1 <=> 0xF <=> (+ 0x10 -1).  */
      tem = scm_ash (SCM_MAKINUM (1), SCM_MAKINUM (8 * len));
      tem = scm_sum (tem, n);
    }
  else
    tem = n;

  /* Endian-specific (start and direction) fill.  */
  for (i = 0, p = SCM_CHARS (dest) + (cbep ? len - 1 : 0);
       i < len;
       i++, p += (cbep ? -1 : 1))
    {
      *p = (unsigned char) SCM_INUM (scm_logand (tem, SCM_MAKINUM (0xff)));
      tem = scm_ash (tem, SCM_MAKINUM (-8));
    }
  if (SCM_FALSEP (scm_num_eq_p (tem, SCM_INUM0)))
    scm_misc_error (FUNC_NAME, "number too big for ~S-byte string: ~S",
                    scm_listify (size, n, SCM_UNDEFINED));

  return dest;
}
#undef FUNC_NAME

MDEFLOCEXP (fpbs2real, "floating-point-byte-string->real", 1, 1, 0,
            (SCM s, SCM big_endian_p),
            "Convert the IEEE floating-point number encoded in string\n"
            "@var{s} to an inexact real number.  The string must contain\n"
            "either 4 or 8 characters.  If @var{big-endian?} is true,\n"
            "then the first character's ASCII value provides the most\n"
            "siginficant eight bits of the IEEE representation,\n"
            "otherwise the first character provides the\n"
            "least-significant eight bits, and so on.  The default value\n"
            "of @var{big-endian?} is the result of @code{system-big-endian?}.")
#define FUNC_NAME s_fpbs2real
{
  int len, cbep;
  double d;
  float f;

  SCM_VALIDATE_ROSTRING (1, s);
  SET_CBEP_MAYBE (cbep, big_endian_p);
  len = SCM_ROLENGTH (s);
  if (! (4 == len || 8 == len))
    scm_misc_error (FUNC_NAME, "string length not 4 or 8: ~S",
                    scm_listify (s, SCM_UNDEFINED));

  correct_strncpy (cbep, ((4 == len)
                          ? (unsigned char *)(&f)
                          : (unsigned char *)(&d)),
                   SCM_CHARS (s),
                   len);

  return scm_make_real ((4 == len) ? ((double) f) : d);
}
#undef FUNC_NAME

MDEFLOCEXP (real2fpbs, "real->floating-point-byte-string", 2, 2, 0,
            (SCM x, SCM size, SCM big_endian_p, SCM dest),
            "Convert the real number @var{x} to its IEEE representation in a\n"
            "string of length @var{size}, which must be 4 or 8.  If\n"
            "@var{big-endian?} is true, then the most significant eight\n"
            "bits of the number are encoded in the first character of the\n"
            "resulting string, otherwise the least-significant bits are\n"
            "encoded in the first character, and so on.  The default value\n"
            "of @var{big-endian?} is the result of @code{system-big-endian?}.\n"
            "If @var{dest} is provided, it must be a mutable string of\n"
            "length @var{size}; in that case, the encoding of @var{x} is written\n"
            "into @var{dest}, and @var{dest} is returned as the result.  If\n"
            "@var{dest} is not provided, the result is a newly allocated\n"
            "string.  If @var{dest} is provided and it is not of length\n"
            "@var{size}, an error is thrown.")
#define FUNC_NAME s_real2fpbs
{
  int len, cbep;
  double cdx;
  float cfx;

  if (SCM_REALP (x))
    cdx = SCM_REAL_VALUE (x);
  else
    scm_misc_error (FUNC_NAME, "not a real number: ~S",
                    scm_listify (x, SCM_UNDEFINED));
  SET_CBEP_MAYBE (cbep, big_endian_p);
  if (SCM_UNBNDP (dest))
    dest = scm_make_string (size, SCM_UNDEFINED);
  SCM_VALIDATE_RWSTRING (4, dest);
  len = SCM_ROLENGTH (dest);
  if (! (4 == len || 8 == len))
    scm_misc_error (FUNC_NAME, "string length not 4 or 8: ~S",
                    scm_listify (dest, SCM_UNDEFINED));

  if (4 == len)
    cfx = (float) cdx;

  correct_strncpy (cbep, SCM_CHARS (dest),
                   ((4 == len)
                    ? (unsigned char *)(&cfx)
                    : (unsigned char *)(&cdx)),
                   len);

  return dest;
}
#undef FUNC_NAME

\f
static
void
init_module (void)
{
#include "binconv.x"
}

MDEFLINKFUNC ("database binconv", database_binconv, init_module)

/* binconv.c ends here */


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user