@setfilename guile.info
@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
+Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010 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
+any later version published by the Free Software Foundation; with
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
@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
@menu
* Preface::
-* Introduction to Guile::
+* Introduction::
+
+* Hello Guile!::
+* Hello Scheme!::
* Programming in Scheme::
* Programming in C::
* API Reference::
* Guile Modules::
+* Standard Library::
+
+* GOOPS::
-* History and Implementation Details::
+* Guile Implementation::
* Autoconf Support::
@include intro.texi
+@include tour.texi
+
+@raisesections
+@include scheme-ideas.texi
+@lowersections
+@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.
-
-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.
+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 detailed reference information on the variables, functions
etc. that make up Guile's application programming interface (API),
@xref{API Reference}.
@menu
-* Basic Ideas:: Basic ideas in Scheme.
* Guile Scheme:: Guile's implementation of Scheme.
* 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.
@end menu
-@include scheme-ideas.texi
@include scheme-intro.texi
@include scheme-scripts.texi
@include scheme-using.texi
-@include scheme-reading.texi
@node Programming in C
@chapter Programming in C
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, see @ref{Data Representation in
-Scheme} and @ref{The Libguile Runtime Environment}.
-
-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),
@menu
* API Overview:: Overview of the Guile API.
+* Discouraged and Deprecated:: 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.
+* 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.
@end menu
@include api-overview.texi
+@include api-discdepr.texi
@include api-scm.texi
@include api-init.texi
@include api-snarf.texi
@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-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 scsh.texi
@include scheme-debugging.texi
-@include autoconf.texi
+@node Standard Library
+@chapter Standard Library
+
+@lowersections
+@include standard-library.texi
+@raisesections
+
+@include goops.texi
-@node History and Implementation Details
-@chapter History and Implementation Details
+@node Guile Implementation
+@chapter Guile Implementation
-Some mumblings about Guile as an artifact of historical processes;
-knowledge of this history useful when hacking the source code.
-Libguile as the end product of
+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
-* A Brief History of Guile:: Foo.
-* Data Representation in Scheme:: Why things aren't just totally
- straightforward, in general terms.
-* The Libguile Runtime Environment:: Low-level details on Guile's C
- runtime library.
-* A Virtual Machine for Guile:: Foo.
-* Compiling to the Virtual Machine:: Bar.
+* 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 vm.texi
@include compiler.texi
+@include autoconf.texi
+
@include fdl.texi
@iftex
HCoop / bpt / guile.git / blobdiff