* 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
* Re: lispref/variables.texi 2005-06-24 1:08 lispref/variables.texi Luc Teirlinck @ 2005-06-24 8:14 ` Kim F. Storm 2005-06-25 0:56 ` lispref/variables.texi Luc Teirlinck 2005-06-24 16:37 ` lispref/variables.texi Richard M. Stallman 1 sibling, 1 reply; 4+ messages in thread From: Kim F. Storm @ 2005-06-24 8:14 UTC (permalink / raw) Cc: emacs-devel 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: lispref/variables.texi 2005-06-24 8:14 ` lispref/variables.texi Kim F. Storm @ 2005-06-25 0:56 ` Luc Teirlinck 0 siblings, 0 replies; 4+ messages in thread From: Luc Teirlinck @ 2005-06-25 0:56 UTC (permalink / raw) Cc: emacs-devel 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 ============================================================ ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: lispref/variables.texi 2005-06-24 1:08 lispref/variables.texi Luc Teirlinck 2005-06-24 8:14 ` lispref/variables.texi Kim F. Storm @ 2005-06-24 16:37 ` Richard M. Stallman 1 sibling, 0 replies; 4+ messages in thread From: Richard M. Stallman @ 2005-06-24 16:37 UTC (permalink / raw) Cc: emacs-devel These changes are good. ^ 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 external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.