;;; help-mode.el --- `help-mode' used by *Help* buffers
;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002,
-;; 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+;; 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: help, internal
;; 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 2, or (at your option)
+;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;; GNU Emacs is distributed in the hope that it will be useful,
(define-key help-mode-map [mouse-2] 'help-follow-mouse)
(define-key help-mode-map "\C-c\C-b" 'help-go-back)
+(define-key help-mode-map "\C-c\C-f" 'help-go-forward)
(define-key help-mode-map "\C-c\C-c" 'help-follow-symbol)
;; Documentation only, since we use minor-mode-overriding-map-alist.
(define-key help-mode-map "\r" 'help-follow)
(put 'help-xref-stack 'permanent-local t)
(make-variable-buffer-local 'help-xref-stack)
+(defvar help-xref-forward-stack nil
+ "The stack of used to navigate help forwards after using the back button.
+Used by `help-follow' and `help-xref-go-forward'.
+An element looks like (POSITION FUNCTION ARGS...).
+To use the element, do (apply FUNCTION ARGS) then goto the point.")
+(put 'help-xref-forward-stack 'permanent-local t)
+(make-variable-buffer-local 'help-xref-forward-stack)
+
(defvar help-xref-stack-item nil
"An item for `help-follow' in this buffer to push onto `help-xref-stack'.
The format is (FUNCTION ARGS...).")
(put 'help-xref-stack-item 'permanent-local t)
(make-variable-buffer-local 'help-xref-stack-item)
+(defvar help-xref-stack-forward-item nil
+ "An item for `help-go-back' to push onto `help-xref-forward-stack'.
+The format is (FUNCTION ARGS...).")
+(put 'help-xref-stack-forward-item 'permanent-local t)
+(make-variable-buffer-local 'help-xref-stack-forward-item)
+
(setq-default help-xref-stack nil help-xref-stack-item nil)
+(setq-default help-xref-forward-stack nil help-xref-forward-stack-item nil)
(defcustom help-mode-hook nil
"Hook run by `help-mode'."
'help-function #'help-xref-go-back
'help-echo (purecopy "mouse-2, RET: go back to previous help buffer"))
+(define-button-type 'help-forward
+ :supertype 'help-xref
+ 'help-function #'help-xref-go-forward
+ 'help-echo (purecopy "mouse-2, RET: move forward to next help buffer"))
+
(define-button-type 'help-info
:supertype 'help-xref
'help-function #'info
(let ((location
(find-function-search-for-symbol fun nil file)))
(pop-to-buffer (car location))
- (goto-char (cdr location))))
+ (if (cdr location)
+ (goto-char (cdr location))
+ (message "Unable to find location in file"))))
'help-echo (purecopy "mouse-2, RET: find function's definition"))
(define-button-type 'help-variable-def
(setq file (help-C-file-name var 'var)))
(let ((location (find-variable-noselect var file)))
(pop-to-buffer (car location))
- (goto-char (cdr location))))
- 'help-echo (purecopy"mouse-2, RET: find variable's definition"))
+ (if (cdr location)
+ (goto-char (cdr location))
+ (message "Unable to find location in file"))))
+ 'help-echo (purecopy "mouse-2, RET: find variable's definition"))
(define-button-type 'help-face-def
:supertype 'help-xref
(let ((location
(find-function-search-for-symbol fun 'defface file)))
(pop-to-buffer (car location))
- (goto-char (cdr location))))
+ (if (cdr location)
+ (goto-char (cdr location))
+ (message "Unable to find location in file"))))
'help-echo (purecopy "mouse-2, RET: find face's definition"))
\f
(use-local-map help-mode-map)
(setq mode-name "Help")
(setq major-mode 'help-mode)
+
(view-mode)
- (make-local-variable 'view-no-disable-on-exit)
- (setq view-no-disable-on-exit t)
+ (set (make-local-variable 'view-no-disable-on-exit) t)
+ ;; With Emacs 22 `view-exit-action' could delete the selected window
+ ;; disregarding whether the help buffer was shown in that window at
+ ;; all. Since `view-exit-action' is called with the help buffer as
+ ;; argument it seems more appropriate to have it work on the buffer
+ ;; only and leave it to `view-mode-exit' to delete any associated
+ ;; window(s).
+ (setq view-exit-action
+ (lambda (buffer)
+ ;; Use `with-current-buffer' to make sure that `bury-buffer'
+ ;; also removes BUFFER from the selected window.
+ (with-current-buffer buffer
+ (bury-buffer))))
+
(run-mode-hooks 'help-mode-hook))
;;;###autoload
;;;###autoload
(defun help-mode-finish ()
- (let ((entry (assq (selected-window) view-return-to-alist)))
- (if entry
- ;; When entering Help mode from the Help window,
- ;; such as by following a link, preserve the same
- ;; meaning for the q command.
- ;; (setcdr entry (cons (selected-window) help-return-method))
- nil
- (setq view-return-to-alist
- (cons (cons (selected-window) help-return-method)
- view-return-to-alist))))
+ (if (eq help-window t)
+ ;; If `help-window' is t, `view-return-to-alist' is handled by
+ ;; `with-help-window'. In this case set `help-window' to the
+ ;; selected window since now is the only moment where we can
+ ;; unambiguously identify it.
+ (setq help-window (selected-window))
+ (let ((entry (assq (selected-window) view-return-to-alist)))
+ (if entry
+ ;; When entering Help mode from the Help window,
+ ;; such as by following a link, preserve the same
+ ;; meaning for the q command.
+ ;; (setcdr entry (cons (selected-window) help-return-method))
+ nil
+ (setq view-return-to-alist
+ (cons (cons (selected-window) help-return-method)
+ view-return-to-alist)))))
+
(when (eq major-mode 'help-mode)
;; View mode's read-only status of existing *Help* buffer is lost
;; by with-output-to-temp-buffer.
(defvar help-back-label (purecopy "[back]")
"Label to use by `help-make-xrefs' for the go-back reference.")
+(defvar help-forward-label (purecopy "[forward]")
+ "Label to use by `help-make-xrefs' for the go-forward reference.")
+
(defconst help-xref-symbol-regexp
(purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|" ; Link to var
- "\\(function\\|command\\)\\|" ; Link to function
- "\\(face\\)\\|" ; Link to face
- "\\(symbol\\|program\\)\\|" ; Don't link
+ "\\(function\\|command\\)\\|" ; Link to function
+ "\\(face\\)\\|" ; Link to face
+ "\\(symbol\\|program\\|property\\)\\|" ; Don't link
"\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
"[ \t\n]+\\)?"
;; Note starting with word-syntax character:
restore it properly when going back."
(with-current-buffer (help-buffer)
(when help-xref-stack-item
- (push (cons (point) help-xref-stack-item) help-xref-stack))
+ (push (cons (point) help-xref-stack-item) help-xref-stack)
+ (setq help-xref-forward-stack nil))
(when interactive-p
(let ((tail (nthcdr 10 help-xref-stack)))
;; Truncate the stack.
(defvar help-xref-following nil
"Non-nil when following a help cross-reference.")
+;;;###autoload
(defun help-buffer ()
(buffer-name ;for with-output-to-temp-buffer
(if help-xref-following
;; An obvious case of a key substitution:
(save-excursion
(while (re-search-forward
- ;; Assume command name is only word characters
- ;; and dashes to get things like `use M-x foo.'.
- "\\<M-x\\s-+\\(\\sw\\(\\sw\\|-\\)+\\)" nil t)
+ ;; Assume command name is only word and symbol
+ ;; characters to get things like `use M-x foo->bar'.
+ ;; Command required to end with word constituent
+ ;; to avoid `.' at end of a sentence.
+ "\\<M-x\\s-+\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)" nil t)
(let ((sym (intern-soft (match-string 1))))
(if (fboundp sym)
(help-xref-button 1 'help-function sym)))))
;; Skip a single blank line.
(and (eolp) (forward-line))
(end-of-line)
- (skip-chars-backward "^\t\n")
+ (skip-chars-backward "^ \t\n")
(if (and (>= (current-column) col)
- (looking-at "\\(\\sw\\|-\\)+$"))
+ (looking-at "\\(\\sw\\|\\s_\\)+$"))
(let ((sym (intern-soft (match-string 0))))
(if (fboundp sym)
(help-xref-button 0 'help-function sym))))
(while (and (not (bobp)) (bolp))
(delete-char -1))
(insert "\n")
+ (when (or help-xref-stack help-xref-forward-stack)
+ (insert "\n"))
;; Make a back-reference in this buffer if appropriate.
(when help-xref-stack
- (insert "\n")
(help-insert-xref-button help-back-label 'help-back
- (current-buffer))
+ (current-buffer)))
+ ;; Make a forward-reference in this buffer if appropriate.
+ (when help-xref-forward-stack
+ (when help-xref-stack
+ (insert "\t"))
+ (help-insert-xref-button help-forward-label 'help-forward
+ (current-buffer)))
+ (when (or help-xref-stack help-xref-forward-stack)
(insert "\n")))
;; View mode steals RET from us.
(set (make-local-variable 'minor-mode-overriding-map-alist)
"From BUFFER, go back to previous help buffer text using `help-xref-stack'."
(let (item position method args)
(with-current-buffer buffer
+ (push (cons (point) help-xref-stack-item) help-xref-forward-stack)
(when help-xref-stack
(setq item (pop help-xref-stack)
;; Clear the current item so that it won't get pushed
(set-window-point (get-buffer-window buffer) position)
(goto-char position)))))
+(defun help-xref-go-forward (buffer)
+ "From BUFFER, go forward to next help buffer."
+ (let (item position method args)
+ (with-current-buffer buffer
+ (push (cons (point) help-xref-stack-item) help-xref-stack)
+ (when help-xref-forward-stack
+ (setq item (pop help-xref-forward-stack)
+ ;; Clear the current item so that it won't get pushed
+ ;; by the function we're about to call. TODO: We could also
+ ;; push it onto a "forward" stack and add a `forw' button.
+ help-xref-stack-item nil
+ position (car item)
+ method (cadr item)
+ args (cddr item))))
+ (apply method args)
+ (with-current-buffer buffer
+ (if (get-buffer-window buffer)
+ (set-window-point (get-buffer-window buffer) position)
+ (goto-char position)))))
+
(defun help-go-back ()
"Go back to previous topic in this help buffer."
(interactive)
(help-xref-go-back (current-buffer))
(error "No previous help buffer")))
+(defun help-go-forward ()
+ "Go back to next topic in this help buffer."
+ (interactive)
+ (if help-xref-forward-stack
+ (help-xref-go-forward (current-buffer))
+ (error "No next help buffer")))
+
(defun help-do-xref (pos function args)
"Call the help cross-reference function FUNCTION with args ARGS.
Things are set up properly so that the resulting help-buffer has