pages, as Emacs provides very few of them.)
There are several standard package hierarchies, and administrators can
-configure others at build time, while users can configure others at run
-time. The standard system hierarchies are all subdirectories of an
-@c #### This is possibly incorrect usage of "installation root."
-XEmacs installation root, typically @file{/usr/local/lib/xemacs/}.
-These are the @file{xemacs-packages}, @file{mule-packages},
-@file{infodock-packages}, and @file{site-packages} hierarchies. Each
-has the structure described above, but the purposes differ. The
+configure others at build time, while users can configure others at
+run time. The standard system hierarchies are all subdirectories of
+@file{$@{PREFIX@}/share/sxemacs/}. These are the @file{site-packages},
+@file{xemacs-packages}, @file{mule-packages},
+@file{infodock-packages}, and @file{sxemacs-packages} hierarchies.
+Each has the structure described above, but the purposes differ. The
@file{xemacs-packages} is the normal place for installing ``official''
packages and many third-party libraries. Unfortunately, it is not yet
quite possible to read libraries containing international characters
-with a non-Mule XEmacs, so such libraries are sequestered in the
-@file{mule-packages} hierarchy. Some packages are compatible only with
-the Infodock development environment, and they will be installed in the
-@file{infodock-packages} hierarchy. The @file{site-packages} hierarchy
-is for packages not distributed by XEmacs.org, typically locally
-developed.
-
-Packages are in principle supposed to be XEmacs version-independent, but
-if such dependencies are unavoidable, additional standard package
-hierarchies may be installed under version directories, @emph{e.g.}
-@file{/usr/local/lib/xemacs-21.4.6/}.
+with a non-Mule SXEmacs, so such libraries are sequestered in the
+@file{mule-packages} hierarchy. Some packages are compatible only
+with the Infodock development environment, and they will be installed
+in the @file{infodock-packages} hierarchy. The @file{site-packages}
+hierarchy is for packages not distributed by XEmacs.org, typically
+locally developed.
+
+@c Really don't think this is right --SY
+@c Packages are in principle supposed to be XEmacs version-independent, but
+@c if such dependencies are unavoidable, additional standard package
+@c hierarchies may be installed under version directories, @emph{e.g.}
+@c @file{/usr/local/lib/xemacs-21.4.6/}.
Users who do not have sufficient privilege to install packages in the
-system hierarchies may install package hierarchies under @file{~/.xemacs}.
-At present only the @file{xemacs-packages}, @file{mule-packages}, and
-@file{site-packages} hierarchies are supported, but it might make sense to
-extend this to support @file{infodock-packages} hierarchies in the future.
+system hierarchies may install package hierarchies under
+@file{@var{$XDG_DATA_HOME}/sxemacs}. At present only the
+@file{site-packages}, @file{xemacs-packages}, @file{mule-packages},
+and @file{sxemacs-packages} hierarchies are supported, but it might
+make sense to extend this to support @file{infodock-packages}
+hierarchies in the future.
The package hierarchies are not searched directly for libraries to be
loaded; this would be very costly. Instead, the hierarchies are ordered
results in a very ``clean'' @code{load-path}.
The order of search can be changed at build time by specifying the
-@samp{--package-path} option to @file{configure}, or at run-time by
+@samp{--with-package-path} option to @file{configure}, or at run-time by
specifying the @code{EMACSPACKAGEPATH} environment variable.
-@xref{Packages,,,xemacs}.
+@xref{Packages,,,sxemacs}
+Also, the location for @code{early-packages} may be set via the
+@code{-user-pkgs-directory} command line argument (@pxref{Command Swithches}).
@c #### The following description is quite possibly inaccurate.
@c Please, Michael, write some specs up!
-The default order of search is hierarchically determined. First, the
-roots are ordered. The @dfn{early} roots are the user-specific roots,
-typically @file{~/.xemacs}. The @dfn{late} roots are the system roots,
-typically @file{/usr/local/lib/xemacs-21.4.6} and
-@file{/usr/local/lib/xemacs}, in that order. All hierarchies for a
-given root are searched for package Lisp directories, which are appended
-to @code{load-path} in the order found. Then the search proceeds to the
-next root, whose results will be appended to the @code{load-path}
-generated by previous roots.
-
-Second, the hierarchies below each root are searched in the order
-@file{site-packages}, @file{infodock-packages}, @file{mule-packages},
-then @file{xemacs-packages}.
+The default order of search is hierarchically determined. There are 3
+``categories'' of lisp hierarchies in SXEmacs, well, actually there are
+4, but we'll get to that in a moment. In order, they are:
+@code{early-packages}, @code{late-packages}, and @dfn{core}.
+
+The @code{early-packages} are the user's local packages, stored
+under their @var{$HOME}. Typically, these packages will be in
+@file{@var{$XDG_DATA_HOME}/sxemacs}. The @code{late-packages} are the
+``system-wide'' packages, typically installed in
+@file{@var{$PREFIX}/share/sxemacs}, and @dfn{core} is the lisp that is
+shipped with SXEmacs and installed to
+@file{@var{$PREFIX}/share/sxemacs-@var{$version}}.
+
+The @code{early-packages} and @code{late-packages} are further split
+into @dfn{package types}. These types are (in search order):
+@file{site-packages}, @file{sxemacs-packages},
+@file{infodock-packages}, @file{mule-packages}, and
+@file{xemacs-packages}.
+
+The @dfn{core} lisp is also sub-divided into @file{mule}, @file{ffi},
+and ``normal'', and searched in that order.
+
+Oh, that 4th category I spoke of earlier, those are the
+@file{last-packages}. By default, SXEmacs does not have a
+pre-configured @dfn{last} package hierarchy. Last hierarchies are
+primarily for using package hierarchies of outdated versions of XEmacs
+as a fallback option. For example, it is possible to run SXEmacs with
+the XEmacs 20.4 package hierarchy as a last hierarchy.
In each hierarchy there should be a @file{lisp} subdirectory, containing
directories named for the packages. Each package's Lisp libraries thus
are contained in a directory of the form
-@var{root}/@var{hierarchy}/lisp/@var{package}/.
+@var{category}/@var{type}/lisp/@var{package}/. The 3 directories that
+make up the @dfn{core lisp} are, in search order@dots{}
+
+@smallexample
+@var{$PREFIX}/share/sxemacs-@var{version}/lisp/mule
+@var{$PREFIX}/share/sxemacs-@var{version}/lisp/ffi
+@var{$PREFIX}/share/sxemacs-@var{version}/lisp
+@end smallexample
With such a complex search algorithm, the possibility of libraries being
shadowed by another library with the same name is quite real. There are
-two considerations here. First, every XEmacs package contains certain
+two considerations here. First, every SXEmacs package contains certain
libraries with constant names. These are
@table @file
projects / sxemacs / blobdiff