lists.texi

[Luc Teirlinck]

I recommend the following changes to lists.texi and can install if
desired.  In as far as spelling issues are concerned, `vs' seems to be
the standard abbreviation of `versus' and `indices' seems to be the plural
form of `index' consistently used in the Elisp manual.

In as far as the return value of `ring-insert-at-beginning' is
concerned, it definitely is _not_ OBJECT as currently documented in
the Elips manual.  The return value is the _new_ length of the ring,
but this seems to be by accident, rather than by design.  We could
either document the actual return value, change
`ring-insert-at-beginning' to really return OBJECT (does not seem
terribly useful to me) or say that the return value is not
significant.  The patch below does the latter.

===File ~/lists.texi-diff===================================
*** lists.texi  17 Jun 2005 09:08:29 -0500      1.52
--- lists.texi  18 Jun 2005 16:58:45 -0500      
***************
*** 715,721 ****
  primitives @code{setcar} and @code{setcdr}.  We call these ``destructive''
  operations because they change existing list structure.
  
! @cindex CL address@hidden vrs @code{setcar}
  @quotation
  @findex rplaca
  @findex rplacd
--- 715,721 ----
  primitives @code{setcar} and @code{setcdr}.  We call these ``destructive''
  operations because they change existing list structure.
  
! @cindex CL address@hidden vs @code{setcar}
  @quotation
  @findex rplaca
  @findex rplacd
***************
*** 1691,1697 ****
  @end defun
  
  @defun ring-p object
! This returns @code{t} if @var{object} is a ring.
  @end defun
  
  @defun ring-size ring
--- 1691,1697 ----
  @end defun
  
  @defun ring-p object
! This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
  @end defun
  
  @defun ring-size ring
***************
*** 1705,1725 ****
  
  @defun ring-elements ring
  This returns a list of the objects in @var{ring}, in no particular
! order.
  @end defun
  
  @defun ring-copy ring
  This returns a new ring which is a copy of @var{ring}.
! The new ring contains the same objects as @var{ring}.
  @end defun
  
  @defun ring-empty-p ring
! This returns @code{t} if @var{ring} is empty.
  @end defun
  
!   The newest element in the ring always has index 0.  Higher indexes
! correspond to older elements.  Index @minus{}1 corresponds to the
! oldest element, @minus{}2 to the next-oldest, and so forth.
  
  @defun ring-ref ring index
  This returns the object in @var{ring} found at index @var{index}.
--- 1705,1728 ----
  
  @defun ring-elements ring
  This returns a list of the objects in @var{ring}, in no particular
! order.  The length of that list is always the ring size.  If the ring
! length is less than the ring size, the entries of the list that do not
! correspond to ring elements are @code{nil}.
  @end defun
  
  @defun ring-copy ring
  This returns a new ring which is a copy of @var{ring}.
! The new ring contains the same (@code{eq}) objects as @var{ring}.
  @end defun
  
  @defun ring-empty-p ring
! This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
  @end defun
  
!   The newest element in the ring always has index 0.  Higher indices
! correspond to older elements.  Indices are computed modulo the ring
! length.  Index @minus{}1 corresponds to the oldest element, @minus{}2
! to the next-oldest, and so forth.
  
  @defun ring-ref ring index
  This returns the object in @var{ring} found at index @var{index}.
***************
*** 1744,1750 ****
  
  @defun ring-insert-at-beginning ring object
  This inserts @var{object} into @var{ring}, treating it as the oldest
! element, and returns @var{object}.
  
  If the ring is full, this function removes the newest element to make
  room for the inserted element.
--- 1747,1753 ----
  
  @defun ring-insert-at-beginning ring object
  This inserts @var{object} into @var{ring}, treating it as the oldest
! element.  The return value is not significant.
  
  If the ring is full, this function removes the newest element to make
  room for the inserted element.
============================================================