Improve documentation of 'set-face-font'

* lisp/faces.el (set-face-font):
* doc/emacs/frames.texi (Fonts):
* doc/lispref/display.texi (Face Attributes)
(Attribute Functions): Clarify and correct the documentation
of set-face-font and related descriptions of font
specifications.  (Bug#14647)

1 files changed, 7 insertions, 4 deletions

diff --git a/lisp/faces.el b/lisp/faces.el
index 75753ecefc9..dc5bcca7609 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -887,10 +887,13 @@ Use `set-face-attribute' for finer control of font weight and slant."
 
 
 (defun set-face-font (face font &optional frame)
-  "Change font-related attributes of FACE to those of FONT (a string).
-The format of the font varies based on the font system in used,
-but it can commonly be an X logical font description (XLFD)
-string, or a simpler XFD string like \"courier:size=10\".
+  "Change font-related attributes of FACE to those of FONT.
+FONT can be a string, a font spec, a font entity, a font object,
+or a fontset.  However, interactively, only strings are accepted.
+The format of the font string specification varies based on the font
+system in use, but it can commonly be an X Logical Font
+Description (XLFD) string, or a simpler string like \"Courier-10\"
+or \"courier:size=10\".
 
 FRAME nil or not specified means change face on all frames.
 This sets the attributes `:family', `:foundry', `:width',