comparison lisp/term/README @ 83524:673d62ad74b5

Fix and/or simplify terminal initialization files. * lisp/faces.el (tty-create-frame-with-faces): Set up faces and background mode only after the terminal has been initialized. (frame-set-background-mode): Handle the 'background-mode terminal parameter. (tty-run-terminal-initialization): Add type option. * lisp/term/README: Update. * lisp/term/rxvt.el: Simplify. * lisp/term/xterm.el: Simplify and fix. * lisp/term/*.el: Simplify and fix. git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-564

83523:6ce7108f7eef

   This directory contains files of elisp that customize Emacs for certain
terminal types.

   When Emacs starts, it checks the TERM environment variable to see what type
of terminal the user is running on, checks for an elisp file named
"term/${TERM}.el", and if one exists, loads it.  If that doesn't yield a file
that exists, the last hyphen and what follows it is stripped.  If that doesn't
yield a file that exists, the previous hyphen is stripped, and so on until all
hyphens are gone.  For example, if the terminal type is `aaa-48-foo', Emacs
will try first `term/aaa-48-foo.el', then `term/aaa-48.el' and finally
`term/aaa.el'.  Each terminal specific file should contain a function
named terminal-init-TERMINALNAME (eg terminal-init-aaa-48 for
term/aaa-48.el) that Emacs will call in order to initialize the
terminal. The terminal files should not contain any top level forms
that are executed when the file is loaded, all the initialization
actions are performed by the terminal-init-TERMINALNAME functions.

   When writing terminal packages, there are some things it is good to keep in
mind.

   First, about keycap names.  Your terminal package can create any keycap

83524:673d62ad74b5

   This directory contains files of elisp that customize Emacs for certain
terminal types.

   When Emacs opens a new terminal, it checks the TERM environment variable to
see what type of terminal the user is running on, searches for an elisp file
named "term/${TERM}.el", and if one exists, loads it.  If Emacs finds no
suitable file, then it strips the last hyphen and what follows it from TERM,
and tries again.  If that still doesn't yield a file, then the previous hyphen
is stripped, and so on until all hyphens are gone.  For example, if the
terminal type is `aaa-48-foo', Emacs will try first `term/aaa-48-foo.el', then
`term/aaa-48.el' and finally `term/aaa.el'.  Emacs stops searching at the
first file found, and will not load more than one file for any terminal.  Note
that it is not an error if Emacs is unable to find a terminal initialization
file; in that case, it will simply proceed with the next step without loading
any files.

   Once the file has been loaded (or the search failed), Emacs tries to call a
function named `terminal-init-TERMINALNAME' (eg `terminal-init-aaa-48' for the
`aaa-48' terminal) in order to initialize the terminal.  Once again, if the
function is not found, Emacs strips the last component of the name and tries
again using the shorter name.  This search is independent of the previous file
search, so that you can have terminal initialization functions for a family of
terminals collected in a single file named after the family name, and users
may put terminal initialization functions directly in their .emacs files.

   Note that an individual terminal file is loaded only once in an Emacs
session; if the same terminal type is opened again, Emacs will simply call the
initialization function without reloading the file.  Therefore, all the actual
initialization actions should be collected in terminal-init-* functions; the
file should not contain any top-level form that is not a function or variable
declaration.  Simply loading the file should not have any side effect.

   Similarly, the terminal initialization function is called only once on any
given terminal, when the first frame is created on it.  The function is not
called for subsequent frames on the same terminal.  Therefore, terminal-init-*
functions should only modify terminal-local variables (such as
`local-function-key-map') and terminal parameters.  For example, it is not
correct to modify frame parameters, since the modifications will only be
applied for the first frame opened on the terminal.


   When writing terminal packages, there are some things it is good to keep in
mind.

   First, about keycap names.  Your terminal package can create any keycap