Jeff Sparkes <jsparkes(a)gmail.com&gt; writes: Excellent! Any chance of documentation for WHEN and DOCSTRING? (In particular, shouldn't it *do* something with WHEN?) -- Regards, Mike _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches

Michael Sperber writes: I don't see why. AFAICS WHEN is a typical GNU-style undesigned hack which only imposes a burden on developers or perhaps the release engineer. IIRC some of our define-*-alias functions already have functionality equivalent to DOCSTRING, which is obviously useful when the API changes incompatibly. Ie, what users really need is some *appropriate warning* when we make these changes. But WHEN doesn't really help with that AFAICS. (I guess it can be used to make `describe-variable' more verbose, but I'm not sure what the point is for obsolete variables which are already marked by `describe-variable'.) If *we* need to know, most likely the best resource is hg annotate. I may be missing something, though. _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches

Michael Sperber writes: Oh, I certainly agree with that. I thought the "it" in your question referred to the define-obsolete-* function itself, that maybe it should do something with WHEN. I'd rather not, as it could get rather messy, what with GNU syncs pulling in GNU version strings and package versions which don't correspond to any version of Emacs itself. I think Jeff's updated patch should be revised to say something like Optional WHEN currently does nothing in XEmacs. It is accepted for compatibility with GNU Emacs. If present, it should be a string naming the version in which the variable was first marked obsolete. and committed. _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches

Michael Sperber writes: OK, here's what I've committed. There were a couple more places where XEmacs does or could theoretically actually use the arguments (ie, the underlying functions accept them), so I changed the define-*-alias functions to do that in a couple more places than Jeff's patch did. Note that the make-{obsolete,compatible}{,-variable} functions accept both WHEN (explicitly) and DOCSTRING (when NEWFUN or NEWVAR is a string), while defvaralias accepts DOCSTRING but defalias does not. We should probably do something about this (issue850). I'm not wedded to my wording in the docstrings; feel free to clarify etc. diff -r 1003acd5a4b8 lisp/ChangeLog --- a/lisp/ChangeLog Mon Feb 04 20:03:04 2013 -0500 +++ b/lisp/ChangeLog Sat Feb 16 21:53:46 2013 +0900 ＠＠ -1,3 +1,16 ＠＠ +2013-02-16 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + Thanks to Jeff Sparkes for suggestion and the original patches and + to Mike Sperber for discussion. + + * obsolete.el (define-obsolete-function-alias): + (define-compatible-function-alias): + (define-obsolete-variable-alias): + (define-compatible-variable-alias): + Add optional WHEN and DOCSTRING arguments for GNU compatibility. + Document WHEN as ignored. Support DOCSTRING as well as the + underlying functions allow. + 2013-01-22 Jerry James <james(a)xemacs.org&gt; * glyphs.el (make-image-specifier): Document that :visible is a diff -r 1003acd5a4b8 lisp/obsolete.el --- a/lisp/obsolete.el Mon Feb 04 20:03:04 2013 -0500 +++ b/lisp/obsolete.el Sat Feb 16 21:53:46 2013 +0900 ＠＠ -36,38 +36,56 ＠＠ ;;; Code: -(defsubst define-obsolete-function-alias (oldfun newfun) +(defsubst define-obsolete-function-alias (oldfun newfun + &optional when docstring) "Define OLDFUN as an obsolete alias for function NEWFUN. This makes calling OLDFUN equivalent to calling NEWFUN and marks OLDFUN -as obsolete." +as obsolete. +Optional WHEN is for GNU compatibility. XEmacs ignores it. \(In Emacs, WHEN +is a string indicating the version where OLDFUN was first marked obsolete.) +Optional DOCSTRING describes any changes in semantics users should be aware of." (define-function oldfun newfun) - (make-obsolete oldfun newfun)) + (make-obsolete oldfun (or docstring newfun) when)) -(defsubst define-compatible-function-alias (oldfun newfun) +(defsubst define-compatible-function-alias (oldfun newfun + &optional when docstring) "Define OLDFUN as a compatible alias for function NEWFUN. This makes calling OLDFUN equivalent to calling NEWFUN and marks OLDFUN -as provided for compatibility only." +as provided for compatibility only. +Optional WHEN is for consistency with `define-obsolete-function-alias'. XEmacs +ignores it. \(If present, it is a string indicating the version where OLDFUN +was first marked as a compatibility API.) +Optional DOCSTRING describes any changes in semantics users should be aware of." (define-function oldfun newfun) - (make-compatible oldfun newfun)) + (make-compatible oldfun (or docstring newfun))) -(defsubst define-obsolete-variable-alias (oldvar newvar) +(defsubst define-obsolete-variable-alias (oldvar newvar + &optional when docstring) "Define OLDVAR as an obsolete alias for variable NEWVAR. This makes referencing or setting OLDVAR equivalent to referencing or setting NEWVAR and marks OLDVAR as obsolete. -If OLDVAR was bound and NEWVAR was not, Set NEWVAR to OLDVAR. +If OLDVAR was bound and NEWVAR was not, set NEWVAR to OLDVAR. +Note: Use this before any other references (defvar/defcustom) to NEWVAR. -Note: Use this before any other references (defvar/defcustom) to NEWVAR." +Optional WHEN is for GNU compatibility. XEmacs ignores it. \(In Emacs, WHEN +is a string indicating the version where OLDVAR was first marked obsolete.) +Optional DOCSTRING describes any changes in semantics users should be aware of." (let ((needs-setting (and (boundp oldvar) (not (boundp newvar)))) (value (and (boundp oldvar) (symbol-value oldvar)))) - (defvaralias oldvar newvar) - (make-obsolete-variable oldvar newvar) + (defvaralias oldvar newvar docstring) + (make-obsolete-variable oldvar newvar when) (and needs-setting (set newvar value)))) -(defsubst define-compatible-variable-alias (oldvar newvar) +(defsubst define-compatible-variable-alias (oldvar newvar + &optional when docstring) "Define OLDVAR as a compatible alias for variable NEWVAR. This makes referencing or setting OLDVAR equivalent to referencing or -setting NEWVAR and marks OLDVAR as provided for compatibility only." - (defvaralias oldvar newvar) +setting NEWVAR and marks OLDVAR as provided for compatibility only. +Optional WHEN is for consistency with `define-obsolete-variable-alias'. XEmacs +ignores it. \(If present, it is a string indicating the version where OLDFUN +was first marked as a compatibility API.) +Optional DOCSTRING describes any changes in semantics users should be aware of." + (defvaralias oldvar newvar docstring) (make-compatible-variable oldvar newvar)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;; buffers _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches