Elisp manual doc of `fontified' property

[Drew Adams]

The doc says this:

`fontified'
     This property says whether the character has a face assigned to it
     by font locking.  The display engine tests it to decide whether a
     buffer portion needs refontifying before display.  *Note Auto
     Faces::.  It takes one of three values:

    `nil'
          Font locking is disabled, or the character's `face' property,
          if any, is invalid.

    `defer'
          This value is only used when "just in time" font locking is
          enabled and it means that the character's `face' property is
          invalid and needs deferred fontification.

    `t'
          The character's `face' property, or absence of one, is valid.

However, some emails from Stefan in emacs-devel suggest that the
`fontified' property is something to be reserved for jit-lock:

* "I'd rather keep this property as something used internally in
  jit-lock and that nobody else should use or look at (unless they're
  reimplementing some kind of alternative to jit-lock)."

  (2006-03-19, subject "Suboptimal documentation of and handling of
  the 'fontified textproperty")

* "`fontified' is a jit-lock thing, so don't expect to be able to use
  it to solve font-lock problems."

  (2007-03-23, subject "how to prevent font-lock from messing with a
  portion of text?")

If property `fontified' (and not just its `defer' value) is to be
reserved for jit-lock and not intended for general use, shouldn't this
be mentioned in the doc? It would help if the doc were clarified to
explain a bit more about this: what property `fontified' is for and
how it is used (use cases etc.). 

On the other hand, if property `fontified' is something truly
internal, then perhaps it should not be documented at all?  As it
stands now, the doc for this property is hardly intelligible
(confusing, at the least), and the status (internal or not) seems
problematic.

See also node Auto Faces.



In GNU Emacs 22.1.50.1 (i386-mingw-nt5.1.2600)
 of 2007-05-22 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'