Re: Documenting buffer display

[martin rudalics <rudalics@gmx.at>]

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