52650 plus minor fixes: add -u for named references pointing to "upper" scope

1 files changed, 8 insertions, 5 deletions

diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index d4914df7a..7b71e34e9 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -31,10 +31,12 @@ referent parameter is in scope, and as early as possible in the
 function if the reference is to a parameter in a calling scope.
 
 A typical use of named references is to pass the name
-of the referent as a positional parameter.  For example,
+of the referent as a positional parameter.  In this case it is
+good practice to use the tt(-u) option to reference the calling
+scope.  For example,
 ifzman()
 example(pop+LPAR()RPAR() {
-  local -n ref=$1
+  local -nu ref=$1
   local last=$ref[$#ref]
   ref[$#ref]=LPAR()RPAR()
   print -r -- $last
@@ -43,9 +45,10 @@ array=LPAR() a list of five values RPAR()
 pop array)
 
 prints the word `tt(values)' and shortens `tt($array)' to
-`tt(LPAR() a list of five RPAR())'.  There are no local parameters in
-tt(pop) at the time `tt(ref=$1)' is assigned, so `tt(ref)' becomes a
-reference to `tt(array)' in the caller.
+`tt(LPAR() a list of five RPAR())'.  With tt(-nu), `tt(ref)' becomes a
+reference to `tt(array)' in the caller.  There are no local parameters in
+tt(pop) at the time `tt(ref=$1)' is assigned, so in this example tt(-u)
+could have been omitted, but it makes the intention clear.
 
 Functions execute in the same process as the caller and
 share all files