Document recent change to HOME handling

* doc/emacs/cmdargs.texi (General Variables):
* doc/emacs/custom.texi (Find Init):
* doc/lispref/files.texi (File Name Expansion):
* etc/NEWS: Document behavior when HOME is a relative file name.

4 files changed, 16 insertions, 7 deletions

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 2e2767ccada..25a25268889 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -529,7 +529,11 @@ otherwise.
 @item HOME
 @vindex HOME@r{, environment variable}
 The location of your files in the directory tree; used for
-expansion of file names starting with a tilde (@file{~}).  On MS-DOS,
+expansion of file names starting with a tilde (@file{~}).
+If set to a relative file name, Emacs expands @file{~} to the
+corresponding absolute file name.  If unset, it normally defaults to
+the home directory of the user given by @env{LOGNAME}, @env{USER} or
+your user ID, or to @file{/} if all else fails.  On MS-DOS,
 it defaults to the directory from which Emacs was started, with
 @samp{/bin} removed from the end if it was present.  On Windows, the
 default value of @env{HOME} is the @file{Application Data}
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index ddde5b22e6b..3dbe8f8003f 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2557,10 +2557,9 @@ library.  @xref{Hooks}.
 @node Find Init
 @subsection How Emacs Finds Your Init File
 
-  Normally Emacs uses the environment variable @env{HOME}
-(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
-@samp{~} means in a file name.  If @file{.emacs} is not found inside
-@file{~/} (nor @file{.emacs.el}), Emacs looks for
+  Normally Emacs uses your home directory to find @file{~/.emacs};
+that's what @samp{~} means in a file name.  @xref{General Variables, HOME}.
+If neither @file{~/.emacs} nor @file{~/.emacs.el} is found, Emacs looks for
 @file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
 byte-compiled).
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 5682919b645..b795864815d 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2367,8 +2367,10 @@ start with @samp{~}.)  Otherwise, the current buffer's value of
 @end example
 
 If the part of @var{filename} before the first slash is
-@samp{~}, it expands to the value of the @env{HOME} environment
-variable (usually your home directory).  If the part before the first
+@samp{~}, it expands to your home directory, which is typically
+specified by the value of the @env{HOME} environment variable
+(@pxref{General Variables,,, emacs, The GNU Emacs Manual}).
+If the part before the first
 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
 it expands to @var{user}'s home directory.
 If you do not want this expansion for a relative @var{filename} that
diff --git a/etc/NEWS b/etc/NEWS
index 44f54894cdb..6577c822520 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -961,6 +961,10 @@ its default value changed in Emacs 27.1.
 
 ** The REPETITIONS argument of 'benchmark-run' can now also be a variable.
 
+** If $HOME is a relative file name, 'expand-file-name' now expands
+"~" and leading "~/" to the corresponding absolute file name.
+Formerly, it incorrectly expanded them to a relative file name.
+
 ** The FILENAME argument to 'file-name-base' is now mandatory and no
 longer defaults to 'buffer-file-name'.