Commit 72ab46fe authored by Paul Eggert's avatar Paul Eggert
Browse files

Improve documentation for recent XDG-related changes

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):
parent 02a74ed3
......@@ -2228,25 +2228,10 @@ as a function from Lisp programs.
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 @@ library. @xref{Hooks}.
@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 @@ editor customizations even if you are running as the super user.
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
......
......@@ -2822,9 +2822,10 @@ filter out a directory named @file{foo.elc}.
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}.
......
......@@ -474,10 +474,13 @@ the value refers to the corresponding source 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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment