From: Eli Zaretskii <eliz@gnu.org>
To: martin rudalics <rudalics@gmx.at>
Cc: emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Mon, 22 Oct 2018 16:55:56 +0300 [thread overview]
Message-ID: <838t2qt79v.fsf@gnu.org> (raw)
In-Reply-To: <5BCD92FF.8070905@gmx.at> (message from martin rudalics on Mon, 22 Oct 2018 11:06:07 +0200)
> 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.
next prev parent reply other threads:[~2018-10-22 13:55 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-10-20 12:20 Documenting buffer display martin rudalics
2018-10-20 13:21 ` Eli Zaretskii
2018-10-20 18:02 ` martin rudalics
2018-10-21 12:56 ` Eli Zaretskii
2018-10-22 9:06 ` martin rudalics
2018-10-22 13:55 ` Eli Zaretskii [this message]
2018-10-22 19:14 ` martin rudalics
2018-10-22 19:27 ` Eli Zaretskii
2018-10-23 8:58 ` martin rudalics
2018-10-23 11:26 ` Pierre-Yves Luyten
2018-10-23 13:45 ` martin rudalics
2018-10-23 17:40 ` Stefan Monnier
2018-10-23 14:04 ` Drew Adams
2018-10-23 18:18 ` martin rudalics
2018-10-23 15:18 ` Eli Zaretskii
2018-10-23 18:23 ` martin rudalics
2018-10-23 19:07 ` Eli Zaretskii
2018-10-24 9:44 ` martin rudalics
2018-10-24 14:48 ` Eli Zaretskii
2018-10-24 17:40 ` martin rudalics
2018-10-24 18:25 ` Eli Zaretskii
2018-10-25 20:42 ` Juri Linkov
2018-10-23 15:52 ` Alan Mackenzie
2018-10-23 18:25 ` martin rudalics
2018-11-08 19:25 ` martin rudalics
2018-10-22 1:39 ` Michael Welsh Duggan
2018-10-22 5:54 ` Eli Zaretskii
2018-10-20 15:22 ` Drew Adams
2018-10-20 18:02 ` martin rudalics
2018-10-20 18:24 ` Drew Adams
2018-10-21 8:22 ` martin rudalics
2018-11-04 9:06 ` martin rudalics
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=838t2qt79v.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=rudalics@gmx.at \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.