Subject: Re: [PATCH] Implement XDG Base Directory specification for user-emacs-directory

From: Paul Eggert <[email-masked]>
Date: Sat, 31 Aug 2019 18:24:40 -0700

[Responding belatedly to a 2019-07-28 review that I missed, as I was looking for 
reviews in Bug#583 instead of in the emacs-devel archive. Sorry about that.]

> the test which describes in detail how Emacs finds the init
> file should be in the section by that name; otherwise it makes no
> sense to have that section in the first place.  The "Init File"
> section should just mention the possible places and refer to that
> other section for the details.

I gave it a shot by installing the first attached patch, which also fixes a few 
other confusions and/or inaccuracies that I spotted.

The documentation also needs to be updated to replace ~/.emacs.d, either with 
~/.config/emacs or with something more general, in places where the 
documentation refers to the value of user-emacs-directory. That should be fairly 
mechanical, and can wait until we have the details nailed down.

>> >  (defconst user-emacs-directory
> ...
> Can this be a defconst?

It's been a defconst ever since it was added to Emacs in 2007. However, the 
manual has always said it's a variable and there are quite a few uses of (setq 
user-emacs-directory ...) in the wild, so I installed the second attached patch 
to make it a defvar.

I think the other issues in the review were addressed earlier.
>From 72ab46fefcc8fa2b20204eaa79e1d750e56d8ccf Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sat, 31 Aug 2019 18:16:17 -0700
Subject: [PATCH 1/2] Improve documentation for recent XDG-related changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adjust documentation in the light of Eli’s review here:
https://lists.gnu.org/r/emacs-devel/2019-07/msg00712.html
* doc/emacs/custom.texi (Init File, Find Init):
* doc/lispref/files.texi (Standard File Names):
* doc/lispref/os.texi (Init File):
---
 doc/emacs/custom.texi  | 56 +++++++++++++++++++++++++-----------------
 doc/lispref/files.texi |  7 +++---
 doc/lispref/os.texi    |  7 ++++--
 3 files changed, 43 insertions(+), 27 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d3d7d97120..0c2509e1cd 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2228,25 +2228,10 @@ Init File
   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 @@ Find Init
 @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 @@ Find Init
 
   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 d53fed4ee8..c3b6c39b28 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2822,9 +2822,10 @@ Standard File Names
 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 df21256908..c94e96bde8 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -474,10 +474,13 @@ Init 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
-- 
2.17.1

>From fd8346600c3872fa1dfdd1ce6522799ba40d0dc0 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sat, 31 Aug 2019 18:17:20 -0700
Subject: [PATCH 2/2] Make user-emacs-directory a variable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is in response to Eli’s review here:
https://lists.gnu.org/r/emacs-devel/2019-07/msg00712.html
* lisp/subr.el (user-emacs-directory): defvar, not defconst
---
 lisp/subr.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/subr.el b/lisp/subr.el
index cf6fb108e9..0d7bffb35f 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2937,7 +2937,7 @@ temp-buffer-setup-hook
 This hook is normally set up with a function to put the buffer in Help
 mode.")
 
-(defconst user-emacs-directory
+(defvar user-emacs-directory
   ;; The value does not matter since Emacs sets this at startup.
   nil
   "Directory beneath which additional per-user Emacs-specific files are placed.
-- 
2.17.1