lispref/variables.texi

lispref/variables.texi

[Luc Teirlinck]

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                       ;; @r{@code{foo} 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                       ;; @r{@code{foo} was changed.}
!      @result{} (a c b e d)
  @end example
  
  @node Variable Scoping
============================================================

Re: lispref/variables.texi

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

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

These are good changes (with a few corrections).  Please install.

> ! 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.

I suggest breaking that up for clarity:


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.


> ! 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.


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).

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: lispref/variables.texi

[Richard M. Stallman]

These changes are good.

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                       ;; @r{@code{foo} 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                       ;; @r{@code{foo} was changed.}
!      @result{} (a c b e d)
  @end example
  
  @node Variable Scoping
============================================================