[patch] describe-variable mention :version and :package-version info

[patch] describe-variable mention :version and :package-version info

[John Paul Wallington]

I don't think `describe-variable' is sufficiently gnarly or long
enough yet.  Is it okay to install the following change?

2007-10-19  John Paul Wallington  <jpw@pobox.com>

	* help-fns.el (describe-variable): Note customizable variable's
	version or package version.

diff -ub

--- help-fns.el	16 Oct 2007 17:35:41 +0100	1.105
+++ help-fns.el	19 Oct 2007 23:50:57 +0100	
@@ -643,7 +643,7 @@
 	      (with-current-buffer standard-output
 		(insert (or doc "Not documented as a variable."))))
 	    ;; Make a link to customize if this variable can be customized.
-	    (if (custom-variable-p variable)
+	    (when (custom-variable-p variable)
 		(let ((customize-label "customize"))
 		  (terpri)
 		  (terpri)
@@ -652,7 +652,32 @@
 		    (save-excursion
 		      (re-search-backward
 		       (concat "\\(" customize-label "\\)") nil t)
-		      (help-xref-button 1 'help-customize-variable variable)))))
+		    (help-xref-button 1 'help-customize-variable variable))))
+	      ;; Add a note for variable with version or package version
+	      (let ((custom-version (get variable 'custom-version))
+		    (cpv (get variable 'custom-package-version))
+		    (output nil))
+		(if custom-version
+		    (setq output 
+			  (format "This variable was introduced, or its default value was changed, in\nversion %s of Emacs.\n"
+				  custom-version))
+		  (when cpv
+		    (let* ((package (car-safe cpv))
+			   (version (car (cdr-safe cpv)))
+			   (pkg-versions (assq package customize-package-emacs-version-alist))
+			   (emacsv (cdr (assoc version pkg-versions))))
+		      (if (and package version)
+			  (setq output
+				(format (concat "This variable was introduced, or its default value was changed, in\nversion %s of the %s package"	     
+						(if emacsv
+						    (format " that is part of Emacs %s" emacsv))
+						".\n")
+					version package))))))
+		(when output
+		  (terpri)
+		  (terpri)
+		  (princ output))))
+	    
 	    (print-help-return-message)
 	    (save-excursion
 	      (set-buffer standard-output)

Re: [patch] describe-variable mention :version and :package-version info

[Stefan Monnier]

> I don't think `describe-variable' is sufficiently gnarly or long
> enough yet.  Is it okay to install the following change?

Can you try and help keep its size under control by creating a new function
for your new code, and just call that function from `describe-variable'?


        Stefan

Re: [patch] describe-variable mention :version and :package-version info

[John Paul Wallington]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I don't think `describe-variable' is sufficiently gnarly or long
>> enough yet.  Is it okay to install the following change?
>
> Can you try and help keep its size under control by creating a new function
> for your new code, and just call that function from `describe-variable'?

Done, sort of.  The helper function returns the string to display instead.

Re: [patch] describe-variable mention :version and :package-version info

[Richard Stallman]

I don't think this info is very important to show to the user, so I
would rather leave it out.  (In Emacs design, Completeness is not the
goal.)  However, if a lot of people think including it is useful, I
will go a long with them.

I see you rushed ahead and installed this already.  You should have
waited longer.  I will see how many other people support it, and thus
decide deciding whether to leave it installed.