--- a/lisp/autoload.el	Thu Jan 23 11:24:13 2003 +0000
+++ b/lisp/autoload.el	Thu Jan 23 11:39:01 2003 +0000
@@ -1,4 +1,4 @@
-;;; autoload.el --- maintain autoloads in loaddefs.el.
+;;; autoload.el --- maintain autoloads in auto-autoloads files.
 
 ;; Copyright (C) 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
 ;; Copyright (C) 1995 Tinker Systems and INS Engineering Corp.
@@ -28,19 +28,194 @@
 
 ;;; Commentary:
 
-;; This code helps XEmacs maintainers keep the loaddefs.el file up to
-;; date.  It interprets magic cookies of the form ";;;###autoload" in
-;; lisp source files in various useful ways.  To learn more, read the
-;; source; if you're going to use this, you'd better be able to.
+;; This code keeps auto-autoloads.el files up to date.  It interprets
+;; magic cookies (of the form ";;;###autoload" in Lisp source files
+;; and "/* ###autoload */" in C source files) in various useful ways.
+
+;; Usage
+;; =====
+
+;; Recommended usage for this library, as implemented in the core
+;; build process, is
+
+;; xemacs -no-packages -batch \
+;;        -eval "(setq generated-autoload-file \"PATH\")" \
+;;        -l autoload -f autoload-update-directory-autoloads PREFIX DIRECTORY
+
+;; which causes XEmacs to update the file named by PATH from the .el
+;; files in DIRECTORY (but not recursing into subdirectories) and (if
+;; the autoload file is not already protected with a feature test) add
+;; a check and provide for 'PREFIX-autoloads.  Currently there is no
+;; sanity check for the provided feature; it is recommended that you
+;; nuke any existing auto-autoloads.el before running the command.
+
+;; There is not yet a recommended API for updating multiple directories
+;; into a single auto-autoloads file.  Using the recipe above for each
+;; DIRECTORY with the same PATH should work but has not been tested.
+;; There is no API for recursing into subdirectories.  There probably
+;; won't be; given the wide variety of ways that existing Lisp packages
+;; arrange their files, and the fact that source packages and installed
+;; packages have a somewhat different directory structure, this seems far
+;; too risky.  Use a script or a Lisp library with an explicit list of
+;; PATHs; see update-elc.el for how to do this without recursive invocation
+;; of XEmacs).
+
+;; The probable next step is to fix up the packages to use the
+;; `autoload-update-directory-autoloads' API.  However, for backward
+;; compatibility with XEmacs 21.4 and 21.1, this can't be done quickly.
+
+;; For now the API used in update-elc-2.el:
+
+;; (let* ((dir "DIRECTORY")
+;;        (generated-autoload-file (expand-file-name "auto-autoloads.el" dir))
+;;        (autoload-package-name "PREFIX"))
+;;   (update-autoload-files (list muledir))
+;;   (byte-recompile-file generated-autoload-file 0))
+
+;; is available, but this ugly kludge is deprecated.  It will be removed
+;; in favor of using proper arguments instead of special variables.
+
+;; For backward compatibility the API used in the packages/XEmacs.rules:
+
+;; xemacs -vanilla -batch -eval "$(AUTOLOAD_PACKAGE_NAME)" \
+;;        -l autoload -f batch-update-directory $(AUTOLOAD_PATH)
+
+;; is supported, and the implementation is unchanged.  However,
+;; revision of the API (in a backward compatible way) and the
+;; implementation are planned, and until those stabilize it is too
+;; risky to use this version of XEmacs for package releases.
+
+;; Implementation:
+;; ===============
+
+;; #### This section should be moved to the Internals manual, or
+;; (maybe) the Lispref, and integrated with the information above.
+;; Don't believe anything written here; the code is still a mess, and
+;; this is a lot of guesswork.
+
+;; Autoloads are used in a number of contexts, including core Lisp,
+;; packaged Lisp, and ELLs (dynamically loadable compiled objects
+;; providing Lisp functionality).  There two general strategies for
+;; collecting autoloads.  The first is to put autoloads for a package
+;; in a package-specific auto-autoloads file.  This is easy to
+;; implement, and allows packages to be distributed with prebuilt
+;; auto-autoloads files.  The second is to collect all the autoloads
+;; in a single global auto-autoloads file.  This is alleged to speed
+;; up initialization significantly, but requires care to ensure that
+;; auto-autoloads files remain synchronized with the libraries.
+
+;; The traditional logic for determining where to put autoload
+;; definitions is complex and is now deprecated.  The special variable
+;; `generated-autoload-file' is used to hold the path to the file, and
+;; is initialized to the traditional (well, it's a new tradition with
+;; XEmacs 20) $blddir/lisp/auto-autoloads.el.  However, this variable
+;; may be bound by calling code, or may be generated at collect time
+;; and I'm not even sure the initialized value was ever used any more.
+
+;; Because there may be multiple auto-autoloads files in use (in XEmacs
+;; 21.x with a full complement of packages there are dozens), and they may
+;; contain initializations that would be dangerous to reexecute, each is
+;; protected by a feature test.  By convention, the feature symbol is of
+;; the form "NAME-autoloads".  For packages, the special variable
+;; `autoload-package-name' is used to determine NAME.  In the core,
+;; autoloads are defined in the modules (all of which are collected in a
+;; single auto-autoloads file), using NAME=modules, in the lisp directory
+;; using NAME=lisp, and in the lisp/mule directory, using NAME=mule, for
+;; the autoloads feature.  These latter are computed by the autoloads
+;; function at collect time.
 
 ;; ChangeLog:
 
-;; Jun-25-2002:  Jerry James added code for processing C files, to
-;;               support modularization
-;; Sep-26-1997:  slb removed code dealing with customization.
+;; See ./ChangeLog.
 
 ;;; Code:
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Standard file and directory names
+
+;; `autoload-file-name' is defvar'd and initialized in packages.el,
+;; which is loaded (and dumped) very early.  If you find it isn't, you
+;; know what you're doing.
+
+(defconst autoload-target-directory "../lisp/"
+  "Standard directory containing autoload declaration file.
+
+Use `generated-autoload-file' (q.v.) to change its installation location.")
+
+;; Dynamic variables for communication among functions
+
+(defvar generated-autoload-file
+  (expand-file-name autoload-file-name lisp-directory)
+  "*File `update-file-autoloads' puts autoloads into.
+A .el file can set this in its local variables section to make its
+autoloads go somewhere else.
+
+Note that `batch-update-directory' binds this variable to its own value,
+generally the file named by `autoload-file-name' in the directory being
+updated.  XEmacs.rules setq's this variable for package autoloads.")
+
+(define-obsolete-variable-alias 'autoload-package-name
+  'autoload-feature-prefix)
+(defvar autoload-feature-prefix nil
+  "If non-nil, use this string to prefix the autoload feature name.
+
+Usually a package name (from AUTOLOAD_PACKAGE_NAME, defined in XEmacs.rules
+in the top of the package hierarchy), or \"auto\" (reserved for the core Lisp
+auto-autoloads file).  Highest priority candidate except for an explicit
+argument to `autoload-make-feature-name' (q.v.).")
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Magic strings in source files
+
+(defconst generate-autoload-cookie ";;;###autoload"
+  "Magic comment indicating the following form should be autoloaded.
+Used by `update-file-autoloads'.  This string should be
+meaningless to Lisp (e.g., a comment).
+
+This string is used:
+
+;;;###autoload
+\(defun function-to-be-autoloaded () ...)
+
+If this string appears alone on a line, the following form will be
+read and an autoload made for it.  If it is followed by the string
+\"immediate\", then the form on the following line will be copied
+verbatim.  If there is further text on the line, that text will be
+copied verbatim to `generated-autoload-file'.")
+
+(defconst generate-c-autoload-cookie "/* ###autoload"
+  "Magic C comment indicating the following form should be autoloaded.
+Used by `update-file-autoloads'.  This string should be
+meaningless to C (e.g., a comment).
+
+This string is used:
+
+/* ###autoload */
+DEFUN (\"function-to-be-autoloaded\", ... )
+
+If this string appears alone on a line, the following form will be
+read and an autoload made for it.  If there is further text on the line,
+that text will be copied verbatim to `generated-autoload-file'.")
+
+(defconst generate-c-autoload-module "/* ###module"
+  "Magic C comment indicating the module containing autoloaded functions.
+Since a module can consist of multiple C files, the module name may not be
+the same as the C source file base name.  In that case, use this comment to
+indicate the actual name of the module from which to autoload functions.")
+
+(defconst generate-autoload-section-header "\f\n;;;### "
+  "String inserted before the form identifying
+the section of autoloads for a file.")
+
+(defconst generate-autoload-section-trailer "\n;;;***\n"
+  "String which indicates the end of the section of autoloads for a file.")
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Parsing the source file text.
+;; Autoloads in C source differ from those in Lisp source.  For historical
+;; reasons, functions handling only Lisp don't have "lisp" in their names;
+;; maybe this should be changed.
+
 (defun make-autoload (form file)
   "Turn a definition generator FORM into an autoload for source file FILE.
 Returns nil if FORM is not a defun, defun*, defmacro, defmacro*,
@@ -104,102 +279,27 @@
      (list 'autoload (list 'quote func-name) module
 	   (buffer-substring begin (point)) interact nil))))
 
-(defvar generate-autoload-cookie ";;;###autoload"
-  "Magic comment indicating the following form should be autoloaded.
-Used by `update-file-autoloads'.  This string should be
-meaningless to Lisp (e.g., a comment).
-
-This string is used:
-
-;;;###autoload
-\(defun function-to-be-autoloaded () ...)
-
-If this string appears alone on a line, the following form will be
-read and an autoload made for it.  If it is followed by the string
-\"immediate\", then the form on the following line will be copied
-verbatim.  If there is further text on the line, that text will be
-copied verbatim to `generated-autoload-file'.")
-
-(defvar generate-c-autoload-cookie "/* ###autoload"
-  "Magic C comment indicating the following form should be autoloaded.
-Used by `update-file-autoloads'.  This string should be
-meaningless to C (e.g., a comment).
-
-This string is used:
-
-/* ###autoload */
-DEFUN (\"function-to-be-autoloaded\", ... )
-
-If this string appears alone on a line, the following form will be
-read and an autoload made for it.  If there is further text on the line,
-that text will be copied verbatim to `generated-autoload-file'.")
-
-(defvar generate-c-autoload-module "/* ###module"
-  "Magic C comment indicating the module containing autoloaded functions.
-Since a module can consist of multiple C files, the module name may not be
-the same as the C source file base name.  In that case, use this comment to
-indicate the actual name of the module from which to autoload functions.")
-
-(defvar generate-autoload-section-header "\f\n;;;### "
-  "String inserted before the form identifying
-the section of autoloads for a file.")
-
-(defvar generate-autoload-section-trailer "\n;;;***\n"
-  "String which indicates the end of the section of autoloads for a file.")
-
-(defvar autoload-package-name nil)
-
-;;; Forms which have doc-strings which should be printed specially.
-;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
-;;; the doc-string in FORM.
-;;;
-;;; There used to be the following note here:
-;;; ;;; Note: defconst and defvar should NOT be marked in this way.
-;;; ;;; We don't want to produce defconsts and defvars that
-;;; ;;; make-docfile can grok, because then it would grok them twice,
-;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
-;;; ;;; once in loaddefs.el.
-;;;
-;;; Counter-note: Yes, they should be marked in this way.
-;;; make-docfile only processes those files that are loaded into the
-;;; dumped Emacs, and those files should never have anything
-;;; autoloaded here.  The above-feared problem only occurs with files
-;;; which have autoloaded entries *and* are processed by make-docfile;
-;;; there should be no such files.
-
-(put 'autoload 'doc-string-elt 3)
-(put 'defun    'doc-string-elt 3)
-(put 'defun*   'doc-string-elt 3)
-(put 'defvar   'doc-string-elt 3)
-(put 'defconst 'doc-string-elt 3)
-(put 'defmacro 'doc-string-elt 3)
-(put 'defmacro* 'doc-string-elt 3)
-(put 'define-skeleton 'doc-string-elt 3)
-(put 'define-derived-mode 'doc-string-elt 4)
-
-(defun autoload-trim-file-name (file)
-  "Returns a relative pathname of FILE including the last directory."
-  (setq file (expand-file-name file))
-  (replace-in-string
-   (file-relative-name file (file-name-directory
-			     (directory-file-name
-			      (file-name-directory file))))
-   "\\\\" "/"))
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Generating autoloads for a single file
 
 ;;;###autoload
 (defun generate-file-autoloads (file &optional funlist)
-  "Insert at point a loaddefs autoload section for FILE.
+  "Insert at point an autoload section for FILE.
 autoloads are generated for defuns and defmacros in FILE
 marked by `generate-autoload-cookie' (which see).
 If FILE is being visited in a buffer, the contents of the buffer
 are used."
   (interactive "fGenerate autoloads for file: ")
-  (if (string-match "\\.el$" file)
-      (generate-file-autoloads-1 file funlist)
-    (generate-c-file-autoloads-1 file funlist)))
+  (cond ((string-match "\\.el$" file)
+	 (generate-file-autoloads-1 file funlist))
+	;; #### jj, are C++ modules possible?
+	((string-match "\\.c$" file)
+	 (generate-c-file-autoloads-1 file funlist))
+	(t
+	 (error 'wrong-type-argument file "not a C or Elisp source file"))))
 
 (defun* generate-file-autoloads-1 (file funlist)
-  "Insert at point a loaddefs autoload section for FILE.
+  "Insert at point an autoload section for FILE.
 autoloads are generated for defuns and defmacros in FILE
 marked by `generate-autoload-cookie' (which see).
 If FILE is being visited in a buffer, the contents of the buffer
@@ -279,8 +379,8 @@
 			(cond ((looking-at "immediate\\s *$") ; XEmacs
 			       ;; This is here so that you can automatically
 			       ;; have small hook functions copied to
-			       ;; loaddefs.el so that it's not necessary to
-			       ;; load a whole file just to get a two-line
+			       ;; auto-autoloads.el so that it's not necessary
+			       ;; to load a whole file just to get a two-line
 			       ;; do-nothing find-file-hook... --Stig
 			       (forward-line 1)
 			       (setq begin (point))
@@ -312,7 +412,7 @@
 	  (terpri outbuf)
 	  ;;;; (insert ";;; Generated autoloads from "
 	  ;;;;	  (autoload-trim-file-name file) "\n")
-	  ;; Warn if we put a line in loaddefs.el
+	  ;; Warn if we put a line in auto-autoloads.el
 	  ;; that is long enough to cause trouble.
 	  (when (< output-end (point))
 	    (setq output-end (point-marker)))
@@ -333,7 +433,7 @@
 	(message "Generating autoloads for %s...done" file))))
 
 (defun* generate-c-file-autoloads-1 (file funlist)
-  "Insert at point a loaddefs autoload section for the C file FILE.
+  "Insert at point an autoload section for the C file FILE.
 autoloads are generated for defuns and defmacros in FILE
 marked by `generate-c-autoload-cookie' (which see).
 If FILE is being visited in a buffer, the contents of the buffer
@@ -343,6 +443,8 @@
 	(load-name (replace-in-string (file-name-nondirectory file)
 				      "\\.c?$"
 				      ""))
+	(exists-p-format 
+	 "(file-exists-p (expand-file-name \"%s.%s\" module-directory))")
 	(trim-name (autoload-trim-file-name file))
 	(print-length nil)
 	(print-readably t)
@@ -382,16 +484,14 @@
 		(if funlist
 		    (progn
 		      (message "Generating autoloads for %s..." trim-name)
-		      (princ "(when (or\n" outbuf)
-		      (princ (format
-			      "       (file-exists-p (expand-file-name \"%s.ell\" module-directory))\n"
-			      load-name) outbuf)
-		      (princ (format
-			      "       (file-exists-p (expand-file-name \"%s.dll\" module-directory))\n"
-			      load-name) outbuf)
-		      (princ (format
-			      "       (file-exists-p (expand-file-name \"%s.so\" module-directory)))\n"
-			      load-name) outbuf)
+		      (princ "(when (or\n       " outbuf)
+		      (princ (format exists-p-format load-name "ell") outbuf)
+		      (princ "\n       " outbuf)
+		      (princ (format exists-p-format load-name "dll") outbuf)
+		      (princ "\n       " outbuf)
+		      (princ (format exists-p-format load-name "so") outbuf)
+		      ;; close the princ'd `or' form
+		      (princ ")\n       " outbuf)
 		      (dolist (arg funlist)
 			(goto-char (point-min))
 			(re-search-forward
@@ -403,6 +503,7 @@
 			  (when autoload
 			    (push (nth 1 (nth 1 autoload)) autoloads-done)
 			    (print-autoload autoload 3 outbuf "  "))))
+		      ;; close the princ'd `when' form
 		      (princ ")" outbuf))
 		  (goto-char (point-min))
 		  (let ((match
@@ -412,16 +513,14 @@
 		      (return-from generate-c-file-autoloads-1))
 
 		    (message "Generating autoloads for %s..." trim-name)
-		    (princ "(when (or\n" outbuf)
-		    (princ (format
-			    "       (file-exists-p (expand-file-name \"%s.ell\" module-directory))\n"
-			    load-name) outbuf)
-		    (princ (format
-			    "       (file-exists-p (expand-file-name \"%s.dll\" module-directory))\n"
-			    load-name) outbuf)
-		    (princ (format
-			    "       (file-exists-p (expand-file-name \"%s.so\" module-directory)))\n"
-			    load-name) outbuf)
+		    (princ "(when (or\n       " outbuf)
+		    (princ (format exists-p-format load-name "ell") outbuf)
+		    (princ "\n       " outbuf)
+		    (princ (format exists-p-format load-name "dll") outbuf)
+		    (princ "\n       " outbuf)
+		    (princ (format exists-p-format load-name "so") outbuf)
+		    ;; close the princ'd `or' form
+		    (princ ")\n       " outbuf)
 		    (while match
 		      (forward-line 1)
 		      (let ((autoload (make-c-autoload load-name)))
@@ -430,6 +529,7 @@
 			  (print-autoload autoload 3 outbuf "  ")))
 		      (setq match
 			    (search-forward generate-c-autoload-cookie nil t)))
+		    ;; close the princ'd `when' form
 		    (princ ")" outbuf))))))
 	(unless visited
 	  ;; We created this buffer, so we should kill it.
@@ -446,6 +546,8 @@
     (or noninteractive ; XEmacs: only need one line in -batch mode.
 	(message "Generating autoloads for %s...done" trim-name))))
 
+;; Assorted utilities for generating  autoloads and pieces thereof
+
 (defun print-autoload (autoload doc-string-elt outbuf margin)
   "Print an autoload form, handling special characters.
 In particular, print docstrings with escapes inserted before left parentheses
@@ -514,36 +616,45 @@
 	    (insert "\\^L")))
 	(goto-char p2)))))
 
-
-(defconst autoload-file-name "auto-autoloads.el"
-  "Generic filename to put autoloads into.
-Unless you are an XEmacs maintainer, it is probably unwise to change this.")
-
-(defvar autoload-target-directory "../lisp/"
-  "Directory to put autoload declaration file into.
-Unless you know what you're doing, don't mess with this.")
+;;; Forms which have doc-strings which should be printed specially.
+;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
+;;; the doc-string in FORM.
+;;;
+;;; defvar and defconst should be also be marked in this way.  There is
+;;; no interference from make-docfile, which only processes those files
+;;; that are loaded into the dumped Emacs, and those files should
+;;; never have anything autoloaded here.  Problems only occur with files
+;;; which have autoloaded entries *and* are processed by make-docfile;
+;;; there should be no such files.
 
-(defvar generated-autoload-file
-  (expand-file-name (concat autoload-target-directory
-			    autoload-file-name)
-		    data-directory)
-  "*File `update-file-autoloads' puts autoloads into.
-A .el file can set this in its local variables section to make its
-autoloads go somewhere else.
+(put 'autoload 'doc-string-elt 3)
+(put 'defun    'doc-string-elt 3)
+(put 'defun*   'doc-string-elt 3)
+(put 'defvar   'doc-string-elt 3)
+(put 'defconst 'doc-string-elt 3)
+(put 'defmacro 'doc-string-elt 3)
+(put 'defmacro* 'doc-string-elt 3)
+(put 'define-skeleton 'doc-string-elt 3)
+(put 'define-derived-mode 'doc-string-elt 4)
 
-Note that `batch-update-directory' binds this variable to its own value,
-generally the file named `autoload-file-name' in the directory being
-updated.")
+(defun autoload-trim-file-name (file)
+  "Returns relative pathname of FILE including the last directory.
 
-(defconst cusload-file-name "custom-load.el"
-  "Generic filename to put custom loads into.
-Unless you are an XEmacs maintainer, it is probably unwise to change this.")
+Hard-codes the directory separator as a forward slash."
+  (setq file (expand-file-name file))
+  (replace-in-string
+   (file-relative-name file (file-name-directory
+			     (directory-file-name
+			      (file-name-directory file))))
+   ;; #### is this a good idea?
+   "\\\\" "/"))
 
 ;;;###autoload
 (defun update-file-autoloads (file)
   "Update the autoloads for FILE in `generated-autoload-file'
 \(which FILE might bind in its local variables).
-This function refuses to update autoloads files."
+This function is a no-op for an autoloads file (ie, a file whose name is
+equal to `autoload-file-name')."
   (interactive "fUpdate autoloads for file: ")
   (setq file (expand-file-name file))
   (when (and (file-newer-than-file-p file generated-autoload-file)
@@ -638,6 +749,78 @@
 	  (if (stringp file)
 	      (generate-file-autoloads file)))))))
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Utilities for batch updates
+
+;;;###autoload
+(defun autoload-update-directory-autoloads ()
+  "Update the autoloads for a directory, using a specified feature prefix.
+Must be used only with -batch.  The feature prefix and directory to update
+are taken from the first and second elements of `command-line-args-left',
+respectively, and they are then removed from `command-line-args-left'.
+
+Runs `update-file-autoloads' on each file in the given directory.  Always
+rewrites the autoloads file, even if unchanged.  Makes a feature name by
+applying `autoload-make-feature-name' to the specified feature prefix.
+
+#### The API and semantics of this function are subject to change."
+  (unless noninteractive
+    (error "autoload-batch-update-autoloads: may be used only with -batch"))
+  (let* ((autoload-feature-prefix (car command-line-args-left))
+	 (dir (cadr command-line-args-left))
+	 (generated-autoload-file (expand-file-name autoload-file-name dir)))
+    (update-autoload-files (list dir) t t)
+    (setq command-line-args-left (cddr command-line-args-left))))
+
+;;;###autoload
+(defun update-autoload-files (files-or-dirs &optional all-into-one-file force)
+  "Update all the autoload files associated with FILES-OR-DIRS.
+FILES-OR-DIRS is a list of files and/or directories to be processed.
+
+An appropriate autoload file is chosen and a feature constructed for
+each element of FILES-OR-DIRS.  Fixup code testing for the autoload file's
+feature and to provide the feature is added.
+
+If optional ALL-INTO-ONE-FILE is non-`nil', `generated-autoload-file'
+should be set to the name of an autoload file and all autoloads will be
+placed in that file.  `autoload-feature-prefix' should be set to an
+appropriate prefix which will be concatenated with \"-autoloads\" to
+produce the feature name.  Otherwise the appropriate autoload file for
+each file or directory (located in that directory, or in the directory of
+the specified file) will be updated with the directory's or file's
+autoloads and the protective forms will be added, and the files will be
+saved.  Use of the default here is unreliable, and therefore deprecated.
+
+Note that if some of FILES-OR-DIRS are directories, recursion goes only
+one level deep.
+
+If FORCE is non-nil, always save out the autoload files even if unchanged."
+  (let ((defdir (directory-file-name default-directory))
+	;; value for all-into-one-file
+	(autoload-feature-name (autoload-make-feature-name))
+	(enable-local-eval nil))	; Don't query in batch mode.
+    (dolist (arg files-or-dirs)
+      (setq arg (expand-file-name arg defdir))
+      (cond
+       ((file-directory-p arg)
+	(message "Updating autoloads for directory %s..." arg)
+	(update-autoloads-from-directory arg))
+       ((file-exists-p arg)
+	(update-file-autoloads arg))
+       (t (error "No such file or directory: %s" arg)))
+      (when (not all-into-one-file)
+	(autoload-featurep-protect-autoloads
+	 (autoload-make-feature-name
+	  (file-name-nondirectory (directory-file-name arg))))
+	(if force (set-buffer-modified-p
+		   t (find-file-noselect generated-autoload-file)))))
+    (when all-into-one-file
+      (autoload-featurep-protect-autoloads autoload-feature-name)
+      (if force (set-buffer-modified-p
+		 t (find-file-noselect generated-autoload-file))))
+    (save-some-buffers t)
+    ))
+
 ;;;###autoload
 (defun update-autoloads-from-directory (dir)
   "Update `generated-autoload-file' with all the current autoloads from DIR.
@@ -652,7 +835,7 @@
   (setq dir (expand-file-name dir))
   (let ((simple-dir (file-name-as-directory
 		     (file-name-nondirectory
-		     (directory-file-name dir))))
+		      (directory-file-name dir))))
 	(enable-local-eval nil))
     (save-excursion
       (let ((find-file-hooks nil))
@@ -678,7 +861,7 @@
       (unless noninteractive
 	(save-buffer)))))
 
-(defun fixup-autoload-buffer (sym)
+(defun autoload-featurep-protect-autoloads (sym)
   (save-excursion
     (set-buffer (find-file-noselect generated-autoload-file))
     (goto-char (point-min))
@@ -691,61 +874,45 @@
 	  (goto-char (point-max))
 	  (insert "\n(provide '" sym ")\n")))))
 
-(defvar autoload-package-name nil)
+(defun autoload-make-feature-name (&optional prefix)
+  "Generate the feature name to protect this auto-autoloads file from PREFIX.
 
-;;;###autoload
-(defun update-autoload-files (files-or-dirs &optional all-into-one-file force)
-  "Update all the autoload files associated with FILES-OR-DIRS.
-FILES-OR-DIRS should be a list of files or directories to be
-processed.  If ALL-INTO-ONE-FILE is not given, the appropriate
-autoload file for each file or directory (located in that directory,
-or in the directory of the specified file) will be updated with the
-directory's or file's autoloads, some additional fixup text will be
-added, and the files will be saved.  If ALL-INTO-ONE-FILE is given,
-`generated-autoload-file' should be set to the name of the autoload
-file into which the autoloads will be generated, and the autoloads
-for all files and directories will go into that same file.
+If PREFIX is nil, it defaults to the value of `autoload-feature-prefix' if
+that is non-nil.
+
+The feature name must be globally unique for this version of XEmacs,
+including packages.
 
-If FORCE is non-nil, always save out the autoload files even if unchanged."
-  (let ((defdir (directory-file-name default-directory))
-	(enable-local-eval nil))	; Don't query in batch mode.
-    ;; (message "Updating autoloads in %s..." generated-autoload-file)
-    (dolist (arg files-or-dirs)
-      (setq arg (expand-file-name arg defdir))
-      (let ((generated-autoload-file
-	     (if all-into-one-file generated-autoload-file
-	       (expand-file-name autoload-file-name
-				 (if (file-directory-p arg) arg
-				   (file-name-directory arg))))))
-	(cond
-	 ((file-directory-p arg)
-	  (message "Updating autoloads for directory %s..." arg)
-	  (update-autoloads-from-directory arg))
-	 ((file-exists-p arg)
-	  (update-file-autoloads arg))
-	 (t (error "No such file or directory: %s" arg)))
-	(when (not all-into-one-file)
-	  (fixup-autoload-buffer (concat (if autoload-package-name
-					     autoload-package-name
-					   (file-name-nondirectory defdir))
-					 "-autoloads"))
-	  (if force (set-buffer-modified-p
-		     t (find-file-noselect generated-autoload-file))))))
-    (when all-into-one-file
-      (fixup-autoload-buffer (concat (if autoload-package-name
-					 autoload-package-name
-				       (file-name-nondirectory defdir))
-				     "-autoloads"))
-      (if force (set-buffer-modified-p
-		 t (find-file-noselect generated-autoload-file))))
-    (save-some-buffers t)
-    ;; (message "Done")
-    ))
+For backward compatibility, if PREFIX and `autoload-feature-prefix' are both
+`nil', PREFIX is computed as the last directory component of
+`generated-autoload-file'.  This is likely to result in non-uniqueness, so
+do not use this feature."
+  (concat
+   (cond (prefix)
+	 (autoload-feature-prefix)
+	 ((stringp generated-autoload-file)
+	  (message "Warning: autoload computing feature prefix.
+You should specify it as an argument to `autoload-make-feature-name'.")
+	  (file-name-nondirectory
+	   (directory-file-name
+	    (file-name-directory generated-autoload-file))))
+	 (t (error 'invalid-argument
+		   "Could not compute a feature name")))
+   "-autoloads"))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Deprecated entry points
+
+;; A grep of the core and packages shows use of `batch-update-autoloads'
+;; by XEmacs.rules, pcomplete, eshell, oort-gnus; `batch-update-directory'
+;; by liece.
 
 ;; #### these entry points below are a big mess, especially the
 ;; first two.  there don't seem to be very many packages that use the
 ;; first one (the "all-into-one-file" variety), and do they actually
 ;; rely on this functionality? --ben
+;; but XEmacs.rules does, though maybe it doesn't "rely" on it, and
+;; modules do now, and that relies on it. --sjt
 
 ;;;###autoload
 (defun batch-update-autoloads ()
@@ -765,7 +932,9 @@
 (defun batch-update-directory ()
   "Update the autoloads for the directories on the command line.
 Runs `update-file-autoloads' on each file in the given directory, and must
-be used only with -batch."
+be used only with -batch.
+
+Uses and removes the first element of `command-line-args-left'."
   (unless noninteractive
     (error "batch-update-directory is to be used only with -batch"))
   (update-autoload-files command-line-args-left)
@@ -778,7 +947,7 @@
 Runs `update-file-autoloads' on each file in the given directory, and must
 be used only with -batch."
   (unless noninteractive
-    (error "batch-update-directory is to be used only with -batch"))
+    (error "batch-update-one-directory is to be used only with -batch"))
   (let ((arg (car command-line-args-left)))
     (setq command-line-args-left (cdr command-line-args-left))
     (update-autoload-files (list arg))))
@@ -787,14 +956,29 @@
 (defun batch-force-update-one-directory ()
   "Update the autoloads for a single directory on the command line.
 Runs `update-file-autoloads' on each file in the given directory, and must
-be used only with -batch.  Always rewrite the autoloads file, even if
-unchanged."
+be used only with -batch.  Always rewrites the autoloads file, even if
+unchanged.
+
+Uses and removes the first element of `command-line-args-left'."
   (unless noninteractive
-    (error "batch-update-directory is to be used only with -batch"))
+    (error "batch-force-update-directory is to be used only with -batch"))
   (let ((arg (car command-line-args-left)))
     (setq command-line-args-left (cdr command-line-args-left))
     (update-autoload-files (list arg) nil t)))
 
+;; Declare obsolescence
+
+(make-obsolete-variable 'autoload-target-directory
+  "Don't use this.  Bind `generated-autoload-file' to an absolute path.")
+(make-obsolete 'batch-update-autoloads
+	       'autoload-update-directory-autoloads)
+(make-obsolete 'batch-update-directory
+	       'autoload-update-directory-autoloads)
+(make-obsolete 'batch-update-one-directory
+	       'autoload-update-directory-autoloads)
+(make-obsolete 'batch-force-update-one-directory
+	       'autoload-update-directory-autoloads)
+
 (provide 'autoload)
 
 ;;; autoload.el ends here