X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/5f5f251895818a8dec3acfc3832012088d07a7ee..95c2df5c60abbb5fcc217bde6efe47bff8e0ac3b:/doc/ref/intro.texi diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 7e248e0e8..fc4e4d6eb 100644 --- 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. -@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? @@ -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: -@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 @@ -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. -@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 @@ -585,6 +586,53 @@ contents are themselves pointers). @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"