* faces.el (read-face-name): Doc fix.

2 files changed, 22 insertions, 17 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a35b537bdb1..2df7452d5b4 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2013-01-09  Chong Yidong  <cyd@gnu.org>
+
+        * faces.el (read-face-name): Doc fix.
+
 2013-01-09  Glenn Morris  <rgm@gnu.org>
 
         * emacs-lisp/trace.el (trace-function, trace-function-background):
diff --git a/lisp/faces.el b/lisp/faces.el
index 4b89335f4cc..7843aef8d71 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -926,27 +926,28 @@ of the default face.  Value is FACE."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (defun read-face-name (prompt &optional default multiple)
-  "Read a face, defaulting to the face or faces at point.
-If the text at point has the property `read-face-name', that
-overrides the `face' property for determining the default.
+  "Read one or more face names, defaulting to the face(s) at point.
+PROMPT should be a prompt string; it should not end in a space.
 
-PROMPT should be a string that describes what the caller will do
-with the face; it should not end in a space.
+The optional argument DEFAULT specifies the default face name(s)
+to return if the user just types RET.  If its value is non-nil,
+it should be a list of face names (symbols); in that case, the
+default return value is the `car' of DEFAULT (if the argument
+MULTIPLE is non-nil), or DEFAULT (if MULTIPLE is nil).  See below
+for the meaning of MULTIPLE.
 
+If DEFAULT is nil, the list of default face names is taken from
+the `read-face-name' property of the text at point, or, if that
+is nil, from the `face' property of the text at point.
 
 This function uses `completing-read-multiple' with \",\" as the
-separator character, i.e.
-
-
-
-
-
-The optional argument DEFAULT provides the value to display in the
-minibuffer prompt that is returned if the user just types RET
-unless DEFAULT is a string (in which case nil is returned).
-
-If MULTIPLE is non-nil, return a list of faces (possibly only one).
-Otherwise, return a single face."
+separator character.  Thus, the user may enter multiple face
+names, separated by commas.  The optional argument MULTIPLE
+specifies the form of the return value.  If MULTIPLE is non-nil,
+return a list of face names; if the user entered just one face
+name, the return value would be a list of one face name.
+Otherwise, return a single face name; if the user entered more
+than one face name, return only the first one."
   (let ((faceprop (or (get-char-property (point) 'read-face-name)
                       (get-char-property (point) 'face)))
         (aliasfaces nil)