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

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

[Drew Adams]

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.

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.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

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

[martin rudalics]

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

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

martin

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

[Drew Adams]

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

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

[martin rudalics]

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

Who creates the *Help* buffer and who calls `display-buffer' in the case
at hand?

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

By trial and error, I suppose.  I wrote `with-help-window' seven years
ago because there were many complaints about the previous behavior.  And
I hardly had any complaints since that.  `with-help-window' has to cater
for people who don't know what an option is or how it can be
customized.  Still, those people want to get help via C-h and get rid of
that help afterwards.  When such people later find that the help window
gets selected in some unintuitive way they can tune the behavior using
this option.

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

Because it relies on things set up correctly at the time the window is
created.  Most of the work I put into `with-help-window' was about
storing information that would allow quitting to return to the previous
state as smoothly as possible.

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

I'll do that.

 > 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

Indeed.  It would be a bug if it didn't get selected.

 > (except that perhaps
 > `with-help-window' is not involved - dunno about that).

martin

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

[Drew Adams]

> Who creates the *Help* buffer and who calls `display-buffer' in the
> case at hand?

The usual displayers of *Help*: `C-h f', `C-h v', `C-h m', `C-h b',
...  And those do generally use `with-help-window'.

But as I mentioned, `display-buffer' in this case uses the logic
of `special-display':

(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))
    ^^^^^^^^^^^^^

>  > 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'?
> 
> By trial and error, I suppose... [When] the help window
> gets selected in some unintuitive way they can tune the behavior
> using this option.

OK.  It doesn't seem to work in the case I presented: *Help* shown
in a dedicated window in a separate frame.

>  > say, for value `other', that "if the help window is alone in
>  > its frame then it is selected".
> 
> I'll do that.

Thanks.

> Indeed.  It would be a bug if it didn't get selected.

That was my hope.  It does not get selected, even with an option
value of `t'.

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

[martin rudalics]

This one is at least dubious

 >      (setq return-window  (select-window
                              ^^^^^^^^^^^^^
 >                            (funcall special-display-function buf args)))

According to its doc-string `display-buffer' should

   Display BUFFER-OR-NAME in some window, without selecting it.

As a rule, `display-buffer' should not select the window used.
Otherwise, `with-help-window' cannot determine the correct window to
select when quitting help.

However, with the current release and trunk, emacs -Q and

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

(add-to-list
  'special-display-buffer-names
  (list "*Help*" '1on1-display-*Help*-frame
        (list '(height . 40))))

the *Help* window is always selected here after C-h f, C-h v, ...

martin

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

[Drew Adams]

> This one is at least dubious
>  >      (setq return-window  (select-window
>  >                            ^^^^^^^^^^^^^
>  >                            (funcall special-display-function buf args)))
> According to its doc-string `display-buffer' should
> 
>    Display BUFFER-OR-NAME in some window, without selecting it.
> 
> As a rule, `display-buffer' should not select the window used.
> Otherwise, `with-help-window' cannot determine the correct window to
> select when quitting help.

That is a new restriction (beginning with `display-buffer-alist'), if it
is one.  `display-buffer' should, as it did prior to `display-buffer-alist',
respect `special-display-buffer-names' and `special-display-function',
which has no such restriction wrt its value's behavior, AFAIK.

And there should be *no reason* for such a restriction.  The addition
of the zillion things that complicated `display-buffer' was supposed to
make it *more* flexible, not less, letting users get more and finer
control over the behavior - not losing the ability to use an arbitrary
display function.

If `display-buffer' with default values for everything does not want
to select the displayed buffer, fine.  But `display-buffer' trying to
prohibit a user-defined display function from selecting (or doing
anything else) would be unnecessarily restrictive: it is not
`display-buffer's business what a user-defined "display" function
might do.

Besides which, "according to its doc-string `display-buffer'..." is
not a reason.  Its doc string can say nothing about what user-defined
display function `special-display-function' does, beyond what the doc
for that variable says.  It says (and should say) nothing about not
selecting the displayed buffer's window in such a case.

> However, with the current release and trunk, emacs -Q and
> (defun 1on1-display-*Help*-frame (buf &optional args) ...
> (add-to-list 'special-display-buffer-names...
> the *Help* window is always selected here after C-h f, C-h v, ...

Well, there is also non-nil `pop-up-frames' etc.  But I see that from
`emacs -Q', with only the above and non-nil `pop-up-frames', what you
say is true, so there must be something else involved as well.  I will
take a look when I get some time.

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

[Drew Adams]

> Well, there is also non-nil `pop-up-frames' etc.  But I see that
> from `emacs -Q', with only the above and non-nil `pop-up-frames', what
> you say is true, so there must be something else involved as well.  I
> will take a look when I get some time.

Found it, I guess.

In addition to non-nil pop-up-frames and the other code sent previously,
do this: (setq w32-grab-focus-on-raise  nil)

Then, as I described, when the *Help* frame already exists it is not
selected by C-h v etc.

Now IIUC, that variable, `w32-grab-focus-on-raise', should only
stop Windows from having `raise-frame' always focus the frame.
That really is (should be) something different from this
(`help-window-select').

IOW, I do not want `raise-frame' to automatically focus the
frame for input each time.  But I might want `help-window-select'
to select the *Help* frame.  Make sense?

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

[Drew Adams]

As the "discussion" with Stefan about what `special-display-function'
can or cannot do might have distracted from the bug description,
let me repeat the recipe to repro the problem, and this time
without including code to select the returned window (which is
irrelevant to the bug, as the previous recipe should have made
clear).

The bug is apparently caused by `w32-grab-focus-on-raise' = nil.
That should only have the effect of not causing `raise-frame' to
focus the frame.  It should not prevent `help-window-select' (or
anything else) from selecting the window.

The effect should, because of `help-window-select' = t, be that
the *Help* window is selected.  Selection should not depend on
whether `raise-frame' happens to also select/focus.

The recipe, after `emacs -Q' and evaluating the code below:

1. C-h v pop-up-frames RET
   That correctly creates the *Help* frame.  And because
   MS Windows alwayse focuses a new frame, it has the focus.
   OK so far.

2. Select the original frame (e.g. with the mouse), so that
   it, not *Help*, now has the focus.

3. C-h v help-window-select RET
   The *Help* window & frame are not selected/focused.
   They should be.

The code:

(setq pop-up-frames  t)

;; This should cause the *Help* window to be selected.
(setq help-window-select  t)

;; This somehow causes the window/frame NOT to be selected.
;; If non-nil then there is no problem.
(setq w32-grab-focus-on-raise  nil)

(add-to-list 'special-display-buffer-names
	      '("*Help*" foo ((background-color . "Thistle"))))

(defun foo (buf &optional args)
  (let (win)
    (setq win  (funcall special-display-function buf args))
    (raise-frame)
    win))

Note that the doc string of `w32-grab-focus-on-raise'
specifically does not say that a value of nil means that
`raise-frame' takes the focus away (unfocuses).  It says
only that a value of t means that `raise-frame' focuses
the frame.

Since nothing is said for nil, the presumption should be
that a nil value has no particular effect on focus, i.e.,
that it neither "grabs input focus", as does t, nor
removes focus.

And all of this code is anyway inside `with-help-window'
because of `C-h v'.  So even if the bug were that
`raise-frame' removed the focus (unlike what the
`w-g-f-o-r' doc string says), `help-window-select'
should anyway ensure that *Help* is focused in the end.



----------------- What I said before ---------------
> Found it, I guess.
> 
> In addition to non-nil pop-up-frames and the other code sent
> previously, do this: (setq w32-grab-focus-on-raise  nil)
> 
> Then, as I described, when the *Help* frame already exists it is not
> selected by C-h v etc.
> 
> Now IIUC, that variable, `w32-grab-focus-on-raise', should only
> stop Windows from having `raise-frame' always focus the frame.
> That really is (should be) something different from this
> (`help-window-select').
> 
> IOW, I do not want `raise-frame' to automatically focus the
> frame for input each time.  But I might want `help-window-select'
> to select the *Help* frame.  Make sense?

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

[martin rudalics]

 > The bug is apparently caused by `w32-grab-focus-on-raise' = nil.
 > That should only have the effect of not causing `raise-frame' to
 > focus the frame.  It should not prevent `help-window-select' (or
 > anything else) from selecting the window.

What makes you sure that it does prevent `help-window-select' from
selecting the window?

 > The effect should, because of `help-window-select' = t, be that
 > the *Help* window is selected.  Selection should not depend on
 > whether `raise-frame' happens to also select/focus.

Then you know more than me.  `w32-grab-focus-on-raise', if nil, triggers
a DeferWindowPos type chain of events, see

http://msdn.microsoft.com/en-us/library/windows/desktop/ms632681%28v=vs.85%29.aspx

which is beyond my comprehension.

 > ;; This somehow causes the window/frame NOT to be selected.
 > ;; If non-nil then there is no problem.
 > (setq w32-grab-focus-on-raise  nil)

Then leave it non-nil.

 > Note that the doc string of `w32-grab-focus-on-raise'
 > specifically does not say that a value of nil means that
 > `raise-frame' takes the focus away (unfocuses).  It says
 > only that a value of t means that `raise-frame' focuses
 > the frame.
 >
 > Since nothing is said for nil, the presumption should be
 > that a nil value has no particular effect on focus, i.e.,
 > that it neither "grabs input focus", as does t, nor
 > removes focus.

If you understand what it does, provide a suitable doc-string.

 > And all of this code is anyway inside `with-help-window'
 > because of `C-h v'.  So even if the bug were that
 > `raise-frame' removed the focus (unlike what the
 > `w-g-f-o-r' doc string says), `help-window-select'
 > should anyway ensure that *Help* is focused in the end.

If you told us how `with-help-window' should deal with asynchronous
frame raise/focus events, we could try to find a solution.

 > ----------------- What I said before ---------------
 >> Found it, I guess.
 >>
 >> In addition to non-nil pop-up-frames and the other code sent
 >> previously, do this: (setq w32-grab-focus-on-raise  nil)
 >>
 >> Then, as I described, when the *Help* frame already exists it is not
 >> selected by C-h v etc.
 >>
 >> Now IIUC, that variable, `w32-grab-focus-on-raise', should only
 >> stop Windows from having `raise-frame' always focus the frame.
 >> That really is (should be) something different from this
 >> (`help-window-select').
 >>
 >> IOW, I do not want `raise-frame' to automatically focus the
 >> frame for input each time.  But I might want `help-window-select'
 >> to select the *Help* frame.  Make sense?

I can only repeat myself: I don't understand what is at work here and
how this is supposed to work.  `help-window-select' simply selects the
window if certain conditions are met.  How selection is implemented and
what consequences it has is platform dependent and beyond its control.

martin

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

[Drew Adams]

>  > The bug is apparently caused by `w32-grab-focus-on-raise' = nil.
>  > That should only have the effect of not causing `raise-frame' to
>  > focus the frame.  It should not prevent `help-window-select' (or
>  > anything else) from selecting the window.
> 
> What makes you sure that it does prevent `help-window-select' from
> selecting the window?

I did not say that it prevents that, and certainly not that I am
sure that it prevents that.  Please read what I actually said.

>  > The effect should, because of `help-window-select' = t, be that
>  > the *Help* window is selected.  Selection should not depend on
>  > whether `raise-frame' happens to also select/focus.
> 
> Then you know more than me.  

Again, I think you are not reading well what I wrote.  I claim
nothing about what is actually happening in the code.  I reported
symptoms, and I stated that there should not be such a dependency.
I did not say that there is any such dependency.

> `w32-grab-focus-on-raise', if nil,
> triggers a DeferWindowPos type chain of events, see
> http://msdn.microsoft.com/en-
> us/library/windows/desktop/ms632681%28v=vs.85%29.aspx
> which is beyond my comprehension.

If that article is beyond your comprehension then it is most
likely beyond mine as well.

But I mentioned an *Emacs* option.  Emacs decides the behavior
of that option.  I have said nothing about the Emacs
implementation.  I care about the resulting behavior, not how
the bug is fixed.

>  > ;; This somehow causes the window/frame NOT to be selected.
>  > ;; If non-nil then there is no problem.
>  > (setq w32-grab-focus-on-raise  nil)
> 
> Then leave it non-nil.

I've been clear that (a) I do not want `raise-frame' to focus
frames, and that (b) whether I, as one user, want that behavior
or not, the behavior of that option should not affect whether
`help-window-select' works.

>  > Note that the doc string of `w32-grab-focus-on-raise'
>  > specifically does not say that a value of nil means that
>  > `raise-frame' takes the focus away (unfocuses).  It says
>  > only that a value of t means that `raise-frame' focuses
>  > the frame.
>  >
>  > Since nothing is said for nil, the presumption should be
>  > that a nil value has no particular effect on focus, i.e.,
>  > that it neither "grabs input focus", as does t, nor
>  > removes focus.
> 
> If you understand what it does, provide a suitable doc-string.

Again, you are misreading, it seems.  (a) I did not say that I
understand what it actually does (beyond the bugged symptoms I
reported).  (b) I made it clear that the bug reported is about
the behavior, not a doc string.

>  > And all of this code is anyway inside `with-help-window'
>  > because of `C-h v'.  So even if the bug were that
>  > `raise-frame' removed the focus (unlike what the
>  > `w-g-f-o-r' doc string says), `help-window-select'
>  > should anyway ensure that *Help* is focused in the end.
> 
> If you told us how `with-help-window' should deal with
> asynchronous frame raise/focus events, we could try to find
> a solution.

It is you who stated what I should expect from the behavior
of `help-select-window', provided the context is
`with-help-window'.  *You* stated that it is a bug if the
window is not selected.

I have nothing to say about the implementation of
`with-help-window'.  I reported a bug in behavior.

It seems clear from your "if-you-know-so-much-then-fix-it"
over and over that you do not want to work on a fix for this.
That's your right, of course.  I reported the bug.  You
clarified some things about it.  Maybe someday Someone (TM)
will try to fix it.  Maybe not.

> I don't understand what is at work here and how this is
> supposed to work.  `help-window-select' simply selects the
> window if certain conditions are met.  How selection is
> implemented and what consequences it has is platform
> dependent and beyond its control.

Fair enough.  I have no idea either what combination of code
causes the bugged behavior.  One place (for Someone (TM)) to
look might be (just a guess) the code that implements and uses
`w32-grab-focus-on-raise'.

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

[martin rudalics]

 > I've been clear that (a) I do not want `raise-frame' to focus
 > frames, and that (b) whether I, as one user, want that behavior
 > or not, the behavior of that option should not affect whether
 > `help-window-select' works.

So you want `raise-frame' to not select the frame and `with-help-window'
select the frame?  Any preferences who should win that game?

 > It is you who stated what I should expect from the behavior
 > of `help-select-window', provided the context is
 > `with-help-window'.  *You* stated that it is a bug if the
 > window is not selected.

So far you did not provide any evidence that the window is not selected.

martin

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

[Drew Adams]

>  > I've been clear that (a) I do not want `raise-frame' to focus
>  > frames, and that (b) whether I, as one user, want that behavior
>  > or not, the behavior of that option should not affect whether
>  > `help-window-select' works.
> 
> So you want `raise-frame' to not select the frame and `with-help-
> window' select the frame?  Any preferences who should win that game?

There is no game.

1. `raise-frame' should not focus the frame (or unfocus it), unless
`w32-grab-focus-on-raise' is non-nil (or unless there is also some
other, similar option that makes `raise-frame' grab the focus).
And as far as I can tell, that is the case: it does not.

But even if it did, that should be irrelevant to what
`help-select-window' does (*this* bug).  `raise-frame' is punctual.
The scope and effect of `help-select-window' are controlled by
`with-help-window' (according to you, whom I believe; I'm no expert
on that, and that is not documented, AFAICT).

2. `help-window-select' = `t' (within `with-help-window', at least)
should select the help window.  (Likewise, for a value of `other',
unless the selected window is alone on the help-window's frame.)

This is all specified by the doc (except the connection between
`help-window-select' and `with-help-window').  And there is no
contradiction between #1 and #2.  `help-window-select' has nothing
to do with `w32-grab-focus-on-raise' and nothing to do with
`raise-frame' (at least according to its spec/doc). And it *should*
have nothing to do with them.

Whether `raise-frame' focuses the frame or not should be irrelevant
to the behavior imposed by `help-window-select'.  It is (according
to you) `with-help-window' that controls the scope of the effect
of `help-window-select'.  It is `with-help-window' that should
ensure that `help-window-select' has the effect it claims to have
when `with-help-window' is finished.

>  > It is you who stated what I should expect from the behavior
>  > of `help-select-window', provided the context is
>  > `with-help-window'.  *You* stated that it is a bug if the
>  > window is not selected.
> 
> So far you did not provide any evidence that the window is not
> selected.

Sure I did.  I said that it does not have the input focus.  Type
text and it goes to the window where you hit `C-h v'.  What's more,
the frame border highlighting shows that the frame is not focused.

You seem to be in denial, for some reason.  Believe me, the
*Help*-selecting effect of non-nil `help-select-window' disappears
if `w32-grab-focus-on-raise' is nil.

It should not disappear.  `w32-grab-focus-on-raise' should affect
only `raise-frame'.  And `help-window-select' & `with-help-window'
should not be affected by whether there is a call to `raise-frame'
or what such a call might do wrt frame focus.

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

[martin rudalics]

 >> So you want `raise-frame' to not select the frame and `with-help-
 >> window' select the frame?  Any preferences who should win that game?
 >
 > There is no game.
 >
 > 1. `raise-frame' should not focus the frame (or unfocus it), unless
 > `w32-grab-focus-on-raise' is non-nil (or unless there is also some
 > other, similar option that makes `raise-frame' grab the focus).
 > And as far as I can tell, that is the case: it does not.

IIUC the default behavior on Windows is that when you raise a frame,
that frame gets focus as well.  So if you set `w32-grab-focus-on-raise'
to nil, Emacs has to explicitly tell Windows to unfocus the frame.

 > But even if it did, that should be irrelevant to what
 > `help-select-window' does (*this* bug).

What is "*this* bug"?  You attribute a behavior you observe to a
variable that does not and cannot control that behavior.

 > `raise-frame' is punctual.

I have no idea what you mean here.

 > The scope and effect of `help-select-window' are controlled by
 > `with-help-window' (according to you, whom I believe; I'm no expert
 > on that, and that is not documented, AFAICT).

Scope and effect of `help-window-select' end where `with-help-window'
exits.

 > 2. `help-window-select' = `t' (within `with-help-window', at least)
 > should select the help window.  (Likewise, for a value of `other',
 > unless the selected window is alone on the help-window's frame.)
 >
 > This is all specified by the doc (except the connection between
 > `help-window-select' and `with-help-window').  And there is no
 > contradiction between #1 and #2.  `help-window-select' has nothing
 > to do with `w32-grab-focus-on-raise' and nothing to do with
 > `raise-frame' (at least according to its spec/doc). And it *should*
 > have nothing to do with them.

If `help-window-select' is t, `with-help-window' selects the frame
unconditionally.

 > Whether `raise-frame' focuses the frame or not should be irrelevant
 > to the behavior imposed by `help-window-select'.  It is (according
 > to you) `with-help-window' that controls the scope of the effect
 > of `help-window-select'.  It is `with-help-window' that should
 > ensure that `help-window-select' has the effect it claims to have
 > when `with-help-window' is finished.

Doesn't it?

 >>   > It is you who stated what I should expect from the behavior
 >>   > of `help-select-window', provided the context is
 >>   > `with-help-window'.  *You* stated that it is a bug if the
 >>   > window is not selected.
 >>
 >> So far you did not provide any evidence that the window is not
 >> selected.
 >
 > Sure I did.

You didn't even care to go through this with a debugger.  What kind of
evidence is that?

 > I said that it does not have the input focus.  Type
 > text and it goes to the window where you hit `C-h v'.  What's more,
 > the frame border highlighting shows that the frame is not focused.

This does not contradict that `with-help-window' selected the window.

 > You seem to be in denial, for some reason.  Believe me, the
 > *Help*-selecting effect of non-nil `help-select-window' disappears
 > if `w32-grab-focus-on-raise' is nil.

I never doubted that.  But it seems to me that you don't want to care
how a nil value for `w32-grab-focus-on-raise' gets processed.  There is
absolutely nothing `with-help-window' or any Elisp code can do there.

 > It should not disappear.  `w32-grab-focus-on-raise' should affect
 > only `raise-frame'.  And `help-window-select' & `with-help-window'
 > should not be affected by whether there is a call to `raise-frame'
 > or what such a call might do wrt frame focus.

You can't have both - select the frame and unfocus it.

martin

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

[Drew Adams]

>  > 1. `raise-frame' should not focus the frame (or unfocus it),
>  > unless `w32-grab-focus-on-raise' is non-nil (or unless there is also
>  > some other, similar option that makes `raise-frame' grab the focus).
>  > And as far as I can tell, that is the case: it does not.
> 
> IIUC the default behavior on Windows is that when you raise a frame,
> that frame gets focus as well.  So if you set `w32-grab-focus-on-
> raise' to nil, Emacs has to explicitly tell Windows to unfocus the frame.
> 
>  > But even if it did, that should be irrelevant to what
>  > `help-select-window' does (*this* bug).
> 
> What is "*this* bug"?  You attribute a behavior you observe to a
> variable that does not and cannot control that behavior.

Bug 19012.  As you admitted, if `help-window-select' is t, it is a bug
if `with-help-window' exits with the window not selected.
 
>  > `raise-frame' is punctual.
> 
> I have no idea what you mean here.

It takes place at a moment in time.  `with-help-window' has an effect
for a duration/scope.  `with-help-window', with `help-window-select'
= t, should ensure that the window is selected when it is finished.

>  > The scope and effect of `help-select-window' are controlled by
>  > `with-help-window' (according to you, whom I believe; I'm no
>  > expert on that, and that is not documented, AFAICT).
> 
> Scope and effect of `help-window-select' end where `with-help-
> window' exits.

Precisely.  And not before.

If Emacs is fixed so that `with-help-window' ensures that the window
is selected when it exits (with non-nil `help-window-select') then
this bug (#19012) can be closed.

>  > 2. `help-window-select' = `t' (within `with-help-window', at
>  > least) should select the help window.  (Likewise, for a value of
>  > `other', unless the selected window is alone on the help-window's
>  > frame.)
>  >
>  > This is all specified by the doc (except the connection between
>  > `help-window-select' and `with-help-window').  And there is no
>  > contradiction between #1 and #2.  `help-window-select' has
> nothing
>  > to do with `w32-grab-focus-on-raise' and nothing to do with
>  > `raise-frame' (at least according to its spec/doc). And it
> *should*
>  > have nothing to do with them.
> 
> If `help-window-select' is t, `with-help-window' selects the frame
> unconditionally.

Great.  Does it ensure that it is selected when it is finished?
It seems that that is not the case yet.  AFAICT (from the info you've
provided), that is the cause of the bugged behavior.

>  > Whether `raise-frame' focuses the frame or not should be
>  > irrelevant to the behavior imposed by `help-window-select'.
>  > It is (according to you) `with-help-window' that controls the scope
>  > of the effect of `help-window-select'.  It is `with-help-window'
>  > that should ensure that `help-window-select' has the effect it
>  > claims to have when `with-help-window' is finished.
> 
> Doesn't it?

Apparently not.  The window is not selected/focused.  (And the
`raise-frame' is called within `with-help-window', not after
`with-help-window' is finished.

>  >>   > It is you who stated what I should expect from the behavior
>  >>   > of `help-select-window', provided the context is
>  >>   > `with-help-window'.  *You* stated that it is a bug if the
>  >>   > window is not selected.
>  >>
>  >> So far you did not provide any evidence that the window is not
>  >> selected.
>  >
>  > Sure I did.
> 
> You didn't even care to go through this with a debugger.  What kind
> of evidence is that?

Dunno what that means.  If you have some recipe you'd like me to
follow, I'll see if I can try it.

>  > I said that it does not have the input focus.  Type
>  > text and it goes to the window where you hit `C-h v'.  What's
>  > more, the frame border highlighting shows that the frame is not
>  > focused.
> 
> This does not contradict that `with-help-window' selected the
> window.

I think it contradicts the expectation that `with-help-window'
ensures that the window is selected when it finishes.  After it
finishes, it of course has no more responsibility wrt whether it
is selected.

>  > You seem to be in denial, for some reason.  Believe me, the
>  > *Help*-selecting effect of non-nil `help-select-window'
>  > disappears if `w32-grab-focus-on-raise' is nil.
> 
> I never doubted that.  But it seems to me that you don't want to
> care how a nil value for `w32-grab-focus-on-raise' gets processed.

Yes, I don't want to get involved with the implementation or
trying to fix the problem.  I am willing to report the problem
and try to obtain more info about symptoms.

> There is absolutely nothing `with-help-window' or any Elisp code
> can do there.

I never said there was.  Perhaps that is the communication problem
here.  I never said that you are responsible for the bug or for
fixing it.  And I never said that the bug is due to Elisp code.
(In fact, since I discovered that it is nil `w32-*' that leads to
the bug, I've been supposing that the problem involves C code.)

>  > It should not disappear.  `w32-grab-focus-on-raise' should affect
>  > only `raise-frame'.  And `help-window-select' & `with-help-
>  > window' should not be affected by whether there is a call to
>  > `raise-frame' or what such a call might do wrt frame focus.
> 
> You can't have both - select the frame and unfocus it.

I'm not asking to unfocus the frame.  I'm asking that
`with-help-window' ensure that, when it exits, the window is
selected and the frame focused.  And that, regardless of whether
some code within its scope happens to focus some other frame
at some point.

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

[martin rudalics]

 >> What is "*this* bug"?  You attribute a behavior you observe to a
 >> variable that does not and cannot control that behavior.
 >
 > Bug 19012.

Then give us a recipe so we can reproduce that "bug".  Sections 51.3
"Understanding Bug Reporting" and 51.4 "Checklist for Bug Reports" of
the Emacs manual will give you further guidance.  Here with emacs -Q
and evaluating

(setq pop-up-frames t)
(setq w32-grab-focus-on-raise nil)
(setq help-window-select t)

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

(add-to-list
  'special-display-buffer-names
  (list "*Help*" '1on1-display-*Help*-frame
        (list '(height . 40))))

both C-h f and C-h v select the window showing *Help*.

martin

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

[Drew Adams]

> Then give us a recipe so we can reproduce that "bug"....
> Here with emacs -Q and evaluating...
> both C-h f and C-h v select the window showing *Help*.

Why do you not try the even simpler recipe I sent on 2014-11-12?
You clearly read that mail, as you replied to other parts of it.

With the latest Emacs build I have (and with others) the recipe
is 100% reproducible.  I am using MS Windows 7 64-bit.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Repository revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

Here is the recipe again:

1. emacs -Q
2. Evaluate the code shown below (after recipe #5).
3. C-h v pop-up-frames RET
   That correctly creates the *Help* frame.  And because
   MS Windows alwayse focuses a new frame, it has the focus.
   OK so far.
4. Select the original frame (e.g. with the mouse), so that
   it, not *Help*, now has the focus.
5. C-h v help-window-select RET
   The *Help* window & frame are not selected/focused.
   They should be.

The code to evaluate at step #2 above:
(setq pop-up-frames  t)
(setq help-window-select  t)
(setq w32-grab-focus-on-raise  nil)
(add-to-list 'special-display-buffer-names
	      '("*Help*" foo ((background-color . "Thistle"))))
(defun foo (buf &optional args)
  (let (win)
    (setq win  (funcall special-display-function buf args))
    (raise-frame)
    win))

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

[martin rudalics]

 > With the latest Emacs build I have (and with others) the recipe
 > is 100% reproducible.  I am using MS Windows 7 64-bit.

Maybe a Windows 7 issue.

 > 1. emacs -Q
 > 2. Evaluate the code shown below (after recipe #5).
 > 3. C-h v pop-up-frames RET
 >     That correctly creates the *Help* frame.  And because
 >     MS Windows alwayse focuses a new frame, it has the focus.
 >     OK so far.
 > 4. Select the original frame (e.g. with the mouse), so that
 >     it, not *Help*, now has the focus.
 > 5. C-h v help-window-select RET
 >     The *Help* window & frame are not selected/focused.
 >     They should be.
 >
 > The code to evaluate at step #2 above:
 > (setq pop-up-frames  t)
 > (setq help-window-select  t)
 > (setq w32-grab-focus-on-raise  nil)
 > (add-to-list 'special-display-buffer-names
 > 	      '("*Help*" foo ((background-color . "Thistle"))))
 > (defun foo (buf &optional args)
 >    (let (win)
 >      (setq win  (funcall special-display-function buf args))
 >      (raise-frame)
 >      win))

Unreproducible here.  After 5 the *Help* frame has focus again.
Sorry.

martin

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

[Drew Adams]

>  > With the latest Emacs build I have (and with others) the recipe
>  > is 100% reproducible.  I am using MS Windows 7 64-bit.
> 
> Maybe a Windows 7 issue.

I can't swear to it, but I think that I saw the same thing when
I was on Windows XP (32-bit).  That was more than a year ago
so I might not remember correctly.

> Unreproducible here.  After 5 the *Help* frame has focus again.
> Sorry.

Thanks for checking.  Hopefully someone else can check on
Windows 7 64-bit.

(I assume that you checked the focus by typing some text or
something.  Here, the text is inserted in the buffer when I
hit `C-h v'.)

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

[martin rudalics]

 > Thanks for checking.  Hopefully someone else can check on
 > Windows 7 64-bit.

Do the following: With emacs -Q eval the code below in *scratch*.  Next
do

1. M-x view-lossage

2. Go back to the *scratch* window.

3. M-x view-lossage

4. In the *scratch* window move to the line that reads
    (defvar selected-window nil), move right after selected-window,
    type C-x C-e.

Here I get #<window 6 on *Help*>.  What do you get?

martin



(defvar selected-window nil)

(setq pop-up-frames  t)
(setq help-window-select  t)
(setq w32-grab-focus-on-raise  nil)
(add-to-list 'special-display-buffer-names
	      '("*Help*" foo ((background-color . "Thistle"))))
(defun foo (buf &optional args)
   (let (win)
     (setq win  (funcall special-display-function buf args))
     (raise-frame)
     win))

(defun view-lossage ()
   "Display last few input keystrokes and the commands run.

To record all your input, use `open-dribble-file'."
   (interactive)
   (help-setup-xref (list #'view-lossage)
		   (called-interactively-p 'interactive))
   (with-help-window (help-buffer)
     (princ " ")
     (princ (mapconcat (lambda (key)
			(cond
			 ((and (consp key) (null (car key)))
			  (format "[%s]\n" (if (symbolp (cdr key)) (cdr key)
					   "anonymous-command")))
			 ((or (integerp key) (symbolp key) (listp key))
			  (single-key-description key))
			 (t
			  (prin1-to-string key nil))))
		      (recent-keys 'include-cmds)
		      " "))
     (with-current-buffer standard-output
       (goto-char (point-min))
       (while (not (eobp))
	(move-to-column 50)
	(unless (eolp)
	  (fill-region (line-beginning-position) (line-end-position)))
	(forward-line 1))
       ;; jidanni wants to see the last keystrokes immediately.
       (set-marker help-window-point-marker (point))))

   (setq selected-window (selected-window)))

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

[Drew Adams]

> Do the following: With emacs -Q eval the code below in *scratch*.

Did that.

> Next do
> 
> 1. M-x view-lossage

I got this error: Wrong number of arguments: recent-keys, 1

`C-h f recent-keys' shows that it accepts no args.

Will try again after you update the code to use, if appropriate.
Thanks for taking a look.

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

[martin rudalics]

 > Will try again after you update the code to use, if appropriate.

OK.  Please try the below.

martin


(defvar selected-window nil)

(setq pop-up-frames  t)
(setq help-window-select  t)
(setq w32-grab-focus-on-raise  nil)
(add-to-list 'special-display-buffer-names
	      '("*Help*" foo ((background-color . "Thistle"))))
(defun foo (buf &optional args)
   (let (win)
     (setq win  (funcall special-display-function buf args))
     (raise-frame)
     win))

(defun view-lossage ()
   "Display last 300 input keystrokes.

To record all your input, use `open-dribble-file'."
   (interactive)
   (help-setup-xref (list #'view-lossage)
		   (called-interactively-p 'interactive))
   (with-help-window (help-buffer)
     (princ (mapconcat (lambda (key)
			(if (or (integerp key) (symbolp key) (listp key))
			    (single-key-description key)
			  (prin1-to-string key nil)))
		      (recent-keys)
		      " "))
     (with-current-buffer standard-output
       (goto-char (point-min))
       (while (progn (move-to-column 50) (not (eobp)))
         (when (search-forward " " nil t)
           (delete-char -1))
         (insert "\n"))
       ;; jidanni wants to see the last keystrokes immediately.
       (set-marker help-window-point-marker (point))))

   (setq selected-window (selected-window)))

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

[Drew Adams]

I too see the message "#<window 6 on *Help*>".

However, if I type text it is inserted in buffer *scratch*.
And the *Help* frame border indicates that it is not the
current/focused/selected frame.

So apparently the frame is not focused, even if the window is
selected.  HTH.

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

[martin rudalics]

 > I too see the message "#<window 6 on *Help*>".
 >
 > However, if I type text it is inserted in buffer *scratch*.
 > And the *Help* frame border indicates that it is not the
 > current/focused/selected frame.
 >
 > So apparently the frame is not focused, even if the window is
 > selected.  HTH.

What does evaluating (selected-window) give when the *Help* frame is
raised while the *scratch* frame is focused?

martin

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

[Drew Adams]

>  > I too see the message "#<window 6 on *Help*>".
>  >
>  > However, if I type text it is inserted in buffer *scratch*.
>  > And the *Help* frame border indicates that it is not the
>  > current/focused/selected frame.
>  >
>  > So apparently the frame is not focused, even if the window is
>  > selected.  HTH.
> 
> What does evaluating (selected-window) give when the *Help* frame is
> raised while the *scratch* frame is focused?

`M-: (selected-window)' at that point shows: #<window 3 on *scratch*>

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

[martin rudalics]

 >>   > I too see the message "#<window 6 on *Help*>".
 >>   >
 >>   > However, if I type text it is inserted in buffer *scratch*.
 >>   > And the *Help* frame border indicates that it is not the
 >>   > current/focused/selected frame.
 >>   >
 >>   > So apparently the frame is not focused, even if the window is
 >>   > selected.  HTH.
 >>
 >> What does evaluating (selected-window) give when the *Help* frame is
 >> raised while the *scratch* frame is focused?
 >
 > `M-: (selected-window)' at that point shows: #<window 3 on *scratch*>

Together this proves two things:

(1) `with-help-window' correctly selects the *Help* window.

(2) `raise-frame' is far from "punctual" (takes place at a moment in
     time) as you claimed earlier.

You can try the following: In `temp-buffer-window-setup-hook' set
`w32-grab-focus-on-raise' to t.  In `temp-buffer-window-show-hook' set
it back to nil.

Meanwhile I seem to understand why I can't see the behavior you describe
on my Windows XP.  I have both "Activation follows mouse" and "Autoraise
when activating" set.  So apparently when the second frame is raised my
mouse moves there and focuses the frame.  This means that the rigmarole
done by `w32-grab-focus-on-raise' nil has no effect here at all.

martin

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

[Drew Adams]

>  >> What does evaluating (selected-window) give when the *Help*
>  >> frame is raised while the *scratch* frame is focused?
>  >
>  > `M-: (selected-window)' at that point shows:
>  > #<window 3 on *scratch*>
> 
> Together this proves two things:
> 
> (1) `with-help-window' correctly selects the *Help* window.
> (2) `raise-frame' is far from "punctual" (takes place at a moment in
>      time) as you claimed earlier.

I won't argue about what it proves.  (I don't see how it proves
#2, but whatever.)  It might indicate only that `raise-frame' does
not necessarily do its "punctual" thing (raise the frame) exactly
when it is called, synchronously.  IOW, it might do that at some
later time, asynchronously.  Dunno.

My point about the interaction between `raise-frame' and
`with-help-window' was that the latter should try to ensure that
the window is selected when it *ends*, not at some earlier point.

But if `raise-frame' effectively does its thing *after*
`with-help-window' ends, even if called from within `w-h-w', then
that macro has no way to ensure selection after the actual effect
of `raise-frame'.

We can at least try to make sure that `w-h-w' selects the window
at the very end.

Of course, `w-h-w' should not affect selection for calls to
`raise-frame' (or other functions that select windows or focus)
that happen after it is done.  But if it can override any such
selections that take place within its scope/duration, that is good.

> You can try the following: In `temp-buffer-window-setup-hook' set
> `w32-grab-focus-on-raise' to t.  In `temp-buffer-window-show-hook'
> set it back to nil.

With the simple recipe I gave, that seems to fix things.  Thanks.
But:

1. The `temp-buffer-*-hook's are not only about showing *Help*.
   That workaround thus affects more than it should.

2. Users of `w32*' should not need to do that explicitly
   themselves.  Perhaps Emacs can do the equivalent, itself (but
   limited to *Help*, not affecting all temp buffer display).

> Meanwhile I seem to understand why I can't see the behavior you
> describe on my Windows XP.  I have both "Activation follows mouse"
> and "Autoraise when activating" set.  So apparently when the
> second frame is raised my mouse moves there and focuses the frame.
> This means that the rigmarole done by `w32-grab-focus-on-raise'
> nil has no effect here at all.

Dunno where those are set in Windows (I could google), but thanks
for the info.  (I do want the `w32*' effect, though.)

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

[martin rudalics]

 > 1. The `temp-buffer-*-hook's are not only about showing *Help*.
 >     That workaround thus affects more than it should.

`temp-buffer-window-setup-hook' is run with *Help* current.  So you
won't have any problems discriminating this special case.

 > 2. Users of `w32*' should not need to do that explicitly
 >     themselves.  Perhaps Emacs can do the equivalent, itself (but
 >     limited to *Help*, not affecting all temp buffer display).

I cannot possibly use a feature like `w32-grab-focus-on-raise' whose
semantics I neither understand nor can reenact in my environment in the
frame/window code of Emacs.

But we could change `help-window-setup' as follows:

(defun help-window-setup (window &optional value)
   "Set up help window WINDOW for `with-help-window'.
WINDOW is the window used for displaying the help buffer.
Return VALUE."
   (let* ((help-buffer (when (window-live-p window)
			(window-buffer window)))
	 (help-setup (when (window-live-p window)
		       (car (window-parameter window 'quit-restore)))))
     (when help-buffer
       ;; Handle `help-window-point-marker'.
       (when (eq (marker-buffer help-window-point-marker) help-buffer)
	(set-window-point window help-window-point-marker)
	;; Reset `help-window-point-marker'.
	(set-marker help-window-point-marker nil))

       (cond
        ((or (eq window (selected-window))
	    (and (or (eq help-window-select t)
		     (eq help-setup 'frame)
		     (and (eq help-window-select 'other)
			  (eq (window-frame window) (selected-frame))
			  (> (length (window-list nil 'no-mini)) 2)))
		 (select-window window)))
	(when help-window-select
	  (select-frame-set-input-focus (window-frame window)))
	;; The help window is or gets selected ...
	(help-window-display-message
	 (cond
	  ((eq help-setup 'window)
	   ;; ... and is new, ...
	   "Type \"q\" to delete help window")
	  ((eq help-setup 'frame)
	   "Type \"q\" to quit the help frame")
	  ((eq help-setup 'other)
	   ;; ... or displayed some other buffer before.
	   "Type \"q\" to restore previous buffer"))
	 window t))
        ((and (eq (window-frame window) (selected-frame))
	     (= (length (window-list nil 'no-mini)) 2))
	;; There are two windows on the help window's frame and the
	;; other one is the selected one.
	(help-window-display-message
	 (cond
	  ((eq help-setup 'window)
	   "Type \\[delete-other-windows] to delete the help window")
	  ((eq help-setup 'other)
	   "Type \"q\" in help window to restore its previous buffer"))
	 window 'other))
        (t
	;; The help window is not selected ...
	(help-window-display-message
	 (cond
	  ((eq help-setup 'window)
	   ;; ... and is new, ...
	   "Type \"q\" in help window to delete it")
	  ((eq help-setup 'other)
	   ;; ... or displayed some other buffer before.
	   "Type \"q\" in help window to restore previous buffer"))
	 window))))
     ;; Return VALUE.
     value))

martin

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

[Drew Adams]

>  > 1. The `temp-buffer-*-hook's are not only about showing *Help*.
>  >     That workaround thus affects more than it should.
> 
> `temp-buffer-window-setup-hook' is run with *Help* current.  So you
> won't have any problems discriminating this special case.

How so?  (Not clear to me.)

`help-window-select' should be for *Help* functions only, not
for all uses of `with-output-to-temp-buffer'.  But I'm probably
not understanding your point.

>  > 2. Users of `w32*' should not need to do that explicitly
>  >    themselves.  Perhaps Emacs can do the equivalent, itself (but
>  >    limited to *Help*, not affecting all temp buffer display).
> 
> I cannot possibly use a feature like `w32-grab-focus-on-raise' whose
> semantics I neither understand nor can reenact in my environment in
> the frame/window code of Emacs.

Do you mean use for testing (this bug)?  Or do you mean use
in general, for your personal use of Emacs?

`w32*' is an Emacs option.  It is not something non-Emacs (e.g.,
from MS Windows), and it is not something that I dreamed up.
It, like `help-window-select', should work (for Emacs).  No?

> But we could change `help-window-setup' as follows:

Great.

That too (like setting `w32-grab-focus-on-raise' to t in
`temp-buffer-window-setup-hook' and setting it to nil in
`temp-buffer-window-show-hook') seems to fix the problem,
for both the test case and AFAICT in my setup.

Would you please make this change to `help-window-setup'?
If so, I think we can close the bug.

Thanks for your help.

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

[martin rudalics]

 >> `temp-buffer-window-setup-hook' is run with *Help* current.  So you
 >> won't have any problems discriminating this special case.
 >
 > How so?  (Not clear to me.)

You can test if the current buffer shows *Help* and change
`w32-grab-focus-on-raise' only in that case.

 >> I cannot possibly use a feature like `w32-grab-focus-on-raise' whose
 >> semantics I neither understand nor can reenact in my environment in
 >> the frame/window code of Emacs.
 >
 > Do you mean use for testing (this bug)?

I think we have established that "this bug" is not a bug.  So please
refrain from calling it a bug.

 > Or do you mean use
 > in general, for your personal use of Emacs?

I don't understand what you mean here.

 > `w32*' is an Emacs option.  It is not something non-Emacs (e.g.,
 > from MS Windows), and it is not something that I dreamed up.
 > It, like `help-window-select', should work (for Emacs).  No?

`w32-grab-focus-on-raise' is a variable, not an option.  IIUC it is a
workaround that might work in some cases.  Apparently, it can fail in
other cases.

 > Would you please make this change to `help-window-setup'?

It would require further tuning.  In its current form it would focus a
frame that already has focus which is a bad idea.

martin

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

[Drew Adams]

>  >> `temp-buffer-window-setup-hook' is run with *Help* current.  So
>  >> you won't have any problems discriminating this special case.
>  >
>  > How so?  (Not clear to me.)
> 
> You can test if the current buffer shows *Help* and change
> `w32-grab-focus-on-raise' only in that case.

Users should not be fiddling with hooks to work around this bug.
Especially hooks intended for more general features (temp buffers
in general).

>  >> I cannot possibly use a feature like `w32-grab-focus-on-raise'
>  >> whose semantics I neither understand nor can reenact in my
>  >> environment in the frame/window code of Emacs.
>  >
>  > Do you mean use for testing (this bug)?
> 
> I think we have established that "this bug" is not a bug.  So please
> refrain from calling it a bug.

We have not established any such thing.  It is a reproducible bug.
You even said that if the help window is not selected at the end of
`w-h-w' that is a bug.  And you found a way to ensure that it is
selected - why not just fix that?

Anyway, you did not respond to the question.  You say that you
cannot reenact the symptoms of the recipe in your environment (at
least I think that's what you were saying).  Why is that?  The
recipe is 100% reproducible in my environment (Win 7 64-bit).

>  > Or do you mean use in general, for your personal use of Emacs?
> 
> I don't understand what you mean here.

I asked for clarification of what you meant by saying that you
"cannot possibly use a feature like `w32-*'".  Did you mean use
it for your personal use?  Did you mean that you cannot test the
recipe using it?  What did you mean?  You answer that question
by asking me what I mean by asking what you mean...

>  > `w32*' is an Emacs option.  It is not something non-Emacs (e.g.,
>  > from MS Windows), and it is not something that I dreamed up.
>  > It, like `help-window-select', should work (for Emacs).  No?
> 
> `w32-grab-focus-on-raise' is a variable, not an option.

OK, yes; my bad.  But is the answer to the question to just be
pedantic (yes, I was wrong in thinking it was an option)?

My point was that it is an *Emacs* variable.  For *user
configuration*.  It is for users - it is not used in the Lisp
source code.  And GNU Emacs came up with it, not Microsoft.
It should work - for Emacs.

> IIUC it is a workaround that might work in some cases.

What basis do you have for supposing that it is intended only
as a workaround?

It is specifically mentioned in the Emacs manual (node `Windows
Misc'), and it has been documented there since Emacs 22 (maybe
even 21; dunno - it's not in the Emacs 20 manual, but the variable
is in Emacs 20).  That's the Emacs *user* manual, not the Elisp
manual.  We point this variable out to *end users*, on purpose.
This is not some internal, implementation thing.

It is too facile to just declare something that you might not
like or might not completely understand is only a "workaround
that might work in some cases" and not something that should
work generally.

> Apparently, it can fail in other cases.

You meant this case, this bug, or something else by "other cases"?
Attributing this bug to a single variable involved in the recipe
is a bit rich.  Especially since you found a simple fix for
`help-window-setup' that takes care of the bug.

> But we could change `help-window-setup' as follows:
>
>  > Would you please make this change to `help-window-setup'?
> 
> It would require further tuning.  In its current form it would
> focus a frame that already has focus which is a bad idea.

What further tuning?  Just not focusing a frame that is already
focused?  And why is focusing a focused frame a bad idea?  (Seems
like that operation should be idempotent.)

You are the expert in this area, not I.  I'm not presuming
anything.  But your response seems enigmatic, if not evasive.

Could you *please* fix `help-window-setup' the way you proposed
("we could change `help-window-setup' as follows..."), adding
whatever "further tuning" might be necessary?  Thank you.

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

[martin rudalics]

 >> You can test if the current buffer shows *Help* and change
 >> `w32-grab-focus-on-raise' only in that case.
 >
 > Users should not be fiddling with hooks to work around this bug.

I asked you twice to not call this a bug.  This is the last time I ask
you to drop it.

 >> I think we have established that "this bug" is not a bug.  So please
 >> refrain from calling it a bug.
 >
 > We have not established any such thing.  It is a reproducible bug.

No.  You have found out yourself that with your scenario the window is
selected after `with-help-window' terminates.

You might as well complain that

(progn
   (switch-to-buffer "a")
   (switch-to-buffer "b"))

does not show "a" in the selected window where according to its
doc-string it should do that.

 > You even said that if the help window is not selected at the end of
 > `w-h-w' that is a bug.

Yes.  And we know meanwhile that it is selected.

 > And you found a way to ensure that it is
 > selected - why not just fix that?

The window already gets selected.  But you want the window's frame get
focus too.  The doc-string of `help-window-select' does not promise such
a thing.

So this is not a fix but the implementation of a new feature.

 > I asked for clarification of what you meant by saying that you
 > "cannot possibly use a feature like `w32-*'".  Did you mean use
 > it for your personal use?  Did you mean that you cannot test the
 > recipe using it?  What did you mean?  You answer that question
 > by asking me what I mean by asking what you mean...

I mean that code in help.el or window.el does not act specially with
respect to the value of a variable like `w32-grab-focus-on-raise'.

 >> IIUC it is a workaround that might work in some cases.
 >
 > What basis do you have for supposing that it is intended only
 > as a workaround?

The way this variable affects the execution of `raise-frame'.  You can
convince me of the contrary if you tell me how it does that.

 > It is specifically mentioned in the Emacs manual (node `Windows
 > Misc'), and it has been documented there since Emacs 22 (maybe
 > even 21; dunno - it's not in the Emacs 20 manual, but the variable
 > is in Emacs 20).  That's the Emacs *user* manual, not the Elisp
 > manual.  We point this variable out to *end users*, on purpose.
 > This is not some internal, implementation thing.

There's nothing wrong with that.  But using this variable may have
unwanted consequences for the user like the one we're talking about
here.

 > It is too facile to just declare something that you might not
 > like or might not completely understand is only a "workaround
 > that might work in some cases" and not something that should
 > work generally.

It does not work in general as you stated yourself.  When the frame is
created it gets focus and setting that variable doesn't help at all.

 > You meant this case, this bug, or something else by "other cases"?
 > Attributing this bug to a single variable involved in the recipe
 > is a bit rich.  Especially since you found a simple fix for
 > `help-window-setup' that takes care of the bug.

I proposed a solution to your problem but implementing it is less simple
than I thought initially.

 >> But we could change `help-window-setup' as follows:
 >>
 >>   > Would you please make this change to `help-window-setup'?
 >>
 >> It would require further tuning.  In its current form it would
 >> focus a frame that already has focus which is a bad idea.
 >
 > What further tuning?  Just not focusing a frame that is already
 > focused?  And why is focusing a focused frame a bad idea?  (Seems
 > like that operation should be idempotent.)

It sends a request to the window manager because Emacs doesn't
necessarily check whether the frame already has focus.  This might not
harm on Windows but it might harm on other platforms.

 > You are the expert in this area, not I.  I'm not presuming
 > anything.  But your response seems enigmatic, if not evasive.
 >
 > Could you *please* fix `help-window-setup' the way you proposed
 > ("we could change `help-window-setup' as follows..."), adding
 > whatever "further tuning" might be necessary?  Thank you.

I'll try to implement a feature that will focus the frame if it's
different from the previous one.  Nothing more.

martin

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

[Drew Adams]

> You have found out yourself that with your scenario the window
> is selected after `with-help-window' terminates.
> 
> You might as well complain that
> (progn
>    (switch-to-buffer "a")
>    (switch-to-buffer "b"))
> 
> does not show "a" in the selected window where according
> to its doc-string it should do that.

No relation.  I am perhaps not using "window selected"
correctly.  But as a user, how does it help that a window is
"selected" if I cannot type into it?  Of what use is such
selection?  You will no doubt say that it means that Lisp
can do things in that window, even if I cannot as a user.
But my point of view is as a user.

So you are free to call this bug report an enhancement
request, if you like.  And you can consider that it casts no
aspersions on `with-help-window' or `help-window-select',
but rather it asks that they together give the (user) input
focus to the help window (instead of only "selecting" it
for Lisp).

>  > You even said that if the help window is not selected
>  > at the end of `w-h-w' that is a bug.
> 
> Yes.  And we know meanwhile that it is selected.

It seems we are now nitpicking over the terms.  OK, it is
selected, for Lisp.  It does not have the input focus,
for a user.  The latter is what is important to me.

And honestly, isn't that the behavior you intended in
the first place?  Did you even consider the other-frame
case?  (I'm not saying you should have; I'm just asking.)

For the same-frame case, the behavior is the same for
selection and input focus.  So for that case (which I
imagine you had in mind, and tested) there is no bug
fix or enhancement needed.  The behavior is just what
a user wants and expects.

For the other-frame case the behavior is still broken
(inadequate), from my point of view.  I'm really only
asking that that case be fixed so that the user
experience is parallel to the same-frame case: the
*Help* window gets the focus, so that if a user hits,
say, `q' it disappears (as opposed to `q' being
inserted in the original buffer).

>  > And you found a way to ensure that it is
>  > selected - why not just fix that?
> 
> The window already gets selected.  But you want the
> window's frame get focus too.

Yes.  You understand correctly.

> The doc-string of `help-window-select' does not
> promise such a thing.

You wrote that doc string, I imagine.  I also imagine
that perhaps you did not consider the other-frame case.

In any case, I am requesting exactly that same behavior,
so that a user for the separate-frame use case has the
same experience as a user for the same-frame case: s?he
can interact directly and immediately with the *Help*
window using the keyboard.  If s?he hits `q' then it
should be the *Help* window and buffer that receive the
`q'.

> So this is not a fix but the implementation of a new
> feature.

If you like.  Or a missing part of the feature you
added.  The feature you added does not handle the
other-frame case.  And it should.  That's what this
bug report or enhancement request is for.

It's not about establishing in a court of law whether the
doc string's promise of the window being selected is in
fact fulfilled.  Nobody is suing anyone here.  And I'm
not criticizing the work you did in adding this feature.
I'm just saying that it will help people if it is extended
to the other-frame case as well.

It's about helping users and doing the right thing, not
justifying the status quo.

>  > It is specifically mentioned in the Emacs manual (node `Windows
>  > Misc'), and it has been documented there since Emacs 22 (maybe
>  > even 21; dunno - it's not in the Emacs 20 manual, but the
>  > variable is in Emacs 20).  That's the Emacs *user* manual,
>  > not the Elisp manual.  We point this variable out to *end
>  > users*, on purpose. This is not some internal, implementation 
>  > thing.
> 
> There's nothing wrong with that.  But using this variable may have
> unwanted consequences for the user like the one we're talking about
> here.

Anything could have unwanted consequences.  Clearly, the
intention of those who provided `w32*' was to allow users
to choose to have `raise-frame' grab the focus.  Nothing more
or less than that.

>  > It is too facile to just declare something that you might not
>  > like or might not completely understand is only a "workaround
>  > that might work in some cases" and not something that should
>  > work generally.
> 
> It does not work in general as you stated yourself.
> When the frame is created it gets focus and setting that
> variable doesn't help at all.

You are acting like a lawyer.  "Generally" does not necessarily
mean in every single case.  If there were a simple fix for the
MS Windows problem of it focusing new frames then Emacs would
have implemented that.  The inability to fix that problem does
not provide an excuse not to fix this problem.  Fix this
problem and you will have advanced the ability to use this
feature "in general".

>  > You meant this case, this bug, or something else by
>  > "other cases"?  Attributing this bug to a single variable
>  > involved in the recipe is a bit rich.  Especially since
>  > you found a simple fix for `help-window-setup' that takes
>  > care of the bug.
> 
> I proposed a solution to your problem but implementing it
> is less simple than I thought initially.

How so?  Can you discuss those problems?  Is adding that sexp
to `help-window-setup' worse than if the equivalent behavior
were done in `with-output-to-temp-buffer'?  IOW, if a user
fiddles with the temp-buffer hooks, is that workaround any
less problematic?

If so, maybe you can fix the problem by doing the equivalent
of a user fiddling with hooks that way.  IOW, maybe put that
code in the code that runs the hooks, instead of telling
users put it in the hooks.

I'm speculating, because you have said nothing about what
the problems are that make things "less simple than [you]
thought initially".

>  >> But we could change `help-window-setup' as follows:
>  >>
>  >>   > Would you please make this change to `help-window-setup'?
>  >>
>  >> It would require further tuning.  In its current form it would
>  >> focus a frame that already has focus which is a bad idea.
>  >
>  > What further tuning?  Just not focusing a frame that is already
>  > focused?  And why is focusing a focused frame a bad idea?
>  > (Seems like that operation should be idempotent.)
> 
> It sends a request to the window manager because Emacs doesn't
> necessarily check whether the frame already has focus.  This
> might not harm on Windows but it might harm on other platforms.

Then either (1) do it and wait to see if problems are reported
for other platforms or (2) do it just for Windows (that's simple
enough to do).

IOW why make the ideal into the enemy of the good?  And why
assume that there will be problems on other platforms?

>  > You are the expert in this area, not I.  I'm not presuming
>  > anything.  But your response seems enigmatic, if not evasive.
>  >
>  > Could you *please* fix `help-window-setup' the way you proposed
>  > ("we could change `help-window-setup' as follows..."), adding
>  > whatever "further tuning" might be necessary?  Thank you.
> 
> I'll try to implement a feature that will focus the frame if
> it's different from the previous one.  Nothing more.

I appreciate your efforts on this (whether you think so or
not).  I am certain that if you try to improve the situation
for this use case you can do so, and without spoiling other
behavior, even if the fix might not be 100% perfect.  Please
give it a try.

Thx.

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

[martin rudalics]

 > How so?  Can you discuss those problems?  Is adding that sexp
 > to `help-window-setup' worse than if the equivalent behavior
 > were done in `with-output-to-temp-buffer'?  IOW, if a user
 > fiddles with the temp-buffer hooks, is that workaround any
 > less problematic?

Not for the user.  But users fiddling with these hooks affect their own
systems only.

 > If so, maybe you can fix the problem by doing the equivalent
 > of a user fiddling with hooks that way.  IOW, maybe put that
 > code in the code that runs the hooks, instead of telling
 > users put it in the hooks.

Again I would affect users who don't work with multiple frames.

 > I'm speculating, because you have said nothing about what
 > the problems are that make things "less simple than [you]
 > thought initially".

I initially thought (like you did too) that Emacs would not send a
request to focus a frame that already has focus.  After looking into
this I noticed that it does send a request unconditionally.

 >> It sends a request to the window manager because Emacs doesn't
 >> necessarily check whether the frame already has focus.  This
 >> might not harm on Windows but it might harm on other platforms.
 >
 > Then either (1) do it and wait to see if problems are reported
 > for other platforms or (2) do it just for Windows (that's simple
 > enough to do).

It's not nice to do that even for Windows only.

 > IOW why make the ideal into the enemy of the good?  And why
 > assume that there will be problems on other platforms?

Because I try to be as minimally invasive as possible.

 > I appreciate your efforts on this (whether you think so or
 > not).  I am certain that if you try to improve the situation
 > for this use case you can do so, and without spoiling other
 > behavior, even if the fix might not be 100% perfect.  Please
 > give it a try.

I'll do that.

martin

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

[Drew Adams]

> I try to be as minimally invasive as possible.

That's good.  It's good to be careful, as you are.

>  > I appreciate your efforts on this (whether you think so or
>  > not).  I am certain that if you try to improve the situation
>  > for this use case you can do so, and without spoiling other
>  > behavior, even if the fix might not be 100% perfect.  Please
>  > give it a try.
> 
> I'll do that.

Thanks.

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

[martin rudalics]

>>   > I appreciate your efforts on this (whether you think so or
>>   > not).  I am certain that if you try to improve the situation
>>   > for this use case you can do so, and without spoiling other
>>   > behavior, even if the fix might not be 100% perfect.  Please
>>   > give it a try.
>>
>> I'll do that.

Done on Emacs 25.0.50.1.  Bug closed.

Thanks, martin

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

[Stefan Monnier]

> That is a new restriction (beginning with `display-buffer-alist'), if it

Hmm... let's see:

      % emacs22 -Q
      C-h f display-buffer RET
      ...
      Make buffer appear in some window but don't select it.
      ...

If you want, I can try some other versions, maybe you just got unlucky?


        Stefan

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

[Drew Adams]

> > That is a new restriction (beginning with `display-buffer-alist'),
> 
> Hmm... let's see:
>       % emacs22 -Q
>       C-h f display-buffer RET
>       ...
>       Make buffer appear in some window but don't select it.
>       ...
> 
> If you want, I can try some other versions, maybe you just got
> unlucky?

Ooh, Smartypants!

Clearly you just want to be snarky and not read what I wrote,
which is that **when `display-buffer' uses
`special-display-function'** there is no such restriction.
`display-buffer' essentially delegates behavior in that context.

A one-liner summary of what `display-buffer' does will not and
cannot, of course, go into such things.

The full doc for it does refer to `special-display-buffer-names',
however, which refers to `special-display-function'.  And that
doc makes it quite clear:

;; Emacs 22 `C-h v special-display-buffer-names'

  ...
  In the second case, FUNCTION is called with BUFFER as the first argument,
  followed by the OTHER-ARGS--it can display BUFFER in any way it likes.
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  All this is done by the function found in `special-display-function'.

There are no limits, beyond its arity and return value, on what
`special-display-function' does.

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

[Stefan Monnier]

> Clearly you just want to be snarky and not read what I wrote,
> which is that **when `display-buffer' uses
> `special-display-function'** there is no such restriction.

Of course special-display-function can do whatever it wants, but if it
doesn't follow the behavior described by display-buffer's docstring, it
may break some callers.


        Stefan

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

[Drew Adams]

> > Clearly you just want to be snarky and not read what I wrote,
> > which is that **when `display-buffer' uses
> > `special-display-function'** there is no such restriction.
> 
> Of course special-display-function can do whatever it wants,
> but if it doesn't follow the behavior described by
> display-buffer's docstring, it may break some callers.

The behavior specified by display-buffer's doc string is just
whatever `special-display-function' does - nothing more or less,
when `special-display-function' is used.

So there is *no* behavior for `special-display-function' for
to follow, other than its own behavior.  `display-buffer' says
nothing about `display-buffer' behavior in this case - it
says only that it delegates `display-buffer' behavior to
`special-display-function'.  That's the point of providing
for `special-display-function'.

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

[Stefan Monnier]

> So there is *no* behavior for `special-display-function' for
> to follow, other than its own behavior.

Let me restate what I said in clearer terms.

   Of course you're free to do whatever you want in
   special-display-function, but if it doesn't follow the behavior
   described by display-buffer's docstring and you get undesirable
   behavior, then I will consider it as a bug in *your* code rather than
   in Emacs. 


-- Stefan

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

[Drew Adams]

> > So there is *no* behavior for `special-display-function'
> > to follow, other than its own behavior.
> 
> Let me restate what I said in clearer terms. Of course you're
> free to do whatever you want in special-display-function, but
> if it doesn't follow the behavior described by display-buffer's 
> docstring and you get undesirable behavior, then I will
> consider it as a bug in *your* code rather than in Emacs.

And you will be wrong, at least wrt what `display-buffer' has
said about its own behavior and wrt what its behavior has been.

It is not a bug, according to what `display-buffer' says
about itself, for it to delegate its behavior to
`special-display-function'.  That *is* its intended behavior
when `special-display-function' is used.

If it interferes with that delegation in some way, that is a
bug.  If `display-buffer' itself "doesn't follow the behavior
described by display-buffer's docstring" then that is a bug
in `display-buffer'.

Of course, as Mr Emacs, you are free to change the behavior
of `display-buffer', or `car', or `setq' anyway you like.