--- a/man/lispref/lists.texi	Mon Mar 29 23:23:33 2010 -0500
+++ b/man/lispref/lists.texi	Thu Apr 01 20:22:50 2010 +0100
@@ -1050,31 +1050,54 @@
 @end smallexample
 @end defun
 
-@defun sort list predicate
+@defun sort* sequence predicate &key (key #'identity)
 @cindex stable sort
 @cindex sorting lists
-This function sorts @var{list} stably, though destructively, and
-returns the sorted list.  It compares elements using @var{predicate}.  A
+@cindex sorting arrays
+@cindex sort
+This function sorts @var{sequence} stably, though destructively, and
+returns the sorted sequence.  It compares elements using @var{predicate}.  A
 stable sort is one in which elements with equal sort keys maintain their
 relative order before and after the sort.  Stability is important when
 successive sorts are used to order elements according to different
 criteria.
 
+@var{sequence} can be any sequence, that is, a list, a vector, a
+bit-vector, or a string.  
+
 The argument @var{predicate} must be a function that accepts two
-arguments.  It is called with two elements of @var{list}.  To get an
+arguments.  It is called with two elements of @var{sequence}.  To get an
 increasing order sort, the @var{predicate} should return @code{t} if the
 first element is ``less than'' the second, or @code{nil} if not.
 
-The destructive aspect of @code{sort} is that it rearranges the cons
-cells forming @var{list} by changing @sc{cdr}s.  A nondestructive sort
+The keyword argument @var{key}, if supplied, is a function used to
+extract an object to be used for comparison from each element of
+@var{sequence}, and defaults to @code{identity}.  For example, to sort a
+vector of lists by the numeric value of the first element, you could use
+the following code:
+
+@example
+@group
+(setq example-vector [(1 "foo") (3.14159 bar) (2 . quux)])
+     @result{} [(1 "foo") (3.14159 bar) (2 . quux)]
+@end group
+@group
+(sort* example-vector #'< :key #'car)
+     @result{} [(1 "foo") (2 . quux) (3.14159 bar)]
+@end group
+@end example
+
+If @var{sequence} is a list, @code{sort*} rearranges the cons cells
+forming @var{sequence} by changing @sc{cdr}s.  A nondestructive sort
 function would create new cons cells to store the elements in their
-sorted order.  If you wish to make a sorted copy without destroying the
+sorted order.  @code{sort*} treats other sequence types in an analogous
+fashion---if you wish to make a sorted copy without destroying the
 original, copy it first with @code{copy-sequence} and then sort.
 
-Sorting does not change the @sc{car}s of the cons cells in @var{list};
-the cons cell that originally contained the element @code{a} in
-@var{list} still has @code{a} in its @sc{car} after sorting, but it now
-appears in a different position in the list due to the change of
+Sorting will not change the @sc{car}s of the cons cells of a list
+@var{sequence}; the cons cell that originally contained the element @code{a} in
+@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now
+appears in a different position in the sequence due to the change of
 @sc{cdr}s.  For example:
 
 @example
@@ -1083,7 +1106,7 @@
      @result{} (1 3 2 6 5 4 0)
 @end group
 @group
-(sort nums '<)
+(sort* nums '<)
      @result{} (0 1 2 3 4 5 6)
 @end group
 @group
@@ -1096,17 +1119,23 @@
 Note that the list in @code{nums} no longer contains 0; this is the same
 cons cell that it was before, but it is no longer the first one in the
 list.  Don't assume a variable that formerly held the argument now holds
-the entire sorted list!  Instead, save the result of @code{sort} and use
+the entire sorted list!  Instead, save the result of @code{sort*} and use
 that.  Most often we store the result back into the variable that held
-the original list:
+the original sequence:
 
 @example
-(setq nums (sort nums '<))
+(setq nums (sort* nums '<))
 @end example
 
+In this implementation, @code{sort} is a function alias for
+@code{sort*}, and accepts the same arguments.  In older XEmacs, and in
+current GNU Emacs, @code{sort} only accepted lists, and did not accept
+the @var{key} argument, so the byte-compiler will warn you if you call
+@code{sort} with more than two arguments.
+
 @xref{Sorting}, for more functions that perform sorting.
 See @code{documentation} in @ref{Accessing Documentation}, for a
-useful example of @code{sort}.
+useful example of @code{sort*}.
 @end defun
 
 @node Sets And Lists