Initial revision

2 files changed, 233 insertions, 0 deletions

diff --git a/etc/=TO-DO b/etc/=TO-DO
new file mode 100644
index 00000000000..cc5b398eeca
--- /dev/null
+++ b/etc/=TO-DO
@@ -0,0 +1,26 @@
+Things useful to do for GNU Emacs:
+
+* Primitive for random access insertion of part of a file.
+
+* Making I/O streams for files, so that read and prin1 can
+ be used on files directly.  The I/O stream itself would
+ serve as a function to read or write one character.
+
+* If a file you can't write is in a directory you can write,
+ make sure it works to modify and save this file.
+
+* Make dired's commands handle correctly the case where
+ ls has listed several subdirectories' contents.
+ It needs to be able to tell which directory each file
+ is really in, by searching backward for the line
+ which identifies the start of a directory.
+
+* Add more dired commands, such as sorting (use the
+ sort utility through call-process-region).
+
+* Make display.c record inverse-video-ness on
+ a character by character basis.  Then make non-full-screen-width
+ mode lines inverse video, and display the marked location in
+ inverse video.
+
+* VMS code to list a file directory.  Make dired work.
diff --git a/lisp/term/README b/lisp/term/README
new file mode 100644
index 00000000000..f31986adcfa
--- /dev/null
+++ b/lisp/term/README
@@ -0,0 +1,207 @@
+   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.
+
+   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
+cookies it likes, but there are good reasons to stick to the set recognized by
+the X-windows code whenever possible.  The X key symbols recognized by Emacs
+are listed in src/term.c; look for the string `keys' in that file.
+
+   For one thing, it means that you'll have the same Emacs key bindings on in
+terminal mode as on an X console.  If there are differences, you can bet
+they'll frustrate you after you've forgotten about them.
+
+   For another, the X keysms provide a standard set of names that Emacs knows
+about.  It tries to bind many of them to useful things at startup, before your
+.emacs is read (so you can override them).  In some ways, the X keysym standard
+is a admittedly poor one; it's incomplete, and not well matched to the set of
+`virtual keys' that UNIX terminfo(3) provides.  But, trust us, the alternatives
+were worse.
+
+   This doesn't mean that if your terminal has a "Cokebottle" key you shouldn't
+define a [cokebottle] keycap.  But if you must define cookies that aren't in
+that set, try to pattern them on the standard terminfo variable names for
+clarity; also, for a fighting chance that your binding may be useful to someone
+else someday.
+
+   For example, if your terminal has a `find' key, observe that terminfo
+supports a key_find capability and call your cookie [key-find].
+
+Here is a complete list, with corresponding X keysyms.
+
+-----------------------------------------------------------------------------
+Variable name	cap	X Keysym	Description
+--------------	---	------------	-------------------------------------
+key_down	kd	down		Sent by terminal down arrow key
+key_up		ku	up		Sent by terminal up arrow key
+key_left	kl	left		Sent by terminal left arrow key
+key_right	kr	right		Sent by terminal right arrow key
+key_home	kh	home		Sent by home key.
+key_backspace	kb			Sent by backspace key
+key_dl		kd	deleteline	Sent by delete line key.
+key_il		kA	insertline	Sent by insert line.
+key_dc		kD			Sent by delete character key.
+key_ic		kI	insertchar (1)	Sent by ins char/enter ins mode key.
+key_eic		KM			Sent by rmir or smir in insert mode.
+key_clear	kC			Sent by clear screen or erase key.
+key_eos		kS			Sent by clear-to-end-of-screen key.
+key_eol		kE			Sent by clear-to-end-of-line key.
+key_sf		kF			Sent by scroll-forward/down key
+key_sr		kR			Sent by scroll-backward/up key
+key_npage	kN	next (2)	Sent by next-page key
+key_ppage	kP	prior (2)	Sent by previous-page key
+key_stab	kT			Sent by set-tab key
+key_ctab	kt			Sent by clear-tab key
+key_catab	ka			Sent by clear-all-tabs key.
+key_enter	@8	kp-enter	Enter/send (unreliable)
+key_print	%9	print		print or copy
+key_ll		kH			Sent by home-down key
+key_a1		K1	kp-1		Upper left of keypad
+key_a3		K3	kp-3		Upper right of keypad
+key_b2		K2	kp-5		Center of keypad
+key_c1		K4	kp-7		Lower left of keypad
+key_c3		K5	kp-9		Lower right of keypad
+key_btab	kB	backtab		Back tab key
+key_beg		@1	begin		beg(inning) key
+key_cancel	@2	cancel		cancel key
+key_close	@3			close key
+key_command	@4	execute (3)	cmd (command) key
+key_copy	@5			copy key
+key_create	@6			create key
+key_end		@7	end		end key
+key_exit	@9			exit key
+key_find	@0			find key
+key_help	%1			help key
+key_mark	%2			mark key
+key_message	%3			message key
+key_move	%4			move key
+key_next	%5	next (2)	next object key
+key_open	%6			open key
+key_options	%7	menu (3)	options key
+key_previous	%8	previous (2)	previous object key
+key_redo	%0	redo		redo key
+key_reference	&1			ref(erence) key
+key_refresh	&2			refresh key
+key_replace	&3			replace key
+key_restart	&4	reset (3)	restart key
+key_resume	&5			resume key
+key_save	&6			save key
+key_sbeg	&9			shifted beginning key
+key_select	*6	select		select key
+key_suspend	&7			suspend key
+key_undo	&8	undo		undo key
+
+key_scancel	&0			shifted cancel key
+key_scommand	*1			shifted command key
+key_scopy	*2			shifted copy key
+key_screate	*3			shifted create key
+key_sdc		*4			shifted delete char key
+key_sdl		*5			shifted delete line key
+key_send	*7			shifted end key
+key_seol	*8			shifted clear line key
+key_sexit	*9			shifted exit key
+key_sf		kF			shifted find key
+key_shelp	#1			shifted help key
+key_shome	#2			shifted home key
+key_sic		#3			shifted input key
+key_sleft	#4			shifted left arrow key
+key_smessage	%a			shifted message key
+key_smove	%b			shifted move key
+key_snext	%c			shifted next key
+key_soptions	%d			shifted options key
+key_sprevious	%e			shifted prev key
+key_sprint	%f			shifted print key
+key_sredo	%g			shifted redo key
+key_sreplace	%h			shifted replace key
+key_sright	%i			shifted right arrow
+key_sresume	%j			shifted resume key
+key_ssave	!1			shifted save key
+key_suspend	!2			shifted suspend key
+key_sundo	!3			shifted undo key
+
+key_f0		k0	f0 (4)		function key 0
+key_f1		k1	f1		function key 1
+key_f2		k2	f2		function key 2
+key_f3		k3	f3		function key 3
+key_f4		k4	f4		function key 4
+key_f5		k5	f5		function key 5
+key_f6		k6	f6		function key 6
+key_f7		k7	f7		function key 7
+key_f8		k8	f8		function key 8
+key_f9		k9	f9		function key 9
+key_f10		k;	f10 (4)		function key 10
+key_f11		F1	f11		function key 11
+  :		:	   :			:
+key_f35		FP	f35		function key 35
+key_f36		FQ			function key 36
+  :		:	   :			:
+key_f64		k1			function key 64
+
+(1) The terminfo documentation says this may be the 'insert character' or
+    `enter insert mode' key.  Accordingly, key_ic is mapped to the `insertchar'
+    keysym if there is also a key_dc key; otherwise it's mapped to `insert'.
+    The presumption is that keyboards with `insert character' keys usually
+    have `delete character' keys paired with them.
+
+(2) If there is no key_next key but there is a key_npage key, key_npage
+    will be bound to the `next' keysym.  If there is no key_previous key but
+    there is a key_ppage key, key_ppage will be bound to the `previous' keysym.
+
+(3) Sorry, these are not exact but they're the best we can do.
+
+(4) The uses of the "k0" capability are inconsistent; sometimes it
+    describes F10, whereas othertimes it describes F0 and "k;" describes F10.
+    Emacs attempts to politely accomodate both systems by testing for
+    "k;", and if it is present, assuming that "k0" denotes F0, otherwise F10.
+-----------------------------------------------------------------------------
+
+   The following X keysyms do *not* have terminfo equivalents.   These are
+the cookies your terminal package will have to set up itself, if you want them:
+
+	break
+	system
+	user
+	kp-backtab
+	kp-space
+	kp-tab
+	kp-f1
+	kp-f2
+	kp-f3
+	kp-f4
+	kp-multiply
+	kp-add
+	kp-separator
+	kp-subtract
+	kp-decimal
+	kp-divide
+	kp-0
+	kp-2
+	kp-4
+	kp-6
+	kp-8
+	kp-equal
+
+   In general, you should not bind any of the standard keysym names to
+functions in a terminal package.  There's code in loaddefs.el that does that;
+the less people make exceptions to that, the more consistent an interface Emacs
+will have across different keyboards.  Those exceptions should go in your
+.emacs file.
+
+   Finally, if you're using a USL UNIX or a Sun box or anything else with the
+USL version of curses(3) on it, bear in mind that the original curses(3) had
+(and still has) a very much smaller set of keycaps.  In fact, the reliable
+ones were just the arrow keys and the first ten function keys.  If you care
+about making your package portable to older Berkeley machines, don't count on
+the setup code to bind anything else.
+
+   If your terminal's arrow key sequences are so funky that they conflict with
+normal Emacs key bindings, the package should set up a function called
+(enable-foo-arrow-keys), where `foo' becomes the terminal name, and leave
+it up to the user's .emacs file whether to call it.
+
+   Before writing a terminal-support package, it's a good idea to read the
+existing ones and learn the common conventions.