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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 38026 in the body.
You can then email your comments to 38026 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Explain negative NABS in `goto-history-element'.
Date: Fri, 01 Nov 2019 18:08:38 -0700

* 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

Message #8 received at 38026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 38026 <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 02 Nov 2019 10:03:19 +0200

> From: Hong Xu <hong <at> 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?

Message #11 received at 38026 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38026 <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
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.

Message #14 received at 38026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 38026 <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 02 Nov 2019 19:54:14 +0200

> Cc: 38026 <at> debbugs.gnu.org
> From: Hong Xu <hong <at> 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.

Message #17 received at 38026 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38026 <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 2 Nov 2019 22:11:53 -0700

[Message part 1 (text/plain, inline)]

On 11/2/19 10:54 AM, Eli Zaretskii wrote:
>> Cc: 38026 <at> debbugs.gnu.org
>> From: Hong Xu <hong <at> 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.

[0001-Mention-future-history-in-some-history-related-minib.patch (text/x-patch, attachment)]

Message #22 received at 38026-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 38026-done <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 09 Nov 2019 11:46:04 +0200

> Cc: 38026 <at> debbugs.gnu.org
> From: Hong Xu <hong <at> 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.

Message #25 received at 38026-done <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38026-done <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 9 Nov 2019 10:48:54 -0800

On 11/9/19 1:46 AM, Eli Zaretskii wrote:
>> Cc: 38026 <at> debbugs.gnu.org
>> From: Hong Xu <hong <at> 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

Message #28 received at 38026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 38026 <at> debbugs.gnu.org
Subject: Re: bug#38026: [PATCH] Explain negative NABS in
 `goto-history-element'.
Date: Sat, 09 Nov 2019 22:00:42 +0200

> Cc: 38026-done <at> debbugs.gnu.org
> From: Hong Xu <hong <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.