bug#15312: Info (point-entered, point-left): Doc incomplete, hence incorrect

[Jambunathan K <kjambunathan@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jambunathan K <kjambunathan@gmail.com>
>> Date: Mon, 09 Sep 2013 19:04:59 +0530
>> 
>> 
>> The info doc (see below) makes no mention of intervals/text properties.
>> It should mention what intervals.c actually does.
>
> What exactly does it not mention now, 

About text properties.  They need to be different.

> and under which circumstances will a Lisp programmer see that?

Does this question mean when will point-entered and point-left hook be
used (or used at all)?  I suggest that you look at table.el, gomoku.el,
landmark.el et.al.
----------------------------------------------------------------

Copy the snippet below to *scratch* buffer and eval them.  (I assume
that your *scratch* buffer is in emacs-lisp-mode and is colorful)

Keep C-f-ing and C-b-ing and see what happens.

You will see that entered and left get triggered when you move from a
text that has one face to another, NOT when they have the same faces.

    (defun --point-entered (&rest args)
      (message "entered: %s" args))

    (defun --point-left (&rest args)
      (message "left: %s" args))

    (add-text-properties (point-min) (point-max) 
                         '(point-left --point-left
                                      point-entered --point-entered))

----------------------------------------------------------------

Doc (makes) an (incomplete and) incorrect claim that the triggering of
hook depends SOLELY on the value of point-left and point-entered
properties.  It is NOT so.  The values of TEXT PROPERTIES should be
DIFFERENT at the transition point.