[Emacs-diffs] trunk r116696: Update docs for select-window and buffer-list-update-hook.

[Martin Rudalics]

------------------------------------------------------------
revno: 116696
revision-id: address@hidden
parent: address@hidden
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Fri 2014-03-07 16:11:12 +0100
message:
  Update docs for select-window and buffer-list-update-hook.
  
  * buffer.c (Vbuffer_list_update_hook): Doc-string fix.
  * window.c (Fselect_window): Explain NORECORD and
  `buffer-list-update-hook' in doc-string.
  * buffers.texi (The Buffer List): Rename node to Buffer List.
  Describe `buffer-list-update-hook'.
  * elisp.texi (Top): "The Buffer List" renamed to "Buffer List".
  Add node for Window Dividers.
  * hooks.texi (Standard Hooks): Add reference to
  `buffer-list-update-hook'.
  * windows.texi (Selecting Windows): Update description of
  `select-window'.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/buffers.texi       
buffers.texi-20091113204419-o5vbwnq5f7feedwu-6164
  doc/lispref/elisp.texi         elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
  doc/lispref/hooks.texi         hooks.texi-20091113204419-o5vbwnq5f7feedwu-6186
  doc/lispref/windows.texi       
windows.texi-20091113204419-o5vbwnq5f7feedwu-6224
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/buffer.c                   buffer.c-20091113204419-o5vbwnq5f7feedwu-264
  src/window.c                   window.c-20091113204419-o5vbwnq5f7feedwu-231

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-07 09:53:23 +0000
+++ b/doc/lispref/ChangeLog     2014-03-07 15:11:12 +0000
@@ -1,7 +1,14 @@
 2014-03-07  Martin Rudalics  <address@hidden>
 
+       * buffers.texi (The Buffer List): Rename node to Buffer List.
+       Describe `buffer-list-update-hook'.
+       * elisp.texi (Top): "The Buffer List" renamed to "Buffer List".
+       Add node for Window Dividers.
+       * hooks.texi (Standard Hooks): Add reference to
+       `buffer-list-update-hook'.
        * windows.texi (Window Sizes): Describe `window-min-size'.
        (Splitting Windows): Update description of `split-window'.
+       (Selecting Windows): Update description of `select-window'.
 
 2014-03-06  Martin Rudalics  <address@hidden>
 

=== modified file 'doc/lispref/buffers.texi'
--- a/doc/lispref/buffers.texi  2014-01-01 07:43:34 +0000
+++ b/doc/lispref/buffers.texi  2014-03-07 15:11:12 +0000
@@ -25,7 +25,7 @@
 * Modification Time::   Determining whether the visited file was changed
                          "behind Emacs's back".
 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
-* The Buffer List::     How to look at all the existing buffers.
+* Buffer List::         How to look at all the existing buffers.
 * Creating Buffers::    Functions that create buffers.
 * Killing Buffers::     Buffers exist until explicitly killed.
 * Indirect Buffers::    An indirect buffer shares text with some other buffer.
@@ -759,7 +759,7 @@
 signal an error if the current buffer is read-only.
 @end defun
 
address@hidden The Buffer List
address@hidden Buffer List
 @section The Buffer List
 @cindex buffer list
 
@@ -910,6 +910,13 @@
 window.
 @end deffn
 
address@hidden buffer-list-update-hook
+This is a normal hook run whenever the buffer list changes.  Functions
+(implicitly) running this hook are @code{get-buffer-create}
+(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}),
address@hidden (@pxref{Killing Buffers}), @code{bury-buffer} (see
+above) and @code{select-window} (@pxref{Selecting Windows}).
address@hidden defvar
 
 @node Creating Buffers
 @section Creating Buffers

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2014-03-05 07:41:48 +0000
+++ b/doc/lispref/elisp.texi    2014-03-07 15:11:12 +0000
@@ -992,7 +992,7 @@
                               "behind Emacs's back".
 * Read Only Buffers::       Modifying text is not allowed in a
                               read-only buffer.
-* The Buffer List::         How to look at all the existing buffers.
+* Buffer List::             How to look at all the existing buffers.
 * Creating Buffers::        Functions that create buffers.
 * Killing Buffers::         Buffers exist until explicitly killed.
 * Indirect Buffers::        An indirect buffer shares text with some
@@ -1344,12 +1344,13 @@
                               for text characters: font, colors, etc.
 * Fringes::                 Controlling window fringes.
 * Scroll Bars::             Controlling vertical scroll bars.
+* Window Dividers::         Separating windows visually.
 * Display Property::        Enabling special display features.
 * Images::                  Displaying images in Emacs buffers.
 * Buttons::                 Adding clickable buttons to Emacs buffers.
 * Abstract Display::        Emacs's Widget for Object Collections.
 * Blinking::                How Emacs shows the matching open parenthesis.
-* Character Display::   How Emacs displays individual characters.
+* Character Display::       How Emacs displays individual characters.
 * Beeping::                 Audible signal to the user.
 * Window Systems::          Which window system is being used.
 * Bidirectional Display::   Display of bidirectional scripts, such as
@@ -1384,10 +1385,10 @@
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for
                               a character.
-* Face Remapping::         Remapping faces to alternative definitions.
+* Face Remapping::          Remapping faces to alternative definitions.
 * Face Functions::          How to define and examine faces.
 * Auto Faces::              Hook for automatic face assignment.
-* Basic Faces::         Faces that are defined by default.
+* Basic Faces::             Faces that are defined by default.
 * Font Selection::          Finding the best available font for a face.
 * Font Lookup::             Looking up the names of available fonts
                               and information about them.

=== modified file 'doc/lispref/hooks.texi'
--- a/doc/lispref/hooks.texi    2014-02-25 08:41:47 +0000
+++ b/doc/lispref/hooks.texi    2014-03-07 15:11:12 +0000
@@ -98,7 +98,7 @@
 
 @item buffer-list-update-hook
 @vindex buffer-list-update-hook
-Hook run when the buffer list changes.
+Hook run when the buffer list changes (@pxref{Buffer List}).
 
 @item buffer-quit-function
 @vindex buffer-quit-function

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2014-03-07 09:53:23 +0000
+++ b/doc/lispref/windows.texi  2014-03-07 15:11:12 +0000
@@ -1504,16 +1504,27 @@
 @defun select-window window &optional norecord
 This function makes @var{window} the selected window and the window
 selected within its frame (@pxref{Basic Windows}) and selects that
-frame.  @var{window} must be a live window.  This function also makes
address@hidden's buffer (@pxref{Buffers and Windows}) current and sets
-that buffer's value of @code{point} to the value of @code{window-point}
-(@pxref{Window Point}) in @var{window}.  The return value is
address@hidden
+frame.  It also makes @var{window}'s buffer (@pxref{Buffers and
+Windows}) current and sets that buffer's value of @code{point} to the
+value of @code{window-point} (@pxref{Window Point}) in @var{window}.
address@hidden must be a live window.  The return value is @var{window}.
 
 By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
+of the buffer list (@pxref{Buffer List}), and makes @var{window} the
 most recently selected window.  However, if the optional argument
 @var{norecord} is address@hidden, these additional actions are omitted.
+
+This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
+unless @var{norecord} is address@hidden  Note that applications and
+internal routines often temporarily select a window in order to simplify
+coding.  As a rule, such selections (including those made by the macros
address@hidden and @code{with-selected-window} below) are
+not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
+Selections that ``really count'' are those causing a visible change in
+the next redisplay of @var{window}'s frame and should be always
+recorded.  This also means that to run a function each time a window
+gets selected, putting it on @code{buffer-list-update-hook} should be
+the right choice.
 @end defun
 
 @cindex most recently selected windows
@@ -1882,7 +1893,7 @@
 return value is the buffer switched to.
 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}).  If
+returned by @code{other-buffer} (@pxref{Buffer List}).  If
 @var{buffer-or-name} is a string that is not the name of any existing
 buffer, this function creates a new buffer with that name; the new
 buffer's major mode is determined by the variable @code{major-mode}
@@ -1890,7 +1901,7 @@
 
 Normally, the specified buffer is put at the front of the buffer
 list---both the global buffer list and the selected frame's buffer
-list (@pxref{The Buffer List}).  However, this is not done if the
+list (@pxref{Buffer List}).  However, this is not done if the
 optional argument @var{norecord} is address@hidden
 
 Sometimes, @code{switch-to-buffer} may be unable to display the buffer
@@ -1968,7 +1979,7 @@
 was switched to.
 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}).  If
+returned by @code{other-buffer} (@pxref{Buffer List}).  If
 @var{buffer-or-name} is a string that is not the name of any existing
 buffer, this function creates a new buffer with that name; the new
 buffer's major mode is determined by the variable @code{major-mode}
@@ -2524,9 +2535,9 @@
 
 If repeated invocations of this command have already shown all buffers
 previously shown in @var{window}, further invocations will show buffers
-from the buffer list of the frame @var{window} appears on (@pxref{The
-Buffer List}), trying to skip buffers that are already shown in another
-window on that frame.
+from the buffer list of the frame @var{window} appears on (@pxref{Buffer
+List}), trying to skip buffers that are already shown in another window
+on that frame.
 @end deffn
 
 @deffn Command switch-to-next-buffer &optional window
@@ -2537,7 +2548,7 @@
 
 If there is no recent invocation of @code{switch-to-prev-buffer} that
 can be undone, this function tries to show a buffer from the buffer list
-of the frame @var{window} appears on (@pxref{The Buffer List}).
+of the frame @var{window} appears on (@pxref{Buffer List}).
 @end deffn
 
 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
@@ -2584,7 +2595,7 @@
 behaves like @code{delete-windows-on} otherwise.
 @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
 
-   When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
+   When @code{bury-buffer} (@pxref{Buffer List}) operates on the
 selected window (which shows the buffer that shall be buried), it
 handles case (2) by calling @code{frame-auto-hide-function}
 (@pxref{Quitting Windows}) to deal with the selected frame.  The other
@@ -2623,7 +2634,7 @@
 hand, a window has been reused for displaying the buffer, you might
 prefer showing the buffer previously shown in that window, by calling the
 function @code{switch-to-prev-buffer} (@pxref{Window History}).
-Finally, you might want to either bury (@pxref{The Buffer List}) or kill
+Finally, you might want to either bury (@pxref{Buffer List}) or kill
 (@pxref{Killing Buffers}) the window's buffer.
 
    The following command uses information on how the window for
@@ -2705,11 +2716,12 @@
 The function specified by this option is called to automatically hide
 frames.  This function is called with one argument---a frame.
 
-The function specified here is called by @code{bury-buffer} (@pxref{The
-Buffer List}) when the selected window is dedicated and shows the buffer
-to bury.  It is also called by @code{quit-restore-window} (see above)
-when the frame of the window to quit has been specially created for
-displaying that window's buffer and the buffer is not killed.
+The function specified here is called by @code{bury-buffer}
+(@pxref{Buffer List}) when the selected window is dedicated and shows
+the buffer to bury.  It is also called by @code{quit-restore-window}
+(see above) when the frame of the window to quit has been specially
+created for displaying that window's buffer and the buffer is not
+killed.
 
 The default is to call @code{iconify-frame} (@pxref{Visibility of
 Frames}).  Alternatively, you may specify either @code{delete-frame}

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2014-03-06 13:41:58 +0000
+++ b/src/ChangeLog     2014-03-07 15:11:12 +0000
@@ -1,3 +1,9 @@
+2014-03-07  Martin Rudalics  <address@hidden>
+
+       * buffer.c (Vbuffer_list_update_hook): Doc-string fix.
+       * window.c (Fselect_window): Explain NORECORD and
+       `buffer-list-update-hook' in doc-string.
+
 2014-03-06  Martin Rudalics  <address@hidden>
 
        * window.c (Fother_window_for_scrolling): Check that

=== modified file 'src/buffer.c'
--- a/src/buffer.c      2014-02-13 12:16:42 +0000
+++ b/src/buffer.c      2014-03-07 15:11:12 +0000
@@ -6284,9 +6284,9 @@
 
   DEFVAR_LISP ("buffer-list-update-hook", Vbuffer_list_update_hook,
               doc: /* Hook run when the buffer list changes.
-Functions running this hook are `get-buffer-create',
+Functions running this hook are, `get-buffer-create',
 `make-indirect-buffer', `rename-buffer', `kill-buffer',
-and `bury-buffer-internal'.  */);
+`bury-buffer-internal' and `select-window'.  */);
   Vbuffer_list_update_hook = Qnil;
   DEFSYM (Qbuffer_list_update_hook, "buffer-list-update-hook");
 

=== modified file 'src/window.c'
--- a/src/window.c      2014-03-06 13:41:58 +0000
+++ b/src/window.c      2014-03-07 15:11:12 +0000
@@ -559,7 +559,7 @@
 DEFUN ("select-window", Fselect_window, Sselect_window, 1, 2, 0,
        doc: /* Select WINDOW which must be a live window.
 Also make WINDOW's frame the selected frame and WINDOW that frame's
-selected window.  In addition, make WINDOW's buffer current and set that
+selected window.  In addition, make WINDOW's buffer current and set its
 buffer's value of `point' to the value of WINDOW's `window-point'.
 Return WINDOW.
 
@@ -567,8 +567,17 @@
 front of the buffer list and do not make this window the most recently
 selected one.
 
-Note that the main editor command loop sets the current buffer to the
-buffer of the selected window before each command.  */)
+Run `buffer-list-update-hook' unless NORECORD is non-nil.  Note that
+applications and internal routines often select a window temporarily for
+various purposes; mostly, to simplify coding.  As a rule, such
+selections should be not recorded and therefore will not pollute
+`buffer-list-update-hook'.  Selections that "really count" are those
+causing a visible change in the next redisplay of WINDOW's frame and
+should be always recorded.  So if you think of running a function each
+time a window gets selected put it on `buffer-list-update-hook'.
+
+Also note that the main editor command loop sets the current buffer to
+the buffer of the selected window before each command.  */)
   (register Lisp_Object window, Lisp_Object norecord)
 {
   return select_window (window, norecord, 0);