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

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

[Hong Xu]

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

* lisp/simple.el (goto-history-element): Explain negative NABS.
---
 doc/lispref/minibuf.texi | 5 +++++
 lisp/simple.el           | 7 ++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index d36babd69873..a9bb3aec9583 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2339,6 +2339,11 @@ Minibuffer Commands
 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.
+
+@{nabs} being a negative number @var{n} means the @var{n-1}th element
+of @code{minibuffer-default} if it is a list, or otherwise the value
+of @code{minibuffer-default}.  This is usually an intelligent guess of
+what the user intends to input."
 @end deffn
 
 @node Minibuffer Windows
diff --git a/lisp/simple.el b/lisp/simple.el
index 10aecd651f39..e95e2bc22972 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2130,7 +2130,12 @@ 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 (N-1)th element of
+`minibuffer-default' if it is a list, or otherwise the value of
+`minibuffer-default'.  This is usually an intelligent guess of
+what the user intends to input."
   (interactive "p")
   (when (and (not minibuffer-default-add-done)
 	     (functionp minibuffer-default-add-function)
-- 
2.20.1

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

[Eli Zaretskii]

> From: Hong Xu <hong@topbug.net>
> Date: Fri, 01 Nov 2019 18:08:38 -0700
> 
> 
> --- a/doc/lispref/minibuf.texi
> +++ b/doc/lispref/minibuf.texi
> @@ -2339,6 +2339,11 @@ Minibuffer Commands
>  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.
> +
> +@{nabs} being a negative number @var{n} means the @var{n-1}th element
> +of @code{minibuffer-default} if it is a list, or otherwise the value
> +of @code{minibuffer-default}.  This is usually an intelligent guess of
> +what the user intends to input."

Thanks, but I don't see how this clarifies the issue.  Can you tell
more about your motivation?

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

[Hong Xu]

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.

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

[Eli Zaretskii]

> 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.

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

[Hong Xu]

[-- 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

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

[Eli Zaretskii]

> Cc: 38026@debbugs.gnu.org
> From: Hong Xu <hong@topbug.net>
> Date: Sat, 2 Nov 2019 22:11:53 -0700
> 
> > 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.

Thanks, I pushed this, but please see how I fixed the log message, and
also the additional fixes in my following commit.  In particular,
please always mention the bug number in the commit log message.

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

[Hong Xu]

On 11/9/19 1:46 AM, Eli Zaretskii wrote:
>> Cc: 38026@debbugs.gnu.org
>> From: Hong Xu <hong@topbug.net>
>> Date: Sat, 2 Nov 2019 22:11:53 -0700
>>
>>> 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.
> 
> Thanks, I pushed this, but please see how I fixed the log message, and
> also the additional fixes in my following commit.  In particular,
> please always mention the bug number in the commit log message.
> 
Thanks.

I did a search on "future history"

     git grep 'future history'

Except a result in Changelog, everywhere else uses `` and ''.

  doc/emacs/ChangeLog.1:5380:34:  (Minibuffer History): Describe "future history" list.  State default
  doc/emacs/mini.texi:647:25:as moving through the ``future history''.
  doc/emacs/mini.texi:649:9:@cindex future history for file names
  doc/emacs/mini.texi:652:9:  The ``future history'' for file names includes several possible
  doc/emacs/mini.texi:660:19:value, then the ``future history'' of file names will include only the
  doc/lispref/minibuf.texi:144:9:@cindex future history in minibuffer input
  doc/lispref/minibuf.texi:148:3:``future history'', available to the user with @kbd{M-n}.
  doc/lispref/minibuf.texi:2312:49:can go beyond the current position and invoke ``future history''
  lisp/simple.el:2134:45:negative number -N means the Nth entry of \"future history.\""

Are you sure that we should change them to " in the newly added doc?

Hong

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

[Eli Zaretskii]

> Cc: 38026-done@debbugs.gnu.org
> From: Hong Xu <hong@topbug.net>
> Date: Sat, 9 Nov 2019 10:48:54 -0800
> 
> I did a search on "future history"
> 
>      git grep 'future history'
> 
> Except a result in Changelog, everywhere else uses `` and ''.

It is correct in Texinfo files, but not in a doc string.  ``..'' in a
doc string doesn't get rendered as curved double quotes, but as two
curved single quotes, which is not what you want.