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 is the GNU Lesser General Public License.  See
the file @file{COPYING.LIB}.

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

@table @strong
@item 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.

@item Part II: Writing and Running Guile Scheme
@itemx 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
@acronym{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.

@item Part IV: Guile API Reference
Documents Guile's core @acronym{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 @acronym{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.

@item 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 @acronym{POSIX} module, which provides Scheme-level procedures for
system and network programming that conform to the @acronym{POSIX}
standard.

@item
The @acronym{SLIB} module, which makes Aubrey Jaffer's portable Scheme
library available for use in Guile.
@end itemize
@end table


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