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

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

[Drew Adams]

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

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

Please give us a clue what :font is - what forms its value takes.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-06-13 on ODIEONE
Bzr revision: 112978 xfq.free@gmail.com-20130613224333-3yfl8navh3c1vmxy
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS='-O0 -g3' CPPFLAGS='-Ic:/Devel/emacs/include'
 LDFLAGS='-Lc:/Devel/emacs/lib''

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

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

[Drew Adams]

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

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

[Drew Adams]

Also, what about adding face attributes that correspond to each
of the font properties listed in (emacs) `Windows Fonts'?
Node (elisp) `Face Attributes' already makes clear that:

 "Some of these attributes are meaningful only on certain kinds
  of displays.  If your display cannot handle a certain attribute,
  the attribute is ignored."

IOW, what about adding these?

:adstyle
:registry
:spacing
:script
:antialias

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

[Eli Zaretskii]

> Date: Mon, 17 Jun 2013 09:37:56 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> >      (*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?

There's a cross-reference there to "Low-Level Font", which tells you
something about these objects.

> >      or a string.
> 
> What kind of string?  What's the format?

There's a cross-reference there to "Fonts" in the Emacs manual, which
answers that question.

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

See above.

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

What is 'myfont' in this example?

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Mon, 17 Jun 2013 09:37:56 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>> 
>> >      (*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?
>
> There's a cross-reference there to "Low-Level Font", which tells you
> something about these objects.

The documentation here looks OK to me now after the changes, so I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no