Doc patch for `fontification-functions': [was: Is there something like `on-display-functions'?]

[Alan Mackenzie <acm@muc.de>]

Hi, Stefan,

On Wed, Jan 27, 2010 at 03:37:33PM +0000, Alan Mackenzie wrote:

> The documentation (elisp manual) and doc string for this are poor.
> They only say what you should use the hook for, not when it's called.
> In particular, they don't say explicitly what happens when font lock
> isn't enabled, or when a different font-lock-support-mode is active.
> I take it the hook is called regardless of these things.

Here's a patch to fix this.  I've also converted some "each function"s
to "the functions [collectively]".  May I commit the patch (with a
proper ChangeLog entry, of course)?



=== modified file 'doc/lispref/display.texi'
*** doc/lispref/display.texi	2010-01-13 08:35:10 +0000
--- doc/lispref/display.texi	2010-01-28 11:22:57 +0000
***************
*** 2654,2676 ****
  
  @defvar fontification-functions
  This variable holds a list of functions that are called by Emacs
! redisplay as needed to assign faces automatically to text in the buffer.
  
  The functions are called in the order listed, with one argument, a
! buffer position @var{pos}.  Each function should attempt to assign faces
! to the text in the current buffer starting at @var{pos}.
  
! Each function should record the faces they assign by setting the
! @code{face} property.  It should also add a non-@code{nil}
! @code{fontified} property for all the text it has assigned faces to.
  That property tells redisplay that faces have been assigned to that text
  already.
  
! It is probably a good idea for each function to do nothing if the
  character after @var{pos} already has a non-@code{nil} @code{fontified}
  property, but this is not required.  If one function overrides the
! assignments made by a previous one, the properties as they are
! after the last function finishes are the ones that really matter.
  
  For efficiency, we recommend writing these functions so that they
  usually assign faces to around 400 to 600 characters at each call.
--- 2654,2678 ----
  
  @defvar fontification-functions
  This variable holds a list of functions that are called by Emacs
! redisplay as needed, just before doing redisplay.  They are called even
! when Font-lock isn't enabled.  When Font-lock is enabled, this variable
! usually holds just one function, @code{jit-lock-function}.
  
  The functions are called in the order listed, with one argument, a
! buffer position @var{pos}.  Collectively they should attempt to assign
! faces to the text in the current buffer starting at @var{pos}.
  
! The functions should record the faces they assign by setting the
! @code{face} property.  They should also add a non-@code{nil}
! @code{fontified} property for all the text they have assigned faces to.
  That property tells redisplay that faces have been assigned to that text
  already.
  
! It is probably a good idea for the functions to do nothing if the
  character after @var{pos} already has a non-@code{nil} @code{fontified}
  property, but this is not required.  If one function overrides the
! assignments made by a previous one, the properties as they are after the
! last function finishes are the ones that really matter.
  
  For efficiency, we recommend writing these functions so that they
  usually assign faces to around 400 to 600 characters at each call.



-- 
Alan Mackenzie (Nuremberg, Germany).