--- a/man/ChangeLog	Tue Feb 12 14:24:40 2002 +0000
+++ b/man/ChangeLog	Tue Feb 12 14:30:54 2002 +0000
@@ -1,3 +1,8 @@
+2002-01-27  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* lispref/packaging.texi (Makefile Variables): Document GENERATED
+	and PRELOADS.  Document DATA_FILES_n and DATA_DEST_n forms.
+
 2002-02-06  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* xemacs-faq.texi (Q1.3.8, Q1.3.9): Unicode support via Mule-UCS.

--- a/man/lispref/packaging.texi	Tue Feb 12 14:24:40 2002 +0000
+++ b/man/lispref/packaging.texi	Tue Feb 12 14:30:54 2002 +0000
@@ -771,11 +771,20 @@
 would probably be a good idea to set them in the @file{Makefile} (they
 do change, fairly often, but at present they aren't.
 
+@c #### This organization sucks.  Should break up by component, with
+@c theory of operations, example, and reference subsections.
 The @file{Makefile} is quite stylized.  The idea is similar to an
 @file{Imakefile} or an @code{automake} file: the complexity is hidden in
 generic rules files, in this case the @file{XEmacs.rules} include file
 in the top directory of the packages hierarchy.
 
+It is important to note that the XEmacs used to compile packages is the
+bare minimum:  it is called with the @samp{-no-user-file -no-site-file
+-no-autoloads}.  This means that anything not dumped into XEmacs by
+default needs to be specified in the @samp{REQUIRES} variable (for
+packaged Lisp) or in some cases the @samp{PRELOADS} (autoloads used in
+libraries mentioned in @samp{PRELOADS}).
+
 An @xpms{} @file{Makefile} has three components.  First, there is a
 variable definition section.  The standard @xpms{} @file{make} variables
 must be defined here for use by the @file{XEmacs.rules} include file.
@@ -1045,7 +1054,7 @@
 The corresponding field names for @file{package-info.in}, where
 relevant, are given in parentheses.
 
-@c #### This is the canonical place for this information.  If there is
+@c This is the canonical place for this information.  If there is
 @c unnecessary duplication with package-info.in documentation, shorten
 @c that and leave this full-length.
 @table @code
@@ -1118,7 +1127,7 @@
 do sanity checking to @email{xemacs-patches@@xemacs.org}.
 @end table
 
-Optional, but very commonly used variables include:
+Optional, but very commonly used variables are explained below.
 
 @table @code
 item EXTRA_SOURCES
@@ -1145,6 +1154,11 @@
 PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
 @end example
 
+Preloads are loaded before @file{package-compile.el}, so the
+@var{load-path} is minimal.  Therefore @samp{PRELOADS} must specify a
+full path to packaged Lisp.  The base @var{load-path} does include the
+core Lisp directory, so core libraries are found.
+
 @item INFO_FILES
 Any Info file(s) generated by the package.  These must be paths relative
 to the root of the package's source tree.
@@ -1158,14 +1172,39 @@
 
 @item DATA_FILES
 Any data files, such as pixmaps, READMEs, and ChangeLogs.  These must be
-paths relative to the root of the package's source tree.
+paths relative to the root of the package's source tree.  These files
+will be copied to @samp{$(DATA_DEST)} for installation.  Any directory
+component component of the path for a file will be stripped, so that the
+file ends up in @samp{$(DATA_DEST)}, not in a subdiredtory.  If there are
+several destination directories, the forms @samp{$(DATA_FILES_@var{n})}
+and @samp{$(DATA_DEST_@var{n})} (@var{n} may take values in 1-40) must
+be used.  The @xpms{} doesn't make provision for copying trees at this
+time.
 
 @item DATA_DEST
 The installation location for data files, relative to the @file{etc/}
-directory of the package hierarchy.  The normal value is simply
-$(PACKAGE).  Leaving it empty (@emph{i.e.}, put it directly under
-@file{etc/}) will probably work, but is subject to name conflicts with
-other packages.
+directory of the package hierarchy.  The default is currently empty, but
+the normal value is simply $(PACKAGE).  Leaving it empty (@emph{i.e.},
+put it directly under @file{etc/}) will probably work, but is subject to
+name conflicts with other packages.  If there are several destination
+directories, the form @samp{$(DATA_DEST_@var{n})} must be used.  The
+@xpms{} doesn't make provision for copying trees at this time.
+@end table
+
+The following variables are defaulted by @file{Local.rules} or
+@file{XEmacs.rules}.  These variables often should be added to using
+@samp{+=} rather than set by @samp{=} or @samp{:=}.
+
+@table @code
+@item GENERATED
+@c #### Is this correct?
+A list of @file{.elc} files compiled from @file{.el} files generated by
+the package build process.  These files and the corresponding @file{.el}
+files are copied to the installed @file{lisp} directory.  Defaults to
+@samp{$@{AUTOLOAD_PATH@}/auto-autoloads.elc}.  Typical usage is
+@example
+GENERATED += $@{AUTOLOAD_PATH@}/custom-load.elc
+@end example
 @end table
 
 Rarely used variables.