-The first one is for locally installed packages for a particular Emacs
-version; the second is for locally installed packages meant for use
-with all installed Emacs versions.
-
- If you run Emacs from the directory where it was built---that is, an
-executable that has not been formally installed---Emacs puts two more
-directories in @code{load-path}. These are the @code{lisp} and
-@code{site-lisp} subdirectories of the main build directory. (Both
-are represented as absolute file names.)
-
- Next, Emacs ``expands'' the initial list of directories in
-@code{load-path} by adding the subdirectories of those directories.
-Both immediate subdirectories and subdirectories multiple levels down
-are added. But it excludes subdirectories whose names do not start
-with a letter or digit, and subdirectories named @file{RCS} or
-@file{CVS}, and subdirectories containing a file named
-@file{.nosearch}.
-
- Next, Emacs adds any extra load directory that you specify using the
-@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
+The first one is for locally installed files for a specific Emacs
+version; the second is for locally installed files meant for use
+with all installed Emacs versions. (If Emacs is running uninstalled,
+it also adds @file{site-lisp} directories from the source and build
+directories, if they exist. Normally these directories do not contain
+@file{site-lisp} directories.)
+
+@cindex @env{EMACSLOADPATH} environment variable
+If the environment variable @env{EMACSLOADPATH} is set, it modifies
+the above initialization procedure. Emacs initializes
+@code{load-path} based on the value of the environment variable.
+
+The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH};
+directory names are separated by @samp{:} (or @samp{;}, on some
+operating systems).
+@ignore
+@c AFAICS, does not (yet) work right to specify non-absolute elements.
+and @samp{.} stands for the current default directory.
+@end ignore
+Here is an example of how to set @env{EMACSLOADPATH} variable (from a
+@command{sh}-style shell):
+
+@example
+export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
+@end example
+
+An empty element in the value of the environment variable, whether
+trailing (as in the above example), leading, or embedded, is replaced
+by the default value of @code{load-path} as determined by the standard
+initialization procedure. If there are no such empty elements, then
+@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must
+include either an empty element, or the explicit path to the directory
+containing the standard Lisp files, else Emacs will not function.
+(Another way to modify @code{load-path} is to use the @option{-L}
+command-line option when starting Emacs; see below.)
+
+ For each directory in @code{load-path}, Emacs then checks to see if
+it contains a file @file{subdirs.el}, and if so, loads it. The
+@file{subdirs.el} file is created when Emacs is built/installed,
+and contains code that causes Emacs to add any subdirectories of those
+directories to @code{load-path}. Both immediate subdirectories and
+subdirectories multiple levels down are added. But it excludes
+subdirectories whose names do not start with a letter or digit, and
+subdirectories named @file{RCS} or @file{CVS}, and subdirectories
+containing a file named @file{.nosearch}.
+
+ Next, Emacs adds any extra load directories that you specify using the
+@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The
HCoop / bpt / emacs.git / blobdiff