X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/108e18b18abc066b2709a09283751e9138ccc935..de3ba527c4cfbd6e168191a4fd305aedccac6e0c:/doc/ref/intro.texi?ds=sidebyside

diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
dissimilarity index 88%
index 7e248e0e8..f3a736e57 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -1,591 +1,279 @@
-@c -*-texinfo-*-
-@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
-@c   Free Software Foundation, Inc.
-@c See the file guile.texi for copying conditions.
-
-@node Introduction to Guile
-@chapter Introduction to Guile
-
-@menu
-* What is Guile?::              
-* Obtaining and Installing Guile::  
-* Whirlwind Tour::              
-* Discouraged and Deprecated::
-* Reporting Bugs::              
-@end menu
-
-@node What is Guile?
-@section What is Guile?
-
-Guile is an interpreter for the Scheme programming language, packaged
-for use in a wide variety of environments.  Guile implements Scheme as
-described in the
-@tex
-Revised$^5$
-@end tex
-@ifnottex
-Revised^5
-@end ifnottex
-Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
-providing clean and general data and control structures.  Guile goes
-beyond the rather austere language presented in @acronym{R5RS}, extending it with
-a module system, full access to @acronym{POSIX} system calls, networking support,
-multiple threads, dynamic linking, a foreign function call interface,
-powerful string processing, and many other features needed for
-programming in the real world.
-
-Like a shell, Guile can run interactively, reading expressions from the
-user, evaluating them, and displaying the results, or as a script
-interpreter, reading and executing Scheme code from a file.  However,
-Guile is also packaged as an object library, allowing other applications
-to easily incorporate a complete Scheme interpreter.  An application can
-then use Guile as an extension language, a clean and powerful configuration
-language, or as multi-purpose ``glue'', connecting primitives provided
-by the application.  It is easy to call Scheme code from C code and vice
-versa, giving the application designer full control of how and when to
-invoke the interpreter.  Applications can add new functions, data types,
-control structures, and even syntax to Guile, creating a domain-specific
-language tailored to the task at hand, but based on a robust language
-design.
-
-Guile's module system allows one to break up a large program into
-manageable sections with well-defined interfaces between them.
-Modules may contain a mixture of interpreted and compiled code; Guile
-can use either static or dynamic linking to incorporate compiled code.
-Modules also encourage developers to package up useful collections of
-routines for general distribution; as of this writing, one can find
-Emacs interfaces, database access routines, compilers, @acronym{GUI}
-toolkit interfaces, and @acronym{HTTP} client functions, among others.
-
-In the future, we hope to expand Guile to support other languages like
-Tcl and Perl by translating them to Scheme code.  This means that users
-can program applications which use Guile in the language of their
-choice, rather than having the tastes of the application's author
-imposed on them.
-
-@node Obtaining and Installing Guile
-@section Obtaining and Installing Guile
-
-Guile can be obtained from the main GNU archive site
-@url{ftp://ftp.gnu.org} or any of its mirrors.  The file will be named
-guile-version.tar.gz.  The current version is @value{VERSION}, so the
-file you should grab is:
-
-@url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
-
-To unbundle Guile use the instruction
-
-@example
-zcat guile-@value{VERSION}.tar.gz | tar xvf -
-@end example
-
-@noindent
-which will create a directory called @file{guile-@value{VERSION}} with
-all the sources.  You can look at the file @file{INSTALL} for detailed
-instructions on how to build and install Guile, but you should be able
-to just do
-
-@example
-cd guile-@value{VERSION}
-./configure
-make
-make install
-@end example
-
-This will install the Guile executable @file{guile}, the Guile library
-@file{libguile} and various associated header files and support
-libraries. It will also install the Guile tutorial and reference
-manual.
-
-@c [[include instructions for getting R5RS]]
-
-Since this manual frequently refers to the Scheme ``standard'', also
-known as R5RS, or the
-@tex
-``Revised$^5$ Report on the Algorithmic Language Scheme'',
-@end tex
-@ifnottex
-``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifnottex
-we have included the report in the Guile distribution; see
-@ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
-Language Scheme}.
-This will also be installed in your info directory.
-
-@node Whirlwind Tour
-@section A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used.  There are additional examples in the @file{examples/}
-directory in the Guile source distribution.
-
-The following examples assume that Guile has been installed in
-@code{/usr/local/}.
-
-@menu
-* Running Guile Interactively::
-* Running Guile Scripts::
-* Linking Guile into Programs::
-* Writing Guile Extensions::
-* Using the Guile Module System::
-@end menu
-
-
-@node Running Guile Interactively
-@subsection Running Guile Interactively
-
-In its simplest form, Guile acts as an interactive interpreter for the
-Scheme programming language, reading and evaluating Scheme expressions
-the user enters from the terminal.  Here is a sample interaction between
-Guile and a user; the user's input appears after the @code{$} and
-@code{guile>} prompts:
-
-@example
-$ guile
-guile> (+ 1 2 3)                ; add some numbers
-6
-guile> (define (factorial n)    ; define a function
-         (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
-  "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
-@end example
-
-
-@node Running Guile Scripts
-@subsection Running Guile Scripts
-
-Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-Here is a trivial Guile script, for more details @xref{Guile Scripting}.
-
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-
-
-@node Linking Guile into Programs
-@subsection Linking Guile into Programs
-
-The Guile interpreter is available as an object library, to be linked
-into applications using Scheme as a configuration or extension
-language.
-
-Here is @file{simple-guile.c}, source code for a program that will
-produce a complete Guile interpreter.  In addition to all usual
-functions provided by Guile, it will also offer the function
-@code{my-hostname}.
-
-@example
-#include <stdlib.h>
-#include <libguile.h>
-
-static SCM
-my_hostname (void)
-@{
-  char *s = getenv ("HOSTNAME");
-  if (s == NULL)
-    return SCM_BOOL_F;
-  else
-    return scm_from_locale_string (s);
-@}
-
-static void
-inner_main (void *data, int argc, char **argv)
-@{
-  scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
-  scm_shell (argc, argv);
-@}
-
-int
-main (int argc, char **argv)
-@{
-  scm_boot_guile (argc, argv, inner_main, 0);
-  return 0; /* never reached */
-@}
-@end example
-
-When Guile is correctly installed on your system, the above program
-can be compiled and linked like this:
-
-@example
-$ gcc -o simple-guile simple-guile.c -lguile
-@end example
-
-When it is run, it behaves just like the @code{guile} program except
-that you can also call the new @code{my-hostname} function.
-
-@example
-$ ./simple-guile
-guile> (+ 1 2 3)
-6
-guile> (my-hostname)
-"burns"
-@end example
-
-@node Writing Guile Extensions
-@subsection Writing Guile Extensions
-
-You can link Guile into your program and make Scheme available to the
-users of your program.  You can also link your library into Guile and
-make its functionality available to all users of Guile.
-
-A library that is linked into Guile is called an @dfn{extensions}, but
-it really just is an ordinary object library.
-
-The following example shows how to write a simple extension for Guile
-that makes the @code{j0} function available to Scheme code.
-
-@smallexample
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
-  return scm_make_real (j0 (scm_num2dbl (x, "j0")));
-@}
-
-void
-init_bessel ()
-@{
-  scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
-@}
-@end smallexample
-
-This C source file needs to be compiled into a shared library.  Here is
-how to do it on GNU/Linux:
-
-@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
-@end smallexample
-
-For creating shared libraries portably, we recommend the use of GNU
-Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
-
-A shared library can be loaded into a running Guile process with the
-function @code{load-extension}.  The @code{j0} is then immediately
-available:
-
-@smallexample
-$ guile
-guile> (load-extension "./libguile-bessel" "init_bessel")
-guile> (j0 2)
-0.223890779141236
-@end smallexample
-
-
-@node Using the Guile Module System
-@subsection Using the Guile Module System
-
-Guile has support for dividing a program into @dfn{modules}.  By using
-modules, you can group related code together and manage the
-composition of complete programs from largely independent parts.
-
-(Although the module system implementation is in flux, feel free to use it
-anyway.  Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
-@xref{Modules}.
-
-@menu
-* Using Modules::
-* Writing new Modules::
-* Putting Extensions into Modules::
-@end menu
-
-
-@node Using Modules
-@subsubsection Using Modules
-
-Guile comes with a lot of useful modules, for example for string
-processing or command line parsing.  Additionally, there exist many
-Guile modules written by other Guile hackers, but which have to be
-installed manually.
-
-Here is a sample interactive session that shows how to use the
-@code{(ice-9 popen)} module which provides the means for communicating
-with other processes over pipes together with the @code{(ice-9
-rdelim)} module that provides the function @code{read-line}.
-
-@smallexample
-$ guile
-guile> (use-modules (ice-9 popen))
-guile> (use-modules (ice-9 rdelim))
-guile> (define p (open-input-pipe "ls -l"))
-guile> (read-line p)
-"total 30"
-guile> (read-line p)
-"drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"
-@end smallexample
-
-@node Writing new Modules
-@subsubsection Writing new Modules
-
-You can create new modules using the syntactic form
-@code{define-module}.  All definitions following this form until the
-next @code{define-module} are placed into the new module.
-
-One module is usually placed into one file, and that file is installed
-in a location where Guile can automatically find it.  The following
-session shows a simple example.
-
-@smallexample
-$ cat /usr/local/share/guile/foo/bar.scm
-
-(define-module (foo bar))
-(export frob)
-
-(define (frob x) (* 2 x))
-
-$ guile
-guile> (use-modules (foo bar))
-guile> (frob 12)
-24
-@end smallexample
-
-@node Putting Extensions into Modules
-@subsubsection Putting Extensions into Modules
-
-In addition to Scheme code you can also put things that are defined in
-C into a module.
-
-You do this by writing a small Scheme file that defines the module and
-call @code{load-extension} directly in the body of the module.
-
-@smallexample
-$ cat /usr/local/share/guile/math/bessel.scm
-
-(define-module (math bessel))
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-
-$ file /usr/local/lib/libguile-bessel.so
-@dots{} ELF 32-bit LSB shared object @dots{}
-$ guile
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-@end smallexample
-
-There is also a way to manipulate the module system from C but only
-Scheme files can be autoloaded.  Thus, we recommend that you define
-your modules in Scheme.
-
-@node Discouraged and Deprecated
-@section Discouraged and Deprecated
-
-From time to time functions and other features of Guile become
-obsolete.  Guile has some mechanisms in place that can help you cope
-with this.
-
-Guile has two levels of obsoleteness: things can be @emph{deprecated},
-meaning that their use is considered harmful and should be avoided,
-even in old code; or they can be merely @emph{discouraged}, meaning
-that they are fine in and of themselves, but that there are better
-alternatives that should be used in new code.
-
-When you use a feature that is deprecated, you will likely get a
-warning message at run-time.  Also, deprecated features are not ready
-for production use: they might be very slow.  When something is merely
-discouraged, it performs normally and you wont get any messages at
-run-time.
-
-The primary source for information about just what things are
-discouraged or deprecated in a given release is the file
-@file{NEWS}.  That file also documents what you should use instead
-of the obsoleted things.
-
-The file @file{README} contains instructions on how to control the
-inclusion or removal of the deprecated and/or discouraged features
-from the public API of Guile, and how to control the warning messages
-for deprecated features.
-
-The idea behind those mechanisms is that normally all deprecated and
-discouraged features are available, but that you can omit them on
-purpose to check whether your code still relies on them.
-
-@node Reporting Bugs
-@section Reporting Bugs
-
-Any problems with the installation should be reported to
-@email{bug-guile@@gnu.org}.
-
-Whenever you have found a bug in Guile you are encouraged to report it
-to the Guile developers, so they can fix it.  They may also be able to
-suggest workarounds when it is not possible for you to apply the bug-fix
-or install a new version of Guile yourself.
-
-Before sending in bug reports, please check with the following list that
-you really have found a bug.
-
-@itemize @bullet
-@item
-Whenever documentation and actual behavior differ, you have certainly
-found a bug, either in the documentation or in the program.
-
-@item
-When Guile crashes, it is a bug.
-
-@item
-When Guile hangs or takes forever to complete a task, it is a bug.
-
-@item
-When calculations produce wrong results, it is a bug.
-
-@item
-When Guile signals an error for valid Scheme programs, it is a bug.
-
-@item
-When Guile does not signal an error for invalid Scheme programs, it may
-be a bug, unless this is explicitly documented.
-
-@item
-When some part of the documentation is not clear and does not make sense
-to you even after re-reading the section, it is a bug.
-@end itemize
-
-When you write a bug report, please make sure to include as much of the
-information described below in the report.  If you can't figure out some
-of the items, it is not a problem, but the more information we get, the
-more likely we can diagnose and fix the bug.
-
-@itemize @bullet
-@item
-The version number of Guile.  Without this, we won't know whether there
-is any point in looking for the bug in the current version of Guile.
-
-You can get the version number by invoking the command
-
-@example
-$ guile --version
-Guile 1.9.0
-Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
-2005, 2006, 2007, 2008, 2009 Free Software Foundation
-Guile may be distributed under the terms of the GNU Lesser General
-Public Licence.  For details, see the files `COPYING.LESSER' and
-`COPYING', which are included in the Guile distribution.  There is
-no warranty, to the extent permitted by law.
-@end example
-
-@item
-The type of machine you are using, and the operating system name and
-version number.  On GNU systems, you can get it with @file{uname}.
-
-@example
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
-@end example
-
-@item
-The operands given to the @file{configure} command when Guile was
-installed.  It's often useful to augment this with the output of the
-command @code{guile-config info}.
-
-@item
-A complete list of any modifications you have made to the Guile source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Guile.  But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes.  A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for
-installing Guile.
-
-@item
-The complete text of any source files needed to reproduce the bug.
-
-If you can tell us a way to cause the problem without loading any source
-files, please do so.  This makes it much easier to debug.  If you do
-need files, make sure you arrange for us to see their exact contents.
-
-@item
-The precise Guile invocation command line we need to type to reproduce
-the bug.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect.  For example, "The Guile process gets a fatal signal," or,
-"The resulting output is as follows, which I think is wrong."
-
-Of course, if the bug is that Guile gets a fatal signal, then one can't
-miss it.  But if the bug is incorrect results, the maintainer might fail
-to notice what is wrong.  Why leave it to chance?
-
-If the manifestation of the bug is a Guile error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Scheme program arrived at the error.
-
-This can be done using the procedure @code{backtrace} in the REPL.
-
-@item
-Check whether any programs you have loaded into Guile, including your
-@file{.guile} file, set any variables that may affect the functioning of
-Guile.  Also, see whether the problem happens in a freshly started Guile
-without loading your @file{.guile} file (start Guile with the @code{-q}
-switch to prevent loading the init file).  If the problem does
-@emph{not} occur then, you must report the precise contents of any
-programs that you must load into Guile in order to cause the problem to
-occur.
-
-@item
-If the problem does depend on an init file or other Scheme programs that
-are not part of the standard Guile distribution, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first.  After they verify that they are using Guile in a way
-that is supposed to work, they should report the bug.
-
-@item
-If you wish to mention something in the Guile source, show the line of
-code with a few lines of context.  Don't just give a line number.
-
-The line numbers in the development sources might not match those in your
-sources.  It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy.  You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Guile distribution.  To run Guile under GDB, you should
-switch to the @file{libguile} subdirectory in which Guile was compiled, then
-do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-For example, many people send just a backtrace, but that is not very
-useful by itself.  A simple backtrace with arguments often conveys
-little about what is happening inside Guile, because most of the
-arguments listed in the backtrace are pointers to Scheme objects.  The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
-@end itemize
-
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
+@c   Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Introduction
+@chapter Introduction
+
+Guile is an implementation of the Scheme programming language.  Scheme
+(@url{schemers.org}) is an elegant and conceptually simple dialect of
+Lisp, originated by Guy Steele and Gerald Sussman, and since evolved
+by the series of reports known as RnRS (the
+@tex
+Revised$^n$
+@end tex
+@ifnottex
+Revised^n
+@end ifnottex
+Reports on Scheme).
+
+Unlike -- for example -- Python or Perl, Scheme has no benevolent
+dictator.  There are many Scheme implementations, with different
+characteristics and with communities and academic activities around
+them, and the language develops as a result of the interplay between
+these.  Guile's particular characteristics are that
+
+@itemize
+@item
+it is easy to combine with other code written in C
+@item
+it has a historical and continuing connection with the GNU Project
+@item
+it emphasizes interactive and incremental programming
+@item
+it actually supports several languages, not just Scheme.
+@end itemize
+
+@noindent
+The next few sections explain what we mean by these points.  The sections after
+that cover how you can obtain and install Guile, and the typographical
+conventions that we use in this manual.
+
+@menu
+* Guile and Scheme::              
+* Combining with C::              
+* Guile and the GNU Project::
+* Interactive Programming::
+* Supporting Multiple Languages::
+* Obtaining and Installing Guile::  
+* Typographical Conventions::          
+@end menu
+
+@node Guile and Scheme
+@section Guile and Scheme
+
+Guile implements Scheme as described in the
+@tex
+Revised$^5$
+@end tex
+@ifnottex
+Revised^5
+@end ifnottex
+Report on the Algorithmic Language Scheme (usually known as
+@acronym{R5RS}), providing clean and general data and control
+structures.  Guile goes beyond the rather austere language presented
+in @acronym{R5RS}, extending it with a module system, full access to
+@acronym{POSIX} system calls, networking support, multiple threads,
+dynamic linking, a foreign function call interface, powerful string
+processing, and many other features needed for programming in the real
+world.
+
+The Scheme community has recently agreed and published R6RS, the
+latest installment in the RnRS series.  R6RS significantly expands the
+core Scheme language, and standardises many non-core functions that
+implementations -- including Guile -- have previously done in
+different ways.  Guile has been updated to incorporate some of the
+features of R6RS, and to adjust some existing features to conform to
+the R6RS specification, but it is by no means a complete R6RS
+implementation.
+
+Between R5RS and R6RS, the SRFI process (@url{http://srfi.schemers.org/})
+standardised interfaces for many practical needs, such as multithreaded
+programming and multidimensional arrays.  Guile supports many SRFIs, as
+documented in detail in @ref{SRFI Support}.
+
+In summary, so far as relationship to the Scheme standards is
+concerned, Guile is an R5RS implementation with many extensions, some
+of which conform to SRFIs or to the relevant parts of R6RS.
+
+@node Combining with C
+@section Combining with C Code
+
+Like a shell, Guile can run interactively --- reading expressions from the user,
+evaluating them, and displaying the results --- or as a script interpreter,
+reading and executing Scheme code from a file.  Guile also provides an object
+library, @dfn{libguile}, that allows other applications to easily incorporate a
+complete Scheme interpreter.  An application can then use Guile as an extension
+language, a clean and powerful configuration language, or as multi-purpose
+``glue'', connecting primitives provided by the application.  It is easy to call
+Scheme code from C code and vice versa, giving the application designer full
+control of how and when to invoke the interpreter.  Applications can add new
+functions, data types, control structures, and even syntax to Guile, creating a
+domain-specific language tailored to the task at hand, but based on a robust
+language design.
+
+This kind of combination is helped by four aspects of Guile's design
+and history.  First is that Guile has always been targeted as an
+extension language.  Hence its C API has always been of great
+importance, and has been developed accordingly.  Second and third are
+rather technical points -- that Guile uses conservative garbage
+collection, and that it implements the Scheme concept of continuations
+by copying and reinstating the C stack -- but whose practical
+consequence is that most existing C code can be glued into Guile as
+is, without needing modifications to cope with strange Scheme
+execution flows.  Last is the module system, which helps extensions to
+coexist without stepping on each others' toes.
+
+Guile's module system allows one to break up a large program into
+manageable sections with well-defined interfaces between them.
+Modules may contain a mixture of interpreted and compiled code; Guile
+can use either static or dynamic linking to incorporate compiled code.
+Modules also encourage developers to package up useful collections of
+routines for general distribution; as of this writing, one can find
+Emacs interfaces, database access routines, compilers, @acronym{GUI}
+toolkit interfaces, and @acronym{HTTP} client functions, among others.
+
+@node Guile and the GNU Project
+@section Guile and the GNU Project
+
+Guile was conceived by the GNU Project following the fantastic success
+of Emacs Lisp as an extension language within Emacs.  Just as Emacs
+Lisp allowed complete and unanticipated applications to be written
+within the Emacs environment, the idea was that Guile should do the
+same for other GNU Project applications.  This remains true today.
+
+Guile is now used by GNU project applications such as AutoGen, Lilypond, Denemo,
+Mailutils, TeXmacs and Gnucash, and we hope that there will be many more in
+future.
+
+@node Interactive Programming
+@section Interactive Programming
+
+Non-free software has no interest in its users being able to see how it works.
+They are supposed to just accept it, or to report problems and hope that the
+source code owners will choose to work on them.
+
+Free software aims to work reliably just as much as non-free software does, but
+it should also empower its users by making its workings available.  This is
+useful for many reasons, including education, auditing and enhancements, as well
+as for debugging problems.
+
+The ideal free software system achieves this by making it easy for interested
+users to see the source code for a feature that they are using, and to follow
+through that source code step-by-step, as it runs.  In Emacs, good examples of
+this are the source code hyperlinks in the help system, and @code{edebug}.
+Then, for bonus points and maximising the ability for the user to experiment
+quickly with code changes, the system should allow parts of the source code to
+be modified and reloaded into the running program, to take immediate effect.
+
+Guile allows this kind of interactive programming, and this distinguishes it
+from many Scheme implementations that instead prioritise running a fixed Scheme
+program as fast as possible --- because there are tradeoffs between performance
+and the ability to modify parts of an already running program.  There are faster
+Schemes than Guile, but Guile is a GNU project and so prioritises the GNU vision
+of programming freedom and experimentation.
+
+@node Supporting Multiple Languages
+@section Supporting Multiple Languages
+
+Since the 2.0 release, Guile's architecture supports compiling any language to
+its core virtual machine bytecode, and Scheme is just one of the supported
+languages.  Other supported languages are Emacs Lisp, ECMAScript (commonly known
+as Javascript) and Brainfuck, and work is under discussion for Lua, Ruby and
+Python.
+
+This means that users can program applications which use Guile in the language
+of their choice, rather than having the tastes of the application's author
+imposed on them.
+
+@node Obtaining and Installing Guile
+@section Obtaining and Installing Guile
+
+Guile can be obtained from the main GNU archive site
+@url{ftp://ftp.gnu.org} or any of its mirrors.  The file will be named
+guile-@var{version}.tar.gz.  The current version is @value{VERSION}, so the
+file you should grab is:
+
+@url{ftp://ftp.gnu.org/pub/gnu/guile/guile-@value{VERSION}.tar.gz}
+
+To unbundle Guile use the instruction
+
+@example
+zcat guile-@value{VERSION}.tar.gz | tar xvf -
+@end example
+
+@noindent
+which will create a directory called @file{guile-@value{VERSION}} with
+all the sources.  You can look at the file @file{INSTALL} for detailed
+instructions on how to build and install Guile, but you should be able
+to just do
+
+@example
+cd guile-@value{VERSION}
+./configure
+make
+make install
+@end example
+
+This will install the Guile executable @file{guile}, the Guile library
+@file{libguile} and various associated header files and support libraries. It
+will also install the Guile reference manual.
+
+@c [[include instructions for getting R5RS]]
+
+Since this manual frequently refers to the Scheme ``standard'', also
+known as R5RS, or the
+@tex
+``Revised$^5$ Report on the Algorithmic Language Scheme'',
+@end tex
+@ifnottex
+``Revised^5 Report on the Algorithmic Language Scheme'',
+@end ifnottex
+we have included the report in the Guile distribution; see
+@ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
+Language Scheme}.
+This will also be installed in your info directory.
+
+@node Typographical Conventions
+@section Typographical Conventions
+
+We use some conventions in this manual.
+
+@itemize @bullet
+
+@item
+For some procedures, notably type predicates, we use ``iff'' to mean
+``if and only if''.  The construct is usually something like: `Return
+@var{val} iff @var{condition}', where @var{val} is usually
+``@nicode{#t}'' or ``non-@nicode{#f}''.  This typically means that
+@var{val} is returned if @var{condition} holds, and that @samp{#f} is
+returned otherwise.  To clarify: @var{val} will @strong{only} be
+returned when @var{condition} is true.
+@cindex iff
+
+@item
+In examples and procedure descriptions and all other places where the
+evaluation of Scheme expression is shown, we use some notation for
+denoting the output and evaluation results of expressions.
+
+The symbol @samp{@result{}} is used to tell which value is returned by
+an evaluation:
+
+@lisp
+(+ 1 2)
+@result{} 3
+@end lisp
+
+Some procedures produce some output besides returning a value.  This
+is denoted by the symbol @samp{@print{}}.
+
+@lisp
+(begin (display 1) (newline) 'hooray)
+@print{} 1
+@result{} hooray
+@end lisp
+
+As you can see, this code prints @samp{1} (denoted by
+@samp{@print{}}), and returns @code{hooray} (denoted by
+@samp{@result{}}).
+
+@c Add other conventions here.
+
+@end itemize
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: