help-window-select and info-lookup-symbol

help-window-select and info-lookup-symbol

[Helmut Eller]

It seems to me that C-h S and C-h f are so similar that both commands
should honor the value of help-window-select.  In fact, there are a lot
of (third party) packages with a display-documentation-in-other-window
command but there seems to be no agreement whether the window should be
selected or not.  Especially annoying is the fact that XEmacs usually
selects the other window while Emacs usually does not.

It would be very nice if you, the Emacs maintainers, could make a rule
or style-guide how this should be done.  E.g. should other packages look
at help-window-select or is that an "internal" variable of help-mode?

I understand that restoring the window configuration after pressing q in
the help window (or info window, or w3m buffer) is sort of tricky and it
gets very complex if multiple frames are involved, yet selecting the
help window is what many users expect.  Since restoring is so tricky it
would also be helpful if there were some general functions to do it
properly.

Helmut.

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 > It seems to me that C-h S and C-h f are so similar that both commands
 > should honor the value of help-window-select.  In fact, there are a lot
 > of (third party) packages with a display-documentation-in-other-window
 > command but there seems to be no agreement whether the window should be
 > selected or not.  Especially annoying is the fact that XEmacs usually
 > selects the other window while Emacs usually does not.

C-h f is a self-contained function while C-h S falls back on `info' for
displaying its findings.  Obviously, a common approach to handle these
and similar cases would be desirable.

 > It would be very nice if you, the Emacs maintainers, could make a rule
 > or style-guide how this should be done.  E.g. should other packages look
 > at help-window-select or is that an "internal" variable of help-mode?

Currently `help-window-select' is an "internal" variable of help-mode.

 > I understand that restoring the window configuration after pressing q in
 > the help window (or info window, or w3m buffer) is sort of tricky and it
 > gets very complex if multiple frames are involved, yet selecting the
 > help window is what many users expect.  Since restoring is so tricky it
 > would also be helpful if there were some general functions to do it
 > properly.

Restoring an old window configuration is awfully tricky.  Let W1 denote
the window configuration before invoking help, W2 the configuration
after invoking help (and after any `fit-window-to-buffer' and balancing
stuff), and W3 the configuration when you press `q'.  A brute force
approach (currently used by info or backtrace) simply restores W1 whe
you press `q' which all so often drives me mad because it destroys the
windows and window-buffer associations I have created in between.

Now theoretically, I could restore W1 if and only if the configurations
W2 and W3 are equal.  In practice, however, this approach often failed
here.  Hence, I tried to base the comparison on a weaker predicate of
equality which ignored the identities of buffers displayed in other
windows and the relative sizes of windows.  I got it to work for help
buffers but was not able to make it work realiably with info buffers.

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-20 11:32+0200] writes:

> Restoring an old window configuration is awfully tricky.  Let W1 denote
> the window configuration before invoking help, W2 the configuration
> after invoking help (and after any `fit-window-to-buffer' and balancing
> stuff), and W3 the configuration when you press `q'.  A brute force
> approach (currently used by info or backtrace) simply restores W1 whe
> you press `q' which all so often drives me mad because it destroys the
> windows and window-buffer associations I have created in between.

For the debugger it's IMO the best option.

> Now theoretically, I could restore W1 if and only if the configurations
> W2 and W3 are equal.  In practice, however, this approach often failed
> here.  Hence, I tried to base the comparison on a weaker predicate of
> equality which ignored the identities of buffers displayed in other
> windows and the relative sizes of windows.  I got it to work for help
> buffers but was not able to make it work realiably with info buffers.

Comparing W2 and W3 per compare-window-configurations would probably
work as a start, but point should probably not be restored.

Here's the code that we use currently:

(defun slime-close-popup-window ()
  (when slime-popup-restore-data
    (destructuring-bind (popup-window selected-window old-buffer)
        slime-popup-restore-data
      (bury-buffer)
      (when (eq popup-window (selected-window))
        (cond ((and (not old-buffer) (not (one-window-p)))
               (delete-window popup-window))
              ((and old-buffer (buffer-live-p old-buffer))
               (set-window-buffer popup-window old-buffer))))
      (when (window-live-p selected-window)
        (select-window selected-window)))
    (kill-local-variable 'slime-popup-restore-data)))

popup-window is the window that displays the help content at W2.
selected-window was selected at W1.
old-buffer was the buffer associated with popup-window at W1.

It's far from perfect and it was a PITA to write.

Helmut.

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 >> A brute force
 >> approach (currently used by info or backtrace) simply restores W1 whe
 >> you press `q' which all so often drives me mad because it destroys the
 >> windows and window-buffer associations I have created in between.
 >
 > For the debugger it's IMO the best option.

When debugging an application which creates a new buffer I have to
create that buffer before running the application in order to see how it
gets filled.  Otherwise, the debugger won't let me see it for long.
Maybe I could show it in another frame, but I don't want to resize my
main frame in order to make another one visible.

 >> Now theoretically, I could restore W1 if and only if the configurations
 >> W2 and W3 are equal.  In practice, however, this approach often failed
 >> here.  Hence, I tried to base the comparison on a weaker predicate of
 >> equality which ignored the identities of buffers displayed in other
 >> windows and the relative sizes of windows.  I got it to work for help
 >> buffers but was not able to make it work realiably with info buffers.
 >
 > Comparing W2 and W3 per compare-window-configurations would probably
 > work as a start, but point should probably not be restored.

My info windows are sometimes open for a couple of minutes, mostly
because I'm to lazy to quit them.  Quitting them at last offers me an
interesting albeit chaotic view of my session's archeology.

 > (defun slime-close-popup-window ()
 >   (when slime-popup-restore-data
 >     (destructuring-bind (popup-window selected-window old-buffer)
 >         slime-popup-restore-data
 >       (bury-buffer)
 >       (when (eq popup-window (selected-window))
 >         (cond ((and (not old-buffer) (not (one-window-p)))
 >                (delete-window popup-window))
 >               ((and old-buffer (buffer-live-p old-buffer))
 >                (set-window-buffer popup-window old-buffer))))
 >       (when (window-live-p selected-window)
 >         (select-window selected-window)))
 >     (kill-local-variable 'slime-popup-restore-data)))
 >
 > popup-window is the window that displays the help content at W2.
 > selected-window was selected at W1.
 > old-buffer was the buffer associated with popup-window at W1.

How do you get the `old-buffer' and `popup-window' values in general?
By comparing window configurations before and after `display-buffer'?
My code included for every window a variable telling whether that window
was split off by `display-buffer' or which buffer the window displayed
before it was "used" by `display-buffer'.

I recall it proved very nasty to save the old buffer value when the
window is re-used again by `display-buffer' because I had to avoid that
a "valuable" non-help content buffer value would get overwritten by the
"uselss" value of a help-content buffer.

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-21 15:27+0200] writes:

>> (defun slime-close-popup-window ()
>>   (when slime-popup-restore-data
>>     (destructuring-bind (popup-window selected-window old-buffer)
>>         slime-popup-restore-data
>>       (bury-buffer)
>>       (when (eq popup-window (selected-window))
>>         (cond ((and (not old-buffer) (not (one-window-p)))
>>                (delete-window popup-window))
>>               ((and old-buffer (buffer-live-p old-buffer))
>>                (set-window-buffer popup-window old-buffer))))
>>       (when (window-live-p selected-window)
>>         (select-window selected-window)))
>>     (kill-local-variable 'slime-popup-restore-data)))
>>
>> popup-window is the window that displays the help content at W2.
>> selected-window was selected at W1.
>> old-buffer was the buffer associated with popup-window at W1.
>
> How do you get the `old-buffer' and `popup-window' values in general?
> By comparing window configurations before and after `display-buffer'?
> My code included for every window a variable telling whether that window
> was split off by `display-buffer' or which buffer the window displayed
> before it was "used" by `display-buffer'.

We do it by walking windows before and after display-buffer.  I guess
that window-config objects also contain the information it's just not
accessible from Lisp.

>
> I recall it proved very nasty to save the old buffer value when the
> window is re-used again by `display-buffer' because I had to avoid that
> a "valuable" non-help content buffer value would get overwritten by the
> "uselss" value of a help-content buffer.

That's the code that stashes the data into the buffer-local variable:

(defun slime-display-popup-buffer (select)
  "Display the current buffer.
Save the selected-window in a buffer-local variable, so that we
can restore it later."
  (let ((selected-window (selected-window))
        (old-windows))
    (walk-windows (lambda (w) (push (cons w (window-buffer w)) old-windows))
                  nil t)
    (let ((new-window (display-buffer (current-buffer))))
      (unless slime-popup-restore-data
        (set (make-local-variable 'slime-popup-restore-data)
             (list new-window
                   selected-window
                   (cdr (find new-window old-windows :key #'car)))))
      (when select
        (select-window new-window))
      (current-buffer))))

Helmut.

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 > We do it by walking windows before and after display-buffer.  I guess
 > that window-config objects also contain the information it's just not
 > accessible from Lisp.

AFAICT they don't have it.  It would be very simple to have window.el
provide a global variable that has the necessary information.
`with-help-window' could use it as well.  BTW you don't restore
`window-start' and `window-point' when you restore the buffer?

 > That's the code that stashes the data into the buffer-local variable:
 >
 > (defun slime-display-popup-buffer (select)
 >   "Display the current buffer.
 > Save the selected-window in a buffer-local variable, so that we
 > can restore it later."
 >   (let ((selected-window (selected-window))
 >         (old-windows))
 >     (walk-windows (lambda (w) (push (cons w (window-buffer w)) old-windows))
 >                   nil t)
 >     (let ((new-window (display-buffer (current-buffer))))
 >       (unless slime-popup-restore-data
 >         (set (make-local-variable 'slime-popup-restore-data)
 >              (list new-window
 >                    selected-window
 >                    (cdr (find new-window old-windows :key #'car)))))
 >       (when select
 >         (select-window new-window))
 >       (current-buffer))))

Doesn't that fail when you manually switch to a buffer B in such a
window?  In that case `slime-popup-restore-data' would remain non-nil
and a later call of `slime-display-popup-buffer' would not save the
value of B.

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-21 16:12+0200] writes:

>> We do it by walking windows before and after display-buffer.  I guess
>> that window-config objects also contain the information it's just not
>> accessible from Lisp.
>
> AFAICT they don't have it.  It would be very simple to have window.el
> provide a global variable that has the necessary information.
> `with-help-window' could use it as well.  BTW you don't restore
> `window-start' and `window-point' when you restore the buffer?

Nope.  To much work :-).  Well, it the most common case the window will
just be deleted and it doesn't matter.

>> That's the code that stashes the data into the buffer-local variable:
>>
>> (defun slime-display-popup-buffer (select)
>>   "Display the current buffer.
>> Save the selected-window in a buffer-local variable, so that we
>> can restore it later."
>>   (let ((selected-window (selected-window))
>>         (old-windows))
>>     (walk-windows (lambda (w) (push (cons w (window-buffer w)) old-windows))
>>                   nil t)
>>     (let ((new-window (display-buffer (current-buffer))))
>>       (unless slime-popup-restore-data
>>         (set (make-local-variable 'slime-popup-restore-data)
>>              (list new-window
>>                    selected-window
>>                    (cdr (find new-window old-windows :key #'car)))))
>>       (when select
>>         (select-window new-window))
>>       (current-buffer))))
>
> Doesn't that fail when you manually switch to a buffer B in such a
> window?  In that case `slime-popup-restore-data' would remain non-nil
> and a later call of `slime-display-popup-buffer' would not save the
> value of B.

Hmm.. no it wouldn't.  I wouldn't call that failing though.  One could
also argue that if the user switches to B and back that's a temporary
excursion and should have no permanent effect.  Right or Wrong depends
on the users expectations.  If the window was freshly created by
slime-display-popup-buffer the user might well expect that pressing q
will close it.  OTOH, some users have strange expectations; they expect
the exact opposite from what I would :-)

That's why a style-guide would be good: that "adjusts" the expectations.

Helmut.

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 > Hmm.. no it wouldn't.  I wouldn't call that failing though.  One could
 > also argue that if the user switches to B and back that's a temporary
 > excursion and should have no permanent effect.  Right or Wrong depends
 > on the users expectations.  If the window was freshly created by
 > slime-display-popup-buffer the user might well expect that pressing q
 > will close it.  OTOH, some users have strange expectations; they expect
 > the exact opposite from what I would :-)

The scenario I had in mind was that (1) `display-buffer' reuses a window
as a help-window (2) in that window the user manually switches to a
buffer via `switch-to-buffer' and (3) `display-buffer' again reuses that
window as a help-window.  Typing `q' in that window now will restore the
buffer shown before (1) and not the buffer shown by (2).  In this scenario
the `switch-to-buffer' hardly counts as a "temporary excursion".

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-22 12:11+0200] writes:

> The scenario I had in mind was that (1) `display-buffer' reuses a window
> as a help-window (2) in that window the user manually switches to a
> buffer via `switch-to-buffer' and (3) `display-buffer' again reuses that
> window as a help-window.  Typing `q' in that window now will restore the
> buffer shown before (1) and not the buffer shown by (2).  In this scenario
> the `switch-to-buffer' hardly counts as a "temporary excursion".

The command which prepares and displays the help buffer (in 1 and 3)
should probably wipe out the buffer-local variable.  
Not a big deal.  Is it?

Helmut.

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 > The command which prepares and displays the help buffer (in 1 and 3)
 > should probably wipe out the buffer-local variable.
 > Not a big deal.  Is it?

IIUC in that case a `display-buffer' following another would wipe out
the variable set by the former.  The problem is with recognizing whether
the buffer `display-buffer' is going to replace in some window was a
buffer the user switched to "manually" or "automatically".  In the
former case `display-buffer' should remember the buffer in its
`old-buffer' variable while in the latter it should leave that variable
alone.  Currently `display-buffer' has no means to distinguish these
cases.

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-26 12:01+0200] writes:

>> The command which prepares and displays the help buffer (in 1 and 3)
>> should probably wipe out the buffer-local variable.
>> Not a big deal.  Is it?
>
> IIUC in that case a `display-buffer' following another would wipe out
> the variable set by the former.  The problem is with recognizing whether
> the buffer `display-buffer' is going to replace in some window was a
> buffer the user switched to "manually" or "automatically".  In the
> former case `display-buffer' should remember the buffer in its
> `old-buffer' variable while in the latter it should leave that variable
> alone.  Currently `display-buffer' has no means to distinguish these
> cases.

I was thinking that a new function or macro would delete the
buffer-local variable before displaying the buffer, something like
with-help-window.  display-buffer would be called in the process but
display-buffer would know nothing about the buffer-local variable.

Helmut

Re: help-window-select and info-lookup-symbol

[martin rudalics]

 >> IIUC in that case a `display-buffer' following another would wipe out
 >> the variable set by the former.  The problem is with recognizing whether
 >> the buffer `display-buffer' is going to replace in some window was a
 >> buffer the user switched to "manually" or "automatically".  In the
 >> former case `display-buffer' should remember the buffer in its
 >> `old-buffer' variable while in the latter it should leave that variable
 >> alone.  Currently `display-buffer' has no means to distinguish these
 >> cases.
 >
 > I was thinking that a new function or macro would delete the
 > buffer-local variable before displaying the buffer, something like
 > with-help-window.  display-buffer would be called in the process but
 > display-buffer would know nothing about the buffer-local variable.

The functions that could safely decide whether a buffer-local-variable
shall be deleted is the "any function calling `display-buffer' but the
help/info type ones".  It's impossible to enumerate them all because
someone might add a new one tomorrow.

What could be done is provide a variable `do-not-wipe-out-old-value'
which is normally nil but the help/info type functions bind to t around
their `display-buffer' calls.  And `display-buffer' wouldn't wipe out
the old value if that variable is t.

martin

Re: help-window-select and info-lookup-symbol

[Helmut Eller]

* martin rudalics [2009-07-26 13:00+0200] writes:

>> I was thinking that a new function or macro would delete the
>> buffer-local variable before displaying the buffer, something like
>> with-help-window.  display-buffer would be called in the process but
>> display-buffer would know nothing about the buffer-local variable.
>
> The functions that could safely decide whether a buffer-local-variable
> shall be deleted is the "any function calling `display-buffer' but the
> help/info type ones".  It's impossible to enumerate them all because
> someone might add a new one tomorrow.

I think we aren't talking with each other.  If there is a (single)
function to initialize help buffers, let's call it display-help-buffer,
then there is exactly one function to enumerate.  The callers of
display-help-buffer don't count.

> What could be done is provide a variable `do-not-wipe-out-old-value'
> which is normally nil but the help/info type functions bind to t around
> their `display-buffer' calls.  And `display-buffer' wouldn't wipe out
> the old value if that variable is t.

display-buffer doesn't need to know what display-help-buffer does with
buffer-local variables.  Actually, display-buffer is already complicated
enough that it would be better to keep that separated.

Helmut