bug#39042: 26.3; Undocumented keys for Info mode

bug#39042: 26.3; Undocumented keys for Info mode

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1087 bytes --]

Emacs Maintainers,
   In Info mode, the following keys are mapped to the listed functions, but there is no description of the keys or what they do in either the Info summary or in the help for Info mode.  Also, none of these functions are available from the Info menu in the menu bar.
1. . (period):  'beginning-of-buffer2. e: 'end-of-buffer
3. ?: 'Info-summary
4. H: 'describe-mode
5. t: 'Info-top-node

The following keys are described in the Info summary, but are not listed in the Info menu on the menu bar:
h    Invoke the Info tutorial.
RET    Follow a node reference near point, like <mouse-2>.m    Pick menu item specified by name (or abbreviation).d    Go to the Info directory node.TAB    Move cursor to next cross-reference or menu item.C-M-i    Move cursor to previous cross-reference or menu item.
f    Follow a cross reference.  Reads name of reference.
S    Search through this Info file for specified regexp case-sensitively.
This might be what is intended, or it might be an oversight that the maintainers want to correct.
---

[-- Attachment #2: Type: text/html, Size: 2294 bytes --]

bug#39042: 26.3; Undocumented keys for Info mode

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1725 bytes --]

tags 39042 + patch
thanks

Mark Harig <idirectscm@aim.com> writes:

> Emacs Maintainers,

Thank you for this bug report.

>    In Info mode, the following keys are mapped to the listed
> functions, but there is no description of the keys or what they do
> in either the Info summary or in the help for Info mode.  Also, none
> of these functions are available from the Info menu in the menu bar.
>
> 1. . (period):  'beginning-of-buffer
> 2. e: 'end-of-buffer
> 3. ?: 'Info-summary
> 4. H: 'describe-mode
> 5. t: 'Info-top-node

(1) is already documented as 'b', which I think is enough.

(2) is a useful addition, I think.  (See the below patch.)

(3) and (4) I think we can leave out.  The user surely knows how to
get help if she is already reading it, right?

(5) is actually already documented.

> The following keys are described in the Info summary, but are not
> listed in the Info menu on the menu bar:
>
> h    Invoke the Info tutorial.
> RET    Follow a node reference near point, like <mouse-2>.
> m    Pick menu item specified by name (or abbreviation).
> d    Go to the Info directory node.
> TAB    Move cursor to next cross-reference or menu item.
> C-M-i    Move cursor to previous cross-reference or menu item.
> f    Follow a cross reference.  Reads name of reference.
> S    Search through this Info file for specified regexp case-sensitively.

The menu is already quite long, so I would only suggest to add the
'Info-directory' command.

Please see the attached patch, where I also suggest to move some menu
items to submenus.  This cuts down the number of items on the top
level of the menu to 17 compared to 21 before.  This buys us the space
to add three separators too.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-leaving-Info-summary-more-intuitive.patch --]
[-- Type: text/x-diff, Size: 1421 bytes --]

From 0d34e8b98c76bfc1f9dcd24dc0691793b2e03ae5 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 28 Apr 2020 00:25:11 +0200
Subject: [PATCH] Make leaving Info-summary more intuitive

* lisp/info.el (Info-summary): Discard character on exit instead of
pushing it onto 'unread-command-events'.
---
 lisp/info.el | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/lisp/info.el b/lisp/info.el
index 3015e60a4f..703907b98f 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -3828,14 +3828,14 @@ Info-summary
     (insert (documentation 'Info-mode))
     (help-mode)
     (goto-char (point-min))
-    (let (ch flag)
-      (while (progn (setq flag (not (pos-visible-in-window-p (point-max))))
-		    (message (if flag "Type Space to see more"
-			       "Type Space to return to Info"))
-		    (if (not (eq ?\s (setq ch (read-event))))
-			(progn (push ch unread-command-events) nil)
-		      flag))
-	(scroll-up)))
+    (while (let ((flag (not (pos-visible-in-window-p (point-max)))))
+	     (message (if flag "Type Space to see more"
+			"Type any key to return to Info"))
+             ;; Space scrolls if there is more content.
+             ;; Any other key returns.
+             (setq ch (read-event))
+	     (and flag (eq ch ?\s)))
+      (scroll-up))
     (bury-buffer "*Help*")))
 \f
 (defun Info-get-token (pos start all &optional errorstring)
-- 
2.26.2

bug#39042: 26.3; Undocumented keys for Info mode

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 28 Apr 2020 01:13:11 +0200
> Cc: 39042@debbugs.gnu.org
> 
> Please see the attached patch, where I also suggest to move some menu
> items to submenus.  This cuts down the number of items on the top
> level of the menu to 17 compared to 21 before.  This buys us the space
> to add three separators too.

I think you've sent the wrong patch.

Thanks.

bug#39042: 26.3; Undocumented keys for Info mode

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 416 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> Please see the attached patch, where I also suggest to move some menu
>> items to submenus.  This cuts down the number of items on the top
>> level of the menu to 17 compared to 21 before.  This buys us the space
>> to add three separators too.
>
> I think you've sent the wrong patch.

Oops, thanks.  The correct patch should be attached here.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-Info-mode-doc-and-menu.patch --]
[-- Type: text/x-diff, Size: 3339 bytes --]

From 8e44a3d4088a1cc9bca8c6042d136f46d8189d73 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 28 Apr 2020 01:05:20 +0200
Subject: [PATCH] Improve Info-mode doc and menu

* lisp/info.el (Info-mode-menu): Re-arrange to be more logical, move
items into submenus, add 'Info-directory' and separators.
(Info-mode): Add 'end-of-buffer' to doc string.  (Bug#39042)
---
 lisp/info.el | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/lisp/info.el b/lisp/info.el
index 703907b98f..004e08f0ea 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -4079,22 +4079,28 @@ Info-check-pointer
     :help "Go to top node of file"]
    ["Final Node" Info-final-node
     :help "Go to final node in this file"]
+   "---"
    ("Menu Item" ["You should never see this" report-emacs-bug t])
    ("Reference" ["You should never see this" report-emacs-bug t])
    ["Search..." Info-search
     :help "Search for regular expression in this Info file"]
    ["Search Next" Info-search-next
     :help "Search for another occurrence of regular expression"]
-   ["Go to Node..." Info-goto-node
+   "---"
+   ("History"
+    ["Back in history" Info-history-back :active Info-history
+     :help "Go back in history to the last node you were at"]
+    ["Forward in history" Info-history-forward :active Info-history-forward
+     :help "Go forward in history"]
+    ["Show History" Info-history :active Info-history-list
+     :help "Go to menu of visited nodes"])
+   ("Jump to"
+    ["Go to Node..." Info-goto-node
     :help "Go to a named node"]
-   ["Back in history" Info-history-back :active Info-history
-    :help "Go back in history to the last node you were at"]
-   ["Forward in history" Info-history-forward :active Info-history-forward
-    :help "Go forward in history"]
-   ["History" Info-history :active Info-history-list
-    :help "Go to menu of visited nodes"]
-   ["Table of Contents" Info-toc
-    :help "Go to table of contents"]
+    ["Table of Contents" Info-toc
+     :help "Go to table of contents"]
+    ["Go to Directory" Info-directory
+     :help "Go to the Info directory node."])
    ("Index"
     ["Lookup a String..." Info-index
      :help "Look for a string in the index items"]
@@ -4104,10 +4110,12 @@ Info-check-pointer
      :help "Look for a string in the index items and display node with results"]
     ["Lookup a string in all indices..." info-apropos
      :help "Look for a string in the indices of all manuals"])
-   ["Copy Node Name" Info-copy-current-node-name
-    :help "Copy the name of the current node into the kill ring"]
-   ["Clone Info buffer" clone-buffer
-    :help "Create a twin copy of the current Info buffer."]
+   ("Misc"
+    ["Copy Node Name" Info-copy-current-node-name
+     :help "Copy the name of the current node into the kill ring"]
+    ["Clone Info buffer" clone-buffer
+     :help "Create a twin copy of the current Info buffer."])
+   "---"
    ["Exit" quit-window :help "Stop reading Info"]))
 
 
@@ -4358,6 +4366,7 @@ Info-mode
 	  already visible, try to go to the previous menu entry, or up
 	  if there is none.
 \\[beginning-of-buffer]	Go to beginning of node.
+\\[end-of-buffer]	Go to end of node.
 
 Advanced commands:
 \\[Info-search]	Search through this Info file for specified regexp,
-- 
2.26.2

bug#39042: 26.3; Undocumented keys for Info mode

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 39042@debbugs.gnu.org,  idirectscm@aim.com
> Date: Tue, 28 Apr 2020 09:44:41 +0200
> 
> -   ["Go to Node..." Info-goto-node
> +   "---"
> +   ("History"
> +    ["Back in history" Info-history-back :active Info-history
> +     :help "Go back in history to the last node you were at"]
> +    ["Forward in history" Info-history-forward :active Info-history-forward
> +     :help "Go forward in history"]
> +    ["Show History" Info-history :active Info-history-list
> +     :help "Go to menu of visited nodes"])
> +   ("Jump to"

I'd use "Go to", not "Jump to".

> -   ["Copy Node Name" Info-copy-current-node-name
> -    :help "Copy the name of the current node into the kill ring"]
> -   ["Clone Info buffer" clone-buffer
> -    :help "Create a twin copy of the current Info buffer."]
> +   ("Misc"
> +    ["Copy Node Name" Info-copy-current-node-name
> +     :help "Copy the name of the current node into the kill ring"]
> +    ["Clone Info buffer" clone-buffer
> +     :help "Create a twin copy of the current Info buffer."])

This only gains one menu item, at the price of hiding 2 items from the
user ("Misc" doesn't really say what's under it).  I'd leave these 2
alone.

Thanks.

bug#39042: 26.3; Undocumented keys for Info mode

[Stefan Kangas]

close 39042 28.1
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> I'd use "Go to", not "Jump to".
[...]
> This only gains one menu item, at the price of hiding 2 items from the
> user ("Misc" doesn't really say what's under it).  I'd leave these 2
> alone.

Thanks, I fixed your comments and pushed this to master as commit
11fd01c994.  Closing this bug.

Best regards,
Stefan Kangas