Suboptimal documentation of and handling of the 'fontified text property.

Suboptimal documentation of and handling of the 'fontified text property.

[Alan Mackenzie]

The text property 'fontified is supposed to indicate that the text it is
attached to has valid font-lock faces.  It is defined (in elisp's
text.texi, in a maddeningly imprecise fashion) to have the values nil
and non-nil.

It Would Be Nice for random.el to be able to test this property to see
whether the font-locking is up to date.

However:
(i) jit-lock-mode additionally uses the special value 'defer.

(ii) When no support mode is active, 'fontified doesn't get set.

(iii) When font-lock-mode is disabled, the 'fontified text property
doesn't get cleared.  

(iv) The file replace.el tests explicitly for the value t. 

These things are inconsistent.  To amend this, it seems that 'fontified
should be restricted (in text.texi) to the three values nil, t, and
'defer.

Additionally, the following alternatives suggest themselves:

(i) State that 'fontified is only meaningful when jit-lock is enabled.

(ii) State that 'fontified is only meaningful when (some sort) of
font-lock is enabled, fixing font-\(lock\|core\).el to set and clear the
text property.

(iii) State that 'fontified is meaningful at all times, and set and clear
it when no support-mode is enabled, and clear it totally when font-lock
is disabled.

[Incidentally, ...../progmodes/cperl-mode.el uses the text-property
'lazy-lock to inhibit fontification.  This surely needs fixing.]

I think alternative (iii) is the best one.  Here is a proposed patch for
text.texi which documents this:

2006-03-16  Alan Mackenzie  <acm@muc.de>

	* text.texi (Special Properties): Clarify the definition of
	'fontified.


Index: text.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/text.texi,v
retrieving revision 1.113
diff -c -r1.113 text.texi
*** text.texi	6 Feb 2006 11:55:10 -0000	1.113
--- text.texi	16 Mar 2006 12:15:21 -0000
***************
*** 2994,3002 ****
  
  @item fontified
  @kindex fontified @r{(text property)}
! This property, if non-@code{nil}, says that text in the buffer has
! had faces assigned automatically by a feature such as Font-Lock mode.
! @xref{Auto Faces}.
  
  @item display
  @kindex display @r{(text property)}
--- 2994,3017 ----
  
  @item fontified
  @kindex fontified @r{(text property)}
! This property says whether the text has had faces assigned to it by
! Font Lock mode.  @xref{Auto Faces}.  It takes one of these three
! values---other values are invalid:
! 
! @table @asis
! @item @code{nil}
! Font locking is disabled, or the @code{face} properties on the text,
! if any, are invalid.
! 
! @item The symbol @code{defer}
! This value states that the text's @code{face} properties are invalid
! and marks it for deferred fontification.  It is used only when ``just
! in time'' font locking is enabled.
! 
! @item @code{t}
! The @code{face} properties, or lack of them, on the text are currently
! valid.
! @end table
  
  @item display
  @kindex display @r{(text property)}


-- 
Alan Mackenzie (Munich, Germany)

Re: Suboptimal documentation of and handling of the 'fontified text property.

[Richard Stallman]

    It Would Be Nice for random.el to be able to test this property to see
    whether the font-locking is up to date.

I agree, it would be nice.  However, I don't think we should take the
risk of any substantial changes in the internals of Font Lock now.

Please install your change in the manual, and thanks.

Re: Suboptimal documentation of and handling of the 'fontified text property.

[Stefan Monnier]

> It Would Be Nice for random.el to be able to test this property to see
> whether the font-locking is up to date.

I disagree.  Actuallt I suspect that what is needed instead is a new
function `font-lock-ensure-fontified'.  It could be based on:

(defun ps-print-ensure-fontified (start end)
  (cond ((and (boundp 'jit-lock-mode) (symbol-value 'jit-lock-mode))
	 (ps-jitify start end))
	((and (boundp 'lazy-lock-mode) (symbol-value 'lazy-lock-mode))
	 (ps-lazify start end))))

> (iii) State that 'fontified is meaningful at all times, and set and clear
> it when no support-mode is enabled, and clear it totally when font-lock
> is disabled.

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


        Stefan