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.

1 files changed, 4 insertions, 4 deletions

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.