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

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: Doc organization (Re: Around again, and docs lead role)

[Wolfgang Jaehrling]

On Thu, May 08, 2003 at 11:21:12AM -0500, Rob Browning wrote:
> 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.

Maintaining redundancy is no fun.  But I don't think it is necessary
here, just generate both versions from the same input.  (Preferably
embedding the information in - and extracting it from - the source
code.)

Cheers,
GNU/Wolfgang


_______________________________________________
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]

>>>>> "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)

[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)

[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: 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)

[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]

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

> >>>>> "Ricard" == Ricard Mira <ricardmm@tiscali.es> writes:
> 
> 
>     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).
      ^^^^^^^^^^^^^^^^^^^^^

snip 

      What about a tutorial, Ricard?

Hi, 

I am new to guile, 
my name is max.


I came across guile, when I gathered information about: 

        What makes up a GNU Package.

As I got it: 

        The decision was and is: 

        The GNU Glue, should be GUILE.
        
Being interested in providing my own stuff to the GNU
Project and/or in giving help to another GNU Package, 
I accepted the need to dive into GUILE. 


Thus I naturally had an eye on this thread 
about the need of restructuring and improving the
documentation. 


> 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, it is difficult even to describe the
> documentation status.)

     My first impression was: 
        Oops...
        such an important project, but obviously
        abandoned...

     The documentation is one of the first important 
     impressions a (potential) user gets. 

     
     I typically look out for a tutorial, immediately 
     after installation. Not to learn, but to find out:
     
        is this something for me? 

      
> 
> Specifically, I think we should (**) promote doing as much programming
> as possible in Scheme, 

      Yeah. 

> and restrict documentation of the C API to the
> parts needed for interfacing Scheme to C code.  
snip 

      Yeah.

> , I think the natural high level documentation structure
> would then be:
> 

     I am missing, things like: 

        * Tutorial 
              
               
        * Introduction 

                ** Background, History 
                ** Advantages 
                ... 

        Basic Concepts, or whatever 

        * Rational / Advocacy

                ** nothing you can`t do with lisp like
                   languages, 

                ** hackable, short path to C  
                
                ** scientific background 
        

        * GOOPS 
                
                (proof of the `nothing you can`t do
                statement) 
               

        * R5RS 

        * Other freely available or even included documentation 

               


     (Some of these sections need not be high volume
     but they serve important purposes.) 


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

        Task based structuring the meat of the documentation
        is an idea I like, Neil.
        
        That`s what we use software for: 
                Solving Tasks 
                (beside for having incredible fun, of cause =:)


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

        Here we are...

regards 
max. 


_______________________________________________
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)

[Max Techter]

Ricard Mira <ricardmm@tiscali.es> writes:

> Max Techter wrote:
> >       What about a tutorial, Ricard?
> 
> There is already a Guile tutorial, but it's quite incomplete.  On the
> other hand, it seems that most of the material in parts I, II and III
> of the Guile reference manual are introductory.
> 

        I agree on this. 
        
        But IMHO a tutorial and an introduction is 
        definitely not an exclusive alternative.

        

> I guess it's not clear yet whether Guile should have a separate
> tutorial, or an introductory section (or some introductory sections)
> in the reference manual.
> 

        Sure.


        Anyway, keeping a  tutorial separated 
        and on a different level(*) 
        is a good idea. 
        (Same principle as in python documentation).


                (*) concerning what you suppose about the knowledge of
                the audience, you are aiming at; concerning what you
                want to communicate,...

        If you keep the tutorial (which) should be
        practical, the whirlwind tour should be theoretical.
        
        Introductory stuff should be kept formal.

        Tutorial may be informal, if necessary even 
        a little bit unprecise, but it has to get you going 
        immediately.
                

        We should not bother too much about the structure 
        already there, if it is clear that there has to be 
        done some restructuring. 

        There are well known
        principles how to document a system. 
        ( And a standalone- (python), 
        or integrated-tutorial (bison) is a good ingredient for 
        the doc of every non trivial system)   ;-) 

        The problem is not so much in finding a suitable
        structure but in writing and maintaining, without
        washing the structure away again. 
        Keeping the proportions is a problem too, but 
        we do not have to bother about this, now.

        (
         The work already done, is a fine prototype.
         We may infer the structure needed, from the 
         problems this documentation posed. 
        ). 


        Maybe I underestimate the complexity, of the needed
        guile documentation.  

        I`ll try to work out a proposal. 
        I am engaged in scheme and guile anyway, 
        and this will force me to have a structured go. 

        (Guess I`ll need =<  a fortnight) 
        
regards 
max.


_______________________________________________
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)

[Max Techter]

Max Techter <mtechter@gmx.de> writes:

> Ricard Mira <ricardmm@tiscali.es> writes:
> 
> > Max Techter wrote:
> > >       What about a tutorial, Ricard?
> > 
> > There is already a Guile tutorial, but it's quite  incomplete.  
snip


        [some arguments concerning tutorials snipped away] 


 
>         We should not bother too much about the structure 
>         already there, if it is clear that there has to be 
>         done some restructuring. 
> 
>         There are well known
>         principles how to document a system. 
>         ( And a standalone- (python), 
>         or integrated-tutorial (bison) is a good ingredient for 
>         the doc of every non trivial system)   ;-) 
> 
>         The problem is not so much in finding a suitable
>         structure but in writing and maintaining, without
>         washing the structure away again. 
>         Keeping the proportions is a problem too, but 
>         we do not have to bother about this, now.
> 
>         (
>          The work already done, is a fine prototype.
>          We may infer the structure needed, from the 
>          problems this documentation posed. 
>         ). 
> 
> 
>         Maybe I underestimate the complexity, of the needed
>         guile documentation.  
> 
>         I`ll try to work out a proposal. 
>         I am engaged in scheme and guile anyway, 
>         and this will force me to have a structured go. 
> 
>         (Guess I`ll need =<  a fortnight) 
>         
        I have to correct myself here. 
        It should have been 

        (Guess I`ll need >=  a fortnight) 

        Anyway, the work I promised to do is underway.
        Although I will not propose a ready made lay out.

        I`ll propose s.th. that is more like a process
        for getting a documentation design. 

        What I did is s.th. like a documentation domain analysis.
        This takes shape right now. 

        That is: 

                A Domain Dictionary has been initialized.
                We need this for discussion. 
                And then 
                `The Guile Documentation Domain Dictionary' 
                may serve for feeding the Glossary in the end. 

                Use Cases are localized 
                 (They answer the question 
                   who, in which state, will consult which
                   part of the documentation to find what) 

                Some thought on dichotomies was spent:

                   policy-mechanism
                   concept-example
                   etc.

                Important Documentation Patterns have been collected 

                   introduction-main-conclusion 

                   concept-example 
                          subtypes are:
                                leading-example 
                                subsequent-example 
                                interleaved-example 
        
                        
                   tutorial 
                   how to read this manual 
                   site-map 
                   elaboration 
                   abstract 
                   bold vision 
                   history 
                   etc

        As soon as GNU documentation guide lines are reached
        I`ll go public.  I cannot go beyond this point
        without your sayings!
        
        Hopefully this procedure will naturally evolve 
        into a process which extends to part of the guile
        community and specializes to Guile Documentation. 


   My understanding of documentation development has 
   been extended by doing these preparations.
   So the work done so far was at least valuable for me. 


    Soon I call again, about those documentation issue ... 

    (The promised `commented manual' is underway too). 

regards 
max.


PS: 
   * Some people say I tend to over analyze, but I doubt the
     thoroughness of their analysis ;-) 
        

   * The whole `Guile (based on Scheme) concept' leaves me
     standing openmouthed, and I am wondering 

       a)  how it could happen that nobody pushed me 
           into lisp/scheme before.

       b) why the project has not been mentioned in work
          dear to me 
          eg. 
          `Generative Programming' by Czarnecki and Eisenecker
           or 
           Coplien`s `Multi-Paradigm Design', Thesis 

           (
            Maybe I overestimate the guile potential, 
            but I constantly get this 
            "whoop, you can do this and then you could do
            that" rush when working on scheme or guile. 
            Time will tell...
           ) 

       c) how it can be that some people, Stallman and others,
          are thus farsighted (includes the elisp choice).


       d) ...


_______________________________________________
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]

>>>>> "Max" == Max Techter <mtechter@gmx.de> writes:

    >> 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, it is difficult even to describe the
    >> documentation status.)

    Max>      My first impression was: 
    Max>         Oops...
    Max>         such an important project, but obviously
    Max>         abandoned...

I don't see how you can conclude that the project is abandoned when
we're right in the middle of a thread about it ....
     
    Max>      I typically look out for a tutorial, immediately 
    Max>      after installation. Not to learn, but to find out:
     
    Max>         is this something for me? 

Did you look at the Guile Tutorial?  How would you improve it?

    >> , I think the natural high level documentation structure
    >> would then be:
    >> 

    Max>      I am missing, things like: [...]

I agree, and some of these pieces are already in place - see the Guile
Reference manual.  But I was really focussing on the issue of Scheme
and C API documentation in my last message.
     
    >> - 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:

    Max>         Task based structuring the meat of the documentation
    Max>         is an idea I like, Neil.
        
    Max>         That`s what we use software for: 
    Max>                 Solving Tasks 
    Max>                 (beside for having incredible fun, of cause =:)

OK, but given a general purpose language like Scheme, there's a limit
to how fully you can document it in a task-based way.  For Scheme you
need a combination of reference documentation and examples.

The C API on the other hand - at least as I think we should see it -
is not general purpose.  It has the specific job of interfacing C to
Scheme and so can be fully covered in a task-based way.

Thanks for your thoughts,

        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)

[Max Techter]

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

> >>>>> "Max" == Max Techter <mtechter@gmx.de> writes:
> 
>     >> 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, it is difficult even to describe the
>     >> documentation status.)
> 
>     Max>      My first impression was: 
>     Max>         Oops...
>     Max>         such an important project, but obviously
>     Max>         abandoned...
> 
> I don't see how you can conclude that the project is abandoned when
> we're right in the middle of a thread about it ....
>      

        I installed the guile package, had a look 
        at the manual and at  the tutorial before 
        I subscribed and read the mailing list.


>     Max>      I typically look out for a tutorial, immediately 
>     Max>      after installation. Not to learn, but to find out:
>      
>     Max>         is this something for me? 
> 
> Did you look at the Guile Tutorial?  

        Yes, I did. 

        That`s what I do as one of my first steps, 
        when exploring s.th. new to me.

        And this was part of the things 
        that caused my _first_ and _wrong_ impression.

                Oops, abandoned. 
        
        Important GNU Packages, have excellent doc,
        guile doc is not bad, but not excellent either.

        (although it is an important Package, 
        as I got it now, and not abandoned...      :-)


> How would you improve it?
> 

        Too much to say about this, 
        to be appropriate for this reply.

        I`ll tell you in a couple of days, more precisely. 

        So far only this:

        As an example: 
        There is a section 

                Using recursion to process a list.

        Before anything was said about pairs, 
        and lists, and the concept of the null
        in scheme. 

        If this is an tutorial about scheme, you can`t 
        ask the (potential) user, to take such a leap.
        You can do this in a preview, but not in 
        a tutorial.
        
        Now if this is not a scheme tutorial, 
        (the Title says `Guile tutorial'),
        there is no need to supply such an 
        example, because it is a standard 
        scheme construct.

        The problem is: 
            the parts of the documentation 
            seen as isolated pieces of 
            knowledge, are good, though not complete.

            But being new to guile, and to scheme 
            I had problems to grasp the context (and the
            rational).
 

>     >> , I think the natural high level documentation structure
>     >> would then be:
>     >> 
> 
>     Max>      I am missing, things like: [...]
> 
> I agree, and some of these pieces are already in place - see the Guile
> Reference manual.  But I was really focussing on the issue of Scheme
> and C API documentation in my last message.
>      
        Ok, obviously I missed your focus.

        That is because I am still struggling to get the big
        picture:



        The Algorithmic Language Scheme

        * GOOPS: (goops).               The GOOPS reference manual.
        * Guile Reference: (guile).     The Guile reference manual.
        * Guile Tutorial: (guile-tut).  The Guile tutorial.
        * R5RS: (r5rs).                 The Revised(5) Report on Scheme.

        (slib is missing in my local installation, what else
        is missing?) 
         
                
>     >> - 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:
> 
>     Max>         Task based structuring the meat of the documentation
>     Max>         is an idea I like, Neil.
>         
>     Max>         That`s what we use software for: 
>     Max>                 Solving Tasks 
>     Max>                 (beside for having incredible fun, of cause =:)
> 
> OK, but given a general purpose language like Scheme, there's a limit
> to how fully you can document it in a task-based way.  


> For Scheme you
> need a combination of reference documentation and examples.
> 
                
       I agree. 

       It is clear that this task-based way has advantages 
       and  has tight limits on the other hand.

       And may I add: 

       Reference 
        
              with short examples.

       Tutorial 

               with intermediate examples, 

       Introduction / Basic Concepts 
                by the way, IMHO there should be a section 

                * `Basic  Concepts of Scheme' 
                      as there already is 

                __and__

                * `Basic  Concepts of Guile' 
                      maybe the Whirlwind tour could be 
                      extended to such a section, and
                      later on this extension could be boiled
                      down again to an improved Whirlwind tour
        
       
               both with longer examples
                (like the one in `An Example of Non-Lexical Scoping'
                 which helped me quite a lot, to dig  one 
                 of the not so simple concepts.) 
       

> The C API on the other hand - at least as I think we should see it -
> is not general purpose.  

> It has the specific job of interfacing C to
> Scheme and so can be fully covered in a task-based way.
> 
     I am definitely not the one to comment on this, 
        not yet   ;-)

regards 
max.


PS: 
    I would like to help in formulating the overall layout,
    and I am prepared to get my hands on real work,
    concerning the tutorials, if it is decided on 
    having (or keeping) them.


_______________________________________________
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 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)

[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: Around again, and docs lead role

[Max Techter]

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

snip
> 
> 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?
> 
        
Hi, 

I am new to guile, new to this list 

(though I posted a couple of replies concerning the overall
structure, and the principle need of tutorials)

I am not ready to offer to take the lead role on Guile
documentation, but I offer to `throw in my two cent' as
Thamer put it in a subsequent posting in this thread.


Last weekend I managed to spare an evening for diving deeper
into the

        `Guile Reference Manual',  
        Edition 1.0, for use with Guile 1.6.2 

The first impression I had was verified:

        A prototype of a documentation. 

        Lacking an understandable high level structure.

        Inconsistent in things that should be common 
          (Eg. sometimes the aim and the audience of the section
           is mentioned, sometimes not) 

        Inconsistent in things that should vary 
          (Eg. different sections, chapters, parts freely
          mix the level of the examples supplied) 
        



Right now I am adding up pall pen remarks to my printed
version, these would normally go down the shredder, after I
managed to extract my private documentation map.


If you think, that in the current state of discussion, this
kind of critique could be useful, tell me:

        hacking revised comments into, say  the .texi
        source, would not put a too heavy workload on me.

regards 
max.


_______________________________________________
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]

>>>>> "Max" == Max Techter <mtechter@gmx.de> writes:

    Max> Neil Jerram <neil@ossau.uklinux.net> writes:
    Max> snip
    >> 
    >> That said... is there anyone out there who'd be interested in taking
    >> over the lead role on Guile documentation?
    >> 
    >> [...]
        
    Max> Hi, 

Hi Max,

    Max> I am new to guile, new to this list 

    Max> (though I posted a couple of replies concerning the overall
    Max> structure, and the principle need of tutorials)

First off, apologies for not replying to your earlier detailed email
yet - I'm a bit busy and taking time to digest it, but it looks like
just the kind of high-level input that I was hoping someone would
supply.

    Max> Last weekend I managed to spare an evening for diving deeper
    Max> into the

    Max>         `Guile Reference Manual', [...]

I will reply to your detailed points here in more detail later, but
for now ...

    Max> If you think, that in the current state of discussion, this
    Max> kind of critique could be useful, tell me:

Yes, absolutely!

    Max>         hacking revised comments into, say  the .texi
    Max>         source, would not put a too heavy workload on me.

That sounds great.  If you have any suggestions for a overall plan of
how to rectify the problems that you've noted, I would love to hear
them too.

Best regards,
        Neil



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

Re: Around again, and docs lead role

[Max Techter]

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

> >>>>> "Max" == Max Techter <mtechter@gmx.de> writes:
> 
>     Max> Neil Jerram <neil@ossau.uklinux.net> writes:
>     Max> snip
>     >> 
snip 

>     Max> I am new to guile, new to this list 
> 
>     Max> (though I posted a couple of replies concerning the overall
>     Max> structure, and the principle need of tutorials)
> 
> First off, apologies for not replying to your earlier detailed email
> yet - I'm a bit busy and taking time to digest it, but it looks like
> just the kind of high-level input that I was hoping someone would
> supply.
snip

        Take your time, Neil.  I will be engaged in "my
        guile analysis" for quite some time.

        And there is no chance for me coming up with first
        well formed proposals before, say the end of this
        month, although I`ll try to supply my comments sooner.


>     Max> If you think, that in the current state of discussion, this
>     Max> kind of critique could be useful, tell me:
> 
> Yes, absolutely!
> 
        
>     Max>         hacking revised comments into, say  the .texi
>     Max>         source, would not put a too heavy workload on me.
> 
snip 

        
        On which version exactly should I build? 
        I produced my printout and info files from: 
                

        @set MANUAL_EDITION 1.0        
        ...
        ...
        @title Guile Reference Manual
        @subtitle Edition @value{MANUAL_EDITION}, \
                for use with Guile @value{VERSION}
                                   # this evaluated to 1.6.2 

        @subtitle $Id: guile.texi,v 1.2.2.17 2002/09/25 00:12:21 ossau Exp $

        
        Is this OK, or should I switch to a source 
        from CVS? 

> If you have any suggestions for a overall plan of
> how to rectify the problems that you've noted, 
> I would love to hear
> them too.
> 
        
        Taking the fun of playing the harsh critic,
        I would feel obliged to propose better ways,
        naturally.


regards 
max.


_______________________________________________
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]

>>>>> "Max" == Max Techter <mtechter@gmx.de> writes:

    Max>         Take your time, Neil.  I will be engaged in "my
    Max>         guile analysis" for quite some time.

    Max>         And there is no chance for me coming up with first
    Max>         well formed proposals before, say the end of this
    Max>         month, although I`ll try to supply my comments sooner.

OK - thanks.

        
    Max>         On which version exactly should I build? 
    Max>         I produced my printout and info files from: 

        
    Max>         Is this OK, or should I switch to a source 
    Max>         from CVS? 

CVS would be better: CVS is where ongoing work should be applied to,
and it will be easier to do this if your patches are against CVS.
        
    Max>         Taking the fun of playing the harsh critic,
    Max>         I would feel obliged to propose better ways,
    Max>         naturally.

I look forward to them.

Regards,
        Neil



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