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

[Eli Zaretskii]

> Date: Sun, 20 Jan 2019 16:17:41 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 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'.

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.

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

To me, "the positions of start and end of the matched text" says
precisely that.  I don't see what can references to match-beginning
and match-end add; if anything, they might confuse, because at least
some readers will be sent down the rabbit hole to the descriptions of
those two, something that IMO is entirely unnecessary for writing a
filter.

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

I modified the doc string to mention Isearch and replace commands.

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