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.

7 files changed, 52 insertions, 14 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
 
diff --git a/etc/NEWS b/etc/NEWS
index e89402db131..cecd3f81f85 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -175,6 +175,13 @@ interface that's more like functions like @code{search-forward}.
 ** More commands support noncontiguous rectangular regions, namely
 'upcase-dwim', 'downcase-dwim', 'replace-string', 'replace-regexp'.
 
++++
+** When asked to visit a large file, Emacs now offers visiting it literally.
+Previously, Emacs would only ask for confirmation before visiting
+large files.  Now it also offers a third alternative: to visit the
+file literally, as in 'find-file-literally', which speeds up
+navigation and editing of large files.
+
 
 * Changes in Specialized Modes and Packages in Emacs 27.1
 
@@ -613,7 +620,8 @@ On terminal emulators that support the feature, Emacs can now support
 ** Window-specific face remapping.
 Face specifications (of the kind used in 'face-remapping-alist')
 now support filters, allowing faces to vary between different windows
-displaying the same buffer.
+displaying the same buffer.  See the Info node "Face Remapping" of the
+Emacs Lisp Reference manual for more detail.
 
 +++
 ** New function assoc-delete-all.
diff --git a/lisp/files.el b/lisp/files.el
index 3921040fa9b..c4a68d04407 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -2031,19 +2031,19 @@ think it does, because \"free\" is pretty hard to define in practice."
                   (x-popup-dialog t `(,prompt
                                       ("Yes" . ?y)
                                       ("No" . ?n)
-                                      ("Open in raw mode" . ?r)))
+                                      ("Open literally" . ?l)))
                 (read-char-choice
-                 (concat prompt " (y)es or (n)o or (r)aw ")
-                 '(?y ?Y ?n ?N ?r ?R)))))
+                 (concat prompt " (y)es or (n)o or (l)iterally ")
+                 '(?y ?Y ?n ?N ?l ?L)))))
         (cond ((memq choice '(?y ?Y)) nil)
-              ((memq choice '(?r ?R)) 'raw)
+              ((memq choice '(?l ?L)) 'raw)
               (t 'abort))))))
 
 (defun abort-if-file-too-large (size op-type filename &optional offer-raw)
   "If file SIZE larger than `large-file-warning-threshold', allow user to abort.
 OP-TYPE specifies the file operation being performed (for message
 to user).  If OFFER-RAW is true, give user the additional option
-to open the file in raw mode. If the user chooses this option,
+to open the file literally. If the user chooses this option,
 `abort-if-file-too-large' returns the symbol `raw'. Otherwise, it
 returns nil or exits non-locally."
   (let ((choice (and large-file-warning-threshold size
diff --git a/src/xfaces.c b/src/xfaces.c
index 265581cca88..31aa14b7102 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -2193,7 +2193,7 @@ merge_named_face (struct window *w,
    (:window PARAMETER VALUE), which matches if the current window has
    a PARAMETER EQ to VALUE.
 
-   This function returns true if the face filter matches and false if
+   This function returns true if the face filter matches, and false if
    it doesn't or if the function encountered an error.  If the filter
    is invalid, set *OK to false and, if ERR_MSGS is true, log an error
    message.  On success, *OK is untouched.  */
@@ -2247,12 +2247,12 @@ evaluate_face_filter (Lisp_Object filter, struct window *w,
 
 /* Determine whether FACE_REF is a "filter" face specification (case
    #4 in merge_face_ref).  If it is, evaluate the filter, and if the
-   filter matches, return the filtered expression.  If the filter does
+   filter matches, return the filtered face spec.  If the filter does
    not match, return `nil'.  If FACE_REF is not a filtered face
    specification, return FACE_REF.
 
    On error, set *OK to false, having logged an error message if
-   ERR_MSGS is true, and return `nil'.
+   ERR_MSGS is true, and return `nil'.  Otherwise, *OK is not touched.
 
    W is either NULL or a window used to evaluate filters.  If W is
    NULL, no window-based face specification filter matches.
@@ -2319,7 +2319,7 @@ filter_face_ref (Lisp_Object face_ref,
    for compatibility with 20.2.
 
    4. Conses of the form
-   (:filter (:window PARAMETER VALUE) FACE-SPECIFICATION),
+   (:filtered (:window PARAMETER VALUE) FACE-SPECIFICATION),
    which applies FACE-SPECIFICATION only if the
    given face attributes are being evaluated in the context of a
    window with a parameter named PARAMETER being EQ VALUE.