Manual debugging and refactoring work.

doc/ref/ChangeLog

@@ -1,5 +1,29 @@
 2002-04-20  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* scheme-intro.texi (Scheme Layout), scm.texi (Reference Layout):
+	Node moved from a to b.
+
+	* guile.texi (Scheme Intro, Basic Ideas, Guile Scripting, Command
+	Line Handling, Debugging Features, Autoconf Support, Miscellaneous
+	Tools, Further Reading): Moved to new Part II.
+
+	* preface.texi (Manual Layout): Part numbers updated accordingly.
+
+	* guile.texi (Top): Move API Overview node to beginning of Guile
+	API Reference part.
+	(Part II: Writing and Running Guile Scheme): New part; will
+	contain content from `Programming with Guile' that pertains to
+	writing and using Guile on the Scheme level.
+
+	* scm.texi (API Overview): Renamed from `Guile API'.
+
+	* guile.texi (Top), scheme-modules.texi (Included Guile Modules):
+	Debugger User Interface node renamed Debugging Features.
+
+	* debugging.texi (Stacks and Frames): Node deleted; non-duplicated
+	material moved to scheme-debug.texi.
+	(Debugging Features): Renamed from `Debugger User Interface'.
+
 	* scheme-debug.texi (Debugging): Rename chapter `Debugging
 	Infrastructure' and reorganize its contents.
 	

doc/ref/debugging.texi

@@ -1,6 +1,6 @@
 @page
-@node Debugger User Interface
+@node Debugging Features
-@chapter Debugger User Interface
+@chapter Debugging Features
 
 @c      --- The title and introduction of this appendix need to
 @c          distinguish this clearly from the chapter on the internal
@@ -23,7 +23,6 @@ and explain why they can't be used to debug interpreted Scheme or Lisp?]
 * 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
 
  
@@ -114,74 +113,3 @@ iteration.  Using @code{trace} here helps us see why this is so.
 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
-
-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

doc/ref/guile.texi

@@ -100,8 +100,8 @@ by the Free Software Foundation.
 @sp 10
 @comment The title is printed in a large font.
 @title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.17 2002-04-01 18:46:26 ossau Exp $
+@subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION}
-@subtitle For use with Guile @value{VERSION}
+@subtitle $Id: guile.texi,v 1.18 2002-04-20 19:26:40 ossau Exp $
 
 @c AUTHORS
 
@@ -217,26 +217,30 @@ Part I: Introduction to Guile
 * Obtaining and Installing Guile::
 * Reporting Bugs::              Reporting bugs in Guile or this manual.
 
-Part II: Programming with Guile
+Part II: Writing and Running Guile Scheme
 
-* Programming Intro::           Introduction to this part.
+* Running Intro::               Introduction to this part.
-* Programming Overview::        An overview of Guile programming.
+* Guile Scheme::                Guile's implementation of Scheme.
-* Scheme Intro::                Introduction to Guile Scheme.
-* Basic Ideas::                 Basic ideas in Scheme.
 * Guile Scripting::             How to write Guile scripts.
 * Command Line Handling::       Command line options and arguments.
-* Libguile Intro::              Using Guile as an extension language.
+* Debugging Features::          Features for debugging errors.
-* Guile API::                   Overview of the Guile API.
-* Data Representation::         Data representation in Guile.
-* GH::                          The deprecated GH interface.
-* Debugger User Interface::
 * Autoconf Support::            Guile-specific configure.in macros.
 * Miscellaneous Tools::         Snarfing, linting, etc.
-* Further Reading::             Where to find out more about Scheme programming.
+* Basic Ideas::                 Basic ideas in Scheme.
+* Further Reading::             Where to find out more about Scheme.
 
-Part III: Guile API Reference
+Part III: Guile as an Extension Language
+
+* Programming Intro::           Introduction to this part.
+* Libguile Intro::              Using Guile as an extension language.
+* Programming Overview::        An overview of Guile programming.
+* Data Representation::         Data representation in Guile.
+* GH::                          The deprecated GH interface.
+
+Part IV: Guile API Reference
 
 * Reference Intro::             Introduction to the Guile API reference.
+* API Overview::                Overview of the Guile API.
 * Simple Data Types::           Numbers, strings, booleans and so on.
 * Compound Data Types::         Data types for holding other data.
 * Procedures and Macros::       Procedures and macros.
@@ -254,7 +258,7 @@ Part III: Guile API Reference
 * Debugging::                   Internal debugging interface.
 * Deprecated::                  Features that are planned to disappear.
 
-Part IV: Guile Modules
+Part V: Guile Modules
 
 * SLIB::                        Using the SLIB Scheme library.
 * POSIX::                       POSIX system calls and networking.
@@ -287,43 +291,61 @@ Indices
 @include intro.texi
 
 @page
-@node Programming Intro
+@node Running Intro
-@unnumbered Part II: Programming with Guile
+@unnumbered Part II: Writing and Running Guile Scheme
 
-In this part of the manual, we aim to present a wide ranging picture of
+Guile's core language is Scheme, and an awful lot can be achieved simply
-what it means to program using Guile, to provide guidance, practical
+by using Guile to write and run Scheme programs.  In this part of the
-guidelines and tips for @emph{how} to program in Guile, and to document
+manual, we explain how to use Guile in this mode, and describe the tools
-the tools that are available to help you with your programming.  For
+that Guile provides to help you with script writing, debugging and
-detailed reference information on the variables, functions etc. that
+packaging your programs for distribution.
+
+For readers who are not yet familiar with the Scheme language, this part
+includes a chapter that presents the basic concepts of the language, and
+gives references to freely available Scheme tutorial material on the
+web.
+
+For detailed reference information on the variables, functions etc. that
 make up Guile's application programming interface (API), please refer to
-Part III (@pxref{Reference Intro,,Part III --- Guile API Reference}).
+Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).
 
-We begin in the first chapter of this part by looking at the programming
-options available.
-
-@include program.texi
 @include scheme-intro.texi
-@include scheme-ideas.texi
 @include scripts.texi
 @include script-getopt.texi
-@include extend.texi
-@include scm.texi
-@include data-rep.texi
-@include gh.texi
 @include debugging.texi
 @include autoconf.texi
 @include tools.texi
+@include scheme-ideas.texi
 @include scheme-reading.texi
 
+@page
+@node Programming Intro
+@unnumbered Part III: Guile as an Extension Language
+
+In this part of the manual, we aim to present a wide ranging picture of
+what it means to use Guile as an application extension language, to
+provide guidance, practical guidelines and tips for @emph{how} to
+program in Guile, and to document the tools that are available to help
+you with your programming.  For detailed reference information on the
+variables, functions etc. that make up Guile's application programming
+interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
+IV --- Guile API Reference}).
+
+@include extend.texi
+@include program.texi
+@include data-rep.texi
+@include gh.texi
+
 @page
 @node Reference Intro
-@unnumbered Part III: Guile API Reference
+@unnumbered Part IV: Guile API Reference
 
 Guile provides an application programming interface (@dfn{API}) to
 developers in two core languages: Scheme and C.  This part of the manual
 contains reference documentation for all of the functionality that is
 available through both Scheme and C interfaces.
 
+@include scm.texi
 @include scheme-data.texi
 @include scheme-compound.texi
 @include scheme-procedures.texi
@@ -343,7 +365,7 @@ available through both Scheme and C interfaces.
 
 @iftex
 @page
-@unnumbered{Part IV: Guile Modules}
+@unnumbered{Part V: Guile Modules}
 @end iftex
 
 @include slib.texi

doc/ref/preface.texi

@@ -74,7 +74,7 @@ do not wish that, delete this exception notice.
 @chapter Layout of this Manual
 @end ifnottex
 
-The manual is divided into three parts.
+The manual is divided into five parts.
 
 @strong{Part I: Introduction to Guile} provides an overview of what
 Guile is and how you can use it.  A whirlwind tour shows how Guile can
@@ -85,13 +85,14 @@ documented again and in full by the later parts of the manual.  This
 part also explains how to obtain and install new versions of Guile, and
 how to report bugs effectively.
 
-@strong{Part II: Programming with Guile} documents all aspects of
+@strong{Part II: Writing and Running Guile Scheme} and @strong{Part III:
-practical programming using Guile.  This covers both the Scheme level
+Programming with Guile} document all aspects of practical programming
---- where we provide an introduction to the key ideas of the Scheme
+using Guile.  This covers both the Scheme level --- where we provide an
-language --- and use of Guile's @code{scm} interface to write new
+introduction to the key ideas of the Scheme language --- and use of
-primitives and objects in C, and to incorporate Guile into a C
+Guile's @code{scm} interface to write new primitives and objects in C,
-application.  It also covers the use of Guile as a POSIX compliant
+and to incorporate Guile into a C application.  It also covers the use
-script interpreter, and how to use the Guile debugger.
+of Guile as a POSIX compliant script interpreter, and how to use the
+Guile debugger.
 
 @c @strong{Part V: Extending Applications Using Guile} explains the options
 @c available for using Guile as a application extension language.  At the
@@ -106,7 +107,7 @@ script interpreter, and how to use the Guile debugger.
 @c This part of the manual covers the complete range of application
 @c extension options.
 
-@strong{Part III: Guile API Reference} documents Guile's core API.  Most
+@strong{Part IV: Guile API Reference} documents Guile's core API.  Most
 of the variables and procedures in Guile's core programming interface
 are available in both Scheme and C, and are related systematically such
 that the C interface can be inferred from the Scheme interface and vice
@@ -127,7 +128,7 @@ together.
 @c all documented from scratch, and organized by functionality rather than
 @c by the defining standards.
 
-@strong{Part IV: Guile Modules} describes some important modules,
+@strong{Part V: Guile Modules} describes some important modules,
 distributed as part of the Guile distribution, that extend the
 functionality provided by the Guile Scheme core.  Two important examples
 are:

doc/ref/scheme-debug.texi

@@ -25,6 +25,13 @@ Return @code{#t} if @var{obj} is a debug object.
 
 @section Capturing the Stack or Innermost Stack Frame
 
+When an error occurs in a running program, or the program hits a
+breakpoint, its state at that point can be represented by a @dfn{stack}
+of all the evaluations and procedure applications that are logically in
+progress at that time, each of which is known as a @dfn{frame}.  The
+programmer can learn more about the program's state at the point of
+interruption or error by inspecting the stack and its frames.
+
 @deffn {Scheme Procedure} make-stack obj . args
 @deffnx {C Function} scm_make_stack (obj, args)
 Create a new stack. If @var{obj} is @code{#t}, the current
@@ -183,6 +190,17 @@ Return the environment of the memoized expression @var{m}.
 @end deffn
 
 
+@section Starting a New Stack
+
+@deffn {Scheme 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
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:

doc/ref/scheme-intro.texi

@@ -1,6 +1,6 @@
 @page
-@node Scheme Intro
+@node Guile Scheme
-@chapter Introduction to Guile Scheme
+@chapter Guile's Implementation of Scheme
 
 Guile's core language is Scheme, which is specified and described in the
 series of reports known as @dfn{RnRS}.  @dfn{RnRS} is shorthand for the
@@ -30,24 +30,6 @@ Guile's support for POSIX-compliant network programming
 GOOPS -- Guile's framework for object oriented programming.
 @end itemize
 
-@menu
-* Scheme Layout::               The layout of this part of the manual.
-@end menu
-
-
-@node Scheme Layout
-@section Layout
-
-This part of the reference manual documents all of Guile's core
-Scheme-level language and features in functionally-related groups.
-Where a particular section of the manual includes both R5RS-compliant
-parts and Guile-specific extensions, the text indicates which parts of
-the documentation describe R5RS behaviour and which parts describe Guile
-extensions.
-
-For a quick way of identifying the parts of Guile that implement
-R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
-
 
 @c Local Variables:
 @c TeX-master: "guile.texi"

doc/ref/scheme-modules.texi

@@ -389,7 +389,7 @@ Guile starts up.
 
 @item (ice-9 debug)
 Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Debugger User Interface}).
+(@pxref{Debugging Features}).
 
 @item (ice-9 threads)
 Guile's support for multi threaded execution (@pxref{Scheduling}).

doc/ref/scm.texi

@@ -1,5 +1,5 @@
 @page
-@node Guile API
+@node API Overview
 @chapter Overview of the Guile API
 
 Guile's application programming interface (@dfn{API}) makes
@@ -40,6 +40,7 @@ primitives on which it is based.
 * Primitives::                  Identical function for Scheme and C.
 * C Only::                      Elements only available in C.
 * Scheme Only::                 Elements only available in Scheme.
+* Reference Layout::            The layout of this part of the manual.
 @end menu
 
 
@@ -164,3 +165,17 @@ generic @code{SCM}.
 
 @node Scheme Only
 @section Elements Available Only in Scheme
+
+
+@node Reference Layout
+@section Reference Material Layout
+
+This part of the reference manual documents all of Guile's core
+Scheme-level language and features in functionally-related groups.
+Where a particular section of the manual includes both R5RS-compliant
+parts and Guile-specific extensions, the text indicates which parts of
+the documentation describe R5RS behaviour and which parts describe Guile
+extensions.
+
+For a quick way of identifying the parts of Guile that implement
+R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.