Commit 0a6a2fb1 authored by Eli Zaretskii's avatar Eli Zaretskii

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

* 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
* lisp/files.el (files--ask-user-about-large-file): Use
"literally" instead of "raw", for consistency with

* doc/lispref/frames.texi (Input Focus): Tell explicitly that
focus-change events are sometimes supported on TTY frames.
parent 2461266b
......@@ -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
......@@ -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
......@@ -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
......@@ -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
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
......@@ -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.
......@@ -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)))
(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
......@@ -2193,7 +2193,7 @@ merge_named_face (struct window *w,
(:window PARAMETER VALUE), which matches if the current window has
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
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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment