--- a/lisp/ChangeLog	Mon Feb 04 20:03:04 2013 -0500
+++ b/lisp/ChangeLog	Sat Feb 16 04:55:38 2013 +0900
@@ -1,3 +1,16 @@
+2013-02-16  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	Thanks to Jeff Sparkes for 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@xemacs.org>
 
 	* glyphs.el (make-image-specifier): Document that :visible is a

--- a/lisp/obsolete.el	Mon Feb 04 20:03:04 2013 -0500
+++ b/lisp/obsolete.el	Sat Feb 16 04:55:38 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