This commit was manufactured by cvs2svn to create branch

'branch_release-1-6'.

doc/ref/autoconf.texi

@@ -0,0 +1,123 @@
+@page
+@node Autoconf Support
+@chapter Autoconf Support
+
+When Guile is installed, a set of autoconf macros is also installed as
+PREFIX/share/aclocal/guile.m4.  This chapter documents the macros provided in
+that file.  @xref{Top,The GNU Autoconf Manual,,autoconf}, for more info.
+
+@menu
+* Autoconf Background::         Why use autoconf?
+* Autoconf Macros::             The GUILE_* macros.
+* Using Autoconf Macros::       How to use them, plus examples.
+@end menu
+
+
+@node Autoconf Background
+@section Autoconf Background
+
+As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
+package needs configuration at build-time.  If your package uses Guile (or
+uses a package that in turn uses Guile), you probably need to know what
+specific Guile features are available and details about them.
+
+The way to do this is to write feature tests and arrange for their execution
+by the @file{configure} script, typically by adding the tests to
+@file{configure.ac}, and running @code{autoconf} to create @file{configure}.
+Users of your package then run @file{configure} in the normal way.
+
+Macros are a way to make common feature tests easy to express.  Autoconf
+provides a wide range macros (@pxref{Existing Tests,,,autoconf}), and Guile
+installation provides Guile-specific tests in the areas of: program detection,
+compilation flags reporting, and Scheme module checks.
+
+
+@node Autoconf Macros
+@section Autoconf Macros
+
+The macro names all begin with "GUILE_".
+
+@c see Makefile.am
+@include autoconf-macros.texi
+
+
+@node Using Autoconf Macros
+@section Using Autoconf Macros
+
+Using the autoconf macros is straightforward: Add the macro "calls" (actually
+instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
+run @code{autoconf}.  If your system doesn't have guile.m4 installed, place
+the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
+and @code{aclocal} will do the right thing.
+
+Some of the macros can be used inside normal shell constructs: @code{if foo ;
+then GUILE_BAZ ; fi}, but this is not guaranteed.  It's probably a good idea
+to instantiate macros at top-level.
+
+We now include two examples, one simple and one complicated.
+
+The first example is for a package that uses libguile, and thus needs to know
+how to compile and link against it.  So we use @code{GUILE_FLAGS} to set the
+vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
+substituted in the Makefile.
+
+@example
+In configure.ac:
+
+  GUILE_FLAGS
+
+In Makefile.in:
+
+  GUILE_CFLAGS  = @@GUILE_CFLAGS@@
+  GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
+
+  myprog.o: myprog.c
+          $(CC) -o $@ $(GUILE_CFLAGS) $<
+  myprog: myprog.o
+          $(CC) -o $@ $< $(GUILE_LDFLAGS)
+@end example
+
+The second example is for a package of Guile Scheme modules that uses an
+external program and other Guile Scheme modules (some might call this a "pure
+scheme" package).  So we use the @code{GUILE_SITE_DIR} macro, a regular
+@code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
+
+@example
+In configure.ac:
+
+  GUILE_SITE_DIR
+
+  probably_wont_work=""
+
+  # pgtype pgtable
+  GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
+  test $have_guile_pg = no &&
+      probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
+
+  # gpgutils
+  AC_PATH_PROG(GNUPG,gpg)
+  test x"$GNUPG" = x &&
+      probably_wont_work="(my gpgutils) $probably_wont_work"
+
+  if test ! "$probably_wont_work" = "" ; then
+      p="         ***"
+      echo
+      echo "$p"
+      echo "$p NOTE:"
+      echo "$p The following modules probably won't work:"
+      echo "$p   $probably_wont_work"
+      echo "$p They can be installed anyway, and will work if their"
+      echo "$p dependencies are installed later.  Please see README."
+      echo "$p"
+      echo
+  fi
+
+In Makefile.in:
+
+  instdir = @@GUILE_SITE@@/my
+
+  install:
+        $(INSTALL) my/*.scm $(instdir)
+@end example
+
+@c autoconf.texi ends here

doc/ref/debugging.texi

@@ -0,0 +1,181 @@
+@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

scripts/snarf-guile-m4-docs

@@ -0,0 +1,85 @@
+#!/bin/sh
+# aside from this initial boilerplate, this is actually -*- scheme -*- code
+main='(module-ref (resolve-module '\''(scripts snarf-guile-m4-docs)) '\'main')'
+exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
+!#
+;;; snarf-guile-m4-docs --- Parse guile.m4 comments for texi documentation
+
+;; 	Copyright (C) 2002 Free Software Foundation, Inc.
+;;
+;; This program is free software; you can redistribute it and/or
+;; modify it under the terms of the GNU General Public License as
+;; published by the Free Software Foundation; either version 2, or
+;; (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this software; see the file COPYING.  If not, write to
+;; the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+;; Boston, MA 02111-1307 USA
+
+;;; Author: Thien-Thi Nguyen <ttn@gnu.org>
+
+;;; Commentary:
+
+;; Usage: snarf-guile-m4-docs FILE
+;;
+;; Grep FILE for comments preceding macro definitions, massage
+;; them into valid texi, and display to stdout.  For each comment,
+;; lines preceding "^# Usage:" are discarded.
+;;
+;; TODO: Generalize.
+
+;;; Code:
+
+(define-module (scripts snarf-guile-m4-docs)
+  :use-module (ice-9 rdelim)
+  :export (snarf-guile-m4-docs))
+
+(define (display-texi lines)
+  (display "@deffn {Autoconf Macro}")
+  (for-each (lambda (line)
+              (display (if (string=? "#" (substring line 0 1))
+                           (substring line 1)
+                           line))
+              (newline))
+            lines)
+  (display "@end deffn")
+  (newline) (newline))
+
+(define (prefix? line sub)
+  (false-if-exception
+   (string=? sub (substring line 0 (string-length sub)))))
+
+(define (massage-usage line)
+  (let loop ((line (string->list line)) (acc '()))
+    (if (null? line)
+        (list (list->string (reverse acc)))
+        (loop (cdr line)
+              (cons (case (car line)
+                      ((#\( #\) #\,) #\space)
+                      (else (car line)))
+                    acc)))))
+
+(define (snarf-guile-m4-docs . args)
+  (let* ((p (open-file (car args) "r"))
+         (next (lambda () (read-line p))))
+    (let loop ((line (next)) (acc #f))
+      (or (eof-object? line)
+          (cond ((prefix? line "# Usage:")
+                 (loop (next) (massage-usage (substring line 8))))
+                ((prefix? line "AC_DEFUN")
+                 (display-texi (reverse acc))
+                 (loop (next) #f))
+                ((and acc (prefix? line "#"))
+                 (loop (next) (cons line acc)))
+                (else
+                 (loop (next) #f)))))))
+
+(define main snarf-guile-m4-docs)
+
+;;; snarf-guile-m4-docs ends here