;;; help.el --- help commands for Emacs
;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002,
-;; 2003, 2004, 2005 Free Software Foundation, Inc.
+;; 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: help, internal
(if first-message " ")
;; If the help buffer will go in a separate frame,
;; it's no use mentioning a command to scroll, so don't.
- (if (special-display-p (buffer-name standard-output))
+ (if (or pop-up-windows
+ (special-display-p (buffer-name standard-output)))
nil
(if (same-window-p (buffer-name standard-output))
;; Say how to scroll this window.
(defalias 'help-for-help 'help-for-help-internal)
;; It can't find this, but nobody will look.
(make-help-screen help-for-help-internal
- "a b c C e f F i I k C-k l L m p s t v w C-c C-d C-f C-n C-p C-t C-w . or ? :"
+ "a b c C e f F i I k C-k l L m p r s t v w C-c C-d C-f C-n C-p C-t C-w . or ? :"
"You have typed %THIS-KEY%, the help character. Type a Help option:
\(Use SPC or DEL to scroll through this text. Type \\<help-map>\\[help-quit] to exit the Help command.)
a command-apropos. Give a list of words or a regexp, to get a list of
- commands whose names match (they contain two or more of the words,
- or a match for the regexp). See also the apropos command.
+ commands whose names match. See also the apropos command.
b describe-bindings. Display table of all key bindings.
c describe-key-briefly. Type a command key sequence;
it prints the function name that sequence runs.
and the current major mode, including their special commands.
n view-emacs-news. Display news of recent Emacs changes.
p finder-by-keyword. Find packages matching a given topic keyword.
+r info-emacs-manual. Display the Emacs manual in Info mode.
s describe-syntax. Display contents of syntax table, plus explanations.
S info-lookup-symbol. Display the definition of a specific symbol
as found in the manual for the language this buffer is written in.
(with-current-buffer standard-output
(goto-char (point-min))
(while (progn (move-to-column 50) (not (eobp)))
- (search-forward " " nil t)
- (insert "\n")))
+ (when (search-forward " " nil t)
+ (delete-char -1))
+ (insert "\n")))
(print-help-return-message)))
\f
(if (> (length keys) 0)
(if remapped
(format "%s is remapped to %s which is on %s"
- definition symbol keys)
+ symbol remapped keys)
(format "%s is on %s" symbol keys))
;; If this is the command the user asked about,
;; and it is not on any key, say so.
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): "))
+ ;; If KEY is a down-event, read and discard the
+ ;; corresponding up-event.
+ (if (and (vectorp key)
+ (eventp (elt key 0))
+ (memq 'down (event-modifiers (elt key 0))))
+ (read-event))
+ (list
+ key
+ (if current-prefix-arg (prefix-numeric-value current-prefix-arg))
+ 1))
+ ;; 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 ((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)"))
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,
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 (vectorp key)
+ (eventp (elt key 0))
+ (memq 'down (event-modifiers (elt key 0))))
+ (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
(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))
(princ "\n which is ")
(describe-function-1 defn)
(when up-event
- (let ((ev (aref up-event 0))
- (descr (key-description up-event))
+ (let ((type (event-basic-type up-event))
(hdr "\n\n-------------- up event ---------------\n\n")
- defn
+ defn sequence
mouse-1-tricky mouse-1-remapped)
- (when (and (consp ev)
- (eq (car ev) 'mouse-1)
+ (setq sequence (vector up-event))
+ (when (and (eq type 'mouse-1)
(windowp window)
mouse-1-click-follows-link
(not (eq mouse-1-click-follows-link 'double))
- (with-current-buffer (window-buffer window)
- (mouse-on-link-p (posn-point (event-start ev)))))
- (setq mouse-1-tricky (integerp mouse-1-click-follows-link)
- mouse-1-remapped (or (not mouse-1-tricky)
- (> mouse-1-click-follows-link 0)))
- (if mouse-1-remapped
- (setcar ev 'mouse-2)))
- (setq defn (or (string-key-binding up-event) (key-binding up-event)))
+ (setq mouse-1-remapped
+ (with-current-buffer (window-buffer window)
+ (mouse-on-link-p (posn-point
+ (event-start up-event))))))
+ (setq mouse-1-tricky (and (integerp mouse-1-click-follows-link)
+ (> mouse-1-click-follows-link 0)))
+ (cond ((stringp mouse-1-remapped)
+ (setq sequence mouse-1-remapped))
+ ((vectorp mouse-1-remapped)
+ (setcar up-event (elt mouse-1-remapped 0)))
+ (t (setcar up-event 'mouse-2))))
+ (setq defn (or (string-key-binding sequence)
+ (key-binding sequence)))
(unless (or (null defn) (integerp defn) (equal defn 'undefined))
(princ (if mouse-1-tricky
"\n\n----------------- up-event (short click) ----------------\n\n"
hdr))
(setq hdr nil)
- (princ descr)
+ (princ (symbol-name type))
(if (windowp window)
(princ " at that spot"))
(if mouse-1-remapped
(princ "\n which is ")
(describe-function-1 defn))
(when mouse-1-tricky
- (setcar ev
- (if (> mouse-1-click-follows-link 0) 'mouse-1 'mouse-2))
- (setq defn (or (string-key-binding up-event) (key-binding up-event)))
- (unless (or (null defn) (integerp defn) (equal defn 'undefined))
+ (setcar up-event 'mouse-1)
+ (setq defn (or (string-key-binding (vector up-event))
+ (key-binding (vector up-event))))
+ (unless (or (null defn) (integerp defn) (eq defn 'undefined))
(princ (or hdr
"\n\n----------------- up-event (long click) ----------------\n\n"))
- (princ "Pressing ")
- (princ descr)
+ (princ "Pressing mouse-1")
(if (windowp window)
(princ " at that spot"))
(princ (format " for longer than %d milli-seconds\n"
- (abs mouse-1-click-follows-link)))
- (if (not mouse-1-remapped)
- (princ " remaps it to <mouse-2> which" ))
+ mouse-1-click-follows-link))
(princ " runs the command ")
(prin1 defn)
(princ "\n which is ")
(describe-function-1 defn)))))
(print-help-return-message)))))))
-
\f
(defun describe-mode (&optional buffer)
"Display documentation of current major mode and minor modes.
;; Document the major mode.
(let ((mode mode-name))
(with-current-buffer standard-output
- (insert mode)
- (add-text-properties (- (point) (length mode)) (point) '(face bold))))
+ (let ((start (point)))
+ (insert (format-mode-line mode))
+ (add-text-properties start (point) '(face bold)))))
(princ " mode:\n")
(princ (documentation major-mode)))
(print-help-return-message))))
;;; Automatic resizing of temporary buffers.
(defcustom temp-buffer-max-height (lambda (buffer) (/ (- (frame-height) 2) 2))
- "*Maximum height of a window displaying a temporary buffer.
+ "Maximum height of a window displaying a temporary buffer.
This is the maximum height (in text lines) which `resize-temp-buffer-window'
will give to a window displaying a temporary buffer.
It can also be a function which will be called with the object corresponding
(funcall temp-buffer-max-height (current-buffer))
temp-buffer-max-height))))
-;; Provide this for the sake of define-minor-mode which generates
-;; defcustoms which require 'help'.
+\f
(provide 'help)
;; arch-tag: cf427352-27e9-49b7-9a6f-741ebab02423