doc/ref/preface.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Preface
   8 @chapter Preface
   9
  10 This manual documents version @value{VERSION} of Guile, GNU's
  11 Ubiquitous Intelligent Language for Extensions.  It describes how to
  12 use Guile in many useful and interesting ways.
  13
  14 @menu
  15 * Manual Layout::
  16 * Manual Conventions::
  17 * Contributors::
  18 * Guile License::
  19 @end menu
  20
  21
  22 @node Manual Layout
  23 @section Layout of this Manual
  24
  25 The manual is divided into five chapters.
  26
  27 @table @strong
  28 @item Chapter 1: Introduction to Guile
  29 This part provides an overview of what Guile is and how you can use
  30 it.  A whirlwind tour shows how Guile can be used interactively and as
  31 a script interpreter, how to link Guile into your own applications,
  32 and how to write modules of interpreted and compiled code for use with
  33 Guile.  Everything introduced here is documented again and in full by
  34 the later parts of the manual.  This part also explains how to obtain
  35 and install new versions of Guile, and how to report bugs effectively.
  36
  37 @item Chapter 2: Programming in Scheme
  38 This part provides an overview of programming in Scheme with Guile.
  39 It covers how to invoke the @code{guile} program from the command-line
  40 and how to write scripts in Scheme.  It also gives an introduction
  41 into the basic ideas of Scheme itself and to the various extensions
  42 that Guile offers beyond standard Scheme.
  43
  44 @item Chapter 3: Programming in C
  45 This part provides an overview of how to use Guile in a C program.  It
  46 discusses the fundamental concepts that you need to understand to
  47 access the features of Guile, such as dynamic types and the garbage
  48 collector.  It explains in a tutorial like manner how to define new
  49 data types and functions for the use by Scheme programs.
  50
  51 @item Chapter 4: Guile API Reference
  52 This part of the manual documents the Guile @acronym{API} in
  53 functionality-based groups with the Scheme and C interfaces presented
  54 side by side.
  55
  56 @item Chapter 5: Guile Modules
  57 Describes some important modules, distributed as part of the Guile
  58 distribution, that extend the functionality provided by the Guile
  59 Scheme core.
  60
  61 @end table
  62
  63
  64 @node Manual Conventions
  65 @section Conventions used in this Manual
  66
  67 We use some conventions in this manual.
  68
  69 @itemize @bullet
  70
  71 @item
  72 For some procedures, notably type predicates, we use ``iff'' to mean
  73 ``if and only if''.  The construct is usually something like: `Return
  74 @var{val} iff @var{condition}', where @var{val} is usually
  75 ``@nicode{#t}'' or ``non-@nicode{#f}''.  This typically means that
  76 @var{val} is returned if @var{condition} holds, and that @samp{#f} is
  77 returned otherwise.  To clarify: @var{val} will @strong{only} be
  78 returned when @var{condition} is true.
  79 @cindex iff
  80
  81 @item
  82 In examples and procedure descriptions and all other places where the
  83 evaluation of Scheme expression is shown, we use some notation for
  84 denoting the output and evaluation results of expressions.
  85
  86 The symbol @samp{@result{}} is used to tell which value is returned by
  87 an evaluation:
  88
  89 @lisp
  90 (+ 1 2)
  91 @result{} 3
  92 @end lisp
  93
  94 Some procedures produce some output besides returning a value.  This
  95 is denoted by the symbol @samp{@print{}}.
  96
  97 @lisp
  98 (begin (display 1) (newline) 'hooray)
  99 @print{} 1
 100 @result{} hooray
 101 @end lisp
 102
 103 As you can see, this code prints @samp{1} (denoted by
 104 @samp{@print{}}), and returns @code{hooray} (denoted by
 105 @samp{@result{}}).  Do not confuse the two.
 106
 107 @c Add other conventions here.
 108
 109 @end itemize
 110
 111 @node Contributors
 112 @section Contributors to this Manual
 113
 114 The Guile reference and tutorial manuals were written and edited
 115 largely by Mark Galassi and Jim Blandy.  In particular, Jim wrote the
 116 original tutorial on Guile's data representation and the C API for
 117 accessing Guile objects.
 118
 119 Significant portions were contributed by Gary Houston (contributions
 120 to POSIX system calls and networking, expect, I/O internals and
 121 extensions, slib installation, error handling) and Tim Pierce
 122 (sections on script interpreter triggers, alists, function tracing).
 123
 124 Tom Lord contributed a great deal of material with early Guile
 125 snapshots; although most of this text has been rewritten, all of it
 126 was important, and some of the structure remains.
 127
 128 Aubrey Jaffer wrote the SCM Scheme implementation and manual upon
 129 which the Guile program and manual are based.  Some portions of the
 130 SCM and SLIB manuals have been included here verbatim.
 131
 132 Since Guile 1.4, Neil Jerram has been maintaining and improving the
 133 reference manual.  Among other contributions, he wrote the Basic
 134 Ideas chapter, developed the tools for keeping the manual in sync
 135 with snarfed libguile docstrings, and reorganized the structure so as
 136 to accommodate docstrings for all Guile's primitives.
 137
 138 Martin Grabmueller has made substantial contributions throughout the
 139 reference manual in preparation for the Guile 1.6 release, including
 140 filling out a lot of the documentation of Scheme data types, control
 141 mechanisms and procedures.  In addition, he wrote the documentation
 142 for Guile's SRFI modules and modules associated with the Guile REPL.
 143
 144 @node Guile License
 145 @section The Guile License
 146 @cindex copying
 147 @cindex GPL
 148 @cindex LGPL
 149 @cindex license
 150
 151 Guile is Free Software.  Guile is copyrighted, not public domain, and
 152 there are restrictions on its distribution or redistribution, but
 153 these restrictions are designed to permit everything a cooperating
 154 person would want to do.
 155
 156 @itemize @bullet
 157 @item
 158 The Guile library (libguile) and supporting files are published under
 159 the terms of the GNU Lesser General Public License version 3 or later.
 160 See the files @file{COPYING.LESSER} and @file{COPYING}.
 161
 162 @item
 163 The Guile readline module is published under the terms of the GNU
 164 General Public License version 3 or later.  See the file @file{COPYING}.
 165
 166 @item
 167 The manual you're now reading is published under the terms of the GNU
 168 Free Documentation License (@pxref{GNU Free Documentation License}).
 169 @end itemize
 170
 171 C code linking to the Guile library is subject to terms of that
 172 library.  Basically such code may be published on any terms, provided
 173 users can re-link against a new or modified version of Guile.
 174
 175 C code linking to the Guile readline module is subject to the terms of
 176 that module.  Basically such code must be published on Free terms.
 177
 178 Scheme level code written to be run by Guile (but not derived from
 179 Guile itself) is not restricted in any way, and may be published on any
 180 terms.  We encourage authors to publish on Free terms.
 181
 182 You must be aware there is no warranty whatsoever for Guile.  This is
 183 described in full in the licenses.
 184
 185
 186 @c Local Variables:
 187 @c TeX-master: "guile.texi"
 188 @c End: