From: Daniel Shahaf <d.s@daniel.shahaf.name>
To: Zsh hackers list <zsh-workers@zsh.org>
Subject: Re: [PATCH 3/4] docs: _wanted: Clarify the example and point to another one.
Date: Tue, 12 Oct 2021 14:40:06 +0000 [thread overview]
Message-ID: <20211012144006.GA17948@tarpaulin.shahaf.local2> (raw)
In-Reply-To: <47164-1632758103.190051@NBUG.TDW3.g63k>
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@daniel.shahaf.name> 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
next prev parent reply other threads:[~2021-10-12 14:40 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-26 8:43 [PATCH 1/4] docs: Clean up some subsection references Daniel Shahaf
2021-09-26 8:43 ` [PATCH 2/4] docs: Add texinode()s, so the next commit can link directly to a subsection Daniel Shahaf
2021-09-27 15:41 ` Bart Schaefer
2021-10-12 14:53 ` Daniel Shahaf
2021-09-26 8:43 ` [PATCH 3/4] docs: _wanted: Clarify the example and point to another one Daniel Shahaf
2021-09-27 15:38 ` Bart Schaefer
2021-09-27 15:55 ` Oliver Kiddle
2021-10-12 14:40 ` Daniel Shahaf [this message]
2021-09-26 8:43 ` [PATCH 4/4] docs: Fix pointers to the `Widgets', `User-defined Widgets', and `Standard Widgets' sections Daniel Shahaf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211012144006.GA17948@tarpaulin.shahaf.local2 \
--to=d.s@daniel.shahaf.name \
--cc=zsh-workers@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).