initialization file in describe-variable

initialization file in describe-variable

[Robert J. Chassell]

Currently, describe-variable does not speak of your
initialization file although it does of customization.

I would like to speak of both and suggest the following changes:

As new button type in ... emacs/lisp/help-mode.el

    (define-button-type 'help-info-variable
      :supertype 'help-xref
      ;; the name of the variable is put before the argument to Info
      'help-function (lambda (a v) (info v))
      'help-echo (purecopy "mouse-2, RET: read this Info node"))

and a change to describe-variable in ... emacs/lisp/help-fns.el to
describe your initialization file both when there is no customization
and when there is customization.  (I leave customization as the first
part of the sentence.  The new type was introduced because with it I
am more confident I changed little else.)

To test with emacs -Q -D, you must first run C-h v (describe-variable)
on a variable such as     american-calendar-display-form
then make the changes.

For a variable without customization evaluate the following

    (defvar bish nil "this is documentation for bish")

the run C-h v (describe-variable) on

    bish


The diffs are:


diff -C 2 -p /usr/local/src/emacs/lisp/help-mode.el.\~1.59.\~ /usr/local/src/emacs/lisp/help-mode.el
*** /usr/local/src/emacs/lisp/help-mode.el.~1.59.~	2008-02-17 19:31:37.000000000 +0000
--- /usr/local/src/emacs/lisp/help-mode.el	2008-02-18 13:09:02.000000000 +0000
*** 145,148 ****
--- 145,154 ----
    'help-echo (purecopy "mouse-2, RET: move forward to next help buffer"))

+ (define-button-type 'help-info-variable
+   :supertype 'help-xref
+   ;; the name of the variable is put before the argument to Info
+   'help-function (lambda (a v) (info v))
+   'help-echo (purecopy "mouse-2, RET: read this Info node"))
+
  (define-button-type 'help-info
    :supertype 'help-xref

Diff finished.  Mon Feb 18 13:17:30 2008


diff -C 2 -p /usr/local/src/emacs/lisp/help-fns.el.\~1.114.\~ /usr/local/src/emacs/lisp/help-fns.el
*** /usr/local/src/emacs/lisp/help-fns.el.~1.114.~	2008-02-12 10:58:38.000000000 +0000
--- /usr/local/src/emacs/lisp/help-fns.el	2008-02-18 13:14:10.000000000 +0000
*** 677,691 ****
  	      (with-current-buffer standard-output
  		(insert (or doc "Not documented as a variable."))))
! 	    ;; Make a link to customize if this variable can be customized.
! 	    (when (custom-variable-p variable)
! 	      (let ((customize-label "customize"))
  		(terpri)
  		(terpri)
! 		(princ (concat "You can " customize-label " this variable."))
  		(with-current-buffer standard-output
  		  (save-excursion
  		    (re-search-backward
  		     (concat "\\(" customize-label "\\)") nil t)
! 		    (help-xref-button 1 'help-customize-variable variable))))
  	      ;; Note variable's version or package version
  	      (let ((output (describe-variable-custom-version-info variable)))
--- 677,713 ----
  	      (with-current-buffer standard-output
  		(insert (or doc "Not documented as a variable."))))
!
!             (let ((customize-label "customize")
!                   (initialization-file "initialization file"))
!               ;; All variables can be set; some can be customized
!               (when (and (symbolp variable) (not (custom-variable-p variable)))
! 		(terpri)
! 		(terpri)
! 		(princ (concat "You can set this variable in your "
!                                initialization-file "."))
! 		(with-current-buffer standard-output
! 		  (save-excursion
!                     (re-search-backward
! 		     (concat "\\(" initialization-file "\\)") nil t)
!                     (help-xref-button 1 'help-info-variable variable
!                                       "(emacs)Init File"))))
!               ;; Make a link to customize if this variable can be customized.
!               (when (custom-variable-p variable)
  		(terpri)
  		(terpri)
! 		(princ (concat "You can " customize-label " this variable"))
! 		(princ (concat " or set it in your " initialization-file "."))
  		(with-current-buffer standard-output
  		  (save-excursion
  		    (re-search-backward
  		     (concat "\\(" customize-label "\\)") nil t)
! 		    (help-xref-button 1 'help-customize-variable variable))
! 		  (save-excursion
!                     (re-search-backward
! 		     (concat "\\(" initialization-file "\\)") nil t)
!                     (help-xref-button 1 'help-info-variable variable
!                                       "(emacs)Init File")
!                     )
!                   ))
  	      ;; Note variable's version or package version
  	      (let ((output (describe-variable-custom-version-info variable)))

Diff finished.  Mon Feb 18 13:18:19 2008

The ChangeLog entry would be:

     * help-mode.el (define-button-type 'help-info-variable):
     New button able to read Info files.

     * help-fns.el (describe-variable): Add phrases about
     initialization file with and without customization;
     use new button type help-info-variable.

Comments, suggestions?  Otherwise, I will install it next Monday.

--
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc