bug#38026: [PATCH] Explain negative NABS in `goto-history-element'.

[Hong Xu <hong@topbug.net>]

[-- Attachment #1: Type: text/plain, Size: 1091 bytes --]

On 11/2/19 10:54 AM, Eli Zaretskii wrote:
>> Cc: 38026@debbugs.gnu.org
>> From: Hong Xu <hong@topbug.net>
>> Date: Sat, 2 Nov 2019 10:07:03 -0700
>>
>> On 11/2/19 1:03 AM, Eli Zaretskii wrote:
>>> Thanks, but I don't see how this clarifies the issue.  Can you tell
>>> more about your motivation?
>>>
>>
>> The motivation is to clarify what a negative NABS means. From the current document, it is unclear that NABS can be negative.
> 
> In that case, the patch is insufficient.  First, we don't document
> minibuffer-default in the manual, so referencing it will leave the
> reader wondering what it is, and how it is set and used.  Second, the
> doc string of goto-history-element should also explain what is the
> meaning of negative values.  And third, several functions bind
> minibuffer-default to certain values, and I'm not sure this variable
> can usefully be documented in a manual.
> 
> So I think the text needs not reference minibuffer-default, but
> instead talk about "future history", like the Emacs manual does.
> 

Thanks. Sounds like a good idea. I've attached an update.


[-- Attachment #2: 0001-Mention-future-history-in-some-history-related-minib.patch --]
[-- Type: text/x-patch, Size: 2834 bytes --]

From 5ccc55886957ad81ffd7c3cd14adf05f0372d3ef Mon Sep 17 00:00:00 2001
From: Hong Xu <hong@topbug.net>
Date: Fri, 1 Nov 2019 18:06:44 -0700
Subject: [PATCH] Mention future history in some history-related minibuffer
 commands.

* lisp/simple.el (goto-history-element): Explain negative NABS.

* doc/lispref/minibuf.texi (Minibuffer Commands): Explain negative NABS.

* lisp/simple.el (next-history-element): Mention ``future history.''

* doc/lispref/minibuf.texi (Minibuffer Commands): Mention ``future history.''
---
 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 d36babd69873..b5798a9c174a 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2307,7 +2307,8 @@ Minibuffer Commands
 
 @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 @@ Minibuffer Commands
 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 10aecd651f39..b7a601b2e2d7 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2130,7 +2130,8 @@ goto-history-element
   "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 @@ goto-history-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))))
-- 
2.20.1