--- a/lisp/README	Sun Aug 26 09:42:24 2001 +0000
+++ b/lisp/README	Sun Aug 26 10:25:14 2001 +0000
@@ -1,3 +1,77 @@
+The files in this directory contain source code for the core XEmacs
+facilities written in Emacs Lisp.  *.el files are Elisp source, and
+*.elc files are byte-compiled versions of the corresponding *.el
+files.  Byte-compiled files are architecture-independent.
+
+Functions used only by files in this directory are considered
+"internal" and are subject to change at any time.  All commands, and
+most functions with docstrings, are part of the exported API.  In
+particular, it is considered good style to use the Common Lisp
+facilities provided in cl*.el.  (Yes, that's ambiguous.  Sorry, we
+don't have a full specification of the API, as the Lispref is
+chronically incomplete.  Anything described in the Lispref is part of
+the API, of course.)
+
+Libraries which implement applications and enhancements are placed in
+the "packages", which are distributed separately from the core
+sources.
+
+#### Someone please update this.
+#### Partially updated 2001-08-25 by sjt.  Needs more work.  Mike?
+
+When XEmacs starts up, it adds certain directories in various
+hierarchies containing Lisp libraries to `load-path' (the list of
+directories to be searched when loading files).  These are: this
+directory, its subdirectory ./mule (in Mule-enabled XEmacs only), the
+site-lisp directory (deprecated), and all the lisp/PACKAGE
+subdirectories of the xemacs-packages, mule-packages, and
+site-packages hierarchies.  See setup-paths.el.
+
+#### Is the following true or relevant any more?
+bogus> Directories whose names begin with "-" or "." are not added to
+bogus> the default load-path.
+
+Some files which you might reasonably want to alter when installing or
+customizing XEmacs at your site are:
+
+	paths.el	You may need to change the default pathnames here,
+			but probably not.  This is loaded before XEmacs is
+			dumped.
+
+	site-init.el	#### obsolete and removed?
+			To pre-load additional libraries into XEmacs and dump
+			them in the executable, load them from this file.
+			Read the instructions in this file for a description
+			of how to do this.
+
+	site-load.el	#### description is obsolete
+			This is like site-init.el, but if you want the 
+			docstrings of your preloaded libraries to be kept in
+			the DOC file instead of in the executable, you should
+			load them from this file instead.  To do this, you must
+			also cause them to be scanned when the DOC file is
+			generated by editing ../src/Makefile.in.in and
+			rerunning configure.
+			#### new semantics
+			This file will preload additional libraries listed in
+			../site-packages and dump them into XEmacs.
+
+	../site-packages  List of additional libraries read by site-load.el.
+
+	site-start.el	This is loaded each time XEmacs starts up, before the
+			user's .emacs file.  (Sysadmin must create.)  Can be
+			inhibited for a given invocation with `--no-site-file'.
+
+	default.el	This is loaded each time XEmacs starts up, after the
+			user's .emacs file, unless .emacs sets the variable
+			inhibit-default-init to t.  (Sysadmin must create.)
+			Can be inhibited for a given invocation with `-q'.
+
+	version.el	This contains the version information for XEmacs.
+
+========================================================================
+Original text follows:
+
 The files in this directory contain source code for the XEmacs
 facilities written in Emacs Lisp.  *.el files are Elisp source, and
 *.elc files are byte-compiled versions of the corresponding *.el