Re: Suggestions for the temporary windows used from the minibuffer

[Lennart Borgman]

Richard M. Stallman wrote:

>    It does not work for C-h ?. Maybe that is the only important case though.
>
> That is handled by very special code.  Would you like to implement
> C-M-v in it?
>  
I have already sent a patch for this but I have a new one here that I 
think is better. The help function in isearch-mode does not work. This 
patch also addresses that issue.

The patch makes it possible to both reach normal help (C-h, f1) and the 
special isearch help from isearch-forward/backward. It also allow the 
help buffer to be scrolled in both case while still at the isearch prompt.

As you might have noticed I think it is important to make it easier for 
beginners and this is a patch towards that goal.
Index: help.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help.el,v
retrieving revision 1.283
diff -u -r1.283 help.el
--- help.el     4 Jul 2005 23:08:54 -0000       1.283
+++ help.el     7 Aug 2005 22:20:35 -0000
@@ -1,7 +1,7 @@
 ;;; help.el --- help commands for Emacs
 
-;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002, 2004,
-;;   2005  Free Software Foundation, Inc.
+;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002,
+;;   2003, 2004, 2005 Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
 ;; Keywords: help, internal
@@ -186,8 +186,8 @@
 (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 ? 
:"
   "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.)
-
+\(Use Page Up/Down to scroll through this text.  Type 
\\<help-map>\\[help-quit] to exit the Help command.)
+%X-DESCRIPTION%
 a  command-apropos.  Give a substring, and see a list of commands
        (functions that are interactively callable) that contain
        that substring.  See also the  apropos  command.
Index: help-macro.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-macro.el,v
retrieving revision 1.33
diff -u -r1.33 help-macro.el
--- help-macro.el       4 Jul 2005 23:08:54 -0000       1.33
+++ help-macro.el       7 Aug 2005 22:20:52 -0000
@@ -1,6 +1,7 @@
 ;;; help-macro.el --- makes command line help such as help-for-help
 
-;; Copyright (C) 1993, 1994 Free Software Foundation, Inc.
+;; Copyright (C) 1993, 1994, 2002, 2003, 2004,
+;;   2005 Free Software Foundation, Inc.
 
 ;; Author: Lynn Slater <address@hidden>
 ;; Maintainer: FSF
@@ -82,21 +83,32 @@
 
 (defmacro make-help-screen (fname help-line help-text helped-map)
   "Construct help-menu function name FNAME.
-When invoked, FNAME shows HELP-LINE and reads a command using HELPED-MAP.
-If the command is the help character, FNAME displays HELP-TEXT
-and continues trying to read a command using HELPED-MAP.
+When invoked, FNAME shows HELP-LINE and reads a command using
+HELPED-MAP.  If the command is the help character, FNAME displays
+HELP-TEXT and continues trying to read a command using
+HELPED-MAP.
+
 If HELP-TEXT contains the sequence `%THIS-KEY%', that is replaced
 with the key sequence that invoked FNAME.
+
+When calling FNAME if the optional parameters X-FUNCTION, X-CHAR
+and X-DESCRIPTION to the defined function FNAME are given they
+must all be given.  In this case the the sequence
+`%X-DESCRIPTION%' in HELP-TEXT is replaced with the parameters
+X-CHAR character and the X-DESCRIPTION string.  Also the keyboard
+character X-CHAR is bound to the parameter X-FUNCTION.
+
 When FNAME finally does get a command, it executes that command
 and then returns."
  (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
   `(progn
     (defun ,doc-fn () ,help-text)
-    (defun ,fname ()
+    (defun ,fname (&optional x-function x-char x-description)
           "Help command."
           (interactive)
           (let ((line-prompt
                  (substitute-command-keys ,help-line)))
+             (when x-char (setq line-prompt (concat (char-to-string x-char) " 
" line-prompt)))
             (if three-step-help
                 (message "%s" line-prompt))
             (let* ((help-screen (documentation (quote ,doc-fn)))
@@ -104,6 +116,12 @@
                    ;; sections, *excluding* where we switch buffers
                    ;; and where we execute the chosen help command.
                    (local-map (make-sparse-keymap))
+                    ;; Some keys should still be available
+                    (still-map (make-sparse-keymap))
+                    (still-lst (list '(scroll-other-window-down . scroll-down)
+                                     '(scroll-other-window      . scroll-up)))
+                    still-cmd
+                    (curr-wind (selected-window))
                    (minor-mode-map-alist nil)
                    (prev-frame (selected-frame))
                    config new-frame key char)
@@ -111,9 +129,28 @@
                   (setq help-screen
                         (replace-match (key-description (substring 
(this-command-keys) 0 -1))
                                        t t help-screen)))
+               (when (string-match "%X-DESCRIPTION%" help-screen)
+                 (let ((x-repl
+                        (if x-description
+                            (format "\n%s  %s\n\n" (char-to-string x-char) 
x-description)
+                          "")))
+                   (setq help-screen
+                         (replace-match x-repl
+                                        t t help-screen))))
+               (mapc (lambda (elt)
+                       (let ((new  (if (consp elt) (cdr elt) elt))
+                             (orig (if (consp elt) (car elt) elt)))
+                         (mapc (lambda (key)
+                                 (define-key still-map key new))
+                               (where-is-internal orig))))
+                     still-lst)
+               ;; Maybe it is good for new users with just next/prior?
+               (define-key still-map [(next)]  'scroll-up)
+               (define-key still-map [(prior)] 'scroll-down)
               (unwind-protect
                   (progn
                     (setcdr local-map ,helped-map)
+                     (when x-function (define-key local-map (make-vector 1 
x-char) x-function))
                     (define-key local-map [t] 'undefined)
                     ;; Make the scroll bar keep working normally.
                     (define-key local-map [vertical-scroll-bar]
@@ -145,7 +182,8 @@
                           (while (or (memq char (append help-event-list
                                                         (cons help-char '(?? 
?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
                                      (eq (car-safe char) 'switch-frame)
-                                     (equal key "\M-v"))
+                                     (equal key "\M-v")
+                                      still-cmd)
                             (condition-case nil
                                 (progn
                                   (if (eq (car-safe char) 'switch-frame)
@@ -160,12 +198,23 @@
                             (let ((cursor-in-echo-area t)
                                   (overriding-local-map local-map))
                               (setq key (read-key-sequence
-                                         (format "Type one of the options 
listed%s: "
-                                                 (if (pos-visible-in-window-p
-                                                      (point-max))
-                                                     "" ", or SPACE or DEL to 
scroll")))
-                                    char (aref key 0)))
-
+                                         (format "Type one of the options 
listed, or %s: "
+                                                 (if (pos-visible-in-window-p 
(point-max))
+                                                     "Page Up"
+                                                    (if 
(pos-visible-in-window-p (point-min))
+                                                        "Page Down"
+                                                      "or Page Up/Down to 
scroll"))))
+                                     char (aref key 0)))
+                             
+                             ;; If this is one of the commands we still should 
run then run it.
+                             (setq still-cmd (lookup-key still-map key))
+                             (when still-cmd
+                               (let ((cmd (assq still-cmd still-lst)))
+                                 (unless cmd (setq cmd still-cmd))
+                                 (condition-case nil
+                                     (command-execute cmd nil key)
+                                   (error nil))))
+                             
                             ;; If this is a scroll bar command, just run it.
                             (when (eq char 'vertical-scroll-bar)
                               (command-execute (lookup-key local-map key) nil 
key)))))
@@ -180,19 +229,23 @@
                       (let ((defn (lookup-key local-map key)))
                         (if defn
                             (progn
-                              (if config
-                                  (progn
-                                    (set-window-configuration config)
-                                    (setq config nil)))
-                              (if new-frame
-                                  (progn (iconify-frame new-frame)
-                                         (setq new-frame nil)))
-                              (call-interactively defn))
-                          (ding)))))
-                (if new-frame (iconify-frame new-frame))
-                (if config
-                    (set-window-configuration config))))))
-     )))
+                               ;; Do not restore in this case since we are 
still in help
+                               (when (eq defn x-function)
+                                 (unless new-frame
+                                   (select-window curr-wind)
+                                     (setq config nil)))
+                               (if config
+                                   (progn
+                                     (set-window-configuration config)
+                                     (setq config nil)))
+                               (if new-frame
+                                   (progn (iconify-frame new-frame)
+                                          (setq new-frame nil)))
+                               (call-interactively defn))
+                           (ding)))))
+                 (if new-frame (iconify-frame new-frame))
+                 (if config
+                     (set-window-configuration config)))))))))
 
 (provide 'help-macro)
 
Index: isearch.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/isearch.el,v
retrieving revision 1.268
diff -u -r1.268 isearch.el
--- isearch.el  28 Jul 2005 13:55:16 -0000      1.268
+++ isearch.el  7 Aug 2005 22:21:22 -0000
@@ -298,6 +298,28 @@
 
 ;; Define isearch-mode keymap.
 
+(defun isearch-scroll-other-down()
+  (interactive)
+  (let ((hbw (get-buffer-window "*Help*")))
+    (when hbw
+      (condition-case nil
+          (save-selected-window
+            (select-window hbw t)
+            (scroll-down))
+        (error nil))
+      (isearch-update))))
+
+(defun isearch-scroll-other-up()
+  (interactive)
+  (let ((hbw (get-buffer-window "*Help*")))
+    (when hbw
+      (condition-case nil
+          (save-selected-window
+            (select-window hbw t)
+            (scroll-up))
+        (error nil))
+      (isearch-update))))
+
 (defvar isearch-mode-map
   (let* ((i 0)
         (map (make-keymap)))
@@ -369,6 +391,12 @@
     ;; Turned off because I find I expect to get the global definition--rms.
     ;; ;; Instead bind C-h to special help command for isearch-mode.
     ;; (define-key map "\C-h" 'isearch-mode-help)
+    (define-key map [(f1)] 'isearch-help-for-help)
+    (define-key map "\C-h" 'isearch-mode-help)
+    (define-key map [(meta prior)] 'isearch-scroll-other-down)
+    (define-key map [(meta next)]  'isearch-scroll-other-up)
+    (define-key map [(prior)] 'isearch-scroll-other-down)
+    (define-key map [(next)]  'isearch-scroll-other-up)
 
     (define-key map "\M-n" 'isearch-ring-advance)
     (define-key map "\M-p" 'isearch-ring-retreat)
@@ -604,6 +632,28 @@
 (defun isearch-mode-help ()
   (interactive)
   (describe-function 'isearch-forward)
+  (isearch-update))
+
+(defun isearch-mode-help-when-active()
+  (interactive)
+  (let ((w (selected-window))
+        (b (current-buffer)))
+    (save-selected-window
+      (unless (get-buffer-window "*Help*")
+        (switch-to-buffer-other-window "*Help*" t))
+      (with-current-buffer (get-buffer "*Help*")
+        (setq buffer-read-only nil)
+        (erase-buffer)
+        (insert (documentation 'isearch-mode))
+        (help-mode)
+        (goto-char (point-min))))
+    (select-window w)
+    (set-buffer b)))
+
+(defun isearch-help-for-help()
+  (interactive)
+  (help-for-help 'isearch-mode-help-when-active ?x "isearch mode help")
+  (sit-for 9)
   (isearch-update))