Re: Documenting buffer display

[Eli Zaretskii]

> Date: Mon, 22 Oct 2018 21:14:52 +0200
> From: martin rudalics <address@hidden>
> CC: address@hidden
> 
>  >> While this would be appropriate for 'switch-to-buffer-other-window' it
>  >> may be wrong for 'pop-to-buffer-same-window' as soon as the user has
>  >> customized 'display-buffer-alist'.  We can't avoid the garden path of
>  >> 'display-buffer' here and elsewhere.
>  >
>  > I don't think we cannot avoid it, we just need to qualify what I wrote
>  > with the "not customized" caveat.  Nothing a single sentence couldn't
>  > fix.
> 
> Trevor Murphy on emacs-devel
> 
>    I just noticed that `find-dired' and friends use `switch-to-buffer' as
>    a subroutine.  Since this does not go through the `display-buffer'
>    mechanism, it’s really hard for me to control where Emacs displays the
>    Find buffer.  I’m currently advising `find-dired' to use
>    `pop-to-buffer' instead.
> 
> to which Stefan replied
> 
>    There's pop-to-buffer-same-window.
> 
> Which means that people want 'pop-to-buffer-same-window' instead
> because they can customize it to display the buffer in _another_
> window.

I must be missing something: using pop-to-buffer-SAME-window to
display a buffer in ANOTHER window?  How can that make sense?

> Which further means that a "not customized" caveat would be
> counterproductive here.

All I meant was to add something like "by default" to the doc string.
I don't see how that could be wrong, all Stefan's advice
notwithstanding.

We shouldn't shoot ourselves in the foot by being afraid that complex
enough customizations could invalidate the documentation.

> Any explanation of what 'pop-to-buffer-same-window' does without
> referring the reader to 'display-buffer' is misleading, at the very
> least.

I obviously disagree, as I did just that, and I object calling the
current text "misleading".