Re: Documenting buffer display

[martin rudalics]

>> And that's where 'pop-to-buffer-same-window' kicks in by accomplishing
>> _two_ things at the same time: It allows the author of 'find-dired'
>> and its "normal" users to continue working as if nothing changed at
>> all.  And it allows users like Trevor to customize the way *Find* is
>> displayed at their discretion.
>
> "Customize", as in setting display-buffer-overriding-action or
> display-buffer-alist, you mean?

The latter.  'display-buffer-overriding-action' is a variable reserved
for applications as the manual should now state more clearly:

     `display-buffer-overriding-action', on the other hand, is reserved
     for applications - who seldom use that option and if they use it,
     then with utmost care.

>> An earlier approach to provide such behavior was to add functions like
>> 'find-dired-other-window' and 'find-dired-other-frame' maybe with
>> appropriate key bindings.
>
> Nothing's wrong with that, IMNSHO: we do that for many other commands,
> so it is a kind-of de-facto Emacs tradition/standard.

Our former maintainer strongly objected the introduction of such
commands and it's not very easy for me to adapt.  In particular
because I have absolutely no opinion in this regard - I never use such
commands consciously.

> But there's also a huge advantage: users who are not very proficient
> in Lisp will both discover the functionality and use it much easier.
> Especially since we have many other commands factored in that way.  By
> contrast, constructing display-buffer actions is not for the faint at
> heart.

The problem is that in most buffer display cases no alternative
'-other-frame', '-other-window', '-same-window' constructs are
provided.  If there were a systematic way to provide them and if there
were suitably mnemonic key-bindings for such commands, things would be
certainly different.

> FWIW, I think it's wrong to advertise display-buffer-overriding-action,

... as you can read above I advertise the opposite ...

> and even display-buffer-alist, as the main way of user-level tweaking
> commands into doing something completely different from what they were
> coded to do.

And the manual should say now

     Users should not pose too many and too severe restrictions on how
     arbitrary buffers get displayed.  Otherwise, they will risk to
     lose the characteristics of showing a buffer for a certain purpose.

> I could argue that if such overrides are to be used as a
> matter of routine, then the whole "middle layer" of
> display-buffer-SOMETHING functions, including
> pop-to-buffer-same-window, is entirely redundant, because many users
> will override their preferences anyway.

What do you suppose a user to do if 'pop-to-buffer-same-window' is the
_only_ alternative an application offers to display a buffer?

> My POV on this functionality is that the overriding action lists are
> mainly for Lisp programs,

Right.  But you should have read the manual before.

> not for users, and that those Lisp programs
> don't abuse the feature to completely subvert certain display-buffer
> function to do the opposite of what their names say.
>
> But I digress.

Why.  You only repeated what the manual already should say now.

> So would adding to the doc string something like this:
>
>    (This default behavior can be changed by customizing
>    `display-buffer-overriding-action' and `display-buffer-alist'.)
>
> take care of your concerns?  This is that "single sentence" I had in
> mind a few messages back.

That doc-string is not for users.  It could say that applications
cannot expect that the buffer is displayed in the selected window or
that the dedicatedness of that window is respected because a user's
customization may override everything that function specifies.

> IOW, I assume that in 90% of the cases the *Find* buffer _will_ pop up
> in the selected window, and that the other 10% are mostly due to users
> who should be knowing what they are doing, and if they don't, it's
> their funeral.  If *Find* does _not_ pop up in the selected window in
> the vast majority of cases, then IMO find-dired has a bug that needs
> to be fixed.

*Find* will continue to pop up in the selected window in the vast
majority of cases.  Just that an application cannot be sure that it
will pop up there in _all_ cases.

> And I submit that you forget one very important class of readers:
> those who are neither the author of find-dired nor those who want to
> tweak the heck out of find-dired.  They are those who want to
> understand _why_ find-dired works like it does, or _how_ does it cause
> the buffer to be displayed in that particular window.  IOW, those who
> see a call to pop-to-buffer-same-window and want to understand what
> that does and which other variables/functions affect what it does.
> This is the primary audience for doc strings.

Such users will have to read the documentation of 'display-buffer'.
It's their funeral if they don't.

> It usually does, or at least should, IMO.  It is IMO wrong to make the
> documentation too complex in order to be 110% accurate, if that
> accuracy comes at a price of leaving the reader without a more-or-less
> clear mental picture regarding what a feature does in 90% of use case.
> Rare corner cases should be "banished" to footnotes and parenthesized
> notes, or even omitted altogether, if they complicate the main use
> cases too much.  This is one such case: it makes little sense to me to
> waste too much of the reader's prime time in order to explain how a
> function designed to display a buffer in the selected window could be
> tweaked into doing the opposite.

Then why do you care to talk about the dedicatedness of windows in the
doc-string?  How many people use dedicated windows?  When and where do
you use them?

>> That view inevitably leads to confusion.
>
> Are you sure "confusion" is the right word here?  If so, please
> elaborate, because I think you meant something like "inaccurate
> information" (and IMO the inaccuracy is very minor).

I don't think that "confusion" is the right word.  IMO the doc-string
is just wrong.  But I didn't want to say that.

> In any case, would you agree that qualifications such as the one
> proposed above will go a long way towards fixing those issues?

I sketched above what I would write instead.

>> Then why do we have all this dispute about 'display-buffer'?
>
> You mean, the discussion about the changes in the manual?  Because you
> asked for review and comments.

I meant the disputes excerpts of which I cited here in various
occasions and which amount to the next two lines.

>> According to the majority of people because its documentation is
>> confusing, wrong, incomplete, implicit, arcane or just bad.
>
> Are you talking about the doc strings or about the manual?  If about
> doc strings, then I'd like to hear or read those complaints, if they
> are still valid after my recent changes.  I hope you trust me that I
> wouldn't have left unfixed any doc strings matching any of the above
> complaints.

I'll remind you the next time this issue comes up.  At least Alan just
wrote about the doc-strings.

martin