* doc/lispref/sequences.texi (Sequence Functions): Copyedits.

2 files changed, 77 insertions, 152 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 84654387dcd..56a073035cf 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2014-12-25  Glenn Morris  <rgm@gnu.org>
 
+        * sequences.texi (Sequence Functions): Copyedits.
+
         * control.texi (Pattern matching case statement):
         * positions.texi (List Motion):
         * streams.texi (Output Functions):
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 8f8cfe72fa3..b1e315c7987 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -217,14 +217,14 @@ y @result{} [foo (69 2)]
 @end example
 @end defun
 
-@defun reverse seq
+@defun reverse sequence
 @cindex string reverse
 @cindex list reverse
 @cindex vector reverse
 @cindex sequence reverse
 This function creates a new sequence whose elements are the elements
-of @var{seq}, but in reverse order.  The original argument @var{seq}
-is @emph{not} altered.   Note that char-table cannot be reversed.
+of @var{sequence}, but in reverse order.  The original argument @var{sequence}
+is @emph{not} altered.  Note that char-tables cannot be reversed.
 
 @example
 @group
@@ -260,12 +260,12 @@ x
 @end example
 @end defun
 
-@defun nreverse seq
+@defun nreverse sequence
 @cindex reversing a string
 @cindex reversing a list
 @cindex reversing a vector
-  This function reverses the order of the elements of @var{seq}.
-Unlike @code{reverse} the original @var{seq} may be modified.
+  This function reverses the order of the elements of @var{sequence}.
+Unlike @code{reverse} the original @var{sequence} may be modified.
 
   For example:
 
@@ -421,22 +421,20 @@ useful example of @code{sort}.
 
 @cindex sequence functions in seq
 @cindex seq library
-  The @file{seq} library provides the following additional sequence
+  The @file{seq.el} library provides the following additional sequence
 manipulation macros and functions, prefixed with @code{seq-}.  To use
-them, you need to load the @file{seq} library first.
+them, you must first load the @file{seq} library.
 
-  All functions defined in the @code{seq} library are free of
-side-effects, meaning that sequence(s) passed as argument(s) to
-functions defined in @code{seq} are not modified.
+  All functions defined in this library are free of side-effects;
+i.e., they do not modify any sequence (list, vector, or string) that
+you pass as an argument.  Unless otherwise stated, the result is a
+sequence of the same type as the input.  For those functions that take
+a predicate, this should be a function of one argument.
 
-@defun seq-drop seq n
-  This function returns a sequence of all but the first @var{n}
-elements of the sequence @var{seq}.
-
-@var{seq} may be a list, vector or string and @var{n} must be an
-integer.  The result is the same type of sequence as @var{seq}.
-
-If @var{n} is a negative integer or zero, @var{seq} is returned.
+@defun seq-drop sequence n
+  This function returns all but the first @var{n} (an integer)
+elements of @var{sequence}.  If @var{n} is negative or zero,
+the result is @var{sequence}.
 
 @example
 @group
@@ -450,14 +448,10 @@ If @var{n} is a negative integer or zero, @var{seq} is returned.
 @end example
 @end defun
 
-@defun seq-take seq n
-  This function returns a sequence of the first @var{n} elements of
-@var{seq}.
-
-@var{seq} may be a list, vector or string and @var{n} must be an
-integer.  The result is the same type of sequence as @var{seq}.
-
-If @var{n} is a negative integer or zero, an empty sequence is returned.
+@defun seq-take sequence n
+  This function returns the first @var{n} (an integer) elements of
+@var{sequence}.  If @var{n} is negative or zero, the result
+is @code{nil}.
 
 @example
 @group
@@ -471,17 +465,9 @@ If @var{n} is a negative integer or zero, an empty sequence is returned.
 @end example
 @end defun
 
-@defun seq-take-while pred seq
-  This function returns a sub-sequence of the successive elements of
-@var{seq} for which calling @code{pred} with that element returns
-non-nil.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.  The result is the same type of sequence as
-@var{seq}.
-
-If evaluating @var{pred} with the first element of @var{seq} as argument
-returns @code{nil}, an empty sequence is returned.
+@defun seq-take-while predicate sequence
+  This function returns the members of @var{sequence} in order,
+stopping before the first one for which @var{predicate} returns @code{nil}.
 
 @example
 @group
@@ -495,17 +481,9 @@ returns @code{nil}, an empty sequence is returned.
 @end example
 @end defun
 
-@defun seq-drop-while pred seq
-  This function returns a sub-sequence of @var{seq} from the first
-element for which calling @var{pred} with that element returns
-@code{nil}.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.  The result is the same type of sequence as
-@var{seq}.
-
-If evaluating @var{pred} with every element of @var{seq} returns
-@code{nil}, @var{seq} is returned.
+@defun seq-drop-while predicate sequence
+  This function returns the members of @var{sequence} in order,
+starting from the first one for which @var{predicate} returns @code{nil}.
 
 @example
 @group
@@ -519,13 +497,10 @@ If evaluating @var{pred} with every element of @var{seq} returns
 @end example
 @end defun
 
-@defun seq-filter pred seq
+@defun seq-filter predicate sequence
 @cindex filtering sequences
-  This function returns a list of all the elements in @var{seq} for
-which calling @var{pred} with that element returns non-nil.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.
+  This function returns a list of all the elements in @var{sequence}
+for which @var{predicate} returns non-@code{nil}.
 
 @example
 @group
@@ -539,13 +514,10 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-remove pred seq
+@defun seq-remove predicate sequence
 @cindex removing from sequences
-  This function returns a list of all the elements in @var{seq} for
-which calling @var{pred} with that element returns @code{nil}.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.
+  This function returns a list of all the elements in @var{sequence}
+for which @var{predicate} returns @code{nil}.
 
 @example
 @group
@@ -559,18 +531,15 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-reduce function seq initial-value
+@defun seq-reduce function sequence initial-value
 @cindex reducing sequences
   This function returns the result of calling @var{function} with
-@var{initial-value} and the first element of @var{seq}, then calling
-@var{function} with that result and the second element of @var{seq},
-then with that result and the third element of @var{seq}, etc.
-
-@var{function} must be a two-arguments function and @var{seq} may be a
-list, vector or string.
-
-If @var{seq} is empty, @var{initial-value} is returned and
-@var{function} is not called.
+@var{initial-value} and the first element of @var{sequence}, then calling
+@var{function} with that result and the second element of @var{sequence},
+then with that result and the third element of @var{sequence}, etc.
+@var{function} should be a function of two arguments.  If
+@var{sequence} is empty, this returns @var{initial-value} without
+calling @var{function}.
 
 @example
 @group
@@ -588,14 +557,9 @@ If @var{seq} is empty, @var{initial-value} is returned and
 @end example
 @end defun
 
-@defun seq-some-p pred seq
-  This function returns any element in @var{seq} for which calling
-@var{pred} with that element returns non-nil.  If successively calling
-@var{pred} with each element of @var{seq} always returns @code{nil},
-@code{nil} is returned.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.
+@defun seq-some-p predicate sequence
+  This function returns the first member of sequence for which @var{predicate}
+returns non-@code{nil}.
 
 @example
 @group
@@ -609,12 +573,9 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-every-p pred seq
-  This function returns non-nil if successively calling @var{pred} with
-each element of @var{seq} always returns non-nil, @code{nil} otherwise.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.
+@defun seq-every-p predicate sequence
+  This function returns non-@code{nil} if applying @var{predicate}
+to every element of @var{sequence} returns non-@code{nil}.
 
 @example
 @group
@@ -628,11 +589,8 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-empty-p seq
-  This function returns non-nil if the sequence @var{seq} is empty,
-@code{nil} otherwise.
-
-@var{seq} may be a list, vector or string.
+@defun seq-empty-p sequence
+  This function returns non-@code{nil} if @var{sequence} is empty.
 
 @example
 @group
@@ -646,12 +604,9 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-count pred seq
-  This function returns the number of elements in @var{seq} for which
-calling @var{pred} with that element returns non-nil.
-
-@var{pred} must be a one-argument function and @var{seq} may be a
-list, vector or string.
+@defun seq-count predicate sequence
+  This function returns the number of elements in @var{sequence} for which
+@var{predicate} returns non-@code{nil}.
 
 @example
 (seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
@@ -659,27 +614,17 @@ list, vector or string.
 @end example
 @end defun
 
-@defun seq-sort pred seq
-  This function returns a sorted sequence of the elements of
-@var{seq}, comparing its elements with @var{pred}.  Called with two
-elements of @var{seq}, @var{pred} should return non-nil if the first
-element should sort before the second.
-
-@var{pred} must be a two-arguments function, @var{seq} may be a list,
-vector or string.
-
-The result is a sequence of the same type as SEQ.
 @cindex sorting sequences
+@defun seq-sort function sequence
+  This function returns a copy of @var{sequence} that is sorted
+according to @var{function}, a function of two arguments that returns
+non-@code{nil} if the first argument should sort before the second.
 @end defun
 
-@defun seq-contains-p seq elt testfn
-  This function returns the first element in @var{seq} that equals to
-@var{elt}.
-
-Equality is defined by @var{testfn} if non-nil or by @code{equal} if
-@code{nil}.
-
-@var{seq} may be a list, vector or string.
+@defun seq-contains-p sequence elt &optional function
+  This function returns the first element in @var{sequence} that is equal to
+@var{elt}.  If the optional argument @var{function} is non-@code{nil},
+it is a function of two arguments to use instead of the default @code{equal}.
 
 @example
 @group
@@ -694,13 +639,10 @@ Equality is defined by @var{testfn} if non-nil or by @code{equal} if
 
 @end defun
 
-@defun seq-uniq seq testfn
-  This function returns a list of the elements of @var{seq} with
-duplicates removed.  @var{testfn} is used to compare elements, or
-@code{equal} if @var{testfn} is @code{nil}.
-
-@var{testfn} must be a two-argument function or @code{nil} and
-@var{seq} may be a list, vector or string.
+@defun seq-uniq sequence &optional function
+  This function returns a list of the elements of @var{sequence} with
+duplicates removed.  If the optional argument @var{function} is non-@code{nil},
+it is a function of two arguments to use instead of the default @code{equal}.
 
 @example
 @group
@@ -714,14 +656,11 @@ duplicates removed.  @var{testfn} is used to compare elements, or
 @end example
 @end defun
 
-@defun seq-subseq seq start &optional end
-  This function returns a sub-sequence of @var{seq} from @var{start}
-to @var{end}.  If @var{end} is omitted, it default to the length of
-@var{seq}. If @var{start} or @var{end} is negative, it counts from
-the end of @var{seq}.
-
-@var{seq} may be a list, vector or string.
-The result is the same type of sequence as @var{seq}.
+@defun seq-subseq sequence start &optional end
+  This function returns a subset of @var{sequence} from @var{start}
+to @var{end}, both integers (@var{end} defaults to the last element).
+If @var{start} or @var{end} is negative, it counts from the end of
+@var{sequence}.
 
 @example
 @group
@@ -739,11 +678,10 @@ The result is the same type of sequence as @var{seq}.
 @end example
 @end defun
 
-@defun seq-concatenate type &rest seqs
-  This function returns a sequence made of the concatenation of
-@var{seqs}.  The result is a sequence of type @var{type}.  @var{type}
-may be one of the following symbols: @code{vector}, @code{list} or
-@code{string}.
+@defun seq-concatenate type &rest sequences
+  This function returns a sequence of type @var{type} made of the
+concatenation of @var{sequences}.  @var{type} may be: @code{vector},
+@code{list} or @code{string}.
 
 @example
 @group
@@ -757,26 +695,11 @@ may be one of the following symbols: @code{vector}, @code{list} or
 @end example
 @end defun
 
-@defmac seq-doseq (var seq [result]) body@dots{}
+@defmac seq-doseq (var sequence [result]) body@dots{}
 @cindex sequence iteration
-This macro is like @code{dolist}, except that @var{seq} can be a list,
+This macro is like @code{dolist}, except that @var{sequence} can be a list,
 vector or string (@pxref{Iteration} for more information about the
-@code{dolist} macro).
-
-@var{seq-doseq} is primarily useful for side-effects.
-
-@example
-(seq-doseq (elt [1 2 3])
-  (print (* 2 elt)))
-  @print{}
-  @print{} 2
-  @print{}
-  @print{} 4
-  @print{}
-  @print{} 6
-  @result{} nil
-
-@end example
+@code{dolist} macro).  This is primarily useful for side-effects.
 @end defmac
 
 @node Arrays