bug#40915: [PATCH] Make leaving Info-summary more intuitive

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Stefan Kangas]

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

Severity: minor

There's a small issue with the Info-summary command:

0. emacs -Q
1. C-h i
2. ?
3. q

Result: Now in *scratch* buffer
Expected: Should end up in *info* buffer

The attached patch should fix it by not pushing the character ('q' in
this case) onto 'unread-command-events' before burying the help
buffer.

Best regards,
Stefan Kangas


In GNU Emacs 28.0.50 (build 14, x86_64-pc-linux-gnu, GTK+ Version
3.24.18, cairo version 1.16.0)
 of 2020-04-27 built on joffe

[-- Attachment #2: 0001-Make-leaving-Info-summary-more-intuitive.patch --]
[-- Type: text/x-patch, 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#40915: [PATCH] Make leaving Info-summary more intuitive

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 28 Apr 2020 00:28:31 +0200
> 
> There's a small issue with the Info-summary command:
> 
> 0. emacs -Q
> 1. C-h i
> 2. ?
> 3. q
> 
> Result: Now in *scratch* buffer
> Expected: Should end up in *info* buffer

I'm not sure I understand the expected result.  The help buffer
displayed when you press '?' says:

  q	Quit Info: reselect previously selected buffer.

So it seems Info behaves as documented?  The way to exit the help
screen and return to the Info manual is by repeatedly pressing SPC
until you wind up in the original Info buffer.

> The attached patch should fix it by not pushing the character ('q' in
> this case) onto 'unread-command-events' before burying the help
> buffer.

I could understand that we'd like to have a single key to quit the
help screen, perhaps even when 'q' is pressed (which would be a change
in behavior), but even then it is IMO wrong to completely remove the
pushing onto unread-command-events, because this command is set such
that you could read about a key and execute it while still in the help
screen.  IOW, the fact that the key you pres is generally executed
after exiting the help screen is an important feature: it avoids the
need to remember the key you found in *Help* and retype it after you
are back in the Info buffer.

Thanks.

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I'm not sure I understand the expected result.  The help buffer
> displayed when you press '?' says:
>
>   q     Quit Info: reselect previously selected buffer.
>
> So it seems Info behaves as documented?  The way to exit the help
> screen and return to the Info manual is by repeatedly pressing SPC
> until you wind up in the original Info buffer.

Sure, the result is formally correct.  It's just counter-intuitive.

Normally when I say 'q' in the "*Help*" buffer, I bury it.  But here,
'q' buries two buffers.

> I could understand that we'd like to have a single key to quit the
> help screen, perhaps even when 'q' is pressed (which would be a change
> in behavior), but even then it is IMO wrong to completely remove the
> pushing onto unread-command-events, because this command is set such
> that you could read about a key and execute it while still in the help
> screen.  IOW, the fact that the key you pres is generally executed
> after exiting the help screen is an important feature: it avoids the
> need to remember the key you found in *Help* and retype it after you
> are back in the Info buffer.

Thanks for explaining the motivation behind that feature.

I'm fine with doing a less invasive change: treat 'q' as a special
case in Info-summary.  Many users are hardwired to press 'q' to make a
"*Help*" buffer go away.

However, there is an inconsistency between modes; in view-mode and
special-mode, '?' is bound to describe-major-mode.

Would it be worth it to be more consistent?  In other words, doing one of:

(a) make 'Info-summary' into a general help command and use it in more
places, or
(b) deprecate 'Info-summary' in favour of 'describe-mode'.

It seems to me that _if_ we think the 'Info-summary' behaviour is
useful, we would want to ensure more modes can benefit from it.  Or,
to put it another way, I don't see why it would be uniquely useful to
Info-mode -- it should be useful either in many more modes or nowhere.
I haven't formed a strong opinion on this, but it would be interesting
to hear what people think.

Best regards,
Stefan Kangas

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 28 Apr 2020 09:37:38 +0200
> Cc: 40915@debbugs.gnu.org
> 
> > I could understand that we'd like to have a single key to quit the
> > help screen, perhaps even when 'q' is pressed (which would be a change
> > in behavior), but even then it is IMO wrong to completely remove the
> > pushing onto unread-command-events, because this command is set such
> > that you could read about a key and execute it while still in the help
> > screen.  IOW, the fact that the key you pres is generally executed
> > after exiting the help screen is an important feature: it avoids the
> > need to remember the key you found in *Help* and retype it after you
> > are back in the Info buffer.
> 
> Thanks for explaining the motivation behind that feature.
> 
> I'm fine with doing a less invasive change: treat 'q' as a special
> case in Info-summary.  Many users are hardwired to press 'q' to make a
> "*Help*" buffer go away.
> 
> However, there is an inconsistency between modes; in view-mode and
> special-mode, '?' is bound to describe-major-mode.

What is describe-major-mode?  Did you mean describe-mode?

> Would it be worth it to be more consistent?  In other words, doing one of:
> 
> (a) make 'Info-summary' into a general help command and use it in more
> places, or
> (b) deprecate 'Info-summary' in favour of 'describe-mode'.
> 
> It seems to me that _if_ we think the 'Info-summary' behaviour is
> useful, we would want to ensure more modes can benefit from it.  Or,
> to put it another way, I don't see why it would be uniquely useful to
> Info-mode -- it should be useful either in many more modes or nowhere.
> I haven't formed a strong opinion on this, but it would be interesting
> to hear what people think.

Info mode is special: it is used to read the manual, including the
Emacs manual and the manual for the Info system itself.  IOW, we have
a kind-of "bootstrapping" problem here: we need to teach how to use
the system/mode by using that same system/mode.

describe-mode shows the same text for Info, but it also shows much
more, which for the new user is pure clutter and source of confusion.
It also pops up a new window, which is another problem: the user may
not know at that point how to work with more than one window.  This is
not an important consideration for the general Help commands, but it
is for Info.

So I think the case of Info _is_ special, and consistency
considerations are much less important here than an attempt to present
a simple and effective help buffer to users who may not yet know any
"advanced" features.

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Drew Adams]

> In other words, doing one of:
> 
> (a) make 'Info-summary' into a general help command and use it in more
> places, or
> (b) deprecate 'Info-summary' in favour of 'describe-mode'.
> 
> It seems to me that _if_ we think the 'Info-summary' behaviour is
> useful, we would want to ensure more modes can benefit from it.  Or,
> to put it another way, I don't see why it would be uniquely useful to
> Info-mode -- it should be useful either in many more modes or nowhere.
> I haven't formed a strong opinion on this, but it would be interesting
> to hear what people think.

I don't really understand.  Info-summary is a
help command that describes Info.  You can invoke
it anywhere - not just in Info, so I don't see
why it would be deprecated and its content given
to describe-mode.

For (a), what do you mean by a "general" help
command?  The point of Info-summary is to provide
succinct help about Info.

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Drew Adams]

> I don't really understand.  Info-summary is a
> help command that describes Info.  You can invoke
> it anywhere - not just in Info, so I don't see
> why it would be deprecated and its content given
> to describe-mode.
> 
> For (a), what do you mean by a "general" help
> command?  The point of Info-summary is to provide
> succinct help about Info.

To be clearer:

In my library info+.el I long ago replaced binding
Info-summary to `?' and `C-h m', binding those to
`describe-mode'.  But I don't see why Info-summary
should be removed/deprecated.  It has a different
purpose: providing only a summary of Info, not all
the other info that describe-mode provides.

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> For (a), what do you mean by a "general" help
> command?  The point of Info-summary is to provide
> succinct help about Info.

I meant that you can have a command which works in any major mode very
easily:

 (defun Info-summary ()
   "Display a brief summary of all Info commands."
   (interactive)
   (save-window-excursion
     (switch-to-buffer "*Help*")
     (setq buffer-read-only nil)
     (erase-buffer)
-    (insert (documentation 'Info-mode))
+    (insert (documentation major-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)))
     (bury-buffer "*Help*")))

Best regards,
Stefan Kangas

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Drew Adams]

> > For (a), what do you mean by a "general" help
> > command?  The point of Info-summary is to provide
> > succinct help about Info.
> 
> I meant that you can have a command which works in any major mode very
> easily:
> 
>  (defun Info-summary ()
>    "Display a brief summary of all Info commands."
>    (interactive)
>    (save-window-excursion
>      (switch-to-buffer "*Help*")
>      (setq buffer-read-only nil)
>      (erase-buffer)
> -    (insert (documentation 'Info-mode))
> +    (insert (documentation major-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)))
>      (bury-buffer "*Help*")))

I see.  +1.

But maybe consider something like this instead.
IOW, let it be useful for any major mode, from
anywhere, not just for the current major mode.

(defun summarize-major-mode (mode)
  (interactive
   (list (completing-read
          (format "Mode (default %s): " major-mode)
          obarray
          (lambda (ss)
            (and (commandp ss)
                 (boundp ss)
                 (string-match-p "-mode\\'"
                                 (symbol-name ss))))
          t nil nil major-mode)))
  ...) ; The rest as you showed

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Severity: minor
>
> There's a small issue with the Info-summary command:
>
> 0. emacs -Q
> 1. C-h i
> 2. ?
> 3. q
>
> Result: Now in *scratch* buffer
> Expected: Should end up in *info* buffer

Hm...  yes, that is a bit surprising...  but the *Help* buffer `?' pops
up is very special -- hitting any key (unbound) key does the normal `q'
action, so it kinda makes sense that `q' quits the *info* buffer.

I think the way it operates now feels natural, even though it's a bit
special.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#40915: [PATCH] Make leaving Info-summary more intuitive

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> There's a small issue with the Info-summary command:
>>
>> 0. emacs -Q
>> 1. C-h i
>> 2. ?
>> 3. q
>>
>> Result: Now in *scratch* buffer
>> Expected: Should end up in *info* buffer
>
> Hm...  yes, that is a bit surprising...  but the *Help* buffer `?' pops
> up is very special -- hitting any key (unbound) key does the normal `q'
> action, so it kinda makes sense that `q' quits the *info* buffer.
>
> I think the way it operates now feels natural, even though it's a bit
> special.

There didn't seem to be much enthusiasm for changing the behaviour here
(even if it is untypical for Emacs), so I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no