new file mode 100644
--- /dev/null
+++ b/src/README.txt
@@ -0,0 +1,140 @@
+README for the Vim source code
+
+Here are a few hints for finding your way around the source code.  This
+doesn't make it less complex than it is, but it gets you started.
+
+You might also want to read ":help development".
+
+
+JUMPING AROUND
+
+First of all, use ":make tags" to generate a tags file, so that you can use
+the ":tag" command to jump around the source code.
+
+To jump to a function or variable definition, move the cursor on the name and
+use the CTRL-] command.  Use CTRL-T or CTRL-O to jump back.
+
+To jump to a file, move the cursor on its name and use the "gf" command.
+
+Most code can be found in a file with an obvious name (incomplete list):
+	buffer.c	manipulating buffers (loaded files)
+	diff.c		diff mode (vimdiff)
+	eval.c		expression evaluation
+	fileio.c	reading and writing files
+	fold.c		folding
+	getchar.c	getting characters and key mapping
+	mark.c		marks
+	memfile.c	storing lines for buffers in a swapfile
+	memline.c	storing lines for buffers in memory
+	menu.c		menus
+	message.c	(error) messages
+	mbyte.c		multy-byte character handling
+	ops.c		handling operators ("d", "y", "p")
+	option.c	options
+	quickfix.c	quickfix commands (":make", ":cn")
+	screen.c	updating the windows
+	search.c	pattern searching
+	tag.c		tags
+	term.c		terminal handling, termcap codes
+	undo.c		undo and redo
+	window.c	handling split windows
+
+
+IMPORTANT VARIABLES
+
+The current mode is stored in "State".  The values it can have are NORMAL,
+INSERT, CMDLINE, and a few others.
+
+The current window is "curwin".  The current buffer is "curbuf".  These point
+to structures with the cursor position in the window, option values, the file
+name, etc.  These are defined in structs.h.
+
+All the global variables are declared in globals.h.
+
+
+THE MAIN LOOP
+
+This is conveniently called main_loop().  It updates a few things and then
+calls normal_cmd() to process a command.  This returns when the command is
+finished.
+
+The basic idea is that Vim waits for the user to type a character and
+processes it until another character is needed.  Thus there are several places
+where Vim waits for a character to be typed.  The vgetc() function is used for
+this.  It also handles mapping.
+
+Updating the screen is mostly postponed until a command or a sequence of
+commands has finished.  The work is done by update_screen(), which calls
+win_update() for every window, which calls win_line() for every line.
+See the start of screen.c for more explanations.
+
+
+COMMAND-LINE MODE
+
+When typing a ":", normal_cmd() will call getcmdline() to obtain a line with
+an Ex command.  getcmdline() contains a loop that will handle each typed
+character.  It returns when hitting <CR> or <Esc> or some other character that
+ends the command line mode.
+
+
+EX COMMANDS
+
+Ex commands are handled by the function do_cmdline().  It does the generic
+parsing of the ":" command line and calls do_one_cmd() for each separate
+command.  It also takes care of while loops.
+
+do_one_cmd() parses the range and generic arguments and puts them in the
+exarg_t and passes it to the function that handles the command.
+
+The ":" commands are listed in ex_cmds.h.  The third entry of each item is the
+name of the function that handles the command.  The last entry are the flags
+that are used for the command.
+
+
+NORMAL MODE COMMANDS
+
+The Normal mode commands are handled by the normal_cmd() function.  It also
+handles the optional count and an extra character for some commands.  These
+are passed in a cmdarg_t to the function that handles the command.
+
+There is a table nv_cmds in normal.c which lists the first character of every
+command.  The second entry of each item is the name of the function that
+handles the command.
+
+
+INSERT MODE COMMANDS
+
+When doing an "i" or "a" command, normal_cmd() will call the edit() function.
+It contains a loop that waits for the next character and handles it.  It
+returns when leaving Insert mode.
+
+
+OPTIONS
+
+There is a list with all option names in option.c, called options[].
+
+
+THE GUI
+
+Most of the GUI code is implemented like it was a clever terminal.  Typing a
+character, moving a scrollbar, clicking the mouse, etc. are all translated
+into events which are written in the input buffer.  These are read by the
+main code, just like reading from a terminal.  The code for this is scattered
+through gui.c.  For example: gui_send_mouse_event() for a mouse click and
+gui_menu_cb() for a menu action.  Key hits are handled by the system-specific
+GUI code, which calls add_to_input_buf() to send the key code.
+
+Updating the GUI window is done by writing codes in the output buffer, just
+like writing to a terminal.  When the buffer gets full or is flushed,
+gui_write() will parse the codes and draw the appropriate items.  Finally the
+system-specific GUI code will be called to do the work.
+
+
+DEBUGGING THE GUI
+
+Remember to prevent that gvim forks and the debugger thinks Vim has exited,
+add the "-f" argument.  In gdb: "run -f -g".
+
+When stepping through display updating code, the focus event is triggerred
+when going from the debugger to Vim and back.  To avoid this, recompile with
+some code in gui_focus_change() disabled.