bug#42388: 27.0.91; Manual is inconsistent about default init file location

[Robert Pluim]

>>>>> 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