update traps documentation (unfinished)

* doc/ref/Makefile.am:
* doc/ref/guile.texi:
* doc/ref/scheme-debugging.texi: Remove scheme-debugging.texi, which
  only described tracing. Tracing documentation is now in
  api-debugging.

* doc/ref/scheme-using.texi (Evaluating Scheme Code): Remove reference
  to source traps, as that section is going away.

* doc/ref/api-modules.texi (Included Guile Modules): Remove reference to
  Tracing. This section is a little silly, anyway...

* doc/ref/api-evaluation.texi (VM Behaviour): Remove section, it is in
  api-debugging now.

* doc/ref/api-debug.texi (Stacks, Frames): Rename sections from
  "Examining the Stack" and "Examining Stack Frames", respectively.
  (Traps): Update for current API. A big and not-quite-finished update.

doc/ref/Makefile.am

@@ -62,7 +62,6 @@ guile_TEXINFOS = preface.texi			\
 		 scheme-scripts.texi		\
 		 api-overview.texi		\
 		 api-deprecated.texi		\
-		 scheme-debugging.texi		\
 		 scheme-using.texi		\
 		 indices.texi			\
 		 script-getopt.texi		\

doc/ref/api-evaluation.texi

@@ -19,7 +19,6 @@ loading, evaluating, and compiling Scheme code at run time.
 * Loading::                     Loading Scheme code from file.
 * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file.
 * Delayed Evaluation::          Postponing evaluation until it is needed.
-* VM Behaviour::                Modifying Guile's virtual machine.
 @end menu
 
 
@@ -868,38 +867,6 @@ value.
 @end deffn
 
 
-@node VM Behaviour
-@subsection VM Behaviour
-
-Like the procedures from the previous section that operate on the
-evaluator, there are also procedures to modify the behavior of a
-virtual machine.
-
-The most useful thing that a user can do is to add to one of the
-virtual machine's predefined hooks:
-
-@deffn {Scheme Procedure} vm-next-hook vm
-@deffnx {Scheme Procedure} vm-apply-hook vm
-@deffnx {Scheme Procedure} vm-push-continuation-hook vm
-@deffnx {Scheme Procedure} vm-pop-continuation-hook vm
-@deffnx {Scheme Procedure} vm-abort-continuation-hook vm
-@deffnx {Scheme Procedure} vm-restore-continuation-hook vm
-Accessors to a virtual machine's hooks. Usually you pass @code{(the-vm)}
-as the @var{vm}.
-@end deffn
-
-@deffn {Scheme Procedure} vm-trace-level vm
-Retrieve the ``trace level'' of the VM. If positive, the trace hooks associated
-with @var{vm} will be run. The initial trace level is 0.
-@end deffn
-
-@deffn {Scheme Procedure} set-vm-trace-level! vm level
-Set the ``trace level'' of the VM.
-@end deffn
-
-@xref{A Virtual Machine for Guile}, for more information on Guile's
-virtual machine.
-
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:

doc/ref/api-modules.texi

@@ -577,10 +577,6 @@ to the entries in this manual which describe them in more detail:
 boot-9 is Guile's initialization module, and it is always loaded when
 Guile starts up.
 
-@item (ice-9 debug)
-Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Tracing}).
-
 @item (ice-9 expect)
 Actions based on matching input from a port (@pxref{Expect}).
 

doc/ref/guile.texi

@@ -360,7 +360,6 @@ available through both Scheme and C interfaces.
 * Expect::			Controlling interactive programs with Guile.
 * sxml-match::                  Pattern matching of SXML.
 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
-* Tracing::                     Tracing program execution.
 @end menu
 
 @include slib.texi
@@ -377,7 +376,6 @@ available through both Scheme and C interfaces.
 @include sxml-match.texi
 
 @include scsh.texi
-@include scheme-debugging.texi
 
 @node Standard Library
 @chapter Standard Library

doc/ref/scheme-debugging.texi

@@ -1,123 +0,0 @@
-@c -*-texinfo-*-
-@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
-@c   Free Software Foundation, Inc.
-@c See the file guile.texi for copying conditions.
-
-@node Tracing
-@section Tracing
-
-The @code{(ice-9 debug)} module implements tracing of procedure
-applications.  When a procedure is @dfn{traced}, it means that every
-call to that procedure is reported to the user during a program run.
-The idea is that you can mark a collection of procedures for tracing,
-and Guile will subsequently print out a line of the form
-
-@lisp
-|  |  [@var{procedure} @var{args} @dots{}]
-@end lisp
-
-whenever a marked procedure is about to be applied to its arguments.
-This can help a programmer determine whether a function is being called
-at the wrong time or with the wrong set of arguments.
-
-In addition, the indentation of the output is useful for demonstrating
-how the traced applications are or are not tail recursive with respect
-to each other.  Thus, a trace of a non-tail recursive factorial
-implementation looks like this:
-
-@lisp
-[fact1 4]
-|  [fact1 3]
-|  |  [fact1 2]
-|  |  |  [fact1 1]
-|  |  |  |  [fact1 0]
-|  |  |  |  1
-|  |  |  1
-|  |  2
-|  6
-24
-@end lisp
-
-While a typical tail recursive implementation would look more like this:
-
-@lisp
-[fact2 4]
-[facti 1 4]
-[facti 4 3]
-[facti 12 2]
-[facti 24 1]
-[facti 24 0]
-24
-@end lisp
-
-@deffn {Scheme Procedure} trace procedure
-Enable tracing for @code{procedure}.  While a program is being run,
-Guile will print a brief report at each call to a traced procedure,
-advising the user which procedure was called and the arguments that were
-passed to it.
-@end deffn
-
-@deffn {Scheme Procedure} untrace procedure
-Disable tracing for @code{procedure}.
-@end deffn
-
-Here is another 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 procedure 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.  Tracing reveals this optimization in operation.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:

doc/ref/scheme-using.texi

@@ -1036,13 +1036,11 @@ region contains a balanced expression, or try to expand the region so
 that it does; it uses the region exactly as it is.
 @end table
 
-If you type @kbd{C-u} before one of these commands, GDS will
+If you type @kbd{C-u} before one of these commands, GDS will immediately
-immediately pop up a Scheme stack buffer, showing the requested
+pop up a Scheme stack buffer, showing the requested evaluation, so that
-evaluation, so that you can single step through it.  (This is achieved
+you can single step through it.  The Scheme stack display, and the
-by setting a @code{<source-trap>} trap at the start of the requested
+options for continuing through the code, are described in the next two
-evaluation; see @ref{Source Traps} for more on how those work.)  The
+sections.
-Scheme stack display, and the options for continuing through the code,
-are described in the next two sections.
 
 
 @node Displaying the Scheme Stack