comparison 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/

90295:4b3d39451150

      (let ((otherstring (key-description untranslated)))
	(if (equal string otherstring)
	    string
	  (format "%s (translated from %s)" string otherstring))))))

(defun describe-key-briefly (key &optional 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.
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")
  (if (numberp untranslated)
      (setq untranslated (this-single-command-raw-keys)))
  (save-excursion
    (let ((modifiers (event-modifiers (aref key 0)))
	  (standard-output (if insert (current-buffer) t))

	    (goto-char position)))
      ;; Ok, now look up the key and name the command.
      (let ((defn (or (string-key-binding key)
		      (key-binding key t)))
	    key-desc)
	;; 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)"))
	(if (and (> (length untranslated) 0)
		 (stringp (aref untranslated (1- (length untranslated)))))

			     "%s at that spot runs the command %s"
			   "%s runs the command %s")
			 key-desc
			 (if (symbolp defn) defn (prin1-to-string defn)))))))))

(defun describe-key (key &optional 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,
pass KEY as a string or a vector.

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")
  (if (numberp untranslated)
      (setq untranslated (this-single-command-raw-keys)))
  (save-excursion
    (let ((modifiers (event-modifiers (aref key 0)))
	  window position)

		position (posn-point (event-start (aref key 0)))))
      (when (windowp window)
	    (set-buffer (window-buffer window))
	(goto-char position))
      (let ((defn (or (string-key-binding key) (key-binding key t))))
	(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))
	  ;; Don't bother user with strings from (e.g.) the select-paste menu.
	  (if (stringp (aref key (1- (length key))))

90296:d57ee9eab157

      (let ((otherstring (key-description untranslated)))
	(if (equal string otherstring)
	    string
	  (format "%s (translated from %s)" string otherstring))))))

(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.
It can also be a number in which case the untranslated events from
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
    (let ((modifiers (event-modifiers (aref key 0)))
	  (standard-output (if insert (current-buffer) t))

	    (goto-char position)))
      ;; Ok, now look up the key and name the command.
      (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)"))
	(if (and (> (length untranslated) 0)
		 (stringp (aref untranslated (1- (length untranslated)))))

			     "%s at that spot runs the command %s"
			   "%s runs the command %s")
			 key-desc
			 (if (symbolp defn) defn (prin1-to-string defn)))))))))

(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,
pass KEY as a string or a vector.

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.

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
    (let ((modifiers (event-modifiers (aref key 0)))
	  window position)

		position (posn-point (event-start (aref key 0)))))
      (when (windowp window)
	    (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))
	  ;; Don't bother user with strings from (e.g.) the select-paste menu.
	  (if (stringp (aref key (1- (length key))))