`pop-up-frames' and binding/setting user options [was: Documenting buffer display]

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

>  > I disagree. If the behavior is documented in
>  > the command's doc string, as it should be, then
>  > the user is aware of it. Using a given command
>  > is a user choice. There is no reason to put on
>  > the hair shirt of not binding a user option in
>  > a user command, as long as the behavior is
>  > documented and the command ends always by
>  > restoring the user's preferred value for the
>  > option.
> 
> A user option has to be respected.

A _user_ has to be respected.  A user has a right
to define or use a command that changes the value
of a user option, whether that change is temporary
(for the duration of the command) or stays in
effect after the command.

This should be obvious.  Think toggle command, as
the most obvious case.  Emacs defines commands
that toggle or otherwise set option values - and
so do users define such commands.

What makes that use case OK?  (1) That's the very
intention of the command: to change the option
value.  And (2) the command doc makes this quite
clear to users.  If you don't want to change the
option value then you don't invoke the command.
Nothing special here.

And BTW, it makes perfect sense for a command
that acts just like an other-window command, but
uses other-frame instead of other-window, to
bind `pop-up-frames'.

That's precisely the meaning of `pop-up-frames':
make other-window commands use other-frame.  And
such a command leaves the option value just as
it was, when done.

We create user options for user convenience.
They are not something that should limit users.

> If the designer of a command sees no other way to
> have a command do what it is supposed to do than by
> overriding a user option we have a severe design problem.

I disagree with such must-not-be-any-other-way
rigidity.  There is no reason, IMO, why a
command definition cannot change an option value,
as long as the command doc makes that behavior
clear.  And in particular when that's the very
raison d'etre for the command.

As I said, I recognize that my opinion is maybe
not the policy of Emacs (or perhaps of only an
inflexible interpretation of the policy - dunno).
Such a rigid policy is not wise, IMO.

> 'display-buffer' has no design problem because
> programmers can always ask it to do what they want
> by specifying the ACTION argument appropriately.

(No one has said that `display-buffer' has a
design problem, AFAIK.)

There is more than one way to do something in
Emacs.  Just because users can manipulate
`display-buffer' to do something, that's no
reason that they should be limited to using it
directly.

That there exists one way to do something is not
a reason not to sometimes do it another way.
Otherwise we would never create high-level
convenience constructs and would just encourage
users to directly use low-level building blocks.

And, as that long-ago article from RMS about the
utility (for Emacs) of dynamic binding shows, the
fact that you can pass arguments to functions is
no good substitute for being able to change the
behavior of a function by dynamically binding a
variable.  Especially when the variable is well
known to users and well documented.

No one argues that global variables cannot make
for debugging difficulties.  They clearly couple
code parts in a non-modular way.  Lisp is not
Haskell, and there are many, many ways in Lisp
to couple code (and data) so that the behavior
is not obvious and not just local.

Just because you can do all kinds of things that
couple code (and data) in Lisp is no reason that
you should do so gratuitously and in silly ways.

But it's also not a reason to forbid developers
from making use of such possibilities when they
make sense.  That Emacs gives you plenty of rope
that you can use to hang yourself is not a reason
for it not to give you rope or to tell you not to
use this or that rope it provides.

> Telling programmers to bind a user option
> instead is an invitation to bad design.

Did anyone tell programmers that they must always
bind a variable instead of passing an argument to
a function?  I don't think so.

Who's making a black-&-white pronouncement of
what everyone should always do or not do?  If
that's happening it's not happening in the
direction of must-bind-variable.

>  > Secondly, users themselves define commands,
>  > and the ability to bind such a variable -
>  > whether it is an option or not, is very
>  > useful for users.
> 
> And when such users become programmers we get
> our problems through the backdoor, compare the
> recent "open bookmark in other frame" thread.

What's your problem with that thread?  I guess
it's this code:

(let ((pop-up-frames  t))
  (bookmark-jump-other-window bookmark))

Nothing could be simpler, clearer, or more
elegant for a command that jumps to a bookmark
in another frame, IMO.

Telling someone that they must instead use
`display-buffer' ACTION hoops to accomplish
the same thing leads them down the garden path,
on a wild goose chase, over the river & through
the woods, and around Robin Hood's barn.  IMO.

But I didn't insist on that code.  Far from it.
I could see such a complaint coming from some
quarters, which is why I suggested to "do the
equivalent of [that code], or similar".  And:

  Non-nil `pop-up-frames' just makes
  "other-window" commands use "other-frame".

  I wrote "the equivalent of this, or similar",
  because someone will perhaps say that there is
  a more "modern" way to do the same thing,
  involving a `display-buffer' ACTION or
  something...

  The above code DTRT, but someone might prefer
  a different formulation that does the same
  thing, or similar.

Why did I write such qualification, even at
the outset?  Why anticipate the possibility of
a knee-jerk reaction to binding a user option?
Why indeed.

Now I even wonder, since you pointed to that
thread, whether my showing `pop-up-frames'
there was perhaps a catalyst for your recent
discouragement of `pop-up-frames' in the doc.

(To reiterate: I do applaud your trying to
clarify the buffer-display doc, other than
the proposed change wrt `pop-up-buffers'.)

To be extra clear: As I said there, I have no
objection to someone writing the Emacs code
for an other-frame bookmark-jump command in a
way that is more round-about, in order to
avoid using `pop-up-frames'.

I personally wouldn't (and didn't) do that.  I
defined it in my code just as I wrote it there.

But I make no pretense of imposing such a "bad
design" style on Emacs.  My wish is only for
Emacs to not discourage it, and for Emacs to
continue to support helpful constructs such as
`pop-up-frames' and `special-display-regexps'.
I still hope it will.

And more generally, I wish that Emacs would
not discourage, let alone forbid, the useful
binding and setting of user options in
commands.

That it sometimes might not make sense for
a command to change the value of an option
is no reason to insist that it doesn't make
sense in general.