[Emacs-diffs] master 0a6a2fb: Improve documentation of several recent changes

[Eli Zaretskii]

branch: master
commit 0a6a2fb1d0b02a5ac442cf6b344e35696aac7eb7
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/emacs/files.texi     |  5 ++++-
 doc/lispref/display.texi |  8 +++++++-
 doc/lispref/frames.texi  |  8 ++++++--
 doc/lispref/text.texi    | 17 +++++++++++++++++
 etc/NEWS                 | 10 +++++++++-
 lisp/files.el            | 10 +++++-----
 src/xfaces.c             |  8 ++++----
 7 files changed, 52 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 7043bdc..f902bae 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 ce7ec3a..0ba7f0f 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
address@hidden@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 address@hidden
+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 5e8b5b4..6678644 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
 
address@hidden 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 bb6ab04..ea9c824 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.
+
address@hidden
+A cons cell of the form @address@hidden(:filtered @var{filter}
address@hidden)}}, 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
address@hidden should be of the form @address@hidden(:window @var{param}
address@hidden)}}, which matches for windows whose parameter @var{param}
+is @code{eq} to @var{value}.  If the variable
address@hidden is address@hidden, 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
 
address@hidden face-filters-always-match
+If this variable is address@hidden, face filters that specify
+attributes applied only when certain conditions are met will be deemed
+to match always.
address@hidden defvar
+
 @node Format Properties
 @subsection Formatted Text Properties
 
diff --git a/etc/NEWS b/etc/NEWS
index e89402d..cecd3f8 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 3921040..c4a68d0 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 265581c..31aa14b 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.