@cindex highlighting by matching
@cindex interactive highlighting
- It is sometimes useful to highlight the strings that match a certain
-regular expression. For example, you might wish to see all the
-references to a certain variable in a program source file, or highlight
-certain parts in a voluminous output of some program, or make certain
-cliches stand out in an article.
+ It is sometimes useful to temporarily highlight text that
+matches a certain regular expression. 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.
@findex hi-lock-mode
Use the @kbd{M-x hi-lock-mode} command to turn on a minor mode that
-allows you to specify regular expressions of the text to be
-highlighted. Hi-lock mode works like Font Lock (@pxref{Font Lock}),
-except that it lets you specify explicitly what parts of text to
-highlight. You control Hi-lock mode with these commands:
+allows you to interactively add and remove regular expressions
+specifying text to be highlighted. Hi Lock mode works like Font Lock
+mode (@pxref{Font Lock}), except that it lets you easily add and
+remove regular expressions while you are editing a buffer. 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.
+
+You control Hi Lock mode with these commands:
@table @kbd
@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w h
@findex highlight-regexp
-Highlight text that matches
-@var{regexp} using face @var{face} (@code{highlight-regexp}).
-By using this command more than once, you can highlight various
-parts of the text in different ways.
+Highlight text that matches @var{regexp} using face @var{face}
+(@code{highlight-regexp}). By using this command more than once, you
+can highlight various parts of the text in different ways. The
+highlighting will remain as long as the buffer is loaded. For
+example, to highlight all occurrences of the word ``whim'' using the
+default face (a yellow background) @kbd{C-x w h whim @key{RET}
+@key{RET}}. Any face can be used for highlighting, Hi Lock provides
+several of its own and these are pre-loaded into a history list. While
+being prompted for a face use @kbd{C-p} and @kbd{C-n} to cycle through
+them.
@item C-x w r @var{regexp} @key{RET}
@kindex C-x w r
@findex unhighlight-regexp
-Unhighlight @var{regexp} (@code{unhighlight-regexp}). You must enter
-one of the regular expressions currently specified for highlighting.
-(You can use completion, or choose from a menu, to enter one of them
-conveniently.)
+Unhighlight @var{regexp} (@code{unhighlight-regexp}).
+When activated from the menu select the expression to unhighlight from
+a list. When activated from the keyboard the most recently added
+expression will be shown. Use @kbd{C-p} to show the next older
+expression and @kbd{C-n} to select the next newer expression. When
+the expression to unhighlight appears press @kbd{@key{RET}} to unhighlight
+it. The expression can also be typed and completion is available.
@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w l
@code{hi-lock-write-interactive-patterns} command.
These patterns will 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 mode is enabled, or whenever you use the @kbd{M-x
hi-lock-find-patterns} command.
@item 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}). The list of pairs is
-found no matter where in the buffer it may be.
+(@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
+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.
This command does nothing if the major mode is a member of the list
@code{hi-lock-exclude-modes}.