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.

6 files changed, 122 insertions, 55 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 585a91decab..e804805c8d0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -64,6 +64,18 @@ been adding them there, put them somewhere else, eg site-lisp.
 
 * 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 602c79854fa..c52891af605 100644
--- 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 555bdbb69ce..52f1fe26056 100644
--- 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 2dbb31de97b..c02b058fef9 100644
--- 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 bef3bbd4c83..4614ba09b3d 100644
--- 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 223741c3bf5..cbfeb06756e 100644
--- 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] == '<')