Re: [PATCH] Implement XDG Base Directory specification for user-emacs-directory (was: [Emacs-diffs] master d68ed15: Implement and document XDG-style startup files under ~/.config.)

[Eli Zaretskii]

> From: Amin Bandali <address@hidden>
> Cc: Eli Zaretskii <address@hidden>,  Stefan Monnier <address@hidden>
> Date: Sun, 09 Jun 2019 03:01:22 -0400
> 
> > Would someone like to suggest changes to fix the problems in this
> > commit?  If so, please show the proposed changes, and let's discuss
> > them.  Failing that, I will revert that commit in a couple of days.
> 
> I’ve attached my first try at this.  At first it was only concerned with
> lisp/startup.el—like ESR’s change—but then I thought it would be even
> nicer to do it at the user-emacs-directory itself.  It’s not quite there
> yet—as it tries to use things in lisp/subr.el before they’re actually
> defined/loaded—but it lays out what I have in mind.

Thanks.

> Feedback and help appreciated.

Below.

> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index 982cea1f21..b582601cae 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -380,7 +380,7 @@ Saving Customizations
>  file.  For example:
>  
>  @example
> -(setq custom-file "~/.config/emacs-custom.el")
> +(setq custom-file "~/.config/emacs/custom.el")
>  (load custom-file)
>  @end example

I question the need to modify the examples in this chapter of the
manual.  They are not directly related to the issue at hand.  If
Eric's changeset modified these parts, I'd rather just revert to what
the text said before.

>    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.  Emacs
> -looks for your init file using the filenames
> -@file{~/.config/emacs},. @file{~/.emacs}, @file{~/.config/emacs.el},
> -@file{~/.emacs.el}, @file{~/.config/emacs.d/init.el} or
> -@file{~/.emacs.d/init.el}; you can choose to use any one of these
> -names (@pxref{Find Init}).  Here, @file{~/} stands for your home
> -directory.
> +looks for your init file using the filenames @file{~/.emacs} or
> +@file{~/.emacs.el}.  Here, @file{~/} stands for your home directory.
> +Alternatively, you may wish to group all things Emacs-related in one
> +place in the Emacs configuration directory.  Emacs looks for
> +@file{$XDG_CONFIG_HOME/emacs/init.el}, using @file{~/.config} for
> +@env{XDG_CONFIG_HOME} if it's not set.  If
> +@file{$XDG_CONFIG_HOME/emacs/} doesn't exist, Emacs will fall back to
> +@file{~/.emacs.d/} and look for @file{~/.emacs.d/init.el} instead
> +(@pxref{Find Init}).

This text is slightly confusing: the part which begins with "Emacs
looks for @file{$XDG_CONFIG_HOME/emacs/init.el}" should tell whether
Emacs looks for the XDG tree before or after looking for ~/.emacs and
~/.emacs.el, otherwise I as a user cannot figure out how to make Emacs
find my init files regardless of whether I want or don't want to go
the XDG way.  Also missing is an explanation of what happens if
XDG_CONFIG_HOME is defined, but the Emacs directory does not exist
there.  the last sentence, which talks about ~/.emacs.d/init.el, adds
more to the confusion, because again the order of examining all these
possibilities is left largely unspecified or at least not entirely
clear.  Maybe arranging the description as an ordered itemized list
would help.

Markup-wise, "@file{$XDG_CONFIG_HOME/emacs/init.el}" uses the Unix
shell $FOO notation, something that we avoid in the manuals.  I
suggest to say something like

  Emacs looks for @file{@var{xdg-home}/emacs/init.el}, where
  @var{xdg-home} is the value of the environment variable
  @env{XDG_CONFIG_HOME} or @file{~/.config} if that variable is not
  defined.

>    While the @file{~/.emacs} and @file{~/.emacs.d/init.el} locations
>  are backward-compatible to older Emacs versions, and the rest of this
> -chapter will use them to name your initialization file, it is better practice
> -to group all of your dotfiles 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.
> +chapter will use them to name your initialization file, it is better
> +practice to group all of your dotfiles under @file{~/.config} so that

I cannot say I like the "better" qualification here.  This is in the
eyes of the beholder.  I think we should say that "modern Posix
platforms prefer to group all of your dotfiles under
@file{~/.config}..." and leave the judgmental part out of the text.
(as an aside, why say ~/.config here and not the directory pointed to
by XDG_CONFIG_HOME?)

> +  Normally Emacs uses your home directory to find @file{~/.emacs}
> +(@samp{~} refers to the user's home directory in a file name).

The last part should reorder words:

  (@samp{~} in a file name refers to the user's home directory)

> +@xref{General Variables, HOME}.  If neither @file{~/.emacs} nor
>  @file{~/.emacs.el} is found, Emacs looks for
> -@file{~/.config/emacs.d/init.el} or @file{~/.emacs.d/init.el} (these,
> -like @file{~/.emacs.el}, can be byte-compiled).
> +@file{$XDG_CONFIG_HOME/emacs/init.el}, substituting @file{~/.config}
> +for @env{XDG_CONFIG_HOME} if it's not set.  If neither of these exist,
> +Emacs will look for @file{~/.emacs.d/init.el}.  These, like
> +@file{~/.emacs.el}, can be byte-compiled.

Similar comments here, although this description is somewhat more
clear regarding the order of looking for init files.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -24,6 +24,12 @@ When you add a new item, use the appropriate mark if you 
> are sure it applies,
>  
>  * Installation Changes in Emacs 27.1
>  
> +** Emacs now supports XDG Base Directory specification

The header line should end in a period.

> +Emacs now uses "$XDG_CONFIG_HOME/emacs/" for 'user-emacs-directory' if

Again, let's not use $FOO notation in documentation.

> diff --git a/lisp/subr.el b/lisp/subr.el
> index 73031a2a9f..dc2a4d8373 100644
> --- a/lisp/subr.el
> +++ b/lisp/subr.el
> @@ -2924,7 +2924,11 @@ user-emacs-directory
>    (if (eq system-type 'ms-dos)
>        ;; MS-DOS cannot have initial dot.
>        "~/_emacs.d/"
> -    "~/.emacs.d/")
> +    (let ((config-dir (or (getenv "XDG_CONFIG_HOME")
> +                          (concat "~" init-file-user "/.config"))))
> +      (if (file-exists-p config-dir)
> +          (concat config-dir "/emacs/")
> +        (concat "~" init-file-user "/.emacs.d/"))))
>    "Directory beneath which additional per-user Emacs-specific files are 
> placed.

user-emacs-directory is a defconst, so calling getenv to compute its
value will record the value of the environment variable at Emacs build
time, which is not what we want, AFAIU.  Moreover, init-file-user is
most probably also not yet computed, and definitely doesn't correspond
to the user who will run the dumped Emacs, right?  So I think this
should be rethought: if you want user-emacs-directory to absorb these
changes, it cannot be computed at build time, and cannot be a
defconst.

Also, there are quite a few places in our sources which mention
user-emacs-directory; they need to be audited to determine whether
redirecting the value to XDG_CONFIG_HOME/emacs will do what the users
expect (as I understand XDG_CONFIG_HOME is a per-session setting that
can change for the next session).