bug#1165: 23.0.60; doc of make-frame-command

bug#1165: 23.0.60; doc of make-frame-command

[Drew Adams]

The doc string of `make-frame-command' (`C-x 5 2') says:
 
"Make a new frame, and select it if the terminal displays only one
frame."
 
The Emacs manual says:
 
"Create a new frame" (node Creating Frames)
 
"Use `C-x 5 2' to create a new frame and switch to it" (node
Non-Window Terminals)
 
The code does this:
 
(if (and window-system (not (eq window-system 'pc)))
    (make-frame)
  (select-frame (make-frame)))
 
1. Why the difference for `pc'?
 
2. What does the doc string mean by "terminal" and "if the terminal
displays only one frame"? If "terminal" refers only to emacs -nw, then
nothing is said about the window-manager case. If "terminal" refers to
both -nw and window mgr cases, then it seems false for the latter -
whether the new frame is selected has nothing to do with whether there
is only one frame.
 
3. Node Creating Frames of the manual should say also that the frame
is selected for a non-window system.
 
4. Somewhere, we should say that the current buffer is what is
displayed (alone) in the new frame. 
 
5. However, we should also mention this apparent exception to #4: If
the current frame is a standalone minibuffer frame, then the buffer
displayed in the new frame is *scratch*. Are there other exceptions?


In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-03 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

bug#1165: 23.0.60; doc of make-frame-command

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 14 Oct 2008 10:42:43 -0700
> Cc: 
> 
> (if (and window-system (not (eq window-system 'pc)))
>     (make-frame)
>   (select-frame (make-frame)))
>  
> 1. Why the difference for `pc'?

`pc' is the value of window-system for the MS-DOS build of Emacs.  The
MS-DOS build behaves like a text terminal, but its window-system has a
non-nil value; thus the difference.

Although correct, that code should actually be rewritten using
display-graphic-p to become cleaner.

> 2. What does the doc string mean by "terminal" and "if the terminal
> displays only one frame"?

It means the text-only terminals, which can only display one frame at
a time.

> If "terminal" refers only to emacs -nw, then nothing is said about
> the window-manager case.

Well, I think it does say something about the windowed terminals: it
says that on those terminals, a new frame is created, but it is not
selected.

bug#1165: 23.0.60; doc of make-frame-command

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 14 Oct 2008 10:42:43 -0700
> Cc: 
> 
> 2. What does the doc string mean by "terminal" and "if the terminal
> displays only one frame"?

Sorry, what I wrote originally was probably unclear.  Here's a better
version:

"Terminal" is any terminal, whether graphics (a.k.a. windowed) or
text-only.  A terminal "that can only display one frame" is a
text-only terminal.

bug#1165: 23.0.60; doc of make-frame-command

[Drew Adams]

> > (if (and window-system (not (eq window-system 'pc)))
> >     (make-frame)
> >   (select-frame (make-frame)))
> >  
> > 1. Why the difference for `pc'?
> 
> `pc' is the value of window-system for the MS-DOS build of Emacs.  The
> MS-DOS build behaves like a text terminal, but its window-system has a
> non-nil value; thus the difference.
> 
> Although correct, that code should actually be rewritten using
> display-graphic-p to become cleaner.
> 
> > 2. What does the doc string mean by "terminal" and "if the terminal
> > displays only one frame"?
> 
> It means the text-only terminals, which can only display one frame at
> a time.

In that case, that's what it should say. There is a difference between (1) a
terminal that _can only_ display one frame at a time and (2) a terminal that is
currently displaying only one frame. The way it is written, it sounds as if that
occurs whenever Emacs (even with a window manager) shows only one frame.

> > If "terminal" refers only to emacs -nw, then nothing is said about
> > the window-manager case.
> 
> Well, I think it does say something about the windowed terminals: it
> says that on those terminals, a new frame is created, but it is not
> selected.

Unless only one frame is displayed. That's what it seems to say.

If the distinction in behavior is really due to emacs -nw versus emacs with a
window manager, then that's what should be said. Saying "if the terminal
displays only one frame" is misleading or, at best, not clear, IMO.

And the manual should be at least as specific about this distinction as the doc
string. In node Creating Frames it says nothing about it.

bug#1165: marked as done (23.0.60; doc of make-frame-command)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 840 bytes --]


Your message dated Wed, 22 Oct 2008 17:11:27 -0400
with message-id <87iqrkbaio.fsf@cyd.mit.edu>
and subject line Re: bug#1165: 23.0.60; doc of make-frame-command
has caused the Emacs bug report #1165,
regarding 23.0.60; doc of make-frame-command
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
1165: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=1165
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3970 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.60; doc of make-frame-command
Date: Tue, 14 Oct 2008 10:42:43 -0700
Message-ID: <001601c92e24$45515bf0$0200a8c0@us.oracle.com>

The doc string of `make-frame-command' (`C-x 5 2') says:
 
"Make a new frame, and select it if the terminal displays only one
frame."
 
The Emacs manual says:
 
"Create a new frame" (node Creating Frames)
 
"Use `C-x 5 2' to create a new frame and switch to it" (node
Non-Window Terminals)
 
The code does this:
 
(if (and window-system (not (eq window-system 'pc)))
    (make-frame)
  (select-frame (make-frame)))
 
1. Why the difference for `pc'?
 
2. What does the doc string mean by "terminal" and "if the terminal
displays only one frame"? If "terminal" refers only to emacs -nw, then
nothing is said about the window-manager case. If "terminal" refers to
both -nw and window mgr cases, then it seems false for the latter -
whether the new frame is selected has nothing to do with whether there
is only one frame.
 
3. Node Creating Frames of the manual should say also that the frame
is selected for a non-window system.
 
4. Somewhere, we should say that the current buffer is what is
displayed (alone) in the new frame. 
 
5. However, we should also mention this apparent exception to #4: If
the current frame is a standalone minibuffer frame, then the buffer
displayed in the new frame is *scratch*. Are there other exceptions?


In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-03 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 




[-- Attachment #3: Type: message/rfc822, Size: 1731 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: Eli Zaretskii <eliz@gnu.org>, Drew Adams <drew.adams@oracle.com>
Cc: 1165-done@emacsbugs.donarmstrong.com
Subject: Re: bug#1165: 23.0.60; doc of make-frame-command
Date: Wed, 22 Oct 2008 17:11:27 -0400
Message-ID: <87iqrkbaio.fsf@cyd.mit.edu>

> > (if (and window-system (not (eq window-system 'pc)))
> >     (make-frame)
> >   (select-frame (make-frame)))
> >  
> > 1. Why the difference for `pc'?
>
> `pc' is the value of window-system for the MS-DOS build of Emacs.  The
> MS-DOS build behaves like a text terminal, but its window-system has a
> non-nil value; thus the difference.
>
> Although correct, that code should actually be rewritten using
> display-graphic-p to become cleaner.

Indeed.  I've changed it to use display-graphic-p.

> > 2. What does the doc string mean by "terminal" and "if the terminal
> > displays only one frame"?
>
> It means the text-only terminals, which can only display one frame at
> a time.

I tweaked the doc-string to make this clearer.