summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/guile.texi5
-rw-r--r--doc/ref/intro.texi281
-rw-r--r--doc/ref/tour.texi282
3 files changed, 290 insertions, 278 deletions
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 7b4a72e52..9db1be3cd 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -169,6 +169,7 @@ x
* Preface::
* Introduction::
+* Hello Guile!::
* Hello Scheme!::
* Programming in Scheme::
@@ -206,6 +207,10 @@ Indices
@include intro.texi
@raisesections
+@include tour.texi
+@lowersections
+
+@raisesections
@include scheme-ideas.texi
@lowersections
@include scheme-reading.texi
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 86e52a573..f26fa83c5 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -37,11 +37,9 @@ it actually supports several languages, not just Scheme.
@end itemize
@noindent
-The next few sections explain 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 the typographical conventions that we use in this
-manual.
+The next few sections explain what we mean by these points. The sections after
+that cover how you can obtain and install Guile, how to report any problems that
+you encounter, and the typographical conventions that we use in this manual.
@menu
* Guile and Scheme::
@@ -50,7 +48,6 @@ manual.
* Interactive Programming::
* Supporting Multiple Languages::
* Obtaining and Installing Guile::
-* Whirlwind Tour::
* Reporting Bugs::
* Typographical Conventions::
@end menu
@@ -230,278 +227,6 @@ we have included the report in the Guile distribution; see
Language Scheme}.
This will also be installed in your info directory.
-@node Whirlwind Tour
-@section A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used. There are additional examples in the @file{examples/}
-directory in the Guile source distribution.
-
-The following examples assume that Guile has been installed in
-@code{/usr/local/}.
-
-@menu
-* Running Guile Interactively::
-* Running Guile Scripts::
-* Linking Guile into Programs::
-* Writing Guile Extensions::
-* Using the Guile Module System::
-@end menu
-
-
-@node Running Guile Interactively
-@subsection Running Guile Interactively
-
-In its simplest form, Guile acts as an interactive interpreter for the
-Scheme programming language, reading and evaluating Scheme expressions
-the user enters from the terminal. Here is a sample interaction between
-Guile and a user; the user's input appears after the @code{$} and
-@code{guile>} prompts:
-
-@example
-$ guile
-guile> (+ 1 2 3) ; add some numbers
-6
-guile> (define (factorial n) ; define a function
- (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb") ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
-@end example
-
-
-@node Running Guile Scripts
-@subsection Running Guile Scripts
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-Here is a trivial Guile script, for more details @xref{Guile Scripting}.
-
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-
-
-@node Linking Guile into Programs
-@subsection Linking Guile into Programs
-
-The Guile interpreter is available as an object library, to be linked
-into applications using Scheme as a configuration or extension
-language.
-
-Here is @file{simple-guile.c}, source code for a program that will
-produce a complete Guile interpreter. In addition to all usual
-functions provided by Guile, it will also offer the function
-@code{my-hostname}.
-
-@example
-#include <stdlib.h>
-#include <libguile.h>
-
-static SCM
-my_hostname (void)
-@{
- char *s = getenv ("HOSTNAME");
- if (s == NULL)
- return SCM_BOOL_F;
- else
- return scm_from_locale_string (s);
-@}
-
-static void
-inner_main (void *data, int argc, char **argv)
-@{
- scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
- scm_shell (argc, argv);
-@}
-
-int
-main (int argc, char **argv)
-@{
- scm_boot_guile (argc, argv, inner_main, 0);
- return 0; /* never reached */
-@}
-@end example
-
-When Guile is correctly installed on your system, the above program
-can be compiled and linked like this:
-
-@example
-$ gcc -o simple-guile simple-guile.c \
- `pkg-config --cflags --libs guile-2.0`
-@end example
-
-When it is run, it behaves just like the @code{guile} program except
-that you can also call the new @code{my-hostname} function.
-
-@example
-$ ./simple-guile
-guile> (+ 1 2 3)
-6
-guile> (my-hostname)
-"burns"
-@end example
-
-@node Writing Guile Extensions
-@subsection Writing Guile Extensions
-
-You can link Guile into your program and make Scheme available to the
-users of your program. You can also link your library into Guile and
-make its functionality available to all users of Guile.
-
-A library that is linked into Guile is called an @dfn{extensions}, but
-it really just is an ordinary object library.
-
-The following example shows how to write a simple extension for Guile
-that makes the @code{j0} function available to Scheme code.
-
-@smallexample
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
-@}
-
-void
-init_bessel ()
-@{
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
-@}
-@end smallexample
-
-This C source file needs to be compiled into a shared library. Here is
-how to do it on GNU/Linux:
-
-@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
-@end smallexample
-
-For creating shared libraries portably, we recommend the use of GNU
-Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
-
-A shared library can be loaded into a running Guile process with the
-function @code{load-extension}. The @code{j0} is then immediately
-available:
-
-@smallexample
-$ guile
-guile> (load-extension "./libguile-bessel" "init_bessel")
-guile> (j0 2)
-0.223890779141236
-@end smallexample
-
-
-@node Using the Guile Module System
-@subsection Using the Guile Module System
-
-Guile has support for dividing a program into @dfn{modules}. By using
-modules, you can group related code together and manage the
-composition of complete programs from largely independent parts.
-
-(Although the module system implementation is in flux, feel free to use it
-anyway. Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
-@xref{Modules}.
-
-@menu
-* Using Modules::
-* Writing new Modules::
-* Putting Extensions into Modules::
-@end menu
-
-
-@node Using Modules
-@subsubsection Using Modules
-
-Guile comes with a lot of useful modules, for example for string
-processing or command line parsing. Additionally, there exist many
-Guile modules written by other Guile hackers, but which have to be
-installed manually.
-
-Here is a sample interactive session that shows how to use the
-@code{(ice-9 popen)} module which provides the means for communicating
-with other processes over pipes together with the @code{(ice-9
-rdelim)} module that provides the function @code{read-line}.
-
-@smallexample
-$ guile
-guile> (use-modules (ice-9 popen))
-guile> (use-modules (ice-9 rdelim))
-guile> (define p (open-input-pipe "ls -l"))
-guile> (read-line p)
-"total 30"
-guile> (read-line p)
-"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
-@end smallexample
-
-@node Writing new Modules
-@subsubsection Writing new Modules
-
-You can create new modules using the syntactic form
-@code{define-module}. All definitions following this form until the
-next @code{define-module} are placed into the new module.
-
-One module is usually placed into one file, and that file is installed
-in a location where Guile can automatically find it. The following
-session shows a simple example.
-
-@smallexample
-$ cat /usr/local/share/guile/foo/bar.scm
-
-(define-module (foo bar))
-(export frob)
-
-(define (frob x) (* 2 x))
-
-$ guile
-guile> (use-modules (foo bar))
-guile> (frob 12)
-24
-@end smallexample
-
-@node Putting Extensions into Modules
-@subsubsection Putting Extensions into Modules
-
-In addition to Scheme code you can also put things that are defined in
-C into a module.
-
-You do this by writing a small Scheme file that defines the module and
-call @code{load-extension} directly in the body of the module.
-
-@smallexample
-$ cat /usr/local/share/guile/math/bessel.scm
-
-(define-module (math bessel))
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-
-$ file /usr/local/lib/libguile-bessel.so
-@dots{} ELF 32-bit LSB shared object @dots{}
-$ guile
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-@end smallexample
-
-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 Reporting Bugs
@section Reporting Bugs
diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi
new file mode 100644
index 000000000..9a5c1fb7b
--- /dev/null
+++ b/doc/ref/tour.texi
@@ -0,0 +1,282 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Hello Guile!
+@section Hello Guile!
+
+This chapter presents a quick tour of all the ways that Guile can be
+used. There are additional examples in the @file{examples/}
+directory in the Guile source distribution.
+
+The following examples assume that Guile has been installed in
+@code{/usr/local/}.
+
+@menu
+* Running Guile Interactively::
+* Running Guile Scripts::
+* Linking Guile into Programs::
+* Writing Guile Extensions::
+* Using the Guile Module System::
+@end menu
+
+
+@node Running Guile Interactively
+@subsection Running Guile Interactively
+
+In its simplest form, Guile acts as an interactive interpreter for the
+Scheme programming language, reading and evaluating Scheme expressions
+the user enters from the terminal. Here is a sample interaction between
+Guile and a user; the user's input appears after the @code{$} and
+@code{guile>} prompts:
+
+@example
+$ guile
+guile> (+ 1 2 3) ; add some numbers
+6
+guile> (define (factorial n) ; define a function
+ (if (zero? n) 1 (* n (factorial (- n 1)))))
+guile> (factorial 20)
+2432902008176640000
+guile> (getpwnam "jimb") ; find my entry in /etc/passwd
+#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
+ "/usr/local/bin/bash")
+guile> @kbd{C-d}
+$
+@end example
+
+
+@node Running Guile Scripts
+@subsection Running Guile Scripts
+
+Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
+script is simply a file of Scheme code with some extra information at
+the beginning which tells the operating system how to invoke Guile, and
+then tells Guile how to handle the Scheme code.
+
+Here is a trivial Guile script, for more details @xref{Guile Scripting}.
+
+@example
+#!/usr/local/bin/guile -s
+!#
+(display "Hello, world!")
+(newline)
+@end example
+
+
+@node Linking Guile into Programs
+@subsection Linking Guile into Programs
+
+The Guile interpreter is available as an object library, to be linked
+into applications using Scheme as a configuration or extension
+language.
+
+Here is @file{simple-guile.c}, source code for a program that will
+produce a complete Guile interpreter. In addition to all usual
+functions provided by Guile, it will also offer the function
+@code{my-hostname}.
+
+@example
+#include <stdlib.h>
+#include <libguile.h>
+
+static SCM
+my_hostname (void)
+@{
+ char *s = getenv ("HOSTNAME");
+ if (s == NULL)
+ return SCM_BOOL_F;
+ else
+ return scm_from_locale_string (s);
+@}
+
+static void
+inner_main (void *data, int argc, char **argv)
+@{
+ scm_c_define_gsubr ("my-hostname", 0, 0, 0, my_hostname);
+ scm_shell (argc, argv);
+@}
+
+int
+main (int argc, char **argv)
+@{
+ scm_boot_guile (argc, argv, inner_main, 0);
+ return 0; /* never reached */
+@}
+@end example
+
+When Guile is correctly installed on your system, the above program
+can be compiled and linked like this:
+
+@example
+$ gcc -o simple-guile simple-guile.c \
+ `pkg-config --cflags --libs guile-2.0`
+@end example
+
+When it is run, it behaves just like the @code{guile} program except
+that you can also call the new @code{my-hostname} function.
+
+@example
+$ ./simple-guile
+guile> (+ 1 2 3)
+6
+guile> (my-hostname)
+"burns"
+@end example
+
+@node Writing Guile Extensions
+@subsection Writing Guile Extensions
+
+You can link Guile into your program and make Scheme available to the
+users of your program. You can also link your library into Guile and
+make its functionality available to all users of Guile.
+
+A library that is linked into Guile is called an @dfn{extensions}, but
+it really just is an ordinary object library.
+
+The following example shows how to write a simple extension for Guile
+that makes the @code{j0} function available to Scheme code.
+
+@smallexample
+#include <math.h>
+#include <libguile.h>
+
+SCM
+j0_wrapper (SCM x)
+@{
+ return scm_make_real (j0 (scm_num2dbl (x, "j0")));
+@}
+
+void
+init_bessel ()
+@{
+ scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
+@}
+@end smallexample
+
+This C source file needs to be compiled into a shared library. Here is
+how to do it on GNU/Linux:
+
+@smallexample
+gcc -shared -o libguile-bessel.so -fPIC bessel.c
+@end smallexample
+
+For creating shared libraries portably, we recommend the use of GNU
+Libtool (@pxref{Top, , Introduction, libtool, GNU Libtool}).
+
+A shared library can be loaded into a running Guile process with the
+function @code{load-extension}. The @code{j0} is then immediately
+available:
+
+@smallexample
+$ guile
+guile> (load-extension "./libguile-bessel" "init_bessel")
+guile> (j0 2)
+0.223890779141236
+@end smallexample
+
+
+@node Using the Guile Module System
+@subsection Using the Guile Module System
+
+Guile has support for dividing a program into @dfn{modules}. By using
+modules, you can group related code together and manage the
+composition of complete programs from largely independent parts.
+
+(Although the module system implementation is in flux, feel free to use it
+anyway. Guile will provide reasonable backwards compatibility.)
+
+Details on the module system beyond this introductory material can be found in
+@xref{Modules}.
+
+@menu
+* Using Modules::
+* Writing new Modules::
+* Putting Extensions into Modules::
+@end menu
+
+
+@node Using Modules
+@subsubsection Using Modules
+
+Guile comes with a lot of useful modules, for example for string
+processing or command line parsing. Additionally, there exist many
+Guile modules written by other Guile hackers, but which have to be
+installed manually.
+
+Here is a sample interactive session that shows how to use the
+@code{(ice-9 popen)} module which provides the means for communicating
+with other processes over pipes together with the @code{(ice-9
+rdelim)} module that provides the function @code{read-line}.
+
+@smallexample
+$ guile
+guile> (use-modules (ice-9 popen))
+guile> (use-modules (ice-9 rdelim))
+guile> (define p (open-input-pipe "ls -l"))
+guile> (read-line p)
+"total 30"
+guile> (read-line p)
+"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
+@end smallexample
+
+@node Writing new Modules
+@subsubsection Writing new Modules
+
+You can create new modules using the syntactic form
+@code{define-module}. All definitions following this form until the
+next @code{define-module} are placed into the new module.
+
+One module is usually placed into one file, and that file is installed
+in a location where Guile can automatically find it. The following
+session shows a simple example.
+
+@smallexample
+$ cat /usr/local/share/guile/foo/bar.scm
+
+(define-module (foo bar))
+(export frob)
+
+(define (frob x) (* 2 x))
+
+$ guile
+guile> (use-modules (foo bar))
+guile> (frob 12)
+24
+@end smallexample
+
+@node Putting Extensions into Modules
+@subsubsection Putting Extensions into Modules
+
+In addition to Scheme code you can also put things that are defined in
+C into a module.
+
+You do this by writing a small Scheme file that defines the module and
+call @code{load-extension} directly in the body of the module.
+
+@smallexample
+$ cat /usr/local/share/guile/math/bessel.scm
+
+(define-module (math bessel))
+(export j0)
+
+(load-extension "libguile-bessel" "init_bessel")
+
+$ file /usr/local/lib/libguile-bessel.so
+@dots{} ELF 32-bit LSB shared object @dots{}
+$ guile
+guile> (use-modules (math bessel))
+guile> (j0 2)
+0.223890779141236
+@end smallexample
+
+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.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: