Add *very* basic test suite for modules, and tighten up the doc style

1 files changed, 90 insertions, 109 deletions

diff --git a/doc/tm.n b/doc/tm.n
index 5675fa4..e9455a3 100644
--- a/doc/tm.n
+++ b/doc/tm.n
@@ -4,7 +4,7 @@
 '\" 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 $
+'\" RCS: @(#) $Id: tm.n,v 1.2 2004/10/22 22:08:25 dkf Exp $
 '\" 
 .so man.macros
 .TH tm n 8.5 Tcl "Tcl Built-In Commands"
@@ -20,25 +20,26 @@ tm \- Facilities for locating and loading of Tcl Modules
 \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"
+Modules. The following commands are supported:
+.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
+.PP
 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
+.PP
 If a path is already present as is, no error will be raised and no
 action will be taken.
-.sp
+.PP
 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
@@ -54,24 +55,24 @@ 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
+takes a list of paths, extends each with "\fBtcl\fIX\fB/site-tcl\fR",
+and "\fBtcl\fIX\fB/\fIX\fB.\fIy\fR", for major version \fIX\fR of the
+Tcl interpreter and minor version \fIy\fR 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.
+.PP
 This command is used internally by the system to set up the
 system-specific default paths.
-.sp
+.PP
 The command has been exposed to allow a buildsystem to define
 additional root paths beyond those defined by the TIP..
-.SH "Module Definition"
+.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
+.CS
+source module_file
+.CE
 .PP
 The \fBload\fR command is not directly used. This restriction is not
 an actual limitation, as some may believe.
@@ -82,22 +83,20 @@ 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
+The name of a module file has to match the regular expression:
+.CS
+([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\\.tm
+.CE
 .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
+command:
+.CS
+package vcompare $version 0
+.CE
 .PP
-.SH "Finding Modules"
+.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.
@@ -145,25 +144,21 @@ satisfied the fall-back is ignored.
 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
+For a module file \fBMF\fR the \fIindex script\fR is always:
+.CS
+package ifneeded PNAME PVERSION [list source MF]
+.CE
+and the \fIprovide script\fR embedded in the above is:
+.CS
+source MF
+.CE
 .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
+.CS
+MF = /module_path/PNAME'-PVERSION.tm
+.CE
 .PP
 Where \fBPNAME'\fR is the partial path of the module as defined in
 section \fBFinding Modules\fR, and translated into PNAME by
@@ -183,96 +178,82 @@ 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
+.SH "DEFAULT PATHS"
+The default list of paths on the module path is computed by a
+\fBtclsh\fR as follows, where \fIX\fR is the major version of the Tcl
+interpreter and \fIy\fR is less than or equal to the minor version of
+the Tcl interpreter.
+.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 below, and for
+lists of paths defined by an environment variable in the order they
+are found in the variable.
+.SS "SYSTEM SPECIFIC PATHS"
 .IP
-\fBfile normalize [info library]/../tclX/X.y\fR
-.sp
-.RS
-.RS
+\fBfile normalize [info library]/../tcl\fIX\fB/\fIX\fB.\fIy\fR
 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
+.RS
+.PP
+For example for Tcl 8.4 the paths searched are:
+.CS
+\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
+.CE
+.PP
+This definition assumes that a package defined for Tcl \fIX\fB.\fIy\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
+\fIX\fR and a minor number greater than \fIy\fR.
 .RE
 .IP
-\fBfile normalize EXEC/tclX/X.y\fR
-.sp
-.RS
-.RS
+\fBfile normalize EXEC/tcl\fIX\fB/\fIX\fB.\fIy\fR
 Where \fBEXEC\fR is \fBfile normalize [info nameofexecutable]/../lib\fR
 or \fBfile normalize [::tcl::pkgconfig get libdir,runtime]\fR
-.sp
+.RS
+.PP
 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
+.SS "SITE SPECIFIC PATHS"
 .IP
-\fBfile normalize [info library]/../tclX/site-tcl\fR
-.sp
-.TP
-User specific paths
+\fBfile normalize [info library]/../tcl\fIX\fB/site-tcl\fR
+.SS "USER SPECIFIC PATHS"
 .IP
-\fB$::env(TCLX.y_TM_PATH)\fR
-.sp
-.RS
-.RS
+\fB$::env(TCL\fIX\fB.\fIy\fB_TM_PATH)\fR
 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
+.RS
+.PP
 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
+.PP
+Note that \fIX\fR and \fIy\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
+environment variables:
+.CS
+\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
+.CE
 .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)
+package(n), Tcl Improvement Proposal #189
+
 .SH "KEYWORDS"
 modules, package