-@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, a tour
-of the ways that you can use it, how to report any problems that you
-encounter, and some 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::
-* Whirlwind Tour::
-* Reporting Bugs::
-* 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 multithreading 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 Other 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. 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.
-
-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
-
-@node Interactive Programming
-@section Interactive Programming
-
-@node Supporting Multiple Languages
-@section Supporting Multiple Languages
-
-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/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 \
- `pkg-config --cflags --libs guile-2.0`
-@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 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
-
-
-@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{}}). Do not confuse the two.
-
-@c Add other conventions here.
-
-@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, 2011, 2013
+@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{http://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::
+* Organisation of this Manual::
+* 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. @xref{R6RS Support}.
+
+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.
+
+The idea of extensibility is closely related to the GNU project's
+primary goal, that of promoting software freedom. Software freedom
+means that people receiving a software package can modify or enhance
+it to their own desires, including in ways that may not have occurred
+at all to the software's original developers. For programs written in
+a compiled language like C, this freedom covers modifying and
+rebuilding the C code; but if the program also provides an extension
+language, that is usually a much friendlier and lower-barrier-of-entry
+way for the user to start making their own changes.
+
+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 is designed for 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/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 Organisation of this Manual
+@section Organisation of this Manual
+
+The rest of this manual is organised into the following chapters.
+
+@table @strong
+@item Chapter 2: Hello Guile!
+A whirlwind tour shows how Guile can be used interactively and as
+a script interpreter, how to link Guile into your own applications,
+and how to write modules of interpreted and compiled code for use with
+Guile. Everything introduced here is documented again and in full by
+the later parts of the manual.
+
+@item Chapter 3: Hello Scheme!
+For readers new to Scheme, this chapter provides an introduction to the basic
+ideas of the Scheme language. This material would apply to any Scheme
+implementation and so does not make reference to anything Guile-specific.
+
+@item Chapter 4: Programming in Scheme
+Provides an overview of programming in Scheme with Guile. It covers how to
+invoke the @code{guile} program from the command-line and how to write scripts
+in Scheme. It also introduces the extensions that Guile offers beyond standard
+Scheme.
+
+@item Chapter 5: Programming in C
+Provides an overview of how to use Guile in a C program. It
+discusses the fundamental concepts that you need to understand to
+access the features of Guile, such as dynamic types and the garbage
+collector. It explains in a tutorial like manner how to define new
+data types and functions for the use by Scheme programs.
+
+@item Chapter 6: Guile API Reference
+This part of the manual documents the Guile @acronym{API} in
+functionality-based groups with the Scheme and C interfaces presented
+side by side.
+
+@item Chapter 7: Guile Modules
+Describes some important modules, distributed as part of the Guile
+distribution, that extend the functionality provided by the Guile
+Scheme core.
+
+@item Chapter 8: GOOPS
+Describes GOOPS, an object oriented extension to Guile that provides
+classes, multiple inheritance and generic functions.
+
+@end table
+
+@node Typographical Conventions
+@section Typographical Conventions
+
+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 Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff