Re: Documenting buffer display

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 22 Oct 2018 11:06:07 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  > I'm not against tutorials; far from that.  I just think they should be
>  > separate from Reference manuals.  Reference manuals can then point to
>  > tutorials for examples.
> 
> I could put the last two sections into the "Tips and Conventions"
> chapter.  Or do we have another place where to put tutorial-like text?

No, I don't think we have any place for tutorial-like stuff.  Tips is
something different.

> My basic idea was to put the description proper into the first three,
> four sections and leave the last two, three sections to those puzzled
> by the technical level used in the decription.

I guess I'll have to re-read the text once it's installed, maybe I
failed to catch the spirit reading the diffs (which included a lot of
whitespace changes, so it wasn't always easy to find the real
changes).

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

> Well, Alan's impression was that
> 
>    The doc string of display-buffer is a bit of a heavy read at this time
>    of night.
> 
> and I'm currently contemplating to remove the description of action
> alist entries from it.

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.

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

>    Unlike `pop-to-buffer', this function prefers using the selected
>    window over popping up a new window or frame.  Specifically, if
>    the selected window is neither a minibuffer window (as reported
>    by `window-minibuffer-p'), nor is dedicated to another buffer
>    (see `window-dedicated-p'), BUFFER will be displayed in the
>    currently selected window; otherwise it will be displayed in
>    another window.
> 
> 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.