;;; help.el --- help commands for Emacs
;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002,
-;; 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+;; 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: help, internal
;; This file is part of GNU Emacs.
-;; GNU Emacs is free software; you can redistribute it and/or modify
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
-;; the Free Software Foundation; either version 3, or (at your option)
-;; any later version.
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with GNU Emacs; see the file COPYING. If not, write to the
-;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-;; Boston, MA 02110-1301, USA.
+;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; invoking `with-output-to-temp-buffer'. If and only if `help-window'
;; is eq to t, `help-mode-finish' (called by `temp-buffer-setup-hook')
;; sets `help-window' to the window selected by `display-buffer'.
-;; Exiting `with-help-window' and calling `print-help-return-message'
+;; Exiting `with-help-window' and calling `help-print-return-message'
;; reset `help-window' to nil.
(defvar help-window nil
"Window chosen for displaying help.")
(WINDOW . quit-window) do quit-window, then select WINDOW.
(WINDOW BUF START POINT) display BUF at START, POINT, then select WINDOW.")
-(defun print-help-return-message (&optional function)
+(define-obsolete-function-alias 'print-help-return-message 'help-print-return-message "23.2")
+(defun help-print-return-message (&optional function)
"Display or return message saying how to restore windows after help command.
This function assumes that `standard-output' is the help buffer.
It computes a message, and applies the optional argument FUNCTION to it.
(defalias 'help-for-help 'help-for-help-internal)
;; It can't find this, but nobody will look.
(make-help-screen help-for-help-internal
- "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?"
+ (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
+ ;; Don't purecopy this one, because it's not evaluated (it's
+ ;; directly used as a docstring in a function definition, so it'll
+ ;; be moved to the DOC file anyway: no need for purecopying it).
"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.)
I METHOD Describe a specific input method, or RET for current.
k KEYS Display the full documentation for the key sequence.
K KEYS Show the on-line manual's section for the command bound to KEYS.
-l Show last 100 characters you typed (lossage).
+l Show last 300 input keystrokes (lossage).
L LANG-ENV Describes a specific language environment, or RET for current.
m Display documentation of current minor modes and current major mode,
including their special commands.
(defun function-called-at-point ()
"Return a function around point or else called by the list containing point.
If that doesn't give a function, return nil."
- (or (with-syntax-table emacs-lisp-mode-syntax-table
- (or (condition-case ()
- (save-excursion
- (or (not (zerop (skip-syntax-backward "_w")))
- (eq (char-syntax (following-char)) ?w)
- (eq (char-syntax (following-char)) ?_)
- (forward-sexp -1))
- (skip-chars-forward "'")
- (let ((obj (read (current-buffer))))
- (and (symbolp obj) (fboundp obj) obj)))
- (error nil))
- (condition-case ()
- (save-excursion
- (save-restriction
- (narrow-to-region (max (point-min)
- (- (point) 1000)) (point-max))
- ;; Move up to surrounding paren, then after the open.
- (backward-up-list 1)
- (forward-char 1)
- ;; If there is space here, this is probably something
- ;; other than a real Lisp function call, so ignore it.
- (if (looking-at "[ \t]")
- (error "Probably not a Lisp function call"))
- (let ((obj (read (current-buffer))))
- (and (symbolp obj) (fboundp obj) obj))))
- (error nil))))
- (let* ((str (find-tag-default))
- (sym (if str (intern-soft str))))
- (if (and sym (fboundp sym))
- sym
- (save-match-data
- (when (and str (string-match "\\`\\W*\\(.*?\\)\\W*\\'" str))
- (setq sym (intern-soft (match-string 1 str)))
- (and (fboundp sym) sym)))))))
+ (with-syntax-table emacs-lisp-mode-syntax-table
+ (or (condition-case ()
+ (save-excursion
+ (or (not (zerop (skip-syntax-backward "_w")))
+ (eq (char-syntax (following-char)) ?w)
+ (eq (char-syntax (following-char)) ?_)
+ (forward-sexp -1))
+ (skip-chars-forward "'")
+ (let ((obj (read (current-buffer))))
+ (and (symbolp obj) (fboundp obj) obj)))
+ (error nil))
+ (condition-case ()
+ (save-excursion
+ (save-restriction
+ (narrow-to-region (max (point-min)
+ (- (point) 1000)) (point-max))
+ ;; Move up to surrounding paren, then after the open.
+ (backward-up-list 1)
+ (forward-char 1)
+ ;; If there is space here, this is probably something
+ ;; other than a real Lisp function call, so ignore it.
+ (if (looking-at "[ \t]")
+ (error "Probably not a Lisp function call"))
+ (let ((obj (read (current-buffer))))
+ (and (symbolp obj) (fboundp obj) obj))))
+ (error nil))
+ (let* ((str (find-tag-default))
+ (sym (if str (intern-soft str))))
+ (if (and sym (fboundp sym))
+ sym
+ (save-match-data
+ (when (and str (string-match "\\`\\W*\\(.*?\\)\\W*\\'" str))
+ (setq sym (intern-soft (match-string 1 str)))
+ (and (fboundp sym) sym))))))))
\f
;;; `User' help functions
(defun view-help-file (file &optional dir)
(view-file (expand-file-name file (or dir data-directory)))
- (goto-address)
+ (goto-address-mode 1)
(goto-char (point-min)))
(defun describe-distribution ()
(view-help-file "MORE.STUFF"))
(defun view-lossage ()
- "Display last 100 input keystrokes.
+ "Display last 300 input keystrokes.
To record all your input on a file, use `open-dribble-file'."
(interactive)
- (help-setup-xref (list #'view-lossage) (interactive-p))
+ (help-setup-xref (list #'view-lossage)
+ (called-interactively-p 'interactive))
(with-help-window (help-buffer)
(princ (mapconcat (lambda (key)
(if (or (integerp key) (symbolp key) (listp key))
or a buffer name."
(interactive)
(or buffer (setq buffer (current-buffer)))
- (help-setup-xref (list #'describe-bindings prefix buffer) (interactive-p))
+ (help-setup-xref (list #'describe-bindings prefix buffer)
+ (called-interactively-p 'interactive))
(with-current-buffer buffer
(describe-bindings-internal nil prefix)))
(if (or (null defn) (integerp defn) (equal defn 'undefined))
(message "%s%s is undefined"
(help-key-description key untranslated) mouse-msg)
- (help-setup-xref (list #'describe-function defn) (interactive-p))
+ (help-setup-xref (list #'describe-function defn)
+ (called-interactively-p 'interactive))
;; Don't bother user with strings from (e.g.) the select-paste menu.
(when (stringp (aref key (1- (length key))))
(aset key (1- (length key)) "(any string)"))
(interactive "@")
(unless buffer (setq buffer (current-buffer)))
(help-setup-xref (list #'describe-mode buffer)
- (interactive-p))
+ (called-interactively-p 'interactive))
;; For the sake of help-do-xref and help-xref-go-back,
;; don't switch buffers before calling `help-buffer'.
(with-help-window (help-buffer)
(help-window-display-message
(if reuse
;; Offer `display-buffer' for consistency with
- ;; `print-help-return-message'. This is hardly TRT when
+ ;; `help-print-return-message'. This is hardly TRT when
;; the other window and the selected window display the
;; same buffer but has been handled this way ever since.
"Type \\[display-buffer] RET to restore the other window"
;; (4) A marker (`help-window-point-marker') to move point in the help
;; window to an arbitrary buffer position.
-;; Note: It's usually always wrong to use `print-help-return-message' in
+;; Note: It's usually always wrong to use `help-print-return-message' in
;; the body of `with-help-window'.
(defmacro with-help-window (buffer-name &rest body)
"Display buffer BUFFER-NAME in a help window evaluating BODY.
Select help window if the actual value of the user option
-`help-window-select' says so."
+`help-window-select' says so. Return last value in BODY."
(declare (indent 1) (debug t))
;; Bind list-of-frames to `frame-list' and list-of-window-tuples to a
;; list of one <window window-buffer window-start window-point> tuple
list))
'no-mini t)
list)))
- ;; We set `help-window' to t in order to trigger `help-mode-finish'
- ;; to set `help-window' to the actual help window.
+ ;; Make `help-window' t to trigger `help-mode-finish' to set
+ ;; `help-window' to the actual help window.
(setq help-window t)
;; Make `help-window-point-marker' point nowhere (the only place
;; where this should be set to a buffer position is within BODY).
(set-marker help-window-point-marker nil)
-
- (with-output-to-temp-buffer ,buffer-name
- (progn ,@body))
-
- (when (windowp help-window)
- ;; Set up help window.
- (help-window-setup list-of-frames list-of-window-tuples))
-
- ;; Reset `help-window' to nil to avoid confusing future calls of
- ;; `help-mode-finish' by "plain" `with-output-to-temp-buffer'.
- (setq help-window nil)))
+ (prog1
+ ;; Return value returned by `with-output-to-temp-buffer'.
+ (with-output-to-temp-buffer ,buffer-name
+ (progn ,@body))
+ (when (windowp help-window)
+ ;; Set up help window.
+ (help-window-setup list-of-frames list-of-window-tuples))
+ ;; Reset `help-window' to nil to avoid confusing future calls of
+ ;; `help-mode-finish' with plain `with-output-to-temp-buffer'.
+ (setq help-window nil))))
\f
(provide 'help)