* docs/global.n: added details for qualified variable names

	[Bug 959831]

2 files changed, 26 insertions, 10 deletions

diff --git a/ChangeLog b/ChangeLog
index 63f91d1..5f07ecd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2004-05-25  Miguel Sofer <msofer@users.sf.net>
 
+	* docs/global.n: added details for qualified variable names 
+	[Bug 959831]
+
+2004-05-25  Miguel Sofer <msofer@users.sf.net>
+
 	* generic/tclNamesp.c (Tcl_FindNamespaceVar):
 	* tests/namespace.test (namespace-17.10-12): reverted commit of
 	2004-05-23 and removed the tests, as it interferes with the
diff --git a/doc/global.n b/doc/global.n
index 16fdfd0..5c0d6ab 100644
--- a/doc/global.n
+++ b/doc/global.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: global.n,v 1.6 2004/05/17 22:23:42 dkf Exp $
+'\" RCS: @(#) $Id: global.n,v 1.7 2004/05/25 20:17:06 msofer Exp $
 '\" 
 .so man.macros
 .TH global n "" Tcl "Tcl Built-In Commands"
@@ -19,24 +19,35 @@ global \- Access global variables
 
 .SH DESCRIPTION
 .PP
-This command is ignored unless a Tcl procedure is being interpreted.
-If so then it declares the given \fIvarname\fR's to be global variables
-rather than local ones.
-Global variables are variables in the global namespace.
-For the duration of the current procedure
-(and only while executing in the current procedure),
-any reference to any of the \fIvarname\fRs
-will refer to the global variable by the same name.
+This command has no effect unless executed in the context of a proc body.
+If the \fBglobal\fR command is executed in the context of a proc body, it
+creates local variables linked to the corresponding global variables (and
+therefore these variables are listed by info locals).
+
+If \fIvarname\fR contains namespace qualifiers, the local variable's name is
+the unqualified name of the global variable, as determined by the
+\fBnamespace tail\fR command. 
 .PP
 \fIvarname\fR is always treated as the name of a variable, not an
 array element.  An error is returned if the name looks like an array element,
 such as \fBa(b)\fR.
-.SH EXAMPLE
+.SH EXAMPLE 1
+This procedure sets the namespace variable \fI::a::x\fR
+.PP
+.CS
+proc reset {} {
+    global a::x
+    set x 0
+}
+.CE
+.PP
+.SH EXAMPLE 2
 This procedure accumulates the strings passed to it in a global
 buffer, separated by newlines.  It is useful for situations when you
 want to build a message piece-by-piece (as if with \fBputs\fR) but
 send that full message in a single piece (e.g. over a connection
 opened with \fBsocket\fR or as part of a counted HTTP response).
+.PP
 .CS
 proc accum {string} {
     global accumulator