Re: Updating *Completions* as you type

[Eli Zaretskii <eliz@gnu.org>]

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