diff lisp/help.el @ 90296:d57ee9eab157

Revision: [e-mail]/emacs--unicode--0--patch-15 Merge from emacs--devo--0 Patches applied: * emacs--devo--0 (patch 66-84) - Update from CVS - rcirc: Add flexible response formatting; Add nick abbrevs - Merge from gnus--rel--5.10 - Update from CVS: man/dired.texi (Tumme): More tumme documentation. - Merge from erc--emacs--0 - Make ERC comply with the new copyright year guidelines. - (rcirc-format-response-string): Fix small bugs - Fix compiler error in erc-dcc.el. * gnus--rel--5.10 (patch 29) - Add sendmail.el and smptmail.el from Emacs tree to contrib/

--- a/lisp/help.el	Sat Feb 11 00:11:19 2006 +0000
+++ b/lisp/help.el	Tue Feb 14 05:54:12 2006 +0000
@@ -556,13 +556,39 @@
 	    string
 	  (format "%s (translated from %s)" string otherstring))))))
 
-(defun describe-key-briefly (key &optional insert untranslated)
+(defun describe-key-briefly (&optional key insert untranslated)
   "Print the name of the function KEY invokes.  KEY is a string.
 If INSERT (the prefix arg) is non-nil, insert the message in the buffer.
-If non-nil UNTRANSLATED is a vector of the untranslated events.
+If non-nil, UNTRANSLATED is a vector of the untranslated events.
 It can also be a number in which case the untranslated events from
-the last key hit are used."
-  (interactive "kDescribe key briefly: \nP\np")
+the last key hit are used.
+
+If KEY is a menu item or a tool-bar button that is disabled, this command
+temporarily enables it to allow getting help on disabled items and buttons."
+  (interactive
+   (let ((enable-disabled-menus-and-buttons t)
+	 (cursor-in-echo-area t)
+	 saved-yank-menu)
+     (unwind-protect
+	 (let (key)
+	   ;; If yank-menu is empty, populate it temporarily, so that
+	   ;; "Select and Paste" menu can generate a complete event.
+	   (when (null (cdr yank-menu))
+	     (setq saved-yank-menu (copy-sequence yank-menu))
+	     (menu-bar-update-yank-menu "(any string)" nil))
+	   (setq key (read-key-sequence "Describe key (or click or menu item): "))
+	   (list
+	    key
+	    (prefix-numeric-value current-prefix-arg)
+	    ;; If KEY is a down-event, read the corresponding up-event
+	    ;; and use it as the third argument.
+	    (if (and (consp key) (symbolp (car key))
+		     (memq 'down (cdr (get (car key) 'event-symbol-elements))))
+		(read-event))))
+       ;; Put yank-menu back as it was, if we changed it.
+       (when saved-yank-menu
+	 (setq yank-menu (copy-sequence saved-yank-menu))
+	 (fset 'yank-menu (cons 'keymap yank-menu))))))
   (if (numberp untranslated)
       (setq untranslated (this-single-command-raw-keys)))
   (save-excursion
@@ -584,6 +610,11 @@
       (let ((defn (or (string-key-binding key)
 		      (key-binding key t)))
 	    key-desc)
+	;; Handle the case where we faked an entry in "Select and Paste" menu.
+	(if (and (eq defn nil)
+		 (stringp (aref key (1- (length key))))
+		 (eq (key-binding (substring key 0 -1)) 'yank-menu))
+	    (setq defn 'menu-bar-select-yank))
 	;; Don't bother user with strings from (e.g.) the select-paste menu.
 	(if (stringp (aref key (1- (length key))))
 	    (aset key (1- (length key)) "(any string)"))
@@ -601,7 +632,7 @@
 			 key-desc
 			 (if (symbolp defn) defn (prin1-to-string defn)))))))))
 
-(defun describe-key (key &optional untranslated up-event)
+(defun describe-key (&optional key untranslated up-event)
   "Display documentation of the function invoked by KEY.
 KEY can be any kind of a key sequence; it can include keyboard events,
 mouse events, and/or menu events.  When calling from a program,
@@ -609,9 +640,35 @@
 
 If non-nil, UNTRANSLATED is a vector of the corresponding untranslated events.
 It can also be a number, in which case the untranslated events from
-the last key sequence entered are used."
-  ;; UP-EVENT is the up-event that was discarded by reading KEY, or nil.
-  (interactive "kDescribe key (or click or menu item): \np\nU")
+the last key sequence entered are used.
+UP-EVENT is the up-event that was discarded by reading KEY, or nil.
+
+If KEY is a menu item or a tool-bar button that is disabled, this command
+temporarily enables it to allow getting help on disabled items and buttons."
+  (interactive
+   (let ((enable-disabled-menus-and-buttons t)
+	 (cursor-in-echo-area t)
+	 saved-yank-menu)
+     (unwind-protect
+	 (let (key)
+	   ;; If yank-menu is empty, populate it temporarily, so that
+	   ;; "Select and Paste" menu can generate a complete event.
+	   (when (null (cdr yank-menu))
+	     (setq saved-yank-menu (copy-sequence yank-menu))
+	     (menu-bar-update-yank-menu "(any string)" nil))
+	   (setq key (read-key-sequence "Describe key (or click or menu item): "))
+	   (list
+	    key
+	    (prefix-numeric-value current-prefix-arg)
+	    ;; If KEY is a down-event, read the corresponding up-event
+	    ;; and use it as the third argument.
+	    (if (and (consp key) (symbolp (car key))
+		     (memq 'down (cdr (get (car key) 'event-symbol-elements))))
+		(read-event))))
+       ;; Put yank-menu back as it was, if we changed it.
+       (when saved-yank-menu
+	 (setq yank-menu (copy-sequence saved-yank-menu))
+	 (fset 'yank-menu (cons 'keymap yank-menu))))))
   (if (numberp untranslated)
       (setq untranslated (this-single-command-raw-keys)))
   (save-excursion
@@ -628,6 +685,11 @@
 	    (set-buffer (window-buffer window))
 	(goto-char position))
       (let ((defn (or (string-key-binding key) (key-binding key t))))
+	;; Handle the case where we faked an entry in "Select and Paste" menu.
+	(if (and (eq defn nil)
+		 (stringp (aref key (1- (length key))))
+		 (eq (key-binding (substring key 0 -1)) 'yank-menu))
+	    (setq defn 'menu-bar-select-yank))
 	(if (or (null defn) (integerp defn) (equal defn 'undefined))
 	    (message "%s is undefined" (help-key-description key untranslated))
 	  (help-setup-xref (list #'describe-function defn) (interactive-p))