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

From: Daniel Mendler <[email-masked]>
Date: Tue, 04 Feb 2025 09:28:47 +0100

Juri Linkov <[email-masked]> writes:

>>>   Describe face (face1,face2,...):
>>>
>>> A more generalized prompt would make this less clear, e.g.
>>>
>>>   Describe face (separator ‘,’):
>>
>> Giving an example does not solve the general issue of a uniform CRM
>> indication for all `completing-read-multiple' calls. In the Emacs code
>> base `completing-read-multiple' is not used widely but it is used in
>> other packages, which we cannot update at once.
>
> Wouldn't addition of more text to the prompt break these packages
> in some way?  Maybe only those that rely on the fixed format
> like minibuf-eldef.el that is quite rare.

I have not seen many such packages which rely on the prompt format, but
yes, one should check the ones like minibuf-eldef.el. I have used my
[CRM,] indicator advice for a long time without big problems.

>> I find Stefan's suggestion of [comma-separated list] quite nice. See the
>> patch I have sent in the other mail. Maybe we could use the
>> [comma-separated list] indicator as fallback if a
>> `completing-read-multiple' call does not provide examples on its own?
>
> The only problem with the patch is that it would be better
> to leave the existing format of the variable 'crm-separator'
> to avoid possible backward-compatibility problems,
> and then add a new variable or two for the separator
> and its description.

Yes, the change of format could be a problem. However if one uses
multiple variables one can easily forget to bind or configure them
together, which leads to bugs or an inconsistency. Currently there is
code, also third-party code, which let-binds a custom crm-separator but
of course not the other variables, such that there would be an
inconsistency immediately if we introduce the new variables. Therefore I
would stick to a single variable. We could also introduce a new variable
crm-config with the proposed list format which is used if crm-separator
is nil. crm-separator will be nil by default and marked obsolete.
Another more tricky approach would be to attach text properties to
crm-separator which carry the additional data. This would be backward-
and forward-compatible also for third-party code, but maybe not very
elegant. What do you think?

>> Another possibility might be to use the completion category and the
>> separator string and convert that to an example, e.g., category face
>> would yield the prompt "Describe face (face1,face2,...):".
>
> Maybe then it's possible to provide the separator and its description
> in the metadata?

This would be more intrusive. Also the question is if the crm-separator
is truly bound to the completion table, or if it should be possible to
reuse the same table with different separators.

Daniel