51375: Clarify documentation, fix typos, add indexing.

ChangeLog

@@ -1,5 +1,8 @@
 2023-02-12  Bart Schaefer  <schaefer@zsh.org>
 
+	* 51375: Doc/Zsh/builtins.yo, Doc/Zsh/expn.yo, Doc/Zsh/params.yo,
+	Doc/Zsh/mod_parameter.yo: Clarify, fix typos, add indexing.
+
 	* 51374: Src/Modules/parameter.c, Src/params.c, Test/README,
 	Test/K01nameref.ztst: Expose named references in $parameters,
 	fix substitution error.

Doc/Zsh/builtins.yo

@@ -2041,16 +2041,22 @@ cindex(named reference)
 cindex(reference, named)
 The flag tt(-n) creates a em(named reference) to another parameter.
 The second parameter need not exist at the time the reference is
-created.  No other attribute flags may be used in conjunction with
+created.  No attributes except tt(-g) may be used in conjunction with
-tt(-n).  The var(name) assigned-to may not be an array element nor use
+tt(-n).  The var(name) so created may not be an array element nor use
 a subscript, but the var(value) assigned may be any valid parameter
-name syntax, even a subscripted array element (incuding an associative
+name syntax, even a subscripted array element (including an associative
 array element) or an array slice, which is evaluated when the named
 reference is expanded.
 See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and
 ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the
 behavior of named references.
 
+Local function scoping rules for `tt(typeset)' do apply with `tt(-n)',
+so a declaration within a function persists only until the end of the
+function unless `tt(-g -n)' is specified, and any local parameter (of
+any type) with the same var(name) supplants a named reference from a
+surrounding scope.
+
 If no attribute flags are given, and either no var(name) arguments are
 present or the flag tt(+m) is used, then each parameter name printed is
 preceded by a list of the attributes of that parameter (tt(array),

Doc/Zsh/expn.yo

@@ -1592,8 +1592,8 @@ tt(${)var(name)tt(:|)var(pname)tt(}))
 
 Expansions of the form `tt(${LPAR()t)tt(RPAR())var(pname)tt(})' expand
 the type information of var(rname), unless var(rname) is empty, in which
-case `tt(nameref)' is expanded, or when no variable var(rname) exists,
+case the expansion is `tt(nameref)', or when no variable var(rname)
-in which case the expansion is empty.
+exists, in which case the expansion is empty.
 
 See also ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)).
 

Doc/Zsh/mod_parameter.yo

@@ -127,6 +127,14 @@ noderef(Parameter Expansion)
 )\
 . The value may also be `tt(undefined)' indicating a parameter that
 may be autoloaded from a module but has not yet been referenced.
+When the key is the name of a named reference, the value is
+`tt(nameref-)' prepended to the type of the referenced parameter,
+for example
+ifzman()
+example(tt(% typeset -n parms=parameters)
+tt(% print -r ${parameters[parms]})
+tt(nameref-association-readonly-hide-hideval-special))
+
 Setting or unsetting keys in this array is not possible.
 )
 vindex(modules)

Doc/Zsh/params.yo

@@ -85,6 +85,8 @@ menu(Parameters Set By The Shell)
 menu(Parameters Used By The Shell)
 endmenu()
 texinode(Array Parameters)(Positional Parameters)()(Parameters)
+cindex(array parameters)
+cindex(parameters, array)
 sect(Array Parameters)
 To assign an array value, write one of:
 findex(set, use of)
@@ -567,6 +569,8 @@ entire second parameter concatenated with the filename generation pattern
 `tt([3,5])'.
 
 texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters)
+cindex(positional parameters)
+cindex(parameters, positional)
 sect(Positional Parameters)
 The positional parameters provide access to the command-line arguments
 of a shell function, shell script, or the shell itself; see
@@ -594,6 +598,8 @@ allowed, and has the effect of shifting all the values at positions greater
 than var(n) by as many positions as necessary to accommodate the new values.
 
 texinode(Local Parameters)(Named References)(Positional Parameters)(Parameters)
+cindex(local parameters)
+cindex(parameters, local)
 sect(Local Parameters)
 Shell function executions delimit scopes for shell parameters.
 (Parameters are dynamically scoped.)  The tt(typeset) builtin, and its
@@ -627,9 +633,9 @@ find the programs in tt(/new/directory) inside a function.
 Note that the restriction in older versions of zsh that local parameters
 were never exported has been removed.
 
+texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters)
 cindex(named references)
 cindex(references, named)
-texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters)
 sect(Named References)
 Zsh supports two different mechanisms for indirect parameter referencing:
 ifzman()
@@ -641,24 +647,24 @@ tt(print -r -- ${)var(pname)tt(}))
 
 The `tt((P))' flag method is older and should be used when a script
 needs to be backwards-compatible.  This is described fully in
-ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)).
+the Parameter Expansion Flags section of
+ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)).  Zsh
+versions em(greater than) tt(5.9.0) are required for `tt(typeset -n)'.
+This manual was generated with Zsh tt(version()).
 
 When a em(named reference) is created with `tt(typeset -n)', all uses
 of var(pname) in assignments and expansions instead assign to or
 expand var(rname).  This also applies to `tt(unset )var(pname)' and to
 most subsequent uses of `tt(typeset)' with the exception of
-`tt(typeset +n)', so to remove a named reference it is necessary to
+`tt(typeset -n)' and `tt(typeset +n)', so to remove a named reference
-use:
+it is necessary to use one of:
 ifzman()
-example(tt(typeset +n )var(pname)
+example(tt(typeset -n )var(pname)
-tt(unset )var(pname))
+tt(typeset +n )var(pname))
 
-When `tt(typeset -n )var(pname)tt(=)var(rname)' appears in a given
+followed by
-(global or function) scope, `tt(${)var(pname)tt(})' refers to
+ifzman()
-var(rname) in the scope of the tt(typeset) command.  This differs
+indent(tt(unset )var(pname))
-from ksh93 where the scope used is that of var(rname) even if the
-current var(rname) would be found in a surrounding scope.
-em(This is a misfeature.)
 
 An empty reference such as one of
 ifzman()
@@ -668,9 +674,11 @@ tt(typeset -n )var(pname)tt(=""))
 
 acts as a placeholder.  The first non-empty assignment to var(pname)
 initializes the reference, and subsequently any expansions of, or
-assignments to, var(pname) act on the referenced parameter.
+assignments to, var(pname) act on the referenced parameter.  This
+is explained in the Named References section of
+ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)).
 
-texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
+texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Named References)(Parameters)
 sect(Parameters Set By The Shell)
 In the parameter lists that follow, the mark `<S>' indicates that the
 parameter is special.  `<Z>' indicates that the parameter does not exist