Re: user-directory: New library to find user {conf, data, state, ...} files

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> The problem is that changes which break users' configurations will not
> be appreciated.

Correct, and fully agreed.  I believe we can avoid this.

> > With all that being said, we must take great care not to cause
> > unnecessary churn.  In particular, we should absolutely not break
> > anything that's currently working.  This means that we should respect
> > locations of already existing files, and ensure they continue working
> > seamlessly.
>
> That is fine, but I'm not sure how you can achieve that goal and still
> prefer the XDG directories.

This is the key point, indeed.

The new name will be preferred only when there is no old file.  If it
exists, the old name will be used.  (This is based on how
'locate-user-emacs-file' works.)  See below.

> > PS. Note that (user-directory 'config) in particular already just falls
> >     back to use whatever `user-emacs-directory' was set to.  There is no
> >     need to duplicate what is happening in startup.el, or to try to
> >     outsmart it.
>
> What do you mean by "falls back"?  To respect the current behavior,
> the value of user-emacs-directory should be used in preference to
> everything else.

Sorry, I should have said "use", not "falls back": it returns the
value of 'user-emacs-directory' and does nothing else.

> But if we do that, then in which cases will the XDG
> directories be used, since user-emacs-directory always exists and is
> defined.

The 'config case is different from the 'cache, 'state and 'data cases,
where the XDG directories will be preferred instead.  To be more
precise, they will be preferred _only_ if we don't specify an old
name, or if we did specify an old name but no such file exists.

To give an example, let's assume that 'user-emacs-directory' is "~/.emacs.d/".

1. If "~/.emacs.d/old" exists, then we get:

    (user-file 'config "new" "old")
    => "~/.emacs.d/old"

    (user-file 'cache "new" "old")
    => "~/.emacs.d/old"

2. However, if "~/.emacs.d/old" does not exist:

    (user-file 'config "new" old")
    => "~/.emacs.d/new"

    (user-file 'cache "new" old")
    => "~/.cache/new"

3. Finally, let's consider the bookmark case, where a user might be
using the very old name "~/.emacs.bmk":

    (user-file 'data "bookmarks" (locate-user-emacs-file "bookmarks"
".emacs.bmk"))
    => "~/.emacs.bmk"

It's true that this requires discipline on behalf of application
developers when calling 'user-directory': they need to provide an "old
name" in addition to a "new name".  I don't see any way around that.
(See my separate email about the state of the API so far, and some
possible simplifications, especially for the third example above.)

I'd consider any failure to use a previously existing file as a bug.
Bugs will inevitably exist, but I don't believe fixing them will be
fundamentally impossible, or necessarily even hard.

Another consideration is that the interface of course has to be
helpful: it has to be easy to use correctly, and hard to use
incorrectly.  I think what it looks like now is not too bad in that
sense, but I'm very open to suggestions about how to do better.