This commit was manufactured by cvs2svn to create tagrelease_1-5-6

'release_1-5-6'.

2 files changed, 0 insertions, 457 deletions

diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi
deleted file mode 100644
index 45fef5082..000000000
--- a/doc/ref/debugging.texi
+++ /dev/null
@@ -1,181 +0,0 @@
-@page
-@node Debugger User Interface
-@chapter Debugger User Interface
-
-@c      --- The title and introduction of this appendix need to
-@c          distinguish this clearly from the chapter on the internal
-@c          debugging interface.
-
-When debugging a program, programmers often find it helpful to examine
-the program's internal status while it runs: the values of internal
-variables, the choices made in @code{if} and @code{cond} statements, and
-so forth.  Guile Scheme provides a debugging interface that programmers
-can use to single-step through Scheme functions and examine symbol
-bindings.  This is different from the @ref{Debugging}, which permits
-programmers to debug the Guile interpreter itself.  Most programmers
-will be more interested in debugging their own Scheme programs than the
-interpreter which evaluates them.
-
-[FIXME: should we include examples of traditional debuggers
-and explain why they can't be used to debug interpreted Scheme or Lisp?]
- 
-@menu
-* Single-Step::         Execute a program or function one step at a time.
-* Trace::               Print a report each time a given function is called.
-* Backtrace::           See a list of the statements that caused an error.
-* Stacks and Frames::	Examine the state of an interrupted program.
-@end menu
-
- 
-@node Single-Step
-@section Single-Step
-
- 
-@node Trace
-@section Trace
-
-When a function is @dfn{traced}, it means that every call to that
-function is reported to the user during a program run.  This can help a
-programmer determine whether a function is being called at the wrong
-time or with the wrong set of arguments.
-
-@defun trace function
-Enable debug tracing on @code{function}.  While a program is being run, Guile
-will print a brief report at each call to a traced function,
-advising the user which function was called and the arguments that were
-passed to it.
-@end defun
-
-@defun untrace function
-Disable debug tracing for @code{function}.
-@end defun
-
-Example:
-
-@lisp
-(define (rev ls)
-  (if (null? ls)
-      '()
-      (append (rev (cdr ls))
-              (cons (car ls) '())))) @result{} rev
-
-(trace rev) @result{} (rev)
-
-(rev '(a b c d e))
-@result{} [rev (a b c d e)]
-   |  [rev (b c d e)]
-   |  |  [rev (c d e)]
-   |  |  |  [rev (d e)]
-   |  |  |  |  [rev (e)]
-   |  |  |  |  |  [rev ()]
-   |  |  |  |  |  ()
-   |  |  |  |  (e)
-   |  |  |  (e d)
-   |  |  (e d c)
-   |  (e d c b)
-   (e d c b a)
-   (e d c b a)
-@end lisp
- 
-Note the way Guile indents the output, illustrating the depth of
-execution at each function call.  This can be used to demonstrate, for
-example, that Guile implements self-tail-recursion properly:
- 
-@lisp
-(define (rev ls sl)
-  (if (null? ls)
-      sl
-      (rev (cdr ls)
-           (cons (car ls) sl)))) @result{} rev
- 
-(trace rev) @result{} (rev)
- 
-(rev '(a b c d e) '())
-@result{} [rev (a b c d e) ()]
-   [rev (b c d e) (a)]
-   [rev (c d e) (b a)]
-   [rev (d e) (c b a)]
-   [rev (e) (d c b a)]
-   [rev () (e d c b a)]
-   (e d c b a)
-   (e d c b a)
-@end lisp
- 
-Since the tail call is effectively optimized to a @code{goto} statement,
-there is no need for Guile to create a new stack frame for each
-iteration.  Using @code{trace} here helps us see why this is so.
- 
-
-@node Backtrace
-@section Backtrace
-
-
-@node Stacks and Frames
-@section Stacks and Frames
-
-When a running program is interrupted, usually upon reaching an error or
-breakpoint, its state is represented by a @dfn{stack} of suspended
-function calls, each of which is called a @dfn{frame}.  The programmer
-can learn more about the program's state at the point of interruption by
-inspecting and modifying these frames.
-
-@deffn {Scheme Procedure} stack? obj
-Return @code{#t} if @var{obj} is a calling stack.
-@end deffn
-
-@deffn {Scheme Procedure} make-stack
-@end deffn
-
-@deffn syntax start-stack id exp
-Evaluate @var{exp} on a new calling stack with identity @var{id}.  If
-@var{exp} is interrupted during evaluation, backtraces will not display
-frames farther back than @var{exp}'s top-level form.  This macro is a
-way of artificially limiting backtraces and stack procedures, largely as
-a convenience to the user.
-@end deffn
-
-@deffn {Scheme Procedure} stack-id stack
-Return the identifier given to @var{stack} by @code{start-stack}.
-@end deffn
-
-@deffn {Scheme Procedure} stack-ref
-@end deffn
-
-@deffn {Scheme Procedure} stack-length
-@end deffn
-
-@deffn {Scheme Procedure} frame?
-@end deffn
-
-@deffn {Scheme Procedure} last-stack-frame
-@end deffn
-
-@deffn {Scheme Procedure} frame-number
-@end deffn
-
-@deffn {Scheme Procedure} frame-source
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure
-@end deffn
-
-@deffn {Scheme Procedure} frame-arguments
-@end deffn
-
-@deffn {Scheme Procedure} frame-previous
-@end deffn
-
-@deffn {Scheme Procedure} frame-next
-@end deffn
-
-@deffn {Scheme Procedure} frame-real?
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure?
-@end deffn
-
-@deffn {Scheme Procedure} frame-evaluating-args?
-@end deffn
-
-@deffn {Scheme Procedure} frame-overflow
-@end deffn
diff --git a/doc/ref/program.texi b/doc/ref/program.texi
deleted file mode 100644
index 61aa69096..000000000
--- a/doc/ref/program.texi
+++ /dev/null
@@ -1,276 +0,0 @@
-@page
-@node Programming Overview
-@chapter An Overview of Guile Programming
-
-Guile is designed as an extension language interpreter that is
-straightforward to integrate with applications written in C (and C++).
-The big win here for the application developer is that Guile
-integration, as the Guile web page says, ``lowers your project's
-hacktivation energy.''  Lowering the hacktivation energy means that you,
-as the application developer, @emph{and your users}, reap the benefits
-that flow from being able to extend the application in a high level
-extension language rather than in plain old C.
-
-Underlying this argument is the assumption that programming in a high
-level language, specifically Guile's implementation of Scheme, is
-necessarily better in some way than programming in C.  What do we mean
-by this claim, and how can we be so sure?
-
-One class of advantages applies not only to Scheme, but more generally
-to any interpretable, high level, scripting language, such as Emacs
-Lisp, Python, Ruby, or @TeX{}'s macro language.  Common features of all
-such languages, when compared to C, are that:
-
-@itemize @bullet
-@item
-They lend themselves to rapid and experimental development cycles,
-owing usually to a combination of their interpretability and the
-integrated development environment in which they are used.
-
-@item
-They free developers from some of the low level bookkeeping tasks
-associated with C programming, notably memory management.
-
-@item
-They provide high level features such as container objects and exception
-handling that make common programming tasks easier.
-@end itemize
-
-In the case of Scheme, further features that make programming easier ---
-and more fun! --- are its powerful mechanisms for abstracting parts of
-programs (closures --- @pxref{About Closure}) and for iteration
-(@pxref{while do}).
-
-The evidence in support of this argument is empirical: the huge amount
-of code that has been written in extension languages for applications
-that support this mechanism.  Most notable are extensions written in
-Emacs Lisp for GNU Emacs, in @TeX{}'s macro language for @TeX{}, and in
-Script-Fu for the Gimp, but there is increasingly now a significant code
-eco-system for Guile-based applications as well, such as Lilypond and
-GnuCash.  It is close to inconceivable that similar amounts of
-functionality could have been added to these applications just by
-writing new code in their base implementation languages.
-
-@menu
-* Testbed Example::             Example: using Guile in a testbed.
-* Programming Options::         Options for Guile programming.
-* User Programming::            How about application users?
-@end menu
-
-
-@node Testbed Example
-@section Example: Using Guile for an Application Testbed
-
-As an example of what this means in practice, imagine writing a testbed
-for an application that is tested by submitting various requests (via a
-C interface) and validating the output received.  Suppose further that
-the application keeps an idea of its current state, and that the
-``correct'' output for a given request may depend on the current
-application state.  A complete ``white box''@footnote{A @dfn{white box}
-test plan is one that incorporates knowledge of the internal design of
-the application under test.} test plan for this application would aim to
-submit all possible requests in each distinguishable state, and validate
-the output for all request/state combinations.
-
-To write all this test code in C would be very tedious.  Suppose instead
-that the testbed code adds a single new C function, to submit an
-arbitrary request and return the response, and then uses Guile to export
-this function as a Scheme procedure.  The rest of the testbed can then
-be written in Scheme, and so benefits from all the advantages of
-programming in Scheme that were described in the previous section.
-
-(In this particular example, there is an additional benefit of writing
-most of the testbed in Scheme.  A common problem for white box testing
-is that mistakes and mistaken assumptions in the application under test
-can easily be reproduced in the testbed code.  It is more difficult to
-copy mistakes like this when the testbed is written in a different
-language from the application.)
-
-
-@node Programming Options
-@section A Choice of Programming Options
-
-The preceding arguments and example point to a model of Guile
-programming that is applicable in many cases.  According to this model,
-Guile programming involves a balance between C and Scheme programming,
-with the aim being to extract the greatest possible Scheme level benefit
-from the least amount of C level work.
-
-The C level work required in this model usually consists of packaging
-and exporting functions and application objects such that they can be
-seen and manipulated on the Scheme level.  To help with this, Guile's C
-language interface includes utility features that aim to make this kind
-of integration very easy for the application developer.  These features
-are documented later in this part of the manual: see REFFIXME.
-
-This model, though, is really just one of a range of possible
-programming options.  If all of the functionality that you need is
-available from Scheme, you could choose instead to write your whole
-application in Scheme (or one of the other high level languages that
-Guile supports through translation), and simply use Guile as an
-interpreter for Scheme.  (In the future, we hope that Guile will also be
-able to compile Scheme code, so lessening the performance gap between C
-and Scheme code.)  Or, at the other end of the C--Scheme scale, you
-could write the majority of your application in C, and only call out to
-Guile occasionally for specific actions such as reading a configuration
-file or executing a user-specified extension.  The choices boil down to
-two basic questions:
-
-@itemize @bullet
-@item
-Which parts of the application do you write in C, and which in Scheme
-(or another high level translated language)?
-
-@item
-How do you design the interface between the C and Scheme parts of your
-application?
-@end itemize
-
-These are of course design questions, and the right design for any given
-application will always depend upon the particular requirements that you
-are trying to meet.  In the context of Guile, however, there are some
-generally applicable considerations that can help you when designing
-your answers.
-
-@menu
-* Available Functionality::     What functionality is already available?
-* Basic Constraints::           Functional and performance constraints.
-* Style Choices::               Your preferred programming style.
-* Program Control::             What controls program execution?
-@end menu
-
-
-@node Available Functionality
-@subsection What Functionality is Already Available?
-
-Suppose, for the sake of argument, that you would prefer to write your
-whole application in Scheme.  Then the API available to you consists of:
-
-@itemize @bullet
-@item
-standard Scheme
-
-@item
-plus the extensions to standard Scheme provided by
-Guile in its core distribution
-
-@item
-plus any additional functionality that you or others have packaged so
-that it can be loaded as a Guile Scheme module.
-@end itemize
-
-A module in the last category can either be a pure Scheme module --- in
-other words a collection of utility procedures coded in Scheme --- or a
-module that provides a Scheme interface to an extension library coded in
-C --- in other words a nice package where someone else has done the work
-of wrapping up some useful C code for you.  The set of available modules
-is growing quickly and already includes such useful examples as
-@code{(gtk gtk)}, which makes Gtk+ drawing functions available in
-Scheme, and @code{(database postgres)}, which provides SQL access to a
-Postgres database.
-
-Given the growing collection of pre-existing modules, it is quite
-feasible that your application could be implemented by combining a
-selection of these modules together with new application code written in
-Scheme.
-
-If this approach is not enough, because the functionality that your
-application needs is not already available in this form, and it is
-impossible to write the new functionality in Scheme, you will need to
-write some C code.  If the required function is already available in C
-(e.g. in a library), all you need is a little glue to connect it to the
-world of Guile.  If not, you need both to write the basic code and to
-plumb it into Guile.
-
-In either case, two general considerations are important.  Firstly, what
-is the interface by which the functionality is presented to the Scheme
-world?  Does the interface consist only of function calls (for example,
-a simple drawing interface), or does it need to include @dfn{objects} of
-some kind that can be passed between C and Scheme and manipulated by
-both worlds.  Secondly, how does the lifetime and memory management of
-objects in the C code relate to the garbage collection governed approach
-of Scheme objects?  In the case where the basic C code is not already
-written, most of the difficulties of memory management can be avoided by
-using Guile's C interface features from the start.
-
-For the full documentation on writing C code for Guile and connecting
-existing C code to the Guile world, see REFFIXME.
-
-
-@node Basic Constraints
-@subsection Functional and Performance Constraints
-
-
-@node Style Choices
-@subsection Your Preferred Programming Style
-
-
-@node Program Control
-@subsection What Controls Program Execution?
-
-
-@node User Programming
-@section How About Application Users?
-
-So far we have considered what Guile programming means for an
-application developer.  But what if you are instead @emph{using} an
-existing Guile-based application, and want to know what your
-options are for programming and extending this application?
-
-The answer to this question varies from one application to another,
-because the options available depend inevitably on whether the
-application developer has provided any hooks for you to hang your own
-code on and, if there are such hooks, what they allow you to
-do.@footnote{Of course, in the world of free software, you always have
-the freedom to modify the application's source code to your own
-requirements.  Here we are concerned with the extension options that the
-application has provided for without your needing to modify its source
-code.}  For example@dots{}
-
-@itemize @bullet
-@item
-If the application permits you to load and execute any Guile code, the
-world is your oyster.  You can extend the application in any way that
-you choose.
-
-@item
-A more cautious application might allow you to load and execute Guile
-code, but only in a @dfn{safe} environment, where the interface
-available is restricted by the application from the standard Guile API.
-
-@item
-Or a really fearful application might not provide a hook to really
-execute user code at all, but just use Scheme syntax as a convenient way
-for users to specify application data or configuration options.
-@end itemize
-
-In the last two cases, what you can do is, by definition, restricted by
-the application, and you should refer to the application's own manual to
-find out your options.
-
-The most well known example of the first case is Emacs, with its
-extension language Emacs Lisp: as well as being a text editor, Emacs
-supports the loading and execution of arbitrary Emacs Lisp code.  The
-result of such openness has been dramatic: Emacs now benefits from
-user-contributed Emacs Lisp libraries that extend the basic editing
-function to do everything from reading news to psychoanalysis and
-playing adventure games.  The only limitation is that extensions are
-restricted to the functionality provided by Emacs's built-in set of
-primitive operations.  For example, you can interact and display data by
-manipulating the contents of an Emacs buffer, but you can't pop-up and
-draw a window with a layout that is totally different to the Emacs
-standard.
-
-This situation with a Guile application that supports the loading of
-arbitrary user code is similar, except perhaps even more so, because
-Guile also supports the loading of extension libraries written in C.
-This last point enables user code to add new primitive operations to
-Guile, and so to bypass the limitation present in Emacs Lisp.
-
-At this point, the distinction between an application developer and an
-application user becomes rather blurred.  Instead of seeing yourself as
-a user extending an application, you could equally well say that you are
-developing a new application of your own using some of the primitive
-functionality provided by the original application.  As such, all the
-discussions of the preceding sections of this chapter are relevant to
-how you can proceed with developing your extension.