Re: [PATCH 3/3] Documentation for named references

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Bart Schaefer wrote on Sun, Feb 05, 2023 at 18:26:50 -0800:
> +++ b/Doc/Zsh/builtins.yo
> @@ -2037,6 +2037,20 @@ To initialize a parameter var(param) to a command output and mark it readonly,
> +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
> +tt(-n).  The var(name) assigned-to may not be an array element nor use

s/assigned-to/assigned to/

> +a subscript, but the var(value) assigned may be any valid parameter
> +name syntax, even a subscripted array element (incuding an associative

"incuding"

> +++ b/Doc/Zsh/expn.yo
> @@ -1523,6 +1526,77 @@ Include the unmatched portion in the result (the em(R)est).
> +subsect(Named References)
> +cindex(named references)
> +cindex(namerefs)
> +cindex(reference variables)
> +cindex(parameters, nameref)
⋮
> +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,

"in which case the expansion is `tt(nameref)'"?

> @@ -1545,12 +1619,16 @@ substitutions; the nested substitution will return either a scalar or an
⋮
> +When both a named reference and the `tt((P))' flag appear, the named
> +reference is resolved before `tt((P))' is applied.

Add a test for this last sentence?

> +++ b/Doc/Zsh/params.yo
> @@ -626,6 +627,49 @@ find the programs in tt(/new/directory) inside a function.
> +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()
> +example(tt(typeset )var(name)tt(=)var(rname)
> +tt(print -r -- ${LPAR()P)tt(RPAR())var(name)tt(}))
> +ifzman()
> +example(tt(typeset -n )var(pname)tt(=)var(rname)
> +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)).
> +

WDYT of documenting somewhere in the manual namerefs are new in 5.10?

> +When `tt(typeset -n )var(pname)tt(=)var(rname)' appears in a given
> +(global or function) scope, `tt(${)var(pname)tt(})' refers to
> +var(rname) in the scope of the tt(typeset) command.  This differs
> +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.)

Does "This is a misfeature" mean "This may change in the future to be
compatible with ksh93"?

> +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.
> +
>  texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
>  sect(Parameters Set By The Shell)

s/Local Parameters/Named References/

Cheers,

Daniel
(public service announcement: we have *.yo syntax highlighting for Vim
in our tree)