bug#36767: 26.1; request: add more quick keys to the *Help* buffer

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[ndame]

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

The Help buffer shows a link to the source code where the symbol is
defined. Add the currently unbound key 's' to quickly visit the source
code without having to navigate to the link.

Also, the user may want to read more about the symbol if it is
a built in one, so add a quick way to visit the Info page
of the symbol which Help is shown. The currently unbound key 'i' is
suitable for this purpose.


 

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

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Drew Adams]

This is really two different feature requests, IMO.
Here is a reply to this one (your second one): 

> Also, the user may want to read more about the
> symbol if it is a built in one, so add a quick
> way to visit the Info page of the symbol which
> Help is shown. The currently unbound key 'i' is
> suitable for this purpose.

This is the same text I replied to your similar
post in help-gnu-emacs@gnu.org.

----

What you request was discussed very recently on
emacs-devel@gnu.org.

I wrote this there:

 Since 2011 library `help-fns+.el' has had that feature.

 And it's user configurable - not just on/off, by
 option `help-cross-reference-manuals':

 1. Choose the list of manuals to search. Default:
    Emacs and Elisp manuals.

 2. Choose whether to (a) search systematically,
    when `*Help*' is created, and add a `manuals'
    link only if search finds hits, or (b) always
    create a link, and search only when the link
    is followed.  Default: (b).

https://lists.gnu.org/archive/html/emacs-devel/2019-07/msg00242.html

This feature is implemented by searching the
manuals listed in a user option.  By default,
the manuals are Emacs and Elisp.  But you can
choose any Info manuals you like.

Now if Emacs itself implemented such a feature
then there might presumably be no need to search
for the right manual location(s) to visit either
(a) when you display the *Help* that contains the
link or (b) when you click the link.

Emacs itself could perhaps have an internal table
that gets populated at build time - at least for
manuals such as Emacs and Elisp.

And if more manuals were chosen by a user (by such
an option) then those additional manuals could be
handled similarly to what `help-fns+.el' does now:
user choice whether to search (a) when *Help* gets
displayed (slow, and useless if there's no match)
or (b) only when you click the link for Info.

Note that the `help-fns+.el' implementation adds
a single link in *Help*.  When followed, if there
are hits in both Emacs and Elisp then it goes to
an Info buffer that has a links to each of those
manuals.  (If only one manual covers it then the
link takes you directly to that location.)

https://www.emacswiki.org/emacs/download/help-fns%2b.el 

----

As for the keys you suggest for your two requested
features: `s' is already bound to `Info-search',
and `i' is already bound to `Info-index'.  Those
keys are longstanding and should not be changed.



 

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Basil L. Contovounesios]

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

> As for the keys you suggest for your two requested
> features: `s' is already bound to `Info-search',
> and `i' is already bound to `Info-index'.  Those
> keys are longstanding and should not be changed.

I believe the feature request is for *Help*, not *info*, buffers.

-- 
Basil

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

ndame <emacsuser@freemail.hu> writes:

> The Help buffer shows a link to the source code where the symbol is
> defined. Add the currently unbound key 's' to quickly visit the source
> code without having to navigate to the link.
>
> Also, the user may want to read more about the symbol if it is
> a built in one, so add a quick way to visit the Info page
> of the symbol which Help is shown. The currently unbound key 'i' is
> suitable for this purpose.

Makes sense to me -- you can tab to the button, and `C-h S' works, but
both are more fiddly, so I've added these commands to Emacs 28.

Which was unexpectedly quite a lot of work, since the *Help* buffers
don't really seem to have any data available to say what they're about.  

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

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Juri Linkov]

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

>> The Help buffer shows a link to the source code where the symbol is
>> defined. Add the currently unbound key 's' to quickly visit the source
>> code without having to navigate to the link.
>>
>> Also, the user may want to read more about the symbol if it is
>> a built in one, so add a quick way to visit the Info page
>> of the symbol which Help is shown. The currently unbound key 'i' is
>> suitable for this purpose.
>
> Makes sense to me -- you can tab to the button, and `C-h S' works, but
> both are more fiddly, so I've added these commands to Emacs 28.

Another missing key is a way to easily customize a variable or a face.
Currently it's a hassle to navigate to the [Customize] button,
whereas with a key when point is on a variable name
it would be possible to type just 'C-h v RET c' to customize it.

> Which was unexpectedly quite a lot of work, since the *Help* buffers
> don't really seem to have any data available to say what they're about.

Since you've already done all the hard work,
it was very easy to add a new command:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help-customize.patch --]
[-- Type: text/x-diff, Size: 1488 bytes --]

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 48cf435f97..24b7ffaa2a 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -46,6 +46,7 @@ help-mode-map
     (define-key map "\r" 'help-follow)
     (define-key map "s" 'help-view-source)
     (define-key map "i" 'help-goto-info)
+    (define-key map "c" 'help-customize)
     map)
   "Keymap for Help mode.")
 
@@ -63,7 +64,9 @@ help-mode-menu
     ["View Source" help-view-source
      :help "Go to the source file for the current help item"]
     ["Goto Info" help-goto-info
-     :help "Go to the info node for the current help item"]))
+     :help "Go to the info node for the current help item"]
+    ["Customize" help-customize
+     :help "Customize variable or face"]))
 
 (defvar help-mode-tool-bar-map
   (let ((map (make-sparse-keymap)))
@@ -746,6 +749,16 @@ help-goto-info
   (info-lookup-symbol (plist-get help-mode--current-data :symbol)
                       'emacs-lisp-mode))
 
+(defun help-customize ()
+  "Customize variable or face."
+  (interactive nil help-mode)
+  (let ((sym (plist-get help-mode--current-data :symbol)))
+    (unless (or (boundp sym) (facep sym))
+      (user-error "No variable or face to customize"))
+    (cond
+     ((boundp sym) (customize-variable sym))
+     ((facep sym) (customize-face sym)))))
+
 (defun help-do-xref (_pos function args)
   "Call the help cross-reference function FUNCTION with args ARGS.
 Things are set up properly so that the resulting help-buffer has

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Thu, 17 Jun 2021 23:34:36 +0300
> Cc: 36767@debbugs.gnu.org, ndame <emacsuser@freemail.hu>
> 
> it would be possible to type just 'C-h v RET c' to customize it.

You forget the need to switch to the *Help* buffer before typing 'c',
don't you?

And that need to go to *Help* is, for me, the single significant
annoyance with Help commands.  For example, I frequently want to look
at the source of a function whose doc string I just requested, and its
a nuisance to have to click on the button there or go to the *Help*
buffer, find the button, and press RET.

So how about some special prefix key and a keymap to allow invoking
these commands from a buffer other than *Help*?

> diff --git a/lisp/help-mode.el b/lisp/help-mode.el
> index 48cf435f97..24b7ffaa2a 100644
> --- a/lisp/help-mode.el
> +++ b/lisp/help-mode.el

No changes in documentation to go with this?

Thanks.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Robert Pluim]

>>>>> On Fri, 18 Jun 2021 09:02:18 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Juri Linkov <juri@linkov.net>
    >> Date: Thu, 17 Jun 2021 23:34:36 +0300
    >> Cc: 36767@debbugs.gnu.org, ndame <emacsuser@freemail.hu>
    >> 
    >> it would be possible to type just 'C-h v RET c' to customize it.

    Eli> You forget the need to switch to the *Help* buffer before typing 'c',
    Eli> don't you?

    Eli> And that need to go to *Help* is, for me, the single significant
    Eli> annoyance with Help commands.  For example, I frequently want to look
    Eli> at the source of a function whose doc string I just requested, and its
    Eli> a nuisance to have to click on the button there or go to the *Help*
    Eli> buffer, find the button, and press RET.

I guess you donʼt like (setq help-window-select t)

    Eli> So how about some special prefix key and a keymap to allow invoking
    Eli> these commands from a buffer other than *Help*?

That would be good

Robert
-- 

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Juri Linkov <juri@linkov.net>,  36767@debbugs.gnu.org,  larsi@gnus.org,
>   emacsuser@freemail.hu
> Date: Fri, 18 Jun 2021 09:20:02 +0200
> 
>     Eli> And that need to go to *Help* is, for me, the single significant
>     Eli> annoyance with Help commands.  For example, I frequently want to look
>     Eli> at the source of a function whose doc string I just requested, and its
>     Eli> a nuisance to have to click on the button there or go to the *Help*
>     Eli> buffer, find the button, and press RET.
> 
> I guess you donʼt like (setq help-window-select t)

The nuisance is to have to switch to the Help window.  That variable
saves the command to switch to it, but it doesn't change the fact that
you are no longer in your original window/buffer.  Viewing help
shouldn't interfere with the window/buffer where you do your main
work, IMO.

bug#36767: [External] : bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Drew Adams]

> I guess you donʼt like (setq help-window-select t)

+1.  I'd even suggest that that be the default,
arguing that it's more helpful - for new users
especially.

Martin added that variable in 2007 (Emacs 23).
(See the old bug with subject "q doesn't always
quit *Help*".)

It was normal for its default value not to change
the longstanding behavior.  But maybe it's time
to consider changing its default value?  If you
think so, maybe the question should be raised in
emacs-devel?

bug#36767: [External] : bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Drew Adams]

> >     Eli> And that need to go to *Help* is, for me, the single significant
> >     Eli> annoyance with Help commands.  For example, I frequently want to
> look
> >     Eli> at the source of a function whose doc string I just requested, and
> its
> >     Eli> a nuisance to have to click on the button there or go to the
> *Help*
> >     Eli> buffer, find the button, and press RET.
> >
> > I guess you donʼt like (setq help-window-select t)
> 
> The nuisance is to have to switch to the Help window.  That variable
> saves the command to switch to it, but it doesn't change the fact that
> you are no longer in your original window/buffer.  Viewing help
> shouldn't interfere with the window/buffer where you do your main
> work, IMO.

I think the two are separate/separable.  Your point
about not necessarily always wanting to switch to
the Help window is valid.  But it's also useful to
switch to the Help window automatically.  Whether
that window should be switched to automatically is
governed by a user preference, as it should be.

There are lots of reasons one might want to be in
the Help window.  Whether some actions there might
merit also being available on keys from other
buffers is a different question (and yes, it's the
question of this thread).
___

It might also be possible for help commands to have
a particular prefix argument effect the opposite
behavior from `help-window-select'.  E.g., with
that prefix arg, the Help window would be selected
only if `help-window-select' is nil.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Stephen Berman]

On Fri, 18 Jun 2021 13:58:32 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Robert Pluim <rpluim@gmail.com>
>> Cc: Juri Linkov <juri@linkov.net>,  36767@debbugs.gnu.org,  larsi@gnus.org,
>>   emacsuser@freemail.hu
>> Date: Fri, 18 Jun 2021 09:20:02 +0200
>> 
>>     Eli> And that need to go to *Help* is, for me, the single significant
>>     Eli> annoyance with Help commands.  For example, I frequently want to look
>>     Eli> at the source of a function whose doc string I just requested, and its
>>     Eli> a nuisance to have to click on the button there or go to the *Help*
>>     Eli> buffer, find the button, and press RET.
>> 
>> I guess you donʼt like (setq help-window-select t)
>
> The nuisance is to have to switch to the Help window.  That variable
> saves the command to switch to it, but it doesn't change the fact that
> you are no longer in your original window/buffer.  Viewing help
> shouldn't interfere with the window/buffer where you do your main
> work, IMO.

I'm using this:

(defun srb-quit-help (&optional any-frame)
  "Quit *Help* buffer without selecting it.
With prefix argument ANY-FRAME quit *Help* on any visible frame,
otherwise quit *Help* buffer only on the selected frame."
  (interactive "P")
  (let ((help-window (get-buffer-window "*Help*" (if any-frame 'visible))))
    (when help-window
      (with-selected-window help-window (quit-window)))))
(global-set-key "\C-cq" 'srb-quit-help)

Of course, if such a command were added to Emacs, it would need a key
binding not reserved for users, and that's where the real difficulty
lies.

Steve Berman

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: Robert Pluim <rpluim@gmail.com>,  36767@debbugs.gnu.org,
>   larsi@gnus.org,  emacsuser@freemail.hu,  juri@linkov.net
> Date: Fri, 18 Jun 2021 16:32:23 +0200
> 
> > The nuisance is to have to switch to the Help window.  That variable
> > saves the command to switch to it, but it doesn't change the fact that
> > you are no longer in your original window/buffer.  Viewing help
> > shouldn't interfere with the window/buffer where you do your main
> > work, IMO.
> 
> I'm using this:
> 
> (defun srb-quit-help (&optional any-frame)
>   "Quit *Help* buffer without selecting it.
> With prefix argument ANY-FRAME quit *Help* on any visible frame,

Thanks.  But what I'd like to have is not a way of burying the Help
window, because I frequently need to consult it for quite some time.
What I'd like to have is a way of using its buttons without going to
that other window first.  For example, I'd love a command, bound to a
key globally, that would display the source of the function in the
same window as the Help window, then allow me to go back to the Help
window.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Stephen Berman]

On Fri, 18 Jun 2021 17:45:13 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <stephen.berman@gmx.net>
>> Cc: Robert Pluim <rpluim@gmail.com>,  36767@debbugs.gnu.org,
>>   larsi@gnus.org,  emacsuser@freemail.hu,  juri@linkov.net
>> Date: Fri, 18 Jun 2021 16:32:23 +0200
>>
>> > The nuisance is to have to switch to the Help window.  That variable
>> > saves the command to switch to it, but it doesn't change the fact that
>> > you are no longer in your original window/buffer.  Viewing help
>> > shouldn't interfere with the window/buffer where you do your main
>> > work, IMO.
>>
>> I'm using this:
>>
>> (defun srb-quit-help (&optional any-frame)
>>   "Quit *Help* buffer without selecting it.
>> With prefix argument ANY-FRAME quit *Help* on any visible frame,
>
> Thanks.  But what I'd like to have is not a way of burying the Help
> window, because I frequently need to consult it for quite some time.
> What I'd like to have is a way of using its buttons without going to
> that other window first.  For example, I'd love a command, bound to a
> key globally, that would display the source of the function in the
> same window as the Help window, then allow me to go back to the Help
> window.

The command `help-view-source' that Lars recently added could probably
help here, with some tweaking.  It calls
help-function-def--button-function, which calls pop-to-buffer with no
ACTION argument, which results in the source buffer being displayed a
different window than the *Help* buffer's window.  So the first
adjustment would be to add an optional ACTION argument.  As far a
returning from the source file to the *Help* buffer, the easiest way I
can think of to do that is if the source file is visited in View mode:
then `q' would bury its buffer, returning to *Help* (I think).  Or would
that not satisfy your use case?  In any case, such a change to
help-function-def--button-function would probably be undesirable in
other cases, so rather than changing that function it would probably be
better to add a new function using the ACTION argument and View mode.
Then that would need to be wrapped in a command like the one I suggested
to use it outside of *Help*, and likewise for View-quit.  That's
starting to sound rather brittle, so maybe it's not a good idea after
all.

Steve Berman

bug#36767: [External] : bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Drew Adams]

> I'm using this:
> 
> (defun srb-quit-help (&optional any-frame)
>   "Quit *Help* buffer without selecting it.
> With prefix argument ANY-FRAME quit *Help* on any visible frame,
> otherwise quit *Help* buffer only on the selected frame."
>   (interactive "P")
>   (let ((help-window (get-buffer-window "*Help*" (if any-frame 'visible))))
>     (when help-window
>       (with-selected-window help-window (quit-window)))))
> (global-set-key "\C-cq" 'srb-quit-help)
> 
> Of course, if such a command were added to Emacs, it would need a key
> binding not reserved for users, and that's where the real difficulty
> lies.

FWIW, I use this, which I bind to `q' (remap `quit-window'):

;; Candidate as a replacement for `quit-window', at least
;; when used interactively.  For example:
;; (define-key global-map [remap quit-window] 'quit-window-delete)
;;
;; Thanks to Martin Rudalics for suggestions.
;;
(defun quit-window-delete (&optional kill window)
  "Quit WINDOW, deleting it, and bury its buffer.
WINDOW must be a live window and defaults to the selected one.
With prefix argument KILL non-nil, kill the buffer instead of
burying it.

This is similar to the version of `quit-window' that Emacs had before
the introduction of `quit-restore-window'.  It ignores the information
stored in WINDOW's `quit-restore' window parameter.

It deletes the WINDOW more often, rather than switching to another
buffer in it.  If WINDOW is alone in its frame then the frame is
deleted or iconified, according to option `frame-auto-hide-function'."
  (interactive "P")
  (set-window-parameter window 'quit-restore `(frame frame nil ,(current-buffer)))
  (quit-restore-window window (if kill 'kill 'bury)))

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: rpluim@gmail.com,  36767@debbugs.gnu.org,  larsi@gnus.org,
>   emacsuser@freemail.hu,  juri@linkov.net
> Date: Fri, 18 Jun 2021 18:02:54 +0200
> 
> > Thanks.  But what I'd like to have is not a way of burying the Help
> > window, because I frequently need to consult it for quite some time.
> > What I'd like to have is a way of using its buttons without going to
> > that other window first.  For example, I'd love a command, bound to a
> > key globally, that would display the source of the function in the
> > same window as the Help window, then allow me to go back to the Help
> > window.
> 
> The command `help-view-source' that Lars recently added could probably
> help here, with some tweaking.  It calls
> help-function-def--button-function, which calls pop-to-buffer with no
> ACTION argument, which results in the source buffer being displayed a
> different window than the *Help* buffer's window.  So the first
> adjustment would be to add an optional ACTION argument.  As far a
> returning from the source file to the *Help* buffer, the easiest way I
> can think of to do that is if the source file is visited in View mode:
> then `q' would bury its buffer, returning to *Help* (I think).  Or would
> that not satisfy your use case?

I don't know, I'd have to try.

But surely, we could devise other methods to get back to the Help
buffer, ones that don't require View mode.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Juri Linkov]

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

>> it would be possible to type just 'C-h v RET c' to customize it.
>
> You forget the need to switch to the *Help* buffer before typing 'c',
> don't you?

I have no such problems because of using windmove-display-*
commands where the prefix arg defines whether to select
the displayed window or not.

Maybe describe-* commands could accept the same prefix arg
where C-u will reverse the value of help-window-select
the same way as C-u of windmove-display-* reverses the value
of windmove-display-no-select.

> And that need to go to *Help* is, for me, the single significant
> annoyance with Help commands.  For example, I frequently want to look
> at the source of a function whose doc string I just requested, and its
> a nuisance to have to click on the button there or go to the *Help*
> buffer, find the button, and press RET.
>
> So how about some special prefix key and a keymap to allow invoking
> these commands from a buffer other than *Help*?

To look at the source of a function, a quicker key is `M-.'
or `C-u M-.' that reads a symbol name.

>> diff --git a/lisp/help-mode.el b/lisp/help-mode.el
>> index 48cf435f97..24b7ffaa2a 100644
>> --- a/lisp/help-mode.el
>> +++ b/lisp/help-mode.el
>
> No changes in documentation to go with this?

Here is the documentation:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help-customize-doc.patch --]
[-- Type: text/x-diff, Size: 801 bytes --]

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 8c24a926af..f144fd2922 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -456,6 +456,8 @@ Help Mode
 (@code{help-view-source}).
 @item i
 Look up the current topic in the manual(s) (@code{help-goto-info}).
+@item c
+Customize the variable or the face (@code{help-customize}).
 @end table
 
 @cindex hyperlink
diff --git a/etc/NEWS b/etc/NEWS
index da1372baf4..b1f1673fd3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1133,6 +1133,10 @@ topic.
 *** New command 'help-goto-info' ('i')
 This command will look up the current symbol (if any) in Info.
 
++++
+*** New command 'help-customize' ('c').
+This command will customize the variable or the face (if any).
+
 ---
 *** The 'help-for-help' ('C-h C-h') screen has been redesigned.
 

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: larsi@gnus.org,  36767@debbugs.gnu.org,  emacsuser@freemail.hu
> Date: Fri, 18 Jun 2021 22:14:05 +0300
> 
> >> it would be possible to type just 'C-h v RET c' to customize it.
> >
> > You forget the need to switch to the *Help* buffer before typing 'c',
> > don't you?
> 
> I have no such problems because of using windmove-display-*
> commands where the prefix arg defines whether to select
> the displayed window or not.

What does windmove have to do with this?

> > So how about some special prefix key and a keymap to allow invoking
> > these commands from a buffer other than *Help*?
> 
> To look at the source of a function, a quicker key is `M-.'
> or `C-u M-.' that reads a symbol name.

That doesn't work well with cross-links in the doc strings, because
you need to type the name of the symbol.  I want a command that will
do the equivalent of TAB in the Help buffer, but which will work from
another buffer.

> +*** New command 'help-customize' ('c').
> +This command will customize the variable or the face (if any).

I think this should make it clear the variable/face are those whose
doc string is being shown in *Help*.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[martin rudalics]

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

 > Thanks.  But what I'd like to have is not a way of burying the Help
 > window, because I frequently need to consult it for quite some time.
 > What I'd like to have is a way of using its buttons without going to
 > that other window first.  For example, I'd love a command, bound to a
 > key globally, that would display the source of the function in the
 > same window as the Help window, then allow me to go back to the Help
 > window.

The attached is an attempt to do that.  Buggy and the nomenclature is
immature but I hope you get the idea.

martin

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help-mode.diff --]
[-- Type: text/x-patch; name="help-mode.diff", Size: 3230 bytes --]

--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -200,6 +200,66 @@ 'help-customize-face
 		   (customize-face v))
   'help-echo (purecopy "mouse-2, RET: customize face"))

+(defvar help-function-def-same-window nil)
+(defvar help-function-def-window nil)
+(defvar help-function-def-buffer nil)
+(defvar help-function-def-quit-restore nil)
+
+(defun help-forward-same-window ()
+  "Go to link following point of help window in that window."
+  (interactive)
+  (let* ((buffer (get-buffer "*Help*"))
+         (window (and buffer (get-buffer-window buffer))))
+    (if window
+        (with-selected-window window
+          (save-excursion
+            (let ((button (forward-button (point-min)))
+	          (help-function-def-same-window t))
+              (if button
+                  (progn
+                    (setq help-function-def-window window)
+                    (setq help-function-def-buffer buffer)
+                    (setq help-function-def-quit-restore
+                          (window-parameter window 'quit-restore))
+                    (button-activate button))
+                (message "No link found")))))
+      (message "No help window found"))))
+
+(defun help-backward-same-window ()
+  "Go back to help window."
+  (interactive)
+  (if (and (window-live-p help-function-def-window)
+           (buffer-live-p help-function-def-buffer))
+      (let ((buffer (window-buffer help-function-def-window)))
+        (set-window-buffer
+         help-function-def-window help-function-def-buffer)
+        (when help-function-def-quit-restore
+          ;; Pretend that window's buffer was never display in window.
+          (set-window-prev-buffers
+           help-function-def-window
+           (assq-delete-all
+            buffer (window-prev-buffers help-function-def-window)))
+          (set-window-parameter
+           help-function-def-window 'quit-restore
+           help-function-def-quit-restore))
+        (setq help-function-def-window nil)
+        (setq help-function-def-buffer nil)
+        (setq help-function-def-quit-restore nil))
+    (message "Cannot find help window or its buffer")))
+
+(defun help-window-quit ()
+  "Quit any help window found."
+  (interactive)
+  (let* ((buffer (get-buffer "*Help*"))
+         (window (and buffer (get-buffer-window buffer))))
+    (if window
+        (quit-restore-window window)
+      (message "No help window found"))))
+
+(define-key goto-map "f" 'help-forward-same-window)
+(define-key goto-map "b" 'help-backward-same-window)
+(define-key goto-map "q" 'help-window-quit)
+
 (defun help-function-def--button-function (fun &optional file type)
   (or file
       (setq file (find-lisp-object-file-name fun type)))
@@ -214,7 +274,9 @@ help-function-def--button-function
     (let* ((location
             (find-function-search-for-symbol fun type file))
            (position (cdr location)))
-      (pop-to-buffer (car location))
+      (if help-function-def-same-window
+          (pop-to-buffer-same-window (car location))
+        (pop-to-buffer (car location)))
       (run-hooks 'find-function-after-hook)
       (if position
           (progn

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> Cc: 36767@debbugs.gnu.org, rpluim@gmail.com, emacsuser@freemail.hu,
>  larsi@gnus.org, juri@linkov.net
> From: martin rudalics <rudalics@gmx.at>
> Date: Sat, 19 Jun 2021 11:08:52 +0200
> 
>  > Thanks.  But what I'd like to have is not a way of burying the Help
>  > window, because I frequently need to consult it for quite some time.
>  > What I'd like to have is a way of using its buttons without going to
>  > that other window first.  For example, I'd love a command, bound to a
>  > key globally, that would display the source of the function in the
>  > same window as the Help window, then allow me to go back to the Help
>  > window.
> 
> The attached is an attempt to do that.  Buggy and the nomenclature is
> immature but I hope you get the idea.

Thanks, looks like a good start.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Another missing key is a way to easily customize a variable or a face.
> Currently it's a hassle to navigate to the [Customize] button,
> whereas with a key when point is on a variable name
> it would be possible to type just 'C-h v RET c' to customize it.

Thanks; looks good to me -- go ahead and push (with NEWS/doc entries).

Eli points out that it'd also be nice to use these commands from outside
the *Help* buffer, too -- and that's true, but it's kinda unusual for
commands to act that way?  I can't think of many other commands (except
`C-M-v') that act on the "other" window.

But perhaps *Help* is a special case here.

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

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 19 Jun 2021 13:58:14 +0200
> Cc: 36767@debbugs.gnu.org, ndame <emacsuser@freemail.hu>
> 
> Eli points out that it'd also be nice to use these commands from outside
> the *Help* buffer, too -- and that's true, but it's kinda unusual for
> commands to act that way?

I didn't necessarily mean the same commands, they could be separate
commands.  What's important to me is their effect.

> I can't think of many other commands (except `C-M-v') that act on
> the "other" window.

Some GUD commands, like the one which sets breakpoints, are similar:
they can be invoked from the GUD buffer and -- with another, more
complex, key sequence -- from the program source buffer as well.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Juri Linkov]

> What does windmove have to do with this?

The same argument:

>> Maybe describe-* commands could accept the same prefix arg
>> where C-u will reverse the value of help-window-select
>> the same way as C-u of windmove-display-* reverses the value
>> of windmove-display-no-select.

> That doesn't work well with cross-links in the doc strings, because
> you need to type the name of the symbol.  I want a command that will
> do the equivalent of TAB in the Help buffer, but which will work from
> another buffer.

This is easy to implement the same way as windmove-display-* implemented,
i.e. a prefix key will allow to select another window, execute the
next command in another window, then select the old window back.

>> +*** New command 'help-customize' ('c').
>> +This command will customize the variable or the face (if any).
>
> I think this should make it clear the variable/face are those whose
> doc string is being shown in *Help*.

Done.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Juri Linkov]

>> Another missing key is a way to easily customize a variable or a face.
>> Currently it's a hassle to navigate to the [Customize] button,
>> whereas with a key when point is on a variable name
>> it would be possible to type just 'C-h v RET c' to customize it.
>
> Thanks; looks good to me -- go ahead and push (with NEWS/doc entries).

Now pushed.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[martin rudalics]

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

 > Thanks, looks like a good start.

Attached find a slightly simpler and hopefully more correct version.

martin

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help-mode.diff --]
[-- Type: text/x-patch; name="help-mode.diff", Size: 3285 bytes --]

--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -200,6 +200,64 @@ 'help-customize-face
 		   (customize-face v))
   'help-echo (purecopy "mouse-2, RET: customize face"))

+(defvar help-link-follow nil
+  "Information stored by `help-link-follow'.
+If this is non-nil, `help-function-def--button-function' will try to
+display its location in the \"same\" window.")
+
+(defun help-link-follow ()
+  "Follow or return from first link in help window.
+If this function finds a help window, it will try to display in
+that window the buffer referred to by the first link found in its
+help buffer.  If there is no help window, this function will try
+to restore the help window from an earlier followed link."
+  (interactive)
+  (cond
+   ((let* ((buffer (get-buffer "*Help*"))
+           (window (and buffer (get-buffer-window buffer))))
+      (and window
+           (with-selected-window window
+             (save-excursion
+               (let ((button (forward-button (point-min)))
+                     (par (window-parameter window 'quit-restore)))
+                 (if button
+                     (condition-case nil
+                         (progn
+                           (setq help-link-follow (list buffer window par))
+                           (button-activate button))
+                       (error (setq help-link-follow nil)))
+                   (user-error "No link found"))))))))
+   ((and help-link-follow
+         (buffer-live-p (nth 0 help-link-follow))
+         (window-live-p (nth 1 help-link-follow)))
+    (let* ((window (nth 1 help-link-follow))
+           (buffer (window-buffer window)))
+      (set-window-buffer window (nth 0 help-link-follow))
+      (when (nth 2 help-link-follow)
+        ;; Pretend that the window's buffer was never displayed in this
+        ;; window to avoid that quitting the help window restores that
+        ;; buffer in the help window.
+        (set-window-prev-buffers
+         window (assq-delete-all buffer (window-prev-buffers window)))
+        (set-window-parameter
+         window 'quit-restore (nth 2 help-link-follow)))
+      (setq help-link-follow nil)))
+   (t
+    (setq help-link-follow nil)
+    (user-error "No help link found"))))
+
+(defun help-window-quit ()
+  "Quit any help window found."
+  (interactive)
+  (let* ((buffer (get-buffer "*Help*"))
+         (window (and buffer (get-buffer-window buffer))))
+    (if window
+        (quit-restore-window window)
+      (user-error "No help window found"))))
+
+(define-key help-map "\C-l" 'help-link-follow)
+(define-key help-map "\C-q" 'help-window-quit)
+
 (defun help-function-def--button-function (fun &optional file type)
   (or file
       (setq file (find-lisp-object-file-name fun type)))
@@ -214,7 +272,10 @@ help-function-def--button-function
     (let* ((location
             (find-function-search-for-symbol fun type file))
            (position (cdr location)))
-      (pop-to-buffer (car location))
+      (if help-link-follow
+          (display-buffer
+           (car location) display-buffer--same-window-action)
+        (pop-to-buffer (car location)))
       (run-hooks 'find-function-after-hook)
       (if position
           (progn

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

Arthur Miller <arthur.miller@live.com> writes:

>> I just thought it would be confusing -- two links in the first line that
>> does different things.  But I'm not against it per se.
>
> I had same thought about entire buffer! My thought was that color
> coding links would visually separate them from each other (say yellow
> for info green for help blue for source etc), but than it would become
> a christmass tree :).

Making the function name into a link would help with discoverability.
And since the link would start at bobp, TAB would still take you to the
second link, so it wouldn't be annoying.

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

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

Arthur Miller <arthur.miller@live.com> writes:

> You can see how it looks like. I have attached a small screenshot too,
> so you don't need to apply it just to see how it looks like. The file
> name at the end of the header is probably clear on it's own; the
> symbol link is as clear/unclear as rest of the links in the buffer.

(You're doing all these mails in a bug report that has been archived, so
the only other people who's reading them are the ones in the CCs.  If
you wish to discuss things publicly, either do so in emacs-devel or open
a new bug report.)

I fixed up your patch so that it works more reliably, but then I
remembered why I didn't add the link: We don't know at this point
whether the symbol in question is documented in the manual.  Adding a
link to something that fails is bad UI.  And we can't check whether the
symbol exists in the manual when generating the *Help* buffer, because
it's slow, and the trade-off (making the command slow versus an extra
link) is not a good one.

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

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 551cf7e1a3..4d6d13ea42 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -367,6 +367,11 @@ 'help-news
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+(define-button-type 'help-symbol-info
+  :supertype 'help-xref
+  'help-function #'help-goto-info
+  'help-echo (purecopy "mouse-2, RET: read this info node"))
 \f
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)
@@ -538,6 +543,15 @@ help-make-xrefs
           ;; The following should probably be abstracted out.
           (unwind-protect
               (progn
+                ;; Make a button of the first time the symbol appears
+                ;; in the buffer.
+                (save-excursion
+                  (when-let ((symbol (plist-get help-mode--current-data
+                                                :symbol)))
+                    (when (or (symbolp symbol) (fboundp symbol))
+                      (goto-char (point-min))
+                      (when (search-forward (symbol-name symbol) nil t)
+                        (help-xref-button 0 'help-symbol-info)))))
                 ;; Info references
                 (save-excursion
                   (while (re-search-forward help-xref-info-regexp nil t)

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

Arthur Miller <arthur.miller@live.com> writes:

> I explained in the first paragraph why you need to hack them. So that
> you can call them from other windows and buffers. As they are
> currently implemented they expect to be called from help buffer, so
> that is culprit why you can't call them from the buffer of some source
> you are editing. I have wrapped those two:

The *Help* buffer commands are fine as they are.  If you want to add
other commands (that aren't in the *Help* buffer), you should define new
ones.

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

bug#36767: [External] : bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Drew Adams]

> Making the function name into a link would help with discoverability.
> And since the link would start at bobp, TAB would still take you to the
> second link, so it wouldn't be annoying.

FWIW, the bug report (enhancement request) was not about
adding links (buttons).  It was about adding key bindings.

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[martin rudalics]

 > I fixed up your patch so that it works more reliably, but then I
 > remembered why I didn't add the link: We don't know at this point
 > whether the symbol in question is documented in the manual.  Adding a
 > link to something that fails is bad UI.  And we can't check whether the
 > symbol exists in the manual when generating the *Help* buffer, because
 > it's slow, and the trade-off (making the command slow versus an extra
 > link) is not a good one.

It would be nice to have an etags-like tool that produces a table of all
symbols documented in installed manuals.

martin

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Lars Ingebrigtsen]

martin rudalics <rudalics@gmx.at> writes:

> It would be nice to have an etags-like tool that produces a table of all
> symbols documented in installed manuals.

Yup.

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

bug#36767: 26.1; request: add more quick keys to the *Help* buffer

[Eli Zaretskii]

> From: martin rudalics <rudalics@gmx.at>
> Date: Sun, 26 Sep 2021 11:11:22 +0200
> Cc: 36767@debbugs.gnu.org, ndame <emacsuser@freemail.hu>
> 
>  > I fixed up your patch so that it works more reliably, but then I
>  > remembered why I didn't add the link: We don't know at this point
>  > whether the symbol in question is documented in the manual.  Adding a
>  > link to something that fails is bad UI.  And we can't check whether the
>  > symbol exists in the manual when generating the *Help* buffer, because
>  > it's slow, and the trade-off (making the command slow versus an extra
>  > link) is not a good one.
> 
> It would be nice to have an etags-like tool that produces a table of all
> symbols documented in installed manuals.

You should be able to use 'etags' itself, it allows you to define
symbols via regular expressions.