GNU bug report logs - #42050
27.0.91; Clarify Info-next docstring

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 42050 in the body.
You can then email your comments to 42050 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: Tino Calancha <tino.calancha <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.91; Clarify Info-next docstring
Date: Thu, 25 Jun 2020 23:43:42 +0200

Severity: wishlist,patch
X-Debbugs-Cc: eliz <at> gnu.org,uyennhi.qm <at> gmail.com

When I am reading a section of the Emacs manual, then I
often assume that `p' and `n' behavior is like when you are
reading a book, i.e. jump to the prev/next page; i.e., my
natural expectation is that `n' is bound to `Info-forward-node'.

I think their docstrings could add some
description and mention to the other existent command.

You get my point in this patch:

--8<-----------------------------cut here---------------start------------->8---
commit 6a8f77a63bb5a57448f6184f96b3ca971e6d7991
Author: Tino Calancha <tino.calancha <at> gmail.com>
Date:   Thu Jun 25 23:29:34 2020 +0200

    Clarify Info-next docstring
    
    Mention that Info-next doesn't descend into sublevels; also
    mention the existence of Info-forward-node.
    
    * lisp/info.el (Info-next)
    (Info-prev)
    (Info-forward-node)
    (Info-backward-node): Clarify docstring.

diff --git a/lisp/info.el b/lisp/info.el
index 7a11bb3ff9..234d1d9f5f 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -2265,7 +2265,11 @@ Info-following-node-name
        (match-string-no-properties 1)))
 
 (defun Info-next ()
-  "Go to the next node of this node."
+  "Go to the next node of this node.
+This moves to the next node within the same hierarchical level, i.e.,
+it doesn't descend into a sublevel.
+
+See also `Info-forward-node'."
   (interactive)
   ;; In case another window is currently selected
   (save-window-excursion
@@ -2273,7 +2277,11 @@ Info-next
     (Info-goto-node (Info-extract-pointer "next"))))
 
 (defun Info-prev ()
-  "Go to the previous node of this node."
+  "Go to the previous node of this node.
+This moves to the previous node within the same hierarchical level, i.e.,
+it doesn't ascend into an upper level.
+
+See also `Info-backward-node'."
   (interactive)
   ;; In case another window is currently selected
   (save-window-excursion
@@ -2887,7 +2895,9 @@ Info-final-node
       (Info-goto-node (Info-extract-menu-counting nil)))))
 
 (defun Info-forward-node (&optional not-down not-up no-error)
-  "Go forward one node, considering all nodes as forming one sequence."
+  "Go forward one node, considering all nodes as forming one sequence.
+Interactively, this is similar as `Info-next' but it also
+descends into sublevels."
   (interactive)
   (goto-char (point-min))
   (forward-line 1)
@@ -2922,7 +2932,9 @@ Info-forward-node
 	  (t (user-error "No pointer forward from this node")))))
 
 (defun Info-backward-node ()
-  "Go backward one node, considering all nodes as forming one sequence."
+  "Go backward one node, considering all nodes as forming one sequence.
+Interactively, this is similar as `Info-prev' but it also
+ascends into upper levels."
   (interactive)
   (let ((prevnode (Info-extract-pointer "prev[ious]*" t))
 	(upnode (Info-extract-pointer "up" t))

--8<-----------------------------cut here---------------end--------------->8---

In GNU Emacs 27.0.91 (build 26, x86_64-pc-linux-gnu, GTK+ Version 3.24.5)
 of 2020-06-25 built on calancha-pc.dy.bbexcite.jp
Repository revision: 632b0119e1ac0b907af41e4e4b7b5ab7557a5d90
Repository branch: emacs-27
Windowing system distributor 'The X.Org Foundation', version 11.0.12004000
System Description: Debian GNU/Linux 10 (buster)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <tino.calancha <at> gmail.com>
Cc: uyennhi.qm <at> gmail.com, 42050-done <at> debbugs.gnu.org
Subject: Re: bug#42050: 27.0.91; Clarify Info-next docstring
Date: Fri, 26 Jun 2020 10:43:12 +0300

> Cc: eliz <at> gnu.org,uyennhi.qm <at> gmail.com
> From: Tino Calancha <tino.calancha <at> gmail.com>
> Date: Thu, 25 Jun 2020 23:43:42 +0200
> 
> When I am reading a section of the Emacs manual, then I
> often assume that `p' and `n' behavior is like when you are
> reading a book, i.e. jump to the prev/next page; i.e., my
> natural expectation is that `n' is bound to `Info-forward-node'.
> 
> I think their docstrings could add some
> description and mention to the other existent command.
> 
> You get my point in this patch:

Thanks, I fixed this in a slightly different way.

P.S. Do you really use [ and ] in Info when reading a manual?

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: 42050 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org, tino.calancha <at> gmail.com
Subject: Re: bug#42050: 27.0.91; Clarify Info-next docstring
Date: Fri, 26 Jun 2020 09:41:47 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> P.S. Do you really use [ and ] in Info when reading a manual?

I do; I hate cliffhangers. ;)

-- 
Basil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 42050 <at> debbugs.gnu.org, tino.calancha <at> gmail.com
Subject: Re: bug#42050: 27.0.91; Clarify Info-next docstring
Date: Fri, 26 Jun 2020 13:31:59 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: eliz <at> gnu.org,  tino.calancha <at> gmail.com
> Date: Fri, 26 Jun 2020 09:41:47 +0100
> 
> > P.S. Do you really use [ and ] in Info when reading a manual?
> 
> I do; I hate cliffhangers. ;)

Why not SPC and DEL?  They incorporate the functionality of [ and ].

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 42050 <at> debbugs.gnu.org, tino.calancha <at> gmail.com
Subject: Re: bug#42050: 27.0.91; Clarify Info-next docstring
Date: Fri, 26 Jun 2020 12:32:43 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: eliz <at> gnu.org,  tino.calancha <at> gmail.com
>> Date: Fri, 26 Jun 2020 09:41:47 +0100
>> 
>> > P.S. Do you really use [ and ] in Info when reading a manual?
>> 
>> I do; I hate cliffhangers. ;)
>
> Why not SPC and DEL?  They incorporate the functionality of [ and ].

I use those too, but sometimes I don't want to scroll through a whole
node if it's longer than a screenful.

-- 
Basil

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

From: Tino Calancha <tino.calancha <at> gmail.com>
To: 42050 <at> debbugs.gnu.org
Subject: Re: bug#42050: closed (Re: bug#42050: 27.0.91; Clarify Info-next
 docstring)
Date: Fri, 26 Jun 2020 17:36:00 +0200

help-debbugs <at> gnu.org (GNU bug Tracking System) writes:

> Thanks, I fixed this in a slightly different way.
Thank you.
> P.S. Do you really use [ and ] in Info when reading a manual?
Yes I do; I like that they always behave as 'next page', with no
sorprise.
For instance, if you are at section X.y, then ']' bring me to
X.y.z,
while 'n' goes to X.y+1 which discuss something unrelated with what
I am digging in that moment.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <tino.calancha <at> gmail.com>
Cc: 42050 <at> debbugs.gnu.org
Subject: Re: bug#42050: closed (Re: bug#42050: 27.0.91;
 Clarify Info-next docstring)
Date: Fri, 26 Jun 2020 20:53:03 +0300

> From: Tino Calancha <tino.calancha <at> gmail.com>
> Date: Fri, 26 Jun 2020 17:36:00 +0200
> 
> > P.S. Do you really use [ and ] in Info when reading a manual?
> Yes I do; I like that they always behave as 'next page', with no
> sorprise.
> For instance, if you are at section X.y, then ']' bring me to
> X.y.z,
> while 'n' goes to X.y+1 which discuss something unrelated with what
> I am digging in that moment.

I didn't mean 'n' and 'p', I meant SPC and DEL.

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

From: Tino Calancha <tino.calancha <at> gmail.com>
To: 42050 <at> debbugs.gnu.org
Subject: Re: bug#42050: closed (Re: bug#42050: 27.0.91; Clarify Info-next
 docstring)
Date: Sun, 28 Jun 2020 18:48:27 +0200 (CEST)

On Fri, 26 Jun 2020, Eli Zaretskii wrote:

>> From: Tino Calancha <tino.calancha <at> gmail.com>
>> Date: Fri, 26 Jun 2020 17:36:00 +0200
>>
>>> P.S. Do you really use [ and ] in Info when reading a manual?
>> Yes I do; I like that they always behave as 'next page', with no

> I didn't mean 'n' and 'p', I meant SPC and DEL.
No I don't use them (neither in buffers in view-mode); I am too used
to scroll myself.

Previous Next

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