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

[Mikael Djurfeldt]

Bill Schottstaedt <address@hidden> 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.