Re: Documenting buffer display

[Eli Zaretskii]

> Date: Tue, 23 Oct 2018 20:23:38 +0200
> From: martin rudalics <address@hidden>
> CC: address@hidden
> 
>  >> 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.

I hope it isn't a scoop that our former maintainer's opinions are not
the only ones on the block.

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

I'm not saying that we should provide such variants for every
buffer-display function.  I'm saying that if it makes sense in the
case of find-dired and other similar commands, there's nothing wrong
with having such variants.

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

Nor does every command have to have a keybinding by default.

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

I was mostly talking about doc strings.

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

Then we agree.  And consequently, the fact that what I wrote in the
doc string about pop-to-buffer-same-window doesn't cover such
customizations should not be a reason to say the doc string is
misleading or confusing, do we agree about that?

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

They should ask for a separate command, or for a user option to have
the buffer displayed not in the selected window.  That option could
(but doesn't have to) be implemented under the hood using action
lists, of course.

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

??? Then for whom are they?

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

That is not a useful documentation, IMO.  It sacrifices usefulness on
the altar of 100% accuracy, instead of being much more useful for the
price of being only 99% accurate.

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

The one-sentence qualification goes a long way towards warning of this
rare possibility.  I see no reason to expand more about that, as doing
that runs the risk of drowning the main scenario in the sea of
relatively unimportant details.

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

We disagree.  I specifically made the doc strings of intermediate
functions more explicit about what they say to avoid forcing the users
to go all the way to display-buffer.  The main reason was that it was
very non-trivial for me, having read the doc string of display-buffer,
to propagate the information back to the higher level functions I was
interested in.  And if it was non-trivial for me, it is certainly
non-trivial for less experienced Lispers and users.

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

Because that describes what the function does.

> How many people use dedicated windows?  When and where do you use
> them?

I don't see how this is relevant to the discussion.  If the code
honors dedicated windows, they are important enough to be mentioned in
the doc string.  If you think dedicated windows are not important, why
did you code their support?

> IMO the doc-string is just wrong.

I cannot disagree more, sorry.  And since we disagree so much, I guess
we should stop this part of the discussion, and I should probably
refrain from commenting on your manual work.

Thanks.