bug#38143: 27.0.50; Say that before-make-frame-hook & after-make-frame-functions are not invoked for the initial frame

[Eli Zaretskii <eliz@gnu.org>]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  martin rudalics <rudalics@gmx.at>,
>   38143@debbugs.gnu.org
> Date: Sun, 05 Dec 2021 04:13:11 +0100
> 
> Óscar Fuentes <ofv@wanadoo.es> writes:
> 
> > 1. The hooks are not run for the initial frame because it is not created
> >    with `make-frame'.
> >
> > 2. Except when Emacs runs as daemon, in that case make-frame is always
> >    used and therefore the hooks are executed.
> >
> > The added text would be something like this:
> >
> >   When Emacs is not executed as a daemon, `make-frame` is not used for
> >   creating the initial frame, therefore the hooks are not invoked on
> >   that case.
> >
> > Or this:
> >
> >   `make-frame` is not used for the frame that is automatically created
> >   before the init file is processed, therefore the hooks are not invoked
> >   for that frame. Please note that when Emacs is executed as a daemon
> >   there is no such frame.
> 
> I've now added something like this to Emacs 29.

Bother:

   (defvar before-make-frame-hook nil
  -  "Functions to run before `make-frame' creates a new frame.")
  +  "Functions to run before `make-frame' creates a new frame.
  +Note that these functions are usually not run for the initial
  +frame, except when the initial frame is created from an Emacs
  +daemon.")

   (defvar after-make-frame-functions nil
     "Functions to run after `make-frame' created a new frame.
   The functions are run with one argument, the newly created
  -frame.")
  +frame.
  +
  +Note that these functions are usually not run for the initial
  +frame, except when the initial frame is created from an Emacs
  +daemon.")

The new text is incorrect -- assuming that by "initial frame" the doc
strings mean what we usually mean by that: the first frame displayed
by a GUI Emacs session (see "Frame Parameters" in the user manual, and
cf. initial-frame-alist).  You can put a breakpoint on Frun_hooks and
on Frun_hook_with_args, run Emacs, and see that both of these hooks
_are_ called during startup.  And the reason is simple: we do create
that "initial frame" via make-frame, see frame-initialize.

Perhaps the bug report was using "initial frame" in another sense: to
allude to the frame we create in temacs, which is a terminal frame,
normally deleted when a GUI session starts, except in a daemon, which
keeps it.  But in that case, these changes will confuse the heck out
of the users who will read them and try to figure out how to use this
information.  We should in that case explain in the doc strings which
"initial frame" we allude to here.