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 is the GNU Lesser General Public License.
  24
  25 @iftex
  26 @section Layout of this Manual
  27 @end iftex
  28
  29 @ifnottex
  30 @node Manual Layout
  31 @chapter Layout of this Manual
  32 @end ifnottex
  33
  34 The manual is divided into five parts.
  35
  36 @strong{Part I: Introduction to Guile} provides an overview of what
  37 Guile is and how you can use it.  A whirlwind tour shows how Guile can
  38 be used interactively and as a script interpreter, how to link Guile
  39 into your own applications, and how to write modules of interpreted and
  40 compiled code for use with Guile.  Everything introduced here is
  41 documented again and in full by the later parts of the manual.  This
  42 part also explains how to obtain and install new versions of Guile, and
  43 how to report bugs effectively.
  44
  45 @strong{Part II: Writing and Running Guile Scheme} and @strong{Part III:
  46 Programming with Guile} document all aspects of practical programming
  47 using Guile.  This covers both the Scheme level --- where we provide an
  48 introduction to the key ideas of the Scheme language --- and use of
  49 Guile's @code{scm} interface to write new primitives and objects in C,
  50 and to incorporate Guile into a C application.  It also covers the use
  51 of Guile as a POSIX compliant script interpreter, and how to use the
  52 Guile debugger.
  53
  54 @c @strong{Part V: Extending Applications Using Guile} explains the options
  55 @c available for using Guile as a application extension language.  At the
  56 @c simpler end of the scale, an application might use Guile to define some
  57 @c application-specific primitives in C and then load an application Scheme
  58 @c file.  In this case most of the application code is written on the
  59 @c Scheme level, and uses the application-specific primitives as an
  60 @c extension to standard Scheme.  At the other end of the scale, an
  61 @c application might be predominantly written in C --- with its main
  62 @c control loop implemented in C --- but make occasional forays into Scheme
  63 @c to, say, read configuration data or run user-defined customization code.
  64 @c This part of the manual covers the complete range of application
  65 @c extension options.
  66
  67 @strong{Part IV: Guile API Reference} documents Guile's core API.  Most
  68 of the variables and procedures in Guile's core programming interface
  69 are available in both Scheme and C, and are related systematically such
  70 that the C interface can be inferred from the Scheme interface and vice
  71 versa.  Therefore this part of the manual documents the Guile API in
  72 functionality-based groups with the Scheme and C interfaces presented
  73 side by side.  Where the Scheme and C interfaces for a particular
  74 functional area do differ --- which is sometimes inevitable, given the
  75 differences in the structure of the two languages --- this is pointed
  76 out and explained.  In all cases the overriding principle is that all
  77 the reference documentation for a given functional area is grouped
  78 together.
  79
  80 @c the core Scheme language and features that Guile implements.  Although
  81 @c the basis for this is the Scheme language described in R5RS, this part
  82 @c of the manual does not assume any prior familiarity with R5RS in
  83 @c particular, or with Scheme in general.  Basic Scheme concepts, standard
  84 @c aspects of the Scheme language and Guile extensions on top of R5RS are
  85 @c all documented from scratch, and organized by functionality rather than
  86 @c by the defining standards.
  87
  88 @strong{Part V: Guile Modules} describes some important modules,
  89 distributed as part of the Guile distribution, that extend the
  90 functionality provided by the Guile Scheme core.  Two important examples
  91 are:
  92
  93 @itemize @bullet
  94 @item
  95 the POSIX module, which provides Scheme level procedures for system and
  96 network programming that conform to the POSIX standard
  97
  98 @item
  99 the SLIB module, which makes Aubrey Jaffer's portable Scheme library
 100 available for use in Guile.
 101 @end itemize
 102
 103
 104 @iftex
 105 @section Manual Conventions
 106 @end iftex
 107
 108 @ifnottex
 109 @node Manual Conventions
 110 @chapter Conventions used in this Manual
 111 @end ifnottex
 112
 113 We use some conventions in this manual.
 114
 115 @itemize @bullet
 116
 117 @item
 118 For some procedures, notably type predicates, we use @dfn{iff} to
 119 mean `if and only if'.  The construct is usually something like:
 120 `Return @var{val} iff @var{condition}', where @var{val} is usually
 121 `@code{#t}' or `non-@code{#f}'.  This typically means that @var{val}
 122 is returned if @var{condition} holds, and that @samp{#f} is returned
 123 otherwise.
 124 @cindex iff
 125
 126 @item
 127 In examples and procedure descriptions and all other places where the
 128 evaluation of Scheme expression is shown, we use some notation for
 129 denoting the output and evaluation results of expressions.
 130
 131 The symbol @code{@result{}} is used to tell which value is returned by
 132 an evaluation:
 133
 134 @lisp
 135 (+ 1 2)
 136 @result{}
 137 3
 138 @end lisp
 139
 140 Some procedures produce some output besides returning a value.  This
 141 is denoted by the symbol @code{@print{}}.
 142
 143 @lisp
 144 (begin (display 1) (newline) 'hooray)
 145 @print{} 1
 146 @result{}
 147 hooray
 148 @end lisp
 149
 150 @c Add other conventions here.
 151
 152 @end itemize
 153
 154
 155 @c Local Variables:
 156 @c TeX-master: "guile.texi"
 157 @c End: