Doc updates related to tty-setup-hook

* doc/emacs/custom.texi (Terminal Init):
Replace term-setup-hook with tty-setup-hook.

* doc/lispref/display.texi (Window Systems):
* doc/lispref/hooks.texi (Standard Hooks):
Replace term-setup-hook with tty-setup-hook.

* doc/lispref/os.texi (Startup Summary, Init File, Terminal-Specific):
Replace term-setup-hook with tty-setup-hook, and update.

* doc/misc/edt.texi (Quick start, Starting emulation):
* doc/misc/efaq.texi (Fullscreen mode on MS-Windows)
(Terminal setup code works after Emacs has begun): Update hook details.

* doc/misc/vip.texi (Loading VIP): Fix hook example.

* lisp/faces.el (tty-setup-hook, tty-run-terminal-initialization): Doc fixes.

* lisp/startup.el (term-setup-hook): Doc fix.  Make obsolete.

* lisp/emulation/edt.el: Comment update.

* lisp/term/sun.el (sun-raw-prefix-hooks):
Use tty-setup-hook instead of term-setup-hook.
(terminal-init-sun): Construct message from bytecomp plist.

* lisp/term/wyse50.el (enable-arrow-keys): Doc fix.

* etc/refcards/vipcard.tex: Hook fix.

* etc/NEWS: Related edit.

19 files changed, 98 insertions, 58 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 9fba16f4126..55c92de2462 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2014-02-25  Glenn Morris  <rgm@gnu.org>
+
+        * custom.texi (Terminal Init):
+        Replace term-setup-hook with tty-setup-hook.
+
 2014-02-23  Glenn Morris  <rgm@gnu.org>
 
         * rmail.texi (Rmail Inbox): Mention rmail-mbox-format.
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 781d58f193d..deaeb913b75 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2474,8 +2474,8 @@ variable @code{term-file-prefix} and the terminal type.  Your @file{.emacs}
 file can prevent the loading of the terminal-specific library by setting
 @code{term-file-prefix} to @code{nil}.
 
-@vindex term-setup-hook
-  Emacs runs the hook @code{term-setup-hook} at the end of
+@vindex tty-setup-hook
+  Emacs runs the hook @code{tty-setup-hook} at the end of
 initialization, after both your @file{.emacs} file and any
 terminal-specific library have been read in.  Add hook functions to this
 hook if you wish to override part of any of the terminal-specific
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index fe00e5a7b53..6a105a03b3b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2014-02-25  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (Window Systems):
+        Replace term-setup-hook with emacs-startup-hook.
+        * hooks.texi (Standard Hooks):
+        Replace term-setup-hook with tty-setup-hook.
+        * os.texi (Startup Summary, Init File, Terminal-Specific):
+        Replace term-setup-hook with tty-setup-hook, and update.
+
 2014-02-22  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * functions.texi (Declare Form): Document gv-expander, gv-setter, and
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c4c2c13d3d2..519d33f5844 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6378,7 +6378,7 @@ 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{term-setup-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
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 22061fe9931..c28fe2d5f5b 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -1,7 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1993, 1998, 2001-2014 Free Software Foundation,
-@c Inc.
+@c Copyright (C) 1990-1993, 1998, 2001-2014 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node Standard Hooks
 @appendix Standard Hooks
@@ -213,7 +212,7 @@ Hook run when about to switch windows with a mouse command.
 @itemx temp-buffer-show-hook
 @xref{Temporary Displays}.
 
-@item term-setup-hook
+@item tty-setup-hook
 @xref{Terminal-Specific}.
 
 @item window-configuration-change-hook
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index cff0b2b15c5..dda139b8d74 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -175,8 +175,8 @@ If the buffer @file{*scratch*} exists and is still in Fundamental mode
 
 @item
 If started on a text terminal, it loads the terminal-specific
-Lisp library, which is specified by the variable
-@code{term-file-prefix} (@pxref{Terminal-Specific}).  This is not done
+Lisp library (@pxref{Terminal-Specific}), and runs the hook
+@code{tty-setup-hook}.  This is not done
 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
 
 @c Now command-line calls command-line-1.
@@ -210,7 +210,7 @@ empty, it inserts @code{initial-scratch-message} into that buffer.
 @c daemon/session restore step?
 
 @item
-It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
+It runs @code{emacs-startup-hook}.
 
 @item
 It calls @code{frame-notice-user-settings}, which modifies the
@@ -408,8 +408,7 @@ terminal) and processing the command-line action arguments.
 
 @defvar emacs-startup-hook
 This normal hook is run, once, just after handling the command line
-arguments, just before @code{term-setup-hook}.  In batch mode, Emacs
-does not run either of these hooks.
+arguments.  In batch mode, Emacs does not run this hook.
 @end defvar
 
 @defvar user-init-file
@@ -440,12 +439,12 @@ trying the @samp{.elc} and @samp{.el} suffixes.
   The usual role of a terminal-specific library is to enable special
 keys to send sequences that Emacs can recognize.  It may also need to
 set or add to @code{input-decode-map} if the Termcap or Terminfo entry
-does not specify all the terminal's function keys.  @xref{Terminal
-Input}.
+does not specify all the terminal's function keys.  @xref{Terminal Input}.
 
-  When the name of the terminal type contains a hyphen or underscore, and no library
-is found whose name is identical to the terminal's name, Emacs strips
-from the terminal's name the last hyphen or underscore and everything that follows
+  When the name of the terminal type contains a hyphen or underscore,
+and no library is found whose name is identical to the terminal's
+name, Emacs strips from the terminal's name the last hyphen or
+underscore and everything that follows
 it, and tries again.  This process is repeated until Emacs finds a
 matching library, or until there are no more hyphens or underscores in the name
 (i.e., there is no terminal-specific library).  For example, if the
@@ -454,17 +453,13 @@ terminal name is @samp{xterm-256color} and there is no
 @file{term/xterm.el}.  If necessary, the terminal library can evaluate
 @code{(getenv "TERM")} to find the full name of the terminal type.
 
-  Your init file can prevent the loading of the
-terminal-specific library by setting the variable
-@code{term-file-prefix} to @code{nil}.  This feature is useful when
-experimenting with your own peculiar customizations.
+  Your init file can prevent the loading of the terminal-specific
+library by setting the variable @code{term-file-prefix} to @code{nil}.
 
   You can also arrange to override some of the actions of the
-terminal-specific library by setting the variable
-@code{term-setup-hook}.  This is a normal hook that Emacs runs
-at the end of its initialization, after loading both
-your init file and any terminal-specific libraries.  You could
-use this hook to define initializations for terminals that do not
+terminal-specific library by using @code{tty-setup-hook}.  This is
+a normal hook that Emacs runs after initializing a new text terminal.
+You could use this hook to define initializations for terminals that do not
 have their own libraries.  @xref{Hooks}.
 
 @defvar term-file-prefix
@@ -484,13 +479,13 @@ terminal-initialization file.
 On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
 @end defvar
 
-@defvar term-setup-hook
-This variable is a normal hook that Emacs runs after loading your
-init file, the default initialization file (if any) and the
-terminal-specific Lisp file.
-
-You can use @code{term-setup-hook} to override the definitions made by a
-terminal-specific file.
+@defvar tty-setup-hook
+This variable is a normal hook that Emacs runs after initializing a
+new text terminal.  (This applies when Emacs starts up in non-windowed
+mode, and when making a tty @command{emacsclient} connection.)  The
+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}.
 @end defvar
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 39ae01e86ec..f017e9479a4 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,5 +1,10 @@
 2014-02-25  Glenn Morris  <rgm@gnu.org>
 
+        * edt.texi (Quick start, Starting emulation): Update hook details.
+        * efaq.texi (Fullscreen mode on MS-Windows)
+        (Terminal setup code works after Emacs has begun): Update hook details.
+        * vip.texi (Loading VIP): Fix hook example.
+
         * efaq-w32.texi (Bash): Don't use setq with hooks.
 
 2014-02-24  Paul Eggert  <eggert@cs.ucla.edu>
diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi
index c4937d4ae6e..ef27d339e9e 100644
--- a/doc/misc/edt.texi
+++ b/doc/misc/edt.texi
@@ -91,7 +91,7 @@ initiate an Emacs session, by adding the following line to your
 @file{.emacs} file:
 
 @example
-(add-hook term-setup-hook 'edt-emulation-on)
+(add-hook 'emacs-startup-hook 'edt-emulation-on)
 @end example
 
 @noindent @strong{Important:} Be sure to read the rest of this manual.
@@ -295,7 +295,7 @@ initiate an Emacs session, by adding the following line to your
 @file{.emacs} file:
 
 @example
-(add-hook term-setup-hook 'edt-emulation-on)
+(add-hook 'emacs-startup-hook 'edt-emulation-on)
 @end example
 
 A reference sheet is included (later on) listing the default EDT
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index a13d3df43f1..ca9e24fbeaa 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -2684,8 +2684,8 @@ Use the function @code{w32-send-sys-command}.  For example, you can
 put the following in your @file{.emacs} file:
 
 @lisp
-(add-hook 'term-setup-hook
-          #'(lambda () (w32-send-sys-command ?\xF030)))
+(add-hook 'emacs-startup-hook
+          (lambda () (w32-send-sys-command ?\xF030)))
 @end lisp
 
 To avoid the slightly distracting visual effect of Emacs starting with
@@ -3594,12 +3594,12 @@ been executed but is not, then you will experience this problem (this
 code/file execution order is not enforced after startup).
 
 To postpone the execution of Emacs Lisp code until after terminal or
-window-system setup, treat the code as a @dfn{lambda list} and set the
-value of either the @code{term-setup-hook} or @code{window-setup-hook}
-variable to this lambda function.  For example,
+window-system setup, treat the code as a @dfn{lambda list} and add it to
+@code{emacs-startup-hook} (or @code{tty-setup-hook} in Emacs 24.4 and
+newer).  For example,
 
 @lisp
-(add-hook 'term-setup-hook
+(add-hook 'emacs-startup-hook
           (lambda ()
            (when (string-match "\\`vt220" (or (getenv "TERM") ""))
              ;; Make vt220's "Do" key behave like M-x:
diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi
index 367ed2adb4c..90dc3cd8dec 100644
--- a/doc/misc/vip.texi
+++ b/doc/misc/vip.texi
@@ -165,7 +165,7 @@ directory and it will be executed every time you invoke Emacs.  If you wish
 to be in vi mode whenever Emacs starts up, you can include the following
 line in your @file{.emacs} file instead of the above line:
 @example
-(setq term-setup-hook 'vip-mode)
+(add-hook 'emacs-startup-hook 'vip-mode)
 @end example
 @noindent
 (@xref{Vi Mode}, for the explanation of vi mode.)
diff --git a/etc/ChangeLog b/etc/ChangeLog
index 62f00d05aca..6f419c346c6 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,7 @@
+2014-02-25  Glenn Morris  <rgm@gnu.org>
+
+        * refcards/vipcard.tex: Hook fix.
+
 2014-02-23  Juanma Barranquero  <lekktu@gmail.com>
 
         * NEWS: Fix references to ?« and ?» that got mangled somehow.
diff --git a/etc/NEWS b/etc/NEWS
index f7a36c51fc2..5a3bf58976f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1202,7 +1202,12 @@ The function `display-popup-menus-p' will now return non-nil for a
 display or frame whenever a mouse is supported on that display or
 frame.
 
-*** New hook `tty-setup-hook'.
++++
+*** New hook `tty-setup-hook', run at the end of initializing a text terminal.
+
++++
+*** The hook `term-setup-hook' is obsolete.  It is entirely equivalent
+to `emacs-startup-hook'.  See also the new `tty-setup-hook'.
 
 ** Window Handling
 
diff --git a/etc/refcards/vipcard.tex b/etc/refcards/vipcard.tex
index deb42a7f34f..23f263202a7 100644
--- a/etc/refcards/vipcard.tex
+++ b/etc/refcards/vipcard.tex
@@ -279,7 +279,7 @@ If you wish to be in vi mode just after you startup Emacs,
 include the line:
 
 \hskip 5ex
-\kbd{(setq term-setup-hook 'vip-mode)}
+\kbd{(add-hook 'emacs-startup-hook 'vip-mode)}
 
 in your \kbd{.emacs} file.
 Or, you can put the following alias in your \kbd{.cshrc} file.
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 69434453c85..67256c588e7 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,12 @@
+2014-02-25  Glenn Morris  <rgm@gnu.org>
+
+        * faces.el (tty-setup-hook, tty-run-terminal-initialization): Doc fixes.
+        * startup.el (term-setup-hook): Doc fix.  Make obsolete.
+        * term/sun.el (sun-raw-prefix-hooks):
+        Use tty-setup-hook instead of term-setup-hook.
+        (terminal-init-sun): Construct message from bytecomp plist.
+        * term/wyse50.el (enable-arrow-keys): Doc fix.
+
 2014-02-24  Juanma Barranquero  <lekktu@gmail.com>
 
         * term/sun.el (kill-region-and-unmark, sun-raw-prefix-hooks):
diff --git a/lisp/emulation/edt.el b/lisp/emulation/edt.el
index 57185053932..a32fb612adb 100644
--- a/lisp/emulation/edt.el
+++ b/lisp/emulation/edt.el
@@ -1,7 +1,6 @@
 ;;; edt.el --- enhanced EDT keypad mode emulation for GNU Emacs
 
-;; Copyright (C) 1986, 1992-1995, 2000-2014 Free Software Foundation,
-;; Inc.
+;; Copyright (C) 1986, 1992-1995, 2000-2014 Free Software Foundation, Inc.
 
 ;; Author: Kevin Gallagher <Kevin.Gallagher@boeing.com>
 ;; Maintainer: Kevin Gallagher <Kevin.Gallagher@boeing.com>
@@ -51,7 +50,7 @@
 ;; you initiate a GNU Emacs session, by adding the following line to
 ;; your init file:
 ;;
-;;    (add-hook term-setup-hook 'edt-emulation-on)
+;;    (add-hook 'emacs-startup-hook 'edt-emulation-on)
 
 ;; IMPORTANT: Be sure to read the Info node `edt' for more details.
 ;; It contains very helpful user information.
diff --git a/lisp/faces.el b/lisp/faces.el
index 3394c721f04..985355ade09 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2107,12 +2107,16 @@ the above example."
 
 (defvar tty-setup-hook nil
   "Hook run after running the initialization function of a new text terminal.
+Specifically, `tty-run-terminal-initialization' runs this.
 This can be used to fine tune the `input-decode-map', for example.")
 
 (defun tty-run-terminal-initialization (frame &optional type)
   "Run the special initialization code for the terminal type of FRAME.
 The optional TYPE parameter may be used to override the autodetected
-terminal type to a different value."
+terminal type to a different value.  As a final step, this runs the
+hook `tty-setup-hook'.
+
+If you set `term-file-prefix' to nil, this function does nothing."
   (setq type (or type (tty-type frame)))
   ;; Load library for our terminal type.
   ;; User init file can set term-file-prefix to nil to prevent this.
diff --git a/lisp/startup.el b/lisp/startup.el
index b3f2316729b..9c9f23ba9a6 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1,7 +1,6 @@
 ;;; startup.el --- process Emacs shell arguments  -*- lexical-binding: t -*-
 
-;; Copyright (C) 1985-1986, 1992, 1994-2014 Free Software Foundation,
-;; Inc.
+;; Copyright (C) 1985-1986, 1992, 1994-2014 Free Software Foundation, Inc.
 
 ;; Maintainer: emacs-devel@gnu.org
 ;; Keywords: internal
@@ -282,10 +281,15 @@ these functions will invoke the debugger.")
   "Normal hook run after loading init files and handling the command line.")
 
 (defvar term-setup-hook nil
-  "Normal hook run after loading terminal-specific Lisp code.
-It also follows `emacs-startup-hook'.  This hook exists for users to set,
-so as to override the definitions made by the terminal-specific file.
-Emacs never sets this variable itself.")
+  "Normal hook run immediately after `emacs-startup-hook'.
+In new code, there is no reason to use this instead of `emacs-startup-hook'.
+If you want to execute terminal-specific Lisp code, for example
+to override the definitions made by the terminal-specific file,
+see `tty-setup-hook'.")
+
+(make-obsolete-variable 'term-setup-hook
+                        "use either `emacs-startup-hook' or \
+`tty-setup-hook' instead." "24.4")
 
 (defvar inhibit-startup-hooks nil
   "Non-nil means don't run `term-setup-hook' and `emacs-startup-hook'.
diff --git a/lisp/term/sun.el b/lisp/term/sun.el
index c2a913ad345..b3af959c30e 100644
--- a/lisp/term/sun.el
+++ b/lisp/term/sun.el
@@ -123,7 +123,8 @@
 
 (defvar sun-raw-prefix-hooks nil
   "List of forms to evaluate after setting `sun-raw-prefix'.")
-(make-obsolete-variable 'sun-raw-prefix-hooks 'term-setup-hook "21.1")
+;; Obsolete since 21.1, but tty-setup-hook only exists since 24.4.
+(make-obsolete-variable 'sun-raw-prefix-hooks 'tty-setup-hook "21.1")
 
 
 
@@ -149,7 +150,9 @@
   (global-set-key [f7]  'enlarge-window)
 
   (when sun-raw-prefix-hooks
-    (message "sun-raw-prefix-hooks is obsolete!  Use term-setup-hook instead!")
+    (message "sun-raw-prefix-hooks is obsolete!  Use %s instead!"
+             (or (car-safe (get 'sun-raw-prefix-hooks 'byte-obsolete-variable))
+                 "emacs-startup-hook"))
     (let ((hooks sun-raw-prefix-hooks))
       (while hooks
         (eval (car hooks))
diff --git a/lisp/term/wyse50.el b/lisp/term/wyse50.el
index a894801f985..aa9ba43d3d7 100644
--- a/lisp/term/wyse50.el
+++ b/lisp/term/wyse50.el
@@ -1,7 +1,6 @@
 ;;; wyse50.el --- terminal support code for Wyse 50
 
-;; Copyright (C) 1989, 1993-1994, 2001-2014 Free Software Foundation,
-;; Inc.
+;; Copyright (C) 1989, 1993-1994, 2001-2014 Free Software Foundation, Inc.
 
 ;; Author: Daniel Pfeiffer <occitan@esperanto.org>,
 ;;      Jim Blandy <jimb@occs.cs.oberlin.edu>
@@ -132,7 +131,7 @@
                          (concat "\ea23R" (1+ (frame-width)) "C\eG0"))))))
 
 (defun enable-arrow-keys ()
-  "To be called by `term-setup-hook'. Overrides 6 Emacs standard keys
+  "To be called by `tty-setup-hook'.  Overrides 6 Emacs standard keys
 whose functions are then typed as follows:
 C-a     Funct Left-arrow
 C-h     M-?