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