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

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

[Drew Adams]

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.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-07 on ODIEONE
Bzr revision: 113750 lekktu@gmail.com-20130808011911-0jzpc9xuncegg6x9
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 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, but if you read the page from the start to finish,
you see that it explains what all meta-syntactical are once.  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.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

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

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

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

And in the next paragraphs it doesn't define MATCHER, because, well,
it's the same.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/