Added example and cleaned up a few bits of documentation.

1 files changed, 24 insertions, 9 deletions

diff --git a/doc/unload.n b/doc/unload.n
index 916c565..b0aab2e 100644
--- a/doc/unload.n
+++ b/doc/unload.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: unload.n,v 1.3 2004/03/17 18:14:12 das Exp $
+'\" RCS: @(#) $Id: unload.n,v 1.4 2004/05/30 14:25:51 dkf Exp $
 '\" 
 .so man.macros
 .TH unload n 8.5 Tcl "Tcl Built-In Commands"
@@ -27,11 +27,13 @@ with \fBload\fR from the application's address space.  \fIfileName\fR
 is the name of the file containing the library file to be unload;  it
 must be the same as the filename provided to \fBload\fR for
 loading the library.
-\fIpackageName\fR is the name of the package, and is used to
-compute the name of the unload procedure.
-\fIinterp\fR is the path name of the interpreter from which to unload
-the package (see the \fBinterp\fR manual entry for details);
-if \fIinterp\fR is omitted, it defaults to the
+The \fIpackageName\fR argument is the name of the package (as
+determined by or passed to \fBload\fR), and is used to
+compute the name of the unload procedure; if not supplied, it is
+computed from \fIfileName\fR in the same manner as \fBload\fR.
+The \fIinterp\fR argument is the path name of the interpreter from
+which to unload the package (see the \fBinterp\fR manual entry for
+details); if \fIinterp\fR is omitted, it defaults to the
 interpreter in which the \fBunload\fR command was invoked.
 .LP
 If the initial arguments to \fBunload\fR start with \fB\-\fR then
@@ -120,7 +122,6 @@ alphabetic and underline characters as the module name.
 For example, the command \fBunload libxyz4.2.so\fR uses the module
 name \fBxyz\fR and the command \fBunload bin/last.so {}\fR uses the
 module name \fBlast\fR.
-
 .SH "PORTABILITY ISSUES"
 .TP
 \fBUnix\fR\0\0\0\0\0
@@ -128,7 +129,6 @@ module name \fBlast\fR.
 Not all unix operating systems support library unloading. Under such
 an operating system \fBunload\fR returns an error (unless -nocomplain has
 been specified).
-
 .SH BUGS
 .PP
 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
@@ -139,9 +139,24 @@ silently detached by the operating system (and as a result Tcl thinks the
 library is still loaded), it may be dangerous to use
 \fBunload\fR on such a library (as the library will be completely detached
 from the application while some interpreters will continue to use it).
+.SH EXAMPLE
+If an unloadable module in the file \fBfoobar.dll\fR had been loaded
+using the \fBload\fR command like this (on Windows):
+.CS
+load c:/some/dir/foobar.dll
+.CE
+then it would be unloaded like this:
+.CS
+\fBunload\fR c:/some/dir/foobar.dll
+.CE
+.PP
+This allows a C code module to be installed temporarily into a
+long-running Tcl program and then removed again (either because it is
+no longer needed or because it is being updated with a new version)
+without having to shut down the overall Tcl process.
 
 .SH "SEE ALSO"
-info sharedlibextension, load, safe(n)
+info sharedlibextension, load(n), safe(n)
 
 .SH KEYWORDS
 binary code, unloading, safe interpreter, shared library