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

From: rm@fabula.de
Cc: Neil Jerram <neil@ossau.uklinux.net>
Subject: Re: Doc organization (Re: Around again, and docs lead role)
Date: Thu, 8 May 2003 19:50:58 +0200	[thread overview]
Message-ID: <20030508175058.GD920@www> (raw)
In-Reply-To: <87d6its93b.fsf@raven.i.defaultvalue.org>

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