Re: [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Oliver Kiddle wrote on Mon, Sep 27, 2021 at 17:55:03 +0200:
> Bart Schaefer wrote:
> > On Sun, Sep 26, 2021 at 1:47 AM Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx> wrote:
> > >
> > > -    compadd matches...)
> > > +    compadd -- var(match1) var(match2)...)
> >
> > Hmm ... I'm uncertain about using var() inside example().  This is
> > going to render in "info" as

There's plenty of precedent:

% ag -G yo 'example\(.*var\('
Doc/Zsh/builtins.yo:227:example(emulate zsh -c 'autoload -Uz var(func)')
Doc/Zsh/mod_system.yo:76:example(tt(exec {)var(fd)tt(}<&-)
Doc/Zsh/expn.yo:474:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() |
Doc/Zsh/expn.yo:514:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ 
Doc/Zsh/expn.yo:529:example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) tt(> >LPAR())var(process)tt(RPAR()))
Doc/Zsh/expn.yo:534:example(tt({ paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() }) tt(> >LPAR())var(process)tt(RPAR()))
Doc/Zsh/contrib.yo:350:example(tt(zle )var(widgetname)tt( -Nw -f "nolast" -- "$@"))
Doc/Zsh/contrib.yo:957:example(:vcs_info:var(vcs-string):var(user-context):var(repo-root-name))
Doc/Zsh/contrib.yo:1560:example(:vcs_info:var(vcs-string)PLUS()var(hook-name):var(user-context):var(repo-root-name))
Doc/Zsh/contrib.yo:2054:example(prompt_cleanup var(command))
Doc/Zsh/contrib.yo:2084:example(autoload var(function)
Doc/Zsh/contrib.yo:4641:ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname)))
Doc/Zsh/contrib.yo:4680:example(zstyle+ ':foo:bar' var(style1) var(value1) \ 
% 

(This is just a line-based grep: there may be additional uses of var()
in multi-line example()s.)

Furthermore, semantically, var() is the correct macro to use here: the
argument «matches» (before this patch) does not literally mean to add
the string «matches» as a completion; it is a placeholder for actual
matches.  If info doesn't render that sanely, ideally we'll teach
ztexi.yo to do that.

How about changing that line to say «compadd foo bar...» instead?

> Also, note that listing no matches at all with compadd is still a
> completely valid compadd command.

Sure.

Incidentally, why does «_f() { compadd; }» followed by «f <TAB>» not
print the message set by «zstyle ':completion:*:warnings' format "No
matches"»?

> This can be useful because you might
> generate the list of candidate matches from a command and pass the list
> straight to compadd without first checking whether any were generated.
> 
> Doesn't this updated usage imply that there must be at least one?

I don't see how.  This isn't the synopsis at the top of «compadd»'s
docs (the usage summary); it's simply an example of how one might invoke
«compadd», whose own docs specify all possible ways to invoke it.

Sorry for my long turn-around on this.

Daniel