bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Drew Adams]

> > > But that doesn't cover future frames, either.  It only affects the
> > > existing GUI frames, per the doc string (and the code, which see).
> >                        ^^^^^^^^^^^^^^^^^^
> >
> > Where are you getting this?  `C-h f set-frame-font' says clearly:
> >
> >    Also, if FRAME is non-nil, alter the user's Customization settings as
> >    though the font-related attributes of the `default' face had been
> >    "set in this session", so that the font is applied to future frames.
> >
> > One of us seems to be sorely missing something. ;-)
> 
> You are missing the previous sentence of the doc string.

No, I was not missing that previous sentence: 

  "If FRAMES is non-nil, it should be a list of frames to act upon,
  or t meaning all graphical frames."

Where does it say that only existing frames should be affected?
It says that `t' means that it affects all graphical frames.  Nothing
limits that to the existing ones.  "All men are created equal" does
not refer only to the men that existed at the time that sentence
was coined.

> I have now made it say clearly that only the existing frames are
> affected.

Too bad.  Anyway I give up.

> > A face, including face `default', is not something that is frame-specific.
> 
> Faces are _always_ frame-specific in Emacs.  That includes the
> 'default' face.  Thus, changing the 'default' face does not imply the
> change affects all frames, let alone future frames.

That's not my understanding.  And if that were the case then it would
be reflected in the doc.  Node (emacs) `Faces' tells you what a face is, 
and it says NOTHING about it being frame-dependent.  Likewise node `Face Attributes', which tells you what a face is in detail, says nothing about
a face definition being frame-dependent.  Likewise node `Defining Faces'.

And in functions etc.  Function `facep' would then require a second arg
FRAME or would implicitly tell you only that the object was a face for,
say, the selected frame.  

And customizing a face (including `default') would affect only a
particular frame.  And `defface' would provide for specifying the
frame(s) to which that particular face applies.

A face is defined independently of any place it might be displayed,
including any frame.

A face _attribute_ can have different values for a given face on
different frames.  That does not mean that the face itself is
different.  And this overriding of a face's default attribute values
is just that: exceptional.  As the doc says:

  Normally, Emacs uses the face specs of each face to automatically
  calculate its attributes on each frame (*note Defining Faces::).  The
  function `set-face-attribute' can override this calculation by directly
  assigning attributes to a face, either on a specific frame or for all
  frames.  This function is mostly intended for internal usage.

A face's default attributes are what apply to newly created frames.
Changing the default font of a face, in particular, should affect new
frames.  And particularly for face `default'.

What's more, the doc says clearly that a `t' value for `set-face-attribute'
parameter FRAME " sets the attributes for all existing frames, as well
as for newly created frames."  Existing and new go together here, and
the same doc says clearly that they go together the same way for all
of the related `set-face-*' functions - including `set-face-font':

  The following commands and functions mostly provide compatibility
  with old versions of Emacs.  They work by calling `set-face-attribute'.
  Values of `t' and `nil' for their FRAME argument are handled just like
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  `set-face-attribute' and `face-attribute'.  The commands read their
  ^^^^^^^^^^^^^^^^^^^^
  arguments using the minibuffer, if called interactively.

Why you would think that `set-face-font' should not do like this doc
says and should be an exception to the rule that `t' affects newly
created frames as well as existing frames, is beyond me.

And even all of the functions that examine face attributes act similarly.
In fact, it is ONLY the new-frame behavior of `t' that is kept in this
case.  The (same) doc says:

  The following functions examine the attributes of a face.  They
  mostly provide compatibility with old versions of Emacs.  If you don't
  specify FRAME, they refer to the selected frame; `t' refers to the
                                                   ^^^^^^^^^^^^^^^^^
  default data for new frames.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

And yes, this includes function `face-font': FRAME = `t' means the
default value, which is what affects new frames.

> The very next bullet is about a different method of changing the font,
> so it's not really relevant to what this first bullet describes.

A different method of doing the same thing: changing the font for
new frames!  ALL of the bullets here describe ways of doing that.

> Anyway, I made the changes that clarify the current behavior.  The
> part that seems to say that Customize settings are changed to affect
> the font change on all future frames does not correspond to what
> actually happens.  This could be a code bug or a documentation bug;
> someone who can decipher the Customize-related code in set-frame-font
> will have to look into this, and fix either the doc string or the code
> as appropriate.  For now, I left that part of the doc string
> unaltered.

Anyway, I give up.  I did my part in filing the bug and in trying to
explain what I think the bug is: the doc is pretty much right in
suggesting that new frames are also affected; the product is wrong in
not respecting that.

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Eli Zaretskii]

> Date: Wed, 21 May 2014 11:03:44 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17532@debbugs.gnu.org
> 
> > > > But that doesn't cover future frames, either.  It only affects the
> > > > existing GUI frames, per the doc string (and the code, which see).
> > >                        ^^^^^^^^^^^^^^^^^^
> > >
> > > Where are you getting this?  `C-h f set-frame-font' says clearly:
> > >
> > >    Also, if FRAME is non-nil, alter the user's Customization settings as
> > >    though the font-related attributes of the `default' face had been
> > >    "set in this session", so that the font is applied to future frames.
> > >
> > > One of us seems to be sorely missing something. ;-)
> > 
> > You are missing the previous sentence of the doc string.
> 
> No, I was not missing that previous sentence: 
> 
>   "If FRAMES is non-nil, it should be a list of frames to act upon,
>   or t meaning all graphical frames."
> 
> Where does it say that only existing frames should be affected?

It says that to me, because it doesn't mention future frames.  Now I
made that clear by saying that explicitly.

> > > A face, including face `default', is not something that is frame-specific.
> > 
> > Faces are _always_ frame-specific in Emacs.  That includes the
> > 'default' face.  Thus, changing the 'default' face does not imply the
> > change affects all frames, let alone future frames.
> 
> That's not my understanding.

Your understanding is wrong.

> A face is defined independently of any place it might be displayed,
> including any frame.
> 
> A face _attribute_ can have different values for a given face on
> different frames.

That's what I meant: the 'font' attribute of the 'default' face can be
different on each frame.

> That does not mean that the face itself is different.

You are playing word games.  I explained above what I meant by saying
"faces are frame-specific".  My point still stands: it is a legitimate
use case to have the default font different on different frames.

> A face's default attributes are what apply to newly created frames.
> Changing the default font of a face, in particular, should affect new
> frames.  And particularly for face `default'.

That's not how Emacs works.  If it did, you wouldn't need
default-frame-alist.

> What's more, the doc says clearly that a `t' value for `set-face-attribute'
> parameter FRAME " sets the attributes for all existing frames, as well
> as for newly created frames."

But set-frame-font doesn't call set-face-attribute with that argument
set to t, it calls set-face-attribute separately for each frame
returned by frame-list.  So only on those frames we modify the font of
the default face, and of course those frames are only those that exist
at the moment of the call.

>   The following commands and functions mostly provide compatibility
>   with old versions of Emacs.  They work by calling `set-face-attribute'.
>   Values of `t' and `nil' for their FRAME argument are handled just like
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>   `set-face-attribute' and `face-attribute'.  The commands read their
>   ^^^^^^^^^^^^^^^^^^^^
>   arguments using the minibuffer, if called interactively.
> 
> Why you would think that `set-face-font' should not do like this doc
> says and should be an exception to the rule that `t' affects newly
> created frames as well as existing frames, is beyond me.

I just read the code, and it tells a different story.

> > The very next bullet is about a different method of changing the font,
> > so it's not really relevant to what this first bullet describes.
> 
> A different method of doing the same thing: changing the font for
> new frames!

That's your interpretation; the text doesn't say that.

> the doc is pretty much right in suggesting that new frames are also
> affected; the product is wrong in not respecting that.

"The product" never did.  In fact, the argument FRAMES appeared only
in Emacs 24.1; before that, you couldn't even set the font for more
than just the selected frame.  I wish it had stayed that way, but
that's me.

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> It says that to me, because it doesn't mention future frames.  Now I
> made that clear by saying that explicitly.

Ok; closing.

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

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Drew Adams]

> Then this is expected behavior: selecting a new font from that menu
> only changes the font for the existing frames, not for the future
> ones.

That's not what the *doc* says.  You don't see that stated anywhere,
do you?

And why should that be the case?  And what happens when you "save this
for future sessions" (node Fonts)?  What good could it do, and what
meaning could it have, to save something that is only for existing
frames (not new frames) in this session?

> > > > The newly displayed buffer's font is not the font you chose using Set
> > > > Default Font.
> > >
> > > I cannot reproduce this with today's trunk: I get the same font as the
> > > one I've chosen from the menu using Set Default Font.
> >
> > I don't. I get the one that I set in `default-frame-alist'.
> 
> As expected.

By you.  Not by what the doc says.

> I think that's what you asked for, by that "-3-" part in the font
> spec.  That's way too small.

Ah yes, that was a "copy-paste" problem.  I meant to use 13, not 3.

The main point about that remains: the font is the one from
`default-frame-alist', not from `Set Default Font'.

> > Anyway, when you use menu item `Set Default Font', it invokes `menu-set-font',
> > which calls `set-frame-font' *non-interactively*, and with `t' as the
> > value for FRAMES.
> 
> But that doesn't cover future frames, either.  It only affects the
> existing GUI frames, per the doc string (and the code, which see).
                       ^^^^^^^^^^^^^^^^^^

Where are you getting this?  `C-h f set-frame-font' says clearly:

   Also, if FRAME is non-nil, alter the user's Customization settings as
   though the font-related attributes of the `default' face had been
   "set in this session", so that the font is applied to future frames.

One of us seems to be sorely missing something. ;-)

(That's a typo, BTW: FRAME here should be FRAMES.)

> > In addition, the doc string for `menu-set-font' says that it makes the
> > font you choose "the default".  It does NOT at all suggest that it changes
> > the font only for the current frame.  Similarly, the menu item itself speaks
> > of "Default".
> 
> "Default font" means the font of the default face, that's all.  Yes,
> that's ambiguous.

A face, including face `default', is not something that is frame-specific.
The doc string of `set-frame-font' clearly mentions face `default'.  This
can only mean that it changes the value of face `default', which if it were
really what happens, would affect also all future frames in the session.

> > > > Note that the doc here includes (emacs) `Fonts'.
> > >
> > > That doesn't seem to imply the font is changed on all frames, either.
> >
> > It says that when you use `Set Default Font' you are changing a user
> > option (although it doesn't tell you which one!).  It suggests that this
> > is for the session generally (it says that for the setting to work also
> > for future sessions you need to save it).
> 
> I don't see how you deduce that.  The text is very simple:
> 
>      * Click on `Set Default Font' in the `Options' menu.  To save this
>        for future sessions, click on `Save Options' in the `Options' menu.
> 
> Unless you are saying that saving the options doesn't make this font
> the default in future sessions, I see nothing wrong or misleading with
> this text (except that the default font is not 12-point, not for many
> years; I will fix that).

See above.  This menu item, in menu **`Options'**, clearly suggests that
you are changing the value (for the session) of a user option.  And that
doc says that you can save this option setting for future sessions.

And when you change the value of a user option (or face) that controls
a default font it affects future frames - whether that be option
`default-frame-alist' or face `default' (or option `special-display-alist'
or `minibuffer-frame-alist'... for such frames.)
 
> > It likens the behavior of `Set Default Font' to modifying `default-frame-
> > alist'.
> 
> No, it doesn't mention default-frame-alist at all.

It most certainly does - the very next bullet!  These bullets are
introduced collectively as "several different ways to specify a different
font".  Different ways to do essentially the same thing.

And they *do* - at least the others do.  They specify the font to use for
the (remainder of) the session.  That includes for all new frames.

I see nothing in the doc that suggests that `Set Default Font' should
be exceptional in this regard, changing the font for only the existing
frames.  You say that, but I see nothing in the doc that supports such
a view.

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Eli Zaretskii]

> Date: Tue, 20 May 2014 14:00:36 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17532@debbugs.gnu.org
> 
> > Then this is expected behavior: selecting a new font from that menu
> > only changes the font for the existing frames, not for the future
> > ones.
> 
> That's not what the *doc* says.  You don't see that stated anywhere,
> do you?

I do.

> And why should that be the case?

Not relevant to the documentation issue.  (Personally, I think that
menu item should have changed the font only on the current frame, but
that's water under the bridge.)

> And what happens when you "save this for future sessions" (node
> Fonts)?

Not relevant to the issue (and IMO explained in the doc).

> What good could it do, and what meaning could it have, to save
> something that is only for existing frames (not new frames) in this
> session?

Fonts are attributes of faces, and faces are always frame-specific.
It is reasonable to give the user a possibility to change the font
only of some frames and not others.

> > > Anyway, when you use menu item `Set Default Font', it invokes `menu-set-font',
> > > which calls `set-frame-font' *non-interactively*, and with `t' as the
> > > value for FRAMES.
> > 
> > But that doesn't cover future frames, either.  It only affects the
> > existing GUI frames, per the doc string (and the code, which see).
>                        ^^^^^^^^^^^^^^^^^^
> 
> Where are you getting this?  `C-h f set-frame-font' says clearly:
> 
>    Also, if FRAME is non-nil, alter the user's Customization settings as
>    though the font-related attributes of the `default' face had been
>    "set in this session", so that the font is applied to future frames.
> 
> One of us seems to be sorely missing something. ;-)

You are missing the previous sentence of the doc string.  I have now
made it say clearly that only the existing frames are affected.

> (That's a typo, BTW: FRAME here should be FRAMES.)

Fixed.

> > > In addition, the doc string for `menu-set-font' says that it makes the
> > > font you choose "the default".  It does NOT at all suggest that it changes
> > > the font only for the current frame.  Similarly, the menu item itself speaks
> > > of "Default".
> > 
> > "Default font" means the font of the default face, that's all.  Yes,
> > that's ambiguous.
> 
> A face, including face `default', is not something that is frame-specific.

Faces are _always_ frame-specific in Emacs.  That includes the
'default' face.  Thus, changing the 'default' face does not imply the
change affects all frames, let alone future frames.

> > > It likens the behavior of `Set Default Font' to modifying `default-frame-
> > > alist'.
> > 
> > No, it doesn't mention default-frame-alist at all.
> 
> It most certainly does - the very next bullet!

The very next bullet is about a different method of changing the font,
so it's not really relevant to what this first bullet describes.

Anyway, I made the changes that clarify the current behavior.  The
part that seems to say that Customize settings are changed to affect
the font change on all future frames does not correspond to what
actually happens.  This could be a code bug or a documentation bug;
someone who can decipher the Customize-related code in set-frame-font
will have to look into this, and fix either the doc string or the code
as appropriate.  For now, I left that part of the doc string
unaltered.

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Drew Adams]

> > emacs -Q
> >
> > M-: (setq default-frame-alist '
> >  ((font . "-outline-Lucida
> >  Console-normal-normal-normal-mono-3-*-*-*-c-*-iso8859-1")))
> >
> > or some other font that is different from the default emacs -Q font.
> >
> > Choose menu item Options > Set Default Font..., and choose yet another
> > font.
> >
> > C-x 4 d RET ; or another command to display another buffer

I should have said:

C-x 5 d RET ; or another command to display another buffer in a new frame
    ^                                                      ^^^^^^^^^^^^^^

You can also try C-x 5 b *Messages*, for instance, to see *Messages* in a new frame.

This is about `default-frame-alist', as it applies to a new frame.

> > The newly displayed buffer's font is not the font you chose using Set
> > Default Font.
> 
> I cannot reproduce this with today's trunk: I get the same font as the
> one I've chosen from the menu using Set Default Font.

I don't. I get the one that I set in `default-frame-alist'.
Except that the size is shrunk *way* down, for some reason (another bug,
presumably).

In the original frame, the font is the one I picked using `Set Default Font'.

100% reproducible, for me, both with a build from 5/17 and with the pretest,
emacs -Q each time.

> > In any case, the doc for `set-frame-font' and the description of `Set
> > Default Font' tell users that the font specified will be used not only
> > for all current frames but also for future frames, and that it will act
> > as the default font from now on.
> 
> I don't see this in the doc string, please show the relevant text.  My
> interpretation of the doc string is that when that function is called
> interactively, it always sets font only of the currently selected
> frame.  To do that for other frames, you need to call the function
> non-interactively to be able to pass it a non-nil last arg.

I guess you could interpret it that way.  To make that clearer, start a
new paragraph for the "When called from Lisp", put a colon after that,
and then list the info for the parameters.

Anyway, when you use menu item `Set Default Font', it invokes `menu-set-font',
which calls `set-frame-font' *non-interactively*, and with `t' as the value
for FRAMES.

In addition, the doc string for `menu-set-font' says that it makes the font
you choose "the default".  It does NOT at all suggest that it changes the
font only for the current frame.  Similarly, the menu item itself speaks of
"Default".

Yes, "default" can mean different things - here especially.  But the most
likely thing that users will think is that they are setting the default 
font for frames for the rest of the session.  If this is not intended to 
be the case (and it is currently not necessarily the case - see above),
the description needs to remove this possible (and natural) interpretation.

> > Note that the doc here includes (emacs) `Fonts'.
> 
> That doesn't seem to imply the font is changed on all frames, either.

It says that when you use `Set Default Font' you are changing a user
option (although it doesn't tell you which one!).  It suggests that this
is for the session generally (it says that for the setting to work also
for future sessions you need to save it).

It likens the behavior of `Set Default Font' to modifying `default-frame-alist'.
It does not say that they are alternative ways to accomplish the same thing
wrt font, but it suggests that they are both ways to set the default font for
your session (as are the other ways listed).

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Eli Zaretskii]

> Date: Tue, 20 May 2014 10:49:13 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17532@debbugs.gnu.org
> 
> > > emacs -Q
> > >
> > > M-: (setq default-frame-alist '
> > >  ((font . "-outline-Lucida
> > >  Console-normal-normal-normal-mono-3-*-*-*-c-*-iso8859-1")))
> > >
> > > or some other font that is different from the default emacs -Q font.
> > >
> > > Choose menu item Options > Set Default Font..., and choose yet another
> > > font.
> > >
> > > C-x 4 d RET ; or another command to display another buffer
> 
> I should have said:
> 
> C-x 5 d RET ; or another command to display another buffer in a new frame
>     ^                                                      ^^^^^^^^^^^^^^
> 
> You can also try C-x 5 b *Messages*, for instance, to see *Messages* in a new frame.
> 
> This is about `default-frame-alist', as it applies to a new frame.

Then this is expected behavior: selecting a new font from that menu
only changes the font for the existing frames, not for the future
ones.

> > > The newly displayed buffer's font is not the font you chose using Set
> > > Default Font.
> > 
> > I cannot reproduce this with today's trunk: I get the same font as the
> > one I've chosen from the menu using Set Default Font.
> 
> I don't. I get the one that I set in `default-frame-alist'.

As expected.

> Except that the size is shrunk *way* down, for some reason (another bug,
> presumably).

I think that's what you asked for, by that "-3-" part in the font
spec.  That's way too small.

> Anyway, when you use menu item `Set Default Font', it invokes `menu-set-font',
> which calls `set-frame-font' *non-interactively*, and with `t' as the value
> for FRAMES.

But that doesn't cover future frames, either.  It only affects the
existing GUI frames, per the doc string (and the code, which see).

> In addition, the doc string for `menu-set-font' says that it makes the font
> you choose "the default".  It does NOT at all suggest that it changes the
> font only for the current frame.  Similarly, the menu item itself speaks of
> "Default".

"Default font" means the font of the default face, that's all.  Yes,
that's ambiguous.

> > > Note that the doc here includes (emacs) `Fonts'.
> > 
> > That doesn't seem to imply the font is changed on all frames, either.
> 
> It says that when you use `Set Default Font' you are changing a user
> option (although it doesn't tell you which one!).  It suggests that this
> is for the session generally (it says that for the setting to work also
> for future sessions you need to save it).

I don't see how you deduce that.  The text is very simple:

  21.8 Fonts
  ==========

  By default, Emacs displays text on graphical displays using a 12-point
  monospace font.  There are several different ways to specify a
  different font:

     * Click on `Set Default Font' in the `Options' menu.  To save this
       for future sessions, click on `Save Options' in the `Options' menu.

Unless you are saying that saving the options doesn't make this font
the default in future sessions, I see nothing wrong or misleading with
this text (except that the default font is not 12-point, not for many
years; I will fix that).

> It likens the behavior of `Set Default Font' to modifying `default-frame-alist'.

No, it doesn't mention default-frame-alist at all.

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Drew Adams]

emacs -Q

M-: (setq default-frame-alist '
 ((font . "-outline-Lucida
 Console-normal-normal-normal-mono-3-*-*-*-c-*-iso8859-1")))

or some other font that is different from the default emacs -Q font.

Choose menu item Options > Set Default Font..., and choose yet another
font.

C-x 4 d RET ; or another command to display another buffer

The newly displayed buffer's font is not the font you chose using Set
Default Font.

Dunno whether the behavior is wrong.  It's maybe good that a users
current value of `default-frame-alist' be respected.  But maybe
`set-frame-font' (called by `menu-set-font', which is Set Default Font)
should change the value of `default-frame-alist' (or maybe not).

In any case, the doc for `set-frame-font' and the description of `Set
Default Font' tell users that the font specified will be used not only
for all current frames but also for future frames, and that it will act
as the default font from now on.

I hesitate to open this can of worms, for fear that you might make some
crazy "improvement" that changes the behavior negatively.  But at least
the doc should reflect the real behavior.  Users should not be led to
expect that the font will affect new frames when it will not do so.

Perhaps the correct description is that it will do that if
`default-frame-alist' is nil.  (Of course then there are other frame
alist options, or at least there were. ;-)).  Whatever the behavior is,
the doc etc. should be updated to reflect it and not lead users astray.

Note that the doc here includes (emacs) `Fonts'.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-05-17 on ODIEONE
Bzr revision: 117119 eggert@cs.ucla.edu-20140517081131-ugu7ociaoec2xk7y
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#17532: 24.4.50; Options > `set-frame-font' does not work as documented

[Eli Zaretskii]

> Date: Mon, 19 May 2014 13:34:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> emacs -Q
> 
> M-: (setq default-frame-alist '
>  ((font . "-outline-Lucida
>  Console-normal-normal-normal-mono-3-*-*-*-c-*-iso8859-1")))
> 
> or some other font that is different from the default emacs -Q font.
> 
> Choose menu item Options > Set Default Font..., and choose yet another
> font.
> 
> C-x 4 d RET ; or another command to display another buffer
> 
> The newly displayed buffer's font is not the font you chose using Set
> Default Font.

I cannot reproduce this with today's trunk: I get the same font as the
one I've chosen from the menu using Set Default Font.

> In any case, the doc for `set-frame-font' and the description of `Set
> Default Font' tell users that the font specified will be used not only
> for all current frames but also for future frames, and that it will act
> as the default font from now on.

I don't see this in the doc string, please show the relevant text.  My
interpretation of the doc string is that when that function is called
interactively, it always sets font only of the currently selected
frame.  To do that for other frames, you need to call the function
non-interactively to be able to pass it a non-nil last arg.

> Note that the doc here includes (emacs) `Fonts'.

That doesn't seem to imply the font is changed on all frames, either.