[PATCH] Forward button for help buffer

[PATCH] Forward button for help buffer

[Nick Roberts]

Here's a patch (from about two years ago!) that gives the help buffer a
forward button so that, with the back button, it functions a bit like
web browsers do.

OK to apply to the trunk now?

-- 
Nick                                           http://www.inet.net.nz/~nickrob



*** help-mode.el	21 Jan 2007 16:53:11 +1300	1.51
--- help-mode.el	07 Jun 2007 10:21:12 +1200	
***************
*** 40,45 ****
--- 40,46 ----
  
  (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)
*************** To use the element, do (apply FUNCTION A
*** 52,64 ****
--- 53,80 ----
  (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'."
*************** The format is (FUNCTION ARGS...).")
*** 123,128 ****
--- 139,149 ----
    '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
*************** Commands:
*** 242,247 ****
--- 263,271 ----
  (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
*************** because we want to record the \"previous
*** 286,292 ****
  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))
      (when interactive-p
        (let ((tail (nthcdr 10 help-xref-stack)))
  	;; Truncate the stack.
--- 310,317 ----
  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)
!       (setq help-xref-forward-stack nil))
      (when interactive-p
        (let ((tail (nthcdr 10 help-xref-stack)))
  	;; Truncate the stack.
*************** that."
*** 480,485 ****
--- 505,515 ----
  	  (insert "\n")
  	  (help-insert-xref-button help-back-label 'help-back
  				   (current-buffer))
+           (insert "\t"))
+         ;; Make a forward-reference in this buffer if appropriate.
+         (when help-xref-forward-stack
+ 	  (help-insert-xref-button help-forward-label 'help-forward
+ 				   (current-buffer))
            (insert "\n")))
        ;; View mode steals RET from us.
        (set (make-local-variable 'minor-mode-overriding-map-alist)
*************** help buffer."
*** 598,603 ****
--- 628,634 ----
    "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
*************** help buffer."
*** 613,624 ****
--- 644,682 ----
  	  (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)
    (if help-xref-stack
        (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.

Re: [PATCH] Forward button for help buffer

[martin rudalics]

[-- Attachment #1: Type: text/plain, Size: 210 bytes --]

The forward buttons are nice, thanks.  One minor nitpick: When there's
only a forward-button and no back-button there's no newline before the
forward-button.  Please consider something like the attached patch.

[-- Attachment #2: help-mode.patch --]
[-- Type: text/plain, Size: 1568 bytes --]

*** help-mode.el	Sun Jun 10 17:46:38 2007
--- help-mode.el	Mon Jun 11 08:44:02 2007
***************
*** 500,515 ****
  	(while (and (not (bobp)) (bolp))
  	  (delete-char -1))
          (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))
!           (insert "\t"))
          ;; Make a forward-reference in this buffer if appropriate.
          (when help-xref-forward-stack
  	  (help-insert-xref-button help-forward-label 'help-forward
! 				   (current-buffer))
            (insert "\n")))
        ;; View mode steals RET from us.
        (set (make-local-variable 'minor-mode-overriding-map-alist)
--- 500,518 ----
  	(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
  	  (help-insert-xref-button help-back-label 'help-back
! 				   (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)

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: [PATCH] Forward button for help buffer

[Nick Roberts]

 > The forward buttons are nice, thanks.  One minor nitpick: When there's
 > only a forward-button and no back-button there's no newline before the
 > forward-button.  Please consider something like the attached patch.

Fine with me.

I had further patches (which I've lost now):

1) Using the info-xref-visited for items that have been viewed.  (This would
   require those that haven't to use info-xref though.)

2) Fontify the value which is helpful for complex values like keymaps,
   auto-mode-alist.


-- 
Nick                                           http://www.inet.net.nz/~nickrob