help / color / mirror / code / Atom feed
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: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.


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

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


  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:

* 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 \


* 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


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).