[Emacs-diffs] master d68ed15: Implement and document XDG-style startup files under ~/.config.

[Eric S. Raymond]

branch: master
commit d68ed152ffe4369b3fe082cf39d631cc5360143b
Author: Eric S. Raymond <address@hidden>
Commit: Eric S. Raymond <address@hidden>

    Implement and document XDG-style startup files under ~/.config.
    
    * lisp/startup.el (command-line): Allow XDG-style as well as old
     style init paths.
    * doc/startup.texi: Document the above change.
---
 ChangeLog.3           |  8 ++++++++
 doc/emacs/custom.texi | 46 ++++++++++++++++++++++++++++++----------------
 lisp/startup.el       | 17 +++++++++++++----
 3 files changed, 51 insertions(+), 20 deletions(-)

diff --git a/ChangeLog.3 b/ChangeLog.3
index e7f4d86..fbaf813 100644
--- a/ChangeLog.3
+++ b/ChangeLog.3
@@ -1,3 +1,11 @@
+2019-05-25  Eric S. Raymond <address@hidden>
+
+       Implement and document XDG-style startup files under ~/.config.
+
+       * lisp/startup.el (command-line): Allow XDG-style as well as old
+       style paths.
+       * doc/startup.texi: Document the above change.
+
 2019-04-11  Eli Zaretskii  <address@hidden>
 
        Improve documentation of 'read-command'
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index bdd6dec..982cea1 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -380,7 +380,7 @@ lines of code to your initialization file, to set the 
variable
 file.  For example:
 
 @example
-(setq custom-file "~/.emacs-custom.el")
+(setq custom-file "~/.config/emacs-custom.el")
 (load custom-file)
 @end example
 
@@ -390,14 +390,14 @@ Emacs versions, like this:
 @example
 (cond ((< emacs-major-version 22)
        ;; @r{Emacs 21 customization.}
-       (setq custom-file "~/.custom-21.el"))
+       (setq custom-file "~/.config/custom-21.el"))
       ((and (= emacs-major-version 22)
             (< emacs-minor-version 3))
        ;; @r{Emacs 22 customization, before version 22.3.}
-       (setq custom-file "~/.custom-22.el"))
+       (setq custom-file "~/.config/custom-22.el"))
       (t
        ;; @r{Emacs version 22.3 or later.}
-       (setq custom-file "~/.emacs-custom.el")))
+       (setq custom-file "~/.config/emacs-custom.el")))
 
 (load custom-file)
 @end example
@@ -2215,16 +2215,28 @@ as a function from Lisp programs.
 @cindex init file
 @cindex .emacs file
 @cindex ~/.emacs file
address@hidden ~/.config/emacs file
 @cindex Emacs initialization file
 @cindex startup (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.  Emacs
-looks for your init file using the filenames @file{~/.emacs},
address@hidden/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to
-use any one of these three names (@pxref{Find Init}).  Here, @file{~/}
-stands for your home directory.
+looks for your init file using the filenames
address@hidden/.config/emacs},. @file{~/.emacs}, @file{~/.config/emacs.el},
address@hidden/.emacs.el}, @file{~/.config/emacs.d/init.el} or
address@hidden/.emacs.d/init.el}; you can choose to use any one of these
+names (@pxref{Find Init}).  Here, @file{~/} stands for your home
+directory.
+
+  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.
 
   You can use the command line switch @samp{-q} to prevent loading
 your init file, and @samp{-u} (or @samp{--user}) to specify a
@@ -2630,14 +2642,16 @@ library.  @xref{Hooks}.
 @node Find Init
 @subsection How Emacs Finds Your Init File
 
-  Normally Emacs uses your home directory to find @file{~/.emacs};
-that's what @samp{~} means in a file name.  @xref{General Variables, HOME}.
-If neither @file{~/.emacs} nor @file{~/.emacs.el} is found, Emacs looks for
address@hidden/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
-byte-compiled).
+  Normally Emacs uses your home directory to find
address@hidden/.config/emacs} or @file{~/.emacs}; that's what @samp{~} means
+in a file name.  @xref{General Variables, HOME}.  If none of
address@hidden/.config/emacs}, @file{~/.emacs}, @file{~/.config/emacs.el} nor
address@hidden/.emacs.el} is found, Emacs looks for
address@hidden/.config/emacs.d/init.el} or @file{~/.emacs.d/init.el} (these,
+like @file{~/.emacs.el}, can be byte-compiled).
 
   However, if you run Emacs from a shell started by @code{su}, Emacs
-tries to find your own @file{.emacs}, not that of the user you are
+tries to find your own initialization files, not that of the user you are
 currently pretending to be.  The idea is that you should get your own
 editor customizations even if you are running as the super user.
 
@@ -2688,10 +2702,10 @@ Type @kbd{C-q}, followed by the key you want to bind, 
to insert @var{char}.
 @cindex early init file
 
   Most customizations for Emacs should be put in the normal init file,
address@hidden or @file{~/.emacs.d/init.el}.  However, it is sometimes desirable
address@hidden/emacs} or @file{~/.config/emacs.d/init.el}.  However, it is 
sometimes desirable
 to have customizations that take effect during Emacs startup earlier than the
 normal init file is processed.  Such customizations can be put in the early
-init file, @file{~/.emacs.d/early-init.el}.  This file is loaded before the
+init file, @file{~/.config/emacs.d/early-init.el} or 
@file{~/.emacs.d/early-init.el}.  This file is loaded before the
 package system and GUI is initialized, so in it you can customize variables
 that affect frame appearance as well as the package initialization process,
 such as @code{package-enable-at-startup}, @code{package-load-list}, and
diff --git a/lisp/startup.el b/lisp/startup.el
index a88118e..f853cec 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1,4 +1,4 @@
-;;; startup.el --- process Emacs shell arguments  -*- lexical-binding: t -*-
+;; startup.el --- process Emacs shell arguments  -*- lexical-binding: t -*-
 
 ;; Copyright (C) 1985-1986, 1992, 1994-2019 Free Software Foundation,
 ;; Inc.
@@ -970,6 +970,15 @@ the `--debug-init' option to view a complete error 
backtrace."
     (when debug-on-error-should-be-set
       (setq debug-on-error debug-on-error-from-init-file))))
 
+(defun find-init-path (fn)
+  "Look in ~/.config/FOO or ~/.FOO for the dotfile or dot directory FOO.
+It is expected that the output will undergo ~ expansion.  Implements the
+XDG convention for dotfiles."
+  (let* ((xdg-path (concat "~" init-file-user "/.config/" fn))
+        (oldstyle-path (concat "~" init-file-user "/." fn))
+        (found-path (if (file-exists-p xdg-path) xdg-path oldstyle-path)))
+    found-path))
+
 (defun command-line ()
   "A subroutine of `normal-top-level'.
 Amongst another things, it parses the command-line arguments."
@@ -1171,7 +1180,7 @@ please check its value")
       ;; "early-init" without an extension, as it does for ".emacs".
       "early-init.el"
       (file-name-as-directory
-       (concat "~" init-file-user "/.emacs.d")))))
+       (find-init-path "emacs.d")))))
   (setq early-init-file user-init-file)
 
   ;; If any package directory exists, initialize the package system.
@@ -1312,7 +1321,7 @@ please check its value")
         ((eq system-type 'ms-dos)
          (concat "~" init-file-user "/_emacs"))
         ((not (eq system-type 'windows-nt))
-         (concat "~" init-file-user "/.emacs"))
+         (find-init-path "emacs"))
         ;; Else deal with the Windows situation.
         ((directory-files "~" nil "^\\.emacs\\(\\.elc?\\)?$")
          ;; Prefer .emacs on Windows.
@@ -1330,7 +1339,7 @@ please check its value")
        (expand-file-name
         "init"
         (file-name-as-directory
-         (concat "~" init-file-user "/.emacs.d"))))
+         (find-init-path "emacs.d"))))
      (not inhibit-default-init))
 
     (when (and deactivate-mark transient-mark-mode)