Add interface to disable automatic finalization
[bpt/guile.git] / doc / ref / guile.texi
index a56f95c..d7a265f 100644 (file)
@@ -2,28 +2,26 @@
 @c -*-texinfo-*-
 @c %**start of header
 @setfilename guile.info
+@documentencoding UTF-8
 @settitle Guile Reference Manual
 @set guile
-@set MANUAL-EDITION 1.1
+@set MANUAL-REVISION 1
 @c %**end of header
 @include version.texi
-@include lib-version.texi
+@include effective-version.texi
 
 @copying
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions.  This is edition @value{MANUAL-EDITION}
-corresponding to Guile @value{VERSION}.
+This manual documents Guile version @value{VERSION}.
 
-Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005 Free
-Software Foundation.
+Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
+2010, 2011, 2012, 2013, 2014 Free Software Foundation.
 
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
-any later version published by the Free Software Foundation; with the
-no Invariant Sections, with the Front-Cover Texts being ``A GNU
-Manual,'' and with the Back-Cover Text ``You are free to copy and
-modify this GNU Manual.''.  A copy of the license is included in the
-section entitled ``GNU Free Documentation License''.
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
 @end copying
 
 
@@ -137,7 +135,7 @@ x
 @sp 10
 @comment The title is printed in a large font.
 @title Guile Reference Manual
-@subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
+@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION}
 @c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $
 
 @c See preface.texi for the list of authors
@@ -168,7 +166,10 @@ x
 @menu
 
 * Preface::
-* Introduction to Guile::
+* Introduction::
+
+* Hello Guile!::
+* Hello Scheme!::
 
 * Programming in Scheme::
 * Programming in C::
@@ -177,11 +178,12 @@ x
 
 * Guile Modules::
 
-* Autoconf Support::
+* GOOPS::
+
+* Guile Implementation::
 
 Appendices
 
-* Data Representation::             All the details.
 * GNU Free Documentation License::  The license of this manual.
 
 Indices
@@ -200,38 +202,38 @@ Indices
 
 @include intro.texi
 
+@include tour.texi
+
+@include scheme-ideas.texi
+@include scheme-reading.texi
+
 @node Programming in Scheme
 @chapter Programming in Scheme
 
-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.
+Guile's core language is Scheme, and a lot can be achieved simply by using Guile
+to write and run Scheme programs --- as opposed to having to dive into C code.
+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),
-@xref{API Reference}.
+For detailed reference information on the variables, functions, and so
+on that make up Guile's application programming interface (API), see
+@ref{API Reference}.
 
 @menu
-* Basic Ideas::                 Basic ideas in Scheme.
 * Guile Scheme::                Guile's implementation of Scheme.
+* Invoking Guile::              Selecting optional features when starting Guile.
 * Guile Scripting::             How to write Guile scripts.
 * Using Guile Interactively::   Guile's REPL features.
 * Using Guile in Emacs::        Guile and Emacs.
-* Further Reading::             Where to find out more about Scheme.
+* Using Guile Tools::           A guild of scheming wizards.
+* Installing Site Packages::    Installing Scheme code.
 @end menu
 
-@include scheme-ideas.texi
 @include scheme-intro.texi
+@include guile-invoke.texi
 @include scheme-scripts.texi
 @include scheme-using.texi
-@include scheme-reading.texi
 
 @node Programming in C
 @chapter Programming in C
@@ -251,31 +253,35 @@ musings and guidelines about programming with Guile.  It explores
 different ways to design a program around Guile, or how to embed Guile
 into existing programs.
 
-There is also a pedagogical yet detailed explanation of how the data
-representation of Guile is implemented, @xref{Data Representation}.
-You don't need to know the details given there to use Guile from C,
-but they are useful when you want to modify Guile itself or when you
-are just curious about how it is all done.
+For a pedagogical yet detailed explanation of how the data representation of
+Guile is implemented, @xref{Data Representation}. You don't need to know the
+details given there to use Guile from C, but they are useful when you want to
+modify Guile itself or when you are just curious about how it is all done.
 
 For detailed reference information on the variables, functions
 etc. that make up Guile's application programming interface (API),
 @xref{API Reference}.
 
 @menu
+* Parallel Installations::      Finding the right Guile.
 * Linking Programs With Guile:: More precisely, with the libguile library.
 * Linking Guile with Libraries::  To extend Guile itself. 
 * General Libguile Concepts::   General concepts for using libguile.
 * Defining New Types (Smobs)::  Adding new types to Guile.
 * Function Snarfing::           A way to define new functions.
 * Programming Overview::        An overview of Guile programming.
+* Autoconf Support::            Putting m4 to good use.
 @end menu
 
+@include libguile-parallel.texi
 @include libguile-linking.texi
 @include libguile-extensions.texi
 @include libguile-concepts.texi
 @include libguile-smobs.texi
 @include libguile-snarf.texi
 @include libguile-program.texi
+@include libguile-autoconf.texi
+
 
 @node API Reference
 @chapter API Reference
@@ -287,30 +293,35 @@ available through both Scheme and C interfaces.
 
 @menu
 * API Overview::                Overview of the Guile API.
+* Deprecation::                 Obsolete back-compatible APIs.
 * The SCM Type::                The fundamental data type for C code.
 * Initialization::              Initializing Guile.
 * Snarfing Macros::             Macros for snarfing initialization actions.
 * Simple Data Types::           Numbers, strings, booleans and so on.
 * Compound Data Types::         Data types for holding other data.
 * Smobs::                       Defining new data types in C.
-* Procedures and Macros::       Procedures and macros.
+* Procedures::                  Procedures.
+* Macros::                      Extending the syntax of Scheme.
 * Utility Functions::           General utility functions.
 * Binding Constructs::          Definitions and variable bindings.
 * Control Mechanisms::          Controlling the flow of program execution.
 * Input and Output::            Ports, reading and writing.
-* Read/Load/Eval::              Reading and evaluating Scheme code.
+* Regular Expressions::         Pattern matching and substitution.
+* LALR(1) Parsing::             Generating LALR(1) parsers.
+* Read/Load/Eval/Compile::      Reading and evaluating Scheme code.
 * Memory Management::           Memory management and garbage collection.
-* Objects::                     Low level object orientation support.
 * Modules::                     Designing reusable code libraries.
+* Foreign Function Interface::  Interacting with C procedures and data.
 * Scheduling::                  Threads, mutexes, asyncs and dynamic roots.
 * Options and Config::          Configuration, features and runtime options.
-* Translation::                 Support for translating other languages.
+* Other Languages::             Emacs Lisp, ECMAScript, and more.
 * Internationalization::        Support for gettext, etc.
 * Debugging::                   Debugging infrastructure and Scheme interface.
-* GH::                          The deprecated GH interface.
+* Code Coverage::               Gathering code coverage data.
 @end menu
 
 @include api-overview.texi
+@include api-deprecated.texi
 @include api-scm.texi
 @include api-init.texi
 @include api-snarf.texi
@@ -318,20 +329,24 @@ available through both Scheme and C interfaces.
 @include api-compound.texi
 @include api-smobs.texi
 @include api-procedures.texi
+@include api-macros.texi
 @include api-utility.texi
 @include api-binding.texi
 @include api-control.texi
 @include api-io.texi
+@include api-regex.texi
+@include api-lalr.texi
 @include api-evaluation.texi
 @include api-memory.texi
 @include api-modules.texi
+@include api-foreign.texi
 @include api-scheduling.texi
 @c object orientation support here
 @include api-options.texi
-@include api-translation.texi
+@include api-languages.texi
 @include api-i18n.texi
 @include api-debug.texi
-@include gh.texi
+@include api-coverage.texi
 
 @node Guile Modules
 @chapter Guile Modules
@@ -339,10 +354,12 @@ available through both Scheme and C interfaces.
 @menu
 * SLIB::                        Using the SLIB Scheme library.
 * POSIX::                       POSIX system calls and networking.
+* Web::                         HTTP, the web, and all that.
 * getopt-long::                 Command line handling.
 * SRFI Support::                Support for various SRFIs.
+* R6RS Support::                Modules defined by the R6RS.
+* Pattern Matching::            Generic pattern matching constructs.
 * Readline Support::            Module for using the readline library.
-* Value History::               Maintaining a value history in the REPL.
 * Pretty Printing::             Nicely formatting Scheme objects for output.
 * Formatted Output::            The @code{format} procedure.
 * File Tree Walk::              Traversing the file system.
@@ -350,29 +367,75 @@ available through both Scheme and C interfaces.
 * Streams::                     Sequences of values.
 * Buffered Input::              Ports made from a reader function.
 * 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.
+* Curried Definitions::         Extended @code{define} syntax.
+* Statprof::                    An easy-to-use statistical profiler.
+* SXML::                        Parsing, transforming, and serializing XML.
+* Texinfo Processing::          Munging documents written in Texinfo.
 @end menu
 
 @include slib.texi
 @include posix.texi
+@include web.texi
 @include mod-getopt-long.texi
 @include srfi-modules.texi
+@include r6rs.texi
+@include match.texi
 @include repl-modules.texi
 @include misc-modules.texi
 @include expect.texi
+
+@c XXX: Would be nicer if it were close to the (sxml simple) documentation.
+@include sxml-match.texi
+
 @include scsh.texi
-@include scheme-debugging.texi
+@include curried.texi
 
-@include autoconf.texi
+@include statprof.texi
+@include sxml.texi
+@include texinfo.texi
 
+@include goops.texi
+
+@node Guile Implementation
+@chapter Guile Implementation
+
+At some point, after one has been programming in Scheme for some time,
+another level of Scheme comes into view: its implementation. Knowledge
+of how Scheme can be implemented turns out to be necessary to become
+an expert hacker. As Peter Norvig notes in his retrospective on
+PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
+Artificial Intelligence Programming}, an old but still useful text on
+Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
+found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
+programmer eventually develops a good `efficiency model'.''
+
+By this Norvig means that over time, the Lisp hacker eventually
+develops an understanding of how much her code ``costs'' in terms of
+space and time.
+
+This chapter describes Guile as an implementation of Scheme: its
+history, how it represents and evaluates its data, and its compiler.
+This knowledge can help you to make that step from being one who is
+merely familiar with Scheme to being a real hacker.
+
+@menu
+* History::                          A brief history of Guile.
+* Data Representation::              How Guile represents Scheme data.
+* A Virtual Machine for Guile::      How compiled procedures work.
+* Compiling to the Virtual Machine:: Not as hard as you might think.
+@end menu
+
+@include history.texi
 @include data-rep.texi
-@include fdl.texi
+@include vm.texi
+@include compiler.texi
 
-@iftex
-@page
-@unnumbered{Indices}
-@end iftex
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
 
 @include indices.texi
 @include scheme-indices.texi