Index: doc/Object.man
===================================================================
diff -u -N -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]