From: Hong Xu <hong@topbug.net>
Date: Sat, 2 Nov 2019 01:06:44 +0000 (-0700)
Subject: Mention future history in history-related minibuffer commands
X-Git-Tag: emacs-27.0.90~693
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=15f4c4156c1a0afdedbe6f13732431383f44f36f;p=emacs.git

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 d36babd6987..b5798a9c174 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 10aecd651f3..b7a601b2e2d 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))))