master f1901fc: Better document obsolescence of 'values'

[Eli Zaretskii]

branch: master
commit f1901fc3084e6bdd6c72f11dbae58ee2a0232224
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Better document obsolescence of 'values'
    
    * doc/lispref/eval.texi (Eval): Mention that 'values' is obsolete.
    * etc/NEWS: Add a rationale for obsoleting 'values'.
---
 doc/lispref/eval.texi | 13 +++++++++----
 etc/NEWS              |  3 +++
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 7893895..e199884 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -862,8 +862,13 @@ expressions that were read, evaluated, and printed from 
buffers
 (including the minibuffer) by the standard Emacs commands which do
 this.  (Note that this does @emph{not} include evaluation in
 @file{*ielm*} buffers, nor evaluation using @kbd{C-j}, @kbd{C-x C-e},
-and similar evaluation commands in @code{lisp-interaction-mode}.)  The
-elements are ordered most recent first.
+and similar evaluation commands in @code{lisp-interaction-mode}.)
+
+This variable is obsolete, and will be removed in a future version,
+since it constantly enlarges the memory footprint of the Emacs
+process.  For that reason, we recommend against using it.
+
+The elements of @code{values} are ordered most recent first.
 
 @example
 @group
@@ -880,8 +885,8 @@ values
 @end group
 @end example
 
-This variable is useful for referring back to values of forms recently
-evaluated.  It is generally a bad idea to print the value of
+This variable could be useful for referring back to values of forms
+recently evaluated.  It is generally a bad idea to print the value of
 @code{values} itself, since this may be very long.  Instead, examine
 particular elements, like this:
 
diff --git a/etc/NEWS b/etc/NEWS
index 2adcc6f..3fa22fb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3374,7 +3374,10 @@ back in Emacs 23.1.  The affected functions are: 
'make-obsolete',
 
 ** The variable 'keyboard-type' is obsolete and not dynamically scoped any 
more.
 
++++
 ** The 'values' variable is now obsolete.
+Using it just contributes to the growth of the Emacs memory
+footprint.
 
 +++
 ** The '&define' keyword in an Edebug specification now disables backtracking.