Index: doc/Object.3
===================================================================
diff -u -r63ef94e81bbdfb6c0c233d65520a3e7b3e47f706 -ra7638da272da3ccdda36b12a062103e7451f0318
--- doc/Object.3	(.../Object.3)	(revision 63ef94e81bbdfb6c0c233d65520a3e7b3e47f706)
+++ doc/Object.3	(.../Object.3)	(revision a7638da272da3ccdda36b12a062103e7451f0318)
@@ -348,6 +348,8 @@
 .sp
 \fIobj\fR \fBuplevel\fR ?\fIlevel\fR? \fIarg1\fR ?\fIarg2\fR \&.\&.\&.?
 .sp
+\fIobj\fR \fBupvar\fR ?\fIlevel\fR? \fIotherVar1\fR \fIlocalVar1\fR ?\fIotherVar2\fR \fIlocalVar2\fR \&.\&.\&.?
+.sp
 \fIobj\fR \fBobject variable\fR ?\fB-accessor\fR \fBpublic\fR | \fBprotected\fR | \fBprivate\fR? ?\fB-incremental\fR? ?\fB-class\fR \fIclassName\fR? ?\fB-configurable\fR \fItrueFalse\fR? ?\fB-initblock\fR \fIscript\fR? ?\fB-trace\fR \fBset\fR | \fBget\fR | \fBdefault\fR? ?\fB-nocomplain\fR? \fIspec\fR ?\fIdefaultValue\fR?
 .sp
 .BE
@@ -1409,13 +1411,14 @@
 .RS
 .IP \(bu
 If the \fIlevel\fR specifier is omitted, \fBuplevel\fR
-will skip any auxiliary frames added to the stack by active filters and
-mixins\&.
+will skip any auxiliary frames added to the stack by active filters and mixins\&. The
+resulting stack-frame level corresponds to the callinglevel
+as indicated by \fBnx::current\fR\&.
 .IP \(bu
 If the \fIlevel\fR specifier is omitted, \fBuplevel\fR gives
-preference to the innermost frame corresponding to a proc, method, or
-apply call\&. Any frames inbetween, incl\&. those of filters
-and mixins (see above), will be skipped\&.
+preference to the innermost enclosing procedure call, i\&.e\&., a frame
+corresponding to a proc, method, or apply call\&. Any frames inbetween,
+incl\&. those of filters and mixins (see above), will be skipped\&.
 .IP \(bu
 If the \fIlevel\fR specifier is provided (relative, or
 absolute), \fBuplevel\fR will move execution into the requested
@@ -1426,10 +1429,11 @@
 
 
   % nx::Object create ::obj
+  ::obj
   % ::obj public object method foo {varName} {
       :uplevel set $varName 1; return
   }
-  ::obj
+  ::obj::foo
   % namespace eval ::ns1 {
        ::obj foo BAR
   }
@@ -1445,6 +1449,54 @@
 resolve to the calling context of \fBfoo\fR (ns1) despite
 mixins and filters being (potentially) registered on \fBobj\fR\&.
 .TP
+\fBupvar\fR
+.RS
+.TP
+\fIobj\fR \fBupvar\fR ?\fIlevel\fR? \fIotherVar1\fR \fIlocalVar1\fR ?\fIotherVar2\fR \fIlocalVar2\fR \&.\&.\&.?
+Links one or more local variables to variables defined for other
+scopes (namespaces, objects, call frames)\&. Behaves like Tcl's \fBupvar\fR,
+with the following important exceptions\&.
+.RS
+.IP \(bu
+If the \fIlevel\fR specifier is omitted, \fBupvar\fR
+will skip any auxiliary frames added to the stack by active filters and mixins\&. The
+resulting stack-frame level corresponds to the callinglevel
+as indicated by \fBnx::current\fR\&.
+.IP \(bu
+If the \fIlevel\fR specifier is omitted, \fBupvar\fR gives
+preference to the innermost enclosing procedure call, i\&.e\&., a frame
+corresponding to a proc, method, or apply call\&. Any frames inbetween,
+incl\&. those of filters and mixins (see above), will be skipped\&.
+.IP \(bu
+If the \fIlevel\fR specifier is provided (relative, or
+absolute), \fBupvar\fR will link into the requested
+stack-frame level (incl\&. those introduced by active active filters and
+mixins), if valid\&.
+.RE
+.CS
+
+
+  % nx::Object create ::obj
+  ::obj
+  % ::obj public object method foo {varName} {
+      :upvar $varName x; set x 1; return
+  }
+  ::obj::foo
+  % namespace eval ::ns1 {
+       ::obj foo BAR
+  }
+  % namespace eval ::ns1 {
+      info exists BAR
+  }
+  1
+
+.CE
+.RE
+.IP
+Note, in the example above, \fBupvar\fR is guaranteed to
+resolve to the calling context of \fBfoo\fR (ns1) despite
+mixins and filters being (potentially) registered on \fBobj\fR\&.
+.TP
 \fBvariable\fR
 .RS
 .TP
Index: doc/Object.man
===================================================================
diff -u -r63ef94e81bbdfb6c0c233d65520a3e7b3e47f706 -ra7638da272da3ccdda36b12a062103e7451f0318
--- doc/Object.man	(.../Object.man)	(revision 63ef94e81bbdfb6c0c233d65520a3e7b3e47f706)
+++ doc/Object.man	(.../Object.man)	(revision a7638da272da3ccdda36b12a062103e7451f0318)
@@ -756,13 +756,14 @@
 [list_begin itemized]
 
 [item] If the [arg level] specifier is omitted, [method "uplevel"]
-will skip any auxiliary frames added to the stack by active [term "filter"]s and
-[term "mixin"]s.
+will skip any auxiliary frames added to the stack by active [term "filter"]s and [term "mixin"]s. The
+resulting stack-frame level corresponds to the [term "callinglevel"]
+as indicated by [cmd nx::current].
 
 [item] If the [arg level] specifier is omitted, [method uplevel] gives
-preference to the innermost frame corresponding to a proc, method, or
-apply call. Any frames inbetween, incl. those of filters
-and mixins (see above), will be skipped.
+preference to the innermost enclosing procedure call, i.e., a frame
+corresponding to a proc, method, or apply call. Any frames inbetween,
+incl. those of filters and mixins (see above), will be skipped.
 
 [item] If the [arg level] specifier is provided (relative, or
 absolute), [method "uplevel"] will move execution into the requested
@@ -773,10 +774,11 @@
 
 [example { 
   % nx::Object create ::obj
+  ::obj  
   % ::obj public object method foo {varName} {
       :uplevel set $varName 1; return
   }
-  ::obj
+  ::obj::foo
   % namespace eval ::ns1 {
        ::obj foo BAR
   }
@@ -792,6 +794,57 @@
 resolve to the calling context of [method "foo"] ([term "ns1"]) despite
 mixins and filters being (potentially) registered on [cmd "obj"].
 
+[cmd_def upvar]
+
+[list_begin definitions]
+
+[call [arg obj] [method upvar] [opt [arg level]] [arg otherVar1] [arg localVar1] [opt "[arg otherVar2] [arg localVar2] ..."]]
+
+Links one or more local variables to variables defined for other
+scopes (namespaces, objects, call frames). Behaves like Tcl's [cmd "upvar"],
+with the following important exceptions.
+
+[list_begin itemized]
+
+[item] If the [arg level] specifier is omitted, [method "upvar"]
+will skip any auxiliary frames added to the stack by active [term "filter"]s and [term "mixin"]s. The
+resulting stack-frame level corresponds to the [term "callinglevel"]
+as indicated by [cmd nx::current].
+
+[item] If the [arg level] specifier is omitted, [method upvar] gives
+preference to the innermost enclosing procedure call, i.e., a frame
+corresponding to a proc, method, or apply call. Any frames inbetween,
+incl. those of filters and mixins (see above), will be skipped.
+
+[item] If the [arg level] specifier is provided (relative, or
+absolute), [method "upvar"] will link into the requested
+stack-frame level (incl. those introduced by active active [term "filter"]s and
+[term "mixin"]s), if valid.
+
+[list_end]
+
+[example { 
+  % nx::Object create ::obj
+  ::obj  
+  % ::obj public object method foo {varName} {
+      :upvar $varName x; set x 1; return
+  }
+  ::obj::foo
+  % namespace eval ::ns1 {
+       ::obj foo BAR
+  }
+  % namespace eval ::ns1 {
+      info exists BAR
+  }
+  1 
+}]
+
+[list_end]
+
+Note, in the example above, [method "upvar"] is guaranteed to
+resolve to the calling context of [method "foo"] ([term "ns1"]) despite
+mixins and filters being (potentially) registered on [cmd "obj"].
+
 [cmd_def variable]
 
 [list_begin definitions]