@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
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
@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