master 15f4c41 1/2: Mention future history in history-related minibuffer commands

[Eli Zaretskii]

branch: master
commit 15f4c4156c1a0afdedbe6f13732431383f44f36f
Author: Hong Xu <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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)
---
 doc/lispref/minibuf.texi | 7 +++++--
 lisp/simple.el           | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index d36babd..b5798a9 100644
--- 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 10aecd6..b7a601b 100644
--- 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))))