bug#53664: 26.3; Doc of the font of a given face

bug#53664: 26.3; Doc of the font of a given face

[Drew Adams]

The Elisp manual doc about the font(s) of a given face is clear, if you
read it carefully and completely.  But it could be a bit more clear, in
particular when it comes to a face having more than one font.  This can
happen if attribute :font is a fontset.  But a face has only one :font
attribute, and by itself the name :font can be a bit misleading.

The description of function `face-font'says that the same face can use
different fonts for different chars, but it starts by talking about "the
font":

  This function returns the name of the font of face FACE.
                                    ^^^^^^^^

  ... the font name used for CHARACTER.
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

That first sentence can mislead.  Maybe say something like "the font of
FACE for a given character, or for all characters if its :font attribute
is not a fontset"?

The description doesn't say anything about fontsets currently.  Maybe it
should, to make the relation clear here.  Maybe we could add something
like this?

  The name of FACE can be different for different chars if the :font
  attribute for FACE is a fontset.

Other parts of the doc about faces:

 ':font'
   The font used to display the face.
   ^^^^^^^^
   Its value should be a font object or a fontset.

It might help to put that info in the first line:

   The font or fontset used to display the face.

The description of `set-face-font' says that it sets the :font
attribute, which is correct, and if you consult the doc for that
attribute you find that the value could be a fontset.  But it might
help if the description of `set-face-font' said something like this:

   This sets the :font attribute of FACE to FONT, which is a font or a
   fontset.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19043
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#53664: 26.3; Doc of the font of a given face

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Mon, 31 Jan 2022 15:57:23 +0000
> 
> The Elisp manual doc about the font(s) of a given face is clear, if you
> read it carefully and completely.  But it could be a bit more clear, in
> particular when it comes to a face having more than one font.

Note: A face always has more than one font: if the user didn't specify
a fontset, Emacs will use the default fontset for characters that
cannot be displayed by the face's font.

> The description of function `face-font'says that the same face can use
> different fonts for different chars, but it starts by talking about "the
> font":
> 
>   This function returns the name of the font of face FACE.
>                                     ^^^^^^^^
> 
>   ... the font name used for CHARACTER.
>       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> That first sentence can mislead.  Maybe say something like "the font of
> FACE for a given character, or for all characters if its :font attribute
> is not a fontset"?

The description of the function in the manual is quite short, and we
expect the readers to read it in its entirety, not just the first
sentence.  It is customary in our documentation to start with
describing the default behavior, and  only go into the details of
non-default one later -- this usually makes the description clearer
and easier to understand for the usual case.

So I didn't make the first sentence fuzzier, but instead fixed the
description of how CHARACTER arg is used (because it was inaccurate).

> The description doesn't say anything about fontsets currently.  Maybe it
> should, to make the relation clear here.  Maybe we could add something
> like this?
> 
>   The name of FACE can be different for different chars if the :font
>   attribute for FACE is a fontset.

That is incorrect: fontsets don't affect face names.  Maybe you meant
FONT instead of FACE, but then this just repeats what the
documentation already says in other words.

> Other parts of the doc about faces:
> 
>  ':font'
>    The font used to display the face.
>    ^^^^^^^^
>    Its value should be a font object or a fontset.
> 
> It might help to put that info in the first line:
> 
>    The font or fontset used to display the face.

I'd rather not go there.  What exactly happens when you specify a
fontset for the :font attribute is complicated, and doesn't really do
what you think it does.  I did add there a note that if the value is a
font, it's for ASCII characters.

> The description of `set-face-font' says that it sets the :font
> attribute, which is correct, and if you consult the doc for that
> attribute you find that the value could be a fontset.  But it might
> help if the description of `set-face-font' said something like this:
> 
>    This sets the :font attribute of FACE to FONT, which is a font or a
>    fontset.

I don't want to advertise this possibility, it wasn't supposed to be
used by applications.

And with that, I'm closing this bug report.