Re: Documenting buffer display

[martin rudalics]

>> But asking again: How else would you address a complaint like
>>
>>     Telling someone that they must instead use
>>     `display-buffer' ACTION hoops to accomplish
>>     the same thing leads them down the garden path,
>>     on a wild goose chase, over the river & through
>>     the woods, and around Robin Hood's barn.  IMO.
>>
>> if not with the help of an example where every single step can be
>> executed right in place and the effect of that step seen right away?
>
> Was that complain before or after I reworked the doc strings?

After, I suppose.  It's from a mail Drew posted yesterday.

> I recommend against the removal.  People who are tired at night
> (myself included) are free not to read the doc string, but that
> doesn't mean there's something wrong with it.  A flexible interface
> always requires a long documentation.

Sooner or later the number of recognized action alist entries will
become too large.

>> 'display-buffer' is a function that delegates
>> its work to action functions (Drew's garden path) and guides the
>> latter with the help of action alists which have now their separate
>> entry in the Elisp manual.  The "further down" in the garden path an
>> information is found, the more Drew will complain.  The "further up"
>> everybody else will complain.
>
> Complaints are not the only thing to guide us in this case.

Complaints are never a good guide.  But here it's hard to find the
right balance of correctness and completeness on the one side and
conciseness on the other.

>> 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.  Which further means that a "not customized" caveat would be
counterproductive here.

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

martin