bug#16308: 24.3.50; doc of `font-lock-keywords'

bug#16308: 24.3.50; doc of `font-lock-keywords'

[Drew Adams]

The description in the Elisp manual, which is our reference, should be
at least as complete as the doc string.  It is not.  In particular, it
does not describe the structure of the value correctly.  It does not
mention the compiled form, with car `t' etc.

The doc string is far more complete.  If anything, it should be the
other way around.  But preferably, both doc string and manual (node
`Search-based Fontification', currently) should each be complete and
correct.

[BTW, the name of that node should use "Search-Based", not "Search-based".]


In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-12-27 on ODIEONE
Bzr revision: 115778 rgm@gnu.org-20131228000456-1797o8z6veuyozs0
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#16308: 24.3.50; doc of `font-lock-keywords'

[Lars Ingebrigtsen]

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

> The description in the Elisp manual, which is our reference, should be
> at least as complete as the doc string.  It is not.  In particular, it
> does not describe the structure of the value correctly.  It does not
> mention the compiled form, with car `t' etc.
>
> The doc string is far more complete.  If anything, it should be the
> other way around.  But preferably, both doc string and manual (node
> `Search-based Fontification', currently) should each be complete and
> correct.

No, I think the information about the compiled form isn't particularly
relevant for people who are composing the keywords, while it is relevant
for people who examine the variable, so it's fine the way it is.

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

bug#16308: 24.3.50; doc of `font-lock-keywords'

[Drew Adams]

> No, I think the information about the compiled form isn't
> particularly relevant for people who are composing the keywords,
> while it is relevant for people who examine the variable, so
> it's fine the way it is.

Well you think wrong, then.

The Elisp manual is our _reference_.  The info there about
`font-lock-keywords' needs to be complete.  It is not at all
there only for "people who are composing the keywords".

bug#16308: 24.3.50; doc of `font-lock-keywords'

[Stefan Monnier]

> Well you think wrong, then.

No, you guys just disagree.  And I side with Lars on this one.


        Stefan