bug#19012: 25.0.50; `help-window-select'

[Drew Adams <drew.adams@oracle.com>]

>  > The description of `other' in the Customize buffer (and the doc
>  > string) is incorrect.  Or else the behavior is bugged.
>  >
>  > If *Help* is shown in its own frame (e.g. from *Help* being a
>  > special-display buffer), and if the option value is `other' (the
>  > default), then the *Help* window (and frame) are *not* selected,
>  > in contradiction to what the doc says.
>  >
>  > On MS Windows, at least, if the *Help* frame in this context does
>  > not yet exist then yes, that frame (and thus the *Help* window is
>  > selected - the frame gets the input focus.  But that is because
>  > Windows always gives a newly created frame the focus.  And if the
>  > frame exists already then no, the *Help* window and its frame are
>  > not selected.  Focus stays with the frame where you invoked the
>  > help command.
> 
> It does get selected here on Windows XP.  What happens when you set
> `help-window-select' to t?

The help window is still not selected.

> Did you create the *Help* window with `with-help-window'?
> If so, please tell me the value of the 'quit-restore window
> parameter of the *Help* window.

No, I guess not (see below), but I'm not sure.

And I did not read the note in the doc saying, "This option has
effect if and only if the help window was created by
`with-help-window'"  (That sentence is missing a period, BTW.)
Mea culpa.

So I guess maybe what I said in the bug report about the behavior not
matching the doc is wrong (i.e., is irrelevant).  The part about the
doc not being too clear might still help you, however.  If not, I
guess you can close the bug.

I am on Windows 7 (but on XP the behavior was the same).
This is the relevant code:

(add-to-list
 'special-display-buffer-names
 (list "*Help*" '1on1-display-*Help*-frame
       (list (cons 'background-color 1on1-help-frame-background)
             (cons 'mouse-color 1on1-help-frame-mouse+cursor-color)
             (cons 'cursor-color 1on1-help-frame-mouse+cursor-color)
             '(height . 40))))

(defun 1on1-display-*Help*-frame (buf &optional args)
  "Display *Help* buffer in its own frame.
`special-display-function' is used to do the actual displaying.
BUF and ARGS are the arguments to `special-display-function'."
  (let ((old-ptr-shape  (and (boundp 'x-pointer-shape) x-pointer-shape))
        return-window)
    (when (boundp 'x-pointer-xterm) (setq x-pointer-shape  x-pointer-xterm))
    (setq return-window
          (select-window (funcall special-display-function buf args)))
    (raise-frame)
    (setq x-pointer-shape  old-ptr-shape)
    return-window))

Does that mean that `with-help-window' is not involved?  Maybe so,
but it's not obvious to me.  How is a user supposed to know whether
this option applies, i.e., whether "the help window was created by
`with-help-window'?

And why shouldn't such an option apply in general for the help window?
Why must it depend on how the window is created?

>  > Note too that the description is anyway inadequate, because it
>  > seems to make the assumption that there *is* another window on
>  > the help window's frame: "unless the selected window is the only
>  > other window on the help window's frame" is not clear for the
>  > case where there is no such other window.
> 
> When there is "no such other window" the selected window "is not the
> only other window on the help window's frame".  What am I missing?

Maybe so, but it's not very clear, IMO.  The vacuous case should be
mentioned explicitly, I think, and not depend for its understanding on
finessing the logic.  Just say, for value `other', that "if the help
window is alone in its frame then it is selected".

With the scenario I described (*Help* is alone in its frame, in a
dedicated window, and the *Help* frame exists prior to calling the
help command) and with a value of `other' or `t', the *Help* window
is *not* selected.

With your interpretation, the "unless" condition is false, so the
*Help* window should be selected (except that perhaps
`with-help-window' is not involved - dunno about that).