inconsistent definition of "sort" (and what about stability?)

Oliver Kullmann <O.Kullmann at swansea.ac.uk> wrote:

   Obviously, I am referring to the MAXIMA documentation:

(I'm in danger of acting like a troll, which is not my intention.
Apology in advance.)

This appears to be the definition of maxima sort:

  (defmfun $sort (l &optional (f 'lessthan))
    (let ((llist l) comparfun bfun ($prederror t))
      (unless ($listp llist)
	(merror (intl:gettext "sort: first argument must be a list; found: ~M") llist))
      (setq llist (copy-list (cdr llist))
	    comparfun 
	    (mfunction1 (setq bfun (getopr f))))
      (when (member bfun '(lessthan great) :test #'eq)
	(setq llist (mapcar #'ratdisrep llist)))
      (cons '(mlist) (sort llist comparfun))))

Despite the murk of the Maxima documentation (which probably predates
the ANS) all the actual sorting is performed by the Common Lisp sort
function.  (Significant exception is that Maxima sort is
non-destructive, which CL sort is allowed to be destuctive.)  So if you
want to know how sort behaves in these various edge cases with a
conforming ANSI CL, the ANS is where you'd have to look.

BTW, the ANS informally defines sort tability.  The function cl:sort
does not guarantee stability, which cl:stable-sort does.  On some
implemnentations, perhaps most. these functions are the same.

(Yes, in a more-perfect world, Maxima documentation would be accurate,
complete, and current.  If so, then this world must fail to be at least
one of the above.  I hope this won't come as a shock to anyone.)

So the current question could be resolved with one of these three choices:

1) Rewrite $sort to conform to the Maxima documentation, in a way that
   is portable to all ANSI-conformant implementations.

2) Rewrite the documentation to agree (other than the copy-list) with
   the ANSI definition.

3) Ignore this minor discrepency for the time being, because more
   important issues require atention in Maxima source and documentation.

I guess (3) could be essentially a troll, but these choices offerred
sincerely.  Sorry about that.