# HG changeset patch
# User Eli Zaretskii <eliz@gnu.org>
# Date 1134215396 0
# Node ID 9b11091298b7e94c8c7132b5ab0464a860280c00
# Parent  279eecf2a9b708422e7609b2adbd87cf521f96d0
(Highlight Interactively): Include global-hi-lock-mode.  Add miscellaneous
details and elaborations.

diff -r 279eecf2a9b7 -r 9b11091298b7 man/display.texi
--- a/man/display.texi	Sat Dec 10 11:48:21 2005 +0000
+++ b/man/display.texi	Sat Dec 10 11:49:56 2005 +0000
@@ -389,35 +389,48 @@
 @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
@@ -436,7 +449,7 @@
 @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
@@ -444,8 +457,14 @@
 @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}.