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

[Drew Adams]

See https://emacs.stackexchange.com/q/47302/105, as one possible
motivaton.

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

And that doc string isn't very precise about the args of the predicate.
It says only: "The function has two arguments: the positions of start
and end of text matched by the search."

It would help to add that these positions are `(match-beginning 0)' and
`(match-end 0)', respectively, and to say that the match start position
is the first of the two args.  (Sure, start coming first is not
surprising, but it also doesn't follow from the description.)

I suggest adding a short topic about filtering with this predicate,
perhaps with a simple example.  At least mention that this is used in
the predefined search commands (including Isearch) and the predefined
replacement commands.

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.)  You could guess
no, based on the `isearch' part of the variable name.  But if you guess
like that then you likely won't also guess that the variable applies to
`perform-replace' - it's not just about Isearch.

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.  Not getting this can be a gotcha with greedy regexp matching.
For example, a filter predicate that excludes matches that extend past
column 70 does not keep the part of a match before column 70, even if
that part also matches the same regexp.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''