Re: Add some tips in `compadd` docs about groups

[dana <dana@xxxxxxx>]

(raised again @ https://github.com/zsh-users/zsh/pull/135)

On Tue 13 May 2025, at 06:34, RocketDev wrote:
> Recently I wrote a zsh completion script to complete like `_pids`, which is 
> public via the link below:
> https://github.com/dbgbgtf1/Ceccomp/blob/92c99eb/completions/_ceccomp

normally you shouldn't use compadd by itself like that. it's very
low-level so if you call it directly you have to manually work out all
of the useful things completion functions are supposed to do. you almost
always want to call it via a helper function or pass it options that
were produced by one

in this case you can wrap it with _wanted, which will set a group name
amongst other things, allowing you to use -o like you expect:

  local -a expl
  _wanted nonk-pids expl 'non-kernel process ID' \
    compadd -o nosort -l -d lines -a pids

On Tue 13 May 2025, at 06:34, RocketDev wrote:
> Should we add some tips in manual, or inherit flags in `addmatches`? I'm 
> willing to make contributions, please reply to me if I could help any.

the documentation could be clearer but i thought the wording used in the
pr wasn't as precise as it could be. what about this

as far as why it discards the flags if you don't give a group name, idk,
but maybe the thinking is that the default group is a catch-all for
matches we don't otherwise know what to do with, so it's not appropriate
for one compadd call to be able to dictate flags for all of them

dana


diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index b0c9b0a5f..e1960d9e7 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -545,7 +545,9 @@ This controls the order in which matches are sorted. var(order) is a
 comma-separated list comprising the following possible values.  These values
 can be abbreviated to their initial two or three characters.  Note that the
 order forms part of the group name space so matches with different orderings
-will not be in the same group.
+will not be in the same group; additionally, since ordering flags are not
+respected on the default group, a group name must be given explicitly.  See
+tt(-J) and tt(-V) below.
 
 startitem()
 item(tt(match))(