* Manual work on debugging infrastructure.

doc/ref/ChangeLog

@@ -1,5 +1,25 @@
 2002-04-20  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* scheme-debug.texi (Debugging): Rename chapter `Debugging
+	Infrastructure' and reorganize its contents.
+	
+	* scheme-debug.texi (Debugging), scheme-control.texi (Handling
+	Errors): Move display-error to error-focussed section.
+
+	* scheme-debug.texi (Debugging), debugging.texi (Backtrace): Move
+	backtrace to user-level debugging chapter.
+	
+	* scheme-debug.texi (Debugging), scheme-procedures.texi (Procedure
+	Properties): Move procedure-name, procedure-source and
+	procedure-environment to procedures chapter.
+
+	* scheme-debug.texi (Debugging), scheme-memory.texi (Garbage
+	Collection): Move malloc-stats to memory management chapter.
+
+	* scheme-procedures.texi (Syntax Rules): Remove mention of
+	use-modules for loading syncase; only use-syntax really works.
+	Thanks to Panagiotis Vossos for spotting this.
+
 	* program.texi (Scheme vs C): New node, with existing material
 	taken from chapter intro.
 	(Programming Overview): New intro para to introduce example of

doc/ref/debugging.texi

@@ -109,6 +109,12 @@ iteration.  Using @code{trace} here helps us see why this is so.
 @node Backtrace
 @section Backtrace
 
+@deffn {Scheme Procedure} backtrace
+@deffnx {C Function} scm_backtrace ()
+Display a backtrace of the stack saved by the last error
+to the current output port.
+@end deffn
+
 
 @node Stacks and Frames
 @section Stacks and Frames

doc/ref/scheme-control.texi

@@ -878,6 +878,17 @@ Throw an error using the key @code{'misc-error}.  The error
 message is created by displaying @var{msg} and writing the @var{args}.
 @end deffn
 
+@deffn {Scheme Procedure} display-error stack port subr message args rest
+@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
+Display an error message to the output port @var{port}.
+@var{stack} is the saved stack for the error, @var{subr} is
+the name of the procedure in which the error occurred and
+@var{message} is the actual error message, which may contain
+formatting instructions. These will format the arguments in
+the list @var{args} accordingly.  @var{rest} is currently
+ignored.
+@end deffn
+
 The following are the error keys defined by libguile and the situations
 in which they are used:
 

doc/ref/scheme-debug.texi

@@ -1,51 +1,6 @@
 @page
 @node Debugging
-@chapter Internal Debugging Interface
+@chapter Debugging Infrastructure
-
---- The name of this chapter needs to clearly distinguish it
-    from the appendix describing the debugger UI.  The intro
-    should have a pointer to the UI appendix.
-
-@deffn {Scheme Procedure} display-error stack port subr message args rest
-@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
-Display an error message to the output port @var{port}.
-@var{stack} is the saved stack for the error, @var{subr} is
-the name of the procedure in which the error occurred and
-@var{message} is the actual error message, which may contain
-formatting instructions. These will format the arguments in
-the list @var{args} accordingly.  @var{rest} is currently
-ignored.
-@end deffn
-
-@deffn {Scheme Procedure} display-application frame [port [indent]]
-@deffnx {C Function} scm_display_application (frame, port, indent)
-Display a procedure application @var{frame} to the output port
-@var{port}. @var{indent} specifies the indentation of the
-output.
-@end deffn
-
-@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
-@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
-Display a backtrace to the output port @var{port}. @var{stack}
-is the stack to take the backtrace from, @var{first} specifies
-where in the stack to start and @var{depth} how much frames
-to display. Both @var{first} and @var{depth} can be @code{#f},
-which means that default values will be used.
-@end deffn
-
-@deffn {Scheme Procedure} backtrace
-@deffnx {C Function} scm_backtrace ()
-Display a backtrace of the stack saved by the last error
-to the current output port.
-@end deffn
-
-@deffn {Scheme Procedure} malloc-stats
-Return an alist ((@var{what} . @var{n}) ...) describing number
-of malloced objects.
-@var{what} is the second argument to @code{scm_must_malloc},
-@var{n} is the number of objects of that type currently
-allocated.
-@end deffn
 
 @deffn {Scheme Procedure} debug-options-interface [setting]
 @deffnx {C Function} scm_debug_options (setting)
@@ -54,110 +9,21 @@ this procedure directly, use the procedures @code{debug-enable},
 @code{debug-disable}, @code{debug-set!} and @code{debug-options}.
 @end deffn
 
+
+@section Using Traps
+
 @deffn {Scheme Procedure} with-traps thunk
 @deffnx {C Function} scm_with_traps (thunk)
 Call @var{thunk} with traps enabled.
 @end deffn
 
-@deffn {Scheme Procedure} memoized? obj
-@deffnx {C Function} scm_memoized_p (obj)
-Return @code{#t} if @var{obj} is memoized.
-@end deffn
-
-@deffn {Scheme Procedure} unmemoize m
-@deffnx {C Function} scm_unmemoize (m)
-Unmemoize the memoized expression @var{m},
-@end deffn
-
-@deffn {Scheme Procedure} memoized-environment m
-@deffnx {C Function} scm_memoized_environment (m)
-Return the environment of the memoized expression @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-name proc
-@deffnx {C Function} scm_procedure_name (proc)
-Return the name of the procedure @var{proc}
-@end deffn
-
-@deffn {Scheme Procedure} procedure-source proc
-@deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-environment proc
-@deffnx {C Function} scm_procedure_environment (proc)
-Return the environment of the procedure @var{proc}.
-@end deffn
-
 @deffn {Scheme Procedure} debug-object? obj
 @deffnx {C Function} scm_debug_object_p (obj)
 Return @code{#t} if @var{obj} is a debug object.
 @end deffn
 
-@deffn {Scheme Procedure} frame-arguments frame
-@deffnx {C Function} scm_frame_arguments (frame)
-Return the arguments of @var{frame}.
-@end deffn
 
-@deffn {Scheme Procedure} frame-evaluating-args? frame
+@section Capturing the Stack or Innermost Stack Frame
-@deffnx {C Function} scm_frame_evaluating_args_p (frame)
-Return @code{#t} if @var{frame} contains evaluated arguments.
-@end deffn
-
-@deffn {Scheme Procedure} frame-next frame
-@deffnx {C Function} scm_frame_next (frame)
-Return the next frame of @var{frame}, or @code{#f} if
-@var{frame} is the last frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-number frame
-@deffnx {C Function} scm_frame_number (frame)
-Return the frame number of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-overflow? frame
-@deffnx {C Function} scm_frame_overflow_p (frame)
-Return @code{#t} if @var{frame} is an overflow frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-previous frame
-@deffnx {C Function} scm_frame_previous (frame)
-Return the previous frame of @var{frame}, or @code{#f} if
-@var{frame} is the first frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure frame
-@deffnx {C Function} scm_frame_procedure (frame)
-Return the procedure for @var{frame}, or @code{#f} if no
-procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure? frame
-@deffnx {C Function} scm_frame_procedure_p (frame)
-Return @code{#t} if a procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-real? frame
-@deffnx {C Function} scm_frame_real_p (frame)
-Return @code{#t} if @var{frame} is a real frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-source frame
-@deffnx {C Function} scm_frame_source (frame)
-Return the source of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame? obj
-@deffnx {C Function} scm_frame_p (obj)
-Return @code{#t} if @var{obj} is a stack frame.
-@end deffn
-
-@deffn {Scheme Procedure} last-stack-frame obj
-@deffnx {C Function} scm_last_stack_frame (obj)
-Return a stack which consists of a single frame, which is the
-last stack frame for @var{obj}. @var{obj} must be either a
-debug object or a continuation.
-@end deffn
 
 @deffn {Scheme Procedure} make-stack obj . args
 @deffnx {C Function} scm_make_stack (obj, args)
@@ -191,6 +57,21 @@ If the @var{outer_cut_N} of the last pair is missing, it is
 taken as 0.
 @end deffn
 
+@deffn {Scheme Procedure} last-stack-frame obj
+@deffnx {C Function} scm_last_stack_frame (obj)
+Return a stack which consists of a single frame, which is the
+last stack frame for @var{obj}. @var{obj} must be either a
+debug object or a continuation.
+@end deffn
+
+
+@section Examining the Stack
+
+@deffn {Scheme Procedure} stack? obj
+@deffnx {C Function} scm_stack_p (obj)
+Return @code{#t} if @var{obj} is a calling stack.
+@end deffn
+
 @deffn {Scheme Procedure} stack-id stack
 @deffnx {C Function} scm_stack_id (stack)
 Return the identifier given to @var{stack} by @code{start-stack}.
@@ -206,9 +87,99 @@ Return the length of @var{stack}.
 Return the @var{index}'th frame from @var{stack}.
 @end deffn
 
-@deffn {Scheme Procedure} stack? obj
+@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
-@deffnx {C Function} scm_stack_p (obj)
+@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
-Return @code{#t} if @var{obj} is a calling stack.
+Display a backtrace to the output port @var{port}. @var{stack}
+is the stack to take the backtrace from, @var{first} specifies
+where in the stack to start and @var{depth} how much frames
+to display. Both @var{first} and @var{depth} can be @code{#f},
+which means that default values will be used.
+@end deffn
+
+
+@section Examining Stack Frames
+
+@deffn {Scheme Procedure} frame? obj
+@deffnx {C Function} scm_frame_p (obj)
+Return @code{#t} if @var{obj} is a stack frame.
+@end deffn
+
+@deffn {Scheme Procedure} frame-number frame
+@deffnx {C Function} scm_frame_number (frame)
+Return the frame number of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-previous frame
+@deffnx {C Function} scm_frame_previous (frame)
+Return the previous frame of @var{frame}, or @code{#f} if
+@var{frame} is the first frame in its stack.
+@end deffn
+
+@deffn {Scheme Procedure} frame-next frame
+@deffnx {C Function} scm_frame_next (frame)
+Return the next frame of @var{frame}, or @code{#f} if
+@var{frame} is the last frame in its stack.
+@end deffn
+
+@deffn {Scheme Procedure} frame-source frame
+@deffnx {C Function} scm_frame_source (frame)
+Return the source of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-procedure? frame
+@deffnx {C Function} scm_frame_procedure_p (frame)
+Return @code{#t} if a procedure is associated with @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-procedure frame
+@deffnx {C Function} scm_frame_procedure (frame)
+Return the procedure for @var{frame}, or @code{#f} if no
+procedure is associated with @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-arguments frame
+@deffnx {C Function} scm_frame_arguments (frame)
+Return the arguments of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-evaluating-args? frame
+@deffnx {C Function} scm_frame_evaluating_args_p (frame)
+Return @code{#t} if @var{frame} contains evaluated arguments.
+@end deffn
+
+@deffn {Scheme Procedure} frame-overflow? frame
+@deffnx {C Function} scm_frame_overflow_p (frame)
+Return @code{#t} if @var{frame} is an overflow frame.
+@end deffn
+
+@deffn {Scheme Procedure} frame-real? frame
+@deffnx {C Function} scm_frame_real_p (frame)
+Return @code{#t} if @var{frame} is a real frame.
+@end deffn
+
+@deffn {Scheme Procedure} display-application frame [port [indent]]
+@deffnx {C Function} scm_display_application (frame, port, indent)
+Display a procedure application @var{frame} to the output port
+@var{port}. @var{indent} specifies the indentation of the
+output.
+@end deffn
+
+
+@section Decoding Memoized Source Expressions
+
+@deffn {Scheme Procedure} memoized? obj
+@deffnx {C Function} scm_memoized_p (obj)
+Return @code{#t} if @var{obj} is memoized.
+@end deffn
+
+@deffn {Scheme Procedure} unmemoize m
+@deffnx {C Function} scm_unmemoize (m)
+Unmemoize the memoized expression @var{m},
+@end deffn
+
+@deffn {Scheme Procedure} memoized-environment m
+@deffnx {C Function} scm_memoized_environment (m)
+Return the environment of the memoized expression @var{m}.
 @end deffn
 
 

doc/ref/scheme-memory.texi

@@ -38,6 +38,14 @@ Flushes the glocs for @var{name}, or all glocs if @var{name}
 is @code{#t}.
 @end deffn
 
+@deffn {Scheme Procedure} malloc-stats
+Return an alist ((@var{what} . @var{n}) ...) describing number
+of malloced objects.
+@var{what} is the second argument to @code{scm_must_malloc},
+@var{n} is the number of objects of that type currently
+allocated.
+@end deffn
+
 
 @node Weak References
 @section Weak References

doc/ref/scheme-procedures.texi

@@ -368,6 +368,21 @@ Procedure properties are general properties to be attached to
 procedures.  These can be the name of a procedure or other relevant
 information, such as debug hints.
 
+@deffn {Scheme Procedure} procedure-name proc
+@deffnx {C Function} scm_procedure_name (proc)
+Return the name of the procedure @var{proc}
+@end deffn
+
+@deffn {Scheme Procedure} procedure-source proc
+@deffnx {C Function} scm_procedure_source (proc)
+Return the source of the procedure @var{proc}.
+@end deffn
+
+@deffn {Scheme Procedure} procedure-environment proc
+@deffnx {C Function} scm_procedure_environment (proc)
+Return the environment of the procedure @var{proc}.
+@end deffn
+
 @deffn {Scheme Procedure} procedure-properties proc
 @deffnx {C Function} scm_procedure_properties (proc)
 Return @var{obj}'s property list.
@@ -627,11 +642,10 @@ example of the previous section looks like this:
 
 In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
 syncase)} module.  To make these facilities available in your code,
-include the expression @code{(use-modules (ice-9 syncase))} or
+include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
-@code{(use-syntax (ice-9 syncase))} (@pxref{Using Guile Modules})
+Guile Modules}) before the first usage of @code{define-syntax} etc.  If
-before the first usage of @code{define-syntax} etc.  If you are writing
+you are writing a Scheme module, you can alternatively include the form
-a Scheme module, you can alternatively use one of the keywords
+@code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
-@code{#:use-module} and @code{#:use-syntax} in your @code{define-module}
 declaration (@pxref{Creating Guile Modules}).
 
 @menu