Format `Revised^n' more nicely in TeX

[bpt/guile.git] / doc / ref / intro.texi

diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 7e248e0..fc4e4d6 100644 (file)
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -4,15 +4,49 @@
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @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::              
 
 @menu
 * What is Guile?::              
 * Obtaining and Installing Guile::  
 * Whirlwind Tour::              

-* Discouraged and Deprecated::

 * Reporting Bugs::              
 * Reporting Bugs::              

+* Typographical Conventions::          

 @end menu
 
 @node What is Guile?
 @end menu
 
 @node What is Guile?


@@ -72,7 +106,7 @@ Guile can be obtained from the main GNU archive site
 guile-version.tar.gz.  The current version is @value{VERSION}, so the
 file you should grab is:
 
 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
 
 
 To unbundle Guile use the instruction
 


@@ -384,39 +418,6 @@ There is also a way to manipulate the module system from C but only
 Scheme files can be autoloaded.  Thus, we recommend that you define
 your modules in Scheme.
 
 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
 
 @node Reporting Bugs
 @section Reporting Bugs
 


@@ -585,6 +586,53 @@ contents are themselves pointers).
 @end itemize
 
 
 @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"
 
 @c Local Variables:
 @c TeX-master: "guile.texi"