bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Drew Adams]

`C-h v isearch(-regexp)-lax-whitespace' tells you that command
`isearch-toggle-lax-whitespace' toggles the variable.  But it does not
tell you that this command is bound, by default, to `M-s SPC' during
Isearch.

It should tell you that.  (It is not so easy to discover the binding.)

In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Eli Zaretskii]

> Date: Mon, 11 Jun 2018 15:16:08 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> `C-h v isearch(-regexp)-lax-whitespace' tells you that command
> `isearch-toggle-lax-whitespace' toggles the variable.  But it does not
> tell you that this command is bound, by default, to `M-s SPC' during
> Isearch.
> 
> It should tell you that.  (It is not so easy to discover the binding.)

Those are variables, not defcustoms.  Why is it important to go to
such lengths in their doc strings?

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Lars Ingebrigtsen]

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

> `C-h v isearch(-regexp)-lax-whitespace' tells you that command
> `isearch-toggle-lax-whitespace' toggles the variable.  But it does not
> tell you that this command is bound, by default, to `M-s SPC' during
> Isearch.
>
> It should tell you that.  (It is not so easy to discover the binding.)

Now done in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Drew Adams]

> > `C-h v isearch(-regexp)-lax-whitespace' tells you that command
> > `isearch-toggle-lax-whitespace' toggles the variable.  But it does not
> > tell you that this command is bound, by default, to `M-s SPC' during
> > Isearch.
> >
> > It should tell you that.  (It is not so easy to discover the binding.)
> 
> Those are variables, not defcustoms.  Why is it important to go to
> such lengths in their doc strings?

Go to such lengths?  Really?

See https://emacs.stackexchange.com/q/41960/105.

Sure, if you consult the doc of `isearch-forward(-regexp)'
or its keys, and you read it all, then when you get to line
43 (out of 82!) you'll find the info you're looking for wrt
lax-vs-strict whitespace matching:

 Type M-s SPC to toggle whitespace matching.
 In incremental searches, a space or spaces normally matches any 
 whitespace defined by the variable 'search-whitespace-regexp';
 see also the variables 'isearch-lax-whitespace' and
 'isearch-regexp-lax-whitespace'.

But if you don't do that then it is not so easy to pick
up the info about that key binding.

And even that text does not make clear what the latter
two vars do.  To discover how to change the default
behavior you need to actually click those var names
and consult their doc.

And yes, setting or binding those two vars really is
the way to go, to set your preferred default behavior.

We provide `search-whitespace-regexp' as a user option,
but not the other two variables, which are more commonly
set by users to govern whitespace matching for search.

Yes, we don't let those vars be options because of the
Emacs policy that code should not modify option values
(even the code for built-in toggles!).

It's an unfortunate policy, IMHO, but it is what it is.

It just makes sense to point out, in the doc for these
two variables that, by default, `M-s SPC' toggles them
while searching.

If providing that info to users is too much trouble
("go to such lengths"?), then ... please don't bother.

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Eli Zaretskii]

> Date: Sat, 16 Jun 2018 06:19:55 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 31790@debbugs.gnu.org
> 
> > Those are variables, not defcustoms.  Why is it important to go to
> > such lengths in their doc strings?
> 
> Go to such lengths?  Really?
> 
> See https://emacs.stackexchange.com/q/41960/105.

I don't see how that is evidence to anything.

> Sure, if you consult the doc of `isearch-forward(-regexp)'
> or its keys, and you read it all, then when you get to line
> 43 (out of 82!) you'll find the info you're looking for wrt
> lax-vs-strict whitespace matching:

Those are powerful and flexible commands, it's no wonder their
documentation is long.  (And 82 lines is not too long in my book.)

> But if you don't do that then it is not so easy to pick
> up the info about that key binding.

And having that in a doc string of a non-user variable will make it
easier to pick up?

> Yes, we don't let those vars be options because of the
> Emacs policy that code should not modify option values
> (even the code for built-in toggles!).
> 
> It's an unfortunate policy, IMHO, but it is what it is.
> 
> It just makes sense to point out, in the doc for these
> two variables that, by default, `M-s SPC' toggles them
> while searching.

Like I said, I disagree.

Maybe we should provide defcustoms that would initialize the values of
these variables.  Then it would make sense to tell what you want in
those defcustoms' doc strings, like we do with search-invisible, for
example.

bug#31790: 27.0; Mention Isearch key bindings of Isedarch variables that are bound by default in Isearch

[Drew Adams]

> And having that in a doc string of a non-user variable will make it
> easier to pick up?

Yes.

> > It just makes sense to point out, in the doc for these
> > two variables that, by default, `M-s SPC' toggles them
> > while searching.
> 
> Like I said, I disagree.
> 
> Maybe we should provide defcustoms that would initialize the values of
> these variables.  Then it would make sense to tell what you want in
> those defcustoms' doc strings, like we do with search-invisible, for
> example.

That takes care of letting users set the default behavior,
yes.

It doesn't, however, tell them anything about being able
to hit a key while searching to toggle the current behavior.

If you add defcustoms and then mention in their doc strings
that the _current_ behavior can be toggled with `M-s SPC'
then that would take care of this bug report.

Users will naturally want to (1) set their preferred default
behavior or (2) toggle the current behavior, or both.  The
point is to help them better to know how they can do these
things (which they can do already).