From: martin rudalics <rudalics@gmx.at>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Wed, 24 Oct 2018 11:44:56 +0200 [thread overview]
Message-ID: <5BD03F18.1020100@gmx.at> (raw)
In-Reply-To: <83k1m8scq9.fsf@gnu.org>
>> 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
next prev parent reply other threads:[~2018-10-24 9:44 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-10-20 12:20 Documenting buffer display martin rudalics
2018-10-20 13:21 ` Eli Zaretskii
2018-10-20 18:02 ` martin rudalics
2018-10-21 12:56 ` Eli Zaretskii
2018-10-22 9:06 ` martin rudalics
2018-10-22 13:55 ` Eli Zaretskii
2018-10-22 19:14 ` martin rudalics
2018-10-22 19:27 ` Eli Zaretskii
2018-10-23 8:58 ` martin rudalics
2018-10-23 11:26 ` Pierre-Yves Luyten
2018-10-23 13:45 ` martin rudalics
2018-10-23 17:40 ` Stefan Monnier
2018-10-23 14:04 ` Drew Adams
2018-10-23 18:18 ` martin rudalics
2018-10-23 15:18 ` Eli Zaretskii
2018-10-23 18:23 ` martin rudalics
2018-10-23 19:07 ` Eli Zaretskii
2018-10-24 9:44 ` martin rudalics [this message]
2018-10-24 14:48 ` Eli Zaretskii
2018-10-24 17:40 ` martin rudalics
2018-10-24 18:25 ` Eli Zaretskii
2018-10-25 20:42 ` Juri Linkov
2018-10-23 15:52 ` Alan Mackenzie
2018-10-23 18:25 ` martin rudalics
2018-11-08 19:25 ` martin rudalics
2018-10-22 1:39 ` Michael Welsh Duggan
2018-10-22 5:54 ` Eli Zaretskii
2018-10-20 15:22 ` Drew Adams
2018-10-20 18:02 ` martin rudalics
2018-10-20 18:24 ` Drew Adams
2018-10-21 8:22 ` martin rudalics
2018-11-04 9:06 ` martin rudalics
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5BD03F18.1020100@gmx.at \
--to=rudalics@gmx.at \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.