Subject: bug#75828: [PATCH] Correct make-frame docstring vis-a-vis make_frame.c

From: Ship Mints <[email-masked]>
Date: Sat, 25 Jan 2025 09:56:40 -0500

Sure, I'll use buffer-list / buffer-predicate and beat my make-frame calls
into submission.

In the end, this was a surprise and it took a while to figure out why
make-frame wasn't doing what I asked. I had to read the code for make_frame
to figure this out. That, alone, is a good reason to at least mention it in
the docstring, and will save some other people time.

On Sat, Jan 25, 2025 at 9:47 AM Eli Zaretskii <[email-masked]> wrote:

> > From: Ship Mints <[email-masked]>
> > Date: Sat, 25 Jan 2025 09:12:50 -0500
> >
> > make-frame's docstring says "creates and returns a new frame, displaying
> the current buffer." This is not
> > true if the buffer is considered conventionally hidden.
> >
> > struct frame *
> > make_frame (bool mini_p)
> > ...
> >     Lisp_Object buf = Fcurrent_buffer ();
> >     /* If current buffer is hidden, try to find another one.  */
> >     if (BUFFER_HIDDEN_P (XBUFFER (buf)))
> >       buf = other_buffer_safely (buf);
> >
> > I'd prefer to have an option to be literal and allow users to make a
> frame on a hidden current buffer.
>
> You can have that already via buffer-list and/or buffer-predicate frame
> parameters, no?
>
> > --- a/lisp/frame.el
> > +++ b/lisp/frame.el
> > @@ -915,6 +915,10 @@ x-display-name
> >
> >  (defun make-frame (&optional parameters)
> >    "Return a newly created frame displaying the current buffer.
> > +If the current buffer is hidden (its name starts with a space
> > +character), then another buffer is chosen to display following the
> > +semantics of `other-buffer'.
>
> Thanks, but this is inaccurate: it is incorrect, for example, if
> PARAMETERS include '((minibuffer . only)).
>
> I'm not sure we should reveal those details here.  Hidden buffers are
> handled specially in many places in Emacs, and I don't think we spell
> that out in every doc string.
>
> Stefan, WDYT?
>
> In any case, if we do decide to make this change, the ELisp manual
> should also be changed.
>