Updated to reflect newer implementation.

1 files changed, 41 insertions, 24 deletions

diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index e4bcf78..3c51284 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.4 1998/10/30 23:02:02 welch Exp $
+'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.5 1998/11/12 05:52:46 welch Exp $
 '\" 
 .so man.macros
 .TH pkg_mkIndex n 8.0 Tcl "Tcl Built-In Commands"
@@ -15,7 +15,7 @@ pkg_mkIndex \- Build an index for automatic loading of packages
 .SH SYNOPSIS
 .nf
 .VS 8.0.3
-\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
+\fBpkg_mkIndex ?\fI-direct\fR? ?\fI-load pkgPat\fR? ?\fI-verbose\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
 .VE
 .fi
 .BE
@@ -43,22 +43,40 @@ The \fIdir\fR argument gives the name of a directory and each
 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
+The optional switches are:
+.TP 15
+\fB\-direct\fR
+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.
+.TP 15
+\fB\-load \fIpkgPat\fR
+The index process will pre-load any packages that exist in the
+current interpreter and match \fIpkgPat\fP into the slave interpreter used to
+generate the index.  The pattern match uses string match rules.
+See COMPLEX CASES below.
+.TP 15
+\fB\-verbose\fR
+Generate output during the indexing process.  Output is via
+the \fBtclLog\fP procedure, which by default prints to stderr.
+.TP 15
+\fB\-\-\fR
+End of the flags, in case \fIdir\fP begins with a dash.
 .VE
-.RS
 .LP
+.RS
 \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.
-It does this by loading each file and seeing what packages
+It does this by loading each file into a slave
+interpreter 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).
 If you have a package split among scripts and binary files, 
 or if you have dependencies among files,
-you may have to adjust the order in which \fBpkg_mkIndex\fR processes
+you may have to use the \fB-load\fP option
+or adjust the order in which \fBpkg_mkIndex\fR processes
 the files.  See COMPLEX CASES below.
 .RE
 .IP [3]
@@ -74,8 +92,7 @@ the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR
 file.  As long as the package is installed as a subdirectory of a
 directory in \fB$tcl_pkgPath\fR it will automatically be found during
 \fBpackage require\fR commands.
-.RS
-.LP
+.IP
 If you install the package anywhere else, then you must ensure that
 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.
@@ -88,7 +105,6 @@ 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,
 Tcl initializes \fBauto_path\fR from it during application startup.
-.RE
 .IP [4]
 Once the above steps have been taken, all you need to do to use a
 package is to invoke \fBpackage require\fR.
@@ -168,8 +184,6 @@ Most complex cases of dependencies among scripts
 and binary files, and packages being split among scripts and
 binary files are handled OK.  However, you may have to adjust
 the order in which files are processed by \fBpkg_mkIndex\fR.
-The only case that is not supported is a package that is
-provided by more than one binary file.
 These issues are described in detail below.
 .PP
 If each script or file contains one package, and packages
@@ -190,12 +204,16 @@ also bad coding style.
 .PP
 If binary files have dependencies on other packages, things
 can become tricky because it is not possible to stub out
-the C-level \fBTcl_PkgRequire\fP API.
+C-level API's such as \fBTcl_PkgRequire\fP API
+when loading a binary file.
 For example, suppose the BLT package requires Tk, and expresses
 this with a call to \fBTcl_PkgRequire\fP in its \fBBlt_Init\fP routine.
-To support this, you must run \fBpkg_mkIndex\fR in a shell that
-has Tk loaded.  \fBpkg_mkIndex\fR will load any packages listed by
-\fBinfo loaded\fP into the interpreter used to process files.
+To support this, you must run \fBpkg_mkIndex\fR in an interpreter that
+has Tk loaded.  You can achieve this with the
+\fB-load \fIpkgPat\fR option.  If you specify this option,
+\fBpkg_mkIndex\fR will load any packages listed by
+\fBinfo loaded\fP and that match \fIpkgPat\fP
+into the interpreter used to process files.
 In most cases this will satisfy the \fBTcl_PkgRequire\fP calls
 made by binary files.
 .PP
@@ -204,17 +222,16 @@ you should specify the one that has dependencies last.
 This way the one without dependencies will get loaded and indexed,
 and then the package it provides
 will be available when the second file is processed.
-.PP
-You cannot have the same package provided by two different binary
-files.  Well, you can, but they cannot be indexed by \fBpkg_mkIndex\fR
-and it seems like a poor design choice anyway.  The problem is that
-once the package is provided by the first binary file, then that
-masks the provide made by the other binary file.  If you
-absolutely must do this, you'll have to run \fBpkg_mkIndex\fR on
-each different file, save the resulting pkgIndex.tcl files,
-and merge the results.
+You may also need to load the first package into the
+temporary interpreter used to create the index by using
+the \fB-load\fP flag;
+it won't hurt to specify package patterns that are not yet loaded.
 .PP
 If you have a package that is split across scripts and a binary file,
+then you should avoid the \fB-load\fP flag. The problem is that
+if you load a package before computing the index it masks any
+other files that provide part of the same package.
+If you must use \fB-load\fP,
 then you must specify the scripts first; otherwise the package loaded from
 the binary file may mask the package defined by the scripts.