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

[Drew Adams <drew.adams@oracle.com>]

[Resending - forgot to include the bug list in my reply.]

> > 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.

Thanks for working on this so promptly.

> > 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,

You say "also".  In addition to what?  What else can one provide here,
besides a font name?

> which is written in Info as below:
> 
>      When specifying this attribute using `set-face-attribute'

But I am not using `set-face-attribute'.  What then?

This node is about face attributes generally.  I'm specifying them
this way, for instance:

(propertize MYFONT
            'face
            (list :foundry FOUNDRY :family FAMILY :weight WEIGHT
                  :slant SLANT :width WIDTH))

That uses text property `face', specifying certain face attributes,
which this node presumably describes.  And in general it works.

Text property `face' is no doubt not the same thing as a face.
But what about a face attribute?  Doesn't a face attribute apply
to both a face and the `face' text property?

And again, using the attributes with a `face' text property does work
for some of the attributes.  Is it not a bug that it does not work
for all of them?  If not, it is a doc bug that we do not specify
which face attributes you can use with a `face' text property.

>      (*note Attribute Functions::), you may also supply a font spec,

What is a font spec?  Is it something like the XLFD string above?

>      a font entity,

What is a font entity?

>      or a string.

What kind of string?  What's the format?

>      Emacs converts such values to an appropriate font object,

As I mentioned before, "font object" seems to be defined nowhere -
at least not in the node cross-referenced for it.  What is a font
object?

>      and stores that font object as the actual attribute
>      value.

Beyond the doc, there is a real product bug - see #14634.
In particular, attribute :font seems to have *no effect* when you do,
for example, this:

(propertize myfont 'face (list :font myfont))

> > 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.

Yes.

But the problem seems to be greater than Customize.  See above:
attribute :font has no effect in at least some contexts (beyond
Customize).  It's not clear what contexts it actually has the
documented effect.  Is it only for `set-face-attribute'?  That would
mean that it does not apply to contexts such as using text property
`face'.


> === modified file 'doc/lispref/display.texi'

Thanks for the patch, but sorry, but I do not see how it is relevant
to this bug.