Doc extension: document font-lock patterns for font-lock-add-keywords

Doc extension: document font-lock patterns for font-lock-add-keywords

[Kai Großjohann]

Mayer Goldberg <gmayer@cs.bgu.ac.il> pointed out to me that the Emacs
info file does not explain the syntax of the patterns arg for
font-lock-add-keywords.  I tried to describe the most common usage
(leaving all the gory details to the lispref) and have concocted the
following patch.  It also xrefs the relevant documentation.

OK to install?

Kai (not quite sure how to proceed with doc fixes)

cvs server: Diffing man
Index: man/ChangeLog
===================================================================
RCS file: /cvsroot/emacs/emacs/man/ChangeLog,v
retrieving revision 1.186
diff -u -r1.186 ChangeLog
--- man/ChangeLog	17 Jun 2003 14:05:19 -0000	1.186
+++ man/ChangeLog	27 Jun 2003 20:06:31 -0000
@@ -1,3 +1,8 @@
+2003-06-27  Kai Gro^[,A_^[(Bjohann  <kai.grossjohann@gmx.net>
+
+	* display.texi (Font Lock): Explain highlighting patterns for
+	font-lock.
+
 2003-06-17  Kai Gro^[,A_^[(Bjohann  <kai.grossjohann@gmx.net>
 
 	Version 2.0.35 of Tramp released.
Index: man/display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/display.texi,v
retrieving revision 1.68
diff -u -r1.68 display.texi
--- man/display.texi	4 Feb 2003 14:53:27 -0000	1.68
+++ man/display.texi	27 Jun 2003 20:06:34 -0000
@@ -317,6 +317,28 @@
   To remove keywords from the font-lock highlighting patterns, use the
 function @code{font-lock-remove-keywords}.
 
+@cindex font-lock highlighting pattern
+  Normally, the highlighting patterns will have the structure
+@code{(@var{regexp} @var{match} @var{face} @var{override})}.  Here,
+@var{regexp} gives the regular expression to match.  It might use
+subexpressions (@code{\\(...\\)}); @var{match} specifies which of the
+subexpressions are to be highlighted.  Zero means to highlight the match
+of the whole regular expression, positive numbers specify the pair of
+parentheses to highlight.  (The open parentheses are counted left to
+right to give the number.)  @var{face} specifies the face to use; type
+@kbd{M-x list-faces-display @key{RET}} for a list of available faces.
+Finally, @var{override} equals t means to override any previously
+specified fontification; `keep' means to
+highlight only unfontified parts; `prepend' means to merge with
+existing fontification where the new fontification takes precedence;
+and finally, `append' means to merge with existing fontififcation where
+the existing fontification takes precedence.
+
+  Complete documentation on the patterns can be found in the
+documentation for the variable @code{font-lock-keywords}, and also in
+the Emacs Lisp Reference Manual, @xref{Search-based
+Fontification,,elisp}.
+
 @cindex just-in-time (JIT) font-lock
 @cindex background syntax highlighting
   Fontifying large buffers can take a long time.  To avoid large


-- 
~/.signature