Merge from origin/emacs-25

b134c20 Sync with gnulib
bb30fa9 Fix last change on 2016-01-02
488a72f ; Spelling fixes
9b1aab9 Port run-prolog EMACS to SWI-Prolog 7.2.3
0e7bcec Avoid crashes due to unreasonably large or small text scaling
85f257c Improve documentation of 'with-eval-after-load'
668c7bc Improve handling of non-ASCII characters in Git log messages
b570769 Remove undefined behavior in OS X dumper.
97211f3 Fix clipping of xwidgets
e87fbc0 Improve Lisp-level documentation of tooltips
9f1786e Faces names should not end in "-face".
3283271 * src/xsmfns.c (syms_of_xsmfns): Remove stray "s in doc strings.
a1f221b Comint and compile no longer set EMACS
5c28890 * lisp/subr.el (read-key): Don't let the prompt linger (bug#2...
a75b9a6 Merge branch 'emacs-25' of git.savannah.gnu.org:/srv/git/emac...
c93ae7a Allow to customize names of executables used by grep.el
f6497c6 Set locale encoding to UTF-8 when run from OS X GUI.
7ad1d07 Avoid signaling errors in 'M-n' at the 'C-x C-f' prompt
a3f1ac2 Avoid infinite loop in 'studlify-word'
f36df4b Don’t recommend obsolete EMACS env var
fb0b531 * lisp/emacs-lisp/package.el: Change from a few days ago need...

3 files changed, 79 insertions, 3 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 1e45501482c..3cd1d4edf1c 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -34,6 +34,7 @@ that Emacs presents to the user.
 * Character Display::   How Emacs displays individual characters.
 * Beeping::             Audible signal to the user.
 * Window Systems::      Which window system is being used.
+* Tooltips::            Tooltip display in Emacs.
 * Bidirectional Display:: Display of bidirectional scripts, such as
                              Arabic and Farsi.
 @end menu
@@ -7131,6 +7132,81 @@ 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}.
 
+@node Tooltips
+@section Tooltips
+@cindex tooltips
+@dfn{Tooltips} are special frames (@pxref{Frames}) that are used to
+display helpful hints (a.k.a.@: ``tips'') related to the current
+position of the mouse pointer.  Emacs uses tooltips to display help
+strings about active portions of text (@pxref{Special Properties}) and
+about various UI elements, such as menu items (@pxref{Extended Menu
+Items}) and tool-bar buttons (@pxref{Tool Bar}).
+
+@defun tooltip-mode
+Tooltip Mode is a minor mode that enables display of tooltips.
+Turning off this mode causes the tooltips be displayed in the echo
+area.  On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always
+displayed in the echo area.
+@end defun
+
+@vindex x-gtk-use-system-tooltips
+When Emacs is built with GTK+ support, it by default displays tooltips
+using GTK+ functions, and the appearance of the tooltips is then
+controlled by GTK+ settings.  GTK+ tooltips can be disabled by
+changing the value of the variable @code{x-gtk-use-system-tooltips} to
+@code{nil}.  The rest of this subsection describes how to control
+non-GTK+ tooltips, which are presented by Emacs itself.
+
+Since tooltips are special frames, they have their frame parameters
+(@pxref{Frame Parameters}).  Unlike other frames, the frame parameters
+for tooltips are stored in a special variable.
+
+@defvar tooltip-frame-parameters
+This customizable option holds the frame parameters used for
+displaying tooltips.  Any font and color parameters are ignored, and
+the corresponding attributes of the @code{tooltip} face are used
+instead.  If @code{left} or @code{top} parameters are included, they
+are used as absolute frame-relative coordinates where the tooltip
+should be shown.  (Mouse-relative position of the tooltip can be
+customized using the variables described in @ref{Tooltips,,, emacs,
+The GNU Emacs Manual}.)  Note that the @code{left} and @code{top}
+parameters, if present, override the values of mouse-relative offsets.
+@end defvar
+
+@vindex tooltip@r{ face}
+The @code{tooltip} face determines the appearance of text shown in
+tooltips.  It should generally use a variable-pitch font of size that
+is preferably smaller than the default frame font.
+
+@findex tooltip-help-tips
+@defvar tooltip-functions
+This abnormal hook is a list of functions to call when Emacs needs to
+display a tooltip.  Each function is called with a single argument
+@var{event} which is a copy of the last mouse movement event.  If a
+function on this list actually displays the tooltip, it should return
+non-@code{nil}, and then the rest of the functions will not be
+called.  The default value of this variable is a single function
+@code{tooltip-help-tips}.
+@end defvar
+
+If you write your own function to be put on the
+@code{tooltip-functions} list, you may need to know the buffer of the
+mouse event that triggered the tooltip display.  The following
+function provides that information.
+
+@defun tooltip-event-buffer event
+This function returns the buffer over which @var{event} occurred.
+Call it with the argument of the function from
+@code{tooltip-functions} to obtain the buffer whose text triggered the
+tooltip.  Note that the event might occur not over a buffer (e.g.,
+over the tool bar), in which case this function will return
+@code{nil}.
+@end defun
+
+Other aspects of tooltip display are controlled by several
+customizable settings; see @ref{Tooltips,,, emacs, The GNU Emacs
+Manual}.
+
 @node Bidirectional Display
 @section Bidirectional Display
 @cindex bidirectional display
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4c1541e98c6..a3bff0b07ac 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1380,6 +1380,7 @@ Emacs Display
 * Character Display::       How Emacs displays individual characters.
 * Beeping::                 Audible signal to the user.
 * Window Systems::          Which window system is being used.
+* Tooltips::                Tooltip display in Emacs.
 * Bidirectional Display::   Display of bidirectional scripts, such as
                               Arabic and Farsi.
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 55f02904fa1..991b47d20b4 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3279,12 +3279,11 @@ or shorter, higher or lower, wider or narrow, or replaced with an image.
 
 @item help-echo
 @kindex help-echo @r{(text property)}
-@cindex tooltip
+@cindex tooltip for help strings
 @anchor{Text help-echo}
 If text has a string as its @code{help-echo} property, then when you
 move the mouse onto that text, Emacs displays that string in the echo
-area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
-Manual}).
+area, or in the tooltip window (@pxref{Tooltips}).
 
 If the value of the @code{help-echo} property is a function, that
 function is called with three arguments, @var{window}, @var{object} and