* modules: New directory.

* modules/module-layout.text: New file.

devel/modules/module-layout.text

@@ -0,0 +1,288 @@
+Module Layout Proposal
+======================
+
+Martin Grabmueller
+<mgrabmue@cs.tu-berlin.de>
+Draft: 2001-03-11
+
+Version: $Id: module-layout.text,v 1.1 2001-03-16 08:37:37 mgrabmue Exp $
+
+* Table of contents
+
+** Abstract
+** Overview
+*** What do we have now?
+*** What should we change?
+** Policy of module separation
+*** Functionality
+*** Standards
+*** Importance
+*** Compatibility
+** Module naming
+*** Scheme
+*** Object oriented programming
+*** Systems programming
+*** Database programming
+*** Text processing
+*** Math programming
+*** Network programming
+*** Graphics
+*** GTK+ programming
+*** X programming
+*** Games
+*** Multiple names
+*** Application modules
+** Future ideas
+
+
+* Abstract
+
+This is a proposal for a new layout of the module name space.  The
+goal is to reduce (or even eliminate) the clutter in the current ice-9
+module directory, and to provide a clean framework for splitting
+libguile into subsystems, grouped by functionality, standards
+compliance and maybe other characteristics.
+
+This is not a completed policy document, but rather a collection of
+ideas and proposals which still have to be decided.  I will mention by
+personal preference, where appropriate, but the final decisions are of
+course up to the maintainers.
+
+
+* Overview
+
+Currently, new modules are added in an ad-hoc manner to the ice-9
+module name space when the need for them arises.  I think that was
+mainly because no other directory for installed Scheme modules was
+created.  With the integration of GOOPS, the new top-level module
+directory oop was introduced, and we should follow this practice for
+other subsystems which share functionality.
+
+DISCLAIMER: Please note that I am no expert on Guile's module system,
+so be patient with me and correct me where I got anything wrong.
+
+** What do we have now?
+
+The module (oop goops) contains all functionality needed for
+object-oriented programming with Guile (with a few exceptions in the
+evaluator, which is clearly needed for performance).
+
+Except for the procedures in the module (ice-9 rdelim), all Guile
+primitives are currently located in the root module (I think it is the
+module (guile)), and some procedures defined in `boot-9.scm' are
+installed in the module (guile-user).
+
+** What should we change?
+
+In the core, there are a lot of primitive procedures which can cleanly
+be grouped into subsystems, and then grouped into modules.  That would
+make the core library more maintainable, would ease seperate testing
+of subsystems and clean up dependencies between subsystems.
+
+
+* Policy of module separation
+
+There are several possibilities to group procedures into modules.
+
+- They could be grouped by functionality.
+- They could be grouped by standards compliance.
+- They could be grouped by level of importance.
+
+One important group of modules should of course be provided
+additionally:
+
+- Compatibility modules.
+
+So the first thing to decide is: Which of these policies should we
+adopt?  Personally, I think that it is not possible to cleanly use
+exactly one of the possibilities, we will probably use a mixture of
+them.  I propose to group by functionality, and maybe use some
+`bridge-modules', which make functionality available when the user
+requests the modules for a given standard.
+
+** Functionality
+
+Candidates for the first possibility are groups of procedures, which
+already are grouped in source files, such as
+
+- Regular expression procedures.
+- Network procedures.
+- Systems programming procedures.
+- Random number procedures.
+- Math/numeric procedures.
+- String-processing procedures.
+- List-processing procedures.
+- Character handling procedures.
+- Object-oriented programming support.
+
+** Standards
+
+Guile now complies to R5RS, and I think that the procedures required
+by this standards should always be available to the programmer.
+People who do not want them, could always create :pure modules when
+they need it.
+
+On the other hand, the SRFI procedures fit nicely into a `group by
+standards' scheme.  An example which is already provided, is the
+SRFI-8 syntax `receive'.  Following that, we could provide two modules
+for each SRFI, one named after the SRFI (like `srfi-8') and one named
+after the main functionality (`receive').
+
+** Importance
+
+By importance, I mean `how important are procedures for the average
+Guile user'.  That means that procedures which are only useful to a
+small group of users (the Guile developers, for example) should not be
+immediately available at the REPL, so that they not confuse the user
+when thay appear in the `apropos' output or the tab completion.
+
+A good example would be debugging procedures (which also could be
+added with a special command-line option), or low-level system calls.
+
+** Compatibility
+
+This group is for modules providing compatibility procedures.  An
+example would be a module for old string-processing procedures, which
+could someday get overridden by incompatible SRFI procedures of the
+same name.
+
+
+* Module naming
+
+Provided we choose to take the `group by functionality' approach, I
+propose the following naming hierarchy (some of them were actually
+suggested by Mikael Djurfeldt).
+
+- Schame language related in     (scheme)
+- Object oriented programming in (oop)
+- Systems programming in         (system)
+- Database programming in        (database)
+- Text processing in             (text)
+- Math/numeric programming in    (math)
+- Network programming in         (network)
+- Graphics programming in	 (graphics)
+- GTK+ programming in		 (gtk)
+- X programming in               (xlib)
+- Games in			 (games)
+
+The layout of sub-hierarchies is up to the writers of modules, we
+should not enforce a strict policy here, because we can not imagine
+what will happen in this area.
+
+** Scheme
+
+(scheme r5rs)		 Complete R5RS procedures set.
+(scheme safe)		 Safe modules.
+(scheme srfi-1)		 List processing.
+(scheme srfi-8)		 Multiple valuas via `receive'.
+(scheme receive)	 dito.
+(scheme and-let-star)	 and-let*
+(scheme syncase)	 syntax-case hygienic macros (maybe included in
+			 (scheme r5rs?).
+(scheme slib)		 SLIB, for historic reasons in (scheme).
+
+** Object oriented programming
+
+Examples in this section are
+(oop goops)              For GOOPS.
+(oop goops ...)          For lower-level GOOPS functionality and utilities.
+
+** Systems programming
+
+(system shell)	         Shell utilities (glob, system etc).
+(system process)	 Process handling.
+(system file-system)	 Low-level filesystem support.
+(system user)		 getuid, setpgrp, etc.
+
+_or_
+
+(system posix)		 All posix procedures.
+
+** Database programming
+
+In the database section, there should be sub-module hierarchies for
+each supported database which contains the low-level code, and a
+common database layer, which should unify access to SQL databases via a single interface a la Perl's DBMI.
+
+(database postgres ...)  Low-level database functionality. 
+(database oracle ...)    ...
+(database mysql ...)     ...
+(database msql ...)      ...
+(database sql)		 Common SQL accessors. 
+(database gdbm ...)      ...
+(database hashed)        Common hashed database accessors (like gdbm).
+(database util)		 Leftovers.
+
+** Text processing
+
+(text rdelim)            Line oriented in-/output.
+(text util)		 Mangling text files.
+
+** Math programming
+
+(math random)            Random numbers.
+(math primes)		 Prime numbers.
+(math vector)		 Vector math.
+(math algebra)		 Algebra.
+(math analysis)		 Analysis.
+(math util)		 Leftovers.
+
+** Network programming
+
+(network inet)		 Internet procedures.
+(network socket)	 Socket interface.
+(network db)		 Network database accessors.
+(network util)		 ntohl, htons and friends.
+
+** Graphics
+
+(graphics vector)	 Generalized vector graphics handling.
+(graphics vector vrml)	 VRML parsers etc.
+(graphisc bitmap)	 Generalized bitmap handling.
+(graphics bitmap ...)    Bitmap format handling (TIFF, PNG, etc.).
+
+** GTK+ programming
+
+(gtk gtk)		 GTK+ procedures.
+(gtk gdk)		 GDK procedures.
+(gtk threads)		 gtktreads.
+
+** X programming
+
+(xlib xlib)		 Low-level XLib programming.
+
+** Games
+
+(games robots)		 GNU robots.
+
+** Multiple names
+
+As already mentioned above, I think that some modules should have
+several names, to make it easier for the user to get the functionality
+she needs.  For example, a user could say: `hey, I need the receive
+macro', or she could say: `I want to stick to SRFI syntax, so where
+the hell is the module for SRFI-8?!?'.
+
+** Application modules
+
+We should not enforce policy on applications.  So I propose that
+application writers should be advised to place modules either in
+application-specific directories $PREFIX/share/$APP/guile/... and name
+that however they like, or to use the application's name as the first
+part of the module name, e.g (gnucash import), (scwm background),
+(rcalc ui).
+
+* Future ideas
+
+I have not yet come up with a good idea for grouping modules, which
+deal for example with XML processing.  They would fit into the (text)
+module space, because most XML files contain text data, but they would
+also fit into (database), because XML files are essentially databases.
+
+On the other hand, XML processing is such a large field that it
+probably is worth it's own top-level name space (xml).
+
+
+Local Variables:
+mode: outline
+End: