Doc updates re window-setup-hook

* lisp/startup.el (window-setup-hook): Doc fix.

* doc/lispref/display.texi (Window Systems): Remove window-setup-hook.

* doc/lispref/os.texi (Startup Summary, Init File):
Improve description of window-setup-hook.
(Terminal-Specific): Update window-setup-hook cross-reference.

* doc/lispref/hooks.texi (Standard Hooks):
Update window-setup-hook cross-reference.

6 files changed, 27 insertions, 20 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 060dca1adcf..1e6b9f445c7 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,11 @@
 2014-06-06  Glenn Morris  <rgm@gnu.org>
 
+	* display.texi (Window Systems): Remove window-setup-hook.
+	* os.texi (Startup Summary, Init File):
+	Improve description of window-setup-hook.
+	(Terminal-Specific): Update window-setup-hook cross-reference.
+	* hooks.texi (Standard Hooks): Update window-setup-hook cross-reference.
+
 	* display.texi (Overlay Properties): Update re priority.  (Bug#17234)
 
 2014-06-05  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 35282138b1a..b4f987bb2a8 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6519,18 +6519,6 @@ indicator of Emacs capabilities on a given display type.  Instead, use
 @code{display-graphic-p} or any of the other @code{display-*-p}
 predicates described in @ref{Display Feature Testing}.
 
-@defvar window-setup-hook
-This variable is a normal hook which Emacs runs after handling the
-initialization files.  Emacs runs this hook after it has completed
-loading your init file, the default initialization file (if
-any), and the terminal-specific Lisp code, and running the hook
-@code{emacs-startup-hook}.
-
-This hook is used for internal purposes: setting up communication with
-the window system, and creating the initial window.  Users should not
-interfere with it.
-@end defvar
-
 @node Bidirectional Display
 @section Bidirectional Display
 @cindex bidirectional display
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 9408174872d..547a2ffe442 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -55,6 +55,7 @@ not exactly a hook, but does a similar job.
 @item after-init-hook
 @itemx before-init-hook
 @itemx emacs-startup-hook
+@itemx window-setup-hook
 @xref{Init File}.
 
 @item after-insert-file-functions
@@ -220,9 +221,6 @@ Hook run when about to switch windows with a mouse command.
 @itemx window-size-change-functions
 @xref{Window Hooks}.
 
-@item window-setup-hook
-@xref{Window Systems}.
-
 @item window-text-change-functions
 @vindex window-text-change-functions
 Functions to call in redisplay when text in the window might change.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index c80dfda096c..272a356c7fe 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -218,7 +218,9 @@ parameters of the selected frame according to whatever the init files
 specify.
 
 @item
-It runs @code{window-setup-hook}.  @xref{Window Systems}.
+It runs @code{window-setup-hook}.  The only difference between this
+hook and @code{emacs-startup-hook} is that this one runs after the
+previously mentioned modifications to the frame parameters.
 
 @item
 @cindex startup screen
@@ -411,6 +413,12 @@ This normal hook is run, once, just after handling the command line
 arguments.  In batch mode, Emacs does not run this hook.
 @end defvar
 
+@defvar window-setup-hook
+This normal hook is very similar to @code{emacs-startup-hook}.
+The only difference is that it runs slightly later, after setting
+of the frame parameters.  @xref{Startup Summary, window-setup-hook}.
+@end defvar
+
 @defvar user-init-file
 This variable holds the absolute file name of the user's init file.  If the
 actual init file loaded is a compiled file, such as @file{.emacs.elc},
@@ -487,7 +495,7 @@ hook runs after loading your init file (if applicable) and the
 terminal-specific Lisp file, so you can use it to adjust the
 definitions made by that file.
 
-For a related feature, @pxref{Window Systems, window-setup-hook}.
+For a related feature, @pxref{Init File, window-setup-hook}.
 @end defvar
 
 @node Command-Line Arguments
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 1280e39ec27..3b5df032e9c 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2014-06-06  Glenn Morris  <rgm@gnu.org>
+
+	* startup.el (window-setup-hook): Doc fix.
+
 2014-06-05  Glenn Morris  <rgm@gnu.org>
 
 	* emacs-lisp/package.el (package-check-signature)
diff --git a/lisp/startup.el b/lisp/startup.el
index 129b54d974f..5f1bdeadbd3 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -302,9 +302,12 @@ keys for use under X.  It is used in a fashion analogous to the
 environment variable TERM.")
 
 (defvar window-setup-hook nil
-  "Normal hook run to initialize window system display.
-Emacs runs this hook after processing the command line arguments and loading
-the user's init file.")
+  "Normal hook run after loading init files and handling the command line.
+This is very similar to `emacs-startup-hook'.  The only difference
+is that this hook runs after frame parameters have been set up in
+response to any settings from your init file.  Unless this matters
+to you, use `emacs-startup-hook' instead.  (The name of this hook
+is due to historical reasons, and does not reflect its purpose very well.)")
 
 (defcustom initial-major-mode 'lisp-interaction-mode
   "Major mode command symbol to use for the initial `*scratch*' buffer."