* 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.

5 files changed, 102 insertions, 38 deletions

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.  */