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

Hi Robert,

I have a few problems with the formulations:

> 
>  -- Function: sort (<L>, <P>)
>  -- Function: sort (<L>)
>      Sorts a list <L> according to a predicate `P' of two arguments,
>      such that `<P>(<L>[k + 1], <L>[k])' is `false' for any two
>      successive elements.  The predicate may be specified as the name
>      of a function or binary infix operator, or as a `lambda'
>      expression.  If specified as the name of an operator, the name is
>      enclosed in "double quotes".
>

I do not understand the last sentence: I guess it should be "the name must
be enclosed in "double quotes"."
 
>      The sorted list is returned as a new object; the argument <L> is
>      not modified.  To construct the return value, `sort' makes a
>      shallow copy of the elements of <L>.
> 
>      It is assumed the predicate <P> is a strict total order on the
>      elements of <L>.  If not, `sort' might run to completion without
>      error, but the result is undefined.  `sort' complains if the
>      predicate evaluates to something other than `true' or `false'.
> 
>      `sort' is a stable sort: if two elements <x> and <y> are
>      equivalent in the sense that `<P>(<x>, <y>)' and `<P>(<y>, <x>)'
>      are both `false', then the relative order of <x> and <y> in <L> is
>      preserved by `sort'.
> 
>      `sort (<L>)' is equivalent to `sort (<L>, orderlessp)'.  That is,
>      the default sorting order is ascending, as determined by
>      `orderlessp'.    All Maxima atoms and expressions are comparable
>      under `orderlessp'.
> 
>      The predicate `ordergreatp' sorts a list in descending order.  The
>      predicate `ordermagnitudep' sorts Maxima numbers, constant symbols
>      with a numerical value, or expressions which can be evaluated to a
>      constant by magnitude.

What is the difference between ordergreatp and ordermagnitudep ?
Actually, one should ask what is the difference between orderlessp
and ordermagnitudep; is the former more general? What is the recommendation?

In general I think that such a list of sentences, when not actually shown that
we have a list of independent sentences, is rather misleading.

There seems to be some prejudice against the use of real lists (with some
form of enumeration or bullets), for example it seems at Wikipedia the opinion
is that paragraphs are to be preferred --- I think exactly the opposite is true:
lists, enumerations etc. are great, paragraphs are bad (if there is not really
a strong connection between the sentences, and often in technical writing
there is actually not much connection between the sentences).

>  All other elements of the list <L> are
>      sorted by `orderlessp'.

To what does "All other elements" refer to? There are two sentences in the paragraph
before this statement, but I can't see how "All other elements" refer to them.
And I can't see what these "other elements" are.

>  The predicate `"<"' allows the ordering
>      by magnitude too, but does not order completely if elements in the
>      list <L> are not comparable under `"<"'.

Shouldn't one say "but is not applicable if ..."?
"does not order completely" sounds "kind of okayish".

Oliver