bug#22036: 25.0.50; (emacs) Lax Search

bug#22036: 25.0.50; (emacs) Lax Search

[Drew Adams]

Mostly minor suggestions.  And I realize that some of the problems
mentioned here are not new - they were already present in node `Special
Isearch', for example.  But things have deteriorated a bit more, I
think.  If you can make improvements, that will help readers.

1. "Normally, you'd want", "are normally perceived as equivalent",
"letter-case differences usually don't matter", "normally ignore the
case", "Searches in Emacs normally perform"...

Please rephrase such text.  There is nothing "normal" about one behavior
or abnormal about the opposite behavior.  There is no norm, here.
Simply say what the behaviors are and what the default behavior is,
without claiming that one is "normal".  And it is not the case for all
(even most?) users that "letter-case differences usually don't matter".
There is no such "usually".

Emacs users and use cases are all over the map.  Saying "normally" or
"usually" can make a reader think that it is important to stick with
this behavior, whereas it is just a default that we chose because we
thought it would be helpful.

2. Please cross-reference node `Replacement and Lax Matches' (which
cross-references node `Lax Search').

3. Why is regexp search not handled here as well?  Why send someone off
to node `Regexp Search' for info about lax matching during regexp
search?  Maybe there is a good reason, but as one user I would expect,
a priori, to read all about lax matching here.

4. There is a problem with this text:

"Hence, `foo bar' matches `foo bar', `foo bar', `foo bar', and so on
(but not `foobar')."  Those three are rendered identically - a single
SPC char is used to separate the words in all cases.

5. Missing word "off" here? "you can turn lax space matching by typing"

6. Unclear: "To disable this feature entirely".  When I read that far, I
thought it was talking about disabling the feature of toggling.  Also,
just say that `M-s <SPC>' toggles lax whitespace search - no need to
describe what toggling means (off, on again, etc.).

7. Everything in this manual is "in Emacs", so you can drop that phrase
everywhere.

8. The explanation of case matching here seems to repeat what is said
about it in node `Special Isearch'.  More factoring needed, perhaps.

9. "This applies to regular expression search as well as to string
search."  Literal search, not string search.

10. The same paragraph is also repetitive: you explain the effect of an
upper-case char, then you say that if it is removed the effect goes away
(OK, but not needed), and then you describe the effect of option
`search-upper-case' by repeating the description of the non-nil
behavior.

11. "does not extend beyond the current incremental search to the next
one" is repetitive.  Presumably "to the next" is what was meant by
"extend beyond".

12. Choose whether you want the term "character folding" to refer to (1)
the general category of folding of chars, including specific kinds of
character folding such as case folding and whitespace folding, or (2)
what is called by the search and replace UI "character folding",
which is just another specific kind of (character) folding.

The equivalence classes recognized by this "character folding" (#2) do
not include case folding - they are specifically about a set of
predefined equivalences other than letter case, equivalences which
involve ignoring diacritical marks plus a few others (quote marks etc.).

We need to find a clear way to talk about this now, because now is when
we are introducing more character folding than just case and whitespace.
If you choose #1 then some more specific term is need here and in the UI
for #2.

It is also the case that, for the moment, at least, the equivalences
defined by character-fold.el are a motley crew - diacriticals and
compositions plus some ad hoc extras (e.g., quotations).  This should
all be sorted out before we go too far with this (useful) feature.

13. It's better to drop the future tense and use the present: "will
match" -> "matches".

14. "the `nil' value" -> just "`nil'".  We don't say "the 4" value; we
say "4".  Same with `nil', `t', etc.

15. "typing an explicit variant of a character, such as `ä'".  Consider
adding the char name after this char, or do something else to help
readers see that what is quoted is not just the letter "a".  This is not
obvious.  Maybe a different char choice would be more obvious; dunno.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-11-27
Bzr revision: a5f2970207d792e5f5d40160485007f282a0569d
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/emacs-25 --with-modules
 --enable-checking=yes --enable-check-lisp-object-type
 --without-compress-install 'CFLAGS=-Og -ggdb3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#22036: 25.0.50; (emacs) Lax Search

[Eli Zaretskii]

> Date: Fri, 27 Nov 2015 20:30:00 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Mostly minor suggestions.  And I realize that some of the problems
> mentioned here are not new - they were already present in node `Special
> Isearch', for example.  But things have deteriorated a bit more, I
> think.  If you can make improvements, that will help readers.

Thanks.  I made most of the changes you suggested; the few comments
below are where I did not.

> 1. "Normally, you'd want", "are normally perceived as equivalent",
> "letter-case differences usually don't matter", "normally ignore the
> case", "Searches in Emacs normally perform"...
> 
> Please rephrase such text.  There is nothing "normal" about one behavior
> or abnormal about the opposite behavior.  There is no norm, here.

I replaced a few of these with "by default", especially where that
alludes to Emacs behavior.  I didn't replace all of them: this is the
"normal" style in the manual, with more than 200 occurrences all over.
I see no reason to replace all of them, and even less reasons to
replace all of them just in this node.

> 3. Why is regexp search not handled here as well?  Why send someone off
> to node `Regexp Search' for info about lax matching during regexp
> search?  Maybe there is a good reason, but as one user I would expect,
> a priori, to read all about lax matching here.

There's a fundamental dilemma when documenting a complex feature such
as this one.  You cannot document it in a single large section,
because it will be too large.  When the description is broken into
several sections and subsections, the dilemma is how to give a
newcomer the big picture without risking drowning them in the details.
What you see is a compromise: some repetition, and some details
stashed in their own subsections and just hinted upon in the general
overview description.

> 7. Everything in this manual is "in Emacs", so you can drop that phrase
> everywhere.

Again, "everywhere" is too radical, IMO.  Dropped a few.

> 8. The explanation of case matching here seems to repeat what is said
> about it in node `Special Isearch'.  More factoring needed, perhaps.

See above: it doesn't repeat, it just summarizes and sends to another
section for details.

> 12. Choose whether you want the term "character folding" to refer to (1)
> the general category of folding of chars, including specific kinds of
> character folding such as case folding and whitespace folding, or (2)
> what is called by the search and replace UI "character folding",
> which is just another specific kind of (character) folding.

I did decide: the text I wrote speaks for itself, I think.  Whether
this is a good decision or needs some corrections -- the time will
tell.  Let the text hit the street, and let's see if there are any
complaints.

> 15. "typing an explicit variant of a character, such as `ä'".  Consider
> adding the char name after this char, or do something else to help
> readers see that what is quoted is not just the letter "a".

I very much doubt we need this with Unicode-capable fonts all around
us.  But if I'm wrong, we will see bug reports.

Thanks.

bug#22036: 25.0.50; (emacs) Lax Search

[Drew Adams]

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

> I made most of the changes you suggested; the few comments
> below are where I did not.

Thanks.

> > 15. "typing an explicit variant of a character, such as `ä'".
> > Consider adding the char name after this char, or do something
> > else to help readers see that what is quoted is not just the
> > letter "a".
> 
> I very much doubt we need this with Unicode-capable fonts all
> around us.  But if I'm wrong, we will see bug reports.

I agree that the name of the char is unimportant here (and so
inappropriate).  I will only say that even with a fairly large
font size, with my default font of Lucida Console I cannot really
see the diacritical - see screenshot.  I do suggest perhaps
trying a different char or "do something else" to make clear that
this letter has a mark.

Even with the default (emacs -Q) font, for instance, `á' is much
easier to distinguish from `a' than is `ä'.  The occurrence of
`ä' in the last paragraph, where there is no other to compare
with, is particularly problematic.

[-- Attachment #2: throw-emacs-bug-22036.png --]
[-- Type: image/png, Size: 69754 bytes --]