bug#49424: 27.2; Misdocumented default initialisation file

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

The info page “49.4.4 How Emacs Finds Your Init File” says:

> For brevity the rest of the Emacs documentation generally uses just
> the current default location ‘~/.emacs.d/init.el’ for the init file.

However, this seems to be inaccurate: if I start Emacs as a new user and make a customisation, that customisation is written to ~/.emacs.  


In GNU Emacs 27.2 (build 1, x86_64-redhat-linux-gnu, GTK+ Version 3.24.29, cairo version 1.17.4)
 of 2021-05-25 built on 67aec83703474aab90196a48063fea20
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Fedora 34 (Workstation Edition)

Configured using:
 'configure --build=x86_64-redhat-linux-gnu
 --host=x86_64-redhat-linux-gnu --program-prefix=
 --disable-dependency-tracking --prefix=/usr --exec-prefix=/usr
 --bindir=/usr/bin --sbindir=/usr/sbin --sysconfdir=/etc
 --datadir=/usr/share --includedir=/usr/include --libdir=/usr/lib64
 --libexecdir=/usr/libexec --localstatedir=/var
 --sharedstatedir=/var/lib --mandir=/usr/share/man
 --infodir=/usr/share/info --with-dbus --with-gif --with-jpeg --with-png
 --with-rsvg --with-tiff --with-xft --with-xpm --with-x-toolkit=gtk3
 --with-gpm=no --with-xwidgets --with-modules --with-harfbuzz
 --with-cairo --with-json build_alias=x86_64-redhat-linux-gnu
 host_alias=x86_64-redhat-linux-gnu CC=gcc 'CFLAGS=-DMAIL_USE_LOCKF -O2
 -flto=auto -ffat-lto-objects -fexceptions -g -grecord-gcc-switches
 -pipe -Wall -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2
 -Wp,-D_GLIBCXX_ASSERTIONS
 -specs=/usr/lib/rpm/redhat/redhat-hardened-cc1 -fstack-protector-strong
 -specs=/usr/lib/rpm/redhat/redhat-annobin-cc1 -m64 -mtune=generic
 -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection'
 LDFLAGS=-Wl,-z,relro
 PKG_CONFIG_PATH=:/usr/lib64/pkgconfig:/usr/share/pkgconfig'

Configured features:
XPM JPEG TIFF GIF PNG RSVG CAIRO SOUND DBUS GSETTINGS GLIB NOTIFY
INOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE HARFBUZZ M17N_FLT LIBOTF
ZLIB TOOLKIT_SCROLL_BARS GTK3 X11 XDBE XIM MODULES THREADS XWIDGETS
LIBSYSTEMD JSON PDUMPER GMP

-- 
Peter Oliver

bug#49424: 27.2; Misdocumented default initialisation file

[Lars Ingebrigtsen]

Peter Oliver <p.d.oliver@mavit.org.uk> writes:

> The info page “49.4.4 How Emacs Finds Your Init File” says:
>
>> For brevity the rest of the Emacs documentation generally uses just
>> the current default location ‘~/.emacs.d/init.el’ for the init file.
>
> However, this seems to be inaccurate: if I start Emacs as a new user
> and make a customisation, that customisation is written to ~/.emacs.

That is indeed the case still in Emacs 28 -- I thought we'd changed that
to prefer either XDG paths or ~/.emacs.d/init.el when there's no
previous init file?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Tue, 06 Jul 2021 17:11:38 +0200, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> Peter Oliver <p.d.oliver@mavit.org.uk> writes:
    >> The info page “49.4.4 How Emacs Finds Your Init File” says:
    >> 
    >>> For brevity the rest of the Emacs documentation generally uses just
    >>> the current default location ‘~/.emacs.d/init.el’ for the init file.
    >> 
    >> However, this seems to be inaccurate: if I start Emacs as a new user
    >> and make a customisation, that customisation is written to ~/.emacs.

Yes, we should change that to say '~/.emacs'

    Lars> That is indeed the case still in Emacs 28 -- I thought we'd changed that
    Lars> to prefer either XDG paths or ~/.emacs.d/init.el when there's no
    Lars> previous init file?

Emacs will prefer the XDG path if it exists and .emacs.d/init.el and
.emacs donʼt. Similarly Emacs will prefer .emacs.d/init.el if it
exists and .emacs doesnʼt.

If nothing exists, Emacs will create ~/.emacs.d, and use ~/.emacs as
the init file. We can change that to use ~/.emacs.d/init.el if we
want, people who already have init files will not be affected.
</bold prediction of there being no consequences>

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Rudolf Schlatte]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Tue, 06 Jul 2021 17:11:38 +0200, Lars Ingebrigtsen <larsi@gnus.org> said:
>
>     Lars> Peter Oliver <p.d.oliver@mavit.org.uk> writes:
>     >> The info page “49.4.4 How Emacs Finds Your Init File” says:
>     >> 
>     >>> For brevity the rest of the Emacs documentation generally uses just
>     >>> the current default location ‘~/.emacs.d/init.el’ for the init file.
>     >> 
>     >> However, this seems to be inaccurate: if I start Emacs as a new user
>     >> and make a customisation, that customisation is written to ~/.emacs.
>
> Yes, we should change that to say '~/.emacs'
>
>     Lars> That is indeed the case still in Emacs 28 -- I thought we'd changed that
>     Lars> to prefer either XDG paths or ~/.emacs.d/init.el when there's no
>     Lars> previous init file?
>
> Emacs will prefer the XDG path if it exists and .emacs.d/init.el and
> .emacs donʼt. Similarly Emacs will prefer .emacs.d/init.el if it
> exists and .emacs doesnʼt.

I wonder if it would make sense to warn during startup if more than one
of these files exist, something like: "Warning: multiple init files
detected.  Using ~/.emacs as init file, ignoring ~/.emacs.d/init.el"

bug#49424: 27.2; Misdocumented default initialisation file

[Phil Sainty]

On 2021-07-07 21:17, Robert Pluim wrote:
> If nothing exists, Emacs will create ~/.emacs.d, and use ~/.emacs as
> as the init file. We can change that to use ~/.emacs.d/init.el if we
> want, people who already have init files will not be affected.
> </bold prediction of there being no consequences>

I know of people who have ~/.emacs.d under version control (used on
multiple machines), and on some machines additionally have a ~/.emacs
file for config which is local to that particular machine.  The .emacs
file simply loads the init.el file.

There are other ways of achieving the same thing; but I thought this
one was quite a neat approach when I heard it.

In other words, FYI some people's configs are definitely reliant on
the current precedence order.

In any case, while the sequence *could* be changed for those two
files, I don't think there's any notable benefit to doing so?  Even
ignoring cases like the one above, that change would undoubtedly
cause some confusion for no good reason.


-Phil

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Thu, 08 Jul 2021 00:24:22 +1200, Phil Sainty <psainty@orcon.net.nz> said:

    Phil> On 2021-07-07 21:17, Robert Pluim wrote:
    >> If nothing exists, Emacs will create ~/.emacs.d, and use ~/.emacs as
    >> as the init file. We can change that to use ~/.emacs.d/init.el if we
    >> want, people who already have init files will not be affected.
    >> </bold prediction of there being no consequences>

    Phil> I know of people who have ~/.emacs.d under version control (used on
    Phil> multiple machines), and on some machines additionally have a ~/.emacs
    Phil> file for config which is local to that particular machine.  The .emacs
    Phil> file simply loads the init.el file.

Thatʼs a different branch of the startup logic :-)

If we change things so that ~/.emacs.d/init.el is used only if there
is no .emacs, they would not be affected. I think this is already
the case, but I may be misremembering

    Phil> There are other ways of achieving the same thing; but I thought this
    Phil> one was quite a neat approach when I heard it.

    Phil> In other words, FYI some people's configs are definitely reliant on
    Phil> the current precedence order.

    Phil> In any case, while the sequence *could* be changed for those two
    Phil> files, I don't think there's any notable benefit to doing so?  Even
    Phil> ignoring cases like the one above, that change would undoubtedly
    Phil> cause some confusion for no good reason.

Iʼm not proposing changing the sequence, only what happens in the case
where there are no init files at all. It would eliminate the 'why is
emacs creating .emacs.d but then not using it' confusion.

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Wed, 07 Jul 2021 13:28:30 +0200, Rudolf Schlatte <rudi@constantly.at> said:

    Rudolf> Robert Pluim <rpluim@gmail.com> writes:

    >> Emacs will prefer the XDG path if it exists and .emacs.d/init.el and
    >> .emacs donʼt. Similarly Emacs will prefer .emacs.d/init.el if it
    >> exists and .emacs doesnʼt.

    Rudolf> I wonder if it would make sense to warn during startup if more than one
    Rudolf> of these files exist, something like: "Warning: multiple init files
    Rudolf> detected.  Using ~/.emacs as init file, ignoring ~/.emacs.d/init.el"

A warning prominent enough for people to notice would also be annoying
enough that people would complain about us changing the status quo out
from under them. The best we could do is putting something in
*Messages*, I suspect

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Stephen Berman]

On Wed, 07 Jul 2021 15:08:21 +0200 Robert Pluim <rpluim@gmail.com> wrote:

>>>>>> On Thu, 08 Jul 2021 00:24:22 +1200, Phil Sainty <psainty@orcon.net.nz> said:
>
>     Phil> On 2021-07-07 21:17, Robert Pluim wrote:
>     >> If nothing exists, Emacs will create ~/.emacs.d, and use ~/.emacs as
>     >> as the init file. We can change that to use ~/.emacs.d/init.el if we
>     >> want, people who already have init files will not be affected.
>     >> </bold prediction of there being no consequences>
>
>     Phil> I know of people who have ~/.emacs.d under version control (used on
>     Phil> multiple machines), and on some machines additionally have a ~/.emacs
>     Phil> file for config which is local to that particular machine.  The .emacs
>     Phil> file simply loads the init.el file.
>
> Thatʼs a different branch of the startup logic :-)
>
> If we change things so that ~/.emacs.d/init.el is used only if there
> is no .emacs, they would not be affected. I think this is already
> the case, but I may be misremembering
>
>     Phil> There are other ways of achieving the same thing; but I thought this
>     Phil> one was quite a neat approach when I heard it.
>
>     Phil> In other words, FYI some people's configs are definitely reliant on
>     Phil> the current precedence order.
>
>     Phil> In any case, while the sequence *could* be changed for those two
>     Phil> files, I don't think there's any notable benefit to doing so?  Even
>     Phil> ignoring cases like the one above, that change would undoubtedly
>     Phil> cause some confusion for no good reason.
>
> Iʼm not proposing changing the sequence, only what happens in the case
> where there are no init files at all. It would eliminate the 'why is
> emacs creating .emacs.d but then not using it' confusion.

One thing I find useful about the current way is that I can use ~/.emacs
to carry out tests requiring (or facilitated by having) an init file,
without having to move or otherwise disable my actual init file
~/.emacs.d/init.el.  That benefit would be lost if the priority was
changed (or it would require making ~/.emacs the real init file and
using ~/.emacs.d/init.el for testing, which seems less appealing).

Steve Berman

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Wed, 07 Jul 2021 16:11:32 +0200, Stephen Berman <stephen.berman@gmx.net> said:

    Stephen> One thing I find useful about the current way is that I can use ~/.emacs
    Stephen> to carry out tests requiring (or facilitated by having) an init file,
    Stephen> without having to move or otherwise disable my actual init file
    Stephen> ~/.emacs.d/init.el.  That benefit would be lost if the priority was
    Stephen> changed (or it would require making ~/.emacs the real init file and
    Stephen> using ~/.emacs.d/init.el for testing, which seems less appealing).

Instead of 'no init files' -> .emacs, weʼd have 'no init files' ->
~/.emacs.d/init.el

That would not affect the existing search logic, which currently
prefers .emacs to ~/.emacs.d/init.el if it finds .emacs

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Stephen Berman]

On Wed, 07 Jul 2021 16:40:24 +0200 Robert Pluim <rpluim@gmail.com> wrote:

>>>>>> On Wed, 07 Jul 2021 16:11:32 +0200, Stephen Berman
> <stephen.berman@gmx.net> said:
>
>     Stephen> One thing I find useful about the current way is that I can use ~/.emacs
>     Stephen> to carry out tests requiring (or facilitated by having) an init file,
>     Stephen> without having to move or otherwise disable my actual init file
>     Stephen> ~/.emacs.d/init.el.  That benefit would be lost if the priority was
>     Stephen> changed (or it would require making ~/.emacs the real init file and
>     Stephen> using ~/.emacs.d/init.el for testing, which seems less appealing).
>
> Instead of 'no init files' -> .emacs, weʼd have 'no init files' ->
> ~/.emacs.d/init.el
>
> That would not affect the existing search logic, which currently
> prefers .emacs to ~/.emacs.d/init.el if it finds .emacs

Ah, right.  Then it's fine by me :-)

Steve Berman

bug#49424: 27.2; Misdocumented default initialisation file

[Rudolf Schlatte]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Wed, 07 Jul 2021 13:28:30 +0200, Rudolf Schlatte <rudi@constantly.at> said:
>
>     Rudolf> Robert Pluim <rpluim@gmail.com> writes:
>
>     >> Emacs will prefer the XDG path if it exists and .emacs.d/init.el and
>     >> .emacs donʼt. Similarly Emacs will prefer .emacs.d/init.el if it
>     >> exists and .emacs doesnʼt.
>
>     Rudolf> I wonder if it would make sense to warn during startup if more than one
>     Rudolf> of these files exist, something like: "Warning: multiple init files
>     Rudolf> detected.  Using ~/.emacs as init file, ignoring ~/.emacs.d/init.el"
>
> A warning prominent enough for people to notice would also be annoying
> enough that people would complain about us changing the status quo out
> from under them. The best we could do is putting something in
> *Messages*, I suspect

A line in *Messages* was what I was thinking of, yes.  Maybe conditional
on a variable in case it turns out annoying for people who have shadowed
init files on purpose and want to keep their *Messages* buffer clean.
Or maybe a command `list-init-file-shadows' analogous to the existing
`list-load-path-shadows'.

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 504 bytes --]

On Wed, 7 Jul 2021, Robert Pluim wrote:

> If nothing exists, Emacs will create ~/.emacs.d, and use ~/.emacs as
> the init file. We can change that to use ~/.emacs.d/init.el if we
> want, people who already have init files will not be affected.

Sounds good to me.

If we’re making a change, here, it may be worth going all the way: create $XDG_CONFIG_HOME/emacs if it and ~/.emacs.d don’t exist, and hence use $XDG_CONFIG_HOME/emacs/init.el when creating a new initialisation file.

-- 
Peter Oliver

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 592 bytes --]

On Wed, 7 Jul 2021, Robert Pluim wrote:

>    > Peter Oliver <p.d.oliver@mavit.org.uk> writes:
>    >> The info page “49.4.4 How Emacs Finds Your Init File” says:
>    >>
>    >>> For brevity the rest of the Emacs documentation generally uses just
>    >>> the current default location ‘~/.emacs.d/init.el’ for the init file.
>    >>
>    >> However, this seems to be inaccurate: if I start Emacs as a new user
>    >> and make a customisation, that customisation is written to ~/.emacs.
>
> Yes, we should change that to say '~/.emacs'

Here’s a patch to do that.

-- 
Peter Oliver

[-- Attachment #2: Type: text/plain, Size: 880 bytes --]

From e0a95ea7a048c505820829d8e10f0addf2cc6c4a Mon Sep 17 00:00:00 2001
From: Peter Oliver <git@mavit.org.uk>
Date: Wed, 7 Jul 2021 19:09:58 +0100
Subject: [PATCH] Document init file with the highest precedence as ~/.emacs

* doc/emacs/custom.texi: Default location of init file is ~/.emacs
(bug#49424).
---
 doc/emacs/custom.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index de5d825248..708349e833 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2713,7 +2713,7 @@ Find Init
 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{~/.emacs.d/init.el} for the
+the current default location @file{~/.emacs} for the
 init file.
 @c  LocalWords:  backtab
 
-- 
2.31.1

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> Date: Wed, 7 Jul 2021 19:12:03 +0100 (BST)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 49424@debbugs.gnu.org
> 
> > Yes, we should change that to say '~/.emacs'
> 
> Here’s a patch to do that.
> 
> -- 
> Peter Oliver
> 
> From e0a95ea7a048c505820829d8e10f0addf2cc6c4a Mon Sep 17 00:00:00 2001
> From: Peter Oliver <git@mavit.org.uk>
> Date: Wed, 7 Jul 2021 19:09:58 +0100
> Subject: [PATCH] Document init file with the highest precedence as ~/.emacs
> 
> * doc/emacs/custom.texi: Default location of init file is ~/.emacs
> (bug#49424).
> ---
>  doc/emacs/custom.texi | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index de5d825248..708349e833 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -2713,7 +2713,7 @@ Find Init
>  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{~/.emacs.d/init.el} for the
> +the current default location @file{~/.emacs} for the
>  init file.

Thanks, but this is still inaccurate.  Can we please change the
documentation so that it tells the whole story?

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

On Wed, 7 Jul 2021, Eli Zaretskii wrote:

>> From: Peter Oliver <p.d.oliver@mavit.org.uk>

>>    For brevity the rest of the Emacs documentation generally uses just
>> -the current default location @file{~/.emacs.d/init.el} for the
>> +the current default location @file{~/.emacs} for the
>>  init file.
>
> Thanks, but this is still inaccurate.  Can we please change the
> documentation so that it tells the whole story?

What do we think is wrong or missing?  In the context of the rest of that page, I admit it looks okay to me.

-- 
Peter Oliver

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> Date: Wed, 7 Jul 2021 20:08:20 +0100 (BST)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> cc: rpluim@gmail.com, larsi@gnus.org, 49424@debbugs.gnu.org
> 
> >>    For brevity the rest of the Emacs documentation generally uses just
> >> -the current default location @file{~/.emacs.d/init.el} for the
> >> +the current default location @file{~/.emacs} for the
> >>  init file.
> >
> > Thanks, but this is still inaccurate.  Can we please change the
> > documentation so that it tells the whole story?
> 
> What do we think is wrong or missing?  In the context of the rest of that page, I admit it looks okay to me.

Then I don't think I understand the change at all.  This sentence
explains that the rest of the documentation doesn't mention the logic
of finding the init file under its various names, instead using just
one possible name.  You changed that one name without changing the
rest of the documentation -- what does that achieve?

Stepping back a notch, the original report was:

  The info page “49.4.4 How Emacs Finds Your Init File” says:

  > For brevity the rest of the Emacs documentation generally uses just
  > the current default location ‘~/.emacs.d/init.el’ for the init file.

  However, this seems to be inaccurate: if I start Emacs as a new user
  and make a customisation, that customisation is written to ~/.emacs.

How can a simplifying convention in a manual be "inaccurate"?  And
what does that convention have to do with the order and logic of how
Emacs actually looks for the init file?

What am I missing here?

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 1362 bytes --]

On Wed, 7 Jul 2021, Eli Zaretskii wrote:

> This sentence
> explains that the rest of the documentation doesn't mention the logic
> of finding the init file under its various names, instead using just
> one possible name.  You changed that one name without changing the
> rest of the documentation -- what does that achieve?

It turns out that the rest of the documentation already refers to ~/.emacs, not ~/.emacs.d/init.el.

> Stepping back a notch, the original report was:
>
>  The info page “49.4.4 How Emacs Finds Your Init File” says:
>
>  > For brevity the rest of the Emacs documentation generally uses just
>  > the current default location ‘~/.emacs.d/init.el’ for the init file.
>
>  However, this seems to be inaccurate: if I start Emacs as a new user
>  and make a customisation, that customisation is written to ~/.emacs.
>
> How can a simplifying convention in a manual be "inaccurate"?  And
> what does that convention have to do with the order and logic of how
> Emacs actually looks for the init file?

I understand the sentence to be making two assertions:

1. Throughout the documentation, “~/.emacs.d/init.el” will be used as a shorthand for “the initialisation file”, whatever filename that happens to have.
2. The default location of the initialisation file is “~/.emacs.d/init.el”.

Neither is true.

-- 
Peter Oliver

bug#49424: 27.2; Misdocumented default initialisation file

[Phil Sainty]

On 2021-07-08 01:08, Robert Pluim wrote:
> Iʼm not proposing changing the sequence, only what happens in the case
> where there are no init files at all. It would eliminate the 'why is
> emacs creating .emacs.d but then not using it' confusion.

Thanks for clarifying.  I agree -- that sounds sensible.

bug#49424: 27.2; Misdocumented default initialisation file

[Phil Sainty]

On 2021-07-08 05:58, Peter Oliver wrote:
> If we’re making a change, here, it may be worth going all the way:
> create $XDG_CONFIG_HOME/emacs if it and ~/.emacs.d don’t exist, and
> hence use $XDG_CONFIG_HOME/emacs/init.el when creating a new
> initialisation file.

I don't agree with doing that.

The current XDG_CONFIG_HOME behaviour is opt-in, and I think it should
stay that way, partly so that the default behaviour is consistent across
systems, but also because I think the suggested behaviour would cause
widespread confusion from users who run Emacs before creating their
~/.emacs.d directory, and then can't figure out why their new config
isn't working.  (IIRC that is exactly what happened with the original
XDG_CONFIG_HOME support code before it was adjusted to ensure that it
was opt-in behaviour, despite the fact that you needed to be running
a pre-release build of Emacs to be affected and therefore likely to
have a better understanding of things than the average newcomer.)


-Phil

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> Date: Wed, 7 Jul 2021 22:51:43 +0100 (BST)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> cc: rpluim@gmail.com, larsi@gnus.org, 49424@debbugs.gnu.org
> 
> >  The info page “49.4.4 How Emacs Finds Your Init File” says:
> >
> >  > For brevity the rest of the Emacs documentation generally uses just
> >  > the current default location ‘~/.emacs.d/init.el’ for the init file.
> >
> >  However, this seems to be inaccurate: if I start Emacs as a new user
> >  and make a customisation, that customisation is written to ~/.emacs.
> >
> > How can a simplifying convention in a manual be "inaccurate"?  And
> > what does that convention have to do with the order and logic of how
> > Emacs actually looks for the init file?
> 
> I understand the sentence to be making two assertions:
> 
> 1. Throughout the documentation, “~/.emacs.d/init.el” will be used as a shorthand for “the initialisation file”, whatever filename that happens to have.
> 2. The default location of the initialisation file is “~/.emacs.d/init.el”.
> 
> Neither is true.

The 2nd one is not what that sentence says.

If the 1st one is incorrect, it should be fixed to reflect the truth.
But that has nothing to do with the rest of this discussion, which is
about the actual method and order Emacs uses to find the init file(s).

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> Date: Thu, 08 Jul 2021 13:17:22 +1200
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 49424@debbugs.gnu.org,
>  Robert Pluim <rpluim@gmail.com>
> 
> On 2021-07-08 05:58, Peter Oliver wrote:
> > If we’re making a change, here, it may be worth going all the way:
> > create $XDG_CONFIG_HOME/emacs if it and ~/.emacs.d don’t exist, and
> > hence use $XDG_CONFIG_HOME/emacs/init.el when creating a new
> > initialisation file.
> 
> I don't agree with doing that.
> 
> The current XDG_CONFIG_HOME behaviour is opt-in, and I think it should
> stay that way, partly so that the default behaviour is consistent across
> systems, but also because I think the suggested behaviour would cause
> widespread confusion from users who run Emacs before creating their
> ~/.emacs.d directory, and then can't figure out why their new config
> isn't working.  (IIRC that is exactly what happened with the original
> XDG_CONFIG_HOME support code before it was adjusted to ensure that it
> was opt-in behaviour, despite the fact that you needed to be running
> a pre-release build of Emacs to be affected and therefore likely to
> have a better understanding of things than the average newcomer.)

I tend to agree with Phil here.  Let's leave this part of Emacs alone
for a release or two, and see how the user community reacts to the
changes we did just recently.  Making changes right now in this
sensitive area could bring more trouble, and what practical problems
are we going to solve?

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Thu, 08 Jul 2021 10:23:57 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> Date: Thu, 08 Jul 2021 13:17:22 +1200
    >> From: Phil Sainty <psainty@orcon.net.nz>
    >> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 49424@debbugs.gnu.org,
    >> Robert Pluim <rpluim@gmail.com>
    >> 
    >> On 2021-07-08 05:58, Peter Oliver wrote:
    >> > If we’re making a change, here, it may be worth going all the way:
    >> > create $XDG_CONFIG_HOME/emacs if it and ~/.emacs.d don’t exist, and
    >> > hence use $XDG_CONFIG_HOME/emacs/init.el when creating a new
    >> > initialisation file.
    >> 
    >> I don't agree with doing that.
    >>

Right. We should never create $XDG_CONFIG_HOME/emacs.

    >> The current XDG_CONFIG_HOME behaviour is opt-in, and I think it should
    >> stay that way, partly so that the default behaviour is consistent across
    >> systems, but also because I think the suggested behaviour would cause
    >> widespread confusion from users who run Emacs before creating their
    >> ~/.emacs.d directory, and then can't figure out why their new config
    >> isn't working.  (IIRC that is exactly what happened with the original
    >> XDG_CONFIG_HOME support code before it was adjusted to ensure that it
    >> was opt-in behaviour, despite the fact that you needed to be running
    >> a pre-release build of Emacs to be affected and therefore likely to
    >> have a better understanding of things than the average newcomer.)

    Eli> I tend to agree with Phil here.  Let's leave this part of Emacs alone
    Eli> for a release or two, and see how the user community reacts to the
    Eli> changes we did just recently.  Making changes right now in this
    Eli> sensitive area could bring more trouble, and what practical problems
    Eli> are we going to solve?

By 'this part' do you mean the XDG_CONFIG_HOME related changes, or
also the suggested change to prefer ~/.emacs.d/init.el when no config
files exist? The latter is a relatively small change, but itʼs in a
convoluted area of startup [1], so Iʼd have no problem with leaving it
alone.

Robert

Footnotes:
[1]  I made the change, tested it, and it gave incorrect results, so had
     to re-do it. Twice.

-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Thu, 08 Jul 2021 09:23:27 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> Date: Wed, 7 Jul 2021 22:51:43 +0100 (BST)
    >> From: Peter Oliver <p.d.oliver@mavit.org.uk>
    >> cc: rpluim@gmail.com, larsi@gnus.org, 49424@debbugs.gnu.org
    >> 
    >> >  The info page “49.4.4 How Emacs Finds Your Init File” says:
    >> >
    >> >  > For brevity the rest of the Emacs documentation generally uses just
    >> >  > the current default location ‘~/.emacs.d/init.el’ for the init file.
    >> >
    >> >  However, this seems to be inaccurate: if I start Emacs as a new user
    >> >  and make a customisation, that customisation is written to ~/.emacs.
    >> >
    >> > How can a simplifying convention in a manual be "inaccurate"?  And
    >> > what does that convention have to do with the order and logic of how
    >> > Emacs actually looks for the init file?
    >> 
    >> I understand the sentence to be making two assertions:
    >> 
    >> 1. Throughout the documentation, “~/.emacs.d/init.el” will be used
    >> as a shorthand for “the initialisation file”, whatever filename that
    >> happens to have.
    >> 2. The default location of the initialisation file is “~/.emacs.d/init.el”.
    >> 
    >> Neither is true.

    Eli> The 2nd one is not what that sentence says.

    Eli> If the 1st one is incorrect, it should be fixed to reflect the truth.
    Eli> But that has nothing to do with the rest of this discussion, which is
    Eli> about the actual method and order Emacs uses to find the init file(s).

FWIW I agree with Peter's interpretation here. We could avoid the
whole argument by deleting the whole sentence, since its information
content is low anyway.

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Phil Sainty <psainty@orcon.net.nz>,  p.d.oliver@mavit.org.uk,
>   larsi@gnus.org,  49424@debbugs.gnu.org
> Date: Thu, 08 Jul 2021 10:30:48 +0200
> 
>     >> The current XDG_CONFIG_HOME behaviour is opt-in, and I think it should
>     >> stay that way, partly so that the default behaviour is consistent across
>     >> systems, but also because I think the suggested behaviour would cause
>     >> widespread confusion from users who run Emacs before creating their
>     >> ~/.emacs.d directory, and then can't figure out why their new config
>     >> isn't working.  (IIRC that is exactly what happened with the original
>     >> XDG_CONFIG_HOME support code before it was adjusted to ensure that it
>     >> was opt-in behaviour, despite the fact that you needed to be running
>     >> a pre-release build of Emacs to be affected and therefore likely to
>     >> have a better understanding of things than the average newcomer.)
> 
>     Eli> I tend to agree with Phil here.  Let's leave this part of Emacs alone
>     Eli> for a release or two, and see how the user community reacts to the
>     Eli> changes we did just recently.  Making changes right now in this
>     Eli> sensitive area could bring more trouble, and what practical problems
>     Eli> are we going to solve?
> 
> By 'this part' do you mean the XDG_CONFIG_HOME related changes, or
> also the suggested change to prefer ~/.emacs.d/init.el when no config
> files exist?

I meant both.  I think we should leave this area alone for a while and
let the dust settle on the recent changes.

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Peter Oliver <p.d.oliver@mavit.org.uk>,  larsi@gnus.org,
>   49424@debbugs.gnu.org
> Date: Thu, 08 Jul 2021 10:40:39 +0200
> 
>     Eli> The 2nd one is not what that sentence says.
> 
>     Eli> If the 1st one is incorrect, it should be fixed to reflect the truth.
>     Eli> But that has nothing to do with the rest of this discussion, which is
>     Eli> about the actual method and order Emacs uses to find the init file(s).
> 
> FWIW I agree with Peter's interpretation here. We could avoid the
> whole argument by deleting the whole sentence, since its information
> content is low anyway.

Deleting that would be a step back, since it was added for a reason,
see the discussions about that.  Specifically, we don't want to repeat
the whole long description of how and where does Emacs find the init
file every time we mention the init file.

bug#49424: 27.2; Misdocumented default initialisation file

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 770 bytes --]

On Thu, 8 Jul 2021, Eli Zaretskii wrote:

>> From: Robert Pluim <rpluim@gmail.com>
>>
>> We could avoid the
>> whole argument by deleting the whole sentence, since its information
>> content is low anyway.
>
> Deleting that would be a step back, since it was added for a reason,
> see the discussions about that.  Specifically, we don't want to repeat
> the whole long description of how and where does Emacs find the init
> file every time we mention the init file.

Perhaos, elsewhere in the documentation, instead of saying “~/.emacs”, we could say “the initialization file”, accompanied by a link to this description of where it can be found.

I couldn’t find the prior discussion of this, so apologies if this idea was already dismissed.

-- 
Peter Oliver

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> Date: Thu, 8 Jul 2021 19:22:59 +0100 (BST)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> cc: Robert Pluim <rpluim@gmail.com>, larsi@gnus.org, 49424@debbugs.gnu.org
> 
> > Deleting that would be a step back, since it was added for a reason,
> > see the discussions about that.  Specifically, we don't want to repeat
> > the whole long description of how and where does Emacs find the init
> > file every time we mention the init file.
> 
> Perhaos, elsewhere in the documentation, instead of saying “~/.emacs”, we could say “the initialization file”, accompanied by a link to this description of where it can be found.

I'd suggest to audit all the places where this could be relevant,
before proposing a solution.  For example, if some text tells the user
"put this-and-that Lisp in your ~/.emacs file", a reference to a
description how Emacs looks for the init file will only confuse.

bug#49424: 27.2; Misdocumented default initialisation file

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I understand the sentence to be making two assertions:
>>
>> 1. Throughout the documentation, “~/.emacs.d/init.el” will be used as a
>> shorthand for “the initialisation file”, whatever filename that happens to
>> have.
>> 2. The default location of the initialisation file is “~/.emacs.d/init.el”.
>>
>> Neither is true.
>
> The 2nd one is not what that sentence says.

This is the text under discussion:

       For brevity the rest of the Emacs documentation generally uses just
    the current default location ‘~/.emacs.d/init.el’ for the init file.

The sentence says: "the current default location ‘~/.emacs.d/init.el’".
I can't interpret this in any other way than that this is the default
location.  This is, as we know, incorrect.

> If the 1st one is incorrect, it should be fixed to reflect the truth.

The proposed fix here was to change it to say:

       For brevity the rest of the Emacs documentation generally uses just
    the current default location ‘~/.emacs’ for the init file.

That is incidentally also the convention we have used historically, and
what you will find all over the documentation.  However, this is also
not entirely correct, as the default will differ depending on the
details discussed in `(emacs) Find Init'.  So I would suggest this
simple change instead:

       For brevity the rest of the Emacs documentation generally uses just
    the historical default location ‘~/.emacs’ for the init file.

As for the rest of this bug report, there is some discussion about:

A) Inadequacies in the Info node `(emacs) Find Init'.
B) Further changes to how we load the init file.

As for A, I think the text is fine as is.  As for B, I agree with Eli
that we should let the dust settle on the recent changes for a while
before doing anything more.

bug#49424: 27.2; Misdocumented default initialisation file

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> This is the text under discussion:
>
>        For brevity the rest of the Emacs documentation generally uses just
>     the current default location ‘~/.emacs.d/init.el’ for the init file.
>
> The sentence says: "the current default location ‘~/.emacs.d/init.el’".
> I can't interpret this in any other way than that this is the default
> location.  This is, as we know, incorrect.

Well, it's the default default location, isn't it?

But saying "current" here is very odd -- it's probably meant as opposed
to "historical", but why should the person reading this text care?  Why
not just say

       For brevity the rest of the Emacs documentation generally uses
       ‘~/.emacs.d/init.el’ for the init file.


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49424: 27.2; Misdocumented default initialisation file

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> This is the text under discussion:
>>
>>        For brevity the rest of the Emacs documentation generally uses just
>>     the current default location ‘~/.emacs.d/init.el’ for the init file.
>>
>> The sentence says: "the current default location ‘~/.emacs.d/init.el’".
>> I can't interpret this in any other way than that this is the default
>> location.  This is, as we know, incorrect.
>
> Well, it's the default default location, isn't it?

The default is ".emacs.el", if this text from (info "(emacs) Find Init")
is correct:

     Emacs looks for your init file using the filenames ‘~/.emacs.el’,
     ‘~/.emacs’, or ‘~/.emacs.d/init.el’ in that order; you can choose
     to use any one of these names. [...] Emacs can also look in an
     XDG-compatible location for ‘init.el’, the default is the directory
     ‘~/.config/emacs’.

> But saying "current" here is very odd -- it's probably meant as opposed
> to "historical", but why should the person reading this text care?  Why
> not just say
>
>        For brevity the rest of the Emacs documentation generally uses
>        ‘~/.emacs.d/init.el’ for the init file.

I guess because that's not the convention we actually use.  :-)
We say ".emacs" everywhere.  AFAICT, the only place we even mention
"~/.emacs.d/init.el" in the manual is this node (!).

That's why I proposed to change "current" to "historical", but the word
"traditional" is also good IMO.

bug#49424: 27.2; Misdocumented default initialisation file

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>>        For brevity the rest of the Emacs documentation generally uses
>>        ‘~/.emacs.d/init.el’ for the init file.
>
> I guess because that's not the convention we actually use.  :-)
> We say ".emacs" everywhere.  AFAICT, the only place we even mention
> "~/.emacs.d/init.el" in the manual is this node (!).

Heh heh.  Oh, OK.

> That's why I proposed to change "current" to "historical", but the word
> "traditional" is also good IMO.

But what about changing all the .emacs instances to ~/.emacs.d/init.el,
which is what we're trying to encourage, I think?  (Even if we let
~/.emacs.el and ~/.emacs take precedence.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49424: 27.2; Misdocumented default initialisation file

[Robert Pluim]

>>>>> On Sun, 24 Oct 2021 01:12:49 -0700, Stefan Kangas <stefan@marxist.se> said:
    Stefan> A) Inadequacies in the Info node `(emacs) Find Init'.
    Stefan> B) Further changes to how we load the init file.

    Stefan> As for A, I think the text is fine as is.  As for B, I agree with Eli
    Stefan> that we should let the dust settle on the recent changes for a while
    Stefan> before doing anything more.

Iʼve not re-read "(emacs) Find Init" recently, so Iʼll defer to your
judgement on that.

And Eli is spot on regarding init file loading changes. Itʼs
complicated enough as it is, and doesnʼt need any more tinkering.

Robert
-- 

bug#49424: 27.2; Misdocumented default initialisation file

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> But what about changing all the .emacs instances to ~/.emacs.d/init.el,
> which is what we're trying to encourage, I think?  (Even if we let
> ~/.emacs.el and ~/.emacs take precedence.)

Sure, that also makes sense.

I think that is what Eli proposed as well.

bug#49424: 27.2; Misdocumented default initialisation file

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> But what about changing all the .emacs instances to ~/.emacs.d/init.el,
> which is what we're trying to encourage, I think?  (Even if we let
> ~/.emacs.el and ~/.emacs take precedence.)

I started this, we have 500+ instances to look over in doc/...

Do we want the full path to the file every time?  That's arguably a bit
better.

bug#49424: 27.2; Misdocumented default initialisation file

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 24 Oct 2021 07:56:50 -0700
> Cc: Eli Zaretskii <eliz@gnu.org>, Peter Oliver <p.d.oliver@mavit.org.uk>, 49424@debbugs.gnu.org, 
> 	rpluim@gmail.com
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > But what about changing all the .emacs instances to ~/.emacs.d/init.el,
> > which is what we're trying to encourage, I think?  (Even if we let
> > ~/.emacs.el and ~/.emacs take precedence.)
> 
> I started this, we have 500+ instances to look over in doc/...
> 
> Do we want the full path to the file every time?  That's arguably a bit
> better.

I'd just say "init file".  It's shorter and simpler, and will not need
any changes when we make the next change in this area.

bug#49424: 27.2; Misdocumented default initialisation file

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I'd just say "init file".  It's shorter and simpler, and will not need
> any changes when we make the next change in this area.

Sounds good to me.