Some hi-lock doc

* doc/emacs/display.texi (Highlight Interactively):
Mention hi-lock-auto-select-face.

* lisp/hi-lock.el (hi-lock-auto-select-face, hi-lock-line-face-buffer)
(hi-lock-face-buffer, hi-lock-face-phrase-buffer)
(hi-lock-face-symbol-at-point, hi-lock-read-face-name): Doc tweaks.

* etc/NEWS: Related edits.

5 files changed, 42 insertions, 31 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 2ee669e7da5..1a884452dbe 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,8 @@
 2014-02-07  Glenn Morris  <rgm@gnu.org>
 
+        * display.texi (Highlight Interactively):
+        Mention hi-lock-auto-select-face.
+
         * anti.texi (Antinews): Fix typo.
 
         * ack.texi (Acknowledgments): No longer mention obsolete files.
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d9fd819c219..d53c80acafd 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -928,6 +928,12 @@ highlighting, Hi Lock provides several of its own and these are
 pre-loaded into a list of default values.  While being prompted
 for a face use @kbd{M-n} and @kbd{M-p} to cycle through them.
 
+@vindex hi-lock-auto-select-face
+Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil}
+value causes this command (and other Hi Lock commands that read faces)
+to automatically choose the next face from the default list without
+prompting.
+
 You can use this command multiple times, specifying various regular
 expressions to highlight in different ways.
 
@@ -976,8 +982,8 @@ initial lower-case letters will become case insensitive.
 @findex highlight-symbol-at-point
 @cindex symbol, highlighting
 @cindex highlighting symbol at point
-Highlight the symbol found near point without prompting, using the next
-available face automatically (@code{highlight-symbol-at-point}).
+Highlight the symbol found near point, using the next available face
+(@code{highlight-symbol-at-point}).
 
 @item M-s h w
 @itemx C-x w b
diff --git a/etc/NEWS b/etc/NEWS
index e2dcadb559f..35e673a8076 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -607,13 +607,13 @@ callers to fit the image to a frame other than the selected frame.
 
 ** Hi-Lock
 
-*** New option `hi-lock-auto-select-face'.  When non-nil, hi-lock commands
-will cycle through faces in `hi-lock-face-defaults' without prompting.
++++
+*** New global command `M-s h .' (`highlight-symbol-at-point') highlights
+the symbol found near point.
 
 +++
-*** New global command `M-s h .' (`highlight-symbol-at-point')
-highlights the symbol found near point without prompting,
-using the next face automatically.
+*** New option `hi-lock-auto-select-face'.  When non-nil, hi-lock commands
+will cycle through faces in `hi-lock-face-defaults' without prompting.
 
 ** New Imenu option `imenu-generic-skip-comments-and-strings'.
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 18587c06e31..97fc72e90ed 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,9 @@
 2014-02-07  Glenn Morris  <rgm@gnu.org>
 
+        * hi-lock.el (hi-lock-auto-select-face, hi-lock-line-face-buffer)
+        (hi-lock-face-buffer, hi-lock-face-phrase-buffer)
+        (hi-lock-face-symbol-at-point, hi-lock-read-face-name): Doc tweaks.
+
         * obsolete/iswitchb.el: Move to obsolete/.
         * simple.el (iswitchb-mode): Add manual autoloads to ease transition,
         since obsolete/ is not scanned for autoloads.
diff --git a/lisp/hi-lock.el b/lisp/hi-lock.el
index fb0136f034b..78efd8671c4 100644
--- a/lisp/hi-lock.el
+++ b/lisp/hi-lock.el
@@ -136,9 +136,9 @@ patterns."
 (put 'hi-lock-file-patterns-policy 'risky-local-variable t)
 
 (defcustom hi-lock-auto-select-face nil
-  "Non-nil if highlighting commands should not prompt for face names.
-When non-nil, each hi-lock command will cycle through faces in
-`hi-lock-face-defaults' without prompting."
+  "Non-nil means highlighting commands do not prompt for the face to use.
+Instead, each hi-lock command will cycle through the faces in
+`hi-lock-face-defaults'."
   :type 'boolean
   :version "24.4")
 
@@ -410,9 +410,8 @@ versions before 22 use the following in your init file:
 ;;;###autoload
 (defun hi-lock-line-face-buffer (regexp &optional face)
   "Set face of all lines containing a match of REGEXP to FACE.
-Interactively, prompt for REGEXP then FACE.  Use
-`read-regexp-defaults-function' to customize default
-value(s) of REGEXP.  Use the global history list for FACE.
+Interactively, prompt for REGEXP using `read-regexp', then FACE.
+Use the global history list for FACE.
 
 Use Font lock mode, if enabled, to highlight REGEXP.  Otherwise,
 use overlays for highlighting.  If overlays are used, the
@@ -435,9 +434,8 @@ highlighting will not update as you type."
 ;;;###autoload
 (defun hi-lock-face-buffer (regexp &optional face)
   "Set face of each match of REGEXP to FACE.
-Interactively, prompt for REGEXP then FACE.  Use
-`read-regexp-defaults-function' to customize default
-value(s) of REGEXP.  Use the global history list for FACE.
+Interactively, prompt for REGEXP using `read-regexp', then FACE.
+Use the global history list for FACE.
 
 Use Font lock mode, if enabled, to highlight REGEXP.  Otherwise,
 use overlays for highlighting.  If overlays are used, the
@@ -456,12 +454,12 @@ highlighting will not update as you type."
 ;;;###autoload
 (defun hi-lock-face-phrase-buffer (regexp &optional face)
   "Set face of each match of phrase REGEXP to FACE.
-Interactively, prompt for REGEXP then FACE.  Use
-`read-regexp-defaults-function' to customize default
-value(s) of REGEXP.  Use the global history list for FACE.  When
-called interactively, replace whitespace in user provided regexp
-with arbitrary whitespace and make initial lower-case letters
-case-insensitive before highlighting with `hi-lock-set-pattern'.
+Interactively, prompt for REGEXP using `read-regexp', then FACE.
+Use the global history list for FACE.
+
+When called interactively, replace whitespace in user-provided
+regexp with arbitrary whitespace, and make initial lower-case
+letters case-insensitive, before highlighting with `hi-lock-set-pattern'.
 
 Use Font lock mode, if enabled, to highlight REGEXP.  Otherwise,
 use overlays for highlighting.  If overlays are used, the
@@ -480,14 +478,13 @@ highlighting will not update as you type."
 (defalias 'highlight-symbol-at-point 'hi-lock-face-symbol-at-point)
 ;;;###autoload
 (defun hi-lock-face-symbol-at-point ()
-  "Set face of each match of the symbol at point.
-Use `find-tag-default-as-symbol-regexp' to retrieve the symbol at point.
-Use non-nil `hi-lock-auto-select-face' to retrieve the next face
-from `hi-lock-face-defaults' automatically.
-
-Use Font lock mode, if enabled, to highlight symbol at point.
-Otherwise, use overlays for highlighting.  If overlays are used,
-the highlighting will not update as you type."
+  "Highlight each instance of the symbol at point.
+Uses the next face from `hi-lock-face-defaults' without prompting,
+unless you use a prefix argument.
+Uses `find-tag-default-as-symbol-regexp' to retrieve the symbol at point.
+
+This uses Font lock mode if it is enabled; otherwise it uses overlays,
+in which case the highlighting will not update as you type."
   (interactive)
   (let* ((regexp (hi-lock-regexp-okay
                   (find-tag-default-as-symbol-regexp)))
@@ -663,7 +660,8 @@ not suitable."
 (defun hi-lock-read-face-name ()
   "Return face for interactive highlighting.
 When `hi-lock-auto-select-face' is non-nil, just return the next face.
-Otherwise, read face name from minibuffer with completion and history."
+Otherwise, or with a prefix argument, read a face from the minibuffer
+with completion and history."
   (unless hi-lock-interactive-patterns
     (setq hi-lock--unused-faces hi-lock-face-defaults))
   (let* ((last-used-face