bug#45539: 26.3; `add-to-ordered-list': Add optional arg for :test predicate for hash table

[Drew Adams]

I just now noticed the doc for this function in (elisp)
`List Variables'.  Should have looked in that manual
sooner.  (I didn't expect it to be documented there;
never heard of this function before.)

That description confirms what I've said, I think.

Dunno why this function was added (and documented in
the manual, which is usually done only for important
functions).  Dunno if anyone uses it.
___

One thing that I've said isn't quite correct: the
list _can_ have duplicates for elements that are
added with no ORDER.  IOW, I should have said that
elements that are recorded in the hash table can't
be duplicated (because a hash table has unique keys).
But other elements can be duplicated.
___

If we're adding a TEST optional arg, to accommodate
hash-table and list membership checks, maybe we should
allow callers to specify a :key arg as well.  In that
case, instead of adding optional TEST and KEY args we
would presumably want to use `cl-defun' and allow
keyword args :test and :key.

What do you think?  I realize that this now is about
redesigning this function a bit, and we (I, at least)
have little knowledge of why this function was added.

Still, it seems like its basic purpose would benefit
from letting you use different :key as well as :test.
___

Until I discovered that the function was in the manual
I was wondering, since this function seems so messed up
and unclear, if we should just remove it.  Now I think
we should maybe just fix it by using `cl-defun'.

Another thing (maybe even the main thing) that's
confusing about this function is its name.

This function is about a special kind of ordering:
the "order" you specify for an element is more of a
kind of "score".  It doesn't directly reflect
(correspond to) the list position of an element.
And the function is not so much about adding an
an element to a list as it is recording the score of
an element (a score used to determine its order in the
list).  And besides the function being able to record
such a score for an element, it can also _remove_ its
score.  (So it's not even necessarily about "adding"
a score.
___

Googling for this function (which is how I accidentally
came across it in the Elisp manual), I see that others
have been confused by its behavior and (IIUC) its aim.
E.g.:

https://stackoverflow.com/q/22440069/729907

I've added an answer to that question here, to clarify
some of its confusion.

https://stackoverflow.com/a/65523104/729907

And I've added a clarification answer to the emacs.SE
question (which provoked this bug report), as well:

https://emacs.stackexchange.com/a/62542/105