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