bug#34150: 26.1; Document filtering with `isearch-filter-predicate' in Elisp manual

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

> > The only doc I can find about making Isearch and `perform-replace'
> (all
> > of its uses) ignore/exclude certain matches is the doc string of
> > variable `isearch-filter-predicate'.
> 
> I don't see why the doc string shouldn't be enough.  This is a quite
> obscure feature, so I don't think it warrants to be described in the
> manual.

I disagree that it is obscure - or that it should be,
at least.  But of course if it is not well documented
and it is (still) hardly ever used by Emacs itself
then it will not necessarily be noticed, understood,
and used.  Its current obscurity is a self-fulfilling
prophecy.

> > It would also be good to state whether predefined search functions
> > such as `re-search-forward' respect it.  (I imagine that they do
> > not, but I haven't checked, and there's no doc about this AFAIK.)
>
> I modified the doc string to mention Isearch and replace commands.

Thanks.  And non-command functions such as `re-search-forward'?

> > One thing that it would also be good to make extra clear is that
> > filtering takes place _after_ input matching; it is not part of
> > matching.
> 
> How can it be part of matching, if the filter needs to be passed the
> limits of the matched text?

No one contests that impossibility.

But it and its consequences are not necessarily
obvious - especially to a user searching, as opposed
to a programmer writing a filter predicate.

Isearch's handling of filter limits is very different
from its handling of buffer limits, for example.  A
filter doesn't constrain search to be inside its
limits, in the sense that the search matches take no
account of such limits.  This is not necessarily
obvious to a _user_.  (It might or might not be clear
to some programmer who defines the filter.)

You can easily notice this as a user if you try to
regexp-search when a filter excludes text outside a
rectangle or a set of columns, for instance.

A user could easily, and incorrectly, expect the
rectangle to "contain" search, similarly to how a
buffer restriction contains it.  She could ask herself
how it is that a regexp with `.*' doesn't "match" some
particular text within the rectangle, the answer being
that it instead matched longer text that extended
outside the rectangle, and that match was filtered out.

If this user-level description makes no sense to you
I expect it's because you haven't played with filters
enough or, more likely, because you start from an
understanding of the code - which a user does not.

Just emphasizing explicitly that filtering takes
place _after_ input matching can help, I think.  As
you know, filtering can in general be done before or
during querying/searching/matching, as well as after
it.  IMO, it's worth emphasizing that this is only
post-match filtering.

If you ask why a _user_ needs to know about filter
predicates and filtering then my answer is longer.
I'll leave that out, unless you ask for it.

Using `isearch-filter-predicate' can be powerful.
But it is also somewhat limited/weak because
filtering cannot be taken into account as part of
matching.

Imagine being able to contain search within a
rectangle, for instance.  That's something you
cannot do with only `isearch-filter-predicate'.

Whether or not such limitation is obvious to a
particular filter writer, it certainly is not
obvious to a filter user, I think.