GNU bug report logs - #45688
28.0.50; New action for display-buffer?

Previous Next

Full log

Message #44 received at 45688 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 45688 <at> debbugs.gnu.org
Subject: Re: bug#45688: 28.0.50; New action for display-buffer?
Date: Thu, 7 Jan 2021 14:18:04 +0100

> I think the doc string for `display-buffer' is pretty intimidating now,
> and seems more geared towards programmers than usage now.  Would it make
> sense to rearrange it a bit?  That is, start off with something like:
>
> -----
>
> Display BUFFER-OR-NAME in some window, without selecting it.  To change
> what window is used, set `display-buffer-overriding-action' to a list
> containing one or more of the following functions:
>
> Action functions and the action they try to perform are:
>   ‘display-buffer-same-window’ -- Use the selected window.
>   ‘display-buffer-reuse-window’ -- Use a window already showing
>      the buffer.
>   ‘display-buffer-in-previous-window’ -- Use a window that did
>      show the buffer before.
>
> etc etc, and then give the details about ACTION and the rest?

By no means.  `display-buffer-overriding-action' is _not_ intended for
the user.  It's an emergency exit for applications.  Better not even
mention it in the user manual and the doc-string.

In every other regard, feel free to change it in a way that sounds less
imitating.  For example, listing the action functions and alist entries
in the doc-string is merely distracting.  We started out with small sets
and every time a new function or entry was added, we also added it to
those lists.  And while you're there you could try to make the Emacs
manual entry more amenable for its audience.  IIUC that's what the blog
you mentioned criticized even more than the doc-string.

martin

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.