unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* lispref/variables.texi
@ 2005-06-24  1:08 Luc Teirlinck
  2005-06-24  8:14 ` lispref/variables.texi Kim F. Storm
  2005-06-24 16:37 ` lispref/variables.texi Richard M. Stallman
  0 siblings, 2 replies; 4+ messages in thread
From: Luc Teirlinck @ 2005-06-24  1:08 UTC (permalink / raw)


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
============================================================

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2005-06-25  0:56 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-06-24  1:08 lispref/variables.texi Luc Teirlinck
2005-06-24  8:14 ` lispref/variables.texi Kim F. Storm
2005-06-25  0:56   ` lispref/variables.texi Luc Teirlinck
2005-06-24 16:37 ` lispref/variables.texi Richard M. Stallman

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).