-Copyright (C) 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Copyright (C) 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
Free Software Foundation, Inc.
See the end of the file for license conditions.
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 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.
\f
This file is part of GNU Emacs.
-GNU Emacs is free software; you can redistribute it and/or modify
+GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 3, or (at your option)
-any later version.
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
-along with GNU Emacs; see the file COPYING. If not, write to the
-Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-Boston, MA 02110-1301, USA.
+along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
HCoop / bpt / emacs.git / blobdiff