[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documenting buffer display
From: |
Eli Zaretskii |
Subject: |
Re: Documenting buffer display |
Date: |
Mon, 22 Oct 2018 16:55:56 +0300 |
> Date: Mon, 22 Oct 2018 11:06:07 +0200
> From: martin rudalics <address@hidden>
> CC: address@hidden
>
> > 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.
- Documenting buffer display, martin rudalics, 2018/10/20
- Re: Documenting buffer display, Eli Zaretskii, 2018/10/20
- Re: Documenting buffer display, martin rudalics, 2018/10/20
- Re: Documenting buffer display, Eli Zaretskii, 2018/10/21
- Re: Documenting buffer display, martin rudalics, 2018/10/22
- Re: Documenting buffer display,
Eli Zaretskii <=
- Re: Documenting buffer display, martin rudalics, 2018/10/22
- Re: Documenting buffer display, Eli Zaretskii, 2018/10/22
- Re: Documenting buffer display, martin rudalics, 2018/10/23
- Re: Documenting buffer display, Pierre-Yves Luyten, 2018/10/23
- Re: Documenting buffer display, martin rudalics, 2018/10/23
- Re: Documenting buffer display, Stefan Monnier, 2018/10/23
- RE: Documenting buffer display, Drew Adams, 2018/10/23
- Re: Documenting buffer display, martin rudalics, 2018/10/23
- Re: Documenting buffer display, Eli Zaretskii, 2018/10/23
- Re: Documenting buffer display, martin rudalics, 2018/10/23