Re: Documenting buffer display

[martin rudalics]

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

That user option already exists as 'display-buffer-alist'.  That
option was invented precisely for that purpose.  That option has no
other purpose.

>> That doc-string is not for users.
>
> ??? Then for whom are they?

For application programmers only.  If you look at the history of that
function you will see that I added it once, that Chong removed it
later and finally re-added it.  IIRC Stefan didn't like it for some
reason and wanted programmers to write out its specification directly.
In retrospect, he was right because 'pop-to-buffer-same-window' does
indeed create false assumptions.

In short

  (pop-to-buffer-same-window buffer norecord)

which can be rewritten as

  (pop-to-buffer buffer display-buffer--same-window-action norecord)

is _not_ semantically equivalent to

  (select-window (display-buffer-same-window buffer nil) norecord)

That last fact is what 'display-buffer' is all about.  'pop-to-buffer'
calls 'display-buffer' so users can customize its behavior.  An
application calls 'pop-to-buffer' so users can customize its behavior.

If we don't agree on this single central issue, it makes no sense to
discuss 'display-buffer' any further.  'display-buffer' does not offer
anything else.  Its sole purpose is to allow users to customize buffer
display.

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

Sadly we disagree here ...

>> Then why do you care to talk about the dedicatedness of windows in the
>> doc-string?
>
> Because that describes what the function does.

... and here ...

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

.. and here.  The code that honors dedicated windows is that of
'display-buffer-same-window' and the latter's doc-string describes
that.

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

At this moment I can only thank you for all the confidence and
patience you've shown in this thread.  I'm probably too categorical
and also feel too old and tired to go on further with this subject.
So let's call it off.  If people want to continue with it, feel free
to peruse the text I submitted any which way you like.

Thanks again, martin