upgraded to the new interfaces: -direct, -nopkgrequire

1 files changed, 66 insertions, 7 deletions

diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index 7c02741..5ac1a9d 100644
--- a/doc/pkgMkIndex.n
+++ b/doc/pkgMkIndex.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: pkgMkIndex.n,v 1.2 1998/09/14 18:39:54 stanton Exp $
+'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.3 1998/10/17 00:16:38 escoffon Exp $
 '\" 
 .so man.macros
 .TH pkg_mkIndex n 7.6 Tcl "Tcl Built-In Commands"
@@ -14,7 +14,9 @@
 pkg_mkIndex \- Build an index for automatic loading of packages
 .SH SYNOPSIS
 .nf
-\fBpkg_mkIndex \fIdir\fR \fIpattern \fR?\fIpattern pattern ...\fR?
+.VS 8.0.3
+\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-verbose\fR? ?\fI-nopkgrequire\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
+.VE
 .fi
 .BE
 
@@ -39,6 +41,12 @@ Create the index by invoking \fBpkg_mkIndex\fR.
 The \fIdir\fR argument gives the name of a directory and each
 \fIpattern\fR argument is a \fBglob\fR-style pattern that selects
 script or binary files in \fIdir\fR.
+.VS 8.0.3
+The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR.
+If the optional \fI-direct\fR argument is given, the generated index
+will manage to load the package immediately upon \fBpackage require\fR
+instead of delaying loading until actual use of one of the commands.
+.VE
 \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR
 with package information about all the files given by the \fIpattern\fR
 arguments.
@@ -46,7 +54,6 @@ It does this by loading each file and seeing what packages
 and new commands appear (this is why it is essential to have
 \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls
 in the files, as described above).
-.VS "" br
 .IP [3]
 Install the package as a subdirectory of one of the directories given by
 the \fBtcl_pkgPath\fR variable.  If \fB$tcl_pkgPath\fR contains more
@@ -63,14 +70,13 @@ directory in \fB$tcl_pkgPath\fR it will automatically be found during
 .RS
 .LP
 If you install the package anywhere else, then you must ensure that
-the directory contaiingn the package is in the \fBauto_path\fR global variable
+the directory containing the package is in the \fBauto_path\fR global variable
 or an immediate subdirectory of one of the directories in \fBauto_path\fR.
 \fBAuto_path\fR contains a list of directories that are searched
 by both the auto-loader and the package loader; by default it
 includes \fB$tcl_pkgPath\fR.
 The package loader also checks all of the subdirectories of the
 directories in \fBauto_path\fR.
-.VE
 You can add a directory to \fBauto_path\fR explicitly in your
 application, or you can add the directory to your \fBTCLLIBPATH\fR
 environment variable:  if this environment variable is present,
@@ -124,12 +130,65 @@ commands for each version of each available package;  these commands
 invoke \fBpackage provide\fR commands to announce the
 availability of the package, and they setup auto-loader
 information to load the files of the package.
-A given file of a given version of a given package isn't
+.VS 8.0.3
+Unless the \fI-direct\fR flag was provided when the \fBpkgIndex.tcl\fR
+was generated,
+.VE
+a given file of a given version of a given package isn't
 actually loaded until the first time one of its commands
 is invoked.
-Thus, after invoking \fBpackage require\fR you won't see
+Thus, after invoking \fBpackage require\fR you
+.VS 8.0.3
+may
+.VE
+not see
 the package's commands in the interpreter, but you will be able
 to invoke the commands and they will be auto-loaded.
 
+.VS 8.0.3
+.SH "DIRECT LOADING"
+.PP
+Some packages, for instance packages which use namespaces and export
+commands or those which require special initialization, might select
+that their package files be loaded immediately upon \fBpackage require\fR
+instead of delaying the actual loading to the first use of one of the
+package's command. This mode is enabled when generating the package
+index by specifying the \fI-direct\fR argument.
+.VE
+
+.VS 8.0.3
+.SH "INDEXING OF DEPENDENT PACKAGES"
+.PP
+Earlier versions of \fBpkg_mkIndex\fR were unable to handle some packages
+that did a \fIpackage require\fR for a second package also to be indexed,
+and then proceeded to execute
+code from that package (for example in a \fInamespace eval\fR construct).
+This happended because the autoloading mechanism did not have access to
+the index file being built, thus causing \fIpackage require\fR to fail.
+\fBPkg_mkIndex\fR circumvented this problem by redefining
+\fIpackage require\fR to be a null operation, which in turn then caused the
+indexing to fail when procedures from the second package were being called
+in the first.
+.LP
+\fBPkg_mkIndex\fR now implements \fIpackage require\fR. Additionally, it
+does the indexing in multiple passes, until either
+all files have been indexed, or until the current pass could index no more
+files. For each pass, files that were indexed are added to a partial
+\fBpkgIndex.tcl\fR, which is reloaded at the start of each pass. In the case
+described above, for example, \fBpkg_mkIndex\fR will do two passes. During the
+first pass, the first package will not index, but the second will. Then,
+during the second pass, the first package will be able to
+\fIpackage require\fR the second, and therefore will also be indexed.
+If the \fI-verbose\fR optional argument is givem, \fBpkg_mkIndex\fR will
+display its progress.
+.LP
+Under some conditions, \fBpkg_mkIndex\fR may not be able to index any file
+during a pass; for example, if package \fIa\fR requires package \fIb\fR,
+and package \fIb\fR requires package \fIa\fR, neither one can be indexed.
+In these situations, you can give the \fI-nopkgrequire\fR optional argument;
+this will cause \fBpkg_mkIndex\fR to revert to the old behaviour, where
+\fIpackage require\fR is a null operation.
+.VE
+
 .SH KEYWORDS
 auto-load, index, package, version