Terminology in multi-tty primitives

Terminology in multi-tty primitives

[Eli Zaretskii]

The terminology used by the multi-tty primitives is in its current
state very irregular, to the degree that IMO it hampers understanding
and promotes confusion.  Examples:

 . Sometimes we use "tty", as in `suspend-tty' and
   `make-frame-on-tty', and sometimes "terminal", as in
   `delete-terminal'.

 . `terminal-name' returns the name of the _terminal_device_, such as
   "/dev/tty", while a terminal object itself does not really have a
   name.

 . `get-device-terminal' accepts not only a device name (like
   "/dev/tty" or "foo:0.0"), as its name might suggest, but also a
   frame or a terminal.

 . Doc strings of several functions use the term "terminal id", but
   the functions accept a _terminal_object_, not an ID.  Since a
   terminal has an integer ID associated with it
   (cf. `get-device-terminal's return value), a user could easily be
   confused to think that we mean that integer identifier.

Are we OK with these inconsistencies?  If it's just me, I'm willing to
leave this alone and just document the status quo.  Otherwise, this is
our last chance to fix this mess before it is codified and frozen
forever.

Re: Terminology in multi-tty primitives

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

>  . Sometimes we use "tty", as in `suspend-tty' and
>    `make-frame-on-tty', and sometimes "terminal", as in
>    `delete-terminal'.

Here, `terminal' is a catch-all term for an input/output device,
including both ttys (text-only terminals) and X/Win32-win/Nextstep
(graphical terminals).  In contrast, tty should always refer to
text-only terminals.

>  . Doc strings of several functions use the term "terminal id", but
>    the functions accept a _terminal_object_, not an ID.  Since a
>    terminal has an integer ID associated with it
>    (cf. `get-device-terminal's return value), a user could easily be
>    confused to think that we mean that integer identifier.

Those doc strings should be corrected.

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Chong Yidong <cyd@stupidchicken.com>
> Cc: emacs-devel@gnu.org
> Date: Sat, 27 Dec 2008 20:00:31 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >  . Sometimes we use "tty", as in `suspend-tty' and
> >    `make-frame-on-tty', and sometimes "terminal", as in
> >    `delete-terminal'.
> 
> Here, `terminal' is a catch-all term for an input/output device,
> including both ttys (text-only terminals) and X/Win32-win/Nextstep
> (graphical terminals).  In contrast, tty should always refer to
> text-only terminals.

But there's no delete-tty or suspend-terminal.

Re: Terminology in multi-tty primitives

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

>> Here, `terminal' is a catch-all term for an input/output device,
>> including both ttys (text-only terminals) and X/Win32-win/Nextstep
>> (graphical terminals).  In contrast, tty should always refer to
>> text-only terminals.
>
> But there's no delete-tty or suspend-terminal.

That seems consistent to me.  The delete-terminal function does
something useful on both text and graphical terminals: for ttys, it
returns control of the tty to the shell; on X, it closes the X
connection.  On the other hand, suspending only makes sense for
text-only terminals: it is used to temporarily return control to the
shell.  There is no analogous operation on graphical displays.  Thus, we
provide suspend-tty rather than suspend-terminal.

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Chong Yidong <cyd@stupidchicken.com>
> Cc: emacs-devel@gnu.org
> Date: Sat, 27 Dec 2008 23:28:59 -0500
> 
> > But there's no delete-tty or suspend-terminal.
> 
> That seems consistent to me.  The delete-terminal function does
> something useful on both text and graphical terminals: for ttys, it
> returns control of the tty to the shell; on X, it closes the X
> connection.  On the other hand, suspending only makes sense for
> text-only terminals: it is used to temporarily return control to the
> shell.  There is no analogous operation on graphical displays.  Thus, we
> provide suspend-tty rather than suspend-terminal.

I think you are wrong about suspend making no sense on GUI terminals:
we have (in Emacs 23) suspend-frame that does work on GUI.

Anyway, the examples I gave were just that: examples.  Here's another
example: we have make-frame-on-display, make-frame-on-tty, and
make-terminal-frame; and then we have make-frame that can do all of
the above.  IMO, it's terribly confusing.

But again, maybe I'm the only one who is confused.  My confusion is
exasperated by the fact that I cannot find any useful methodical way
to describe all these functions with partially overlapping
functionality in the ELisp manual.  Suggestions welcome...

Re: Terminology in multi-tty primitives

[Juanma Barranquero]

On Sun, Dec 28, 2008 at 20:18, Eli Zaretskii <eliz@gnu.org> wrote:

> Here's another
> example: we have make-frame-on-display, make-frame-on-tty, and
> make-terminal-frame; and then we have make-frame that can do all of
> the above.  IMO, it's terribly confusing.
>
> But again, maybe I'm the only one who is confused.

No. I find the make-frame-* multiplicity confusing, too (and the
terminal/tty stuff, but I mostly don't deal with it).

    Juanma

Re: Terminology in multi-tty primitives

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

> I think you are wrong about suspend making no sense on GUI terminals:
> we have (in Emacs 23) suspend-frame that does work on GUI.

Since GUI terminals are basically a connection to a graphical display,
it doesn't (IMHO) make sense to talk about "suspending" the terminal.
As long as the display connection is open, you can minimize/iconify
frames on a GUI terminal individually.  In contrast, suspending a text
terminal actually does cause Emacs to relinquish control of the tty, and
this operation acts on all frames on that terminal.

> Anyway, the examples I gave were just that: examples.  Here's another
> example: we have make-frame-on-display, make-frame-on-tty, and
> make-terminal-frame; and then we have make-frame that can do all of
> the above.  IMO, it's terribly confusing.

make-terminal-frame should probably be renamed.  This is an internal
function that is not useful except when called from faces.el anyway.
Maybe we should call it internal-make-tty-frame.

> But again, maybe I'm the only one who is confused.  My confusion is
> exasperated by the fact that I cannot find any useful methodical way
> to describe all these functions with partially overlapping
> functionality in the ELisp manual.  Suggestions welcome...

As far as frame creation goes, there is just one primary Elisp interface
for making frames: the function `make-frame'.  The frame parameters
passed to `make-frame' determine where the frame appears.  The commands
`make-frame-on-display' and `make-frame-on-tty' exist just for
convenience: their purpose is to allow the user to interactively specify
a display or tty name to `make-frame', using the minibuffer.  Internal
functions, such as x-create-frame-with-faces and
tty-create-frame-with-faces, should not be documented in the Elisp
manual.

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Chong Yidong <cyd@stupidchicken.com>
> Cc: emacs-devel@gnu.org
> Date: Mon, 29 Dec 2008 00:31:09 -0500
> 
> > But again, maybe I'm the only one who is confused.  My confusion is
> > exasperated by the fact that I cannot find any useful methodical way
> > to describe all these functions with partially overlapping
> > functionality in the ELisp manual.  Suggestions welcome...
> 
> As far as frame creation goes, there is just one primary Elisp interface
> for making frames: the function `make-frame'.  The frame parameters
> passed to `make-frame' determine where the frame appears.  The commands
> `make-frame-on-display' and `make-frame-on-tty' exist just for
> convenience: their purpose is to allow the user to interactively specify
> a display or tty name to `make-frame', using the minibuffer.  Internal
> functions, such as x-create-frame-with-faces and
> tty-create-frame-with-faces, should not be documented in the Elisp
> manual.

Thanks, but what I'm trying to do is arrange the new multi-tty
functions into some logical order of a few sections.  These are not
limited to frame creation functions, see the corresponding portion of
etc/NEWS.

Maybe I should just stop trying to describe them together, and instead
put every function where it belongs elsewhere in the manual...

Re: Terminology in multi-tty primitives

[Richard M Stallman]

    I think you are wrong about suspend making no sense on GUI terminals:
    we have (in Emacs 23) suspend-frame that does work on GUI.

It does this by lumping together various different operations.
Really it is just a way of trying to make C-z do something meaningful
on window systems where suspending Emacs is not useful.
It is a useful command, but sheds no light on how to conceptualize the
interfaces at the Lisp level.

    Anyway, the examples I gave were just that: examples.  Here's another
    example: we have make-frame-on-display, make-frame-on-tty, and
    make-terminal-frame; and then we have make-frame that can do all of
    the above.  IMO, it's terribly confusing.

Would you like to propose a change for these, which people could consider?

Re: Terminology in multi-tty primitives

[Stephen J. Turnbull]

Richard M Stallman writes:

 >     I think you are wrong about suspend making no sense on GUI terminals:
 >     we have (in Emacs 23) suspend-frame that does work on GUI.
 > 
 > It does this by lumping together various different operations.
 > Really it is just a way of trying to make C-z do something meaningful
 > on window systems where suspending Emacs is not useful.
 > It is a useful command, but sheds no light on how to conceptualize the
 > interfaces at the Lisp level.

I used to agree with you, but The Kids These Days (ie, those who have
grown up with WIMPy interfaces) think of a window as a (foreground)
process.  If the window goes away, the process stops.  I think that is
well-based in psychology.  If Eli (the MS-DOS Ambassador to Emacs!) 
finds commonality there, there's *something* in common there.

In particular, on a GUI the difference between a kill -STOP'ed emacs
and one with no visible windows is hardly important to the user, who
must do something unusual to resurrect it.  So the "withdraw frame"
function (which happens to be called `suspend-frame') just keeps
withdrawing frames, and when the last one is withdrawn, emacs goes to
sleep.  On a X11-style GUI, this requires no additional work: no
window, no events, no Maya == Nirvana.  On a TTY, you need to suspend
Emacs to achieve enlightenment.  No big difference from the user's POV.

 >     Anyway, the examples I gave were just that: examples.  Here's another
 >     example: we have make-frame-on-display, make-frame-on-tty, and
 >     make-terminal-frame; and then we have make-frame that can do all of
 >     the above.  IMO, it's terribly confusing.
 > 
 > Would you like to propose a change for these, which people could consider?

The semantics are a bit delicate, but if you have/create a notion of
"current-terminal", which is the terminal from which input was last
received, then in practice most frames are created on that terminal,
and most of the rest have an implicit notion of "my terminal" (eg, an
emacsclient -nw process will use its controlling tty).  So give
make-frame a terminal parameter, and (make-frame) will use the current
terminal as default.  The general form will be

    (make-frame '((terminal DESCRIPTOR)
                  (terminal-type TYPE)))

where if 'terminal-type is absent, `make-frame' uses an heuristic to
guess it.  In particular, there should be a way to discriminate
between a human-oriented descriptor and an unambiguous internal one.

It seems to me that humans who know what they want will invariably use
a string descriptor, such as ":0" or "CON:" or "/dev/tty3".  So make
the internal type of terminals something else (the small integer
indexing a table of connections would do fine).  This internal type is
what `frame-terminal' (takes a frame argument), `get-terminal' (takes
a string and optional type argument, implements the guessing algorithm
used above, and calls `make-terminal' if an appropriate terminal
connection doesn't exist yet), and `make-terminal' (the more-or-less
internal function that does the heavy lifting) return.  Then the
general `make-frame' call above would be precisely equivalent to

    (make-frame '((terminal (get-terminal DESCRIPTOR TYPE))))

when DESCRIPTOR is a string.  Use of the internal type for DESCRIPTOR
in `get-terminal' should be an error.

Personally, I see no need whatsoever for `make-frame-on-...'
variants.  If they can't be removed for hysterical raisins, then at
least they can be deprecated in the documentation.

Re: Terminology in multi-tty primitives

[Richard M Stallman]

    The semantics are a bit delicate, but if you have/create a notion of
    "current-terminal", which is the terminal from which input was last
    received, then in practice most frames are created on that terminal,
    and most of the rest have an implicit notion of "my terminal" (eg, an
    emacsclient -nw process will use its controlling tty).  So give
    make-frame a terminal parameter, and (make-frame) will use the current
    terminal as default.  The general form will be

	(make-frame '((terminal DESCRIPTOR)
		      (terminal-type TYPE)))

I think this is not very different from the current situation, as
regards Lisp calls.  The reason for make-frame-on-display and
make-frame-on-tty is for invocation with M-x, where you need to
specify the terminal with a string.

These commands could be merged by using a heuristic to
tell whether the argument is a tty device or an X server.

Re: Terminology in multi-tty primitives

[Stefan Monnier]

> 	(make-frame '((terminal DESCRIPTOR)
> 		      (terminal-type TYPE)))

> I think this is not very different from the current situation, as
> regards Lisp calls.  The reason for make-frame-on-display and
> make-frame-on-tty is for invocation with M-x, where you need to
> specify the terminal with a string.

> These commands could be merged by using a heuristic to
> tell whether the argument is a tty device or an X server.

I don't think it's important to merge them.  More important is to make
it clear why they exist.  E.g. by marking them as "not for use from
Elisp" and/or by documenting which `make-frame' call is equivalent when
called from Elisp.


        Stefan

Re: Terminology in multi-tty primitives

[Dan Nicolaescu]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

  > > 	(make-frame '((terminal DESCRIPTOR)
  > > 		      (terminal-type TYPE)))
  > 
  > > I think this is not very different from the current situation, as
  > > regards Lisp calls.  The reason for make-frame-on-display and
  > > make-frame-on-tty is for invocation with M-x, where you need to
  > > specify the terminal with a string.
  > 
  > > These commands could be merged by using a heuristic to
  > > tell whether the argument is a tty device or an X server.
  > 
  > I don't think it's important to merge them.  More important is to make
  > it clear why they exist.  E.g. by marking them as "not for use from
  > Elisp" and/or by documenting which `make-frame' call is equivalent when
  > called from Elisp.

BTW is `make-frame-on-tty' useful as an interactive function?  What
would the use-case be for that?  I'd say: drop the interactive spec for it...

Re: Terminology in multi-tty primitives

[Stefan Monnier]

>> > 	(make-frame '((terminal DESCRIPTOR)
>> > 		      (terminal-type TYPE)))
>> 
>> > I think this is not very different from the current situation, as
>> > regards Lisp calls.  The reason for make-frame-on-display and
>> > make-frame-on-tty is for invocation with M-x, where you need to
>> > specify the terminal with a string.
>> 
>> > These commands could be merged by using a heuristic to
>> > tell whether the argument is a tty device or an X server.
>> 
>> I don't think it's important to merge them.  More important is to make
>> it clear why they exist.  E.g. by marking them as "not for use from
>> Elisp" and/or by documenting which `make-frame' call is equivalent when
>> called from Elisp.

> BTW is `make-frame-on-tty' useful as an interactive function?  What
> would the use-case be for that?  I'd say: drop the interactive spec for it...

We could/should just get rid of it, actually.
BTW, what's up with the test (eq window-system 'pc) in
make-frame-on-tty?  Does it really do something useful?


        Stefan

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: rms@gnu.org,  cyd@stupidchicken.com,  "Stephen J. Turnbull" <stephen@xemacs.org>,  eliz@gnu.org,  emacs-devel@gnu.org
> Date: Tue, 30 Dec 2008 22:20:41 -0500
> 
> BTW, what's up with the test (eq window-system 'pc) in
> make-frame-on-tty?  Does it really do something useful?

Yes: it makes the function work on MS-DOS.

Re: Terminology in multi-tty primitives

[Stefan Monnier]

>> BTW, what's up with the test (eq window-system 'pc) in
>> make-frame-on-tty?  Does it really do something useful?

> Yes: it makes the function work on MS-DOS.

You mean the MS-DOS port supports multiple "tty"s?


        Stefan

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: dann@ics.uci.edu,  rms@gnu.org,  cyd@stupidchicken.com,  stephen@xemacs.org,  emacs-devel@gnu.org
> Date: Wed, 31 Dec 2008 01:25:15 -0500
> 
> >> BTW, what's up with the test (eq window-system 'pc) in
> >> make-frame-on-tty?  Does it really do something useful?
> 
> > Yes: it makes the function work on MS-DOS.
> 
> You mean the MS-DOS port supports multiple "tty"s?

Yes, in the sense that all the APIs introduced by multi-tty do work in
the MS-DOS port if they make sense on DOS.

For example, make-frame-on-tty does make sense on MS-DOS when its
first arg is "/dev/tty" or "CON", so I didn't want it to fail just
because it assumed that on a tty, the value of window-system _must_ be
nil.

Re: Terminology in multi-tty primitives

[Dan Nicolaescu]

Eli Zaretskii <eliz@gnu.org> writes:

  > > From: Stefan Monnier <monnier@iro.umontreal.ca>
  > > Cc: dann@ics.uci.edu,  rms@gnu.org,  cyd@stupidchicken.com,  stephen@xemacs.org,  emacs-devel@gnu.org
  > > Date: Wed, 31 Dec 2008 01:25:15 -0500
  > > 
  > > >> BTW, what's up with the test (eq window-system 'pc) in
  > > >> make-frame-on-tty?  Does it really do something useful?
  > > 
  > > > Yes: it makes the function work on MS-DOS.
  > > 
  > > You mean the MS-DOS port supports multiple "tty"s?
  > 
  > Yes, in the sense that all the APIs introduced by multi-tty do work in
  > the MS-DOS port if they make sense on DOS.
  > 
  > For example, make-frame-on-tty does make sense on MS-DOS when its
  > first arg is "/dev/tty" or "CON", so I didn't want it to fail just
  > because it assumed that on a tty, the value of window-system _must_ be
  > nil.

Then it would be better to just push the test inside the `window-system'
form, rather that duplicate the whole call.  But IMHO make-frame-on-tty
is not very useful in general, and we would be better off without it,
there's a single user (in server.el) in the tree...

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> Date: Wed, 31 Dec 2008 13:39:28 -0800 (PST)
> From: Dan Nicolaescu <dann@ics.uci.edu>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, rms@gnu.org,
>         cyd@stupidchicken.com, stephen@xemacs.org, emacs-devel@gnu.org
> 
>   > For example, make-frame-on-tty does make sense on MS-DOS when its
>   > first arg is "/dev/tty" or "CON", so I didn't want it to fail just
>   > because it assumed that on a tty, the value of window-system _must_ be
>   > nil.
> 
> Then it would be better to just push the test inside the `window-system'
> form, rather that duplicate the whole call.

I don't mind making that change.

> there's a single user (in server.el) in the tree...

But that's true for many (most?) of the multi-tty features, isn't it?

Re: Terminology in multi-tty primitives

[Dan Nicolaescu]

Eli Zaretskii <eliz@gnu.org> writes:

  > > Date: Wed, 31 Dec 2008 13:39:28 -0800 (PST)
  > > From: Dan Nicolaescu <dann@ics.uci.edu>
  > > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, rms@gnu.org,
  > >         cyd@stupidchicken.com, stephen@xemacs.org, emacs-devel@gnu.org
  > > 
  > >   > For example, make-frame-on-tty does make sense on MS-DOS when its
  > >   > first arg is "/dev/tty" or "CON", so I didn't want it to fail just
  > >   > because it assumed that on a tty, the value of window-system _must_ be
  > >   > nil.
  > > 
  > > Then it would be better to just push the test inside the `window-system'
  > > form, rather that duplicate the whole call.
  > 
  > I don't mind making that change.
  > 
  > > there's a single user (in server.el) in the tree...
  > 
  > But that's true for many (most?) of the multi-tty features, isn't it?

Examples please.  If that's indeed that case, then they should get
similar treatment.

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> Date: Wed, 31 Dec 2008 13:55:27 -0800 (PST)
> From: Dan Nicolaescu <dann@ics.uci.edu>
> Cc: monnier@iro.umontreal.ca, rms@gnu.org, cyd@stupidchicken.com,
>         stephen@xemacs.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
>   > > there's a single user (in server.el) in the tree...
>   > 
>   > But that's true for many (most?) of the multi-tty features, isn't it?
> 
> Examples please.

suspend-tty, resume-tty, delete-terminal.

Re: Terminology in multi-tty primitives

[Dan Nicolaescu]

Eli Zaretskii <eliz@gnu.org> writes:

  > > Date: Wed, 31 Dec 2008 13:55:27 -0800 (PST)
  > > From: Dan Nicolaescu <dann@ics.uci.edu>
  > > Cc: monnier@iro.umontreal.ca, rms@gnu.org, cyd@stupidchicken.com,
  > >         stephen@xemacs.org, emacs-devel@gnu.org
  > > 
  > > Eli Zaretskii <eliz@gnu.org> writes:
  > > 
  > >   > > there's a single user (in server.el) in the tree...
  > >   > 
  > >   > But that's true for many (most?) of the multi-tty features, isn't it?
  > > 
  > > Examples please.
  > 
  > suspend-tty, resume-tty, delete-terminal.

Not really similar, these are C functions used in elisp.  They have much
better defined semantics.
make-frame-on-tty is not something that can be really used, and it's
just a simple wrapper for make-frame.

Re: Terminology in multi-tty primitives

[Richard M Stallman]

    > I think this is not very different from the current situation, as
    > regards Lisp calls.  The reason for make-frame-on-display and
    > make-frame-on-tty is for invocation with M-x, where you need to
    > specify the terminal with a string.

    > These commands could be merged by using a heuristic to
    > tell whether the argument is a tty device or an X server.

    I don't think it's important to merge them.  More important is to make
    it clear why they exist.

It is not necessary to merge them, but it seems like a simplification.

make-frame-on-tty is not currently mentioned in the Emacs Manual.
Supposing we added it, that would add to the complexity.  If instead
we merge the two commands, that would require only small changes in
the existing documentation of make-frame-on-display.

    BTW is `make-frame-on-tty' useful as an interactive function?  What
    would the use-case be for that?  I'd say: drop the interactive spec for it...

It seems to be a simple wrapper intended for interactive calling.  It
does not provide much simplification for a caller in Lisp.  If it is
not useful for interactive calling, maybe we should delete it.

By the way, why does it need the conditional that tests window-system?
Should the proper handling of window-system be built into `make-frame'
instead?  If it is needed for all frame creation on MSDOG, putting it
in `make-frame' is best because that way it only needs to be done once
and callers are all simpler.

Re: Terminology in multi-tty primitives

[Stefan Monnier]

> It seems to be a simple wrapper intended for interactive calling.  It
> does not provide much simplification for a caller in Lisp.  If it is
> not useful for interactive calling, maybe we should delete it.

That's indeed what I'm thinking: for interactive use, it doesn't seem
tremendously useful (tho I've used it occasionally for debugging
purposes: it allows the use of the multi-tty code without going through
emacsclient and server.el).

> By the way, why does it need the conditional that tests window-system?
> Should the proper handling of window-system be built into `make-frame'
> instead?  If it is needed for all frame creation on MSDOG, putting it
> in `make-frame' is best because that way it only needs to be done once
> and callers are all simpler.

My thought exactly,


        Stefan

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stephen@xemacs.org,  eliz@gnu.org,  cyd@stupidchicken.com,  emacs-devel@gnu.org
> Date: Wed, 31 Dec 2008 12:22:44 -0500
> 
> > By the way, why does it need the conditional that tests window-system?
> > Should the proper handling of window-system be built into `make-frame'
> > instead?  If it is needed for all frame creation on MSDOG, putting it
> > in `make-frame' is best because that way it only needs to be done once
> > and callers are all simpler.
> 
> My thought exactly,

Could you two please explain the details of your thoughts?

The original make-frame-on-tty, before I added the `pc' condition, did
this:

    (make-frame `((window-system . nil) (tty . ,tty) (tty-type . ,type) . ,parameters))))

Now, what do you want to change exactly, and which part do you want to
move to make-frame?

Re: Terminology in multi-tty primitives

[Stefan Monnier]

>> > By the way, why does it need the conditional that tests window-system?
>> > Should the proper handling of window-system be built into `make-frame'
>> > instead?  If it is needed for all frame creation on MSDOG, putting it
>> > in `make-frame' is best because that way it only needs to be done once
>> > and callers are all simpler.
>> My thought exactly,

> Could you two please explain the details of your thoughts?
> The original make-frame-on-tty, before I added the `pc' condition, did
> this:

>     (make-frame `((window-system . nil) (tty . ,tty) (tty-type . ,type) . ,parameters))))

> Now, what do you want to change exactly, and which part do you want to
> move to make-frame?

I think calls to make-frame-on-tty should be replaceable by just

   (make-frame `((tty . ,tty) (tty-type . ,type) . ,parameters))))

I.e. the explicit `tty' parameter should be interpreted by make-frame as
overriding the window-system of the current frame.


        Stefan

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: rms@gnu.org,  stephen@xemacs.org,  cyd@stupidchicken.com,  emacs-devel@gnu.org
> Date: Thu, 01 Jan 2009 12:13:53 -0500
> 
> >     (make-frame `((window-system . nil) (tty . ,tty) (tty-type . ,type) . ,parameters))))
> 
> > Now, what do you want to change exactly, and which part do you want to
> > move to make-frame?
> 
> I think calls to make-frame-on-tty should be replaceable by just
> 
>    (make-frame `((tty . ,tty) (tty-type . ,type) . ,parameters))))
> 
> I.e. the explicit `tty' parameter should be interpreted by make-frame as
> overriding the window-system of the current frame.

I won't object to such a change, but I must say I don't see how that
would be more elegant than the current code in make-frame-on-tty.
Perhaps even less elegant: make-frame-on-tty is a user command, so it
can sustain more ugliness, if user-level considerations justify that.
By contrast, make-frame is a general-purpose infrastructure, and
introducing such conditions into it makes it less general.

Re: Terminology in multi-tty primitives

[Stefan Monnier]

>> I think calls to make-frame-on-tty should be replaceable by just
>> 
>> (make-frame `((tty . ,tty) (tty-type . ,type) . ,parameters))))
>> 
>> I.e. the explicit `tty' parameter should be interpreted by make-frame as
>> overriding the window-system of the current frame.

> I won't object to such a change, but I must say I don't see how that
> would be more elegant than the current code in make-frame-on-tty.
> Perhaps even less elegant: make-frame-on-tty is a user command, so it
> can sustain more ugliness, if user-level considerations justify that.
> By contrast, make-frame is a general-purpose infrastructure, and
> introducing such conditions into it makes it less general.

I kind of agree.

- the user-level command make-frame-on-tty doesn't seem very useful and
  I'd be happy to remove it.

- if we remove it, then we have to replace the only call to it from
  Elisp, which is of course in server.el.
  I guess server.el can't be used under MS-DOS, so the test you added
  wouldn't be needed there anyway, so server.el could just as well use
  (make-frame `((window-system) (tty . ,tty) (tty-type . ,type) . ,parameters))
  so the uglyness is not really crucial in make-frame.

- still, when make-frame is called with an explicit `tty' argument but
  without an explicit `window-system' argument, the right thing to do is
  to give precedence to the `tty' and choose an appropriate
  window-system for it.
 

        Stefan

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: rms@gnu.org,  stephen@xemacs.org,  cyd@stupidchicken.com,  emacs-devel@gnu.org
> Date: Fri, 02 Jan 2009 21:32:11 -0500
> 
> - the user-level command make-frame-on-tty doesn't seem very useful and
>   I'd be happy to remove it.
> 
> - if we remove it, then we have to replace the only call to it from
>   Elisp, which is of course in server.el.
>   I guess server.el can't be used under MS-DOS, so the test you added
>   wouldn't be needed there anyway, so server.el could just as well use
>   (make-frame `((window-system) (tty . ,tty) (tty-type . ,type) . ,parameters))
>   so the uglyness is not really crucial in make-frame.

server.el is indeed not used in the MS-DOS port, so removing
make-frame-on-tty will eliminate the need for that kludge.  (I somehow
had an impression that make-frame-on-tty is used somewhere else, but I
see now that I was dreaming.)

However, are we really that sure users won't want to have an ability
to create frames on other tty's?  By the same token, why do we have
make-frame-on-display? the same reason(s) would be arguments to retain
make-frame-on-tty.

> - still, when make-frame is called with an explicit `tty' argument but
>   without an explicit `window-system' argument, the right thing to do is
>   to give precedence to the `tty' and choose an appropriate
>   window-system for it.

If we don't need this, why introduce it?

Re: Terminology in multi-tty primitives

[Stefan Monnier]

> However, are we really that sure users won't want to have an ability
> to create frames on other tty's?  By the same token, why do we have
> make-frame-on-display? the same reason(s) would be arguments to retain
> make-frame-on-tty.

Not really: 99.99% of the time, ttys are controlled by a shell, or some
other program, so if we use M-x make-frame-on-tty RET we get into
a situation where 2 programs use this tty at the same time, without any
synchronization between them.  I've used it for debug purposes (to
circumvent the server.el and emacsclient code), but it tends to give you
various forms of display corruption, so it's not really appropriate for
a user command.

>> - still, when make-frame is called with an explicit `tty' argument but
>> without an explicit `window-system' argument, the right thing to do is
>> to give precedence to the `tty' and choose an appropriate
>> window-system for it.

> If we don't need this, why introduce it?

It's not crucial indeed.


        Stefan

Re: Terminology in multi-tty primitives

[Chetan Pandya]

--- On Sun, 1/4/09, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> > However, are we really that sure users won't want to have an ability
> > to create frames on other tty's?  By the same token, why do we have
> > make-frame-on-display? the same reason(s) would be arguments to retain
> > make-frame-on-tty.
> 
> Not really: 99.99% of the time, ttys are controlled by a shell, or some
> other program, so if we use M-x make-frame-on-tty RET we get into
> a situation where 2 programs use this tty at the same time, without any
> synchronization between them.  I've used it for debug
> purposes (to circumvent the server.el and emacsclient code), but it
> tends to give you various forms of display corruption, so it's not really
> appropriate for a user command.
> 
> >> - still, when make-frame is called with an explicit `tty' argument but
> >> without an explicit `window-system' argument, the right thing to do is
> >> to give precedence to the `tty' and choose an appropriate window-system for it.
> 
> > If we don't need this, why introduce it?
> 
> It's not crucial indeed.
> 
> 
>         Stefan

On my system I cannot create a tty frame, but isn't there supposed to be the ability to create multiple frames on a terminal?

Would it make sense to fix the problems, if there are any, or just remove the ability to do that, if not?

Chetan

Re: Terminology in multi-tty primitives

[Jason Rumney]

Chetan Pandya wrote:
> On my system I cannot create a tty frame, but isn't there supposed to be the ability to create multiple frames on a terminal?
>   

That is distinct from creating a frame on a different tty. The issue 
here is that creating a frame on a tty that Emacs does not already own 
can lead to corruption, because the process that owns that tty keeps 
drawing to it while Emacs is using it.

Perhaps we should limit the ttys that Emacs will create frames on with 
make-frame-on-tty to ttys that Emacs already owns (either through 
emacsclient, or the tty that emacs -nw was started in). It is true that 
we don't limit displays in the same way, but X displays are designed to 
have multiple applications using them at a time, so we don't have the 
same problem there.

Re: Terminology in multi-tty primitives

[Chetan Pandya]

--- On Sun, 1/4/09, Jason Rumney <jasonr@gnu.org> wrote:

> That is distinct from creating a frame on a different tty. The issue 
> here is that creating a frame on a tty that Emacs does not already own 
> can lead to corruption, because the process that owns that tty keeps 
> drawing to it while Emacs is using it.
> 
> Perhaps we should limit the ttys that Emacs will create frames on with 
> make-frame-on-tty to ttys that Emacs already owns (either through 
> emacsclient, or the tty that emacs -nw was started in). It is true that 
> we don't limit displays in the same way, but X displays are designed to 
> have multiple applications using them at a time, so we don't have the 
> same problem there.

I don't see how the situation needs to be different for emacsclient. If emacsclient is waiting, so can the other process be. Isn't it the user's responsibility to make sure of that?

Re: Terminology in multi-tty primitives

[Richard M Stallman]

    I used to agree with you, but The Kids These Days (ie, those who have
    grown up with WIMPy interfaces) think of a window as a (foreground)
    process.  If the window goes away, the process stops.

But that is generally false.  If you iconify a window, the application
continues working -- you just don't see what it displays.  For
instance, if you iconify a terminal, the processes running in it do
not stop.

    In particular, on a GUI the difference between a kill -STOP'ed emacs
    and one with no visible windows is hardly important to the user, who
    must do something unusual to resurrect it.

To de-iconify the Emacs frame just requires moving the mouse to the
icon, or to the tab in the bar at the bottom of the screen, and
clicking.  I don't think that is unusual.

      So the "withdraw frame"
    function (which happens to be called `suspend-frame') just keeps
    withdrawing frames, and when the last one is withdrawn, emacs goes to
    sleep.

It doesn't go to sleep.  If it was waiting for a command, it continues
waiting and there is no easy way for it to receive one.

Re: Terminology in multi-tty primitives

[Stephen J. Turnbull]

Richard M Stallman writes:

 >     I used to agree with you, but The Kids These Days (ie, those who have
 >     grown up with WIMPy interfaces) think of a window as a (foreground)
 >     process.  If the window goes away, the process stops.
 > 
 > But that is generally false.  For instance, if you iconify a
 > terminal, the processes running in it do not stop.

Sure.  But that's machine-centric thinking.  Here, we're discussing
the user interface.  From the user's point of view, the *user
interaction process* stops, and that is generally all the user cares
about when suspending a process: "Get out of my face so I can do
something else I want to do!!!"  If the process wants to do some
background work, how often would the user object?

I don't care what the interface is called.  But my feeling is that the
primary UI operation here is "withdrawing a frame", and that whether
the process gets STOPed or not is an implementation detail.  For
example, in a terminal-based emacs you could (in theory) do

M-x long-running-process RET
C-z
bg %emacs
# do other work
fg %emacs

to the same effect as iconifying a GUI window.  In fact, a little
magic with keyboard macros and timers or subprocesses could presumably
allow us to write `execute-key-sequence-and-background-emacs', which
GUI-habituated users might prefer to bind to C-z for use in a
terminal-based environment.  (Don't take that entirely seriously, I
haven't thought it through.)

Re: Terminology in multi-tty primitives

[Stefan Monnier]

> I don't care what the interface is called.  But my feeling is that the
> primary UI operation here is "withdrawing a frame", and that whether
> the process gets STOPed or not is an implementation detail.  For
> example, in a terminal-based emacs you could (in theory) do

We all agree.  What you're describing is a command: the "consistent
behavior" is user-level behavior, not Lisp-level behavior.
So we do have the suspend-frame command for that purpose.

But we're here talking about whether such a *function* would make sense
and how.  Since the implementation of the concept of "suspend" is wildly
different in those different cases, the Lisp behavior will be quite
different as well, making it more difficult (and/or less useful) to
unify it.


        Stefan

Re: Terminology in multi-tty primitives

[Stephen J. Turnbull]

Stefan Monnier writes:

 > We all agree.  What you're describing is a command: the "consistent
 > behavior" is user-level behavior, not Lisp-level behavior.
 > So we do have the suspend-frame command for that purpose.
 > 
 > But we're here talking about whether such a *function* would make
 > sense and how.

Huh?  On systems where stopping a process makes sense, `suspend-emacs'
does so.  On other systems, it starts a subshell.

Attaching "suspend emacs" semantics to a (Lisp-level) "withdraw frame"
function will cause nothing but trouble, and I'm very surprised that
this amount of discussion could be generated on such a premise.

As far as I can see, Lisp (in general) has no need-to-know about the
implementation of frames or terminals.  That's entirely the province
of redisplay and (because of the human penchant for imprecision) UI.
The API I sketched has the bare minimum of implementation knowledge:
enough to distinguish ambiguities in interpretation of terminal names.

Re: Terminology in multi-tty primitives

[Chong Yidong]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> I don't care what the interface is called.  But my feeling is that the
> primary UI operation here is "withdrawing a frame", and that whether
> the process gets STOPed or not is an implementation detail.

On a tty, you want to withdraw all the frames in one go, so conceptually
that's equivalent to withdrawing the terminal; on a graphical display,
that's not so useful, and it would be a nuisance if C-z iconfified all
frames instead of just the current frame.  On a graphical display, you
want to withdraw individual frames; on a tty, that's not at all useful,
and it would be a nuisance if C-z acted on single frames.

Re: Terminology in multi-tty primitives

[Stephen J. Turnbull]

Stefan just said we're not talking about UI.  Now you say we are.  I'm
confused....

Chong Yidong writes:

 > On a graphical display, you want to withdraw individual frames; on

Here, I disagree.  Pre-virtual-desktops, I used iconify-emacs a lot.[1]
Now I switch desktops instead.  Different mechanism, very similar user
experience.

 > a tty, that's not at all useful, and it would be a nuisance if C-z
 > acted on single frames.

On a TTY withdrawing a frame is just as useful to me as iconifying one
on a GUI: it uncovers whatever was underneath.  You may not use it
that way, but I do.[2]  What is different is that it is not useful to
*suspend* a whole emacs process on a GUI, while it may be useful on a
TTY (although I'm finding it less and less useful, in fact these days
I only use C-z to freeze emacs when I want to look at it in gdb
... and IIUC that signal is actually caught by gdb, not emacs).


Footnotes: 
[1]  This may be XEmacs-specific; it withdraws all visible frames and
replaces them with a *single* icon.

[2]  To be precise, I use C-x 5 o a lot.  I'd probably use
withdraw-frame on a TTY as often and in the same way as I use
iconify-frame on a GUI, if XEmacs had a more mnemonic way to name
frames.

Re: Terminology in multi-tty primitives

[Richard M Stallman]

     . Sometimes we use "tty", as in `suspend-tty' and
       `make-frame-on-tty', and sometimes "terminal", as in
       `delete-terminal'.

These examples suggest the distinction that `terminal' refers
to any kind of terminal (including X), whereas `tty' implies that
the function applies only to text terminals.

    But there's no delete-tty or suspend-terminal.

Here's how it appears to me.  The function to delete works on any kind
of terminal, so its name says "terminal".  The function to suspend
works only on ttys, so its name says "tty".

I am not sure that those facts are accurate, but if they are, the
names make sense.

So the current usage is consistent.  However, we don't have to
make this distinction.   We could rename `tty' to `terminal'
in these function names, and that would also be consistent.

     . `terminal-name' returns the name of the _terminal_device_, such
       as "/dev/tty", while a terminal object itself does not really
       have a name.

Perhaps `terminal-device' would be a clearer name for that.

     . `get-device-terminal' accepts not only a device name (like
       "/dev/tty" or "foo:0.0"), as its name might suggest, but also a
       frame or a terminal.

It could be called `get-terminal' by analogy with `get-buffer'.

     . Doc strings of several functions use the term "terminal id", but
       the functions accept a _terminal_object_, not an ID.  Since a
       terminal has an integer ID associated with it
       (cf. `get-device-terminal's return value), a user could easily be
       confused to think that we mean that integer identifier.

The term "ID" is misleading here, and should be changed.

In the manual I see

    +  Emacs represents each terminal on which it displays frames as a
    +special @dfn{terminal object} data type, see @ref{Terminal Type}.  The
    +terminal object has a unique integer identifier and the following
    +attributes:

The terminal does have a unique integer identifier, but is this useful
to mention here?  Do users ever use it?  If not, we may as well
leave it unmentioned.

Re: Terminology in multi-tty primitives

[Eli Zaretskii]

> From: Richard M Stallman <rms@gnu.org>
> CC: emacs-devel@gnu.org
> Date: Sun, 28 Dec 2008 12:29:09 -0500
> 
>     +  Emacs represents each terminal on which it displays frames as a
>     +special @dfn{terminal object} data type, see @ref{Terminal Type}.  The
>     +terminal object has a unique integer identifier and the following
>     +attributes:
> 
> The terminal does have a unique integer identifier, but is this useful
> to mention here?  Do users ever use it?

I don't know yet.  It is printed as part of the printed representation
of the terminal object, but other than that, it's hard to know what is
it for.  It's quite possible that even the corresponding member of
struct terminal is unused.  If I won't find any use for it, I will
delete any references to it.  For now, I'm still trying to find my way
back home...

Re: Terminology in multi-tty primitives

[Stefan Monnier]

>      . Sometimes we use "tty", as in `suspend-tty' and
>        `make-frame-on-tty', and sometimes "terminal", as in
>        `delete-terminal'.

> These examples suggest the distinction that `terminal' refers
> to any kind of terminal (including X), whereas `tty' implies that
> the function applies only to text terminals.

>     But there's no delete-tty or suspend-terminal.

> Here's how it appears to me.  The function to delete works on any kind
> of terminal, so its name says "terminal".  The function to suspend
> works only on ttys, so its name says "tty".

> I am not sure that those facts are accurate, but if they are, the
> names make sense.

> So the current usage is consistent.  However, we don't have to
> make this distinction.   We could rename `tty' to `terminal'
> in these function names, and that would also be consistent.

Indeed, we could rename suspend-tty to suspend-terminal.  If we ever
come up with a meaningful behavior for it on non-tty terminals, that
would be a good name.

But I think all the suspend-tty/resume-tty functionality is likely to be
too specific to ttys to be meaningful for non-tty devices.  So we may as
well keep the `tty' in its name.

>      . `terminal-name' returns the name of the _terminal_device_, such
>        as "/dev/tty", while a terminal object itself does not really
>        have a name.
> Perhaps `terminal-device' would be a clearer name for that.

Yes.

>      . `get-device-terminal' accepts not only a device name (like
>        "/dev/tty" or "foo:0.0"), as its name might suggest, but also a
>        frame or a terminal.
> It could be called `get-terminal' by analogy with `get-buffer'.

Indeed, just like get-buffer it accepts as input the output looked for,
in which case it just returns it.

>      . Doc strings of several functions use the term "terminal id", but
>        the functions accept a _terminal_object_, not an ID.  Since a
>        terminal has an integer ID associated with it
>        (cf. `get-device-terminal's return value), a user could easily be
>        confused to think that we mean that integer identifier.
> The term "ID" is misleading here, and should be changed.
> In the manual I see

>     +  Emacs represents each terminal on which it displays frames as a
>     +special @dfn{terminal object} data type, see @ref{Terminal Type}.  The
>     +terminal object has a unique integer identifier and the following
>     +attributes:

> The terminal does have a unique integer identifier, but is this useful
> to mention here?  Do users ever use it?  If not, we may as well
> leave it unmentioned.

The terminal ID should indeed not be mentioned.  In the original
multi-tty code, terminal IDs (small integers) were used all over the
place instead of terminal objects (which were not exported to Elisp).
I changed the code so as to make terminal objects into first class Elisp
objects, which made it possible to get rid of the terminal IDs.
Obviously, I failed to update some of the docstrings.  AFAIK, the
terminal ID is only ever used of by `print' and friends.
We could/should use the terminal's address (in hex) in its place.


        Stefan

Terminology in multi-tty primitives

[Eli Zaretskii]

The terminology used by the multi-tty primitives is in its current
state very irregular, to the degree that IMO it hampers understanding
and promotes confusion.  Examples:

 . Sometimes we use "tty", as in `suspend-tty' and
   `make-frame-on-tty', and sometimes "terminal", as in
   `delete-terminal'.

 . `terminal-name' returns the name of the _terminal_device_, such as
   "/dev/tty", while a terminal object itself does not really have a
   name.

 . Doc strings of several functions use the term "terminal id", but
   the functions accept a _terminal_object_, not an ID.  Since a
   terminal has an integer ID associated with it
   (cf. `get-device-terminal's return value), a user could easily be
   confused to think that we mean that integer identifier.

Are we OK with these inconsistencies?  If it's just me, I'm willing to
leave this alone and just document the status quo.  Otherwise, this is
our last chance to fix the terminology before it is documented and
frozen forever.