[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#42388: 27.0.91; Manual is inconsistent about default init file locat
From: |
Robert Pluim |
Subject: |
bug#42388: 27.0.91; Manual is inconsistent about default init file location |
Date: |
Thu, 16 Jul 2020 19:00:04 +0200 |
>>>>> On Thu, 16 Jul 2020 07:23:36 -0300, "Jorge P. de Morais Neto"
>>>>> <jorge@disroot.org> said:
Jorge> The manual at [[info:emacs#Find Init]] says:
Jorge> Emacs can also look in an XDG-compatible location for
‘init.el’,
Jorge> the default is the directory ‘~/.config/emacs’. This can be
Jorge> overriden by setting ‘XDG_CONFIG_HOME’ in your environment, its
Jorge> value replaces ‘~/.config’ in the name of the default XDG init
file.
Jorge> However ‘~/.emacs.d’ and ‘~/.emacs’ are always preferred if they
Jorge> exist, which means that you must delete or rename them in order
to
Jorge> use the XDG location.
Jorge> However, at [[info:emacs#Init File]] it says:
Jorge> When Emacs is started, it normally tries to load a Lisp program
from
Jorge> an “initialization file”, or “init file” for short. This file,
if
Jorge> it exists, specifies how to initialize Emacs for you. If the
file
Jorge> ‘~/.config/emacs/init.el’ exists, it is used as the init file;
Jorge> otherwise Emacs may look at ‘~/.emacs.el’, ‘~/.emacs’,
Jorge> ‘~/.emacs.d/init.el’, or other locations. *Note Find Init::.
Jorge> So [[info:emacs#Find Init]] says that `~/.emacs.d' and `~/.emacs' are
Jorge> preferred, while [[info:emacs#Init File]] says that
Jorge> `~/.config/emacs/init.el' is preferred.
Yes, that is indeed inconsistent, I missed that part of the manual
when flipping the XDG preference.
I thought this would be a simple change, but as ever the rabbit hole
was deep. Based on testing '~/.emacs.el' is preferred to '~/.emacs',
is that expected? Anyway, I came up with the following:
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 719e09e861..00c8ee4f98 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2252,10 +2252,13 @@ 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 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}.
+Traditionally, file @file{~/.emacs} is used as the init file, although
+Emacs also looks at @file{~/.emacs.el}, @file{~/.emacs.d/init.el},
+@file{~/.config/emacs/init.el}, or other locations. @xref{Find Init}.
+
+You may find it convenient to have all your Emacs configuration in one
+directory, in which case you should use @file{~/.emacs.d/init.el} or
+the XDG-compatible @file{~/.config/emacs/init.el}.
You can use the command line switch @samp{-q} to prevent loading
your init file, and @samp{-u} (or @samp{--user}) to specify a
@@ -2661,23 +2664,21 @@ Find Init
@subsection How Emacs Finds Your Init File
Emacs normally finds your init file in a location under your home
-directory. @xref{Init File}. By default this location is
-@file{~/.emacs.d/init.el} where @file{~/} stands for your home directory.
-This default can be overridden as described below.
+directory. @xref{Init File}.
-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.)
+ Emacs looks for your init file using the filenames @file{~/.emacs.el},
+@file{~/.emacs}, or @file{~/.emacs.d/init.el} in that order; 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.)
Emacs can also look in an XDG-compatible location for @file{init.el},
the default is the directory @file{~/.config/emacs}. This can be
overriden by setting @env{XDG_CONFIG_HOME} in your environment, its
value replaces @file{~/.config} in the name of the default XDG init
-file. However @file{~/.emacs.d} and @file{~/.emacs} are always
-preferred if they exist, which means that you must delete or rename
-them in order to use the XDG location.
+file. However @file{~/.emacs.d}, @file{~/.emacs}, and
+@file{~/.emacs.el} are always preferred if they exist, which means
+that you must delete or rename them in order to use the XDG location.
Note also that if neither the XDG location nor @file{~/.emacs.d}
exist, then Emacs will create @file{~/.emacs.d} (and therefore use it