bug#14629: 24.3.50; (elisp) `Face Attributes', :font -> "font object"

[Kenichi Handa]

> From: Drew Adams <drew.adams@oracle.com>
[...]
> The description of face attribute :font is incomprehensible.

> It says that the value should be a "font object".  What is that, you
> ask?  Well, it says to see node `Font Selection' to find out.  But
> that
> node says nothing about a "font object".

I've just committed the attached fix.

> I have no idea what it is, that is, what possible values attribute
> :font
> can have.  I know about the frame parameter `font', whose value is an
> XLFD string (AFAICT).  But I have no idea what :font can be set to.

You can also specify a font name, which is written in Info
as below:

     When specifying this attribute using `set-face-attribute' (*note
     Attribute Functions::), you may also supply a font spec, a font
     entity, or a string.  Emacs converts such values to an appropriate
     font object, and stores that font object as the actual attribute
     value.  If you specify a string, the contents of the string should
     be a font name (*note Fonts: (emacs)Fonts.); if the font name is
     an XLFD containing wildcards, Emacs chooses the first font
     matching those wildcards. 

> Not only that, but if I try to guess from using `M-x customize-face',
> there is no `Font' attribute.  There are only attributes `Font Family'
> and `Font Foundry'.

Ah, perhaps customize-face should be improved.

---
Kenichi Handa
handa@gnu.org

=== modified file 'doc/lispref/display.texi'
--- doc/lispref/display.texi    2013-04-06 07:39:48 +0000
+++ doc/lispref/display.texi    2013-06-17 15:00:04 +0000
@@ -2126,7 +2126,8 @@
 
 @item :font
 The font used to display the face.  Its value should be a font object.
-@xref{Font Selection}, for information about font objects.
+@xref{Low-Level Font}, for information about font objects, font specs,
+and font entities.
 
 When specifying this attribute using @code{set-face-attribute}
 (@pxref{Attribute Functions}), you may also supply a font spec, a font
@@ -3260,7 +3261,9 @@
 properties are intermediate between a font object and a font spec:
 like a font object, and unlike a font spec, it refers to a single,
 specific font.  Unlike a font object, creating a font entity does not
-load the contents of that font into computer memory.
+load the contents of that font into computer memory.  Emacs may open
+multiple font objects of different sizes from a single font entity
+referring to a scalable font.
 
 @defun find-font font-spec &optional frame
 This function returns a font entity that best matches the font spec