"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/lisp/term/README" (14 Apr 2017, 11206 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README": 25.1_vs_25.2.

    1 Copyright (C) 1993, 2001-2017 Free Software Foundation, Inc.
    2 See the end of the file for license conditions.
    3 
    4 
    5    This directory contains files of elisp that customize Emacs for certain
    6 terminal types.
    7 
    8    When Emacs opens a new terminal, it checks the TERM environment variable
    9 to see what type of terminal the user is running on.  (If there is an entry
   10 for TERM in the 'term-file-aliases' variable, Emacs uses the associated value
   11 in place of TERM in the following.)  Emacs searches for an elisp file named
   12 "term/${TERM}.el", and if one exists, loads it.  If Emacs finds no
   13 suitable file, then it strips the last hyphen and what follows it from TERM,
   14 and tries again.  If that still doesn't yield a file, then the previous hyphen
   15 is stripped, and so on until all hyphens are gone.  For example, if the
   16 terminal type is 'aaa-48-foo', Emacs will try first 'term/aaa-48-foo.el', then
   17 'term/aaa-48.el' and finally 'term/aaa.el'.  Emacs stops searching at the
   18 first file found, and will not load more than one file for any terminal.  Note
   19 that it is not an error if Emacs is unable to find a terminal initialization
   20 file; in that case, it will simply proceed with the next step without loading
   21 any files.
   22 
   23    Once the file has been loaded (or the search failed), Emacs tries to call a
   24 function named 'terminal-init-TERMINALNAME' (eg 'terminal-init-aaa-48' for the
   25 'aaa-48' terminal) in order to initialize the terminal.  Once again, if the
   26 function is not found, Emacs strips the last component of the name and tries
   27 again using the shorter name.  This search is independent of the previous file
   28 search, so that you can have terminal initialization functions for a family of
   29 terminals collected in a single file named after the family name, and users
   30 may put terminal initialization functions directly in their .emacs files.
   31 
   32    Note that an individual terminal file is loaded only once in an Emacs
   33 session; if the same terminal type is opened again, Emacs will simply call the
   34 initialization function without reloading the file.  Therefore, all the actual
   35 initialization actions should be collected in terminal-init-* functions; the
   36 file should not contain any top-level form that is not a function or variable
   37 declaration.  Simply loading the file should not have any side effect.
   38 
   39    Similarly, the terminal initialization function is called only once on any
   40 given terminal, when the first frame is created on it.  The function is not
   41 called for subsequent frames on the same terminal.  Therefore, terminal-init-*
   42 functions should only modify terminal-local variables (such as
   43 'local-function-key-map') and terminal parameters.  For example, it is not
   44 correct to modify frame parameters, since the modifications will only be
   45 applied for the first frame opened on the terminal.
   46 
   47 
   48    When writing terminal packages, there are some things it is good to keep in
   49 mind.
   50 
   51    First, about keycap names.  Your terminal package can create any keycap
   52 cookies it likes, but there are good reasons to stick to the set recognized by
   53 the X-windows code whenever possible.  The key symbols recognized by Emacs
   54 are listed in src/term.c; look for the string 'keys' in that file.
   55 
   56    For one thing, it means that you'll have the same Emacs key bindings on in
   57 terminal mode as on an X console.  If there are differences, you can bet
   58 they'll frustrate you after you've forgotten about them.
   59 
   60    For another, the X keysyms provide a standard set of names that Emacs knows
   61 about.  It tries to bind many of them to useful things at startup, before your
   62 .emacs is read (so you can override them).  In some ways, the X keysym standard
   63 is a admittedly poor one; it's incomplete, and not well matched to the set of
   64 'virtual keys' that UNIX terminfo(3) provides.  But, trust us, the alternatives
   65 were worse.
   66 
   67    This doesn't mean that if your terminal has a "Cokebottle" key you shouldn't
   68 define a [cokebottle] keycap.  But if you must define cookies that aren't in
   69 that set, try to pattern them on the standard terminfo variable names for
   70 clarity; also, for a fighting chance that your binding may be useful to someone
   71 else someday.
   72 
   73    For example, if your terminal has a 'find' key, observe that terminfo
   74 supports a key_find capability and call your cookie [find].
   75 
   76 Here is a complete list, with corresponding X keysyms.
   77 
   78 -----------------------------------------------------------------------------
   79 Variable name	cap	X Keysym	Description
   80 --------------	---	------------	-------------------------------------
   81 key_down	kd	down		Sent by terminal down arrow key
   82 key_up		ku	up		Sent by terminal up arrow key
   83 key_left	kl	left		Sent by terminal left arrow key
   84 key_right	kr	right		Sent by terminal right arrow key
   85 key_home	kh	home		Sent by home key.
   86 key_backspace	kb			Sent by backspace key
   87 key_dl		kd	deleteline	Sent by delete line key.
   88 key_il		kA	insertline	Sent by insert line.
   89 key_dc		kD			Sent by delete character key.
   90 key_ic		kI	insertchar (1)	Sent by ins char/enter ins mode key.
   91 key_eic		KM			Sent by rmir or smir in insert mode.
   92 key_clear	kC			Sent by clear screen or erase key.
   93 key_eos		kS			Sent by clear-to-end-of-screen key.
   94 key_eol		kE			Sent by clear-to-end-of-line key.
   95 key_sf		kF			Sent by scroll-forward/down key
   96 key_sr		kR			Sent by scroll-backward/up key
   97 key_npage	kN	next (2)	Sent by next-page key
   98 key_ppage	kP	prior (2)	Sent by previous-page key
   99 key_stab	kT			Sent by set-tab key
  100 key_ctab	kt			Sent by clear-tab key
  101 key_catab	ka			Sent by clear-all-tabs key.
  102 key_enter	@8	kp-enter	Enter/send (unreliable)
  103 key_print	%9	print		print or copy
  104 key_ll		kH			Sent by home-down key
  105 key_a1		K1	kp-1		Upper left of keypad
  106 key_a3		K3	kp-3		Upper right of keypad
  107 key_b2		K2	kp-5		Center of keypad
  108 key_c1		K4	kp-7		Lower left of keypad
  109 key_c3		K5	kp-9		Lower right of keypad
  110 key_btab	kB	backtab		Back tab key
  111 key_beg		@1	begin		beg(inning) key
  112 key_cancel	@2	cancel		cancel key
  113 key_close	@3			close key
  114 key_command	@4	execute (3)	cmd (command) key
  115 key_copy	@5			copy key
  116 key_create	@6			create key
  117 key_end		@7	end		end key
  118 key_exit	@9			exit key
  119 key_find	@0			find key
  120 key_help	%1			help key
  121 key_mark	%2			mark key
  122 key_message	%3			message key
  123 key_move	%4			move key
  124 key_next	%5	next (2)	next object key
  125 key_open	%6			open key
  126 key_options	%7	menu (3)	options key
  127 key_previous	%8	previous (2)	previous object key
  128 key_redo	%0	redo		redo key
  129 key_reference	&1			ref(erence) key
  130 key_refresh	&2			refresh key
  131 key_replace	&3			replace key
  132 key_restart	&4	reset (3)	restart key
  133 key_resume	&5			resume key
  134 key_save	&6			save key
  135 key_sbeg	&9			shifted beginning key
  136 key_select	*6	select		select key
  137 key_suspend	&7			suspend key
  138 key_undo	&8	undo		undo key
  139 
  140 key_scancel	&0			shifted cancel key
  141 key_scommand	*1			shifted command key
  142 key_scopy	*2			shifted copy key
  143 key_screate	*3			shifted create key
  144 key_sdc		*4			shifted delete char key
  145 key_sdl		*5			shifted delete line key
  146 key_send	*7			shifted end key
  147 key_seol	*8			shifted clear line key
  148 key_sexit	*9			shifted exit key
  149 key_sf		kF			shifted find key
  150 key_shelp	#1			shifted help key
  151 key_shome	#2			shifted home key
  152 key_sic		#3			shifted input key
  153 key_sleft	#4			shifted left arrow key
  154 key_smessage	%a			shifted message key
  155 key_smove	%b			shifted move key
  156 key_snext	%c			shifted next key
  157 key_soptions	%d			shifted options key
  158 key_sprevious	%e			shifted prev key
  159 key_sprint	%f			shifted print key
  160 key_sredo	%g			shifted redo key
  161 key_sreplace	%h			shifted replace key
  162 key_sright	%i			shifted right arrow
  163 key_sresume	%j			shifted resume key
  164 key_ssave	!1			shifted save key
  165 key_suspend	!2			shifted suspend key
  166 key_sundo	!3			shifted undo key
  167 
  168 key_f0		k0	f0 (4)		function key 0
  169 key_f1		k1	f1		function key 1
  170 key_f2		k2	f2		function key 2
  171 key_f3		k3	f3		function key 3
  172 key_f4		k4	f4		function key 4
  173 key_f5		k5	f5		function key 5
  174 key_f6		k6	f6		function key 6
  175 key_f7		k7	f7		function key 7
  176 key_f8		k8	f8		function key 8
  177 key_f9		k9	f9		function key 9
  178 key_f10		k;	f10 (4)		function key 10
  179 key_f11		F1	f11		function key 11
  180   :		:	   :			:
  181 key_f35		FP	f35		function key 35
  182 key_f36		FQ			function key 36
  183   :		:	   :			:
  184 key_f64		k1			function key 64
  185 
  186 (1) The terminfo documentation says this may be the 'insert character' or
  187     'enter insert mode' key.  Accordingly, key_ic is mapped to the 'insertchar'
  188     keysym if there is also a key_dc key; otherwise it's mapped to 'insert'.
  189     The presumption is that keyboards with 'insert character' keys usually
  190     have 'delete character' keys paired with them.
  191 
  192 (2) If there is no key_next key but there is a key_npage key, key_npage
  193     will be bound to the 'next' keysym.  If there is no key_previous key but
  194     there is a key_ppage key, key_ppage will be bound to the 'previous' keysym.
  195 
  196 (3) Sorry, these are not exact but they're the best we can do.
  197 
  198 (4) The uses of the "k0" capability are inconsistent; sometimes it
  199     describes F10, whereas othertimes it describes F0 and "k;" describes F10.
  200     Emacs attempts to politely accommodate both systems by testing for
  201     "k;", and if it is present, assuming that "k0" denotes F0, otherwise F10.
  202 -----------------------------------------------------------------------------
  203 
  204    The following X keysyms do *not* have terminfo equivalents.   These are
  205 the cookies your terminal package will have to set up itself, if you want them:
  206 
  207 	break
  208 	system
  209 	user
  210 	kp-backtab
  211 	kp-space
  212 	kp-tab
  213 	kp-f1
  214 	kp-f2
  215 	kp-f3
  216 	kp-f4
  217 	kp-multiply
  218 	kp-add
  219 	kp-separator
  220 	kp-subtract
  221 	kp-decimal
  222 	kp-divide
  223 	kp-0
  224 	kp-2
  225 	kp-4
  226 	kp-6
  227 	kp-8
  228 	kp-equal
  229 
  230    In general, you should not bind any of the standard keysym names to
  231 functions in a terminal package.  There's code in loaddefs.el that does that;
  232 the less people make exceptions to that, the more consistent an interface Emacs
  233 will have across different keyboards.  Those exceptions should go in your
  234 .emacs file.
  235 
  236    Finally, if you're using a USL UNIX or a Sun box or anything else with the
  237 USL version of curses(3) on it, bear in mind that the original curses(3) had
  238 (and still has) a very much smaller set of keycaps.  In fact, the reliable
  239 ones were just the arrow keys and the first ten function keys.  If you care
  240 about making your package portable to older Berkeley machines, don't count on
  241 the setup code to bind anything else.
  242 
  243    If your terminal's arrow key sequences are so funky that they conflict with
  244 normal Emacs key bindings, the package should set up a function called
  245 (enable-foo-arrow-keys), where 'foo' becomes the terminal name, and leave
  246 it up to the user's .emacs file whether to call it.
  247 
  248    Before writing a terminal-support package, it's a good idea to read the
  249 existing ones and learn the common conventions.
  250 
  251 
  252 This file is part of GNU Emacs.
  253 
  254 GNU Emacs is free software: you can redistribute it and/or modify
  255 it under the terms of the GNU General Public License as published by
  256 the Free Software Foundation, either version 3 of the License, or
  257 (at your option) any later version.
  258 
  259 GNU Emacs is distributed in the hope that it will be useful,
  260 but WITHOUT ANY WARRANTY; without even the implied warranty of
  261 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  262 GNU General Public License for more details.
  263 
  264 You should have received a copy of the GNU General Public License
  265 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.