* doc/tm.n: New file, documentation for Tcl Modules, based on the

	  TIP.

	* unix/mkLinks: Regenerated.
	* win/makefile.vc: Added tm.tcl to list of files to install.

1 files changed, 278 insertions, 0 deletions

diff --git a/doc/tm.n b/doc/tm.n
new file mode 100644
index 0000000..5675fa4
--- /dev/null
+++ b/doc/tm.n
@@ -0,0 +1,278 @@
+'\"
+'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: tm.n,v 1.1 2004/08/19 00:13:15 andreas_kupries Exp $
+'\" 
+.so man.macros
+.TH tm n 8.5 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tm \- Facilities for locating and loading of Tcl Modules
+.SH SYNOPSIS
+.nf
+\fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR...
+\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR...
+\fB::tcl::tm::path\fR \fBlist\fR
+\fB::tcl::tm::roots\fR \fIpath\fR...
+.fi
+.BE
+.SH DESCRIPTION
+This document describes the facilities for locating and loading Tcl
+Modules as specified by TIP #189.
+.SH "API"
+.TP
+\fB::tcl::tm::path\fR \fBadd\fR \fIpath\fR...\fR
+The paths are added at the head to the list of module paths, in order
+of appearance. This means that the last argument ends up as the new
+head of the list.
+.sp
+The command enforces the restriction that no path may be an ancestor
+directory of any other path on the list. If any of the new paths
+violates this restriction an error will be raised, before any of the
+paths have been added. In other words, if only one path argument
+violates the restriction then none will be added.
+.sp
+If a path is already present as is, no error will be raised and no
+action will be taken.
+.sp
+Paths are searched later in the order of their appearance in the
+list. As they are added to the front of the list they are searched in
+reverse order of addition. In other words, the paths added last are
+looked at first.
+.TP
+\fB::tcl::tm::path\fR \fBremove\fR \fIpath\fR...\fR
+Removes the paths from the list of module paths. The command silently
+ignores all paths which are not on the list.
+.TP
+\fB::tcl::tm::path\fR \fBlist\fR\fR
+Returns a list containing all registered module paths, in the order
+that they are searched for modules.
+.TP
+\fB::tcl::tm::roots\fR \fIpath\fR...\fR
+Similar to \fBpath add\fR, and layered on top of it. This command
+takes a list of paths, extends each with "\fItclX/site-tcl\fR", and
+"\fItclX/X.y\fR", for major version X of the tcl interpreter and minor
+version y less than or equal to the minor version of the interpreter,
+and adds the resulting set of paths to the list of paths to search.
+.sp
+This command is used internally by the system to set up the
+system-specific default paths.
+.sp
+The command has been exposed to allow a buildsystem to define
+additional root paths beyond those defined by the TIP..
+.SH "Module Definition"
+A Tcl Module is a Tcl Package contained in a single file, and no other
+files required by it. This file has to be \fBsource\fRable. In other
+words, a Tcl Module is always imported via:
+.PP
+.nf
+    source module_file
+.fi
+.PP
+The \fBload\fR command is not directly used. This restriction is not
+an actual limitation, as some may believe.
+Ever since 8.4 the Tcl \fBsource\fR command reads only until the first
+^Z character. This allows us to combine an arbitrary Tcl script with
+arbitrary binary data into one file, where the script processes the
+attached data in any it chooses to fully import and activate the
+package. Please read TIP #190 "Implementation Choices for Tcl Modules"
+for more explanations of the various choices which are possible.
+.PP
+The name of a module file has to match the regular expression
+.PP
+.nf
+    ([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\\.tm
+.fi
+.PP
+The first capturing parentheses provides the name of the package, the
+second clause its version. In addition to matching the pattern, the
+extracted version number must not raise an error when used in the
+command
+.PP
+.nf
+    package vcompare $version 0
+.fi
+.PP
+.SH "Finding Modules"
+The directory tree for storing Tcl modules is separate from other
+parts of the filesystem and independent of \fBauto_path\fR. The
+reasons for this are detailed in the TIP.
+.PP
+Tcl Modules are searched for in all directories listed in the result
+of the command \fB::tcl::tm::path list\fR
+(See also section \fBAPI\fR).
+This is called the \fIModule path\fR. Neither \fBauto_path\fR nor
+\fBtcl_pkgPath\fR are used.
+All directories on the module path have to obey one restriction:
+.IP
+For any two directories, neither is an ancestor directory of the
+other.
+.PP
+This is required to avoid ambiguities in package naming. If for
+example the two directories "\fIfoo/\fR" and "\fIfoo/cool\fR" were on
+the path a package named \fBcool::ice\fR could be found via the
+names \fBcool::ice\fR or \fBice\fR, the latter potentially
+obscuring a package named \fBice\fR, unqualified.
+.PP
+Before the search is started, the name of the requested package is
+translated into a partial path, using the following algorithm:
+.IP
+All occurrences of "\fB::\fR" in the package name are replaced by
+the appropriate directory separator character for the platform we are
+on. On Unix, for example, this is "\fB/\fR".
+.PP
+Example:
+.IP
+The requested package is \fBencoding::base64\fR. The generated
+partial path is "\fIencoding/base64\fR"
+.PP
+After this translation the package is looked for in all module paths,
+by combining them one-by-one, first to last with the partial path to
+form a complete search pattern. Note that the search algorithm rejects
+all files where the filename does not match the regular expression
+given in the section \fBModule Definition\fR. For the remaining
+files \fIprovide scripts\fR are generated and added to the package
+ifneeded database.
+.PP
+The algorithm falls back to the previous unknown handler when none of
+the found module files satisfy the request. If the request was
+satisfied the fall-back is ignored.
+.PP
+Note that packages in module form have \fIno\fR control over the
+\fIindex\fR and \fIprovide script\fRs entered into the package
+database for them.
+For a module file \fBMF\fR the \fIindex script\fR is always
+.PP
+.nf
+    package ifneeded PNAME PVERSION [list source MF]
+.fi
+.PP
+and the \fIprovide script\fR embedded in the above is
+.PP
+.nf
+    source MF
+.fi
+.PP
+Both package name \fBPNAME\fR and package version \fBPVERSION\fR are
+extracted from the filename \fBMF\fR according to the definition
+below:
+.PP
+.nf
+    MF = /module_path/PNAME'-PVERSION.tm
+.fi
+.PP
+Where \fBPNAME'\fR is the partial path of the module as defined in
+section \fBFinding Modules\fR, and translated into PNAME by
+changing all directory separators to "\fB::\fR",
+and \fBmodule_path\fR is the path (from the list of paths to search)
+that we found the module file under.
+.PP
+Note also that we are here creating a connection between package names
+and paths. Tcl is case-sensitive when it comes to comparing package
+names, but there are filesystems which are not, like NTFS. Luckily
+these filesystems do store the case of the name, despite not using the
+information when comparing.
+.PP
+Given the above we allow the names for packages in Tcl modules to have
+mixed-case, but also require that there are no collisions when
+comparing names in a case-insensitive manner. In other words, if a
+package \fBFoo\fR is deployed in the form of a Tcl Module,
+packages like \fBfoo\fR, \fBfOo\fR, etc. are not allowed
+anymore.
+.SH "Default Paths"
+The default list of paths on the module path is computed by a tclsh as
+follows, where \fBX\fR is the major version of the Tcl interpreter and
+\fBy\fR is less than or equal to the minor version of the Tcl
+interpreter.
+.TP
+System specific paths
+.IP
+\fBfile normalize [info library]/../tclX/X.y\fR
+.sp
+.RS
+.RS
+In other words, the interpreter will look into a directory specified
+by its major version and whose minor versions are less than or equal
+to the minor version of the interpreter.
+.sp
+For example for Tcl 8.4 the paths searched are
+.sp
+.nf
+    \fB[info library]/../tcl8/8.4\fR
+    \fB[info library]/../tcl8/8.3\fR
+    \fB[info library]/../tcl8/8.2\fR
+    \fB[info library]/../tcl8/8.1\fR
+    \fB[info library]/../tcl8/8.0\fR
+.fi
+.sp
+This definition assumes that a package defined for Tcl \fBX\fR.\fBy\fR
+can also be used by all interpreters which have the same major number
+\fBX\fR and a minor number greater than \fBy\fR.
+.RE
+.RE
+.IP
+\fBfile normalize EXEC/tclX/X.y\fR
+.sp
+.RS
+.RS
+Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
+or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
+.sp
+This sets of paths is handled equivalently to the set coming before,
+except that it is anchored in \fBEXEC_PREFIX\fR.
+For a build with \fBPREFIX\fR = \fBEXEC_PREFIX\fR the two sets are
+identical.
+.RE
+.RE
+.sp
+.TP
+Site specific paths
+.IP
+\fBfile normalize [info library]/../tclX/site-tcl\fR
+.sp
+.TP
+User specific paths
+.IP
+\fB$::env(TCLX.y_TM_PATH)\fR
+.sp
+.RS
+.RS
+A list of paths, separated by either \fB:\fR (Unix) or \fB;\fR
+(Windows). This is user and site specific as this environment variable
+can be set not only by the user's profile, but by system configuration
+scripts as well.
+.sp
+These paths are seen and therefore shared by all Tcl shells in the
+\fB$::env(PATH)\fR of the user.
+.sp
+Note that \fBX\fR and \fBy\fR follow the general rules set out
+above. In other words, Tcl 8.4, for example, will look at these 5
+environment variables
+.sp
+.nf
+    \fB$::env(TCL8.4_TM_PATH)\fR
+    \fB$::env(TCL8.3_TM_PATH)\fR
+    \fB$::env(TCL8.2_TM_PATH)\fR
+    \fB$::env(TCL8.1_TM_PATH)\fR
+    \fB$::env(TCL8.0_TM_PATH)\fR
+.fi
+.RE
+.RE
+.PP
+All the default paths are added to the module path, even those paths
+which do not exist. Non-existent paths are filtered out during actual
+searches. This enables a user to create one of the paths searched when
+needed and all running applications will automatically pick up any
+modules placed in them.
+.PP
+The paths are added in the order as they are listed above, and for
+lists of paths defined by an environment variable in the order they
+are found in the variable.
+.SH "SEE ALSO"
+package(n)
+.SH "KEYWORDS"
+modules, package