Make emacs prefer an existing ~/.emacs.d to an existing XDG location

* doc/emacs/custom.texi (Find Init): Update description of how Emacs
finds its init file directory and the interaction with
$XDG_CONFIG_HOME
(Early Init File): Correct XDG location of early-init.el

* etc/NEWS: Update description to make it clear the ~/.emacs.d is
preferred, even if the XDG location exists.

* lisp/startup.el: Prefer ~/.emacs.d even if the XDG location exists.

* lib-src/emacsclient.c (open_config): Prefer home directory the XDG
location.

1 files changed, 18 insertions, 19 deletions

diff --git a/etc/NEWS b/etc/NEWS
index c1e00395c84..38fff3f7568 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -161,25 +161,24 @@ Emacs 28.
 * Startup Changes in Emacs 27.1
 
 +++
-** Emacs now uses the XDG convention for init files.
-For example, it looks for init.el in "~/.config/emacs/init.el", and
-similarly for other init files.
-
-The 'XDG_CONFIG_HOME' environment variable (which defaults to "~/.config")
-specifies the parent directory of these and other configuration files,
-and will override their traditional locations (the home directory,
-"~/.emacs.d", etc.).
-
-Emacs will still look for init files in their traditional locations if
-"$XDG_CONFIG_HOME/emacs" does not exist, but "~/.emacs.d" or
-"~/.emacs" does exist, so invoking Emacs with XDG_CONFIG_HOME='/nowhere'
-might be useful if your new-location init files are scrambled, or if
-you want to force Emacs to ignore files under 'XDG_CONFIG_HOME' for
-some other reason.
-
-If neither "$XDG_CONFIG_HOME/emacs" nor "~/.emacs.d" exist, Emacs will
-now default to "$XDG_CONFIG_HOME/emacs", and will create that directory
-and set 'user-emacs-directory' to point to it.
+** Emacs can now use the XDG convention for init files.
+The 'XDG_CONFIG_HOME' environment variable (which defaults to
+"~/.config") specifies the XDG configuration parent directory.  Emacs
+checks for "init.el" and other configuration files inside the "emacs"
+subdirectory of 'XDG_CONFIG_HOME', i.e. "$XDG_CONFIG_HOME/emacs/init.el"
+
+However, Emacs will still initially look for init files in their
+traditional locations if "~/.emacs.d" or "~/.emacs" exist, even if
+"$XDG_CONFIG_HOME/emacs" also exists.  This means that you must delete
+or rename any existing "~/.emacs.d" and "~/.emacs" to enable use of
+the XDG directory.
+
+If "~/.emacs.d" does not exist, and Emacs has decided to use it
+(i.e. "$XDG_CONFIG_HOME/emacs" does not exist), Emacs will create it.
+Emacs will never create "$XDG_CONFIG_HOME/emacs".
+
+Whichever directory Emacs decides to use, it will set
+'user-emacs-directory' to point to it.
 
 +++
 ** Emacs can now be configured using an early init file.