Merge commit '7c621da28f07e449ad90c387344f07a453927569' as 'tcllib'

7 files changed, 858 insertions, 0 deletions

diff --git a/tcllib/devdoc/critcl-tcllib.txt b/tcllib/devdoc/critcl-tcllib.txt
new file mode 100644
index 0000000..d63b7d8
--- /dev/null
+++ b/tcllib/devdoc/critcl-tcllib.txt
@@ -0,0 +1,116 @@
+* Enhancing tcllib with CriTcl
+
+    I have been looking into using critcl [http://wiki.tcl.tk.critcl]
+    to enhance some of the computationally intensive packages in
+    tcllib with compiled functions. The intention here is to provide
+    an alternative implementation for the 'hot-spots' in a package. In
+    the case of the uuencode package, for instance, we can provide
+    just the function that encodes or decodes a chunk of data. The
+    remainder of the package can be left in Tcl - which importantly
+    means that the public interface to the package remains identical.
+
+    There is already some precedent for enhancing tcllib in this
+    way. Trf is used in the base64, md5 and sha1 packages to
+    optionally provide a compiled implementation of the
+    package. Importantly we still have a pure-tcl implementation.
+
+    Provided that we accept that this hot-spot compilation strategy is
+    a good idea there is an issue to do with how the compiled code is
+    bundled. Critcl can build libraries or packages. Packages are the
+    same as libraries except that the library is placed into a
+    platform dependent subdirectory and a suitable pkgIndex file is
+    created. 
+
+    There are four main possibilities:
+       1) library-per-package
+       2) package-per-package
+       3) package-per-module
+       4) tcllib-c-package
+
+** library-per-package
+    a library is built for each critcl-enabled tcllib package. For
+    instance, 'critcl -lib uuencode.dll base64/uuencode.tcl'. This
+    doesn't generate any package loading tcl code and so doesn't
+    require a new package name. Instead the calling code will have to
+    handle loading the correct library. Once loaded the compiled
+    commands are available in the tcl namespace. For example,
+    ' load uuencode.tcl ; uuencode::CEncode abc '
+
+** package-per-package
+    a compiled package is built for each critcl-enabled package. For
+    instance, 'critcl -pkg uuencode_c base64/uuencode.tcl'. This
+    builds the same library and for library-per-package but also
+    generates the package loading code. This requires a unique package
+    name (such as ${package}_c).
+
+** package-per-module
+    a compiled package is built for each tcllib module. For instance,
+    'critcl -pkg base64c base64/base64c.tcl base64/uuencode.tcl
+    base64/yencode.tcl'. This collects all the critcl sections for a
+    module (which may contain a number of packages) into one library
+    and then creates the package loading code for this library.
+
+** tcllib-c-package
+    a compiled package is built for tcllib. This combines all the
+    critcl sections for all tcllib packages together in one
+    library. An advantage to this is that there is only one package
+    name and only one library.
+
+
+
+* Examples
+
+** library-per-package
+
+    critcl -lib yencode.dll base64\yencode.tcl
+    critcl -lib uuencode.dll base64\uuencode.tcl
+    critcl -lib md4c.dll md4\md4c.tcl
+    critcl -lib md4c.dll md4\md4c.tcl
+    critcl -lib sum.dll crc\sum.tcl
+
+    This gives us the named dll's in the current directory. For this case
+    I get (under Windows):
+      md4c.dll     - 15,360
+      md5c.dll     - 15,360
+      sum.dll      - 12,800
+      uuencode.dll - 13,312
+      yencode.dll  - 12,800
+
+** package-per-package
+
+    This creates libraries of the same size as library-per-package.
+
+** package-per-module
+
+    critcl -libdir . -pkg base64c base64c\base64c.tcl base64\uuencode.tcl
+        base64\yencode.tcl
+    critcl -libdir . -pkg md4c md4\md4c.tcl
+    critcl -libdir . -pkg md5c md5\md5c.tcl
+    critcl -libdir . -pkg crc  crc\crcc.tcl crc\sum.tcl
+    
+    This gives:
+      base64c.dll - 14,848
+      crcc.dll    - 12,800
+      md4c.dll    - 15,360
+      md5c.dll    - 15,360
+
+** tcllib-c-package
+
+    critcl -libdir . -pkg tcllibc <all the above>
+      tcllibc.dll - 19,968
+
+* Conclusion
+
+    We can see that the overhead of producing a dynamic library is
+    quite significant - at least for Windows. Building a library for
+    all 5 packages is only around 4000 bytes larger than the library
+    for a single package. There is also a cost involved in loading
+    each dynamic library as they have to be loaded from disk and
+    relocated in memory. Other concerns are the package namespace
+    pollution - by which I mean the proliferation of package names
+    caused by creating compiled packages for each tcllib package. Also
+    ease of loading - I don't really think abandoning the tcl package
+    mechanism is a good idea.
+
+Pat Thoyts
+
diff --git a/tcllib/devdoc/cvs.branches.fig b/tcllib/devdoc/cvs.branches.fig
new file mode 100644
index 0000000..3c6f6a3
--- /dev/null
+++ b/tcllib/devdoc/cvs.branches.fig
@@ -0,0 +1,32 @@
+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+6 3000 2025 5400 2400
+4 0 12 50 0 0 14 0.0000 4 150 2385 3000 2175 Point releases are branched\001
+4 0 12 50 0 0 14 0.0000 4 150 1530 3000 2370 from RELEASES\001
+-6
+6 2400 750 5700 1200
+4 0 1 50 0 0 14 0.0000 4 195 3225 2400 900 Developer performs internal releases,\001
+4 0 1 50 0 0 14 0.0000 4 195 3285 2400 1095 merging from HEAD into RELEASES\001
+-6
+2 1 0 4 0 7 50 0 -1 0.000 0 0 7 1 0 2
+	2 1 4.00 240.00 480.00
+	 300 600 5700 600
+2 1 0 2 1 7 50 0 -1 0.000 0 0 -1 1 0 2
+	2 1 2.00 120.00 240.00
+	 2100 600 2400 1800
+2 1 0 5 12 7 50 0 -1 0.000 0 0 -1 1 0 3
+	2 1 5.00 300.00 600.00
+	 2700 1800 3000 3000 5700 3000
+2 1 0 4 17 7 50 0 -1 0.000 0 0 7 1 0 3
+	2 1 4.00 240.00 480.00
+	 1200 600 1500 1800 5700 1800
+4 0 0 50 0 0 14 0.0000 4 195 2835 3150 1575 Staging for release : RELEASES\001
+4 0 0 50 0 0 14 0.0000 4 195 1905 3900 300 Development : HEAD\001
+4 0 0 50 0 0 14 0.0000 4 150 930 4800 2700 Tcllib 1.2.0\001
diff --git a/tcllib/devdoc/devguide.html b/tcllib/devdoc/devguide.html
new file mode 100644
index 0000000..c438ca4
--- /dev/null
+++ b/tcllib/devdoc/devguide.html
@@ -0,0 +1,50 @@
+<!- Guide for Tcllib developers -->
+
+<h1>Guide for Tcllib developers.
+</h1>
+<hr>
+
+<h2>CVS Repository
+</h2>
+<table><tr><td valign=top>
+      <!-- The local source of this image is
+		tcllib/devel/cvs.branches.*
+	-->
+      <img src="http://sourceforge.net/dbimage.php?id=2221">
+</td><td valign=top><p>
+
+The CVS repository for Tcllib contains two main branches, the HEAD for
+development, and RELEASES as the staging area for official
+releases. At RELEASES the minor branches containing the various
+official releases are anchored at.
+</p></td></tr></table>
+
+<p>All the branches are of interest to the developers for
+      Tcllib. Ongoing development happens in HEAD, which can be
+      unstable or may not work at all. Whenever a developer considers
+      a piece of code, or module, he is responsible for as
+      sufficiently stable she has to perform an internal release which
+      merges this part from HEAD into RELEASES. Tools to help with
+      this will be provided.
+</p>
+
+<p>The branches for the official releases of tcllib are of interest to
+      a developer because it is expected that fixes for important bugs
+      not only go into the HEAD branch but also into the release
+      branches for the release they were found in and all releases
+      following that one. This is to allow the release manager to
+      create patch releases of existing releases distributing important
+      bugfixes as well.
+</p>
+
+<p>Version numbers for modules are handled as described below. This
+      way of handling them was chosen so that the modules in the
+      development branch always uses version numbers different from
+      the version numbers in the official releases made so far.
+</p>
+<ul>
+<li>Whenever an internal release of a module FOO is done, the
+	developer performing this internal release has to increment
+	the version number of the module <b>after</b> the release was
+	executed.
+</ul>
diff --git a/tcllib/devdoc/dirlayout_install.txt b/tcllib/devdoc/dirlayout_install.txt
new file mode 100644
index 0000000..8cacea0
--- /dev/null
+++ b/tcllib/devdoc/dirlayout_install.txt
@@ -0,0 +1,85 @@
+Tcllib installation directory layout
+====================================
+
+This document describes the possible layouts for an installed tcllib,
+discusses their pro and contra and makes a choice for Tcllib 1.4. A
+roadmap of changes in the future is made available as appendix.
+
+[L1/D] Deep layout
+------------------
+
+        This is the layout of Tcllib 1.3 (and versions before that).
+
+        A single directory tcllib<version> is created, and all
+        subdirectories of the 'modules' subdirectory in the
+        distribution is copied into it. This is restricted at large to
+        *.tcl files, with exception made for some modules with special
+        needs.
+
+        Pro:
+        Contra:
+                Makes the handling of the various package indices,
+                well, not difficult, but uncomfortable.
+
+
+[L2/Fa] Flat layout 1
+---------------------
+
+        A directory is created for each module of tcllib.
+
+        Pro:
+                Handling of package indices is easier than for L1/D, a
+                toplevel index file with all its problems is not
+                required anymore.
+
+        Contra:
+                Directories should be versioned to avoid conflicts
+                between multiple releases. modules have no
+                version. This can be faked for modules containing one
+                package, but not for the modules with more.
+
+
+[L2/Fb] Flat layout 2
+---------------------
+
+        A directory is created for each package in tcllib.
+
+        Pro
+                Handling of package indices is easy, one per package.
+
+        Contra:
+                Modules containing more than one package are difficult
+                to handle. The system has to split them into the
+                individual packages. This rendered very difficult
+                because of shared package index files.
+        
+                This can be solved by moving tcllib (back) towards of
+                one package per module. When that goal is reached
+                L2/Fa and L2/Fb become the same, and the contra for
+                L2/Fa vanishes too as an exact version number can be
+                associated with each directory.
+
+Chosen layout for Tcllib 1.4
+----------------------------
+
+        L1/D
+
+        Despite the problems with package indices the contras against
+        the flat structures are too strong at this point in
+        time. Automatic solutions are not really possible, or require
+        a very high effort.
+
+Roadmap
+-------
+        Change the module directories of tcllib to contain exactly one
+        package per directory, with appropriate index (and meta data).
+
+        This not only makes sense for easier handling of installation
+        and package indices, but also in the greater context of
+        wrapping code for deployment.
+
+
+-----------------------------------
+This document is in the public domain.
+
+                        Andreas Kupries <andreas_kupries@users.sf.net>
diff --git a/tcllib/devdoc/indexing.txt b/tcllib/devdoc/indexing.txt
new file mode 100644
index 0000000..ddc501a
--- /dev/null
+++ b/tcllib/devdoc/indexing.txt
@@ -0,0 +1,418 @@
+Tcllib package indexing
+=======================
+
+This document describes the possibilities for using one or more
+pkgIndex.tcl files in an installation of tcllib to provide the
+information about all of its packages to a tcl interpreter, discusses
+their pro and contra and makes a choice for Tcllib 1.4. A roadmap of
+changes in the future is made available as an appendix.
+
+Background under which to see the solutions:
+
+        There are three level of groupings:
+
+        -       The tcllib project itself
+        -       Modules in the project (== subdirectory of 'modules')
+        -       Packages in a module.
+
+        Each module currently contains one package index file.
+
+        Some modules contain more than one package. They share the index.
+
+        Most packages require specific versions of the Tcl
+        interpreter. They perform the checks in their package index
+        file and do not register if the pre-requisites are not
+        fulfilled.
+
+        Other checks are possible, but currently not in use.
+
+Note I:
+	Whether a solution is actually applicable depends on external
+	factors, like the chosen directory layout of an installed
+	tcllib.
+
+Note II:
+	All solutions currently depend on the specific implementation
+	of [tclPkgUnknown] coming with the basic core, simply by the
+	fact that the files looked at are called 'pkgIndex.tcl'. This
+	is therefore no contra argument against any specific solution,
+	but against all. We ignore this as currently there is no
+	better replacement in existence.
+
+Note III:
+	We have to support Tcl before 8.3. as some packages in tcllib
+	allow this.
+
+
+[i1/ng] No global package index
+-------------------------------
+
+        In this solution the module package indices are the only index
+        files present in an installation.
+
+        This solution is applicable if and only if one of the flat
+        directory layouts (L2/Fa or L2/Fb) has been chosen.
+
+        Pro:
+                Simple. No need for complex management.
+
+
+[i2/ad] Global package index, auto_path extension, direct
+---------------------------------------------------------
+
+        A single global package index is present in the toplevel
+        directory of the installation.
+
+        This solution is applicable if and only if the deep directory
+        layout (L2/D) has been chosen.
+
+        The package index contains a series of statements extending
+        the auto_path variable with all module directories. The list
+        of names of the module directories is hardcoded. In other
+        words, it is _not_ determined via [glob].
+
+        Example:
+                lappend auto_path [file join $dir md4]
+                lappend auto_path [file join $dir md5]
+                lappend auto_path [file join $dir sha1]
+                ...
+
+
+        Pro:
+                [[0]]   Compared to [i3/ag] this should be bit faster
+                        as glob'ing the directory tree of tcllib is
+                        avoided. This performance-boost is not a big
+                        pro according to the opinions below.
+
+                [[1]]   Relies on the module package index files for
+                        the actual registration of packages, thus
+                        automatically inherits the correct constraints
+                        on the registration of packages. No additional
+                        complexities.
+
+                [[2]]   Easier to generate than [i6/dr].
+
+        Contra:
+                [[3]]   Hard coding the directory names implies that
+                        adding modules to the installed tcllib is not
+                        as easy as just creating a new directory for
+                        the module/package. The global index has to be
+                        updated too.
+
+                        Contra-Contra:
+                                <<Don: New, updated packages should be
+                                installed separately, outside of
+                                tcllib. The ticked version number
+                                ensures that it is prefered over the
+                                package in tcllib.>>
+
+                                <<AK: Agree fully>>
+        
+                [[4]]   Extending the 'auto_path' list causes the
+                        package management of the tcl core to re-read
+                        the list and glob through all of them for new
+                        package indices. This has a high cost in terms
+                        of filesystem access, i.e. is an issue of
+                        performance.
+
+                        Contra-Contra:
+                                <<Don: IMHO, it's not really tcllib's
+                                job to fix [tclPkgUnknown]'s
+                                performance problems. If performance
+                                is a problem, users could try the
+                                patch with Tcl Feature Request 680169
+                                and see if it helps.>>
+
+                                <<AK: Not sure yet about this>>
+
+
+                [[5]]   This enables auto-loading in each module
+                        (according to any tclIndex file installed).
+                        This should not be done by the package
+                        indexer, but by the package itself.  See
+                        control for an example.
+
+	  	[[10]]	Will not work with Tcl releases prior to
+			8.3.1.  Only then was [tclPkgUnknown]
+			"enhanced" to deal with changing ::auto_path
+			values.  If tcllib 1.4 wishes to continue
+			supporting pre-8.3.1 Tcl, then this option has
+			to be supplemented with a fallback.
+
+
+[i3/ag] Global package index, auto_path extension, glob
+-------------------------------------------------------
+
+        This is like [i2/ad], except that the list of sub directories
+        is not hardcoded into the index, but determined through glob.
+
+        Example:
+                foreach subdir [glob -nocomplain -type d $dir/*] {
+                    lappend auto_path $subdir
+                }
+
+        Pro:
+                Anti-[[3]]
+                [[1]]
+
+        Contra:
+                All the contras of [i2/ad] and Anti-[[0]].
+
+
+[i4/sd] Global package index, sourcing module indices, direct
+-------------------------------------------------------------
+
+        A single global package index is present in the toplevel
+        directory of the installation.
+
+        This solution is applicable if and only if the deep directory
+        layout (L2/D) has been chosen.
+
+        The package index contains a series of statements source'ing
+        the package index files of the modules in tcllib. The list
+        of names of the module directories is hardcoded. In other
+        words, it is _not_ determined via [glob].
+
+        Example:
+                set main $dir
+                set dir [file join $main md4]  ; source [file join $dir pkgIndex.tcl]
+                set dir [file join $main md5]  ; source [file join $dir pkgIndex.tcl]
+                set dir [file join $main sha1] ; source [file join $dir pkgIndex.tcl]
+                ...
+
+        Pro:
+                [[0]], but compared to [i5/sg].
+                [[1]]
+                [[2]]
+                [[6]]   In contrast to [i2/ad] and [i3/ag] repeated
+                        glob'ing for package index files is
+                        avoided. This cuts down on costly FS accesses.
+                        I.e. another perf. boost.
+
+        Contra:
+                [[3]]
+
+[i5/sg] Global package index, sourcing module indices, glob
+-----------------------------------------------------------
+
+        This is like [i4/sd], except that the list of package indices
+        to source is not hardcoded into the index, but determined
+        through glob.
+
+        Example:
+                foreach subdir [glob -nocomplain -type d $dir/*] {
+                        set dir $subdir
+                        source [file join $dir pkgIndex.tcl]
+                }
+
+        Pro:
+                Anti-[[3]]
+                [[1]]
+                [[2]]
+
+        Contra:
+                All the contras of [i2/sd], and Anti-[[0]]
+
+
+[i6/dr] Global package index, direct registration
+-------------------------------------------------
+
+        A single global package index is present in the toplevel
+        directory of the installation.
+
+        This solution is applicable if and only if the deep directory
+        layout (L2/D) has been chosen.
+
+        The package index contains a series of statements which
+        directly register all the tcllib packages.
+
+        Example:
+                if {[constraint]} {return}
+                package ifneeded md4  [list source [file join $dir md4 md4.tcl]]
+                package ifneeded md5  [list source [file join $dir md4 md4.tcl]]
+                package ifneeded sha1 [list source [file join $dir md4 md4.tcl]]
+                ... more constraints ... package ifneeded
+
+        Pro:
+                [[7]]   This is the fasted solution as the number of
+                        accesses to the filesystem is minimal.
+
+        Contra:
+                [[[3]]
+                Anti-[[1]]	Care has to be taken to ensure that
+                                the constraints the module indices
+                                place on the registration of packages
+                                are replicated in the global
+                                index. All other solutions simply used
+                                the module indices and thus got it
+                                right automatically. Now supporting
+                                code is required to detect such
+                                constraints and then to properly
+                                recreate them globally.
+
+                                = High complexity for the maintainer.
+
+[i7/ad] Global package index, auto_path extension, direct
+---------------------------------------------------------
+
+        A single global package index is present in the toplevel
+        directory of the installation.
+
+        This solution is applicable if and only if the deep directory
+        layout (L2/D) has been chosen.
+
+        The package index contains a single statement extending the
+        auto_path variable with the tcllib main directory. The
+        standard package management will then find all module sub
+        directories and the package indices in them.
+
+        Example:
+                lappend auto_path $dir
+
+        Pro:
+                [[1]]
+                [[8]]   This is the easiest solution by far in terms
+                        of code to write, and complexities to solve
+                        (none).
+
+		[[9]]	<<Don: I believe this is the only proposal listed
+			that actually fixes tcllib Bug 720318
+			(successful [package require] of packages
+			within a SafeBase) because it is the only one
+			that changes the value of ::auto_path.>>
+
+			<<AK: This is true, yet brittle. It depends on
+			when the SafeBase sees the auto_path. If it
+			happens to be before a [package require
+			something] forced the reading of all package
+			indices (and thus the extension of
+			'auto_path') we are still SOL.>>
+
+	Contra: [[4]]
+	  	[[10]]
+
+
+[i8/pm] Global package index, pkg_mkIndex
+-----------------------------------------
+
+Just use [pkg_mkIndex modules */*.tcl] to generate the master index.
+
+	Pro:
+		Easy to do.
+
+	Contra:
+		Does not handle constraints in subordinate package
+		indices, simply because they are actually ignored
+		during processing.
+
+		Adding code to handle constraints evolves this into
+		[i6/dr].
+
+	Note: The contra is hard enough IMHO to make this solution not
+	applicable for 1.4, which does have constraints, and handling
+	them wrong (not at all) is a bug.
+
+
+General discussion
+------------------
+
+Given that a deep directory layout was chosen [i1/ng] is not
+applicable and therefore dropped from the discussion.
+
+In the pro and contra arguments listed above three independent axes of
+reasoning emerged:
+
+a)        Performance of the solution, with the number of accesses to
+          filesystem the main factor determining it.
+
+b)        Complexity/difficulty of the solution with regard to
+          adding/updating packages.
+
+c)        Complexity of generating the master index.
+
+Axis (b) has essentially been thrown out. Trying to modify the
+installation of tcllib itself is bad practice. Install new/updated
+packages separately. The version numbering takes care of the rest,
+i.e. usage of the new over the older version found in tcllib.
+
+With respect to axis (c), complexity of generation, [i7/ad] is the
+definite winner, with the other *d solutions close behind (all use
+fixed scripts, I7/ad wins on size). This is followed by the *g
+solutions as they require actual dynamic generation of code. And at
+the bottom of the ladder is [i6/dr] with its need for close inspection
+of the sub-ordinate indices to get everything right.
+
+Now axis (a), performance, [i6/dr] is most likely the winner as it
+causes only one index to be read and nothing else. This is followed by
+the all *d solutions, which read the subordinate indices, but do not
+need much glob'ing. The actual order in this group is difficult to
+determine. I guess that the auto_path extending methods are slower
+than the sourcing methods, and the adding of one directory faster than
+the adding of all, as the latter looks for much more subdirectories.
+The next group are the *g solutions as they perform their own glob'ing too
+beyond that done by the package mgmt.
+
+Two final rankings
+
+        (c), then (a)           (a), then (c)
+        -------------           -------------
+        [i7/ad]                 [i6/dr]
+        [i4/sd]                 [i4/sd]
+        [i2/ad]                 [i7/ad]
+        [i5/sg]                 [i2/ad]
+        [i3/ag]                 [i5/sg]
+        [i6/dr]                 [i3/ag]
+        -------------           -------------
+
+[i4/sd] seems to be a good compromise solution between performance and
+complexity of generation, but [i7/ad] is not too bad either.
+
+[i4/sd] reminder:
+        set main $dir
+        set dir [file join $main md4]  ; source [file join $dir pkgIndex.tcl]
+        set dir [file join $main md5]  ; source [file join $dir pkgIndex.tcl]
+        set dir [file join $main sha1] ; source [file join $dir pkgIndex.tcl]
+        ...
+
+[i7/ad] reminder:
+        lappend auto_path $dir
+
+Other opinions:
+
+      	Don Porter prefers [i7/ad], and [i6/dr] as second choice.  Also
+	as [i7/ad] fallback for older Tcl before 8.3.1
+
+	Joe English strictly opposes any solution modifying the
+	auto_path, violating his opinion that index scripts should
+	have no side-effects beyond registering a package.
+
+
+Chosen solution for Tcllib 1.4
+------------------------------
+
+After comparing the code for the combination of [i7/ad] and [i6/dr] as
+submitted by Don Porter, and for [i4/sd] as submitted by myself
+(Andreas), and a small discussion on the Tcl'ers chat between Don and
+me, we took [i4/sd] for the main body of the index, and the header of
+Don's code. Basically the chosen package index is a combination of
+[i7/id] and of [i4/sd] as fallback.
+
+This is still as easy to generate as [4/sd], the index is also only a
+bit more complex, and speed should be okay too.
+
+Don convinced me that while extending auto_path is definitely bad in
+the long-term it is still okay for the short-term and release 1.4.
+
+
+Roadmap
+-------
+
+After Tcllib has been driven into the state of one package per module
+directory, and switched to a flat directory layout for its
+installation we switch to [i1/ng] for the indexing structure.
+
+
+-----------------------------------
+This document is in the public domain.
+
+                        Andreas Kupries <andreas_kupries@users.sf.net>
diff --git a/tcllib/devdoc/installation.txt b/tcllib/devdoc/installation.txt
new file mode 100644
index 0000000..e8b95b7
--- /dev/null
+++ b/tcllib/devdoc/installation.txt
@@ -0,0 +1,85 @@
+Tcllib installation directory layout
+====================================
+
+This document describes the possible layouts for an installed tcllib,
+discusses their pro and contra and makes a choice for Tcllib 1.4. A
+roadmap of changes in the future is made available as appendix.
+
+[L1/D] Deep layout
+------------------
+
+	This is the layout of Tcllib 1.3 (and versions before that).
+
+	A single directory tcllib<version> is created, and all
+	subdirectories of the 'modules' subdirectory in the
+	distribution is copied into it. This is restricted at large to
+	*.tcl files, with exception made for some modules with special
+	needs.
+
+	Pro:
+	Contra:
+		Makes the handling of the various package indices,
+		well, not difficult, but uncomfortable.
+
+
+[L2/Fa] Flat layout 1
+---------------------
+
+	A directory is created for each module of tcllib.
+
+	Pro:
+		Handling of package indices is easier than for L1/D, a
+		toplevel index file with all its problems is not
+		required anymore.
+
+	Contra:
+		Directories should be versioned to avoid conflicts
+		between multiple releases. modules have no
+		version. This can be faked for modules containing one
+		package, but not for the modules with more.
+
+
+[L2/Fb] Flat layout 2
+---------------------
+
+	A directory is created for each package in tcllib.
+
+	Pro
+		Handling of package indices is easy, one per package.
+
+	Contra:
+		Modules containing more than one package are difficult
+		to handle. The system has to split them into the
+		individual packages. This rendered very difficult
+		because of shared package index files.
+	
+		This can be solved by moving tcllib (back) towards of
+		one package per module. When that goal is reached
+		L2/Fa and L2/Fb become the same, and the contra for
+		L2/Fa vanishes too as an exact version number can be
+		associated with each directory.
+
+Chosen layout for Tcllib 1.4
+----------------------------
+
+	L2/D
+
+	Despite the problems with package indices the contras against
+	the flat structures are too strong at this point in
+	time. Automatic solutions are not really possible, or require
+	a very high effort.
+
+Roadmap
+-------
+	Change the module directories of tcllib to contain exactly one
+	package per directory, with appropriate index (and meta data).
+
+	This not only makes sense for easier handling of installation
+	and package indices, but also in the greater context of
+	wrapping code for deployment.
+
+
+-----------------------------------
+This document is in the public domain.
+
+			Andreas Kupries	<andreas_kupries@users.sf.net>
diff --git a/tcllib/devdoc/releaseguide.html b/tcllib/devdoc/releaseguide.html
new file mode 100644
index 0000000..1fd086c
--- /dev/null
+++ b/tcllib/devdoc/releaseguide.html
@@ -0,0 +1,72 @@
+<!- Guide to the creation of source releases for Tcllib -->
+
+<h1>Guide to the creation of source releases for Tcllib
+</h1>
+<hr>
+
+<h2>Recap
+</h2>
+<table><tr><td valign=top>
+      <!-- The local source of this image is
+		tcllib/devel/cvs.branches.*
+	-->
+      <img src="http://sourceforge.net/dbimage.php?id=2221">
+</td><td valign=top><p>
+The CVS repository for Tcllib contains two main branches,
+      the HEAD for development, and RELEASES as the staging area for
+      official releases.
+</p></td></tr></table>
+
+<h2>Dependencies
+</h2>
+
+<h2>Creation of a new official release
+</h2>
+
+<p>To create a new official release of Tcllib the release manager has
+      to perform the steps described below:
+</p>
+
+
+<ol>
+<li> Retrieve the sources at the current head
+	from the CVS repository, using a command like
+<pre>
+	  CVSROOT=:pserver:anonymous@cvs.tcllib.sourceforge.net:/cvsroot/tcllib
+	  cvs -d${CVSROOT} co tcllib
+</pre>
+	Vary this command according to taste as long as the overall
+	meaning is not changed. Compression options and the like.
+
+<li> Tag these sources with a new branch tag for the new release of
+	  tcllib, like
+<pre>
+	  cvs -d${CVSROOT} rtag tcllib
+</pre>
+
+<li> Commit the changes, then update the working directory.
+
+<li> Use a tclsh to run the <b>sak</b> tool with the argument <i>gendist</i>, like
+<pre>
+    tclsh /path/to/tcllib/sak.tcl gendist
+</pre>
+
+<li> This results in the creation of a <i>tcllib-VERSION</i> directory
+in the current working directory, and of two archives, <i>.zip</i>,
+and <i>.tar.gz</i>. A starkit will be created if <b>sdx</b> is present
+in the PATH. If additionally a file named <b>tclkit</b> is present in
+the current working directory a starpack will be created too, using
+this tclkit as the runtime.
+
+
+<li> Now follow the instructions in the Sourceforge site documentation
+		    for uploading the archives generated by the last
+		    step to
+		    <b>ftp://upload.sourceforge.net/incoming</b>, and
+		    follow the procedures for creating packages and
+		    releases at Sourceforge.
+</ol>
+
+<p>At last notify the relevant persons in other communities like
+Debian (See list of contacts) about the new release.
+</p>