Improvements to local-variable reporting in `describe-variable'.

* lisp/help-fns.el (describe-variable): Add hyperlink for
directory-local variables files.  Improve buffer-local and
permanent-local reporting; suggested by MON KEY.

* lisp/help-mode.el (help-dir-local-var-def): New button type.

Fixes: debbugs:6644

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 71d7b50482c5b1309060415243890a3d616acd1c..623bf4336b67886d4dfcbc09521bd4d443d6b612 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,11 @@
 2012-08-05  Chong Yidong  <cyd@gnu.org>
 
+       * help-fns.el (describe-variable): Add hyperlink for
+       directory-local variables files.  Improve buffer-local and
+       permanent-local reporting; suggested by MON KEY (Bug#6644).
+
+       * help-mode.el (help-dir-local-var-def): New button type.
+
        * files.el (kill-buffer-hook): Provide a defvar.
 
 2012-08-05  Glenn Morris  <rgm@gnu.org>

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index f585bff871f19f28dd33d94fa9a52c71db72aabe..495063fb17ceb2d4fd43522c4427d32a8805b99f 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -713,6 +713,7 @@ it is displayed along with the global value."
        (message "You did not specify a variable")
       (save-excursion
        (let ((valvoid (not (with-current-buffer buffer (boundp variable))))
+             (permanent-local (get variable 'permanent-local))
              val val-start-pos locus)
          ;; Extract the value before setting up the output buffer,
          ;; in case `buffer' *is* the output buffer.
@@ -752,7 +753,6 @@ it is displayed along with the global value."
                (princ "value is ")
                (let ((from (point))
                      (line-beg (line-beginning-position))
-                     ;;
                      (print-rep
                       (let ((print-quoted t))
                         (prin1-to-string val))))
@@ -780,9 +780,7 @@ it is displayed along with the global value."
            (when locus
              (cond
                ((bufferp locus)
-                (princ (format "%socal in buffer %s; "
-                               (if (get variable 'permanent-local)
-                                   "Permanently l" "L")
+                (princ (format "Local in buffer %s; "
                                (buffer-name))))
                ((framep locus)
                 (princ (format "It is a frame-local variable; ")))
@@ -792,20 +790,22 @@ it is displayed along with the global value."
                 (princ (format "It is local to %S" locus))))
              (if (not (default-boundp variable))
                  (princ "globally void")
-               (let ((val (default-value variable)))
+               (let ((global-val (default-value variable)))
                  (with-current-buffer standard-output
                    (princ "global value is ")
-                   (terpri)
-                   ;; Fixme: pp can take an age if you happen to
-                   ;; ask for a very large expression.  We should
-                   ;; probably print it raw once and check it's a
-                   ;; sensible size before prettyprinting.  -- fx
-                   (let ((from (point)))
-                     (pp val)
-                     ;; See previous comment for this function.
-                     ;; (help-xref-on-pp from (point))
-                     (if (< (point) (+ from 20))
-                         (delete-region (1- from) from))))))
+                   (if (eq val global-val)
+                       (princ "the same.")
+                     (terpri)
+                     ;; Fixme: pp can take an age if you happen to
+                     ;; ask for a very large expression.  We should
+                     ;; probably print it raw once and check it's a
+                     ;; sensible size before prettyprinting.  -- fx
+                     (let ((from (point)))
+                       (pp global-val)
+                       ;; See previous comment for this function.
+                       ;; (help-xref-on-pp from (point))
+                       (if (< (point) (+ from 20))
+                           (delete-region (1- from) from)))))))
               (terpri))
 
            ;; If the value is large, move it to the end.
@@ -846,18 +846,26 @@ it is displayed along with the global value."
                                  alias 'variable-documentation))
                           (error (format "Doc not found: %S" err))))
                    (extra-line nil))
-              ;; Add a note for variables that have been make-var-buffer-local.
-              (when (and (local-variable-if-set-p variable)
-                         (or (not (local-variable-p variable))
-                             (with-temp-buffer
-                               (local-variable-if-set-p variable))))
+
+             ;; Mention if it's a local variable.
+             (cond
+              ((and (local-variable-if-set-p variable)
+                    (or (not (local-variable-p variable))
+                        (with-temp-buffer
+                          (local-variable-if-set-p variable))))
                 (setq extra-line t)
                 (princ "  Automatically becomes ")
-               (if (get variable 'permanent-local)
+               (if permanent-local
                    (princ "permanently "))
                (princ "buffer-local when set.\n"))
+              ((not permanent-local))
+              ((bufferp locus)
+               (princ "  This variable's buffer-local value is permanent.\n"))
+              (t
+                (princ "  This variable's value is permanent \
+if it is given a local binding.\n")))
 
-              ;; Mention if it's an alias
+             ;; Mention if it's an alias.
               (unless (eq alias variable)
                 (setq extra-line t)
                 (princ (format "  This variable is an alias for `%s'.\n" alias)))
@@ -879,9 +887,11 @@ it is displayed along with the global value."
                                       (not (file-remote-p (buffer-file-name)))
                                       (dir-locals-find-file
                                        (buffer-file-name))))
-                          (type "file"))
-                     (princ "  This variable is a directory local variable")
-                     (when file
+                          (dir-file t))
+                     (princ "  This variable's value is directory-local")
+                     (if (null file)
+                         (princ ".\n")
+                       (princ ", set ")
                         (if (consp file) ; result from cache
                             ;; If the cache element has an mtime, we
                             ;; assume it came from a file.
@@ -889,21 +899,27 @@ it is displayed along with the global value."
                                 (setq file (expand-file-name
                                             dir-locals-file (car file)))
                               ;; Otherwise, assume it was set directly.
-                              (setq type "directory")))
-                       (princ (format "\n  from the %s \"%s\"" type file)))
-                     (princ ".\n"))
-                 (princ "  This variable is a file local variable.\n")))
+                              (setq dir-file nil)))
+                       (princ (if dir-file
+                                  "by the file\n  `"
+                                "for the directory\n  `"))
+                       (with-current-buffer standard-output
+                         (insert-text-button
+                          file 'type 'help-dir-local-var-def
+                          'help-args (list variable file)))
+                       (princ "'.\n")))
+                 (princ "  This variable's value is file-local.\n")))
 
              (when (memq variable ignored-local-variables)
                (setq extra-line t)
-               (princ "  This variable is ignored when used as a file local \
+               (princ "  This variable is ignored as a file-local \
 variable.\n"))
 
              ;; Can be both risky and safe, eg auto-fill-function.
              (when (risky-local-variable-p variable)
                (setq extra-line t)
-               (princ "  This variable is potentially risky when used as a \
-file local variable.\n")
+               (princ "  This variable may be risky if used as a \
+file-local variable.\n")
                (when (assq variable safe-local-variable-values)
                  (princ "  However, you have added it to \
 `safe-local-variable-values'.\n")))

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 7b6490b6b13092a5b1df72fc7cb0a7180c36ed71..9924300647cc76ee65b6be654029fd92e1c95f30 100644 (file)
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -265,6 +265,15 @@ The format is (FUNCTION ARGS...).")
   :supertype 'help-xref
   'help-function 'customize-create-theme
   'help-echo (purecopy "mouse-2, RET: edit this theme file"))
+
+(define-button-type 'help-dir-local-var-def
+  :supertype 'help-xref
+  'help-function (lambda (var &optional file)
+                  ;; FIXME: this should go to the point where the
+                  ;; local variable was defined.
+                  (find-file file))
+  'help-echo (purecopy "mouse-2, RET: open directory-local variables file"))
+
 \f
 (defvar bookmark-make-record-function)