From 5fe81ebbb52a82ed13635df4861039ac7ed42022 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Wed, 14 Nov 2018 21:45:41 +0200
Subject: [PATCH] Minor copyedits in documentation of HOME handling

* etc/NEWS: Reword the recent entry regarding the change in
how relative file names are interpreted in $HOME.

* doc/emacs/cmdargs.texi (General Variables): Advise against
using relative directory names in $HOME.
---
 doc/emacs/cmdargs.texi | 21 +++++++++++----------
 etc/NEWS               |  9 ++++++---
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 25a25268889..960398df081 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -528,16 +528,17 @@ This variable defaults to @file{~/.bash_history} if you use Bash, to
 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{~}).
-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}
-subdirectory of the user profile directory (normally, this is
+The location of your files in the directory tree; used for expansion
+of file names starting with a tilde (@file{~}).  If set, it should be
+set to an absolute file name.  (If set to a relative file name, Emacs
+interprets it relative to the directory where Emacs was started, but
+we don't recommend to use this feature.)  If unset, @env{HOME}
+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} subdirectory of the user profile directory (normally, this is
 @file{C:/Documents and Settings/@var{username}/Application Data},
 where @var{username} is your user name), though for backwards
 compatibility @file{C:/} will be used instead if a @file{.emacs} file
diff --git a/etc/NEWS b/etc/NEWS
index 6577c822520..dff7c5d0d5f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -961,9 +961,12 @@ 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.
+** Interpretation of relative HOME directory has changed.
+If $HOME is set to a relative file name, 'expand-file-name' now
+interprets it relative to the directory where Emacs was started, not
+relative to the default-directory of the current buffer.  We recommend
+always setting $HOME to an absolute file name, so that its meaning is
+independent of where Emacs was started.
 
 ** The FILENAME argument to 'file-name-base' is now mandatory and no
 longer defaults to 'buffer-file-name'.
-- 
2.39.5