Improve documentation of '--init-directory' command-line option.

* doc/emacs/custom.texi (Find Init):
* doc/emacs/cmdargs.texi (Initial Options): More accurate and
detailed description of what '--init-directory' does and how it
affects the Emacs session.  Add index entries and cross-references
as needed.  (Bug#72294)

2 files changed, 17 insertions, 1 deletions

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 49810ee7693..cd7d2be6d2f 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -351,6 +351,16 @@ Do not include the @file{site-lisp} directories in @code{load-path}
 @item --init-directory
 @opindex --init-directory
 Specify the directory to use when looking for the Emacs init files.
+Note that this merely overrides the value of
+@file{user-emacs-directory}, the directory which Emacs usually
+determines as side effect of searching for your init file (@pxref{Find
+Init}), but does not change the search for the init file.  In
+particular, if there's no init file in the directory named by this
+option, Emacs will find and use the init file it would have used without
+this option (but will search for your other per-user Emacs files in the
+directory specified by this option).  If you want to force Emacs to use
+the init file in this directory, make sure it exists there before
+starting Emacs with this option.
 
 @item --no-splash
 @opindex --no-splash
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 1527e42bbfe..4b16410eeec 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2958,8 +2958,14 @@ Note also that if neither the XDG location nor @file{~/.emacs.d}
 exist, then Emacs will create @file{~/.emacs.d} (and therefore use it
 during subsequent invocations).
 
+@vindex user-emacs-directory
 Emacs will set @code{user-emacs-directory} to the directory it decides
-to use.
+to use.  This directory is subsequently used to look for your other
+user-specific Emacs files, such as @code{custom-file} (@pxref{Saving
+Customizations}), the saved desktop (@pxref{Saving Emacs Sessions}) and
+others.  The @code{--init-directory} command-line option (@pxref{Initial
+Options}) overrides the value of @code{user-emacs-directory} determined
+as side effect of the search for your user init file described above.
 
 Although this is backward-compatible with older Emacs versions, modern
 POSIX platforms prefer putting your initialization files under