Mention future history in history-related minibuffer commands

* lisp/simple.el (goto-history-element):
* doc/lispref/minibuf.texi (Minibuffer Commands): Explain
negative NABS.
* lisp/simple.el (next-history-element):
* doc/lispref/minibuf.texi (Minibuffer Commands): Mention
"future history."  (Bug#38026)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index d36babd69873e21e2b10d47358b6787d98319377..b5798a9c174a243f561a70c6b6716300b1ee9796 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2307,7 +2307,8 @@ This command replaces the minibuffer contents with the value of the
 
 @deffn Command next-history-element n
 This command replaces the minibuffer contents with the value of the
-@var{n}th more recent history element.
+@var{n}th more recent history element.  The position in the history
+can go beyond the current position and invoke ``future history.''
 @end deffn
 
 @deffn Command previous-matching-history-element pattern n
@@ -2338,7 +2339,9 @@ contents of the minibuffer before the point.
 This function puts element of the minibuffer history in the
 minibuffer.  The argument @var{nabs} specifies the absolute history
 position in descending order, where 0 means the current element and a
-positive number @var{n} means the @var{n}th previous element.
+positive number @var{n} means the @var{n}th previous element.  NABS
+being a negative number -@var{n} means the @var{n}th entry of ``future
+history.''
 @end deffn
 
 @node Minibuffer Windows

diff --git a/lisp/simple.el b/lisp/simple.el
index 10aecd651f39b28df863a721afca717c2ec47e3e..b7a601b2e2d704f5f9afb405d506f1aae1603a20 100644 (file)
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2130,7 +2130,8 @@ the end of the list of defaults just after the default value."
   "Puts element of the minibuffer history in the minibuffer.
 The argument NABS specifies the absolute history position in
 descending order, where 0 means the current element and a
-positive number N means the Nth previous element."
+positive number N means the Nth previous element.  NABS being a
+negative number -N means the Nth entry of ``future history.''"
   (interactive "p")
   (when (and (not minibuffer-default-add-done)
             (functionp minibuffer-default-add-function)
@@ -2187,7 +2188,9 @@ positive number N means the Nth previous element."
 
 (defun next-history-element (n)
   "Puts next element of the minibuffer history in the minibuffer.
-With argument N, it uses the Nth following element."
+With argument N, it uses the Nth following element.  The position
+in the history can go beyond the current position and invoke
+``future history.''"
   (interactive "p")
   (or (zerop n)
       (goto-history-element (- minibuffer-history-position n))))