From: martin rudalics <rudalics@gmx.at>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Sat, 20 Oct 2018 20:02:22 +0200 [thread overview]
Message-ID: <5BCB6DAE.30209@gmx.at> (raw)
In-Reply-To: <834ldgvjmj.fsf@gnu.org>
> Thanks, please find a few comments below.
Thanks for the comments. Everything not cited below will be
corrected in your sense.
> Please consider adding one or more @cindex entries here, so that
> readers could get here when they look for topics described in this
> section. Similarly for each of the new subsections.
I haven't done any indexing yet. Suggestions, like the ones you
provide below, are highly welcome.
>> +In this section we describe how Emacs finds or creates a window
>> +suitable for displaying a buffer. We first introduce the function
>> +@code{display-buffer}---the workhorse for choosing such a window.
>> +Next, action functions---auxiliary functions called by
>> +@code{display-buffer} to find or create a suitable window---are
>> +presented. Then we describe action alists---special association lists
>> +used to fine-tune the behavior of action functions.
>> +
>> + We continue with the description of additional options to customize
>> +the behavior of @code{display-buffer}. Then a series of examples will
>> +try to explain the precedence among action functions in a single call
>> +of @code{display-buffer}. We conclude this section with some
>> +guidelines for managing the complexity of buffer display.
>
> I suggest to rewrite this text in terms of what the reader might be
> looking for, or as a list of tasks related to the material in the
> section. The way the text is written now, it is an overview of the
> topics covered by the section, without any explicit relation to what
> the reader may want to do or learn about. Such "abstract" overviews
> are IME much less useful.
Fully agreed but I ran out of ideas here. It would be a great help if
you or anyone else came up with a rough sketch of what to do instead.
>> +* Action Functions:: Support functions for buffer display.
>> +* Action Alists:: Alists for fine-tuning buffer display.
>
> I question the wisdom of removing "Display" from the names of these
> nodes. "Action Functions" and "Action Alists" are IMO too general,
> and might clash with some other kind of "actions".
Agreed. But IMO "display action function" is even worse because
"display" has a very different connotation in Emacs. So I can only
propose "buffer display action function" or "display buffer action
function" instead. WDYT?
>> +@node Action Functions
>> +@subsection Action Functions for Buffer Display
>
> I think @cindex entries here about "action functions" and "display
> action functions" are in order.
They are already indexed in Choosing Window thusly
@cindex display action
@cindex action function, for @code{display-buffer}
@cindex action alist, for @code{display-buffer}
so you suggest to move the indices to the corresponding sections?
>> The following basic action functions are defined in Emacs. Each of
>
> "Action function" is a term introduced in this section, right? If so,
> its first instance should be in @dfn, and this section should define
> the term.
They are defined in Choosing Window thusly
Here, @var{function} is either a function or a list of functions,
which we refer to as @dfn{action functions}; @var{alist} is an
association list, which we refer to as an @dfn{action alist}.
so you suggest to move the @dfns to the corresponding sections as well
and leave only the cross references in Choosing Window?
>> +@node Action Alists
>> +@subsection Action Alists for Buffer Display
>> +
>> +An action alist (@pxref{Choosing Window}) is an association list
>> +mapping predefined symbols recognized by action functions to values
>
> Here you provide the definition of "action alist", so its first
> instance should be in @dfn, and there should be a @cindex entry here.
Same as for "Action Functions" above.
>> + Many efforts in the design of @code{display-buffer} have been given
>> +to maintain compatibility with code that uses older options like
>> +@code{pop-up-windows}, @code{pop-up-frames},
>> +@code{pop-up-frame-alist}, @code{same-window-buffer-names} and
>> +@code{same-window-regexps}. Applications and users should refrain
>
> The text below this should have index entries for the obsolete
> variables you describe.
OK (they are not obsolete yet, BTW).
> FWIW, I find such tutorial-like style
I initially wanted to call this section "A Tutorial for ...".
> not really appropriate for a
> reference manual. For starters, it takes more space; more
> importantly, it gets to the point only implicitly and requires the
> reader to participate in the discovery.
Yes to all. And I expect everyone who complained in the past about
how difficult it is to work with 'display-buffer' to do exactly that -
participate in the discovery (just as I did when I wrote those
examples). Please keep in mind: I didn't invent the action functions,
frequently argued that people won't like them and that it will be hard
to document them. In fact, writing action functions can be a pain and
examples are one way to relieve that pain. Even if it takes space to
write the examples and time to read them.
> It could even annoy, if the
> reader is in a hurry.
Readers in a hurry are not supposed to read that section. If
necessary, I can put an according warning at its start.
> Suggest to rewrite as reference text instead.
> I'm sure this stuff can be described other than by example.
On this list people have asked for examples quite often. Roland
Winkler:
The current discussion of 'display-buffer-alist' in the elisp manual
appears rather technical, suited only for expert users. On the
other hand, the variable is declared with defcustom, as if
individual users should customize it to their personal liking.
N. Jackson in the same thread:
Perhaps `display-buffer-alist' is sufficient for the BBDB case. As
its documentation is a little unclear (while recursive code is okay,
recursive documentation is a little bit trying), it would be nice to
see an example of how this might be done.
Honestly, I have no idea how to do if not with the help of a detailed
sequence of examples. The "Precedence ..." section is IMO one way to
discover how 'display-buffer' works and why it works the way it does.
If anyone comes up with a better idea I'll be all ears.
> And a final remark: the last two subsections you added read like more
> or less arbitrary collection of tips and tricks. While it's okay to
> do that, I wonder whether such a long list of tricks means there might
> be some more meaningful organization of most of this material. Just a
> thought.
Have a look at two recent threads. This one is by Florian Weimer on
help-gnu-emacs:
I see. Further questions: How can I restore the window configuration
after the process terminates? Is there something similar to
save-excursion?
To which Stefan Monnier answers:
If you don't care about other people's configs and you only use a single
frame, there's save-window-excursion (but for configs like mine, every
use of save-window-excursion is generally a source of problems).
A simpler solution to "undo" a pop-to-buffer is to (bury-buffer).
Now the canonical mechanism provided by 'pop-to-buffer' is to use
'quit-window' but how do I tell that to our former maintainer and how
do I put that in the manual? So I mention it in the Zen section.
Or take this one by Alan:
I've thought about this overnight. And I think the answer is no, it
would not be better to use pop-to-buffer. At least, not if an ACTION
argument needs to be constructed.
The specification of the ACTION argument seems so arcane, so implicit, so
difficult to use, that it will be simpler just to write a function such
as edebug-pop-to-buffer. edebug-pop-to-buffer will also be much easier
to understand and maintain than an equivalent using pop-to-buffer with an
ACTION.
In short, pop-to-buffer and display-buffer with ACTION seem to be
"pyrrhic functions". At least, that's how I see it from reading the doc,
not having yet tried to use them. Also, edebug-pop-to-buffer already
exists and works.
There are around 479 calls to these two functions in the Emacs source. A
quick eyeballing of the grep results found just one single use of ACTION,
in replace.el. I dare say there are more, but very few altogether.
Maybe some of the tips and tricks I propose here will help Alan to
avoid sleepless nights (and Stefan when quitting an edebug session
will yet another time try to restore his window configuration on the
wrong frame).
martin
next prev parent reply other threads:[~2018-10-20 18:02 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 [this message]
2018-10-21 12:56 ` Eli Zaretskii
2018-10-22 9:06 ` martin rudalics
2018-10-22 13:55 ` Eli Zaretskii
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=5BCB6DAE.30209@gmx.at \
--to=rudalics@gmx.at \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/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.