GNU bug report logs - #40915
[PATCH] Make leaving Info-summary more intuitive

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 40915 in the body.
You can then email your comments to 40915 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: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 00:28:31 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Make-leaving-Info-summary-more-intuitive.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 40915 <at> debbugs.gnu.org
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 10:09:00 +0300

> From: Stefan Kangas <stefan <at> 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.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 40915 <at> debbugs.gnu.org
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 09:37:38 +0200

Eli Zaretskii <eliz <at> 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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 40915 <at> debbugs.gnu.org
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 10:57:17 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Tue, 28 Apr 2020 09:37:38 +0200
> Cc: 40915 <at> 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.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 40915 <at> debbugs.gnu.org
Subject: RE: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 10:11:26 -0700 (PDT)

> 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.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 40915 <at> debbugs.gnu.org
Subject: RE: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 10:17:26 -0700 (PDT)

> 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.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 40915 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 19:39:15 +0200

Drew Adams <drew.adams <at> 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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 40915 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: RE: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Tue, 28 Apr 2020 11:43:54 -0700 (PDT)

> > 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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 40915 <at> debbugs.gnu.org
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Sat, 08 Aug 2020 14:13:39 +0200

Stefan Kangas <stefan <at> 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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 40915 <at> debbugs.gnu.org
Subject: Re: bug#40915: [PATCH] Make leaving Info-summary more intuitive
Date: Wed, 07 Oct 2020 06:31:42 +0200

Lars Ingebrigtsen <larsi <at> 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

Previous Next

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