Merged from emacs@sv.gnu.org

[bpt/emacs.git] / lisp / help-fns.el

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index cffe313..0a78ed8 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1,7 +1,7 @@
 ;;; help-fns.el --- Complex help functions
 
 ;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001,
-;;   2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+;;   2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
 ;; Keywords: help, internal
@@ -113,7 +113,8 @@ With ARG, you are asked to choose which language."
      (setq val (completing-read (if fn
                                    (format "Describe function (default %s): " fn)
                                  "Describe function: ")
-                               obarray 'fboundp t nil nil (symbol-name fn)))
+                               obarray 'fboundp t nil nil
+                               (and fn (symbol-name fn))))
      (list (if (equal val "")
               fn (intern val)))))
   (if (null function)
@@ -223,7 +224,6 @@ KIND should be `var' for a variable or `subr' for a subroutine."
            (concat "src/" file)
          file)))))
 
-;;;###autoload
 (defface help-argument-name '((((supports :slant italic)) :inherit italic))
   "Face to highlight argument names in *Help* buffers."
   :group 'help)
@@ -252,6 +252,7 @@ face (according to `face-differs-from-default-p')."
                          "\\)"
                          "\\(?:es\\|s\\|th\\)?"  ; for ARGth, ARGs
                          "\\(?:-[a-z0-9-]+\\)?"  ; for ARG-xxx, ARG-n
+                         "\\(?:-[{([<`\"].*?\\)?"; for ARG-{x}, (x), <x>, [x], `x'
                          "\\>")                  ; end of word
                  (help-default-arg-highlight arg)
                  doc t t 1)))))
@@ -283,6 +284,7 @@ face (according to `face-differs-from-default-p')."
   ;; Return value is like the one from help-split-fundoc, but highlighted
   (cons usage doc))
 
+;;;###autoload
 (defun describe-simplify-lib-file-name (file)
   "Simplify a library name FILE to a relative name, and make it a source file."
   (if file
@@ -291,7 +293,7 @@ face (according to `face-differs-from-default-p')."
        ;; Now convert that back to a file name and see if we get
        ;; the original one.  If so, they are equivalent.
        (if (equal file (locate-file libname load-path '("")))
-           (if (string-match "[.]elc?\\'" libname)
+           (if (string-match "[.]elc\\'" libname)
                (substring libname 0 -1)
              libname)
          file))))
@@ -435,7 +437,9 @@ face (according to `face-differs-from-default-p')."
                          (format "\nMacro: %s" (format-kbd-macro def)))
                         (t "[Missing arglist.  Please make a bug report.]")))
                  (high (help-highlight-arguments use doc)))
-            (insert (car high) "\n")
+            (let ((fill-begin (point)))
+             (insert (car high) "\n")
+             (fill-region fill-begin (point)))
             (setq doc (cdr high))))
         (let ((obsolete (and
                          ;; function might be a lambda construct.
@@ -482,10 +486,11 @@ If ANY-SYMBOL is non-nil, don't insist the symbol be bound."
       0))
 
 ;;;###autoload
-(defun describe-variable (variable &optional buffer)
+(defun describe-variable (variable &optional buffer frame)
   "Display the full documentation of VARIABLE (a symbol).
 Returns the documentation as a string, also.
-If VARIABLE has a buffer-local value in BUFFER (default to the current buffer),
+If VARIABLE has a buffer-local value in BUFFER or FRAME
+\(default to the current buffer and current frame),
 it is displayed along with the global value."
   (interactive
    (let ((v (variable-at-point))
@@ -495,19 +500,28 @@ it is displayed along with the global value."
                                    (format
                                     "Describe variable (default %s): " v)
                                  "Describe variable: ")
-                               obarray 'boundp t nil nil
+                               obarray
+                               '(lambda (vv)
+                                  (or (boundp vv)
+                                      (get vv 'variable-documentation)))
+                               t nil nil
                                (if (symbolp v) (symbol-name v))))
      (list (if (equal val "")
               v (intern val)))))
   (unless (buffer-live-p buffer) (setq buffer (current-buffer)))
+  (unless (frame-live-p frame) (setq frame (selected-frame)))
   (if (not (symbolp variable))
       (message "You did not specify a variable")
     (save-excursion
-      (let* ((valvoid (not (with-current-buffer buffer (boundp variable))))
-            ;; Extract the value before setting up the output buffer,
-            ;; in case `buffer' *is* the output buffer.
-            (val (unless valvoid (buffer-local-value variable buffer)))
-            val-start-pos)
+      (let ((valvoid (not (with-current-buffer buffer (boundp variable))))
+           val val-start-pos locus)
+       ;; Extract the value before setting up the output buffer,
+       ;; in case `buffer' *is* the output buffer.
+       (unless valvoid
+         (with-selected-frame frame
+           (with-current-buffer buffer
+             (setq val (symbol-value variable)
+                   locus (variable-binding-locus variable)))))
        (help-setup-xref (list #'describe-variable variable buffer)
                         (interactive-p))
        (with-output-to-temp-buffer (help-buffer)
@@ -548,10 +562,10 @@ it is displayed along with the global value."
                        (help-xref-button 1 'help-variable-def
                                          variable file-name)))
                    (if valvoid
-                       (princ "It is void as a variable.\n")
+                       (princ "It is void as a variable.")
                      (princ "Its ")))
                (if valvoid
-                   (princ " is void as a variable.\n")
+                   (princ " is void as a variable.")
                  (princ "'s "))))
            (if valvoid
                nil
@@ -568,11 +582,13 @@ it is displayed along with the global value."
                      (delete-region (1- from) from)))))
            (terpri)
 
-           (when (local-variable-p variable)
-             (princ (format "%socal in buffer %s; "
-                            (if (get variable 'permanent-local)
-                                "Permanently l" "L")
-                            (buffer-name)))
+           (when locus
+             (if (bufferp locus)
+                 (princ (format "%socal in buffer %s; "
+                                (if (get variable 'permanent-local)
+                                    "Permanently l" "L")
+                                (buffer-name)))
+               (princ (format "It is a frame-local variable; ")))
              (if (not (default-boundp variable))
                  (princ "globally void")
                (let ((val (default-value variable)))