From: martin rudalics <rudalics@gmx.at>
To: Alan Mackenzie <acm@muc.de>
Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Tue, 23 Oct 2018 20:25:57 +0200 [thread overview]
Message-ID: <5BCF67B5.3010602@gmx.at> (raw)
In-Reply-To: <20181023155231.GB7594@ACM>
> All the same, there are some concrete things in display-buffer's doc
> string I would like to comment on.
Thanks for these comments.
> (i) PLEASE do not delete the extensive description of the ACTION
> argument. Without it, the function would be more difficult to
> understand, even if the doc string were shorter.
I would like to remove the description of the ALIST entries. At least
these
‘window-height’ -- Value specifies either an integer (the number
of lines of a new window), a floating point number (the
fraction of a new window with respect to the height of the
frame’s root window) or a function to be called with one
argument - a new window. The function is supposed to adjust
the height of the window; its return value is ignored.
Suitable functions are ‘shrink-window-if-larger-than-buffer’
and ‘fit-window-to-buffer’.
‘window-width’ -- Value specifies either an integer (the number
of columns of a new window), a floating point number (the
fraction of a new window with respect to the width of the
frame’s root window) or a function to be called with one
argument - a new window. The function is supposed to adjust
the width of the window; its return value is ignored.
occupy too much space and are hardly indispensable for understanding
'display-buffer'. WDYT?
> (ii) The optional argument FRAME gets combined with other ALIST entries.
> But where? Is it considered before or after the other entries?
It's inserted into the list of 'reusable-frames' after "most of" the
other entries. So any separate specification of 'reusable-frames'
will usually override it. Something similar holds for a non-nil
non-list value of the ACTION argument. Search for 'extra-action' in
the code. Applications should use neither the one nor the other.
> (iii) "If ACTION is non-nil .... where FUNCTION is either a function or
> a list of functions ....". Would it not be better to call this element
> "FUNCTIONS" (plural)?
I have no opinion in this regard. If you feel strongly about it,
please change it.
> (iv) "If ACTION is non-nil .... ALIST is an arbitrary association
> list...". This is unfinished. Could it not say, for example, "... an
> arbitrary association list which FOO uses to BAR BAZ (see below)"?
I now try to say in the manual in more detail where and how ALIST is
constructed and used. Inherently, an eventually fully constructed
ALIST is passed to all action functions 'display-buffer' eventually
calls. But specifying how such an ALIST is constructed cannot be part
of the doc-string. I now give one example of a fully constructed
ALIST in the manual. And what an action function does with an entry
is described individually for each action function.
> (v) "Based on those arguments, it should display the buffer and return
> the window.". Possibly better would be "it should TRY TO display the
> buffer and return the window.". Maybe.
Maybe. There was a time when 'display-buffer' was considered to never
fail. Even now it hardly ever fails to display a buffer. You need
quite a couple of ropes to accomplish that.
> (vi) (Same paragraph): isn't there a missing "...otherwise the function
> will throw an error" after the bit about (allow-no-window . t)?
'display-buffer' doesn't throw an error, hopefully. If it fails it
returns nil.
> (vii) `reusable frames': it sort of seems that a list of frames could be
> given as the cdr of this entry. That is not the case. Maybe the text
> could become: "value, AN ATOM, specifies frame(s) to search...". This
> will remove that uncertainty over the possibility of a list of frames,
> forcing the reader to follow the hyperlink to get details.
Please change this as you see fit.
> (viii) `allow-no-window' is a little unclear on what happens when a
> function fails to display and return a window. The text implies that
> the window remains undisplayed, whereas I think that instead the next
> function is tried, and so on, until one returns a window.
Yes. I'll try to fix this as soon as I understand the semantics.
(And please try my patch, read the new sections and send fixes for the more
embarrassing errors.)
Thanks, martin
next prev parent reply other threads:[~2018-10-23 18:25 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
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 [this message]
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=5BCF67B5.3010602@gmx.at \
--to=rudalics@gmx.at \
--cc=acm@muc.de \
--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.