[PATCH] Fix named reference documentation

[Philippe Altherr <philippe.altherr@xxxxxxxxx>]

I reviewed the documentation of named references to remove all language about subscripted references. I also made the following changes:

• Added -h as another flag compatible with -n

• Dropped "In ksh emulation, the parens around this flag are optional" from the documentation of (!) because it gives the false impression that ${(!)name} and ${!name} are somehow related (see workers/55047).

• Fixed a paragraph that inverted pname and rname.

I have a question about section 14.3.3 "Rules":

Note that, unless the ‘(P)’ flag or a named reference is present, the flags and any subscripts apply directly to the value of the nested substitution; for example, the expansion ${${foo}} behaves exactly the same as ${foo}. When a named reference or the ‘(P)’ flag is used in a nested substitution, the other substitution rules are applied to the value before it is interpreted as a name, so ${${(P)foo}} may differ from ${(P)foo}. When both a named reference and the ‘(P)’ flag appear, the named reference is resolved before ‘(P)’ is applied.

I don't understand what the highlighted part is about. What are examples of ${${(P)foo}} that differ from ${(P)foo} and examples of ${${ref}} that differ from ${ref}?

- Fix named reference documentation

Philippe

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index ca9ba996b..b9dd8faa5 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -2037,14 +2037,13 @@ 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.  Only the tt(-H), tt(-g), and tt(-r) flags may be used in
-conjunction with tt(-n), having their usual meanings.  The tt(-u)
+created.  Only the tt(-H), tt(-g), tt(-h), and tt(-r) flags may be used
+in conjunction with tt(-n), having their usual meanings.  The tt(-u)
 flag is special and may be applied to alter the scope of the reference.
 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 (including an associative
-array element) or an array slice, which is evaluated when the named
-reference is expanded.  It is an error for a named reference to refer
+name, but not a subscripted array (or associative array) element nor
+an array slice.  It is an error for a named reference to refer
 to itself, even indirectly through a chain of references.  When tt(-u)
 is applied to a named reference, the parameter identified by var(value)
 is always found in the calling function scope rather than the current
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index cbdaddead..c5995f4e4 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -976,8 +976,7 @@ following flags are supported:
 startitem()
 item(tt(!))(
 When the parameter being expanded is a named reference, the reference
-itself is examined and thus is em(not) resolved to its referent.  In
-ksh emulation, the parens around this flag are optional.
+itself is examined and thus is em(not) resolved to its referent.
 )
 item(tt(#))(
 Evaluate the resulting words as numeric expressions and interpret
@@ -1615,26 +1614,15 @@ Note, however, that named references to em(special) parameters acquire
 the behavior of the special parameter, regardless of the scope where
 the reference is declared.
 
-In the event that the local var(pname) goes out of scope (its declaring
-function returns) before the reference var(rname) goes out of scope,
+In the event that the local var(rname) goes out of scope (its declaring
+function returns) before the reference var(pname) goes out of scope,
 the reference may change to another parameter having the same name as
-var(pname), or assignments may fail as described above.  Keep the
-declaration of var(rname) as close as possible to its initialization
-to var(pname) to avoid confusion.
-
-When var(rname) includes an array subscript, the subscript expression
-is interpreted at the time tt(${)var(pname)tt(}) is expanded.  Any
-form of subscript is allowed, including those that select individual
-elements, substrings of scalar strings, or multiple elements as with
-array slices or the `tt((i))', `tt((I))', `tt((r))', `tt((R))' and
-`tt((w))' subscript flags.  However, the subscript is evaluated with
-the tt(NO_EXEC) option in effect, so command substitution and other
-similar constructs produce no output, although are not syntactically
-excluded.
-
-When var(rname) is an array (but not an array element or slice), the
-named reference may also be used in substitutions requiring an
-var(arrayname), so these are equivalent:
+var(rname), or assignments may fail as described above.  Keep the
+initialization of var(pname) as close as possible to the declaration of
+var(rname) to avoid confusion.
+
+When var(rname) is an array, the named reference may also be used in
+substitutions requiring an var(arrayname), so these are equivalent:
 ifzman()
 example(tt(${)var(name)tt(:|)var(rname)tt(})
 tt(${)var(name)tt(:|)var(pname)tt(}))
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 7d16083fb..e2db24880 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -22,10 +22,10 @@ place of any other parameter having the same name that was assigned or
 declared in an earlier function scope.
 (See sectref(Local Parameters)(zshparam).)
 
-A named parameter declared with the `tt(-n)' option to any of the
-`tt(typeset)' acts as a reference to another parameter, which may
-be at a different call level than the declaring function.  When the
-`tt(-u)' option is also given, the referenced parameter is always
+A named reference declared with the `tt(-n)' option to any of the
+`tt(typeset)' commands acts as a reference to another parameter, which
+may be at a different call level than the declaring function.  When
+the `tt(-u)' option is also given, the referenced parameter is always
 found at a call level above the function where the reference is
 declared, otherwise the reference scope is dynamic.  For this reason,
 it is good practice to declare a named reference as soon as the