New structure for Eglot manual

.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

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.

README

@@ -2,7 +2,7 @@ Copyright (C) 2001-2023 Free Software Foundation, Inc.
 See the end of the file for license conditions.
 
 
-This directory tree holds version 30.0.50 of GNU Emacs, the extensible,
+This directory tree holds version 29.0.60 of GNU Emacs, the extensible,
 customizable, self-documenting real-time display editor.
 
 The file INSTALL in this directory says how to build and install GNU

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/admin.el

@@ -110,7 +110,7 @@ Root must be the root of an Emacs source tree."
 				(submatch (1+ (in "0-9."))))))
   (set-version-in-file root "configure.ac" version
 		       (rx (and "AC_INIT" (1+ (not (in ?,)))
-                                ?, (0+ space)
+                                ?, (0+ space) ?\[
                                 (submatch (1+ (in "0-9."))))))
   (set-version-in-file root "nt/README.W32" version
 		       (rx (and "version" (1+ space)
@@ -843,11 +843,8 @@ $Date: %s $
       (package-install pkg)
       (require pkg nil t))))
 
-(declare-function org-html-export-as-html "ox-html.el")
 (defvar org-html-postamble)
 (defvar org-html-mathjax-template)
-(defvar htmlize-output-type)
-
 (defun make-news-html-file (root version)
   "Convert the NEWS file into an HTML file."
   (interactive (let ((root

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/find-gc.el

@@ -100,7 +100,7 @@ Also store it in `find-gc-unsafe-list'."
 
 
 
-(defun trace-call-tree (&optional _ignored)
+(defun trace-call-tree (&optional ignored)
   (message "Setting up directories...")
   (setq find-gc-subrs-called nil)
   (let ((case-fold-search nil)

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 Jan 31 2023 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
@@ -1707,16 +1707,3 @@ $REAL_GIT bisect skip $(cat $0 | grep '^# SKIP-SINGLE ' | sed 's/^# SKIP-SINGLE
 # 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/gitmerge.el

@@ -293,7 +293,7 @@ should not be skipped."
   "Try to resolve conflicts in FILE with smerge.
 Returns non-nil if conflicts remain."
   (unless (file-exists-p file) (error "Gitmerge-resolve: Can't find %s" file))
-  (with-demoted-errors "Error: %S"
+  (with-demoted-errors
     (let ((exists (find-buffer-visiting file)))
       (with-current-buffer (let ((enable-local-variables :safe)
                                  (enable-local-eval nil))

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.
 
@@ -179,13 +169,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,30 +23,29 @@
 
 # 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
   crypto/md5 crypto/md5-buffer
   crypto/sha1-buffer crypto/sha256-buffer crypto/sha512-buffer
   d-type diffseq double-slash-root dtoastr dtotimespec dup2
-  environ execinfo faccessat
+  environ execinfo explicit_bzero faccessat
   fchmodat fcntl fcntl-h fdopendir file-has-acl
   filemode filename filevercmp flexmember fpieee
   free-posix fstatat fsusage fsync futimens
   getloadavg getopt-gnu getrandom gettime gettimeofday gitlog-to-changelog
   ieee754-h ignore-value intprops largefile libgmp lstat
-  manywarnings memmem-simple mempcpy memrchr memset_explicit
-  minmax mkostemp mktime
+  manywarnings memmem-simple mempcpy memrchr minmax mkostemp mktime
   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/git-workflow

@@ -16,14 +16,14 @@ Initial setup
 
 Then we want to clone the repository.  We normally want to have both
 the current master and (if there is one) the active release branch
-(eg emacs-29).
+(eg emacs-28).
 
 mkdir ~/emacs
 cd ~/emacs
 git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git master
 cd master
 git config push.default current
-git worktree add ../emacs-29 emacs-29
+git worktree add ../emacs-28 emacs-28
 
 You now have both branches conveniently accessible, and you can do
 "git pull" in them once in a while to keep updated.
@@ -67,10 +67,10 @@ which will look like
 
 commit 958b768a6534ae6e77a8547a56fc31b46b63710b
 
-cd ~/emacs/emacs-29
+cd ~/emacs/emacs-28
 git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
 
-and add "Backport:" to the commit string.  Then
+and optionally add "Backport:" to the commit string.  Then
 
 git push
 
@@ -109,7 +109,7 @@ up-to-date by doing a pull.  Then start Emacs with
   emacs -l admin/gitmerge.el -f gitmerge
 
 You'll be asked for the branch to merge, which will default to
-(eg) 'origin/emacs-29', which you should accept.  Merging a local tracking
+(eg) 'origin/emacs-28', which you should accept.  Merging a local tracking
 branch is discouraged, since it might not be up-to-date, or worse,
 contain commits from you which are not yet pushed upstream.
 

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

@@ -31,17 +31,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-parser-create 'html))
+(setq css (treesit-parser-create 'css))
+(setq js (treesit-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
+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
 
@@ -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.

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

@@ -4,7 +4,7 @@
 
 # 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

@@ -4,7 +4,7 @@
 
 # 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

@@ -23,7 +23,7 @@ dnl  along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 AC_PREREQ([2.65])
 dnl Note this is parsed by (at least) make-dist and lisp/cedet/ede/emacs.el.
-AC_INIT([GNU Emacs], [30.0.50], [bug-gnu-emacs@gnu.org], [],
+AC_INIT([GNU Emacs], [29.0.60], [bug-gnu-emacs@gnu.org], [],
   [https://www.gnu.org/software/emacs/])
 
 dnl Set emacs_config_options to the options of 'configure', quoted for the shell,
@@ -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])
@@ -1843,9 +1841,7 @@ AC_CHECK_HEADERS_ONCE(
   coff.h pty.h
   sys/resource.h
   sys/utsname.h pwd.h utmp.h util.h
-  sanitizer/lsan_interface.h
-  sanitizer/asan_interface.h
-  sanitizer/common_interface_defs.h])
+  sanitizer/lsan_interface.h])
 
 AC_CACHE_CHECK([for ADDR_NO_RANDOMIZE],
   [emacs_cv_personality_addr_no_randomize],
@@ -2034,29 +2030,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.
@@ -2689,6 +2693,39 @@ if test "${HAVE_X11}" = "yes"; then
     export LD_RUN_PATH
   fi
 
+  if test "${opsys}" = "gnu-linux"; then
+    AC_CACHE_CHECK([whether X on GNU/Linux needs -b to link], [emacs_cv_b_link],
+    [AC_LINK_IFELSE([AC_LANG_PROGRAM([[]],
+     [[XOpenDisplay ("foo");]])],
+     [xgnu_linux_first_failure=no],
+     [xgnu_linux_first_failure=yes])
+    if test "${xgnu_linux_first_failure}" = "yes"; then
+      OLD_CPPFLAGS="$CPPFLAGS"
+      OLD_LIBS="$LIBS"
+      CPPFLAGS="$CPPFLAGS -b i486-linuxaout"
+      LIBS="$LIBS -b i486-linuxaout"
+      AC_LINK_IFELSE([AC_LANG_PROGRAM([[]],
+       [[XOpenDisplay ("foo");]])],
+       [xgnu_linux_second_failure=no],
+       [xgnu_linux_second_failure=yes])
+      if test "${xgnu_linux_second_failure}" = "yes"; then
+	# If we get the same failure with -b, there is no use adding -b.
+	# So leave it out.  This plays safe.
+        emacs_cv_b_link=no
+      else
+        emacs_cv_b_link=yes
+      fi
+      CPPFLAGS=$OLD_CPPFLAGS
+      LIBS=$OLD_LIBS
+    else
+      emacs_cv_b_link=no
+    fi])
+    if test "x$emacs_cv_b_link" = xyes ; then
+      LD_SWITCH_X_SITE="$LD_SWITCH_X_SITE -b i486-linuxaout"
+      C_SWITCH_X_SITE="$C_SWITCH_X_SITE -b i486-linuxaout"
+    fi
+  fi
+
   # Reportedly, some broken Solaris systems have XKBlib.h but are missing
   # header files included from there.
   AC_CACHE_CHECK([for Xkb], [emacs_cv_xkb],
@@ -2769,25 +2806,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
@@ -3773,7 +3791,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 +3899,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
@@ -3921,10 +3939,21 @@ if test "${HAVE_X11}" = "yes"; then
   if test "${HAVE_XCB}" = "yes"; then
     AC_CHECK_LIB([X11-xcb], [XGetXCBConnection], [HAVE_X11_XCB=yes])
     if test "${HAVE_X11_XCB}" = "yes"; then
-      AC_DEFINE([USE_XCB], [1],
+      AC_CHECK_LIB([xcb-util], [xcb_aux_sync], [HAVE_XCB_UTIL=yes])
+      if test "${HAVE_XCB_UTIL}" = "yes"; then
+	AC_DEFINE([USE_XCB], [1],
 [Define to 1 if you have the XCB library and X11-XCB library for mixed
-X11/XCB programming.])
-      XCB_LIBS="-lX11-xcb -lxcb"
+  X11/XCB programming.])
+        XCB_LIBS="-lX11-xcb -lxcb -lxcb-util"
+      else
+	AC_CHECK_LIB([xcb-aux], [xcb_aux_sync], [HAVE_XCB_AUX=yes])
+        if test "${HAVE_XCB_AUX}" = "yes"; then
+	  AC_DEFINE([USE_XCB], [1],
+[Define to 1 if you have the XCB library and X11-XCB library for mixed
+ X11/XCB programming.])
+          XCB_LIBS="-lX11-xcb -lxcb -lxcb-aux"
+        fi
+      fi
     fi
   fi
 fi
@@ -4192,14 +4221,12 @@ AC_SUBST_FILE([module_env_snippet_26])
 AC_SUBST_FILE([module_env_snippet_27])
 AC_SUBST_FILE([module_env_snippet_28])
 AC_SUBST_FILE([module_env_snippet_29])
-AC_SUBST_FILE([module_env_snippet_30])
 module_env_snippet_25="$srcdir/src/module-env-25.h"
 module_env_snippet_26="$srcdir/src/module-env-26.h"
 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 +4309,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 +4336,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
 
@@ -4682,7 +4707,7 @@ AC_SUBST([XINERAMA_LIBS])
 ### Use Xfixes (-lXfixes) if available
 HAVE_XFIXES=no
 if test "${HAVE_X11}" = "yes"; then
-  XFIXES_REQUIRED=1.0.0
+  XFIXES_REQUIRED=4.0.0
   XFIXES_MODULES="xfixes >= $XFIXES_REQUIRED"
   EMACS_CHECK_MODULES([XFIXES], [$XFIXES_MODULES])
   if test $HAVE_XFIXES = no; then
@@ -4986,7 +5011,6 @@ pthread_sigmask strsignal setitimer \
 sendto recvfrom getsockname getifaddrs freeifaddrs \
 gai_strerror sync \
 getpwent endpwent getgrent endgrent \
-renameat2 \
 cfmakeraw cfsetspeed __executable_start log2 pthread_setname_np \
 pthread_set_name_np])
 LIBS=$OLD_LIBS
@@ -5616,7 +5640,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.])
   ;;
@@ -6380,7 +6404,7 @@ fi
 # it temporarily reverts them to their pre-pkg-config values,
 # because gnulib needs to work with both src (which uses the
 # pkg-config stuff) and lib-src (which does not).  For example, gnulib
-# may need to determine whether CLOCK_TIME_LIB should contain -lrt,
+# may need to determine whether LIB_CLOCK_GETTIME should contain -lrt,
 # and it therefore needs to run in an environment where LIBS does not
 # already contain -lrt merely because 'pkg-config --libs' printed '-lrt'
 # for some package unrelated to lib-src.
@@ -6520,12 +6544,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 +6596,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 +6667,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/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

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.

doc/emacs/files.texi

@@ -812,21 +812,22 @@ in these cases, customize the variable
 @vindex write-region-inhibit-fsync
   Normally, when a program writes a file, the operating system briefly
 caches the file's data in main memory before committing the data to
-secondary storage.  Although this can greatly improve performance, it
-risks data loss if the system loses power before committing the cache,
-and on some platforms other processes might not immediately notice the
-file's change.
+disk.  This can greatly improve performance; for example, when running
+on laptops, it can avoid a disk spin-up each time a file is written.
+However, it risks data loss if the operating system crashes before
+committing the cache to disk.
 
   To lessen this risk, Emacs can invoke the @code{fsync} system call
 after saving a file.  Using @code{fsync} does not eliminate the risk
-of data loss or slow notification, partly because many systems do not support
+of data loss, partly because many systems do not implement
 @code{fsync} properly, and partly because Emacs's file-saving
 procedure typically relies also on directory updates that might not
 survive a crash even if @code{fsync} works properly.
 
   The @code{write-region-inhibit-fsync} variable controls whether
 Emacs invokes @code{fsync} after saving a file.  The variable's
-default value is @code{t}.
+default value is @code{nil} when Emacs is interactive, and @code{t}
+when Emacs runs in batch mode (@pxref{Initial Options, Batch Mode}).
 
   Emacs never uses @code{fsync} when writing auto-save files, as these
 files might lose data anyway.
@@ -1737,13 +1738,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
@@ -1903,11 +1900,6 @@ following in the Trash directory:
 liable to also delete this @code{.dir-locals.el} file, so this should
 only be done if you delete files from the Trash directory manually.
 
-@vindex remote-file-name-inhibit-delete-by-moving-to-trash
-  If the variable @code{remote-file-name-inhibit-delete-by-moving-to-trash}
-is non-@code{nil}, remote files are never moved to the Trash.  They
-are deleted instead.
-
 @ifnottex
   If a file is under version control (@pxref{Version Control}), you
 should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
@@ -2289,15 +2281,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 +2345,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/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

@@ -2283,25 +2283,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

@@ -1810,28 +1810,31 @@ you can give each daemon its own server name like this:
   emacs --daemon=foo
 @end example
 
-@vindex server-stop-automatically
+@findex server-stop-automatically
   The Emacs server can optionally be stopped automatically when
-certain conditions are met.  To do this, set the option
-@code{server-stop-automatically} to one of the following values:
+certain conditions are met.  To do this, call the function
+@code{server-stop-automatically} in your init file (@pxref{Init
+File}), with one of the following arguments:
 
-@table @code
-@item empty
-This value causes the server to be stopped when it has no clients, no
-unsaved file-visiting buffers and no running processes anymore.
+@itemize
+@item
+With the argument @code{empty}, the server is stopped when it has no
+clients, no unsaved file-visiting buffers and no running processes
+anymore.
 
-@item delete-frame
-This value means that when the last client frame is being closed, you
-are asked whether each unsaved file-visiting buffer must be saved and
-each unfinished process can be stopped, and if so, the server is
+@item
+With the argument @code{delete-frame}, when the last client frame is
+being closed, you are asked whether each unsaved file-visiting buffer
+must be saved and each unfinished process can be stopped, and if so,
+the server is stopped.
+
+@item
+With the argument @code{kill-terminal}, when the last client frame is
+being closed with @kbd{C-x C-c} (@code{save-buffers-kill-terminal}),
+you are asked whether each unsaved file-visiting buffer must be saved
+and each unfinished process can be stopped, and if so, the server is
 stopped.
-
-@item kill-terminal
-This value means that when the last client frame is being closed with
-@kbd{C-x C-c} (@code{save-buffers-kill-terminal}), you are asked
-whether each unsaved file-visiting buffer must be saved and each
-unfinished process can be stopped, and if so, the server is stopped.
-@end table
+@end itemize
 
 @findex server-eval-at
   If you have defined a server by a unique server name, it is possible

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
@@ -266,66 +265,6 @@ 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
@@ -492,9 +431,6 @@ large chunks of code:
 @table @kbd
 @item C-M-q
 Reindent all the lines within one parenthetical grouping.
-@item M-q
-Fill a single paragraph in a defun, or reindent all the lines within
-that defun.
 @item C-u @key{TAB}
 Shift an entire parenthetical grouping rigidly sideways so that its
 first line is properly indented.
@@ -515,21 +451,6 @@ indentation of the line where the grouping starts).  The function that
 etc.  To correct the overall indentation as well, type @kbd{@key{TAB}}
 first.
 
-@kindex M-q
-@findex prog-fill-reindent-defun
-@vindex beginning-of-defun-function
-@vindex end-of-defun-function
-@vindex fill-paragraph-function
-  To reindent the entire defun around point, type @kbd{M-q}
-(@code{prog-fill-reindent-defun}).  If point is in a comment or a
-string, this command fills and indents the comment or string instead.
-What exactly constitutes a comment, a string, or a defun depends on
-the major mode: the bounds of a defun are decided by the variables
-@code{beginning-of-defun-function} and @code{end-of-defun-function}
-(@pxref{List Motion,,, elisp, The Emacs Lisp Reference Manual}),
-and the filling mechanism is decided by @code{fill-paragraph-function}
-(@pxref{Filling,,, elisp, The Emacs Lisp Reference Manual}).
-
 @kindex C-u TAB
   If you like the relative indentation within a grouping but not the
 indentation of its first line, move point to that first line and type
@@ -1387,12 +1308,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

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/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

@@ -1960,8 +1960,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 +2395,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 +2443,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 +3215,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/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
@@ -6920,7 +6833,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 +6846,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 +6893,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/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

@@ -692,9 +692,11 @@ files that the user does not need to know about.
 
 @defvar write-region-inhibit-fsync
 If this variable's value is @code{nil}, @code{write-region} uses the
-@code{fsync} system call after writing a file.  If the value is
-@code{t}, Emacs does not use @code{fsync}.  The default value is
-@code{t}.  @xref{Files and Storage}.
+@code{fsync} system call after writing a file.  Although this slows
+Emacs down, it lessens the risk of data loss after power failure.  If
+the value is @code{t}, Emacs does not use @code{fsync}.  The default
+value is @code{nil} when Emacs is interactive, and @code{t} when Emacs
+runs in batch mode.  @xref{Files and Storage}.
 @end defvar
 
 @defmac with-temp-file file body@dots{}
@@ -1877,11 +1879,6 @@ no prefix argument is given, and @code{nil} otherwise.
 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @end deffn
 
-@defopt remote-file-name-inhibit-delete-by-moving-to-trash
-If this variable is non-@code{nil}, remote files are never moved to
-the Trash.  They are deleted instead.
-@end defopt
-
 @cindex file permissions, setting
 @cindex permissions, file
 @cindex file modes, setting
@@ -2051,28 +2048,17 @@ data already stored elsewhere on secondary storage until one file or
 the other is later modified; this will lose both files if the only
 copy on secondary storage is lost due to media failure.  Second, the
 operating system might not write data to secondary storage
-immediately, which will lose the data if power is lost
-or if there is a media failure.
+immediately, which will lose the data if power is lost.
 
 @findex write-region
 Although both sorts of failures can largely be avoided by a suitably
-configured system, such systems are typically more expensive or
-less efficient.  In lower-end systems, to survive media failure you
+configured file system, such systems are typically more expensive or
+less efficient.  In more-typical systems, to survive media failure you
 can copy the file to a different device, and to survive a power
-failure (or be immediately notified of a media failure) you can use
-the @code{write-region} function with the
+failure you can use the @code{write-region} function with the
 @code{write-region-inhibit-fsync} variable set to @code{nil}.
-Although this variable is ordinarily @code{t} because that can
-significantly improve performance, it may make sense to temporarily
-bind it to @code{nil} if using Emacs to implement database-like
-transactions that survive power failure on lower-end systems.
 @xref{Writing to Files}.
 
-On some platforms when Emacs changes a file other processes might not
-be notified of the change immediately.  Setting
-@code{write-region-inhibit-fsync} to @code{nil} may improve
-notification speed in this case, though there are no guarantees.
-
 @node File Names
 @section File Names
 @cindex file names
@@ -3390,7 +3376,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 +3391,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 +3437,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 +3452,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

@@ -3577,7 +3577,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 +4112,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 +4141,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

@@ -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
@@ -2631,12 +2626,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 +2688,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__))}}

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
@@ -1504,24 +1440,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:
 

doc/lispref/lists.texi

@@ -705,7 +705,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 +1224,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

doc/lispref/loading.texi

@@ -1338,7 +1338,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

@@ -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
@@ -4155,7 +4138,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
@@ -5081,9 +5064,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

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

@@ -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
@@ -1358,8 +1305,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

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

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/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.
 
@@ -5510,7 +5509,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 +5528,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
@@ -2561,9 +2558,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 +2606,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

@@ -3216,7 +3216,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

doc/misc/calc.texi

@@ -5394,7 +5394,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
@@ -11042,8 +11042,7 @@ the year even for older dates.   The customizable variable
 have Calc's date forms switch from the Julian to Gregorian calendar at
 any specified date.
 
-A few platforms support leap seconds, such as the time stamp
-1972-06-30 23:59:60 UTC, an extra second appended to June 1972.
+Today's timekeepers introduce an occasional ``leap second''.
 These do not occur regularly and Calc does not take these minor
 effects into account.  (If it did, it would have to report a
 non-integer number of days between, say,
@@ -17343,12 +17342,8 @@ it can be a variable which is a time zone name in upper- or lower-case.
 For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
 (for Pacific standard and daylight saving times, respectively).
 
-North American and European time zone names are defined as follows.
-These names are obsolescent and new code should not rely on them:
-the @samp{YST}-related names have disagreed with time in Yukon since 1973,
-and other names could well become confusing or wrong in the future
-as countries change their time zone rules.
-For each time zone there is one name for standard time,
+North American and European time zone names are defined as follows;
+note that for each time zone there is one name for standard time,
 another for daylight saving time, and a third for ``generalized'' time
 in which the daylight saving adjustment is computed from context.
 
@@ -17370,7 +17365,7 @@ To define time zone names that do not appear in the above table,
 you must modify the Lisp variable @code{math-tzone-names}.  This
 is a list of lists describing the different time zone names; its
 structure is best explained by an example.  The three entries for
-circa-2022 US Pacific Time look like this:
+Pacific Time look like this:
 
 @smallexample
 @group

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

@@ -3133,23 +3133,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

@@ -2,7 +2,7 @@
 @c %**start of header
 @setfilename ../../eglot.info
 @settitle Eglot: The Emacs Client for the Language Server Protocol
-@include docstyle.texi
+@include ../emacs/docstyle.texi
 @syncodeindex vr cp
 @syncodeindex fn cp
 @c %**end of header
@@ -98,7 +98,7 @@ 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
+* Advanced server configuration::
 * Troubleshooting Eglot::       Troubleshooting and reporting bugs.
 * GNU Free Documentation License::  The license for this manual.
 * Index::
@@ -154,11 +154,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!
@@ -171,7 +171,7 @@ This chapter describes how to set up Eglot for your needs, and how to
 start it.
 
 @menu
-* Setting Up LSP Servers::   How to configure LSP servers for your needs.
+* Setting Up LSP Servers::      How to configure LSP servers for your needs.
 * Starting Eglot::              Ways of starting Eglot for your project.
 * Shutting Down LSP Servers::
 @end menu
@@ -228,9 +228,8 @@ 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}).
+how to construct the @samp{initializationOptions} JSON object for the
+server (@pxref{Advanced server configuration}).
 
 @item (@var{host} @var{port} @var{args}@dots{})
 Here @var{host} is a string and @var{port} is a positive integer
@@ -465,10 +464,52 @@ 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
+
+@item M-x eglot-inlay-hints-mode
+This command toggles LSP ``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++ LSP
+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.
+
 @end itemize
 
 Not all servers support the full set of LSP capabilities, but most of
@@ -671,44 +712,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 +967,123 @@ 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.
+
 @end table
 
 @node Advanced server configuration
 @chapter Advanced server configuration
 
-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.
+Though many language servers work very well out-of-the-both, most
+servers allow fine-grained configuration of their operation.  A small
+number of servers even require a special configuration to work
+acceptably or at all.  
 
-After having setup a server executable program in
+After having setup your 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:
+verifying that Eglot can invoke it, you may want to take advantage of
+options specific to that server.  Before doing so, it's important to
+distinguish the two main modes of server configuration:
 
 @itemize @bullet
-@item
-Project-specific, applying to a specific project;
+@item 
+User-specific, applies to all projects the server is used for
+
+This manner of configuring the server applies to all projects the
+server is employed for.  You can do this in a variety of ways,
+depending on what the server allows.  Some servers allow command line
+options To use it, a specific syntax of @code{eglot-server-programs}
+can be used, namely its @code{:initializationOptions}.
 
 @item
-User-specific, applying to all projects the server is used for.
+Project-specific, applies to a specific project
+
 @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:
+Note that not all servers accept both forms of customization, and it's
+not even guaranteed that the options accepted in one form are also
+accepted in the other or have the same effect.  When in doubt consult
+your language server's documentation.
 
-@menu
-* Project-specific configuration::
-* User-specific configuration::
-* JSONRPC objects in Elisp::
-@end menu
+@node The @code{:initializationOptions} option
 
-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
+@node The @code{eglot-workspace-configuration} variable
 @vindex eglot-workspace-configuration
-@cindex workspace configuration
+@cindex server 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 meant to be set in the @file{.dir-locals.el} file, to
+provide per-project settings, as described below in more detail.
 
-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.
+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.
 
-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}).
+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.
 
-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,189 +1091,34 @@ 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
+@node How to represent LSP options in Elisp
 
-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:
-
-@lisp
-(with-eval-after-load 'eglot
-  (add-to-list 'eglot-server-programs
-               `(c++-mode . ("clangd" "--compile-commands-dir=/tmp"))))
-
-@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
+@node Other modes of controlling server behaviour
 
 @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.
 
@@ -1275,143 +1128,53 @@ 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

@@ -952,7 +952,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
@@ -1477,30 +1477,10 @@ 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.
-
 @item
 To report a bug in ERC, use @kbd{M-x erc-bug}.
 

doc/misc/eshell.texi

@@ -418,9 +418,9 @@ alias (@pxref{Aliases}).  Example:
 @example
 ~ $ which sudo
 eshell/sudo is a compiled Lisp function in `em-tramp.el'.
-~ $ alias sudo '*sudo $@@*'
+~ $ alias sudo '*sudo $*'
 ~ $ which sudo
-sudo is an alias, defined as "*sudo $@@*"
+sudo is an alias, defined as "*sudo $*"
 @end example
 
 Some of the built-in commands have different behavior from their
@@ -540,7 +540,7 @@ Manual}.
 
 If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this
 command does not use Emacs's internal @code{diff}.  This is the same
-as using @samp{alias diff '*diff $@@*'}.
+as using @samp{alias diff '*diff $*'}.
 
 @item dirname
 @cmindex dirname
@@ -602,8 +602,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},
@@ -612,9 +610,9 @@ but use Emacs's internal @code{grep} instead.
 
 If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these
 commands do not use Emacs's internal @code{grep}.  This is the same as
-using @samp{alias grep '*grep $@@*'}, though this setting applies to
-all of the built-in commands for which you would need to create a
-separate alias.
+using @samp{alias grep '*grep $*'}, though this setting applies to all
+of the built-in commands for which you would need to create a separate
+alias.
 
 @item history
 @cmindex history
@@ -670,7 +668,7 @@ Alias to Emacs's @code{locate} function, which simply runs the external
 
 If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's
 internal @code{locate} is not used.  This is the same as using
-@samp{alias locate '*locate $@@*'}.
+@samp{alias locate '*locate $*'}.
 
 @item ls
 @cmindex ls
@@ -1049,21 +1047,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 +1078,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
@@ -1103,47 +1091,24 @@ necessary.  Its value is @code{@var{emacs-version},eshell}.
 @node Aliases
 @section Aliases
 
-@findex eshell-read-aliases-list
-Aliases are commands that expand to a longer input line.  For example,
-@command{ll} is a common alias for @code{ls -l}.  To define this alias
-in Eshell, you can use the command invocation @kbd{alias ll 'ls -l
-$@@*'}; with this defined, running @samp{ll foo} in Eshell will
-actually run @samp{ls -l foo}.  Aliases defined (or deleted) by the
-@command{alias} command are automatically written to the file named by
-@code{eshell-aliases-file}, which you can also edit directly.  After
-doing so, use @w{@kbd{M-x eshell-read-aliases-list}} to load the
-edited aliases.
-
-Note that unlike aliases in Bash, arguments must be handled
-explicitly.  Within aliases, you can use the special variables
-@samp{$*}, @samp{$0}, @samp{$1}, @samp{$2}, etc. to refer to the
-arguments passed to the alias.
-
-@table @code
-
 @vindex $*
-@item $*
-This expands to the list of arguments passed to the alias.  For
-example, if you run @code{my-alias 1 2 3}, then @samp{$*} would be the
-list @code{(1 2 3)}.  Note that since this variable is a list, using
-@samp{$*} in an alias will pass this list as a single argument to the
-aliased command.  Therefore, when defining an alias, you should
-usually use @samp{$@@*} to pass all arguments along, splicing them
-into your argument list (@pxref{Dollars Expansion}).
+Aliases are commands that expand to a longer input line.  For example,
+@command{ll} is a common alias for @code{ls -l}, and would be defined
+with the command invocation @kbd{alias ll 'ls -l $*'}; with this defined,
+running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}.
+Aliases defined (or deleted) by the @command{alias} command are
+automatically written to the file named by @code{eshell-aliases-file},
+which you can also edit directly (although you will have to manually
+reload it).
 
-@vindex $0
-@item $0
-This expands to the name of the alias currently being executed.
-
-@vindex $1, $2, @dots{}, $9
-@item $1, $2, @dots{}, $9
-These variables expand to the nth argument (starting at 1) passed to
-the alias.  This lets you selectively use an alias's arguments, so
+@vindex $1, $2, @dots{}
+Note that unlike aliases in Bash, arguments must be handled
+explicitly.  Typically the alias definition would end in @samp{$*} to
+pass all arguments along.  More selective use of arguments via
+@samp{$1}, @samp{$2}, etc., is also possible.  For example,
 @kbd{alias mcd 'mkdir $1 && cd $1'} would cause @kbd{mcd foo} to
 create and switch to a directory called @samp{foo}.
 
-@end table
-
 @node History
 @section History
 @cmindex history
@@ -1374,24 +1339,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
@@ -1418,36 +1370,12 @@ to split the string.  @var{regexp} can be any form other than a
 number.  For example, @samp{$@var{var}[: 0]} will return the first
 element of a colon-delimited string.
 
-@cindex length operator, in variable expansion
 @item $#@var{expr}
-This is the @dfn{length operator}.  It expands to the length of the
-result of @var{expr}, an expression in one of the above forms.  For
-example, @samp{$#@var{var}} returns the length of the variable
-@var{var} and @samp{$#@var{var}[0]} returns the length of the first
-element of @var{var}.  Again, signals an error if the result of
-@var{expr} is not a string or a sequence.
-
-@cindex splice operator, in variable expansion
-@item $@@@var{expr}
-This is the @dfn{splice operator}.  It ``splices'' the elements of
-@var{expr} (an expression of one of the above forms) into the
-resulting list of arguments, much like the @samp{,@@} marker in Emacs
-Lisp (@pxref{Backquote, , , elisp, The Emacs Lisp Reference Manual}).
-The elements of @var{expr} become arguments at the same level as the
-other arguments around it.  For example, if @var{numbers} is the list
-@code{(1 2 3)}, then:
-
-@example
-@group
-~ $ echo 0 $numbers
-(0
- (1 2 3))
-@end group
-@group
-~ $ echo 0 $@@numbers
-(0 1 2 3)
-@end group
-@end example
+Expands to the length of the result of @var{expr}, an expression in
+one of the above forms.  For example, @samp{$#@var{var}} returns the
+length of the variable @var{var} and @samp{$#@var{var}[0]} returns the
+length of the first element of @var{var}.  Again, signals an error if
+the result of @var{expr} is not a string or a sequence.
 
 @end table
 
@@ -2166,7 +2094,7 @@ Allow for a Bash-compatible syntax, such as:
 
 @example
 alias arg=blah
-function arg () @{ blah $@@* @}
+function arg () @{ blah $* @}
 @end example
 
 @item Pcomplete sometimes gets stuck
@@ -2191,6 +2119,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
@@ -2249,6 +2179,11 @@ So that @kbd{M-@key{DEL}} acts in a predictable manner, etc.
 
 @item Allow all Eshell buffers to share the same history and list-dir
 
+@item There is a problem with script commands that output to @file{/dev/null}
+
+If a script file, somewhere in the middle, uses @samp{> /dev/null},
+output from all subsequent commands is swallowed.
+
 @item Split up parsing of text after @samp{$} in @file{esh-var.el}
 
 Make it similar to the way that @file{esh-arg.el} is structured.
@@ -2457,6 +2392,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

doc/misc/flymake.texi

@@ -1,8 +1,8 @@
 \input texinfo   @c -*- mode: texinfo; coding: utf-8 -*-
 @comment %**start of header
 @setfilename ../../info/flymake.info
-@set VERSION 1.3.4
-@set UPDATED April 2023
+@set VERSION 1.2.2
+@set UPDATED November 2021
 @settitle GNU Flymake @value{VERSION}
 @include docstyle.texi
 @syncodeindex pg cp
@@ -142,12 +142,6 @@ highlighted regions to learn what the specific problem
 is.  Alternatively, place point on the highlighted regions and use the
 commands @code{eldoc} or @code{display-local-help}.
 
-Another easy way to get instant access to the diagnostic text is to
-set @code{flymake-show-diagnostics-at-end-of-line} to a non-@code{nil}
-value.  This makes the diagnostic messages appear at the end of the
-line where the regular annotation is located (@pxref{Customizable
-variables})
-
 @cindex next and previous diagnostic
 If the diagnostics are outside the visible region of the buffer,
 @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are
@@ -320,22 +314,6 @@ Which fringe (if any) should show the warning/error bitmaps.
 @item flymake-wrap-around
 If non-@code{nil}, moving to errors with @code{flymake-goto-next-error} and
 @code{flymake-goto-prev-error} wraps around buffer boundaries.
-
-@item flymake-show-diagnostics-at-end-of-line
-If non-@code{nil}, show summarized descriptions of diagnostics at the
-end of the line.  Depending on your preference, this can either be
-distracting and easily confused with actual code, or a significant
-early aid that relieves you from moving around or reaching for the
-mouse to consult an error message.
-
-@item flymake-error-eol
-A custom face for summarizing diagnostic error messages.
-
-@item flymake-warning-eol
-A custom face for summarizing diagnostic warning messages.
-
-@item flymake-note-eol
-A custom face for summarizing diagnostic notes.
 @end vtable
 
 @node Extending Flymake
@@ -416,7 +394,7 @@ its @code{flymake-overlay-control} property:
 
 @item
 @cindex severity of diagnostic
-@code{severity} is a non-negative integer specifying the
+@code{flymake-severity} is a non-negative integer specifying the
 diagnostic's severity.  The higher the value, the more serious is the
 error.  If the overlay property @code{priority} is not specified in
 @code{flymake-overlay-control}, @code{flymake-severity} is used to set
@@ -431,17 +409,6 @@ type, in case the name of the symbol associated with it is very long.
 @vindex flymake-category
 @code{flymake-category} is a symbol whose property list is considered
 the default for missing values of any other properties.
-
-@item
-@cindex mode-line appearance of a diagnostic
-@code{mode-line-face} is a face specifier controlling the appearance
-of the indicator of this type of diagnostic in the mode line.
-
-@item
-@cindex summarized appearance of a diagnostic
-@code{echo-face} is a face specifier controlling the appearance of the
-summarized description of this diagnostic when reading diagnostic
-messages (@pxref{Finding diagnostics}).
 @end itemize
 
 @cindex predefined diagnostic types

doc/misc/gnus.texi

@@ -10528,9 +10528,9 @@ article (@code{gnus-summary-refer-references}).
 @kindex A T @r{(Summary)}
 Display the full thread where the current article appears
 (@code{gnus-summary-refer-thread}).  By default this command looks for
-articles only in the current group.  If the group belongs to a backend
-that has an associated search engine, articles are found by searching.
-In other cases each header in the current group must be fetched and
+articles only in the current group.  Some backends (currently only
+@code{nnimap}) know how to find articles in the thread directly.  In
+other cases each header in the current group must be fetched and
 examined, so it usually takes a while.  If you do it often, you may
 consider setting @code{gnus-fetch-old-headers} to @code{invisible}
 (@pxref{Filling In Threads}).  This won't have any visible effects
@@ -10538,22 +10538,19 @@ normally, but it'll make this command work a whole lot faster.  Of
 course, it'll make group entry somewhat slow.
 
 @vindex gnus-refer-thread-use-search
-If @code{gnus-refer-thread-use-search} is @code{nil} (the default)
-then thread-referral only looks for articles in the current group. If
-this variable is @code{t} the server to which the current group
-belongs is searched (provided that searching is available for the
-server's backend).  If this variable is a list of servers, each server
-in the list is searched.
+If @code{gnus-refer-thread-use-search} is non-@code{nil} then those backends
+that know how to find threads directly will search not just in the
+current group but all groups on the same server.
 
 @vindex gnus-refer-thread-limit
 The @code{gnus-refer-thread-limit} variable says how many old (i.e.,
 articles before the first displayed in the current group) headers to
-fetch when referring a thread.  The default is 500.  If @code{t}, all
-the available headers will be fetched.  This variable can be
-overridden by giving the @kbd{A T} command a numerical prefix.
+fetch when doing this command.  The default is 200.  If @code{t}, all
+the available headers will be fetched.  This variable can be overridden
+by giving the @kbd{A T} command a numerical prefix.
 
 @vindex gnus-refer-thread-limit-to-thread
-@code{gnus-summary-refer-thread} tries to add any articles it finds to
+In most cases @code{gnus-refer-thread} adds any articles it finds to
 the current summary buffer.  (When @code{gnus-refer-thread-use-search}
 is true and the initial referral starts from a summary buffer for a
 non-virtual group this may not be possible.  In this case a new

doc/misc/idlwave.texi

@@ -1372,9 +1372,10 @@ among, with differing advantages and disadvantages.  The variable
 to (as long as @code{idlwave-help-use-assistant} is not set).  This
 function is used to set the variable @code{browse-url-browser-function}
 locally for IDLWAVE help only.  Customize the latter variable to see
-what choices of browsers your system offers.  Certain browsers like EWW
-(@pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}) are run within Emacs,
-and use Emacs buffers to display the HTML help.  This can be convenient,
+what choices of browsers your system offers.  Certain browsers like
+@code{w3} (bundled with many versions of Emacs) and @code{w3m}
+(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use
+Emacs buffers to display the HTML help.  This can be convenient,
 especially on small displays, and images can even be displayed in-line
 on newer Emacs versions.  However, better formatting results are often
 achieved with external browsers, like Mozilla.  IDLWAVE assumes any

doc/misc/message.texi

@@ -1948,9 +1948,11 @@ requires the @acronym{POP}-before-@acronym{SMTP} authentication.
 @cindex X-Message-SMTP-Method
 If you have a complex @acronym{SMTP} setup, and want some messages to
 go via one mail server, and other messages to go through another, you
-can use the @samp{X-Message-SMTP-Method} header to override the
-default by using the keyword @samp{smtp} followed by the server
-information:
+can use the @samp{X-Message-SMTP-Method} header.  These are the
+supported values:
+
+@table @samp
+@item smtpmail
 
 @example
 X-Message-SMTP-Method: smtp smtp.fsf.org 587
@@ -1966,19 +1968,16 @@ This is the same as the above, but uses @samp{other-user} as the user
 name when authenticating.  This is handy if you have several
 @acronym{SMTP} accounts on the same server.
 
-This header may also be used to specify an alternative MTA by using a
-@samp{mailer} keyword, where @samp{mailer} is the name of an MTA with
-a corresponding @code{message-send-mail-with-'mailer'} function.  For
-example:
+@item sendmail
 
 @example
 X-Message-SMTP-Method: sendmail
 @end example
 
-will send the message via the locally installed sendmail program.  The
-recognized values of @samp{mailer} are sendmail, qmail, mh, and
-mailclient.
+This will send the message via the locally installed sendmail/exim/etc
+installation.
 
+@end table
 
 @item message-mh-deletable-headers
 @vindex message-mh-deletable-headers

doc/misc/mh-e.texi

@@ -793,7 +793,7 @@ You should see the scan line for your message, and perhaps others. Use
 
 @cartouche
 @smallexample
-  3 t08/24 root       received fax files on Wed Aug 24 11:00:13 -0700 1
+  3 t08/24 root       received fax files on Wed Aug 24 11:00:13 PDT 1
 # 4+t08/24 To:wohler  Test<<This is a test message to get the wheels
 
 -:%%  @{+inbox/select@} 4 msgs (1-4)   Bot L4     (MH-Folder Show)---------

doc/misc/newsticker.texi

@@ -307,16 +307,11 @@ news ticker.
 
 @findex newsticker-start-ticker
 @findex newsticker-stop-ticker
-@vindex newsticker-ticker-period
 Headlines can be displayed in the echo area, either scrolling like
 messages in a stock-quote ticker, or just changing.  This can be
 started with the command @code{newsticker-start-ticker}.  It can be
 stopped with @code{newsticker-stop-ticker}.
 
-The ticker by default runs continuously.  To only run it once, at a
-specific time interval, set the @code{newsticker-ticker-period}
-variable.
-
 
 @node Navigation
 @section Navigation
@@ -547,10 +542,8 @@ are shown in the echo area, i.e., the ``ticker''.
 @itemize
 @item
 @vindex newsticker-display-interval
-@vindex newsticker-ticker-period
 @vindex newsticker-scroll-smoothly
-@code{newsticker-ticker-interval},
-@code{newsticker-ticker-period}, and
+@code{newsticker-ticker-interval} and
 @code{newsticker-scroll-smoothly} define how headlines are shown in
 the echo area.
 @end itemize

doc/misc/org.org

@@ -5958,9 +5958,8 @@ the agenda (see [[*Weekly/daily agenda]]).  We distinguish:
   #+findex: org-block
 
   For more complex date specifications, Org mode supports using the
-  special expression diary entries implemented in the
-  [[info:emacs#Special Diary Entries][Emacs Calendar package]][fn:20].
-  For example, with optional time:
+  special expression diary entries implemented in the Emacs Calendar
+  package[fn:20].  For example, with optional time:
 
   #+begin_example
   ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month

doc/misc/rcirc.texi

@@ -691,11 +691,11 @@ window is showing them), the mode line will now show you the abbreviated
 channel or nick name.  Use @kbd{C-c C-@key{SPC}} to switch to these
 buffers.
 
-@cindex rcirc-track-abbreviate-flag
+@cindex rcirc-track-abbrevate-flag
 By default the channel names are abbreviated, set
-@code{rcirc-track-abbreviate-flag} to a non-@code{nil} value.  This
-might be interesting if the IRC activities are not tracked in the mode
-line, but somewhere else.
+@code{rcirc-track-abbrevate-flag} to a non-@code{nil} value. This might be
+interesting if the IRC activities are not tracked in the mode line,
+but somewhere else.
 
 @vindex rcirc-mode-hook
 If you prefer not to load @code{rcirc} immediately, you can delay the

doc/misc/sc.texi

@@ -404,7 +404,7 @@ from the alist with the @code{sc-mail-field} function.  Thus, if the
 following fields were present in the original article:
 
 @example
-Date:@: 08 Apr 1991 17:32:09 -0500
+Date:@: 08 April 1991, 17:32:09 EST
 Subject:@: Better get out your asbestos suit
 @end example
 
@@ -415,7 +415,7 @@ then, the following lisp constructs return:
 
 @example
 (sc-mail-field "date")
-==> "08 Apr 1991 17:32:09 -0500"
+==> "08 April 1991, 17:32:09 EST"
 
 (sc-mail-field "subject")
 ==> "Better get out your asbestos suit"