From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Eli Zaretskii <eliz@gnu.org>
Newsgroups: gmane.emacs.devel
Subject: Re: Updating *Completions* as you type
Date: Tue, 28 Nov 2023 17:03:48 +0200
Message-ID: <837cm19ay3.fsf@gnu.org>
References: <87bkd3z9bi.fsf@catern.com> <87y1fztke8.fsf@catern.com>
 <86r0lrw17x.fsf@mail.linkov.net> <87il5xlf9b.fsf@catern.com>
 <86y1esuajx.fsf@mail.linkov.net> <ierleas4fcr.fsf@janestreet.com>
 <86v89ws5t3.fsf@mail.linkov.net> <iercyw445tu.fsf@janestreet.com>
 <86v89vzf1o.fsf@mail.linkov.net> <87pm03jn3w.fsf@catern.com>
 <861qcjw3ch.fsf@mail.linkov.net> <ier1qcin8db.fsf@janestreet.com>
 <86r0ki2on3.fsf@mail.linkov.net> <ierttpdlqe4.fsf@janestreet.com>
 <86leao519y.fsf@mail.linkov.net> <87fs0wk5oq.fsf@catern.com>
 <86edgfin4v.fsf@mail.linkov.net> <87o7fhixzv.fsf@catern.com>
 <86o7fhy9ae.fsf@mail.linkov.net> <87v89ohc6f.fsf@catern.com>
 <86il5nhdvh.fsf@mail.linkov.net> <87plzuuend.fsf@catern.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="11437"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: juri@linkov.net, sbaugh@janestreet.com, emacs-devel@gnu.org
To: Spencer Baugh <sbaugh@catern.com>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Nov 28 16:04:23 2023
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>
Envelope-to: ged-emacs-devel@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>)
	id 1r7zdP-0002j7-4K
	for ged-emacs-devel@m.gmane-mx.org; Tue, 28 Nov 2023 16:04:23 +0100
Original-Received: from localhost ([::1] helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <emacs-devel-bounces@gnu.org>)
	id 1r7zd5-0006vj-V5; Tue, 28 Nov 2023 10:04:03 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@gnu.org>) id 1r7zd4-0006vS-Rv
 for emacs-devel@gnu.org; Tue, 28 Nov 2023 10:04:02 -0500
Original-Received: from fencepost.gnu.org ([2001:470:142:3::e])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@gnu.org>)
 id 1r7zd3-00050D-SX; Tue, 28 Nov 2023 10:04:01 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
 s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From:
 Date; bh=VjK4zYyLlcnR9HmLGm90aCMDkhrLlDiSgwMbhPj2030=; b=H9trrKDWICIuQttF/mEr
 FBOQlS5vNq4zE/FOmu2/YdgyC+1uNkc7Lxa31wXyskU6R0jLBtVa5hANKH+t/vqV2M+qJvWvKpVr8
 XApgyHNb8tXKXcDqqa+C6m3AiM6ipZ5oCIYg+66WM+7pzoKmp1A56OD2dcXMSsV4l1asIntdVxKNi
 P0wJ2lLj3FvrNz0lzrewslG8Pr+zE0rN8sQe9UpBC1PeFhC4ftCe43pfEWGcxIUdqbmjFJQaSA/xK
 iFP7PHcIRwRqO0Ec2VO6zsQnbS9SLieiOtBt/ubc//mizkqYep6msruCQqr0BEg7P3inqblj5wLh2
 IaPaaH2LtRf5zA==;
In-Reply-To: <87plzuuend.fsf@catern.com> (message from Spencer Baugh on Tue,
 28 Nov 2023 14:38:55 +0000 (UTC))
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Emacs development discussions." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/emacs-devel>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Xref: news.gmane.io gmane.emacs.devel:313325
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/313325>

> From: Spencer Baugh <sbaugh@catern.com>
> Date: Tue, 28 Nov 2023 14:38:55 +0000 (UTC)
> Cc: Spencer Baugh <sbaugh@janestreet.com>, emacs-devel@gnu.org
> 
> +*** New value for 'historical' for user option 'completions-sort'
                 ^^^
That "for" should be removed.

> +When 'completions-sort' is set to 'historical', completion candidates
> +will be sorted by their position in the minibuffer history, more
                           ^^^^^^^^
Not "position", but chronological order.

> +Completion candidates in the *Completions* buffer are sorted
> +depending on the value.
> +
> +If nil, sorting is disabled.

"If it's nil, sorting is disabled."

> +If `alphabetical', candidates are sorted by
> +`minibuffer-sort-alphabetically'.

"If it's `alphabetical', candidates are sorted..."

Etc.

Also, did you make sure these symbols are not highlighted as links
even if a function or variable by that name exists?  I think you
should use this technique from "Documentation Tips" to prevent that:

     If a symbol has a function definition and/or a variable definition,
     but those are irrelevant to the use of the symbol that you are
     documenting, you can write the words ‘symbol’ or ‘program’ before
     the symbol name to prevent making any hyperlink.

> +If a function, the function is called to sort the candidates.
> +The sorting function takes and returns a list of completion
> +candidate strings.

Can it return the same list, or should it always return a copy?

> +If the completion-specific metadata provides a
> +`display-sort-function', that is used instead and this value is
> +ignored."

"If the completion-specific metadata provides
a`display-sort-function', that function overrides the value of this
variable."

>    :type '(choice (const :tag "No sorting" nil)
>                   (const :tag "Alphabetical sorting" alphabetical)
> +                 (const :tag "Historical sorting" historical)
                                 ^^^^^^^^^^^^^^^^^^
"Chronological sorting"

> +(defvar minibuffer-completion-base nil
> +  "The base for the current completion.
> +
> +This is the part of the current minibuffer input which is not
> +being completed on.

I couldn't understand what this sentence means.

> +(defun minibuffer-sort-by-history (completions)
> +  "Sort COMPLETIONS by their position in `minibuffer-history-variable'.
> +
> +COMPLETIONS are sorted first by `minibuffer-sort-alphbetically',
> +then any elements occuring in the minibuffer history list are
> +moved to the front based on the order they occur in the history.
> +If a history variable hasn't been specified for this call of
> +`completing-read', COMPLETIONS are sorted only by
> +`minibuffer-sort-alphbetically'.

Again, please use "chronologically" here, not "by history".