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

[Bart Schaefer <schaefer@brasslantern.com>]

On Mon, Feb 6, 2023 at 4:57 PM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> Bart Schaefer wrote on Sun, Feb 05, 2023 at 18:26:50 -0800:

> > +tt(-n).  The var(name) assigned-to may not be an array element nor use
>
> s/assigned-to/assigned to/

I did that on purpose to remove any ambiguity about what object "to" acts upon.
I've used s/assigned-to/so created/

> "incuding"

Thanks.

> > +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)'"?

Better, thank you.

> > +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?

I can't think of a way to do so.  Given ${(P)ptr}, there are two possibilities:
1) ptr is a scalar, in which case we're not testing the right thing
2) ptr is a reference, so any other order of expansion is meaningless

If ptr is a reference, a working test of ${ptr} implies that ${(P)ptr}
also works.  I almost didn't include that sentence in the doc at all,
but I found the nameref sections of "man ksh93" to be so nearly
unreadable that I went as far as I could in the other direction.  (The
sections on discipline functions are even worse, even the author of
the O'Reilly ksh book basically gives up on the topic.)

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

I was going to add something to NEWS and README eventually ... also, I
wasn't sure we'd landed on a version number yet.  I suppose (once we
do) a mention wouldn't hurt since the docs are likely to end up on
line.

> > +em(This is a misfeature.)
>
> Does "This is a misfeature" mean "This may change in the future to be
> compatible with ksh93"?

Oops, I was supposed to delete that whole paragraph, I already fixed
that with the base/width overloading.

> >  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/

Thanks, thought I'd caught all of those ... it was nice when the older
version of yodl complained about those incorrect references.

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

I have a yodl-mode.el file for emacs floating around somewhere too,
tho it hasn't been updated since about GNU emacs 12.