Let C-h f do autoloading, and report if a function was previously autoloaded.

* lisp/help-fns.el (help-fns--autoloaded-p): New function.
(describe-function-1): Refer to a function as "autoloaded" if it
was autoloaded at any time in the past.  Perform autoloading if
help-enable-auto-load is non-nil.

* lisp/help.el (help-enable-auto-load): New variable.

* src/doc.c (Fsubstitute_command_keys): Fix punctuation.

diff --git a/etc/NEWS b/etc/NEWS
index 585a91decab84658cd28bdbba5decff8f1f62b23..e804805c8d046bfdaa6aa00bccfa47c7caa73a16 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -64,6 +64,18 @@ been adding them there, put them somewhere else, eg site-lisp.
 \f
 * Changes in Emacs 24.2
 
+** Help changes
+
+*** `C-h f' (describe-function) can now perform autoloading.
+When this command is called for an autoloaded function whose docstring
+contains a key substitution construct, that function's library is
+automatically loaded, so that the documentation can be shown
+correctly.  To disable this, set `help-enable-auto-load' to nil.
+
+*** `C-h f' now reports previously-autoloaded functions as "autoloaded",
+even after their associated libraries have been loaded (and the
+autoloads have been redefined as functions).
+
 ** The function `current-time' now returns extended-format time stamps
 (HIGH LOW USEC PSEC) that use picosecond resolution; the PSEC
 component is new.  PSEC is typically a multiple of 1000 on current

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 602c79854fa2a9e92148aa8a25a706b3c24376e0..c52891af6058fbee0247c34ce3c1eeca3c5ea3b2 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,12 @@
+2012-06-27  Chong Yidong  <cyd@gnu.org>
+
+       * help.el (help-enable-auto-load): New variable.
+
+       * help-fns.el (help-fns--autoloaded-p): New function.
+       (describe-function-1): Refer to a function as "autoloaded" if it
+       was autoloaded at any time in the past.  Perform autoloading if
+       help-enable-auto-load is non-nil.
+
 2012-06-26  Eli Zaretskii  <eliz@gnu.org>
 
        * makefile.w32-in (compile, compile-always): Depend on

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 555bdbb69ce5f906a12c3d1d3d058306ab233a39..52f1fe26056522852b3d3118df6065a4418947ec 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -401,6 +401,21 @@ suitable file is found, return nil."
               (help-xref-button 1 'help-function-cmacro function lib)))))
       (princ ".\n\n"))))
 
+;; We could use `symbol-file' but this is a wee bit more efficient.
+(defun help-fns--autoloaded-p (function file)
+  "Return non-nil if FUNCTION has previously been autoloaded.
+FILE is the file where FUNCTION was probably defined."
+  (let* ((file (file-name-sans-extension (file-truename file)))
+        (load-hist load-history)
+        (target (cons t function))
+        found)
+    (while (and load-hist (not found))
+      (and (caar load-hist)
+          (equal (file-name-sans-extension (caar load-hist)) file)
+          (setq found (member target (cdar load-hist))))
+      (setq load-hist (cdr load-hist)))
+    found))
+
 ;;;###autoload
 (defun describe-function-1 (function)
   (let* ((advised (and (symbolp function) (featurep 'advice)
@@ -416,59 +431,66 @@ suitable file is found, return nil."
         (def (if (symbolp real-function)
                  (symbol-function real-function)
                function))
-        file-name string
-        (beg (if (commandp def) "an interactive " "a "))
+        (aliased (symbolp def))
+        (real-def (if aliased
+                      (let ((f def))
+                        (while (and (fboundp f)
+                                    (symbolp (symbol-function f)))
+                          (setq f (symbol-function f)))
+                        f)
+                    def))
+        (file-name (find-lisp-object-file-name function def))
          (pt1 (with-current-buffer (help-buffer) (point)))
-        errtype)
-    (setq string
-         (cond ((or (stringp def) (vectorp def))
-                "a keyboard macro")
-               ((subrp def)
-                (if (eq 'unevalled (cdr (subr-arity def)))
-                    (concat beg "special form")
-                  (concat beg "built-in function")))
-               ((byte-code-function-p def)
-                (concat beg "compiled Lisp function"))
-               ((symbolp def)
-                (while (and (fboundp def)
-                            (symbolp (symbol-function def)))
-                  (setq def (symbol-function def)))
-                ;; Handle (defalias 'foo 'bar), where bar is undefined.
-                (or (fboundp def) (setq errtype 'alias))
-                (format "an alias for `%s'" def))
-               ((eq (car-safe def) 'lambda)
-                (concat beg "Lisp function"))
-               ((eq (car-safe def) 'macro)
-                "a Lisp macro")
-               ((eq (car-safe def) 'closure)
-                (concat beg "Lisp closure"))
-               ((eq (car-safe def) 'autoload)
-                (format "%s autoloaded %s"
-                        (if (commandp def) "an interactive" "an")
-                        (if (eq (nth 4 def) 'keymap) "keymap"
-                          (if (nth 4 def) "Lisp macro" "Lisp function"))))
-                ((keymapp def)
-                 (let ((is-full nil)
-                       (elts (cdr-safe def)))
-                   (while elts
-                     (if (char-table-p (car-safe elts))
-                         (setq is-full t
-                               elts nil))
-                     (setq elts (cdr-safe elts)))
-                   (if is-full
-                       "a full keymap"
-                     "a sparse keymap")))
-               (t "")))
-    (princ string)
-    (if (eq errtype 'alias)
+        (beg (if (and (or (byte-code-function-p def)
+                          (keymapp def)
+                          (memq (car-safe def) '(macro lambda closure)))
+                      (help-fns--autoloaded-p function file-name))
+                 (if (commandp def)
+                     "an interactive autoloaded "
+                   "an autoloaded ")
+               (if (commandp def) "an interactive " "a "))))
+
+    ;; Print what kind of function-like object FUNCTION is.
+    (princ (cond ((or (stringp def) (vectorp def))
+                 "a keyboard macro")
+                ((subrp def)
+                 (if (eq 'unevalled (cdr (subr-arity def)))
+                     (concat beg "special form")
+                   (concat beg "built-in function")))
+                ((byte-code-function-p def)
+                 (concat beg "compiled Lisp function"))
+                (aliased
+                 (format "an alias for `%s'" real-def))
+                ((eq (car-safe def) 'lambda)
+                 (concat beg "Lisp function"))
+                ((eq (car-safe def) 'macro)
+                 (concat beg "Lisp macro"))
+                ((eq (car-safe def) 'closure)
+                 (concat beg "Lisp closure"))
+                ((eq (car-safe def) 'autoload)
+                 (format "%s autoloaded %s"
+                         (if (commandp def) "an interactive" "an")
+                         (if (eq (nth 4 def) 'keymap) "keymap"
+                           (if (nth 4 def) "Lisp macro" "Lisp function"))))
+                ((keymapp def)
+                 (let ((is-full nil)
+                       (elts (cdr-safe def)))
+                   (while elts
+                     (if (char-table-p (car-safe elts))
+                         (setq is-full t
+                               elts nil))
+                     (setq elts (cdr-safe elts)))
+                   (concat beg (if is-full "keymap" "sparse keymap"))))
+                (t "")))
+
+    (if (and aliased (not (fboundp real-def)))
        (princ ",\nwhich is not defined.  Please make a bug report.")
       (with-current-buffer standard-output
        (save-excursion
          (save-match-data
            (when (re-search-backward "alias for `\\([^`']+\\)'" nil t)
-             (help-xref-button 1 'help-function def)))))
+             (help-xref-button 1 'help-function real-def)))))
 
-      (setq file-name (find-lisp-object-file-name function def))
       (when file-name
        (princ " in `")
        ;; We used to add .el to the file name,
@@ -531,11 +553,21 @@ suitable file is found, return nil."
            (unless (looking-back "\n\n")
              (terpri)))))
       (help-fns--compiler-macro function)
-      (let* ((advertised (gethash def advertised-signature-table t))
+      (let* ((advertised (gethash real-def advertised-signature-table t))
             (arglist (if (listp advertised)
-                         advertised (help-function-arglist def)))
-            (doc (condition-case err (documentation function)
-                    (error (format "No Doc! %S" err))))
+                         advertised (help-function-arglist real-def)))
+            (doc-raw (condition-case err
+                         (documentation function t)
+                       (error (format "No Doc! %S" err))))
+            ;; If the function is autoloaded, and its docstring has
+            ;; key substitution constructs, load the library.
+            (doc (progn
+                   (and (eq (car-safe real-def) 'autoload)
+                        help-enable-auto-load
+                        (string-match "\\([^\\]=\\|[^=]\\|\\`\\)\\\\[[{<]"
+                                      doc-raw)
+                        (load (cadr real-def) t))
+                   (substitute-command-keys doc-raw)))
             (usage (help-split-fundoc doc function)))
        (with-current-buffer standard-output
          ;; If definition is a keymap, skip arglist note.
@@ -556,9 +588,9 @@ suitable file is found, return nil."
                                                          function)))))
                            usage)
                          (car usage))
-                        ((or (stringp def)
-                             (vectorp def))
-                         (format "\nMacro: %s" (format-kbd-macro def)))
+                        ((or (stringp real-def)
+                             (vectorp real-def))
+                         (format "\nMacro: %s" (format-kbd-macro real-def)))
                         (t "[Missing arglist.  Please make a bug report.]")))
                   (high (help-highlight-arguments use doc)))
              (let ((fill-begin (point)))

diff --git a/lisp/help.el b/lisp/help.el
index 2dbb31de97b73d3098ecf2e9dc37315c3a377eeb..c02b058fef9a54abecc8bc97bb30c0e20c95f33b 100644 (file)
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1030,6 +1030,16 @@ by `with-help-window'"
   :group 'help
   :version "23.1")
 
+(defcustom help-enable-auto-load t
+  "Whether Help commands can perform autoloading.
+If non-nil, whenever \\[describe-function] is called for an
+autoloaded function whose docstring contains any key substitution
+construct (see `substitute-command-keys'), the library is loaded,
+so that the documentation can show the right key bindings."
+  :type 'boolean
+  :group 'help
+  :version "24.2")
+
 (defun help-window-display-message (quit-part window &optional scroll)
   "Display message telling how to quit and scroll help window.
 QUIT-PART is a string telling how to quit the help window WINDOW.

diff --git a/src/ChangeLog b/src/ChangeLog
index bef3bbd4c83a92a73592088cd5edc3af5fa4b3c8..4614ba09b3dc821be6be6e7c6550e1e6b6b80be5 100644 (file)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2012-06-27  Chong Yidong  <cyd@gnu.org>
+
+       * doc.c (Fsubstitute_command_keys): Fix punctuation.
+
 2012-06-26  John Wiegley  <johnw@newartisans.com>
 
        * unexmacosx.c (copy_data_segment): Added two section names used

diff --git a/src/doc.c b/src/doc.c
index 223741c3bf516fd07b7d0b4d7121f2a14d201672..cbfeb06756e68ce975a45f41b109a915546fceb0 100644 (file)
--- a/src/doc.c
+++ b/src/doc.c
@@ -897,11 +897,11 @@ Otherwise, return a new string, without any text properties.  */)
          if (NILP (tem))
            {
              name = Fsymbol_name (name);
-             insert_string ("\nUses keymap \"");
+             insert_string ("\nUses keymap `");
              insert_from_string (name, 0, 0,
                                  SCHARS (name),
                                  SBYTES (name), 1);
-             insert_string ("\", which is not currently defined.\n");
+             insert_string ("', which is not currently defined.\n");
              if (start[-1] == '<') keymap = Qnil;
            }
          else if (start[-1] == '<')