Subject: Re: bug#77312: [PATCH] Add uniquify-get-unique-names

From: Dmitry Gutov <[email-masked]>
Date: Fri, 27 Jun 2025 05:05:09 +0300

On 23/06/2025 19:09, Eli Zaretskii wrote:
>> But either way they are described from the pov of how they affect a
>> buffer and some behavior in it.
>>
>> So I wonder how you would want it introduced.
> Just describe what this face is used for and what is its effect.
> 
>> Maybe instead we would instead have a note somewhere near where
>> 'completing-read-function', saying something to the effect that the
>> completion strings might have a certain text property that would point
>> to related object. Which the completion UI might use to provide some
>> extra functionality.
> We should do both.

Here's what I have come up with, so far. In the practical sense, it 
seems adequate, though it might seem to elevate this particular text 
property too much (mentioning it in a very general context).

A more general approach might be better, one which would allow 
transforming the string names just when the selection is being made. 
Similar to what Spencer described, though I'm not sure if the predicate 
is the place to do transformation.

Anyway, doc proposal for the current functionality below. WDYT?

(Need code change too, will be included in the final patch.)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index b34f73feb5b..fc994496db0 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1239,7 +1239,10 @@ Minibuffer Completion
  @code{completing-read} to actually do its work.  It should accept the
  same arguments as @code{completing-read}.  This can be bound to a
  different function to completely override the normal behavior of
-@code{completing-read}.
+@code{completing-read}.  The function is free to use the string values,
+or text properties on them when available such as
+@code{uniquify-orig-buffer}, to offer additional UI which would act on
+those entities.
  @end defvar

  @findex completing-read-multiple
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a23033f2ab0..f7fe0b0180e 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4020,6 +4020,12 @@ Special Properties
  Custom, display-line-numbers,, emacs, The GNU Emacs Manual}) for the
  text which has this property.

+@kindex uniquify-orig-buffer @r{(text property)}
+@item uniquify-orig-buffer
+This text property might be attached to some strings when reading a
+buffer name, to reference the original buffer object the string relates
+to.  Such strings are returned by @code{uniquify-get-unique-names}.
+
  @end table

  @defvar inhibit-point-motion-hooks