emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

lispref/variables.texi


From: Luc Teirlinck
Subject: lispref/variables.texi
Date: Thu, 23 Jun 2005 20:08:02 -0500 (CDT)

I propose the following changes to the description  of
`add-to-ordered' list in variables.texi.  I can install if desired.

The current description and example seem to suggest that adding an
element without numeric order always _appends_ the element to the
list, which is false.  The new description suggests that the order of
elements without numeric order, or of elements with the same tied
numeric order, is unspecified, even though it strictly speaking is
predictable.  But I believe that the idea is that the order of such
elements does not matter.  I replaced a redundant part of the example
(exactly the same @r{Move @code{b}.} point is made a few lines above)
with an example showing that a nil ORDER does not always append (as
@r{Append @code{d}.} misleadingly suggests.

===File ~/variables.texi-diff===============================
*** variables.texi      20 Jun 2005 17:10:57 -0500      1.66
--- variables.texi      23 Jun 2005 19:18:34 -0500      
***************
*** 909,927 ****
  position specified by @var{order}.  If @var{element} is already a
  member of the list, its position in the list is adjusted according
  to @var{order}.  Membership is tested using @code{eq}.
! The valued returned is the resulting list, whether updated or not.
  
! The @var{order} is a number, and the elements on list are sorted in
! increasing numerical order.  Elements without a numeric list order are
! placed at the end of @var{symbol}.
  
  The argument @var{symbol} is not implicitly quoted;
  @code{add-to-ordered-list} is an ordinary function, like @code{set}
  and unlike @code{setq}.  Quote the argument yourself if that is what
  you want.
  
! The ordering information is stored in an alist on @var{symbol}'s
! @code{list-order} property.
  @end defun
  
  Here's a scenario showing how to use @code{add-to-ordered-list}:
--- 909,933 ----
  position specified by @var{order}.  If @var{element} is already a
  member of the list, its position in the list is adjusted according
  to @var{order}.  Membership is tested using @code{eq}.
! This function returns the resulting list, whether updated or not.
  
! The @var{order} is a number, and the elements of the list are sorted
! in non-decreasing numerical order.  @var{order} may also be omitted or
! @code{nil}.  Then the numeric order of @var{element} stays unchanged
! if it already has one; otherwise, @var{element} has no numeric order.
! Elements without a numeric list order are placed at the end of
! the list, in no particular order.
  
  The argument @var{symbol} is not implicitly quoted;
  @code{add-to-ordered-list} is an ordinary function, like @code{set}
  and unlike @code{setq}.  Quote the argument yourself if that is what
  you want.
  
! The ordering information is stored in a hash table on @var{symbol}'s
! @code{list-order} property.  You can change the numeric list order of
! an element by a new call to @code{add-to-ordered-list}, but the only
! way to remove the numeric order of an element once it has one is to
! manipulate the internal hash table directly.
  @end defun
  
  Here's a scenario showing how to use @code{add-to-ordered-list}:
***************
*** 945,955 ****
  (add-to-ordered-list 'foo 'd)       ;; @r{Append @code{d}.}
       @result{} (a c b d)
  
! (add-to-ordered-list 'foo 'b 2)     ;; @r{Move @code{b}.}
!      @result{} (a b c d)
  
  foo                       ;; @address@hidden was changed.}
!      @result{} (a b c d)
  @end example
  
  @node Variable Scoping
--- 951,961 ----
  (add-to-ordered-list 'foo 'd)       ;; @r{Append @code{d}.}
       @result{} (a c b d)
  
! (add-to-ordered-list 'foo 'e)       ;; @r{Add @code{e}}.
!      @result{} (a c b e d)
  
  foo                       ;; @address@hidden was changed.}
!      @result{} (a c b e d)
  @end example
  
  @node Variable Scoping
============================================================




reply via email to

[Prev in Thread] Current Thread [Next in Thread]