[Emacs-diffs] /srv/bzr/emacs/trunk r109952: Clarify descriptions of delq and delete in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 109952
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-09-09 15:50:45 +0800
message:
  Clarify descriptions of delq and delete in Lisp manual.
  
  * doc/lispref/lists.texi (Sets And Lists): Explain that the return value for
  delete should be used, like for delq.
modified:
  doc/lispref/ChangeLog
  doc/lispref/lists.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-09 06:43:47 +0000
+++ b/doc/lispref/ChangeLog     2012-09-09 07:50:45 +0000
@@ -1,5 +1,8 @@
 2012-09-09  Chong Yidong  <address@hidden>
 
+       * lists.texi (Sets And Lists): Explain that the return value for
+       delete should be used, like for delq.
+
        * minibuf.texi (Yes-or-No Queries): Document recentering and
        scrolling in y-or-n-p.  Remove gratuitous example.
 

=== modified file 'doc/lispref/lists.texi'
--- a/doc/lispref/lists.texi    2012-05-27 01:34:14 +0000
+++ b/doc/lispref/lists.texi    2012-09-09 07:50:45 +0000
@@ -1293,14 +1293,19 @@
 @defun delq object list
 @cindex deleting list elements
 This function destructively removes all elements @code{eq} to
address@hidden from @var{list}.  The letter @samp{q} in @code{delq} says
-that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq} and @code{remq}.
address@hidden from @var{list}, and returns the resulting list.  The
+letter @samp{q} in @code{delq} says that it uses @code{eq} to compare
address@hidden against the elements of the list, like @code{memq} and
address@hidden
+
+Typically, when you invoke @code{delq}, you should use the return
+value by assigning it to the variable which held the original list.
+The reason for this is explained below.
 @end defun
 
-When @code{delq} deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
+The @code{delq} function deletes elements from the front of the list
+by simply advancing down the list, and returning a sublist that starts
+after those elements.  For example:
 
 @example
 @group
@@ -1308,6 +1313,7 @@
 @end group
 @end example
 
address@hidden
 When an element to be deleted appears in the middle of the list,
 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
 
@@ -1432,12 +1438,15 @@
 @end defun
 
 @defun delete object sequence
-If @code{sequence} is a list, this function destructively removes all
-elements @code{equal} to @var{object} from @var{sequence}.  For lists,
address@hidden is to @code{delq} as @code{member} is to @code{memq}: it
-uses @code{equal} to compare elements with @var{object}, like
address@hidden; when it finds an element that matches, it cuts the
-element out just as @code{delq} would.
+This function removes all elements @code{equal} to @var{object} from
address@hidden, and returns the resulting sequence.
+
+If @var{sequence} is a list, @code{delete} is to @code{delq} as
address@hidden is to @code{memq}: it uses @code{equal} to compare
+elements with @var{object}, like @code{member}; when it finds an
+element that matches, it cuts the element out just as @code{delq}
+would.  As with @code{delq}, you should typically use the return value
+by assigning it to the variable which held the original list.
 
 If @code{sequence} is a vector or string, @code{delete} returns a copy
 of @code{sequence} with all elements @code{equal} to @code{object}