bug#15120: 24.3.50; (elisp) `Search-based Fontification': unspecified MATCHER cases

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

> > The doc string is good in this regard, but the Elisp manual is
> > not.
> >
> > The manual says that an element can be FUNCTION.  OK.
> >
> > And it says, for (MATCHER . SUBEXP), that MATCHER can be a
> > function.  OK.
> >
> > But it does not say that for all of the other (MATCHER . *)
> > patterns MATCHER can also be a function.  In fact, for the others
> > MATCHER is left unspecified.
> >
> > And for (MATCHER . SUBEXP-HIGHLIGHTER) the doc actually refers to
> > a "SUBEXP in MATCHER", which suggests, but does not specify, that
> > MATCHER in this case can be or perhaps even *must be* a REGEXP.
> >
> > Follow the example of the doc string, or state somewhere that
> > MATCHER, in all that follows, can be either a regexp or a function...
> >
> > IOW, make clear just what MATCHER can be, in general or in each of
> > the cases.
> 
> I see what you mean, 

No, I don't think you do.

> but if you read the page from the start to finish,

I certainly did that.  Did you?

> you see that it explains what all meta-syntactical are once.

Not at all.

> It says what MATCHER is the first time it talks about it, and then it
> just describes what each new element is.  So I think the page is OK as
> is.

You are just not reading.

What it says, at the place where you apparently think that it
introduces MATCHER for the entire page, is this:

  "In this kind of element, MATCHER is..."
   ^^^^^^^^^^^^^^^^^^^^^^^

IN THIS KIND OF ELEMENT!  Why on Earth does it say that?

It is specifying what MATCHER means in the form `(MATCHER . SUBEXP)',
where SUBEXP must be...  And by taking the pains to specify
explicitly that this applies to this kind of element, the
suggestion is that it does NOT necessarily apply to the other
kinds of element shown on the page.  Otherwise, why say that?

That's the point: each of these kinds of "element" is specified
separately, and it says so explicitly.  If you want to make the
current description of MATCHER apply to the whole page, then it
needs to be introduced at the outset as applying to the whole page.

And the text certainly should NOT then say that the description
applies to some particular kind of element.  IOW, remove that
"In this kind of element...", as well.

Again, please _read_ the bug report.  Among other things, it says
that the doc string gets it right.  Use it, if it helps, as your
inspiration for actually _fixing_ this bug.