From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.devel Subject: Manual suggestions for quit-restore documentation Date: Sat, 04 Mar 2017 17:32:05 -0800 Message-ID: <87varoh5ka.fsf@ericabrahamsen.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1488677588 26571 195.159.176.226 (5 Mar 2017 01:33:08 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 5 Mar 2017 01:33:08 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Mar 05 02:33:01 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ckL2h-0005tg-2v for ged-emacs-devel@m.gmane.org; Sun, 05 Mar 2017 02:32:59 +0100 Original-Received: from localhost ([::1]:37214 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ckL2l-00052F-Ls for ged-emacs-devel@m.gmane.org; Sat, 04 Mar 2017 20:33:03 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33933) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ckL29-00051y-Ov for emacs-devel@gnu.org; Sat, 04 Mar 2017 20:32:26 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ckL26-0004aC-L8 for emacs-devel@gnu.org; Sat, 04 Mar 2017 20:32:25 -0500 Original-Received: from [195.159.176.226] (port=43947 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ckL26-0004Zl-FI for emacs-devel@gnu.org; Sat, 04 Mar 2017 20:32:22 -0500 Original-Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1ckL1y-0001cA-8V for emacs-devel@gnu.org; Sun, 05 Mar 2017 02:32:14 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 89 Original-X-Complaints-To: usenet@blaine.gmane.org Cancel-Lock: sha1:6HznbV6OXOG3xMEz1ZRAz7fezlU= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 195.159.176.226 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:212758 Archived-At: --=-=-= Content-Type: text/plain As mentioned in a thread in emacs.help, I've got some suggestions for the parts of the Elisp manual that touch on the quit-restore window parameter, and its behaviors. I've attached a diff with my edits; if/when some version of this is eventually approved I can do a proper commit. I didn't add anything in the Window Parameters section about the first two elements of the quit-restore parameter, simply because I don't understand them well enough. I still think something should be said there about how they influence quit behavior, though -- this is the first place that people will look to find out how this works, and the current docs are very clear about "what", but beg the question of "why". Eric --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=windowsdoc.diff diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index affa28c920..504a74dfd1 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2803,12 +2803,13 @@ Window History @section Window History @cindex window history -Each window remembers in a list the buffers it has previously displayed, -and the order in which these buffers were removed from it. This history -is used, for example, by @code{replace-buffer-in-windows} -(@pxref{Buffers and Windows}). The list is automatically maintained by -Emacs, but you can use the following functions to explicitly inspect or -alter it: +Each window remembers in a list the buffers it has previously +displayed, and the order in which these buffers were removed from it. +This history is used, for example, by @code{replace-buffer-in-windows} +(@pxref{Buffers and Windows}), and when quitting windows +(@pxref{Quitting Windows}). The list is automatically maintained by +Emacs, but you can use the following functions to explicitly inspect +or alter it: @defun window-prev-buffers &optional window This function returns a list specifying the previous contents of @@ -2998,15 +2999,17 @@ Quitting Windows before its buffer was displayed in it. The optional argument @var{window} must be a live window and defaults to the selected one. -If @var{window} was created specially for displaying its buffer, this -function deletes @var{window} provided its frame contains at least one -other live window. If @var{window} is the only window on its frame and -there are other frames on the frame's terminal, the value of the -optional argument @var{bury-or-kill} determines how to proceed with the -window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted -unconditionally. Otherwise, the fate of the frame is determined by -calling @code{frame-auto-hide-function} (see below) with that frame as -sole argument. +If @var{window} was previously used for displaying other buffers +(@pxref{Window History}), the most recent buffer in that history will +be displayed. If it has no history, this function deletes +@var{window} altogether, provided its frame contains at least one +other live window. If @var{window} is the only window on its frame +and there are other frames on the frame's terminal, the value of the +optional argument @var{bury-or-kill} determines how to proceed with +the window. If @var{bury-or-kill} equals @code{kill}, the frame is +deleted unconditionally. Otherwise, the fate of the frame is +determined by calling @code{frame-auto-hide-function} (see below) with +that frame as sole argument. Otherwise, this function tries to redisplay the buffer previously shown in @var{window}. It also tries to restore the window start @@ -4857,8 +4860,9 @@ Window Parameters window when it deletes the window passed to it as argument. The fourth element is the buffer whose display caused the creation of -this parameter. @code{quit-restore-window} deletes the specified window -only if it still shows that buffer. +this parameter. @code{quit-restore-window} deletes the specified +window only if it still shows that buffer, and it has no history of +previously-displayed buffers. @item @code{window-side} @code{window-slot} These parameters are used for implementing side windows (@pxref{Side --=-=-=--