Re: lispref/variables.texi

[Luc Teirlinck]

Kim Storm wrote:

   To "remove" the order, you can specify a non-nil, non-numeric value
   for ORDER -- in that case, the element's order in the hash table is
   set to nil (which effitively means "no" ordering).

I actually did not know that.  Then a few further changes to
variables.texi are needed, as well as some changes to the
add-to-ordered-list docstring.  The current docs suggest that only
numbers or nil values for ORDER are allowed.  On an unrelated note,
the first lines of the docstrings of both add-to-ordered-list and
add-to-list needlessly exceed the maximum allowed 67 characters.  I
believe that the shortened versions in the patch below are actually
not only shorter, but better readable as well.

Below are a proposed new patch to subr.el and a slightly revised
version of my patch to variables.texi.

===File ~/subr.el-diff======================================
*** subr.el     22 Jun 2005 18:21:04 -0500      1.468
--- subr.el     24 Jun 2005 19:22:52 -0500      
***************
*** 937,943 ****
          (set hook hook-value))))))
  
  (defun add-to-list (list-var element &optional append)
!   "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet.
  The test for presence of ELEMENT is done with `equal'.
  If ELEMENT is added, it is added at the beginning of the list,
  unless the optional argument APPEND is non-nil, in which case
--- 937,943 ----
          (set hook hook-value))))))
  
  (defun add-to-list (list-var element &optional append)
!   "Add ELEMENT to the value of LIST-VAR if it isn't there yet.
  The test for presence of ELEMENT is done with `equal'.
  If ELEMENT is added, it is added at the beginning of the list,
  unless the optional argument APPEND is non-nil, in which case
***************
*** 959,973 ****
  
  
  (defun add-to-ordered-list (list-var element &optional order)
!   "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet.
  The test for presence of ELEMENT is done with `eq'.
  
  The resulting list is reordered so that the elements are in the
  order given by each element's numeric list order.  Elements
  without a numeric list order are placed at the end of the list.
  
! If the third optional argument ORDER is non-nil, set the
! element's list order to the given value.
  
  The list order for each element is stored in LIST-VAR's
  `list-order' property.
--- 959,976 ----
  
  
  (defun add-to-ordered-list (list-var element &optional order)
!   "Add ELEMENT to the value of LIST-VAR if it isn't there yet.
  The test for presence of ELEMENT is done with `eq'.
  
  The resulting list is reordered so that the elements are in the
  order given by each element's numeric list order.  Elements
  without a numeric list order are placed at the end of the list.
  
! If the third optional argument ORDER is a number (integer or
! float), set the element's list order to the given value.  If
! ORDER is nil or omitted, do not change the numeric order of
! ELEMENT.  If ORDER has any other value, remove the numeric order
! of ELEMENT if it has one.
  
  The list order for each element is stored in LIST-VAR's
  `list-order' property.
============================================================

===File ~/variables.texi-diff===============================
*** variables.texi      20 Jun 2005 17:10:57 -0500      1.66
--- variables.texi      24 Jun 2005 19:17:50 -0500      
***************
*** 909,926 ****
  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
  
--- 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 typically a number (integer or float), 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.
! 
! Any other value for @var{order} removes the numeric order of @var{element}
! if it already has one; otherwise, it is equivalent to @code{nil}.
  
  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.
  @end defun
  
***************
*** 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
--- 952,962 ----
  (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
============================================================