diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index ced89de8c..235c53373 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,5 +1,29 @@ 2002-04-20 Neil Jerram + * 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. diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi index 0a2471ca8..06a61473d 100644 --- a/doc/ref/debugging.texi +++ b/doc/ref/debugging.texi @@ -1,6 +1,6 @@ @page -@node Debugger User Interface -@chapter Debugger User Interface +@node Debugging Features +@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 diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 25f9ef264..c819fb53d 100644 --- a/doc/ref/guile.texi +++ b/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 For use with Guile @value{VERSION} +@subtitle Edition @value{MANUAL_EDITION}, 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. -* Programming Overview:: An overview of Guile programming. -* Scheme Intro:: Introduction to Guile Scheme. -* Basic Ideas:: Basic ideas in Scheme. +* Running Intro:: Introduction to this part. +* Guile Scheme:: Guile's implementation of Scheme. * Guile Scripting:: How to write Guile scripts. * Command Line Handling:: Command line options and arguments. -* Libguile Intro:: Using Guile as an extension language. -* Guile API:: Overview of the Guile API. -* Data Representation:: Data representation in Guile. -* GH:: The deprecated GH interface. -* Debugger User Interface:: +* Debugging Features:: Features for debugging errors. * 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 -@unnumbered Part II: Programming with Guile +@node Running Intro +@unnumbered Part II: Writing and Running Guile Scheme -In this part of the manual, we aim to present a wide ranging picture of -what it means to program using Guile, 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 +Guile's core language is Scheme, and an awful lot can be achieved simply +by using Guile to write and run Scheme programs. In this part of the +manual, we explain how to use Guile in this mode, and describe the tools +that Guile provides to help you with script writing, debugging and +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 diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi index 0a6ce32ba..bcabb411a 100644 --- a/doc/ref/preface.texi +++ b/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 -practical programming using Guile. This covers both the Scheme level ---- where we provide an introduction to the key ideas of the Scheme -language --- and use of Guile's @code{scm} interface to write new -primitives and objects in C, and to incorporate Guile into a C -application. It also covers the use of Guile as a POSIX compliant -script interpreter, and how to use the Guile debugger. +@strong{Part II: Writing and Running Guile Scheme} and @strong{Part III: +Programming with Guile} document all aspects of practical programming +using Guile. This covers both the Scheme level --- where we provide an +introduction to the key ideas of the Scheme language --- and use of +Guile's @code{scm} interface to write new primitives and objects in C, +and to incorporate Guile into a C application. It also covers the use +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: diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi index ce0be8907..670bd0884 100644 --- a/doc/ref/scheme-debug.texi +++ b/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: diff --git a/doc/ref/scheme-intro.texi b/doc/ref/scheme-intro.texi index 3cd9967b4..22e875339 100644 --- a/doc/ref/scheme-intro.texi +++ b/doc/ref/scheme-intro.texi @@ -1,6 +1,6 @@ @page -@node Scheme Intro -@chapter Introduction to Guile Scheme +@node 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" diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi index 06bb813af..b2895f636 100644 --- a/doc/ref/scheme-modules.texi +++ b/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}). diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi index 06a3b19a3..d4a634eb9 100644 --- a/doc/ref/scm.texi +++ b/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}.