Subject: bug#42050: closed (Re: bug#42050: 27.0.91; Clarify Info-next docstring)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 26 Jun 2020 07:44:02 +0000

Your bug report

#42050: 27.0.91; Clarify Info-next docstring

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
42050: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=42050
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#42050: 27.0.91; Clarify Info-next docstring
From: Eli Zaretskii <[email-masked]>
To: Tino Calancha <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Fri, 26 Jun 2020 10:43:12 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> Cc: [email-masked],[email-masked]
> From: Tino Calancha <[email-masked]>
> 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?

Subject: 27.0.91; Clarify Info-next docstring
From: Tino Calancha <[email-masked]>
To: [email-masked]
Date: Thu, 25 Jun 2020 23:43:42 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Severity: wishlist,patch
X-Debbugs-Cc: [email-masked],[email-masked]

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 <[email-masked]>
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)