changeset 77357:26dabce82422

(Highlight Interactively): Correct previous change. Clarify doc of hi-lock-find-patterns, and move new features into it.

--- a/man/display.texi	Sat Apr 21 03:29:50 2007 +0000
+++ b/man/display.texi	Sat Apr 21 08:23:55 2007 +0000
@@ -651,15 +651,14 @@
 
 @cindex Hi Lock mode
 @findex hi-lock-mode
-  Hi Lock mode is another minor mode, which highlights text that
-matches your specified regular expressions.  For example, you might
-wish to see all the references to a certain variable in a program
-source file, highlight certain parts in a voluminous output of some
-program, or make certain names stand out in an article.  Use the
-@kbd{M-x hi-lock-mode} command to enable (or disable) Hi Lock mode.
-To enable Hi Lock mode for all buffers, use @kbd{M-x
-global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)} in your
-@file{.emacs} file.
+  Hi Lock mode highlights text that matches regular expressions you
+specify.  For example, you might wish to see all the references to a
+certain variable in a program source file, highlight certain parts in
+a voluminous output of some program, or make certain names stand out
+in an article.  Use the @kbd{M-x hi-lock-mode} command to enable (or
+disable) Hi Lock mode.  To enable Hi Lock mode for all buffers, use
+@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)}
+in your @file{.emacs} file.
 
   Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except
 that you specify explicitly the regular expressions to highlight.  You
@@ -711,33 +710,32 @@
 program.  (This key binding runs the
 @code{hi-lock-write-interactive-patterns} command.)
 
-These patterns may be read the next time you visit the file while
-Hi Lock mode is enabled, or whenever you use the @kbd{M-x
-hi-lock-find-patterns} command. 
-
-Patterns are not read if the buffer's mode is listed in
-@code{hi-lock-exclude-modes}. Patterns are only used if
-@code{hi-lock-file-patterns-policy} is 'ask and the user responds yes
-to a prompt, or if @code{hi-lock-file-patterns-policy} is bound to a
-function and that function returns t. The function is called with the
-patterns as an argument.
+These patterns are extracted from the comments, if appropriate, if you
+invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
+Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).
 
 @item C-x w i
 @kindex C-x w i
 @findex hi-lock-find-patterns
-@vindex hi-lock-exclude-modes
-Re-read regexp/face pairs in the current buffer
-(@code{hi-lock-write-interactive-patterns}).  Users familiar with Font
-Lock keywords might interactively enter patterns
-(@code{highlight-regexp}), write them into the file
-(@code{hi-lock-write-interactive-patterns}), edit them, perhaps
+Extract regexp/face pairs from comments in the current buffer
+(@code{hi-lock-find-patterns}).  Thus, you can enter patterns
+interactively with @code{highlight-regexp}, store them into the file
+with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
 including different faces for different parenthesized parts of the
-match, and finally use this command
-(@code{hi-lock-write-interactive-patterns}) to have Hi Lock highlight
-them.
+match), and finally use this command (@code{hi-lock-find-patterns}) to
+have Hi Lock highlight the edited patterns.
 
-This command does nothing if the current major mode's symbol is a member
-of the list @code{hi-lock-exclude-modes}.
+@vindex hi-lock-file-patterns-policy
+The variable @code{hi-lock-file-patterns-policy} controls whether
+@code{hi-lock-find-patterns} should really do anything.  Its value can
+be @code{nil} (do nothing), @code{t} (extract the patterns),
+@code{ask} (query the user), or a function.  If it is a function,
+@code{hi-lock-find-patterns} calls it with the patterns as argument;
+if the function returns non-@code{nil}, the patterns are used.
+
+@vindex hi-lock-exclude-modes
+Also, @code{hi-lock-find-patterns} does nothing if the current major
+mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
 @end table
 
 @node Fringes