From bb6b0efc3490a1e47e69e3afbc115576025f3606 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 9 Sep 2012 15:50:45 +0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 3 +++ doc/lispref/lists.texi | 33 +++++++++++++++++++++------------ 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 79691bfb18..ceb199dae8 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,8 @@ 2012-09-09 Chong Yidong + * 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. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 023f8ba18d..d685ce0aa7 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1293,14 +1293,19 @@ compare @var{object} against the elements of the list. For example: @defun delq object list @cindex deleting list elements This function destructively removes all elements @code{eq} to -@var{object} 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}. +@var{object} from @var{list}, and returns the resulting 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}. + +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 @@ after those elements: @end group @end example +@noindent 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 @@ Compare this with @code{memq}: @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, -@code{delete} is to @code{delq} as @code{member} 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. +This function removes all elements @code{equal} to @var{object} from +@var{sequence}, and returns the resulting sequence. + +If @var{sequence} is a list, @code{delete} is to @code{delq} as +@code{member} 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} -- 2.20.1