Improve documentation of several recent changes

* src/xfaces.c (merge_face_ref): Fix a typo in the commentary.
(evaluate_face_filter, filter_face_ref): Minor copyedits in
the commentary.
* doc/lispref/display.texi (Face Remapping):
* doc/lispref/text.texi (Special Properties): Document the
':filter' face specs and their effects.  Document
'face-filters-always-match'.

* doc/emacs/files.texi (Visiting): Document the new
possibility to visit large files literally in response to
question asked by Emacs.
* etc/NEWS: Mention the new possibility to visit large files
literally.
* lisp/files.el (files--ask-user-about-large-file): Use
"literally" instead of "raw", for consistency with
find-file-literally.

* doc/lispref/frames.texi (Input Focus): Tell explicitly that
focus-change events are sometimes supported on TTY frames.

4 files changed, 34 insertions, 4 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 7043bdc0688..f902baee9c2 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -206,7 +206,10 @@ saved it.  If the file has changed, Emacs offers to reread it.
   If you try to visit a file larger than
 @code{large-file-warning-threshold} (the default is 10000000, which is
 about 10 megabytes), Emacs asks you for confirmation first.  You can
-answer @kbd{y} to proceed with visiting the file.  Note, however, that
+answer @kbd{y} to proceed with visiting the file or @kbd{l} to visit
+the file literally (see below).  Visiting large files literally speeds
+up navigation and editing of such files, because various
+potentially-expensive features are turned off.  Note, however, that
 Emacs cannot visit files that are larger than the maximum Emacs buffer
 size, which is limited by the amount of memory Emacs can allocate and
 by the integers that Emacs can represent (@pxref{Buffers}).  If you
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ce7ec3ac10d..0ba7f0fd586 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2938,7 +2938,13 @@ the remapped face---it replaces the normal definition of @var{face},
 instead of modifying it.
 
 If @code{face-remapping-alist} is buffer-local, its local value takes
-effect only within that buffer.
+effect only within that buffer.  If @code{face-remapping-alist}
+includes faces applicable only to certain windows, by using the
+@w{@code{(:filtered (:window @var{param} @var{val}) @var{spec})}},
+that face takes effect only in windows that match the filter
+conditions (@pxref{Special Properties}).  To turn off face filtering
+temporarily, bind @code{face-filters-always-match} to a non-@code{nil}
+value, then all face filters will match any window.
 
 Note: face remapping is non-recursive.  If @var{remapping} references
 the same face name @var{face}, either directly or via the
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 5e8b5b46d5d..6678644bec7 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2783,11 +2783,15 @@ could switch to a different terminal without switching back when
 you're done.
 @end deffn
 
+@cindex text-terminal focus notification
 Emacs cooperates with the window system by arranging to select frames
 as the server and window manager request.  When a window system
 informs Emacs that one of its frames has been selected, Emacs
-internally generates a @dfn{focus-in} event.  Focus events are
-normally handled by @code{handle-focus-in}.
+internally generates a @dfn{focus-in} event.  When an Emacs frame is
+displayed on a text-terminal emulator, such as @command{xterm}, which
+supports reporting of focus-change notification, the focus-in and
+focus-out events are available even for text-mode frames.  Focus
+events are normally handled by @code{handle-focus-in}.
 
 @deffn Command handle-focus-in event
 This function handles focus-in events from window systems and
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index bb6ab04a927..ea9c82422ec 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3325,6 +3325,17 @@ foreground or background color, similar to @code{(:foreground
 @var{color-name})} or @code{(:background @var{color-name})}.  This
 form is supported for backward compatibility only, and should be
 avoided.
+
+@item
+A cons cell of the form @w{@code{(:filtered @var{filter}
+@var{face-spec})}}, that specifies the face given by @var{face-spec},
+but only if @var{filter} matches when the face is used for display.
+The @var{face-spec} can use any of the forms mentioned above.  The
+@var{filter} should be of the form @w{@code{(:window @var{param}
+@var{value})}}, which matches for windows whose parameter @var{param}
+is @code{eq} to @var{value}.  If the variable
+@code{face-filters-always-match} is non-@code{nil}, all face filters
+are deemed to have matched.
 @end itemize
 
 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
@@ -3699,6 +3710,12 @@ string to display, which is passed through
 The GNU Emacs Manual}) provides an example.
 @end defvar
 
+@defvar face-filters-always-match
+If this variable is non-@code{nil}, face filters that specify
+attributes applied only when certain conditions are met will be deemed
+to match always.
+@end defvar
+
 @node Format Properties
 @subsection Formatted Text Properties