[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: |
Thu, 08 Nov 2018 20:25:20 +0100 |
> All the same, there are some concrete things in display-buffer's doc
> string I would like to comment on.
I hope I addressed all issues. Please have a look.
> (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.
>
> (ii) The optional argument FRAME gets combined with other ALIST entries.
> But where? Is it considered before or after the other entries?
I think it says that now.
> (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)?
>
> (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)"?
>
> (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.
>
> (vi) (Same paragraph): isn't there a missing "...otherwise the function
> will throw an error" after the bit about (allow-no-window . t)?
I'm not quite sure what you meant here. 'display-buffer' will return
nil after one of its action functions "successfully" processed the
'allow-no-window' entry and will also return nil if it didn't find a
window (which is quite difficult to achieve). But by design it never
throws an error.
> (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.
I use the tem "set" now.
> (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.
The window remains undisplayed if this entry is actually processed by
an action function and 'display-buffer' returns immediately
thereafter. No further action functions are tried in that case.
martin