Where is the argument's message displayed?

It's in the manual if you know where to look, but the way it's explained, you practically have to know the answer to understand what the manual is saying.

_arguments calls this a “message” and the manual says that this “describes”. So you take a leap of faith — or read the source code of _arguments and puzzle out that this message is passed to _describe. The documentation of this function states that

The descr is taken as a string to display above the matches if the format style for the descriptions tag is set.

A style is something you configure with zstyle. The section “Completion System Configuration” documents the format of styles for completion:

The fields are always in the order :completion:function:completer:command:argument:tag.

So you need to call zstyle ':completion:*:*:*:*:descriptions' format=SOMETHING. Or replace the * by something else if you only want to do it in certain contexts.

The documentation of the descriptions tag is not particularly helpful at this stage, but the documentation of the format style is:

If this is set for the descriptions tag, its value is used as a string to display above matches in completion lists. The sequence %d in this string will be replaced with a short description of what these matches are. This string may also contain the output attribute sequences understood by compadd -X

See the compadd documentation which in turns refers to prompt expansion; you can mainly use visual effects.

So run

zstyle ':completion:*:*:*:*:descriptions' format '%F{green}%d%f'

and you'll see that message in green above the completions. Or

zstyle ':completion:*:*:program:*:descriptions' format '%F{green}%d%f'

if you only want it to apply when completing arguments of program.


You need to set the format zstyle of completion:

zstyle ':completion:*' format 'Completing %d'

Then:

$ program -b Tab
Completing my message
x  y

See info zsh format for details.

That's set by compinstall if you follow this menu selection:

3.  Styles for changing the way completions are displayed and inserted.
[...]
1.  Change appearance of completion lists:  allows descriptions of
    completions to appear and sorting of different types of completions.
[...]
1.  Print a message above completion lists describing what is being
    completed.
[...]
You can set a string which is displayed on a line above the list of matches
for completions.  A `%d' in this string will be replaced by a brief
description of the type of completion.  For example, if you set the
string to `Completing %d', and type ^D to show a list of files, the line
`Completing files' will appear above that list.  Enter an empty line to
turn this feature off.  If you enter something which doesn't include `%d',
then `%d' will be appended.  Quotation will be added automatically.

description>