Documentation of ‘define-alternatives’

Documentation of ‘define-alternatives’

[Shynur Xie]

Hi friends, I’m reading (elisp) 22.2.5 Select among Command
Alternatives.  It’s a little difficult for me understand it:

> contain an alist with alternative implementations

What does it mean by ‘implementation’?  An expression?

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

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

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.

Re: Documentation of ‘define-alternatives’

[Shynur Xie]

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

Thx, quite clear now!

One more question (info "(elisp) Generic Commands"):

> Macro: define-alternatives command &rest customizations
>
>  ... ...
>
>  If CUSTOMIZATIONS is non-‘nil’, it should consist of ... and values
>  to add to the declaration of ‘COMMAND-alternatives’.

Does it mean that user can initialize ‘COMMAND-alternatives’ by
putting the expected values in the ‘(define-alternative COMMAND ...)’
form?  If so, what is the standard way?  I tried:

    (define-alternatives your/generic-cmd-1
      '("1" . ignore)
      '("2" . ignore))
    (define-alternatives your/generic-cmd-2
      '(("1" . ignore)
        ("2" . ignore)))

Both don’t work (perhaps because the macro expects a keyword here).

Re: Documentation of ‘define-alternatives’

[Eli Zaretskii]

> From: Shynur Xie <one.last.kiss@outlook.com>
> CC: "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Date: Tue, 15 Aug 2023 10:16:36 +0000
> msip_labels:
> 
> > Macro: define-alternatives command &rest customizations
> >
> >  ... ...
> >
> >  If CUSTOMIZATIONS is non-‘nil’, it should consist of ... and values
> >  to add to the declaration of ‘COMMAND-alternatives’.
> 
> Does it mean that user can initialize ‘COMMAND-alternatives’ by
> putting the expected values in the ‘(define-alternative COMMAND ...)’
> form?

No.  The text says:

     If CUSTOMIZATIONS is non-‘nil’, it should consist of alternating
     ‘defcustom’ keywords (typically ‘:group’ and ‘:version’) and values
     to add to the declaration of ‘COMMAND-alternatives’.

So CUSTOMIZATIONS is for adding keyword/value pairs we usually use in
a defcustom (since this macro creates a defcustom).