Block atimers while loading native code

.dir-locals.el

@@ -21,9 +21,6 @@
                (electric-quote-comment . nil)
                (electric-quote-string . nil)
 	       (mode . bug-reference-prog)))
- (c-ts-mode . ((c-ts-mode-indent-style . gnu)
-               (indent-tabs-mode . t)
-               (mode . bug-reference-prog)))
  (log-edit-mode . ((log-edit-font-lock-gnu-style . t)
                    (log-edit-setup-add-author . t)
 		   (vc-git-log-edit-summary-target-len . 50)))

CONTRIBUTE

@@ -18,7 +18,7 @@ To configure Git for Emacs development, you can run the following:
 
 The following shell commands then build and run Emacs from scratch:
 
-	git clone https://git.savannah.gnu.org/git/emacs.git
+	git clone git://git.sv.gnu.org/emacs.git
 	cd emacs
 	./autogen.sh
 	./configure
@@ -110,7 +110,7 @@ admin/notes/bug-triage.
 
 Any change that matters to end-users should have an entry in etc/NEWS.
 Try to start each NEWS entry with a sentence that summarizes the entry
-and takes just one line -- this will allow reading NEWS in Outline
+and takes just one line -- this will allow to read NEWS in Outline
 mode after hiding the body of each entry.
 
 Doc-strings should be updated together with the code.
@@ -123,7 +123,7 @@ Think about whether your change requires updating the manuals.  If you
 know it does not, mark the NEWS entry with "---".  If you know
 that *all* the necessary documentation updates have been made as part
 of your changes or those by others, mark the entry with "+++".
-Otherwise, do not mark it.
+Otherwise do not mark it.
 
 If your change requires updating the manuals to document new
 functions/commands/variables/faces, then use the proper Texinfo
@@ -321,7 +321,7 @@ them right the first time, so here are guidelines for formatting them:
 ** Committing your changes.
 
 When you commit changes, Git invokes several scripts that test the
-commit for validity, and may abort the commit if some of the tests
+commit for validity, and may abort the commit of some of the tests
 fail.  These scripts live in the '.git/hooks/' subdirectory of the
 top-level directory of the repository, and they perform the following
 tests:
@@ -400,7 +400,7 @@ the commit to master, by starting the commit message with "Backport:".
 The gitmerge function excludes these commits from the merge to the master.
 
 Some changes should not be merged to master at all, for whatever
-reason.  These should be marked by including something like "Do not
+reasons.  These should be marked by including something like "Do not
 merge to master" or anything that matches gitmerge-skip-regexp (see
 admin/gitmerge.el) in the commit message.
 
@@ -449,8 +449,8 @@ files intended for use only with Emacs version 24.5 and later.
 
 *** Useful files in the admin/ directory
 
-See all the files in 'admin/notes/*'.  In particular, see
-'admin/notes/newfile' and 'admin/notes/repo'.
+See all the files in admin/notes/* .  In particular, see
+admin/notes/newfile, see admin/notes/repo.
 
 The file admin/MAINTAINERS records the areas of interest of frequent
 Emacs contributors.  If you are making changes in one of the files

ChangeLog.2

@@ -111,7 +111,7 @@
 
 2017-03-21  Noam Postavsky  <npostavs@gmail.com>
 
-	Narrow scope of modification hook re-enabling in org-src fontification
+	Narrow scope of modification hook renabling in org-src fontification
 
 	Modification hooks should be enabled while modifying text in the
 	org-src temp buffer, but in 2017-01-29 "Call modification hooks in

ChangeLog.3

@@ -1,431 +1,3 @@
-2022-02-18  Stefan Kangas  <stefankangas@gmail.com>
-
-	* Version 28.3 released.
-
-2023-02-17  Stefan Kangas  <stefankangas@gmail.com>
-
-	Update HISTORY for Emacs 28.3
-
-2023-02-17  Stefan Kangas  <stefankangas@gmail.com>
-
-	Bump Emacs version to 28.3
-
-	* README:
-	* configure.ac:
-	* msdos/sed2v2.inp:
-	* nt/README.W32: Bump Emacs version to 28.3.
-
-2023-02-17  Stefan Kangas  <stefankangas@gmail.com>
-
-	Update NEWS for Emacs 28.3
-
-	* etc/NEWS: Update for Emacs 28.3.
-
-2023-02-17  Stefan Kangas  <stefankangas@gmail.com>
-
-	Update ChangeLog and AUTHORS for Emacs 28.3
-
-	* ChangeLog.3:
-	* etc/AUTHORS: Update for Emacs 28.3.
-
-2023-02-17  Xi Lu  <lx@shellcodes.org>
-
-	Fix etags local command injection vulnerability
-
-	* lib-src/etags.c: (escape_shell_arg_string): New function.
-	(process_file_name): Use it to quote file names passed to the
-	shell.  (Bug#59817)
-
-	(cherry picked from commit 01a4035c869b91c153af9a9132c87adb7669ea1c)
-
-2023-02-17  Xi Lu  <lx@shellcodes.org>
-
-	Fixed ctags local command execute vulnerability
-
-	* lib-src/etags.c:
-
-	(clean_matched_file_tag): New function
-	(do_move_file): New function
-	(readline_internal):
-	Add `leave_cr` parameter, if true, include the \r character
-
-	* test/manual/etags/CTAGS.good_crlf: New file
-	* test/manual/etags/CTAGS.good_update: New file
-	* test/manual/etags/crlf: New file
-	* test/manual/etags/Makefile: Add `ctags -u` test cases
-
-	(cherry picked from commit d48bb4874bc6cd3e69c7a15fc3c91cc141025c51)
-
-2023-02-17  Xi Lu  <lx@shellcodes.org>
-
-	Fix ruby-mode.el local command injection vulnerability (bug#60268)
-
-	* lisp/progmodes/ruby-mode.el
-	(ruby-find-library-file): Fix local command injection vulnerability.
-
-	(cherry picked from commit 9a3b08061feea14d6f37685ca1ab8801758bfd1c)
-
-2023-02-17  Xi Lu  <lx@shellcodes.org>
-
-	Fix htmlfontify.el command injection vulnerability.
-
-	* lisp/htmlfontify.el (hfy-text-p): Fix command injection
-	vulnerability.  (Bug#60295)
-
-	(cherry picked from commit 1b4dc4691c1f87fc970fbe568b43869a15ad0d4c)
-
-2022-12-19  Eli Zaretskii  <eliz@gnu.org>
-
-	Fix storing email into nnmail by Gnus
-
-	Backporting suggested by Florian Weimer, since this is
-	a denial-of-service issue.
-	* lisp/gnus/nnml.el (nnml--encode-headers): Wrap
-	'rfc2047-encode-string' calls with 'ignore-errors', to avoid
-	disrupting email workflows due to possibly-invalid headers.
-	Reported by Florian Weimer <fweimer@redhat.com>.
-
-	(cherry picked from commit 23f7c9c2a92e4619b7c4d2286d4249f812cd695d)
-
-2022-11-14  Robert Pluim  <rpluim@gmail.com>
-
-	Explain how to bind keys to non-ASCII sequences
-
-	* doc/emacs/custom.texi (Init Rebinding): Explain how to use `kbd'
-	when binding keys to non-ASCII sequences.
-
-2022-11-12  Eli Zaretskii  <eliz@gnu.org>
-
-	Document that 'transient-mark-mode' is off in batch mode
-
-	* doc/emacs/mark.texi (Mark, Disabled Transient Mark): Document,
-	belatedly, that 'transient-mark-mode' is turned on by default only
-	in interactive sessions.  (Bug#59201)
-
-2022-10-14  Eli Zaretskii  <eliz@gnu.org>
-
-	Document how to control where the *.eln files are written
-
-	* doc/lispref/compile.texi (Native Compilation): Document the
-	trick of pointing $HOME to a non-existent directory.
-	(Native-Compilation Variables): Document the role of
-	'native-comp-eln-load-path' in determining where *.eln files are
-	written.
-
-2022-10-14  Robert Pluim  <rpluim@gmail.com>
-
-	Add cross-reference to alternative syntaxes for Unicode
-
-	These alternative syntaxes allow you to specify Unicode codepoints
-	using only ASCII, which helps avoid decoding issues.
-
-	* doc/emacs/custom.texi (Init Non-ASCII): Add cross reference to
-	"General Escape Syntax" in the Emacs Lisp Reference Manual.
-
-2022-10-07  Lars Ingebrigtsen  <larsi@gnus.org>
-
-	Update name of hs-mouse-toggle-hiding in Emacs manual
-
-	* doc/emacs/programs.texi (Hideshow): Update the name of
-	hs-mouse-toggle-hiding (bug#58331).
-
-2022-10-06  Stefan Kangas  <stefankangas@gmail.com>
-
-	Fix typo in `(emacs) Lisp Doc'
-
-	* doc/emacs/programs.texi (Lisp Doc): Fix reference to
-	'eldoc-echo-area-display-truncation-message'.  (Bug#58324)
-
-2022-10-06  Stefan Kangas  <stefankangas@gmail.com>
-
-	Fix references to 'default-indent-new-line'
-
-	* doc/emacs/programs.texi (Comment Commands)
-	(Multi-Line Comments): Fix references to
-	'default-indent-new-line'.  (Bug#58325)
-
-2022-10-04  Andreas Schwab  <schwab@linux-m68k.org>
-
-	* src/emacs.c (load_pdump): Propery handle case when executable
-	wasn't found.
-
-2022-10-04  Eli Zaretskii  <eliz@gnu.org>
-
-	Avoid assertion violations in STRING_CHAR
-
-	* src/xdisp.c (handle_composition_prop):
-	* src/editfns.c (styled_format): Don't call 'STRING_CHAR' on
-	unibyte strings.  This avoids assertion violation in
-	'string_char_and_length'.
-
-	(cherry picked from commit d52d6e1e106117eb4bba81a65e256e2e793037b6)
-
-2022-10-03  Stefan Kangas  <stefankangas@gmail.com>
-
-	Fix documentation  of 'TAB' in cc-mode
-
-	* doc/emacs/programs.texi (C Indent): Fix documentation of 'TAB'
-	in cc-mode.  (Bug#58258)
-
-2022-10-03  Stefan Kangas  <stefankangas@gmail.com>
-
-	Fix 'org-export-dispatch' command name in manual
-
-	* doc/emacs/text.texi (Org Authoring): Fix 'org-export-dispatch'
-	command name.  (Bug#58260)
-
-2022-10-02  Andreas Schwab  <schwab@linux-m68k.org>
-
-	* src/emacs.c (load_pdump): Fix use of xpalloc.
-
-2022-10-02  Eli Zaretskii  <eliz@gnu.org>
-
-	Avoid assertion violation in 'xpalloc'
-
-	* src/emacs.c (load_pdump): Ensure the 3rd argument of xpalloc is
-	always positive.  (Bug#58232)
-
-2022-09-30  Michael Albinus  <michael.albinus@gmx.de>
-
-	Fix connection property incompatibility in Tramp
-
-	* lisp/net/tramp.el (tramp-get-remote-tmpdir): Remove obsolete
-	connection property "tmpdir".  (Bug#57800)
-
-2022-09-29  Lars Ingebrigtsen  <larsi@gnus.org>
-
-	Update some Gnus documentation in the Emacs manual
-
-	* doc/emacs/misc.texi (Gnus Group Buffer, Gnus Summary Buffer):
-	Update documentation (bug#58145).
-
-2022-09-28  Eli Zaretskii  <eliz@gnu.org>
-
-	Clarify image file search
-
-	* doc/lispref/display.texi (Defining Images, Image Descriptors):
-	* lisp/image.el (create-image): Clarify that non-absolute image
-	files are searched along 'image-load-path'.  (Bug#52931)
-
-2022-09-28  Stefan Kangas  <stefankangas@gmail.com>
-
-	.mailcap: Some additional fixes.
-
-2022-09-28  Eli Zaretskii  <eliz@gnu.org>
-
-	Avoid assertion violations in 'pop_it'
-
-	* src/xdisp.c (pop_it): Avoid assertion violations when handling
-	lists or vectors of display properties.  (Bug#58122)
-
-2022-09-28  Stefan Kangas  <stefankangas@gmail.com>
-
-	Add .mailmap for proper git log output
-
-	This file is used to fix a few misspelled names in various git
-	listings (e.g., "git log").  This can be used to fix incorrect
-	attribution, poor display, or names showing up more than once.
-	It also allows updating an old email addresses to a new one.
-	See "man git-shortlog" for more information on the format.
-
-	* .mailmap: New file.
-
-2022-09-27  Stefan Kangas  <stefankangas@gmail.com>
-
-	* doc/emacs/ack.texi (Acknowledgments): Update maintainers.
-
-2022-09-24  Stefan Monnier  <monnier@iro.umontreal.ca>
-
-	* lisp/progmodes/hideshow.el (hs-toggle-hiding): Fix `interactive` form
-
-	This fixes the first part of bug#52092, which is a regression
-	introduced by commit d0e9113de97.
-
-2022-09-23  YAMAMOTO Mitsuharu  <mituharu@math.s.chiba-u.ac.jp>
-
-	Fix shaping with bitmap-only fonts on HarfBuzz 5.2.0 (Bug#57976)
-
-	* src/ftcrfont.c (ftcrhbfont_begin_hb_font): Undo last change for
-	HarfBuzz 5.2.0.
-
-2022-09-20  Stefan Monnier  <monnier@iro.umontreal.ca>
-
-	* lisp/text-modes/tex-mode.el (tex-mode): Fix AUCTeX regression
-
-	As discussed in
-	https://lists.gnu.org/r/auctex/2022-08/msg00004.html
-	AUCTeX installs its own advice to redefine `tex-mode`, and that
-	advice used to take precedence before commit 6075a7c5ae3fa456cd.
-
-2022-09-20  Robert Pluim  <rpluim@gmail.com>
-
-	Add vc-annotate-switches to manual
-
-	* doc/emacs/maintaining.texi (Old Revisions): Add description of
-	`vc-annotate-switches' and `vc-BACKEND-annotate-switches'.
-
-2022-09-20  Robert Pluim  <rpluim@gmail.com>
-
-	Remove mention of non-existent `annotate-switches'
-
-	* lisp/vc/vc.el (vc-annotate-switches): Remove mention of
-	`annotate-switches'.  As far as I can tell this has never existed in
-	Emacs.
-
-2022-09-20  Robert Pluim  <rpluim@gmail.com>
-
-	Mention that src/macuvs.h sometimes needs committing
-
-	* admin/notes/unicode: src/macuvs.h is generated, but needs to be
-	committed sometimes.
-
-2022-09-19  Gerd Möllmann  <gerd@gnu.org>
-
-	MacOS ld warning from native compilation (bug#57849)
-
-	* lisp/emacs-lisp/comp.el (native-comp-driver-options): Add "-Wl,-w"
-	on Darwin systems.
-	* etc/NEWS: Describe change.
-
-2022-09-18  Michael Albinus  <michael.albinus@gmx.de>
-
-	Fix Tramp error with eshell integration
-
-	* lisp/net/tramp-integration.el (tramp-eshell-directory-change):
-	Respect local `default-directory'.  (Bug#57556)
-
-2022-09-17  Michael Albinus  <michael.albinus@gmx.de>
-
-	Sync with Tramp 2.5.3.2.  Don't merge with master
-
-	* doc/misc/tramp.texi (Android shell setup): Rework.
-	(Frequently Asked Questions): Improve recommendations for speeding up.
-
-	* doc/misc/trampver.texi:
-	* lisp/net/trampver.el: Change version to "2.5.4-pre".
-
-	* lisp/net/tramp-adb.el (tramp-methods): Use "%d".
-	(tramp-adb-handle-directory-files-and-attributes): Fix "." and
-	".." in listing.
-	(tramp-adb-handle-file-attributes)
-	(tramp-adb-handle-directory-files-and-attributes)
-	(tramp-adb-handle-file-name-all-completions): Pipe "ls" output
-	through "cat", in order to avoid quoting special characters.
-	(tramp-adb-maybe-open-connection): Compute args from `tramp-login-args'.
-
-	* lisp/net/tramp-compat.el (tramp-compat-replace-regexp-in-region):
-	New defalias.
-
-	* lisp/net/tramp-gvfs.el (tramp-gvfs-do-copy-or-rename-file):
-	Adapt check for proper remote command.
-
-	* lisp/net/tramp.el (tramp-methods): Adapt docstring.
-	(tramp-handle-make-process): Check for adb device if indicated.
-	(tramp-get-remote-tmpdir): Cache result in temporary connection
-	property.
-
-	* test/lisp/net/tramp-tests.el  (tramp-test17-insert-directory)
-	(tramp-test22-file-times, tramp--test-utf8): Adapt tests.
-	(tramp--test-shell-file-name): Do not depend on `tramp--test-adb-p'.
-	(tramp-test46-unload): Ignore autoload functions in
-	`tramp-file-name' structure tests, since `tramp-file-name-handler'
-	is also autoloaded in Emacs 29.
-
-2022-09-17  Stefan Kangas  <stefankangas@gmail.com>
-
-	Simplify regexp in make-news-html-file
-
-	* admin/admin.el (make-news-html-file): Simplify regexp.
-	Suggested by Mattias Engdegård <mattiase@acm.org>.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	* admin/admin.el (make-news-html-file): Set id on correct tag.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	Add version headlines to HTML NEWS export
-
-	This allows linking to, e.g. "NEWS.28.html#28.1" to go directly to
-	those release notes.
-	* admin/admin.el (admin--org-export-headers-format)
-	(make-news-html-file): Add XX.Y version headlines with an HTML anchor.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	Improve HTML export of NEWS file
-
-	* admin/admin.el (admin--org-export-headers-format)
-	(admin--org-html-postamble): New variables.
-	(admin--require-external-package): New function.
-	(make-news-html-file): Improve HTML export.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	Delete "etc/NEWS*.html" from .gitignore
-
-	We actually do want to see it when preparing a release, so that we
-	don't include it in a tarball by mistake.
-	* .gitignore: Don't ignore "etc/NEWS*.html".
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	Recommend NonGNU ELPA over MELPA
-
-	* doc/misc/org.org (Using CDLaTeX to enter math, Footnotes): Recommend
-	NonGNU ELPA over MELPA.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	Minor doc fixes in picture.el
-
-	* lisp/textmodes/picture.el: Improve Commentary.
-	(picture-forward-column, picture-backward-column)
-	(picture-move-down, picture-move-up, picture-movement-nw)
-	(picture-movement-ne, picture-movement-sw, picture-movement-se)
-	(picture-set-motion, picture-clear-line, picture-newline)
-	(picture-tab, picture-yank-rectangle)
-	(picture-yank-rectangle-from-register, picture-insert-rectangle)
-	(picture-draw-rectangle): Minor doc fixes.
-
-2022-09-16  Stefan Kangas  <stefankangas@gmail.com>
-
-	* lisp/textmodes/page-ext.el: Improve Commentary.
-
-2022-09-14  Stefan Kangas  <stefankangas@gmail.com>
-
-	Automate exporting etc/NEWS to HTML
-
-	* admin/admin.el (make-news-html-file): New function.
-	* .gitignore: Ignore generated "etc/NEWS*.html" file.
-
-2022-09-14  Eli Zaretskii  <eliz@gnu.org>
-
-	* Makefile.in (uninstall): Remove the *.eln files.  (Bug#57771)
-
-2022-09-12  Stefan Kangas  <stefankangas@gmail.com>
-
-	Update HISTORY for Emacs 28.2
-
-	* etc/HISTORY: Update for the Emacs 28.2 release.
-
-2022-09-07  Stefan Kangas  <stefankangas@gmail.com>
-
-	Bump Emacs version to 28.2
-
-	* README:
-	* configure.ac:
-	* msdos/sed2v2.inp:
-	* nt/README.W32: Bump Emacs version to 28.2.
-
-2022-09-07  Stefan Kangas  <stefankangas@gmail.com>
-
-	Update ChangeLog and AUTHORS for Emacs 28.2
-
-	* ChangeLog.3:
-	* etc/AUTHORS:
-	* etc/NEWS: Update for Emacs 28.2.
-
 2022-09-06  Stefan Kangas  <stefankangas@gmail.com>
 
 	* doc/misc/idlwave.texi (Troubleshooting): Don't say "Emacsen".
@@ -205169,7 +204741,7 @@
 
 2017-03-21  Noam Postavsky  <npostavs@gmail.com>
 
-	Narrow scope of modification hook re-enabling in org-src fontification
+	Narrow scope of modification hook renabling in org-src fontification
 
 	Modification hooks should be enabled while modifying text in the
 	org-src temp buffer, but in 2017-01-29 "Call modification hooks in
@@ -237348,7 +236920,7 @@
 
 This file records repository revisions from
 commit 9d56a21e6a696ad19ac65c4b405aeca44785884a (exclusive) to
-commit f7bd5ac55211ad0ae2e473f0dff46df1e60f99bf (inclusive).
+commit ddabb03a0176beb4b7fc8d4f2267d459fd2ebded (inclusive).
 See ChangeLog.2 for earlier changes.
 
 ;; Local Variables:

INSTALL.REPO

@@ -4,7 +4,7 @@ The Emacs repository is hosted on Savannah.  The following Git command
 will clone the repository to the 'emacs' subdirectory of the current
 directory on your local machine:
 
-    git clone https://git.savannah.gnu.org/git/emacs.git
+    git clone git://git.sv.gnu.org/emacs.git
 
 To build the repository code, simply run 'make' in the 'emacs'
 directory.  This should work if your files are freshly checked out

Makefile.in

@@ -417,9 +417,9 @@ advice-on-failure:
 
 sanity-check:
 	@[ -f .no-advice-on-failure ] && exit 0; true
-	@v=`src/emacs${EXEEXT} --batch --eval \
+	@v=$$(src/emacs${EXEEXT} --batch --eval \
 	  '(progn (defun f (n) (if (= 0 n) 1 (* n (f (- n 1))))) (princ (f 10)))' \
-	  2> /dev/null`; \
+	  2> /dev/null); \
 	[ "X$$v" = "X3628800" ] && exit 0; \
 	echo >&2 '***'; \
 	echo >&2 '*** '"\"make ${make-target}\" succeeded, but Emacs is not functional."; \
@@ -841,7 +841,7 @@ install-etc:
 	rm -f $${tmp}
 	tmp=etc/emacsclient.tmpdesktop; rm -f $${tmp}; \
 	client_name=`echo emacsclient | sed '$(TRANSFORM)'`${EXEEXT}; \
-	sed -e "/^Exec=/ s|emacsclient|${bindir}/$${client_name}|" \
+	sed -e "/^Exec=emacsclient/ s|emacsclient|${bindir}/$${client_name}|" \
 	  -e "/^Icon=emacs/ s/emacs/${EMACS_NAME}/" \
 	  $(USE_STARTUP_NOTIFICATION_SED_CMD) \
 	  ${srcdir}/etc/emacsclient.desktop > $${tmp}; \
@@ -855,7 +855,7 @@ install-etc:
 	rm -f $${tmp}
 	tmp=etc/emacsclient-mail.tmpdesktop; rm -f $${tmp}; \
 	client_name=`echo emacsclient | sed '$(TRANSFORM)'`${EXEEXT}; \
-	sed -e "/^Exec=/ s|emacsclient|${bindir}/$${client_name}|" \
+	sed -e "/^Exec=emacsclient/ s|emacsclient|${bindir}/$${client_name}|" \
 	  -e "/^Icon=emacs/ s/emacs/${EMACS_NAME}/" \
 	  ${srcdir}/etc/emacsclient-mail.desktop > $${tmp}; \
 	${INSTALL_DATA} $${tmp} "$(DESTDIR)${desktopdir}/$${client_name}-mail.desktop"; \
@@ -1030,9 +1030,6 @@ $(foreach dir,$(distclean_dirs),$(eval $(call submake_template,$(dir),distclean)
 
 distclean: $(distclean_dirs:=_distclean) clean-gsettings-schemas
 	${top_distclean}
-ifeq ($(HAVE_NATIVE_COMP),yes)
-	rm -rf native-lisp
-endif
 
 ### 'bootstrap-clean'
 ###      Delete everything that can be reconstructed by 'make' and that
@@ -1287,7 +1284,7 @@ PREFERRED_BRANCH = emacs-28
 preferred-branch-is-current:
 	git branch | grep -q '^\* $(PREFERRED_BRANCH)$$'
 unchanged-history-files:
-	x=`git diff-files --name-only $(CHANGELOG_N) $(emacslog)` && \
+	x=$$(git diff-files --name-only $(CHANGELOG_N) $(emacslog)) && \
 	  test -z "$$x"
 
 # Regular expression that matches the newest commit covered by a ChangeLog.

admin/MAINTAINERS

@@ -294,7 +294,7 @@ Po Lu
 
 Tramp
 	Maintainer: Michael Albinus
-	Repository: https://git.savannah.gnu.org/git/tramp.git
+	Repository: git://git.savannah.gnu.org/tramp.git
 	Mailing List: tramp-devel@gnu.org
 	Bug Reports: M-x tramp-bug
 	Notes: For backward compatibility requirements, see
@@ -316,7 +316,7 @@ Modus themes
 Org Mode
 	Home Page: https://orgmode.org/
 	Maintainer: Org Mode developers
-	Repository: https://git.savannah.gnu.org/git/emacs/org-mode.git
+	Repository: git://git.sv.gnu.org/emacs/org-mode.git
 	Mailing list: emacs-orgmode@gnu.org
 	Bug Reports: M-x org-submit-bug-report
 	Notes: Org Mode is maintained as a separate project that is

admin/authors.el

@@ -182,7 +182,7 @@ files.")
     ("Philip Kaludercic" "Philip K\\." "Philip K")
     ("Philipp Stephani" "Philipp .*phst@google")
     ("Piotr Zieliński" "Piotr Zielinski")
-    ("Po Lu" "Po Lu Via" "Your Name")   ; looks like a mistake
+    ("Po Lu" "Po Lu Via")               ; looks like a mistake
     ("Przemysław Wojnowski" "Przemyslaw Wojnowski")
     ("R. Bernstein" "rb@dustyfeet.com")
     ("Rainer Schöpf" "Rainer Schoepf")

admin/charsets/Makefile.in

@@ -181,7 +181,7 @@ ${charsetdir}/GB180304.map: ${charsetdir}/GB180302.map ${gb180304}
 	${AM_V_GEN}$(AWK) -f ${gb180304} < $< > $@
 
 ${charsetdir}/JISX0201.map: ${GLIBC_CHARMAPS}/JIS_X0201.gz ${mapconv} ${compact}
-	${AM_V_GEN}(${run_mapconv} $< '/^<.*[ 	]\/x[0-9]/' GLIBC-1 ${compact} && \
+	${AM_V_GEN}(${mapconv} $< '/^<.*[ 	]\/x[0-9]/' GLIBC-1 ${compact} && \
 	  echo "# Generated by hand" && \
 	  echo "0xA1-0xDF 0xFF61" ) > $@
 

admin/charsets/mapconv

@@ -38,8 +38,7 @@
 ## So that eg [A-F] as used by KANJI-DATABASE branch below works as expected.
 ## Otherwise with LANG=en_US.utf8, CNS-6.map was generated with a
 ## bogus entry.  By experiment, LC_COLLATE=C was not enough.
-LC_ALL=C
-export LC_ALL
+export LC_ALL=C
 
 BASE=`expr "$1" : '.*/\(.*\)' '|' "$1"` # basename
 FILE="admin/charsets/mapfiles/$BASE"

admin/git-bisect-start

@@ -82,7 +82,7 @@ done
 # SKIP-BRANCH 58cc931e92ece70c3e64131ee12a799d65409100
 
 ## The list below is the exhaustive list of all commits between Dec 1
-## 2016 and Feb 28 2023 on which building Emacs with the default
+## 2016 and Dec 31 2022 on which building Emacs with the default
 ## options, on a GNU/Linux computer and with GCC, fails.  It is
 ## possible (though unlikely) that building Emacs with non-default
 ## options, with other compilers, or on other platforms, would succeed
@@ -1674,49 +1674,3 @@ $REAL_GIT bisect skip $(cat $0 | grep '^# SKIP-SINGLE ' | sed 's/^# SKIP-SINGLE
 # SKIP-SINGLE 8c13e8497821881b5197a1717e9e53b9991859d0
 # SKIP-SINGLE a6db8464e150c49724c71c5969b97f205ee2dec5
 # SKIP-SINGLE cfbfd393b450d4eb7ac0b7922b44208688553c9e
-# SKIP-SINGLE 382e018856a884a96a94ad551dbc1d7b0317b2e5
-# SKIP-SINGLE 8360e12f0ea3a3ccf0305adab3c7ea7e38af36c1
-# SKIP-SINGLE 56e8607dc99b90c43f82001cbf073e58a4698298
-# SKIP-SINGLE 956889d8ff1c79db45ca9b1711f406961e71c272
-# SKIP-SINGLE e2e937300f5a68ce1e2a349a583859a29394ac5f
-# SKIP-SINGLE 176830fe2bb1c80ee128e515f6223cddc8b0a2ca
-# SKIP-SINGLE 3f069bd796b0024033640051b5f74ba9834985f8
-# SKIP-SINGLE 435ba92ccc4c46914c261de57f71ac6d92c20178
-# SKIP-SINGLE ad6d8f7df180a9563d3f064f29c6366f114b8de0
-# SKIP-SINGLE 8d7ad65665833ae99b7e7119dae37afa438968a4
-# SKIP-SINGLE 10032f424ccf611783f5b92742e91e70595587c4
-# SKIP-SINGLE 4b1714571c8c6cf7ae2ee2602c66b7c903c45a4a
-# SKIP-SINGLE f27a330b99eebbe7f4690163358b4cacbd4e17a1
-# SKIP-SINGLE b73539832d9c4e802925cb8f261a13473da383b3
-# SKIP-SINGLE f50cb7d7c4b37cd8e4bb1ffa5d3f9273c7e19e10
-# SKIP-SINGLE 96015c9c8cc1720e8ee7cd9cea4de48126dd9122
-# SKIP-SINGLE 2bd0b9475384adfb4dd2cc794bbe1d8621546717
-# SKIP-SINGLE d9a2673ee95cf7172a622dc0229ddf72aec8e8c1
-# SKIP-SINGLE 0116e27b26cb4a98f2de8dca12d8e9d90d222992
-# SKIP-SINGLE 96601cd90ba1b8a650d0e41dad2a58cb9e270f1b
-# SKIP-SINGLE 99e40959f4036debe099f144ed2664a38e23563d
-# SKIP-SINGLE 207a0d9408cb97b9ae78469e2487e3075ade03f8
-# SKIP-SINGLE 64fee21d5f85db465198970a4d636cb17d500f26
-# SKIP-SINGLE 48bd17923a98f49a30bdce2f3a52e03fe45d63f0
-# SKIP-SINGLE 9058601308db4892fbc3e599b83fe4326fef9886
-# SKIP-SINGLE a3003492ace0571e5179500b42bbe44cb9763dbb
-# SKIP-SINGLE 197f994384cb37ae4ae7a771815bbe565d4ae242
-# SKIP-SINGLE 1970726e26a979243925fabe32686ba2ee757c6b
-# SKIP-SINGLE 1de6ebf2878485a0ef6b778df7d6a14d5b22a01c
-# SKIP-SINGLE 013ab7e2a83afa7fb577c356ae686439a2906f34
-# SKIP-SINGLE 1c3ca3bb649b7e812a84b4a559463462d4357080
-# SKIP-SINGLE 48ed4228a75907ae1bb7a2d4314ffb3277c75e3a
-# SKIP-SINGLE b9025c507a3a7dae4de19b18cafaa09b18183832
-# SKIP-SINGLE 8d8464bd5a98598e7a6fe63370545c7f07574926
-# SKIP-SINGLE 11c4177430230ef41cb700c48afecf475cf39893
-# SKIP-SINGLE cf3c89423fabc2c5a7891a5b5465fa995e461218
-# SKIP-SINGLE 8d5d7509b0a2c248084fa349b0b188d4de4af804
-# SKIP-SINGLE b6e2799aa1c3887c2995e115e6ff2f69d59f0e44
-# SKIP-SINGLE 1795839babcf8572a79aaee3c76ca5b357937a59
-# SKIP-SINGLE abfd00e5c02ec0aed8bbac1eca0d0db1874f020a
-# SKIP-SINGLE 8aef401b4f66a64ddfa9390590fb2cae1f96d522
-# SKIP-SINGLE d5bf26f488b7968feed9f43e612a90da2aab15a8
-# SKIP-SINGLE 5d0912f1445e33f1ccf23a84f0dc6d08c4ee2b60
-# SKIP-SINGLE 95692f6754c3a8f55a90df2d6f7ce62be55cdcfc
-# SKIP-SINGLE a3edacd3f547195740304139cb68aaa94d7b18ee
-# SKIP-SINGLE ae4ff4f25fbf704446f8f38d8e818f223b79042b

admin/make-tarball.txt

@@ -68,25 +68,16 @@ General steps (for each step, check for possible errors):
       PREFERRED_BRANCH = emacs-NN
 
     where NN is the version on the release branch from which you are
-    producing the tarball.  If NN is incorrect (which it usually is
-    when starting a pretest of a new major release), update
-    Makefile.in and re-run 'configure' to update Makefile.
+    producing the tarball.  If NN is incorrect, update Makefile.in and
+    re-run 'configure' to update Makefile.
 
-    For the first pretest of a new major release, consider starting a
-    new top-level ChangeLog.N file if the last versioned ChangeLog.N
-    file is too large.  A good point to start a new ChangeLog.N file
-    is when the last one gets larger than 1.5 MiB.  If so, start a new
-    one by bumping N, and also update the line in top-level
-    Makefile.in which says
+    If the versioned ChangeLog.N file is too large, start a new one
+    by bumping N, and also update the line in top-level Makefile.in
+    which says
 
       CHANGELOG_HISTORY_INDEX_MAX = N
 
     by incrementing the value of N by 1; then regenerate Makefile.
-    After bumping N, you need to actually create and commit
-    ChangeLog.N with the updated N, otherwise "M-x authors" below will
-    fail.  The easiest way of creating the new ChangeLog.N is to
-    rename the file ChangeLog (without the .N suffix) left over from
-    the last major release (it is usually unversioned) and commit it.
 
     Now:
 
@@ -108,12 +99,11 @@ General steps (for each step, check for possible errors):
     the relevant entry.  If a file was deleted or renamed, consider
     adding an appropriate entry to variables authors-ignored-files,
     authors-valid-file-names, or authors-renamed-files-alist in
-    authors.el.  If some authors are "ignored", consider adding
-    entries to the author-aliases variable.
+    authors.el.
 
     If necessary, repeat 'C-u M-x authors' after making those changes.
     Save the "*Authors*" buffer as etc/AUTHORS.
-    Check the diff looks reasonable.  Maybe add more entries to
+    Check the diff looks reasonable.  Maybe add entries to
     authors-ambiguous-files or authors-aliases, and repeat.
     Commit any fixes to authors.el.
 
@@ -160,11 +150,10 @@ General steps (for each step, check for possible errors):
 4.    autoreconf -i -I m4 --force
       make bootstrap
 
-    The below script checks for any mistakes in the source text of
-    manual pages.  Fix any errors and re-run the script to verify.
-
       ./admin/check-man-pages
 
+    The above script checks for any mistakes in the source text of
+    manual pages.  Fix any errors and re-run the script to verify.
     Then do this:
 
       make -C etc/refcards
@@ -179,13 +168,7 @@ General steps (for each step, check for possible errors):
     messages from TeX, but those seem to be harmless, as the result
     looks just fine.)
 
-5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.  After copying, edit
-    ldefs-boot.el to add
-
-    ;; no-byte-compile: t
-
-    to its file-local variables section, otherwise make-dist will
-    complain.
+5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
 
     Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the files
     changed by M-x set-version.  Note that the set-version changes

admin/merge-gnulib

@@ -23,10 +23,10 @@
 
 # written by Paul Eggert
 
-GNULIB_URL=https://git.savannah.gnu.org/git/gnulib.git
+GNULIB_URL=git://git.savannah.gnu.org/gnulib.git
 
 GNULIB_MODULES='
-  alignasof alloca-opt binary-io byteswap c-ctype c-strcase
+  alloca-opt binary-io byteswap c-ctype c-strcase
   canonicalize-lgpl
   careadlinkat close-stream copy-file-range
   count-leading-zeros count-one-bits count-trailing-zeros
@@ -44,9 +44,9 @@ GNULIB_MODULES='
   nanosleep nproc nstrftime
   pathmax pipe2 pselect pthread_sigmask
   qcopy-acl readlink readlinkat regex
-  sig2str sigdescr_np socklen stat-time std-gnu11 stdbool stddef stdio
+  sig2str sigdescr_np socklen stat-time std-gnu11 stdalign stdbool stddef stdio
   stpcpy strnlen strtoimax symlink sys_stat sys_time
-  tempname time-h time_r time_rz timegm timer-time timespec-add timespec-sub
+  tempname time time_r time_rz timegm timer-time timespec-add timespec-sub
   update-copyright unlocked-io utimensat
   vla warnings
 '

admin/notes/elpa

@@ -3,7 +3,7 @@ NOTES ON THE EMACS PACKAGE ARCHIVE
 The GNU Emacs package archive, at elpa.gnu.org, is managed using a Git
 repository named "elpa", hosted on Savannah.  To check it out:
 
-  git clone https://git.savannah.gnu.org/git/emacs/elpa
+  git clone git://git.sv.gnu.org/emacs/elpa
   cd elpa
   make setup
 

admin/notes/emba

@@ -83,46 +83,6 @@ Lisp packages, Makefiles, scripts, and other software could determine
 whether they run on emba by checking for the environment variable
 EMACS_EMBA_CI.
 
-* Running Emba tests locally
-
-As usual in GitLab, the tests run in containers, which could be
-applied also locally.  Unfortunately, the Emba container registry,
-emba.gnu.org:5050, is not accessible publicly.  Instead, the container
-images must be build locally.  Change the current directory to a
-recent Emacs branch, and apply the command
-
-  docker build --target emacs-inotify --tag emacs-inotify \
-    -f test/infra/Dockerfile.emba .
-
-This creates the Debian-based image emacs-inotify, based on the
-instructions in the file Dockerfile.emba.  This image is good for the
-majority of tests.  However, there are also other image build
-instructions like emacs-filenotify-gio, emacs-eglot, emacs-gnustep and
-emacs-native-comp-speed{0,1,2}.  Use the appropriate one.
-
-The image contains a directory "/checkout", which is a copy of your
-local Emacs git repository.  Emacs has been built in this directory
-via "make bootstrap".  In order to use the image, start a container
-like
-
-  docker run --interactive --env EMACS_EMBA_CI=1 --name emacs-inotify \
-    emacs-inotify /bin/sh -i
-
-In this container, change the current directory to "/checkout".  Now
-you can apply all commands known for Emacs, like
-
-  cd /checkout
-  make -C test files-tests.log
-
-While this container runs, you can also access its filesystem from
-your local Emacs via Tramp.  For example, in order to see the result
-of the above test run, open the log file in your local Emacs with
-
-  C-x C-f /docker:emacs-inotify:/checkout/test/lisp/files-tests.log
-
-Note: On local Red Hat-based systems, use "podman" instead of "docker"
-in the shell commands and Tramp file names.
-
 
 This file is part of GNU Emacs.
 

admin/notes/tree-sitter/build-module/README

@@ -0,0 +1,17 @@
+To build the language definition for a particular language, run
+
+    ./build.sh <language>
+
+eg,
+
+    ./build.sh html
+
+The dynamic module will be in /dist directory
+
+To build all modules at once, run
+
+    ./batch.sh
+
+This gives you C, JSON, Go, HTML, Javascript, CSS, Python, Typescript
+(tsx), C# (csharp), C++ (cpp), Rust. More can be added to batch.sh
+unless it's directory structure is not standard.

admin/notes/tree-sitter/build-module/batch.sh

@@ -8,10 +8,8 @@ languages=(
     'css'
     'c-sharp'
     'dockerfile'
-    'elixir'
     'go'
     'go-mod'
-    'heex'
     'html'
     'javascript'
     'json'

admin/notes/tree-sitter/build-module/build.sh

@@ -3,17 +3,12 @@
 lang=$1
 topdir="$PWD"
 
-case $(uname) in
-    "Darwin")
-        soext="dylib"
-        ;;
-    *"MINGW"*)
-        soext="dll"
-        ;;
-    *)
-        soext="so"
-        ;;
-esac
+if [ $(uname) == "Darwin" ]
+then
+    soext="dylib"
+else
+    soext="so"
+fi
 
 echo "Building ${lang}"
 
@@ -31,17 +26,11 @@ case "${lang}" in
     "cmake")
         org="uyha"
         ;;
-    "elixir")
-        org="elixir-lang"
-        ;;
     "go-mod")
         # The parser is called "gomod".
         lang="gomod"
         org="camdencheek"
         ;;
-    "heex")
-        org="phoenixframework"
-        ;;
     "typescript")
         sourcedir="tree-sitter-typescript/typescript/src"
         grammardir="tree-sitter-typescript/typescript"

admin/notes/tree-sitter/html-manual/Accessing-Node.html

@@ -0,0 +1,205 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Accessing Node (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Accessing Node (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Accessing Node (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Pattern-Matching.html" rel="next" title="Pattern Matching">
+<link href="Retrieving-Node.html" rel="prev" title="Retrieving Node">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Accessing-Node">
+<div class="header">
+<p>
+Next: <a href="Pattern-Matching.html" accesskey="n" rel="next">Pattern Matching Tree-sitter Nodes</a>, Previous: <a href="Retrieving-Node.html" accesskey="p" rel="prev">Retrieving Node</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Accessing-Node-Information"></span><h3 class="section">37.4 Accessing Node Information</h3>
+
+<p>Before going further, make sure you have read the basic conventions
+about tree-sitter nodes in the previous node.
+</p>
+<span id="Basic-information"></span><h3 class="heading">Basic information</h3>
+
+<p>Every node is associated with a parser, and that parser is associated
+with a buffer.  The following functions let you retrieve them.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dnode_002dparser"><span class="category">Function: </span><span><strong>treesit-node-parser</strong> <em>node</em><a href='#index-treesit_002dnode_002dparser' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns <var>node</var>&rsquo;s associated parser.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dbuffer"><span class="category">Function: </span><span><strong>treesit-node-buffer</strong> <em>node</em><a href='#index-treesit_002dnode_002dbuffer' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated buffer.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dlanguage"><span class="category">Function: </span><span><strong>treesit-node-language</strong> <em>node</em><a href='#index-treesit_002dnode_002dlanguage' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns <var>node</var>&rsquo;s parser&rsquo;s associated language.
+</p></dd></dl>
+
+<p>Each node represents a piece of text in the buffer.  Functions below
+finds relevant information about that text.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dnode_002dstart"><span class="category">Function: </span><span><strong>treesit-node-start</strong> <em>node</em><a href='#index-treesit_002dnode_002dstart' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Return the start position of <var>node</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dend"><span class="category">Function: </span><span><strong>treesit-node-end</strong> <em>node</em><a href='#index-treesit_002dnode_002dend' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Return the end position of <var>node</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dtext"><span class="category">Function: </span><span><strong>treesit-node-text</strong> <em>node &amp;optional object</em><a href='#index-treesit_002dnode_002dtext' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Returns the buffer text that <var>node</var> represents.  (If <var>node</var> is
+retrieved from parsing a string, it will be text from that string.)
+</p></dd></dl>
+
+<p>Here are some basic checks on tree-sitter nodes.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dnode_002dp"><span class="category">Function: </span><span><strong>treesit-node-p</strong> <em>object</em><a href='#index-treesit_002dnode_002dp' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Checks if <var>object</var> is a tree-sitter syntax node.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002deq"><span class="category">Function: </span><span><strong>treesit-node-eq</strong> <em>node1 node2</em><a href='#index-treesit_002dnode_002deq' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Checks if <var>node1</var> and <var>node2</var> are the same node in a syntax
+tree.
+</p></dd></dl>
+
+<span id="Property-information"></span><h3 class="heading">Property information</h3>
+
+<p>In general, nodes in a concrete syntax tree fall into two categories:
+<em>named nodes</em> and <em>anonymous nodes</em>.  Whether a node is named
+or anonymous is determined by the language definition
+(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p>
+<span id="index-tree_002dsitter-missing-node"></span>
+<p>Apart from being named/anonymous, a node can have other properties.  A
+node can be &ldquo;missing&rdquo;: missing nodes are inserted by the parser in
+order to recover from certain kinds of syntax errors, i.e., something
+should probably be there according to the grammar, but not there.
+</p>
+<span id="index-tree_002dsitter-extra-node"></span>
+<p>A node can be &ldquo;extra&rdquo;: extra nodes represent things like comments,
+which can appear anywhere in the text.
+</p>
+<span id="index-tree_002dsitter-node-that-has-changes"></span>
+<p>A node &ldquo;has changes&rdquo; if the buffer changed since when the node is
+retrieved, i.e., outdated.
+</p>
+<span id="index-tree_002dsitter-node-that-has-error"></span>
+<p>A node &ldquo;has error&rdquo; if the text it spans contains a syntax error.  It
+can be the node itself has an error, or one of its
+children/grandchildren... has an error.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dnode_002dcheck"><span class="category">Function: </span><span><strong>treesit-node-check</strong> <em>node property</em><a href='#index-treesit_002dnode_002dcheck' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function checks if <var>node</var> has <var>property</var>.  <var>property</var>
+can be <code>'named</code>, <code>'missing</code>, <code>'extra</code>,
+<code>'has-changes</code>, or <code>'has-error</code>.
+</p></dd></dl>
+
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dtype"><span class="category">Function: </span><span><strong>treesit-node-type</strong> <em>node</em><a href='#index-treesit_002dnode_002dtype' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Named nodes have &ldquo;types&rdquo; (see <a href="Language-Definitions.html#tree_002dsitter-node-type">node type</a>).
+For example, a named node can be a <code>string_literal</code> node, where
+<code>string_literal</code> is its type.
+</p>
+<p>This function returns <var>node</var>&rsquo;s type as a string.
+</p></dd></dl>
+
+<span id="Information-as-a-child-or-parent"></span><h3 class="heading">Information as a child or parent</h3>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dindex"><span class="category">Function: </span><span><strong>treesit-node-index</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnode_002dindex' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the index of <var>node</var> as a child node of its
+parent.  If <var>named</var> is non-nil, it only count named nodes
+(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-node-field-name</strong> <em>node</em><a href='#index-treesit_002dnode_002dfield_002dname' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>A child of a parent node could have a field name (see <a href="Language-Definitions.html#tree_002dsitter-node-field-name">field name</a>).  This function returns the field name
+of <var>node</var> as a child of its parent.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dfield_002dname_002dfor_002dchild"><span class="category">Function: </span><span><strong>treesit-node-field-name-for-child</strong> <em>node n</em><a href='#index-treesit_002dnode_002dfield_002dname_002dfor_002dchild' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the field name of the <var>n</var>&rsquo;th child of
+<var>node</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dchild_002dcount"><span class="category">Function: </span><span><strong>treesit-node-child-count</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dchild_002dcount' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the number of children of <var>node</var>.  If
+<var>named</var> is non-nil, it only counts named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p></dd></dl>
+
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>, Previous: <a href="Retrieving-Node.html">Retrieving Node</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Language-Definitions.html

@@ -0,0 +1,401 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Language Definitions (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Language Definitions (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Language Definitions (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Using-Parser.html" rel="next" title="Using Parser">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Language-Definitions">
+<div class="header">
+<p>
+Next: <a href="Using-Parser.html" accesskey="n" rel="next">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Tree_002dsitter-Language-Definitions"></span><h3 class="section">37.1 Tree-sitter Language Definitions</h3>
+<span id="index-language-definitions_002c-for-tree_002dsitter"></span>
+
+<span id="Loading-a-language-definition"></span><h3 class="heading">Loading a language definition</h3>
+<span id="index-loading-language-definition-for-tree_002dsitter"></span>
+
+<span id="index-language-argument_002c-for-tree_002dsitter"></span>
+<p>Tree-sitter relies on language definitions to parse text in that
+language.  In Emacs, a language definition is represented by a symbol.
+For example, the C language definition is represented as the symbol
+<code>c</code>, and <code>c</code> can be passed to tree-sitter functions as the
+<var>language</var> argument.
+</p>
+<span id="index-treesit_002dextra_002dload_002dpath"></span>
+<span id="index-treesit_002dload_002dlanguage_002derror"></span>
+<span id="index-treesit_002dload_002dsuffixes"></span>
+<p>Tree-sitter language definitions are distributed as dynamic libraries.
+In order to use a language definition in Emacs, you need to make sure
+that the dynamic library is installed on the system.  Emacs looks for
+language definitions in several places, in the following order:
+</p>
+<ul>
+<li> first, in the list of directories specified by the variable
+<code>treesit-extra-load-path</code>;
+</li><li> then, in the <samp>tree-sitter</samp> subdirectory of the directory
+specified by <code>user-emacs-directory</code> (see <a href="Init-File.html">The Init File</a>);
+</li><li> and finally, in the system&rsquo;s default locations for dynamic libraries.
+</li></ul>
+
+<p>In each of these directories, Emacs looks for a file with file-name
+extensions specified by the variable <code>dynamic-library-suffixes</code>.
+</p>
+<p>If Emacs cannot find the library or has problems loading it, Emacs
+signals the <code>treesit-load-language-error</code> error.  The data of
+that signal could be one of the following:
+</p>
+<dl compact="compact">
+<dt><span><code>(not-found <var>error-msg</var> &hellip;)</code></span></dt>
+<dd><p>This means that Emacs could not find the language definition library.
+</p></dd>
+<dt><span><code>(symbol-error <var>error-msg</var>)</code></span></dt>
+<dd><p>This means that Emacs could not find in the library the expected function
+that every language definition library should export.
+</p></dd>
+<dt><span><code>(version-mismatch <var>error-msg</var>)</code></span></dt>
+<dd><p>This means that the version of language definition library is incompatible
+with that of the tree-sitter library.
+</p></dd>
+</dl>
+
+<p>In all of these cases, <var>error-msg</var> might provide additional
+details about the failure.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dlanguage_002davailable_002dp"><span class="category">Function: </span><span><strong>treesit-language-available-p</strong> <em>language &amp;optional detail</em><a href='#index-treesit_002dlanguage_002davailable_002dp' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns non-<code>nil</code> if the language definitions for
+<var>language</var> exist and can be loaded.
+</p>
+<p>If <var>detail</var> is non-<code>nil</code>, return <code>(t . nil)</code> when
+<var>language</var> is available, and <code>(nil . <var>data</var>)</code> when it&rsquo;s
+unavailable.  <var>data</var> is the signal data of
+<code>treesit-load-language-error</code>.
+</p></dd></dl>
+
+<span id="index-treesit_002dload_002dname_002doverride_002dlist"></span>
+<p>By convention, the file name of the dynamic library for <var>language</var> is
+<samp>libtree-sitter-<var>language</var>.<var>ext</var></samp>, where <var>ext</var> is the
+system-specific extension for dynamic libraries.  Also by convention,
+the function provided by that library is named
+<code>tree_sitter_<var>language</var></code>.  If a language definition library
+doesn&rsquo;t follow this convention, you should add an entry
+</p>
+<div class="example">
+<pre class="example">(<var>language</var> <var>library-base-name</var> <var>function-name</var>)
+</pre></div>
+
+<p>to the list in the variable <code>treesit-load-name-override-list</code>, where
+<var>library-base-name</var> is the basename of the dynamic library&rsquo;s file name,
+(usually, <samp>libtree-sitter-<var>language</var></samp>), and
+<var>function-name</var> is the function provided by the library
+(usually, <code>tree_sitter_<var>language</var></code>).  For example,
+</p>
+<div class="example">
+<pre class="example">(cool-lang &quot;libtree-sitter-coool&quot; &quot;tree_sitter_cooool&quot;)
+</pre></div>
+
+<p>for a language that considers itself too &ldquo;cool&rdquo; to abide by
+conventions.
+</p>
+<span id="index-language_002ddefinition-version_002c-compatibility"></span>
+<dl class="def">
+<dt id="index-treesit_002dlanguage_002dversion"><span class="category">Function: </span><span><strong>treesit-language-version</strong> <em>&amp;optional min-compatible</em><a href='#index-treesit_002dlanguage_002dversion' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the version of the language-definition
+Application Binary Interface (<acronym>ABI</acronym>) supported by the
+tree-sitter library.  By default, it returns the latest ABI version
+supported by the library, but if <var>min-compatible</var> is
+non-<code>nil</code>, it returns the oldest ABI version which the library
+still can support.  Language definition libraries must be built for
+ABI versions between the oldest and the latest versions supported by
+the tree-sitter library, otherwise the library will be unable to load
+them.
+</p></dd></dl>
+
+<span id="Concrete-syntax-tree"></span><h3 class="heading">Concrete syntax tree</h3>
+<span id="index-syntax-tree_002c-concrete"></span>
+
+<p>A syntax tree is what a parser generates.  In a syntax tree, each node
+represents a piece of text, and is connected to each other by a
+parent-child relationship.  For example, if the source text is
+</p>
+<div class="example">
+<pre class="example">1 + 2
+</pre></div>
+
+<p>its syntax tree could be
+</p>
+<div class="example">
+<pre class="example">                  +--------------+
+                  | root &quot;1 + 2&quot; |
+                  +--------------+
+                         |
+        +--------------------------------+
+        |       expression &quot;1 + 2&quot;       |
+        +--------------------------------+
+           |             |            |
++------------+   +--------------+   +------------+
+| number &quot;1&quot; |   | operator &quot;+&quot; |   | number &quot;2&quot; |
++------------+   +--------------+   +------------+
+</pre></div>
+
+<p>We can also represent it as an s-expression:
+</p>
+<div class="example">
+<pre class="example">(root (expression (number) (operator) (number)))
+</pre></div>
+
+<span id="Node-types"></span><h4 class="subheading">Node types</h4>
+<span id="index-node-types_002c-in-a-syntax-tree"></span>
+
+<span id="index-type-of-node_002c-tree_002dsitter"></span>
+<span id="tree_002dsitter-node-type"></span><span id="index-named-node_002c-tree_002dsitter"></span>
+<span id="tree_002dsitter-named-node"></span><span id="index-anonymous-node_002c-tree_002dsitter"></span>
+<p>Names like <code>root</code>, <code>expression</code>, <code>number</code>, and
+<code>operator</code> specify the <em>type</em> of the nodes.  However, not all
+nodes in a syntax tree have a type.  Nodes that don&rsquo;t have a type are
+known as <em>anonymous nodes</em>, and nodes with a type are <em>named
+nodes</em>.  Anonymous nodes are tokens with fixed spellings, including
+punctuation characters like bracket &lsquo;<samp>]</samp>&rsquo;, and keywords like
+<code>return</code>.
+</p>
+<span id="Field-names"></span><h4 class="subheading">Field names</h4>
+
+<span id="index-field-name_002c-tree_002dsitter"></span>
+<span id="index-tree_002dsitter-node-field-name"></span>
+<span id="tree_002dsitter-node-field-name"></span><p>To make the syntax tree easier to analyze, many language definitions
+assign <em>field names</em> to child nodes.  For example, a
+<code>function_definition</code> node could have a <code>declarator</code> and a
+<code>body</code>:
+</p>
+<div class="example">
+<pre class="example">(function_definition
+ declarator: (declaration)
+ body: (compound_statement))
+</pre></div>
+
+<span id="Exploring-the-syntax-tree"></span><h3 class="heading">Exploring the syntax tree</h3>
+<span id="index-explore-tree_002dsitter-syntax-tree"></span>
+<span id="index-inspection-of-tree_002dsitter-parse-tree-nodes"></span>
+
+<p>To aid in understanding the syntax of a language and in debugging of
+Lisp program that use the syntax tree, Emacs provides an &ldquo;explore&rdquo;
+mode, which displays the syntax tree of the source in the current
+buffer in real time.  Emacs also comes with an &ldquo;inspect mode&rdquo;, which
+displays information of the nodes at point in the mode-line.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dexplore_002dmode"><span class="category">Command: </span><span><strong>treesit-explore-mode</strong><a href='#index-treesit_002dexplore_002dmode' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This mode pops up a window displaying the syntax tree of the source in
+the current buffer.  Selecting text in the source buffer highlights
+the corresponding nodes in the syntax tree display.  Clicking
+on nodes in the syntax tree highlights the corresponding text in the
+source buffer.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dinspect_002dmode"><span class="category">Command: </span><span><strong>treesit-inspect-mode</strong><a href='#index-treesit_002dinspect_002dmode' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This minor mode displays on the mode-line the node that <em>starts</em>
+at point.  For example, the mode-line can display
+</p>
+<div class="example">
+<pre class="example"><var>parent</var> <var>field</var>: (<var>node</var> (<var>child</var> (&hellip;)))
+</pre></div>
+
+<p>where <var>node</var>, <var>child</var>, etc., are nodes which begin at point.
+<var>parent</var> is the parent of <var>node</var>.  <var>node</var> is displayed in
+a bold typeface.  <var>field-name</var>s are field names of <var>node</var> and
+of <var>child</var>, etc.
+</p>
+<p>If no node starts at point, i.e., point is in the middle of a node,
+then the mode line displays the earliest node that spans point, and
+its immediate parent.
+</p>
+<p>This minor mode doesn&rsquo;t create parsers on its own.  It uses the first
+parser in <code>(treesit-parser-list)</code> (see <a href="Using-Parser.html">Using Tree-sitter Parser</a>).
+</p></dd></dl>
+
+<span id="Reading-the-grammar-definition"></span><h3 class="heading">Reading the grammar definition</h3>
+<span id="index-reading-grammar-definition_002c-tree_002dsitter"></span>
+
+<p>Authors of language definitions define the <em>grammar</em> of a
+programming language, which determines how a parser constructs a
+concrete syntax tree out of the program text.  In order to use the
+syntax tree effectively, you need to consult the <em>grammar file</em>.
+</p>
+<p>The grammar file is usually <samp>grammar.js</samp> in a language
+definition&rsquo;s project repository.  The link to a language definition&rsquo;s
+home page can be found on
+<a href="https://tree-sitter.github.io/tree-sitter">tree-sitter&rsquo;s
+homepage</a>.
+</p>
+<p>The grammar definition is written in JavaScript.  For example, the
+rule matching a <code>function_definition</code> node looks like
+</p>
+<div class="example">
+<pre class="example">function_definition: $ =&gt; seq(
+  $.declaration_specifiers,
+  field('declarator', $.declaration),
+  field('body', $.compound_statement)
+)
+</pre></div>
+
+<p>The rules are represented by functions that take a single argument
+<var>$</var>, representing the whole grammar.  The function itself is
+constructed by other functions: the <code>seq</code> function puts together
+a sequence of children; the <code>field</code> function annotates a child
+with a field name.  If we write the above definition in the so-called
+<em>Backus-Naur Form</em> (<acronym>BNF</acronym>) syntax, it would look like
+</p>
+<div class="example">
+<pre class="example">function_definition :=
+  &lt;declaration_specifiers&gt; &lt;declaration&gt; &lt;compound_statement&gt;
+</pre></div>
+
+<p>and the node returned by the parser would look like
+</p>
+<div class="example">
+<pre class="example">(function_definition
+  (declaration_specifier)
+  declarator: (declaration)
+  body: (compound_statement))
+</pre></div>
+
+<p>Below is a list of functions that one can see in a grammar definition.
+Each function takes other rules as arguments and returns a new rule.
+</p>
+<dl compact="compact">
+<dt><span><code>seq(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
+<dd><p>matches each rule one after another.
+</p></dd>
+<dt><span><code>choice(<var>rule1</var>, <var>rule2</var>, &hellip;)</code></span></dt>
+<dd><p>matches one of the rules in its arguments.
+</p></dd>
+<dt><span><code>repeat(<var>rule</var>)</code></span></dt>
+<dd><p>matches <var>rule</var> for <em>zero or more</em> times.
+This is like the &lsquo;<samp>*</samp>&rsquo; operator in regular expressions.
+</p></dd>
+<dt><span><code>repeat1(<var>rule</var>)</code></span></dt>
+<dd><p>matches <var>rule</var> for <em>one or more</em> times.
+This is like the &lsquo;<samp>+</samp>&rsquo; operator in regular expressions.
+</p></dd>
+<dt><span><code>optional(<var>rule</var>)</code></span></dt>
+<dd><p>matches <var>rule</var> for <em>zero or one</em> time.
+This is like the &lsquo;<samp>?</samp>&rsquo; operator in regular expressions.
+</p></dd>
+<dt><span><code>field(<var>name</var>, <var>rule</var>)</code></span></dt>
+<dd><p>assigns field name <var>name</var> to the child node matched by <var>rule</var>.
+</p></dd>
+<dt><span><code>alias(<var>rule</var>, <var>alias</var>)</code></span></dt>
+<dd><p>makes nodes matched by <var>rule</var> appear as <var>alias</var> in the syntax
+tree generated by the parser.  For example,
+</p>
+<div class="example">
+<pre class="example">alias(preprocessor_call_exp, call_expression)
+</pre></div>
+
+<p>makes any node matched by <code>preprocessor_call_exp</code> appear as
+<code>call_expression</code>.
+</p></dd>
+</dl>
+
+<p>Below are grammar functions of lesser importance for reading a
+language definition.
+</p>
+<dl compact="compact">
+<dt><span><code>token(<var>rule</var>)</code></span></dt>
+<dd><p>marks <var>rule</var> to produce a single leaf node.  That is, instead of
+generating a parent node with individual child nodes under it,
+everything is combined into a single leaf node.  See <a href="Retrieving-Nodes.html">Retrieving Nodes</a>.
+</p></dd>
+<dt><span><code>token.immediate(<var>rule</var>)</code></span></dt>
+<dd><p>Normally, grammar rules ignore preceding whitespace; this
+changes <var>rule</var> to match only when there is no preceding
+whitespaces.
+</p></dd>
+<dt><span><code>prec(<var>n</var>, <var>rule</var>)</code></span></dt>
+<dd><p>gives <var>rule</var> the level-<var>n</var> precedence.
+</p></dd>
+<dt><span><code>prec.left([<var>n</var>,] <var>rule</var>)</code></span></dt>
+<dd><p>marks <var>rule</var> as left-associative, optionally with level <var>n</var>.
+</p></dd>
+<dt><span><code>prec.right([<var>n</var>,] <var>rule</var>)</code></span></dt>
+<dd><p>marks <var>rule</var> as right-associative, optionally with level <var>n</var>.
+</p></dd>
+<dt><span><code>prec.dynamic(<var>n</var>, <var>rule</var>)</code></span></dt>
+<dd><p>this is like <code>prec</code>, but the precedence is applied at runtime
+instead.
+</p></dd>
+</dl>
+
+<p>The documentation of the tree-sitter project has
+<a href="https://tree-sitter.github.io/tree-sitter/creating-parsers">more
+about writing a grammar</a>.  Read especially &ldquo;The Grammar DSL&rdquo;
+section.
+</p>
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Using-Parser.html">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Multiple-Languages.html

@@ -0,0 +1,327 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Multiple Languages (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Multiple Languages (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Multiple Languages (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Tree_002dsitter-major-modes.html" rel="next" title="Tree-sitter major modes">
+<link href="Pattern-Matching.html" rel="prev" title="Pattern Matching">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Multiple-Languages">
+<div class="header">
+<p>
+Next: <a href="Tree_002dsitter-major-modes.html" accesskey="n" rel="next">Developing major modes with tree-sitter</a>, Previous: <a href="Pattern-Matching.html" accesskey="p" rel="prev">Pattern Matching Tree-sitter Nodes</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Parsing-Text-in-Multiple-Languages"></span><h3 class="section">37.6 Parsing Text in Multiple Languages</h3>
+<span id="index-multiple-languages_002c-parsing-with-tree_002dsitter"></span>
+<span id="index-parsing-multiple-languages-with-tree_002dsitter"></span>
+<p>Sometimes, the source of a programming language could contain snippets
+of other languages; <acronym>HTML</acronym> + <acronym>CSS</acronym> + JavaScript is one
+example.  In that case, text segments written in different languages
+need to be assigned different parsers.  Traditionally, this is
+achieved by using narrowing.  While tree-sitter works with narrowing
+(see <a href="Using-Parser.html#tree_002dsitter-narrowing">narrowing</a>), the recommended way is
+instead to set regions of buffer text (i.e., ranges) in which a parser
+will operate.  This section describes functions for setting and
+getting ranges for a parser.
+</p>
+<p>Lisp programs should call <code>treesit-update-ranges</code> to make sure
+the ranges for each parser are correct before using parsers in a
+buffer, and call <code>treesit-language-at</code> to figure out the language
+responsible for the text at some position.  These two functions don&rsquo;t
+work by themselves, they need major modes to set
+<code>treesit-range-settings</code> and
+<code>treesit-language-at-point-function</code>, which do the actual work.
+These functions and variables are explained in more detail towards the
+end of the section.
+</p>
+<span id="Getting-and-setting-ranges"></span><h3 class="heading">Getting and setting ranges</h3>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dset_002dincluded_002dranges"><span class="category">Function: </span><span><strong>treesit-parser-set-included-ranges</strong> <em>parser ranges</em><a href='#index-treesit_002dparser_002dset_002dincluded_002dranges' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function sets up <var>parser</var> to operate on <var>ranges</var>.  The
+<var>parser</var> will only read the text of the specified ranges.  Each
+range in <var>ranges</var> is a list of the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->.
+</p>
+<p>The ranges in <var>ranges</var> must come in order and must not overlap.
+That is, in pseudo code:
+</p>
+<div class="example">
+<pre class="example">(cl-loop for idx from 1 to (1- (length ranges))
+         for prev = (nth (1- idx) ranges)
+         for next = (nth idx ranges)
+         should (&lt;= (car prev) (cdr prev)
+                    (car next) (cdr next)))
+</pre></div>
+
+<span id="index-treesit_002drange_002dinvalid"></span>
+<p>If <var>ranges</var> violates this constraint, or something else went
+wrong, this function signals the <code>treesit-range-invalid</code> error.
+The signal data contains a specific error message and the ranges we
+are trying to set.
+</p>
+<p>This function can also be used for disabling ranges.  If <var>ranges</var>
+is <code>nil</code>, the parser is set to parse the whole buffer.
+</p>
+<p>Example:
+</p>
+<div class="example">
+<pre class="example">(treesit-parser-set-included-ranges
+ parser '((1 . 9) (16 . 24) (24 . 25)))
+</pre></div>
+</dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dincluded_002dranges"><span class="category">Function: </span><span><strong>treesit-parser-included-ranges</strong> <em>parser</em><a href='#index-treesit_002dparser_002dincluded_002dranges' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the ranges set for <var>parser</var>.  The return
+value is the same as the <var>ranges</var> argument of
+<code>treesit-parser-included-ranges</code>: a list of cons cells of the form
+<code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->.  If <var>parser</var> doesn&rsquo;t have any
+ranges, the return value is <code>nil</code>.
+</p>
+<div class="example">
+<pre class="example">(treesit-parser-included-ranges parser)
+    &rArr; ((1 . 9) (16 . 24) (24 . 25))
+</pre></div>
+</dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dquery_002drange"><span class="category">Function: </span><span><strong>treesit-query-range</strong> <em>source query &amp;optional beg end</em><a href='#index-treesit_002dquery_002drange' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function matches <var>source</var> with <var>query</var> and returns the
+ranges of captured nodes.  The return value is a list of cons cells of
+the form <code>(<var>beg</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->, where <var>beg</var> and
+<var>end</var> specify the beginning and the end of a region of text.
+</p>
+<p>For convenience, <var>source</var> can be a language symbol, a parser, or a
+node.  If it&rsquo;s a language symbol, this function matches in the root
+node of the first parser using that language; if a parser, this
+function matches in the root node of that parser; if a node, this
+function matches in that node.
+</p>
+<p>The argument <var>query</var> is the query used to capture nodes
+(see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>).  The capture names don&rsquo;t matter.  The
+arguments <var>beg</var> and <var>end</var>, if both non-<code>nil</code>, limit the
+range in which this function queries.
+</p>
+<p>Like other query functions, this function raises the
+<code>treesit-query-error</code> error if <var>query</var> is malformed.
+</p></dd></dl>
+
+<span id="Supporting-multiple-languages-in-Lisp-programs"></span><h3 class="heading">Supporting multiple languages in Lisp programs</h3>
+
+<p>It should suffice for general Lisp programs to call the following two
+functions in order to support program sources that mixes multiple
+languages.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dupdate_002dranges"><span class="category">Function: </span><span><strong>treesit-update-ranges</strong> <em>&amp;optional beg end</em><a href='#index-treesit_002dupdate_002dranges' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function updates ranges for parsers in the buffer.  It makes sure
+the parsers&rsquo; ranges are set correctly between <var>beg</var> and <var>end</var>,
+according to <code>treesit-range-settings</code>.  If omitted, <var>beg</var>
+defaults to the beginning of the buffer, and <var>end</var> defaults to the
+end of the buffer.
+</p>
+<p>For example, fontification functions use this function before querying
+for nodes in a region.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dlanguage_002dat"><span class="category">Function: </span><span><strong>treesit-language-at</strong> <em>pos</em><a href='#index-treesit_002dlanguage_002dat' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the language of the text at buffer position
+<var>pos</var>.  Under the hood it calls
+<code>treesit-language-at-point-function</code> and returns its return
+value.  If <code>treesit-language-at-point-function</code> is <code>nil</code>,
+this function returns the language of the first parser in the returned
+value of <code>treesit-parser-list</code>.  If there is no parser in the
+buffer, it returns <code>nil</code>.
+</p></dd></dl>
+
+<span id="Supporting-multiple-languages-in-major-modes"></span><h3 class="heading">Supporting multiple languages in major modes</h3>
+
+<span id="index-host-language_002c-tree_002dsitter"></span>
+<span id="index-tree_002dsitter-host-and-embedded-languages"></span>
+<span id="index-embedded-language_002c-tree_002dsitter"></span>
+<p>Normally, in a set of languages that can be mixed together, there is a
+<em>host language</em> and one or more <em>embedded languages</em>.  A Lisp
+program usually first parses the whole document with the host
+language&rsquo;s parser, retrieves some information, sets ranges for the
+embedded languages with that information, and then parses the embedded
+languages.
+</p>
+<p>Take a buffer containing <acronym>HTML</acronym>, <acronym>CSS</acronym> and JavaScript
+as an example.  A Lisp program will first parse the whole buffer with
+an <acronym>HTML</acronym> parser, then query the parser for
+<code>style_element</code> and <code>script_element</code> nodes, which
+correspond to <acronym>CSS</acronym> and JavaScript text, respectively.  Then
+it sets the range of the <acronym>CSS</acronym> and JavaScript parser to the
+ranges in which their corresponding nodes span.
+</p>
+<p>Given a simple <acronym>HTML</acronym> document:
+</p>
+<div class="example">
+<pre class="example">&lt;html&gt;
+  &lt;script&gt;1 + 2&lt;/script&gt;
+  &lt;style&gt;body { color: &quot;blue&quot;; }&lt;/style&gt;
+&lt;/html&gt;
+</pre></div>
+
+<p>a Lisp program will first parse with a <acronym>HTML</acronym> parser, then set
+ranges for <acronym>CSS</acronym> and JavaScript parsers:
+</p>
+<div class="example">
+<pre class="example">;; Create parsers.
+(setq html (treesit-get-parser-create 'html))
+(setq css (treesit-get-parser-create 'css))
+(setq js (treesit-get-parser-create 'javascript))
+</pre><pre class="example">
+
+</pre><pre class="example">;; Set CSS ranges.
+(setq css-range
+      (treesit-query-range
+       'html
+       &quot;(style_element (raw_text) @capture)&quot;))
+(treesit-parser-set-included-ranges css css-range)
+</pre><pre class="example">
+
+</pre><pre class="example">;; Set JavaScript ranges.
+(setq js-range
+      (treesit-query-range
+       'html
+       &quot;(script_element (raw_text) @capture)&quot;))
+(treesit-parser-set-included-ranges js js-range)
+</pre></div>
+
+<p>Emacs automates this process in <code>treesit-update-ranges</code>.  A
+multi-language major mode should set <code>treesit-range-settings</code> so
+that <code>treesit-update-ranges</code> knows how to perform this process
+automatically.  Major modes should use the helper function
+<code>treesit-range-rules</code> to generate a value that can be assigned to
+<code>treesit-range-settings</code>.  The settings in the following example
+directly translate into operations shown above.
+</p>
+<div class="example">
+<pre class="example">(setq-local treesit-range-settings
+            (treesit-range-rules
+             :embed 'javascript
+             :host 'html
+             '((script_element (raw_text) @capture))
+</pre><pre class="example">
+
+</pre><pre class="example">             :embed 'css
+             :host 'html
+             '((style_element (raw_text) @capture))))
+</pre></div>
+
+<dl class="def">
+<dt id="index-treesit_002drange_002drules"><span class="category">Function: </span><span><strong>treesit-range-rules</strong> <em>&amp;rest query-specs</em><a href='#index-treesit_002drange_002drules' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function is used to set <var>treesit-range-settings</var>.  It
+takes care of compiling queries and other post-processing, and outputs
+a value that <var>treesit-range-settings</var> can have.
+</p>
+<p>It takes a series of <var>query-spec</var>s, where each <var>query-spec</var> is
+a <var>query</var> preceded by zero or more <var>keyword</var>/<var>value</var>
+pairs.  Each <var>query</var> is a tree-sitter query in either the
+string, s-expression or compiled form, or a function.
+</p>
+<p>If <var>query</var> is a tree-sitter query, it should be preceded by two
+<var>:keyword</var>/<var>value</var> pairs, where the <code>:embed</code> keyword
+specifies the embedded language, and the <code>:host</code> keyword
+specified the host language.
+</p>
+<p><code>treesit-update-ranges</code> uses <var>query</var> to figure out how to set
+the ranges for parsers for the embedded language.  It queries
+<var>query</var> in a host language parser, computes the ranges in which
+the captured nodes span, and applies these ranges to embedded
+language parsers.
+</p>
+<p>If <var>query</var> is a function, it doesn&rsquo;t need any <var>:keyword</var> and
+<var>value</var> pair.  It should be a function that takes 2 arguments,
+<var>start</var> and <var>end</var>, and sets the ranges for parsers in the
+current buffer in the region between <var>start</var> and <var>end</var>.  It is
+fine for this function to set ranges in a larger region that
+encompasses the region between <var>start</var> and <var>end</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002drange_002dsettings"><span class="category">Variable: </span><span><strong>treesit-range-settings</strong><a href='#index-treesit_002drange_002dsettings' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This variable helps <code>treesit-update-ranges</code> in updating the
+ranges for parsers in the buffer.  It is a list of <var>setting</var>s
+where the exact format of a <var>setting</var> is considered internal.  You
+should use <code>treesit-range-rules</code> to generate a value that this
+variable can have.
+</p>
+</dd></dl>
+
+
+<dl class="def">
+<dt id="index-treesit_002dlanguage_002dat_002dpoint_002dfunction"><span class="category">Variable: </span><span><strong>treesit-language-at-point-function</strong><a href='#index-treesit_002dlanguage_002dat_002dpoint_002dfunction' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This variable&rsquo;s value should be a function that takes a single
+argument, <var>pos</var>, which is a buffer position, and returns the
+language of the buffer text at <var>pos</var>.  This variable is used by
+<code>treesit-language-at</code>.
+</p></dd></dl>
+
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Tree_002dsitter-major-modes.html">Developing major modes with tree-sitter</a>, Previous: <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html

@@ -0,0 +1,247 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Parser-based Font Lock (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Parser-based Font Lock (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Font-Lock-Mode.html" rel="up" title="Font Lock Mode">
+<link href="Multiline-Font-Lock.html" rel="prev" title="Multiline Font Lock">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="subsection" id="Parser_002dbased-Font-Lock">
+<div class="header">
+<p>
+Previous: <a href="Multiline-Font-Lock.html" accesskey="p" rel="prev">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html" accesskey="u" rel="up">Font Lock Mode</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Parser_002dbased-Font-Lock-1"></span><h4 class="subsection">24.6.10 Parser-based Font Lock</h4>
+<span id="index-parser_002dbased-font_002dlock"></span>
+
+
+<p>Besides simple syntactic font lock and regexp-based font lock, Emacs
+also provides complete syntactic font lock with the help of a parser.
+Currently, Emacs uses the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>) for this purpose.
+</p>
+<p>Parser-based font lock and other font lock mechanisms are not mutually
+exclusive.  By default, if enabled, parser-based font lock runs first,
+replacing syntactic font lock, then the regexp-based font lock.
+</p>
+<p>Although parser-based font lock doesn&rsquo;t share the same customization
+variables with regexp-based font lock, it uses similar customization
+schemes.  The tree-sitter counterpart of <var>font-lock-keywords</var> is
+<var>treesit-font-lock-settings</var>.
+</p>
+<span id="index-tree_002dsitter-fontifications_002c-overview"></span>
+<span id="index-fontifications-with-tree_002dsitter_002c-overview"></span>
+<p>In general, tree-sitter fontification works as follows:
+</p>
+<ul>
+<li> A Lisp program (usually, part of a major mode) provides a <em>query</em>
+consisting of <em>patterns</em>, each pattern associated with a
+<em>capture name</em>.
+
+</li><li> The tree-sitter library finds the nodes in the parse tree
+that match these patterns, tags the nodes with the corresponding
+capture names, and returns them to the Lisp program.
+
+</li><li> The Lisp program uses the returned nodes to highlight the portions of
+buffer text corresponding to each node as appropriate, using the
+tagged capture names of the nodes to determine the correct
+fontification.  For example, a node tagged <code>font-lock-keyword</code>
+would be highlighted in <code>font-lock-keyword</code> face.
+</li></ul>
+
+<p>For more information about queries, patterns, and capture names, see
+<a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>.
+</p>
+<p>To setup tree-sitter fontification, a major mode should first set
+<code>treesit-font-lock-settings</code> with the output of
+<code>treesit-font-lock-rules</code>, then call
+<code>treesit-major-mode-setup</code>.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dfont_002dlock_002drules"><span class="category">Function: </span><span><strong>treesit-font-lock-rules</strong> <em>&amp;rest query-specs</em><a href='#index-treesit_002dfont_002dlock_002drules' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function is used to set <var>treesit-font-lock-settings</var>.  It
+takes care of compiling queries and other post-processing, and outputs
+a value that <var>treesit-font-lock-settings</var> accepts.  Here&rsquo;s an
+example:
+</p>
+<div class="example">
+<pre class="example">(treesit-font-lock-rules
+ :language 'javascript
+ :feature 'constant
+ :override t
+ '((true) @font-lock-constant-face
+   (false) @font-lock-constant-face)
+ :language 'html
+ :feature 'script
+ &quot;(script_element) @font-lock-builtin-face&quot;)
+</pre></div>
+
+<p>This function takes a series of <var>query-spec</var>s, where each
+<var>query-spec</var> is a <var>query</var> preceded by one or more
+<var>:keyword</var>/<var>value</var> pairs.  Each <var>query</var> is a
+tree-sitter query in either the string, s-expression or compiled form.
+</p>
+<p>For each <var>query</var>, the <var>:keyword</var>/<var>value</var> pairs that
+precede it add meta information to it.  The <code>:language</code> keyword
+declares <var>query</var>&rsquo;s language.  The <code>:feature</code> keyword sets the
+feature name of <var>query</var>.  Users can control which features are
+enabled with <code>font-lock-maximum-decoration</code> and
+<code>treesit-font-lock-feature-list</code> (described below).  These two
+keywords are mandatory.
+</p>
+<p>Other keywords are optional:
+</p>
+<table>
+<thead><tr><th width="15%">Keyword</th><th width="15%">Value</th><th width="60%">Description</th></tr></thead>
+<tr><td width="15%"><code>:override</code></td><td width="15%">nil</td><td width="60%">If the region already has a face, discard the new face</td></tr>
+<tr><td width="15%"></td><td width="15%">t</td><td width="60%">Always apply the new face</td></tr>
+<tr><td width="15%"></td><td width="15%"><code>append</code></td><td width="60%">Append the new face to existing ones</td></tr>
+<tr><td width="15%"></td><td width="15%"><code>prepend</code></td><td width="60%">Prepend the new face to existing ones</td></tr>
+<tr><td width="15%"></td><td width="15%"><code>keep</code></td><td width="60%">Fill-in regions without an existing face</td></tr>
+</table>
+
+<p>Lisp programs mark patterns in <var>query</var> with capture names (names
+that starts with <code>@</code>), and tree-sitter will return matched nodes
+tagged with those same capture names.  For the purpose of
+fontification, capture names in <var>query</var> should be face names like
+<code>font-lock-keyword-face</code>.  The captured node will be fontified
+with that face.
+</p>
+<span id="index-treesit_002dfontify_002dwith_002doverride"></span>
+<p>Capture names can also be function names, in which case the function
+is called with 4 arguments: <var>node</var> and <var>override</var>, <var>start</var>
+and <var>end</var>, where <var>node</var> is the node itself, <var>override</var> is
+the override property of the rule which captured this node, and
+<var>start</var> and <var>end</var> limits the region in which this function
+should fontify.  (If this function wants to respect the <var>override</var>
+argument, it can use <code>treesit-fontify-with-override</code>.)
+</p>
+<p>Beyond the 4 arguments presented, this function should accept more
+arguments as optional arguments for future extensibility.
+</p>
+<p>If a capture name is both a face and a function, the face takes
+priority.  If a capture name is neither a face nor a function, it is
+ignored.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dfont_002dlock_002dfeature_002dlist"><span class="category">Variable: </span><span><strong>treesit-font-lock-feature-list</strong><a href='#index-treesit_002dfont_002dlock_002dfeature_002dlist' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This is a list of lists of feature symbols.  Each element of the list
+is a list that represents a decoration level.
+<code>font-lock-maximum-decoration</code> controls which levels are
+activated.
+</p>
+<p>Each element of the list is a list of the form <code>(<var>feature</var>&nbsp;&hellip;)</code><!-- /@w -->, where each <var>feature</var> corresponds to the
+<code>:feature</code> value of a query defined in
+<code>treesit-font-lock-rules</code>.  Removing a feature symbol from this
+list disables the corresponding query during font-lock.
+</p>
+<p>Common feature names, for many programming languages, include
+<code>definition</code>, <code>type</code>, <code>assignment</code>, <code>builtin</code>,
+<code>constant</code>, <code>keyword</code>, <code>string-interpolation</code>,
+<code>comment</code>, <code>doc</code>, <code>string</code>, <code>operator</code>,
+<code>preprocessor</code>, <code>escape-sequence</code>, and <code>key</code>.  Major
+modes are free to subdivide or extend these common features.
+</p>
+<p>Some of these features warrant some explanation: <code>definition</code>
+highlights whatever is being defined, e.g., the function name in a
+function definition, the struct name in a struct definition, the
+variable name in a variable definition; <code>assignment</code> highlights
+the whatever is being assigned to, e.g., the variable or field in an
+assignment statement; <code>key</code> highlights keys in key-value pairs,
+e.g., keys in a JSON object, or a Python dictionary; <code>doc</code>
+highlights docstrings or doc-comments.
+</p>
+<p>For example, the value of this variable could be:
+</p><div class="example">
+<pre class="example">((comment string doc) ; level 1
+ (function-name keyword type builtin constant) ; level 2
+ (variable-name string-interpolation key)) ; level 3
+</pre></div>
+
+<p>Major modes should set this variable before calling
+<code>treesit-major-mode-setup</code>.
+</p>
+<span id="index-treesit_002dfont_002dlock_002drecompute_002dfeatures"></span>
+<p>For this variable to take effect, a Lisp program should call
+<code>treesit-font-lock-recompute-features</code> (which resets
+<code>treesit-font-lock-settings</code> accordingly), or
+<code>treesit-major-mode-setup</code> (which calls
+<code>treesit-font-lock-recompute-features</code>).
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dfont_002dlock_002dsettings"><span class="category">Variable: </span><span><strong>treesit-font-lock-settings</strong><a href='#index-treesit_002dfont_002dlock_002dsettings' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>A list of settings for tree-sitter based font lock.  The exact format
+of each setting is considered internal.  One should always use
+<code>treesit-font-lock-rules</code> to set this variable.
+</p>
+</dd></dl>
+
+<p>Multi-language major modes should provide range functions in
+<code>treesit-range-functions</code>, and Emacs will set the ranges
+accordingly before fontifing a region (see <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>).
+</p>
+</div>
+<hr>
+<div class="header">
+<p>
+Previous: <a href="Multiline-Font-Lock.html">Multiline Font Lock Constructs</a>, Up: <a href="Font-Lock-Mode.html">Font Lock Mode</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html

@@ -0,0 +1,280 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Parser-based Indentation (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Auto_002dIndentation.html" rel="up" title="Auto-Indentation">
+<link href="SMIE.html" rel="prev" title="SMIE">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="subsection" id="Parser_002dbased-Indentation">
+<div class="header">
+<p>
+Previous: <a href="SMIE.html" accesskey="p" rel="prev">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html" accesskey="u" rel="up">Automatic Indentation of code</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Parser_002dbased-Indentation-1"></span><h4 class="subsection">24.7.2 Parser-based Indentation</h4>
+<span id="index-parser_002dbased-indentation"></span>
+
+
+<p>When built with the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>), Emacs is capable of parsing the program source and producing
+a syntax tree.  This syntax tree can be used for guiding the program
+source indentation commands.  For maximum flexibility, it is possible
+to write a custom indentation function that queries the syntax tree
+and indents accordingly for each language, but that is a lot of work.
+It is more convenient to use the simple indentation engine described
+below: then the major mode needs only to write some indentation rules
+and the engine takes care of the rest.
+</p>
+<p>To enable the parser-based indentation engine, either set
+<var>treesit-simple-indent-rules</var> and call
+<code>treesit-major-mode-setup</code>, or equivalently, set the value of
+<code>indent-line-function</code> to <code>treesit-indent</code>.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dindent_002dfunction"><span class="category">Variable: </span><span><strong>treesit-indent-function</strong><a href='#index-treesit_002dindent_002dfunction' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This variable stores the actual function called by
+<code>treesit-indent</code>.  By default, its value is
+<code>treesit-simple-indent</code>.  In the future we might add other,
+more complex indentation engines.
+</p></dd></dl>
+
+<span id="Writing-indentation-rules"></span><h3 class="heading">Writing indentation rules</h3>
+<span id="index-indentation-rules_002c-for-parser_002dbased-indentation"></span>
+
+<dl class="def">
+<dt id="index-treesit_002dsimple_002dindent_002drules"><span class="category">Variable: </span><span><strong>treesit-simple-indent-rules</strong><a href='#index-treesit_002dsimple_002dindent_002drules' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This local variable stores indentation rules for every language.  It is
+a list of the form: <code>(<var>language</var>&nbsp;.&nbsp;<var>rules</var>)</code><!-- /@w -->, where
+<var>language</var> is a language symbol, and <var>rules</var> is a list of the
+form <code>(<var>matcher</var>&nbsp;<var>anchor</var>&nbsp;<var>offset</var>)</code><!-- /@w -->.
+</p>
+<p>First, Emacs passes the smallest tree-sitter node at the beginning of
+the current line to <var>matcher</var>; if it returns non-<code>nil</code>, this
+rule is applicable.  Then Emacs passes the node to <var>anchor</var>, which
+returns a buffer position.  Emacs takes the column number of that
+position, adds <var>offset</var> to it, and the result is the indentation
+column for the current line.  <var>offset</var> can be an integer or a
+variable whose value is an integer.
+</p>
+<p>The <var>matcher</var> and <var>anchor</var> are functions, and Emacs provides
+convenient defaults for them.
+</p>
+<p>Each <var>matcher</var> or <var>anchor</var> is a function that takes three
+arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>.  The argument
+<var>bol</var> is the buffer position whose indentation is required: the
+position of the first non-whitespace character after the beginning of
+the line.  The argument <var>node</var> is the largest (highest-in-tree)
+node that starts at that position; and <var>parent</var> is the parent of
+<var>node</var>.  However, when that position is in a whitespace or inside
+a multi-line string, no node can start at that position, so
+<var>node</var> is <code>nil</code>.  In that case, <var>parent</var> would be the
+smallest node that spans that position.
+</p>
+<p>Emacs finds <var>bol</var>, <var>node</var> and <var>parent</var> and
+passes them to each <var>matcher</var> and <var>anchor</var>.  <var>matcher</var>
+should return non-<code>nil</code> if the rule is applicable, and
+<var>anchor</var> should return a buffer position.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dsimple_002dindent_002dpresets"><span class="category">Variable: </span><span><strong>treesit-simple-indent-presets</strong><a href='#index-treesit_002dsimple_002dindent_002dpresets' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This is a list of defaults for <var>matcher</var>s and <var>anchor</var>s in
+<code>treesit-simple-indent-rules</code>.  Each of them represents a function
+that takes 3 arguments: <var>node</var>, <var>parent</var> and <var>bol</var>.  The
+available default functions are:
+</p>
+<dl compact="compact">
+<dt id='index-no_002dnode'><span><code>no-node</code><a href='#index-no_002dnode' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function that is called with 3 arguments:
+<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code>,
+indicating a match, if <var>node</var> is <code>nil</code>, i.e., there is no
+node that starts at <var>bol</var>.  This is the case when <var>bol</var> is on
+an empty line or inside a multi-line string, etc.
+</p>
+</dd>
+<dt id='index-parent_002dis'><span><code>parent-is</code><a href='#index-parent_002dis' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
+function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
+and <var>bol</var>, and returns non-<code>nil</code> (i.e., a match) if
+<var>parent</var>&rsquo;s type matches regexp <var>type</var>.
+</p>
+</dd>
+<dt id='index-node_002dis'><span><code>node-is</code><a href='#index-node_002dis' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
+function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
+and <var>bol</var>, and returns non-<code>nil</code> if <var>node</var>&rsquo;s type matches
+regexp <var>type</var>.
+</p>
+</dd>
+<dt id='index-query'><span><code>query</code><a href='#index-query' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function of one argument, <var>query</var>; it returns a
+function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
+and <var>bol</var>, and returns non-<code>nil</code> if querying <var>parent</var>
+with <var>query</var> captures <var>node</var> (see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>).
+</p>
+</dd>
+<dt id='index-match'><span><code>match</code><a href='#index-match' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function of 5 arguments: <var>node-type</var>,
+<var>parent-type</var>, <var>node-field</var>, <var>node-index-min</var>, and
+<var>node-index-max</var>).  It returns a function that is called with 3
+arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>, and returns
+non-<code>nil</code> if <var>node</var>&rsquo;s type matches regexp <var>node-type</var>,
+<var>parent</var>&rsquo;s type matches regexp <var>parent-type</var>, <var>node</var>&rsquo;s
+field name in <var>parent</var> matches regexp <var>node-field</var>, and
+<var>node</var>&rsquo;s index among its siblings is between <var>node-index-min</var>
+and <var>node-index-max</var>.  If the value of an argument is <code>nil</code>,
+this matcher doesn&rsquo;t check that argument.  For example, to match the
+first child where parent is <code>argument_list</code>, use
+</p>
+<div class="example">
+<pre class="example">(match nil &quot;argument_list&quot; nil nil 0 0)
+</pre></div>
+
+</dd>
+<dt id='index-comment_002dend'><span><code>comment-end</code><a href='#index-comment_002dend' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This matcher is a function that is called with 3 arguments:
+<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code> if
+point is before a comment ending token.  Comment ending tokens are
+defined by regular expression <code>treesit-comment-end</code>
+(see <a href="Tree_002dsitter-major-modes.html">treesit-comment-end</a>).
+</p>
+</dd>
+<dt id='index-first_002dsibling'><span><code>first-sibling</code><a href='#index-first_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the start of the first child
+of <var>parent</var>.
+</p>
+</dd>
+<dt id='index-parent'><span><code>parent</code><a href='#index-parent' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the start of <var>parent</var>.
+</p>
+</dd>
+<dt id='index-parent_002dbol'><span><code>parent-bol</code><a href='#index-parent_002dbol' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the first non-space character
+on the line of <var>parent</var>.
+</p>
+</dd>
+<dt id='index-prev_002dsibling'><span><code>prev-sibling</code><a href='#index-prev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the start of the previous
+sibling of <var>node</var>.
+</p>
+</dd>
+<dt id='index-no_002dindent'><span><code>no-indent</code><a href='#index-no_002dindent' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the start of <var>node</var>.
+</p>
+</dd>
+<dt id='index-prev_002dline'><span><code>prev-line</code><a href='#index-prev_002dline' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the first non-whitespace
+character on the previous line.
+</p>
+</dd>
+<dt id='index-point_002dmin'><span><code>point-min</code><a href='#index-point_002dmin' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the beginning of the buffer.
+This is useful as the beginning of the buffer is always at column 0.
+</p>
+</dd>
+<dt id='index-comment_002dstart'><span><code>comment-start</code><a href='#index-comment_002dstart' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the position right after the
+comment-start token.  Comment-start tokens are defined by regular
+expression <code>treesit-comment-start</code> (see <a href="Tree_002dsitter-major-modes.html">treesit-comment-start</a>).  This function assumes <var>parent</var> is
+the comment node.
+</p>
+</dd>
+<dt id='index-coment_002dstart_002dskip'><span><code>comment-start-skip</code><a href='#index-coment_002dstart_002dskip' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
+<var>parent</var>, and <var>bol</var>, and returns the position after the
+comment-start token and any whitespace characters following that
+token.  Comment-start tokens are defined by regular expression
+<code>treesit-comment-start</code>.  This function assumes <var>parent</var> is
+the comment node.
+</p></dd>
+</dl>
+</dd></dl>
+
+<span id="Indentation-utilities"></span><h3 class="heading">Indentation utilities</h3>
+<span id="index-utility-functions-for-parser_002dbased-indentation"></span>
+
+<p>Here are some utility functions that can help writing parser-based
+indentation rules.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dcheck_002dindent"><span class="category">Function: </span><span><strong>treesit-check-indent</strong> <em>mode</em><a href='#index-treesit_002dcheck_002dindent' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function checks the current buffer&rsquo;s indentation against major
+mode <var>mode</var>.  It indents the current buffer according to
+<var>mode</var> and compares the results with the current indentation.
+Then it pops up a buffer showing the differences.  Correct
+indentation (target) is shown in green color, current indentation is
+shown in red color.  </p></dd></dl>
+
+<p>It is also helpful to use <code>treesit-inspect-mode</code> (see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>) when writing indentation rules.
+</p>
+</div>
+<hr>
+<div class="header">
+<p>
+Previous: <a href="SMIE.html">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html">Automatic Indentation of code</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html

@@ -0,0 +1,125 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Parsing Program Source (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Parsing Program Source (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Parsing Program Source (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="index.html" rel="up" title="Top">
+<link href="Abbrevs.html" rel="next" title="Abbrevs">
+<link href="Syntax-Tables.html" rel="prev" title="Syntax Tables">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="chapter" id="Parsing-Program-Source">
+<div class="header">
+<p>
+Next: <a href="Abbrevs.html" accesskey="n" rel="next">Abbrevs and Abbrev Expansion</a>, Previous: <a href="Syntax-Tables.html" accesskey="p" rel="prev">Syntax Tables</a>, Up: <a href="index.html" accesskey="u" rel="up">Emacs Lisp</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Parsing-Program-Source-1"></span><h2 class="chapter">37 Parsing Program Source</h2>
+
+<span id="index-syntax-tree_002c-from-parsing-program-source"></span>
+<p>Emacs provides various ways to parse program source text and produce a
+<em>syntax tree</em>.  In a syntax tree, text is no longer considered a
+one-dimensional stream of characters, but a structured tree of nodes,
+where each node representing a piece of text.  Thus, a syntax tree can
+enable interesting features like precise fontification, indentation,
+navigation, structured editing, etc.
+</p>
+<p>Emacs has a simple facility for parsing balanced expressions
+(see <a href="Parsing-Expressions.html">Parsing Expressions</a>).  There is also the SMIE library for
+generic navigation and indentation (see <a href="SMIE.html">Simple Minded Indentation Engine</a>).
+</p>
+<p>In addition to those, Emacs also provides integration with
+<a href="https://tree-sitter.github.io/tree-sitter">the tree-sitter
+library</a>) if support for it was compiled in.  The tree-sitter library
+implements an incremental parser and has support from a wide range of
+programming languages.
+</p>
+<dl class="def">
+<dt id="index-treesit_002davailable_002dp"><span class="category">Function: </span><span><strong>treesit-available-p</strong><a href='#index-treesit_002davailable_002dp' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns non-<code>nil</code> if tree-sitter features are
+available for the current Emacs session.
+</p></dd></dl>
+
+<p>To be able to parse the program source using the tree-sitter library
+and access the syntax tree of the program, a Lisp program needs to
+load a language definition library, and create a parser for that
+language and the current buffer.  After that, the Lisp program can
+query the parser about specific nodes of the syntax tree.  Then, it
+can access various kinds of information about each node, and search
+for nodes using a powerful pattern-matching syntax.  This chapter
+explains how to do all this, and also how a Lisp program can work with
+source files that mix multiple programming languages.
+</p>
+
+<ul class="section-toc">
+<li><a href="Language-Definitions.html" accesskey="1">Tree-sitter Language Definitions</a></li>
+<li><a href="Using-Parser.html" accesskey="2">Using Tree-sitter Parser</a></li>
+<li><a href="Retrieving-Nodes.html" accesskey="3">Retrieving Nodes</a></li>
+<li><a href="Accessing-Node-Information.html" accesskey="4">Accessing Node Information</a></li>
+<li><a href="Pattern-Matching.html" accesskey="5">Pattern Matching Tree-sitter Nodes</a></li>
+<li><a href="Multiple-Languages.html" accesskey="6">Parsing Text in Multiple Languages</a></li>
+<li><a href="Tree_002dsitter-major-modes.html" accesskey="7">Developing major modes with tree-sitter</a></li>
+<li><a href="Tree_002dsitter-C-API.html" accesskey="8">Tree-sitter C API Correspondence</a></li>
+</ul>
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Abbrevs.html">Abbrevs and Abbrev Expansion</a>, Previous: <a href="Syntax-Tables.html">Syntax Tables</a>, Up: <a href="index.html">Emacs Lisp</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Pattern-Matching.html

@@ -0,0 +1,450 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Pattern Matching (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Pattern Matching (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Pattern Matching (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Multiple-Languages.html" rel="next" title="Multiple Languages">
+<link href="Accessing-Node-Information.html" rel="prev" title="Accessing Node Information">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Pattern-Matching">
+<div class="header">
+<p>
+Next: <a href="Multiple-Languages.html" accesskey="n" rel="next">Parsing Text in Multiple Languages</a>, Previous: <a href="Accessing-Node-Information.html" accesskey="p" rel="prev">Accessing Node Information</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Pattern-Matching-Tree_002dsitter-Nodes"></span><h3 class="section">37.5 Pattern Matching Tree-sitter Nodes</h3>
+<span id="index-pattern-matching-with-tree_002dsitter-nodes"></span>
+
+<span id="index-capturing_002c-tree_002dsitter-node"></span>
+<p>Tree-sitter lets Lisp programs match patterns using a small
+declarative language.  This pattern matching consists of two steps:
+first tree-sitter matches a <em>pattern</em> against nodes in the syntax
+tree, then it <em>captures</em> specific nodes that matched the pattern
+and returns the captured nodes.
+</p>
+<p>We describe first how to write the most basic query pattern and how to
+capture nodes in a pattern, then the pattern-matching function, and
+finally the more advanced pattern syntax.
+</p>
+<span id="Basic-query-syntax"></span><h3 class="heading">Basic query syntax</h3>
+
+<span id="index-tree_002dsitter-query-pattern-syntax"></span>
+<span id="index-pattern-syntax_002c-tree_002dsitter-query"></span>
+<span id="index-query_002c-tree_002dsitter"></span>
+<p>A <em>query</em> consists of multiple <em>patterns</em>.  Each pattern is an
+s-expression that matches a certain node in the syntax node.  A
+pattern has the form <code>(<var>type</var>&nbsp;(<var>child</var>&hellip;))</code><!-- /@w -->
+</p>
+<p>For example, a pattern that matches a <code>binary_expression</code> node that
+contains <code>number_literal</code> child nodes would look like
+</p>
+<div class="example">
+<pre class="example">(binary_expression (number_literal))
+</pre></div>
+
+<p>To <em>capture</em> a node using the query pattern above, append
+<code>@<var>capture-name</var></code> after the node pattern you want to
+capture.  For example,
+</p>
+<div class="example">
+<pre class="example">(binary_expression (number_literal) @number-in-exp)
+</pre></div>
+
+<p>captures <code>number_literal</code> nodes that are inside a
+<code>binary_expression</code> node with the capture name
+<code>number-in-exp</code>.
+</p>
+<p>We can capture the <code>binary_expression</code> node as well, with, for
+example, the capture name <code>biexp</code>:
+</p>
+<div class="example">
+<pre class="example">(binary_expression
+ (number_literal) @number-in-exp) @biexp
+</pre></div>
+
+<span id="Query-function"></span><h3 class="heading">Query function</h3>
+
+<span id="index-query-functions_002c-tree_002dsitter"></span>
+<p>Now we can introduce the <em>query functions</em>.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dquery_002dcapture"><span class="category">Function: </span><span><strong>treesit-query-capture</strong> <em>node query &amp;optional beg end node-only</em><a href='#index-treesit_002dquery_002dcapture' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function matches patterns in <var>query</var> within <var>node</var>.
+The argument <var>query</var> can be either a string, a s-expression, or a
+compiled query object.  For now, we focus on the string syntax;
+s-expression syntax and compiled query are described at the end of the
+section.
+</p>
+<p>The argument <var>node</var> can also be a parser or a language symbol.  A
+parser means using its root node, a language symbol means find or
+create a parser for that language in the current buffer, and use the
+root node.
+</p>
+<p>The function returns all the captured nodes in a list of the form
+<code>(<var><span class="nolinebreak">capture_name</span></var>&nbsp;.&nbsp;<var>node</var>)</code><!-- /@w -->.  If <var>node-only</var> is
+non-<code>nil</code>, it returns the list of nodes instead.  By default the
+entire text of <var>node</var> is searched, but if <var>beg</var> and <var>end</var>
+are both non-<code>nil</code>, they specify the region of buffer text where
+this function should match nodes.  Any matching node whose span
+overlaps with the region between <var>beg</var> and <var>end</var> are captured,
+it doesn&rsquo;t have to be completely in the region.
+</p>
+<span id="index-treesit_002dquery_002derror"></span>
+<span id="index-treesit_002dquery_002dvalidate"></span>
+<p>This function raises the <code>treesit-query-error</code> error if
+<var>query</var> is malformed.  The signal data contains a description of
+the specific error.  You can use <code>treesit-query-validate</code> to
+validate and debug the query.
+</p></dd></dl>
+
+<p>For example, suppose <var>node</var>&rsquo;s text is <code>1 + 2</code>, and
+<var>query</var> is
+</p>
+<div class="example">
+<pre class="example">(setq query
+      &quot;(binary_expression
+        (number_literal) @number-in-exp) @biexp&quot;)
+</pre></div>
+
+<p>Matching that query would return
+</p>
+<div class="example">
+<pre class="example">(treesit-query-capture node query)
+    &rArr; ((biexp . <var>&lt;node for &quot;1 + 2&quot;&gt;</var>)
+       (number-in-exp . <var>&lt;node for &quot;1&quot;&gt;</var>)
+       (number-in-exp . <var>&lt;node for &quot;2&quot;&gt;</var>))
+</pre></div>
+
+<p>As mentioned earlier, <var>query</var> could contain multiple patterns.
+For example, it could have two top-level patterns:
+</p>
+<div class="example">
+<pre class="example">(setq query
+      &quot;(binary_expression) @biexp
+       (number_literal)  @number @biexp&quot;)
+</pre></div>
+
+<dl class="def">
+<dt id="index-treesit_002dquery_002dstring"><span class="category">Function: </span><span><strong>treesit-query-string</strong> <em>string query language</em><a href='#index-treesit_002dquery_002dstring' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function parses <var>string</var> with <var>language</var>, matches its
+root node with <var>query</var>, and returns the result.
+</p></dd></dl>
+
+<span id="More-query-syntax"></span><h3 class="heading">More query syntax</h3>
+
+<p>Besides node type and capture, tree-sitter&rsquo;s pattern syntax can
+express anonymous node, field name, wildcard, quantification,
+grouping, alternation, anchor, and predicate.
+</p>
+<span id="Anonymous-node"></span><h4 class="subheading">Anonymous node</h4>
+
+<p>An anonymous node is written verbatim, surrounded by quotes.  A
+pattern matching (and capturing) keyword <code>return</code> would be
+</p>
+<div class="example">
+<pre class="example">&quot;return&quot; @keyword
+</pre></div>
+
+<span id="Wild-card"></span><h4 class="subheading">Wild card</h4>
+
+<p>In a pattern, &lsquo;<samp>(_)</samp>&rsquo; matches any named node, and &lsquo;<samp>_</samp>&rsquo; matches
+any named and anonymous node.  For example, to capture any named child
+of a <code>binary_expression</code> node, the pattern would be
+</p>
+<div class="example">
+<pre class="example">(binary_expression (_) @in_biexp)
+</pre></div>
+
+<span id="Field-name"></span><h4 class="subheading">Field name</h4>
+
+<p>It is possible to capture child nodes that have specific field names.
+In the pattern below, <code>declarator</code> and <code>body</code> are field
+names, indicated by the colon following them.
+</p>
+<div class="example">
+<pre class="example">(function_definition
+  declarator: (_) @func-declarator
+  body: (_) @func-body)
+</pre></div>
+
+<p>It is also possible to capture a node that doesn&rsquo;t have a certain
+field, say, a <code>function_definition</code> without a <code>body</code> field.
+</p>
+<div class="example">
+<pre class="example">(function_definition !body) @func-no-body
+</pre></div>
+
+<span id="Quantify-node"></span><h4 class="subheading">Quantify node</h4>
+
+<span id="index-quantify-node_002c-tree_002dsitter"></span>
+<p>Tree-sitter recognizes quantification operators &lsquo;<samp>*</samp>&rsquo;, &lsquo;<samp>+</samp>&rsquo; and
+&lsquo;<samp>?</samp>&rsquo;.  Their meanings are the same as in regular expressions:
+&lsquo;<samp>*</samp>&rsquo; matches the preceding pattern zero or more times, &lsquo;<samp>+</samp>&rsquo;
+matches one or more times, and &lsquo;<samp>?</samp>&rsquo; matches zero or one time.
+</p>
+<p>For example, the following pattern matches <code>type_declaration</code>
+nodes that has <em>zero or more</em> <code>long</code> keyword.
+</p>
+<div class="example">
+<pre class="example">(type_declaration &quot;long&quot;*) @long-type
+</pre></div>
+
+<p>The following pattern matches a type declaration that has zero or one
+<code>long</code> keyword:
+</p>
+<div class="example">
+<pre class="example">(type_declaration &quot;long&quot;?) @long-type
+</pre></div>
+
+<span id="Grouping"></span><h4 class="subheading">Grouping</h4>
+
+<p>Similar to groups in regular expression, we can bundle patterns into
+groups and apply quantification operators to them.  For example, to
+express a comma separated list of identifiers, one could write
+</p>
+<div class="example">
+<pre class="example">(identifier) (&quot;,&quot; (identifier))*
+</pre></div>
+
+<span id="Alternation"></span><h4 class="subheading">Alternation</h4>
+
+<p>Again, similar to regular expressions, we can express &ldquo;match anyone
+from this group of patterns&rdquo; in a pattern.  The syntax is a list of
+patterns enclosed in square brackets.  For example, to capture some
+keywords in C, the pattern would be
+</p>
+<div class="example">
+<pre class="example">[
+  &quot;return&quot;
+  &quot;break&quot;
+  &quot;if&quot;
+  &quot;else&quot;
+] @keyword
+</pre></div>
+
+<span id="Anchor"></span><h4 class="subheading">Anchor</h4>
+
+<p>The anchor operator &lsquo;<samp>.</samp>&rsquo; can be used to enforce juxtaposition,
+i.e., to enforce two things to be directly next to each other.  The
+two &ldquo;things&rdquo; can be two nodes, or a child and the end of its parent.
+For example, to capture the first child, the last child, or two
+adjacent children:
+</p>
+<div class="example">
+<pre class="example">;; Anchor the child with the end of its parent.
+(compound_expression (_) @last-child .)
+</pre><pre class="example">
+
+</pre><pre class="example">;; Anchor the child with the beginning of its parent.
+(compound_expression . (_) @first-child)
+</pre><pre class="example">
+
+</pre><pre class="example">;; Anchor two adjacent children.
+(compound_expression
+ (_) @prev-child
+ .
+ (_) @next-child)
+</pre></div>
+
+<p>Note that the enforcement of juxtaposition ignores any anonymous
+nodes.
+</p>
+<span id="Predicate"></span><h4 class="subheading">Predicate</h4>
+
+<p>It is possible to add predicate constraints to a pattern.  For
+example, with the following pattern:
+</p>
+<div class="example">
+<pre class="example">(
+ (array . (_) @first (_) @last .)
+ (#equal @first @last)
+)
+</pre></div>
+
+<p>tree-sitter only matches arrays where the first element equals to
+the last element.  To attach a predicate to a pattern, we need to
+group them together.  A predicate always starts with a &lsquo;<samp>#</samp>&rsquo;.
+Currently there are two predicates, <code>#equal</code> and <code>#match</code>.
+</p>
+<dl class="def">
+<dt id="index-equal-1"><span class="category">Predicate: </span><span><strong>equal</strong> <em>arg1 arg2</em><a href='#index-equal-1' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Matches if <var>arg1</var> equals to <var>arg2</var>.  Arguments can be either
+strings or capture names.  Capture names represent the text that the
+captured node spans in the buffer.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-match-1"><span class="category">Predicate: </span><span><strong>match</strong> <em>regexp capture-name</em><a href='#index-match-1' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Matches if the text that <var>capture-name</var>&rsquo;s node spans in the buffer
+matches regular expression <var>regexp</var>.  Matching is case-sensitive.
+</p></dd></dl>
+
+<p>Note that a predicate can only refer to capture names that appear in
+the same pattern.  Indeed, it makes little sense to refer to capture
+names in other patterns.
+</p>
+<span id="S_002dexpression-patterns"></span><h3 class="heading">S-expression patterns</h3>
+
+<span id="index-tree_002dsitter-patterns-as-sexps"></span>
+<span id="index-patterns_002c-tree_002dsitter_002c-in-sexp-form"></span>
+<p>Besides strings, Emacs provides a s-expression based syntax for
+tree-sitter patterns.  It largely resembles the string-based syntax.
+For example, the following query
+</p>
+<div class="example">
+<pre class="example">(treesit-query-capture
+ node &quot;(addition_expression
+        left: (_) @left
+        \&quot;+\&quot; @plus-sign
+        right: (_) @right) @addition
+
+        [\&quot;return\&quot; \&quot;break\&quot;] @keyword&quot;)
+</pre></div>
+
+<p>is equivalent to
+</p>
+<div class="example">
+<pre class="example">(treesit-query-capture
+ node '((addition_expression
+         left: (_) @left
+         &quot;+&quot; @plus-sign
+         right: (_) @right) @addition
+
+         [&quot;return&quot; &quot;break&quot;] @keyword))
+</pre></div>
+
+<p>Most patterns can be written directly as strange but nevertheless
+valid s-expressions.  Only a few of them needs modification:
+</p>
+<ul>
+<li> Anchor &lsquo;<samp>.</samp>&rsquo; is written as <code>:anchor</code>.
+</li><li> &lsquo;<samp>?</samp>&rsquo; is written as &lsquo;<samp>:?</samp>&rsquo;.
+</li><li> &lsquo;<samp>*</samp>&rsquo; is written as &lsquo;<samp>:*</samp>&rsquo;.
+</li><li> &lsquo;<samp>+</samp>&rsquo; is written as &lsquo;<samp>:+</samp>&rsquo;.
+</li><li> <code>#equal</code> is written as <code>:equal</code>.  In general, predicates
+change their &lsquo;<samp>#</samp>&rsquo; to &lsquo;<samp>:</samp>&rsquo;.
+</li></ul>
+
+<p>For example,
+</p>
+<div class="example">
+<pre class="example">&quot;(
+  (compound_expression . (_) @first (_)* @rest)
+  (#match \&quot;love\&quot; @first)
+  )&quot;
+</pre></div>
+
+<p>is written in s-expression as
+</p>
+<div class="example">
+<pre class="example">'((
+   (compound_expression :anchor (_) @first (_) :* @rest)
+   (:match &quot;love&quot; @first)
+   ))
+</pre></div>
+
+<span id="Compiling-queries"></span><h3 class="heading">Compiling queries</h3>
+
+<span id="index-compiling-tree_002dsitter-queries"></span>
+<span id="index-queries_002c-compiling"></span>
+<p>If a query is intended to be used repeatedly, especially in tight
+loops, it is important to compile that query, because a compiled query
+is much faster than an uncompiled one.  A compiled query can be used
+anywhere a query is accepted.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dquery_002dcompile"><span class="category">Function: </span><span><strong>treesit-query-compile</strong> <em>language query</em><a href='#index-treesit_002dquery_002dcompile' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function compiles <var>query</var> for <var>language</var> into a compiled
+query object and returns it.
+</p>
+<p>This function raises the <code>treesit-query-error</code> error if
+<var>query</var> is malformed.  The signal data contains a description of
+the specific error.  You can use <code>treesit-query-validate</code> to
+validate and debug the query.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dquery_002dlanguage"><span class="category">Function: </span><span><strong>treesit-query-language</strong> <em>query</em><a href='#index-treesit_002dquery_002dlanguage' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function return the language of <var>query</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dquery_002dexpand"><span class="category">Function: </span><span><strong>treesit-query-expand</strong> <em>query</em><a href='#index-treesit_002dquery_002dexpand' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function converts the s-expression <var>query</var> into the string
+format.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dpattern_002dexpand"><span class="category">Function: </span><span><strong>treesit-pattern-expand</strong> <em>pattern</em><a href='#index-treesit_002dpattern_002dexpand' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function converts the s-expression <var>pattern</var> into the string
+format.
+</p></dd></dl>
+
+<p>For more details, read the tree-sitter project&rsquo;s documentation about
+pattern-matching, which can be found at
+<a href="https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries">https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries</a>.
+</p>
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>, Previous: <a href="Accessing-Node-Information.html">Accessing Node Information</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Retrieving-Node.html

@@ -0,0 +1,420 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Retrieving Node (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Accessing-Node-Information.html" rel="next" title="Accessing Node Information">
+<link href="Using-Parser.html" rel="prev" title="Using Parser">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Retrieving-Node">
+<div class="header">
+<p>
+Next: <a href="Accessing-Node-Information.html" accesskey="n" rel="next">Accessing Node Information</a>, Previous: <a href="Using-Parser.html" accesskey="p" rel="prev">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Retrieving-Node-1"></span><h3 class="section">37.3 Retrieving Node</h3>
+<span id="index-retrieve-node_002c-tree_002dsitter"></span>
+<span id="index-tree_002dsitter_002c-find-node"></span>
+<span id="index-get-node_002c-tree_002dsitter"></span>
+
+<span id="index-terminology_002c-for-tree_002dsitter-functions"></span>
+<p>Here&rsquo;s some terminology and conventions we use when documenting
+tree-sitter functions.
+</p>
+<p>We talk about a node being &ldquo;smaller&rdquo; or &ldquo;larger&rdquo;, and &ldquo;lower&rdquo; or
+&ldquo;higher&rdquo;.  A smaller and lower node is lower in the syntax tree and
+therefore spans a smaller portion of buffer text; a larger and higher
+node is higher up in the syntax tree, it contains many smaller nodes
+as its children, and therefore spans a larger portion of text.
+</p>
+<p>When a function cannot find a node, it returns <code>nil</code>.  For
+convenience, all functions that take a node as argument and return
+a node, also accept the node argument of <code>nil</code> and in that case
+just return <code>nil</code>.
+</p>
+<span id="index-treesit_002dnode_002doutdated"></span>
+<p>Nodes are not automatically updated when the associated buffer is
+modified, and there is no way to update a node once it is retrieved.
+Using an outdated node signals the <code>treesit-node-outdated</code> error.
+</p>
+<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3>
+<span id="index-retrieving-tree_002dsitter-nodes"></span>
+<span id="index-syntax-tree_002c-retrieving-nodes"></span>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dat"><span class="category">Function: </span><span><strong>treesit-node-at</strong> <em>pos &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the <em>smallest</em> node that starts at or after
+the buffer position <var>pos</var>.  In other words, the start of the node
+is greater or equal to <var>pos</var>.
+</p>
+<p>When <var>parser-or-lang</var> is <code>nil</code> or omitted, this function uses
+the first parser in <code>(treesit-parser-list)</code> of the current
+buffer.  If <var>parser-or-lang</var> is a parser object, it uses that
+parser; if <var>parser-or-lang</var> is a language, it finds the first
+parser using that language in <code>(treesit-parser-list)</code>, and uses
+that.
+</p>
+<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
+only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p>
+<p>When <var>pos</var> is after all the text in the buffer, technically there
+is no node after <var>pos</var>.  But for convenience, this function will
+return the last leaf node in the parse tree.  If <var>strict</var> is
+non-<code>nil</code>, this function will strictly comply to the semantics and
+return <var>nil</var>.
+</p>
+<p>Example:
+</p>
+<div class="example">
+<pre class="example">;; Find the node at point in a C parser's syntax tree.
+(treesit-node-at (point) 'c)
+  &rArr; #&lt;treesit-node (primitive_type) in 23-27&gt;
+</pre></div>
+</dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002don"><span class="category">Function: </span><span><strong>treesit-node-on</strong> <em>beg end &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002don' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the <em>smallest</em> node that covers the region
+of buffer text between <var>beg</var> and <var>end</var>.  In other words, the
+start of the node is before or at <var>beg</var>, and the end of the node
+is at or after <var>end</var>.
+</p>
+<p><em>Beware:</em> calling this function on an empty line that is not
+inside any top-level construct (function definition, etc.) most
+probably will give you the root node, because the root node is the
+smallest node that covers that empty line.  Most of the time, you want
+to use <code>treesit-node-at</code>, described above, instead.
+</p>
+<p>When <var>parser-or-lang</var> is <code>nil</code>, this function uses the first
+parser in <code>(treesit-parser-list)</code> of the current buffer.  If
+<var>parser-or-lang</var> is a parser object, it uses that parser; if
+<var>parser-or-lang</var> is a language, it finds the first parser using
+that language in <code>(treesit-parser-list)</code>, and uses that.
+</p>
+<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node
+only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-parser-root-node</strong> <em>parser</em><a href='#index-treesit_002dparser_002droot_002dnode' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the root node of the syntax tree generated by
+<var>parser</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dbuffer_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-buffer-root-node</strong> <em>&amp;optional language</em><a href='#index-treesit_002dbuffer_002droot_002dnode' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the first parser that uses <var>language</var> in
+<code>(treesit-parser-list)</code> of the current buffer, and returns the
+root node generated by that parser.  If it cannot find an appropriate
+parser, it returns <code>nil</code>.
+</p></dd></dl>
+
+<p>Given a node, a Lisp program can retrieve other nodes starting from
+it, or query for information about this node.
+</p>
+<span id="Retrieving-node-from-other-nodes"></span><h3 class="heading">Retrieving node from other nodes</h3>
+<span id="index-syntax-tree-nodes_002c-retrieving-from-other-nodes"></span>
+
+<span id="By-kinship"></span><h4 class="subheading">By kinship</h4>
+<span id="index-kinship_002c-syntax-tree-nodes"></span>
+<span id="index-nodes_002c-by-kinship"></span>
+<span id="index-syntax-tree-nodes_002c-by-kinship"></span>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dparent"><span class="category">Function: </span><span><strong>treesit-node-parent</strong> <em>node</em><a href='#index-treesit_002dnode_002dparent' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the immediate parent of <var>node</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dchild"><span class="category">Function: </span><span><strong>treesit-node-child</strong> <em>node n &amp;optional named</em><a href='#index-treesit_002dnode_002dchild' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the <var>n</var>&rsquo;th child of <var>node</var>.  If
+<var>named</var> is non-<code>nil</code>, it counts only named nodes
+(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p>
+<p>For example, in a node that represents a string <code>&quot;text&quot;</code>, there
+are three children nodes: the opening quote <code>&quot;</code>, the string text
+<code>text</code>, and the closing quote <code>&quot;</code>.  Among these nodes, the
+first child is the opening quote <code>&quot;</code>, and the first named child
+is the string text.
+</p>
+<p>This function returns <code>nil</code> if there is no <var>n</var>&rsquo;th child.
+<var>n</var> could be negative, e.g., <code>-1</code> represents the last child.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dchildren"><span class="category">Function: </span><span><strong>treesit-node-children</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnode_002dchildren' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns all of <var>node</var>&rsquo;s children as a list.  If
+<var>named</var> is non-<code>nil</code>, it retrieves only named nodes.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnext_002dsibling"><span class="category">Function: </span><span><strong>treesit-node-next-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnext_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the next sibling of <var>node</var>.  If <var>named</var> is
+non-<code>nil</code>, it finds the next named sibling.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dprev_002dsibling"><span class="category">Function: </span><span><strong>treesit-node-prev-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dprev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the previous sibling of <var>node</var>.  If
+<var>named</var> is non-<code>nil</code>, it finds the previous named sibling.
+</p></dd></dl>
+
+<span id="By-field-name"></span><h4 class="subheading">By field name</h4>
+<span id="index-nodes_002c-by-field-name"></span>
+<span id="index-syntax-tree-nodes_002c-by-field-name"></span>
+
+<p>To make the syntax tree easier to analyze, many language definitions
+assign <em>field names</em> to child nodes (see <a href="Language-Definitions.html#tree_002dsitter-node-field-name">field name</a>).  For example, a <code>function_definition</code> node
+could have a <code>declarator</code> node and a <code>body</code> node.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dchild_002dby_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-node-child-by-field-name</strong> <em>node field-name</em><a href='#index-treesit_002dchild_002dby_002dfield_002dname' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the child of <var>node</var> whose field name is
+<var>field-name</var>, a string.
+</p>
+<div class="example">
+<pre class="example">;; Get the child that has &quot;body&quot; as its field name.
+(treesit-node-child-by-field-name node &quot;body&quot;)
+  &rArr; #&lt;treesit-node (compound_statement) in 45-89&gt;
+</pre></div>
+</dd></dl>
+
+<span id="By-position"></span><h4 class="subheading">By position</h4>
+<span id="index-nodes_002c-by-position"></span>
+<span id="index-syntax-tree-nodes_002c-by-position"></span>
+
+<dl class="def">
+<dt id="index-treesit_002dfirst_002dchild_002dfor_002dpos"><span class="category">Function: </span><span><strong>treesit-node-first-child-for-pos</strong> <em>node pos &amp;optional named</em><a href='#index-treesit_002dfirst_002dchild_002dfor_002dpos' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the first child of <var>node</var> that extends beyond
+buffer position <var>pos</var>.  &ldquo;Extends beyond&rdquo; means the end of the
+child node is greater or equal to <var>pos</var>.  This function only looks
+for immediate children of <var>node</var>, and doesn&rsquo;t look in its
+grandchildren.  If <var>named</var> is non-<code>nil</code>, it looks for the
+first named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002ddescendant_002dfor_002drange"><span class="category">Function: </span><span><strong>treesit-node-descendant-for-range</strong> <em>node beg end &amp;optional named</em><a href='#index-treesit_002dnode_002ddescendant_002dfor_002drange' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds the <em>smallest</em> descendant node of <var>node</var>
+that spans the region of text between positions <var>beg</var> and
+<var>end</var>.  It is similar to <code>treesit-node-at</code>.  If <var>named</var>
+is non-<code>nil</code>, it looks for smallest named child.
+</p></dd></dl>
+
+<span id="Searching-for-node"></span><h3 class="heading">Searching for node</h3>
+
+<dl class="def">
+<dt id="index-treesit_002dsearch_002dsubtree"><span class="category">Function: </span><span><strong>treesit-search-subtree</strong> <em>node predicate &amp;optional backward all limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function traverses the subtree of <var>node</var> (including
+<var>node</var> itself), looking for a node for which <var>predicate</var>
+returns non-<code>nil</code>.  <var>predicate</var> is a regexp that is matched
+against each node&rsquo;s type, or a predicate function that takes a node
+and returns non-<code>nil</code> if the node matches.  The function returns
+the first node that matches, or <code>nil</code> if none does.
+</p>
+<p>By default, this function only traverses named nodes, but if <var>all</var>
+is non-<code>nil</code>, it traverses all the nodes.  If <var>backward</var> is
+non-<code>nil</code>, it traverses backwards (i.e., it visits the last child first
+when traversing down the tree).  If <var>limit</var> is non-<code>nil</code>, it
+must be a number that limits the tree traversal to that many levels
+down the tree.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dsearch_002dforward"><span class="category">Function: </span><span><strong>treesit-search-forward</strong> <em>start predicate &amp;optional backward all</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Like <code>treesit-search-subtree</code>, this function also traverses the
+parse tree and matches each node with <var>predicate</var> (except for
+<var>start</var>), where <var>predicate</var> can be a regexp or a function.
+For a tree like the below where <var>start</var> is marked S, this function
+traverses as numbered from 1 to 12:
+</p>
+<div class="example">
+<pre class="example">              12
+              |
+     S--------3----------11
+     |        |          |
+o--o-+--o  1--+--2    6--+-----10
+|  |                  |        |
+o  o                +-+-+   +--+--+
+                    |   |   |  |  |
+                    4   5   7  8  9
+</pre></div>
+
+<p>Note that this function doesn&rsquo;t traverse the subtree of <var>start</var>,
+and it always traverse leaf nodes first, then upwards.
+</p>
+<p>Like <code>treesit-search-subtree</code>, this function only searches for
+named nodes by default, but if <var>all</var> is non-<code>nil</code>, it
+searches for all nodes.  If <var>backward</var> is non-<code>nil</code>, it
+searches backwards.
+</p>
+<p>While <code>treesit-search-subtree</code> traverses the subtree of a node,
+this function starts with node <var>start</var> and traverses every node
+that comes after it in the buffer position order, i.e., nodes with
+start positions greater than the end position of <var>start</var>.
+</p>
+<p>In the tree shown above, <code>treesit-search-subtree</code> traverses node
+S (<var>start</var>) and nodes marked with <code>o</code>, where this function
+traverses the nodes marked with numbers.  This function is useful for
+answering questions like &ldquo;what is the first node after <var>start</var> in
+the buffer that satisfies some condition?&rdquo;
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dsearch_002dforward_002dgoto"><span class="category">Function: </span><span><strong>treesit-search-forward-goto</strong> <em>node predicate &amp;optional start backward all</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function moves point to the start or end of the next node after
+<var>node</var> in the buffer that matches <var>predicate</var>.  If <var>start</var>
+is non-<code>nil</code>, stop at the beginning rather than the end of a node.
+</p>
+<p>This function guarantees that the matched node it returns makes
+progress in terms of buffer position: the start/end position of the
+returned node is always greater than that of <var>node</var>.
+</p>
+<p>Arguments <var>predicate</var>, <var>backward</var> and <var>all</var> are the same
+as in <code>treesit-search-forward</code>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dinduce_002dsparse_002dtree"><span class="category">Function: </span><span><strong>treesit-induce-sparse-tree</strong> <em>root predicate &amp;optional process-fn limit</em><a href='#index-treesit_002dinduce_002dsparse_002dtree' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function creates a sparse tree from <var>root</var>&rsquo;s subtree.
+</p>
+<p>It takes the subtree under <var>root</var>, and combs it so only the nodes
+that match <var>predicate</var> are left.  Like previous functions, the
+<var>predicate</var> can be a regexp string that matches against each
+node&rsquo;s type, or a function that takes a node and return non-<code>nil</code>
+if it matches.
+</p>
+<p>For example, for a subtree on the left that consist of both numbers
+and letters, if <var>predicate</var> is &ldquo;letter only&rdquo;, the returned tree
+is the one on the right.
+</p>
+<div class="example">
+<pre class="example">    a                 a              a
+    |                 |              |
++---+---+         +---+---+      +---+---+
+|   |   |         |   |   |      |   |   |
+b   1   2         b   |   |      b   c   d
+    |   |     =&gt;      |   |  =&gt;      |
+    c   +--+          c   +          e
+    |   |  |          |   |
+ +--+   d  4       +--+   d
+ |  |              |
+ e  5              e
+</pre></div>
+
+<p>If <var>process-fn</var> is non-<code>nil</code>, instead of returning the matched
+nodes, this function passes each node to <var>process-fn</var> and uses the
+returned value instead.  If non-<code>nil</code>, <var>limit</var> is the number of
+levels to go down from <var>root</var>.
+</p>
+<p>Each node in the returned tree looks like
+<code>(<var><span class="nolinebreak">tree-sitter-node</span></var>&nbsp;.&nbsp;(<var>child</var>&nbsp;&hellip;))</code><!-- /@w -->.  The
+<var>tree-sitter-node</var> of the root of this tree will be nil if
+<var>root</var> doesn&rsquo;t match <var>predicate</var>.  If no node matches
+<var>predicate</var>, the function returns <code>nil</code>.
+</p></dd></dl>
+
+<span id="More-convenience-functions"></span><h3 class="heading">More convenience functions</h3>
+
+<dl class="def">
+<dt id="index-treesit_002dfilter_002dchild"><span class="category">Function: </span><span><strong>treesit-filter-child</strong> <em>node predicate &amp;optional named</em><a href='#index-treesit_002dfilter_002dchild' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function finds immediate children of <var>node</var> that satisfy
+<var>predicate</var>.
+</p>
+<p>The <var>predicate</var> function takes a node as the argument and should
+return non-<code>nil</code> to indicate that the node should be kept.  If
+<var>named</var> is non-<code>nil</code>, this function only examines the named
+nodes.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparent_002duntil"><span class="category">Function: </span><span><strong>treesit-parent-until</strong> <em>node predicate</em><a href='#index-treesit_002dparent_002duntil' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function repeatedly finds the parents of <var>node</var>, and returns
+the parent that satisfies <var>predicate</var>, a function that takes a
+node as the argument.  If no parent satisfies <var>predicate</var>, this
+function returns <code>nil</code>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparent_002dwhile"><span class="category">Function: </span><span><strong>treesit-parent-while</strong> <em>node predicate</em><a href='#index-treesit_002dparent_002dwhile' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function repeatedly finds the parent of <var>node</var>, and keeps
+doing so as long as the nodes satisfy <var>predicate</var>, a function that
+takes a node as the argument.  That is, this function returns the
+farthest parent that still satisfies <var>predicate</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dnode_002dtop_002dlevel"><span class="category">Function: </span><span><strong>treesit-node-top-level</strong> <em>node &amp;optional type</em><a href='#index-treesit_002dnode_002dtop_002dlevel' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the highest parent of <var>node</var> that has the
+same type as <var>node</var>.  If no such parent exists, it returns
+<code>nil</code>.  Therefore this function is also useful for testing
+whether <var>node</var> is top-level.
+</p>
+<p>If <var>type</var> is non-<code>nil</code>, this function matches each parent&rsquo;s
+type with <var>type</var> as a regexp, rather than using <var>node</var>&rsquo;s type.
+</p></dd></dl>
+
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Accessing-Node-Information.html">Accessing Node Information</a>, Previous: <a href="Using-Parser.html">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html

@@ -0,0 +1,211 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Tree-sitter C API (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Tree-sitter C API (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Tree-sitter C API (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Tree_002dsitter-major-modes.html" rel="prev" title="Tree-sitter major modes">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Tree_002dsitter-C-API">
+<div class="header">
+<p>
+Previous: <a href="Tree_002dsitter-major-modes.html" accesskey="p" rel="prev">Developing major modes with tree-sitter</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Tree_002dsitter-C-API-Correspondence"></span><h3 class="section">37.8 Tree-sitter C API Correspondence</h3>
+
+<p>Emacs&rsquo; tree-sitter integration doesn&rsquo;t expose every feature
+provided by tree-sitter&rsquo;s C API.  Missing features include:
+</p>
+<ul>
+<li> Creating a tree cursor and navigating the syntax tree with it.
+</li><li> Setting timeout and cancellation flag for a parser.
+</li><li> Setting the logger for a parser.
+</li><li> Printing a <acronym>DOT</acronym> graph of the syntax tree to a file.
+</li><li> Copying and modifying a syntax tree.  (Emacs doesn&rsquo;t expose a tree
+object.)
+</li><li> Using (row, column) coordinates as position.
+</li><li> Updating a node with changes.  (In Emacs, retrieve a new node instead
+of updating the existing one.)
+</li><li> Querying statics of a language definition.
+</li></ul>
+
+<p>In addition, Emacs makes some changes to the C API to make the API more
+convenient and idiomatic:
+</p>
+<ul>
+<li> Instead of using byte positions, the Emacs Lisp API uses character
+positions.
+</li><li> Null nodes are converted to nil.
+</li></ul>
+
+<p>Below is the correspondence between all C API functions and their
+ELisp counterparts.  Sometimes one ELisp function corresponds to
+multiple C functions, and many C functions don&rsquo;t have an ELisp
+counterpart.
+</p>
+<div class="example">
+<pre class="example">ts_parser_new                           treesit-parser-create
+ts_parser_delete
+ts_parser_set_language
+ts_parser_language                      treesit-parser-language
+ts_parser_set_included_ranges           treesit-parser-set-included-ranges
+ts_parser_included_ranges               treesit-parser-included-ranges
+ts_parser_parse
+ts_parser_parse_string                  treesit-parse-string
+ts_parser_parse_string_encoding
+ts_parser_reset
+ts_parser_set_timeout_micros
+ts_parser_timeout_micros
+ts_parser_set_cancellation_flag
+ts_parser_cancellation_flag
+ts_parser_set_logger
+ts_parser_logger
+ts_parser_print_dot_graphs
+ts_tree_copy
+ts_tree_delete
+ts_tree_root_node
+ts_tree_language
+ts_tree_edit
+ts_tree_get_changed_ranges
+ts_tree_print_dot_graph
+ts_node_type                            treesit-node-type
+ts_node_symbol
+ts_node_start_byte                      treesit-node-start
+ts_node_start_point
+ts_node_end_byte                        treesit-node-end
+ts_node_end_point
+ts_node_string                          treesit-node-string
+ts_node_is_null
+ts_node_is_named                        treesit-node-check
+ts_node_is_missing                      treesit-node-check
+ts_node_is_extra                        treesit-node-check
+ts_node_has_changes
+ts_node_has_error                       treesit-node-check
+ts_node_parent                          treesit-node-parent
+ts_node_child                           treesit-node-child
+ts_node_field_name_for_child            treesit-node-field-name-for-child
+ts_node_child_count                     treesit-node-child-count
+ts_node_named_child                     treesit-node-child
+ts_node_named_child_count               treesit-node-child-count
+ts_node_child_by_field_name             treesit-node-by-field-name
+ts_node_child_by_field_id
+ts_node_next_sibling                    treesit-node-next-sibling
+ts_node_prev_sibling                    treesit-node-prev-sibling
+ts_node_next_named_sibling              treesit-node-next-sibling
+ts_node_prev_named_sibling              treesit-node-prev-sibling
+ts_node_first_child_for_byte            treesit-node-first-child-for-pos
+ts_node_first_named_child_for_byte      treesit-node-first-child-for-pos
+ts_node_descendant_for_byte_range       treesit-descendant-for-range
+ts_node_descendant_for_point_range
+ts_node_named_descendant_for_byte_range treesit-descendant-for-range
+ts_node_named_descendant_for_point_range
+ts_node_edit
+ts_node_eq                              treesit-node-eq
+ts_tree_cursor_new
+ts_tree_cursor_delete
+ts_tree_cursor_reset
+ts_tree_cursor_current_node
+ts_tree_cursor_current_field_name
+ts_tree_cursor_current_field_id
+ts_tree_cursor_goto_parent
+ts_tree_cursor_goto_next_sibling
+ts_tree_cursor_goto_first_child
+ts_tree_cursor_goto_first_child_for_byte
+ts_tree_cursor_goto_first_child_for_point
+ts_tree_cursor_copy
+ts_query_new
+ts_query_delete
+ts_query_pattern_count
+ts_query_capture_count
+ts_query_string_count
+ts_query_start_byte_for_pattern
+ts_query_predicates_for_pattern
+ts_query_step_is_definite
+ts_query_capture_name_for_id
+ts_query_string_value_for_id
+ts_query_disable_capture
+ts_query_disable_pattern
+ts_query_cursor_new
+ts_query_cursor_delete
+ts_query_cursor_exec                    treesit-query-capture
+ts_query_cursor_did_exceed_match_limit
+ts_query_cursor_match_limit
+ts_query_cursor_set_match_limit
+ts_query_cursor_set_byte_range
+ts_query_cursor_set_point_range
+ts_query_cursor_next_match
+ts_query_cursor_remove_match
+ts_query_cursor_next_capture
+ts_language_symbol_count
+ts_language_symbol_name
+ts_language_symbol_for_name
+ts_language_field_count
+ts_language_field_name_for_id
+ts_language_field_id_for_name
+ts_language_symbol_type
+ts_language_version
+</pre></div>
+</div>
+<hr>
+<div class="header">
+<p>
+Previous: <a href="Tree_002dsitter-major-modes.html">Developing major modes with tree-sitter</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/Using-Parser.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<!-- This is the GNU Emacs Lisp Reference Manual
+corresponding to Emacs version 29.0.50.
+
+Copyright © 1990-1996, 1998-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License," with the
+Front-Cover Texts being "A GNU Manual," and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License."
+
+(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom." -->
+<title>Using Parser (GNU Emacs Lisp Reference Manual)</title>
+
+<meta name="description" content="Using Parser (GNU Emacs Lisp Reference Manual)">
+<meta name="keywords" content="Using Parser (GNU Emacs Lisp Reference Manual)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+<link href="index.html" rel="start" title="Top">
+<link href="Index.html" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
+<link href="Retrieving-Nodes.html" rel="next" title="Retrieving Nodes">
+<link href="Language-Definitions.html" rel="prev" title="Language Definitions">
+<style type="text/css">
+<!--
+a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+span:hover a.copiable-anchor {visibility: visible}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="./manual.css">
+
+
+</head>
+
+<body lang="en">
+<div class="section" id="Using-Parser">
+<div class="header">
+<p>
+Next: <a href="Retrieving-Nodes.html" accesskey="n" rel="next">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html" accesskey="p" rel="prev">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<span id="Using-Tree_002dsitter-Parser"></span><h3 class="section">37.2 Using Tree-sitter Parser</h3>
+<span id="index-tree_002dsitter-parser_002c-using"></span>
+
+<p>This section describes how to create and configure a tree-sitter
+parser.  In Emacs, each tree-sitter parser is associated with a
+buffer.  As the user edits the buffer, the associated parser and
+syntax tree are automatically kept up-to-date.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dmax_002dbuffer_002dsize"><span class="category">Variable: </span><span><strong>treesit-max-buffer-size</strong><a href='#index-treesit_002dmax_002dbuffer_002dsize' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This variable contains the maximum size of buffers in which
+tree-sitter can be activated.  Major modes should check this value
+when deciding whether to enable tree-sitter features.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dcan_002denable_002dp"><span class="category">Function: </span><span><strong>treesit-can-enable-p</strong><a href='#index-treesit_002dcan_002denable_002dp' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function checks whether the current buffer is suitable for
+activating tree-sitter features.  It basically checks
+<code>treesit-available-p</code> and <code>treesit-max-buffer-size</code>.
+</p></dd></dl>
+
+<span id="index-creating-tree_002dsitter-parsers"></span>
+<span id="index-tree_002dsitter-parser_002c-creating"></span>
+<dl class="def">
+<dt id="index-treesit_002dparser_002dcreate"><span class="category">Function: </span><span><strong>treesit-parser-create</strong> <em>language &amp;optional buffer no-reuse</em><a href='#index-treesit_002dparser_002dcreate' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>Create a parser for the specified <var>buffer</var> and <var>language</var>
+(see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>).  If <var>buffer</var> is omitted or
+<code>nil</code>, it stands for the current buffer.
+</p>
+<p>By default, this function reuses a parser if one already exists for
+<var>language</var> in <var>buffer</var>, but if <var>no-reuse</var> is
+non-<code>nil</code>, this function always creates a new parser.
+</p></dd></dl>
+
+<p>Given a parser, we can query information about it.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dparser_002dbuffer"><span class="category">Function: </span><span><strong>treesit-parser-buffer</strong> <em>parser</em><a href='#index-treesit_002dparser_002dbuffer' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the buffer associated with <var>parser</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dlanguage"><span class="category">Function: </span><span><strong>treesit-parser-language</strong> <em>parser</em><a href='#index-treesit_002dparser_002dlanguage' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the language used by <var>parser</var>.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dp"><span class="category">Function: </span><span><strong>treesit-parser-p</strong> <em>object</em><a href='#index-treesit_002dparser_002dp' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function checks if <var>object</var> is a tree-sitter parser, and
+returns non-<code>nil</code> if it is, and <code>nil</code> otherwise.
+</p></dd></dl>
+
+<p>There is no need to explicitly parse a buffer, because parsing is done
+automatically and lazily.  A parser only parses when a Lisp program
+queries for a node in its syntax tree.  Therefore, when a parser is
+first created, it doesn&rsquo;t parse the buffer; it waits until the Lisp
+program queries for a node for the first time.  Similarly, when some
+change is made in the buffer, a parser doesn&rsquo;t re-parse immediately.
+</p>
+<span id="index-treesit_002dbuffer_002dtoo_002dlarge"></span>
+<p>When a parser does parse, it checks for the size of the buffer.
+Tree-sitter can only handle buffer no larger than about 4GB.  If the
+size exceeds that, Emacs signals the <code>treesit-buffer-too-large</code>
+error with signal data being the buffer size.
+</p>
+<p>Once a parser is created, Emacs automatically adds it to the
+internal parser list.  Every time a change is made to the buffer,
+Emacs updates parsers in this list so they can update their syntax
+tree incrementally.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dparser_002dlist"><span class="category">Function: </span><span><strong>treesit-parser-list</strong> <em>&amp;optional buffer</em><a href='#index-treesit_002dparser_002dlist' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the parser list of <var>buffer</var>.  If
+<var>buffer</var> is <code>nil</code> or omitted, it defaults to the current
+buffer.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002ddelete"><span class="category">Function: </span><span><strong>treesit-parser-delete</strong> <em>parser</em><a href='#index-treesit_002dparser_002ddelete' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function deletes <var>parser</var>.
+</p></dd></dl>
+
+<span id="index-tree_002dsitter-narrowing"></span>
+<span id="tree_002dsitter-narrowing"></span><p>Normally, a parser &ldquo;sees&rdquo; the whole buffer, but when the buffer is
+narrowed (see <a href="Narrowing.html">Narrowing</a>), the parser will only see the accessible
+portion of the buffer.  As far as the parser can tell, the hidden
+region was deleted.  When the buffer is later widened, the parser
+thinks text is inserted at the beginning and at the end.  Although
+parsers respect narrowing, modes should not use narrowing as a means
+to handle a multi-language buffer; instead, set the ranges in which the
+parser should operate.  See <a href="Multiple-Languages.html">Parsing Text in Multiple Languages</a>.
+</p>
+<p>Because a parser parses lazily, when the user or a Lisp program
+narrows the buffer, the parser is not affected immediately; as long as
+the mode doesn&rsquo;t query for a node while the buffer is narrowed, the
+parser is oblivious of the narrowing.
+</p>
+<span id="index-tree_002dsitter-parse-string"></span>
+<span id="index-parse-string_002c-tree_002dsitter"></span>
+<p>Besides creating a parser for a buffer, a Lisp program can also parse a
+string.  Unlike a buffer, parsing a string is a one-off operation, and
+there is no way to update the result.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dparse_002dstring"><span class="category">Function: </span><span><strong>treesit-parse-string</strong> <em>string language</em><a href='#index-treesit_002dparse_002dstring' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function parses <var>string</var> using <var>language</var>, and returns
+the root node of the generated syntax tree.
+</p></dd></dl>
+
+<span id="Be-notified-by-changes-to-the-parse-tree"></span><h3 class="heading">Be notified by changes to the parse tree</h3>
+<span id="index-update-callback_002c-for-tree_002dsitter-parse_002dtree"></span>
+<span id="index-after_002dchange-notifier_002c-for-tree_002dsitter-parse_002dtree"></span>
+<span id="index-tree_002dsitter-parse_002dtree_002c-update-and-after_002dchange-callback"></span>
+<span id="index-notifiers_002c-tree_002dsitter"></span>
+
+<p>A Lisp program might want to be notified of text affected by
+incremental parsing.  For example, inserting a comment-closing token
+converts text before that token into a comment.  Even
+though the text is not directly edited, it is deemed to be &ldquo;changed&rdquo;
+nevertheless.
+</p>
+<p>Emacs lets a Lisp program to register callback functions
+(a.k.a. <em>notifiers</em>) for this kind of changes.  A notifier
+function takes two arguments: <var>ranges</var> and <var>parser</var>.
+<var>ranges</var> is a list of cons cells of the form <code>(<var>start</var>&nbsp;.&nbsp;<var>end</var>)</code><!-- /@w -->, where <var>start</var> and <var>end</var> mark the start and the
+end positions of a range.  <var>parser</var> is the parser issuing the
+notification.
+</p>
+<p>Every time a parser reparses a buffer, it compares the old and new
+parse-tree, computes the ranges in which nodes have changed, and
+passes the ranges to notifier functions.
+</p>
+<dl class="def">
+<dt id="index-treesit_002dparser_002dadd_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-add-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dadd_002dnotifier' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function adds <var>function</var> to <var>parser</var>&rsquo;s list of
+after-change notifier functions.  <var>function</var> must be a function
+symbol, not a lambda function (see <a href="Anonymous-Functions.html">Anonymous Functions</a>).
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dremove_002dnotifier"><span class="category">Function: </span><span><strong>treesit-parser-remove-notifier</strong> <em>parser function</em><a href='#index-treesit_002dparser_002dremove_002dnotifier' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function removes <var>function</var> from the list of <var>parser</var>&rsquo;s
+after-change notifier functions.  <var>function</var> must be a function
+symbol, rather than a lambda function.
+</p></dd></dl>
+
+<dl class="def">
+<dt id="index-treesit_002dparser_002dnotifiers"><span class="category">Function: </span><span><strong>treesit-parser-notifiers</strong> <em>parser</em><a href='#index-treesit_002dparser_002dnotifiers' class='copiable-anchor'> &para;</a></span></dt>
+<dd><p>This function returns the list of <var>parser</var>&rsquo;s notifier functions.
+</p></dd></dl>
+
+</div>
+<hr>
+<div class="header">
+<p>
+Next: <a href="Retrieving-Nodes.html">Retrieving Nodes</a>, Previous: <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>

admin/notes/tree-sitter/html-manual/build-manual.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+MANUAL_DIR="../../../../doc/lispref"
+THIS_DIR=$(pwd)
+
+echo "Build manual"
+cd "${MANUAL_DIR}"
+make elisp.html HTML_OPTS="--html --css-ref=./manual.css"
+
+cd "${THIS_DIR}"
+
+echo "Copy manual"
+cp -f "${MANUAL_DIR}/elisp.html/Parsing-Program-Source.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Language-Definitions.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Using-Parser.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Retrieving-Node.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Accessing-Node.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Pattern-Matching.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Multiple-Languages.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Tree_002dsitter-C-API.html" .
+
+cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Font-Lock.html" .
+cp -f "${MANUAL_DIR}/elisp.html/Parser_002dbased-Indentation.html" .

admin/notes/tree-sitter/html-manual/manual.css

@@ -0,0 +1,374 @@
+/* Style-sheet to use for Emacs manuals  */
+
+/* Copyright (C) 2013-2014, 2023 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.
+*/
+
+/* style.css begins here */
+
+/* This stylesheet is used by manuals and a few older resources. */
+
+/* reset.css begins here */
+
+/*
+Software License Agreement (BSD License)
+
+Copyright (c) 2006, Yahoo! Inc.
+All rights reserved.
+
+Redistribution and use of this software in source and
+binary forms, with or without modification, arepermitted
+provided that the following conditions are met:
+
+* Redistributions of source code must retain the above
+copyright notice, this list of conditions and the
+following disclaimer.
+
+* Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the
+following disclaimer in the documentation and/or other
+materials provided with the distribution.
+
+* Neither the name of Yahoo! Inc. nor the names of its
+contributors may be used to endorse or promote products
+derived from this software without specific prior
+written permission of Yahoo! Inc.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+*/
+
+html {
+    color: #000;
+    background: #FFF;
+}
+
+body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4,
+h5, h6, pre, code, form, fieldset, legend, input,
+button, textarea, p, blockquote, th, td {
+    margin: 0;
+    padding: 0;
+}
+
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+
+fieldset, img {
+    border: 0;
+}
+
+address, caption, cite, code, dfn, em, strong,
+th, var, optgroup {
+    font-style: inherit;
+    font-weight: inherit;
+}
+
+del, ins {
+    text-decoration: none;
+}
+
+li {
+    list-style:none;
+}
+
+caption, th {
+    text-align: left;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-size: 100%;
+    font-weight: normal;
+}
+
+q:before, q:after {
+    content:'';
+}
+
+abbr, acronym {
+    border: 0;
+    font-variant: normal;
+}
+
+sup {
+    vertical-align: baseline;
+}
+sub {
+    vertical-align: baseline;
+}
+
+legend {
+    color: #000;
+}
+
+input, button, textarea, select, optgroup, option {
+    font-family: inherit;
+    font-size: inherit;
+    font-style: inherit;
+    font-weight: inherit;
+}
+
+input, button, textarea, select {
+    *font-size: 100%;
+}
+
+
+/* reset.css ends here */
+
+/***  PAGE LAYOUT  ***/
+
+html, body {
+    font-size: 1em;
+    text-align: left;
+    text-decoration: none;
+}
+html { background-color: #e7e7e7; }
+
+body {
+    max-width: 74.92em;
+    margin: 0 auto;
+    padding: .5em 1em 1em 1em;
+    background-color: white;
+    border: .1em solid #c0c0c0;
+}
+
+
+/*** BASIC ELEMENTS ***/
+
+/* Size and positioning */
+
+p, pre, li, dt, dd, table, code, address { line-height: 1.3em; }
+
+h1 { font-size: 2em; margin: 1em 0 }
+h2 { font-size: 1.50em; margin: 1.0em 0 0.87em 0; }
+h3 { font-size: 1.30em; margin: 1.0em 0 0.87em 0; }
+h4 { font-size: 1.13em; margin: 1.0em 0 0.88em 0; }
+h5 { font-size: 1.00em; margin: 1.0em 0 1.00em 0; }
+
+p, pre { margin: 1em 0; }
+pre { overflow: auto; padding-bottom: .3em; }
+
+ul, ol, blockquote { margin-left: 1.5%; margin-right: 1.5%; }
+hr { margin: 1em 0; }
+/* Lists of underlined links are difficult to read. The top margin
+   gives a little more spacing between entries. */
+ul li { margin: .5em 1em; }
+ol li { margin: 1em; }
+ol ul li { margin: .5em 1em; }
+ul li p, ul ul li { margin-top: .3em; margin-bottom: .3em; }
+ul ul, ol ul { margin-top: 0; margin-bottom: 0; }
+
+/* Separate description lists from preceding text */
+dl { margin: 1em 0 0 0; }
+/* separate the "term" from subsequent "description" */
+dt { margin: .5em 0; }
+/* separate the "description" from subsequent list item
+   when the final <dd> child is an anonymous box */
+dd { margin: .5em 3% 1em 3%; }
+/* separate anonymous box (used to be the first element in <dd>)
+   from subsequent <p> */
+dd p { margin: .5em 0; }
+
+table {
+    display: block; overflow: auto;
+    margin-top: 1.5em; margin-bottom: 1.5em;
+}
+th { padding: .3em .5em; text-align: center; }
+td { padding: .2em .5em; }
+
+address { margin-bottom: 1em; }
+caption { margin-bottom: .5em; text-align: center; }
+sup { vertical-align: super; }
+sub { vertical-align: sub; }
+
+/* Style */
+
+h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; }
+
+/* The default color (black) is too dark for large text in
+   bold font. */
+h1, h2, h3, h4 { color: #333; }
+h5, h6, dt { color: #222; }
+
+a[href] { color: #005090; }
+a[href]:visited { color: #100070; }
+a[href]:active, a[href]:hover {
+    color: #100070;
+    text-decoration: none;
+}
+
+h1 a[href]:visited, h2 a[href]:visited, h3 a[href]:visited,
+h4 a[href]:visited { color: #005090; }
+h1 a[href]:hover, h2 a[href]:hover, h3 a[href]:hover,
+h4 a[href]:hover { color: #100070; }
+
+ol { list-style: decimal outside;}
+ul { list-style: square outside; }
+ul ul, ol ul { list-style: circle; }
+li { list-style: inherit; }
+
+hr { background-color: #ede6d5; }
+table { border: 0; }
+
+abbr,acronym {
+    border-bottom:1px dotted #000;
+    text-decoration: none;
+    cursor:help;
+}
+del { text-decoration: line-through; }
+em { font-style: italic; }
+small { font-size: .9em; }
+
+img { max-width: 100%}
+
+
+/*** SIMPLE CLASSES ***/
+
+.center, .c { text-align: center; }
+.nocenter{ text-align: left; }
+
+.underline { text-decoration: underline; }
+.nounderline { text-decoration: none; }
+
+.no-bullet { list-style: none; }
+.inline-list li { display: inline }
+
+.netscape4, .no-display { display: none; }
+
+
+/*** MANUAL PAGES ***/
+
+/* This makes the very long tables of contents in Gnulib and other
+   manuals easier to read. */
+.contents ul, .shortcontents ul { font-weight: bold; }
+.contents ul ul, .shortcontents ul ul { font-weight: normal; }
+.contents ul { list-style: none; }
+
+/* For colored navigation bars (Emacs manual): make the bar extend
+   across the whole width of the page and give it a decent height. */
+.header, .node { margin: 0 -1em; padding: 0 1em; }
+.header p, .node p { line-height: 2em; }
+
+/* For navigation links */
+.node a, .header a { display: inline-block; line-height: 2em; }
+.node a:hover, .header a:hover { background: #f2efe4; }
+
+/* Inserts */
+table.cartouche td { padding: 1.5em; }
+
+div.display, div.lisp, div.smalldisplay,
+div.smallexample, div.smalllisp { margin-left: 3%; }
+
+div.example { padding: .8em 1.2em .4em; }
+pre.example { padding: .8em 1.2em; }
+div.example, pre.example {
+    margin: 1em 0 1em 3% ;
+    -webkit-border-radius: .3em;
+    -moz-border-radius: .3em;
+    border-radius: .3em;
+    border: 1px solid #d4cbb6;
+    background-color: #f2efe4;
+}
+div.example > pre.example {
+    padding: 0 0 .4em;
+    margin: 0;
+    border: none;
+}
+
+pre.menu-comment { padding-top: 1.3em; margin: 0; }
+
+
+/*** FOR WIDE SCREENS ***/
+
+@media (min-width: 40em) {
+    body { padding: .5em 3em 1em 3em; }
+    div.header, div.node { margin: 0 -3em; padding: 0 3em; }
+}
+
+/* style.css ends here */
+
+/* makeinfo convert @deffn and similar functions to something inside
+   <blockquote>.  style.css uses italic for blockquote.  This looks poor
+   in the Emacs manuals, which make extensive use of @defun (etc).
+   In particular, references to function arguments appear as <var>
+   inside <blockquote>.  Since <var> is also italic, it makes it
+   impossible to distinguish variables.  We could change <var> to
+   e.g. bold-italic, or normal, or a different color, but that does
+   not look as good IMO.  So we just override blockquote to be non-italic.
+   */
+blockquote { font-style: normal; }
+
+var { font-style: italic; }
+
+div.header {
+    background-color: #DDDDFF;
+    padding-top: 0.2em;
+}
+
+
+/*** Customization ***/
+
+body {
+    font-family: Charter, serif;
+    font-size: 14pt;
+    line-height: 1.4;
+    background-color: #fefefc;
+    color: #202010;
+}
+
+pre.menu-comment {
+    font-family: Charter, serif;
+    font-size: 14pt;
+}
+
+body > *, body > div.display, body > div.lisp, body > div.smalldisplay,
+body > div.example, body > div.smallexample, body > div.smalllisp {
+    width: 700px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+div.header {
+    width: 100%;
+    min-height: 3em;
+    font-size: 13pt;
+}
+
+/* Documentation block for functions and variables. Make then
+   narrower*/
+dd {
+    margin: .5em 6% 1em 6%
+}
+
+code, pre, kbd, samp, tt {
+    font-size: 12pt;
+    font-family: monospace;
+}
+
+/* In each node we have index table to all sub-nodes. Make more space
+   for the first column, which is the name to each sub-node. */
+table.menu tbody tr td:nth-child(1) {
+    white-space: nowrap;
+}
+
+div.header p {
+    text-align: center;
+    margin: 0.5em auto 0.5em auto;
+}

admin/notes/tree-sitter/starter-guide

@@ -17,7 +17,6 @@ TOC:
 - More features?
 - Common tasks (code snippets)
 - Manual
-- Appendix 1
 
 * Building Emacs with tree-sitter
 
@@ -43,9 +42,11 @@ You can use this script that I put together here:
 
     https://github.com/casouri/tree-sitter-module
 
+You can also find them under this directory in /build-modules.
+
 This script automatically pulls and builds language definitions for C,
-C++, Rust, JSON, Go, HTML, JavaScript, CSS, Python, Typescript,
-C#, etc. Better yet, I pre-built these language definitions for
+C++, Rust, JSON, Go, HTML, Javascript, CSS, Python, Typescript,
+and C#. Better yet, I pre-built these language definitions for
 GNU/Linux and macOS, they can be downloaded here:
 
     https://github.com/casouri/tree-sitter-module/releases/tag/v2.1
@@ -67,10 +68,6 @@ organization has all the "official" language definitions:
 
    https://github.com/tree-sitter
 
-Alternatively, you can use treesit-install-language-grammar command
-and follow its instructions. If everything goes right, it should
-automatically download and compile the language grammar for you.
-
 * Setting up for adding major mode features
 
 Start Emacs and load tree-sitter with
@@ -81,10 +78,6 @@ Now check if Emacs is built with tree-sitter library
 
     (treesit-available-p)
 
-Make sure Emacs can find the language grammar you want to use
-
-    (treesit-language-available-p 'lang)
-
 * Tree-sitter major modes
 
 Tree-sitter modes should be separate major modes, so other modes
@@ -96,15 +89,12 @@ modes.
 
 If the tree-sitter variant and the "native" variant could share some
 setup, you can create a "base mode", which only contains the common
-setup.  For example, python.el defines python-base-mode (shared),
-python-mode (native), and python-ts-mode (tree-sitter).
+setup.  For example, there is python-base-mode (shared), python-mode
+(native), and python-ts-mode (tree-sitter).
 
 In the tree-sitter mode, check if we can use tree-sitter with
 treesit-ready-p, it will error out if tree-sitter is not ready.
 
-In Emacs 30 we'll introduce some mechanism to more gracefully inherit
-modes and fallback to other modes.
-
 * Naming convention
 
 Use tree-sitter for text (documentation, comment), use treesit for
@@ -190,17 +180,18 @@ mark the offending part in red.
 To enable tree-sitter font-lock, set ‘treesit-font-lock-settings’ and
 ‘treesit-font-lock-feature-list’ buffer-locally and call
 ‘treesit-major-mode-setup’. For example, see
-‘python--treesit-settings’ in python.el. Below is a snippet of it.
+‘python--treesit-settings’ in python.el. Below I paste a snippet of
+it.
 
-Just like the current font-lock, if the to-be-fontified region already
-has a face (ie, an earlier match fontified part/all of the region),
-the new face is discarded rather than applied. If you want later
-matches always override earlier matches, use the :override keyword.
+Note that like the current font-lock, if the to-be-fontified region
+already has a face (ie, an earlier match fontified part/all of the
+region), the new face is discarded rather than applied. If you want
+later matches always override earlier matches, use the :override
+keyword.
 
 Each rule should have a :feature, like function-name,
 string-interpolation, builtin, etc. Users can then enable/disable each
-feature individually. See Appendix 1 at the bottom for a set of common
-features names.
+feature individually.
 
 #+begin_src elisp
 (defvar python--treesit-settings
@@ -256,7 +247,8 @@ Concretely, something like this:
                   (string-interpolation decorator)))
     (treesit-major-mode-setup))
    (t
-    ;; No tree-sitter, do nothing or fallback to another mode.
+    ;; No tree-sitter
+    (setq-local font-lock-defaults ...)
     ...)))
 #+end_src
 
@@ -279,7 +271,7 @@ Matchers and anchors are functions that takes (NODE PARENT BOL &rest
 _). Matches return nil/non-nil for no match/match, and anchors return
 the anchor point. Below are some convenient builtin matchers and anchors.
 
-For MATCHER we have
+For MATHCER we have
 
     (parent-is TYPE) => matches if PARENT’s type matches TYPE as regexp
     (node-is TYPE) => matches NODE’s type
@@ -297,7 +289,6 @@ For ANCHOR we have
     first-sibling => start of the first sibling
     parent => start of parent
     parent-bol => BOL of the line parent is on.
-    standalone-parent => Like parent-bol but handles more edge cases
     prev-sibling => start of previous sibling
     no-indent => current position (don’t indent)
     prev-line => start of previous line
@@ -338,8 +329,7 @@ tells you which rule is applied in the echo area.
        ...))))
 #+end_src
 
-To setup indentation for your major mode, set
-‘treesit-simple-indent-rules’ to your rules, and call
+Then you set ‘treesit-simple-indent-rules’ to your rules, and call
 ‘treesit-major-mode-setup’:
 
 #+begin_src elisp
@@ -349,14 +339,36 @@ To setup indentation for your major mode, set
 
 * Imenu
 
-Set ‘treesit-simple-imenu-settings’ and call
-‘treesit-major-mode-setup’.
+Not much to say except for utilizing ‘treesit-induce-sparse-tree’ (and
+explicitly pass a LIMIT argument: most of the time you don't need more
+than 10).  See ‘js--treesit-imenu-1’ in js.el for an example.
+
+Once you have the index builder, set ‘imenu-create-index-function’ to
+it.
 
 * Navigation
 
-Set ‘treesit-defun-type-regexp’ and call
-‘treesit-major-mode-setup’. You can additionally set
-‘treesit-defun-name-function’.
+Mainly ‘beginning-of-defun-function’ and ‘end-of-defun-function’.
+You can find the end of a defun with something like
+
+(treesit-search-forward-goto "function_definition" 'end)
+
+where "function_definition" matches the node type of a function
+definition node, and ’end means we want to go to the end of that node.
+
+Tree-sitter has default implementations for
+‘beginning-of-defun-function’ and ‘end-of-defun-function’.  So for
+ordinary languages, it is enough to set ‘treesit-defun-type-regexp’
+to something that matches all the defun struct types in the language,
+and call ‘treesit-major-mode-setup’.  For example,
+
+#+begin_src emacs-lisp
+(setq-local treesit-defun-type-regexp (rx bol
+                                          (or "function" "class")
+                                          "_definition"
+                                          eol))
+(treesit-major-mode-setup)
+#+end_src>
 
 * Which-func
 
@@ -364,7 +376,36 @@ If you have an imenu implementation, set ‘which-func-functions’ to
 nil, and which-func will automatically use imenu’s data.
 
 If you want an independent implementation for which-func, you can
-find the current function by ‘treesit-defun-at-point’.
+find the current function by going up the tree and looking for the
+function_definition node. See the function below for an example.
+Since Python allows nested function definitions, that function keeps
+going until it reaches the root node, and records all the function
+names along the way.
+
+#+begin_src elisp
+(defun python-info-treesit-current-defun (&optional include-type)
+  "Identical to `python-info-current-defun' but use tree-sitter.
+For INCLUDE-TYPE see `python-info-current-defun'."
+  (let ((node (treesit-node-at (point)))
+        (name-list ())
+        (type nil))
+    (cl-loop while node
+             if (pcase (treesit-node-type node)
+                  ("function_definition"
+                   (setq type 'def))
+                  ("class_definition"
+                   (setq type 'class))
+                  (_ nil))
+             do (push (treesit-node-text
+                       (treesit-node-child-by-field-name node "name")
+                       t)
+                      name-list)
+             do (setq node (treesit-node-parent node))
+             finally return (concat (if include-type
+                                        (format "%s " type)
+                                      "")
+                                    (string-join name-list ".")))))
+#+end_src
 
 * More features?
 
@@ -408,51 +449,7 @@ section is Parsing Program Source. Typing
 
     C-h i d m elisp RET g Parsing Program Source RET
 
-will bring you to that section. You don’t need to read through every
-sentence, just read the text paragraphs and glance over function
-names.
-
-* Appendix 1
-
-Below is a set of common features used by built-in major mode.
-
-Basic tokens:
-
-delimiter               ,.;      (delimit things)
-operator                == != || (produces a value)
-bracket                 []{}()
-misc-punctuation        (other punctuation that you want to highlight)
-
-constant                true, false, null
-number
-keyword
-comment                 (includes doc-comments)
-string                  (includes chars and docstrings)
-string-interpolation    f"text {variable}"
-escape-sequence         "\n\t\\"
-function                every function identifier
-variable                every variable identifier
-type                    every type identifier
-property                a.b  <--- highlight b
-key                     { a: b, c: d } <--- highlight a, c
-error                   highlight parse error
-
-Abstract features:
-
-assignment: the LHS of an assignment (thing being assigned to), eg:
-
-a = b    <--- highlight a
-a.b = c  <--- highlight b
-a[1] = d <--- highlight a
-
-definition: the thing being defined, eg:
-
-int a(int b) { <--- highlight a
- return 0
-}
-
-int a;  <-- highlight a
-
-struct a { <--- highlight a
- int b;   <--- highlight b
-}
+will bring you to that section. You can also read the HTML version
+under /html-manual in this directory. I find the HTML version easier
+to read. You don’t need to read through every sentence, just read the
+text paragraphs and glance over function names.

admin/notes/tree-sitter/treesit_record_change

@@ -1,50 +0,0 @@
-NOTES ON TREESIT_RECORD_CHANGE
-
-It is vital that Emacs informs tree-sitter of every change made to the
-buffer, lest tree-sitter's parse tree would be corrupted/out of sync.
-
-All buffer changes in Emacs are made through functions in insdel.c
-(and casefiddle.c), I augmented functions in those files with calls to
-treesit_record_change.  Below is a manifest of all the relevant
-functions in insdel.c as of Emacs 29:
-
-Function                          Calls
-----------------------------------------------------------------------
-copy_text                         (*1)
-insert                            insert_1_both
-insert_and_inherit                insert_1_both
-insert_char                       insert
-insert_string                     insert
-insert_before_markers             insert_1_both
-insert_before_markers_and_inherit insert_1_both
-insert_1_both                     treesit_record_change
-insert_from_string                insert_from_string_1
-insert_from_string_before_markers insert_from_string_1
-insert_from_string_1              treesit_record_change
-insert_from_gap_1                 treesit_record_change
-insert_from_gap                   insert_from_gap_1
-insert_from_buffer                treesit_record_change
-insert_from_buffer_1              (used by insert_from_buffer) (*2)
-replace_range                     treesit_record_change
-replace_range_2                   (caller needs to call treesit_r_c)
-del_range                         del_range_1
-del_range_1                       del_range_2
-del_range_byte                    del_range_2
-del_range_both                    del_range_2
-del_range_2                       treesit_record_change
-
-(*1) This functions is used only to copy from string to string when
-used outside of insdel.c, and when used inside insdel.c, the caller
-calls treesit_record_change.
-
-(*2) This function is a static function, and insert_from_buffer is its
-only caller.  So it should be fine to call treesit_record_change in
-insert_from_buffer but not insert_from_buffer_1.  I also left a
-reminder comment.
-
-
-As for casefiddle.c, do_casify_unibyte_region and
-do_casify_multibyte_region modifies buffer, but they are static
-functions and are called by casify_region, which calls
-treesit_record_change.  Other higher-level functions calls
-casify_region to do the work.

autogen.sh

@@ -340,8 +340,7 @@ git_config diff.texinfo.xfuncname \
 tailored_hooks=
 sample_hooks=
 
-for hook in commit-msg pre-commit prepare-commit-msg post-commit \
-            pre-push commit-msg-files.awk; do
+for hook in commit-msg pre-commit prepare-commit-msg; do
     cmp -- build-aux/git-hooks/$hook "$hooks/$hook" >/dev/null 2>&1 ||
 	tailored_hooks="$tailored_hooks $hook"
 done

build-aux/config.guess

@@ -1,10 +1,10 @@
 #! /bin/sh
 # Attempt to guess a canonical system name.
-#   Copyright 1992-2023 Free Software Foundation, Inc.
+#   Copyright 1992-2022 Free Software Foundation, Inc.
 
 # shellcheck disable=SC2006,SC2268 # see below for rationale
 
-timestamp='2023-01-01'
+timestamp='2022-09-17'
 
 # This file is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by
@@ -60,7 +60,7 @@ version="\
 GNU config.guess ($timestamp)
 
 Originally written by Per Bothner.
-Copyright 1992-2023 Free Software Foundation, Inc.
+Copyright 1992-2022 Free Software Foundation, Inc.
 
 This is free software; see the source for copying conditions.  There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."

build-aux/config.sub

@@ -1,10 +1,10 @@
 #! /bin/sh
 # Configuration validation subroutine script.
-#   Copyright 1992-2023 Free Software Foundation, Inc.
+#   Copyright 1992-2022 Free Software Foundation, Inc.
 
 # shellcheck disable=SC2006,SC2268 # see below for rationale
 
-timestamp='2023-01-21'
+timestamp='2022-09-17'
 
 # This file is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by
@@ -76,7 +76,7 @@ Report bugs and patches to <config-patches@gnu.org>."
 version="\
 GNU config.sub ($timestamp)
 
-Copyright 1992-2023 Free Software Foundation, Inc.
+Copyright 1992-2022 Free Software Foundation, Inc.
 
 This is free software; see the source for copying conditions.  There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
@@ -1075,7 +1075,7 @@ case $cpu-$vendor in
 	pentium-* | p5-* | k5-* | k6-* | nexgen-* | viac3-*)
 		cpu=i586
 		;;
-	pentiumpro-* | p6-* | 6x86-* | athlon-* | athlon_*-*)
+	pentiumpro-* | p6-* | 6x86-* | athlon-* | athalon_*-*)
 		cpu=i686
 		;;
 	pentiumii-* | pentium2-* | pentiumiii-* | pentium3-*)

build-aux/git-hooks/commit-msg-files.awk

@@ -1,128 +0,0 @@
-# Check the file list of GNU Emacs change log entries for each commit SHA.
-
-# Copyright 2023 Free Software Foundation, Inc.
-
-# This file is part of GNU Emacs.
-
-# GNU Emacs is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# GNU Emacs is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-
-# You should have received a copy of the GNU General Public License
-# along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
-
-### Commentary:
-
-# This script accepts a list of (unabbreviated) Git commit SHAs, and
-# will then iterate over them to check that any files mentioned in the
-# commit message are actually present in the commit's diff.  If not,
-# it will print out the incorrect file names and return 1.
-
-# You can also pass "-v reason=pre-push", which will add more-verbose
-# output, indicating the abbreviated commit SHA and first line of the
-# commit message for any improper commits.
-
-### Code:
-
-function get_commit_changes(commit_sha, changes,    cmd, i, j, len, \
-                            bits, filename) {
-  # Collect all the files touched in the specified commit.
-  cmd = ("git show --name-status --first-parent --format= " commit_sha)
-  while ((cmd | getline) > 0) {
-    for (i = 2; i <= NF; i++) {
-      len = split($i, bits, "/")
-      for (j = 1; j <= len; j++) {
-        if (j == 1)
-          filename = bits[j]
-        else
-          filename = filename "/" bits[j]
-        changes[filename] = 1
-      }
-    }
-  }
-  close(cmd)
-}
-
-function check_commit_msg_files(commit_sha, verbose,    changes, good, \
-                                cmd, msg, filenames_str, filenames, i) {
-  get_commit_changes(commit_sha, changes)
-  good = 1
-
-  cmd = ("git log -1 --format=%B " commit_sha)
-  while ((cmd | getline) > 0) {
-    if (verbose && ! msg)
-      msg = $0
-
-    # Find file entries in the commit message.  We look at any line
-    # starting with "*" (possibly prefixed by "; ") followed by a ":",
-    # possibly on a different line.  If we encounter a blank line
-    # without seeing a ":", then we don't treat that as a file entry.
-
-    # Accumulate the contents of a (possible) file entry.
-    if (/^[ \t]*$/)
-      filenames_str = ""
-    else if (/^(; )?\*[ \t]+[[:alnum:]]/)
-      filenames_str = $0
-    else if (filenames_str)
-      filenames_str = (filenames_str $0)
-
-    # We have a file entry; analyze it.
-    if (filenames_str && /:/) {
-      # Delete the leading "*" and any trailing information.
-      sub(/^(; )?\*[ \t]+/, "", filenames_str)
-      sub(/[ \t]*[[(<:].*$/, "", filenames_str)
-
-      # There might be multiple files listed in this entry, separated
-      # by spaces (and possibly a comma).  Iterate over each of them.
-      split(filenames_str, filenames, ",[ \t]+")
-      for (i in filenames) {
-        # Remove trailing slashes from any directory entries.
-        sub(/\/$/, "", filenames[i])
-
-        if (length(filenames[i]) && ! (filenames[i] in changes)) {
-          if (good) {
-            # Print a header describing the error.
-            if (verbose)
-              printf("In commit %s \"%s\"...\n", substr(commit_sha, 1, 10), msg)
-            printf("Files listed in commit message, but not in diff:\n")
-          }
-          printf("  %s\n", filenames[i])
-          good = 0
-        }
-      }
-
-      filenames_str = ""
-    }
-  }
-  close(cmd)
-
-  return good
-}
-
-BEGIN {
-  if (reason == "pre-push")
-    verbose = 1
-}
-
-/^[a-z0-9]{40}$/ {
-  if (! check_commit_msg_files($0, verbose)) {
-    status = 1
-  }
-}
-
-END {
-  if (status != 0) {
-    if (reason == "pre-push")
-      error_msg = "Push aborted"
-    else
-      error_msg = "Bad commit message"
-    printf("%s; please see the file 'CONTRIBUTE'\n", error_msg)
-  }
-  exit status
-}

build-aux/git-hooks/post-commit

@@ -1,47 +0,0 @@
-#!/bin/sh
-# Check the file list of GNU Emacs change log entries after committing.
-
-# Copyright 2023 Free Software Foundation, Inc.
-
-# This file is part of GNU Emacs.
-
-# GNU Emacs is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# GNU Emacs is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-
-# You should have received a copy of the GNU General Public License
-# along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
-
-### Commentary:
-
-# This hook runs after a commit is finalized and checks that the files
-# mentioned in the commit message match the diff.  We perform this in
-# the post-commit phase so that we can be sure we properly detect all
-# the files in the diff (this is difficult during the commit-msg hook,
-# since there's no cross-platform way to detect when a commit is being
-# amended).
-
-# However, since this is a post-commit hook, it's too late to error
-# out and abort the commit: it's already done!  As a result, this hook
-# is purely advisory, and instead we error out when trying to push
-# (see "pre-push" in this directory).
-
-### Code:
-
-HOOKS_DIR=`dirname "$0"`
-
-# Prefer gawk if available, as it handles NUL bytes properly.
-if type gawk >/dev/null 2>&1; then
-  awk="gawk"
-else
-  awk="awk"
-fi
-
-git rev-parse HEAD | $awk -v reason=post-commit \
-                          -f "$HOOKS_DIR"/commit-msg-files.awk

build-aux/git-hooks/pre-push

@@ -1,88 +0,0 @@
-#!/bin/sh
-# Check the file list of GNU Emacs change log entries before pushing.
-
-# Copyright 2023 Free Software Foundation, Inc.
-
-# This file is part of GNU Emacs.
-
-# GNU Emacs is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# GNU Emacs is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-
-# You should have received a copy of the GNU General Public License
-# along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
-
-### Commentary:
-
-# This hook runs before pushing a series of commits and checks that
-# the files mentioned in each commit message match the diffs.  This
-# helps ensure that the resulting change logs are correct, which
-# should prevent errors when generating etc/AUTHORS.
-
-# These checks also happen in the "post-commit" hook (which see), but
-# that hook can't abort a commit; it just advises the committer to fix
-# the commit so that this hook runs without errors.
-
-### Code:
-
-HOOKS_DIR=`dirname "$0"`
-
-# Prefer gawk if available, as it handles NUL bytes properly.
-if type gawk >/dev/null 2>&1; then
-  awk="gawk"
-else
-  awk="awk"
-fi
-
-# Standard input receives lines of the form:
-#   <local ref> SP <local sha> SP <remote ref> SP <remote sha> LF
-$awk -v origin_name="$1" '
-  # If the local SHA is all zeroes, ignore it.
-  $2 ~ /^0{40}$/ {
-    next
-  }
-
-  # Check any lines with a valid local SHA and whose remote ref is
-  # master or an emacs-NN release branch.  (We want to avoid checking
-  # feature or scratch branches here.)
-  $2 ~ /^[a-z0-9]{40}$/ && $3 ~ /^refs\/heads\/(master|emacs-[0-9]+)$/ {
-    newref = $2
-    # If the remote SHA is all zeroes, this is a new object to be
-    # pushed (likely a branch)...
-    if ($4 ~ /^0{40}$/) {
-      back = 0
-      # ... Go backwards until we find a SHA on an origin branch.
-      # Stop trying after 1000 commits, just in case...
-      for (back = 0; back < 1000; back++) {
-        cmd = ("git branch -r -l '\''" origin_name "/*'\''" \
-               " --contains " newref "~" back)
-        rv = (cmd | getline)
-        close(cmd)
-        if (rv > 0)
-          break;
-      }
-
-      cmd = ("git rev-parse " newref "~" back)
-      cmd | getline oldref
-      if (!(oldref ~ /^[a-z0-9]{40}$/)) {
-        # The SHA is misformatted!  Skip this line.
-        next
-      }
-      close(cmd)
-    } else if ($4 ~ /^[a-z0-9]{40}$/)  {
-      oldref = $4
-    } else {
-      # The SHA is misformatted!  Skip this line.
-      next
-    }
-
-    # Print every SHA after oldref, up to (and including) newref.
-    system("git rev-list --first-parent --reverse " oldref ".." newref)
-  }
-' | $awk -v reason=pre-push -f "$HOOKS_DIR"/commit-msg-files.awk

build-aux/update-copyright

@@ -137,7 +137,7 @@
 eval 'exec perl -wSx -0777 -pi "$0" "$@"'
      if 0;
 
-my $VERSION = '2023-01-11.04:24'; # UTC
+my $VERSION = '2020-04-04.15:07'; # UTC
 # The definition above must lie within the first 8 lines in order
 # for the Emacs time-stamp write hook (at end) to update it.
 # If you change this file with Emacs, please let the write hook
@@ -280,7 +280,7 @@ if (defined $stmt_re)
           }
 
         # Replace the old copyright statement.
-        s/$stmt_re/$stmt_wrapped/g;
+        s/$stmt_re/$stmt_wrapped/;
       }
   }
 else

configure.ac

@@ -1001,7 +1001,7 @@ AC_ARG_ENABLE([gcc-warnings],
    # however, if there is also a .tarball-version file it is probably
    # just a release imported into Git for patch management.
    gl_gcc_warnings=no
-   if test -d "$srcdir"/.git && test ! -f "$srcdir"/.tarball-version; then
+   if test -e "$srcdir"/.git && test ! -f "$srcdir"/.tarball-version; then
       # Clang typically identifies itself as GCC 4.2 or something similar
       # even if it is recent enough to accept the warnings we enable.
       AS_IF([test "$emacs_cv_clang" = yes],
@@ -1139,7 +1139,6 @@ AS_IF([test $gl_gcc_warnings = no],
 
   # clang is unduly picky about some things.
   if test "$emacs_cv_clang" = yes; then
-    gl_WARN_ADD([-Wno-bitwise-instead-of-logical])
     gl_WARN_ADD([-Wno-missing-braces])
     gl_WARN_ADD([-Wno-null-pointer-arithmetic])
     gl_WARN_ADD([-Wno-implicit-const-int-float-conversion])
@@ -1643,8 +1642,7 @@ case "$opsys" in
   ## Motif needs -lgen.
   unixware) LIBS_SYSTEM="-lsocket -lnsl -lelf -lgen" ;;
 
-  # Haiku needs -lbsd for cfsetspeed.
-  haiku) LIBS_SYSTEM="-lnetwork -lbsd" ;;
+  haiku) LIBS_SYSTEM="-lnetwork" ;;
 esac
 
 AC_SUBST([LIBS_SYSTEM])
@@ -2034,29 +2032,37 @@ if test "${with_ns}" != no; then
      ns_appresdir=${ns_appdir}/Contents/Resources
      ns_appsrc=Cocoa/Emacs.base
      ns_fontfile=macfont.o
-  elif flags=`(gnustep-config --objc-flags) 2>/dev/null`; then
+  elif flags=$( (gnustep-config --objc-flags) 2>/dev/null); then
      NS_IMPL_GNUSTEP=yes
      NS_GNUSTEP_CONFIG=yes
      GNU_OBJC_CFLAGS="$flags"
-     LIBS_GNUSTEP=`gnustep-config --gui-libs || exit`
+     LIBS_GNUSTEP=$(gnustep-config --gui-libs) || exit
   elif test -f $GNUSTEP_CONFIG_FILE; then
      NS_IMPL_GNUSTEP=yes
      dnl FIXME sourcing this several times in subshells seems inefficient.
-     GNUSTEP_SYSTEM_HEADERS=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_SYSTEM_HEADERS"])`
-     GNUSTEP_SYSTEM_LIBRARIES=` . $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_SYSTEM_LIBRARIES"])`
+     GNUSTEP_SYSTEM_HEADERS=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_SYSTEM_HEADERS"])
+     )
+     GNUSTEP_SYSTEM_LIBRARIES=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_SYSTEM_LIBRARIES"])
+     )
      dnl I seemed to need these as well with GNUstep-startup 0.25.
-     GNUSTEP_LOCAL_HEADERS=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_LOCAL_HEADERS"])`
-     GNUSTEP_LOCAL_LIBRARIES=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_LOCAL_LIBRARIES"])`
+     GNUSTEP_LOCAL_HEADERS=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_LOCAL_HEADERS"])
+     )
+     GNUSTEP_LOCAL_LIBRARIES=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_LOCAL_LIBRARIES"])
+     )
      test "x${GNUSTEP_LOCAL_HEADERS}" != "x" && \
        GNUSTEP_LOCAL_HEADERS="-I${GNUSTEP_LOCAL_HEADERS}"
      test "x${GNUSTEP_LOCAL_LIBRARIES}" != "x" && \
        GNUSTEP_LOCAL_LIBRARIES="-L${GNUSTEP_LOCAL_LIBRARIES}"
-     CPPFLAGS="$CPPFLAGS -isystem ${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
-     CFLAGS="$CFLAGS -isystem ${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
+     CPPFLAGS="$CPPFLAGS -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
+     CFLAGS="$CFLAGS -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
      LDFLAGS="$LDFLAGS -L${GNUSTEP_SYSTEM_LIBRARIES} ${GNUSTEP_LOCAL_LIBRARIES}"
      LIBS_GNUSTEP="-lgnustep-gui -lgnustep-base -lobjc -lpthread"
      dnl GNUstep defines BASE_NATIVE_OBJC_EXCEPTIONS to 0 or 1.
@@ -2769,25 +2775,6 @@ if test "${with_webp}" != "no"; then
       WEBP_MODULE="libwebpdemux >= $WEBP_REQUIRED"
 
       EMACS_CHECK_MODULES([WEBP], [$WEBP_MODULE])
-
-      # WebPGetInfo is sometimes not present inside libwebpdemux, so
-      # if it does not link, also check for libwebpdecoder.
-
-      OLD_CFLAGS=$CFLAGS
-      OLD_LIBS=$LIBS
-      CFLAGS="$CFLAGS $WEBP_CFLAGS"
-      LIBS="$LIBS $WEBP_LIBS"
-
-      AC_CHECK_FUNC([WebPGetInfo], [],
-        [WEBP_MODULE="$WEBP_MODULE libwebpdecoder >= $WEBP_REQUIRED"
-	 HAVE_WEBP=no
-	 AS_UNSET([WEBP_LIBS])
-	 AS_UNSET([WEBP_CFLAGS])
-	 EMACS_CHECK_MODULES([WEBP], [$WEBP_MODULE])])
-
-      CFLAGS=$OLD_CFLAGS
-      LIBS=$OLD_LIBS
-
       AC_SUBST([WEBP_CFLAGS])
       AC_SUBST([WEBP_LIBS])
    fi
@@ -3595,12 +3582,8 @@ XWIDGETS_OBJ=
 if test "$with_xwidgets" != "no"; then
   if test "$USE_GTK_TOOLKIT" = "GTK3" && test "$window_system" != "none"; then
     WEBKIT_REQUIRED=2.12
-    WEBKIT_MODULES="webkit2gtk-4.1 >= $WEBKIT_REQUIRED"
+    WEBKIT_MODULES="webkit2gtk-4.0 >= $WEBKIT_REQUIRED"
     EMACS_CHECK_MODULES([WEBKIT], [$WEBKIT_MODULES])
-    if test "$HAVE_WEBKIT" = "no"; then
-      WEBKIT_MODULES="webkit2gtk-4.0 >= $WEBKIT_REQUIRED"
-      EMACS_CHECK_MODULES([WEBKIT], [$WEBKIT_MODULES])
-    fi
     HAVE_XWIDGETS=$HAVE_WEBKIT
     XWIDGETS_OBJ="xwidget.o"
     if test "$HAVE_X_WINDOWS" = "yes" && test "${with_cairo}" = "no"; then
@@ -3773,7 +3756,7 @@ if test "${HAVE_X11}" = "yes"; then
 	  AC_DEFINE([HAVE_OTF_GET_VARIATION_GLYPHS], [1],
 		    [Define to 1 if libotf has OTF_get_variation_glyphs.])
 	fi
-	if $PKG_CONFIG --atleast-version=0.9.16 libotf; then :; else
+	if ! $PKG_CONFIG --atleast-version=0.9.16 libotf; then
 	  AC_DEFINE([HAVE_OTF_KANNADA_BUG], [1],
 [Define to 1 if libotf is affected by https://debbugs.gnu.org/28110.])
 	fi
@@ -3881,7 +3864,7 @@ if test "${HAVE_BE_APP}" = "yes"; then
 	  AC_DEFINE([HAVE_OTF_GET_VARIATION_GLYPHS], [1],
 		    [Define to 1 if libotf has OTF_get_variation_glyphs.])
 	fi
-	if $PKG_CONFIG --atleast-version=0.9.16 libotf; then :; else
+	if ! $PKG_CONFIG --atleast-version=0.9.16 libotf; then
 	  AC_DEFINE([HAVE_OTF_KANNADA_BUG], [1],
 [Define to 1 if libotf is affected by https://debbugs.gnu.org/28110.])
 	fi
@@ -4199,7 +4182,7 @@ module_env_snippet_27="$srcdir/src/module-env-27.h"
 module_env_snippet_28="$srcdir/src/module-env-28.h"
 module_env_snippet_29="$srcdir/src/module-env-29.h"
 module_env_snippet_30="$srcdir/src/module-env-30.h"
-emacs_major_version=`AS_ECHO([$PACKAGE_VERSION]) | sed 's/[[.]].*//'`
+emacs_major_version="${PACKAGE_VERSION%%.*}"
 AC_SUBST([emacs_major_version])
 
 ### Emacs Lisp native compiler support
@@ -4282,8 +4265,8 @@ If you really want to try it anyway, use the configure option
 fi
 
 if test "${with_native_compilation}" != "no"; then
-    if test "$with_unexec" = yes; then
-       AC_MSG_ERROR(['--with-native-compilation' is not compatible with unexec])
+    if test "${HAVE_PDUMPER}" = no; then
+       AC_MSG_ERROR(['--with-native-compilation' requires '--with-dumping=pdumper'])
     fi
     if test "${HAVE_ZLIB}" = no; then
        AC_MSG_ERROR(['--with-native-compilation' requires zlib])
@@ -4309,16 +4292,14 @@ if test "${with_native_compilation}" != "no"; then
         # available.  (We filter out the gcc4 packages, because they
         # don't support jit, and they have names like "gcc49" that
         # sort later than "gcc11".)
-        PORT_PACKAGE=`port installed active | grep '^ *gcc@<:@0-9@:>@* ' | \
+        PORT_PACKAGE=$(port installed active | grep '^ *gcc@<:@0-9@:>@* ' | \
                             awk '{ print $1; }' | grep -v 'gcc4@<:@0-9@:>@' | \
-                            sort -V | tail -n 1`
+                            sort -V | tail -n 1)
         if test -n "$PORT_PACKAGE"; then
-	  emacs_val=`port contents $PORT_PACKAGE | grep libgccjit.h`
-	  emacs_val=`dirname $emacs_val`
-          MAC_CFLAGS="-I$emacs_val"
-	  emacs_val=`port contents $PORT_PACKAGE | grep libgccjit.dylib`
-	  emacs_val=`dirname $emacs_val`
-          MAC_LIBS="-L$emacs_val"
+          MAC_CFLAGS="-I$(dirname $(port contents $PORT_PACKAGE | \
+                                           grep libgccjit.h))"
+          MAC_LIBS="-L$(dirname $(port contents $PORT_PACKAGE | \
+                                              grep libgccjit.dylib))"
         fi
       fi
 
@@ -5616,7 +5597,7 @@ case $opsys in
 esac
 
 case $opsys in
-  gnu-* | solaris | cygwin )
+  gnu-* | solaris )
     dnl FIXME Can't we test if this exists (eg /proc/$$)?
     AC_DEFINE([HAVE_PROCFS], [1], [Define if you have the /proc filesystem.])
   ;;
@@ -6520,12 +6501,6 @@ if test "$window_system" != "none"; then
   AC_DEFINE([POLL_FOR_INPUT], [1],
     [Define if you poll periodically to detect C-g.])
   WINDOW_SYSTEM_OBJ="fontset.o fringe.o image.o"
-
-  if test "$window_system" = "x11"; then
-    AC_DEFINE([HAVE_TEXT_CONVERSION], [1],
-      [Define if the window system has text conversion support.])
-    WINDOW_SYSTEM_OBJ="$WINDOW_SYSTEM_OBJ textconv.o"
-  fi
 fi
 
 AC_SUBST([WINDOW_SYSTEM_OBJ])
@@ -6578,9 +6553,7 @@ if test "${HAVE_GTK}" = "yes"; then
 fi
 
 if test $USE_ACL -ne 0; then
-  ACL_SUMMARY="yes"
-  test "$LIB_ACL" && ACL_SUMMARY="$ACL_SUMMARY $LIB_ACL"
-  test "$LIB_XATTR" && ACL_SUMMARY="$ACL_SUMMARY $LIB_XATTR"
+  ACL_SUMMARY="yes $LIB_ACL"
 else
   ACL_SUMMARY=no
 fi
@@ -6651,7 +6624,6 @@ AC_DEFINE_UNQUOTED([EMACS_CONFIG_FEATURES], ["${emacs_config_features}"],
   [Summary of some of the main features enabled by configure.])
 
 AS_ECHO(["  Does Emacs use -lXaw3d?                                 ${HAVE_XAW3D}
-  Does Emacs use the X Double Buffer Extension?           ${HAVE_XDBE}
   Does Emacs use -lXpm?                                   ${HAVE_XPM}
   Does Emacs use -ljpeg?                                  ${HAVE_JPEG}
   Does Emacs use -ltiff?                                  ${HAVE_TIFF}

doc/emacs/anti.texi

@@ -69,14 +69,13 @@ idea anyway.
 @item
 In line with simplifying and eventually removing the
 native-compilation option, we've deleted the
-@option{--with-native-compilation=aot} configure-time option.  This
-greatly simplifies how native compilation works and makes your
-configure-time decision regarding native compilation in Emacs
-clear-cut: either Emacs compiles non-preloaded Lisp packages to native
-code only before using it, or it never uses native compilation at all;
-no more half measures and special exceptions.  For similar reasons,
-@code{native-compile-prune-cache} and
-@code{startup-redirect-eln-cache} features are no longer part of
+@code{inhibit-automatic-native-compilation} variable and its support
+code.  This greatly simplifies how native compilation works and makes
+your configure-time decision regarding native compilation in Emacs
+clear-cut: either Emacs always compiles Lisp to native code before
+using it, or it never does so; no more half measures and special
+exceptions.  For similar reasons, @code{native-compile-prune-cache}
+and @code{startup-redirect-eln-cache} features are no longer part of
 Emacs.
 
 @item

doc/emacs/basic.texi

@@ -887,40 +887,19 @@ z z z}.  The first @kbd{C-x z} repeats the command once, and each
 subsequent @kbd{z} repeats it once again.
 
 @findex repeat-mode
-@findex describe-repeat-maps
 @vindex repeat-exit-key
 @vindex repeat-exit-timeout
-  You can also activate @code{repeat-mode} which allows repeating
-commands bound to sequences of two or more keys by typing a single
-character.  For example, after typing @w{@kbd{C-x u}} (@code{undo},
-@pxref{Undo}) to undo the most recent edits, you can undo many more
-edits by typing @w{@kbd{u u u@dots{}}}.  Similarly, type @w{@kbd{C-x o
-o o@dots{}}} instead of @w{@kbd{C-x o C-x o C-x o@dots{}}} to switch
-to the window several windows away.  This works by entering a
-transient repeating mode after you type the full key sequence that
-invokes the command; the single-key shortcuts are shown in the echo
-area.
-
-Only some commands support repetition in @code{repeat-mode}; type
-@w{@kbd{M-x describe-repeat-maps @key{RET}}} to see which ones.
-
-The single-character shortcuts enabled by the transient repeating mode
-do not need to be identical: for example, after typing @w{@kbd{C-x
-@{}}, either @kbd{@{} or @kbd{@}} or @kbd{^} or @kbd{v}, or any series
-that mixes these characters in any order, will resize the selected
-window in respective ways.  Similarly, after @w{@kbd{M-g n}} or
-@kbd{M-g p}, typing any sequence of @kbd{n} and/or @kbd{p} in any mix
-will repeat @code{next-error} and @code{previous-error} to navigate in
-a @file{*compilation*} or @file{*grep*} buffer (@pxref{Compilation
-Mode}).
-
-Typing any key other than those defined to repeat the previous command
-exits the transient repeating mode, and then the key you typed is
-executed normally.  You can also define a key which will exit the
-transient repeating mode @emph{without} executing the key which caused
-the exit.  To this end, customize the user option
-@code{repeat-exit-key} to name a key; one natural value is @key{RET}.
-Finally, it's possible to break the repetition chain automatically
-after some amount of idle time: customize the user option
-@code{repeat-exit-timeout} to specify the idle time in seconds after
-which this transient repetition mode will be turned off automatically.
+  Also you can activate @code{repeat-mode} that temporarily enables a
+transient mode with short keys after a limited number of commands.
+Currently supported shorter key sequences are @kbd{C-x u u} instead of
+@kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of
+@kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^
+v v} to resize the selected window interactively, @kbd{M-g n n p p} to
+navigate @code{next-error} matches, and @kbd{C-x ] ] [ [} to navigate
+through pages.  Any other key exits transient mode and then is
+executed normally.  The user option @code{repeat-exit-key} defines an
+additional key to exit this transient mode.  Also it's possible to
+break the repetition chain automatically after some idle time by
+customizing the user option @code{repeat-exit-timeout} to specify the
+idle time in seconds after which this transient mode will be turned
+off.

doc/emacs/building.texi

@@ -961,7 +961,9 @@ the fringe of a source buffer to set a breakpoint there.
 @vindex gud-gdb-command-name
   To run GDB using just the GUD interaction buffer interface, without
 these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
-GUD}).
+GUD}).  You must use this if you want to debug multiple programs
+within one Emacs session, as that is currently unsupported by @kbd{M-x
+gdb}.
 
   Internally, @kbd{M-x gdb} informs GDB that its screen size is
 unlimited; for correct operation, you must not change GDB's screen
@@ -1049,9 +1051,9 @@ to restore only when @code{gdb-show-main} is non-@code{nil}.
   You may also specify additional GDB-related buffers to display,
 either in the same frame or a different one.  Select the buffers you
 want by typing @kbd{M-x gdb-display-@var{buffertype}-buffer} or
-@kbd{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype} is
-the relevant buffer type, such as @samp{breakpoints} or @samp{io}.
-You can do the same from the menu bar, with the @samp{GDB-Windows} and
+@kbd{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype}
+is the relevant buffer type, such as @samp{breakpoints}.  You can do
+the same with the menu bar, with the @samp{GDB-Windows} and
 @samp{GDB-Frames} sub-menus of the @samp{GUD} menu.
 
 @vindex gdb-max-source-window-count
@@ -1271,14 +1273,10 @@ non-@code{nil} value.
 @node Other GDB Buffers
 @subsubsection Other GDB Buffers
 
-Other buffers provided by @kbd{M-x gdb} whose display you can
-optionally request include:
-
 @table @asis
-@findex gdb-display-locals-buffer
 @item Locals Buffer
 This buffer displays the values of local variables of the current
-stack frame for simple data types (@pxref{Frame Info, Frame Info,
+frame for simple data types (@pxref{Frame Info, Frame Info,
 Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
 click @kbd{mouse-2} on the value if you want to edit it.
 
@@ -1288,35 +1286,20 @@ you can examine the value of the local variable at point by typing
 GDB, use @key{RET} or @kbd{mouse-2} on the type description
 (@samp{[struct/union]} or @samp{[array]}).  @xref{Watch Expressions}.
 
-To display the Locals buffer, type @kbd{M-x gdb-display-locals-buffer}.
-
-@findex gdb-display-io-buffer
-@item I/O Buffer
-If the program you are debugging uses standard input and output
-streams for interaction with the user, or emits a significant amount
-of output to its standard output, you may wish to separate its I/O
-from interaction with GDB.  Use the command @w{@kbd{M-x
-gdb-display-io-buffer}} to show a window with a buffer to which Emacs
-redirects the input and output from the program you are debugging.
-
-@findex gdb-display-registers-buffer
 @item Registers Buffer
+@findex toggle-gdb-all-registers
 This buffer displays the values held by the registers
-(@pxref{Registers,,, gdb, The GNU debugger}).  Request the display of
-this buffer with the command @kbd{M-x gdb-display-registers-buffer}.
-Press @key{RET} or click @kbd{mouse-2} on a register if you want to
-edit its value.  With GDB 6.4 or later, recently changed register
-values display with @code{font-lock-warning-face}.
+(@pxref{Registers,,, gdb, The GNU debugger}).  Press @key{RET} or
+click @kbd{mouse-2} on a register if you want to edit its value.  With
+GDB 6.4 or later, recently changed register values display with
+@code{font-lock-warning-face}.
 
-@findex gdb-display-disassembly-buffer
 @item Assembler Buffer
 The assembler buffer displays the current frame as machine code.  An
 arrow points to the current instruction, and you can set and remove
 breakpoints as in a source buffer.  Breakpoint icons also appear in
-the fringe or margin.  To request the display of this buffer, use
-@kbd{M-x gdb-display-disassembly-buffer}.
+the fringe or margin.
 
-@findex gdb-display-memory-buffer
 @item Memory Buffer
 The memory buffer lets you examine sections of program memory
 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
@@ -1324,8 +1307,7 @@ Click @kbd{mouse-1} on the appropriate part of the header line to
 change the starting address or number of data items that the buffer
 displays.  Alternatively, use @kbd{S} or @kbd{N} respectively.  Click
 @kbd{mouse-3} on the header line to select the display format or unit
-size for these data items.  Use @w{@kbd{M-x
-gdb-display-memory-buffer}} to request display of this buffer.
+size for these data items.
 @end table
 
 When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
@@ -1556,26 +1538,18 @@ command prompts for a @dfn{library name} rather than a file name; it
 searches through each directory in the Emacs Lisp load path, trying to
 find a file matching that library name.  If the library name is
 @samp{@var{foo}}, it tries looking for files named
-@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}.  (If
-Emacs was built with native compilation enabled, @code{load-library}
-looks for a @samp{.eln} file that corresponds to @file{@var{foo}.el}
-and loads it instead of @file{@var{foo}.elc}.)  The default behavior
-is to load the first file found.  This command prefers @file{.eln}
-files over @file{.elc} files, and prefers @file{.elc} files over
-@file{.el} files, because compiled files load and run faster.  If it
-finds that @file{@var{lib}.el} is newer than @file{@var{lib}.elc}, it
-issues a warning, in case someone made changes to the @file{.el} file
-and forgot to recompile it, but loads the @file{.elc} file anyway.
-(Due to this behavior, you can save unfinished edits to Emacs Lisp
-source files, and not recompile until your changes are ready for use.)
-If you set the option @code{load-prefer-newer} to a non-@code{nil}
-value, however, then rather than the procedure described above, Emacs
-loads whichever version of the file is newest.  If Emacs was built
-with native compilation, and it cannot find the @samp{.eln} file
-corresponding to @file{@var{lib}.el}, it will load a
-@file{@var{lib}.elc} and start native compilation of
-@file{@var{lib}.el} in the background, then load the @samp{.eln} file
-when it finishes compilation.
+@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}.  The
+default behavior is to load the first file found.  This command
+prefers @file{.elc} files over @file{.el} files because compiled files
+load and run faster.  If it finds that @file{@var{lib}.el} is newer
+than @file{@var{lib}.elc}, it issues a warning, in case someone made
+changes to the @file{.el} file and forgot to recompile it, but loads
+the @file{.elc} file anyway.  (Due to this behavior, you can save
+unfinished edits to Emacs Lisp source files, and not recompile until
+your changes are ready for use.)  If you set the option
+@code{load-prefer-newer} to a non-@code{nil} value, however, then
+rather than the procedure described above, Emacs loads whichever
+version of the file is newest.
 
   Emacs Lisp programs usually load Emacs Lisp files using the
 @code{load} function.  This is similar to @code{load-library}, but is
@@ -1612,11 +1586,6 @@ It is customary to put locally installed libraries in the
 @code{load-path}, or in some subdirectory of @file{site-lisp}.  This
 way, you don't need to modify the default value of @code{load-path}.
 
-@vindex native-comp-eln-load-path
-  Similarly to @code{load-path}, the list of directories where Emacs
-looks for @file{*.eln} files with natively-compiled Lisp code is
-specified by the variable @code{native-comp-eln-load-path}.
-
 @cindex autoload
   Some commands are @dfn{autoloaded}; when you run them, Emacs
 automatically loads the associated library first.  For instance, the

doc/emacs/custom.texi

@@ -1245,7 +1245,6 @@ Manual}.
 These four keywords are not really variables; setting them in any
 other context has no special meaning.
 
-@cindex fallback modes
   If you're editing a file across Emacs versions, and a new mode has
 been introduced to handle a file in a newer Emacs version, you can use
 several @code{mode} entries to use the new mode (called
@@ -1888,31 +1887,23 @@ command is less work to invoke when you really want to.
 you can specify them in your initialization file by writing Lisp code.
 @xref{Init File}, for a description of the initialization file.
 
-@findex keymap-global-set
-  The recommended way to write a key binding using Lisp is to use
-either the @code{keymap-global-set} or the @code{keymap-set}
-functions.  For example, here's how to bind @kbd{C-z} to the
-@code{shell} command in the global keymap (@pxref{Interactive Shell}):
+@findex kbd
+  There are several ways to write a key binding using Lisp.  The
+simplest is to use the @code{kbd} function, which converts a textual
+representation of a key sequence---similar to how we have written key
+sequences in this manual---into a form that can be passed as an
+argument to @code{keymap-global-set}.  For example, here's how to bind
+@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
 
 @example
 (keymap-global-set "C-z" 'shell)
 @end example
 
-@cindex key sequence syntax
 @noindent
-The first argument to @code{keymap-global-set} describes the key
-sequence.  It is a string made of a series of characters separated
-by spaces, with each character corresponding to a key.  Keys with
-modifiers can be specified by prepending the modifier, such as
-@samp{C-} for Control, or @samp{M-} for Meta.  Special keys, such as
-@key{TAB} and @key{RET}, can be specified within angle brackets as in
-@kbd{@key{TAB}} and @kbd{@key{RET}}.
-
-  The single-quote before the command name that is being bound to the
-key sequence, @code{shell} in the above example, marks it as a
+The single-quote before the command name, @code{shell}, marks it as a
 constant symbol rather than a variable.  If you omit the quote, Emacs
-would try to evaluate @code{shell} as a variable.  This will probably
-cause an error; it certainly isn't what you want.
+would try to evaluate @code{shell} as a variable.  This probably
+causes an error; it certainly isn't what you want.
 
   Here are some additional examples, including binding function keys
 and mouse events:
@@ -1929,27 +1920,6 @@ and mouse events:
   Language and coding systems may cause problems with key bindings for
 non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
 
-@findex global-set-key
-@findex define-key
-  Alternatively, you can use the low level functions @code{define-key}
-and @code{global-set-key}.  For example, to bind @kbd{C-z} to the
-@code{shell} command, as in the above example, using these low-level
-functions, use:
-
-@example
-(global-set-key (kbd "C-z") 'shell)
-@end example
-
-@findex kbd
-@noindent
-There are various ways to specify the key sequence but the simplest is
-to use the function @code{kbd} as shown in the example above.
-@code{kbd} takes a single string argument that is a textual
-representation of a key sequence, and converts it into a form suitable
-for low-level functions such as @code{global-set-key}.  For more
-details about binding keys using Lisp, @pxref{Keymaps,,, elisp, The
-Emacs Lisp Reference Manual}.
-
 @findex keymap-set
 @findex keymap-unset
   As described in @ref{Local Keymaps}, major modes and minor modes can

doc/emacs/dired.texi

@@ -715,10 +715,6 @@ Otherwise, the command operates on the current file only.
 Certain other Dired commands, such as @kbd{!} and the @samp{%}
 commands, use the same conventions to decide which files to work on.
 
-  In addition to Dired commands described here, you can also invoke
-Version Control (VC) commands on one or more files shown in a Dired
-buffer.  @xref{Version Control}.
-
 @vindex dired-dwim-target
 @cindex two directories (in Dired)
   Commands which ask for a destination directory, such as those which
@@ -1659,11 +1655,11 @@ become available.
 @findex image-dired-display-previous
   With point in the thumbnail buffer, you can type @key{RET}
 (@code{image-dired-display-this}) to display the image in another
-window.  Use the standard Emacs movement key bindings or the arrow
-keys to move around in the thumbnail buffer.  For easy browsing, use
-@key{SPC} (@code{image-dired-display-next}) to advance and display the
-next image.  Typing @key{DEL} (@code{image-dired-display-previous})
-backs up to the previous thumbnail and displays that instead.
+window.  Use the arrow keys to move around in the thumbnail buffer.
+For easy browsing, use @key{SPC} (@code{image-dired-display-next}) to
+advance and display the next image.  Typing @key{DEL}
+(@code{image-dired-display-previous}) backs up to the previous
+thumbnail and displays that instead.
 
 @vindex image-dired-external-viewer
   Type @kbd{C-@key{RET}}
@@ -1673,19 +1669,9 @@ in an external viewer.  You must first configure
 
   You can delete images through Image-Dired also.  Type @kbd{d}
 (@code{image-dired-flag-thumb-original-file}) to flag the image file
-for deletion in the Dired buffer.  Alternatively, you can remove an
-image's thumbnail from the thumbnail buffer without flagging the image
-for deletion, by typing @kbd{C-d} (@code{image-dired-delete-char}).
-
-@findex image-dired-dired-toggle-marked-thumbs
-@findex image-dired-dired-display-external
-@findex image-dired-dired-display-image
-  You could also use Image-Dired for ``inline'' operations (i.e.,
-right into the Dired buffer).  Type @kbd{C-t C-t}, and the thumbnails
-of the selected images in Dired will appear in front of their names
-(@code{image-dired-dired-toggle-marked-thumbs}).  @kbd{C-t i} and
-@kbd{C-t x} will display the image under the point in Emacs or with
-the external viewer, respectively.
+for deletion in the Dired buffer.  You can also delete the thumbnail
+image from the thumbnail buffer with @kbd{C-d}
+(@code{image-dired-delete-char}).
 
   More advanced features include @dfn{image tags}, which are metadata
 used to categorize image files.  The tags are stored in a plain text
@@ -1698,18 +1684,14 @@ in the minibuffer.  To mark files having a certain tag, type @kbd{C-t f}
 (@code{image-dired-mark-tagged-files}).  After marking image files
 with a certain tag, you can use @kbd{C-t d} to view them.
 
-@findex image-dired-dired-comment-files
-@findex image-dired-dired-edit-comment-and-tags
   You can also tag a file directly from the thumbnail buffer by typing
-@kbd{t t}, and you can remove a tag by typing @kbd{t r}.  There is
-also a special tag called ``comment'' for each file (it is not a tag
-in the exact same sense as the other tags, it is handled slightly
-differently).  That is used to enter a comment or description about
-the image.  You comment a file from the thumbnail buffer by typing
+@kbd{t t} and you can remove a tag by typing @kbd{t r}.  There is also
+a special tag called ``comment'' for each file (it is not a tag in
+the exact same sense as the other tags, it is handled slightly
+differently).  That is used to enter a comment or description about the
+image.  You comment a file from the thumbnail buffer by typing
 @kbd{c}.  You will be prompted for a comment.  Type @kbd{C-t c} to add
 a comment from Dired (@code{image-dired-dired-comment-files}).
-@kbd{C-t e} will bring a buffer to edit comment and tags
-(@code{image-dired-dired-edit-comment-and-tags}).
 
 @vindex image-dired-thumb-visible-marks
   Files that are marked in Dired will also be marked in Image-Dired if

doc/emacs/display.texi

@@ -154,7 +154,7 @@ the buffer will be momentarily unfontified.
 @vindex redisplay-skip-fontification-on-input
 Finally, a third alternative to these variables is
 @code{redisplay-skip-fontification-on-input}.  If this variable is
-non-@code{nil}, skip some fontifications if there's input pending.
+non-@code{nil}, skip some fontifications is there's input pending.
 This usually does not affect the display because redisplay is
 completely skipped anyway if input was pending, but it can make
 scrolling smoother by avoiding unnecessary fontification.
@@ -1024,65 +1024,17 @@ customize-group @key{RET} font-lock-faces @key{RET}}.  You can then
 use that customization buffer to customize the appearance of these
 faces.  @xref{Face Customization}.
 
-@cindex just-in-time (JIT) font-lock
-@cindex background syntax highlighting
-  Fontifying very large buffers can take a long time.  To avoid large
-delays when a file is visited, Emacs initially fontifies only the
-visible portion of a buffer.  As you scroll through the buffer, each
-portion that becomes visible is fontified as soon as it is displayed;
-this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT})
-Lock.  You can control how JIT Lock behaves, including telling it to
-perform fontification while idle, by customizing variables in the
-customization group @samp{jit-lock}.  @xref{Specific Customization}.
-
-  The information that major modes use for determining which parts of
-buffer text to fontify and what faces to use can be based on several
-different ways of analyzing the text:
-
-@itemize @bullet
-@item
-Search for keywords and other textual patterns based on regular
-expressions (@pxref{Regexp Search,, Regular Expression Search}).
-
-@item
-Find syntactically distinct parts of text based on built-in syntax
-tables (@pxref{Syntax Tables,,, elisp, The Emacs Lisp Reference
-Manual}).
-
-@item
-Use syntax tree produced by a full-blown parser, via a special-purpose
-library, such as the tree-sitter library (@pxref{Parsing Program
-Source,,, elisp, The Emacs Lisp Reference Manual}), or an external
-program.
-@end itemize
-
-@menu
-* Traditional Font Lock::  Font Lock based on regexps and syntax tables.
-* Parser-based Font Lock:: Font Lock based on external parser.
-@end menu
-
-@node Traditional Font Lock
-@subsection Traditional Font Lock
-@cindex traditional font-lock
-
-  ``Traditional'' methods of providing font-lock information are based
-on regular-expression search and on syntactic analysis using syntax
-tables built into Emacs.  This subsection describes the use and
-customization of font-lock for major modes which use these traditional
-methods.
-
 @vindex font-lock-maximum-decoration
-  You can control the amount of fontification applied by Font Lock
-mode by customizing the variable @code{font-lock-maximum-decoration},
-for major modes that support this feature.  The value of this variable
-should be a number (with 1 representing a minimal amount of
-fontification; some modes support levels as high as 3); or @code{t},
-meaning ``as high as possible'' (the default).  To be effective for a
-given file buffer, the customization of
-@code{font-lock-maximum-decoration} should be done @emph{before} the
-file is visited; if you already have the file visited in a buffer when
-you customize this variable, kill the buffer and visit the file again
-after the customization.
+  You can customize the variable @code{font-lock-maximum-decoration}
+to alter the amount of fontification applied by Font Lock mode, for
+major modes that support this feature.  The value should be a number
+(with 1 representing a minimal amount of fontification; some modes
+support levels as high as 3); or @code{t}, meaning ``as high as
+possible'' (the default).  To be effective for a given file buffer,
+the customization of @code{font-lock-maximum-decoration} should be
+done @emph{before} the file is visited; if you already have the file
+visited in a buffer when you customize this variable, kill the buffer
+and visit the file again after the customization.
 
 You can also specify different numbers for particular major modes; for
 example, to use level 1 for C/C++ modes, and the default level
@@ -1130,59 +1082,16 @@ keywords by customizing the @code{font-lock-ignore} option,
 @pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference
 Manual}.
 
-@node Parser-based Font Lock
-@subsection Parser-based Font Lock
-@cindex font-lock via tree-sitter
-@cindex parser-based font-lock
-  If your Emacs was built with the tree-sitter library, it can use the
-results of parsing the buffer text by that library for the purposes of
-fontification.  This is usually faster and more accurate than the
-``traditional'' methods described in the previous subsection, since
-the tree-sitter library provides full-blown parsers for programming
-languages and other kinds of formatted text which it supports.  Major
-modes which utilize the tree-sitter library are named
-@code{@var{foo}-ts-mode}, with the @samp{-ts-} part indicating the use
-of the library.  This subsection documents the Font Lock support based
-on the tree-sitter library.
-
-@vindex treesit-font-lock-level
-  You can control the amount of fontification applied by Font Lock
-mode of major modes based on tree-sitter by customizing the variable
-@code{treesit-font-lock-level}.  Its value is a number between 1 and
-4:
-
-@table @asis
-@item Level 1
-This level usually fontifies only comments and function names in
-function definitions.
-@item Level 2
-This level adds fontification of keywords, strings, and data types.
-@item Level 3
-This is the default level; it adds fontification of assignments,
-numbers, etc.
-@item Level 4
-This level adds everything else that can be fontified: operators,
-delimiters, brackets, other punctuation, function names in function
-calls, property look ups, variables, etc.
-@end table
-
-@vindex treesit-font-lock-feature-list
-@noindent
-What exactly constitutes each of the syntactical categories mentioned
-above depends on the major mode and the parser grammar used by
-tree-sitter for the major-mode's language.  However, in general the
-categories follow the conventions of the programming language or the
-file format supported by the major mode.  The buffer-local value of
-the variable @code{treesit-font-lock-feature-list} holds the
-fontification features supported by a tree-sitter based major mode,
-where each sub-list shows the features provided by the corresponding
-fontification level.
-
-  Once you change the value of @code{treesit-font-lock-level} via
-@w{@kbd{M-x customize-variable}} (@pxref{Specific Customization}), it
-takes effect immediately in all the existing buffers and for files you
-visit in the future in the same session.
-
+@cindex just-in-time (JIT) font-lock
+@cindex background syntax highlighting
+  Fontifying large buffers can take a long time.  To avoid large
+delays when a file is visited, Emacs initially fontifies only the
+visible portion of a buffer.  As you scroll through the buffer, each
+portion that becomes visible is fontified as soon as it is displayed;
+this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT})
+Lock.  You can control how JIT Lock behaves, including telling it to
+perform fontification while idle, by customizing variables in the
+customization group @samp{jit-lock}.  @xref{Specific Customization}.
 
 @node Highlight Interactively
 @section Interactive Highlighting
@@ -1402,11 +1311,7 @@ right-to-left paragraphs.
 functionality especially in @code{prog-mode} and its descendants
 (@pxref{Major Modes}) to indicate the position of a specific column
 that has some special meaning for formatting the source code of a
-program.  This assumes the buffer uses a fixed-pitch font, where all
-the characters (with the possible exception of double-width
-characters) have the same width on display.  If the buffer uses
-variable-pitch fonts, the fill-column indicators on different lines
-might appear unaligned.
+program.
 
   To activate the fill-column indication display, use the minor modes
 @code{display-fill-@-column-indicator-mode} and

doc/emacs/emacs.texi

@@ -383,10 +383,6 @@ Controlling the Display
 * Visual Line Mode::       Word wrap and screen line-based editing.
 * Display Custom::         Information on variables for customizing display.
 
-Font Lock
-* Traditional Font Lock::  Font Lock based on regexps and syntax tables.
-* Parser-based Font Lock:: Font Lock based on external parser.
-
 Searching and Replacement
 
 * Incremental Search::     Search happens as you type the string.

doc/emacs/files.texi

@@ -215,17 +215,6 @@ by the integers that Emacs can represent (@pxref{Buffers}).  If you
 try, Emacs displays an error message saying that the maximum buffer
 size has been exceeded.
 
-@vindex treesit-max-buffer-size
-  If you try to visit a file whose major mode (@pxref{Major Modes})
-uses the tree-sitter parsing library, Emacs will display a warning if
-the file's size in bytes is larger than the value of the variable
-@code{treesit-max-buffer-size}.  The default value is 40 megabytes for
-64-bit Emacs and 15 megabytes for 32-bit Emacs.  This avoids the
-danger of having Emacs run out of memory by preventing the activation
-of major modes based on tree-sitter in such large buffers, because a
-typical tree-sitter parser needs about 10 times as much memory as the
-text it parses.
-
 @cindex wildcard characters in file names
 @vindex find-file-wildcards
   If the file name you specify contains shell-style wildcard
@@ -1737,13 +1726,9 @@ only the hunks within the region.
 Re-generate the current hunk (@code{diff-refresh-hunk}).
 
 @item C-c C-w
-@vindex diff-ignore-whitespace-switches
 @findex diff-ignore-whitespace-hunk
-Re-generate the current hunk, disregarding changes in whitespace.
-With a non-@code{nil} prefix arg, re-generate all the hunks
-(@code{diff-ignore-whitespace-hunk}).  This calls @code{diff-command}
-with @code{diff-ignore-whitespace-switches}, which defaults to
-@samp{-b}, meaning ignore changes in whitespace only.
+Re-generate the current hunk, disregarding changes in whitespace
+(@code{diff-ignore-whitespace-hunk}).
 
 @item C-x 4 A
 @findex diff-add-change-log-entries-other-window
@@ -2289,15 +2274,10 @@ behavior by using the options @code{image-auto-resize} and
 @code{image-auto-resize-on-window-resize}.
 
 @findex image-transform-fit-to-window
-@kindex s w (Image mode)
 @findex image-transform-set-percent
-@kindex s p (Image mode)
 @findex image-transform-set-scale
-@kindex s s (Image mode)
 @findex image-transform-reset-to-initial
-@kindex s 0 (Image mode)
 @findex image-transform-reset-to-original
-@kindex s o (Image mode)
 To resize the image manually you can use the command
 @code{image-transform-fit-to-window} bound to @kbd{s w} that fits the
 image to both the window height and width.  To scale the image to a
@@ -2358,94 +2338,6 @@ frames at once.  You can go to a specific frame with @kbd{F}
 (@code{image-reverse-speed}) reverses it.  The command @kbd{a 0}
 (@code{image-reset-speed}) resets the speed to the original value.
 
-In addition to the above key bindings, which are specific to Image
-mode, images shown in any Emacs buffer have special key bindings when
-point is at or inside the image:
-
-@table @kbd
-@cindex resize images
-@cindex image resize
-@findex image-increase-size
-@kindex i + (Image mode)
-@item i +
-Increase the image size (@code{image-increase-size}) by 20%.  Prefix
-numeric argument controls the increment; the value of @var{n} means to
-multiply the size by the factor of @w{@code{1 + @var{n} / 10}}, so
-@w{@kbd{C-u 5 i +}} means to increase the size by 50%.
-
-@findex image-decrease-size
-@kindex i - (Image mode)
-@item i -
-Decrease the image size (@code{image-increase-size}) by 20%.  Prefix
-numeric argument controls the decrement; the value of @var{n} means to
-multiply the size by the factor of @w{@code{1 - @var{n} / 10}}, so
-@w{@kbd{C-u 3 i -}} means to decrease the size by 30%.
-
-@cindex rotating images
-@cindex image rotation
-@findex image-rotate
-@kindex i r (Image mode)
-@item i r
-Rotate the image by 90 degrees clockwise (@code{image-rotate}).
-With the prefix argument, rotate by 90 degrees counter-clockwise instead.
-Note that this command is not available for sliced images.
-
-@findex image-flip-horizontally
-@kindex i h (Image mode)
-@item i h
-Flip the image horizontally (@code{image-flip-horizontally}).  This
-presents the image as if reflected in a vertical mirror.
-Note that this command is not available for sliced images.
-
-@findex image-flip-vertically
-@kindex i v (Image mode)
-@item i v
-Flip the image vertically (@code{image-flip-vertically}).  This
-presents the image as if reflected in a horizontal mirror.
-Note that this command is not available for sliced images.
-
-@findex image-save
-@kindex i o (Image mode)
-@item i o
-Save the image to a file (@code{image-save}).  This command prompts
-you for the name of the file to save the image.
-
-@cindex cropping images
-@vindex image-crop-crop-command
-@findex image-crop
-@kindex i c (Image mode)
-@item i c
-Crop the image (@code{image-crop}).  This command is available only if
-your system has an external program installed that can be used for
-cropping and cutting of images; the user option
-@code{image-crop-crop-command} determines what program to use, and
-defaults to the ImageMagick's @command{convert} program.  The command
-displays the image with a rectangular frame superimposed on it, and
-lets you use the mouse to move and resize the frame.  Type @kbd{m} to
-cause mouse movements to move the frame instead of resizing it; type
-@kbd{s} to move a square frame instead.  When you are satisfied with
-the position and size of the cropping frame, type @kbd{@key{RET}} to
-actually crop the part under the frame; or type @kbd{q} to exit
-without cropping.  You can then save the cropped image using @w{@kbd{i
-o}} or @w{@kbd{M-x image-save}}.
-
-@findex image-cut
-@kindex i x (Image mode)
-@vindex image-cut-color
-@vindex image-crop-cut-command
-@item i x
-Cut a rectangle from the image (@code{image-cut}).  This works the
-same as @code{image-crop} (and also requires an external program,
-defined by the variable @code{image-crop-cut-command}, to perform the
-image cut), but instead of cropping the image, it removes the part
-inside the frame and fills that part with the color specified by
-@code{image-cut-color}.  With prefix argument, the command prompts for
-the color to use.
-@end table
-
-The size and rotation commands are ``repeating'', which means that you
-can continue adjusting the image without using the @kbd{i} prefix.
-
 @cindex ImageMagick support
 @vindex imagemagick-enabled-types
 @vindex imagemagick-types-inhibit

doc/emacs/frames.texi

@@ -334,7 +334,6 @@ In this way, you can use the mouse to move point over a button without
 activating it.  Dragging the mouse over or onto a button has its usual
 behavior of setting the region, and does not activate the button.
 
-@vindex mouse-1-click-follows-link
   You can change how @kbd{mouse-1} applies to buttons by customizing
 the variable @code{mouse-1-click-follows-link}.  If the value is a
 positive integer, that determines how long you need to hold the mouse

doc/emacs/help.texi

@@ -317,16 +317,6 @@ by using the @kbd{M-x shortdoc} command.  This will prompt you for an
 area of interest, e.g., @code{string}, and pop you to a buffer where
 many of the functions relevant for handling strings are listed.
 
-You can also request that documentation of functions and commands
-shown in @file{*Help*} buffers popped by @kbd{C-h f} includes examples
-of their use.  To that end, add the following to your initialization
-file (@pxref{Init File}):
-
-@example
-(add-hook 'help-fns-describe-function-functions
-          #'shortdoc-help-fns-examples-function)
-@end example
-
 @kindex C-h v
 @findex describe-variable
   @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but

doc/emacs/macos.texi

@@ -201,6 +201,13 @@ Setting a lower number makes the trackpad more sensitive, and a higher
 number makes the trackpad less sensitive.
 @end table
 
+@subsection Font Panel
+
+@findex ns-popup-font-panel
+The standard Mac / GNUstep font panel is accessible with @kbd{M-x
+ns-popup-font-panel} and will set the default font in the frame most
+recently used or clicked on.
+
 @c  To make the setting permanent, use @samp{Save Options} in the
 @c Options menu, or run @code{menu-bar-options-save}.
 

doc/emacs/maintaining.texi

@@ -94,20 +94,6 @@ is useful when you perform version control commands outside Emacs
 different version control system, or remove it from version control
 entirely.
 
-@cindex VC commands, in Dired buffers
-@cindex filesets, VC, in Dired buffers
-  VC is also enabled automatically in Dired buffers (@pxref{Dired})
-showing directories whose files are controlled by a VCS@.  All VC
-commands described in this section can be invoked from any Dired
-buffer showing a directory with VC-controlled files; any files that
-are marked in a Dired buffer (@pxref{Marks vs Flags}) are considered
-to belong to the current fileset, and VC commands operate on the files
-in this fileset.  This allows you to construct VC filesets including
-any files you want, regardless of their VC state.  (If no files are
-marked when a VC command is invoked from a Dired buffer, the file
-shown on the current line in the buffer is considered the only file in
-the fileset.)
-
 @menu
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.
@@ -485,10 +471,7 @@ collection of one or more files that a VC operation acts on.  When you
 type VC commands in a buffer visiting a version-controlled file, the
 VC fileset is simply that one file.  When you type them in a VC
 Directory buffer, and some files in it are marked, the VC fileset
-consists of the marked files (@pxref{VC Directory Mode}).  Likewise,
-when you invoke a VC command from a Dired buffer, the VC fileset
-consists of the marked files (@pxref{Marks vs Flags}), defaulting to
-the file shown on the current line if no files are marked.
+consists of the marked files (@pxref{VC Directory Mode}).
 
   On modern changeset-based version control systems (@pxref{VCS
 Changesets}), VC commands handle multi-file VC filesets as a group.
@@ -512,9 +495,7 @@ action on the current VC fileset: either registering it with a version
 control system, or committing it, or unlocking it, or merging changes
 into it.  The precise actions are described in detail in the following
 subsections.  You can use @kbd{C-x v v} either in a file-visiting
-buffer, in a Dired buffer, or in a VC Directory buffer; in the latter
-two cases the command operates on the fileset consisting of the marked
-files.
+buffer, in a Dired buffer, or in a VC Directory buffer.
 
   Note that VC filesets are distinct from the named filesets used
 for viewing and visiting files in functional groups
@@ -859,7 +840,7 @@ details.
 
   If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
 (@pxref{Dired}), the file listed on the current line is treated as the
-current VC fileset.  The VC fileset can also include several marked files.
+current VC fileset.
 
 @ifnottex
 @findex vc-ediff
@@ -1019,25 +1000,16 @@ Search the change history for a specified pattern.
 @findex vc-print-log
   @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
 @file{*vc-change-log*}, showing the history of changes made to the
-current fileset in the long form, including who made the changes, the
-dates, and the log entry for each change (these are the same log
-entries you would enter via the @file{*vc-log*} buffer; @pxref{Log
-Buffer}).  When invoked from a buffer visiting a file, the current
-fileset consists of that single file, and point in the displayed
-@file{*vc-change-log*} buffer is centered at the revision of that
-file.  When invoked from a VC Directory buffer (@pxref{VC Directory
-Mode}) or from a Dired buffer (@pxref{Dired}), the fileset consists of
-all the marked files, defaulting to the file shown on the current line
-in the directory buffer if no file is marked.
+current file, including who made the changes, the dates, and the log
+entry for each change (these are the same log entries you would enter
+via the @file{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
+centered at the revision of the file currently being visited.  With a
+prefix argument, the command prompts for the revision to center on,
+and the maximum number of revisions to display.
 
-  If the fileset includes one or more directories, the resulting
-@file{*vc-change-log*} buffer shows a short log of changes (one line
-for each change), if the VC backend supports that; otherwise it shows
-the log in the long form.
-
-  With a prefix argument, the command prompts for the revision to
-center on in the @file{*vc-change-log*} buffer and for the maximum
-number of revisions to display.
+  If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
+Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
+file listed on the current line.
 
 @kindex C-x v L
 @findex vc-print-root-log
@@ -1243,11 +1215,6 @@ called PCL-CVS which is specialized for CVS@.  @xref{Top, , About
 PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
 @end ifnottex
 
-  You can also invoke VC commands from Dired buffers (@pxref{Dired}).
-In that case, any VC command you invoke considers the marked files as
-the current fileset (@pxref{Basic VC Editing}), defaulting to the file
-on the current line if no files are marked.
-
 @menu
 * Buffer: VC Directory Buffer.      What the buffer looks like and means.
 * Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
@@ -1364,18 +1331,11 @@ point is on a directory entry, mark all files in that directory tree
 listed files and directories.
 
 @findex vc-dir-mark-by-regexp
-@item % m
-@itemx * %
+@item %
 You can use this command to mark files by regexp
 (@code{vc-dir-mark-by-regexp}).  If given a prefix, unmark files
 instead.
 
-@findex vc-dir-mark-registered-files
-@item * r
-You can use this command to mark files that are in one of registered
-states, including edited, added or removed.
-(@code{vc-dir-mark-registered-files}).
-
 @item G
 Add the file under point to the list of files that the VC should
 ignore (@code{vc-dir-ignore}).  For instance, if the VC is Git, it
@@ -2283,25 +2243,16 @@ buffer, but doesn't select any of them.
 
 @kindex M-,
 @findex xref-go-back
-  To go back to places @emph{from where} you've displayed the
-definition, use @kbd{M-,} (@code{xref-go-back}).  It jumps back to the
+  To go back to places @emph{from where} you've displayed the definition,
+use @kbd{M-,} (@code{xref-go-back}).  It jumps back to the
 point of the last invocation of @kbd{M-.}.  Thus you can find and
 examine the definition of something with @kbd{M-.} and then return to
-where you were with @kbd{M-,}.  @kbd{M-,} allows you to retrace the
-steps you made forward in the history of places, all the way to the
-first place in history, where you first invoked @kbd{M-.}, or to any
-place in-between.
+where you were with @kbd{M-,}.
 
 @kindex C-M-,
 @findex xref-go-forward
-  If you previously went back too far with @kbd{M-,}, or want to
-re-examine a place from which you went back, you can use @kbd{C-M-,}
-(@code{xref-go-forward}) to go forward again.  This is similar to
-using @kbd{M-.}, except that you don't need on each step to move point
-to the identifier whose definition you want to look up.  @kbd{C-M-,}
-allows you to retrace all the steps you made back in the history of
-places, all the way to the last place in history, where you invoked
-@kbd{M-,}, or to any place in-between.
+  If you previously went back too far with @kbd{M-,}, @kbd{C-M-,}
+(@code{xref-go-forward}) can be used to go forward again.
 
 @findex xref-etags-mode
   Some major modes install @code{xref} support facilities that might

doc/emacs/mini.texi

@@ -313,27 +313,19 @@ may be defined in your Emacs session.  For example, if a command
 called @code{authorize-me} was defined, Emacs could only complete
 as far as @samp{aut}.)
 
-  If you type @kbd{@key{TAB}} again immediately, it cannot determine
-the next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So
-it does not add any characters; instead, @key{TAB} displays a list of
-all possible completions in another window.
+  If you type @key{TAB} again immediately, it cannot determine the
+next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
+does not add any characters; instead, @key{TAB} displays a list of all
+possible completions in another window.
 
   Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
 the only command name that starts with this is @code{auto-fill-mode}.
-If you now type @kbd{@key{TAB}}, completion fills in the rest of the
+If you now type @key{TAB}, completion fills in the rest of the
 argument @samp{auto-fill-mode} into the minibuffer.
 
   Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to
 enter @samp{auto-fill-mode}.
 
-  @key{TAB} also works while point is not at the end of the
-minibuffer.  In that case, it will fill in text both at point and at
-the end of the minibuffer.  If you type @kbd{M-x autocm}, then press
-@kbd{C-b} to move point before the @samp{m}, you can type
-@kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
-at the end of the minibuffer, so that the minibuffer contains
-@samp{autoconf-mode}.
-
 @node Completion Commands
 @subsection Completion Commands
 
@@ -961,14 +953,12 @@ File ‘foo.el’ exists; overwrite? (y or n)
 @end smallexample
 
 @cindex yes or no prompt
-@vindex yes-or-no-prompt
   The second type of yes-or-no query is typically employed if giving
 the wrong answer would have serious consequences; it thus features a
-longer prompt ending with @samp{(yes or no)} (or the value of
-@code{yes-or-no-prompt} if you've customized that).  For example, if
-you invoke @kbd{C-x k} (@code{kill-buffer}) on a file-visiting buffer
-with unsaved changes, Emacs activates the minibuffer with a prompt
-like this:
+longer prompt ending with @samp{(yes or no)}.  For example, if you
+invoke @kbd{C-x k} (@code{kill-buffer}) on a file-visiting buffer with
+unsaved changes, Emacs activates the minibuffer with a prompt like
+this:
 
 @smallexample
 Buffer foo.el modified; kill anyway? (yes or no)

doc/emacs/misc.texi

@@ -470,7 +470,11 @@ documents.  It provides features such as slicing, zooming, and
 searching inside documents.  It works by converting the document to a
 set of images using the @command{gs} (GhostScript) or
 @command{pdfdraw}/@command{mutool draw} (MuPDF) commands and other
-external tools, and then displays those converted images.
+external tools @footnote{PostScript files require GhostScript, DVI
+files require @code{dvipdf} or @code{dvipdfm}, OpenDocument and
+Microsoft Office documents require the @code{unoconv} tool, and EPUB,
+CBZ, FB2, XPS and OXPS files require @code{mutool} to be available.},
+and displaying those images.
 
 @findex doc-view-toggle-display
 @findex doc-view-minor-mode
@@ -747,8 +751,6 @@ Command Output*"} (@code{shell-command-buffer-name}) buffer (if the
 output is long).  The variables @code{resize-mini-windows} and
 @code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when
 Emacs should consider the output to be too long for the echo area.
-Note that customizing @code{shell-command-dont-erase-buffer},
-described below, can affect what is displayed in the echo area.
 
   For instance, one way to decompress a file named @file{foo.gz} is to
 type @kbd{M-! gunzip foo.gz @key{RET}}.  That shell command normally
@@ -865,10 +867,6 @@ Restores the position of point as it was before inserting the
 shell-command output.
 @end table
 
-Note that if this option is non-@code{nil}, the output shown in the
-echo area could be from more than just the last command, since the
-echo area just displays a portion of the output buffer.
-
 In case the output buffer is not the current buffer, shell command
 output is appended at the end of this buffer.
 
@@ -2745,12 +2743,10 @@ desktop reloading, since it bypasses the init file, where
 @findex desktop-revert
   You can have separate saved desktop configurations in different
 directories; starting Emacs from a directory where you have a saved
-desktop configuration will restore that configuration, provided that
-you customize @code{desktop-path} to prepend @file{.} (the current
-directory) to the other directories there.  You can save the current
-desktop and reload the one saved in another directory by typing
-@kbd{M-x desktop-change-dir}.  Typing @kbd{M-x desktop-revert} reverts
-to the previously reloaded desktop.
+desktop configuration will restore that configuration.  You can save
+the current desktop and reload the one saved in another directory by
+typing @kbd{M-x desktop-change-dir}.  Typing @kbd{M-x desktop-revert}
+reverts to the previously reloaded desktop.
 
 @vindex desktop-load-locked-desktop
   The file in which Emacs saves the desktop is locked while the

doc/emacs/modes.texi

@@ -429,19 +429,11 @@ For example, one element normally found in the list has the form
 @code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C
 mode for files whose names end in @file{.c}.  (Note that @samp{\\} is
 needed in Lisp syntax to include a @samp{\} in the string, which must
-be used to suppress the special meaning of @samp{.} in regexps.)
-
-@cindex backup files, choosing a major mode
-@cindex encrypted files, choosing a major mode
-If the element has the form @w{@code{(@var{regexp} @var{mode-function}
-@var{flag})}} and @var{flag} is non-@code{nil}, then after calling
-@var{mode-function} (if it is non-@code{nil}), Emacs discards the
-suffix that matched @var{regexp} and searches the list again for
-another match.  This ``recursive extension stripping'' is used for
-files which have multiple extensions, and the ``outer'' extension
-hides the ``inner'' one that actually specifies the right mode.  For
-example, backup files and GPG-encrypted files with @file{.gpg}
-extension use this feature.
+be used to suppress the special meaning of @samp{.} in regexps.)  If
+the element has the form @code{(@var{regexp} @var{mode-function}
+@var{flag})} and @var{flag} is non-@code{nil}, then after calling
+@var{mode-function}, Emacs discards the suffix that matched
+@var{regexp} and searches the list again for another match.
 
 @vindex auto-mode-case-fold
   On GNU/Linux and other systems with case-sensitive file names, Emacs
@@ -473,12 +465,9 @@ specify which mode you prefer.
   If you have changed the major mode of a buffer, you can return to
 the major mode Emacs would have chosen automatically, by typing
 @kbd{M-x normal-mode}.  This is the same function that
-@code{find-file} calls to choose the major mode.  If the buffer is
-visiting a file, this command also processes the file's @samp{-*-}
-line and file-local variables list (if any).  @xref{File Variables}.
-If the buffer doesn't visit a file, the command processes only the
-major mode specification, if any, in the @samp{-*-} line and in the
-file-local variables list.
+@code{find-file} calls to choose the major mode.  It also processes
+the file's @samp{-*-} line or local variables list (if any).
+@xref{File Variables}.
 
 @vindex change-major-mode-with-file-name
   The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to

doc/emacs/package.texi

@@ -329,15 +329,15 @@ version of the package, a newer version is also installed.
 @section Package Installation
 
 @findex package-install
-@findex package-upgrade
-@findex package-upgrade-all
+@findex package-update
+@findex package-update-all
   Packages are most conveniently installed using the package menu
 (@pxref{Package Menu}), but you can also use the command @kbd{M-x
 package-install}.  This prompts for the name of a package with the
 @samp{available} status, then downloads and installs it.  Similarly,
-if you want to upgrade a package, you can use the @kbd{M-x
-package-upgrade} command, and if you want to upgrade all the packages,
-you can use the @kbd{M-x package-upgrade-all} command.
+if you want to update a package, you can use the @kbd{M-x
+package-update} command, and if you just want to update all the
+packages, you can use the @kbd{M-x package-update-all} command.
 
 @cindex package requirements
   A package may @dfn{require} certain other packages to be installed,
@@ -551,13 +551,36 @@ bugs.
 source code for a package directly from source.  The command will also
 automatically ensure that all files are byte-compiled and auto-loaded,
 just like with a regular package.  Packages installed this way behave
-just like any other package.  You can upgrade them using
-@code{package-upgrade} or @code{package-upgrade-all} and delete them
+just like any other package.  You can update them using
+@code{package-update} or @code{package-update-all} and delete them
 again using @code{package-delete}.  They are even displayed in the
 regular package listing.  If you just wish to clone the source of a
 package, without adding it to the package list, use
 @code{package-vc-checkout}.
 
+@vindex package-vc-selected-packages
+@findex package-vc-install-selected-packages
+  An alternative way to use @code{package-vc-install} is via the
+@code{package-vc-selected-packages} user option.  This is an alist of
+packages to install, where each key is a package name and the value is
+@code{nil}, indicating that any revision is to install, a string,
+indicating a specific revision or a package specification plist.  The
+side effect of setting the user option is to install the package, but
+the process can also be manually triggered using the function
+@code{package-vc-install-selected-packages}.  Here is an example of
+how the user option:
+
+@example
+@group
+(setopt package-vc-selected-packages
+        '((modus-themes . "0f39eb3fd9") ;specific revision
+          (auctex . nil)                ;any revision
+          (foo                          ;a package specification
+           :url "https://git.sv.gnu.org/r/foo-mode.git"
+           :branch "trunk")))
+@end group
+@end example
+
 @findex package-report-bug
 @findex package-vc-prepare-patch
   With the source checkout, you might want to reproduce a bug against
@@ -578,80 +601,3 @@ from the package directory (@pxref{Package Files}) to your checkout
 and initializes the code.  Note that you might have to use
 @code{package-vc-refresh} to repeat the initialization and update the
 autoloads.
-
-@subsection Specifying Package Sources
-@cindex package specification
-@cindex specification, for source packages
-
-  To install a package from source, Emacs must know where to get the
-package's source code (such as a code repository) and basic
-information about the structure of the code (such as the main file in
-a multi-file package).  A @dfn{package specification} describes these
-properties.
-
-  When supported by a package archive (@pxref{Package
-Archives,,,elisp, The Emacs Lisp Reference Manual}), Emacs can
-automatically download a package's specification from said archive.
-If the first argument passed to @code{package-vc-install} is a symbol
-naming a package, then Emacs will use the specification provided by
-the archive for that package.
-
-@example
-@group
-;; Emacs will download BBDB's specification from GNU ELPA:
-(package-vc-install 'bbdb)
-@end group
-@end example
-
-  The first argument to @code{package-vc-install} may also be a
-package specification.  This allows you to install source packages
-from locations other than the known archives listed in the user option
-@code{package-archives}.  A package specification is a list of the
-form @code{(@var{name} . @var{spec})}, in which @var{spec} should be a
-property list using any of the keys in the table below.
-
-For definitions of basic terms for working with code repositories and
-version control systems, see @ref{VCS Concepts,,,emacs, The GNU Emacs
-Manual}.
-
-@table @code
-@item :url
-A string providing the URL that specifies the repository from which to
-fetch the package's source code.
-
-@item :branch
-A string providing the revision of the code to install.  Do not
-confuse this with a package's version number.
-
-@item :lisp-dir
-A string providing the repository-relative name of the directory to
-use for loading the Lisp sources, which defaults to the root directory
-of the repository.
-
-@item :main-file
-A string providing the main file of the project, from which to gather
-package metadata.  If not given, the default is the package name with
-".el" appended to it.
-
-@item :doc
-A string providing the repository-relative name of the documentation
-file from which to build an Info file.  This can be a Texinfo file or
-an Org file.
-
-@item :vc-backend
-A symbol naming the VC backend to use for downloading a copy of the
-package's repository (@pxref{Version Control Systems,,,emacs, The GNU
-Emacs Manual}).  If omitted, Emacs will attempt to make a guess based
-on the provided URL, or, failing that, the process will fall back onto
-the value of @code{package-vc-default-backend}.
-@end table
-
-@example
-@group
-;; Specifying information manually:
-(package-vc-install
-  '(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git"
-         :lisp-dir "lisp"
-         :doc "doc/bbdb.texi"))
-@end group
-@end example

doc/emacs/programs.texi

@@ -163,7 +163,6 @@ Emacs we use it for all languages.
 * Left Margin Paren::   An open-paren or similar opening delimiter
                           starts a defun if it is at the left margin.
 * Moving by Defuns::    Commands to move over or mark a major definition.
-* Moving by Sentences:: Commands to move over certain code units.
 * Imenu::               Making buffer indexes as menus.
 * Which Function::      Which Function mode shows which function you are in.
 @end menu
@@ -255,77 +254,6 @@ they do their standard jobs in a way better fitting a particular
 language.  Other major modes may replace any or all of these key
 bindings for that purpose.
 
-@cindex nested defuns
-@vindex treesit-defun-tactic
-  Some programming languages supported @dfn{nested defuns}, whereby a
-defun (such as a function or a method or a class) can be defined
-inside (i.e., as part of the body) of another defun.  The commands
-described above by default find the beginning and the end of the
-@emph{innermost} defun around point.  Major modes based on the
-tree-sitter library provide control of this behavior: if the variable
-@code{treesit-defun-tactic} is set to the value @code{top-level}, the
-defun commands will find the @emph{outermost} defuns instead.
-
-@node Moving by Sentences
-@subsection Moving by Sentences
-@cindex sentences, in programming languages
-
-  These commands move point or set up the region based on units of
-code, also called @dfn{sentences}.  Even though sentences are usually
-considered when writing human languages, Emacs can use the same
-commands to move over certain constructs in programming languages
-(@pxref{Sentences}, @pxref{Moving by Defuns}).  In a programming
-language a sentence is usually a complete language construct smaller
-than defuns, but larger than sexps (@pxref{List Motion,,, elisp, The
-Emacs Lisp Reference Manual}).  What exactly is a sentence in this
-case depends on the programming language, but usually it is a complete
-statement, such as a variable definition and initialization, or a
-conditional statement.  An example of a sentence in the C language
-could be
-
-@example
-int x = 5;
-@end example
-
-@noindent
-or in the JavaScript language it could look like
-
-@example
-@group
-const thing = () => console.log("Hi");
-@end group
-@group
-const foo = [1] == '1'
-  ? "No way"
-  : "...";
-@end group
-
-@end example
-
-@table @kbd
-@item M-a
-Move to beginning of current or preceding sentence
-(@code{backward-sentence}).
-@item M-e
-Move to end of current or following sentence (@code{forward-sentence}).
-@end table
-
-@cindex move to beginning or end of sentence
-@cindex sentence, move to beginning or end
-@kindex M-a @r{(programming modes)}
-@kindex M-e @r{(programming modes)}
-@findex backward-sentence @r{(programming modes)}
-@findex forward-sentence @r{(programming modes)}
-  The commands to move to the beginning and end of the current
-sentence are @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e}
-(@code{forward-sentence}).  If you repeat one of these commands, or
-use a positive numeric argument, each repetition moves to the next
-sentence in the direction of motion.
-
-  @kbd{M-a} with a negative argument @minus{}@var{n} moves forward
-@var{n} times to the next end of a sentence.  Likewise, @kbd{M-e} with
-a negative argument moves back to the start of a sentence.
-
 @node Imenu
 @subsection Imenu
 @cindex index of buffer definitions
@@ -610,27 +538,20 @@ then indent it like this:
 @item C-c C-q
 @kindex C-c C-q @r{(C mode)}
 @findex c-indent-defun
-@findex c-ts-mode-indent-defun
 Reindent the current top-level function definition or aggregate type
-declaration (@code{c-indent-defun} in CC mode,
-@code{c-ts-mode-indent-defun} in @code{c-ts-mode} based on tree-sitter).
+declaration (@code{c-indent-defun}).
 
 @item C-M-q
 @kindex C-M-q @r{(C mode)}
 @findex c-indent-exp
-@findex prog-indent-sexp
-Reindent each line in the balanced expression (@pxref{Expressions}),
-also known as ``sexp'', that follows point.  In CC mode, this invokes
-@code{c-indent-exp}; in tree-sitter based @code{c-ts-mode} this
-invokes a more general @code{prog-indent-sexp}.  A prefix argument
-inhibits warning messages about invalid syntax.
+Reindent each line in the balanced expression that follows point
+(@code{c-indent-exp}).  A prefix argument inhibits warning messages
+about invalid syntax.
 
 @item @key{TAB}
 @findex c-indent-line-or-region
 Reindent the current line, active region, or block starting on this
-line (@code{c-indent-line-or-region}).  With prefix argument, rigidly
-reindent the balanced expression which starts on the current line, if
-the current line needs reindentation.
+line (@code{c-indent-line-or-region}).
 
 @vindex c-tab-always-indent
 If @code{c-tab-always-indent} is @code{t}, this command always reindents
@@ -665,8 +586,7 @@ onto the indentation of the @dfn{anchor statement}.
 
 @table @kbd
 @item C-c . @var{style} @key{RET}
-Select a predefined style @var{style} (@code{c-set-style} in CC mode,
-@code{c-ts-mode-set-style} in @code{c-ts-mode} based on tree-sitter).
+Select a predefined style @var{style} (@code{c-set-style}).
 @end table
 
   A @dfn{style} is a named collection of customizations that can be
@@ -682,7 +602,6 @@ typing @kbd{C-M-q} at the start of a function definition.
 
 @kindex C-c . @r{(C mode)}
 @findex c-set-style
-@findex c-ts-mode-set-style
   To choose a style for the current buffer, use the command @w{@kbd{C-c
 .}}.  Specify a style name as an argument (case is not significant).
 This command affects the current buffer only, and it affects only
@@ -691,11 +610,11 @@ the code already in the buffer.  To reindent the whole buffer in the
 new style, you can type @kbd{C-x h C-M-\}.
 
 @vindex c-default-style
-  When using CC mode, you can also set the variable
-@code{c-default-style} to specify the default style for various major
-modes.  Its value should be either the style's name (a string) or an
-alist, in which each element specifies one major mode and which
-indentation style to use for it.  For example,
+  You can also set the variable @code{c-default-style} to specify the
+default style for various major modes.  Its value should be either the
+style's name (a string) or an alist, in which each element specifies
+one major mode and which indentation style to use for it.  For
+example,
 
 @example
 (setq c-default-style
@@ -712,11 +631,6 @@ one of the C-like major modes; thus, if you specify a new default
 style for Java mode, you can make it take effect in an existing Java
 mode buffer by typing @kbd{M-x java-mode} there.
 
-@vindex c-ts-mode-indent-style
-  When using the tree-sitter based @code{c-ts-mode}, you can set the
-default indentation style by customizing the variable
-@code{c-ts-mode-indent-style}.
-
   The @code{gnu} style specifies the formatting recommended by the GNU
 Project for C; it is the default, so as to encourage use of our
 recommended style.
@@ -1387,12 +1301,6 @@ this, change the value of the variable @code{Man-switches} to
 @kbd{M-p} to switch between man pages in different sections.  The mode
 line shows how many manual pages are available.
 
-@vindex Man-prefer-synchronous-call
-  By default, @kbd{M-x man} calls the @code{man} program
-asynchronously.  You can force the invocation to be synchronous by
-customizing @code{Man-prefer-synchronous-calls} to a non-@code{nil}
-value.
-
 @findex woman
 @cindex manual pages, on MS-DOS/MS-Windows
   An alternative way of reading manual pages is the @kbd{M-x woman}

doc/emacs/text.texi

@@ -253,10 +253,6 @@ value of @code{sentence-end-double-space}.
 of a sentence.  Set the variable @code{sentence-end-without-period} to
 @code{t} in such cases.
 
-  Even though the above mentioned sentence movement commands are based
-on human languages, other Emacs modes can set these command to get
-similar functionality (@pxref{Moving by Sentences}).
-
 @node Paragraphs
 @section Paragraphs
 @cindex paragraphs
@@ -623,12 +619,7 @@ variable @code{fill-column}.  The default value (@pxref{Locals}) is
 is to use the command @kbd{C-x f} (@code{set-fill-column}).  With a
 numeric argument, it uses that as the new fill column.  With just
 @kbd{C-u} as argument, it sets @code{fill-column} to the current
-horizontal position of point.  Note that, by its very nature,
-@code{fill-column} is measured in column units; the actual position of
-that column on a graphical display depends on the font being used.  In
-particular, using variable-pitch fonts will cause the
-@code{fill-column} occupy different horizontal positions on display in
-different lines.
+horizontal position of point.
 
 @cindex centering
 @findex center-line
@@ -967,6 +958,8 @@ hooks.
 @cindex invisible lines
 
 @findex outline-mode
+@findex outline-minor-mode
+@vindex outline-minor-mode-prefix
 @vindex outline-mode-hook
   Outline mode is a major mode derived from Text mode, which is
 specialized for editing outlines.  It provides commands to navigate
@@ -989,19 +982,6 @@ previous visible line.  Killing the ellipsis at the end of a visible
 line really kills all the following invisible text associated with the
 ellipsis.
 
-@menu
-* Outline Minor Mode::  Outline mode to use with other major modes.
-* Outline Format::      What the text of an outline looks like.
-* Outline Motion::      Special commands for moving through outlines.
-* Outline Visibility::  Commands to control what is visible.
-* Outline Views::       Outlines and multiple views.
-* Foldout::             Folding means zooming in on outlines.
-@end menu
-
-@node Outline Minor Mode
-@subsection Outline Minor Mode
-
-@findex outline-minor-mode
   Outline minor mode is a buffer-local minor mode which provides the
 same commands as the major mode, Outline mode, but can be used in
 conjunction with other major modes.  You can type @kbd{M-x
@@ -1010,7 +990,6 @@ buffer, or use a file-local variable setting to enable it in a
 specific file (@pxref{File Variables}).
 
 @kindex C-c @@ @r{(Outline minor mode)}
-@vindex outline-minor-mode-prefix
   The major mode, Outline mode, provides special key bindings on the
 @kbd{C-c} prefix.  Outline minor mode provides similar bindings with
 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
@@ -1026,16 +1005,22 @@ this variable is @code{insert}, the buttons are inserted directly into
 the buffer text, so @key{RET} on the button will also toggle display
 of the section, like a mouse click does.  If the value is
 @code{in-margins}, Outline minor mode will use the window margins to
-indicate that a section is hidden.  The buttons are customizable as icons
-(@pxref{Icons}).
+indicate that a section is hidden.
 
 @vindex outline-minor-mode-cycle
   If the @code{outline-minor-mode-cycle} user option is
-non-@code{nil}, the @kbd{TAB} and @kbd{S-@key{TAB}} keys that cycle
-the visibility are enabled on the outline heading lines
-(@pxref{Outline Visibility, outline-cycle}).  @kbd{TAB} cycles hiding,
-showing the sub-heading, and showing all for the current section.
-@kbd{S-@key{TAB}} does the same for the entire buffer.
+non-@code{nil}, the @kbd{TAB} and @kbd{S-@key{TAB}} keys are enabled on the
+outline heading lines.  @kbd{TAB} cycles hiding, showing the
+sub-heading, and showing all for the current section.  @kbd{S-@key{TAB}}
+does the same for the entire buffer.
+
+@menu
+* Outline Format::      What the text of an outline looks like.
+* Outline Motion::      Special commands for moving through outlines.
+* Outline Visibility::  Commands to control what is visible.
+* Outline Views::       Outlines and multiple views.
+* Foldout::             Folding means zooming in on outlines.
+@end menu
 
 @node Outline Format
 @subsection Format of Outlines

doc/emacs/trouble.texi

@@ -496,43 +496,8 @@ Customization}.
   If you think you have found a bug in Emacs, please report it.  We
 cannot promise to fix it, or always to agree that it is a bug, but we
 certainly want to hear about it.  The same applies for new features
-you would like to see added.  This section will help you to determine
-whether you found a bug, and if so, construct an effective bug report.
-
-The general procedure when you find something that could be a bug is
-as follows:
-
-@itemize @bullet
-@item
-See if what you found is a known problem or a bug that was already
-reported and/or fixed.  @xref{Known Problems}, where you will find how
-to look for known problems and bugs.
-
-@item
-If you are unsure whether the behavior you see is a bug, see @ref{Bug
-Criteria}, which tells what we consider as clear bugs in Emacs.
-
-@item
-Once you decide you found a bug, see @ref{Understanding Bug
-Reporting}, which helps you in describing what you see in the most
-efficient manner, making our job of reproducing the issue and
-investigating it easier.
-
-@item
-Next, see @ref{Checklist, Checklist for Bug Reports}, where we
-describe in detail how to submit a bug report and what information to
-include in it.  In a nutshell, you submit a bug report via electronic
-mail using the Emacs command @code{report-emacs-bug}, which assists
-you in doing so.  Submitting a bug report starts the process of
-investigating and fixing the bug, where you will receive copies of
-email messages discussing the bug, in which we might ask you to
-provide more information, test possible fixes, etc.
-
-@item
-Finally, if you want to propose specific changes to Emacs, whether to
-fix a bug, add a new feature, or improve our documentation, please see
-@ref{Sending Patches}, for details about submitting such changes.
-@end itemize
+you would like to see added.  The following sections will help you to
+construct an effective bug report.
 
 @menu
 * Known Problems::               How to read about known problems and bugs.
@@ -544,10 +509,9 @@ fix a bug, add a new feature, or improve our documentation, please see
 
 @node Known Problems
 @subsection Reading Existing Bug Reports and Known Problems
-@cindex known bugs and problems
 
-  Before reporting a bug, if at all possible, please check to see if
-we already know about it.  Indeed, it may already have been fixed in a
+  Before reporting a bug, if at all possible please check to see if it
+is already known about.  Indeed, it may already have been fixed in a
 later release of Emacs, or in the development version.  Here is a list
 of the main places you can read about known issues:
 
@@ -555,26 +519,20 @@ of the main places you can read about known issues:
 @item
 The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it.  This
 file contains a list of particularly well-known issues that have been
-encountered in compiling, installing and running Emacs, with special
-emphasis on issues caused by other software that cannot be easily
-solved in Emacs.  Often, you will find there suggestions for
-workarounds and solutions.
+encountered in compiling, installing and running Emacs.  Often, there
+are suggestions for workarounds and solutions.
 
 @cindex bug tracker
-@cindex issue tracker
-@cindex search known bugs
 @item
-The GNU Bug Tracker at @url{https://debbugs.gnu.org}.  Emacs bugs and
-issues are filed in the tracker under the @samp{emacs} package.  The
-tracker records information about the status of each bug, the initial
-bug report, and the follow-up messages by the bug reporter and Emacs
-developers who participate in discussing and fixing the bug.  You can
-search for bugs by subject, severity, and other criteria.  For more
-complex search criteria, use
-@url{https://debbugs.gnu.org/cgi/search.cgi}.
+The GNU Bug Tracker at @url{https://debbugs.gnu.org}.  Emacs bugs are
+filed in the tracker under the @samp{emacs} package.  The tracker
+records information about the status of each bug, the initial bug
+report, and the follow-up messages by the bug reporter and Emacs
+developers.  You can search for bugs by subject, severity, and other
+criteria.
 
 @cindex debbugs package
-Instead of browsing the bug tracker as a web page, you can browse it
+Instead of browsing the bug tracker as a webpage, you can browse it
 from Emacs using the @code{debbugs} package, which can be downloaded
 via the Package Menu (@pxref{Packages}).  This package provides the
 command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
@@ -600,14 +558,14 @@ used, and is mainly of historical interest.  At one time, it was used
 for bug reports in development (i.e., not yet released) versions of
 Emacs.  You can read the archives for 2003 to mid 2007 at
 @url{https://lists.gnu.org/r/emacs-pretest-bug/}.  Nowadays,
-email messages sent to this list are redirected to
-@samp{bug-gnu-emacs}.
+it is an alias for @samp{bug-gnu-emacs}.
 
 @item
 The @samp{emacs-devel} mailing list.  Sometimes people report bugs to
 this mailing list.  This is not the main purpose of the list, however,
 and it is much better to send bug reports to the bug list.  You should
 not feel obliged to read this list before reporting a bug.
+
 @end itemize
 
 
@@ -670,21 +628,20 @@ to begin by reporting them to the package developers.
 
 @node Understanding Bug Reporting
 @subsection Understanding Bug Reporting
-@cindex bug reporting, principles
+@cindex bug reporting
 @cindex report an Emacs bug, how to
 
-  When you decide that there is a bug, it is important to report it,
+  When you decide that there is a bug, it is important to report it
 and to report it in a way which is useful.  What is most useful is an
 exact description of what commands you type, starting with the shell
-command to run Emacs, until the problem happens, and the effects
-produced by typing those commands.
+command to run Emacs, until the problem happens.
 
   The most important principle in reporting a bug is to report
 @emph{facts}.  Hypotheses and verbal descriptions are no substitute
 for the detailed raw data.  Reporting the facts is straightforward,
 but many people strain to posit explanations and report them instead
 of the facts.  If the explanations are based on guesses about how
-Emacs is implemented, they night not be useful; meanwhile, lacking the
+Emacs is implemented, they will be useless; meanwhile, lacking the
 facts, we will have no real information about the bug.  If you want to
 actually @emph{debug} the problem, and report explanations that are
 more than guesses, that is useful---but please include the raw facts
@@ -704,23 +661,19 @@ problem.  There is no way we could guess that we should try visiting a
 file with a @samp{z} in its name.
 
   You should not even say ``visit a file'' instead of @kbd{C-x C-f}.
-That's because a file can be visited in more than one way, and there's
-no certainty that all of them reproduce the problem.  Similarly,
-rather than saying ``if I have three characters on the line'', say
-``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if that is the
-way you entered the text---that is, tell us about the text which in
-your case produced the problem.
+Similarly, rather than saying ``if I have three characters on the
+line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if
+that is the way you entered the text.
 
   If possible, try quickly to reproduce the bug by invoking Emacs with
 @command{emacs -Q} (so that Emacs starts with no initial
 customizations; @pxref{Initial Options}), and repeating the steps that
 you took to trigger the bug.  If you can reproduce the bug this way,
-that rules out bugs in your personal customizations and makes the bug
-much easier to reproduce.  Then your bug report should begin by
-stating that you started Emacs with @command{emacs -Q}, followed by
-the exact sequence of steps for reproducing the bug.  If possible,
-inform us of the exact contents of any file that is needed to
-reproduce the bug.
+that rules out bugs in your personal customizations.  Then your bug
+report should begin by stating that you started Emacs with
+@command{emacs -Q}, followed by the exact sequence of steps for
+reproducing the bug.  If possible, inform us of the exact contents of
+any file that is needed to reproduce the bug.
 
   Some bugs are not reproducible from @command{emacs -Q}; some are not
 easily reproducible at all.  In that case, you should report what you
@@ -734,7 +687,6 @@ separate bug report for each.
 @subsection Checklist for Bug Reports
 @cindex checklist before reporting a bug
 @cindex bug reporting, checklist
-@cindex report bugs in Emacs
 
   Before reporting a bug, first try to see if the problem has already
 been reported (@pxref{Known Problems}).
@@ -754,7 +706,7 @@ information; you should still read and follow the guidelines below, so
 you can enter the other crucial information by hand before you send
 the message.  You may feel that some of the information inserted by
 @kbd{M-x report-emacs-bug} is not relevant, but unless you are
-absolutely sure, it is best to leave it, so that the developers can
+absolutely sure it is best to leave it, so that the developers can
 decide for themselves.
 
 When you have finished writing your report, type @kbd{C-c C-c} and it
@@ -769,26 +721,24 @@ If you cannot send mail from inside Emacs, you can copy the
 text of your report to your normal mail client (if your system
 supports it, you can type @kbd{C-c M-i} to have Emacs do this for you)
 and send it to that address.  Or you can simply send an email to that
-address describing the problem, including the necessary information
-mentioned below.
+address describing the problem.
 
 If you want to submit code to Emacs (to fix a problem or implement a
 new feature), the easiest way to do this is to send a patch to the
-Emacs issue tracker.  Use the @kbd{M-x submit-emacs-patch} command for
-that, which works much the same as when reporting bugs; @pxref{Sending
-Patches}.
+Emacs issue tracker.  This is done with the @kbd{M-x
+submit-emacs-patch} command, and works much the same as when reporting
+bugs.
 
 In any case, your report will be sent to the @samp{bug-gnu-emacs}
 mailing list, and stored in the GNU Bug Tracker at
 @url{https://debbugs.gnu.org}.  Please include a valid reply email
 address, in case we need to ask you for more information about your
 report.  Submissions are moderated, so there may be a delay before
-your report actually appears on the tracker.
+your report appears.
 
 You do not need to know how the GNU Bug Tracker works in order to
-report a bug, but if you want to, you can read the tracker's
-@uref{https://debbugs.gnu.org/Advanced.html, online documentation} to
-see the various features you can use.
+report a bug, but if you want to, you can read the tracker's online
+documentation to see the various features you can use.
 
 All mail sent to the @samp{bug-gnu-emacs} mailing list is also
 gatewayed to the @samp{gnu.emacs.bug} newsgroup.  The reverse is also
@@ -799,43 +749,55 @@ tracker.
 
 If your data is more than 500,000 bytes, please don't include it
 directly in the bug report; instead, offer to send it on request, or
-make it available online and say where.  Large attachments are best
-sent compressed.
+make it available online and say where.
 
 The GNU Bug Tracker will assign a bug number to your report; please
-use it in the following discussions, keeping the bug address in the
-list of recipients, so that the bug discussion is recorded by the
-tracker.  The bug address will look like
-@samp{@var{nnnnn}@@debbugs.gnu.org}, where @var{nnnnn} is the bug
-number.
+use it in the following discussions.
 
   To enable maintainers to investigate a bug, your report
 should include all these things:
 
 @itemize @bullet
 @item
-A description of what behavior you observe that you believe is
-incorrect.  For example, ``The Emacs process gets a fatal signal'', or,
-``The resulting text is as follows, which I think is wrong.''
+The version number of Emacs.  Without this, we won't know whether there is any
+point in looking for the bug in the current version of GNU Emacs.
 
-Of course, if the bug is that Emacs gets a fatal signal, then one can't
-miss it.  But if the bug is incorrect text, the maintainer might fail to
-notice what is wrong.  Why leave it to chance?
+@findex emacs-version
+@kbd{M-x report-emacs-bug} includes this information automatically,
+but if you are not using that command for your report you can get the
+version number by typing @kbd{M-x emacs-version @key{RET}}.  If that
+command does not work, you probably have something other than GNU
+Emacs, so you will have to report the bug somewhere else.
 
-Even if the problem you experience is a fatal signal, you should still
-say so explicitly.  Suppose something strange is going on, such as, your
-copy of the source is out of sync, or you have encountered a bug in the
-C library on your system.  (This has happened!)  Your copy might crash
-and the copy here might not.  If you @emph{said} to expect a crash, then
-when Emacs here fails to crash, we would know that the bug was not
-happening.  If you don't say to expect a crash, then we would not know
-whether the bug was happening---we would not be able to draw any
-conclusion from our observations.
+@item
+The type of machine you are using, and the operating system name and
+version number (again, automatically included by @w{@kbd{M-x
+report-emacs-bug}}).  @w{@kbd{M-x emacs-version @key{RET}}} provides
+this information too.  Copy its output from the @file{*Messages*}
+buffer, so that you get it all and get it accurately, or use
+@w{@kbd{C-u M-x emacs-version @key{RET}}} to insert the version
+information into the current buffer.
 
-Usually, description of the behavior and of the way to reproduce the
-problem needs to specify one or more of the following aspects:
+@item
+The operands given to the @code{configure} command when Emacs was
+installed (automatically included by @kbd{M-x report-emacs-bug}).
+
+@item
+A complete list of any modifications you have made to the Emacs source.
+(We may not have time to investigate the bug unless it happens in an
+unmodified Emacs.  But if you've made modifications and you don't tell
+us, you are sending us on a wild goose chase.)
+
+Be precise about these changes.  A description in English is not
+enough---send a unified context diff for them.
+
+Adding files of your own, or porting to another machine, is a
+modification of the source.
+
+@item
+Details of any other deviations from the standard procedure for installing
+GNU Emacs.
 
-@itemize @minus
 @item
 The complete text of any files needed to reproduce the bug.
 
@@ -856,12 +818,79 @@ customizations.
 @cindex dribble file
 @cindex logging keystrokes
 One way to record the input to Emacs precisely is to write a dribble
-file.  To start the file, use the command @w{@kbd{M-x open-dribble-file}}.
+file.  To start the file, use the @kbd{M-x open-dribble-file} command.
 From then on, Emacs copies all your input to the specified dribble
 file until the Emacs process is killed.  Be aware that sensitive
 information (such as passwords) may end up recorded in the dribble
 file.
 
+@item
+@findex open-termscript
+@cindex termscript file
+@vindex TERM@r{, environment variable, and display bugs}
+For possible display bugs on text-mode terminals, the terminal type
+(the value of environment variable @env{TERM}), the complete termcap
+entry for the terminal from @file{/etc/termcap} (since that file is
+not identical on all machines), and the output that Emacs actually
+sent to the terminal.
+
+The way to collect the terminal output is to execute the Lisp expression
+
+@example
+(open-termscript "~/termscript")
+@end example
+
+@noindent
+using @kbd{M-:} or from the @file{*scratch*} buffer just after
+starting Emacs.  From then on, Emacs copies all terminal output to the
+specified termscript file as well, until the Emacs process is killed.
+If the problem happens when Emacs starts up, put this expression into
+your Emacs initialization file so that the termscript file will be
+open when Emacs displays the screen for the first time.
+
+Be warned: it is often difficult, and sometimes impossible, to fix a
+terminal-dependent bug without access to a terminal of the type that
+stimulates the bug.
+
+@item
+If non-@acronym{ASCII} text or internationalization is relevant, the locale that
+was current when you started Emacs.  On GNU/Linux and Unix systems, or
+if you use a POSIX-style shell such as Bash, you can use this shell
+command to view the relevant values:
+
+@smallexample
+echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
+  LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
+@end smallexample
+
+Alternatively, use the @command{locale} command, if your system has it,
+to display your locale settings.
+
+You can use the @kbd{M-!} command to execute these commands from
+Emacs, and then copy the output from the @file{*Messages*} buffer into
+the bug report.  Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
+@key{RET}} will display the value of @code{LC_ALL} in the echo area, and
+you can copy its output from the @file{*Messages*} buffer.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``The Emacs process gets a fatal signal'', or,
+``The resulting text is as follows, which I think is wrong.''
+
+Of course, if the bug is that Emacs gets a fatal signal, then one can't
+miss it.  But if the bug is incorrect text, the maintainer might fail to
+notice what is wrong.  Why leave it to chance?
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly.  Suppose something strange is going on, such as, your
+copy of the source is out of sync, or you have encountered a bug in the
+C library on your system.  (This has happened!)  Your copy might crash
+and the copy here might not.  If you @emph{said} to expect a crash, then
+when Emacs here fails to crash, we would know that the bug was not
+happening.  If you don't say to expect a crash, then we would not know
+whether the bug was happening---we would not be able to draw any
+conclusion from our observations.
+
 @item
 If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual
 fails to describe the actual behavior of Emacs, or that the text is
@@ -877,6 +906,33 @@ To get the error message text accurately, copy it from the
 @file{*Messages*} buffer into the bug report.  Copy all of it, not just
 part.
 
+@findex toggle-debug-on-error
+@pindex Edebug
+To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error}
+before the error happens (that is to say, you must give that command
+and then make the bug happen).  This causes the error to start the Lisp
+debugger, which shows you a backtrace.  Copy the text of the
+debugger's backtrace into the bug report.  @xref{Edebug,, Edebug,
+elisp, the Emacs Lisp Reference Manual}, for information on debugging
+Emacs Lisp programs with the Edebug package.
+
+This use of the debugger is possible only if you know how to make the
+bug happen again.  If you can't make it happen again, at least copy
+the whole error message.
+
+@vindex debug-on-quit
+If Emacs appears to be stuck in an infinite loop or in a very long
+operation, typing @kbd{C-g} with the variable @code{debug-on-quit}
+non-@code{nil} will start the Lisp debugger and show a backtrace.
+This backtrace is useful for debugging such long loops, so if you can
+produce it, copy it into the bug report.
+
+@vindex debug-on-event
+If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
+@code{inhibit-quit} is set), then you can try sending the signal
+specified by @code{debug-on-event} (default SIGUSR2) from outside
+Emacs to cause it to enter the debugger.
+
 @item
 Check whether any programs you have loaded into the Lisp world,
 including your initialization file, set any variables that may affect
@@ -904,89 +960,65 @@ code is in your version at a given line number, and we could not be
 certain.
 
 @item
-@findex open-termscript
-@cindex termscript file
-@vindex TERM@r{, environment variable, and display bugs}
-For possible display bugs on text-mode terminals, the terminal type
-(the value of environment variable @env{TERM}), the complete termcap
-entry for the terminal from @file{/etc/termcap} (since that file is
-not identical on all machines), and the output that Emacs actually
-sent to the terminal.
+Additional information from a C debugger such as GDB might enable
+someone to find a problem on a machine which he does not have available.
+If you don't know how to use GDB, please read the GDB manual---it is not
+very long, and using GDB is easy.  You can find the GDB distribution,
+including the GDB manual in online form, in most of the same places you
+can find the Emacs distribution.  To run Emacs under GDB, you should
+switch to the @file{src} subdirectory in which Emacs was compiled, then
+do @samp{gdb emacs}.  It is important for the directory @file{src} to be
+current so that GDB will read the @file{.gdbinit} file in this
+directory.
 
-The way to collect the terminal output is to invoke the command
-@kbd{M-x open-termscript} just after starting Emacs; it will prompt
-you for the name of the file where to record all terminal output until
-the Emacs process is killed.  If the problem happens when Emacs starts
-up, put the Lisp expression
+However, you need to think when you collect the additional information
+if you want it to show what causes the bug.
 
-@example
-(open-termscript "~/termscript")
-@end example
+@cindex backtrace for bug reports
+For example, many people send just a C-level backtrace, but that is
+not very useful by itself.  A simple backtrace with arguments often
+conveys little about what is happening inside GNU Emacs, because most
+of the arguments listed in the backtrace are pointers to Lisp objects.
+The numeric values of these pointers have no significance whatever;
+all that matters is the contents of the objects they point to (and
+most of the contents are themselves pointers).
 
-@noindent
-into your Emacs initialization file so that the termscript file will
-be open when Emacs displays the screen for the first time.
+@findex debug_print
+To provide useful information, you need to show the values of Lisp
+objects in Lisp notation.  Do this for each variable which is a Lisp
+object, in several stack frames near the bottom of the stack.  Look at
+the source to see which variables are Lisp objects, because the debugger
+thinks of them as integers.
 
-Be warned: it is often difficult, and sometimes impossible, to fix a
-terminal-dependent bug without access to a terminal of the type that
-stimulates the bug.
-@end itemize
+To show a variable's value in Lisp syntax, first print its value, then
+use the user-defined GDB command @code{pr} to print the Lisp object in
+Lisp syntax.  (If you must use another debugger, call the function
+@code{debug_print} with the object as an argument.)  The @code{pr}
+command is defined by the file @file{.gdbinit}, and it works only if you
+are debugging a running process (not with a core dump).
 
-@item
-The version number of Emacs.  Without this, we won't know whether there is any
-point in looking for the bug in the current version of GNU Emacs.
+To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
+@code{Fsignal}.
 
-@findex emacs-version
-@kbd{M-x report-emacs-bug} includes this information automatically,
-but if you are not using that command for your report you can get the
-version number by typing @kbd{M-x emacs-version @key{RET}}.  If that
-command does not work, you probably have something other than GNU
-Emacs, so you will have to report the bug somewhere else.
+For a short listing of Lisp functions running, type the GDB
+command @code{xbacktrace}.
 
-@item
-The type of machine you are using, and the operating system name and
-version number (again, automatically included by @w{@kbd{M-x
-report-emacs-bug}}).  @w{@kbd{M-x emacs-version @key{RET}}} provides
-this information too.  Copy its output from the @file{*Messages*}
-buffer, so that you get it all and get it accurately, or use
-@w{@kbd{C-u M-x emacs-version @key{RET}}} to insert the version
-information into the current buffer.
+The file @file{.gdbinit} defines several other commands that are useful
+for examining the data types and contents of Lisp objects.  Their names
+begin with @samp{x}.  These commands work at a lower level than
+@code{pr}, and are less convenient, but they may work even when
+@code{pr} does not, such as when debugging a core dump or when Emacs has
+had a fatal signal.
 
-@item
-The command-line arguments given to the @code{configure} command when
-Emacs was built (automatically included by @kbd{M-x
-report-emacs-bug}).
+@cindex debugging Emacs, tricks and techniques
+More detailed advice and other useful techniques for debugging Emacs
+are available in the file @file{etc/DEBUG} in the Emacs distribution.
+That file also includes instructions for investigating problems
+whereby Emacs stops responding (many people assume that Emacs is
+``hung'', whereas in fact it might be in an infinite loop).
 
-@item
-A complete list of any modifications you have made to the Emacs source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Emacs.  But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes.  A description in English is not
-enough---send a unified context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for installing
-GNU Emacs.
-
-@item
-If non-@acronym{ASCII} text or internationalization is relevant, the locale that
-was current when you started Emacs.   This is automatically included by @kbd{M-x
-report-emacs-bug}; alternatively, on GNU/Linux and Unix systems, or
-if you use a POSIX-style shell such as Bash, you can use this shell
-command to view the relevant values:
-
-@smallexample
-echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
-  LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
-@end smallexample
-
-You can also use the @command{locale} command, if your system has it,
-to display your locale settings.
+To find the file @file{etc/DEBUG} in your Emacs installation, use the
+directory name stored in the variable @code{data-directory}.
 @end itemize
 
 Here are some things that are not necessary in a bug report:
@@ -1043,13 +1075,17 @@ objects with @code{pr} (see above).
 A patch for the bug.
 
 A patch for the bug is useful if it is a good one.  But don't omit the
-other information that a bug report needs, such as the test case, on
-the assumption that a patch is sufficient.  We might see problems with
-your patch and decide to fix the problem another way, or we might not
+other information that a bug report needs, such as the test case, on the
+assumption that a patch is sufficient.  We might see problems with your
+patch and decide to fix the problem another way, or we might not
 understand it at all.  And if we can't understand what bug you are
 trying to fix, or why your patch should be an improvement, we mustn't
-install it.  @xref{Sending Patches}, for guidelines on how to make it
-easy for us to understand and install your patches.
+install it.
+
+@ifnottex
+@xref{Sending Patches}, for guidelines on how to make it easy for us to
+understand and install your patches.
+@end ifnottex
 
 @item
 A guess about what the bug is or what it depends on.
@@ -1058,108 +1094,6 @@ Such guesses are usually wrong.  Even experts can't guess right about
 such things without first using the debugger to find the facts.
 @end itemize
 
-If you are willing to debug Emacs and provide additional information
-about the bug, here is some useful advice:
-
-@findex toggle-debug-on-error
-@pindex Edebug
-@itemize
-@item
-If the bug manifests itself as an error message, try providing a Lisp
-backtrace for the error.  To make a backtrace for the error, use
-@kbd{M-x toggle-debug-on-error} before the error happens (that is to
-say, you must give that command and then make the bug happen).  This
-causes the error to start the Lisp debugger, which shows you a
-backtrace.  Copy the text of the debugger's backtrace into the bug
-report.  (The backtrace is more detailed if you load the relevant Lisp
-@file{*.el} source files before triggering the error, so do that if
-you know how to find and load those files.)
-
-To debug the error, we suggest using Edebug.  @xref{Edebug,, Edebug,
-elisp, the Emacs Lisp Reference Manual}, for information on debugging
-Emacs Lisp programs with the Edebug package.
-
-This use of the debugger is possible only if you know how to make the
-bug happen again.  If you can't make it happen again, at least copy
-the whole error message.
-
-@vindex debug-on-quit
-@item
-If Emacs appears to be stuck in an infinite loop or in a very long
-operation, typing @kbd{C-g} with the variable @code{debug-on-quit}
-non-@code{nil} will start the Lisp debugger and show a backtrace.
-This backtrace is useful for debugging such long loops, so if you can
-produce it, copy it into the bug report.
-
-@vindex debug-on-event
-If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
-@code{inhibit-quit} is set), then you can try sending the signal
-specified by @code{debug-on-event} (default SIGUSR2) from outside
-Emacs to cause it to enter the debugger.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy.  You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Emacs distribution.  To run Emacs under GDB, you should
-switch to the @file{src} subdirectory in which Emacs was compiled, then
-type @kbd{gdb ./emacs}.  It is important for the directory @file{src} to be
-current so that GDB will read the @file{.gdbinit} file in this
-directory.  (You can also tell GDB to read that file from inside GDB,
-by typing @kbd{source ./.gdbinit}.)
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-@cindex backtrace for bug reports
-For example, many people send just a C-level backtrace, but that is
-not very useful by itself.  A simple backtrace with arguments often
-conveys little about what is happening inside GNU Emacs, because most
-of the arguments listed in the backtrace are pointers to Lisp objects.
-The numeric values of these pointers have no significance whatever;
-all that matters is the contents of the objects they point to (and
-most of the contents are themselves pointers).
-
-@findex debug_print
-To provide useful information, you need to show the values of Lisp
-objects in Lisp notation.  Do this for each variable which is a Lisp
-object, in several stack frames near the bottom of the stack.  Look at
-the source to see which variables are Lisp objects, because the debugger
-thinks of them as integers.
-
-To show a variable's value in Lisp syntax, first print its value, then
-use the user-defined GDB command @code{pr} to print the Lisp object in
-Lisp syntax.  (If you must use another debugger, call the function
-@code{debug_print} with the object as an argument.)  The @code{pr}
-command is defined by the file @file{.gdbinit}, and it works only if you
-are debugging a running process (not with a core dump).
-
-To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
-@code{Fsignal}.
-
-For a backtrace of Lisp functions running, type the GDB command
-@code{xbacktrace}.
-
-The file @file{.gdbinit} defines several other commands that are useful
-for examining the data types and contents of Lisp objects.  Their names
-begin with @samp{x}.  These commands work at a lower level than
-@code{pr}, and are less convenient, but they may work even when
-@code{pr} does not, such as when debugging a core dump or when Emacs has
-had a fatal signal.
-
-@cindex debugging Emacs, tricks and techniques
-More detailed advice and other useful techniques for debugging Emacs
-are available in the file @file{etc/DEBUG} in the Emacs distribution.
-That file also includes instructions for investigating problems
-whereby Emacs stops responding (many people assume that Emacs is
-``hung'', whereas in fact it might be in an infinite loop).
-
-To find the file @file{etc/DEBUG} in your Emacs installation, use the
-directory name stored in the variable @code{data-directory}.
-@end itemize
-
 @node Sending Patches
 @subsection Sending Patches for GNU Emacs
 
@@ -1174,29 +1108,26 @@ work in the best of circumstances, and we can't keep up unless you do
 your best to help.
 
 Every patch must have several pieces of information before we
-can properly evaluate it.  They are described below.
+can properly evaluate it.
 
-When you have all these pieces, use the @kbd{M-x submit-emacs-patch}
-command to send the patch.  The command will prompt you for the
-Subject of the patch and a patch file.  It will then create and
-display a Message mode buffer with the patch file as an attachment,
-display the buffer, and let you explain more about the patch and add
-any other information as requested below.  When you are done, type
-@kbd{C-c C-c} to send the patch via email to the developers.  It will
-be sent to the GNU Bug Tracker at @url{https://debbugs.gnu.org}.  The
-tracker will assign a number to your submission, just like it does
-with bug reports.  The developers will usually respond, perhaps asking
-you for more details or any additional information, so be sure to
-include a valid reply email address.
+When you have all these pieces, bundle them up in a mail message and
+send it to the developers.  Sending it to
+@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
+recommended, because that list is coupled to a tracking system that
+makes it easier to locate patches.  If your patch is not complete and
+you think it needs more discussion, you might want to send it to
+@email{emacs-devel@@gnu.org} instead.  If you revise your patch,
+send it as a followup to the initial topic.
 
-Here's what we ask you to provide as part of your patch submissions:
+We prefer to get the patches as plain text, either inline (be careful
+your mail client does not change line breaks) or as MIME attachments.
 
 @itemize @bullet
 @item
-An explanation of what problem you are fixing or what improvement will
-the patches bring about:
+Include an explanation with your changes of what problem they fix or what
+improvement they bring about.
 
-@itemize @minus
+@itemize
 @item
 For a fix for an existing bug, it is
 best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
@@ -1209,28 +1140,26 @@ implementation.
 
 @item
 For a new bug, include a proper bug report for the problem you think
-you have fixed; @pxref{Checklist, Checklist for Bug Reports}.  We need
-to convince ourselves that the change is right before installing it.
-Even if it is correct, we might have trouble understanding it if we
-don't have a way to reproduce the problem it tries to fix.
+you have fixed.  We need to convince ourselves that the change is
+right before installing it.  Even if it is correct, we might have
+trouble understanding it if we don't have a way to reproduce the
+problem.
 @end itemize
 
 @item
-Include in your code changes all the comments that are appropriate to
-help people reading the source in the future understand why this
-change was needed.
+Include all the comments that are appropriate to help people reading the
+source in the future understand why this change was needed.
 
 @item
 Don't mix together changes made for different reasons.
 Send them @emph{individually}.
 
-If you make two changes for separate reasons, then we might not want
-to install them both.  We might want to install just one, or install
-each one in a different versions of Emacs.  If you send them all
-jumbled together in a single set of diffs, we have to do extra work to
-disentangle them---to figure out which parts of the change serve which
-purpose.  If we don't have time for this, we might have to postpone
-inclusion of your patches for a long time.
+If you make two changes for separate reasons, then we might not want to
+install them both.  We might want to install just one.  If you send them
+all jumbled together in a single set of diffs, we have to do extra work
+to disentangle them---to figure out which parts of the change serve
+which purpose.  If we don't have time for this, we might have to ignore
+your changes entirely.
 
 If you send each change as soon as you have written it, with its own
 explanation, then two changes never get tangled up, and we can consider
@@ -1247,46 +1176,52 @@ right away.  That gives us the option of installing it immediately if it
 is important.
 
 @item
-The patch itself.  This can be produced in one of the following ways:
+The patch itself.
+
+Use @samp{diff -u} to make your diffs.  Diffs without context are hard
+to install reliably.  More than that, they are hard to study; we must
+always study a patch to decide whether we want to install it.  Context
+format is better than contextless diffs, but we prefer the unified
+format.
+
+If you have GNU diff, use @samp{diff -u -F'^[_a-zA-Z0-9$]\+ *('} when
+making diffs of C code.  This shows the name of the function that each
+change occurs in.
 
-@itemize @minus
-@item
 If you are using the Emacs repository, make sure your copy is
 up-to-date (e.g., with @code{git pull}).  You can commit your changes
 to a private branch and generate a patch from the master version by
-using @code{git format-patch master}.  (This is the preferred method,
-as it makes our job of applying the patch easier.)  Or you can leave
-your changes uncommitted and use @code{git diff}, as described below.
+using @code{git format-patch master}. Or you can leave your changes
+uncommitted and use @code{git diff}.
 
 @item
-Use @kbd{diff -u} to make your diffs.  If you have GNU diff, use
-@w{@kbd{diff -u -F'^[_a-zA-Z0-9$]\+ *('}} when making diffs of C code.
-This shows the name of the function that each change occurs in.
-
-When producing the diffs, avoid any ambiguity as to which is the old
-version and which is the new.  Please make the old version the first
-argument to diff, and the new version the second argument.  And please
-give one version or the other a name that indicates whether it is the
-old version or your new changed one.
-@end itemize
+Avoid any ambiguity as to which is the old version and which is the new.
+Please make the old version the first argument to diff, and the new
+version the second argument.  And please give one version or the other a
+name that indicates whether it is the old version or your new changed
+one.
 
 @item
 Write the commit log entries for your changes.  This is both to save us
 the extra work of writing them, and to help explain your changes so we
 can understand them.
 
-The purpose of the commit log is to explain the rationale of the
-changes, the way the modified code solves whatever problems your patch
-is trying to fix, and also show people where to find what was changed.
-So you need to be specific about what functions you changed and why.
-For the details about our style and requirements for good commit log
-messages, please see the ``Commit messages'' section of the file
-@file{CONTRIBUTE} in the Emacs source tree.
+The purpose of the commit log is to show people where to find what was
+changed.  So you need to be specific about what functions you changed;
+in large functions, it's often helpful to indicate where within the
+function the change was.
 
-Please also look at the commit log entries of recent commits to see
-what sorts of information to put in, and to learn the style that we
-use.  Note that, unlike some other projects, we do require commit logs
-for documentation, i.e., Texinfo files.  @xref{Change Log},
+On the other hand, once you have shown people where to find the change,
+you need not explain its purpose in the change log.  Thus, if you add a
+new function, all you need to say about it is that it is new.  If you
+feel that the purpose needs explaining, it probably does---but put the
+explanation in comments in the code.  It will be more useful there.
+
+Please look at the commit log entries of recent commits to see what
+sorts of information to put in, and to learn the style that we use.
+Note that, unlike some other projects, we do require commit logs for
+documentation, i.e., Texinfo files.
+@xref{Change Log},
 @ifset WWW_GNU_ORG
 see
 @url{https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
@@ -1297,7 +1232,7 @@ Change Log Concepts, standards, GNU Coding Standards}.
 @item
 When you write the fix, keep in mind that we can't install a change that
 would break other systems.  Please think about what effect your change
-will have if compiled and/or used on another type of system.
+will have if compiled on another type of system.
 
 Sometimes people send fixes that @emph{might} be an improvement in
 general---but it is hard to be sure of this.  It's hard to install
@@ -1305,10 +1240,9 @@ such changes because we have to study them very carefully.  Of course,
 a good explanation of the reasoning by which you concluded the change
 was correct can help convince us.
 
-The safest changes are changes to the files or portions of files that
-are only used for a particular machine or a particular system.  These
-are safe because they can't create new bugs on other machines or
-systems.
+The safest changes are changes to the configuration files for a
+particular machine.  These are safe because they can't create new bugs
+on other machines.
 
 Please help us keep up with the workload by designing the patch in a
 form that is clearly safe to install.
@@ -1325,7 +1259,7 @@ There are many ways to contribute to Emacs:
 
 @itemize
 @item
-find and report bugs; @pxref{Bugs}.
+find and report bugs; @xref{Bugs}.
 
 @item
 answer questions on the Emacs user mailing list
@@ -1392,15 +1326,15 @@ before you start; it might be possible to suggest ways to make your
 extension fit in better with the rest of Emacs.
 
 When implementing a feature, please follow the Emacs coding standards;
-@pxref{Coding Standards}.  In addition, substantial contributions
-require a copyright assignment to the FSF; @pxref{Copyright Assignment}.
+@xref{Coding Standards}. In addition, non-trivial contributions
+require a copyright assignment to the FSF; @xref{Copyright Assignment}.
 
 The development version of Emacs can be downloaded from the
 repository where it is actively maintained by a group of developers.
 See the Emacs project page
 @url{https://savannah.gnu.org/projects/emacs/} for access details.
 
-It is important to write your patches based on the current working
+It is important to write your patch based on the current working
 version.  If you start from an older version, your patch may be
 outdated (so that maintainers will have a hard time applying it), or
 changes in Emacs may have made your patch unnecessary.  After you have
@@ -1463,7 +1397,7 @@ the Emacs Lisp Reference Manual
 
 @node Coding Standards
 @subsection Coding Standards
-@cindex coding standards for Emacs submissions
+@cindex coding standards
 
 Contributed code should follow the GNU Coding Standards
 @url{https://www.gnu.org/prep/standards/}. This may also be available
@@ -1498,6 +1432,10 @@ to be included in Emacs.
 @item
 Remove all trailing whitespace in all source and text files.
 
+@item
+Emacs has no convention on whether to use tabs in source code; please
+don't change whitespace in the files you edit.
+
 @item
 Use @code{?\s} instead of @code{? } in Lisp code for a space character.
 
@@ -1517,7 +1455,7 @@ packages stored in GNU ELPA, we require that the copyright be assigned
 to the FSF@.  For the reasons behind this, see
 @url{https://www.gnu.org/licenses/why-assign.html}.
 
-Copyright assignment is a simple process.  Residents of many countries
+Copyright assignment is a simple process.  Residents of some countries
 can do it entirely electronically.  We can help you get started,
 including sending you the forms you should fill, and answer any
 questions you may have (or point you to the people with the answers),

doc/emacs/vc1-xtra.texi

@@ -288,16 +288,16 @@ is about to run.
 
 @findex vc-prepare-patch
 When collaborating on projects it is common to send patches via email,
-to share changes.  You can do this using VC with the
+to share changes.  If you wish to do this using VC, you can use the
 @code{vc-prepare-patch} command.  This will prompt you for the
 revisions you wish to share, and which destination email address(es)
-to use.  Separate the revisions using the value of
-@var{crm-separator}, commas by default.  The command will then prepare
+to use.  The revisions are separated using commas (or whatever was
+configured by @var{crm-separator}).  The command will then prepare
 those revisions using your @abbr{MUA, Mail User Agent} for you to
 review and send.
 
 When invoked interactively in a Log View buffer with marked revisions,
-those marked revisions will be used.
+these revisions will be used.
 
 @vindex vc-prepare-patches-separately
 Depending on the value of the user option

doc/emacs/windows.texi

@@ -310,8 +310,8 @@ the space that it occupied is given to an adjacent window (but not the
 minibuffer window, even if that is active at the time).  Deleting the
 window has no effect on the buffer it used to display; the buffer
 continues to exist, and you can still switch to it with @kbd{C-x b}.
-The option @code{delete-window-choose-selected} controls which
-window is chosen as the new selected window instead (@pxref{Deleting
+The option @code{delete-window-choose-selected} allows to choose which
+window becomes the new selected window instead (@pxref{Deleting
 Windows,,, elisp, The Emacs Lisp Reference Manual}).
 
 @findex kill-buffer-and-window

doc/lispintro/emacs-lisp-intro.texi

@@ -6604,11 +6604,10 @@ works.  You will probably need to use @kbd{C-h f}
 (@code{describe-function}).  The newer version uses a conditional to
 determine whether the buffer has been narrowed.
 
-Also, the modern version of @code{what-line} uses
-@code{line-number-at-pos}, which among other simple expressions, such
-as @code{(goto-char (point-min))}, moves point to the beginning of the
-current line with @code{(forward-line 0)} rather than
-@code{beginning-of-line}.)
+(Also, it uses @code{line-number-at-pos}, which among other simple
+expressions, such as @code{(goto-char (point-min))}, moves point to
+the beginning of the current line with @code{(forward-line 0)} rather
+than @code{beginning-of-line}.)
 
 The @code{what-line} function as shown here has a documentation line
 and is interactive, as you would expect.  The next two lines use the

doc/lispref/buffers.texi

@@ -959,9 +959,9 @@ infinite recursion.
 
 @defun buffer-match-p condition buffer-or-name &optional arg
 This function checks if a buffer designated by @code{buffer-or-name}
-satisfies the specified @code{condition}.  Optional third argument
-@var{arg} is passed to the predicate function in @var{condition}.  A
-valid @var{condition} can be one of the following:
+satisfies a @code{condition}.  Optional third argument @var{arg} is
+passed to the predicate function in @var{condition}.  A condition can
+be one of the following:
 @itemize @bullet{}
 @item
 A string, interpreted as a regular expression.  The buffer
@@ -990,23 +990,21 @@ Satisfied if @emph{all} the conditions in @var{conds} satisfy
 Satisfied if the buffer's major mode derives from @var{expr}.
 @item major-mode
 Satisfied if the buffer's major mode is equal to @var{expr}.  Prefer
-using @code{derived-mode} instead, when both can work.
+using @code{derived-mode} instead when both can work.
 @end table
 @item t
 Satisfied by any buffer.  A convenient alternative to @code{""} (empty
-string) or @code{(and)} (empty conjunction).
+string), @code{(and)} (empty conjunction) or @code{always}.
 @end itemize
 @end defun
 
 @defun match-buffers condition &optional buffer-list arg
-This function returns a list of all buffers that satisfy the
-@code{condition}.  If no buffers match, the function returns
-@code{nil}.  The argument @var{condition} is as defined in
-@code{buffer-match-p} above.  By default, all the buffers are
-considered, but this can be restricted via the optional argument
-@code{buffer-list}, which should be a list of buffers to consider.
-Optional third argument @var{arg} will be passed to @var{condition} in
-the same way as @code{buffer-match-p} does.
+This function returns a list of all buffers that satisfy a
+@code{condition}, as defined for @code{buffer-match-p}.  By default
+all buffers are considered, but this can be restricted via the second
+optional @code{buffer-list} argument.  Optional third argument
+@var{arg} will be used by @var{condition} in the same way as
+@code{buffer-match-p} does.
 @end defun
 
 @node Creating Buffers

doc/lispref/commands.texi

@@ -99,12 +99,6 @@ is removed from the hook.
 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
 command does.
 
-  Note that, when the buffer text includes very long lines, these two
-hooks are called as if they were in a @code{with-restriction} form
-(@pxref{Narrowing}), with a
-@code{long-line-optimizations-in-command-hooks} label and with the
-buffer narrowed to a portion around point.
-
 @node Defining Commands
 @section Defining Commands
 @cindex defining commands
@@ -325,10 +319,10 @@ function @code{oclosure-interactive-form}.
 @defun oclosure-interactive-form function
 Just like @code{interactive-form}, this function takes a command and
 returns its interactive form.  The difference is that it is a generic
-function and it is only called when @var{function} is an OClosure
-(@pxref{OClosures}).  The purpose is to make it possible for some
-OClosure types to compute their interactive forms dynamically instead
-of carrying it in one of their slots.
+function and it is only called when @var{function} is an OClosure.
+The purpose is to make it possible for some OClosure types to compute
+their interactive forms dynamically instead of carrying it in one of
+their slots.
 
 This is used for example for @code{kmacro} functions in order to
 reduce their memory size, since they all share the same interactive
@@ -1960,8 +1954,8 @@ end-position of a drag event, this position list may represent a
 location outside the boundaries of the initially selected frame, in
 which case the list contains that frame in place of a window.
 
-The @code{track-mouse} macro enables generation of motion
-events within its body.  Outside of @code{track-mouse} body, Emacs
+The special form @code{track-mouse} enables generation of motion
+events within its body.  Outside of @code{track-mouse} forms, Emacs
 does not generate events for mere motion of the mouse, and these
 events do not appear.  @xref{Mouse Tracking}.
 
@@ -2395,17 +2389,6 @@ as @code{set-language-environment}), use the
 ;; Get the full localized name of the language
 (w32-get-locale-info language-id t)
 @end smallexample
-
-@cindex @code{end-session} event
-@item end-session
-This event is generated on MS-Windows when the operating system
-informs Emacs that the user terminated the interactive session, or
-that the system is shutting down.  The standard definition of this
-event is to invoke the @code{kill-emacs} command (@pxref{Killing
-Emacs}) so as to shut down Emacs in an orderly fashion; if there are
-unsaved changes, this will produce auto-save files
-(@pxref{Auto-Saving}) that the user can use after restarting the
-session to restore the unsaved edits.
 @end table
 
   If one of these events arrives in the middle of a key sequence---that
@@ -2454,7 +2437,7 @@ into another window.  That produces a pair of events like these:
 
 The frame with input focus might not take up the entire screen, and
 the user might move the mouse outside the scope of the frame.  Inside
-the @code{track-mouse} macro, that produces an event like this:
+the @code{track-mouse} special form, that produces an event like this:
 
 @smallexample
 (mouse-movement (#<frame *ielm* 0x102849a30> nil (563 . 205) 532301936))
@@ -3226,24 +3209,15 @@ unspecified, the only fallback disabled is downcasing of the last
 event.
 @end defun
 
-@vindex read-char-choice-use-read-key
 @defun read-char-choice prompt chars &optional inhibit-quit
-This function uses @code{read-from-minibuffer} to read and return a
-single character that is a member of @var{chars}, which should be a
-list of single characters.  It discards any input characters that are
-not members of @var{chars}, and shows a message to that effect.
-
-The optional argument @var{inhibit-quit} is by default ignored, but if
-the variable @code{read-char-choice-use-read-key} is non-@code{nil},
-this function uses @code{read-key} instead of
-@code{read-from-minibuffer}, and in that case @var{inhibit-quit}
-non-@code{nil} means ignore keyboard-quit events while waiting for
-valid input.  In addition, if @code{read-char-choice-use-read-key} is
-non-@code{nil}, binding @code{help-form} (@pxref{Help Functions}) to a
-non-@code{nil} value while calling this function causes it to evaluate
-@code{help-form} and display the result when the user presses
-@code{help-char}; it then continues to wait for a valid input
-character, or for keyboard-quit.
+This function uses @code{read-key} to read and return a single
+character.  It ignores any input that is not a member of @var{chars},
+a list of accepted characters.  Optionally, it will also ignore
+keyboard-quit events while it is waiting for valid input.  If you bind
+@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
+while calling @code{read-char-choice}, then pressing @code{help-char}
+causes it to evaluate @code{help-form} and display the result.  It
+then continues to wait for a valid input character, or keyboard-quit.
 @end defun
 
 @defun read-multiple-choice prompt choices &optional help-string show-help long-form

doc/lispref/compile.texi

@@ -849,12 +849,7 @@ from writing its results, the @file{*.eln} files, into a subdirectory
 of @code{user-emacs-directory} (@pxref{Init File}).  You can do that
 by either changing the value of @code{native-comp-eln-load-path}
 (@pxref{Native-Compilation Variables}) or by temporarily pointing the
-@env{HOME} environment variable to a non-existing directory.  Note
-that the latter technique might still produce a small number of
-@file{*.eln} files if Emacs needs to generate @dfn{trampolines}, which
-are used if Lisp primitives are advised or redefined in your Lisp code
-that is being natively compiled.  @xref{Native-Compilation Variables,
-trampolines}.
+@env{HOME} environment variable to a non-existing directory.
 
 @menu
 * Native-Compilation Functions::  Functions to natively-compile Lisp.
@@ -986,6 +981,24 @@ whether native-compilation is available should use this predicate.
   This section documents the variables that control
 native-compilation.
 
+@defvar inhibit-automatic-native-compilation
+If your Emacs has support for native compilation, Emacs will (by
+default) compile the Lisp files you're loading in the background, and
+then install the native-compiled versions of the functions.  If you
+wish to disable this, you can set this variable to non-@code{nil}.  If
+you want to set it permanently, this should probably be done from the
+early init file, since setting it in the normal init file is probably
+too late.
+
+While setting this variable disables automatic compilation of Lisp
+files, the compiler may still be invoked to install @dfn{trampolines}
+if any built-in functions are redefined.  However, these trampolines
+will not get written to your cache directory.
+
+You can also use the @samp{EMACS_INHIBIT_AUTOMATIC_NATIVE_COMPILATION}
+environment variable to disable native compilation.
+@end defvar
+
 @defopt native-comp-speed
 This variable specifies the optimization level for native compilation.
 Its value should be a number between @minus{}1 and 3.  Values between
@@ -1080,66 +1093,3 @@ The directories in this list are also used for writing the
 specifically, Emacs will write these files into the first writable
 directory in the list.  Thus, you can control where native-compilation
 stores the results by changing the value of this variable.
-
-@cindex disable asynchronous native compilation
-@cindex inhibit asynchronous native compilation
-@cindex asynchronous native compilation, disable
-@defvar native-comp-jit-compilation
-This variable, if non-@code{nil}, enables asynchronous (a.k.a.@:
-@dfn{just-in-time}, or @acronym{JIT}) native compilation of the
-@file{*.elc} files loaded by Emacs for which the corresponding
-@file{*.eln} files do not already exist.  This JIT compilation uses
-separate Emacs sub-processes running in batch mode, according to the
-value of @code{native-comp-async-jobs-number}.  When the JIT
-compilation of a Lisp file finishes successfully, the resulting
-@file{.eln} file is loaded and its code replaces the definition of
-functions provided by the @file{.elc} file.
-@end defvar
-
-@cindex trampolines, in native compilation
-  Setting the value of @code{native-comp-jit-compilation} to@code{nil}
-disables JIT native compilation.  However, even when JIT native
-compilation is disabled, Emacs might still need to start asynchronous
-native compilation subprocesses to produce @dfn{trampolines}.  To
-control this, use a separate variable, described below.
-
-@defvar native-comp-enable-subr-trampolines
-This variable controls generation of trampolines.  A trampoline is a
-small piece of native code required to allow calling Lisp primitives,
-which were advised or redefined, from Lisp code that was
-natively-compiled with @code{native-comp-speed} set to 2 or greater.
-Emacs stores the generated trampolines on separate @file{*.eln} files.
-By default, this variable's value is @code{t}, which enables the
-generation of trampoline files; setting it to @code{nil} disables the
-generation of trampolines.  Note that if a trampoline needed for
-advising or redefining a primitive is not available and cannot be
-generated, calls to that primitive from natively-compiled Lisp will
-ignore redefinitions and advices, and will behave as if the primitive
-was called directly from C.  Therefore, we don't recommend disabling
-the trampoline generation, unless you know that all the trampolines
-needed by your Lisp programs are already compiled and accessible to
-Emacs.
-
-The value of this variable can also be a string, in which case it
-specifies the name of a directory in which to store the generated
-trampoline @file{*.eln} files, overriding the directories in
-@code{native-comp-eln-load-path}.  This is useful if you want the
-trampolines to be generated as needed, but don't want to store them
-under the user's @env{HOME} directory or in the other public
-directories where @file{*.eln} files are kept.  However, unlike with
-directories in @code{native-comp-eln-load-path}, the trampolines will
-be stored in the directory given by the value of this variable, not in
-its version-specific subdirectory.  If the name of this directory is
-not absolute, it is interpreted relative to
-@code{invocation-directory} (@pxref{System Environment})
-
-If this variable is non-@code{nil}, and Emacs needs to produce a
-trampoline, but it cannot find any writable directory to store the
-trampoline, it will store it inside @code{temporary-file-directory}
-(@pxref{Unique File Names}).
-
-Trampolines produced when no writable directory is found to store
-them, or when this variable is a string, will only be available for
-the duration of the current Emacs session, because Emacs doesn't look
-for trampolines in either of these places.
-@end defvar

doc/lispref/control.texi

@@ -1809,9 +1809,6 @@ wish the program to continue execution despite an error in a subroutine.
 In these cases, you would use @code{condition-case} to establish
 @dfn{error handlers} to recover control in case of error.
 
-  For reporting problems without terminating the execution of the
-current command, consider issuing a warning instead.  @xref{Warnings}.
-
   Resist the temptation to use error handling to transfer control from
 one part of the program to another; use @code{catch} and @code{throw}
 instead.  @xref{Catch and Throw}.

doc/lispref/customize.texi

@@ -264,12 +264,11 @@ have any number of prefixes.
 @end table
 
 @cindex @code{custom-group} property
-The variables, faces, and subgroups of a group are stored in the
+The variables and subgroups of a group are stored in the
 @code{custom-group} property of the group's symbol.  @xref{Symbol
 Plists}.  The value of that property is a list of pairs whose
-@code{car} is the symbol of the variable or the face or the subgroup,
-and the @code{cdr} is one of the corresponding symbols
-@code{custom-variable}, @code{custom-face}, or @code{custom-group}.
+@code{car} is the variable or subgroup symbol and the @code{cdr} is
+either @code{custom-variable} or @code{custom-group}.
 @end defmac
 
 @defopt custom-unlispify-remove-prefixes
@@ -379,15 +378,8 @@ the option as a Lisp variable); preferably, though, it should not
 modify its value argument destructively.  The default for
 @var{setfunction} is @code{set-default-toplevel-value}.
 
-If defined, @var{setfunction} will also be called when evaluating a
-@code{defcustom} form with @kbd{C-M-x} in Emacs Lisp mode and when the
-@var{option}'s value is changed via the @code{setopt} macro
-(@pxref{Setting Variables, setopt}).
-
 If you specify this keyword, the variable's documentation string
-should describe how to do the same job in hand-written Lisp code,
-either by invoking @var{setfunction} directly or by using
-@code{setopt}.
+should describe how to do the same job in hand-written Lisp code.
 
 @item :get @var{getfunction}
 @kindex get@r{, @code{defcustom} keyword}

doc/lispref/display.texi

@@ -310,29 +310,29 @@ reformatted, with undesirable results.  Instead, use @code{(message
 "%s" @var{string})}.
 @end defun
 
-The following facilities allow users and Lisp programs to control how
-echo-area messages are displayed.
-
 @defvar set-message-function
 If this variable is non-@code{nil}, it should be a function of one
-argument, the text of a message to display in the echo area.  That
+argument, the text of a message to display in the echo area.  This
 function will be called by @code{message} and related functions.  If
 the function returns @code{nil}, the message is displayed in the echo
-area as usual.  If the function returns a string, that string is
-displayed in the echo area @emph{instead} of the original message.  If
-the function returns any other non-@code{nil} value, that means the
-message was already handled, so @code{message} will not display
-anything in the echo area.
+area as usual.  If this function returns a string, that string is
+displayed in the echo area instead of the original one.  If this
+function returns other non-@code{nil} values, that means the message
+was already handled, so @code{message} will not display anything in
+the echo area.  See also @code{clear-message-function} that can be
+used to clear the message displayed by this function.
 
-The default value calls @code{set-minibuffer-message}, described
-below.
+The default value is the function that displays the message at the end
+of the minibuffer when the minibuffer is active.  However, if the text
+shown in the active minibuffer has the @code{minibuffer-message} text
+property (@pxref{Special Properties}) on some character, the message
+will be displayed before the first character having that property.
 @end defvar
 
 @defvar clear-message-function
-If this variable is non-@code{nil}, it should be a function of no
-arguments; @code{message} and related functions call it when their
-argument message is @code{nil} or the empty string, to clear the echo
-area.
+If this variable is non-@code{nil}, @code{message} and related
+functions call it with no arguments when their argument message is
+@code{nil} or the empty string.
 
 Usually this function is called when the next input event arrives
 after displaying an echo-area message.  The function is expected to
@@ -358,51 +358,11 @@ with the same text; if the last function in the list returns
 function returns a non-@code{nil} value that is not a string, the
 message is considered to be handled, and no further functions in the
 list are called.
-
-The three useful functions to be put in the list that is the value of
-this option are described below.
 @end defopt
 
-@defun set-minibuffer-message message
-This function displays @var{message} in the echo-area when the
-minibuffer is not active, and at the end of the minibuffer when the
-minibuffer is active.  However, if the text shown in the active
-minibuffer has the @code{minibuffer-message} text property
-(@pxref{Special Properties}) on some character, the message will be
-displayed before the first character having that property.
-
-This function is by default the only member of the list in
-@code{set-message-functions}.
-@end defun
-
-@vindex inhibit-message-regexps
-@defun inhibit-message message
-If an echo-area @var{message} matches any regexp in the list that is
-the value of the user option @code{inhibit-message-regexps}, this
-function suppresses the display of that message and returns a
-non-@code{nil} value that is not a string.  Thus, if this function is
-in the list @code{set-message-functions}, the rest of the functions in
-the list will not be called when @var{message} matches the regexps in
-@code{inhibit-message-regexps}.  To ensure a matching @var{message}
-will never be displayed, make this function be the first element of
-the list in @code{set-message-functions}.
-@end defun
-
-@vindex multi-message-max
-@vindex multi-message-timeout
-@defun set-multi-message message
-This function accumulates several echo-area messages emitted one after
-another, and returns them as a single string in which individual
-messages are separated by newlines.  Up to @code{multi-message-max}
-recent messages can be accumulated.  The accumulated messages are
-discarded when more than @code{multi-message-timeout} seconds have
-elapsed since the time the first message was emitted.
-@end defun
-
 @defvar inhibit-message
 When this variable is non-@code{nil}, @code{message} and related functions
-will not display any messages in the Echo Area.  Echo-area messages
-are still logged in the @file{*Messages*} buffer, though.
+will not use the Echo Area to display messages.
 @end defvar
 
 @defmac with-temp-message message &rest body
@@ -752,8 +712,7 @@ echo area (which is really a special use of the minibuffer window;
 @cindex warnings
 
   @dfn{Warnings} are a facility for a program to inform the user of a
-possible problem, but continue running (as opposed to signaling an
-error, @pxref{Errors}).
+possible problem, but continue running.
 
 @menu
 * Warning Basics::      Warnings concepts and functions to report them.
@@ -766,74 +725,69 @@ error, @pxref{Errors}).
 @subsection Warning Basics
 @cindex severity level
 
-  Every warning is a textual message, which explains the problem for
-the user, with the associated @dfn{severity level} which is a symbol.
-Here are the supported severity levels, in order of decreasing
-severity, and their meanings:
+  Every warning has a textual message, which explains the problem for
+the user, and a @dfn{severity level} which is a symbol.  Here are the
+possible severity levels, in order of decreasing severity, and their
+meanings:
 
 @table @code
 @item :emergency
 A problem that will seriously impair Emacs operation soon
-if the user does not attend to it promptly.
+if you do not attend to it promptly.
 @item :error
-A report about data or circumstances that are inherently wrong.
+A report of data or circumstances that are inherently wrong.
 @item :warning
-A report about data or circumstances that are not inherently wrong,
-but raise suspicion of a possible problem.
+A report of data or circumstances that are not inherently wrong, but
+raise suspicion of a possible problem.
 @item :debug
-A report of information that may be useful if the user is currently
-debugging the Lisp program which issues the warning.
+A report of information that may be useful if you are debugging.
 @end table
 
   When your program encounters invalid input data, it can either
-signal a Lisp error by calling @code{error} or @code{signal}
-(@pxref{Signaling Errors}) or report a warning with severity
-@code{:error}.  Signaling a Lisp error is the easiest thing to do, but
-it means the signaling program cannot continue execution.  If you want
-to take the trouble of implementing a way to continue processing
-despite the invalid data, then reporting a warning of severity
-@code{:error} is the right way of informing the user of the problem.
-For instance, the Emacs Lisp byte compiler can report an error that
-way and continue compiling other functions.  (If the program signals a
-Lisp error and then handles it with @code{condition-case}, the user
-won't see the error message; reporting that as a warning instead
-avoids that problem.)
+signal a Lisp error by calling @code{error} or @code{signal} or report
+a warning with severity @code{:error}.  Signaling a Lisp error is the
+easiest thing to do, but it means the program cannot continue
+processing.  If you want to take the trouble to implement a way to
+continue processing despite the bad data, then reporting a warning of
+severity @code{:error} is the right way to inform the user of the
+problem.  For instance, the Emacs Lisp byte compiler can report an
+error that way and continue compiling other functions.  (If the
+program signals a Lisp error and then handles it with
+@code{condition-case}, the user won't see the error message; it could
+show the message to the user by reporting it as a warning.)
 
+@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
+@c "bytecomp" here?  The parens are part of warning-type-format but
+@c not part of the warning type. --xfq
 @cindex warning type
-  In addition to severity level, each warning has a @dfn{warning type}
-to classify it.  The warning type is either a symbol or a list of
-symbols.  If it is a symbol, it should be the custom group that you
-use for the program's user options; if it is a list, the first element
-of the list should be that custom group.  For example, byte compiler
-warnings use the warning type @code{(bytecomp)}.  If the warning type
-is a list, the elements of the list after the first one, which should
-be arbitrary symbols, represent subcategories of the warning: they
-will be displayed to the user to better explain the nature of the
-warning.
+  Each warning has a @dfn{warning type} to classify it.  The type is a
+list of symbols.  The first symbol should be the custom group that you
+use for the program's user options.  For example, byte compiler
+warnings use the warning type @code{(bytecomp)}.  You can also
+subcategorize the warnings, if you wish, by using more symbols in the
+list.
 
 @defun display-warning type message &optional level buffer-name
-This function reports a warning, using the string @var{message} as the
-warning text and @var{type} as the warning type.  @var{level} should
-be the severity level, and defaults to @code{:warning} if omitted or
-@code{nil}.
+This function reports a warning, using @var{message} as the message
+and @var{type} as the warning type.  @var{level} should be the
+severity level, with @code{:warning} being the default.
 
 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
-for logging the warning message.  By default, it is @file{*Warnings*}.
+for logging the warning.  By default, it is @file{*Warnings*}.
 @end defun
 
 @defun lwarn type level message &rest args
-This function reports a warning using the value returned by
-@w{@code{(format-message @var{message} @var{args}@dots{})}} as the
-message text in the @file{*Warnings*} buffer.  In other respects it is
-equivalent to @code{display-warning}.
+This function reports a warning using the value of @code{(format-message
+@var{message} @var{args}...)} as the message in the @file{*Warnings*}
+buffer.  In other respects it is equivalent to @code{display-warning}.
 @end defun
 
 @defun warn message &rest args
-This function reports a warning using the value returned by
-@w{@code{(format-message @var{message} @var{args}@dots{})}} as the
-message text, @code{emacs} as the warning type, and @code{:warning} as
-the severity level.  It exists for compatibility only; we recommend
-not using it, because you should specify a specific warning type.
+This function reports a warning using the value of @code{(format-message
+@var{message} @var{args}...)} as the message, @code{(emacs)} as the
+type, and @code{:warning} as the severity level.  It exists for
+compatibility only; we recommend not using it, because you should
+specify a specific warning type.
 @end defun
 
 @node Warning Variables
@@ -848,16 +802,15 @@ This list defines the meaning and severity order of the warning
 severity levels.  Each element defines one severity level,
 and they are arranged in order of decreasing severity.
 
-Each element has the form @w{@code{(@var{level} @var{string}
-[@var{function}])}}, where @var{level} is the severity level it
-defines.  @var{string} specifies the textual description of this
-level.  @var{string} should use @samp{%s} to specify where to put the
-warning type information, or it can omit the @samp{%s} so as not to
-include that information.
+Each element has the form @code{(@var{level} @var{string}
+@var{function})}, where @var{level} is the severity level it defines.
+@var{string} specifies the textual description of this level.
+@var{string} should use @samp{%s} to specify where to put the warning
+type information, or it can omit the @samp{%s} so as not to include
+that information.
 
 The optional @var{function}, if non-@code{nil}, is a function to call
-with no arguments, to get the user's attention.  A notable example is
-@code{ding} (@pxref{Beeping}).
+with no arguments, to get the user's attention.
 
 Normally you should not change the value of this variable.
 @end defvar
@@ -866,19 +819,18 @@ Normally you should not change the value of this variable.
 If non-@code{nil}, the value is a function to generate prefix text for
 warnings.  Programs can bind the variable to a suitable function.
 @code{display-warning} calls this function with the warnings buffer
-the current buffer, and the function can insert text into it.  That
-text becomes the beginning of the warning message.
+current, and the function can insert text in it.  That text becomes
+the beginning of the warning message.
 
 The function is called with two arguments, the severity level and its
-entry in @code{warning-levels}.  It should return a list to use
-@emph{instead} of that entry (the value need not be an actual member
-of @code{warning-levels}, but it must have the same structure).  By
-constructing this value, the function can change the severity of the
-warning, or specify different handling for a given severity level.
+entry in @code{warning-levels}.  It should return a list to use as the
+entry (this value need not be an actual member of
+@code{warning-levels}).  By constructing this value, the function can
+change the severity of the warning, or specify different handling for
+a given severity level.
 
-If the variable's value is @code{nil}, there's no prefix text, before
-the warning is displayed, starting with the @var{string} part of the
-entry in @code{warning-levels} corresponding to the warning's level.
+If the variable's value is @code{nil} then there is no function
+to call.
 @end defvar
 
 @defvar warning-series
@@ -886,18 +838,17 @@ Programs can bind this variable to @code{t} to say that the next
 warning should begin a series.  When several warnings form a series,
 that means to leave point on the first warning of the series, rather
 than keep moving it for each warning so that it appears on the last one.
-The series ends when the local binding of this variable is unbound and
+The series ends when the local binding is unbound and
 @code{warning-series} becomes @code{nil} again.
 
 The value can also be a symbol with a function definition.  That is
 equivalent to @code{t}, except that the next warning will also call
-the function with no arguments with the warnings buffer the current
-buffer.  The function can, for example, insert text which will serve
-as a header for the series of warnings.
+the function with no arguments with the warnings buffer current.  The
+function can insert text which will serve as a header for the series
+of warnings.
 
-Once a series has begun, the value of this variable is a marker which
-points to the buffer position in the warnings buffer of the start of
-the series.
+Once a series has begun, the value is a marker which points to the
+buffer position in the warnings buffer of the start of the series.
 
 The variable's normal value is @code{nil}, which means to handle
 each warning separately.
@@ -905,7 +856,7 @@ each warning separately.
 
 @defvar warning-fill-prefix
 When this variable is non-@code{nil}, it specifies a fill prefix to
-use for filling the text of each warning.
+use for filling each warning's text.
 @end defvar
 
 @defvar warning-fill-column
@@ -914,11 +865,11 @@ The column at which to fill warnings.
 
 @defvar warning-type-format
 This variable specifies the format for displaying the warning type
-in the warning text.  The result of formatting the type this way
+in the warning message.  The result of formatting the type this way
 gets included in the message under the control of the string in the
 entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
-If you bind it to the empty string @code{""} then the warning type
-won't appear at all.
+If you bind it to @code{""} then the warning type won't appear at
+all.
 @end defvar
 
 @node Warning Options
@@ -930,71 +881,38 @@ when a Lisp program reports a warning.
 
 @defopt warning-minimum-level
 This user option specifies the minimum severity level that should be
-shown immediately to the user, by popping the warnings buffer in some
-window.  The default is @code{:warning}, which means to show the
-warning buffer for any warning severity except @code{:debug}.  The
-warnings of lower severity levels will still be written into the
-warnings buffer, but the buffer will not be forced onto display.
+shown immediately to the user.  The default is @code{:warning}, which
+means to immediately display all warnings except @code{:debug}
+warnings.
 @end defopt
 
 @defopt warning-minimum-log-level
 This user option specifies the minimum severity level that should be
-logged in the warnings buffer.  Warnings of lower severity will be
-completely ignored: not written to the warnings buffer and not
-displayed.  The default is @code{:warning}, which means to log
-warnings of any severity except @code{:debug}.
+logged in the warnings buffer.  The default is @code{:warning}, which
+means to log all warnings except @code{:debug} warnings.
 @end defopt
 
 @defopt warning-suppress-types
 This list specifies which warning types should not be displayed
-immediately when they occur.  Each element of the list should be a
-list of symbols.  If an element of this list has the same elements as
-the first elements in a warning type, then the warning of that type
-will not be shown on display by popping the warnings buffer in some
-window (the warning will still be logged in the warnings buffer).
-
-For example, if the value of this variable is a list like this:
-
-@lisp
-((foo) (bar subtype))
-@end lisp
-
-@noindent
-then warnings whose types are @code{foo} or @code{(foo)} or
-@w{@code{(foo something)}} or @w{@code{(bar subtype other)}} will not
-be shown to the user.
+immediately for the user.  Each element of the list should be a list
+of symbols.  If its elements match the first elements in a warning
+type, then that warning is not displayed immediately.
 @end defopt
 
 @defopt warning-suppress-log-types
-This list specifies which warning types should be ignored: not logged
-in the warnings buffer and not shown to the user.  The structure and
-the matching of warning types are the same as for
-@code{warning-suppress-types} above.
+This list specifies which warning types should not be logged in the
+warnings buffer.  Each element of the list should be a list of
+symbols.  If it matches the first few elements in a warning type, then
+that warning is not logged.
 @end defopt
 
-@cindex warnings, suppressing during startup
-@cindex prevent warnings in init files
-  During startup, Emacs delays showing any warnings until after it
-loads and processes the site-wide and user's init files
-(@pxref{Startup Summary}).  Let-binding (@pxref{Local Variables}) the
-values of these options around some code in your init files which
-might emit a warning will therefore not work, because it will not be
-in effect by the time the warning is actually processed.  Thus, if you
-want to suppress some warnings during startup, change the values of
-the above options in your init file early enough, or put those
-let-binding forms in your @code{after-init-hook} or
-@code{emacs-startup-hook} functions.  @xref{Init File}.
-
 @node Delayed Warnings
 @subsection Delayed Warnings
 @cindex delayed warnings
-@cindex warnings, delayed
 
 Sometimes, you may wish to avoid showing a warning while a command is
 running, and only show it only after the end of the command.  You can
-use the function @code{delay-warning} for this.  Emacs automatically
-delays any warnings emitted during the early stages of startup, and
-shows them only after the init files are processed.
+use the function @code{delay-warning} for this.
 
 @defun delay-warning type message &optional level buffer-name
 This function is the delayed counterpart to @code{display-warning}
@@ -1015,7 +933,7 @@ with the same form, and the same meanings, as the argument list of
 @code{display-warning}.  Immediately after running
 @code{post-command-hook} (@pxref{Command Overview}), the Emacs
 command loop displays all the warnings specified by this variable,
-then resets the variable to @code{nil}.
+then resets it to @code{nil}.
 @end defvar
 
   Programs which need to further customize the delayed warnings
@@ -1024,9 +942,7 @@ mechanism can change the variable @code{delayed-warnings-hook}:
 @defvar delayed-warnings-hook
 This is a normal hook which is run by the Emacs command loop, after
 @code{post-command-hook}, in order to process and display delayed
-warnings.  Emacs also runs this hook during startup, after loading the
-site-start and user init files (@pxref{Startup Summary}), because
-warnings emitted before that are automatically delayed.
+warnings.
 
 Its default value is a list of two functions:
 
@@ -2429,11 +2345,10 @@ newline.  The property value can be one of several forms:
 @item t
 If the property value is @code{t}, the newline character has no
 effect on the displayed height of the line---the visible contents
-alone determine the height.  The @code{line-spacing} property of the
-newline, described below, is also ignored in this case.  This is
-useful for tiling small images (or image slices) without adding blank
-areas between the images.
-
+alone determine the height.  The @code{line-spacing} property,
+described below, is also ignored in this case.  This is useful for
+tiling small images (or image slices) without adding blank areas
+between the images.
 @item (@var{height} @var{total})
 If the property value is a list of the form shown, that adds extra
 space @emph{below} the display line.  First Emacs uses @var{height} as
@@ -2494,9 +2409,7 @@ overrides line spacings specified for the frame.
 property that can enlarge the default frame line spacing and the
 buffer local @code{line-spacing} variable: if its value is larger than
 the buffer or frame defaults, that larger value is used instead, for
-the display line ending in that newline (unless the newline also has
-the @code{line-height} property whose value is one of the special
-values which cause @code{line-spacing} to be ignored, see above).
+the display line ending in that newline.
 
   One way or another, these mechanisms specify a Lisp value for the
 spacing of each line.  The value is a height spec, and it translates
@@ -3588,11 +3501,11 @@ function finishes are the ones that really matter.
 For efficiency, we recommend writing these functions so that they
 usually assign faces to around 400 to 600 characters at each call.
 
-Note that, when the buffer text includes very long lines, these
-functions are called as if they were in a @code{with-restriction} form
-(@pxref{Narrowing}), with a
-@code{long-line-optimizations-in-fontification-functions} label and
-with the buffer narrowed to a portion around @var{pos}.
+When the buffer text includes very long lines, these functions are
+called with the buffer narrowed to a relatively small region around
+@var{pos}, and with narrowing locked, so the functions cannot use
+@code{widen} to gain access to the rest of the buffer.
+@xref{Narrowing}.
 @end defvar
 
 @node Basic Faces
@@ -5372,10 +5285,9 @@ space taken by the line-number display.
   The @code{left}, @code{center}, and @code{right} positions can be
 used with @code{:align-to} to specify a position relative to the left
 edge, center, or right edge of the text area.  When the window
-displays line numbers, and @code{:align-to} is used in display
-properties of buffer text (as opposed to header line, see below), the
-@code{left} and the @code{center} positions are offset to account for
-the screen space taken by the line-number display.
+displays line numbers, the @code{left} and the @code{center} positions
+are offset to account for the screen space taken by the line-number
+display.
 
   Any of the above window elements (except @code{text}) can also be
 used with @code{:align-to} to specify that the position is relative to
@@ -5389,11 +5301,11 @@ the left-margin, use
 :align-to (+ left-margin (0.5 . left-margin))
 @end example
 
-  If no specific base offset is set for alignment, it is always
-relative to the left edge of the text area.  For example,
-@samp{:align-to 0} aligns with the first text column in the text area.
-When the window displays line numbers, the text is considered to start
-where the space used for line-number display ends.
+  If no specific base offset is set for alignment, it is always relative
+to the left edge of the text area.  For example, @samp{:align-to 0} in a
+header-line aligns with the first text column in the text area.  When
+the window displays line numbers, the text is considered to start where
+the space used for line-number display ends.
 
   A value of the form @code{(@var{num} . @var{expr})} stands for the
 product of the values of @var{num} and @var{expr}.  For example,
@@ -5405,35 +5317,6 @@ product of the values of @var{num} and @var{expr}.  For example,
 expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
 the value of the expressions.
 
-@vindex header-line-format@r{, and } :align-to
-@cindex aligning header line, when line numbers are displayed
-@cindex header line alignment when line numbers are displayed
-  Text shown in the header line that uses @code{:align-to} display
-specifications is not automatically realigned when
-@code{display-line-numbers-mode} is turned on and off, or when the
-width of line numbers on display changes.  To arrange for the
-header-line text alignment to be updated, thus keeping the header-line
-text aligned with the buffer text, turn on the
-@code{header-line-indent-mode} in the buffer and use its two
-variables, @code{header-line-indent} and
-@code{header-line-indent-width}, in the display specification.
-@xref{Header Lines}.  Here's a simple example:
-
-@lisp
-(setq header-line-format
-      (concat (propertize " "
-                          'display
-                          '(space :align-to
-                                  (+ header-line-indent-width 10)))
-              "Column"))
-@end lisp
-
-@noindent
-This will keep the text @samp{Column} on the header line aligned with
-column 10 of buffer text, regardless of whether
-@code{display-line-numbers-mode} is on or off, and also when
-line-number display changes its width.
-
 @node Other Display Specs
 @subsection Other Display Specifications
 
@@ -6920,7 +6803,7 @@ This function puts image @var{image} in front of @var{pos} in the
 current buffer.  The argument @var{pos} should be an integer or a
 marker.  It specifies the buffer position where the image should appear.
 The argument @var{string} specifies the text that should hold the image
-as an alternative to the default @samp{x}.
+as an alternative to the default.
 
 The argument @var{image} must be an image descriptor, perhaps returned
 by @code{create-image} or stored by @code{defimage}.
@@ -6933,7 +6816,7 @@ buffer's text.
 
 Internally, this function creates an overlay, and gives it a
 @code{before-string} property containing text that has a @code{display}
-property whose value is the image.  (Whew! that was a mouthful@dots{})
+property whose value is the image.  (Whew!)
 @end defun
 
 @defun remove-images start end &optional buffer
@@ -6980,47 +6863,41 @@ This function returns @code{t} if point is on an image, and @code{nil}
 otherwise.
 @end defun
 
-@cindex operations on images
 Images inserted with the insertion functions above also get a local
 keymap installed in the text properties (or overlays) that span the
 displayed image.  This keymap defines the following commands:
 
 @table @kbd
-@findex image-increase-size
 @item i +
-Increase the image size (@code{image-increase-size})
+Increase the image size (@code{image-increase-size}).  A prefix value
+of @samp{4} means to increase the size by 40%.  The default is 20%.
 
-@findex image-decrease-size
 @item i -
-Decrease the image size (@code{image-decrease-size}).
+Decrease the image size (@code{image-increase-size}).  A prefix value
+of @samp{4} means to decrease the size by 40%.  The default is 20%.
 
-@findex image-rotate
 @item i r
-Rotate the image (@code{image-rotate}).
+Rotate the image by 90 degrees clockwise (@code{image-rotate}).
+A prefix means to rotate by 90 degrees counter-clockwise instead.
 
-@findex image-flip-horizontally
 @item i h
 Flip the image horizontally (@code{image-flip-horizontally}).
 
-@findex image-flip-vertically
 @item i v
 Flip the image vertically (@code{image-flip-vertically}).
 
-@findex image-save
 @item i o
 Save the image to a file (@code{image-save}).
 
-@findex image-crop
 @item i c
-Interactively crop the image (@code{image-crop}).
+Crop the image interactively (@code{image-crop}).
 
-@findex image-cut
 @item i x
-Interactively cut a rectangle from the image (@code{image-cut}).
+Cut a rectangle from the image interactively (@code{image-cut}).
 @end table
 
-@xref{Image Mode,,, emacs, The GNU Emacs Manual}, for more details
-about these image-specific key bindings.
+The size and rotation commands are ``repeating'', which means that you
+can continue adjusting the image without using the @kbd{i} prefix.
 
 @node Multi-Frame Images
 @subsection Multi-Frame Images

doc/lispref/elisp.texi

@@ -569,7 +569,6 @@ Functions
 * Function Cells::          Accessing or setting the function definition
                               of a symbol.
 * Closures::                Functions that enclose a lexical environment.
-* OClosures::               Function objects with meta-data.
 * Advising Functions::      Adding to the definition of a function.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler

doc/lispref/eval.texi

@@ -252,8 +252,11 @@ the original symbol.  If the contents are another symbol, this
 process, called @dfn{symbol function indirection}, is repeated until
 it obtains a non-symbol.  @xref{Function Names}, for more information
 about symbol function indirection.
-We eventually obtain a non-symbol, which ought to be a function or
-other suitable object.
+
+  One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol.
+Otherwise, we eventually obtain a non-symbol, which ought to be a
+function or other suitable object.
 
 @kindex invalid-function
   More precisely, we should now have a Lisp function (a lambda
@@ -329,17 +332,19 @@ or just
   The built-in function @code{indirect-function} provides an easy way to
 perform symbol function indirection explicitly.
 
-@defun indirect-function function
+@defun indirect-function function &optional noerror
 @anchor{Definition of indirect-function}
 This function returns the meaning of @var{function} as a function.  If
 @var{function} is a symbol, then it finds @var{function}'s function
 definition and starts over with that value.  If @var{function} is not a
 symbol, then it returns @var{function} itself.
 
-This function returns @code{nil} if the final symbol is unbound.
+This function returns @code{nil} if the final symbol is unbound.  It
+signals a @code{cyclic-function-indirection} error if there is a loop
+in the chain of symbols.
 
-There is also a second, optional argument that is obsolete and has no
-effect.
+The optional argument @var{noerror} is obsolete, kept for backward
+compatibility, and has no effect.
 
 Here is how you could define @code{indirect-function} in Lisp:
 

doc/lispref/files.texi

@@ -893,12 +893,6 @@ permissions of the file itself.)
 If the file does not exist, or if there was trouble determining
 whether the file exists, this function returns @code{nil}.
 
-@cindex empty file name, and @code{file-exists-p}
-Since a file name that is an empty string is interpreted relative to
-the current buffer's default directory (@pxref{Relative File Names}),
-calling @code{file-exists-p} with an argument that is an empty string
-will report about the buffer's default directory.
-
 @cindex dangling symlinks, testing for existence
 Directories are files, so @code{file-exists-p} can return @code{t}
 when given a directory.  However, because @code{file-exists-p} follows
@@ -1988,11 +1982,7 @@ all.
 
 @defun file-modes-number-to-symbolic modes
 This function converts a numeric file mode specification in
-@var{modes} into the equivalent string form.  The string which this
-function returns is in the same format produced by the shell command
-@kbd{ls -l} and by @code{file-attributes}, @emph{not} the symbolic
-form accepted by @code{file-modes-symbolic-to-number} and the
-@command{chmod} shell command.
+@var{modes} into the equivalent symbolic form.
 @end defun
 
 @defun set-file-times filename &optional time flag
@@ -2362,10 +2352,6 @@ form.
 @end example
 @end defun
 
-@cindex empty file name
-  A file name that is an empty string stands for the current buffer's
-default directory.
-
 @node Directory Names
 @subsection Directory Names
 @cindex directory name
@@ -2555,7 +2541,6 @@ This is for the sake of filesystems that have the concept of a
 superroot above the root directory @file{/}.  On other filesystems,
 @file{/../} is interpreted exactly the same as @file{/}.
 
-@cindex empty file names, and @code{expand-file-name}
 Expanding @file{.} or the empty string returns the default directory:
 
 @example
@@ -3390,7 +3375,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-directory-p},
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
-@code{file-group-gid}, @code{file-in-directory-p},
+@code{file-in-directory-p},
 @code{file-local-copy}, @code{file-locked-p},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
@@ -3405,8 +3390,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-system-info},
-@code{file-truename}, @code{file-user-uid},
-@code{file-writable-p},
+@code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},@*
 @code{get-file-buffer},
 @code{insert-directory},
@@ -3452,7 +3436,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-direc@discretionary{}{}{}tory-p},
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
-@code{file-group-gid}, @code{file-in-directory-p},
+@code{file-in-directory-p},
 @code{file-local-copy}, @code{file-locked-p},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
@@ -3467,8 +3451,7 @@ first, before handlers for jobs such as remote file access.
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-system-info},
-@code{file-truename}, @code{file-user-uid},
-@code{file-writable-p},
+@code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
 @code{get-file-buffer},
 @code{insert-directory},

doc/lispref/frames.texi

@@ -1474,24 +1474,19 @@ in this frame.  Its value is @code{color}, @code{grayscale} or
 
 @vindex title@r{, a frame parameter}
 @item title
-If a frame has a non-@code{nil} title, that title appears in the window
+If a frame has a non-@code{nil} title, it appears in the window
 system's title bar at the top of the frame, and also in the mode line
 of windows in that frame if @code{mode-line-frame-identification} uses
 @samp{%F} (@pxref{%-Constructs}).  This is normally the case when
 Emacs is not using a window system, and can only display one frame at
-a time.  When Emacs is using a window system, this parameter, if
-non-@code{nil}, overrides the title determined by the @code{name}
-parameter and the implicit title calculated according to
-@code{frame-title-format}.  It also overrides the title determined by
-@code{icon-title-format} for iconified frames.  @xref{Frame Titles}.
+a time.  @xref{Frame Titles}.
 
 @vindex name@r{, a frame parameter}
 @item name
-The name of the frame.  If you don't specify a name via this
-parameter, Emacs sets the frame name automatically, as specified by
-@code{frame-title-format} and @code{icon-title-format}, and that is
-the frame's title that will appear on display when Emacs uses a window
-system (unless the @code{title} parameter overrides it).
+The name of the frame.  The frame name serves as a default for the frame
+title, if the @code{title} parameter is unspecified or @code{nil}.  If
+you don't specify a name, Emacs sets the frame name automatically
+(@pxref{Frame Titles}).
 
 If you specify the frame name explicitly when you create the frame, the
 name is also used (instead of the name of the Emacs executable) when
@@ -2635,27 +2630,17 @@ frame name automatically based on a template stored in the variable
 frame is redisplayed.
 
 @defvar frame-title-format
-This variable specifies how to compute a name for a frame when you
-have not explicitly specified one (via the frame's parameters;
-@pxref{Basic Parameters}).  The variable's value is actually a mode
+This variable specifies how to compute a name for a frame when you have
+not explicitly specified one.  The variable's value is actually a mode
 line construct, just like @code{mode-line-format}, except that the
-@samp{%c}, @samp{%C}, and @samp{%l} constructs are ignored.
-@xref{Mode Line Data}.
+@samp{%c}, @samp{%C}, and @samp{%l} constructs are ignored.  @xref{Mode Line
+Data}.
 @end defvar
 
 @defvar icon-title-format
-This variable specifies how to compute the name for an iconified frame
-when you have not explicitly specified the frame's name via the
-frame's parameters.  The resulting title appears in the frame's icon
-itself.  If the value is a string, is should be a mode line construct
-like that of @code{frame-title-format}.  The value can also be
-@code{t}, which means to use @code{frame-title-format} instead; this
-avoids problems with some window managers and desktop environments,
-where a change in a frame's title (when a frame is iconified) is
-interpreted as a request to raise the frame and/or give it input
-focus.  It is also useful if you want the frame's title to be the same
-no matter if the frame is iconified or not.  The default value is a
-string identical to the default value of @code{frame-title-format}.
+This variable specifies how to compute the name for an iconified frame,
+when you have not explicitly specified the frame title.  This title
+appears in the icon itself.
 @end defvar
 
 @defvar multiple-frames
@@ -3577,7 +3562,7 @@ the mouse position list will be @code{nil} if the value is
 @code{drag-source}.  This is useful to determine if a frame is not
 directly visible underneath the mouse pointer.
 
-The @code{track-mouse} macro causes Emacs to generate mouse motion
+The @code{track-mouse} form causes Emacs to generate mouse motion
 events by binding the variable @code{track-mouse} to a
 non-@code{nil} value.  If that variable has the special value
 @code{dragging}, it additionally instructs the display engine to
@@ -4112,7 +4097,7 @@ has the same meaning as the @var{action} argument to
   Emacs implements receiving text and URLs individually for each
 window system, and does not by default support receiving other kinds
 of data as drops.  To support receiving other kinds of data, use the
-X-specific interface described below.
+X-specific interface described below:
 
 @vindex x-dnd-test-function
 @vindex x-dnd-known-types
@@ -4141,71 +4126,29 @@ depending on the specific drag-and-drop protocol being used.  For
 example, the data type used for plain text may be either
 @code{"STRING"} or @code{"text/plain"}.
 
-@cindex XDS
-@cindex direct save protocol
 @vindex x-dnd-direct-save-function
-  When Emacs runs on X window system, it supports the X Direct Save
-(@acronym{XDS}) protocol, which allows users to save a file by
-dragging and dropping it onto an Emacs window, such as a Dired window.
-To comply with the unique requirements of @acronym{XDS}, these
-drag-and-drop requests are processed specially: instead of being
-handled according to @code{x-dnd-types-alist}, they are handled by the
-@dfn{direct-save function} that is the value of the variable
-@code{x-dnd-direct-save-function}.  The value should be a function of
-two arguments, @var{need-name} and @var{filename}.  The @acronym{XDS}
-protocol uses a two-step procedure for dragging files:
-
-@enumerate 1
-@item
-The application from which the file is dragged asks Emacs to provide
-the full file name under which to save the file.  For this purpose,
-the direct-save function is called with its first argument
-@var{need-name} non-@code{nil}, and the second argument @var{filename}
-set to the basename of the file to be saved.  It should return the
-fully-expanded absolute file name under which to save the file.  For
-example, if a file is dragged to a Dired window, the natural directory
-for the file is the directory of the file shown at location of the
-drop.  If saving the file is not possible for some reason, the
-function should return @code{nil}, which will cancel the drag-and-drop
-operation.
-
-@item
-The application from which the file is dragged saves the file under
-the name returned by the first call to the direct-save function.  If
-it succeeds in saving the file, the direct-save function is called
-again, this time with the first argument @var{need-name} set to
-@code{nil} and the second argument @var{filename} set to the full
-absolute name of the saved file.  The function is then expected to do
-whatever is needed given the fact that file was saved.  For example,
-Dired should update the directory on display by showing the new file
-there.
-@end enumerate
-
-The default value of @code{x-dnd-direct-save-function} is
-@code{x-dnd-save-direct}.
-
-@defun x-dnd-save-direct need-name filename
-When called with the @var{need-name} argument non-@code{nil}, this
-function prompts the user for the absolute file name under which it
-should be saved.  If the specified file already exists, it
-additionally asks the user whether to overwrite it, and returns the
-absolute file name only if the user confirms the overwriting.
-
-When called with the @var{need-name} argument @code{nil}, it reverts
-the Dired listing if the current buffer is in Dired mode or one of its
-descendants, and otherwise visits the file by calling @code{find-file}
-(@pxref{Visiting Functions}).
-@end defun
-
-@defun x-dnd-save-direct-immediately need-name filename
-This function works like @code{x-dnd-save-direct}, but when called
-with its @var{need-name} argument non-@code{nil}, it doesn't prompt
-the user for the full name of the file to be saved; instead, it
-returns its argument @var{filename} expanded against the current
-buffer's default directory (@pxref{File Name Expansion}).  (It still
-asks for confirmation if a file by that name already exists in the
-default directory.)
-@end defun
+@c FIXME: This description is overly-complicated and confusing.  In
+@c particular, the two calls to the function basically sound
+@c identical, so it is unclear how should the function distinguish
+@c between the first and the second one.  The description of who asks
+@c whom to do what is also very hard to understand.  Needs rewording,
+@c and needs shorter sentences.  Perhaps examples could help.
+  However, @code{x-dnd-types-alist} does not handle a special kind of
+drop sent by a program that wants Emacs to tell it where to save a
+file in a specific location determined by the user.  These drops are
+instead handled by a function that is the value of the variable
+@code{x-dnd-direct-save-function}.  This function should accept two arguments.
+If the first argument is non-@code{nil}, then the second argument is a
+file name to save (with leading directories) that the other
+program recommends, and the
+function should return the full file name under which it should be
+saved.  After the function completes, Emacs will ask the other program
+to save the file under the name that was returned, and if the file was
+successfully saved, call the function again with the first argument
+set to a non-@code{nil} value and the second argument set to the file
+name that was returned.  The function should then perform whatever
+action is appropriate (i.e., opening the file or refreshing a
+directory listing.)
 
 @cindex initiating drag-and-drop
   On capable window systems, Emacs also supports dragging contents

doc/lispref/functions.texi

@@ -22,7 +22,7 @@ define them.
 * Function Cells::              Accessing or setting the function definition
                             of a symbol.
 * Closures::                    Functions that enclose a lexical environment.
-* OClosures::                   Function objects with meta-data.
+* OClosures::                   Function objects
 * Advising Functions::          Adding to the definition of a function.
 * Obsolete Functions::          Declaring functions obsolete.
 * Inline Functions::            Functions that the compiler will expand inline.
@@ -593,8 +593,8 @@ symbol a function definition, its function cell is said to be
   In practice, nearly all functions have names, and are referred to by
 their names.  You can create a named Lisp function by defining a
 lambda expression and putting it in a function cell (@pxref{Function
-Cells}).  However, it is more common to use the @code{defun} macro,
-described in the next section.
+Cells}).  However, it is more common to use the @code{defun} special
+form, described in the next section.
 @ifnottex
 @xref{Defining Functions}.
 @end ifnottex
@@ -737,12 +737,9 @@ explicitly in the source file being loaded.  This is because
 By contrast, in programs that manipulate function definitions for other
 purposes, it is better to use @code{fset}, which does not keep such
 records.  @xref{Function Cells}.
-
-If the resulting function definition chain would be circular, then
-Emacs will signal a @code{cyclic-function-indirection} error.
 @end defun
 
-@defun function-alias-p object
+@defun function-alias-p object &optional noerror
 Checks whether @var{object} is a function alias.  If it is, it returns
 a list of symbols representing the function alias chain, else
 @code{nil}.  For instance, if @code{a} is an alias for @code{b}, and
@@ -753,8 +750,9 @@ a list of symbols representing the function alias chain, else
     @result{} (b c)
 @end example
 
-There is also a second, optional argument that is obsolete and has no
-effect.
+If there's a loop in the definitions, an error will be signaled.  If
+@var{noerror} is non-@code{nil}, the non-looping parts of the chain is
+returned instead.
 @end defun
 
   You cannot create a new primitive function with @code{defun} or
@@ -1541,9 +1539,6 @@ is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}):
 If you wish to use @code{fset} to make an alternate name for a
 function, consider using @code{defalias} instead.  @xref{Definition of
 defalias}.
-
-If the resulting function definition chain would be circular, then
-Emacs will signal a @code{cyclic-function-indirection} error.
 @end defun
 
 @node Closures
@@ -1586,69 +1581,56 @@ examining or altering the structure of closure objects.
 
 @node OClosures
 @section Open Closures
-@cindex oclosures
-@cindex open closures
 
-  Traditionally, functions are opaque objects which offer no other
-functionality but to call them.  (Emacs Lisp functions aren't fully
+Traditionally, functions are opaque objects which offer no other
+functionality but to call them.  Emacs Lisp functions aren't fully
 opaque since you can extract some info out of them such as their
 docstring, their arglist, or their interactive spec, but they are
-still mostly opaque.)  This is usually what we want, but occasionally
-we need functions to expose a bit more information about themselves.
+mostly opaque.  This is usually what we want, but occasionally we need
+functions to expose a bit more information about themselves.
 
-  @dfn{Open closures}, or @dfn{OClosures} for short, are function
-objects which carry additional type information and expose some
-information about themselves in the form of slots which you can access
+OClosures are functions which carry additional type information,
+and expose some information in the form of slots which you can access
 via accessor functions.
 
- OClosures are defined in two steps: first you use
-@code{oclosure-define} to define a new OClosure type by specifying the
-slots carried by the OClosures of this type, and then you use
-@code{oclosure-lambda} to create an OClosure object of a given type.
-
-Let's say we want to define keyboard macros, i.e.@: interactive
-functions which re-execute a sequence of key events (@pxref{Keyboard
-Macros}).  You could do it with a plain function as follows:
+They are defined in two steps: first @code{oclosure-define} is used to
+define new OClosure types by specifying the slots carried by those
+OClosures, and then @code{oclosure-lambda} is used to create an
+OClosure object of a given type.
 
+Say we want to define keyboard macros, i.e. interactive functions
+which re-execute a sequence of key events.  You could do it with
+a plain function as follows:
 @example
 (defun kbd-macro (key-sequence)
   (lambda (&optional arg)
     (interactive "P")
     (execute-kbd-macro key-sequence arg)))
 @end example
-
-@noindent
 But with such a definition there is no easy way to extract the
 @var{key-sequence} from that function, for example to print it.
 
 We can solve this problem using OClosures as follows.  First we define
 the type of our keyboard macros (to which we decided to add
 a @code{counter} slot while at it):
-
 @example
 (oclosure-define kbd-macro
   "Keyboard macro."
   keys (counter :mutable t))
 @end example
-
-@noindent
 After which we can rewrite our @code{kbd-macro} function:
-
 @example
 (defun kbd-macro (key-sequence)
   (oclosure-lambda (kbd-macro (keys key-sequence) (counter 0))
       (&optional arg)
-    (interactive "P")
+    (interactive "p")
     (execute-kbd-macro keys arg)
     (setq counter (1+ counter))))
 @end example
-
-@noindent
 As you can see, the @code{keys} and @code{counter} slots of the
 OClosure can be accessed as local variables from within the body
 of the OClosure.  But we can now also access them from outside of the
 body of the OClosure, for example to describe a keyboard macro:
-
 @example
 (defun describe-kbd-macro (km)
   (if (not (eq 'kbd-macro (oclosure-type km)))
@@ -1657,90 +1639,55 @@ body of the OClosure, for example to describe a keyboard macro:
           (counter (kbd-macro--counter km)))
       (message "Keys=%S, called %d times" keys counter))))
 @end example
-
-@noindent
 Where @code{kbd-macro--keys} and @code{kbd-macro--counter} are
-accessor functions generated by the @code{oclosure-define} macro for
-oclosures whose type is @code{kbd-macro}.
+accessor functions generated by the @code{oclosure-define} macro.
 
-@defmac oclosure-define oname &optional docstring &rest slots
+@defmac oclosure-define name &optional docstring &rest slots
 This macro defines a new OClosure type along with accessor functions
-for its @var{slots}.  @var{oname} can be a symbol (the name of the new
-type), or a list of the form
-@w{@code{(@var{oname} . @var{type-props})}}, in which case
-@var{type-props} is a list of additional properties of this oclosure
-type.  @var{slots} is a list of slot descriptions where each slot can
-be either a symbol (the name of the slot) or it can be of the form
-@w{@code{(@var{slot-name} . @var{slot-props})}}, where
-@var{slot-props} is a property list of the corresponding slot
-@var{slot-name}.
-The OClosure type's properties specified by @var{type-props} can
-include the following:
+for its slots.  @var{name} can be a symbol (the name of
+the new type), or a list of the form @code{(@var{name} . @var{type-props})} in
+which case @var{type-props} is a list of additional properties.
+@var{slots} is a list of slot descriptions where each slot can be
+either a symbol (the name of the slot) or it can be of the form
+@code{(@var{slot-name} . @var{slot-props})} where @var{slot-props} is
+a property list.
 
-@table @code
-@item (:predicate @var{pred-name})
-This requests creation of a predicate function named @var{pred-name}.
-This function will be used to recognize OClosures of the type
-@var{oname}.  If this type property is not specified,
-@code{oclosure-define} will generate a default name for the
-predicate.
-@item (:parent @var{otype})
-This makes type @var{otype} of OClosures be the parent of the type
-@var{oname}.  The OClosures of type @var{oname} inherit the
-@var{slots} defined by their parent type.
-@c FIXME: Is the above description of :parent correct?
-@item (:copier @var{copier-name} @var{copier-args})
-This causes the definition of a functional update function, knows as
-the @dfn{copier}, which takes an OClosure of type @var{oname} as its
-first argument and returns a copy of it with the slots named in
-@var{copier-args} modified to contain the value passed in the
-corresponding argument in the actual call to @var{copier-name}.
-@end table
+For each slot, the macro creates an accessor function named
+@code{@var{name}--@var{slot-name}}.  By default slots are immutable.
+If you need a slot to be mutable, you need to specify it with the
+@code{:mutable} slot property, after which it can be mutated for
+example with @code{setf}.
 
-For each slot in @var{slots}, the @code{oclosure-define} macro creates
-an accessor function named @code{@var{oname}--@var{slot-name}}; these
-can be used to access the values of the slots.  The slot definitions
-in @var{slots} can specify the following properties of the slots:
-
-@table @code
-@item :mutable @var{val}
-By default, slots are immutable, but if you specify the
-@code{:mutable} property with a non-@code{nil} value, the slot can be
-mutated, for example with @code{setf} (@pxref{Setting Generalized
-Variables}).
-@c FIXME: Some rationale and meaning of immutable slot is probably in
-@c order here.
-@item :type @var{val-type}
-This specifies the type of the values expected to appear in the slot.
-@c FIXME: What will happen if the value is of a different type? error?
-@end table
+Beside slot accessors, the macro can create a predicate and
+functional update functions according to @var{type-props}:
+a @code{(:predicate @var{pred-name})} in the @var{type-props} causes
+the definition of a predicate function under the name @var{pred-name},
+and @code{(:copier @var{copier-name} @var{copier-arglist})} causes the
+definition of a functional update function which takes an OClosure of
+type @var{name} as first argument and returns a copy of it with the
+slots named in @var{copier-arglist} modified to the value passed in the
+corresponding argument.
 @end defmac
 
 @defmac oclosure-lambda (type . slots) arglist &rest body
-This macro creates an anonymous OClosure of type @var{type}, which
-should have been defined with @code{oclosure-define}.  @var{slots}
-should be a list of elements of the form
-@w{@code{(@var{slot-name} @var{expr})}}.  At run time, each @var{expr}
-is evaluated, in order, after which the OClosure is created with its
-slots initialized with the resulting values.
+This macro creates an anonymous OClosure of type @var{type}.
+@var{slots} should be a list of elements of the form @code{(@var{slot-name}
+@var{exp})}.
+At run time, each @var{exp} is evaluated, in order, after which
+the OClosure is created with its slots initialized with the
+resulting values.
 
-When called as a function (@pxref{Calling Functions}), the OClosure
-created by this macro will accept arguments according to @var{arglist}
-and will execute the code in @var{body}.  @var{body} can refer to the
-value of any of its slot directly as if it were a local variable that
-had been captured by static scoping.
+When called as a function, the OClosure will accept arguments
+according to @var{arglist} and will execute the code in @var{body}.
+@var{body} can refer to the value of any of its slot directly as if it
+were a local variable that had been captured by static scoping.
 @end defmac
 
 @defun oclosure-type object
-This function returns the OClosure type (a symbol) of @var{object} if
-it is an OClosure, and @code{nil} otherwise.
+This function returns the OClosure type (a symbol) of @var{object} if it is an
+OClosure, and @code{nil} otherwise.
 @end defun
 
-One other function related to OClosures is
-@code{oclosure-interactive-form}, which allows some types of OClosures
-to compute their interactive forms dynamically.  @xref{Using
-Interactive, oclosure-interactive-form}.
-
 
 @node Advising Functions
 @section Advising Emacs Lisp Functions
@@ -2631,12 +2578,6 @@ so the byte compiler can ignore calls whose value is ignored.  This is
 the same as the @code{side-effect-free} property of the function's
 symbol, @pxref{Standard Properties}.
 
-@item (important-return-value @var{val})
-If @var{val} is non-@code{nil}, the byte compiler will warn about
-calls to this function that do not use the returned value.  This is the
-same as the @code{important-return-value} property of the function's
-symbol, @pxref{Standard Properties}.
-
 @item (speed @var{n})
 Specify the value of @code{native-comp-speed} in effect for native
 compilation of this function (@pxref{Native-Compilation Variables}).
@@ -2699,14 +2640,13 @@ byte compiler can check that the calls match the declaration.
 Tell the byte compiler to assume that @var{function} is defined in the
 file @var{file}.  The optional third argument @var{arglist} is either
 @code{t}, meaning the argument list is unspecified, or a list of
-formal parameters in the same style as @code{defun} (including the
-parentheses).  An omitted @var{arglist} defaults to @code{t}, not
-@code{nil}; this is atypical behavior for omitted arguments, and it
-means that to supply a fourth but not third argument one must specify
-@code{t} for the third-argument placeholder instead of the usual
-@code{nil}.  The optional fourth argument @var{fileonly}
-non-@code{nil} means check only that @var{file} exists, not that it
-actually defines @var{function}.
+formal parameters in the same style as @code{defun}.  An omitted
+@var{arglist} defaults to @code{t}, not @code{nil}; this is atypical
+behavior for omitted arguments, and it means that to supply a fourth
+but not third argument one must specify @code{t} for the third-argument
+placeholder instead of the usual @code{nil}.  The optional fourth
+argument @var{fileonly} non-@code{nil} means check only that
+@var{file} exists, not that it actually defines @var{function}.
 @end defmac
 
 @findex check-declare-file

doc/lispref/help.texi

@@ -989,29 +989,3 @@ in the function group to insert the function into.
 If @var{group} doesn't exist, it will be created.  If @var{section}
 doesn't exist, it will be added to the end of the function group.
 @end defun
-
-You can also query the examples of use of functions defined in
-shortdoc groups.
-
-@defun shortdoc-function-examples function
-This function returns all shortdoc examples for @var{function}.  The
-return value is an alist with items of the form
-@w{@code{(@var{group} . @var{examples})}}, where @var{group} is a
-documentation group where @var{function} appears, and @var{examples}
-is a string with the examples of @var{function}s use as defined in
-@var{group}.
-
-@code{shortdoc-function-examples} returns @code{nil} if @var{function}
-is not a function or if it doesn't have any shortdoc examples.
-@end defun
-
-@vindex help-fns-describe-function-functions
-@defun shortdoc-help-fns-examples-function function
-This function queries the registered shortdoc groups and inserts
-examples of use of a given Emacs Lisp @var{function} into the current
-buffer.  It is suitable for addition to the
-@code{help-fns-describe-function-functions} hook, in which case
-examples from shortdoc of using a function will be displayed in the
-@file{*Help*} buffer when the documentation of the function is
-requested.
-@end defun

doc/lispref/internals.texi

@@ -558,15 +558,12 @@ The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in
 value is 400,000 for the default 32-bit configuration and 800,000 for
 the 64-bit one.  If you specify a larger value, garbage collection
 will happen less often.  This reduces the amount of time spent garbage
-collecting (so Lisp programs will run faster between cycles of garbage
-collection that happen more rarely), but increases total memory use.
-You may want to do this when running a program that creates lots of
-Lisp data, especially if you need it to run faster.  However, we
+collecting, but increases total memory use.  You may want to do this
+when running a program that creates lots of Lisp data.  However, we
 recommend against increasing the threshold for prolonged periods of
 time, and advise that you never set it higher than needed for the
 program to run in reasonable time.  Using thresholds higher than
-necessary could potentially cause higher system-wide memory pressure,
-and also make each garbage-collection cycle take much more time, and
+necessary could potentially cause system-wide memory pressure, and
 should therefore be avoided.
 
 You can make collections more frequent by specifying a smaller value, down
@@ -735,15 +732,14 @@ Emacs session.
 @section C Dialect
 @cindex C programming language
 
-The C part of Emacs is portable to C99 or later: later C features such
-as @samp{<stdckdint.h>} and @samp{[[noreturn]]} are not used without a check,
+The C part of Emacs is portable to C99 or later: C11-specific features such
+as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check,
 typically at configuration time, and the Emacs build procedure
-provides a substitute implementation if necessary.  Some later features,
+provides a substitute implementation if necessary.  Some C11 features,
 such as anonymous structures and unions, are too difficult to emulate,
 so they are avoided entirely.
 
-At some point in the future the base C dialect will no doubt change to
-something later than C99.
+At some point in the future the base C dialect will no doubt change to C11.
 
 @node Writing Emacs Primitives
 @section Writing Emacs Primitives
@@ -898,17 +894,15 @@ Currently, only the following attributes are recognized:
 @table @code
 @item noreturn
 Declares the C function as one that never returns.  This corresponds
-to C23's @code{[[noreturn]]}, to C11's @code{_Noreturn}, and to GCC's
-@w{@code{__attribute__ ((__noreturn__))}} (@pxref{Function
-Attributes,,, gcc, Using the GNU Compiler Collection}).  (Internally,
-Emacs's own C code uses @code{_Noreturn} as it can be defined as a
-macro on C platforms that do not support it.)
+to the C11 keyword @code{_Noreturn} and to @w{@code{__attribute__
+((__noreturn__))}} attribute of GCC (@pxref{Function Attributes,,,
+gcc, Using the GNU Compiler Collection}).
 
 @item const
 Declares that the function does not examine any values except its
 arguments, and has no effects except the return value.  This
-corresponds to C23's @code{[[unsequenced]]} and to GCC's
-@w{@code{__attribute__ ((__const__))}}.
+corresponds to @w{@code{__attribute__ ((__const__))}} attribute of
+GCC.
 
 @item noinline
 This corresponds to @w{@code{__attribute__ ((__noinline__))}}
@@ -2556,7 +2550,7 @@ variable names have underscores replaced with dashes.  For instance,
 @code{mode_line_format} stores the value of @code{mode-line-format}.
 
 @item overlays
-The interval tree containing this buffer's overlays.
+The inveral tree containing this buffer's overlays.
 
 @item last_selected_window
 This is the last window that was selected with this buffer in it, or @code{nil}

doc/lispref/keymaps.texi

@@ -451,70 +451,9 @@ Here's an example:
 @lisp
 (defvar-keymap eww-textarea-map
   :parent text-mode-map
-  :doc "Keymap for the eww text area."
   "RET" #'forward-line
   "TAB" #'shr-next-link)
 @end lisp
-
-@kindex :repeat
-@kindex repeat-mode
-@cindex repeatable key bindings
-Each command in the keymap can be marked as `repeatable', i.e. usable
-in @code{repeat-mode}, by putting a @code{repeat-map} property on it,
-e.g.
-
-@lisp
-(put 'undo 'repeat-map 'undo-repeat-map)
-@end lisp
-
-where the value of the property is the map to be used by
-@code{repeat-mode}.
-
-To avoid repetitive invocations of @code{put}, @code{defvar-keymap}
-also has a @code{:repeat} keyword, which can be used to specify which
-commands in the keymap are usable by @code{repeat-mode}.  The
-following values are available:
-
-@table @code
-@item t
-This means all the commands in the keymap are repeatable, and is the
-most common usage.
-
-@item (:enter (commands ...) :exit (commands ...))
-This specifies that the commands in the @code{:enter} list enter
-@code{repeat-mode}, and the commands in the @code{:exit} list exit
-repeat mode.
-
-If the @code{:enter} list is empty, then all commands in the map enter
-@code{repeat-mode}.  Specifying one or more commands in this list is
-useful if there is a command which doesn't exist in the map being
-defined, but which should have the @code{repeat-map} property.
-
-If the @code{:exit} list is empty then no commands in the map exit
-@code{repeat-mode}.  Specifying one ore more commands in this list is
-useful if the keymap being defined contains a command that should not
-have the @code{repeat-map} property.
-@end table
-
-In order to make e.g.@: @kbd{u} repeat the @code{undo} command, the
-following two stanzas are equivalent:
-
-@lisp
-(defvar-keymap undo-repeat-map
-  "u" #'undo)
-(put 'undo 'repeat-map 'undo-repeat-map)
-@end lisp
-
-and
-
-@lisp
-(defvar-keymap undo-repeat-map
-  :repeat t
-  "u" #'undo)
-@end lisp
-
-The latter is preferred when there are many commands in the map, all
-of which should be repeatable.
 @end defmac
 
 @defun copy-keymap keymap
@@ -768,8 +707,8 @@ prefix definition, and then by those from the global map.
   In the following example, we make @kbd{C-p} a prefix key in the local
 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
-like @kbd{C-x C-f}.  By contrast, the key sequence @kbd{C-p 9} is not
-found in any active keymap.
+like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
+active keymap.
 
 @example
 @group
@@ -778,14 +717,15 @@ found in any active keymap.
 @end group
 @group
 (keymap-local-set "C-p" ctl-x-map)
-    @result{} (keymap #^[nil nil keymap @dots{}
+    @result{} nil
 @end group
 @group
-(keymap-lookup nil "C-p C-f")
+(keymap-binding "C-p C-f")
     @result{} find-file
 @end group
+
 @group
-(keymap-lookup nil "C-p 9")
+(keymap-binding "C-p 6")
     @result{} nil
 @end group
 @end example
@@ -882,7 +822,7 @@ Normally it ignores @code{overriding-local-map} and
 then it pays attention to them.  @var{position} can optionally be either
 an event position as returned by @code{event-start} or a buffer
 position, and may change the keymaps as described for
-@code{keymap-lookup} (@pxref{Functions for Key Lookup, keymap-lookup}).
+@code{keymap-binding}.
 @end defun
 
 @node Searching Keymaps
@@ -1307,11 +1247,7 @@ the second example.
 @end group
 @end example
 
-The @var{keymap} argument can be @code{nil}, meaning to look up
-@var{key} in the current keymaps (as returned by
-@code{current-active-maps}, @pxref{Active Keymaps}); or it can be a
-keymap or a list of keymaps, meaning to look up @var{key} only in the
-specified keymaps.
+The @var{keymap} argument can also be a list of keymaps.
 
 Unlike @code{read-key-sequence}, this function does not modify the
 specified events in ways that discard information (@pxref{Key Sequence
@@ -1442,8 +1378,7 @@ Binding Conventions}).
 or if @var{key} is not a valid key.
 
 @var{key} is a string representing a single key or a series of key
-strokes, and must satisfy @code{key-valid-p}.  Key strokes are
-separated by a single space character.
+strokes.  Key strokes are separated by a single space character.
 
 Each key stroke is either a single character, or the name of an
 event, surrounded by angle brackets.  In addition, any key stroke
@@ -1478,7 +1413,6 @@ The only keys that have a special shorthand syntax are @kbd{NUL},
 The modifiers have to be specified in alphabetical order:
 @samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}.
 
-@findex keymap-set
 @defun keymap-set keymap key binding
 This function sets the binding for @var{key} in @var{keymap}.  (If
 @var{key} is more than one event long, the change is actually made
@@ -1504,24 +1438,6 @@ bindings in a keymap makes no difference for keyboard input, but it
 does matter for menu keymaps (@pxref{Menu Keymaps}).
 @end defun
 
-@findex keymap-unset
-@defun keymap-unset keymap key &optional remove
-This function is the inverse of @code{keymap-set}, it unsets the
-binding for @var{key} in @var{keymap}, which is the same as setting
-the binding to @code{nil}.  In order to instead remove the binding
-completely, specify @var{remove} as non-@code{nil}.  This only makes a
-difference if @var{keymap} has a parent keymap: if you just unset a key
-in a child map, it will still shadow the same key in the parent
-keymap; using @var{remove} instead will allow the key in the parent keymap
-to be used.
-@end defun
-
-Note: using @code{keymap-unset} with @var{remove} non-@code{nil} is
-intended for users to put in their init file; Emacs packages should
-avoid using it if possible, since they have complete control over
-their own keymaps anyway, and they should not be altering other
-packages' keymaps.
-
   This example creates a sparse keymap and makes a number of
 bindings in it:
 
@@ -3163,13 +3079,13 @@ the menu.  To put it elsewhere in the menu, use @code{keymap-set-after}:
 @defun keymap-set-after map key binding &optional after
 Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after
-the binding for the event @var{after}.  The argument @var{key} should
-represent a single menu item or key, and @var{after} should be a
-single event type---a symbol or a character, not a sequence.  The new
-binding goes after the binding for @var{after}.  If @var{after} is
-@code{t} or is omitted, then the new binding goes last, at the end of
-the keymap.  However, new bindings are added before any inherited
-keymap.
+the binding for the event @var{after}.  The argument @var{key} should be
+of length one---a vector or string with just one element.  But
+@var{after} should be a single event type---a symbol or a character, not
+a sequence.  The new binding goes after the binding for @var{after}.  If
+@var{after} is @code{t} or is omitted, then the new binding goes last, at
+the end of the keymap.  However, new bindings are added before any
+inherited keymap.
 
 Here is an example:
 

doc/lispref/lists.texi

@@ -79,10 +79,7 @@ circular or dotted.  If a program doesn't look far enough down the
 list to see the @sc{cdr} of the final cons cell, it won't care.
 However, some functions that operate on lists demand proper lists and
 signal errors if given a dotted list.  Most functions that try to find
-the end of a list enter infinite loops if given a circular list.  You
-can use the function @code{proper-list-p}, described in the next
-section (@pxref{List-related Predicates, proper-list-p}), to determine
-whether a list is a proper one.
+the end of a list enter infinite loops if given a circular list.
 
 @cindex list structure
   Because most cons cells are used as part of lists, we refer to any
@@ -705,7 +702,7 @@ same way.
 Normally, when @var{tree} is anything other than a cons cell,
 @code{copy-tree} simply returns @var{tree}.  However, if @var{vecp} is
 non-@code{nil}, it copies vectors too (and operates recursively on
-their elements).  This function cannot cope with circular lists.
+their elements).
 @end defun
 
 @defun flatten-tree tree
@@ -1224,15 +1221,7 @@ x
 @end example
 
 However, the other arguments (all but the last) should be mutable
-lists.  They can be dotted lists, whose last @sc{cdr}s are then
-replaced with the next argument:
-
-@example
-@group
-(nconc (cons 1 2) (cons 3 (cons 4 5)) 'z)
-     @result{} (1 3 4 . z)
-@end group
-@end example
+lists.
 
 A common pitfall is to use a constant list as a non-last argument to
 @code{nconc}.  If you do this, the resulting behavior is undefined
@@ -1925,11 +1914,6 @@ properties.  Every symbol possesses a list of properties, used to
 record miscellaneous information about the symbol; these properties
 are stored in the form of a property list.  @xref{Symbol Properties}.
 
-@defun plistp object
-This predicate function returns non-@code{nil} if @var{object} is a
-valid property list.
-@end defun
-
 @menu
 * Plists and Alists::           Comparison of the advantages of property
                                   lists and association lists.

doc/lispref/loading.texi

@@ -75,20 +75,17 @@ file exists, and Emacs was compiled with native-compilation support
 (@pxref{Native Compilation}), @code{load} attempts to find a
 corresponding @samp{.eln} file, and if found, loads it instead of
 @file{@var{filename}.elc}.  Otherwise, it loads
-@file{@var{filename}.elc} (and starts a background native compilation
-to produce the missing @samp{.eln} file, followed by loading that
-file).  If there is no @file{@var{filename}.elc}, then @code{load}
-looks for a file named @file{@var{filename}.el}.  If that file exists,
-it is loaded.  If Emacs was compiled with support for dynamic modules
-(@pxref{Dynamic Modules}), @code{load} next looks for a file named
-@file{@var{filename}.@var{ext}}, where @var{ext} is a system-dependent
-file-name extension of shared libraries (@samp{.so} on GNU and Unix
-systems).  Finally, if neither of those names is found, @code{load}
-looks for a file named @var{filename} with nothing appended, and loads
-it if it exists.  (The @code{load} function is not clever about
-looking at @var{filename}.  In the perverse case of a file named
-@file{foo.el.el}, evaluation of @code{(load "foo.el")} will indeed
-find it.)
+@file{@var{filename}.elc}.  If there is no file by that name, then
+@code{load} looks for a file named @file{@var{filename}.el}.  If that
+file exists, it is loaded.  If Emacs was compiled with support for
+dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for
+a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a
+system-dependent file-name extension of shared libraries.  Finally, if
+neither of those names is found, @code{load} looks for a file named
+@var{filename} with nothing appended, and loads it if it exists.  (The
+@code{load} function is not clever about looking at @var{filename}.
+In the perverse case of a file named @file{foo.el.el}, evaluation of
+@code{(load "foo.el")} will indeed find it.)
 
 If Auto Compression mode is enabled, as it is by default, then if
 @code{load} can not find a file, it searches for a compressed version
@@ -1338,7 +1335,7 @@ specified @var{file} and perform the necessary initialization of the
 module.  This is the primitive which makes sure the module exports the
 @code{plugin_is_GPL_compatible} symbol, calls the module's
 @code{emacs_module_init} function, and signals an error if that
-function returns an error indication, or if the user typed @kbd{C-g}
+function returns an error indication, or if the use typed @kbd{C-g}
 during the initialization.  If the initialization succeeds,
 @code{module-load} returns @code{t}.  Note that @var{file} must
 already have the proper file-name extension, as this function doesn't

doc/lispref/minibuf.texi

@@ -312,7 +312,7 @@ to @code{regexp-history}.
 
 @cindex @code{case-fold}, text property
 @findex read-regexp-case-fold-search
-The user can use the @kbd{M-s c} command to indicate whether case
+The user can use the @kbd{M-c} command to indicate whether case
 folding should be on or off.  If the user has used this command, the
 returned string will have the text property @code{case-fold} set to
 either @code{fold} or @code{inhibit-fold}.  It is up to the caller of
@@ -2233,12 +2233,10 @@ minibuffer.  It returns @code{t} if the user enters @samp{yes},
 @code{nil} if the user types @samp{no}.  The user must type @key{RET} to
 finalize the response.  Upper and lower case are equivalent.
 
-@vindex yes-or-no-prompt
-@code{yes-or-no-p} starts by displaying @var{prompt} in the
-minibuffer, followed by the value of @code{yes-or-no-prompt} @w{(default
-@samp{(yes or no) })}.  The user must type one of the expected
-responses; otherwise, the function responds @w{@samp{Please answer yes or
-no.}}, waits about two seconds and repeats the request.
+@code{yes-or-no-p} starts by displaying @var{prompt} in the minibuffer,
+followed by @w{@samp{(yes or no) }}.  The user must type one of the
+expected responses; otherwise, the function responds @samp{Please answer
+yes or no.}, waits about two seconds and repeats the request.
 
 @code{yes-or-no-p} requires more work from the user than
 @code{y-or-n-p} and is appropriate for more crucial decisions.

doc/lispref/modes.texi

@@ -1775,8 +1775,6 @@ it's used to say which major modes this minor mode is useful in.
 
 Any other keyword arguments are passed directly to the
 @code{defcustom} generated for the variable @var{mode}.
-@xref{Variable Definitions}, for the description of those keywords and
-their values.
 
 The command named @var{mode} first performs the standard actions such as
 setting the variable named @var{mode} and then executes the @var{body}
@@ -1862,10 +1860,9 @@ by visiting files, and buffers that use a major mode other than
 Fundamental mode; but it does not detect the creation of a new buffer
 in Fundamental mode.
 
-This macro defines the customization option @var{global-mode}
-(@pxref{Customization}), which can be toggled via the Customize
-interface to turn the minor mode on and off.  As with
-@code{define-minor-mode}, you should ensure that the
+This defines the customization option @var{global-mode} (@pxref{Customization}),
+which can be toggled in the Customize interface to turn the minor mode on
+and off.  As with @code{define-minor-mode}, you should ensure that the
 @code{define-globalized-minor-mode} form is evaluated each time Emacs
 starts, for example by providing a @code{:require} keyword.
 
@@ -1878,27 +1875,24 @@ Use @code{:variable @var{variable}} if that's not the case--some minor
 modes use a different variable to store this state information.
 
 Generally speaking, when you define a globalized minor mode, you should
-also define a non-globalized version, so that people could use it (or
-disable it) in individual buffers.  This also allows them to disable a
+also define a non-globalized version, so that people can use (or
+disable) it in individual buffers.  This also allows them to disable a
 globally enabled minor mode in a specific major mode, by using that
 mode's hook.
 
-If the macro is given a @code{:predicate} keyword, it will create a
-user option called the same as the global mode variable, but with
-@code{-modes} instead of @code{-mode} at the end, i.e.@:
-@code{@var{global-mode}s}.  This variable will be used in a predicate
-function that determines whether the minor mode should be activated in
-a particular major mode.  Valid values of @code{:predicate} include
-@code{t} (use in all major modes), @code{nil} (don't use in any major
-modes), or a list of mode names, optionally preceded with @code{not}
-(as in @w{@code{(not @var{mode-name} @dots{})}}).  These elements can
-be mixed, as shown in the following examples.
+If given a @code{:predicate} keyword, a user option called the same as
+the global mode variable, but with @code{-modes} instead of
+@code{-mode} at the end will be created.  The variable is used as a
+predicate that specifies which major modes the minor mode should be
+activated in.  Valid values include @code{t} (use in all major modes,
+@code{nil} (use in no major modes), or a list of mode names (or
+@code{(not mode-name ...)}) elements (as well as @code{t} and
+@code{nil}).
 
 @example
 (c-mode (not mail-mode message-mode) text-mode)
 @end example
 
-@noindent
 This means ``use in modes derived from @code{c-mode}, and not in
 modes derived from @code{message-mode} or @code{mail-mode}, but do use
 in modes derived from @code{text-mode}, and otherwise no other
@@ -1908,15 +1902,13 @@ modes''.
 ((not c-mode) t)
 @end example
 
-@noindent
-This means ``don't use in modes derived from @code{c-mode}, but do use
+This means ``don't use modes derived from @code{c-mode}, but use
 everywhere else''.
 
 @example
 (text-mode)
 @end example
 
-@noindent
 This means ``use in modes derived from @code{text-mode}, but nowhere
 else''.  (There's an implicit @code{nil} element at the end.)
 @end defmac
@@ -2357,19 +2349,18 @@ enabled separately in each buffer.
 
 @defvar global-mode-string
 This variable holds a mode line construct that, by default, appears in
-the mode line as part of @code{mode-line-misc-info}, just after the
-@code{which-function-mode} information if that minor mode is enabled,
-else after @code{mode-line-modes}.  Elements that are added to this
-construct should normally end in a space (to ensure that consecutive
-@code{global-mode-string} elements display properly).  For instance,
-the command @code{display-time} sets @code{global-mode-string} to
-refer to the variable @code{display-time-string}, which holds a string
-containing the time and load information.
+the mode line just after the @code{which-function-mode} minor mode if
+set, else after @code{mode-line-modes}.  Elements that are added to
+this construct should normally end in a space (to ensure that
+consecutive @code{global-mode-string} elements display properly).  For
+instance, the command @code{display-time} sets
+@code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time
+and load information.
 
 The @samp{%M} construct substitutes the value of
-@code{global-mode-string}.  This construct is not used by the default
-mode line, as the variable itself is used in
-@code{mode-line-misc-info}.
+@code{global-mode-string}, but that is obsolete, since the variable is
+included in the mode line from @code{mode-line-format}.
 @end defvar
 
 Here is a simplified version of the default value of
@@ -2398,7 +2389,6 @@ specifies addition of text properties.
 
 @node %-Constructs
 @subsection @code{%}-Constructs in the Mode Line
-@cindex @code{%}-constructs in the mode line
 
   Strings used as mode line constructs can use certain
 @code{%}-constructs to substitute various kinds of data.  The
@@ -2450,10 +2440,6 @@ abbreviate.
 The current line number of point, counting within the accessible portion
 of the buffer.
 
-@item %M
-The value of @code{global-mode-string} (which is part of
-@code{mode-line-misc-info} by default).
-
 @item %n
 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
 @code{narrow-to-region} in @ref{Narrowing}).
@@ -2489,9 +2475,6 @@ The mnemonics of keyboard, terminal, and buffer coding systems.
 @item %Z
 Like @samp{%z}, but including the end-of-line format.
 
-@item %&
-@samp{*} if the buffer is modified, and @samp{-} otherwise.
-
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@@ -2503,6 +2486,9 @@ Like @samp{%z}, but including the end-of-line format.
 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
 read-only buffer.  @xref{Buffer Modification}.
 
+@item %&
+@samp{*} if the buffer is modified, and @samp{-} otherwise.
+
 @item %@@
 @samp{@@} if the buffer's @code{default-directory} (@pxref{File Name
 Expansion}) is on a remote machine, and @samp{-} otherwise.
@@ -2524,16 +2510,13 @@ The character @samp{%}---this is how to include a literal @samp{%} in a
 string in which @code{%}-constructs are allowed.
 @end table
 
-@subsubheading Obsolete @code{%}-Constructs
-
-  The following constructs should no longer be used.
+The following @code{%}-construct is still supported, but it is
+obsolete, since you can get the same result using the variable
+@code{mode-name}.
 
 @table @code
 @item %m
-Obsolete; use the @code{mode-name} variable instead.  The @code{%m}
-construct is inadequate, as it produces an empty string if the value
-of @code{mode-name} is a non-string mode-line construct (as in
-@code{emacs-lisp-mode}, for example).
+The value of @code{mode-name}.
 @end table
 
 @node Properties in Mode
@@ -2595,70 +2578,21 @@ header line, for windows displaying the buffer.  The format of the value
 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
 It is normally @code{nil}, so that ordinary buffers have no header
 line.
-@end defvar
 
-If @code{display-line-numbers-mode} is turned on in a buffer
-(@pxref{Display Custom, display-line-numbers-mode,, emacs, The GNU
-Emacs Manual}), the buffer text is indented on display by the amount
-of screen space needed to show the line numbers.  By contrast, text of
-the header line is not automatically indented, because a header line
-never displays a line number, and because the text of the header line
-is not necessarily directly related to buffer text below it.  If a
-Lisp program needs the header-line text to be aligned with buffer text
-(for example, if the buffer displays columnar data, like
-@code{tabulated-list-mode} does, @pxref{Tabulated List Mode}), it
-should turn on the minor mode @code{header-line-indent-mode}.
-
-@deffn Command header-line-indent-mode
-This buffer-local minor mode tracks the changes of the width of the
-line-number display on screen (which may vary depending on the range
-of line numbers shown in the window), and allows Lisp programs to
-arrange that header-line text is always aligned with buffer text when
-the line-number width changes.  Such Lisp programs should turn on this
-mode in the buffer, and use the variables @code{header-line-indent}
-and @code{header-line-indent-width} in the @code{header-line-format}
-to ensure it is adjusted to the text indentation at all times.
-@end deffn
-
-@defvar header-line-indent
-This variable's value is a whitespace string whose width is kept equal
-to the current width of line-numbers on display, provided that
-@code{header-line-indent-mode} is turned on in the buffer shown in the
-window.  The number of spaces is calculated under the assumption that
-the face of the header-line text uses the same font, including size,
-as the frame's default font; if that assumption is false, use
-@code{header-line-indent-width}, described below, instead.  This
-variable is intended to be used in simple situations where the
-header-line text needs to be indented as a whole to be realigned with
-buffer text, by prepending this variable's value to the actual
-header-line text.  For example, the following definition of
-@code{header-line-format}:
+@findex header-line-indent-mode
+If @code{display-line-numbers-mode} is used, and you want the header
+line to be indented by the same amount as the buffer contents, you can
+use the @code{header-line-indent-mode} minor mode.  This minor mode
+keeps the @code{header-line-indent} variable updated, so that you can
+say something like:
 
 @lisp
 (setq header-line-format
-      `("" header-line-indent ,my-header-line))
+      `("" header-line-format ,my-header-line))
 @end lisp
 
-@noindent
-where @code{my-header-line} is the format string that produces the
-actual text of the header line, will make sure the header-line text
-is always indented like the buffer text below it.
-@end defvar
-
-@defvar header-line-indent-width
-This variable's value is kept updated to provide the current width, in
-units of the frame's canonical character width, used for displaying
-the line numbers, provided that @code{header-line-indent-mode} is
-turned on in the buffer shown in the window.  It can be used for
-aligning the header-line text with the buffer text when
-@code{header-line-indent} is not flexible enough.  For example, if the
-header line uses a font whose metrics is different from the default
-face's font, your Lisp program can calculate the width of line-number
-display in pixels, by multiplying the value of this variable by the
-value returned by @code{frame-char-width} (@pxref{Frame Font}), and
-then use the result to align header-line text using the
-@code{:align-to} display property spec (@pxref{Specified Space}) in
-pixels on the relevant parts of @code{header-line-frormat}.
+This can be useful if you're displaying columnar data, and the header
+line should align with that data in the buffer.
 @end defvar
 
 @defun window-header-line-height &optional window
@@ -3696,20 +3630,10 @@ in C.
 @vindex font-lock-function-name-face
 for the name of a function being defined or declared.
 
-@item font-lock-function-call-face
-@vindex font-lock-function-call-face
-for the name of a function being called.  This face inherits, by
-default, from @code{font-lock-function-name-face}.
-
 @item font-lock-variable-name-face
 @vindex font-lock-variable-name-face
 for the name of a variable being defined or declared.
 
-@item font-lock-variable-use-face
-@vindex font-lock-variable-use-face
-for the name of a variable being referenced.  This face inherits, by
-default, from @code{font-lock-variable-name-face}.
-
 @item font-lock-keyword-face
 @vindex font-lock-keyword-face
 for a keyword with special syntactic significance, like @samp{for} and
@@ -3783,16 +3707,11 @@ for numbers.
 @vindex font-lock-operator-face
 for operators.
 
-@item font-lock-property-name-face
-@vindex font-lock-property-name-face
-for properties of an object, such as the declaration of fields in a
-struct.  This face inherits, by default, from
-@code{font-lock-variable-name-face}.
-
-@item font-lock-property-use-face
-@vindex font-lock-property-use-face
-for properties of an object, such as use of fields in a struct.  This
-face inherits, by default, from @code{font-lock-property-name-face}.
+@item font-lock-property-face
+@vindex font-lock-property-face
+for properties of an object, such as the declaration and use of fields
+in a struct.
+This face inherits, by default, from @code{font-lock-variable-name-face}.
 
 For example,
 
@@ -4155,7 +4074,7 @@ Other keywords are optional:
 @end multitable
 
 Lisp programs mark patterns in @var{query} with capture names (names
-that start with @code{@@}), and tree-sitter will return matched nodes
+that starts with @code{@@}), and tree-sitter will return matched nodes
 tagged with those same capture names.  For the purpose of
 fontification, capture names in @var{query} should be face names like
 @code{font-lock-keyword-face}.  The captured node will be fontified
@@ -5007,7 +4926,8 @@ the current line to @var{matcher}; if it returns non-@code{nil}, this
 rule is applicable.  Then Emacs passes the node to @var{anchor}, which
 returns a buffer position.  Emacs takes the column number of that
 position, adds @var{offset} to it, and the result is the indentation
-column for the current line.
+column for the current line.  @var{offset} can be an integer or a
+variable whose value is an integer.
 
 The @var{matcher} and @var{anchor} are functions, and Emacs provides
 convenient defaults for them.
@@ -5023,13 +4943,10 @@ inside a multi-line string, no node can start at that position, so
 @var{node} is @code{nil}.  In that case, @var{parent} would be the
 smallest node that spans that position.
 
-@var{matcher} should return non-@code{nil} if the rule is applicable,
-and @var{anchor} should return a buffer position.
-
-@var{offset} can be an integer, a variable whose value is an integer,
-or a function that returns an integer.  If it is a function, it is
-passed @var{node}, @var{parent}, and @var{bol}, like matchers and
-anchors.
+Emacs finds @var{bol}, @var{node} and @var{parent} and
+passes them to each @var{matcher} and @var{anchor}.  @var{matcher}
+should return non-@code{nil} if the rule is applicable, and
+@var{anchor} should return a buffer position.
 @end defvar
 
 @defvar treesit-simple-indent-presets
@@ -5081,9 +4998,6 @@ first child where parent is @code{argument_list}, use
 (match nil "argument_list" nil nil 0 0)
 @end example
 
-In addition, @var{node-type} can be a special value @code{null},
-which matches when the value of @var{node} is @code{nil}.
-
 @item n-p-gp
 Short for ``node-parent-grandparent'', this matcher is a function of 3
 arguments: @var{node-type}, @var{parent-type}, and
@@ -5113,15 +5027,7 @@ This anchor is a function that is called with 3 arguments: @var{node},
 @item parent-bol
 This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the first non-space character
-on the line which @var{parent}'s start is on.
-
-@item parent-bol
-This anchor is a function that is called with 3 arguments: @var{node},
-@var{parent}, and @var{bol}.  It finds the first ancestor node
-(parent, grandparent, etc) of @var{node} that starts on its own line,
-and return the start of that node.  ``Starting on its own line'' means
-there is only whitespace character before the node on the line which
-the node's start is on.
+on the line of @var{parent}.
 
 @item prev-sibling
 This anchor is a function that is called with 3 arguments: @var{node},
@@ -5137,10 +5043,10 @@ This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the first non-whitespace
 character on the previous line.
 
-@item column-0
+@item point-min
 This anchor is a function that is called with 3 arguments: @var{node},
-@var{parent}, and @var{bol}, and returns the beginning of the current
-line, which is at column 0.
+@var{parent}, and @var{bol}, and returns the beginning of the buffer.
+This is useful as the beginning of the buffer is always at column 0.
 
 @item comment-start
 This anchor is a function that is called with 3 arguments: @var{node},
@@ -5154,11 +5060,8 @@ This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}.  It tries to go to the beginning of the
 previous non-empty line, and matches @code{adaptive-fill-regexp}.  If
 there is a match, this function returns the end of the match,
-otherwise it returns nil.  However, if the current line begins with a
-prefix (e.g., ``-''), return the beginning of the prefix of the
-previous line instead, so that the two prefixes aligns.  This anchor
-is useful for a @code{indent-relative}-like indent behavior for block
-comments.
+otherwise it returns nil.  This anchor is useful for a
+@code{indent-relative}-like indent behavior for block comments.
 
 @end ftable
 @end defvar

doc/lispref/numbers.texi

@@ -219,25 +219,17 @@ creates huge integers.
 
 @cindex @acronym{IEEE} floating point
   Floating-point numbers are useful for representing numbers that are
-not integral.  The range of floating-point numbers is the same as the
-range of the C data type @code{double} on the machine you are using.
-On almost all computers supported by Emacs, this is @acronym{IEEE}
-binary64 floating point format, which is standardized by
-@url{https://standards.ieee.org/standard/754-2019.html,,IEEE Std
-754-2019} and is discussed further in David Goldberg's paper
+not integral.  The range of floating-point numbers is
+the same as the range of the C data type @code{double} on the machine
+you are using.  On all computers supported by Emacs, this is
+@acronym{IEEE} binary64 floating point format, which is standardized by
+@url{https://standards.ieee.org/standard/754-2019.html,,IEEE Std 754-2019}
+and is discussed further in David Goldberg's paper
 ``@url{https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html,
-What Every Computer Scientist Should Know About Floating-Point
-Arithmetic}''.  On modern platforms, floating-point operations follow
-the IEEE-754 standard closely; however, results are not always rounded
-correctly on some systems, notably 32-bit x86.
-
-  On some old computer systems, Emacs may not use IEEE floating-point.
-We know of one such system on which Emacs runs correctly, but does not
-follow IEEE-754: the VAX running NetBSD using GCC 10.4.0, where the
-VAX @samp{D_Floating} format is used instead.  IBM System/370-derived
-mainframes and their XL/C compiler are also capable of utilizing a
-hexadecimal floating point format, but Emacs has not yet been built in
-such a configuration.
+What Every Computer Scientist Should Know About Floating-Point Arithmetic}''.
+On modern platforms, floating-point operations follow the IEEE-754
+standard closely; however, results are not always rounded correctly on
+some obsolescent platforms, notably 32-bit x86.
 
   The read syntax for floating-point numbers requires either a decimal
 point, an exponent, or both.  Optional signs (@samp{+} or @samp{-})
@@ -270,10 +262,6 @@ two NaNs as equal when their
 signs and significands agree.  Significands of NaNs are
 machine-dependent, as are the digits in their string representation.
 
-  NaNs are not available on systems which do not use IEEE
-floating-point arithmetic; if the read syntax for a NaN is used on a
-VAX, for example, the reader signals an error.
-
   When NaNs and signed zeros are involved, non-numeric functions like
 @code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and
 @code{gethash} determine whether values are indistinguishable, not
@@ -754,10 +742,9 @@ by rounding the quotient towards zero after each division.
 
 @cindex @code{arith-error} in division
 If you divide an integer by the integer 0, Emacs signals an
-@code{arith-error} error (@pxref{Errors}).  On systems using IEEE-754
-floating-point, floating-point division of a nonzero number by zero
-yields either positive or negative infinity (@pxref{Float Basics});
-otherwise, an @code{arith-error} is signaled as usual.
+@code{arith-error} error (@pxref{Errors}).  Floating-point division of
+a nonzero number by zero yields either positive or negative infinity
+(@pxref{Float Basics}).
 @end defun
 
 @defun % dividend divisor

doc/lispref/objects.texi

@@ -466,20 +466,19 @@ You can specify characters by their Unicode values.
 @code{?\u@var{xxxx}} and @code{?\U@var{xxxxxxxx}} represent code
 points @var{xxxx} and @var{xxxxxxxx}, respectively, where each @var{x}
 is a single hexadecimal digit.  For example, @code{?\N@{U+E0@}},
-@code{?\u00e0} and @code{?\U000000E0} are all equivalent to
-@code{?@`a} and to @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}}.  The
-Unicode Standard defines code points only up to @samp{U+@var{10ffff}},
-so if you specify a code point higher than that, Emacs signals an
-error.
+@code{?\u00e0} and @code{?\U000000E0} are all equivalent to @code{?à}
+and to @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}}.  The Unicode
+Standard defines code points only up to @samp{U+@var{10ffff}}, so if
+you specify a code point higher than that, Emacs signals an error.
 
 @item
 You can specify characters by their hexadecimal character
 codes.  A hexadecimal escape sequence consists of a backslash,
 @samp{x}, and the hexadecimal character code.  Thus, @samp{?\x41} is
 the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and
-@code{?\xe0} is the character @kbd{@`a} (@kbd{a} with grave accent).
-You can use one or more hex digits after @samp{x}, so you can
-represent any character code in this way.
+@code{?\xe0} is the character @kbd{à} (@kbd{a} with grave accent).
+You can use any number of hex digits, so you can represent any
+character code in this way.
 
 @item
 @cindex octal character code
@@ -1008,6 +1007,13 @@ It looks like this:
 @end example
 @end ifnottex
 
+  As a somewhat peculiar side effect of @code{(a b . c)} and
+@code{(a . (b . c))} being equivalent, for consistency this means
+that if you replace @code{b} here with the empty sequence, then it
+follows that @code{(a . c)} and @code{(a . ( . c))} are equivalent,
+too.  This also means that @code{( .  c)} is equivalent to @code{c},
+but this is seldom used.
+
 @node Association List Type
 @subsubsection Association List Type
 

doc/lispref/os.texi

@@ -182,9 +182,7 @@ is over, and, together with @code{before-init-time}, provides the
 measurement of how long it took.
 
 @item
-It runs the normal hooks @code{after-init-hook} and
-@code{delayed-warnings-hook}.  The latter shows any warnings emitted
-during previous stages of startup, which are automatically delayed.
+It runs the normal hook @code{after-init-hook}.
 
 @item
 If the buffer @file{*scratch*} exists and is still in Fundamental mode
@@ -1279,33 +1277,13 @@ This function returns the real @acronym{UID} of the user.
 This function returns the effective @acronym{UID} of the user.
 @end defun
 
-@defun file-user-uid
-This function returns the connection-local value for the user's
-effective @acronym{UID}.  If @code{default-directory} is local, this
-is equivalent to @code{user-uid}, but for remote files (@pxref{Remote
-Files, , , emacs, The GNU Emacs Manual}), it will return the
-@acronym{UID} for the user associated with that remote connection; if
-the remote connection has no associated user, it will instead return
--1.
-@end defun
-
 @cindex GID
-@defun group-real-gid
-This function returns the real @acronym{GID} of the Emacs process.
-@end defun
-
 @defun group-gid
 This function returns the effective @acronym{GID} of the Emacs process.
 @end defun
 
-@defun file-group-gid
-This function returns the connection-local value for the user's
-effective @acronym{GID}.  Similar to @code{file-user-uid}, if
-@code{default-directory} is local, this is equivalent to
-@code{group-gid}, but for remote files (@pxref{Remote Files, , ,
-emacs, The GNU Emacs Manual}), it will return the @acronym{GID} for
-the user associated with that remote connection; if the remote
-connection has no associated user, it will instead return -1.
+@defun group-real-gid
+This function returns the real @acronym{GID} of the Emacs process.
 @end defun
 
 @defun system-users

doc/lispref/parsing.texi

@@ -734,7 +734,7 @@ is non-@code{nil}, it looks for smallest named child.
 
 @heading Searching for node
 
-@defun treesit-search-subtree node predicate &optional backward all depth
+@defun treesit-search-subtree node predicate &optional backward all limit
 This function traverses the subtree of @var{node} (including
 @var{node} itself), looking for a node for which @var{predicate}
 returns non-@code{nil}.  @var{predicate} is a regexp that is matched
@@ -745,9 +745,9 @@ the first node that matches, or @code{nil} if none does.
 By default, this function only traverses named nodes, but if @var{all}
 is non-@code{nil}, it traverses all the nodes.  If @var{backward} is
 non-@code{nil}, it traverses backwards (i.e., it visits the last child
-first when traversing down the tree).  If @var{depth} is
+first when traversing down the tree).  If @var{limit} is
 non-@code{nil}, it must be a number that limits the tree traversal to
-that many levels down the tree.  If @var{depth} is @code{nil}, it
+that many levels down the tree.  If @var{limit} is @code{nil}, it
 defaults to 1000.
 @end defun
 
@@ -805,7 +805,7 @@ Arguments @var{predicate}, @var{backward} and @var{all} are the same
 as in @code{treesit-search-forward}.
 @end defun
 
-@defun treesit-induce-sparse-tree root predicate &optional process-fn depth
+@defun treesit-induce-sparse-tree root predicate &optional process-fn limit
 This function creates a sparse tree from @var{root}'s subtree.
 
 It takes the subtree under @var{root}, and combs it so only the nodes
@@ -836,8 +836,8 @@ b   1   2         b   |   |      b   c   d
 
 If @var{process-fn} is non-@code{nil}, instead of returning the
 matched nodes, this function passes each node to @var{process-fn} and
-uses the returned value instead.  If non-@code{nil}, @var{depth} is
-the number of levels to go down from @var{root}.  If @var{depth} is
+uses the returned value instead.  If non-@code{nil}, @var{limit} is
+the number of levels to go down from @var{root}.  If @var{limit} is
 @code{nil}, it defaults to 1000.
 
 Each node in the returned tree looks like
@@ -849,53 +849,6 @@ Each node in the returned tree looks like
 
 @heading More convenience functions
 
-@defun treesit-node-get node instructions
-This is a convenience function that chains together multiple node
-accessor functions together.  For example, to get @var{node}'s
-parent's next sibling's second child's text:
-
-@example
-@group
-(treesit-node-get node
-   '((parent 1)
-    (sibling 1 nil)
-    (child 1 nil)
-    (text nil)))
-@end group
-@end example
-
-@var{instruction} is a list of INSTRUCTIONs of the form
-@w{@code{(@var{fn} @var{arg}...)}}.  The following @var{fn}'s are
-supported:
-
-@table @code
-@item (child @var{idx} @var{named})
-Get the @var{idx}'th child.
-
-@item (parent @var{n})
-Go to parent @var{n} times.
-
-@item (field-name)
-Get the field name of the current node.
-
-@item (type)
-Get the type of the current node.
-
-@item (text @var{no-property})
-Get the text of the current node.
-
-@item (children @var{named})
-Get a list of children.
-
-@item (sibling @var{step} @var{named})
-Get the nth prev/next sibling, negative @var{step} means prev sibling,
-positive means next sibling.
-@end table
-
-Note that arguments like @var{named} and @var{no-property} can't be
-omitted, unlike in their original functions.
-@end defun
-
 @defun treesit-filter-child node predicate &optional named
 This function finds immediate children of @var{node} that satisfy
 @var{predicate}.
@@ -906,24 +859,18 @@ return non-@code{nil} to indicate that the node should be kept.  If
 nodes.
 @end defun
 
-@defun treesit-parent-until node predicate &optional include-node
+@defun treesit-parent-until node predicate
 This function repeatedly finds the parents of @var{node}, and returns
-the parent that satisfies @var{pred}, a function that takes a node as
-the argument and returns a boolean that indicates a match.  If no
-parent satisfies @var{pred}, this function returns @code{nil}.
-
-Normally this function only looks at the parents of @var{node} but not
-@var{node} itself. But if @var{include-node} is non-@var{nil}, this
-function returns @var{node} if @var{node} satisfies @var{pred}.
+the parent that satisfies @var{predicate}, a function that takes a
+node as the argument.  If no parent satisfies @var{predicate}, this
+function returns @code{nil}.
 @end defun
 
-@defun treesit-parent-while node pred
-This function goes up the tree starting from @var{node}, and keeps
-doing so as long as the nodes satisfy @var{pred}, a function that
+@defun treesit-parent-while node predicate
+This function repeatedly finds the parent of @var{node}, and keeps
+doing so as long as the nodes satisfy @var{predicate}, a function that
 takes a node as the argument.  That is, this function returns the
-highest parent of @var{node} that still satisfies @var{pred}.  Note
-that if @var{node} satisfies @var{pred} but its immediate parent
-doesn't, @var{node} itself is returned.
+farthest parent that still satisfies @var{predicate}.
 @end defun
 
 @defun treesit-node-top-level node &optional type
@@ -982,13 +929,9 @@ Here are some predicates on tree-sitter nodes:
 Checks if @var{object} is a tree-sitter syntax node.
 @end defun
 
-@cindex compare tree-sitter syntax nodes
-@cindex tree-sitter nodes, comparing
 @defun treesit-node-eq node1 node2
-Checks if @var{node1} and @var{node2} refer to the same node in a
-tree-sitter syntax tree.  This function uses the same equivalence
-metric as @code{equal}.  You can also compare nodes using @code{equal}
-(@pxref{Equality Predicates}).
+Checks if @var{node1} and @var{node2} are the same node in a syntax
+tree.
 @end defun
 
 @heading Property information
@@ -1023,15 +966,10 @@ A node ``has error'' if the text it spans contains a syntax error.  It
 can be that the node itself has an error, or one of its descendants
 has an error.
 
-@cindex tree-sitter, live parsing node
-@cindex live node, tree-sitter
-A node is considered @dfn{live} if its parser is not deleted, and the
-buffer to which it belongs to is a live buffer (@pxref{Killing Buffers}).
-
 @defun treesit-node-check node property
-This function returns non-@code{nil} if @var{node} has the specified
-@var{property}.  @var{property} can be @code{named}, @code{missing},
-@code{extra}, @code{outdated}, @code{has-error}, or @code{live}.
+This function checks if @var{node} has the specified @var{property}.
+@var{property} can be @code{named}, @code{missing}, @code{extra},
+@code{outdated}, or @code{has-error}.
 @end defun
 
 @defun treesit-node-type node
@@ -1358,8 +1296,7 @@ matches regular expression @var{regexp}.  Matching is case-sensitive.
 
 @deffn Predicate pred fn &rest nodes
 Matches if function @var{fn} returns non-@code{nil} when passed each
-node in @var{nodes} as arguments.  The function runs with the current
-buffer set to the buffer of node being queried.
+node in @var{nodes} as arguments.
 @end deffn
 
 Note that a predicate can only refer to capture names that appear in
@@ -1643,9 +1580,9 @@ ranges for @acronym{CSS} and JavaScript parsers:
 @example
 @group
 ;; Create parsers.
-(setq html (treesit-parser-create 'html))
-(setq css (treesit-parser-create 'css))
-(setq js (treesit-parser-create 'javascript))
+(setq html (treesit-get-parser-create 'html))
+(setq css (treesit-get-parser-create 'css))
+(setq js (treesit-get-parser-create 'javascript))
 @end group
 
 @group
@@ -1751,48 +1688,26 @@ integration for a major mode.
 A major mode supporting tree-sitter features should roughly follow
 this pattern:
 
+@c FIXME: Update this part once we settle on the exact format.
 @example
 @group
 (define-derived-mode woomy-mode prog-mode "Woomy"
   "A mode for Woomy programming language."
-  (when (treesit-ready-p 'woomy)
+  ;; Shared setup.
+  ...
+  (cond
+   ;; Tree-sitter setup.
+   ((treesit-ready-p 'woomy)
     (setq-local treesit-variables ...)
-    ...
-    (treesit-major-mode-setup)))
+    (treesit-major-mode-setup))
+   ;; Non-tree-sitter setup.
+   (t
+    ...)))
 @end group
 @end example
 
-@code{treesit-ready-p} automatically emits a warning if conditions for
-enabling tree-sitter aren't met.
-
-If a tree-sitter major mode shares setup with their ``native''
-counterpart, they can create a ``base mode'' that contains the common
-setup, like this:
-
-@example
-@group
-(define-derived-mode woomy--base-mode prog-mode "Woomy"
-  "An internal mode for Woomy programming language."
-  (common-setup)
-  ...)
-@end group
-
-@group
-(define-derived-mode woomy-mode woomy--base-mode "Woomy"
-  "A mode for Woomy programming language."
-  (native-setup)
-  ...)
-@end group
-
-@group
-(define-derived-mode woomy-ts-mode woomy--base-mode "Woomy"
-  "A mode for Woomy programming language."
-  (when (treesit-ready-p 'woomy)
-    (setq-local treesit-variables ...)
-    ...
-    (treesit-major-mode-setup)))
-@end group
-@end example
+First, the major mode should use @code{treesit-ready-p} to determine
+whether tree-sitter can be activated in this mode.
 
 @defun treesit-ready-p language &optional quiet
 This function checks for conditions for activating tree-sitter.  It
@@ -1803,12 +1718,15 @@ language grammar for @var{language} is available on the system
 
 This function emits a warning if tree-sitter cannot be activated.  If
 @var{quiet} is @code{message}, the warning is turned into a message;
-if @var{quiet} is @code{t}, no warning or message is displayed.
+if @var{quiet} is @code{nil}, no warning or message is displayed.
 
 If all the necessary conditions are met, this function returns
 non-@code{nil}; otherwise it returns @code{nil}.
 @end defun
 
+Next, the major mode should set up tree-sitter variables and call
+@code{treesit-major-mode-setup}.
+
 @defun treesit-major-mode-setup
 This function activates some tree-sitter features for a major mode.
 

doc/lispref/positions.texi

@@ -858,40 +858,6 @@ top-level defuns, if the value is @code{nested}, navigation functions
 recognize nested defuns.
 @end defvar
 
-@defvar treesit-sentence-type-regexp
-The value of this variable is a regexp matching the node type of sentence
-nodes.  (For ``node'' and ``node type'', @pxref{Parsing Program Source}.)
-@end defvar
-
-@findex treesit-forward-sentence
-@findex forward-sentence
-@findex backward-sentence
-If Emacs is compiled with tree-sitter, it can use the tree-sitter
-parser information to move across syntax constructs.  Since what
-exactly is considered a sentence varies between languages, a major
-mode should set @code{treesit-sentence-type-regexp} to determine that.
-Then the mode can get navigation-by-sentence functionality for free,
-by using @code{forward-sentence} and
-@code{backward-sentence}(@pxref{Moving by Sentences,,, emacs, The
-extensible self-documenting text editor}).
-
-@defvar treesit-sexp-type-regexp
-The value of this variable is a regexp matching the node type of sexp
-nodes.  (For ``node'' and ``node type'', @pxref{Parsing Program
-Source}.)
-@end defvar
-
-@findex treesit-forward-sexp
-@findex forward-sexp@r{, and tree-sitter}
-@findex backward-sexp@r{, and tree-sitter}
-If Emacs is compiled with tree-sitter, it can use the tree-sitter
-parser information to move across syntax constructs.  Since what
-exactly is considered a sexp varies between languages, a major mode
-should set @code{treesit-sexp-type-regexp} to determine that.  Then
-the mode can get navigation-by-sexp functionality for free, by using
-@code{forward-sexp} and @code{backward-sexp}(@pxref{Moving by
-Sentences,,, emacs, The extensible self-documenting text editor}).
-
 @node Skipping Characters
 @subsection Skipping Characters
 @cindex skipping characters
@@ -1071,13 +1037,11 @@ positions.
 In an interactive call, @var{start} and @var{end} are set to the bounds
 of the current region (point and the mark, with the smallest first).
 
-However, when the narrowing has been set by @code{with-restriction} with
-a label argument (see below), @code{narrow-to-region} can be used only
-within the limits of that narrowing.  If @var{start} or @var{end} are
-outside these limits, the corresponding limit set by
-@code{with-restriction} is used instead.  To gain access to other
-portions of the buffer, use @code{without-restriction} with the same
-label.
+Note that, in rare circumstances, Emacs may decide to leave, for
+performance reasons, the accessible portion of the buffer unchanged
+after a call to @code{narrow-to-region}.  This can happen when a Lisp
+program is called via low-level hooks, such as
+@code{jit-lock-functions}, @code{post-command-hook}, etc.
 @end deffn
 
 @deffn Command narrow-to-page &optional move-count
@@ -1101,14 +1065,14 @@ It is equivalent to the following expression:
 @example
 (narrow-to-region 1 (1+ (buffer-size)))
 @end example
-
-However, when a narrowing has been set by @code{with-restriction} with a
-label argument (see below), the limits set by @code{with-restriction}
-are restored, instead of canceling the narrowing.  To gain access to
-other portions of the buffer, use @code{without-restriction} with the
-same label.
 @end deffn
 
+Note that, in rare circumstances, Emacs may decide to leave, for
+performance reasons, the accessible portion of the buffer unchanged
+after a call to @code{widen}.  This can happen when a Lisp program is
+called via low-level hooks, such as @code{jit-lock-functions},
+@code{post-command-hook}, etc.
+
 @defun buffer-narrowed-p
 This function returns non-@code{nil} if the buffer is narrowed, and
 @code{nil} otherwise.
@@ -1122,9 +1086,6 @@ in effect.  The state of narrowing is restored even in the event of an
 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 Therefore, this construct is a clean way to narrow a buffer temporarily.
 
-This construct also saves and restores the narrowings that were set by
-@code{with-restriction} with a label argument (see below).
-
 The value returned by @code{save-restriction} is that returned by the
 last form in @var{body}, or @code{nil} if no body forms were given.
 
@@ -1174,64 +1135,3 @@ This is the contents of foo@point{}
 @end group
 @end example
 @end defspec
-
-@defspec with-restriction start end [:label label] body
-This special form saves the current bounds of the accessible portion
-of the buffer, sets the accessible portion to start at @var{start} and
-end at @var{end}, evaluates the @var{body} forms, and restores the
-saved bounds.  In that case it is equivalent to
-
-@example
-(save-restriction
-  (narrow-to-region start end)
-  body)
-@end example
-
-@cindex labeled narrowing
-When the optional argument @var{label}, a symbol, is present, the
-narrowing is @dfn{labeled}.  A labeled narrowing differs from a
-non-labeled one in several ways:
-
-@itemize @bullet
-@item
-During the evaluation of the @var{body} form, @code{narrow-to-region}
-and @code{widen} can be used only within the @var{start} and @var{end}
-limits.
-
-@item
-To lift the restriction introduced by @code{with-restriction} and gain
-access to other portions of the buffer, use @code{without-restriction}
-with the same @var{label} argument.  (Another way to gain access to
-other portions of the buffer is to use an indirect buffer
-(@pxref{Indirect Buffers}).)
-
-@item
-Labeled narrowings can be nested.
-
-@item
-Labeled narrowings can only be used in Lisp programs: they are never
-visible on display, and never interfere with narrowings set by the
-user.
-@end itemize
-
-If you use @code{with-restriction} with the optional @var{label}
-argument, we recommend documenting the @var{label} in the doc strings
-of the functions which use it, so that other Lisp programs your code
-calls could lift the labeled narrowing if and when it needs.
-@end defspec
-
-@defspec without-restriction [:label label] body
-This special form saves the current bounds of the accessible portion
-of the buffer, widens the buffer, evaluates the @var{body} forms, and
-restores the saved bounds.  In that case it is equivalent to
-
-@example
-(save-restriction
-  (widen)
-  body)
-@end example
-
-When the optional argument @var{label} is present, the narrowing set
-by @code{with-restriction} with the same @var{label} argument is
-lifted.
-@end defspec

doc/lispref/processes.texi

@@ -1755,9 +1755,7 @@ caught automatically, so that it doesn't stop the execution of whatever
 program was running when the filter function was started.  However, if
 @code{debug-on-error} is non-@code{nil}, errors are not caught.
 This makes it possible to use the Lisp debugger to debug filter
-functions.  @xref{Debugger}.  If an error is caught, Emacs pauses for
-@code{process-error-pause-time} seconds so that the user sees the
-error.  @xref{Asynchronous Processes}
+functions.  @xref{Debugger}.
 
   Many filter functions sometimes (or always) insert the output in the
 process's buffer, mimicking the actions of the default filter.
@@ -2161,9 +2159,7 @@ automatically, so that it doesn't stop the execution of whatever
 programs was running when the sentinel was started.  However, if
 @code{debug-on-error} is non-@code{nil},  errors are not caught.
 This makes it possible to use the Lisp debugger to debug the
-sentinel.  @xref{Debugger}.  If an error is caught, Emacs pauses for
-@code{process-error-pause-time} seconds so that the user sees the
-error.  @xref{Asynchronous Processes}
+sentinel.  @xref{Debugger}.
 
   While a sentinel is running, the process sentinel is temporarily
 set to @code{nil} so that the sentinel won't run recursively.

doc/lispref/sequences.texi

@@ -376,43 +376,45 @@ is less than @var{c}, then @var{a} must be less than @var{c}.  If you
 use a comparison function which does not meet these requirements, the
 result of @code{sort} is unpredictable.
 
-The destructive aspect of @code{sort} for lists is that it reuses the
-cons cells forming @var{sequence} by changing their contents, possibly
-rearranging them in a different order.  This means that the value of
-the input list is undefined after sorting; only the list returned by
-@code{sort} has a well-defined value.  Example:
+The destructive aspect of @code{sort} for lists is that it rearranges the
+cons cells forming @var{sequence} by changing @sc{cdr}s.  A nondestructive
+sort function would create new cons cells to store the elements in their
+sorted order.  If you wish to make a sorted copy without destroying the
+original, copy it first with @code{copy-sequence} and then sort.
+
+Sorting does not change the @sc{car}s of the cons cells in @var{sequence};
+the cons cell that originally contained the element @code{a} in
+@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now
+appears in a different position in the list due to the change of
+@sc{cdr}s.  For example:
 
 @example
 @group
-(setq nums (list 2 1 4 3 0))
-(sort nums #'<)
-     @result{} (0 1 2 3 4)
-     ; nums is unpredictable at this point
+(setq nums (list 1 3 2 6 5 4 0))
+     @result{} (1 3 2 6 5 4 0)
 @end group
-@end example
-
-Most often we store the result back into the variable that held the
-original list:
-
-@example
-(setq nums (sort nums #'<))
-@end example
-
-If you wish to make a sorted copy without destroying the original,
-copy it first and then sort:
-
-@example
 @group
-(setq nums (list 2 1 4 3 0))
-(sort (copy-sequence nums) #'<)
-     @result{} (0 1 2 3 4)
+(sort nums #'<)
+     @result{} (0 1 2 3 4 5 6)
 @end group
 @group
 nums
-     @result{} (2 1 4 3 0)
+     @result{} (1 2 3 4 5 6)
 @end group
 @end example
 
+@noindent
+@strong{Warning}: Note that the list in @code{nums} no longer contains
+0; this is the same cons cell that it was before, but it is no longer
+the first one in the list.  Don't assume a variable that formerly held
+the argument now holds the entire sorted list!  Instead, save the result
+of @code{sort} and use that.  Most often we store the result back into
+the variable that held the original list:
+
+@example
+(setq nums (sort nums #'<))
+@end example
+
 For the better understanding of what stable sort is, consider the following
 vector example.  After sorting, all items whose @code{car} is 8 are grouped
 at the beginning of @code{vector}, but their relative order is preserved.

doc/lispref/strings.texi

@@ -911,8 +911,8 @@ This function returns a new string containing one character,
 @end defun
 
 @defun string-to-char string
-  This function returns the first character in @var{string}.  This is
-mostly identical to @w{@code{(aref string 0)}}, except that it returns 0
+  This function returns the first character in @var{string}.  This
+mostly identical to @code{(aref string 0)}, except that it returns 0
 if the string is empty.  (The value is also 0 when the first character
 of @var{string} is the null character, @acronym{ASCII} code 0.)  This
 function may be eliminated in the future if it does not seem useful

doc/lispref/symbols.texi

@@ -276,8 +276,9 @@ This function returns the string that is @var{symbol}'s name.  For example:
 @end group
 @end example
 
-@strong{Warning:} Never alter the string returned by that function.
-Doing that might make Emacs dysfunctional, and might even crash Emacs.
+@strong{Warning:} Changing the string by substituting characters does
+change the name of the symbol, but fails to update the obarray, so don't
+do it!
 @end defun
 
 @cindex uninterned symbol, and generating Lisp code
@@ -643,12 +644,6 @@ ignore a call whose value is unused.  If the property's value is
 calls.  In addition to byte compiler optimizations, this property is
 also used for determining function safety (@pxref{Function Safety}).
 
-@item important-return-value
-@cindex @code{important-return-value} property
-A non-@code{nil} value makes the byte compiler warn about code that
-calls the named function without using its returned value.  This is
-useful for functions where doing so is likely to be a mistake.
-
 @item undo-inhibit-region
 If non-@code{nil}, the named function prevents the @code{undo} operation
 from being restricted to the active region, if @code{undo} is invoked

doc/lispref/text.texi

@@ -3765,19 +3765,18 @@ Consecutive characters with the same @code{field} property constitute a
 @item cursor
 @kindex cursor @r{(text property)}
 Normally, the cursor is displayed at the beginning or the end of any
-overlay and text property strings that ``hide'' (i.e., are displayed
-instead of) the current buffer position.  You can instead tell Emacs
-to place the cursor on any desired character of these strings by
-giving that character a non-@code{nil} @code{cursor} text property.
-In addition, if the value of the @code{cursor} property is an integer,
-it specifies the number of buffer's character positions, starting with
-the position where the overlay or the @code{display} property begins,
-for which the cursor should be displayed on that character.
-Specifically, if the value of the @code{cursor} property of a
-character is the number @var{n}, the cursor will be displayed on this
-character for any buffer position in the range
-@code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos} is the
-overlay's starting position given by @code{overlay-start}
+overlay and text property strings present at the current buffer
+position.  You can instead tell Emacs to place the cursor on any
+desired character of these strings by giving that character a
+non-@code{nil} @code{cursor} text property.  In addition, if the value
+of the @code{cursor} property is an integer, it specifies the number
+of buffer's character positions, starting with the position where the
+overlay or the @code{display} property begins, for which the cursor
+should be displayed on that character.  Specifically, if the value of
+the @code{cursor} property of a character is the number @var{n}, the
+cursor will be displayed on this character for any buffer position in
+the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
+is the overlay's starting position given by @code{overlay-start}
 (@pxref{Managing Overlays}), or the position where the @code{display}
 text property begins in the buffer.
 
@@ -4948,38 +4947,16 @@ computed for the whole of @var{object}.
 If the argument @var{binary} is omitted or @code{nil}, the function
 returns the @dfn{text form} of the hash, as an ordinary Lisp string.
 If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
-form}, as a sequence of bytes stored in a unibyte string.  The length
-of the returned string depends on @var{algorithm}:
-
-@itemize
-@item
-For @code{md5}: 32 characters (32 bytes if @var{binary} is
-non-@code{nil}).
-@item
-For @code{sha1}: 40 characters (40 bytes if @var{binary} is
-non-@code{nil}).
-@item
-For @code{sha224}: 56 characters (56 bytes if @var{binary} is
-non-@code{nil}).
-@item
-For @code{sha256}: 64 characters (64 bytes if @var{binary} is
-non-@code{nil}).
-@item
-For @code{sha384}: 96 characters (96 bytes if @var{binary} is
-non-@code{nil}).
-@item
-For @code{sha512}: 128 characters (128 bytes if @var{binary} is
-non-@code{nil}).
-@end itemize
+form}, as a sequence of bytes stored in a unibyte string.
 
 This function does not compute the hash directly from the internal
 representation of @var{object}'s text (@pxref{Text Representations}).
 Instead, it encodes the text using a coding system (@pxref{Coding
 Systems}), and computes the hash from that encoded text.  If
 @var{object} is a buffer, the coding system used is the one which
-would be chosen by default for writing the text of that buffer into a
-file.  If @var{object} is a string, the user's preferred coding system
-is used (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
+would be chosen by default for writing the text into a file.  If
+@var{object} is a string, the user's preferred coding system is used
+(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
 @end defun
 
 @defun md5 object &optional start end coding-system noerror
@@ -4987,7 +4964,7 @@ This function returns an MD5 hash.  It is semi-obsolete, since for
 most purposes it is equivalent to calling @code{secure-hash} with
 @code{md5} as the @var{algorithm} argument.  The @var{object},
 @var{start} and @var{end} arguments have the same meanings as in
-@code{secure-hash}.  The function returns a 32-character string.
+@code{secure-hash}.
 
 If @var{coding-system} is non-@code{nil}, it specifies a coding system
 to use to encode the text; if omitted or @code{nil}, the default
@@ -5010,20 +4987,7 @@ It should be somewhat more efficient on larger buffers than
 @code{secure-hash} is, and should not allocate more memory.
 @c Note that we do not document what hashing function we're using, or
 @c even whether it's a cryptographic hash, since that may change
-@c according to what we find useful.  We also don't document the
-@c length of the hash string it returns, since that can be used to
-@c guess the hashing function being used.
-@end defun
-
-@defun sha1 object &optional start end binary
-This function is equivalent to calling @code{secure-hash} like this:
-
-@lisp
-(secure-hash 'sha1 object start end binary)
-@end lisp
-
-It returns a 40-character string if @var{binary} is @code{nil}, or a
-40-byte unibyte string otherwise.
+@c according to what we find useful.
 @end defun
 
 @node Suspicious Text
@@ -5510,7 +5474,7 @@ contents of an SQLite database.
 @section Parsing HTML and XML
 @cindex parsing html
 
-  Emacs can be compiled with built-in @file{libxml2} support.
+  Emacs can be compiled with built-in libxml2 support.
 
 @defun libxml-available-p
 This function returns non-@code{nil} if built-in libxml2 support is
@@ -5529,10 +5493,8 @@ mistakes.
 If @var{start} or @var{end} are @code{nil}, they default to the values
 from @code{point-min} and @code{point-max}, respectively.
 
-The optional argument @var{base-url}, if non-@code{nil}, should be
-used for warnings and errors reported by the @file{libxml2} library,
-but Emacs currently calls the library with errors and warnings
-disabled, so this argument is not used.
+The optional argument @var{base-url}, if non-@code{nil}, should be a
+string specifying the base URL for relative URLs occurring in links.
 
 If the optional argument @var{discard-comments} is non-@code{nil},
 any top-level comment is discarded.  (This argument is obsolete and

doc/lispref/variables.texi

@@ -1183,16 +1183,13 @@ wants the current value of a variable, it looks first in the lexical
 environment; if the variable is not specified in there, it looks in
 the symbol's value cell, where the dynamic value is stored.
 
-  (Internally, the lexical environment is a list whose members are
-usually cons cells that are symbol-value pairs, but some of its
-members can be symbols rather than cons cells.  A symbol in the list
-means the lexical environment declared that symbol's variable as
-locally considered to be dynamically bound.  This list can be passed
-as the second argument to the @code{eval} function, in order to
-specify a lexical environment in which to evaluate a form.
-@xref{Eval}.  Most Emacs Lisp programs, however, should not interact
-directly with lexical environments in this way; only specialized
-programs like debuggers.)
+  (Internally, the lexical environment is an alist of symbol-value
+pairs, with the final element in the alist being the symbol @code{t}
+rather than a cons cell.  Such an alist can be passed as the second
+argument to the @code{eval} function, in order to specify a lexical
+environment in which to evaluate a form.  @xref{Eval}.  Most Emacs
+Lisp programs, however, should not interact directly with lexical
+environments in this way; only specialized programs like debuggers.)
 
 @cindex closures, example of using
   Lexical bindings have indefinite extent.  Even after a binding
@@ -2026,7 +2023,6 @@ file-local variables stored in @code{file-local-variables-alist}.
 @end defvar
 
 @cindex safe local variable
-@cindex @code{safe-local-variable}, property of variable
   You can specify safe values for a variable with a
 @code{safe-local-variable} property.  The property has to be a
 function of one argument; any value is safe if the function returns
@@ -2561,9 +2557,6 @@ documentation as @var{base-variable} has, if any, unless
 the documentation of the variable at the end of the chain of aliases.
 
 This function returns @var{base-variable}.
-
-If the resulting variable definition chain would be circular, then
-Emacs will signal a @code{cyclic-variable-indirection} error.
 @end defun
 
   Variable aliases are convenient for replacing an old name for a
@@ -2612,6 +2605,9 @@ look like:
 This function returns the variable at the end of the chain of aliases
 of @var{variable}.  If @var{variable} is not a symbol, or if @var{variable} is
 not defined as an alias, the function returns @var{variable}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
 @end defun
 
 @example

doc/lispref/windows.texi

@@ -629,12 +629,6 @@ example, by calling @code{select-window} with argument @var{norecord}
 @code{nil}.  Hence, this macro is the preferred way to temporarily work
 with @var{window} as the selected window without needlessly running
 @code{buffer-list-update-hook}.
-
-Note that this macro temporarily puts the window management code in an
-unstable state.  In particular, the most recently used window (see below)
-will not necessarily match the selected one.  Hence, functions like
-@code{get-lru-window} and @code{get-mru-window} may return unexpected
-results when called from the body of this macro.
 @end defmac
 
 @defmac with-selected-frame frame forms@dots{}
@@ -656,17 +650,15 @@ The @dfn{use time} of a window is not really a time value, but an
 integer that does increase monotonically with each call of
 @code{select-window} with a @code{nil} @var{norecord} argument.  The
 window with the lowest use time is usually called the least recently
-used window.  The window with the highest use time is called the most
-recently used one (@pxref{Cyclic Window Ordering}) and is usually the
-selected window unless @code{with-selected-window} has been used.
+used window while the window with the highest use time is called the
+most recently used one (@pxref{Cyclic Window Ordering}).
 @end defun
 
 @defun window-bump-use-time &optional window
-This function marks @var{window} as being the second most recently
-used one (after the selected window).  It does nothing if @var{window}
-is the selected window or the selected window does not have the
-highest use time among all windows which may happen within the scope
-of @code{with-selected-window}.
+This function marks @var{window} as being the most recently used
+one.  This can be useful when writing certain @code{pop-to-buffer}
+scenarios (@pxref{Switching Buffers}).  @var{window} must be a live
+window and defaults to the selected one.
 @end defun
 
 @anchor{Window Group}Sometimes several windows collectively and
@@ -2763,40 +2755,14 @@ before.
 
 @defun display-buffer-use-some-window buffer alist
 This function tries to display @var{buffer} by choosing an existing
-window and displaying the buffer in that window.  It first tries to find
-a window that has not been used recently (@pxref{Cyclic Window
-Ordering}) on any frame specified by a @code{lru-frames} @var{alist}
-entry, falling back to the selected frame if no such entry exists.  It
-also prefers windows that satisfy the constraints specified by
-@code{window-min-width} and @code{window-min-height} @var{alist}
-entries; preferring full-width windows if no @code{window-min-width}
-entry is found.  Finally, it will not return a window whose use time is
-higher than that specified by any @code{lru-time} entry provided by
-@var{alist}.
-
-If no less recently used window is found, this function will try to use
-some other window, preferably a large window on some visible frame.  It
-can fail if all windows are dedicated to other buffers (@pxref{Dedicated
-Windows}).
+window and displaying the buffer in that window.  It can fail if all
+windows are dedicated to other buffers (@pxref{Dedicated Windows}).
 @end defun
 
 @defun display-buffer-use-least-recent-window buffer alist
-This function is similar to @code{display-buffer-use-some-window}, but
-will try harder to not use the a recently used window.  In particular,
-it does not use the selected window.  In addition, it will first try to
-reuse a window that shows @var{buffer} already, base the decision
-whether it should use a window showing another buffer on that window's
-use time alone and pop up a new window if no usable window is found.
-
-Finally, this function will bump the use time (@pxref{Selecting
-Windows}) of any window it returns in order to avoid that further
-invocations will use that window for showing another buffer.  An
-application that wants to display several buffers in a row can help this
-function by providing a @code{lru-time} @var{alist} entry it has
-initially set to the value of the selected window's use time.  Each
-invocation of this function will then bump the use time of the window
-returned to a value higher than that and a subsequent invocation will
-inhibit this function to use a window it returned earlier.
+This function is like @code{display-buffer-use-some-window}, but will
+not reuse the current window, and will use the least recently
+switched-to window.
 @end defun
 
 @defun display-buffer-in-direction buffer alist
@@ -3066,40 +3032,12 @@ The value specifies an alist of window parameters to give the chosen
 window.  All action functions that choose a window should process this
 entry.
 
-@vindex window-min-width@r{, a buffer display action alist entry}
-@item window-min-width
-The value specifies a minimum width of the window used, in canonical
-frame columns.  The special value @code{full-width} means the chosen
-window should be one that has no other windows on the left or right of
-it in its frame.
-
-This entry is currently honored by @code{display-buffer-use-some-window}
-and @code{display-buffer-use-least-recent-window}, which try hard to avoid
-returning a less recently used window that does not satisfy the entry.
-
-Note that providing such an entry alone does not necessarily make the
-window as wide as specified by its value.  To actually resize an
-existing window or make a new window as wide as specified by this
-entry's value, a @code{window-width} entry specifying that value
-should be provided as well.  Such a @code{window-width} entry can,
-however, specify a completely different value, or ask the window width
-to fit that of its buffer, in which case the
-@code{window-min-width} entry provides the guaranteed minimum width of
-the window.
-
 @vindex window-min-height@r{, a buffer display action alist entry}
 @item window-min-height
-The value specifies a minimum height of the window used, in canonical
-frame lines.  The special value @code{full-height} means the chosen
-window should be a full-height window, one that has no other windows
-above or below it in its frame.
-
-This entry is currently honored by @code{display-buffer-below-selected}
-which does not use a window that is not as high as specified by this
-entry.  It's also honored by @code{display-buffer-use-some-window} and
-@code{display-buffer-use-least-recent-window} which try hard to avoid
-returning a less recently used window if it does not satisfy this
-constraint.
+The value specifies a minimum height of the window used, in lines.  If
+a window is not or cannot be made as high as specified by this entry,
+the window is not considered for use.  The only client of this entry
+is presently @code{display-buffer-below-selected}.
 
 Note that providing such an entry alone does not necessarily make the
 window as tall as specified by its value.  To actually resize an
@@ -3216,7 +3154,7 @@ any window it creates as dedicated to its buffer (@pxref{Dedicated
 Windows}).  It does that by calling @code{set-window-dedicated-p} with
 the chosen window as first argument and the entry's value as second.
 Side windows are by default dedicated with the value @code{side}
-(@pxref{Side Window Options and Functions}).
+((@pxref{Side Window Options and Functions}).
 
 @vindex preserve-size@r{, a buffer display action alist entry}
 @item preserve-size
@@ -3228,40 +3166,6 @@ preserve both, its width and its height.  This entry should be
 processed only under certain conditions which are specified right
 after this list.
 
-@vindex lru-frames@r{, a buffer display action alist entry}
-@item lru-frames
-The value specifies the set of frames to search for a window that can be
-used to display the buffer.  It is honored by
-@code{display-buffer-use-some-window} and
-@code{display-buffer-use-least-recent-window} when trying to find a less
-recently used window showing some other buffer.  Its values are the same
-as for the @code{reusable-frames} entry described above.
-
-@vindex lru-time@r{, a buffer display action alist entry}
-@item lru-time
-The value is supposed to specify a use time (@pxref{Selecting Windows}).
-This entry is honored by @code{display-buffer-use-some-window} and
-@code{display-buffer-use-least-recent-window} when trying to find a less
-recently used window showing some other buffer.  If a window's use time
-is higher than the value specified by this option, these action
-functions will not consider such a window for displaying the buffer.
-
-@vindex bump-use-time@r{, a buffer display action alist entry}
-@item bump-use-time
-If non-@code{nil}, such an entry will cause @code{display-buffer} to
-bump the use time (@pxref{Selecting Windows}) of the window it uses.
-This should avoid later use of this window by action functions
-like @code{display-buffer-use-some-window} and
-@code{display-buffer-use-least-recent-window} for showing another
-buffer.
-
-There is a fine difference between using this entry and using the action
-function @code{display-buffer-use-least-recent-window}.  Calling the
-latter means to only bump the use times of windows that function uses
-for displaying the buffer.  The entry described here will cause
-@code{display-buffer} to bump the use time of @emph{any} window used for
-displaying a buffer.
-
 @vindex pop-up-frame-parameters@r{, a buffer display action alist entry}
 @item pop-up-frame-parameters
 The value specifies an alist of frame parameters to give a new frame,
@@ -3417,6 +3321,13 @@ window has at least that many columns.  If the value is @code{nil},
 that means not to split this way.
 @end defopt
 
+@defopt display-buffer-avoid-small-windows
+If non-@code{nil}, this should be a number.  Windows that have fewer
+lines than that will be avoided when choosing an existing window.  The
+value is interpreted in units of the frame's canonical line height,
+like @code{window-total-height} does (@pxref{Window Sizes}).
+@end defopt
+
 @defopt even-window-sizes
 This variable, if non-@code{nil}, causes @code{display-buffer} to even
 window sizes whenever it reuses an existing window, and that window is
@@ -4081,80 +3992,54 @@ related to the new window.  For non-input related actions
 @code{display-buffer-below-selected} might be preferable because the
 selected window usually already has the user's attention.
 
-@item Take care which window is selected
-Many applications call @code{display-buffer} from within window
-excursions produced by @code{with-selected-window} or
-@code{select-window} calls with a non-@code{nil} @var{norecord}
-argument.  This is almost always a bad idea because the window selected
-within such an excursion is usually not the window selected in the
-configuration presented to the user.
+@item Handle subsequent invocations of @code{display-buffer}
+@code{display-buffer} is not overly well suited for displaying several
+buffers in sequence and making sure that all these buffers are shown
+orderly in the resulting window configuration.  Again, the standard
+action functions @code{display-buffer-pop-up-window} and
+@code{display-buffer-use-some-window} are not very suited for this
+purpose due to their somewhat chaotic nature in more complex
+configurations.
 
-If, for example, a user had added an @code{inhibit-same-window} alist
-entry, that entry would have avoided the window selected within the
-scope of the excursion and not the window selected in the resulting
-configuration.  Even if no such entry has been added, the resulting
-behavior might be strange.  While in a frame containing one live
-window, evaluating the following form
+   To produce a window configuration displaying multiple buffers (or
+different views of one and the same buffer) in one and the same
+display cycle, Lisp programmers will unavoidably have to write
+their own action functions.  A few tricks listed below might help in
+this regard.
 
-@example
-@group
-(progn
-  (split-window)
-  (display-buffer "*Messages*"))
-@end group
-@end example
+@itemize @bullet
+@item
+Making windows atomic (@pxref{Atomic Windows}) avoids breaking an
+existing window composition when popping up a new window.
+The new window will pop up outside the composition instead.
 
-@noindent
-will display a window showing the @file{*Messages*} buffer at the bottom
-and leave the other window selected.  Evaluating the next form
+@item
+Temporarily dedicating windows to their buffers (@pxref{Dedicated
+Windows}) avoids using a window for displaying a different
+buffer.  A non-dedicated window will be used instead.
 
-@example
-@group
-(with-selected-window (split-window)
-  (display-buffer "*Messages*"))
-@end group
-@end example
+@item
+Calling @code{window-preserve-size} (@pxref{Preserving Window Sizes})
+will try to keep the size of the argument window unchanged when
+popping up a new window.  You have to make sure that another window in
+the same combination can be shrunk instead, though.
 
-@noindent
-will display @file{*Messages*} in a window on the top and select it
-which is usually not what @code{display-buffer} is supposed to do.
+@item
+Side windows (@pxref{Side Windows}) can be used for displaying
+specific buffers always in a window at the same position of a frame.
+This permits grouping buffers that do not compete for being shown at
+the same time on a frame and showing any such buffer in the same window
+without disrupting the display of other buffers.
 
-On the other hand, while evaluating the following form
-
-@example
-@group
-(progn
-  (split-window)
-  (pop-to-buffer "*Messages*"))
-@end group
-@end example
-
-@noindent
-will correctly select the @file{*Messages*} buffer, the next form
-
-@example
-@group
-(progn
-  (split-window)
-  (with-selected-window (selected-window)
-    (pop-to-buffer "*Messages*")))
-@end group
-@end example
-
-@noindent
-will not.
-
-Also, invocations of action functions like
-@code{display-buffer-use-some-window} and
-@code{display-buffer-use-least-recent-window} that expect the selected
-window to have the highest use time among all windows, may fail to
-produce a window according to their specifications.
-
-Hence, an application that relies on using a window excursion should try
-to postpone the @code{display-buffer} call until after the excursion has
-terminated.
+@item
+Child frames (@pxref{Child Frames}) can be used to display a buffer
+within the screen estate of the selected frame without disrupting that
+frame's window configuration and without the overhead associated with
+full-fledged frames as inflicted by @code{display-buffer-pop-up-frame}.
+@end itemize
 @end table
 
+
 @node Window History
 @section Window History
 @cindex window history

doc/misc/calc.texi

@@ -232,8 +232,7 @@ series of calculators, its many features include:
 
 @itemize @bullet
 @item
-Choice of algebraic or Reverse Polish notation (RPN),
-i.e. stack-based, entry of calculations.
+Choice of algebraic or RPN (stack-based) entry of calculations.
 
 @item
 Arbitrary precision integers and floating-point numbers.
@@ -422,8 +421,8 @@ difference between lower-case and upper-case letters.  Remember,
 @key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab,
 Delete, and Space keys.
 
-@strong{RPN calculation.}  In Reverse Polish notation (RPN), you type
-the input number(s) first, then the command to operate on the numbers.
+@strong{RPN calculation.}  In RPN, you type the input number(s) first,
+then the command to operate on the numbers.
 
 @noindent
 Type @kbd{2 @key{RET} 3 + Q} to compute
@@ -1349,19 +1348,18 @@ to control various modes of the Calculator.
 @subsection RPN Calculations and the Stack
 
 @cindex RPN notation
-@cindex Reverse Polish notation
 @noindent
 @ifnottex
-Calc normally uses Reverse Polish notation (RPN).  You may be familiar
-with the RPN system from Hewlett-Packard calculators, FORTH, or
-PostScript.  (Reverse Polish Notation is named after the Polish
-mathematician Jan Lukasiewicz.)
+Calc normally uses RPN notation.  You may be familiar with the RPN
+system from Hewlett-Packard calculators, FORTH, or PostScript.
+(Reverse Polish Notation, RPN, is named after the Polish mathematician
+Jan Lukasiewicz.)
 @end ifnottex
 @tex
-Calc normally uses Reverse Polish notation (RPN).  You may be familiar
-with the RPN system from Hewlett-Packard calculators, FORTH, or
-PostScript.  (Reverse Polish Notation is named after the Polish
-mathematician Jan \L ukasiewicz.)
+Calc normally uses RPN notation.  You may be familiar with the RPN
+system from Hewlett-Packard calculators, FORTH, or PostScript.
+(Reverse Polish Notation, RPN, is named after the Polish mathematician
+Jan \L ukasiewicz.)
 @end tex
 
 The central component of an RPN calculator is the @dfn{stack}.  A
@@ -5394,7 +5392,7 @@ a variable containing a vector of rules.
 1:  [merge, secsqr]          1:  [a/x + b/x := (a + b)/x, ... ]
     .                                 .
 
-    ' [merge,secsqr] @key{RET}          =
+    ' [merge,sinsqr] @key{RET}          =
 
 @end group
 @end smallexample

doc/misc/cc-mode.texi

@@ -330,7 +330,6 @@ Syntactic Symbols
 * Multiline Macro Symbols::
 * Objective-C Method Symbols::
 * Java Symbols::
-* Constraint Symbols::
 * Statement Block Symbols::
 * K&R Symbols::
 
@@ -4235,9 +4234,6 @@ The first line in a ``topmost'' definition.  @ref{Function Symbols}.
 Topmost definition continuation lines.  This is only used in the parts
 that aren't covered by other symbols such as @code{func-decl-cont} and
 @code{knr-argdecl}.  @ref{Function Symbols}.
-@item constraint-cont
-Continuation line of a topmost C++20 concept or requires clause.
-@ref{Constraint Symbols}.
 @item annotation-top-cont
 Topmost definition continuation lines where all previous items are
 annotations.  @ref{Java Symbols}.
@@ -4401,7 +4397,6 @@ Java.  @ref{Java Symbols}.
 * Multiline Macro Symbols::
 * Objective-C Method Symbols::
 * Java Symbols::
-* Constraint Symbols::
 * Statement Block Symbols::
 * K&R Symbols::
 @end menu
@@ -5075,39 +5070,6 @@ the current line.  Similarly, line 4 is assigned the @code{annotation-var-cont}
 syntax due to it being a continuation of a variable declaration where preceding
 the declaration is an annotation.
 
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node    Constraint Symbols
-@subsection C++ Constraint Symbols
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-The C++20 standard introduced the notion of @dfn{concepts} and
-@dfn{requirements}, a typical instance of which looks something like
-this:
-
-@example
- 1: template <typename T>
- 2: requires
- 3:   requires (T t) @{
- 4:     @{ ++t; @}
- 5:   @}
- 6:   && std::is_integral<T>
- 7:   int foo();
-@end example
-
-@ssindex constraint-cont
-Line 1 is assigned the familiar @code{topmost-intro}.  Line 2 gets
-@code{topmost-intro-cont}, being the keyword which introduces a
-@dfn{requires clause}.  Lines 3, 6, and 7 are assigned the syntax
-@code{constraint-cont}, being continuations of the requires clause
-started on line 2.  Lines 4 and 5 get the syntaxes
-@code{defun-block-intro} and @code{defun-close}, being analyzed as
-though part of a function.
-
-Note that the @code{requires} on Line 3 begins a @dfn{requires
-expression}, not a a requires clause, hence its components are not
-assigned @code{constraint-cont}.  See
-@url{https://en.cppreference.com/w/cpp/language/requires}.
-
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node    Statement Block Symbols
 @subsection Statement Block Symbols

doc/misc/efaq.texi

@@ -847,7 +847,6 @@ in the Emacs development repository (@pxref{Latest version of Emacs}).
 @menu
 * Origin of the term Emacs::
 * Latest version of Emacs::
-* New in Emacs 29::
 * New in Emacs 28::
 * New in Emacs 27::
 * New in Emacs 26::
@@ -920,125 +919,6 @@ Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}).  You can give
 this command a prefix argument to read about which features were new
 in older versions.
 
-@node New in Emacs 29
-@section What is different about Emacs 29?
-@cindex Differences between Emacs 28 and Emacs 29
-@cindex Emacs 29, new features in
-
-Here's a list of the most important changes in Emacs 29 as compared to
-Emacs 28 (the full list is too long, and can be read in the Emacs
-@file{NEWS} file by typing @kbd{C-h n} inside Emacs).
-
-@itemize
-@item
-Emacs can now be built with the
-@uref{https://tree-sitter.github.io/tree-sitter/, tree-sitter
-library}, which provides incremental parsing capabilities for several
-programming languages.  Emacs comes with several major modes which use
-this library for syntax highlighting (a.k.a. ``fontification''),
-indentation, Imenu support, etc.  These modes have names
-@code{@var{lang}-ts-mode}, where @var{lang} is the programming
-language.  For example, @code{c-ts-mode}, @code{ruby-ts-mode}, etc.
-There are several new font-lock faces, such as
-@code{font-lock-number-face} and @code{font-lock-operator-face},
-intended to be used with these modes.
-
-@item
-Emacs can now be built in the PGTK (``pure GTK'') configuration, which
-supports running Emacs on window systems other than X, such as Wayland
-and Broadway.
-
-@item
-Emacs now has built-in support for accessing SQLite databases.  This
-requires Emacs to be built with the optional @file{sqlite3} library.
-
-@item
-Emacs comes with the popular @code{use-package} package bundled.
-
-@item
-Emacs can now display WebP images, if it was built with the optional
-@file{libwebp} library.
-
-@item
-On X window system, Emacs now supports the XInput2 specification for
-input events.
-
-@item
-Emacs now comes with a client library for using Language Server
-Protocol (@acronym{LSP}) servers.  This library, named @file{eglot.el}
-(the name stands for ``Emacs polyGlot'') provides LSP support for
-various software development and maintenance features, such as
-@code{xref}, Imenu, ElDoc, etc.
-
-@item
-Emacs can now cope with files with very long lines much better.  It no
-longer hangs when displaying such long lines, and allows
-reasonably-responsive editing when such lines are present in the
-visible portion of a buffer.
-
-@item
-Emacs now supports the latest version 15.0 of the Unicode Standard.
-
-@item
-The new mode @code{pixel-scroll-precision-mode} allows precise and
-smooth scrolling of the display at pixel resolution, if your mouse
-supports this.
-
-@item
-Emacs now supports 24-bit true colors on more terminals.
-
-@item
-On capable X terminal emulators, Emacs now supports setting the X
-primary selection on TTY frames.
-
-@item
-New convenient commands are now available for inserting, searching,
-listing, and describing Emoji.  These commands are on the @w{@kbd{C-x
-8 e}} prefix key.  The commands @kbd{C-u C-x =}
-(@code{what-cursor-position}) and @kbd{M-x describe-char} now show the
-names of Emoji sequences at point.
-
-@item
-The Help commands were enhanced:
-
-@itemize @minus
-@item
-@kbd{M-x apropos-variable} shows the values of the matching variables.
-@item
-@kbd{C-h b} activates @code{outline-minor-mode} in the buffer, which
-makes it easier to browse long lists of key bindings.
-@item
-@kbd{I} in the @file{*Help*} buffer displays the corresponding
-documentation in the Emacs Lisp Reference manual.
-@item
-New command @code{help-quick} displays a buffer with overview of
-common Help commands.
-@end itemize
-
-@item
-Outline Minor mode uses buttons to hide and show outlines.
-
-@item
-Deleted frames can now be undeleted using @kbd{C-x 5 u}, if the
-optional @code{undelete-frame-mode} is enabled.
-
-@item
-You can now delete the entire composed sequence of characters with
-@key{Delete} and edits the composed sequence by turning on the
-@code{composition-break-at-point} option.
-
-@item
-Support is added for many old scripts and writing systems, such as Tai
-Tham, Brahmi, Tirhuta, Modi, Lepcha, and many others.
-
-@item
-New translations of the Emacs tutorial: Ukrainian and Greek.
-
-@item
-New major modes for Typescript, Csharp, CMake, Go, Rust, and Yaml.
-@end itemize
-
-
 @node New in Emacs 28
 @section What is different about Emacs 28?
 @cindex Differences between Emacs 27 and Emacs 28
@@ -3133,23 +3013,13 @@ example, you can put the following in your init file:
 
 To avoid the slightly distracting visual effect of Emacs starting with
 its default frame size and then growing to fullscreen, you can add an
-@samp{Emacs.Geometry} entry to the Windows Registry settings.  @xref{X
-Resources,,, emacs, The GNU Emacs Manual}.  To compute the correct
-values for width and height you use in the Registry settings, first
-maximize the Emacs frame and then evaluate @code{(frame-height)} and
+@samp{Emacs.Geometry} entry to the Windows registry settings.
+@xref{X Resources,,, emacs, The GNU Emacs Manual}.
+
+To compute the correct values for width and height, first maximize the
+Emacs frame and then evaluate @code{(frame-height)} and
 @code{(frame-width)} with @kbd{M-:}.
 
-Alternatively, you can avoid the visual effect of Emacs changing its
-frame size entirely in your init file (i.e., without using the
-Registry), like this:
-
-@lisp
-(setq frame-resize-pixelwise t)
-(set-frame-position nil 0 0)
-(set-frame-size nil (display-pixel-width) (display-pixel-height) t)
-@end lisp
-
-
 @node Emacs in a Linux console
 @section How can I alleviate the limitations of the Linux console?
 @cindex Console, Linux console, TTY, fbterm

doc/misc/eglot.texi

@@ -98,7 +98,6 @@ This manual documents how to configure, use, and customize Eglot.
 * Eglot and LSP Servers::       How to work with language servers.
 * Using Eglot::                 Important Eglot commands and variables.
 * Customizing Eglot::           Eglot customization and advanced features.
-* Advanced server configuration::  Fine-tune a specific language server
 * Troubleshooting Eglot::       Troubleshooting and reporting bugs.
 * GNU Free Documentation License::  The license for this manual.
 * Index::
@@ -154,11 +153,11 @@ Use Eglot.
 
 Most Eglot facilities are integrated into Emacs features, such as
 ElDoc, Flymake, Xref, and Imenu.  However, Eglot also provides
-commands of its own, mainly to perform tasks by the language server,
-such as @kbd{M-x eglot-rename} (to rename an identifier across the
-entire project), @kbd{M-x eglot-format} (to reformat and reindent
-code), and some others.  @xref{Eglot Commands}, for the detailed list
-of Eglot commands.
+commands of its own, mainly to perform tasks by the LSP server, such
+as @kbd{M-x eglot-rename} (to rename an identifier across the entire
+project), @kbd{M-x eglot-format} (to reformat and reindent code), and
+some others.  @xref{Eglot Commands}, for the detailed list of Eglot
+commands.
 
 @item
 That's it!
@@ -227,10 +226,11 @@ This says to invoke @var{program} with zero or more arguments
 standard input and standard output streams.
 
 @item (@var{program} @var{args}@dots{} :initializationOptions @var{options}@dots{})
-@var{program} is invoked with @var{args} but @var{options} specifies
-how to construct the @samp{:initializationOptions} JSON object to pass
-the server on during the LSP handshake (@pxref{Advanced server
-configuration}).
+Like above, but with @var{options} specifying the options to be
+used for constructing the @samp{initializationOptions} JSON object for
+the server.  @var{options} can also be a function of one argument, in
+which case it will be called with the server instance as the argument,
+and should return the JSON object to use for initialization.
 
 @item (@var{host} @var{port} @var{args}@dots{})
 Here @var{host} is a string and @var{port} is a positive integer
@@ -465,10 +465,43 @@ ElDoc look nicer on display.
 
 @item
 In addition to enabling and enhancing other features and packages,
-Eglot also provides a number of user commands based on the
-capabilities of language servers.  Examples include renaming symbols
-with @kbd{eglot-rename} and asking to automatically correct problems
-with @kbd{eglot-code-actions}.  @xref{Eglot Commands}.
+Eglot also provides a small number of user commands based directly on
+the capabilities of language servers.  These commands are:
+
+@table @kbd
+@item M-x eglot-rename
+This prompts for a new name for the symbol at point, and then modifies
+all the project source files to rename the symbol to the new name,
+based on editing data received from the language-server.  @xref{Eglot
+and Buffers}, for the details of how project files are defined.
+
+@item M-x eglot-format
+This reformats and prettifies the current active region according to
+source formatting rules of the language-server.  If the region is not
+active, it reformats the entire buffer instead.
+
+@item M-x eglot-format-buffer
+This reformats and prettifies the current buffer according to source
+formatting rules of the language-server.
+
+@cindex code actions
+@item M-x eglot-code-actions
+@itemx M-x eglot-code-action-organize-imports
+@itemx M-x eglot-code-action-quickfix
+@itemx M-x eglot-code-action-extract
+@itemx M-x eglot-code-action-inline
+@itemx M-x eglot-code-action-rewrite
+These command allow you to invoke the so-called @dfn{code actions}:
+requests for the language-server to provide editing commands for
+various code fixes, typically either to fix an error diagnostic or to
+beautify/refactor code.  For example,
+@code{eglot-code-action-organize-imports} rearranges the program
+@dfn{imports}---declarations of modules whose capabilities the program
+uses.  These commands affect all the files that belong to the
+project.  The command @kbd{M-x eglot-code-actions} will pop up a menu
+of code applicable actions at point.
+@end table
+
 @end itemize
 
 Not all servers support the full set of LSP capabilities, but most of
@@ -671,44 +704,20 @@ entire current buffer.
 This command reformats the current buffer, in the same manner as
 @code{eglot-format} does.
 
-@cindex code actions
 @item M-x eglot-code-actions
-@itemx M-x eglot-code-action-organize-imports
+@itemx mouse-1
+This command asks the server for any @dfn{code actions} applicable at
+point.  It can also be invoked by @kbd{mouse-1} clicking on
+diagnostics provided by the server.
+
+@item M-x eglot-code-action-organize-imports
 @itemx M-x eglot-code-action-quickfix
 @itemx M-x eglot-code-action-extract
 @itemx M-x eglot-code-action-inline
 @itemx M-x eglot-code-action-rewrite
-These commands allow you to invoke the so-called @dfn{code actions}:
-requests for the language server to provide editing commands for
-correcting, refactoring or beautifying your code.  These commands may
-affect more than one visited file belong to the project.
-
-The command @code{eglot-code-actions} asks the server if there any
-code actions for any point in the buffer or contained in the active
-region.  If there are, you the choice to execute one of them via the
-minibuffer.
-
-A common use of code actions is fixing the Flymake error diagnostics
-issued by Eglot (@pxref{Top,,, flymake, GNU Flymake manual}).
-Clicking on a diagnostic with @kbd{mouse-2} invokes
-@code{eglot-code-actions-at-mouse} which pops up a menu of available
-code actions.  The variable @code{eglot-diagnostics-map} can be used
-to control the mouse binding.
-
-Other commands execute a specific code action.  For example,
-@code{eglot-code-action-organize-imports} rearranges the program's
-@dfn{imports}---declarations of modules whose capabilities the program
-uses.
-
-@cindex inlay hints
-@item M-x eglot-inlay-hints-mode
-This command toggles LSP @dfn{inlay hints} on and off for the current
-buffer.  Inlay hints are small text annotations to specific parts of
-the whole buffer, not unlike diagnostics, but designed to help
-readability instead of indicating problems.  For example, a C++
-language server can serve hints about positional parameter names in
-function calls and a variable's automatically deduced type.  Inlay
-hints help the user not have to remember these things by heart.
+These commands invoke specific code actions supported by the language
+server.
+@c FIXME: Need more detailed description of each action.
 @end ftable
 
 The following Eglot commands are used less commonly, mostly for
@@ -950,132 +959,85 @@ mechanism.
 @cindex progress
 @item eglot-report-progress
 Set this variable to true if you'd like progress notifications coming
-from the language server to be handled as Emacs's progress reporting
+from the LSP server to be handled as Emacs's progress reporting
 facilities.
+
+@vindex eglot-workspace-configuration
+@cindex server workspace configuration
+@item eglot-workspace-configuration
+This variable is meant to be set in the @file{.dir-locals.el} file, to
+provide per-project settings, as described below in more detail.
 @end table
 
-@node Advanced server configuration
-@chapter Advanced server configuration
+Some language servers need to know project-specific settings, which
+the LSP calls @dfn{workspace configuration}.  Eglot allows such fine
+tuning of per-project settings via the variable
+@code{eglot-workspace-configuration}.  Eglot sends the settings in
+this variable to each server, and each server applies the portion of the
+settings relevant to it and ignores the rest.  These settings are
+communicated to the server initially (upon establishing the
+connection) or when the settings are changed, or in response to a
+configuration request from the server.
 
-Though many language servers work well out-of-the-box, most allow
-fine-grained control of their operation via specific configuration
-options that are transmitted over the LSP protocol and vary from
-server to server.  A small number of servers require such special
-configuration to work acceptably, or even to work at all.
+In many cases, servers can be configured globally using a
+configuration file in the user's home directory or in the project
+directory, which the language server reads.  For example, the
+@command{pylsp} server for Python reads the file
+@file{~/.config/pycodestyle} and the @command{clangd} server reads the
+file @file{.clangd} anywhere in the current project's directory tree.
+If possible, we recommend using those configuration files that are
+independent of Eglot and Emacs; they have the advantage that they will
+work with other LSP clients as well.
 
-After having setup a server executable program in
-@code{eglot-server-programs} (@pxref{Setting Up LSP Servers}) and
-ensuring Eglot can invoke it, you may want to take advantage of some
-of these options.  You should first distinguish two main kinds of
-server configuration:
-
-@itemize @bullet
-@item
-Project-specific, applying to a specific project;
-
-@item
-User-specific, applying to all projects the server is used for.
-@end itemize
-
-When you have decided which kind you need, the following sections
-teach how Eglot's user variables can be used to achieve it:
-
-@menu
-* Project-specific configuration::
-* User-specific configuration::
-* JSONRPC objects in Elisp::
-@end menu
-
-It's important to note that not all servers allow both kinds of
-configuration, nor is it guaranteed that user options can be copied
-over to project options, and vice-versa.  When in doubt, consult your
-language server's documentation.
-
-It's also worth noting that some language servers can read these
-settings from configuration files in the user's @code{HOME} directory
-or in a project's directory.  For example, the @command{pylsp} Python
-server reads the file @file{~/.config/pycodestyle} for user
-configuration.  The @command{clangd} C/C++ server reads both
-@file{~/.config/clangd/config.yaml} for user configuration and
-@file{.clangd} for project configuration.  It may be advantageous to
-use these mechanisms instead of Eglot's, as this will probably work
-with other LSP clients and may be easier to debug than options riding
-on the LSP wire.
-
-@node Project-specific configuration
-@section Project-specific configuration
-@vindex eglot-workspace-configuration
-@cindex workspace configuration
-
-To set project-specific settings, which the LSP specification calls
-@dfn{workspace configuration}, the variable
-@code{eglot-workspace-configuration} may be used.
-
-This variable is a directory-local variable (@pxref{Directory
-Variables, , Per-directory Local Variables, emacs, The GNU Emacs
-Manual}).  It's important to recognize that this variable really only
-makes sense when set directory-locally.  It usually does not make
-sense to set it file-locally or in a major-mode hook.
-
-The most common way to set @code{eglot-workspace-configuration } is
-using a @file{.dir-locals.el} file in the root of your project.  If
-you can't do that, you may also set it from Elisp code via the
-@code{dir-locals-set-class-variables} function.  (@pxref{Directory
-Local Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
-
-However you choose to set it, the variable's value is a plist
-(@pxref{Property Lists,,, elisp, GNU Emacs Lisp Reference Manual}) with
-the following format:
+If you do need to provide Emacs-specific configuration for a language
+server, we recommend defining the appropriate value in the
+@file{.dir-locals.el} file in the project's directory.  The value of
+this variable should be a property list of the following format:
 
 @lisp
- (@var{:server1} @var{plist1} @var{:server2} @var{plist2} @dots{})
+ (:@var{server} @var{plist}@dots{})
 @end lisp
 
 @noindent
-Here, @var{:server1} and @var{:server2} are keywords whose names
-identify the LSP language servers to target.  Consult server
-documentation to find out what name to use.  @var{plist1} and
-@var{plist2} are plists of options, possibly nesting other plists.
+Here @code{:@var{server}} identifies a particular language server and
+@var{plist} is the corresponding keyword-value property list of one or
+more parameter settings for that server, serialized by Eglot as a JSON
+object.  @var{plist} may be arbitrarily complex, generally containing
+other keyword-value property sublists corresponding to JSON subobjects.
+The JSON values @code{true}, @code{false}, @code{null} and @code{@{@}}
+are represented by the Lisp values @code{t}, @code{:json-false},
+@code{nil}, and @code{eglot-@{@}}, respectively.
 
 @findex eglot-show-workspace-configuration
 When experimenting with workspace settings, you can use the command
 @kbd{M-x eglot-show-workspace-configuration} to inspect and debug the
-value of this variable in its final JSON form, ready to be sent to the
-server (@pxref{JSONRPC objects in Elisp}).  This helper command works
-even before actually connecting to the server.
+JSON value to be sent to the server.  This helper command works even
+before actually connecting to the server.
 
-These variable's value doesn't take effect immediately.  That happens
-upon establishing the connection, in response to an explicit query
-from the server, or when issuing the command @kbd{M-x
-eglot-signal-didChangeConfiguration} which notifies the server during
-an ongoing Eglot session.
+Here's an example of defining the workspace-configuration settings for
+a project that uses two different language servers, one for Python,
+the other one for Go (presumably, the project is written in a
+combination of these two languages).  The server for Python in this
+case is @command{pylsp}, the server for Go is @command{gopls}.  The
+value of @code{eglot-workspace-configuration} in this case should be:
 
-@subsection Examples
+@lisp
+((python-mode
+  . ((eglot-workspace-configuration
+      . (:pylsp (:plugins (:jedi_completion (:include_params t
+                                             :fuzzy t)
+                           :pylint (:enabled :json-false)))))))
+ (go-mode
+  . ((eglot-workspace-configuration
+      . (:gopls (:usePlaceholders t))))))
+@end lisp
 
-For some users, setting @code{eglot-workspace-configuration} is a
-somewhat daunting task.  One of the reasons is having to manage the
-general Elisp syntax of per-mode directory-local variables, which uses
-alists (@pxref{Association Lists,,, elisp, GNU Emacs Lisp Reference
-Manual}), and the specific syntax of Eglot's variable, which uses
-plists.  Some examples are useful.
+@noindent
+This should go into the @file{.dir-locals.el} file in the project's
+root directory.  It sets up the value of
+@code{eglot-workspace-configuration} separately for each major mode.
 
-Let's say you want to configure two language servers to be used in a
-project written in a combination of the Python and Go languages.  You
-want to use the @command{pylsp} and @command{gopls} languages
-servers.  In the documentation of the servers in question (or in some
-other editor's configuration file, or in some blog article), you find
-the following configuration options in informal dotted-notation
-syntax:
-
-@example
-pylsp.plugins.jedi_completion.include_params: true
-pylsp.plugins.jedi_completion.fuzzy: true
-pylsp.pylint.enabled: false
-gopls.usePlaceholders: true
-@end example
-
-To apply this to Eglot, and assuming you chose the
-@file{.dir-locals.el} file method, the contents of that file could be:
+Alternatively, the same configuration could be defined as follows:
 
 @lisp
 ((nil
@@ -1083,335 +1045,117 @@ To apply this to Eglot, and assuming you chose the
       . (:pylsp (:plugins (:jedi_completion (:include_params t
                                              :fuzzy t)
                            :pylint (:enabled :json-false)))
-         :gopls (:usePlaceholders t)))))
- (python-mode . ((indent-tabs-mode . nil)))
- (go-mode     . ((indent-tabs-mode . t))))
+         :gopls (:usePlaceholders t))))))
 @end lisp
 
-@noindent
-This sets the value of @code{eglot-workspace-configuration} in all the
-buffers inside the project; each server will use only the section of
-the parameters intended for that server, and ignore the rest.  Note
-how alists are used for associating Emacs mode names with alists
-associating variable names with variable values.  Then notice how
-plists are used inside the value of
-@code{eglot-workspace-configuration}.
+This is an equivalent setup which sets the value for all the
+major-modes inside the project; each server will use only the section
+of the parameters intended for that server, and ignore the rest.
 
-This following form may also be used:
-
-@lisp
-((python-mode
-  . ((eglot-workspace-configuration
-      . (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))))
-     (indent-tabs-mode . nil)))
- (go-mode
-  . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders t)))
-     (indent-tabs-mode . t))))
-@end lisp
-
-@noindent
-This sets up the value of @code{eglot-workspace-configuration}
-separately depending on the major mode of each of that project's
-buffers.  @code{python-mode} buffers will have the variable set to
-@code{(:pylsp (:plugins ...))}.  @code{go-mode} buffers will have the
-variable set to @code{(:gopls (:usePlaceholders t))}.
-
-Some servers will issue workspace configuration for specific files
-inside your project.  For example, if you know @code{gopls} is asking
-about specific files in the @code{src/imported} subdirectory and you
-want to set a different option for @code{gopls.usePlaceholders} , you
-may use something like:
-
-@lisp
-((python-mode
-  . ((eglot-workspace-configuration
-      . (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))))
-     (indent-tabs-mode nil)))
- (go-mode
-  . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders t)))
-     (indent-tabs-mode t)))
- ("src/imported"
-   . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders nil))))))
-@end lisp
+As yet another alternative, you can set the value of
+@code{eglot-workspace-configuration} programmatically, via the
+@code{dir-locals-set-class-variables} function, @pxref{Directory Local
+Variables,,, elisp, GNU Emacs Lisp Reference Manual}.
 
 Finally, if one needs to determine the workspace configuration based
 on some dynamic context, @code{eglot-workspace-configuration} can be
 set to a function.  The function is called with the
 @code{eglot-lsp-server} instance of the connected server (if any) and
 with @code{default-directory} set to the root of the project.  The
-function should return a plist suitable for use as the variable's
-value.
+function should return a value of the form described above.
 
-@node User-specific configuration
-@section User-specific configuration
-@cindex initializationOptions
-@cindex command-line arguments
+Some servers need special hand-holding to operate correctly.  If your
+server has some quirks or non-conformity, it's possible to extend
+Eglot via Elisp to adapt to it, by defining a suitable
+@code{eglot-initialization-options} method via @code{cl-defmethod}
+(@pxref{Generic Functions,,, elisp, GNU Emacs Lisp Reference Manual}).
 
-This kind of configuration applies to all projects the server is used
-for.  Here, there are a number of ways to do this inside Eglot.
-
-A common way is to pass command-line options to the server invocation
-via @code{eglot-server-programs}.  Let's say we want to configure
-where the @command{clangd} server reads its
-@code{compile_commands.json} from.  This can be done like so:
+Here's an example:
 
 @lisp
-(with-eval-after-load 'eglot
-  (add-to-list 'eglot-server-programs
-               `(c++-mode . ("clangd" "--compile-commands-dir=/tmp"))))
+(require 'eglot)
 
+(add-to-list 'eglot-server-programs
+             '((c++-mode c-mode) . (eglot-cquery "cquery")))
+
+(defclass eglot-cquery (eglot-lsp-server) ()
+  :documentation "A custom class for cquery's C/C++ langserver.")
+
+(cl-defmethod eglot-initialization-options ((server eglot-cquery))
+  "Passes through required cquery initialization options"
+  (let* ((root (car (project-roots (eglot--project server))))
+         (cache (expand-file-name ".cquery_cached_index/" root)))
+    (list :cacheDirectory (file-name-as-directory cache)
+          :progressReportFrequencyMs -1)))
 @end lisp
 
 @noindent
-Another way is to have Eglot pass a JSON object to the server during
-the LSP handshake.  This is done using the
-@code{:initializationOptions} syntax of @code{eglot-server-programs}:
-
-@lisp
-(with-eval-after-load 'eglot
-  (add-to-list 'eglot-server-programs
-               `(c++-mode . ("clangd" :initializationOptions
-                                      (:compilationDatabasePath "/tmp")))))
-@end lisp
-
-@noindent
-The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
-representation in plist format of a simple JSON object
-@code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @pxref{JSONRPC
-objects in Elisp}.
-
-In this case, the two examples achieve exactly the same, but notice
-how the option's name has changed between them.
-
-@vindex eglot-workspace-configuration
-Finally there is another way to do user-specific configuration of
-language servers, which may be used if the methods above are not
-supported.  It consists of @emph{globally} setting
-@code{eglot-workspace-configuration}, a variable originally intended
-for project-specific configuration.  This has the same effect as
-giving all your projects a certain default configuration, as described
-in @ref{Project-specific configuration}.  Here is an example:
-
-@lisp
-(setq-default eglot-workspace-configuration
-              '(:pylsp (:plugins (:jedi_completion (:include_params t
-                                                    :fuzzy t)
-                                  :pylint (:enabled :json-false)))
-                :gopls (:usePlaceholders t)))
-@end lisp
-
-Note that the global value of @code{eglot-workspace-configuration} is
-always overriden if a directory-local value is detected.
-
-@node JSONRPC objects in Elisp
-@section JSONRPC objects in Elisp
-
-Emacs's preferred way of representing JSON is via Lisp lists.  In
-Eglot, the syntax of this list is the simplest possible (the one with
-fewer parenthesis), a plist (@pxref{Property Lists,,, elisp, GNU Emacs
-Lisp Reference Manual}).
-
-The plist may be arbitrarily complex, and generally containing other
-keyword-value property sub-plists corresponding to JSON sub-objects.
-
-For representing the JSON leaf values @code{true}, @code{false},
-@code{null} and @code{@{@}}, you can use the Lisp values @code{t},
-@code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
-JSON arrays are represented as Elisp vectors surrounded by square brackets
-(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
-
-For example, the plist
-
-@lisp
-(:pylsp (:plugins (:jedi_completion (:include_params t
-                                     :fuzzy t
-                                     :cache_for ["pandas" "numpy"]
-                   :pylint (:enabled :json-false))))
- :gopls (:usePlaceholders t))
-@end lisp
-
-@noindent
-is serialized by Eglot to the following JSON text:
-
-@example
-@{
-  "pylsp": @{
-    "plugins": @{
-      "jedi_completion": @{
-        "include_params": true,
-        "fuzzy": true,
-        "cache_for": [ "pandas", "numpy" ],
-      @},
-      "pylint": @{
-        "enabled": false
-      @}
-    @}
-  @},
-  "gopls": @{
-    "usePlaceholders":true
-  @},
-@}
-@end example
+See the doc string of @code{eglot-initialization-options} for more
+details.
+@c FIXME: The doc string of eglot-initialization-options should be
+@c enhanced and extended.
 
 @node Troubleshooting Eglot
 @chapter Troubleshooting Eglot
 @cindex troubleshooting Eglot
 
-This chapter documents commands and variables that can be used to
+This section documents commands and variables that can be used to
 troubleshoot Eglot problems.  It also provides guidelines for
 reporting Eglot bugs in a way that facilitates their resolution.
 
 When you encounter problems with Eglot, try first using the commands
-@kbd{M-x eglot-events-buffer} and @kbd{M-x eglot-stderr-buffer}.  They
+@kbd{M-x eglot-events-server} and @kbd{M-x eglot-stderr-buffer}.  They
 pop up special buffers that can be used to inspect the communications
 between the Eglot and language server.  In many cases, this will
 indicate the problems or at least provide a hint.
 
-@menu
-* Performance::
-* Getting the latest version::
-* Reporting bugs::
-@end menu
-
-@node Performance
-@section Performance
-@cindex performance problems, with Eglot
 A common and easy-to-fix cause of performance problems is the length
-of the Eglot events buffer because it represent additional work that
-Eglot must do.  After verifying Eglot is operating correctly but
-slowly, try to customize the variable @code{eglot-events-buffer-size}
-(@pxref{Eglot Variables}) to 0.  This will disable any debug logging
-and may speed things up.
+of these two buffers.  If Eglot is operating correctly but slowly,
+customize the variable @code{eglot-events-buffer-size} (@pxref{Eglot
+Variables}) to limit logging, and thus speed things up.
 
-In other situations, the cause of poor performance lies in the
-language server itself.  Servers use aggressive caching and other
-techniques to improve their performance.  Often, this can be tweaked
-by changing the server configuration (@pxref{Advanced server
-configuration}).
-
-@node Getting the latest version
-@section Getting the latest version
-@cindex upgrading Eglot
-
-To install the latest Eglot in an Emacs version that does not bundle
-Eglot, use @kbd{M-x package-install}.
-
-Often, a newer Eglot version exists that has fixed a longstanding bug,
-has more LSP features, or just better supports a particular language
-server.  Recent Eglot versions can self-update via the command
-@kbd{M-x eglot-upgrade-eglot}.  This will replace any currently
-installed version with the newest one available from the ELPA archives
-configured in @code{package-archives}.
-
-You can also update Eglot through other methods, such as
-@code{use-package} (@pxref{Installing packages,,, use-package,
-use-package User Manual}), @code{package-install},
-@code{list-packages} or the newer @code{package-upgrade}
-(@pxref{Packages,,, emacs, GNU Emacs Manual}).  However, do read the
-docstrings of the command you intend to use before you use it, as some
-of them may not work in exactly the same way across Emacs versions,
-meaning your configuration may be not portable.
-
-@node Reporting bugs
-@section Reporting bugs
-@cindex bug reports
-
-If you think you have found a bug, we want to hear about it.  Before
-reporting a bug, keep in mind that interaction with language servers
-represents a large quantity of unknown variables.  Therefore, it is
-generally both @emph{difficult} and @emph{absolutely essential} that
-the maintainers reproduce bugs exactly as they happened to you, the
-user.
-
-To report an Eglot bug, send e-mail to @email{bug-gnu-emacs@@gnu.org}.
-
-To understand how to write this email, get acquainted with Emacs's bug
-reporting guidelines (@pxref{Bugs,,, emacs, GNU Emacs Manual}).  Then,
-follow this Eglot-specific checklist:
+If you need to report an Eglot bug, please keep in mind that, because
+there are so many variables involved, it is generally both very
+@emph{difficult} and @emph{absolutely essential} to reproduce bugs
+exactly as they happened to you, the user.  Therefore, every bug
+report should include:
 
 @enumerate
 @item
-Include the transcript of JSONRPC events obtained from the buffer
-popped up by @kbd{M-x eglot-events-buffer}.  You may narrow down the
-transcript if you are sure of where the problematic exchange is, but
-it's safer to include the whole transcript, either attached or inline.
+The transcript of events obtained from the buffer popped up by
+@kbd{M-x eglot-events-buffer}.  If the transcript can be narrowed down
+to show the problematic exchange, so much the better.  This is
+invaluable for the investigation and reproduction of the problem.
 
 @item
 If Emacs signaled an error (an error message was seen or heard), make
-sure to repeat the process after turning on @code{debug-on-error} via
-@kbd{M-x toggle-debug-on-error}.  This normally produces a backtrace
-of the error that should also be attached to the bug report.
+sure to repeat the process after toggling @code{debug-on-error} on
+(via @kbd{M-x toggle-debug-on-error}).  This normally produces a
+backtrace of the error that should also be attached to the bug report.
 
 @item
-Include a description of how the maintainer should obtain, install,
-and configure the language server you used.  Maintainers usually have
-access to GNU/Linux systems, though not necessarily the distribution
-that you may be using.  If possible, try to replicate the problem with
-the C/C@t{++} or Python servers, as these are very easy to install.
+An explanation of how to obtain, install, and configure the language
+server you used.  If possible, try to replicate the problem with the
+C/C@t{++} or Python servers, as these are very easy to install.
 
 @item
-Describe how to setup a @emph{minimal} project directory where Eglot
-should be started for the problem to happen.  Describe each file's
-name and its contents.  Alternatively, you can supply the address of a
-public Git repository.
+A description of how to setup the @emph{minimal} project (one or two
+files and their contents) where the problem happens.
 
 @item
-Include versions of the software used.  The Emacs version can be
-obtained with @kbd{M-x emacs-version}.
-
-We welcome bug reports about all Eglot versions, but it is helpful to
-first check if the problem isn't already fixed in the latest version
-(@pxref{Getting the latest version}).
-
-It's also essential to include the version of ELPA packages that are
-explicitly or implicitly loaded.  The optional but popular Company or
-Markdown packages are distributed as GNU ELPA packages, not to mention
-Eglot itself in some situations.  Some major modes (Go, Rust, etc.)
-are provided by ELPA packages.  It's sometimes easy to miss these,
-since they are usually implicitly loaded when visiting a file in that
-language.
-
-ELPA packages usually live in @code{~/.emacs.d/elpa} (or what is in
-@code{package-user-dir}).  Including a listing of files in that
-directory is a way to tell the maintainers about ELPA package
-versions.
+A recipe to replicate the problem with @emph{a clean Emacs run}.  This
+means @kbd{emacs -Q} invocation or a very minimal (no more that 10
+lines) @file{.emacs} initialization file.  @code{eglot-ensure} and
+@code{use-package} calls are generally @emph{not} needed.
 
 @item
-Include a recipe to replicate the problem with @emph{a clean Emacs
-run}.  The invocation @code{emacs -Q -f package-initialize} starts
-Emacs with no configuration and initializes the ELPA packages.  A very
-minimal @file{.emacs} initialization file (10 lines or less) is also
-acceptable and good means to describe changes to variables.
-
-There is usually no need to include @code{require} statements in the
-recipe, as Eglot's functionality uses autoloads.
-
-Likewise, there is rarely the need to use things like
-@code{use-package} or @code{eglot-ensure}.  This just makes the recipe
-harder to follow.  Prefer setting variables with @code{setq} and
-adding to hooks with @code{add-hook}.  Prefer starting Eglot with
-@code{M-x eglot}.
-
-@item
-Make sure to double check all the above elements and re-run the recipe
-to see that the problem is reproducible.  Following the recipe should
-produce event transcript and error backtraces that are very similar to
-the ones you included.  If the problem only happens sometimes, mention
-this in your report.
+Make sure to double check all the above elements and re-run the
+recipe to see that the problem is reproducible.
 @end enumerate
 
 Please keep in mind that some problems reported against Eglot may
 actually be bugs in the language server or the Emacs feature/package
-that used Eglot to communicate with the language server.  Eglot is, in
-many cases, just a frontend to that functionality.
+that used Eglot to communicate with the language server.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License

doc/misc/erc.texi

@@ -2,7 +2,7 @@
 @c %**start of header
 @setfilename ../../info/erc.info
 @settitle ERC Manual
-@set ERCVER 5.5
+@set ERCVER 5.4.1
 @set ERCDIST as distributed with Emacs @value{EMACSVER}
 @include docstyle.texi
 @syncodeindex fn cp
@@ -90,8 +90,7 @@ Advanced Usage
 @chapter Introduction
 
 ERC is a powerful, modular, and extensible IRC client for Emacs.
-It has been included in Emacs since 2006 (@pxref{History}) and is also
-available on GNU ELPA.
+It is distributed with Emacs since version 22.1.
 
 IRC is short for Internet Relay Chat.  When using IRC, you can
 communicate with other users on the same IRC network.  There are many
@@ -540,55 +539,36 @@ so demands special precautions to avoid degrading the user experience.
 At present, the only such module is @code{networks}, whose library ERC
 always loads anyway.
 
-@anchor{Local Modules}
 @subheading Local Modules
 @cindex local modules
 
 All modules operate as minor modes under the hood, and some newer ones
 may be defined as buffer-local.  These so-called ``local modules'' are
 a work in progress and their behavior and interface are subject to
-change.  As of ERC 5.5, the only practical differences are as follows:
+change.  As of ERC 5.5, the only practical differences are
 
 @enumerate
 @item
-``Control variables,'' like @code{erc-sasl-mode}, retain their values
-across IRC sessions and override @code{erc-module} membership when
-influencing module activation.
+``Control variables,'' like @code{erc-sasl-mode}, are stateful across
+IRC sessions and override @code{erc-module} membership when influencing
+module activation in new sessions.
 @item
 Removing a local module from @code{erc-modules} via Customize not only
 disables its mode but also kills its control variable in all ERC
 buffers.
 @item
-``Mode toggles,'' like @code{erc-sasl-mode} and the complementary
-@code{erc-sasl-enable}/@code{erc-sasl-disable} pairing, behave
-differently than their global counterparts.
+``Mode toggles,'' like @code{erc-sasl-mode} and
+@code{erc-sasl-enable}, behave differently relative to each other and
+to their global counterparts.  (More on this just below.)
 @end enumerate
 
-In target buffers, a local module's activation state survives
-``reassociation'' by default, but modules themselves always have the
-final say.  For example, a module may reset all instances of itself in
-its network context upon reconnecting.  Moreover, the value of a mode
-variable may be meaningless in buffers that its module has no interest
-in.  For example, the value of @code{erc-sasl-mode} doesn't matter in
-target buffers and may even remain non-@code{nil} after SASL has been
-disabled for the current connection (and vice versa).
-
-When it comes to server buffers, a module's activation state only
-persists for sessions revived via the automatic reconnection mechanism
-or a manual @samp{/reconnect} issued at the prompt.  In other words,
-this doesn't apply to sessions revived by an entry-point command, such
-as @code{erc-tls}, because such commands always ensure a clean slate
-by looking only to @code{erc-modules}.  Although a session revived in
-this manner may indeed harvest other information from a previous
-server buffer, it simply doesn't care which modules might have been
-active during that connection.
-
-Lastly, a local mode's toggle command, like @code{erc-sasl-mode}, only
-affects the current buffer, but its ``non-mode'' cousins, like
-@code{erc-sasl-enable} and @code{erc-sasl-disable}, operate on all
-buffers belonging to their connection (when called interactively).
-And unlike global toggles, none of these ever mutates
-@code{erc-modules}.
+By default, all local-mode toggles, like @code{erc-sasl-mode}, only
+affect the current buffer, but their ``non-mode'' variants, such as
+@code{erc-sasl-enable}, operate on all buffers belonging to a
+connection when called interactively.  Keep in mind that whether
+enabled or not, a module may effectively be ``inert'' in certain types
+of buffers, such as queries and channels.  Whatever the case, a local
+toggle never mutates @code{erc-modules}.
 
 
 @c PRE5_4: Document every option of every module in its own subnode
@@ -952,7 +932,7 @@ Here, ``password'' refers to your account password, which is usually
 your @samp{NickServ} password.  To make this work, customize
 @code{erc-sasl-user} and @code{erc-sasl-password} or specify the
 @code{:user} and @code{:password} keyword arguments when invoking
-@code{erc-tls}.
+@code{erc-tls}.  Note that @code{:user} cannot be given interactively.
 
 @item @code{external} (via Client TLS Certificate)
 This works in conjunction with the @code{:client-certificate} keyword
@@ -1464,7 +1444,6 @@ or if you have bugs to report, there are several places you can go.
 @item
 @uref{https://www.emacswiki.org/emacs/ERC} is the
 emacswiki.org page for ERC@.  Anyone may add tips, hints, etc.@: to it.
-If you do so, please help keep it up to date.
 
 @item
 You can ask questions about using ERC on the Emacs mailing list,
@@ -1473,33 +1452,7 @@ You can ask questions about using ERC on the Emacs mailing list,
 @item
 You can visit the IRC Libera.Chat channel @samp{#emacs}.  Many of the
 contributors are frequently around and willing to answer your
-questions.  You can also try the relatively quiet @samp{#erc}, on the
-same network, for more involved questions.
-
-@item
-@anchor{Upgrading}
-You can check GNU ELPA between Emacs releases to see if a newer
-version is available that might contain a fix for your issue:
-@uref{https://elpa.gnu.org/packages/erc.html}.
-
-To upgrade, run @kbd{M-x list-packages @key{RET}}.  In the
-@file{*Packages*} (@code{package-menu-mode}) buffer, click the
-@samp{erc} package link for the desired version.  If unsure, or if the
-version column is too narrow to tell, try the bottom-most candidate.
-In the resulting @code{help-mode} buffer, confirm the version and
-click @samp{Install}.  Make sure to restart Emacs before reconnecting
-to IRC, and don't forget that you can roll back to the previous
-version by running @kbd{M-x package-delete @key{RET}}.
-@xref{Packages,,,emacs, the Emacs manual} for more information.
-
-In the rare instance you need an emergency fix or have volunteered to
-test an edge feature between ERC releases, you can try adding
-@samp{("devel" . "https://elpa.gnu.org/devel/")} to
-@code{package-archives} prior to performing the steps above.  For
-this, you'll want to instead select a ``snapshot'' version from the
-menu.  Please be aware that when going this route, the latest changes
-may not yet be available and you run the risk of incurring other bugs
-and encountering unstable features.
+questions.
 
 @item
 To report a bug in ERC, use @kbd{M-x erc-bug}.

doc/misc/eshell.texi

@@ -64,11 +64,10 @@ modify this GNU manual.''
 
 Eshell is a shell-like command interpreter implemented in Emacs Lisp.
 It invokes no external processes except for those requested by the
-user.  It is intended to be an alternative to the IELM (@pxref{Lisp
-Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor})
-REPL@footnote{Short for ``Read-Eval-Print Loop''.} for Emacs
-@emph{and} with an interface similar to command shells such as
-@command{bash}, @command{zsh}, @command{rc}, or @command{4dos}.
+user.  It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor})
+REPL for Emacs @emph{and} with an interface similar to command shells
+such as @command{bash}, @command{zsh}, @command{rc}, or
+@command{4dos}.
 @c This manual is updated to release 2.4 of Eshell.
 
 @insertcopying
@@ -194,13 +193,6 @@ In a command shell, everything is done by invoking commands.  This
 chapter covers command invocations in Eshell, including the command
 history and invoking commands in a script file.
 
-Unlike regular system shells, Eshell never invokes kernel functions
-directly, such as @code{exec(3)}.  Instead, it uses the Lisp functions
-available in the Emacs Lisp library.  It does this by transforming the
-input line into a callable Lisp form.@footnote{To see the Lisp form
-that will be invoked, type this as the Eshell prompt:
-@kbd{eshell-parse-command 'echo hello'}}
-
 @menu
 * Invocation::
 * Arguments::
@@ -215,16 +207,23 @@ that will be invoked, type this as the Eshell prompt:
 
 @node Invocation
 @section Invocation
-Eshell is both a command shell and an Emacs Lisp @acronym{REPL}.  As a
-result, you can invoke commands in two different ways: in @dfn{command
-form} or in @dfn{lisp form}.
+Unlike regular system shells, Eshell never invokes kernel functions
+directly, such as @code{exec(3)}.  Instead, it uses the Lisp functions
+available in the Emacs Lisp library.  It does this by transforming the
+input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
 
-You can use the semicolon (@code{;}) to separate multiple command
-invocations on a single line, executing each in turn.  You can also
-separate commands with @code{&&} or @code{||}. When using @code{&&},
-Eshell will execute the second command only if the first succeeds
-(i.e.@: has an exit status of 0); with @code{||}, Eshell will execute
-the second command only if the first fails.
+The command can be either an Elisp function or an external command.
+Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
+command, then a built-in (@pxref{Built-ins}) or a function with the
+same name; if there is no match, it then tries to execute it as an
+external command.
+
+The semicolon (@code{;}) can be used to separate multiple command
+invocations on a single line.  You can also separate commands with
+@code{&&} or @code{||}. When using @code{&&}, Eshell will execute the
+second command only if the first succeeds (i.e.@: has an exit
+status of 0); with @code{||}, Eshell will execute the second command
+only if the first fails.
 
 A command invocation followed by an ampersand (@code{&}) will be run
 in the background.  Eshell has no job control, so you can not suspend
@@ -233,80 +232,12 @@ the foreground.  That said, background processes invoked from Eshell
 can be controlled the same way as any other background process in
 Emacs.
 
-@subsection Command form
-Command form looks much the same as in other shells.  A command
-consists of arguments separated by spaces; the first argument is the
-command to run, with any subsequent arguments being passed to that
-command.
-
-@example
-~ $ echo hello
-hello
-@end example
-
-@cindex order of looking for commands
-@cindex command lookup order
-The command can be either an Elisp function or an external command.
-Eshell looks for the command in the following order:
-
-@enumerate
-@item
-As a command alias (@pxref{Aliases})
-
-@item
-As a built-in command (@pxref{Built-ins})
-
-@item
-As an external program
-
-@item
-As an ordinary Lisp function
-@end enumerate
-
-@vindex eshell-prefer-lisp-functions
-If you would prefer to use ordinary Lisp functions over external
-programs, set the option @code{eshell-prefer-lisp-functions} to
-@code{t}.  This will swap the lookup order of the last two items.
-
-You can also group command forms together into a subcommand with curly
-braces (@code{@{@}}).  This lets you use the output of a subcommand as
-an argument to another command, or within control flow statements
-(@pxref{Control Flow}).
-
-@example
-~ $ echo @{echo hello; echo there@}
-hellothere
-@end example
-
-@subsection Lisp form
-Lisp form looks like ordinary Emacs Lisp code, because that's what it
-is.  As a result, you can use any syntax normally available to an
-Emacs Lisp program (@pxref{Top, , , elisp, The Emacs Lisp Reference
-Manual}).
-
-@example
-~ $ (format "hello, %s" user-login-name)
-hello, user
-@end example
-
-In addition, you can @emph{combine} command forms and Lisp forms
-together into single statements, letting you use whatever form is the
-most convenient for expressing your intentions.
-
-@example
-~ $ ls *.patch > (format-time-string "%F.log")
-@end example
-
-This command writes a list of all files matching the glob pattern
-@code{*.patch} (@pxref{Globbing}) to a file named
-@code{@var{current-date}.log} (@pxref{Redirection}).
-
 @node Arguments
 @section Arguments
-Ordinarily, Eshell parses arguments in command form as either strings
+Ordinarily, command arguments are parsed by Eshell as either strings
 or numbers, depending on what the parser thinks they look like.  To
-specify an argument of some other data type, you can use a Lisp form
-(@pxref{Invocation}):
+specify an argument of some other data type, you can use an
+@ref{Dollars Expansion, Elisp expression}:
 
 @example
 ~ $ echo (list 1 2 3)
@@ -423,6 +354,10 @@ eshell/sudo is a compiled Lisp function in `em-tramp.el'.
 sudo is an alias, defined as "*sudo $@@*"
 @end example
 
+@vindex eshell-prefer-lisp-functions
+If you would prefer to use the built-in commands instead of the external
+commands, set @code{eshell-prefer-lisp-functions} to @code{t}.
+
 Some of the built-in commands have different behavior from their
 external counterparts, and some have no external counterpart.  Most of
 these will print a usage message when given the @code{--help} option.
@@ -602,8 +537,6 @@ disabled by default.
 @cmindex egrep
 @itemx fgrep
 @cmindex fgrep
-@itemx rgrep
-@cmindex rgrep
 @itemx glimpse
 @cmindex glimpse
 The @command{grep} commands are compatible with GNU @command{grep},
@@ -990,14 +923,15 @@ For example, you could handle a subset of the options for the
 @node Variables
 @section Variables
 @vindex eshell-prefer-lisp-variables
-Since Eshell is a combination of an Emacs @acronym{REPL} and a command
-shell, it can refer to variables from two different sources: ordinary
-Emacs Lisp variables, as well as environment variables.  By default,
-when using a variable in Eshell, it will first look in the list of
-built-in variables, then in the list of environment variables, and
-finally in the list of Lisp variables.  If you would prefer to use
-Lisp variables over environment variables, you can set
-@code{eshell-prefer-lisp-variables} to @code{t}.
+Since Eshell is a combination of an Emacs @acronym{REPL}@footnote{
+Short for ``Read-Eval-Print Loop''.
+} and a command shell, it can refer to variables from two different
+sources: ordinary Emacs Lisp variables, as well as environment
+variables.  By default, when using a variable in Eshell, it will first
+look in the list of built-in variables, then in the list of
+environment variables, and finally in the list of Lisp variables.  If
+you would prefer to use Lisp variables over environment variables, you
+can set @code{eshell-prefer-lisp-variables} to @code{t}.
 
 You can set variables in a few different ways.  To set a Lisp
 variable, you can use the command @samp{setq @var{name} @var{value}},
@@ -1049,21 +983,12 @@ whenever you change the current directory to a different host
 the value will automatically update to reflect the search path on that
 host.
 
-@vindex $UID
-@item $UID
-This returns the effective @acronym{UID} for the current user.  This
-variable is connection-aware, so when the current directory is remote,
-its value will be @acronym{UID} for the user associated with that
-remote connection.
-
 @vindex $_
 @item $_
 This refers to the last argument of the last command.  With a
 subscript, you can access any argument of the last command.  For
 example, @samp{$_[1]} refers to the second argument of the last
-command (excluding the command name itself).  To get all arguments of
-the last command, you can use an index range like @samp{$_[..]}
-(@pxref{Dollars Expansion}).
+command (excluding the command name itself).
 
 @vindex $$
 @item $$
@@ -1089,7 +1014,6 @@ that are currently visible in the Eshell window.  They are both
 copied to the environment, so external commands invoked from
 Eshell can consult them to do the right thing.
 
-@vindex $INSIDE_EMACS
 @item $INSIDE_EMACS
 This variable indicates to external commands that they are being
 invoked from within Emacs so they can adjust their behavior if
@@ -1374,24 +1298,11 @@ index.  The exact behavior depends on the type of @var{expr}'s value:
 @item a sequence
 Expands to the element at the (zero-based) index @var{i} of the
 sequence (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The
-Emacs Lisp Reference Manual}).  If @var{i} is negative, @var{i} counts
-from the end, so -1 refers to the last element of the sequence.
-
-If @var{i} is a range like @code{@var{start}..@var{end}}, this expands
-to a subsequence from the indices @var{start} to @var{end}, where
-@var{end} is excluded@footnote{This behavior is different from ranges
-in Bash (where both the start and end are included in the range), but
-matches the behavior of similar Emacs Lisp functions, like
-@code{substring} (@pxref{Creating Strings, , , elisp, The Emacs Lisp
-Reference Manual}).}.  @var{start} and/or @var{end} can also be
-omitted, which is equivalent to the start and/or end of the entire
-list.  For example, @samp{$@var{expr}[-2..]} expands to the last two
-values of @var{expr}.
+Emacs Lisp Reference Manual}).
 
 @item a string
 Split the string at whitespace, and then expand to the @var{i}th
-element of the resulting sequence.  As above, @var{i} can be a range
-like @code{@var{start}..@var{end}}.
+element of the resulting sequence.
 
 @item an alist
 If @var{i} is a non-numeric value, expand to the value associated with
@@ -2191,6 +2102,8 @@ Hitting space during a process invocation, such as @command{make}, will
 cause it to track the bottom of the output; but backspace no longer
 scrolls back.
 
+@item It's not possible to fully @code{unload-feature} Eshell
+
 @item Menu support was removed, but never put back
 
 @item If an interactive process is currently running, @kbd{M-!} doesn't work
@@ -2457,6 +2370,13 @@ current being used.
 
 This way, the user could change it to use rc syntax: @samp{>[2=1]}.
 
+@item Allow @samp{$_[-1]}, which would indicate the last element of the array
+
+@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
+
+Return them as a list, so that @samp{$_[*]} is all the arguments of the
+last command.
+
 @item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
 
 Make it possible for the user to send char-by-char to the underlying

doc/misc/eww.texi

@@ -92,10 +92,9 @@ searched via @code{eww-search-prefix}.  The default search engine is
 either prefix the file name with @code{file://} or use the command
 @kbd{M-x eww-open-file}.
 
-  If you invoke @code{eww} or @code{eww-open-file} with a prefix
-argument, as in @w{@kbd{C-u M-x eww}}, they will create a new EWW
-buffer instead of reusing the default one, which is normally called
-@file{*eww*}.
+  If you invoke @code{eww} with a prefix argument, as in @w{@kbd{C-u
+M-x eww}}, it will create a new EWW buffer instead of reusing the
+default one, which is normally called @file{*eww*}.
 
 @findex eww-quit
 @findex eww-reload