bug#42210: Add -other-window variants of project-prefix-map commands

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

> > 1. I disagree with calling the macro `define-other-window-command'.
> >
> > My disagreement is this: Defining an other-window command
> > should do just that.  It should not define a command that
> > only "prefers" to display in another window.  It should
> > define a command that actually displays in another window.
> >
> > And your doc string in fact says the latter, though the
> > behavior is, I guess, only the former.  Please consider
> > renaming the macro and fixing the doc string, to make clear
> > that it's NOT other-window but only maybe-other-window.
> 
> Hmm, but doesn't pop-to-buffer-other-window also only prefer to use
> another window, and ultimately defers to the display-buffer-alist
> machinery?

1. (There is no `pop-to-buffer-other-window', is there?)

The doc of `pop-to-buffer' goes out of its way to tell
about its relation with `display-buffer' - because it
passes its arg to it.  

The doc of `switch-to-buffer-other-window' just says
directly that it selects the buffer in another window.

Only at its very end does it mention the possibility
that `display-buffer' can alter behavior:

  This uses the function `display-buffer' as a subroutine;
  see its documentation for additional customization
  information.

What's not so good is to (a) not say what THIS function
is for: other-window and (b) not mention `display-buffer',
while suggesting some other behavior than other-window.

2. I suppose `display-buffer(-alist)' can override
anything now.

If that's all that's meant then I think it shouldn't
be put that way.  It's OK (but might not be needed or
appropriate) to add some mention of it at the end.
But I don't think the behavior of the command should
be described that way.

The point of the resulting function is (presumably)
to use another window.  The point of any additional
`display-buffer*' shenanigans - or other Lisp code
that might have an effect on things - could be just
about anything.

This doc should be about what the resulting function
intends to do, not whatever some other code might
make it do instead.  If you want to go the other route,
then make the relation explicit, as does the doc of
`pop-to-buffer' and `switch-to-buffer-other-window'.

> > 2. Why "resultant buffer".  What does the buffer result
> > from?  It's about whatever FUNCTION displays, no?
> 
> Please feel free to suggest alternative phrasing that will be short
> enough to fit in one line, which I understand to be required.

 Define an other-window version of FUNCTION.

or

 Define a function like FUNCTION that outputs to another window.

or

 Define a function like FUNCTION but that outputs to another window.

> > 3. Presumably FUNCTION must be a _command_.  If so,
> > the arg should be called COMMAND, and the doc adjusted
> > accordingly.
> 
> No, it can just be a function too.

You're right; I was wrong about that.

However, isn't the real purpose of this macro to
define commands, which you can bind to keys to get
other-window behavior?  Is there really some other
expected use case?  Would anyone use it for a
non-interactive function?

If you want to be exact then yes, FUNCTION.  But
in that case I think the doc should say that
FUNCTION is typically a command, i.e., give the
use case that's the raison d'etre for the macro.

BTW, this part of your patch doesn't seem right:
(called-interactively-p).

Argument KIND is optional (should it really be?),
but the behavior of calling the function without
KIND is not documented, and it always just returns
nil.

(I filed bug #42222 about KIND being optional etc.)