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'.

3 files changed, 20 insertions, 5 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index 9fef63c9a58..6d1285a82da 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,9 @@
+2014-03-07  Martin Rudalics  <rudalics@gmx.at>
+
+        * 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  <rudalics@gmx.at>
 
         * window.c (Fother_window_for_scrolling): Check that
diff --git a/src/buffer.c b/src/buffer.c
index 90c15420d1d..028ef76ff71 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -6284,9 +6284,9 @@ The function `kill-all-local-variables' runs this before doing anything else.  *
 
   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");
 
diff --git a/src/window.c b/src/window.c
index 4d8520d7436..f42219cae94 100644
--- a/src/window.c
+++ b/src/window.c
@@ -559,7 +559,7 @@ select_window_1 (Lisp_Object window, bool inhibit_point_swap)
 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 @@ Optional second arg NORECORD non-nil means do not put this buffer at the
 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);