RE: Exposing Isearch toggleable options

[Drew Adams <drew.adams@oracle.com>]

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

> I'm not yet sure if this is worth merging to master, so I'd
> very much appreciate opinions.

FWIW, I amnot in favor of it.  I'd prefer that users consult
the Isearch help for such info.

I have many more togglable options, and Emacs might in the
future also.

And there are many aspects regarding the current Isearch state
that it would be worthwhile indicating to users (either on an
ongoing basis or on demand, depending on the aspect of state).

The current value of a togglable variable, as well as the key
to toggle it, is info that falls in that category: it is part
of the current state.  I'd sooner see this info handled along
with other state info.  We've discussed this in other threads,
I believe.

----

FWIW, in my code I bind `C-h' to a modified version of
`isearch-mode-help' that not only shows the help but also 
exits Isearch.  I find that more useful than (a) requiring
`C-h m' and (b) keeping Isearch active.

Users need to be able to explore the *Help* buffer.  Especially
if there is a lot of info there, and in my version it lists
all of the Isearch bindings, in addition to showing the doc
string of `isearch-forward' (which in my case is longer).

I think it makes little sense to keep Isearch open during this
time.  It is trivial to restart Isearch.

FWIW, this is the definition I use, and bind to `C-h' in
`isearch-mode-map':

(defun isearch-mode-help ()
  "Display information on interactive search in buffer *Help*."
  (interactive)
  (describe-function 'isearch-forward)
  (isearch-done)
  (isearch-clean-overlays)
  (with-current-buffer "*Help*"
    (goto-char (point-max))
    (let ((buffer-read-only  nil)) (insert (substitute-command-keys "

Bindings in Isearch minor mode:
------------------------------

\\{isearch-mode-map}")))))

Attached is what *Help* shows for Isearch in my context.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: throw-isearch-help3.txt --]
[-- Type: text/plain; charset=Windows-1252; name="throw-isearch-help3.txt", Size: 10277 bytes --]

isearch-forward is an interactive Lisp function in `isearch+.el'.

It is bound to C-s, <menu-bar> <edit> <search> <i-search>
<isearch-forward>.

(isearch-forward &optional ARG NO-RECURSIVE-EDIT)

Search forward incrementally - Isearch+ version.

With a non-negative prefix arg, do an incremental regular expression
search instead.

With a negative prefix arg, do a (plain, not regexp) incremental
search across multiple buffers:
 * If the prefix arg is `-' (from `M--') then you are prompted for the
   list of buffers. 
 * Otherwise, (e.g. `M-- 2'), you are prompted for a regexp that
   matches the names of the buffers to be searched.

If you try to exit with the search string empty then nonincremental
search is used.


As you type characters, they add to the search string and are found.
The following non-printing keys are bound in `isearch-mode-map'.

Options
-------
`isearchp-case-fold'			- search is case sensitive?
`isearchp-dim-outside-search-area-flag' [*] - dim non-search zones?
`isearchp-dimming-color' [*]		- color for non-search zones
`isearchp-set-region-flag'		- select last search target?
`isearchp-restrict-to-region-flag'	- restrict search to region?
`isearchp-deactivate-region-flag'	- search deactivates region?
`isearchp-ignore-comments-flag' [*]	- ignore THINGs in comments?
`isearchp-hide-whitespace-before-comment-flag' [*] - precomment space?
`isearchp-mouse-2-flag'		- `mouse-2' anywhere yanks selection?
`isearchp-regexp-quote-yank-flag'	- regexp-quote yanked text?
`isearchp-toggle-option-flag'		- toggle options too?
`isearchp-drop-mismatch'	- handling input after search mismatch
`isearchp-drop-mismatch-regexp-flag'	- regexp search drop mismatch?
`isearchp-initiate-edit-commands'	- keys that edit, not exit

 [*] Requires library `isearch-prop.el'.

Commands
--------
DEL	- cancel last input item from end of search string
RET	- exit, leaving point at location found
C-s	- search again forward, C-r backward
C-y C-w	- yank a word or char from buffer onto search string
C-z	- yank a char from buffer onto search string
C-M-w	- delete char from end of search string
C-y C-e	- yank text up to end of line onto search string
C-y C-y	- yank the last string of killed or copied text
M-y	- replace string just yanked with string killed/copied before it
M-w	- copy current search string to kill ring
C-_	- yank a symbol or char from buffer onto search string
C-(	- yank sexp, symbol, or char from buffer onto search string
C-q	- quote a control character, to search for it
C-x 8 RET	- add a Unicode char to search string by Unicode name
C-M-l	- remove failed part of search string, if any
C-g	- remove failed part of search string, or cancel if none
C-x o	- invoke Emacs command loop recursively, during Isearch
M-g	- insert successful search string from when you hit `C-g'
M-s e	- edit the search string in the minibuffer
M-n, M-p	- search for next/previous item in search ring
C-M-i	- complete the search string using the search ring
M-%	- run `query-replace' to replace search-string matches
C-M-%	- run `query-replace-regexp'
M-s o	- run `occur' for search-string matches
M-s h r	- run `highlight-regexp' to highlight search-string matches
M-x isearchp-fontify-buffer-now	- fontify whole buffer
M-x isearchp-set-region-around-search-target	- select last search

<f1> b	- list all Isearch key bindings
<f1> k	- show documentation of an Isearch key
<f1> m	- show documentation for Isearch mode

M-k	- cycle option `isearchp-drop-mismatch'
M-s c	- toggle case-sensitivity (for current search or more: `C-u')
M-s h l	- option `lazy-highlight-cleanup' (removal of highlighting)
C-+	- toggle searching invisible text
M-s i	- toggle searching invisible text, for current search or more
M-s v	- toggle option `isearchp-toggle-option-flag'
C-x n	- toggle restricting search to active region
C-SPC	- toggle setting region around search target
C-`	- toggle quoting (escaping) of regexp special characters
M-s w	- toggle word-searching
M-s _	- toggle symbol-searching
M-s SPC	- toggle whitespace matching

A `SPC' char normally matches all whitespace defined by variable
`search-whitespace-regexp'.  See also variables
`isearch-lax-whitespace' and `isearch-regexp-lax-whitespace'.

Commands that Require Library `isearch-prop.el'
----------------------------------------------- 

C-t	- search for a character (overlay or text) property
C-M-t	- regexp-search for a character (overlay or text) property
C-M-~	- toggle searching complements of normal search contexts
C-M-S-d	- toggle dimming non-search zones
C-M-;	- toggle ignoring comments for `isearchp-thing'
M-;	- hide or (`C-u') show comments

M-x isearchp-put-prop-on-region	- add a text property to region
M-x isearchp-add-regexp-as-property	- add prop to regexp matches
M-x isearchp-regexp-context-search	- search regexp contexts
M-x isearchp-regexp-define-contexts	- define regexp contexts

M-x isearchp-imenu 	- search Emacs-Lisp definitions
M-x isearchp-imenu-command 	- search Emacs command definitions
M-x isearchp-imenu-non-interactive-function 	- search non-commands
M-x isearchp-imenu-macro 	- search Emacs-Lisp macro definitions

M-x isearchp-thing	- search THING search contexts
M-x isearchp-thing-define-contexts	- define THING contexts
M-x isearchp-previous-visible-thing	- go to previous visible THING
M-x isearchp-next-visible-thing	- go to next visible THING

Input Methods
-------------

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 C-\.  It also toggles the input
method in the current buffer.

To use a different input method for searching, type C-^,
and specify an input method you want to use.

---

The above keys, bound in `isearch-mode-map', are often controlled by
user options - do M-x apropos on search-.* to find them.

If either option `isearch-allow-prefix' or option
`isearch-allow-scroll' is non-nil then you can use a prefix arg with
an Isearch key.  If option `isearch-allow-scroll' is non-nil then you
can use scrolling keys without exiting Isearch.

If these options are both nil then other control and meta chars
terminate the search and are then used normally (depending on
`search-exit-option').  Likewise for function keys and mouse button
events.

If this function is called non-interactively with nil argument
NO-RECURSIVE-EDIT then it does not return to the calling function
until the search is done.  See function `isearch-mode'.


Bindings in Isearch minor mode:
------------------------------

key             binding
---             -------

TAB .. C-j	isearch-printing-char
SPC .. ~	isearch-printing-char
€ .. ø¿½¿	isearch-printing-char
€ .. ÿ	isearch-printing-char

C-g		isearch-abort
C-h		isearch-mode-help
RET		isearch-exit
C-q		isearch-quote-char
C-r		isearch-repeat-backward
C-s		isearch-repeat-forward
C-t		isearchp-property-forward
C-w		isearch-yank-word-or-char
C-x		Prefix Command
C-y		Prefix Command
C-z		isearchp-yank-char
ESC		Prefix Command
C-\		isearch-toggle-input-method
C-^		isearch-toggle-specified-input-method
C-_		isearchp-yank-symbol-or-char
DEL		isearch-delete-char
S-SPC		isearch-printing-char
C-SPC		isearchp-toggle-set-region
C-(		isearchp-yank-sexp-symbol-or-char
C-+		isearchp-toggle-search-invisible
C-`		isearchp-toggle-regexp-quote-yank
C-S-SPC		isearchp-narrow-to-lazy-highlights
<C-M-return>	isearchp-act-on-demand
<C-M-tab>	isearchp-complete
<M-S-delete>	isearchp-cleanup
<backspace>	isearch-delete-char
<down-mouse-2>	ignore
<f1>		Prefix Command
<help>		Prefix Command
<mouse-2>	isearch-mouse-2
<next>		isearch-repeat-forward
<prior>		isearch-repeat-backward
<remap>		Prefix Command
<return>	isearch-exit
<switch-frame>	ignore

C-x 8		Prefix Command
C-x n		isearchp-toggle-region-restriction
C-x o		isearchp-open-recursive-edit
C-x r		Prefix Command

C-y C-c		isearchp-yank-char
C-y C-e		isearchp-yank-line
C-y C-w		isearchp-yank-word-or-char
C-y C-y		isearch-yank-kill
C-y ESC		Prefix Command
C-y C-_		isearchp-yank-symbol-or-char
C-y C-(		isearchp-yank-sexp-symbol-or-char

C-M-i		isearch-complete
C-M-l		isearchp-remove-failed-part
C-M-r		isearch-repeat-backward
C-M-s		isearch-repeat-forward
C-M-t		isearchp-property-forward-regexp
C-M-w		isearch-del-char
C-M-y		isearch-yank-char
ESC ESC		Prefix Command
M-%		isearch-query-replace
M-:		isearchp-eval-sexp-and-insert
M-;		isearchp-toggle-hiding-comments
M-c		isearch-toggle-case-fold
M-e		isearch-edit-string
M-g		isearchp-retrieve-last-quit-search
M-k		isearchp-cycle-mismatch-removal
M-n		isearch-ring-advance
M-p		isearch-ring-retreat
M-r		isearch-toggle-regexp
M-s		Prefix Command
M-w		isearchp-kill-ring-save
M-y		isearch-yank-pop
C-M-S-d		isearchp-toggle-dimming-outside-search-area
C-M-%		isearch-query-replace-regexp
C-M-;		isearchp-toggle-ignoring-comments
C-M-`		isearchp-toggle-literal-replacement
C-M-~		isearchp-toggle-complementing-domain

M-ESC ESC	isearch-cancel

M-s C-e		isearch-yank-line
M-s SPC		isearch-toggle-lax-whitespace
M-s _		isearch-toggle-symbol
M-s c		isearch-toggle-case-fold
M-s e		isearch-edit-string
M-s h		Prefix Command
M-s i		isearch-toggle-invisible
M-s o		isearch-occur
M-s r		isearch-toggle-regexp
M-s v		isearchp-toggle-option-toggle
M-s w		isearch-toggle-word

<remap> <isearch-complete>	isearchp-complete

<f1> C-h	isearch-help-for-help
<f1> ?		isearch-help-for-help
<f1> b		isearch-describe-bindings
<f1> k		isearch-describe-key
<f1> m		isearch-describe-mode
<f1> q		help-quit
<f1> <f1>	isearch-help-for-help
<f1> <help>	isearch-help-for-help

<help> C-h	isearch-help-for-help
<help> ?	isearch-help-for-help
<help> b	isearch-describe-bindings
<help> k	isearch-describe-key
<help> m	isearch-describe-mode
<help> q	help-quit
<help> <f1>	isearch-help-for-help
<help> <help>	isearch-help-for-help

C-x r g		isearchp-append-register

C-x 8 RET	isearch-char-by-name

C-y M-g		isearchp-retrieve-last-quit-search
C-y M-y		isearch-yank-pop

M-s h l		isearchp-toggle-lazy-highlight-cleanup
M-s h r		isearch-highlight-regexp