Yet more doc update backporting

1 files changed, 137 insertions, 92 deletions

diff --git a/doc/namespace.n b/doc/namespace.n
index c79ce08..e93a704 100644
--- a/doc/namespace.n
+++ b/doc/namespace.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: namespace.n,v 1.9 2003/01/21 20:06:11 jenglish Exp $
+'\" RCS: @(#) $Id: namespace.n,v 1.9.2.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH namespace n 8.0 Tcl "Tcl Built-In Commands"
@@ -24,8 +24,8 @@ The \fBnamespace\fR command lets you create, access, and destroy
 separate contexts for commands and variables.
 See the section \fBWHAT IS A NAMESPACE?\fR below
 for a brief overview of namespaces.
-The legal \fIoption\fR's are listed below.
-Note that you can abbreviate the \fIoption\fR's.
+The legal values of \fIoption\fR are listed below.
+Note that you can abbreviate the \fIoption\fRs.
 .TP
 \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
 Returns a list of all child namespaces that belong to the
@@ -33,14 +33,14 @@ namespace \fInamespace\fR.
 If \fInamespace\fR is not specified,
 then the children are returned for the current namespace.
 This command returns fully-qualified names,
-which start with \fB::\fR.
+which start with a double colon (\fB::\fR).
 If the optional \fIpattern\fR is given,
 then this command returns only the names that match the glob-style pattern.
 The actual pattern used is determined as follows:
-a pattern that starts with \fB::\fR is used directly,
+a pattern that starts with double colon (\fB::\fR) is used directly,
 otherwise the namespace \fInamespace\fR
 (or the fully-qualified name of the current namespace)
-is prepended onto the the pattern.
+is prepended onto the pattern.
 .TP
 \fBnamespace code \fIscript\fR
 Captures the current namespace context for later execution
@@ -66,7 +66,7 @@ extensions like Tk normally execute callback scripts
 in the global namespace.
 A scoped command captures a command together with its namespace context
 in a way that allows it to be executed properly later.
-See the section \fBSCOPED VALUES\fR for some examples
+See the section \fBSCOPED SCRIPTS\fR for some examples
 of how this is used to create callback scripts.
 .TP
 \fBnamespace current\fR
@@ -129,7 +129,7 @@ this command returns the namespace's current export list.
 Removes previously imported commands from a namespace.
 Each \fIpattern\fR is a simple or qualified name such as
 \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR.
-Qualified names contain \fB::\fRs and qualify a name
+Qualified names contain double colons (\fB::\fR) and qualify a name
 with the name of one or more namespaces.
 Each \fIqualified pattern\fR is qualified with the name of an
 exporting namespace 
@@ -211,7 +211,7 @@ the fully-qualified name of the current namespace's parent is returned.
 .TP
 \fBnamespace qualifiers\fR \fIstring\fR
 Returns any leading namespace qualifiers for \fIstring\fR.
-Qualifiers are namespace names separated by \fB::\fRs.
+Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
 this command returns \fB::foo::bar\fR,
 and for \fB::\fR it returns an empty string.
@@ -222,7 +222,7 @@ the names of currently defined namespaces.
 .TP
 \fBnamespace tail\fR \fIstring\fR
 Returns the simple name at the end of a qualified string.
-Qualifiers are namespace names separated by \fB::\fRs.
+Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
 this command returns \fBx\fR,
 and for \fB::\fR it returns an empty string.
@@ -244,7 +244,6 @@ fully-qualified name of the variable.
 If no flag is given, \fIname\fR is treated as a command name.
 See the section \fBNAME RESOLUTION\fR below for an explanation of
 the rules regarding name resolution.
-
 .SH "WHAT IS A NAMESPACE?"
 .PP
 A namespace is a collection of commands and variables.
@@ -256,15 +255,15 @@ The global namespace holds all global variables and commands.
 The \fBnamespace eval\fR command lets you create new namespaces.
 For example,
 .CS
-\fBnamespace eval Counter {
-    namespace export bump
-    variable num 0
+\fBnamespace eval\fR Counter {
+   \fBnamespace export\fR bump
+   variable num 0
 
-    proc bump {} {
-        variable num
-        incr num
-    }
-}\fR
+   proc bump {} {
+      variable num
+      incr num
+   }
+}
 .CE
 creates a new namespace containing the variable \fBnum\fR and
 the procedure \fBbump\fR.
@@ -286,21 +285,21 @@ namespace over time using a series of \fBnamespace eval\fR commands.
 For example, the following series of commands has the same effect
 as the namespace definition shown above:
 .CS
-\fBnamespace eval Counter {
-    variable num 0
-    proc bump {} {
-        variable num
-        return [incr num]
-    }
+\fBnamespace eval\fR Counter {
+   variable num 0
+   proc bump {} {
+      variable num
+      return [incr num]
+   }
 }
-namespace eval Counter {
-    proc test {args} {
-        return $args
-    }
+\fBnamespace eval\fR Counter {
+   proc test {args} {
+      return $args
+   }
 }
-namespace eval Counter {
+\fBnamespace eval\fR Counter {
     rename test ""
-}\fR
+}
 .CE
 Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
 and later removed via the \fBrename\fR command.
@@ -309,7 +308,6 @@ Namespaces can have other namespaces within them,
 so they nest hierarchically.
 A nested namespace is encapsulated inside its parent namespace
 and can not interfere with other namespaces.
-
 .SH "QUALIFIED NAMES"
 .PP
 Each namespace has a textual name such as
@@ -325,8 +323,8 @@ The topmost or global namespace has the name ``'' (i.e., an empty string),
 although \fB::\fR is a synonym.
 As an example, the name \fB::safe::interp::create\fR
 refers to the command \fBcreate\fR in the namespace \fBinterp\fR
-that is a child of of namespace \fB::safe\fR,
-which in turn is a child of the global namespace \fB::\fR.
+that is a child of namespace \fB::safe\fR,
+which in turn is a child of the global namespace, \fB::\fR.
 .PP
 If you want to access commands and variables from another namespace,
 you must use some extra syntax.
@@ -334,12 +332,12 @@ Names must be qualified by the namespace that contains them.
 From the global namespace,
 we might access the \fBCounter\fR procedures like this:
 .CS
-\fBCounter::bump 5
-Counter::Reset\fR
+Counter::bump 5
+Counter::Reset
 .CE
 We could access the current count like this:
 .CS
-\fBputs "count = $Counter::num"\fR
+puts "count = $Counter::num"
 .CE
 When one namespace contains another, you may need more than one
 qualifier to reach its elements.
@@ -347,18 +345,18 @@ If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
 you could invoke its \fBbump\fR procedure
 from the global namespace like this:
 .CS
-\fBFoo::Counter::bump 3\fR
+Foo::Counter::bump 3
 .CE
 .PP
 You can also use qualified names when you create and rename commands.
 For example, you could add a procedure to the \fBFoo\fR
 namespace like this:
 .CS
-\fBproc Foo::Test {args} {return $args}\fR
+proc Foo::Test {args} {return $args}
 .CE
 And you could move the same procedure to another namespace like this:
 .CS
-\fBrename Foo::Test Bar::Test\fR
+rename Foo::Test Bar::Test
 .CE
 .PP
 There are a few remaining points about qualified names
@@ -366,12 +364,11 @@ that we should cover.
 Namespaces have nonempty names except for the global namespace.
 \fB::\fR is disallowed in simple command, variable, and namespace names
 except as a namespace separator.
-Extra \fB:\fRs in a qualified name are ignored;
-that is, two or more \fB:\fRs are treated as a namespace separator.
+Extra colons in any separator part of a qualified name are ignored;
+i.e. two or more colons are treated as a namespace separator.
 A trailing \fB::\fR in a qualified variable or command name
 refers to the variable or command named {}.
 However, a trailing \fB::\fR in a qualified namespace name is ignored.
-
 .SH "NAME RESOLUTION"
 .PP
 In general, all Tcl commands that take variable and command names
@@ -392,10 +389,10 @@ by looking in only the current namespace.
 .PP
 In the following example,
 .CS
-\fBset traceLevel 0
-namespace eval Debug {
-    printTrace $traceLevel
-}\fR
+set traceLevel 0
+\fBnamespace eval\fR Debug {
+   printTrace $traceLevel
+}
 .CE
 Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
 and then in the global namespace.
@@ -404,14 +401,14 @@ If a variable or command name is not found in either context,
 the name is undefined.
 To make this point absolutely clear, consider the following example:
 .CS
-\fBset traceLevel 0
-namespace eval Foo {
-    variable traceLevel 3
+set traceLevel 0
+\fBnamespace eval\fR Foo {
+   variable traceLevel 3
 
-    namespace eval Debug {
-        printTrace $traceLevel
-    }
-}\fR
+   \fBnamespace eval\fR Debug {
+      printTrace $traceLevel
+   }
+}
 .CE
 Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
 Since it is not found there, Tcl then looks for it 
@@ -423,12 +420,12 @@ You can use the \fBnamespace which\fR command to clear up any question
 about name resolution.
 For example, the command:
 .CS
-\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel}
 .CE
 returns \fB::traceLevel\fR.
 On the other hand, the command,
 .CS
-\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel}
 .CE
 returns \fB::Foo::traceLevel\fR.
 .PP
@@ -439,7 +436,7 @@ Namespace names are always resolved in the current namespace.
 This means, for example,
 that a \fBnamespace eval\fR command that creates a new namespace
 always creates a child of the current namespace
-unless the new namespace name begins with a \fB::\fR.
+unless the new namespace name begins with \fB::\fR.
 .PP
 Tcl has no access control to limit what variables, commands,
 or namespaces you can reference.
@@ -459,7 +456,6 @@ to variables in the global namespace.
 It is not necessary to use a \fBvariable\fR command
 if you always refer to the namespace variable using an
 appropriate qualified name.
-
 .SH "IMPORTING COMMANDS"
 .PP
 Namespaces are often used to represent libraries.
@@ -469,21 +465,21 @@ For example, suppose that all of the commands in a package
 like BLT are contained in a namespace called \fBBlt\fR.
 Then you might access these commands like this:
 .CS
-\fBBlt::graph .g \-background red
-Blt::table . .g 0,0\fR
+Blt::graph .g \-background red
+Blt::table . .g 0,0
 .CE
 If you use the \fBgraph\fR and \fBtable\fR commands frequently,
 you may want to access them without the \fBBlt::\fR prefix.
 You can do this by importing the commands into the current namespace,
 like this:
 .CS
-\fBnamespace import Blt::*\fR
+\fBnamespace import\fR Blt::*
 .CE
 This adds all exported commands from the \fBBlt\fR namespace
 into the current namespace context, so you can write code like this:
 .CS
-\fBgraph .g \-background red
-table . .g 0,0\fR
+graph .g \-background red
+table . .g 0,0
 .CE
 The \fBnamespace import\fR command only imports commands
 from a namespace that that namespace exported
@@ -494,7 +490,7 @@ a bad idea since you don't know what you will get.
 It is better to import just the specific commands you need.
 For example, the command
 .CS
-\fBnamespace import Blt::graph Blt::table\fR
+\fBnamespace import\fR Blt::graph Blt::table
 .CE
 imports only the \fBgraph\fR and \fBtable\fR commands into the
 current context.
@@ -507,12 +503,12 @@ reissue the \fBnamespace import\fR command to pick up new commands
 that have appeared in a namespace.  In that case, you can use the
 \fB\-force\fR option, and existing commands will be silently overwritten:
 .CS
-\fBnamespace import \-force Blt::graph Blt::table\fR
+\fBnamespace import\fR \-force Blt::graph Blt::table
 .CE
 If for some reason, you want to stop using the imported commands,
-you can remove them with an \fBnamespace forget\fR command, like this:
+you can remove them with a \fBnamespace forget\fR command, like this:
 .CS
-\fBnamespace forget Blt::*\fR
+\fBnamespace forget\fR Blt::*
 .CE
 This searches the current namespace for any commands imported from \fBBlt\fR.
 If it finds any, it removes them.  Otherwise, it does nothing.
@@ -521,42 +517,41 @@ prefix.
 .PP
 When you delete a command from the exporting namespace like this:
 .CS
-\fBrename Blt::graph ""\fR
+rename Blt::graph ""
 .CE
 the command is automatically removed from all namespaces that import it.
-
 .SH "EXPORTING COMMANDS"
 You can export commands from a namespace like this:
 .CS
-\fBnamespace eval Counter {
-    namespace export bump reset
-    variable Num 0
-    variable Max 100
+\fBnamespace eval\fR Counter {
+   \fBnamespace export\fR bump reset
+   variable Num 0
+   variable Max 100
 
-    proc bump {{by 1}} {
-        variable Num
-        incr Num $by
-        Check
-        return $Num
-    }
-    proc reset {} {
-        variable Num
-        set Num 0
-    }
-    proc Check {} {
-        variable Num
-        variable Max
-        if {$Num > $Max} {
-            error "too high!"
-        }
-    }
-}\fR
+   proc bump {{by 1}} {
+      variable Num
+      incr Num $by
+      Check
+      return $Num
+   }
+   proc reset {} {
+      variable Num
+      set Num 0
+   }
+   proc Check {} {
+      variable Num
+      variable Max
+      if {$Num > $Max} {
+         error "too high!"
+      }
+   }
+}
 .CE
 The procedures \fBbump\fR and \fBreset\fR are exported,
 so they are included when you import from the \fBCounter\fR namespace,
 like this:
 .CS
-\fBnamespace import Counter::*\fR
+\fBnamespace import\fR Counter::*
 .CE
 However, the \fBCheck\fR procedure is not exported,
 so it is ignored by the import operation.
@@ -567,6 +562,56 @@ The \fBnamespace export\fR command specifies what commands
 may be imported by other namespaces.
 If a \fBnamespace import\fR command specifies a command
 that is not exported, the command is not imported.
+.SH "SCOPED SCRIPTS"
+The \fBnamespace code\fR command is the means by which a script may be
+packaged for evaluation in a namespace other than the one in which it
+was created.  It is used most often to create event handlers, Tk bindings,
+and traces for evaluation in the global context.  For instance, the following
+code indicates how to direct a variable trace callback into the current
+namespace:
+.CS
+\fBnamespace eval\fR a {
+   variable b
+   proc theTraceCallback { n1 n2 op } {
+      upvar 1 $n1 var
+      puts "the value of $n1 has changed to $var"
+      return
+   }
+   trace variable b w [\fBnamespace code\fR theTraceCallback]
+}
+set a::b c
+.CE
+When executed, it prints the message:
+.CS
+the value of a::b has changed to c
+.CE
+.SH EXAMPLES
+Create a namespace containing a variable and an exported command:
+.CS
+\fBnamespace eval\fR foo {
+   variable bar 0
+   proc grill {} {
+      variable bar
+      puts "called [incr bar] times"
+   }
+   \fBnamespace export\fR grill
+}
+.CE
+.PP
+Call the command defined in the previous example in various ways.
+.CS
+# Direct call
+foo::grill
+
+# Import into current namespace, then call local alias
+namespace import foo::grill
+grill
+.CE
+.PP
+Look up where the command imported in the previous example came from:
+.CS
+puts "grill came from [\fBnamespace which\fR grill]"
+.CE
 
 .SH "SEE ALSO"
 variable(n)