(eval-when-compile): Require `help-macro'.

(isearch-help-for-help-internal): Isearch specific Help screen
created by `make-help-screen'.
(isearch-help-map): New variable that binds "b", "k", "m" to
isearch-specific commands, and binds other keys to
isearch-other-control-char, thus allowing other Help keys to
exit isearch mode and execute their global definitions.
(isearch-help-for-help, isearch-describe-bindings)
(isearch-describe-key, isearch-describe-mode): New commands.
(isearch-mode-help): Define alias to isearch-describe-mode
and remove its old function definition.
(isearch-mode-map): Bind "\C-h" to isearch-help-map.
Remove old comments because this issue is settled now.
(isearch-forward): Describe three new Help commands in the docstring.
(isearch-mode): Remove \\{isearch-mode-map} from the docstring,
leave the single sentence at the first line of the docstring,
and prepend the word "function" before `isearch-forward'
to make the Help link to the function instead of variable.

2 files changed, 116 insertions, 13 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index d7ae805cc10..7db5250f09c 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,46 @@
 2008-04-22  Juri Linkov  <juri@jurta.org>
 
+        * isearch.el (eval-when-compile): Require `help-macro'.
+        (isearch-help-for-help-internal): Isearch specific Help screen
+        created by `make-help-screen'.
+        (isearch-help-map): New variable that binds "b", "k", "m" to
+        isearch-specific commands, and binds other keys to
+        isearch-other-control-char, thus allowing other Help keys to
+        exit isearch mode and execute their global definitions.
+        (isearch-help-for-help, isearch-describe-bindings)
+        (isearch-describe-key, isearch-describe-mode): New commands.
+        (isearch-mode-help): Define alias to isearch-describe-mode
+        and remove its old function definition.
+        (isearch-mode-map): Bind "\C-h" to isearch-help-map.
+        Remove old comments because this issue is settled now.
+        (isearch-forward): Describe three new Help commands in the docstring.
+        (isearch-mode): Remove \\{isearch-mode-map} from the docstring,
+        leave the single sentence at the first line of the docstring,
+        and prepend the word "function" before `isearch-forward'
+        to make the Help link to the function instead of variable.
+
+2008-04-22  Juri Linkov  <juri@jurta.org>
+
+        * isearch.el (isearch-success-function): New variable with default
+        to `isearch-success-function-default'.
+        (isearch-search): Call a function from `isearch-success-function'
+        instead of calling the hard-coded `isearch-range-invisible'.
+        (isearch-success-function-default): New function that calls
+        `isearch-range-invisible' and inverts its return value.
+
+        * info.el (Info-search): In two similar places that skip
+        undesired search matches move code to Info-search-success-function,
+        and call `isearch-success-function' instead.
+        (Info-search-success-function): New function copied from code
+        in Info-search.  Replace isearch-range-invisible with
+        text-property-not-all that checks for 'invisible and 'display
+        properties to skip partially invisible matches (whose display
+        properties were set by Info-fontify-node).
+        (Info-mode): Set buffer-local isearch-success-function
+        to Info-search-success-function.
+
+2008-04-22  Juri Linkov  <juri@jurta.org>
+
         * minibuffer.el (internal-complete-buffer-except): New function.
 
         * files.el (read-buffer-to-switch): New function.
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 92176236d5c..ef6321be02c 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -181,7 +181,7 @@ to the search status stack.")
 (defvar isearch-success-function 'isearch-success-function-default
   "Function to report whether the new search match is considered successful.
 The function has two arguments: the positions of start and end of text
-matched by the search.  It this function returns nil, continue
+matched by the search.  If this function returns nil, continue
 searching without stopping at this match.")
 
 ;; Search ring.
@@ -328,6 +328,73 @@ A value of nil means highlight all matches."
                                 'lazy-highlight-face
                                 "22.1")
 
+;; Define isearch help map.
+
+(defvar isearch-help-map
+  (let ((i 0)
+        (map (make-sparse-keymap)))
+    (define-key map [t] 'isearch-other-control-char)
+    (define-key map (char-to-string help-char) 'isearch-help-for-help)
+    (define-key map [help] 'isearch-help-for-help)
+    (define-key map [f1] 'isearch-help-for-help)
+    (define-key map "?" 'isearch-help-for-help)
+    (define-key map "b" 'isearch-describe-bindings)
+    (define-key map "k" 'isearch-describe-key)
+    (define-key map "m" 'isearch-describe-mode)
+    (define-key map "q" 'help-quit)
+    map)
+  "Keymap for characters following the Help key for isearch mode.")
+
+(eval-when-compile (require 'help-macro))
+
+(make-help-screen isearch-help-for-help-internal
+  "Type a help option: [bkm] or ?"
+  "You have typed %THIS-KEY%, the help character.  Type a Help option:
+\(Type \\<help-map>\\[help-quit] to exit the Help command.)
+
+b           Display all isearch key bindings.
+k KEYS      Display full documentation of isearch key sequence.
+m           Display documentation of isearch mode.
+
+You can't type here other help keys available in the global help map,
+but outise of this help window when you type them in isearch mode,
+they exit isearch mode before displaying global help."
+  isearch-help-map)
+
+(defun isearch-help-for-help ()
+  "Display isearch help menu."
+  (interactive)
+  (let (same-window-buffer-names same-window-regexps)
+    (isearch-help-for-help-internal))
+  (isearch-update))
+
+(defun isearch-describe-bindings ()
+  "Show a list of all keys defined in isearch mode, and their definitions.
+This is like `describe-bindings', but displays only isearch keys."
+  (interactive)
+  (let (same-window-buffer-names same-window-regexps)
+    (with-help-window "*Help*"
+      (with-current-buffer standard-output
+        (princ "Isearch Mode Bindings:\n")
+        (princ (substitute-command-keys "\\{isearch-mode-map}"))))))
+
+(defun isearch-describe-key ()
+  "Display documentation of the function invoked by isearch key."
+  (interactive)
+  (let (same-window-buffer-names same-window-regexps)
+    (call-interactively 'describe-key))
+  (isearch-update))
+
+(defun isearch-describe-mode ()
+  "Display documentation of isearch mode."
+  (interactive)
+  (let (same-window-buffer-names same-window-regexps)
+    (describe-function 'isearch-forward))
+  (isearch-update))
+
+(defalias 'isearch-mode-help 'isearch-describe-mode)
+
+
 ;; Define isearch-mode keymap.
 
 (defvar isearch-mode-map
@@ -394,9 +461,7 @@ A value of nil means highlight all matches."
     (define-key map "\M-\C-y" 'isearch-yank-char)
     (define-key map    "\C-y" 'isearch-yank-line)
 
-    ;; 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 "\C-h" isearch-help-map)
 
     (define-key map "\M-n" 'isearch-ring-advance)
     (define-key map "\M-p" 'isearch-ring-retreat)
@@ -581,6 +646,10 @@ Type \\[isearch-ring-retreat] to search for the previous item in the search\
  ring.
 Type \\[isearch-complete] to complete the search string using the search ring.
 
+Type \\[isearch-describe-bindings] to display all isearch key bindings.
+Type \\[isearch-describe-key] to display documentation of isearch key.
+Type \\[isearch-describe-mode] to display documentation of isearch mode.
+
 If an input method is turned on in the current buffer, that input
 method is also active while you are typing characters to search.  To
 toggle the input method, type \\[isearch-toggle-input-method].  It
@@ -633,12 +702,6 @@ is treated as a regexp.  See \\[isearch-forward] for more info."
   (interactive "P\np")
   (isearch-mode nil (null not-regexp) nil (not no-recursive-edit)))
 
-
-(defun isearch-mode-help ()
-  (interactive)
-  (describe-function 'isearch-forward)
-  (isearch-update))
-
 
 ;; isearch-mode only sets up incremental search for the minor mode.
 ;; All the work is done by the isearch-mode commands.
@@ -650,9 +713,8 @@ is treated as a regexp.  See \\[isearch-forward] for more info."
 
 
 (defun isearch-mode (forward &optional regexp op-fun recursive-edit word-p)
-  "Start isearch minor mode.  Called by `isearch-forward', etc.
-
-\\{isearch-mode-map}"
+  "Start isearch minor mode.
+It is called by the function `isearch-forward' and other related functions."
 
   ;; Initialize global vars.
   (setq isearch-forward forward