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

[Jambunathan K <kjambunathan@gmail.com>]

Eli

> Info (point-entered, point-left): Doc incomplete, hence incorrect

You asked for a wall-of-text.  Here you go.

----------------------------------------------------------------
Imagery:


If a hotel is interested in taking visitors why should it even care how
it is painted or that it be painted differently from the neighbouring
hotels?

----------------------------------------------------------------
Unask the question:


Consider the following scenario?

    1. The WHOLE buffer has the SAME point-visited property.
    2. The whole buffer has NO OTHER text properties applied to it.

Under the above conditions, can the user use the point-visited property
achieve a sensible behaviour.

The answer is an emphatic YES.  Read on.

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

On relevance and expedience:


You are making a WRONG ASSUMPTION that text properties MUST flip-flop.

The flip-flopping of text properties is a mere chunking trick to
rate-limit point visited calls.  It is a requirement IMPOSED FROM
OUTSIDE (and which can usually be met in practice) but is not GERMANE to
the problem at hand.


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

What (usually) are text properties, in this context?

In this context, the text properties act as a pre-computed syntactic
context.  The requirement that properties flip-flop is but a way of
saying that a stretch of text be syntactically different from the
surrounding text.


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

Can uniqueness be expressed in other ways, apart from text properties?


Yes.  With parsers, it is possible to infer a context JUST-IN-TIME.
Should parsers be expected to decorated text?  Not necessary.  There
could be reasons why parsers don't decorate text.  One reason could be
that it is young.  One example, is the Org parser.  (Font-locking and
the ppss stuff is just a poor man's parser)

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

Stop the bullshit.  Give an example?

See
http://lists.gnu.org/archive/html/emacs-orgmode/2013-09/msg00425.html

    (add-hook 'org-mode-hook
              (lambda nil
                (setq-local default-text-properties
                            '(point-entered org-link-entered-maybe))))

    (defun org-link-entered-maybe (op np)
      (when (derived-mode-p 'org-mode)
        ;; (message "In org-link-entered-maybe")
        (let* ((inhibit-point-motion-hooks t)
               (ctx (org-element-context)))
          (when (eq 'link (org-element-type ctx))
            (tooltip-show (org-element-property :raw-link ctx)
                          (not 'use-echo-area))))))


In the above example, the context - that the character is part of a link
- is computed JIT to pop open a tooltip that shows the underlying URL.

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

Can text properties express rich context with less OVERHEADS?


Text properties (typically) break the text in to pieces.  They can
express UNIQUENESS.  Can they express the much richer, UNIQUENESS and
CONTAINMENT - I am an Org link, within the second item, of the third
level list within 4 th level heading - in a fully-synced manner.

I think the answer is NO.

Since Text Properties are pre-computed text, it becomes messy to keep
them in SYNC with an ever-changing text.

Expressed simply, JIT eliminates the caches and problems associated with
it.

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

In what ways can a character be special?


A character can be special for the following reasons

1. Syntactic:  It's position in the buffer text - A hyperlink, variable
   name etc.

2. Spatial: A character that belongs to the margins.  i.e., to the left
   of `left-margin'.


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


Text properties cannot express spatial uniqueness


Can text properties be used for expressing spatial uniqueness?  Good
luck with it.  

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

Spatial uniqueness and text properties. 


I am noting this only because this was the primary motivation to explore
point-visited properties in first place.

    How to edit a left-marginned text and make sure that point never
    rests on the margin area.  Think of a diary or a todo item.  They
    are a MIX of indented and un-indented text.

Left-marginned text, no problem?

    (setq left-margin 16)
    (setq indent-line-function 'indent-to-left-margin)

I want C-p and C-n to actively seek indented text.  No problem.

    C-x C-n

I want C-a not to actively rest within on text area and NEVER stray in
to the margins.  I am at a total loss here.  How will I do it?  


1. Play with tangibility of `\n +'.  I need to mess with
   `indent-line-function'.  I don't want to keep decorating and
   un-decorating a character for spatial reasons.

2. Let me look at other possiblities.  Ha! point-entered and point-left
   looks interesting. 

   ;; Within point-entered property.
   (if ( < (current-column) left-margin)
       (goto-char left-margin))

   This is very wonderful, I don't even have to set the goal column.

3. Hmm! Doesn't work.  Why?  Because document sucks?

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