3 files changed, 43 insertions, 27 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d3d7d97120a..0c2509e1cd6 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2228,25 +2228,10 @@ as a function from Lisp programs.
   When Emacs is started, it normally tries to load a Lisp program from
 an @dfn{initialization file}, or @dfn{init file} for short.  This
 file, if it exists, specifies how to initialize Emacs for you.
-If the directory @file{@var{xdghome}/.config/emacs} exists, Emacs uses
-@file{@var{xdghome}/.config/emacs/init.el} as the init file.  Here,
-@var{xdghome} stands for the value of the environment variable
-@env{XDG_CONFIG_HOME}, or for @file{~/.config} if
-@env{XDG_CONFIG_HOME} is unset; @file{~/} stands for your home
-directory.
-
-  If @file{~/.config/emacs} does not exist, Emacs looks for your init
-file using the filenames @file{~/.emacs}, @file{~/.emacs.el}, or
-@file{~/.emacs.d/init.el}; you can choose to use any one of these
-names (@pxref{Find Init}).  Although this is backward-compatible
-with older Emacs versions, modern POSIX platforms prefer putting your
-initialization files under @file{.config} so that if you have
-to troubleshoot a problem that might be due to a bad init file, or
-archive a collection of them, it can be done by renaming or
-copying that directory.  Note that the @file{.config} versions
-don't have a leading dot on the basename part of the file.
-For convenience the rest of this section assumes @env{XDG_CONFIG_HOME}
-is unset or has a value equivalent to @file{~/.config}.
+If the file @file{~/.config/emacs/init.el} exists, it is used as the
+init file; otherwise Emacs may look at @file{~/.emacs.el},
+@file{~/.emacs}, @file{~/.emacs.d/init.el}, or other locations.
+@xref{Find Init}.
 
   You can use the command line switch @samp{-q} to prevent loading
 your init file, and @samp{-u} (or @samp{--user}) to specify a
@@ -2652,8 +2637,31 @@ library.  @xref{Hooks}.
 @subsection How Emacs Finds Your Init File
 
   Emacs normally finds your init file in a location under your home
-directory, e.g., @file{~/.config/emacs/init.el} or
-@file{~/.emacs.d/init.el}.  @xref{Init File}.
+directory.  @xref{Init File}.  By default this location is
+@file{~/.config/emacs/init.el} where @file{~/} stands for your home directory.
+This default can be overridden as described below.
+
+  If @env{XDG_CONFIG_HOME} is set in your environment, its
+value replaces @file{~/.config} in the name of the default
+init file.
+
+  If the default init file's parent directory does not exist but the
+directory @file{~/.emacs.d} does exist, Emacs looks for your init file
+using the filenames @file{~/.emacs.el}, @file{~/.emacs}, or
+@file{~/.emacs.d/init.el}; you can choose to use any one of these
+names.  (Note that only the locations directly in your home directory
+have a leading dot in the location's basename.)  Although this is
+backward-compatible with older Emacs versions, modern POSIX platforms
+prefer putting your initialization files under @file{~/.config} so
+that troubleshooting a problem that might be due to a bad init file,
+or archiving a collection of init files, can be done by renaming that
+directory.  To help older Emacs versions find configuration files in
+their current default locations, you can execute the following
+Emacs Lisp code:
+
+@example
+(make-symbolic-link ".config/emacs" "~/.emacs.d")
+@end example
 
   However, if you run Emacs from a shell started by @code{su} and
 @env{XDG_CONFIG_HOME} is not set in your environment, Emacs
@@ -2663,10 +2671,14 @@ editor customizations even if you are running as the super user.
 
   More precisely, Emacs first determines which user's init file to use.
 It gets your user name from the environment variables @env{LOGNAME} and
-@env{USER}; if neither of those exists, it uses effective user-ID@.
+@env{USER}; if neither of those exists, it uses the effective user-ID@.
 If that user name matches the real user-ID, then Emacs uses @env{HOME};
 otherwise, it looks up the home directory corresponding to that user
 name in the system's data base of users.
+
+  For brevity the rest of the Emacs documentation generally uses just
+the current default location @file{~/.config/emacs/init.el} for the
+init file.
 @c  LocalWords:  backtab
 
 @node Init Non-ASCII
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index d53fed4ee87..c3b6c39b283 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2822,9 +2822,10 @@ filter out a directory named @file{foo.elc}.
 name for a particular use---typically, to hold configuration data
 specified by the current user.  Usually, such files should be located
 in the directory specified by @code{user-emacs-directory}, which is
-@file{~/.config/emacs} or @file{~/.emacs.d} by default (@pxref{Init
-File}).  For example, abbrev definitions are stored by default in
-@file{~/.config/emacs/abbrev_defs} or @file{~/.emacs.d/abbrev_defs}.
+typically @file{~/.config/emacs} by default (@pxref{Find
+Init,,How Emacs Finds Your Init File, emacs, The GNU Emacs Manual}).
+For example, abbrev definitions are stored by default in
+@file{~/.config/emacs/abbrev_defs}.
 The easiest way to specify such a file name is to use the function
 @code{locate-user-emacs-file}.
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index df212569087..c94e96bde82 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -474,10 +474,13 @@ the value refers to the corresponding source file.
 
 @defvar user-emacs-directory
 This variable holds the name of the Emacs default directory.
-It is @file{@var{xdghome}/emacs/} if that directory exists, otherwise
-@file{~/.emacs.d/} on all platforms but MS-DOS.  Here, @var{xdghome}
+It defaults to @file{$@{XDG_CONFIG_HOME-'~/.config'@}/emacs/}
+if that directory exists and @file{~/.emacs.d/} does not exist,
+otherwise to @file{~/.emacs.d/} on all platforms but MS-DOS@.
+Here, @file{$@{XDG_CONFIG_HOME-'~/.config'@}}
 stands for the value of the environment variable @env{XDG_CONFIG_HOME}
 if that variable is set, and for @file{~/.config} otherwise.
+@xref{Find Init,,How Emacs Finds Your Init File, emacs, The GNU Emacs Manual}.
 @end defvar
 
 @node Terminal-Specific