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 ;; @[EMAIL PROTECTED] 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 ;; @[EMAIL PROTECTED] was changed.}
! @result{} (a c b e d)
@end example
@node Variable Scoping
============================================================
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
