doc/ref/preface.texi

   1 @iftex
   2 @page
   3 @unnumbered Preface
   4
   5 This reference manual documents Guile, GNU's Ubiquitous Intelligent
   6 Language for Extensions.  It describes how to use Guile in many useful
   7 and interesting ways.
   8
   9 This is edition @value{MANUAL_EDITION} of the reference manual, and
  10 corresponds to Guile version @value{VERSION}.
  11 @end iftex
  12
  13
  14 @iftex
  15 @section The Guile License
  16 @end iftex
  17
  18 @ifnottex
  19 @node Guile License
  20 @chapter The Guile License
  21 @end ifnottex
  22
  23 The license of Guile consists of the GNU GPL plus a special statement
  24 giving blanket permission to link with non-free software.  This is the
  25 license statement as found in any individual file that it applies to:
  26
  27 @quotation
  28 This program is free software; you can redistribute it and/or modify it
  29 under the terms of the GNU General Public License as published by the
  30 Free Software Foundation; either version 2, or (at your option) any
  31 later version.
  32
  33 This program is distributed in the hope that it will be useful, but
  34 WITHOUT ANY WARRANTY; without even the implied warranty of
  35 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  36 General Public License for more details.
  37
  38 You should have received a copy of the GNU General Public License along
  39 with this software; see the file COPYING.  If not, write to the Free
  40 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  41 02111-1307 USA
  42
  43 As a special exception, the Free Software Foundation gives permission
  44 for additional uses of the text contained in its release of GUILE.
  45
  46 The exception is that, if you link the GUILE library with other files to
  47 produce an executable, this does not by itself cause the resulting
  48 executable to be covered by the GNU General Public License.  Your use of
  49 that executable is in no way restricted on account of linking the GUILE
  50 library code into it.
  51
  52 This exception does not however invalidate any other reasons why the
  53 executable file might be covered by the GNU General Public License.
  54
  55 This exception applies only to the code released by the Free Software
  56 Foundation under the name GUILE.  If you copy code from other Free
  57 Software Foundation releases into a copy of GUILE, as the General Public
  58 License permits, the exception does not apply to the code that you add
  59 in this way.  To avoid misleading anyone as to the status of such
  60 modified files, you must delete this exception notice from them.
  61
  62 If you write modifications of your own for GUILE, it is your choice
  63 whether to permit this exception to apply to your modifications.  If you
  64 do not wish that, delete this exception notice.
  65 @end quotation
  66
  67
  68 @iftex
  69 @section Layout of this Manual
  70 @end iftex
  71
  72 @ifnottex
  73 @node Manual Layout
  74 @chapter Layout of this Manual
  75 @end ifnottex
  76
  77 The manual is divided into five parts.
  78
  79 @strong{Part I: Introduction to Guile} provides an overview of what
  80 Guile is and how you can use it.  A whirlwind tour shows how Guile can
  81 be used interactively and as a script interpreter, how to link Guile
  82 into your own applications, and how to write modules of interpreted and
  83 compiled code for use with Guile.  Everything introduced here is
  84 documented again and in full by the later parts of the manual.  This
  85 part also explains how to obtain and install new versions of Guile, and
  86 how to report bugs effectively.
  87
  88 @strong{Part II: Writing and Running Guile Scheme} and @strong{Part III:
  89 Programming with Guile} document all aspects of practical programming
  90 using Guile.  This covers both the Scheme level --- where we provide an
  91 introduction to the key ideas of the Scheme language --- and use of
  92 Guile's @code{scm} interface to write new primitives and objects in C,
  93 and to incorporate Guile into a C application.  It also covers the use
  94 of Guile as a POSIX compliant script interpreter, and how to use the
  95 Guile debugger.
  96
  97 @c @strong{Part V: Extending Applications Using Guile} explains the options
  98 @c available for using Guile as a application extension language.  At the
  99 @c simpler end of the scale, an application might use Guile to define some
 100 @c application-specific primitives in C and then load an application Scheme
 101 @c file.  In this case most of the application code is written on the
 102 @c Scheme level, and uses the application-specific primitives as an
 103 @c extension to standard Scheme.  At the other end of the scale, an
 104 @c application might be predominantly written in C --- with its main
 105 @c control loop implemented in C --- but make occasional forays into Scheme
 106 @c to, say, read configuration data or run user-defined customization code.
 107 @c This part of the manual covers the complete range of application
 108 @c extension options.
 109
 110 @strong{Part IV: Guile API Reference} documents Guile's core API.  Most
 111 of the variables and procedures in Guile's core programming interface
 112 are available in both Scheme and C, and are related systematically such
 113 that the C interface can be inferred from the Scheme interface and vice
 114 versa.  Therefore this part of the manual documents the Guile API in
 115 functionality-based groups with the Scheme and C interfaces presented
 116 side by side.  Where the Scheme and C interfaces for a particular
 117 functional area do differ --- which is sometimes inevitable, given the
 118 differences in the structure of the two languages --- this is pointed
 119 out and explained.  In all cases the overriding principle is that all
 120 the reference documentation for a given functional area is grouped
 121 together.
 122
 123 @c the core Scheme language and features that Guile implements.  Although
 124 @c the basis for this is the Scheme language described in R5RS, this part
 125 @c of the manual does not assume any prior familiarity with R5RS in
 126 @c particular, or with Scheme in general.  Basic Scheme concepts, standard
 127 @c aspects of the Scheme language and Guile extensions on top of R5RS are
 128 @c all documented from scratch, and organized by functionality rather than
 129 @c by the defining standards.
 130
 131 @strong{Part V: Guile Modules} describes some important modules,
 132 distributed as part of the Guile distribution, that extend the
 133 functionality provided by the Guile Scheme core.  Two important examples
 134 are:
 135
 136 @itemize @bullet
 137 @item
 138 the POSIX module, which provides Scheme level procedures for system and
 139 network programming that conform to the POSIX standard
 140
 141 @item
 142 the SLIB module, which makes Aubrey Jaffer's portable Scheme library
 143 available for use in Guile.
 144 @end itemize
 145
 146
 147 @iftex
 148 @section Manual Conventions
 149 @end iftex
 150
 151 @ifnottex
 152 @node Manual Conventions
 153 @chapter Conventions used in this Manual
 154 @end ifnottex
 155
 156 We use some conventions in this manual.
 157
 158 @itemize @bullet
 159
 160 @item
 161 For some procedures, notably type predicates, we use @dfn{iff} to
 162 mean `if and only if'.  The construct is usually something like:
 163 `Return @var{val} iff @var{condition}', where @var{val} is usually
 164 `@code{#t}' or `non-@code{#f}'.  This typically means that @var{val}
 165 is returned if @var{condition} holds, and that @samp{#f} is returned
 166 otherwise.
 167 @cindex iff
 168
 169 @item
 170 In examples and procedure descriptions and all other places where the
 171 evaluation of Scheme expression is shown, we use some notation for
 172 denoting the output and evaluation results of expressions.
 173
 174 The symbol @code{@result{}} is used to tell which value is returned by
 175 an evaluation:
 176
 177 @lisp
 178 (+ 1 2)
 179 @result{}
 180 3
 181 @end lisp
 182
 183 Some procedures produce some output besides returning a value.  This
 184 is denoted by the symbol @code{@print{}}.
 185
 186 @lisp
 187 (begin (display 1) (newline) 'hooray)
 188 @print{} 1
 189 @result{}
 190 hooray
 191 @end lisp
 192
 193 @c Add other conventions here.
 194
 195 @end itemize
 196
 197
 198 @c Local Variables:
 199 @c TeX-master: "guile.texi"
 200 @c End: