@@ -1,7 +1,10 @@
 This will build a Tclkit named "tclkit-<version>".
 
+---------------
+Using This Tool
+---------------
 Usage:
 	kitcreator [{<version> | cvs_<cvsTag> | clean | distclean}]
 	           [<configure_options...>]
 
 	Where:
@@ -61,5 +64,84 @@
 
 	3. TCLKIT
 		Specify the path to a Tclkit that is runnable on the current
 		system.  The default is "tclkit".  A working tclkit is required
 		for cross-compiling Tclkits.
+
+
+
+-------------------
+Method of Operation
+-------------------
+Summary:
+	1. "kitcreator" calls */build.sh
+	2. */build.sh downloads and compiles appropriate software
+	3. */build.sh installs software into "inst" (run-time + compile-time)
+	4. */build.sh installs run-time software into "out", this will be
+	   included in the Tclkit as if it were the root directory of the
+	   Tclkit (combined with other "out" directories)
+	5. kitsh/build.sh compiles a "main" function and links all the built
+	   libraries together into an executable
+	6. kitsh/build.sh combines all the "out" directories into one
+	7. kitsh/build.sh creates a Metakit database from the combined
+	   directories and appends that to the compiled executable using:
+		a. A Tclkit found in the environment variable "TCLKIT" (tclkit
+		   if unset) if it is functional; or
+		b. The built kit itself (does not work for cross-compiling)
+
+Details:
+	The general mechanism that enables a Tclkit to operate is a small Tcl
+initialization routine linked statically to the core libraries needed to
+operate a Tcl interpreter, the Tcl VFS Layer, and a database-backed (Metakit)
+Virtual File System that is appended to the end of the executable.
+
+This project brings together all of the required pieces, plus some additional
+pieces that were found in the original Tclkit:
+	1. Tk (dynamically linked)
+	2. Itcl (dynamically linked)
+
+These source code for these pieces are downloaded, compiled, and linked, and
+the database containing the appropriate filesystem data is created.  What sets
+this project apart from other similar projects is that:
+	1. It attempts to be modular;
+	2. It supports cross-compiling;
+	3. It downloads the source from their original repositories;
+	4. It allows you to specify an arbitrary version of Tcl (including
+	   CVS); and
+	5. It uses GNU Autoconf scripts for compiling the part of the Tclkit
+	   that brings the whole thing together (the Kitsh)
+
+To accomplish these goals the following mechanisms are in place:
+	1. The top-level "kitcreator" script; and
+	2. Per-project subdirectories, each containing a "build.sh" script
+
+The top-level "kitcreator" script is very simple.  It's only job is to
+interpret command line arguments, and call the per-project "build.sh" scripts.
+For the "tcl" project it also finds the appropriate "tclConfig.sh" (and stores
+this path in TCLCONFIGDIR) to enable subsequent build scripts to find the
+appropriate Tcl to link against.
+
+The per-project "build.sh" scripts are entirely autonomous.  They are
+responsible for downloading the source code for the appropriate version that
+will compile and link against the current version of Tcl (user requested
+version can be found in "TCLVERS", while the actual version must be requested
+from the "tclConfig.sh" script), compiling it, installing a functional copy
+into the per-project "inst" directory, and installing anything that needs to
+be in the Tclkit's VFS root into the per-project "out" directory.
+
+The exception to this is the "kitsh" project.  It is the glue that binds all
+the individual projects together into a single executable.  Its build script
+does not create an "inst" or an "out" directory because it is not a library.
+Instead, it collects all the other project's "out" directories into a single
+directory (starpack.vfs), as well a static file (boot.tcl).  It then compiles
+the source code, and then installs the Metakit database containing the VFS
+onto the resulting executable.
+
+To create the Metakit database, one of two Tclkits is used (tried in this
+order):
+	1. The Tclkit specified by the TCLKIT environment variable (or
+	   "tclkit" if that variable is not set) if it is functional; or
+	2. The built Tclkit itself
+
+The second method will not work if the built Tclkit is not executable on the
+current platform (i.e., in the case of cross-compilation) and so it may be
+necessary to bootstrap a runnable Tclkit first.