* scripts/README, scripts/hello.scm, safe/untrusted.scm,

	safe/evil.scm, safe/README, modules/README, modules/main,
	modules/module-0.scm, modules/module-1.scm, modules/module-2.scm:
	Minor cleanup.

	* README: Added intro stuff, restructured a bit.

	* box-dynamic/README, box-module/README, box/README: Cleanup and
	restructuring.

	* box-dynamic-module/box-mixed.scm: New file, demonstrating usage
	of extension library functionality, but without exporting
	procedures from the library.

	Thanks to Thomas Wawrzinek for the idea and example code!

	* box-dynamic-module/box-module.scm: Add comments, export
	make-box, box-ref, box-set!.

	* box-dynamic-module/README: Integrate new module (box-mixed),
	restructure and cleanup a bit.

21 files changed, 235 insertions, 59 deletions

diff --git a/examples/ChangeLog b/examples/ChangeLog
index fda148a24..5af8d9b05 100644
--- a/examples/ChangeLog
+++ b/examples/ChangeLog
@@ -1,3 +1,27 @@
+2001-06-14  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
+
+	* scripts/README, scripts/hello.scm, safe/untrusted.scm,
+	safe/evil.scm, safe/README, modules/README, modules/main,
+	modules/module-0.scm, modules/module-1.scm, modules/module-2.scm:
+	Minor cleanup.
+
+	* README: Added intro stuff, restructured a bit.
+
+	* box-dynamic/README, box-module/README, box/README: Cleanup and
+	restructuring.
+
+	* box-dynamic-module/box-mixed.scm: New file, demonstrating usage
+	of extension library functionality, but without exporting
+	procedures from the library.
+
+	Thanks to Thomas Wawrzinek for the idea and example code!
+	
+	* box-dynamic-module/box-module.scm: Add comments, export
+	make-box, box-ref, box-set!.
+
+	* box-dynamic-module/README: Integrate new module (box-mixed),
+	restructure and cleanup a bit.
+
 2001-06-06  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
 
 	* box-dynamic-module/box-module.scm: New file.
diff --git a/examples/README b/examples/README
index 2a362f2cd..793d131c8 100644
--- a/examples/README
+++ b/examples/README
@@ -1,12 +1,28 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory contains examples illustrating various aspects of Guile
 programming.
 
+If you plan writing Scheme programs, have a look at the `scripts'
+directory.  To learn more about Guile modules, check out the `modules'
+directory, and maybe the `box-module' and `box-dynamic-module'
+directories, if you are into C programming or shared libraries,
+respectively.  The `safe' directory contains examples for evaluation
+Scheme code in controlled environments (sandboxing).  The directories
+`box', `box-module', `box-dynamic' and `box-dynamic-module' are
+interesting if you plan writing Guile extensions.
+
 See the README files in the subdirectories for details.
 
+
+* Included Examples
+
 scripts             Examples for writing simple scripts in Guile Scheme.
+
 box		    Example for extending Guile with a new data type.
+
 box-module	    Similar to `box', but defines new procedures in a
 		    named module.
 box-dynamic	    Implements the box type in a dynamically loadable
@@ -14,6 +30,7 @@ box-dynamic	    Implements the box type in a dynamically loadable
 box-dynamic-module  Combination of `box-module' and `box-dynamic': 
 		    Implements the `box' type in a shared library and
 		    defines the procedures in a Guile module.
+
 modules		    Examples for writing and using Guile modules.
-safe		    Examples for creating and using safe environments.
 
+safe		    Examples for creating and using safe environments.
diff --git a/examples/box-dynamic-module/Makefile.am b/examples/box-dynamic-module/Makefile.am
index ca157f2bc..4d7df0210 100644
--- a/examples/box-dynamic-module/Makefile.am
+++ b/examples/box-dynamic-module/Makefile.am
@@ -19,7 +19,7 @@
 ##   to the Free Software Foundation, Inc., 59 Temple Place, Suite
 ##   330, Boston, MA 02111-1307 USA
 
-EXTRA_DIST = README box.c box-module.scm
+EXTRA_DIST = README box.c box-module.scm box-mixed.scm
 
 CFLAGS=`guile-config compile`
 LIBS=`guile-config link`
diff --git a/examples/box-dynamic-module/README b/examples/box-dynamic-module/README
index 6e4636fa3..5097ec7d9 100644
--- a/examples/box-dynamic-module/README
+++ b/examples/box-dynamic-module/README
@@ -1,35 +1,44 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes an example program for extending Guile with a
 new (and even useful) data type, putting it into a shared library, so it 
 can be called from an unmodified guile interpreter. Further, the shared 
 library defines a new guile module.
 
+
+* Build Instructions
+
 To build the example, simply type
 
   make libbox-module
 
 in this directory.
 
+
+* The Box Data Type
+
 A box is simply an object for storing one other object in.  It can be
 used for passing parameters by reference, for example.  You simply
 store an object into a box, pass it to another procedure which can
 store a new object into it and thus return a value via the box.
 
+
+** Usage
+
 Box objects are created with `make-box', set with `box-set!' and
 examined with `box-ref'.  Note that these procedures are placed in a
 module called (box-module) and can thus only be accessed after using
-this module.  See the following example session for usage details:
+this module.  See the following example session for usage details.
+
+
+** The Module (box-module)
 
 Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and
 .libs and make sure that your current working directory is the one
 this file is contained in.
 
-If you like this example so much that you want to have it available
-for normal usage, install the dynamic libraries in the .libs directory
-to the directory $(prefix)/lib and the scheme file `box-module.scm' in
-a directory in your GUILE_LOAD_PATH.
-
 $ guile
 guile> (use-modules (box-module))
 guile> (define b (make-box))
@@ -42,3 +51,27 @@ guile> (box-ref b)
 (list of values)
 guile> (quit)
 $
+
+
+** The Module (box-mixed)
+
+The following example uses the module (box-mixed), also included in
+this directory.  It uses the shared library libbox-module like the
+module (box-module) above, but does not export the procedures from
+that module.  It only implements some procedures for dealing with box
+objects.
+
+$ guile
+guile> (use-modules (box-mixed))
+guile> (define bl  (make-box-list 1 2 3)) 
+guile> bl
+(#<box 1> #<box 2> #<box 3>)
+guile> (box-map (lambda (el) (make-box-list (list el))) bl)
+(#<box (#<box (1)>)> #<box (#<box (2)>)> #<box (#<box (3)>)>)
+guile> (quit)
+$
+
+If you like this example so much that you want to have it available
+for normal usage, install the dynamic libraries in the .libs directory
+to the directory $(prefix)/lib and the scheme file `box-module.scm' in
+a directory in your GUILE_LOAD_PATH.
diff --git a/examples/box-dynamic-module/box-mixed.scm b/examples/box-dynamic-module/box-mixed.scm
new file mode 100644
index 000000000..9e6135291
--- /dev/null
+++ b/examples/box-dynamic-module/box-mixed.scm
@@ -0,0 +1,44 @@
+;;; examples/box-dynamic-module/box-mixed.scm -- Scheme module using some
+;;;   functionality from the shared library libbox-module, but do not
+;;;   export procedures from the module.
+
+;;; Commentary:
+
+;;; This is the Scheme module box-mixed.  It uses some functionality
+;;; from the shared library libbox-module, but does not export it.
+
+;;; Code:
+
+;;; Author: Thomas Wawrzinek
+;;; Date: 2001-06-08
+;;; Changed: 2001-06-14 by martin, some commenting, cleanup and integration.
+
+(define-module (box-mixed))
+
+;; First, load the library.
+;;
+(load-extension "libbox-module" "scm_init_box")
+
+;; Create a list of boxes, each containing one element from ARGS.
+;;
+(define (make-box-list . args)
+  (map (lambda (el)
+	 (let ((b (make-box)))
+	   (box-set! b el) b))
+       args))
+
+;; Map the procedure FUNC over all elements of LST, which must be a
+;; list of boxes.  The result is a list of freshly allocated boxes,
+;; each containing the result of an application of FUNC.
+(define (box-map func lst)
+  (map (lambda (el)
+	 (let ((b (make-box)))
+	   (box-set! b (func (box-ref el)))
+	   b))
+       lst))
+
+;; Export the procedures, so that they can be used by others.
+;;
+(export make-box-list box-map)
+
+;;; End of file.
diff --git a/examples/box-dynamic-module/box-module.scm b/examples/box-dynamic-module/box-module.scm
index cab41c7e5..ab589ba1b 100644
--- a/examples/box-dynamic-module/box-module.scm
+++ b/examples/box-dynamic-module/box-module.scm
@@ -1,5 +1,5 @@
-;;; examples/box-dynamic-module/box-module.scm -- Scheme part of the
-;;;   dynamic module (box-module)
+;;; examples/box-dynamic-module/box-module.scm -- Scheme module exporting
+;;;   some functionality from the shared library libbox-module.
 
 ;;; Commentary:
 
@@ -14,4 +14,12 @@
 
 (define-module (box-module))
 
+;; First, load the library.
+;;
 (load-extension "libbox-module" "scm_init_box")
+
+;; Then export the procedures which should be visible to module users.
+;;
+(export make-box box-ref box-set!)
+
+;;; End of file.
diff --git a/examples/box-dynamic-module/box.c b/examples/box-dynamic-module/box.c
index fa9eaff41..c159a8f82 100644
--- a/examples/box-dynamic-module/box.c
+++ b/examples/box-dynamic-module/box.c
@@ -107,14 +107,13 @@ box_set_x (SCM b, SCM value)
 #undef FUNC_NAME
 
 
-/* Create and initialize the new smob type, and register the
-   primitives withe the interpreter library.
-
-   This function must be declared a bit different from the example in
-   the ../box directory, because it will be called by
-   `scm_c_define_module', called from below.  */
-static void
-init_box_type (void * unused)
+/* This is the function which must be given to `load-extension' as the
+   second argument.  In this example, the Scheme file box-module.scm
+   (or box-mixed.scm) is responsible for doing the load-extension
+   call.  The Scheme modules are also responsible for placing the
+   procedure definitions in the correct module. */
+void
+scm_init_box ()
 {
   scm_tc16_box = scm_make_smob_type ("box", 0);
   scm_set_smob_mark (scm_tc16_box, mark_box);
@@ -123,26 +122,6 @@ init_box_type (void * unused)
   scm_c_define_gsubr ("make-box", 0, 0, 0, make_box);
   scm_c_define_gsubr ("box-set!", 2, 0, 0, box_set_x);
   scm_c_define_gsubr ("box-ref", 1, 0, 0, box_ref);
-
-  /* This is new too: Since the procedures are now in a module, we
-     have to explicitly export them before they can be used.  */
-  scm_c_export ("make-box", "box-set!", "box-ref", NULL);
-}
-
-/* This is the function which must be given to `load-extension' as the
-   second argument.  It will initialize the shared, library, but will
-   place the definitions in a module called (box-module), so that an
-   additional (use-modules (box-module)) is needed to make them
-   accessible.  In this example, the Scheme file box-module.scm is
-   responsible for doing the load-extension call.  */
-void
-scm_init_box ()
-{
-  /* Unlike the example in ../box, init_box_type is not called
-     directly, but by scm_c_define_module, which will create a module
-     named (box-module) and make this module current while called
-     init_box_type, thus placing the definitions into that module.  */
-  scm_c_define_module ("box-module", init_box_type, NULL);
 }
 
 /* End of file.  */
diff --git a/examples/box-dynamic/README b/examples/box-dynamic/README
index 561e4841a..bb87b5db7 100644
--- a/examples/box-dynamic/README
+++ b/examples/box-dynamic/README
@@ -1,20 +1,31 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes an example program for extending Guile with a
 new (and even useful) data type, putting it into a shared library, so it 
 can be called from an unmodified guile interpreter.
 
+
+* Build Instructions
+
 To build the example, simply type
 
   make libbox
 
 in this directory.
 
+
+* The Box Data Type
+
 A box is simply an object for storing one other object in.  It can be
 used for passing parameters by reference, for example.  You simply
 store an object into a box, pass it to another procedure which can
 store a new object into it and thus return a value via the box.
 
+
+** Usage
+
 Box objects are created with `make-box', set with `box-set!' and
 examined with `box-ref'.  Note that these procedures are placed in a
 module called (box-module) and can thus only be accessed after using
@@ -23,9 +34,8 @@ this module.  See the following example session for usage details:
 Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and
 .libs 
 
-If you like this example so much that you want to have it available
-for normal usage, install the dynamic libraries in the .libs directory
-to the directory $(prefix)/lib
+
+** Example Session
 
 $ ./guile
 guile> (load-extension "libbox" "scm_init_box")
@@ -39,3 +49,10 @@ guile> (box-ref b)
 (list of values)
 guile> (quit)
 $
+
+
+* Module Installation
+
+If you like this example so much that you want to have it available
+for normal usage, install the dynamic libraries in the .libs directory
+to the directory $(prefix)/lib
diff --git a/examples/box-module/README b/examples/box-module/README
index 7f5d8521d..e1f1cd7af 100644
--- a/examples/box-module/README
+++ b/examples/box-module/README
@@ -1,4 +1,6 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes an example program for extending Guile with a
 new (and even useful) data type.
@@ -9,6 +11,9 @@ interpreter in this directory will place all defined primitive
 procedures in a module called (box-module).  That means that this
 module must be used before the primitives can be accessed.
 
+
+* Build Instructions
+
 To build the example, simply type
 
   make box
@@ -18,16 +23,25 @@ in this directory.
 The resulting `box' program is a Guile interpreter which has one
 additional data type called `box'.
 
+
+* The Box Data Type
+
 A box is simply an object for storing one other object in.  It can be
 used for passing parameters by reference, for example.  You simply
 store an object into a box, pass it to another procedure which can
 store a new object into it and thus return a value via the box.
 
+
+** Usage
+
 Box objects are created with `make-box', set with `box-set!' and
 examined with `box-ref'.  Note that these procedures are placed in a
 module called (box-module) and can thus only be accessed after using
 this module.  See the following example session for usage details:
 
+
+** Example Session
+
 $ ./box
 guile> (use-modules (box-module))
 guile> (define b (make-box))
diff --git a/examples/box/README b/examples/box/README
index 78b7762ef..fb0ef1305 100644
--- a/examples/box/README
+++ b/examples/box/README
@@ -1,8 +1,13 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes an example program for extending Guile with a
 new (and even useful) data type.
 
+
+* Build Instructions
+
 To build the example, simply type
 
   make box
@@ -12,15 +17,24 @@ in this directory.
 The resulting `box' program is a Guile interpreter which has one
 additional data type called `box'.
 
+
+* The Box Data Type
+
 A box is simply an object for storing one other object in.  It can be
 used for passing parameters by reference, for example.  You simply
 store an object into a box, pass it to another procedure which can
 store a new object into it and thus return a value via the box.
 
+
+** Usage
+
 Box objects are created with `make-box', set with `box-set!' and
 examined with `box-ref'.  See the following example session for usage
 details:
 
+
+** Example Session
+
 $ ./box
 guile> (define b (make-box))
 guile> b
diff --git a/examples/modules/README b/examples/modules/README
index 12df77f69..ddad881cc 100644
--- a/examples/modules/README
+++ b/examples/modules/README
@@ -1,4 +1,6 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes examples which show how to write and use Guile
 modules in Scheme programs.
@@ -7,7 +9,11 @@ The descriptions below assume that you have a working copy of Guile
 installed and available with the standard installation prefix
 `/usr/local'.
 
-main:
+
+* Included Examples
+
+
+** main
 
   The main program, which uses the modules described below to perform
   some actions.  Module usage and selective importing as well as
@@ -19,7 +25,7 @@ main:
 
   guile -s main
 
-module-0.scm, module-1.scm, module-2.scm:
+** module-0.scm, module-1.scm, module-2.scm
  
   Two modules which export several procedure, some of which have the
   same names (so that renaming/selection is required for proper
diff --git a/examples/modules/module-0.scm b/examples/modules/module-0.scm
index 47e8433c7..a5a001b64 100644
--- a/examples/modules/module-0.scm
+++ b/examples/modules/module-0.scm
@@ -20,3 +20,5 @@
 (define (bar)
   (display "module-0 bar")
   (newline))
+
+;;; End of file.
diff --git a/examples/modules/module-1.scm b/examples/modules/module-1.scm
index d62264021..6a7bb43e0 100644
--- a/examples/modules/module-1.scm
+++ b/examples/modules/module-1.scm
@@ -20,3 +20,5 @@
 (define (bar)
   (display "module-1 bar")
   (newline))
+
+;;; End of file.
diff --git a/examples/modules/module-2.scm b/examples/modules/module-2.scm
index a63d5e492..3147b2cab 100644
--- a/examples/modules/module-2.scm
+++ b/examples/modules/module-2.scm
@@ -24,3 +24,5 @@
 (define (braz)
   (display "module-2 braz")
   (newline))
+
+;;; End of file.
diff --git a/examples/safe/README b/examples/safe/README
index be16e1e74..47abcbf9f 100644
--- a/examples/safe/README
+++ b/examples/safe/README
@@ -1,4 +1,6 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes examples which show how to create and use safe
 environments for safe (sand-boxed) execution of Scheme programs.
@@ -12,7 +14,10 @@ The descriptions below assume that you have a working copy of Guile
 installed and available with the standard installation prefix
 `/usr/local'.
 
-safe:
+* Included Examples
+
+
+** safe
 
   The main program, which executes the Scheme code in a file given on
   the command line in a safe environment.  The following command will
@@ -24,12 +29,12 @@ safe:
 
   guile -s safe untrusted.scm
 
-untrusted.scm:
+** untrusted.scm
 
   This file contains some Scheme code, which will be executed in a
   safe environment by the `safe' script.
 
-evil.scm
+** evil.scm
 
   This file also contains Scheme code, but it tries to do evil things.
   Evaluating this with the `safe' script will abort on those evil
diff --git a/examples/safe/evil.scm b/examples/safe/evil.scm
index 9eb64db8e..f9ee9082f 100644
--- a/examples/safe/evil.scm
+++ b/examples/safe/evil.scm
@@ -23,3 +23,5 @@
 (let lp ((ch (read-char passwd)))
   (if (not (eof-object? ch))
     (lp (read-char passwd))))
+
+;;; End of file.
diff --git a/examples/safe/untrusted.scm b/examples/safe/untrusted.scm
index 9cdf1b640..f3ae5fe97 100644
--- a/examples/safe/untrusted.scm
+++ b/examples/safe/untrusted.scm
@@ -29,3 +29,5 @@
     ((= x 11))
   (display (fact x))
   (newline))
+
+;;; End of file.
diff --git a/examples/scripts/README b/examples/scripts/README
index 491007c27..f3e965b5a 100644
--- a/examples/scripts/README
+++ b/examples/scripts/README
@@ -1,4 +1,6 @@
-							       -*- text -*-
+							       -*- outline -*-
+
+* Overview
 
 This directory includes examples which show how to write scripts using
 Guile.
@@ -7,13 +9,16 @@ The descriptions below assume that you have a working copy of Guile
 installed and available with the standard installation prefix
 `/usr/local'.
 
-simple-hello.scm:
+* Included Examples
+
+
+** simple-hello.scm
 
   The simplest "Hello World!" program for Guile. Run it like this:
 
   $ guile -s simple-hello.scm
 
-hello:
+** hello
 
   An advanced version of the script above, with command line handling
   for the important options --help and --version.  Run it like this:
@@ -24,7 +29,7 @@ hello:
 
   guile -s hello
 
-fact:
+** fact
 
   Command-line factorial calculator.  Run it like this:
 
diff --git a/examples/scripts/fact b/examples/scripts/fact
index 90eecd7c2..05bcc9ffe 100755
--- a/examples/scripts/fact
+++ b/examples/scripts/fact
@@ -67,4 +67,3 @@
 ;; Local variables:
 ;; mode: scheme
 ;; End:
-
diff --git a/examples/scripts/hello b/examples/scripts/hello
index 4108db400..afeb64781 100755
--- a/examples/scripts/hello
+++ b/examples/scripts/hello
@@ -55,4 +55,3 @@
 ;; Local variables:
 ;; mode: scheme
 ;; End:
-
diff --git a/examples/scripts/simple-hello.scm b/examples/scripts/simple-hello.scm
index 713a1aee4..b46bc36ff 100644
--- a/examples/scripts/simple-hello.scm
+++ b/examples/scripts/simple-hello.scm
@@ -12,3 +12,5 @@
 
 (display "Hello, World!")
 (newline)
+
+;;; End of file.