Rename `struct device' to `struct terminal'. Rename some terminal-related functions...
[bpt/emacs.git] / README.multi-tty
index 5deb706..f1a0cde 100644 (file)
@@ -9,7 +9,7 @@ Some use cases:
 Emacs is notoriously slow at startup, so most people use another
 editor or emacsclient for quick editing jobs from the console.
 Unfortunately, emacsclient was very awkward to use, because it did not
-support opening a new Emacs frame on the current virtual console.
+support opening a new Emacs frame on the current virtual tty.
 Now, with multi-tty support, it can do that.  (Emacsclient starts up
 faster than vi!)
 
@@ -55,6 +55,7 @@ Kalle Olavi Niemitalo <kon@iki.fi>
 Mark Plaksin <happy@mcplaksin.org>
 Frank Ruell <stoerte@dreamwarrior.net>
 Tom Schutzer-Weissmann <trmsw@yahoo.co.uk>
+Joakim Verona <joakim@verona.se>
 Dan Waber <dwaber@logolalia.com>
 and many others.
 
@@ -85,11 +86,11 @@ major problems have been fixed, only a few minor issues remain.  (It
 still needs to be ported to Windows/Mac/DOS, though.)  Both multiple
 tty device support and simultaneous X and tty frame support works
 fine.  Emacsclient has been extended to support opening new tty and X
-frames.  It has been changed open new Emacs frames by default.
+frames.  It has been changed to open new Emacs frames by default.
 
 The multi-tty branch has been scheduled for inclusion in the next
 major release of Emacs (version 23).  I expect the merge into the
-development trunk to occur sometime during next year (2005), after the
+development trunk to occur sometime during next year (2006), after the
 merge of the Unicode branch.
 
 Tested on GNU/Linux, Solaris 8, FreeBSD and OpenBSD.  Please let me
@@ -140,36 +141,36 @@ Known problems:
          system-dependent source files need to be adapted
          accordingly.  The changes are mostly trivial, so almost
          anyone can help, if only by compiling the branch and
-         reporting the compiler errors.  (It is not worth to do this
-         yet, though.)
+         reporting the compiler errors.
 
 
 HOW TO GET THE BRANCH
 ---------------------
 
-The branch uses GNU Arch (http://www.gnuarch.org) for version control.
+The branch uses Bazaar 1 (http://bazaar.canonical.com) for version control.
 
 Retrieving the latest version of the branch:
 
-       tla register-archive -f http://lorentey.hu/arch/2004/
-       tla get lorentey@elte.hu--2004/emacs--multi-tty <directory>
+       baz register-archive -f http://aszt.inf.elte.hu/~lorentey/mirror/arch/2004
+       baz get lorentey@elte.hu--2004/emacs--multi-tty <directory>
 
-This incantation uses my private archive mirror that is hosted on a
-relatively low-bandwidth site; if you are outside Hungary, you will
-probably want to you use my secondary mirror: (Note that the -f option
-will overwrite the archive location if you have previously registered
-the Hungarian one.)
+This incantation uses an archive mirror that is hosted on a
+high-bandwidth site.  Please note that on average there is a two-hour
+delay for commits to arrive on this mirror.  My primary mirror is on the
+low-bandwidth http://lorentey.hu/ site:
 
-       tla register-archive -f http://aszt.inf.elte.hu/~lorentey/mirror/arch/2004
-       tla get lorentey@elte.hu--2004/emacs--multi-tty <directory>
+       baz register-archive -f http://lorentey.hu/arch/2004/
+       baz get lorentey@elte.hu--2004/emacs--multi-tty <directory>
 
-       http://aszt.inf.elte.hu/~lorentey/mirror/arch/2004
+This is "instantly" updated, but very slow from outside Hungary.
+(By "instantly" I mean as soon as I connect the notebook I work on to
+a network.  It could take days.)
 
 The Arch supermirror provides mirroring services for all public Arch
 repositories.  We have a mirror there, too, if you prefer.
 
-       tla register-archive -f http://mirrors.sourcecontrol.net/lorentey%40elte.hu--2004
-       tla get lorentey@elte.hu--2004/emacs--multi-tty <directory>
+       baz register-archive -f http://mirrors.sourcecontrol.net/lorentey%40elte.hu--2004
+       baz get lorentey@elte.hu--2004/emacs--multi-tty <directory>
 
 My GPG key id is 0FB27A3F; it is available from
 hkp://wwwkeys.eu.pgp.net/, or from my homepage at
@@ -179,16 +180,20 @@ Don't worry if the above checkout takes a few minutes to complete;
 once you have a source tree, updating it to the latest revision will
 be _much_ faster.  Use the following command for the update:
 
-       tla replay
+       baz replay
 
-You can find more information about Arch on http://wiki.gnuarch.org/.
-It's a wonderful source control system, I highly recommend it.
+You can find more information about Bazaar on
+http://bazaar.canonical.com/.  It's a distributed source control
+system that is somewhat less broken than competing projects.
 
-If you don't have tla, the branch has a homepage from which you can
+If you don't have Bazaar, the branch has a homepage from which you can
 download conventional patches against Emacs CVS HEAD:
 
        http://lorentey.hu/project/emacs.html
 
+I suggest you use Bazaar whenever feasible.
+
+
 DEBIAN PACKAGES
 ---------------
 
@@ -244,9 +249,9 @@ finish editing the specified files (C-x #), but delete-frame (C-x 5 0)
 also works.  Of course, you can create frames on more than two tty
 devices.
 
-Creating new frames on the same tty with C-x 5 2 works, and they
-behave the same way as in previous Emacs versions.  If you exit emacs,
-all terminals should be restored to their previous states.
+Creating new frames on the same tty with C-x 5 2 (make-frame-command)
+works, and behaves the same way as in previous Emacs versions.  If you
+exit emacs, all terminals should be restored to their previous states.
 
 This is work in progress, and probably full of bugs.  It is a good
 idea to run emacs from gdb, so that you'll have a live instance to
@@ -344,47 +349,50 @@ NEWS
 
 For the NEWS file:  (Needs much, much work)
 
-** Support for multiple terminal devices has been added.
+** Support for multiple terminal devices and simultaneous graphical
+   and tty frames has been added.  You can test for the presence of
+   this feature in your Lisp code by testing for the `multi-tty'
+   feature.
+
+*** The `window-system' variable has been made frame-local. The new
+    `initial-window-system' variable contains the `window-system'
+    value for the first frame.
 
 *** You can specify a terminal device (`tty' parameter) and a terminal
     type (`tty-type' parameter) to `make-terminal-frame'.
 
-*** You can test for the presence of multiple terminal support by
-    testing for the `multi-tty' feature.
+*** The new function `make-frame-on-tty' allows you to create a new
+    frame on another tty device interactively.
+
+*** The function `make-frame-on-display' now works during a tty
+    session, and `make-frame-on-tty' works during a graphical session.
 
 *** Emacsclient has been extended to support opening a new terminal
     frame. Its behaviour has been changed to open a new Emacs frame by
     default.  Use the -c option to get the old behavior of opening
     files in the currently selected Emacs frame.
 
-*** A make-frame-on-tty function has been added to make it easier to
-    create frames on new terminals.
+*** C-z now invokes `suspend-frame', C-x C-c now invokes
+    `save-buffers-kill-terminal'.
 
 *** New functions: frame-tty-name, frame-tty-type, delete-tty,
-    terminal-local-value, set-terminal-local-value
-
-    terminal-id, terminal-parameters, terminal-parameter,
-    set-terminal-parameter
+    suspend-tty, resume-tty, terminal-id, terminal-parameters,
+    terminal-parameter, set-terminal-parameter,
+    modify-terminal-parameters, environment, let-environment
 
-*** New variables: global-key-translation-map
+*** New variables: local-key-translation-map, local-function-key-map
 
-*** The keymaps key-translation-map and function-key-map are now
-    terminal-local.
+*** The `keyboard-translate-table' variable and the terminal and
+    keyboard coding systems have been made terminal-local.
 
-** Support for simultaneous graphical and terminal frames has been
-   added.
-
-*** The function `make-frame-on-display' now works during a terminal
-    session, and `make-frame-on-tty' works during a graphical session.
-
-*** The `window-system' variable has been made frame-local.
-
-*** The new `initial-window-system' variable contains the
-    `window-system' value for the first frame.
+*** In addition to the global key-translation-map and
+    function-key-map, Emacs has terminal-local
+    local-key-translation-map and local-function-key-map variables,
+    and uses them instead of the global keymaps to set up translations
+    and function key sequences relevant to a specific terminal device.
 
 *** talk.el has been extended for multiple tty support.
 
-
 * * *
 
 (The rest of this file consists of my development notes and as such it
@@ -393,6 +401,30 @@ is probably not very interesting for anyone else.)
 THINGS TO DO
 ------------
 
+** Trouble: `setenv' doesn't actually set environment variables in the
+   Emacs process.  This defeats the purpose of the elaborate
+   `server-with-environment' magic around the `tgetent' call in
+   `init_tty'.  D'oh.
+
+** (Possibly) create hooks in struct device for creating frames on a
+   specific terminal, and eliminate the hackish terminal-related frame
+   parameters (display, tty, tty-type).
+
+       make_terminal_frame
+               create_tty_output
+
+** Decide whether to keep the C implementation of terminal parameters,
+   or revert to the previous, purely Lisp code.  It turned out that
+   local environments do not need terminal parameters after all.
+
+** Move Fsend_string_to_terminal to term.c, and declare get_named_tty
+   as static, removing it from dispextern.h.
+   Move fatal to emacs.c and declare it somewhere.
+
+** Search for `suspend-emacs' references and replace them with
+   `suspend-frame', if necessary.  Ditto for `save-buffers-kill-emacs'
+   vs. `save-buffers-kill-display'.
+
 ** Emacs crashes when a tty frame is resized so that there is no space
    for all its windows.  (Tom Schutzer-Weissmann)
 
@@ -433,11 +465,20 @@ THINGS TO DO
    changed in CVS, and frame.el in multi-tty has not yet been adapted
    for the changes.  (It needs to look at
    default-frame-background-mode.)  (Update: maybe it is fixed now;
-   needs testing.)
+   needs testing.) (Note that the byte compiler has this to say about
+   term/rxvt.el:)
+
+       term/rxvt.el:309:17:Warning: assignment to free variable
+           `default-frame-background-mode'
 
 ** I think `(set-)terminal-local-value' and the terminal parameter
    mechanism should be integrated into a single framework.
 
+   (Update: `(set-)terminal-local-value' is now eliminated, but the
+   terminal-local variables should still be accessible as terminal
+   parameters.  This also applies to `display-name' and similar
+   functions.)
+
 ** Add the following hooks: after-delete-frame-hook (for server.el,
    instead of delete-frame-functions),
    after-delete-terminal-functions, after-create-terminal-functions.
@@ -477,15 +518,16 @@ THINGS TO DO
     frames-on-display-list             frames-on-terminal-list
 
    The following functions were introduced in the multi-tty branch, and
-   can be renamed without aliases:
+   were renamed without aliases:
 
-    display-controlling-tty-p           terminal-controlling-tty-p
+    delete-display                     delete-terminal
+    display-controlling-tty-p           controlling-tty-p
     display-list                        terminal-list
     display-live-p                      terminal-live-p
     display-name                        terminal-name
-    display-tty-type                    terminal-tty-type
-    frame-display                       terminal-of-frame
-    delete-display                     delete-terminal
+    display-tty-type                    tty-type
+    frame-display                       frame-terminal
+    selected-display                   selected-terminal
 
 ** The single-keyboard mode of MULTI_KBOARD is extremely confusing
    sometimes; Emacs does not respond to stimuli from other keyboards.
@@ -1296,5 +1338,44 @@ DIARY OF CHANGES
 
    (Disabled in patch-450.)
 
+-- Implement automatic forwarding of client environment variables to
+   forked processes, as discussed on the multi-tty list.  Terminal
+   parameters are now accessible in C code, so the biggest obstacle is
+   gone.  The `getenv_internal' and `child_setup' functions in
+   callproc.c must be changed to support the following variable:
+
+       terminal-local-environment-variables is a variable defined in ...
+
+       Enable or disable terminal-local environment variables.
+
+       If set to t, `getenv', `setenv' and subprocess creation
+       functions use the environment variables of the emacsclient
+       process that created the selected frame, ignoring
+       `process-environment'.
+
+       If set to nil, Emacs uses `process-environment' and ignores
+       the client environment.
+
+       Otherwise, `terminal-local-environment-variables' should be a
+       list of variable names (represented by Lisp strings) to look
+       up in the client environment.  The rest will come from
+       `process-environment'.
+
+   (Implemented in patch-461; `terminal-getenv', `terminal-setenv' and
+   `with-terminal-environment' are now replaced by extensions to
+   `getenv' and `setenv', and the new `local-environment-variables'
+   facility.  Yay!)
+
+   (Updated in patch-465 to fix the semantics of let-binding
+   `process-environment'.  `process-environment' was changed to
+   override all local/global environment variables, and a new variable
+   `global-environment' was introduced to have `process-environment's
+   old meaning.)
+
+   (Updated in patch-466 to fix the case when two emacsclient sessions
+   share the same terminal, but have different environment.  The local
+   environment lists are now stored as frame parameters, so the
+   C-level terminal parameters are not strictly necessary any more.)
+
 ;;; arch-tag: 8da1619e-2e79-41a8-9ac9-a0485daad17d