[PATCH] Document ${(!)refname}

[PATCH] Document ${(!)refname}

[Bart Schaefer]

This documents workers/51509.

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 7bc736470..418139424 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -987,6 +987,11 @@ means the same thing as the more readable
`(tt(%%qqq))'.  The
 following flags are supported:

 startitem()
+item(tt(!))(
+When the parameter being expanded is a named reference, the reference
+string is substituted and thus the reference is em(not) resolved.  In
+ksh emulation, the parens around this flag are optional.
+)
 item(tt(#))(
 Evaluate the resulting words as numeric expressions and interpret
 these as character codes.  Output the corresponding characters.  Note

Re: [PATCH] Document ${(!)refname}

[Jun T]

> 2023/06/23 6:39、Bart Schaefer <schaefer@brasslantern.com>のメール:
> 
> This documents workers/51509.
(snip)
> +item(tt(!))(
> +When the parameter being expanded is a named reference, the reference
> +string is substituted and thus the reference is em(not) resolved.

% typeset -n ptr=var
% echo $(\!t)ptr}
nameref

In this case "the reference string is substituted" seems to be not so
suitable. The flag ! always indicates
"the named reference itself, not its referent".

Probably something like the following,
"When the parameter being expanded is a named reference, do not
resolve to its referent but use its own value."
but not sure this is clear enough.

At the end of the subsection "Named References" in zshexpn(1)
(expn.yo:1614), there is a description of ${(t)ptr}.
How about adding a description of $(!t)ptr} here?

Re: [PATCH] Document ${(!)refname}

[Bart Schaefer]

On Thu, Jul 6, 2023 at 11:45 PM Jun T <takimoto-j@kba.biglobe.ne.jp> wrote:
>
> % typeset -n ptr=var
> % echo $(\!t)ptr}
> nameref
>
> Probably something like the following,
> "When the parameter being expanded is a named reference, do not
> resolve to its referent but use its own value."
>
> At the end of the subsection "Named References" in zshexpn(1)
> (expn.yo:1614), there is a description of ${(t)ptr}.
> How about adding a description of $(!t)ptr} here?

Perhaps this?

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 7bc736470..4285aa4c1 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -987,6 +987,11 @@ means the same thing

 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.
+)
 item(tt(#))(
 Evaluate the resulting words as numeric expressions and interpret
 these as character codes.  Output the corresponding characters.  Note
@@ -1245,7 +1250,8 @@ item(tt(hideval))(
 for parameters with the `hideval' flag (tt(-H))
 )
 item(tt(nameref))(
-for named references having an empty value (tt(-n))
+for named references either having an empty value (tt(-n)) or when combined
+with `tt(!)' as in `tt(${LPAR()!t)tt(RPAR()var(rname)})'
 )
 item(tt(special))(
 for special parameters defined by the shell

Re: [PATCH] Document ${(!)refname}

[Bart Schaefer]

On Mon, Jul 10, 2023 at 6:21 PM Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> +for named references either having an empty value (tt(-n)) or when combined

Hm.  The (tt(-n)) would normally be at the end of the line to match
all the other examples, but in this case it might make more sense to
write

+for named references (tt(-n)) either having an empty value or when combined