From 72ab46fefcc8fa2b20204eaa79e1d750e56d8ccf Mon Sep 17 00:00:00 2001 From: Paul Eggert 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