Subject: bug#76028: 31; completing-read-multiple: Add prompt indicator

From: Daniel Mendler <[email-masked]>
Date: Mon, 03 Feb 2025 14:02:35 +0100

Eli Zaretskii <[email-masked]> writes:

>> Cc: Juri Linkov <[email-masked]>
>> Date: Mon, 03 Feb 2025 10:27:30 +0100
>> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <[email-masked]>
>> 
>> The function `completing-read-multiple' (CRM) can be used to read
>> multiple candidates, separated by comma (see the variable
>> `crm-separator'). Besides that it acts similarly to `completing-read'.
>> To the user it is no obvious if CRM is used.
>> 
>> For years I have used an advice in my configuration which adds a CRM
>> indicator to the prompt. For example, the advice turns the
>> `describe-face' prompt from "Describe face: " into "[CRM ,] Describe
>> face: ", which tells the user that multiple face names are read,
>> separated by comma:
>> 
>> #+begin_src emacs-lisp
>> (defun crm-indicator (args)
>>   (defvar crm-separator)
>>   (cons (format "[%s %s] %s"
>>                 (propertize "CRM" 'face 'error)
>>                 (propertize
>>                  (replace-regexp-in-string
>>                   "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" ""
>>                   crm-separator)
>>                  'face 'success)
>>                 (car args))
>>         (cdr args)))
>> (advice-add #'completing-read-multiple :filter-args #'crm-indicator)
>> #+end_src
>> 
>> I propose to add such an indicator to CRM by default. Above I have
>> chosen the tag "CRM" for its shortness, but a more user friendly
>> solution might require a longer more descriptive name. Furthermore the
>> code above extracts the separator from the regular expression
>> `crm-separator', which is not robust for all separators.
>
> Isn't that too cryptic?

Yes. For my purposes the cryptic text is sufficient but I would prefer
something more readable if we add such an indicator to
`completing-read-multiple'.

> A prompt "Describe face: " which expects one or more faces is not the
> best prompt text, and should preferably be improved by implying
> multiple faces separated by a comma.  Or maybe we need some
> specialized help key there, which would spell that out.  Or something
> else which would be explicit even to users who are using CRM for the
> first time in their lives.

Improving every `completing-read-multiple' prompt is an option too.
However I would prefer if we uniformly add an indicator to
`completing-read-multiple' such that multi completion becomes clearly
recognizable. Other options could be a help text in the mode line or a
`minibuffer-message' telling the user about multi completion. In any
case the indicator should be guarded by a customization options such
that it can be disabled or customized.

Daniel