Re: Terminology in multi-tty primitives

[Stefan Monnier <monnier@iro.umontreal.ca>]

>      . 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