guile/doc/ref/preface.texi

@iftex
@page
@unnumbered Preface

This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions.  It describes how to use Guile in many useful
and interesting ways.

This is edition @value{MANUAL-EDITION} of the reference manual, and
corresponds to Guile version @value{VERSION}.
@end iftex


@iftex
@section The Guile License
@end iftex

@ifnottex
@node Guile License
@chapter The Guile License
@end ifnottex

The license of Guile consists of the GNU GPL plus a special statement
giving blanket permission to link with non-free software.  This is the
license statement as found in any individual file that it applies to:

@quotation
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this software; see the file COPYING.  If not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA

As a special exception, the Free Software Foundation gives permission
for additional uses of the text contained in its release of GUILE.

The exception is that, if you link the GUILE library with other files to
produce an executable, this does not by itself cause the resulting
executable to be covered by the GNU General Public License.  Your use of
that executable is in no way restricted on account of linking the GUILE
library code into it.

This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License.

This exception applies only to the code released by the Free Software
Foundation under the name GUILE.  If you copy code from other Free
Software Foundation releases into a copy of GUILE, as the General Public
License permits, the exception does not apply to the code that you add
in this way.  To avoid misleading anyone as to the status of such
modified files, you must delete this exception notice from them.

If you write modifications of your own for GUILE, it is your choice
whether to permit this exception to apply to your modifications.  If you
do not wish that, delete this exception notice.
@end quotation


@iftex
@section Layout of this Manual
@end iftex

@ifnottex
@node Manual Layout
@chapter Layout of this Manual
@end ifnottex

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
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.  This
part also explains how to obtain and install new versions of Guile, and
how to report bugs effectively.

@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
@c simpler end of the scale, an application might use Guile to define some
@c application-specific primitives in C and then load an application Scheme
@c file.  In this case most of the application code is written on the
@c Scheme level, and uses the application-specific primitives as an
@c extension to standard Scheme.  At the other end of the scale, an
@c application might be predominantly written in C --- with its main
@c control loop implemented in C --- but make occasional forays into Scheme
@c to, say, read configuration data or run user-defined customization code.
@c This part of the manual covers the complete range of application
@c extension options.

@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
versa.  Therefore this part of the manual documents the Guile API in
functionality-based groups with the Scheme and C interfaces presented
side by side.  Where the Scheme and C interfaces for a particular
functional area do differ --- which is sometimes inevitable, given the
differences in the structure of the two languages --- this is pointed
out and explained.  In all cases the overriding principle is that all
the reference documentation for a given functional area is grouped
together.

@c the core Scheme language and features that Guile implements.  Although
@c the basis for this is the Scheme language described in R5RS, this part
@c of the manual does not assume any prior familiarity with R5RS in
@c particular, or with Scheme in general.  Basic Scheme concepts, standard
@c aspects of the Scheme language and Guile extensions on top of R5RS are
@c all documented from scratch, and organized by functionality rather than
@c by the defining standards.

@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:

@itemize @bullet
@item
the POSIX module, which provides Scheme level procedures for system and
network programming that conform to the POSIX standard

@item
the SLIB module, which makes Aubrey Jaffer's portable Scheme library
available for use in Guile.
@end itemize


@iftex
@section Manual Conventions
@end iftex

@ifnottex
@node Manual Conventions
@chapter Conventions used in this Manual
@end ifnottex

We use some conventions in this manual.

@itemize @bullet

@item
For some procedures, notably type predicates, we use @dfn{iff} to
mean `if and only if'.  The construct is usually something like:
`Return @var{val} iff @var{condition}', where @var{val} is usually
`@code{#t}' or `non-@code{#f}'.  This typically means that @var{val}
is returned if @var{condition} holds, and that @samp{#f} is returned
otherwise.
@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 @code{@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 @code{@print{}}.

@lisp
(begin (display 1) (newline) 'hooray)
@print{} 1
@result{}
hooray
@end lisp

@c Add other conventions here.

@end itemize


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: