* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. @ 2019-11-02 1:08 Hong Xu 2019-11-02 8:03 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Hong Xu @ 2019-11-02 1:08 UTC (permalink / raw) To: 38026 * 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-02 1:08 bug#38026: [PATCH] Explain negative NABS in `goto-history-element' Hong Xu @ 2019-11-02 8:03 ` Eli Zaretskii 2019-11-02 17:07 ` Hong Xu 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2019-11-02 8:03 UTC (permalink / raw) To: Hong Xu; +Cc: 38026 > 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? ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-02 8:03 ` Eli Zaretskii @ 2019-11-02 17:07 ` Hong Xu 2019-11-02 17:54 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Hong Xu @ 2019-11-02 17:07 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 38026 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-02 17:07 ` Hong Xu @ 2019-11-02 17:54 ` Eli Zaretskii 2019-11-03 5:11 ` Hong Xu 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2019-11-02 17:54 UTC (permalink / raw) To: Hong Xu; +Cc: 38026 > 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-02 17:54 ` Eli Zaretskii @ 2019-11-03 5:11 ` Hong Xu 2019-11-09 9:46 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Hong Xu @ 2019-11-03 5:11 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 38026 [-- 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-03 5:11 ` Hong Xu @ 2019-11-09 9:46 ` Eli Zaretskii 2019-11-09 18:48 ` Hong Xu 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2019-11-09 9:46 UTC (permalink / raw) To: Hong Xu; +Cc: 38026-done > 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-09 9:46 ` Eli Zaretskii @ 2019-11-09 18:48 ` Hong Xu 2019-11-09 20:00 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Hong Xu @ 2019-11-09 18:48 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 38026-done 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. 2019-11-09 18:48 ` Hong Xu @ 2019-11-09 20:00 ` Eli Zaretskii 0 siblings, 0 replies; 8+ messages in thread From: Eli Zaretskii @ 2019-11-09 20:00 UTC (permalink / raw) To: Hong Xu; +Cc: 38026 > 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2019-11-09 20:00 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-11-02 1:08 bug#38026: [PATCH] Explain negative NABS in `goto-history-element' Hong Xu 2019-11-02 8:03 ` Eli Zaretskii 2019-11-02 17:07 ` Hong Xu 2019-11-02 17:54 ` Eli Zaretskii 2019-11-03 5:11 ` Hong Xu 2019-11-09 9:46 ` Eli Zaretskii 2019-11-09 18:48 ` Hong Xu 2019-11-09 20:00 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).