Commit 8f68449c authored by Glenn Morris's avatar Glenn Morris

Merge from origin/emacs-26

0b810ebc Fix a typo in char-width-table
3f00db7c Minor update in admin/notes/unicode
bcd0115e Fix lisp indent infloop on unfinished strings (Bug#37045)
5f992d19 Improve commentary in composite.el
3a04be20 ; Improve commentary in xdisp.c
15de1d11 Fix markup in dired-x.texi
bda7fc75 ; Fix typo in a doc string of speedbar.el
6f57ef9d * src/callproc.c (Fcall_process): Doc fix.

# Conflicts:
#	doc/misc/dired-x.texi
#	lisp/international/characters.el
#	src/callproc.c
parents 65dc07f5 0b810ebc
......@@ -62,6 +62,9 @@ of OTF script tags in otf-script-alist, whose source is on this page:
https://docs.microsoft.com/en-us/typography/opentype/spec/scripttags
Other databases in fontset.el might also need to be updated as needed.
One notable place to check is the function setup-default-fontset,
where new scripts will generally need some addition, most probably to
the list of "simple" scripts (search for "Simple").
The function 'ucs-names', defined in lisp/international/mule-cmds.el,
might need to be updated because it knows about used and unused ranges
......
......@@ -126,7 +126,7 @@ original @file{dired-x.el}).
@node Features
@section Features
@cindex Features
@cindex Dired-x features
Some features provided by Dired Extra:
......@@ -158,7 +158,7 @@ respectively (@pxref{Find File At Point}).
@node Technical Details
@section Technical Details
@cindex Modified functions
@cindex modified functions
@cindex @file{dired-aux.el}
When @file{dired-x.el} is loaded, some standard Dired functions from
......@@ -213,7 +213,7 @@ when you first type @kbd{C-x d}).
@node Optional Installation Dired Jump
@section Optional Installation Dired Jump
@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window}
@cindex autoloading @code{dired-jump} and @code{dired-jump-other-window}
In order to have @code{dired-jump} and @code{dired-jump-other-window}
(@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and
......@@ -234,7 +234,7 @@ for these functions. In your @file{.emacs} file put
@node Optional Installation File At Point
@section Optional Installation File At Point
@cindex Binding @code{dired-x-find-file}
@cindex binding @code{dired-x-find-file}
If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over
@code{find-file} (@pxref{Find File At Point}), then you will need to set
@code{dired-x-hands-off-my-keys}. To do this, either set it
......@@ -253,8 +253,8 @@ or call @code{dired-x-bind-find-file} after changing the value.
@node Omitting Files in Dired
@chapter Omitting Files in Dired
@cindex Omitting Files in Dired
@cindex Uninteresting files
@cindex omitting Files in Dired
@cindex uninteresting files
@dfn{Omitting} a file means removing it from the directory listing. Omitting
is useful for keeping Dired buffers free of ``uninteresting'' files (for
instance, auto-save, auxiliary, backup, and revision control files) so that
......@@ -309,18 +309,13 @@ inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate
@node Omitting Variables
@section Omitting Variables
@cindex Customizing file omitting
@cindex customizing file omitting
The following variables can be used to customize omitting.
@table @code
@vindex dired-omit-mode
@item dired-omit-mode
Default: @code{nil}
@cindex How to make omitting the default in Dired
@cindex how to make omitting the default in Dired
@defvar dired-omit-mode
If non-@code{nil}, ``uninteresting'' files are not listed.
The default is @code{nil}.
Uninteresting files are files whose names match regexp
@code{dired-omit-files}, plus files whose names end with extension in
@code{dired-omit-extensions}. @kbd{C-x M-o} (@code{dired-omit-mode})
......@@ -346,56 +341,49 @@ a directory local setting
@noindent
to a @file{.dir-locals.el} file in that directory. You can use the
command @code{add-dir-local-variable} to do this.
@end defvar
@vindex dired-omit-files
@item dired-omit-files
Default: @code{"^#\\|\\.$"}
Files whose names match this buffer-local regexp will not be displayed.
This only has effect when @code{dired-omit-mode}'s value is @code{t}.
@defvar dired-omit-files
This buffer-local variable's value is a regexp, a string. Files whose
names match this regexp will not be displayed. This only has effect
when @code{dired-omit-mode}'s value is @code{t}.
The default value omits the special directories @file{.} and @file{..} and
autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}).
@vindex dired-omit-extensions
@item dired-omit-extensions
Default: The elements of @code{completion-ignored-extensions},
@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions}
and @code{dired-texinfo-unclean-extensions}.
If non-@code{nil}, a list of extensions (strings) to omit from Dired listings.
Its format is the same as that of @code{completion-ignored-extensions}.
@vindex dired-omit-case-fold
@item dired-omit-case-fold
@end defvar
@defvar dired-omit-extensions
If non-@code{nil}, this variable's value is a list of extensions
(strings) to omit from Dired listings. Its format is the same as that
of @code{completion-ignored-extensions}. The default value is the
elements of @code{completion-ignored-extensions},
@code{dired-latex-unclean-extensions},
@code{dired-bibtex-unclean-extensions} and
@code{dired-texinfo-unclean-extensions}.
@end defvar
@defvar dired-omit-case-fold
Default: @code{filesystem}
This variable controls whether file-name matching is case-insensitive.
By default, when @code{dired-omit-case-fold} is set to @code{filesystem},
@code{dired-omit-mode} will match filenames and extensions
case-sensitively on Dired buffers visiting case-sensitive filesystems,
and case-insensitively on case-insensitive filesystems. Set it to
@code{nil} to be always case-sensitive, and to @code{t} to be always
case-insensitive.
@vindex dired-omit-localp
@item dired-omit-localp
Default: @code{no-dir}
The @var{localp} argument @code{dired-omit-expunge} passes to
@code{dired-get-filename}. If it is @code{no-dir}, omitting is much faster,
but you can only match against the non-directory part of the file name. Set it
to @code{nil} if you need to match the whole file name or @code{t} to match the
file name relative to the buffer's top-level directory.
@item dired-omit-marker-char
@vindex dired-omit-marker-char
@cindex Omitting additional files
Default: @kbd{C-o}
@end defvar
@defvar dired-omit-localp
This variable determines the @var{localp} argument
@code{dired-omit-expunge} passes to @code{dired-get-filename}. If it
is @code{no-dir}, teh default, omitting is much faster, but you can
only match against the non-directory part of the file name. Set it to
@code{nil} if you need to match the whole file name or @code{t} to
match the file name relative to the buffer's top-level directory.
@end defvar
@cindex omitting additional files
@defvar dired-omit-marker-char
Temporary marker used by Dired to implement omitting. Should never be used
as marker by the user or other packages. There is one exception to this rule:
by adding
......@@ -411,8 +399,8 @@ to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a
@kbd{C-o} marker, thus causing these files to be omitted in addition to the
usually omitted files. Unfortunately the files you omitted manually this way
will show up again after reverting the buffer, unlike the others.
@end table
The default value is @kbd{C-o}.
@end defvar
@node Omitting Examples
@section Examples of Omitting Various File Types
......@@ -421,7 +409,7 @@ will show up again after reverting the buffer, unlike the others.
@item
@cindex RCS files, how to omit them in Dired
@cindex Omitting RCS files in Dired
@cindex omitting RCS files in Dired
If you wish to avoid seeing RCS files and the @file{RCS} directory, then put
@example
......@@ -437,8 +425,8 @@ in the @code{dired-load-hook} (@pxref{Installation}). This assumes
@code{^} in the regexp.
@item
@cindex Tib files, how to omit them in Dired
@cindex Omitting tib files in Dired
@cindex tib files, how to omit them in Dired
@cindex omitting tib files in Dired
If you use @code{tib}, the bibliography program for use with @TeX{} and
@LaTeX{}, and you
want to omit the @file{INDEX} and the @file{*-t.tex} files, then put
......@@ -452,8 +440,8 @@ want to omit the @file{INDEX} and the @file{*-t.tex} files, then put
in the @code{dired-load-hook} (@pxref{Installation}).
@item
@cindex Dot files, how to omit them in Dired
@cindex Omitting dot files in Dired
@cindex dot files, how to omit them in Dired
@cindex omitting dot files in Dired
If you do not wish to see @samp{dot} files (files starting with a @file{.}),
then put
......@@ -479,7 +467,7 @@ in your @code{dired-mode-hook}.
@node Shell Command Guessing
@chapter Shell Command Guessing
@cindex Guessing shell commands for files.
@cindex guessing shell commands for files.
Based upon the name of a file, Dired tries to guess what shell
command you might want to apply to it. For example, if you have point
......@@ -496,19 +484,22 @@ file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
Dired only tries to guess a command for a single file, never for a list
of marked files.
@table @code
@item dired-guess-shell-alist-default
@vindex dired-guess-shell-alist-default
Predefined rules for shell commands. Set this to @code{nil} to turn guessing off.
The elements of @code{dired-guess-shell-alist-user} (defined by the
user) will override these rules.
@item dired-guess-shell-alist-user
@vindex dired-guess-shell-alist-user
If non-@code{nil}, a user-defined alist of file regexps and their suggested
commands. These rules take precedence over the predefined rules in the
variable @code{dired-guess-shell-alist-default} (to which they are prepended)
when @code{dired-do-shell-command} is run).
The following variables control guessing of shell commands:
@defvar dired-guess-shell-alist-default
This variable specifies the predefined rules for guessing shell
commands suitable for certain files. Set this to @code{nil} to turn
guessing off. The elements of @code{dired-guess-shell-alist-user}
(defined by the user) will override these rules.
@end defvar
@defvar dired-guess-shell-alist-user
If non-@code{nil}, this variables specifies the user-defined alist of
file regexps and their suggested commands. These rules take
precedence over the predefined rules in the variable
@code{dired-guess-shell-alist-default} (to which they are prepended)
when @code{dired-do-shell-command} is run). The default is
@code{nil}.
Each element of the alist looks like
......@@ -541,54 +532,50 @@ to add rules for @samp{.foo} and @samp{.bar} file extensions, write
@noindent
This will override any predefined rules for the same extensions.
@end defvar
@item dired-guess-shell-case-fold-search
@vindex dired-guess-shell-case-fold-search
Default: @code{t}
Non-@code{nil} means @code{dired-guess-shell-alist-default} and
@defvar dired-guess-shell-case-fold-search
If this variable is non-@code{nil},
@code{dired-guess-shell-alist-default} and
@code{dired-guess-shell-alist-user} are matched case-insensitively.
The default is @code{t}.
@end defvar
@cindex passing GNU Tar its @samp{z} switch.
@defvar dired-guess-shell-gnutar
If this variable is non-@code{nil}, it specifies the name of the GNU
Tar executable (e.g., @file{tar} or @file{gnutar}). GNU Tar's
@samp{z} switch is used for compressed archives. If you don't have
GNU Tar, set this to @code{nil}: a pipe using @command{zcat} is then
used instead. The default is @code{nil}.
@end defvar
@item dired-guess-shell-gnutar
@vindex dired-guess-shell-gnutar
@cindex Passing GNU Tar its @samp{z} switch.
Default: @code{nil}
If non-@code{nil}, this is the name of the GNU Tar executable (e.g.,
@samp{tar} or @samp{gnutar}). GNU Tar's @samp{z} switch is used for
compressed tar files.
If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is
then used.
@item dired-guess-shell-gzip-quiet
@vindex dired-guess-shell-gzip-quiet
@cindex @code{gzip}
Default: @code{t}
A non-@code{nil} value means that @samp{-q} is passed to @code{gzip}
overriding a verbose option in the @env{GZIP} environment variable.
@defvar dired-guess-shell-gzip-quiet
A non-@code{nil} value of this variable means that @samp{-q} is passed
to @command{gzip}, possibly overriding a verbose option in the @env{GZIP}
environment variable. The default is @code{t}.
@end defvar
@item dired-guess-shell-znew-switches nil
@vindex dired-guess-shell-znew-switches
@cindex @code{znew}
Default: @code{nil}
A string of switches passed to @code{znew}. An example is
@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is
smaller than the @file{.gz} file.
@item dired-shell-command-history nil
@vindex dired-shell-command-history
History list for commands that read dired-shell commands.
@end table
@defvar dired-guess-shell-znew-switches nil
This variable specifies a string of switches passed to @command{znew}.
An example is @samp{-K} which will make @command{znew} keep a @file{.Z}
file when it is smaller than the @file{.gz} file. The default is
@code{nil}: no additional switches are passed to @command{znew}.
@end defvar
@defvar dired-shell-command-history nil
This variable holds the history list for commands that read
dired-shell commands.
@end defvar
@node Virtual Dired
@chapter Virtual Dired
@cindex Virtual Dired
@cindex Perusing @code{ls} listings
@cindex @code{ls} listings, how to peruse them in Dired
@cindex virtual Dired
@cindex perusing @code{ls} listings
@cindex @command{ls} listings, how to peruse them in Dired
Using @dfn{Virtual Dired} means putting a buffer with Dired-like
contents in Dired mode. The files described by the buffer contents need
not actually exist. This is useful if you want to peruse an @samp{ls -lR}
......@@ -630,8 +617,8 @@ local-variable files.
@table @kbd
@item F
@kindex F
@cindex Visiting several files at once
@cindex Simultaneous visiting of several files
@cindex visiting several files at once
@cindex simultaneous visiting of several files
@findex dired-do-find-marked-files
(@code{dired-do-find-marked-files}) Find all marked files at once displaying
them simultaneously. If optional @var{noselect} is non-@code{nil} then just
......@@ -719,41 +706,36 @@ and @file{*.dvi} files for deletion.
@node Advanced Cleaning Variables
@section Advanced Cleaning Variables
@noindent Variables used by the above cleaning commands (and in the default value for
variable @code{dired-omit-extensions}, @pxref{Omitting Variables})
@table @code
@item dired-patch-unclean-extensions
@vindex dired-patch-unclean-extensions
Default: @code{(".rej" ".orig")}
List of extensions of dispensable files created by the @samp{patch} program.
@item dired-tex-unclean-extensions
@vindex dired-tex-unclean-extensions
Default: @code{(".toc" ".log" ".aux")}
List of extensions of dispensable files created by @TeX{}.
@item dired-texinfo-unclean-extensions
@vindex dired-texinfo-unclean-extensions
Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"}
@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}
List of extensions of dispensable files created by @samp{texinfo}.
@item dired-latex-unclean-extensions
@vindex dired-latex-unclean-extensions
Default: @code{(".idx" ".lof" ".lot" ".glo")}
List of extensions of dispensable files created by @LaTeX{}.
@item dired-bibtex-unclean-extensions
@vindex dired-bibtex-unclean-extensions
Default: @code{(".blg" ".bbl")}
List of extensions of dispensable files created by Bib@TeX{}.
@end table
Variables used by the above cleaning commands (and in the default value for
variable @code{dired-omit-extensions}, @pxref{Omitting Variables}):
@defvar dired-patch-unclean-extensions
This variable specifies the list of extensions of dispensable files
created by the @samp{patch} program. The default is @w{@code{(".rej"
".orig")}}.
@end defvar
@defvar dired-tex-unclean-extensions
This variable specifies the list of extensions of dispensable files
created by @TeX{}. The default is @w{@code{(".toc" ".log" ".aux")}}.
@end defvar
@defvar dired-texinfo-unclean-extensions
This variable holds the list of extensions of dispensable files
created by @samp{texinfo}. The default is @w{@code{(".cp" ".cps" ".fn"
".fns" ".ky" ".kys"} @code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}}
@end defvar
@defvar dired-latex-unclean-extensions
This variable specifies the list of extensions of dispensable files
created by @LaTeX{}. The default is @w{@code{(".idx" ".lof" ".lot"
".glo")}}.
@end defvar
@defvar dired-bibtex-unclean-extensions
This variable specifies the list of extensions of dispensable files
created by Bib@TeX{}. The default is @w{@code{(".blg" ".bbl")}}.
@end defvar
@node Special Marking Function
@section Special Marking Function
......@@ -762,10 +744,11 @@ List of extensions of dispensable files created by Bib@TeX{}.
@item M-(
@kindex M-(
@findex dired-mark-sexp
@cindex Lisp expression, marking files with in Dired
@cindex Mark file by Lisp expression
(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns
non-@code{nil}. With a prefix argument, unflag those files instead.
@cindex lisp expression, marking files with in Dired
@cindex mark file by Lisp expression
Mark files for which @var{predicate} returns non-@code{nil}
(@code{dired-mark-sexp}). With a prefix argument, unflag those files
instead.
The @var{predicate} is a Lisp expression that can refer to the following
symbols:
......@@ -814,8 +797,8 @@ to mark all @file{.el} files without a corresponding @file{.elc} file.
@node Multiple Dired Directories
@chapter Multiple Dired Directories and Non-Dired Commands
@cindex Multiple Dired directories
@cindex Working directory
@cindex multiple Dired directories
@cindex working directory
An Emacs buffer can have but one working directory, stored in the
buffer-local variable @code{default-directory}. A Dired buffer may have
several subdirectories inserted, but it still has only one working
......@@ -833,8 +816,8 @@ Dired buffers, is like @code{shell-command}, but it runs with
@node Find File At Point
@chapter Find File At Point
@cindex Visiting a file mentioned in a buffer
@cindex Finding a file at point
@cindex visiting a file mentioned in a buffer
@cindex finding a file at point
@file{dired-x} provides a method of visiting or editing a file mentioned in
the buffer you are viewing (e.g., a mail buffer, a news article, a
......@@ -942,7 +925,7 @@ inserted subdirectories.
@item dired-jump
@findex dired-jump
@kindex C-x C-j
@cindex Jumping to Dired listing containing file.
@cindex jumping to Dired listing containing file.
Bound to @kbd{C-x C-j}. Jump back to Dired: If in a file, edit the current
directory and move to file's line. If in Dired already, pop up a level and
go to old directory's line. In case the proper Dired file line cannot be
......@@ -962,7 +945,7 @@ bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to
@kbd{C-x 4 C-j}.
@item dired-vm
@cindex Reading mail.
@cindex reading mail.
@kindex V
@findex dired-vm
Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}. Run VM on this
......@@ -982,14 +965,14 @@ If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound
to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound.
@item dired-rmail
@cindex Reading mail.
@cindex reading mail.
@findex dired-rmail
Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this
file (assumed to be mail folder in Rmail format).
@item dired-info
@kindex I
@cindex Running info.
@cindex running info.
@findex dired-info
Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info
format).
......@@ -999,7 +982,7 @@ If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
not be bound to @kbd{I}.
@item dired-man
@cindex Running man.
@cindex running man.
@kindex N
@findex dired-man
Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff}
......@@ -1010,7 +993,7 @@ If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
be bound to @kbd{N}.
@item dired-do-relsymlink
@cindex Relative symbolic links.
@cindex relative symbolic links.
@kindex Y
@findex dired-do-relsymlink
Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a
......@@ -1039,7 +1022,7 @@ info.
@node Bugs
@chapter Bugs
@cindex Bugs
@cindex bugs
@noindent
If you encounter a bug in this package, or wish to suggest an
......
......@@ -555,6 +555,11 @@ All non-spacing characters have this function in
;; This sequence doesn't start with a proper base character.
((memq (get-char-code-property (lgstring-char gstring 0)
'general-category)
;; "Improper" base characters are of the following general
;; categories:
;; Mark (nonspacing, combining, enclosing)
;; Separator (space, line, paragraph)
;; Other (control, format, surrogate)
'(Mn Mc Me Zs Zl Zp Cc Cf Cs))
nil)
......@@ -647,6 +652,7 @@ All non-spacing characters have this function in
de (+ de yoff)))
((and (= class 0)
(eq (get-char-code-property (lglyph-char glyph)
;; Me = enclosing mark
'general-category) 'Me))
;; Artificially laying out glyphs in an enclosing
;; mark is difficult. All we can do is to adjust
......@@ -772,7 +778,8 @@ prepending a space before it."
'general-category)
'Cf)
(progn
;; Compose by replacing with a space.
;; Compose Cf (format) control characters by
;; replacing with a space.
(lglyph-set-char glyph 32)
(lglyph-set-width glyph 1)
(setq i (1+ i)))
......
......@@ -822,7 +822,7 @@ by more than one line to cross a string literal."
(setq last-sexp (nth 2 ppss)))
(setq depth (car ppss))
;; Skip over newlines within strings.
(nth 3 ppss))
(and (not (eobp)) (nth 3 ppss)))
(let ((string-start (nth 8 ppss)))
(setq ppss (parse-partial-sexp (point) (point-max)
nil nil ppss 'syntax-table))
......@@ -838,17 +838,22 @@ by more than one line to cross a string literal."
indent-stack)))))
(prog1
(let (indent)
(cond ((= (forward-line 1) 1) nil)
;; Negative depth, probably some kind of syntax error.
(cond ((= (forward-line 1) 1)
;; Can't move to the next line, apparently end of buffer.
nil)
((null indent-stack)
;; Reset state.
;; Negative depth, probably some kind of syntax
;; error. Reset the state.
(setq ppss (parse-partial-sexp (point) (point))))
((car indent-stack))
((integerp (setq indent (calculate-lisp-indent ppss)))
(setf (car indent-stack) indent))
((consp indent) ; (COLUMN CONTAINING-SEXP-START)
(car indent))
;; This only happens if we're in a string.
;; This only happens if we're in a string, but the
;; loop should always skip over strings (unless we hit
;; end of buffer, which is taken care of by the first
;; clause).
(t (error "This shouldn't happen"))))
(setf (lisp-indent-state-stack state) indent-stack)
(setf (lisp-indent-state-ppss-point state) ppss-point)
......
......@@ -986,7 +986,7 @@ with L, LRE, or LRO Unicode bidi character type.")
(#x1039 . #x103A)
(#x103D . #x103E)
(#x1058 . #x1059)
(#x105E . #x1160)
(#x105E . #x1060)
(#x1071 . #x1074)
(#x1082 . #x1082)
(#x1085 . #x1086)
......
......@@ -697,7 +697,7 @@ singular expression. This variable will be turned into
function `speedbar-add-supported-extension' to add a new extension at
runtime, or use the configuration dialog to set it in your init file.
If you add an extension to this list, and it does not appear, you may
need to also modify `completion-ignored-extension' which will also help
need to also modify `completion-ignored-extensions' which will also help
file completion."
:group 'speedbar
:type '(repeat (regexp :tag "Extension Regexp"))
......
......@@ -220,7 +220,7 @@ DEFUN ("call-process", Fcall_process, Scall_process, 1, MANY, 0,
doc: /* Call PROGRAM synchronously in separate process.
The remaining arguments are optional.
The program's input comes from file INFILE (nil means `/dev/null').
The program's input comes from file INFILE (nil means `null-device').
If you want to make the input come from an Emacs buffer, use
`call-process-region' instead.
......
......@@ -152,6 +152,8 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
description of the environment in which the text is to be
displayed. But this is too early, read on.
Iteration over buffer and strings.
Characters and pixmaps displayed for a range of buffer text depend
on various settings of buffers and windows, on overlays and text
properties, on display tables, on selective display. The good news
......@@ -176,6 +178,46 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
current X and Y position, and lots of other stuff you can better
see in dispextern.h.
The "stop position".
Some of the fields maintained by the iterator change relatively
infrequently. These include the face of the characters, whether
text is invisible, the object (buffer or display or overlay string)
being iterated, character composition info, etc. For any given
buffer or string position, these sources of information that
affects the display can be determined by calling the appropriate
primitives, such as Fnext_single_property_change, but both these
calls and the processing of their return values is relatively
expensive. To optimize redisplay, the display engine checks these
sources of display information only when needed. To that end, it
always maintains the position of the next place where it must stop
and re-examine all those potential sources. This is called "stop
position" and is stored in the stop_charpos field of the iterator.
The stop position is updated by compute_stop_pos, which is called
whenever the iteration reaches the current stop position and
processes it. Processing a stop position is done by handle_stop,
which invokes a series of handlers, one each for every potential
source of display-related information; see the it_props array for
those handlers. For example, one handler is handle_face_prop,
which detects changes in face properties, and supplies the face ID
that the iterator will use for all the glyphs it generates up to
the next stop position; this face ID is the result of realizing the
face specified by the relevant text properties at this position.
Each handler called by handle_stop processes the sources of display
information for which it is "responsible", and returns a value
which tells handle_stop what to do next.
Once handle_stop returns, the information it stores in the iterator
fields will not be refreshed until the iteration reaches the next
stop position, which is computed by compute_stop_pos called at the
end of handle_stop. compute_stop_pos examines the buffer's or
string's interval tree to determine where the text properties
change, finds the next position where overlays and character
composition can change, and stores in stop_charpos the closest
position where any of these factors should be reconsider.
Producing glyphs.