Merge from origin/emacs-25

0ae9a81 Document 'timerp'
2c72c46 Improve documentation of overlay priorities
f6fa160 Fix 'dired-compress-files'
2b8c5f0 Update commentary of STRING_CHAR and FETCH_MULTIBYTE_CHAR

# Conflicts:
#	lisp/dired.el
#	src/buffer.h
#	src/character.h

2 files changed, 24 insertions, 10 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 93b84a0f205..381edbac48a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1553,10 +1553,8 @@ the buffer's undo list.
 
   Since more than one overlay can specify a property value for the
 same character, Emacs lets you specify a priority value of each
-overlay.  In case two overlays have the same priority value, and one
-is nested in the other, then the inner one will have priority over the
-outer one.  If neither is nested in the other then you should not make
-assumptions about which overlay will prevail.
+overlay.  The priority value is used to decide which of the
+overlapping overlays will ``win''.
 
   These functions read and set the properties of an overlay:
 
@@ -1593,17 +1591,26 @@ If you want to specify a priority value, use either @code{nil}
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property; the one whose
-@code{priority} value is larger overrides the other.  For the
+@code{priority} value is larger overrides the other.  (For the
 @code{face} property, the higher priority overlay's value does not
 completely override the other value; instead, its face attributes
 override the face attributes of the lower priority @code{face}
-property.
+property.)  If two overlays have the same priority value, and one is
+nested in the other, then the inner one will prevail over the outer
+one.  If neither is nested in the other then you should not make
+assumptions about which overlay will prevail.
 
 Currently, all overlays take priority over text properties.
 
 Note that Emacs sometimes uses non-numeric priority values for some of
-its internal overlays, so do not try to do arithmetic on the
-priority of an overlay (unless it is one that you created).  If you
+its internal overlays, so do not try to do arithmetic on the priority
+of an overlay (unless it is one that you created).  In particular, the
+overlay used for showing the region uses a priority value of the form
+@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
+value is used as described above, and @var{secondary} is the fallback
+value used when @var{primary} and the nesting considerations fail to
+resolve the precedence between overlays.  However, you are advised not
+to design Lisp programs based on this implementation detail; if you
 need to put overlays in priority order, use the @var{sorted} argument
 of @code{overlays-at}.  @xref{Finding Overlays}.
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 08c69d37c5e..277abb1477d 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1726,10 +1726,17 @@ This function returns @code{t} if @var{year} is a leap year.
 
 @node Timers
 @section Timers for Delayed Execution
-@cindex timer
+@cindex timers
 
   You can set up a @dfn{timer} to call a function at a specified
-future time or after a certain length of idleness.
+future time or after a certain length of idleness.  A timer is a
+special object that stores the information about the next invocation
+times and the function to invoke.
+
+@defun timerp object
+This predicate function returns non-@code{nil} of @code{object} is a
+timer.
+@end defun
 
   Emacs cannot run timers at any arbitrary point in a Lisp program; it
 can run them only when Emacs could accept output from a subprocess: