From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Hong Xu Newsgroups: gmane.emacs.bugs Subject: bug#38026: [PATCH] Explain negative NABS in `goto-history-element'. Date: Sat, 2 Nov 2019 22:11:53 -0700 Message-ID: <2436a065-6f5b-69f7-026b-364062695d24@topbug.net> References: <8736f7ccfd.fsf@topbug.net> <83h83mk8mw.fsf@gnu.org> <86065fb6-a830-a575-f5c4-7cae336a768d@topbug.net> <83sgn6i2pl.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------E206DA36CDA19A5C72EA22FF" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="90009"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.9.0 Cc: 38026@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Nov 03 06:13:13 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iR8CP-000NJ6-Gd for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Nov 2019 06:13:13 +0100 Original-Received: from localhost ([::1]:51952 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iR8CN-00088t-NP for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Nov 2019 01:13:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55105) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iR8CG-00088f-Bm for bug-gnu-emacs@gnu.org; Sun, 03 Nov 2019 01:13:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iR8CE-00011E-Sm for bug-gnu-emacs@gnu.org; Sun, 03 Nov 2019 01:13:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52752) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iR8CE-000116-Pa for bug-gnu-emacs@gnu.org; Sun, 03 Nov 2019 01:13:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iR8CE-0004pE-I7 for bug-gnu-emacs@gnu.org; Sun, 03 Nov 2019 01:13:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Hong Xu Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 03 Nov 2019 05:13:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 38026 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 38026-submit@debbugs.gnu.org id=B38026.157275792518466 (code B ref 38026); Sun, 03 Nov 2019 05:13:02 +0000 Original-Received: (at 38026) by debbugs.gnu.org; 3 Nov 2019 05:12:05 +0000 Original-Received: from localhost ([127.0.0.1]:33340 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iR8BI-0004nk-RB for submit@debbugs.gnu.org; Sun, 03 Nov 2019 01:12:05 -0400 Original-Received: from sender4-of-o54.zoho.com ([136.143.188.54]:21494) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iR8BG-0004nK-1U for 38026@debbugs.gnu.org; Sun, 03 Nov 2019 01:12:02 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1572757915; cv=none; d=zohomail.com; s=zohoarc; b=J56KeCmlmJdiafTO8k0mJaYHPXU19QWrXkR6ahjxFAbTAxuXcY1yCP18660iJunTlzEsfNz16jMlwuvzm4J/EvpIm6sExpm+pc/Rj87ZORC6aLL0h6WQRzZf3pGsECF27e0Be8Ez4DT+W/1z3s1923CeYPwD63817VUK92fM188= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1572757915; h=Content-Type:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=Xh3WhZUx/EtSCOupZ4yKcZ7RCm/hvlRS2/BJWafcaA4=; b=dN0Lj7vdLRoYC47HpnCl3NM9Fkg1WyKlc9oPSSdBo36qf+tgMDETfFMRqmrklwlkKJDwVk3nlUD+lUxEZfcdAvtJAXxYby4S3MB+YEUtpo+2Nu/hh/gWm/5DITJ8xP7deyJfI9i8lT+ygrdZ7ycPe+7Vgi/fAFUeojYfzx4+SIg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=topbug.net; spf=pass smtp.mailfrom=hong@topbug.net; dmarc=pass header.from= header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1572757915; s=zoho; d=topbug.net; i=hong@topbug.net; h=Subject:To:Cc:References:From:Message-ID:Date:MIME-Version:In-Reply-To:Content-Type; l=4501; bh=Xh3WhZUx/EtSCOupZ4yKcZ7RCm/hvlRS2/BJWafcaA4=; b=G2xwPWGFd50uUkKHD0NzCPkkuhdTOpvJte5JXgkDYmX7t7t7OHpxxzPnBFf/2UAN ZoUXbkEnTB0pbHoIgD8985tfOWledc4UIE3DCC5bIJnAmA/LvFWa3UvIK4ec+Vsv423 V0K1N+RKp+VE1CM3TP4JV7yxjAoEPqDTBhmp5Nbk= Original-Received: from [192.168.88.88] (69-215-149-151.lightspeed.sntcca.sbcglobal.net [69.215.149.151]) by mx.zohomail.com with SMTPS id 1572757913965692.8732118457467; Sat, 2 Nov 2019 22:11:53 -0700 (PDT) Openpgp: preference=signencrypt In-Reply-To: <83sgn6i2pl.fsf@gnu.org> Content-Language: en-US X-Zoho-Virus-Status: 1 X-ZohoMailClient: External X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:170861 Archived-At: This is a multi-part message in MIME format. --------------E206DA36CDA19A5C72EA22FF Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit On 11/2/19 10:54 AM, Eli Zaretskii wrote: >> Cc: 38026@debbugs.gnu.org >> From: Hong Xu >> 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. --------------E206DA36CDA19A5C72EA22FF Content-Type: text/x-patch; name="0001-Mention-future-history-in-some-history-related-minib.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-Mention-future-history-in-some-history-related-minib.pa"; filename*1="tch" >From 5ccc55886957ad81ffd7c3cd14adf05f0372d3ef Mon Sep 17 00:00:00 2001 From: Hong Xu 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 --------------E206DA36CDA19A5C72EA22FF--