Re: Documentation of ‘define-alternatives’

[Eli Zaretskii]

> From: Shynur Xie <one.last.kiss@outlook.com>
> Date: Mon, 14 Aug 2023 12:34:42 +0000
> 
> Hi friends, I’m reading (elisp) 22.2.5 Select among Command
> Alternatives.  It’s a little difficult for me understand it:

Not the best example of our documentation, obviously...

> > If customizations is non-nil, it should consist of ...  and values
> > to add to the declaration of command-alternatives.
> 
> How to include the ‘values’?
> 
> I tried:
> 
>   - evaluate:
> 
>         (define-alternatives your/generic-cmd-1)
>         (setq your/generic-cmd-1-alternatives '((1 . (ignore))))
>         ;; Or the reverse order.
> 
>     then type ‘M-x your/generic-cmd-1 <return> <tab>’.
>     Got ‘no match’
> 
>   - evaluate:
> 
>         (define-alternatives your/generic-cmd-2
>           '(1 . (ignore))
>           '(2 . (ignore)))
> 
>     Got error.

The value of COMMAND-alternatives is an alist whose elements are of
the form (ALTERNATIVE-NAME . ALTERNATIVE-FUNCTION), where car is a
string, the name of the alternative command to be shown to the user;
and ALTERNATIVE-FUNCTION is the function to be called when that
alternative is selected.  Your "values" are not of that form.

> IMHO, section 22.2.5 needs an example or more readable or clear
> description for ‘define-alternatives’.

The latter, of course.