[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documenting buffer display
From: |
martin rudalics |
Subject: |
Re: Documenting buffer display |
Date: |
Mon, 22 Oct 2018 21:14:52 +0200 |
>> 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
- 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, 2018/10/22
- Re: Documenting buffer display,
martin rudalics <=
- 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
- Re: Documenting buffer display, Eli Zaretskii, 2018/10/23