[PATCH] focus hook documentation

[Brian Jenkins <brian@brianjenkins.org>]

[-- Attachment #1.1: Type: text/plain, Size: 196 bytes --]

Hello, Emacs Hackers.

Here is documentation for the new focus hooks (focus-in-hook and
focus-out-hook), including requests not to impose focus hooks on others,
as discussed.

Best,
Brian Jenkins

[-- Attachment #1.2: Type: text/html, Size: 308 bytes --]

[-- Attachment #2: focus-hook-docs.patch --]
[-- Type: application/octet-stream, Size: 3598 bytes --]

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 4935534..1027c86 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1479,6 +1479,28 @@ The redirection lasts until @code{redirect-frame-focus} is called to
 change it.
 @end defun
 
+@defun focus-in-hook
+This is a normal hook run when an Emacs frame gains input focus.
+
+Note that this hook is run when focus switches from one Emacs frame to
+another.
+
+This hook should not be set in published packages.  It
+should be be left to the user to configure, as behavior on focus
+change is a matter of (often strongly held) personal preference.
+@end defun
+
+@defun focus-out-hook
+Normal hook run when a frame loses input focus.
+
+Note that this hook is run when focus switches from one Emacs frame to
+another.
+
+This hook should not be set in published packages.  It
+should be be left to the user to configure, as behavior on focus
+change is a matter of (often strongly held) personal preference.
+@end defun
+
 @defopt focus-follows-mouse
 This option is how you inform Emacs whether the window manager transfers
 focus when the user moves the mouse.  Non-@code{nil} says that it does.
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 745393f..08396cb 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -115,6 +115,12 @@ Function to call to ``quit'' the current buffer.
 @vindex delayed-warnings-hook
 The command loop runs this soon after @code{post-command-hook} (q.v.).
 
+@item focus-in-hook
+@vindex focus-in-hook
+@itemx focus-out-hook
+@vindex focus-out-hook
+@xref{Input Focus}
+
 @item delete-frame-functions
 @xref{Deleting Frames}.
 
diff --git a/etc/NEWS b/etc/NEWS
index 9772f97..900855c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -165,6 +165,8 @@ Generic commands are interactive functions whose implementation can be
 selected among several alternatives, as a matter of user preference.
 
 ** New hooks `focus-in-hook', `focus-out-hook'.
+Normal hooks run when an Emacs frame gains or loses input focus.
+(Intended for use only by end-users, not in packages.)
 
 ** The blink cursor stops blinking after 10 blinks (default) on X and NS.
 You can change the default by customizing the variable blink-cursor-blinks.
diff --git a/src/frame.c b/src/frame.c
index fbfc772..5b537da 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -4472,12 +4472,22 @@ The pointer becomes visible again when the mouse is moved.  */);
   Vmake_pointer_invisible = Qt;
 
   DEFVAR_LISP ("focus-in-hook", Vfocus_in_hook,
-               doc: /* Normal hook run when a frame gains input focus.  */);
+               doc: /* Normal hook run when an Emacs frame gains input focus.
+Note that this hook is run when focus switches from one Emacs frame to
+another.
+This hook should not be set in published packages.  It
+should be be left to the user to configure, as behavior on focus
+change is a matter of (often strongly held) personal preference.*/);
   Vfocus_in_hook = Qnil;
   DEFSYM (Qfocus_in_hook, "focus-in-hook");
 
   DEFVAR_LISP ("focus-out-hook", Vfocus_out_hook,
-               doc: /* Normal hook run when a frame loses input focus.  */);
+               doc: /* Normal hook run when an Emacs frame loses input focus.
+Note that this hook is run when focus switches from one Emacs frame to
+another.
+This hook should not be set in published packages.  It
+should be be left to the user to configure, as behavior on focus
+change is a matter of (often strongly held) personal preference.*/);
   Vfocus_out_hook = Qnil;
   DEFSYM (Qfocus_out_hook, "focus-out-hook");