Exposing Isearch toggleable options

Exposing Isearch toggleable options

[Artur Malabarba]

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

I just pushed a branch called scratch/isearch-show-toggles, which
implements a way of exposing some of isearch options to the user.

Basically, as soon as isearch starts, you should see something like this.

Toggles [M-s]:  [w] Word OFF  [_] Symbol OFF  ['] Character-Fold ON   [r]
Regexp OFF
I-search: search string here

If your window is wide enough, you'll also see toggles for Lax-Whitespace,
Case-Fold, and Invisibe (it auto-ajusts the number of toggles displayed so
as to not take more than one line).

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

Here's the (two-commit) patch for those who prefer:

From 1ddd546be001116024dbbb0afe74d137ff8c679f Mon Sep 17 00:00:00 2001
From: Artur Malabarba <bruce.connor.am@gmail.com>
Date: Thu, 29 Oct 2015 00:28:14 +0000
Subject: [PATCH 1/2] * lisp/isearch.el (isearch-define-mode-toggle): Add
 keyword args

(isearch--toggles): New variable.
---
 lisp/isearch.el | 46 ++++++++++++++++++++++++++++++----------------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/lisp/isearch.el b/lisp/isearch.el
index e9eec01..6ec5c7f 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -1488,20 +1488,31 @@ isearch-repeat-backward


 ;;; Toggles for `isearch-regexp-function' and `search-default-regexp-mode'.
-(defmacro isearch-define-mode-toggle (mode key function &optional
docstring &rest body)
+(defvar isearch--toggles nil
+  "List of toggles defined with `isearch-define-mode-toggle'.
+Each element is a list of (NAME KEY PRED-FORM).")
+
+(cl-defmacro isearch-define-mode-toggle (mode key &rest body &key function
+                                              doc pred-form
&allow-other-keys)
   "Define a command called `isearch-toggle-MODE' and bind it to `M-s KEY'.
 The first line of the docstring is auto-generated, the remainder
-may be provided in DOCSTRING.
+may be provided in DOC.
 If FUNCTION is a symbol, this command first toggles the value of
 `isearch-regexp-function' between nil and FUNCTION.  Also set the
 `isearch-message-prefix' property of FUNCTION.
-The command then executes BODY and updates the isearch prompt."
+The command then executes BODY and updates the isearch prompt.
+
+PRED-FORM, when evaluated should return non-nil if the mode is
+active.  It is mandatory only if FUNCTION is not provided."
   (declare (indent defun))
-  (let ((command-name (intern (format "isearch-toggle-%s" mode))))
+  (let ((command-name (intern (format "isearch-toggle-%s" mode)))
+        (pred-form (or pred-form `(eq isearch-regexp-function
#',function))))
+    (while (keywordp (car body))
+      (setq body (cdr (cdr body))))
     `(progn
        (defun ,command-name ()
          ,(format "Toggle %s searching on or off.%s" mode
-                  (if docstring (concat "\n" docstring) ""))
+                  (if doc (concat "\n" doc) ""))
          (interactive)
          ,@(when function
              `((setq isearch-regexp-function
@@ -1512,6 +1523,7 @@ isearch-define-mode-toggle
          (setq isearch-success t isearch-adjusted t)
          (isearch-update))
        (define-key isearch-mode-map ,(concat "\M-s" key) #',command-name)
+       (setf (alist-get ',mode isearch--toggles) '(,key (lambda ()
,pred-form)))
        ,@(when (symbolp function)
            `((put ',function 'isearch-message-prefix ,(format "%s " mode))
              (cl-callf (lambda (types) (cons 'choice
@@ -1519,12 +1531,12 @@ isearch-define-mode-toggle
                                               (cdr types))))
                  (get 'search-default-regexp-mode 'custom-type)))))))

-(isearch-define-mode-toggle word "w" word-search-regexp)
-(isearch-define-mode-toggle symbol "_" isearch-symbol-regexp)
-(isearch-define-mode-toggle character-fold "'" character-fold-to-regexp)
+(isearch-define-mode-toggle word "w"           :function
word-search-regexp)
+(isearch-define-mode-toggle symbol "_"         :function
isearch-symbol-regexp)
+(isearch-define-mode-toggle character-fold "'" :function
character-fold-to-regexp)
 (put 'character-fold-to-regexp 'isearch-message-prefix "char-fold ")

-(isearch-define-mode-toggle regexp "r" nil nil
+(isearch-define-mode-toggle regexp "r" :pred-form isearch-regexp
   (setq isearch-regexp (not isearch-regexp))
   (if isearch-regexp (setq isearch-regexp-function nil)))

@@ -1537,8 +1549,9 @@ isearch--momentary-message
              string))
   (sit-for 1))

-(isearch-define-mode-toggle lax-whitespace " " nil
-  "In ordinary search, toggles the value of the variable
+(isearch-define-mode-toggle lax-whitespace " "
+  :pred-form (if isearch-regexp isearch-regexp-lax-whitespace
isearch-lax-whitespace)
+  :doc "In ordinary search, toggles the value of the variable
 `isearch-lax-whitespace'.  In regexp search, toggles the
 value of the variable `isearch-regexp-lax-whitespace'."
   (isearch--momentary-message
@@ -1548,20 +1561,21 @@ isearch--momentary-message
        "match spaces loosely"
      "match spaces literally")))

-(isearch-define-mode-toggle case-fold "c" nil
-  "Toggles the value of the variable `isearch-case-fold-search'."
+(isearch-define-mode-toggle case-fold "c"
+  :pred-form isearch-case-fold-search
+  :doc "Toggles the value of the variable `isearch-case-fold-search'."
   (isearch--momentary-message
    (if (setq isearch-case-fold-search
              (if isearch-case-fold-search nil 'yes))
        "case insensitive"
      "case sensitive")))

-(isearch-define-mode-toggle invisible "i" nil
-  "This determines whether to search inside invisible text or not.
+(isearch-define-mode-toggle invisible "i"
+  :pred-form isearch-invisible
+  :doc "This determines whether to search inside invisible text or not.
 Toggles the variable `isearch-invisible' between values
 nil and a non-nil value of the option `search-invisible'
 \(or `open' if `search-invisible' is nil)."
-  "match %svisible text"
   (isearch--momentary-message
    (if (setq isearch-invisible
              (if isearch-invisible
-- 
2.5.3


From 37d169df4433be1869eac9c916e548b9bd66ff04 Mon Sep 17 00:00:00 2001
From: Artur Malabarba <bruce.connor.am@gmail.com>
Date: Thu, 29 Oct 2015 00:51:21 +0000
Subject: [PATCH 2/2] * lisp/isearch.el: Display toggles and their keys

(isearch--describe-toggles): New function.
(isearch-show-toggles): New user option.
(isearch-message-prefix): Use them.
---
 lisp/isearch.el | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 6ec5c7f..6327068 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -1583,6 +1583,30 @@ isearch--momentary-message
        "match invisible text"
      "match visible text")))

+(defcustom isearch-show-toggles t
+  "Non-nil means to list options above input prompt."
+  :type 'boolean
+  :version "25.1")
+
+(defun isearch--describe-toggles ()
+  "Return a propertized description of isearch toggles."
+  (let ((toggles
+         (concat
+          #("Toggles [M-s]:  " 0 9 (face minibuffer-prompt) 12 16 (face
minibuffer-prompt))
+          (mapconcat (lambda (x) (format (propertize "[%s] %s %s" 'face
'minibuffer-prompt)
+                                    (propertize (elt x 1) 'face 'default)
+                                    (capitalize (symbol-name (car x)))
+                                    (if (funcall (elt x 2))
+                                        (propertize "ON " 'face 'default)
"OFF")))
+                     (reverse isearch--toggles)
+                     "  ")
+          "\n"))
+        (width (window-width (minibuffer-window))))
+    (if (> width (string-width toggles))
+        toggles
+      (replace-regexp-in-string "\\[[^[]*\\'" "\n"
+                                (substring toggles 0 width)))))
+

 ;; Word search

@@ -2592,8 +2616,9 @@ isearch-message-prefix
             (concat " [" current-input-method-title "]: "))
              ": ")
            )))
-    (propertize (concat (upcase (substring m 0 1)) (substring m 1))
-        'face 'minibuffer-prompt)))
+    (concat (when isearch-show-toggles (isearch--describe-toggles))
+            (propertize (concat (upcase (substring m 0 1)) (substring m 1))
+                        'face 'minibuffer-prompt))))

 (defun isearch-message-suffix (&optional c-q-hack)
   (concat (if c-q-hack "^Q" "")
-- 
2.5.3

[-- Attachment #2: Type: text/html, Size: 10635 bytes --]

Re: Exposing Isearch toggleable options

[Juri Linkov]

> I just pushed a branch called scratch/isearch-show-toggles, which
> implements a way of exposing some of isearch options to the user.
>
> Basically, as soon as isearch starts, you should see something like this.
>
> Toggles [M-s]:  [w] Word OFF  [_] Symbol OFF  ['] Character-Fold ON   [r]
> Regexp OFF
> I-search: search string here
>
> If your window is wide enough, you'll also see toggles for Lax-Whitespace,
> Case-Fold, and Invisibe (it auto-ajusts the number of toggles displayed so
> as to not take more than one line).
>
> I'm not yet sure if this is worth merging to master, so I'd very much
> appreciate opinions.

What key is used to toggle toggles?

Re: Exposing Isearch toggleable options

[Artur Malabarba]

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

On 29 Oct 2015 12:27 am, "Juri Linkov" <juri@linkov.net> wrote:
> What key is used to toggle toggles?

M-s  plus some other key. They're each listed in the prompt.

[-- Attachment #2: Type: text/html, Size: 272 bytes --]

Re: Exposing Isearch toggleable options

[Juri Linkov]

>> What key is used to toggle toggles?
>
> M-s  plus some other key. They're each listed in the prompt.

But what key could be used to toggle the display of that additional line
containing a list of toggles?  If such a key will be intuitive enough it
would be easy to type to reveal this helpful line even when disabled by default.

Re: Exposing Isearch toggleable options

[Random832]

Juri Linkov <juri@linkov.net> writes:
>>> What key is used to toggle toggles?
>>
>> M-s  plus some other key. They're each listed in the prompt.
>
> But what key could be used to toggle the display of that additional line
> containing a list of toggles?

Well, how about M-s? A general way to supply a "prompt" string to be
printed in the echo area after typing a prefix key (either immediately
or when the echo-keystrokes delay triggers) might be nice.

Re: Exposing Isearch toggleable options

[Oleh Krehel]

Random832 <random832@fastmail.com> writes:

> Juri Linkov <juri@linkov.net> writes:
>>>> What key is used to toggle toggles?
>>>
>>> M-s  plus some other key. They're each listed in the prompt.
>>
>> But what key could be used to toggle the display of that additional line
>> containing a list of toggles?
>
> Well, how about M-s? A general way to supply a "prompt" string to be
> printed in the echo area after typing a prefix key (either immediately
> or when the echo-keystrokes delay triggers) might be nice.

I could very well be "M-s". And what you described above is exactly what
`defhydra` does: both bind the functions and wrap helpers around
them. It's like `define-key', but with the automatic doc popup right
after you press the prefix.

Currently, we have "M-s" do a dumb prompt for more keys, with the only
help available on "M-s C-h", which incidentally quits the minibuffer, so
you have to start over. The `defhydra` approach embeds "C-h" right into
"M-s", without quitting the minibuffer, and automatically closes the
hint once an option is chosen.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-29 23:58 GMT+00:00 Juri Linkov <juri@linkov.net>:
>>> What key is used to toggle toggles?
>>
>> M-s  plus some other key. They're each listed in the prompt.
>
> But what key could be used to toggle the display of that additional line
> containing a list of toggles?  If such a key will be intuitive enough it
> would be easy to type to reveal this helpful line even when disabled by default.

Oh, I see what you meant now. There's no key for that yet, though we
could certainly add one. However, I'm leaning more towards other
suggested solutions anyway.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-30 9:56 GMT+00:00 Artur Malabarba <bruce.connor.am@gmail.com>:
> I'm leaning more towards other suggested solutions anyway.

Ok. Thanks everyone for the feedback. I've see 3 good suggestions here
on this thread, all of which I like better than my current solution.
What I list below are actually slightly modified versions in order to
help expose this stuff.

I'm ditching the two-line minibuffer I originally suggested. All of
the options below keep the minibuffer as a single line.
Listed in my order of preference.

1. On the right-edge of the minibuffer (if there's enough space),
display “[C-h m] Mode help” (or, if we're fine with rebinding C-h here
we can use just “[C-h] Help”). Hitting this key would the bring up
`isearch-mode-help`.
   This is probably the most consistent option, as plenty of other
Emacs features offer a similar (C-h help) indicator.
   If we go with this, I'll probably suggest some improvements to
`isearch-mode-help`.

2. On the right-edge of the minibuffer (if there's enough space),
display “[M-s] Options”. Hitting this key would then bring up a hydra
with all defined options under M-s (preferably something dynamically
generated, and not hardcoded, though this is just a detail).
   This would be the prettiest option. Hydras also support delaying
the display for a second or so, so people who know what they want
wouldn't have to see it.

3. Display an information similar to the prompt I originally
suggested, but on the mode-line.

In items 1 and 2, we could display the indicators on an idle timer if preferred.
Here's what the minibuffer might look like in that situation:

Isearch: search string                            [C-h] Help

Re: Exposing Isearch toggleable options

[Marcin Borkowski]

On 2015-10-30, at 11:42, Artur Malabarba <bruce.connor.am@gmail.com> wrote:

> 2. On the right-edge of the minibuffer (if there's enough space),
> display “[M-s] Options”. Hitting this key would then bring up a hydra

Just curious: is hydra going to be bundled with Emacs?

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Exposing Isearch toggleable options

[Artur Malabarba]

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

On 30 Oct 2015 11:03 am, "Marcin Borkowski" <mbork@mbork.pl> wrote:
>
>
> On 2015-10-30, at 11:42, Artur Malabarba <bruce.connor.am@gmail.com>
wrote:
>
> > 2. On the right-edge of the minibuffer (if there's enough space),
> > display “[M-s] Options”. Hitting this key would then bring up a hydra
>
> Just curious: is hydra going to be bundled with Emacs?

In order to use this option, it would have to be.
But I'm fine with that, as I think emacs would benefit from using more
hydras in general.

[-- Attachment #2: Type: text/html, Size: 724 bytes --]

Re: Exposing Isearch toggleable options

[Marcin Borkowski]

On 2015-10-30, at 12:56, Artur Malabarba <bruce.connor.am@gmail.com> wrote:

> On 30 Oct 2015 11:03 am, "Marcin Borkowski" <mbork@mbork.pl> wrote:
>>
>>
>> On 2015-10-30, at 11:42, Artur Malabarba <bruce.connor.am@gmail.com>
> wrote:
>>
>> > 2. On the right-edge of the minibuffer (if there's enough space),
>> > display “[M-s] Options”. Hitting this key would then bring up a hydra
>>
>> Just curious: is hydra going to be bundled with Emacs?
>
> In order to use this option, it would have to be.
> But I'm fine with that, as I think emacs would benefit from using more
> hydras in general.

I agree - while I do not use hydra (yet), including it in Emacs seems
a very good idea.  Not only because it is good, but also because it is
(I think at least) unique.  AFAIR, it's called "USP"
(https://en.wikipedia.org/wiki/Unique_selling_proposition).

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Exposing Isearch toggleable options

[Kaushal Modi]

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

The hydra option looks good. A user can even customize that hydra if they
want to. But as Marcin said, do we then need to bundle hydra with emacs.

In addition to that option, it would be nice to always show the toggle
starts in the mode-line. The hydra can also show the current states of all
the toggles. But it would be useful to show "a representation of the toggle
states" in the mode-line so that the user does not need to launch the hydra
just to see the states.

By "representation", I recall what Drew had mentioned in one of the earlier
threads discussing this:

If modeline shows: "AbCd", the search will be case sensitive, without char
folding.

If modeline shows: "abcd", the search will be case insensitive, without
char folding.

If modeline shows: "âbcd", the search will be case insensitive, with char
folding.

And so on...

But then "abcd" example might not fit the bill for all toggles.

Instead, should we have 2-letter acronyms for all toggles in the modeline
and change their face based on the toggle state?

Let's say, these are the acronyms:

Cs - Case sensitive
RE - Regular expressions
ČF - Char folding
LW - Lax Whitespace
... And so on.

This list of 2-char acronyms can again be made user customizable. But the
association of acronyms to the toggle var should be kept fixed to prevent
confusion and unneeded complication.

Those acronyms will be displayed with sort of a dimmed out, gray face when
the respective toggle is disabled. But the face will be changed to
something like bold green when enabled. It goes without saying that the
faces would be customizable.

What do you guys think?

[-- Attachment #2: Type: text/html, Size: 1970 bytes --]

Re: Exposing Isearch toggleable options

[Oleh Krehel]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Let's say, these are the acronyms: 
>
> Cs - Case sensitive 
> RE - Regular expressions 
> ČF - Char folding 
> LW - Lax Whitespace 
> ... And so on. 
>
> This list of 2-char acronyms can again be made user customizable. But the association of acronyms to the toggle var
> should be kept fixed to prevent confusion and unneeded complication. 
>
> Those acronyms will be displayed with sort of a dimmed out, gray face when the respective toggle is disabled. But the
> face will be changed to something like bold green when enabled. It goes without saying that the faces would be
> customizable. 
>
> What do you guys think?

I can only say that I couldn't manage to remember what each of "U:---"
does in 5 years of using Emacs. It's possible to check what they do only
by hovering the mouse or reading the manual.  Then I switched to
powerline, which only uses one position of the 5:

    - for a normal buffer
    * for a modified buffer
    % for a read-only buffer

Of course, it's just one personal preference. Some people instead like
to have a lot of info in the mode line, they even put the clock and CPU
load there.

I think having the illusion of simplicity is important: select the
simplest looking thing and go with it, and allow the user to make it
complex if she wants. That's the way a lot of the successful editors
work (except the option to make it complex, which is an advantage of
Emacs).

On the other hand, most users learn basic Elisp because they want to
hide the unnecessary tool bars, menu bars, and scroll bars, startup
messages etc, all of which are on by default.

Re: Exposing Isearch toggleable options

[Random832]

Kaushal Modi <kaushal.modi@gmail.com> writes:
> In addition to that option, it would be nice to always show the toggle
> starts in the mode-line. The hydra can also show the current states of
> all the toggles. But it would be useful to show "a representation of
> the toggle states" in the mode-line so that the user does not need to
> launch the hydra just to see the states. 

Why not show it in the prompt? Regexp, word, symbol, are already shown
in the prompt.

Re: Exposing Isearch toggleable options

[Kaushal Modi]

> Why not show it in the prompt? Regexp, word, symbol, are already shown
> in the prompt.

The idea was to reduce clutter in the prompt where user is typing the
search strings. The modeline instead can be used to show the toggle
states momentarily only while the isearch is in progress.

Re: Exposing Isearch toggleable options

[Oleh Krehel]

Artur Malabarba <bruce.connor.am@gmail.com> writes:

> 2. On the right-edge of the minibuffer (if there's enough space),
> display “[M-s] Options”. Hitting this key would then bring up a hydra
> with all defined options under M-s (preferably something dynamically
> generated, and not hardcoded, though this is just a detail).
>    This would be the prettiest option. Hydras also support delaying
> the display for a second or so, so people who know what they want
> wouldn't have to see it.

It just occurred to me that Ediff does it in the exact same way as the
Hydra approach.

Initially, it only says "Type ? for help". The "?" key is a toggle, just
like "C-o" is in my previous proposition.  Pressing the actual keys that
are described in the doc popup doesn't close the doc popup, which could
be replicated with `:exit nil'.

And the docstring of Ediff is actually customizable through
e.g. `ediff-long-help-message-word-mode', although it's not
automatically synced with the keymap, like Hydra does it.

I suggest that you look at the Ediff interface if you're not yet
familiar with it. Just don't forget to:

(setq ediff-window-setup-function 'ediff-setup-windows-plain)

or you'll get the horrible multi-frame default setting.

Re: Exposing Isearch toggleable options

[Juri Linkov]

>> I'm leaning more towards other suggested solutions anyway.
>
> Ok. Thanks everyone for the feedback. I've see 3 good suggestions here
> on this thread, all of which I like better than my current solution.
> What I list below are actually slightly modified versions in order to
> help expose this stuff.
>
> I'm ditching the two-line minibuffer I originally suggested. All of
> the options below keep the minibuffer as a single line.
> Listed in my order of preference.
>
> 1. On the right-edge of the minibuffer (if there's enough space),
> display “[C-h m] Mode help” (or, if we're fine with rebinding C-h here
> we can use just “[C-h] Help”). Hitting this key would the bring up
> `isearch-mode-help`.
>    This is probably the most consistent option, as plenty of other
> Emacs features offer a similar (C-h help) indicator.
>    If we go with this, I'll probably suggest some improvements to
> `isearch-mode-help`.

Instead of the Help buffer we could open a Customizable-like buffer
with widget-type fields, thus in addition to *showing* the current
search options and info about keys to change them, also allow
*changing* the current search options.

> 2. On the right-edge of the minibuffer (if there's enough space),
> display “[M-s] Options”. Hitting this key would then bring up a hydra
> with all defined options under M-s (preferably something dynamically
> generated, and not hardcoded, though this is just a detail).
>    This would be the prettiest option. Hydras also support delaying
> the display for a second or so, so people who know what they want
> wouldn't have to see it.

This will violate the layered architecture where specific packages
(that are sometimes fancy in the sense of not using traditional UI)
are built on top of the core packages like isearch.el (that of course
doesn't preclude from writing a isearch-hydra.el or hydra-isearch.el
combinations).

> 3. Display an information similar to the prompt I originally
> suggested, but on the mode-line.

We already have a precedent in C mode with mode-line like
“C/lah ,” (note the space character inside, indicating Word mode).
In Isearch doing the same will show something like “Isearch/c' w”
(case-sensitive char-folded lax-whitespace word search).

> In items 1 and 2, we could display the indicators on an idle timer if preferred.
> Here's what the minibuffer might look like in that situation:
>
> Isearch: search string                            [C-h] Help

I doubt that users might want to see the same reminder “[C-h] Help”
permanently or when paused to look at the highlighted search results.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-31 0:27 GMT+00:00 Juri Linkov <juri@linkov.net>:
>> 1. [...]
>
> Instead of the Help buffer we could open a Customizable-like buffer
> with widget-type fields, thus in addition to *showing* the current
> search options and info about keys to change them, also allow
> *changing* the current search options.

Sounds like a good addition.

>> 3. Display an information similar to the prompt I originally
>> suggested, but on the mode-line.
>
> We already have a precedent in C mode with mode-line like
> “C/lah ,” (note the space character inside, indicating Word mode).
> In Isearch doing the same will show something like “Isearch/c' w”
> (case-sensitive char-folded lax-whitespace word search).

While that's a fine addition to the current situation. I'm
specifically trying to expose the keys you use to change isearch
options. I suppose we could display those in a help-echo hint on those
mode-line abbreviations, but I prefer to make it very clear to the
user that they can type a key to see options.

>> In items 1 and 2, we could display the indicators on an idle timer if preferred.
>> Here's what the minibuffer might look like in that situation:
>>
>> Isearch: search string                            [C-h] Help
>
> I doubt that users might want to see the same reminder “[C-h] Help”
> permanently or when paused to look at the highlighted search results.

You see that `Isearch: ' prompt every time you hit C-s, and that's
right beside the text you're typing. This Help reminder would be off
to the right edge (so it's far from the text you're typing). Besides,
if you just type C-h once, you'll see a buffer explaining (among other
things) how to disable this reminder.

RE: Exposing Isearch toggleable options

[Drew Adams]

> > Instead of the Help buffer we could open a Customizable-like buffer
> > with widget-type fields, thus in addition to *showing* the current
> > search options and info about keys to change them, also allow
> > *changing* the current search options.
> 
> Sounds like a good addition.

Not to me, it doesn't.  A widget-filled buffer is a step
backward in this context, IMO.

Isearch options/state should be togglable on the fly, using
Isearch keys.  *Help* can and should describe the options, and
it can remind users about customizing them.

The latter is not strictly needed as an extra reminder, because
simply mentioning each option in *Help* provides a link to its
detailed help, which in turn includes a link to customize it.

The tiny grain of sense in that suggestion is that Isearch can
indicate, on an ongoing basis (not just on demand, in a separate
*Help* or "Customizable-like" buffer), the current search state,
including the states of individual Isearch options.

1. Indicating the current state is one thing, and important.
2. Keys to change the current state are another thing.
3. Help reminding you about those keys is a third thing.

#1 should be indicated continually (e.g., in the mode-line),
at least for the most important aspects of the state.

#2 (the keys) should be available at all times and easily
discoverable.

But #3, reminders about Isearch keys, do not need to be
visible continually, and should not claim screen real
estate that way. #3 should be available on demand -
preferably by simply hitting the help key, `C-h'.  (If
necessary, the single key `C-h' could be mentioned in the
mode-line.)

A *Help* buffer is the logical choice for #3.  It should be
what users already expect or come to expect as the first
detailed help about something.  Widgety Customize-like
buffers should not become the new normal for that first-stop
help role.

Emacs should continue to teach users to ask for, get, and use
*Help*-style help.  It automatically provides links to more
detailed help about Isearch options, keys, etc., and to
customization of options.  There is no need to throw another
style of first-stop help in their face, for Isearch. 

A user can always keep the *Help* buffer displayed, if s?he
likes (separate window or frame).  On-demand (not immediately
and constantly in-your-face).  But keep it around as long as
you want.

And a user can easily rename the *Help* buffer, so that it
does not interfere with other *Help* displays.

[I bind a key to `rename-buffer'.  And my advised version of
`rename-buffer' provides (lax) completion for the buffer name.
I think it would be good for vanilla Emacs to do likewise (and
to mention the key concisely in *Help* or its mode-line).]

> >> 3. Display an information similar to the prompt I originally
> >> suggested, but on the mode-line.
> >
> > We already have a precedent in C mode with mode-line like
> > “C/lah ,” (note the space character inside, indicating Word mode).
> > In Isearch doing the same will show something like “Isearch/c' w”
> > (case-sensitive char-folded lax-whitespace word search).
> 
> While that's a fine addition to the current situation. I'm
> specifically trying to expose the keys you use to change isearch
> options. I suppose we could display those in a help-echo hint on those
> mode-line abbreviations, but I prefer to make it very clear to the
> user that they can type a key to see options.

See above.  The mode-line is precious, and it has limited
space.  Isearch *in particular* should use it to show the
current state, not to remind users of Isearch keys.
Isearch is becoming richer all the time, with more and more
keys that perform actions.  The mode-line is a poor design
choice for reminders about Isearch keys.

And again, prominent reminders of Isearch keys should not
privilege the keys to change option values.  Just because
we (Artur/Bruce - which do you prefer, BTW?) recently added
another (very welcome) toggle, char folding, that is not a
reason that option toggling should suddenly be considered
the only, or even the most, important kind of Isearch
action to remind users about.

> >> In items 1 and 2, we could display the indicators on an idle
> >> timer if preferred.
> >> Here's what the minibuffer might look like in that situation:
> >> Isearch: search string                            [C-h] Help
> >
> > I doubt that users might want to see the same reminder “[C-h] Help”
> > permanently or when paused to look at the highlighted search results.
> 
> You see that `Isearch: ' prompt every time you hit C-s, and that's
> right beside the text you're typing. This Help reminder would be off
> to the right edge (so it's far from the text you're typing). Besides,
> if you just type C-h once, you'll see a buffer explaining (among other
> things) how to disable this reminder.

I agree that putting such a reminder in the echo area
would not be a step forward.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-11-01 16:01 GMT+00:00 Drew Adams <drew.adams@oracle.com>:
>> > Instead of the Help buffer we could open a Customizable-like buffer
>> > with widget-type fields, thus in addition to *showing* the current
>> > search options and info about keys to change them, also allow
>> > *changing* the current search options.
>>
>> Sounds like a good addition.
>
> Not to me, it doesn't.  A widget-filled buffer is a step
> backward in this context, IMO.

I should have explained more. I don't mean it would be good to merge
isearch's customization group with the help buffer.
I just meant we could add a few checkboxes to that buffer. For
instance, currently the help for isearch has a paragraph like this:

Type M-s c to toggle search case-sensitivity.
Type M-s i to toggle search in invisible text.
Type M-s r to toggle regular-expression mode.
Type M-s w to toggle word mode.
Type M-s _ to toggle symbol mode.
Type M-s ' to toggle character folding.

Adding a single checkbox to the end (or start) of each line would be
nice (and it isn't what I'd call a "widget-filled" buffer).
Or we could replace that paragraph with something like this (where []
denotes a checkbox)

   Search options        | Toggle key
---------------------------------------------------
[] case-sensitive        | M-s c
[] inside invisible text | M-s i
[] regular-expression    | M-s r
[] word mode             | M-s w
[] symbol mode           | M-s _
[] character folding     | M-s '

(let's not nitpick on the format here, I'm just suggesting how the
options could be made toggleable)

> See above.  The mode-line is precious,[...] The mode-line is a poor design
> choice for reminders about Isearch keys.

Which is why number 3 is my least preferred option. :-)

> And again, prominent reminders of Isearch keys should not
> privilege the keys to change option values. [...]
> option toggling should [not] suddenly be considered
> the only, or even the most, important kind of Isearch
> action to remind users about.

Which is why option 1) was my first preference. The isearch help
buffer exposes all keys, not just those toggles (and we can reorder it
how we see fit).

> (Artur/Bruce - which do you prefer, BTW?)

Artur. Chaging this email address has been on my todo list. :-P

> I agree that putting such a reminder in the echo area
> would not be a step forward.

Noted.

RE: Exposing Isearch toggleable options

[Drew Adams]

> I should have explained more. I don't mean it would be good to merge
> isearch's customization group with the help buffer.
> I just meant we could add a few checkboxes to that buffer. For
> instance, currently the help for isearch has a paragraph like this:
> 
> Type M-s c to toggle search case-sensitivity.
> Type M-s i to toggle search in invisible text.
> Type M-s r to toggle regular-expression mode.
> Type M-s w to toggle word mode.
> Type M-s _ to toggle symbol mode.
> Type M-s ' to toggle character folding.
> 
> Adding a single checkbox to the end (or start) of each line would be
> nice (and it isn't what I'd call a "widget-filled" buffer).
> Or we could replace that paragraph with something like this (where []
> denotes a checkbox)
> 
>    Search options        | Toggle key
> ---------------------------------------------------
> [] case-sensitive        | M-s c
> [] inside invisible text | M-s i
> [] regular-expression    | M-s r
> [] word mode             | M-s w
> [] symbol mode           | M-s _
> [] character folding     | M-s '
> 
> (let's not nitpick on the format here, I'm just suggesting how the
> options could be made toggleable)

I still disagree, but I've already said most of what I
think about this.

I prefer to see *Help* provide help as information, and
not try to get into the business of becoming a clickable
dialog box that effects actions.

*Help* can tell users about keys for toggling options;
provide links to customize things; and inform users about
menus that, among other things, can provide toggle items
(with check boxes).

I'd sooner see usera use the same ways to toggle Isearch
states: keys, Customize, and (why not?) an Isearch menu-bar
menu.

Just as we have a temporary Minibuf menu for the minibuffer,
so we can have an Isearch menu, with as many actions on it
as you like, and grouped into submenus if that makes sense.
New users are used to menus, and menus can be quite helpful
for discovery (one of the topics skirted in this thread).

Some Emacs users are used to Customize as well.  (And yes,
we _should_ guide users to Customize, more generally, IMO.)

And all Emacs users will expect *Help* to (1) provide info
about commands, keys, and features; to (2) guide them to
more, linked help; and to (3) guide them to the manual.

That's not to say that Emacs can never change to add
checkboxes or whatever here or there.  But I would prefer
that we start by sticking with, and leveraging, the usual
Emacs ways of offering such things: (a) keys, menus, and
Customize, to act, and (b) help and manuals to inform.

The mode-line is a limited space where, like menus, we
have sometimes combined information with ways to act.
In menus, actions predominate; in the mode-line, info
predominates.  But *Help* has so far pretty much been
limited, in terms of actions, to following links.

I suggest we start by (1) doing _without_ sticking
checkboxes into *Help*, and (2) adding a useful Isearch
menu (which includes option toggles as some of its items).

Just one opinion.

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> I still disagree, but I've already said most of what I think about this.

> I prefer to see *Help* provide help as information, and not try to get into
> the business of becoming a clickable dialog box that effects actions.

Artur,

Would you be willing to write up a final version of your I-search proposal as
a separate document, so we can all review it? I feel the important points are
getting lost in the weeds with this thread, as I no longer have a coherent
picture of your proposed changes.

I've created a page at http://www.emacswiki.org specifically for gathering
such proposals, so we can review and revise them:

    http://www.emacswiki.org/emacs/Proposals

If you could add a link on that page to your proposed change, it would help
focus our discussion.

Feel free to continue debating technical points here, I'd just like there to
be a "current state of the proposal" that I could look at on any given day, as
these discussion evolve.

Thank you,
  John

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-11-02 20:19 GMT+00:00 John Wiegley <johnw@newartisans.com>:
>>>>>> Drew Adams <drew.adams@oracle.com> writes:
>
>> I still disagree, but I've already said most of what I think about this.
>
>> I prefer to see *Help* provide help as information, and not try to get into
>> the business of becoming a clickable dialog box that effects actions.
>
> Artur,
>
> Would you be willing to write up a final version of your I-search proposal as
> a separate document, so we can all review it? I feel the important points are
> getting lost in the weeds with this thread, as I no longer have a coherent
> picture of your proposed changes.
>
> I've created a page at http://www.emacswiki.org specifically for gathering
> such proposals, so we can review and revise them:
>
>     http://www.emacswiki.org/emacs/Proposals
>
> If you could add a link on that page to your proposed change, it would help
> focus our discussion.

Here we go:
http://www.emacswiki.org/emacs/Isearch-prompt-proposal

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:

> Here we go:
> http://www.emacswiki.org/emacs/Isearch-prompt-proposal

Thank you, Artur! Once my current work trip in Boston is over, I'll post some
comments.

John

Re: Exposing Isearch toggleable options

[Juri Linkov]

>> I've created a page at http://www.emacswiki.org specifically for gathering
>> such proposals, so we can review and revise them:
>>
>>     http://www.emacswiki.org/emacs/Proposals
>>
>> If you could add a link on that page to your proposed change, it would help
>> focus our discussion.
>
> Here we go:
> http://www.emacswiki.org/emacs/Isearch-prompt-proposal

After learning about [F1 m] it might become too distracting to see
it permanently.  Of course, like ‘inhibit-startup-screen’ we could create
a customization ‘inhibit-isearch-message-help’, but everyone has
to make an effort to disable it, that's not too nice.

A better option is to allow customization of the whole isearch echo area
like ‘mode-line-format’ is used to customize the mode-line.  Then
‘isearch-message-format’ could support either full names of search options/states,
i.e. have a placeholder in the format string for every option in the message
(e.g. “%'%cI-search%b” for “Case-fold case-sensitive I-search backward”),
thus allowing to customize their order or to remove some of them.  Or customizing
to use abbreviations (e.g. “I-search/%w/%%_/%'” for “I-search/w/_/'”),
where clicking on one of them will toggle the corresponding search option.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-11-05 0:24 GMT+00:00 Juri Linkov <juri@linkov.net>:
>>> If you could add a link on that page to your proposed change, it would help
>>> focus our discussion.
>>
>> Here we go:
>> http://www.emacswiki.org/emacs/Isearch-prompt-proposal
>
> After learning about [F1 m] it might become too distracting to see
> it permanently.

I understand that people are worried about this, but:
1) The help buffer you get from typing `F1 m' will tell you how to
disable the reminder (there'll be a variable, of course).
2) I really don't think it'll be that distracting. On large screens
it'll be over 100 spaces to the right of the search string. On small
screens we can make it so that it doesn't appear at all (just to make
sure the prompt doesn't get crowded).

> Of course, like ‘inhibit-startup-screen’ we could create
> a customization ‘inhibit-isearch-message-help’,

Yes, something like this would surely exist.

> but everyone has to make an effort to disable it, that's not too nice.

Or just ignore it. :-)

> A better option is to allow customization of the whole isearch echo area
> like ‘mode-line-format’ is used to customize the mode-line.

This sounds like a fine suggestion, but completely orthogonal to the
current dicussion.

The question here is: would it be an overall improvement to add a
(disableable) small reminder to the right edge of the echo-area? i.e.,
would the benefit to people who've never seen the isearch help
outweigh the annoyance of those who'll want to disable it.

Re: Exposing Isearch toggleable options

[Dmitry Gutov]

On 11/05/2015 02:55 AM, Artur Malabarba wrote:

> The question here is: would it be an overall improvement to add a
> (disableable) small reminder to the right edge of the echo-area? i.e.,
> would the benefit to people who've never seen the isearch help
> outweigh the annoyance of those who'll want to disable it.

I vote yes.

Re: Exposing Isearch toggleable options

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I vote yes.

We're not looking for votes on this list.  We're going to poll the
users, asking them to provide more than votes.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Exposing Isearch toggleable options

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > 2) I really don't think it'll be that distracting. On large screens
  > it'll be over 100 spaces to the right of the search string.

Do people actually use Emacs with windows so wide?
My screen is wide, but having more than 80 columns in Emacs would
be a screw, so I tell Emacs that the screen is 80 columns wide.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Exposing Isearch toggleable options

[Alan Mackenzie]

Hello, Richard.

On Thu, Nov 05, 2015 at 05:44:53PM -0500, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]

>   > 2) I really don't think it'll be that distracting. On large screens
>   > it'll be over 100 spaces to the right of the search string.

> Do people actually use Emacs with windows so wide?
> My screen is wide, but having more than 80 columns in Emacs would
> be a screw, so I tell Emacs that the screen is 80 columns wide.

My screen is 240 characters wide.  It is great to be able to have two
related buffers in side by side windows.

And for long, tortuous functions, I use Follow Mode in three side by
side windows, these being 79, 79, 80 characters wide.  This allows me to
view 195 consecutive lines of a buffer at once.  This is on a Linux
virtual terminal, on a 1920 x 1080 pixel screen.

Sometimes, I wonder how I ever managed on my old restricted CRT monitor,
which I think went to ~120 characters wide.

> -- 
> Dr Richard Stallman
> President, Free Software Foundation (gnu.org, fsf.org)
> Internet Hall-of-Famer (internethalloffame.org)
> Skype: No way! See stallman.org/skype.html.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Exposing Isearch toggleable options

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > My screen is 240 characters wide.  It is great to be able to have two
  > related buffers in side by side windows.

Interesting.  It's true that most laptop screens are length wise and
width foolish.  But not this laptop's.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Richard Stallman <rms@gnu.org> writes:

> Do people actually use Emacs with windows so wide?
> My screen is wide, but having more than 80 columns in Emacs would
> be a screw, so I tell Emacs that the screen is 80 columns wide.

I think he means that the minibuffer would look like this:

    PROMPT INPUT                                                HELP

If INPUT gets long enough to reach HELP, I hope the input area would wrap as
it does now, leaving HELP fixed in place. This would be true no matter the
screen width.

In practice, INPUT should be short enough that adding 10 characters of HELP
would not impact anyone, not even at <80 columns wide.

John

Re: Exposing Isearch toggleable options

[Stephen Leake]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > 2) I really don't think it'll be that distracting. On large screens
>   > it'll be over 100 spaces to the right of the search string.
>
> Do people actually use Emacs with windows so wide?

I use 120 chars wide. That makes it more comfortable to use good (ie
longer) variable names; less line wrapping.

I have a 2560 x 1440 pixel display; allows for two 120 char Emacs frames
side by side, with some left over for Firefox etc.


-- 
-- Stephe

Re: Exposing Isearch toggleable options

[Gian Uberto Lauri]

Stephen Leake writes:
 > Richard Stallman <rms@gnu.org> writes:
 > 
 > > [[[ To any NSA and FBI agents reading my email: please consider    ]]]
 > > [[[ whether defending the US Constitution against all enemies,     ]]]
 > > [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
 > >
 > >   > 2) I really don't think it'll be that distracting. On large screens
 > >   > it'll be over 100 spaces to the right of the search string.
 > >
 > > Do people actually use Emacs with windows so wide?
 > 
 > I use 120 chars wide. That makes it more comfortable to use good (ie
 > longer) variable names; less line wrapping.
 > 
 > I have a 2560 x 1440 pixel display; allows for two 120 char Emacs frames
 > side by side, with some left over for Firefox etc.

Same here, 118 char wide screen with wide linum-mode column on the
left.

Almost priceless with some world-wrapping :) lines I find in some
co-worker code...

-- 
ing. Gian Uberto Lauri
Senior Solution Developer
Dir. Tecnica Innovazione Ricerca / Tech. Innovation & Research Div.
GianUberto.Lauri@eng.it

Sun Java Certified Programmer

Engineering Ingegneria Informatica spa
Corso Stati Uniti 23/C, 35127 Padova (PD)

Tel. +39-049.8283.517         | main(){printf(&unix["\021%six\012\0"],
Fax  +39-049.8283.569		  |    (unix)["have"]+"fun"-0x60);}
http://www.eng.it          	  |          David Korn, AT&T Bell Labs
                  			  |          ioccc best One Liner, 1987

Re: Exposing Isearch toggleable options

[Ashton Kemerling]

I've got mine all the way out to 365 columns.

--
Ashton

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Gian Uberto Lauri <saint@eng.it> writes:

> Same here, 118 char wide screen with wide linum-mode column on the left.

Artur's work is not more or less functional at different widths.

For a discussion on how our screens and windows are configured, I invite those
interested to join the new emacs-tangents list, where such a thread is most
welcome!

John

Re: Exposing Isearch toggleable options

[Xue Fuqiao]

Hi John,

On Fri, Nov 6, 2015 at 11:44 PM, John Wiegley <jwiegley@gmail.com> wrote:

> For a discussion on how our screens and windows are configured, I invite those
> interested to join the new emacs-tangents list, where such a thread is most
> welcome!

Thank you and Richard for creating this mailing list!

For those who haven't found this mailing list yet, here's the link:

https://lists.gnu.org/mailman/listinfo/emacs-tangents

Although IMHO there should also be a link to this ML in
https://savannah.gnu.org/mail/?group=emacs .

Re: Exposing Isearch toggleable options

[Dmitry Gutov]

On 11/06/2015 12:44 AM, Richard Stallman wrote:

>    > 2) I really don't think it'll be that distracting. On large screens
>    > it'll be over 100 spaces to the right of the search string.
>
> Do people actually use Emacs with windows so wide?

Do you mean frames? The minibuffer spans the whole frame.

> My screen is wide, but having more than 80 columns in Emacs would
> be a screw, so I tell Emacs that the screen is 80 columns wide.

split-window-horizontally is very handy.

My frames are full screen usually, which comes out to ~220 columns.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-11-06 15:54 GMT+00:00 Dmitry Gutov <dgutov@yandex.ru>:
> On 11/06/2015 12:44 AM, Richard Stallman wrote:
>
>>    > 2) I really don't think it'll be that distracting. On large screens
>>    > it'll be over 100 spaces to the right of the search string.
>>
>> Do people actually use Emacs with windows so wide?
>
> Do you mean frames? The minibuffer spans the whole frame.

I will not give up on repeating this. :-)
Can we branch this off to another subject, please?

RE: Exposing Isearch toggleable options

[Drew Adams]

[-- 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

RE: Exposing Isearch toggleable options

[Artur Malabarba]

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

On 29 Oct 2015 1:19 am, "Drew Adams" <drew.adams@oracle.com> wrote:
>
> > 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.

Ok, Thanks.

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

FWIW, the options are not hardcoded. So a different set can be displayed.

> 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.

I agree with you partially. The information of which options are active or
relevant is a state info. Bit the info of which key toggles them is of
general use (and I'd like to expose it to users who don't read the manual).

[-- Attachment #2: Type: text/html, Size: 1449 bytes --]

RE: Exposing Isearch toggleable options

[Drew Adams]

> I agree with you partially. The information of which options are
> active or relevant is a state info. Bit the info of which key
> toggles them is of general use (and I'd like to expose it to users
> who don't read the manual).

I didn't propose that they be limited to getting such info from the
manual.  What I suggested is that they get it (and other info about
Isearch) from `C-h' during Isearch.

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-29 14:02 GMT+00:00 Drew Adams <drew.adams@oracle.com>:
>> I agree with you partially. The information of which options are
>> active or relevant is a state info. Bit the info of which key
>> toggles them is of general use (and I'd like to expose it to users
>> who don't read the manual).
>
> I didn't propose that they be limited to getting such info from the
> manual.  What I suggested is that they get it (and other info about
> Isearch) from `C-h' during Isearch.

Yes, sorry. I misunderstood you.
I'm liking this option quite a bit.

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:

> Basically, as soon as isearch starts, you should see something like this.
> Toggles [M-s]: [w] Word OFF [_] Symbol OFF ['] Character-Fold ON [r] Regexp
> OFF I-search: search string here

Artur, does this mean the I-search prompt would be two-lines high in the
minibuffer, instead of one-line? If so, I would definitely want a way to
disable it; if I already know the options, it shortens the text window for
documentation I wouldn't need.

For new users, I'm not sure whether it should be on by default or not. It's
handy, for sure, but distracting maybe? I can't say without that mindset. I'd
love to hear from some users to see what they think.

John

Re: Exposing Isearch toggleable options

[Nicolas Petton]

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

John Wiegley <johnw@newartisans.com> writes:

>>>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:
>
>> Basically, as soon as isearch starts, you should see something like this.
>> Toggles [M-s]: [w] Word OFF [_] Symbol OFF ['] Character-Fold ON [r] Regexp
>> OFF I-search: search string here
>
> Artur, does this mean the I-search prompt would be two-lines high in the
> minibuffer, instead of one-line? If so, I would definitely want a way to
> disable it; if I already know the options, it shortens the text window for
> documentation I wouldn't need.
>
> For new users, I'm not sure whether it should be on by default or not. It's
> handy, for sure, but distracting maybe? I can't say without that mindset. I'd
> love to hear from some users to see what they think.

Hi,

Magit displays all options for each Git action in a separate window,
which I still find useful, even now that I know most of them.  The same
goes for org-mode export, it is very handy.  I think this kind of
usability improvements are worth it, even if they take a significant
amount of screen space.

However, I'm afraid that with your changes Artur new users might think
that these visible options are the only ones isearch supports.  I know I
wouldn't look for more options than the one displayed when doing a Git
operation with Magit.

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-29 9:29 GMT+00:00 Nicolas Petton <nicolas@petton.fr>:
> John Wiegley <johnw@newartisans.com> writes:
>
>>>>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:
>>
>>> Basically, as soon as isearch starts, you should see something like this.
>>> Toggles [M-s]: [w] Word OFF [_] Symbol OFF ['] Character-Fold ON [r] Regexp
>>> OFF I-search: search string here
>>
>> Artur, does this mean the I-search prompt would be two-lines high in the
>> minibuffer, instead of one-line? If so, I would definitely want a way to
>> disable it; if I already know the options, it shortens the text window for
>> documentation I wouldn't need.
>>
>> For new users, I'm not sure whether it should be on by default or not. It's
>> handy, for sure, but distracting maybe? I can't say without that mindset. I'd
>> love to hear from some users to see what they think.
>
> Hi,
>
> Magit displays all options for each Git action in a separate window,
> which I still find useful, even now that I know most of them.  The same
> goes for org-mode export, it is very handy.  I think this kind of
> usability improvements are worth it, even if they take a significant
> amount of screen space.

Good point about magit. I feel the same way.

> However, I'm afraid that with your changes Artur new users might think
> that these visible options are the only ones isearch supports.  I know I
> wouldn't look for more options than the one displayed when doing a Git
> operation with Magit.

Hm. If there's very little friction to this addition (which I don't
think will be the case), I could expand this with even more lines so
as to show all the options.

Re: Exposing Isearch toggleable options

[Nicolas Petton]

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

Artur Malabarba <bruce.connor.am@gmail.com> writes:

> Hm. If there's very little friction to this addition (which I don't
> think will be the case), I could expand this with even more lines so
> as to show all the options.

Adding another entry like `More options' or even just `More' that would
display the help for isearch would be enough IMO.

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: Exposing Isearch toggleable options

[Kaushal Modi]

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

Hi Artur,

I like the effort you are putting into this to make the isearch bindings
more discoverable.

As few others suggested, I would also find that to be distracting. So I
wouldn't want to enable it by default.

But then I also wouldn't disable it by default forever. It would be useful
to see that hint window once in a while. That sort of fits with the use of
hydra that Oleh suggested. (I yet have to try out the isearch patches you
posted, Drew's help patch and the hydra that Oleh posted.)

That way the help pops up only when the user wants to, while in isearch.
And once used, the popup disappears. It will not show up again until the
user activates that help popup next time.

Another idea would be to do what guide-key and which-key packages do... The
help pops up only if the isearch input is idle for 2 seconds *only when the
input minibuffer is empty*. Once the user starts typing, that popup goes
away. That way the help popup will not distract while the user is typing
the search terms, cycling through the search results, etc. It will only
show up when the user has started isearch but hasn't typed anything in it
for 2 seconds, or if they typed something, then erased everything, then
again waiting for 2 seconds. Of course this 2 second auto help popup should
be able to be disabled. They should also be a key bound that also activates
that help popup manually. In that case too, the popup should disappear once
isearch activity is detected.

[-- Attachment #2: Type: text/html, Size: 1586 bytes --]

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Nicolas Petton <nicolas@petton.fr> writes:

> Magit displays all options for each Git action in a separate window, which I
> still find useful, even now that I know most of them. The same goes for
> org-mode export, it is very handy. I think this kind of usability
> improvements are worth it, even if they take a significant amount of screen
> space.

There's one major difference between Isearch and Magit: When Magit shows you
key options in a separate window, you aren't also looking at content in the
main buffer to see the results of your actions. With Isearch you are, so it
would take away screen real-estate from the very thing you're trying to see:
candidate hits within the buffer.

John

Re: Exposing Isearch toggleable options

[Artur Malabarba]

2015-10-29 5:53 GMT+00:00 John Wiegley <johnw@newartisans.com>:
> Artur, does this mean the I-search prompt would be two-lines high in the
> minibuffer, instead of one-line?

With this turned on, yes.

> If so, I would definitely want a way to
> disable it; if I already know the options, it shortens the text window for
> documentation I wouldn't need.

Yes there's an option to disable it.

> For new users, I'm not sure whether it should be on by default or not. It's
> handy, for sure, but distracting maybe? I can't say without that mindset. I'd
> love to hear from some users to see what they think.

Yes, that's my doubt.
The point here is to expose this to new users. So if it won't be ON by
default, I'd rather not even merge (it would just increase code
complexity and make it harder for us to take another direction on this
later).

But then, I'm not sure it's useful and non-distracting enough to
warrant being on by default.
I'm currently using it locally to get a feel for it and I hope other
people will too.
Maybe I should just add this to master with the message that it may
well be reverted before release.

Re: Exposing Isearch toggleable options

[Oleh Krehel]

"John Wiegley" <johnw@newartisans.com> writes:

> For new users, I'm not sure whether it should be on by default or not. It's
> handy, for sure, but distracting maybe? I can't say without that mindset. I'd
> love to hear from some users to see what they think.

It's pretty distracting, and I'd be upset if I was still using `isearch'
(instead of `swiper').

Here's a solution using `hydra' that might work better:

(defhydra hydra-isearch-toggles (:exit t
                                 :columns 4
                                 :pre (isearch-update))
  "Toggles"
  ("w" isearch-toggle-word
       (format
        "word: %S"
        (eq isearch-regexp-function
            #'word-search-regexp)))
  ("_" isearch-toggle-symbol
       (format
        "symbol: %S"
        (eq isearch-regexp-function
            #'isearch-symbol-regexp)))
  ("'" isearch-toggle-character-fold
       (format
        "character-fold: %S"
        (eq isearch-regexp-function
            #'character-fold-to-regexp)))
  ("r" isearch-toggle-regexp
       (format
        "regexp: %S" isearch-regexp))
  ("SPC" isearch-toggle-lax-whitespace
         (format
          "lax-whitespace: %S"
          (if isearch-regexp
              isearch-regexp-lax-whitespace
            isearch-lax-whitespace)))
  ("c" isearch-toggle-case-fold
       (format
        "case-fold: %S"
        isearch-case-fold-search))
  ("i" isearch-toggle-invisible
       (format
        "invisible: %S"
        isearch-invisible))
  ("q" nil "quit")
  ("C-o" nil "quit"))
(define-key isearch-mode-map (kbd "C-o")
  'hydra-isearch-toggles/body)

Nothing extra is shown initially, but once you press "C-o" (I selected a
prefix different from "M-s", so that it's easy to compare), all
available options will be seen.

You can toggle options like this: "C-o c" "C-o _" etc.

If you set `:exit nil`, you can toggle many options at once: "C-o c_rq",
but you'll have to press "q" in the end to get rid of the menu.

As a small note, I've noticed an annoying delay after each toggle before
the minibuffer comes back to normal, as if there's a (sit-for 1)
somewhere. As long as the isearch input is modified, the user may think
that it's not yet ready for further input, and wait until isearch input
is un-modified again.

Here's a suggestion to fix it:

(defun isearch--momentary-message (string)
  "Print STRING at the end of the isearch prompt for 1 second"
  (lv-message string)
  (run-at-time 2.0 nil #'lv-delete-window))

This suggestion isn't without its faults though: it uses an extra line
and temporarily resizes windows to make space for the message.

Oleh

Re: Exposing Isearch toggleable options

[Rasmus]

Hi,

Oleh Krehel <ohwoeowho@gmail.com> writes:

> Nothing extra is shown initially, but once you press "C-o" (I selected a
> prefix different from "M-s", so that it's easy to compare), all
> available options will be seen.

I like this.  This is similar to "?" in the org-exporter when "expert
mode" is non-nil.  However, with a key like C-o or M-s I would guess you
won’t solve the visibility issue.  Perhaps the modeline could give a hint
about what to click to show further options in a nice popup.

I do, strongly(!), agree with Arthur that it’s really hard to know about
all the isearch options.

Rasmus

-- 
And I faced endless streams of vendor-approved Ikea furniture. . .

RE: Exposing Isearch toggleable options

[Drew Adams]

> I do, strongly(!), agree with Arthur that it’s really hard to know about
> all the isearch options.

No.  It's simple - provided `C-h' brings up help on Isearch,
including a list of the key bindings.

A user just needs to expect that `C-h' after a key such as `C-s'
might show key bindings, just as it does for prefix keys.  S?he
will then be pleasantly surprised to see that in the case of
Isearch `C-h' shows not only the keys but also a description
of Isearch, with descriptions of the important features,
including the important keys.

`C-h' should be the starting place, in general.  For the
help commands, of course, but also for prefix keys and modes
that use the minibuffer or, modes like Isearch, that seem to
use the  minibuffer.

Re: Exposing Isearch toggleable options

[Eli Zaretskii]

> From: "John Wiegley" <johnw@newartisans.com>
> Date: Wed, 28 Oct 2015 22:53:27 -0700
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> >>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:
> 
> > Basically, as soon as isearch starts, you should see something like this.
> > Toggles [M-s]: [w] Word OFF [_] Symbol OFF ['] Character-Fold ON [r] Regexp
> > OFF I-search: search string here
> 
> Artur, does this mean the I-search prompt would be two-lines high in the
> minibuffer, instead of one-line? If so, I would definitely want a way to
> disable it; if I already know the options, it shortens the text window for
> documentation I wouldn't need.

How about showing that on the mode line, like we do for eldoc-mode?

RE: Exposing Isearch toggleable options

[Drew Adams]

> > Artur, does this mean the I-search prompt would be two-lines high in the
> > minibuffer, instead of one-line? If so, I would definitely want a way to
> > disable it; if I already know the options, it shortens the text window for
> > documentation I wouldn't need.
> 
> How about showing that on the mode line, like we do for eldoc-mode?

There are many Isearch bindings, some of which are (far) more
important than toggles.  Why promote these particular bindings
in this way?

Why not encourage users to consult the Isearch help?
 And have that help explicitly describe the available toggles,
     as well as the most important keys.
 And have that help list _all_ of the Isearch key bindings,
     at the end.
 And provide that help on a quick Isearch key (e.g. `C-h').

It is misguided, IMHO, to privilege this kind of thing, either
at Isearch startup (a message) or in the mode line.

Messages should be used for changes of state.
Mode-line indications should be used for the current state.

Re: Exposing Isearch toggleable options

[Aldric Giacomoni]

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

On Thu, Oct 29, 2015 at 1:53 AM John Wiegley <johnw@newartisans.com> wrote:

> >>>>> Artur Malabarba <bruce.connor.am@gmail.com> writes:
>
> > Basically, as soon as isearch starts, you should see something like this.
> > Toggles [M-s]: [w] Word OFF [_] Symbol OFF ['] Character-Fold ON [r]
> Regexp
> > OFF I-search: search string here
>
> Artur, does this mean the I-search prompt would be two-lines high in the
> minibuffer, instead of one-line? If so, I would definitely want a way to
> disable it; if I already know the options, it shortens the text window for
> documentation I wouldn't need.
>
> For new users, I'm not sure whether it should be on by default or not. It's
> handy, for sure, but distracting maybe? I can't say without that mindset.
> I'd
> love to hear from some users to see what they think.
>
> John
>
>
In the wake of magit, Mickey Petersen (who wrote Mastering Emacs) wrote a
package called discover.el (blog intro + screenshot):
https://www.masteringemacs.org/article/discoverel-discover-emacs-context-menus


This might be a good direction for the conversation.

I've been an emacs user for ~2 years now. I think some minimal
documentation / toggles in the magit spirit would go a long way in
demystifying the emacs behavior.

As noted by someone else, I would consider it critical to indicate somehow
that there are other modifiers and options.

I would, of course, want a toggle for this.

Some of the things that have made my life as a newbie better were:
- discovering which function I just triggered with my keypress
- discovering which keypress I can use for the function I just called
- discovering how I can modify the default behavior of an emacs function

Any way in which emacs can help with these things is good for a beginner,
to help them map emacs behavior with emacs terminology.

[-- Attachment #2: Type: text/html, Size: 2547 bytes --]

Re: Exposing Isearch toggleable options

[John Wiegley]

>>>>> Aldric Giacomoni <trevoke@gmail.com> writes:

> I've been an emacs user for ~2 years now. I think some minimal documentation
> / toggles in the magit spirit would go a long way in demystifying the emacs
> behavior.

I use this module to achieve something similar:

    https://github.com/justbur/emacs-which-key

I'd be happy to see this moved into core, with a customization option
mentioned in the tutorial for enabling it globally.

I'm not so sure about it being a global default, however. It can be very
annoying to users who don't want it. Not every use case in Emacs fits the
"Magit pattern", such as Isearch (as I mentioned in another message).

John

Re: Exposing Isearch toggleable options

[Óscar Fuentes]

Aldric Giacomoni <trevoke@gmail.com> writes:

> In the wake of magit, Mickey Petersen (who wrote Mastering Emacs) wrote a
> package called discover.el (blog intro + screenshot):
> https://www.masteringemacs.org/article/discoverel-discover-emacs-context-menus
>
>
> This might be a good direction for the conversation.
>
> I've been an emacs user for ~2 years now. I think some minimal
> documentation / toggles in the magit spirit would go a long way in
> demystifying the emacs behavior.
>
> As noted by someone else, I would consider it critical to indicate somehow
> that there are other modifiers and options.
>
> I would, of course, want a toggle for this.

I designed the Magit popup and implemented it on my fork (the Magit
maintainer at the time then reimplemented it with a few differences
instead of pulling my work, due to a miscommunication.) So you can take
for granted that I like the Magit approach... for driving git. The
same paradigm seems to work ok for parts of Org mode too.

However, I don't think that the Magit popup is the correct solution for
Emacs' poor discoverability, for several reasons. First of all, git is a
single entry point with lots of commands and options. Magit assigns a
key to groups of related commands and then lists the commands and its
options. In Emacs, there would be a large number of groups and, within
each group, lots of options. This would cause a high cognitive load, if
it were practical at all to browse the large number of entries.

I could go on about why the Magit popup approach is not the right one,
for Emacs in general.

The discoverability issue is a very interesting one. Even more when
combined with ergonomics and convenience in general. Not too long ago I
was surprised to see how discoverability *and* convenience are benefited
from having a good completion mechanism on the M-x and set-variable
prompts. Ido+flx was a big enhancement for a tiny effort, IMO. I'm sure
that other packages can bring similar or superior benefits.

Ido+flx work on command/variable names. It would be better to have
conceptual relations among features, and exploit those relations
contextually. Some type of smart search engine for features, with the
right interfaces.

[snip]

RE: Exposing Isearch toggleable options

[Drew Adams]

> The discoverability issue is a very interesting one. Even more when
> combined with ergonomics and convenience in general. Not too long ago I
> was surprised to see how discoverability *and* convenience are benefited
> from having a good completion mechanism on the M-x and set-variable
> prompts. Ido+flx was a big enhancement for a tiny effort, IMO. I'm sure
> that other packages can bring similar or superior benefits.
> 
> Ido+flx work on command/variable names. It would be better to have
> conceptual relations among features, and exploit those relations
> contextually. Some type of smart search engine for features, with the
> right interfaces.

FWIW: Icicles provides this for all minibuffer completion, not
just for command and variable names.  It also provides all of
the keys available in the current dynamic context, including after
you hit prefix keys.  (And you can invoke the completed keys -
any number of the key-completion candidates.)

By default, it automatically provides short help in the mode line
for the "current" completion candidate (you can cycle candidates
or otherwise choose any as the "current" one).  And you can hit
a key to get the complete help for the current candidate, in *Help*.

For example, for `M-x', the candidates are command names.  Cycling
among those that match your current minibuffer input, as each is
cycled through, one-line help is shown for it in the mode line.
And if you hit `C-M-RET' then the complete `describe-function'
help for it is shown in `*Help*'.

Same thing for faces (using `describe-face'), packages,... whatever.

Same thing for key completion: the available keys (at top level or
after a prefix key) are completion candidates, and their help too
is available in the mode line and (on demand) in *Help*.

So yes, I agree that discoverability is radically helped by
providing help on completion candidates.

And extending this to keys is particularly helpful.  Emacs lets
you know what you can do at any time, and lets you find out more
and more about what's possible, on demand, on the fly.  (You can
access the manual from *Help*...)