@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@node Introduction to Guile
-@chapter Introduction to Guile
+@node Introduction
+@chapter Introduction
+
+Guile is an implementation of the Scheme programming language. Scheme
+(@url{schemers.org}) is an elegant and conceptually simple dialect of
+Lisp, originated by Guy Steele and Gerald Sussman, and since evolved
+by the series of reports known as RnRS (the
+@tex
+Revised$^n$
+@end tex
+@ifnottex
+Revised^n
+@end ifnottex
+Reports onScheme).
+
+Unlike -- for example -- Python or Perl, Scheme has no benevolent
+dictator. There are many Scheme implementations, with different
+characteristics and with communities and academic activities around
+them, and the language develops as a result of the interplay between
+these. Guile's particular characteristics are that
+@itemize
+@item
+it is easy to combine with other code written in C
+@item
+it has a historical and continuing connection with the GNU Project
+@item
+it emphasizes interactive and incremental programming
+@item
+it actually supports several languages, not just Scheme.
+@end itemize
+@noindent
+The next section explains what we mean by these points. The sections
+after that cover how you can obtain and install Guile, a tour of the
+ways that you can use it, how to report any problems that you
+encounter, and some typographical conventions that we use in this
+manual.
@menu
* What is Guile?::
* Obtaining and Installing Guile::
* Whirlwind Tour::
-* Discouraged and Deprecated::
* Reporting Bugs::
+* Typographical Conventions::
@end menu
@node What is Guile?
guile-version.tar.gz. The current version is @value{VERSION}, so the
file you should grab is:
-@url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
+@url{ftp://ftp.gnu.org/pub/gnu/guile/guile-@value{VERSION}.tar.gz}
To unbundle Guile use the instruction
zcat guile-@value{VERSION}.tar.gz | tar xvf -
@end example
+@noindent
which will create a directory called @file{guile-@value{VERSION}} with
all the sources. You can look at the file @file{INSTALL} for detailed
instructions on how to build and install Guile, but you should be able
@end example
This will install the Guile executable @file{guile}, the Guile library
-@file{-lguile} and various associated header files and support
+@file{libguile} and various associated header files and support
libraries. It will also install the Guile tutorial and reference
manual.
Since this manual frequently refers to the Scheme ``standard'', also
known as R5RS, or the
-@iftex
+@tex
``Revised$^5$ Report on the Algorithmic Language Scheme'',
-@end iftex
+@end tex
@ifnottex
``Revised^5 Report on the Algorithmic Language Scheme'',
@end ifnottex
-we have included the report in the Guile distribution;
-@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
+we have included the report in the Guile distribution; see
+@ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
Language Scheme}.
This will also be installed in your info directory.
Scheme files can be autoloaded. Thus, we recommend that you define
your modules in Scheme.
-@node Discouraged and Deprecated
-@section Discouraged and Deprecated
-
-From time to time functions and other features of Guile become
-obsolete. Guile has some mechanisms in place that can help you cope
-with this.
-
-Guile has two levels of obsoleteness: things can be @emph{deprecated},
-meaning that their use is considered harmful and should be avoided,
-even in old code; or they can be merely @emph{discouraged}, meaning
-that they are fine in and of themselves, but that there are better
-alternatives that should be used in new code.
-
-When you use a feature that is deprecated, you will likely get a
-warning message at run-time. Also, deprecated features are not ready
-for production use: they might be very slow. When something is merely
-discouraged, it performs normally and you wont get any messages at
-run-time.
-
-The primary source for information about just what things are
-discouraged or deprecated in a given release is the file
-@file{NEWS}. That file also documents what you should use instead
-of the obsoleted things.
-
-The file @file{README} contains instructions on how to control the
-inclusion or removal of the deprecated and/or discouraged features
-from the public API of Guile, and how to control the warning messages
-for deprecated features.
-
-The idea behind those mechanisms is that normally all deprecated and
-discouraged features are available, but that you can omit them on
-purpose to check whether your code still relies on them.
-
@node Reporting Bugs
@section Reporting Bugs
Any problems with the installation should be reported to
-@email{bug-guile@@gnu.org}. Please note that you must be subscribed to
-this list first, in order to successfully send a report to it.
+@email{bug-guile@@gnu.org}.
Whenever you have found a bug in Guile you are encouraged to report it
to the Guile developers, so they can fix it. They may also be able to
@example
$ guile --version
-Guile 1.4.1
-Copyright (c) 1995, 1996, 1997, 2000, 2006 Free Software Foundation
-Guile may be distributed under the terms of the GNU General Public License;
-certain other uses are permitted as well. For details, see the file
-`COPYING', which is included in the Guile distribution.
-There is no warranty, to the extent permitted by law.
+Guile 1.9.0
+Copyright (c) 1995, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007, 2008, 2009 Free Software Foundation
+Guile may be distributed under the terms of the GNU Lesser General
+Public Licence. For details, see the files `COPYING.LESSER' and
+`COPYING', which are included in the Guile distribution. There is
+no warranty, to the extent permitted by law.
@end example
@item
@end itemize
+@node Typographical Conventions
+@section Typographical Conventions
+
+We use some conventions in this manual.
+
+@itemize @bullet
+
+@item
+For some procedures, notably type predicates, we use ``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"
HCoop / bpt / guile.git / blobdiff