; Whitespace cleanup

* lisp/net/tramp-ftp.el (tramp-ftp-file-name-handler): Support threads.
(Bug#33135)

.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

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

Makefile.in

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

admin/authors.el

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

admin/charsets/Makefile.in

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

admin/charsets/mapconv

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

admin/git-bisect-start

@@ -82,7 +82,7 @@ done
 # SKIP-BRANCH 58cc931e92ece70c3e64131ee12a799d65409100
 
 ## The list below is the exhaustive list of all commits between Dec 1
-## 2016 and Feb 28 2023 on which building Emacs with the default
+## 2016 and 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/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

@@ -46,7 +46,7 @@ GNULIB_MODULES='
   qcopy-acl readlink readlinkat regex
   sig2str sigdescr_np socklen stat-time std-gnu11 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/emba

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

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

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

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

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

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

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

configure.ac

@@ -1001,7 +1001,7 @@ AC_ARG_ENABLE([gcc-warnings],
    # however, if there is also a .tarball-version file it is probably
    # just a release imported into Git for patch management.
    gl_gcc_warnings=no
-   if test -d "$srcdir"/.git && test ! -f "$srcdir"/.tarball-version; then
+   if test -e "$srcdir"/.git && test ! -f "$srcdir"/.tarball-version; then
       # Clang typically identifies itself as GCC 4.2 or something similar
       # even if it is recent enough to accept the warnings we enable.
       AS_IF([test "$emacs_cv_clang" = yes],
@@ -1643,8 +1643,7 @@ case "$opsys" in
   ## Motif needs -lgen.
   unixware) LIBS_SYSTEM="-lsocket -lnsl -lelf -lgen" ;;
 
-  # Haiku needs -lbsd for cfsetspeed.
-  haiku) LIBS_SYSTEM="-lnetwork -lbsd" ;;
+  haiku) LIBS_SYSTEM="-lnetwork" ;;
 esac
 
 AC_SUBST([LIBS_SYSTEM])
@@ -2034,29 +2033,37 @@ if test "${with_ns}" != no; then
      ns_appresdir=${ns_appdir}/Contents/Resources
      ns_appsrc=Cocoa/Emacs.base
      ns_fontfile=macfont.o
-  elif flags=`(gnustep-config --objc-flags) 2>/dev/null`; then
+  elif flags=$( (gnustep-config --objc-flags) 2>/dev/null); then
      NS_IMPL_GNUSTEP=yes
      NS_GNUSTEP_CONFIG=yes
      GNU_OBJC_CFLAGS="$flags"
-     LIBS_GNUSTEP=`gnustep-config --gui-libs || exit`
+     LIBS_GNUSTEP=$(gnustep-config --gui-libs) || exit
   elif test -f $GNUSTEP_CONFIG_FILE; then
      NS_IMPL_GNUSTEP=yes
      dnl FIXME sourcing this several times in subshells seems inefficient.
-     GNUSTEP_SYSTEM_HEADERS=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_SYSTEM_HEADERS"])`
-     GNUSTEP_SYSTEM_LIBRARIES=` . $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_SYSTEM_LIBRARIES"])`
+     GNUSTEP_SYSTEM_HEADERS=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_SYSTEM_HEADERS"])
+     )
+     GNUSTEP_SYSTEM_LIBRARIES=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_SYSTEM_LIBRARIES"])
+     )
      dnl I seemed to need these as well with GNUstep-startup 0.25.
-     GNUSTEP_LOCAL_HEADERS=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_LOCAL_HEADERS"])`
-     GNUSTEP_LOCAL_LIBRARIES=`. $GNUSTEP_CONFIG_FILE \
-       && AS_ECHO(["$GNUSTEP_LOCAL_LIBRARIES"])`
+     GNUSTEP_LOCAL_HEADERS=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_LOCAL_HEADERS"])
+     )
+     GNUSTEP_LOCAL_LIBRARIES=$(
+       . $GNUSTEP_CONFIG_FILE
+       AS_ECHO(["$GNUSTEP_LOCAL_LIBRARIES"])
+     )
      test "x${GNUSTEP_LOCAL_HEADERS}" != "x" && \
        GNUSTEP_LOCAL_HEADERS="-I${GNUSTEP_LOCAL_HEADERS}"
      test "x${GNUSTEP_LOCAL_LIBRARIES}" != "x" && \
        GNUSTEP_LOCAL_LIBRARIES="-L${GNUSTEP_LOCAL_LIBRARIES}"
-     CPPFLAGS="$CPPFLAGS -isystem ${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
-     CFLAGS="$CFLAGS -isystem ${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
+     CPPFLAGS="$CPPFLAGS -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
+     CFLAGS="$CFLAGS -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
      LDFLAGS="$LDFLAGS -L${GNUSTEP_SYSTEM_LIBRARIES} ${GNUSTEP_LOCAL_LIBRARIES}"
      LIBS_GNUSTEP="-lgnustep-gui -lgnustep-base -lobjc -lpthread"
      dnl GNUstep defines BASE_NATIVE_OBJC_EXCEPTIONS to 0 or 1.
@@ -2769,25 +2776,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 +3761,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 +3869,7 @@ if test "${HAVE_BE_APP}" = "yes"; then
 	  AC_DEFINE([HAVE_OTF_GET_VARIATION_GLYPHS], [1],
 		    [Define to 1 if libotf has OTF_get_variation_glyphs.])
 	fi
-	if $PKG_CONFIG --atleast-version=0.9.16 libotf; then :; else
+	if ! $PKG_CONFIG --atleast-version=0.9.16 libotf; then
 	  AC_DEFINE([HAVE_OTF_KANNADA_BUG], [1],
 [Define to 1 if libotf is affected by https://debbugs.gnu.org/28110.])
 	fi
@@ -4199,7 +4187,7 @@ module_env_snippet_27="$srcdir/src/module-env-27.h"
 module_env_snippet_28="$srcdir/src/module-env-28.h"
 module_env_snippet_29="$srcdir/src/module-env-29.h"
 module_env_snippet_30="$srcdir/src/module-env-30.h"
-emacs_major_version=`AS_ECHO([$PACKAGE_VERSION]) | sed 's/[[.]].*//'`
+emacs_major_version="${PACKAGE_VERSION%%.*}"
 AC_SUBST([emacs_major_version])
 
 ### Emacs Lisp native compiler support
@@ -4282,8 +4270,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 +4297,14 @@ if test "${with_native_compilation}" != "no"; then
         # available.  (We filter out the gcc4 packages, because they
         # don't support jit, and they have names like "gcc49" that
         # sort later than "gcc11".)
-        PORT_PACKAGE=`port installed active | grep '^ *gcc@<:@0-9@:>@* ' | \
+        PORT_PACKAGE=$(port installed active | grep '^ *gcc@<:@0-9@:>@* ' | \
                             awk '{ print $1; }' | grep -v 'gcc4@<:@0-9@:>@' | \
-                            sort -V | tail -n 1`
+                            sort -V | tail -n 1)
         if test -n "$PORT_PACKAGE"; then
-	  emacs_val=`port contents $PORT_PACKAGE | grep libgccjit.h`
-	  emacs_val=`dirname $emacs_val`
-          MAC_CFLAGS="-I$emacs_val"
-	  emacs_val=`port contents $PORT_PACKAGE | grep libgccjit.dylib`
-	  emacs_val=`dirname $emacs_val`
-          MAC_LIBS="-L$emacs_val"
+          MAC_CFLAGS="-I$(dirname $(port contents $PORT_PACKAGE | \
+                                           grep libgccjit.h))"
+          MAC_LIBS="-L$(dirname $(port contents $PORT_PACKAGE | \
+                                              grep libgccjit.dylib))"
         fi
       fi
 
@@ -5616,7 +5602,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.])
   ;;

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

@@ -247,6 +247,36 @@ but will instead just display the buffer's contents before the
 changes, and show an echo-area message telling you how to revert the
 buffer from the file.
 
+@cindex visiting files asynchronously
+@vindex execute-file-commands-asynchronously
+  Sometimes, it is handy to visit a file asynchronously.  This means,
+while loading the file into its buffer Emacs keeps responsive, and you
+can continue to edit other files, or call commands.  This is
+controlled by the user option @code{execute-file-commands-asynchronously}.
+If this option is @code{nil} (the default), visiting a file is a
+synchronous operation.  If the value is a regexp, this allows
+asynchronously visiting files whose name matches the regexp, otherwise
+synchronously.  If the value is @code{t}, visiting files is
+unconditionally asynchronous.
+
+If you want to visit all remote files asynchronously, you should set
+
+@example
+@group
+(customize-set-variable
+  'execute-file-commands-asynchronously tramp-file-name-regexp
+  "Visit remote files asynchronously")
+@end group
+@end example
+
+@kindex C-x &
+  If you type @kbd{C-x &} (@code{universal-async-argument}) prior the
+file visiting command, the meaning of
+@code{execute-file-commands-asynchronously} will be reverted.  If this
+user option is @code{nil}, visiting a file is performed
+asynchronously.  Contrary, if this user option is non-@code{nil},
+visiting a file is performed synchronously.
+
 @kindex C-x C-v
 @findex find-alternate-file
   If you visit the wrong file unintentionally by typing its name
@@ -2289,15 +2319,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 +2383,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
 

doc/emacs/modes.texi

@@ -473,12 +473,9 @@ specify which mode you prefer.
   If you have changed the major mode of a buffer, you can return to
 the major mode Emacs would have chosen automatically, by typing
 @kbd{M-x normal-mode}.  This is the same function that
-@code{find-file} calls to choose the major mode.  If the buffer is
-visiting a file, this command also processes the file's @samp{-*-}
-line and file-local variables list (if any).  @xref{File Variables}.
-If the buffer doesn't visit a file, the command processes only the
-major mode specification, if any, in the @samp{-*-} line and in the
-file-local variables list.
+@code{find-file} calls to choose the major mode.  It also processes
+the file's @samp{-*-} line or local variables list (if any).
+@xref{File Variables}.
 
 @vindex change-major-mode-with-file-name
   The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to

doc/emacs/package.texi

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

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

@@ -26,6 +26,7 @@ are done, and the subroutines that allow Lisp programs to do them.
 * Waiting::             Waiting for user input or elapsed time.
 * Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
 * Prefix Command Arguments::    How the commands to set prefix args work.
+* Prefix Commands::     A way to dispatch commands with an option.
 * Recursive Editing::   Entering a recursive edit,
                           and why you usually shouldn't.
 * Disabling Commands::  How the command loop handles disabled commands.
@@ -325,10 +326,10 @@ function @code{oclosure-interactive-form}.
 @defun oclosure-interactive-form function
 Just like @code{interactive-form}, this function takes a command and
 returns its interactive form.  The difference is that it is a generic
-function and it is only called when @var{function} is an OClosure
-(@pxref{OClosures}).  The purpose is to make it possible for some
-OClosure types to compute their interactive forms dynamically instead
-of carrying it in one of their slots.
+function and it is only called when @var{function} is an OClosure.
+The purpose is to make it possible for some OClosure types to compute
+their interactive forms dynamically instead of carrying it in one of
+their slots.
 
 This is used for example for @code{kmacro} functions in order to
 reduce their memory size, since they all share the same interactive
@@ -1960,8 +1961,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 +2396,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 +2444,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 +3216,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
@@ -3954,6 +3935,39 @@ command; its value is negated to form the new prefix argument.  Don't
 call this command yourself unless you know what you are doing.
 @end deffn
 
+@node Prefix Commands
+@section Prefix Commands
+@cindex prefix command
+
+  A @dfn{prefix command} is a command which precedes another command.
+It dispatches the @emph{next} command by toggling a controlling
+variable's value, which could be taken into account then by that next
+command.  Whether the following command cares about the controlling
+variable is up to that command.
+
+Emacs knows of two prefix commands, @code{universal-async-argument}
+(@pxref{Visiting,,, emacs, The GNU Emacs Manual}) and
+@code{universal-coding-system-argument} (@pxref{Text Coding,,, emacs,
+The GNU Emacs Manual}).
+
+@deffn Command universal-async-argument
+This prefix command indicates the next command to run asynchronously.
+It is up to that next command to decide what asynchronously means, or
+to ignore the prefix command.
+@end deffn
+
+@defvar universal-async-argument
+This is the controlling variable toggled by the
+@code{universal-async-argument} command.  If a command supports
+asynchronous behavior, it should check whether the value of this
+variable is non-@code{nil}.
+@end defvar
+
+@deffn Command universal-coding-system-argument
+This prefix command determines the coding system to be used by the
+next I/O command.
+@end deffn
+
 @node Recursive Editing
 @section Recursive Editing
 @cindex recursive command loop

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/elisp.texi

@@ -569,7 +569,6 @@ Functions
 * Function Cells::          Accessing or setting the function definition
                               of a symbol.
 * Closures::                Functions that enclose a lexical environment.
-* OClosures::               Function objects with meta-data.
 * Advising Functions::      Adding to the definition of a function.
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
@@ -789,6 +788,7 @@ Command Loop
 * Waiting::             Waiting for user input or elapsed time.
 * Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
 * Prefix Command Arguments::    How the commands to set prefix args work.
+* Prefix Commands::     A way to dispatch commands with an option.
 * Recursive Editing::   Entering a recursive edit,
                           and why you usually shouldn't.
 * Disabling Commands::  How the command loop handles disabled commands.

doc/lispref/files.texi

@@ -96,7 +96,7 @@ not alter it, the fastest way is to use @code{insert-file-contents} in a
 temporary buffer.  Visiting the file is not necessary and takes longer.
 @xref{Reading from Files}.
 
-@deffn Command find-file filename &optional wildcards
+@deffn Command find-file filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename},
 using an existing buffer if there is one, and otherwise creating a
 new buffer and reading the file into it.  It also returns that buffer.
@@ -105,7 +105,8 @@ Aside from some technical details, the body of the @code{find-file}
 function is basically equivalent to:
 
 @smallexample
-(switch-to-buffer (find-file-noselect filename nil nil wildcards))
+(switch-to-buffer
+  (find-file-noselect filename nil nil wildcards async))
 @end smallexample
 
 @noindent
@@ -115,21 +116,28 @@ If @var{wildcards} is non-@code{nil}, which is always true in an
 interactive call, then @code{find-file} expands wildcard characters in
 @var{filename} and visits all the matching files.
 
+If @var{async} is non-@code{nil}, the file will be loaded into the
+buffer asynchronously.  Interactively, this is indicated by either
+setting user option @code{execute-file-commands-asynchronously} to
+non-@code{nil}, or by typing @kbd{C-x &}
+(@code{universal-async-argument}) prior the command.
+
 When @code{find-file} is called interactively, it prompts for
 @var{filename} in the minibuffer.
 @end deffn
 
-@deffn Command find-file-literally filename
+@deffn Command find-file-literally filename &optional async
 This command visits @var{filename}, like @code{find-file} does, but it
 does not perform any format conversions (@pxref{Format Conversion}),
 character code conversions (@pxref{Coding Systems}), or end-of-line
 conversions (@pxref{Coding System Basics, End of line conversion}).
-The buffer visiting the file is made unibyte, and its major mode is
-Fundamental mode, regardless of the file name.  File local variable
-specifications  in the file (@pxref{File Local Variables}) are
-ignored, and automatic decompression and adding a newline at the end
-of the file due to @code{require-final-newline} (@pxref{Saving
-Buffers, require-final-newline}) are also disabled.
+If called interactively, the argument @var{async} is determined like
+in @code{find-file}.  The buffer visiting the file is made unibyte,
+and its major mode is Fundamental mode, regardless of the file name.
+File local variable specifications in the file (@pxref{File Local
+Variables}) are ignored, and automatic decompression and adding a
+newline at the end of the file due to @code{require-final-newline}
+(@pxref{Saving Buffers, require-final-newline}) are also disabled.
 
 Note that if Emacs already has a buffer visiting the same file
 non-literally, it will not visit the same file literally, but instead
@@ -139,7 +147,7 @@ buffer and then read the file contents into it using
 @code{insert-file-contents-literally} (@pxref{Reading from Files}).
 @end deffn
 
-@defun find-file-noselect filename &optional nowarn rawfile wildcards
+@defun find-file-noselect filename &optional nowarn rawfile wildcards async
 This function is the guts of all the file-visiting functions.  It
 returns a buffer visiting the file @var{filename}.  You may make the
 buffer current or display it in a window if you wish, but this
@@ -157,7 +165,9 @@ Reading the file involves decoding the file's contents (@pxref{Coding
 Systems}), including end-of-line conversion, and format conversion
 (@pxref{Format Conversion}).  If @var{wildcards} is non-@code{nil},
 then @code{find-file-noselect} expands wildcard characters in
-@var{filename} and visits all the matching files.
+@var{filename} and visits all the matching files.  If @var{async} is
+non-@code{nil} and there are several matching files due to expansion
+of wildcard characters, every file will be loaded in an own thread.
 
 This function displays warning or advisory messages in various peculiar
 cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
@@ -191,7 +201,7 @@ various files.
 @end example
 @end defun
 
-@deffn Command find-file-other-window filename &optional wildcards
+@deffn Command find-file-other-window filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename}, but
 does so in a window other than the selected window.  It may use
 another existing window or split a window; see @ref{Switching
@@ -201,7 +211,7 @@ When this command is called interactively, it prompts for
 @var{filename}.
 @end deffn
 
-@deffn Command find-file-read-only filename &optional wildcards
+@deffn Command find-file-read-only filename &optional wildcards async
 This command selects a buffer visiting the file @var{filename}, like
 @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
 Buffers}, for related functions and variables.
@@ -219,6 +229,16 @@ the @code{find-file} commands ignore their @var{wildcards} argument
 and never treat wildcard characters specially.
 @end defopt
 
+@kindex C-x &
+@findex universal-async-argument
+@defopt execute-file-commands-asynchronously
+If this variable is non-@code{nil}, a file will be visited
+asynchronously when called interactively.  If it is a regular
+expression, it must match the file name to be visited.  This behavior
+is toggled by the command @kbd{C-x &} (@code{universal-async-argument})
+prior to the interactive call of the file visiting command.
+@end defopt
+
 @defopt find-file-hook
 The value of this variable is a list of functions to be called after a
 file is visited.  The file's local-variables specification (if any) will
@@ -3390,7 +3410,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},
@@ -3452,7 +3472,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},

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

@@ -22,7 +22,7 @@ define them.
 * Function Cells::              Accessing or setting the function definition
                             of a symbol.
 * Closures::                    Functions that enclose a lexical environment.
-* OClosures::                   Function objects with meta-data.
+* OClosures::                   Function objects
 * Advising Functions::          Adding to the definition of a function.
 * Obsolete Functions::          Declaring functions obsolete.
 * Inline Functions::            Functions that the compiler will expand inline.
@@ -593,8 +593,8 @@ symbol a function definition, its function cell is said to be
   In practice, nearly all functions have names, and are referred to by
 their names.  You can create a named Lisp function by defining a
 lambda expression and putting it in a function cell (@pxref{Function
-Cells}).  However, it is more common to use the @code{defun} macro,
-described in the next section.
+Cells}).  However, it is more common to use the @code{defun} special
+form, described in the next section.
 @ifnottex
 @xref{Defining Functions}.
 @end ifnottex
@@ -1586,69 +1586,56 @@ examining or altering the structure of closure objects.
 
 @node OClosures
 @section Open Closures
-@cindex oclosures
-@cindex open closures
 
-  Traditionally, functions are opaque objects which offer no other
-functionality but to call them.  (Emacs Lisp functions aren't fully
+Traditionally, functions are opaque objects which offer no other
+functionality but to call them.  Emacs Lisp functions aren't fully
 opaque since you can extract some info out of them such as their
 docstring, their arglist, or their interactive spec, but they are
-still mostly opaque.)  This is usually what we want, but occasionally
-we need functions to expose a bit more information about themselves.
+mostly opaque.  This is usually what we want, but occasionally we need
+functions to expose a bit more information about themselves.
 
-  @dfn{Open closures}, or @dfn{OClosures} for short, are function
-objects which carry additional type information and expose some
-information about themselves in the form of slots which you can access
+OClosures are functions which carry additional type information,
+and expose some information in the form of slots which you can access
 via accessor functions.
 
- OClosures are defined in two steps: first you use
-@code{oclosure-define} to define a new OClosure type by specifying the
-slots carried by the OClosures of this type, and then you use
-@code{oclosure-lambda} to create an OClosure object of a given type.
-
-Let's say we want to define keyboard macros, i.e.@: interactive
-functions which re-execute a sequence of key events (@pxref{Keyboard
-Macros}).  You could do it with a plain function as follows:
+They are defined in two steps: first @code{oclosure-define} is used to
+define new OClosure types by specifying the slots carried by those
+OClosures, and then @code{oclosure-lambda} is used to create an
+OClosure object of a given type.
 
+Say we want to define keyboard macros, i.e. interactive functions
+which re-execute a sequence of key events.  You could do it with
+a plain function as follows:
 @example
 (defun kbd-macro (key-sequence)
   (lambda (&optional arg)
     (interactive "P")
     (execute-kbd-macro key-sequence arg)))
 @end example
-
-@noindent
 But with such a definition there is no easy way to extract the
 @var{key-sequence} from that function, for example to print it.
 
 We can solve this problem using OClosures as follows.  First we define
 the type of our keyboard macros (to which we decided to add
 a @code{counter} slot while at it):
-
 @example
 (oclosure-define kbd-macro
   "Keyboard macro."
   keys (counter :mutable t))
 @end example
-
-@noindent
 After which we can rewrite our @code{kbd-macro} function:
-
 @example
 (defun kbd-macro (key-sequence)
   (oclosure-lambda (kbd-macro (keys key-sequence) (counter 0))
       (&optional arg)
-    (interactive "P")
+    (interactive "p")
     (execute-kbd-macro keys arg)
     (setq counter (1+ counter))))
 @end example
-
-@noindent
 As you can see, the @code{keys} and @code{counter} slots of the
 OClosure can be accessed as local variables from within the body
 of the OClosure.  But we can now also access them from outside of the
 body of the OClosure, for example to describe a keyboard macro:
-
 @example
 (defun describe-kbd-macro (km)
   (if (not (eq 'kbd-macro (oclosure-type km)))
@@ -1657,90 +1644,55 @@ body of the OClosure, for example to describe a keyboard macro:
           (counter (kbd-macro--counter km)))
       (message "Keys=%S, called %d times" keys counter))))
 @end example
-
-@noindent
 Where @code{kbd-macro--keys} and @code{kbd-macro--counter} are
-accessor functions generated by the @code{oclosure-define} macro for
-oclosures whose type is @code{kbd-macro}.
+accessor functions generated by the @code{oclosure-define} macro.
 
-@defmac oclosure-define oname &optional docstring &rest slots
+@defmac oclosure-define name &optional docstring &rest slots
 This macro defines a new OClosure type along with accessor functions
-for its @var{slots}.  @var{oname} can be a symbol (the name of the new
-type), or a list of the form
-@w{@code{(@var{oname} . @var{type-props})}}, in which case
-@var{type-props} is a list of additional properties of this oclosure
-type.  @var{slots} is a list of slot descriptions where each slot can
-be either a symbol (the name of the slot) or it can be of the form
-@w{@code{(@var{slot-name} . @var{slot-props})}}, where
-@var{slot-props} is a property list of the corresponding slot
-@var{slot-name}.
-The OClosure type's properties specified by @var{type-props} can
-include the following:
+for its slots.  @var{name} can be a symbol (the name of
+the new type), or a list of the form @code{(@var{name} . @var{type-props})} in
+which case @var{type-props} is a list of additional properties.
+@var{slots} is a list of slot descriptions where each slot can be
+either a symbol (the name of the slot) or it can be of the form
+@code{(@var{slot-name} . @var{slot-props})} where @var{slot-props} is
+a property list.
 
-@table @code
-@item (:predicate @var{pred-name})
-This requests creation of a predicate function named @var{pred-name}.
-This function will be used to recognize OClosures of the type
-@var{oname}.  If this type property is not specified,
-@code{oclosure-define} will generate a default name for the
-predicate.
-@item (:parent @var{otype})
-This makes type @var{otype} of OClosures be the parent of the type
-@var{oname}.  The OClosures of type @var{oname} inherit the
-@var{slots} defined by their parent type.
-@c FIXME: Is the above description of :parent correct?
-@item (:copier @var{copier-name} @var{copier-args})
-This causes the definition of a functional update function, knows as
-the @dfn{copier}, which takes an OClosure of type @var{oname} as its
-first argument and returns a copy of it with the slots named in
-@var{copier-args} modified to contain the value passed in the
-corresponding argument in the actual call to @var{copier-name}.
-@end table
+For each slot, the macro creates an accessor function named
+@code{@var{name}--@var{slot-name}}.  By default slots are immutable.
+If you need a slot to be mutable, you need to specify it with the
+@code{:mutable} slot property, after which it can be mutated for
+example with @code{setf}.
 
-For each slot in @var{slots}, the @code{oclosure-define} macro creates
-an accessor function named @code{@var{oname}--@var{slot-name}}; these
-can be used to access the values of the slots.  The slot definitions
-in @var{slots} can specify the following properties of the slots:
-
-@table @code
-@item :mutable @var{val}
-By default, slots are immutable, but if you specify the
-@code{:mutable} property with a non-@code{nil} value, the slot can be
-mutated, for example with @code{setf} (@pxref{Setting Generalized
-Variables}).
-@c FIXME: Some rationale and meaning of immutable slot is probably in
-@c order here.
-@item :type @var{val-type}
-This specifies the type of the values expected to appear in the slot.
-@c FIXME: What will happen if the value is of a different type? error?
-@end table
+Beside slot accessors, the macro can create a predicate and
+functional update functions according to @var{type-props}:
+a @code{(:predicate @var{pred-name})} in the @var{type-props} causes
+the definition of a predicate function under the name @var{pred-name},
+and @code{(:copier @var{copier-name} @var{copier-arglist})} causes the
+definition of a functional update function which takes an OClosure of
+type @var{name} as first argument and returns a copy of it with the
+slots named in @var{copier-arglist} modified to the value passed in the
+corresponding argument.
 @end defmac
 
 @defmac oclosure-lambda (type . slots) arglist &rest body
-This macro creates an anonymous OClosure of type @var{type}, which
-should have been defined with @code{oclosure-define}.  @var{slots}
-should be a list of elements of the form
-@w{@code{(@var{slot-name} @var{expr})}}.  At run time, each @var{expr}
-is evaluated, in order, after which the OClosure is created with its
-slots initialized with the resulting values.
+This macro creates an anonymous OClosure of type @var{type}.
+@var{slots} should be a list of elements of the form @code{(@var{slot-name}
+@var{exp})}.
+At run time, each @var{exp} is evaluated, in order, after which
+the OClosure is created with its slots initialized with the
+resulting values.
 
-When called as a function (@pxref{Calling Functions}), the OClosure
-created by this macro will accept arguments according to @var{arglist}
-and will execute the code in @var{body}.  @var{body} can refer to the
-value of any of its slot directly as if it were a local variable that
-had been captured by static scoping.
+When called as a function, the OClosure will accept arguments
+according to @var{arglist} and will execute the code in @var{body}.
+@var{body} can refer to the value of any of its slot directly as if it
+were a local variable that had been captured by static scoping.
 @end defmac
 
 @defun oclosure-type object
-This function returns the OClosure type (a symbol) of @var{object} if
-it is an OClosure, and @code{nil} otherwise.
+This function returns the OClosure type (a symbol) of @var{object} if it is an
+OClosure, and @code{nil} otherwise.
 @end defun
 
-One other function related to OClosures is
-@code{oclosure-interactive-form}, which allows some types of OClosures
-to compute their interactive forms dynamically.  @xref{Using
-Interactive, oclosure-interactive-form}.
-
 
 @node Advising Functions
 @section Advising Emacs Lisp Functions
@@ -2631,12 +2583,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 +2645,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

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/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
@@ -5137,10 +5117,10 @@ This anchor is a function that is called with 3 arguments: @var{node},
 @var{parent}, and @var{bol}, and returns the first non-whitespace
 character on the previous line.
 
-@item column-0
+@item point-min
 This anchor is a function that is called with 3 arguments: @var{node},
-@var{parent}, and @var{bol}, and returns the beginning of the current
-line, which is at column 0.
+@var{parent}, and @var{bol}, and returns the beginning of the buffer.
+This is useful as the beginning of the buffer is always at column 0.
 
 @item comment-start
 This anchor is a function that is called with 3 arguments: @var{node},

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
@@ -1290,22 +1288,12 @@ the remote connection has no associated user, it will instead return
 @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/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

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

@@ -98,7 +98,6 @@ This manual documents how to configure, use, and customize Eglot.
 * Eglot and LSP Servers::       How to work with language servers.
 * Using Eglot::                 Important Eglot commands and variables.
 * Customizing Eglot::           Eglot customization and advanced features.
-* Advanced server configuration::  Fine-tune a specific language server
 * Troubleshooting Eglot::       Troubleshooting and reporting bugs.
 * GNU Free Documentation License::  The license for this manual.
 * Index::
@@ -154,11 +153,11 @@ Use Eglot.
 
 Most Eglot facilities are integrated into Emacs features, such as
 ElDoc, Flymake, Xref, and Imenu.  However, Eglot also provides
-commands of its own, mainly to perform tasks by the language server,
-such as @kbd{M-x eglot-rename} (to rename an identifier across the
-entire project), @kbd{M-x eglot-format} (to reformat and reindent
-code), and some others.  @xref{Eglot Commands}, for the detailed list
-of Eglot commands.
+commands of its own, mainly to perform tasks by the LSP server, such
+as @kbd{M-x eglot-rename} (to rename an identifier across the entire
+project), @kbd{M-x eglot-format} (to reformat and reindent code), and
+some others.  @xref{Eglot Commands}, for the detailed list of Eglot
+commands.
 
 @item
 That's it!
@@ -227,10 +226,11 @@ This says to invoke @var{program} with zero or more arguments
 standard input and standard output streams.
 
 @item (@var{program} @var{args}@dots{} :initializationOptions @var{options}@dots{})
-@var{program} is invoked with @var{args} but @var{options} specifies
-how to construct the @samp{:initializationOptions} JSON object to pass
-the server on during the LSP handshake (@pxref{Advanced server
-configuration}).
+Like above, but with @var{options} specifying the options to be
+used for constructing the @samp{initializationOptions} JSON object for
+the server.  @var{options} can also be a function of one argument, in
+which case it will be called with the server instance as the argument,
+and should return the JSON object to use for initialization.
 
 @item (@var{host} @var{port} @var{args}@dots{})
 Here @var{host} is a string and @var{port} is a positive integer
@@ -465,10 +465,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 +713,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 +968,85 @@ mechanism.
 @cindex progress
 @item eglot-report-progress
 Set this variable to true if you'd like progress notifications coming
-from the language server to be handled as Emacs's progress reporting
+from the LSP server to be handled as Emacs's progress reporting
 facilities.
+
+@vindex eglot-workspace-configuration
+@cindex server workspace configuration
+@item eglot-workspace-configuration
+This variable is meant to be set in the @file{.dir-locals.el} file, to
+provide per-project settings, as described below in more detail.
 @end table
 
-@node Advanced server configuration
-@chapter Advanced server configuration
+Some language servers need to know project-specific settings, which
+the LSP calls @dfn{workspace configuration}.  Eglot allows such fine
+tuning of per-project settings via the variable
+@code{eglot-workspace-configuration}.  Eglot sends the settings in
+this variable to each server, and each server applies the portion of the
+settings relevant to it and ignores the rest.  These settings are
+communicated to the server initially (upon establishing the
+connection) or when the settings are changed, or in response to a
+configuration request from the server.
 
-Though many language servers work well out-of-the-box, most allow
-fine-grained control of their operation via specific configuration
-options that are transmitted over the LSP protocol and vary from
-server to server.  A small number of servers require such special
-configuration to work acceptably, or even to work at all.
+In many cases, servers can be configured globally using a
+configuration file in the user's home directory or in the project
+directory, which the language server reads.  For example, the
+@command{pylsp} server for Python reads the file
+@file{~/.config/pycodestyle} and the @command{clangd} server reads the
+file @file{.clangd} anywhere in the current project's directory tree.
+If possible, we recommend using those configuration files that are
+independent of Eglot and Emacs; they have the advantage that they will
+work with other LSP clients as well.
 
-After having setup a server executable program in
-@code{eglot-server-programs} (@pxref{Setting Up LSP Servers}) and
-ensuring Eglot can invoke it, you may want to take advantage of some
-of these options.  You should first distinguish two main kinds of
-server configuration:
-
-@itemize @bullet
-@item
-Project-specific, applying to a specific project;
-
-@item
-User-specific, applying to all projects the server is used for.
-@end itemize
-
-When you have decided which kind you need, the following sections
-teach how Eglot's user variables can be used to achieve it:
-
-@menu
-* Project-specific configuration::
-* User-specific configuration::
-* JSONRPC objects in Elisp::
-@end menu
-
-It's important to note that not all servers allow both kinds of
-configuration, nor is it guaranteed that user options can be copied
-over to project options, and vice-versa.  When in doubt, consult your
-language server's documentation.
-
-It's also worth noting that some language servers can read these
-settings from configuration files in the user's @code{HOME} directory
-or in a project's directory.  For example, the @command{pylsp} Python
-server reads the file @file{~/.config/pycodestyle} for user
-configuration.  The @command{clangd} C/C++ server reads both
-@file{~/.config/clangd/config.yaml} for user configuration and
-@file{.clangd} for project configuration.  It may be advantageous to
-use these mechanisms instead of Eglot's, as this will probably work
-with other LSP clients and may be easier to debug than options riding
-on the LSP wire.
-
-@node Project-specific configuration
-@section Project-specific configuration
-@vindex eglot-workspace-configuration
-@cindex workspace configuration
-
-To set project-specific settings, which the LSP specification calls
-@dfn{workspace configuration}, the variable
-@code{eglot-workspace-configuration} may be used.
-
-This variable is a directory-local variable (@pxref{Directory
-Variables, , Per-directory Local Variables, emacs, The GNU Emacs
-Manual}).  It's important to recognize that this variable really only
-makes sense when set directory-locally.  It usually does not make
-sense to set it file-locally or in a major-mode hook.
-
-The most common way to set @code{eglot-workspace-configuration } is
-using a @file{.dir-locals.el} file in the root of your project.  If
-you can't do that, you may also set it from Elisp code via the
-@code{dir-locals-set-class-variables} function.  (@pxref{Directory
-Local Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
-
-However you choose to set it, the variable's value is a plist
-(@pxref{Property Lists,,, elisp, GNU Emacs Lisp Reference Manual}) with
-the following format:
+If you do need to provide Emacs-specific configuration for a language
+server, we recommend defining the appropriate value in the
+@file{.dir-locals.el} file in the project's directory.  The value of
+this variable should be a property list of the following format:
 
 @lisp
- (@var{:server1} @var{plist1} @var{:server2} @var{plist2} @dots{})
+ (:@var{server} @var{plist}@dots{})
 @end lisp
 
 @noindent
-Here, @var{:server1} and @var{:server2} are keywords whose names
-identify the LSP language servers to target.  Consult server
-documentation to find out what name to use.  @var{plist1} and
-@var{plist2} are plists of options, possibly nesting other plists.
+Here @code{:@var{server}} identifies a particular language server and
+@var{plist} is the corresponding keyword-value property list of one or
+more parameter settings for that server, serialized by Eglot as a JSON
+object.  @var{plist} may be arbitrarily complex, generally containing
+other keyword-value property sublists corresponding to JSON subobjects.
+The JSON values @code{true}, @code{false}, @code{null} and @code{@{@}}
+are represented by the Lisp values @code{t}, @code{:json-false},
+@code{nil}, and @code{eglot-@{@}}, respectively.
 
 @findex eglot-show-workspace-configuration
 When experimenting with workspace settings, you can use the command
 @kbd{M-x eglot-show-workspace-configuration} to inspect and debug the
-value of this variable in its final JSON form, ready to be sent to the
-server (@pxref{JSONRPC objects in Elisp}).  This helper command works
-even before actually connecting to the server.
+JSON value to be sent to the server.  This helper command works even
+before actually connecting to the server.
 
-These variable's value doesn't take effect immediately.  That happens
-upon establishing the connection, in response to an explicit query
-from the server, or when issuing the command @kbd{M-x
-eglot-signal-didChangeConfiguration} which notifies the server during
-an ongoing Eglot session.
+Here's an example of defining the workspace-configuration settings for
+a project that uses two different language servers, one for Python,
+the other one for Go (presumably, the project is written in a
+combination of these two languages).  The server for Python in this
+case is @command{pylsp}, the server for Go is @command{gopls}.  The
+value of @code{eglot-workspace-configuration} in this case should be:
 
-@subsection Examples
+@lisp
+((python-mode
+  . ((eglot-workspace-configuration
+      . (:pylsp (:plugins (:jedi_completion (:include_params t
+                                             :fuzzy t)
+                           :pylint (:enabled :json-false)))))))
+ (go-mode
+  . ((eglot-workspace-configuration
+      . (:gopls (:usePlaceholders t))))))
+@end lisp
 
-For some users, setting @code{eglot-workspace-configuration} is a
-somewhat daunting task.  One of the reasons is having to manage the
-general Elisp syntax of per-mode directory-local variables, which uses
-alists (@pxref{Association Lists,,, elisp, GNU Emacs Lisp Reference
-Manual}), and the specific syntax of Eglot's variable, which uses
-plists.  Some examples are useful.
+@noindent
+This should go into the @file{.dir-locals.el} file in the project's
+root directory.  It sets up the value of
+@code{eglot-workspace-configuration} separately for each major mode.
 
-Let's say you want to configure two language servers to be used in a
-project written in a combination of the Python and Go languages.  You
-want to use the @command{pylsp} and @command{gopls} languages
-servers.  In the documentation of the servers in question (or in some
-other editor's configuration file, or in some blog article), you find
-the following configuration options in informal dotted-notation
-syntax:
-
-@example
-pylsp.plugins.jedi_completion.include_params: true
-pylsp.plugins.jedi_completion.fuzzy: true
-pylsp.pylint.enabled: false
-gopls.usePlaceholders: true
-@end example
-
-To apply this to Eglot, and assuming you chose the
-@file{.dir-locals.el} file method, the contents of that file could be:
+Alternatively, the same configuration could be defined as follows:
 
 @lisp
 ((nil
@@ -1083,189 +1054,61 @@ To apply this to Eglot, and assuming you chose the
       . (:pylsp (:plugins (:jedi_completion (:include_params t
                                              :fuzzy t)
                            :pylint (:enabled :json-false)))
-         :gopls (:usePlaceholders t)))))
- (python-mode . ((indent-tabs-mode . nil)))
- (go-mode     . ((indent-tabs-mode . t))))
+         :gopls (:usePlaceholders t))))))
 @end lisp
 
-@noindent
-This sets the value of @code{eglot-workspace-configuration} in all the
-buffers inside the project; each server will use only the section of
-the parameters intended for that server, and ignore the rest.  Note
-how alists are used for associating Emacs mode names with alists
-associating variable names with variable values.  Then notice how
-plists are used inside the value of
-@code{eglot-workspace-configuration}.
+This is an equivalent setup which sets the value for all the
+major-modes inside the project; each server will use only the section
+of the parameters intended for that server, and ignore the rest.
 
-This following form may also be used:
-
-@lisp
-((python-mode
-  . ((eglot-workspace-configuration
-      . (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))))
-     (indent-tabs-mode . nil)))
- (go-mode
-  . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders t)))
-     (indent-tabs-mode . t))))
-@end lisp
-
-@noindent
-This sets up the value of @code{eglot-workspace-configuration}
-separately depending on the major mode of each of that project's
-buffers.  @code{python-mode} buffers will have the variable set to
-@code{(:pylsp (:plugins ...))}.  @code{go-mode} buffers will have the
-variable set to @code{(:gopls (:usePlaceholders t))}.
-
-Some servers will issue workspace configuration for specific files
-inside your project.  For example, if you know @code{gopls} is asking
-about specific files in the @code{src/imported} subdirectory and you
-want to set a different option for @code{gopls.usePlaceholders} , you
-may use something like:
-
-@lisp
-((python-mode
-  . ((eglot-workspace-configuration
-      . (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))))
-     (indent-tabs-mode nil)))
- (go-mode
-  . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders t)))
-     (indent-tabs-mode t)))
- ("src/imported"
-   . ((eglot-workspace-configuration
-      . (:gopls (:usePlaceholders nil))))))
-@end lisp
+As yet another alternative, you can set the value of
+@code{eglot-workspace-configuration} programmatically, via the
+@code{dir-locals-set-class-variables} function, @pxref{Directory Local
+Variables,,, elisp, GNU Emacs Lisp Reference Manual}.
 
 Finally, if one needs to determine the workspace configuration based
 on some dynamic context, @code{eglot-workspace-configuration} can be
 set to a function.  The function is called with the
 @code{eglot-lsp-server} instance of the connected server (if any) and
 with @code{default-directory} set to the root of the project.  The
-function should return a plist suitable for use as the variable's
-value.
+function should return a value of the form described above.
 
-@node User-specific configuration
-@section User-specific configuration
-@cindex initializationOptions
-@cindex command-line arguments
+Some servers need special hand-holding to operate correctly.  If your
+server has some quirks or non-conformity, it's possible to extend
+Eglot via Elisp to adapt to it, by defining a suitable
+@code{eglot-initialization-options} method via @code{cl-defmethod}
+(@pxref{Generic Functions,,, elisp, GNU Emacs Lisp Reference Manual}).
 
-This kind of configuration applies to all projects the server is used
-for.  Here, there are a number of ways to do this inside Eglot.
-
-A common way is to pass command-line options to the server invocation
-via @code{eglot-server-programs}.  Let's say we want to configure
-where the @command{clangd} server reads its
-@code{compile_commands.json} from.  This can be done like so:
+Here's an example:
 
 @lisp
-(with-eval-after-load 'eglot
-  (add-to-list 'eglot-server-programs
-               `(c++-mode . ("clangd" "--compile-commands-dir=/tmp"))))
+(require 'eglot)
 
+(add-to-list 'eglot-server-programs
+             '((c++-mode c-mode) . (eglot-cquery "cquery")))
+
+(defclass eglot-cquery (eglot-lsp-server) ()
+  :documentation "A custom class for cquery's C/C++ langserver.")
+
+(cl-defmethod eglot-initialization-options ((server eglot-cquery))
+  "Passes through required cquery initialization options"
+  (let* ((root (car (project-roots (eglot--project server))))
+         (cache (expand-file-name ".cquery_cached_index/" root)))
+    (list :cacheDirectory (file-name-as-directory cache)
+          :progressReportFrequencyMs -1)))
 @end lisp
 
 @noindent
-Another way is to have Eglot pass a JSON object to the server during
-the LSP handshake.  This is done using the
-@code{:initializationOptions} syntax of @code{eglot-server-programs}:
-
-@lisp
-(with-eval-after-load 'eglot
-  (add-to-list 'eglot-server-programs
-               `(c++-mode . ("clangd" :initializationOptions
-                                      (:compilationDatabasePath "/tmp")))))
-@end lisp
-
-@noindent
-The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
-representation in plist format of a simple JSON object
-@code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @pxref{JSONRPC
-objects in Elisp}.
-
-In this case, the two examples achieve exactly the same, but notice
-how the option's name has changed between them.
-
-@vindex eglot-workspace-configuration
-Finally there is another way to do user-specific configuration of
-language servers, which may be used if the methods above are not
-supported.  It consists of @emph{globally} setting
-@code{eglot-workspace-configuration}, a variable originally intended
-for project-specific configuration.  This has the same effect as
-giving all your projects a certain default configuration, as described
-in @ref{Project-specific configuration}.  Here is an example:
-
-@lisp
-(setq-default eglot-workspace-configuration
-              '(:pylsp (:plugins (:jedi_completion (:include_params t
-                                                    :fuzzy t)
-                                  :pylint (:enabled :json-false)))
-                :gopls (:usePlaceholders t)))
-@end lisp
-
-Note that the global value of @code{eglot-workspace-configuration} is
-always overriden if a directory-local value is detected.
-
-@node JSONRPC objects in Elisp
-@section JSONRPC objects in Elisp
-
-Emacs's preferred way of representing JSON is via Lisp lists.  In
-Eglot, the syntax of this list is the simplest possible (the one with
-fewer parenthesis), a plist (@pxref{Property Lists,,, elisp, GNU Emacs
-Lisp Reference Manual}).
-
-The plist may be arbitrarily complex, and generally containing other
-keyword-value property sub-plists corresponding to JSON sub-objects.
-
-For representing the JSON leaf values @code{true}, @code{false},
-@code{null} and @code{@{@}}, you can use the Lisp values @code{t},
-@code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
-JSON arrays are represented as Elisp vectors surrounded by square brackets
-(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
-
-For example, the plist
-
-@lisp
-(:pylsp (:plugins (:jedi_completion (:include_params t
-                                     :fuzzy t
-                                     :cache_for ["pandas" "numpy"]
-                   :pylint (:enabled :json-false))))
- :gopls (:usePlaceholders t))
-@end lisp
-
-@noindent
-is serialized by Eglot to the following JSON text:
-
-@example
-@{
-  "pylsp": @{
-    "plugins": @{
-      "jedi_completion": @{
-        "include_params": true,
-        "fuzzy": true,
-        "cache_for": [ "pandas", "numpy" ],
-      @},
-      "pylint": @{
-        "enabled": false
-      @}
-    @}
-  @},
-  "gopls": @{
-    "usePlaceholders":true
-  @},
-@}
-@end example
+See the doc string of @code{eglot-initialization-options} for more
+details.
+@c FIXME: The doc string of eglot-initialization-options should be
+@c enhanced and extended.
 
 @node Troubleshooting Eglot
 @chapter Troubleshooting Eglot
 @cindex troubleshooting Eglot
 
-This chapter documents commands and variables that can be used to
+This section documents commands and variables that can be used to
 troubleshoot Eglot problems.  It also provides guidelines for
 reporting Eglot bugs in a way that facilitates their resolution.
 
@@ -1275,143 +1118,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

@@ -2,7 +2,7 @@
 @c %**start of header
 @setfilename ../../info/erc.info
 @settitle ERC Manual
-@set ERCVER 5.5
+@set ERCVER 5.4.1
 @set ERCDIST as distributed with Emacs @value{EMACSVER}
 @include docstyle.texi
 @syncodeindex fn cp
@@ -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

@@ -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},

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/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
@@ -18097,8 +18096,7 @@ evaluating untrusted code blocks by prompting for a confirmation.
 
 - =yes= ::
 
-  Org evaluates the source code, possibly asking permission according
-  to ~org-confirm-babel-evaluate~.
+  Org always evaluates the source code without asking permission.
 
 - =never= or =no= ::
 

doc/misc/texinfo.tex

@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2023-03-04.12}
+\def\texinfoversion{2023-01-02.21}
 %
 % Copyright 1985, 1986, 1988, 1990-2023 Free Software Foundation, Inc.
 %
@@ -2683,21 +2683,25 @@
 }
 \setregularquotes
 
-% output for ' in @code
-% in tt font hex 0D (undirected) or 27 (curly right quote)
+% Allow an option to not use regular directed right quote/apostrophe
+% (char 0x27), but instead the undirected quote from cmtt (char 0x0d).
+% The undirected quote is ugly, so don't make it the default, but it
+% works for pasting with more pdf viewers (at least evince), the
+% lilypond developers report.  xpdf does work with the regular 0x27.
 %
 \def\codequoteright{%
   \ifusingtt
       {\ifflagclear{txicodequoteundirected}%
           {\ifflagclear{codequoteundirected}%
               {'}%
-              {\char"0D }}%
-          {\char"0D }}%
+              {\char'15 }}%
+          {\char'15 }}%
       {'}%
 }
 
-% output for ` in @code
-% in tt font hex 12 (grave accent) or 60 (curly left quote)
+% and a similar option for the left quote char vs. a grave accent.
+% Modern fonts display ASCII 0x60 as a grave accent, so some people like
+% the code environments to do likewise.
 % \relax disables Spanish ligatures ?` and !` of \tt font.
 %
 \def\codequoteleft{%
@@ -2705,8 +2709,8 @@
       {\ifflagclear{txicodequotebacktick}%
           {\ifflagclear{codequotebacktick}%
               {\relax`}%
-              {\char"12 }}%
-          {\char"12 }}%
+              {\char'22 }}%
+          {\char'22 }}%
       {\relax`}%
 }
 
@@ -2725,7 +2729,7 @@
     \errmessage{Unknown @codequoteundirected value `\temp', must be on|off}%
   \fi\fi
 }
-
+%
 \parseargdef\codequotebacktick{%
   \def\temp{#1}%
   \ifx\temp\onword
@@ -2740,11 +2744,6 @@
   \fi\fi
 }
 
-% Turn them on by default
-\let\SETtxicodequoteundirected = t
-\let\SETtxicodequotebacktick = t
-
-
 % [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font.
 \def\noligaturesquoteleft{\relax\lq}
 
@@ -2930,6 +2929,10 @@
      \let-\dashnobreak
      \let_\realunder
     \fi
+    % Given -foo (with a single dash), we do not want to allow a break
+    % after the hyphen.
+    \global\let\codedashprev=\codedash
+    %
     \codex
   }
   %
@@ -2939,30 +2942,21 @@
     %
     % Now, output a discretionary to allow a line break, unless
     % (a) the next character is a -, or
-    % (b) the preceding character is a -, or
-    % (c) we are at the start of the string.
-    % In both cases (b) and (c), \codedashnobreak should be set to \codedash.
-    %
+    % (b) the preceding character is a -.
     % E.g., given --posix, we do not want to allow a break after either -.
     % Given --foo-bar, we do want to allow a break between the - and the b.
     \ifx\next\codedash \else
-      \ifx\codedashnobreak\codedash
+      \ifx\codedashprev\codedash
       \else \discretionary{}{}{}\fi
     \fi
     % we need the space after the = for the case when \next itself is a
     % space token; it would get swallowed otherwise.  As in @code{- a}.
-    \global\let\codedashnobreak= \next
+    \global\let\codedashprev= \next
   }
 }
 \def\normaldash{-}
 %
-\def\codex #1{\tclose{%
-  % Given -foo (with a single dash), we do not want to allow a break
-  % after the -.  \codedashnobreak is set to the first character in
-  % @code.
-  \futurelet\codedashnobreak\relax
-  #1%
-}\endgroup}
+\def\codex #1{\tclose{#1}\endgroup}
 
 \def\codeunder{%
   % this is all so @math{@code{var_name}+1} can work.  In math mode, _
@@ -3956,23 +3950,33 @@
 
 \def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting
 
-% Set the page number to 1.
+% When we turn headings on, set the page number to 1.
 \def\pageone{
   \global\pageno=1
   \global\arabiccount = \pagecount
 }
 
-\let\contentsalignmacro = \chappager
-
-% \def\HEADINGSon{\HEADINGSdouble} % defined by \CHAPPAGon
-
 % For double-sided printing, put current file name in lower left corner,
 % chapter name on inside top of right hand pages, document
 % title on inside top of left hand pages, and page numbers on outside top
 % edge of all pages.
-\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdouble}
-\let\HEADINGSdoubleafter=\HEADINGSafter
 \def\HEADINGSdouble{%
+\pageone
+\HEADINGSdoublex
+}
+\let\contentsalignmacro = \chappager
+
+% For single-sided printing, chapter title goes across top left of page,
+% page number on top right.
+\def\HEADINGSsingle{%
+\pageone
+\HEADINGSsinglex
+}
+% \def\HEADINGSon{\HEADINGSdouble} % defined by \CHAPPAGon
+
+\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
+\let\HEADINGSdoubleafter=\HEADINGSafter
+\def\HEADINGSdoublex{%
 \global\evenfootline={\hfil}
 \global\oddfootline={\hfil}
 \global\evenheadline={\line{\folio\hfil\thistitle}}
@@ -3982,10 +3986,8 @@
 \global\let\contentsalignmacro = \chapoddpage
 }
 
-% For single-sided printing, chapter title goes across top left of page,
-% page number on top right.
-\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsingle}
-\def\HEADINGSsingle{%
+\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
+\def\HEADINGSsinglex{%
 \global\evenfootline={\hfil}
 \global\oddfootline={\hfil}
 \global\evenheadline={\line{\thischapter\hfil\folio}}
@@ -3997,6 +3999,7 @@
 
 % for @setchapternewpage off
 \def\HEADINGSsinglechapoff{%
+\pageone
 \global\evenfootline={\hfil}
 \global\oddfootline={\hfil}
 \global\evenheadline={\line{\thischapter\hfil\folio}}
@@ -4102,7 +4105,6 @@
     \nobreak\kern\dimen0
     \endgroup
     \itemxneedsnegativevskiptrue
-    \penalty 10021 % for \indexpar
   \fi
 }
 
@@ -4219,7 +4221,6 @@
    % We can be in inner vertical mode in a footnote, although an
    % @itemize looks awful there.
   }%
-  \penalty 10021 % for \indexpar
   \flushcr
 }
 
@@ -4724,11 +4725,13 @@
 % except not \outer, so it can be used within macros and \if's.
 \edef\newwrite{\makecsname{ptexnewwrite}}
 
-% \newindex {IX} defines an index named IX.
+% \newindex {foo} defines an index named IX.
 % It automatically defines \IXindex such that
 % \IXindex ...rest of line... puts an entry in the index IX.
 % It also defines \IXindfile to be the number of the output channel for
 % the file that accumulates this index.  The file's extension is IX.
+% The name of an index should be no more than 2 characters long
+% for the sake of vms.
 %
 \def\newindex#1{%
   \expandafter\chardef\csname#1indfile\endcsname=0
@@ -4784,17 +4787,11 @@
 % and it is the two-letter name of the index.
 
 \def\doindex#1{\edef\indexname{#1}\parsearg\doindexxxx}
-\def\doindexxxx #1{\indexpar\doind{\indexname}{#1}}
+\def\doindexxxx #1{\doind{\indexname}{#1}}
 
 % like the previous two, but they put @code around the argument.
 \def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx}
-\def\docodeindexxxx #1{\indexpar\docind{\indexname}{#1}}
-
-% End any open paragraph, unless we are immediately after @item in
-% @itemize or @enumerate.
-\def\indexpar{%
-\ifnum\lastpenalty=10021 \else\endgraf\fi
-}
+\def\docodeindexxxx #1{\docind{\indexname}{#1}}
 
 
 % \definedummyword defines \#1 as \string\#1\space, thus effectively
@@ -4992,7 +4989,7 @@
   \commondummyword\ampchar          {\normalamp}%
   \commondummyword\atchar           {\@}%
   \commondummyword\arrow            {->}%
-  \commondummyword\backslashchar    {\realbackslash}%
+  \commondummyword\backslashchar    {}%
   \commondummyword\bullet           {bullet}%
   \commondummyword\comma            {,}%
   \commondummyword\copyright        {copyright}%
@@ -5092,6 +5089,9 @@
   %
   % We need to get rid of all macros, leaving only the arguments (if present).
   % Of course this is not nearly correct, but it is the best we can do for now.
+  % makeinfo does not expand macros in the argument to @deffn, which ends up
+  % writing an index entry, and texindex isn't prepared for an index sort entry
+  % that starts with \.
   %
   % Since macro invocations are followed by braces, we can just redefine them
   % to take a single TeX argument.  The case of a macro invocation that
@@ -5351,9 +5351,7 @@
 % ..., ready, GO:
 %
 \def\safewhatsit#1{\ifhmode
-  \whatsitpenalty = \lastpenalty
   #1%
-  \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
  \else
   % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
   \whatsitskip = \lastskip
@@ -7389,7 +7387,6 @@
 \def\setupverb{%
   \tt
   \def\par{\leavevmode\endgraf}%
-  \parindent = 0pt
   \setcodequotes
   \tabeightspaces
   % Respect line breaks,
@@ -7565,6 +7562,11 @@
   \exdentamount=\defbodyindent
 }
 
+\newtoks\defidx
+\newtoks\deftext
+
+\def\useindex#1{\defidx={#1}\ignorespaces}
+
 % Called as \printdefunline \deffooheader{text}
 %
 \def\printdefunline#1#2{%
@@ -7572,6 +7574,10 @@
     \plainfrenchspacing
     % call \deffooheader:
     #1#2 \endheader
+    % create the index entry
+    \defcharsdefault
+    \edef\temp{\noexpand\doind{\the\defidx}{\the\deftext}}%
+    \temp
     % common ending:
     \interlinepenalty = 10000
     \advance\rightskip by 0pt plus 1fil\relax
@@ -7586,24 +7592,6 @@
 
 \def\Edefun{\endgraf\medbreak}
 
-% @defblock, @defline do not automatically create index entries
-\envdef\defblock{%
-  \startdefun
-}
-\let\Edefblock\Edefun
-
-\def\defline{%
-  \doingtypefnfalse
-  \parseargusing\activeparens{\printdefunline\deflineheader}%
-}
-\def\deflineheader#1 #2 #3\endheader{%
-  \defname{#1}{}{#2}\magicamp\defunargs{#3\unskip}%
-}
-\def\deftypeline{%
-  \doingtypefntrue
-  \parseargusing\activeparens{\printdefunline\deflineheader}%
-}
-
 % \makedefun{deffoo} (\deffooheader parameters) { (\deffooheader expansion) }
 %
 % Define \deffoo, \deffoox  \Edeffoo and \deffooheader.
@@ -7655,18 +7643,23 @@
   \fi\fi
 }
 
+\def\defind#1#2{
+  \defidx={#1}%
+  \deftext={#2}%
+}
+
 % Untyped functions:
 
 % @deffn category name args
 \makedefun{deffn}#1 #2 #3\endheader{%
-  \doind{fn}{\code{#2}}%
+  \defind{fn}{\code{#2}}%
   \defname{#1}{}{#2}\magicamp\defunargs{#3\unskip}%
 }
 
 % @defop category class name args
 \makedefun{defop}#1 {\defopheaderx{#1\ \putwordon}}
 \def\defopheaderx#1#2 #3 #4\endheader{%
-  \doind{fn}{\code{#3}\space\putwordon\ \code{#2}}%
+  \defind{fn}{\code{#3}\space\putwordon\ \code{#2}}%
   \defname{#1\ \code{#2}}{}{#3}\magicamp\defunargs{#4\unskip}%
 }
 
@@ -7674,7 +7667,7 @@
 
 % @deftypefn category type name args
 \makedefun{deftypefn}#1 #2 #3 #4\endheader{%
-  \doind{fn}{\code{#3}}%
+  \defind{fn}{\code{#3}}%
   \doingtypefntrue
   \defname{#1}{#2}{#3}\defunargs{#4\unskip}%
 }
@@ -7682,7 +7675,7 @@
 % @deftypeop category class type name args
 \makedefun{deftypeop}#1 {\deftypeopheaderx{#1\ \putwordon}}
 \def\deftypeopheaderx#1#2 #3 #4 #5\endheader{%
-  \doind{fn}{\code{#4}\space\putwordon\ \code{#1\ \code{#2}}}%
+  \defind{fn}{\code{#4}\space\putwordon\ \code{#1\ \code{#2}}}%
   \doingtypefntrue
   \defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
 }
@@ -7691,14 +7684,14 @@
 
 % @deftypevr category type var args
 \makedefun{deftypevr}#1 #2 #3 #4\endheader{%
-  \doind{vr}{\code{#3}}%
+  \defind{vr}{\code{#3}}%
   \defname{#1}{#2}{#3}\defunargs{#4\unskip}%
 }
 
 % @deftypecv category class type var args
 \makedefun{deftypecv}#1 {\deftypecvheaderx{#1\ \putwordof}}
 \def\deftypecvheaderx#1#2 #3 #4 #5\endheader{%
-  \doind{vr}{\code{#4}\space\putwordof\ \code{#2}}%
+  \defind{vr}{\code{#4}\space\putwordof\ \code{#2}}%
   \defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
 }
 
@@ -7715,7 +7708,7 @@
 
 % @deftp category name args
 \makedefun{deftp}#1 #2 #3\endheader{%
-  \doind{tp}{\code{#2}}%
+  \defind{tp}{\code{#2}}%
   \defname{#1}{}{#2}\defunargs{#3\unskip}%
 }
 
@@ -8587,87 +8580,6 @@
   \fi \macnamexxx}
 
 
-% @linemacro
-
-\parseargdef\linemacro{%
-  \linegetargs#1 \linegetargs
-  \expandafter\linegetparamlist\argl;%
-  \begingroup \macrobodyctxt \usembodybackslash
-  \parselinemacrobody
-}
-
-% Parse the arguments to a @linemacro line.  Set \macname to the name
-% of the macro and \argl to the list of arguments.
-\def\linegetargs#1 #2\linegetargs{%
-  \macname={#1}%
-  \def\argl{#2}%
-}
-
-% Build up \paramlist which will be used as the parameter text for the macro.
-% At the end it will be like "#1 #2 #3\endlinemacro".
-\def\linegetparamlist#1;{%
-  \paramno=0\def\paramlist{}%
-  \let\hash\relax \let\xeatspaces\relax
-  \linegetparamlistxxx#1; %
-}
-\def\linegetparamlistxxx#1 {%
-  \if#1;\let\next=\linegetparamlistxxxx
-  \else \let\next=\linegetparamlistxxx
-    \advance\paramno by 1
-    \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
-        {\noexpand\xeatspaces{\hash\the\paramno}}%
-    \edef\paramlist{\paramlist\hash\the\paramno\space}%
-  \fi\next}
-\def\linegetparamlistxxxx{%
-  \ifx\paramlist\empty
-     \def\paramlist{\hash 1\endlinemacro}%
-  \else
-    \expandafter\fixparamlist\paramlist\fixparamlist
-  \fi
-}
-% Replace final space token
-\def\fixparamlist#1 \fixparamlist{%
-  \def\paramlist{#1\endlinemacro}%
-}
-
-% Read the body of the macro, replacing backslash-surrounded variables
-%
-{\catcode`\ =\other\long\gdef\parselinemacrobody#1@end linemacro{%
-\let\xeatspaces\relax
-\xdef\macrobody{#1}%
-\endgroup
-\linemacrodef
-}}
-
-% Make the definition
-\def\linemacrodef{%
-  \let\hash=##%
-  \let\xeatspaces\relax
-  \expandafter\xdef\csname\the\macname\endcsname{%
-    \bgroup
-    \noexpand\scanctxt
-    \noexpand\parsearg
-    \expandafter\noexpand\csname\the\macname @@\endcsname
-  }
-  \expandafter\xdef\csname\the\macname @@\endcsname##1{%
-    \egroup
-    \expandafter\noexpand
-    \csname\the\macname @@@\endcsname##1 \noexpand\endlinemacro
-    % Note that we append a space to the macro line to terminate the last
-    % argument in case the final argument is empty.  @xeatspaces may be needed
-    % to remove this space.
-  }
-  \expandafter\expandafter
-  \expandafter\xdef
-  \expandafter\expandafter\csname\the\macname @@@\endcsname\paramlist{%
-    \newlinechar=13 % split \macrobody into lines
-    \let\noexpand\xeatspaces\noexpand\eatspaces
-    \noexpand\scantokens{\macrobody}%
-  }
-}
-
-
-
 % @alias.
 % We need some trickery to remove the optional spaces around the equal
 % sign.  Make them active and then expand them all to nothing.

doc/misc/tramp.texi

@@ -938,16 +938,6 @@ be used.
 
 This method does not support user names.
 
-@item @option{flatpak}
-@cindex method @option{flatpak}
-@cindex @option{flatpak} method
-
-Integration of Flatpak sandboxes.  The host name may be either an
-application ID, a sandbox instance ID, or a PID, as returned by
-@samp{flatpak ps}.
-
-This method does not support user names.
-
 @end table
 
 
@@ -1257,7 +1247,6 @@ syntax requires a leading volume (share) name, for example:
 
 @item @option{dav}
 @item @option{davs}
-@cindex WebDAV
 @cindex method @option{dav}
 @cindex method @option{davs}
 @cindex @option{dav} method
@@ -1514,10 +1503,8 @@ access and it has the most reasonable security protocols, use
 @end example
 
 If @option{ssh} is unavailable for whatever reason, look for other
-obvious options.  For MS Windows, try the @option{plink}
-method@footnote{This shouldn't be needed with recent @code{OpenSSH}
-versions for MS Windows.  Use method @option{sshx}.}.  For Kerberos,
-try @option{krlogin}.
+obvious options.  For MS Windows, try the @option{plink} method.  For
+Kerberos, try @option{krlogin}.
 
 For editing local files as @option{su} or @option{sudo} methods, try
 the shortened syntax of @samp{root}:
@@ -2393,11 +2380,10 @@ This uses also the settings in @code{tramp-sh-extra-args}.
 @vindex RemoteCommand@r{, ssh option}
 @strong{Note}: If you use an @option{ssh}-based method for connection,
 do @emph{not} set the @option{RemoteCommand} option in your
-@command{ssh} configuration to something like @command{screen}.  If
-used, @option{RemoteCommand} must open an interactive shell on the
-remote host.  On the other hand, some @option{ssh}-based methods, like
-@option{sshx} or @option{scpx}, silently overwrite a
-@option{RemoteCommand} option of the configuration file.
+@command{ssh} configuration, for example to @command{screen}.  On the
+other hand, some @option{ssh}-based methods, like @option{sshx} or
+@option{scpx}, silently overwrite a @option{RemoteCommand} option of
+the configuration file.
 
 
 @subsection Other remote shell setup hints
@@ -2742,7 +2728,6 @@ entry, @option{Seconds between keepalives} option.  Set this to 5.
 There is no counter which could be set.
 
 
-@anchor{Using ssh connection sharing}
 @subsection Using ssh connection sharing
 
 @vindex ControlPath@r{, ssh option}
@@ -2772,33 +2757,20 @@ allows you to set the @option{ControlPath} provided the variable
 Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as
 @samp{%%r}, @samp{%%h} and @samp{%%p}.
 
-@vindex tramp-use-connection-share
-Using a predefined string in @code{tramp-ssh-controlmaster-options},
-or puzzling an own string, happens only when user option
-@code{tramp-use-connection-share} is set to @code{t}.  If the
-@file{~/.ssh/config} file is configured appropriately for the above
-behavior, then any changes to @command{ssh} can be suppressed with
-this @code{nil} setting:
+@vindex tramp-use-ssh-controlmaster-options
+If the @file{~/.ssh/config} file is configured appropriately for the
+above behavior, then any changes to @command{ssh} can be suppressed
+with this @code{nil} setting:
 
 @lisp
-(customize-set-variable 'tramp-use-connection-share nil)
+(customize-set-variable 'tramp-use-ssh-controlmaster-options nil)
 @end lisp
 
-Sometimes, it is not possible to use OpenSSH's @option{ControlMaster}
-option for remote processes.  This could result in concurrent access
-to the OpenSSH socket when reading data by different processes, which
-could block Emacs.  In this case, setting
-@code{tramp-use-connection-share} to @code{suppress} disables shared
-access.  It is not needed to set this user option permanently to
-@code{suppress}, binding the user option prior calling
-@code{make-process} is sufficient.  @value{tramp} does this for
-esxample for compilation processes on its own.
-
 @vindex ProxyCommand@r{, ssh option}
 @vindex ProxyJump@r{, ssh option}
-@code{tramp-use-connection-share} should also be set to @code{nil} or
-@code{suppress} if you use the @option{ProxyCommand} or
-@option{ProxyJump} options in your @command{ssh} configuration.
+This should also be set to @code{nil} if you use the
+@option{ProxyCommand} or @option{ProxyJump} options in your
+@command{ssh} configuration.
 
 In order to use the @option{ControlMaster} option, @value{tramp} must
 check whether the @command{ssh} client supports this option.  This is
@@ -2820,16 +2792,12 @@ Host *
 Check the @samp{ssh_config(5)} man page whether these options are
 supported on your proxy host.
 
-On MS Windows, @code{tramp-use-connection-share} is set to @code{nil}
-by default, because the MS Windows and MSYS2 implementations of
-@command{OpenSSH} do not support this option properly.
+On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to
+@code{nil} by default, because the MS Windows and MSYS2
+implementations of @command{OpenSSH} do not support this option properly.
 
-In PuTTY, you can achieve connection sharing in the
-@option{Connection/SSH} entry, enabling the @option{Share SSH
-connections if possible} option.  @code{tramp-use-connection-share}
-must be set to @code{nil}.  If @code{tramp-use-connection-share} is
-set to @code{t} or @code{suppress}, @command{plink} is called with the
-option @option{-share} or @option{-noshare}, respectively.
+In PuTTY, you can achieve connection sharing in the @option{Connection/SSH}
+entry, enabling the @option{Share SSH connections if possible} option.
 
 
 @subsection Configure direct copying between two remote servers
@@ -2879,19 +2847,11 @@ When @value{tramp} uses direct remote copying, password caches are not
 consulted.
 
 
-@subsection Issues with Cygwin and MS Windows ssh
+@subsection Issues with Cygwin ssh
 @cindex cygwin, issues
-@cindex ms Windows, issues
 
 This section is incomplete.  Please share your solutions.
 
-@cindex ms windows and @command{ssh}
-@cindex ms windows and @command{ssh-agent}
-
-MS Windows' @command{ssh} does not open a remote TTY@.  Use the method
-@option{sshx} or @option{scpx} instead.  Furthermore, it cannot read a
-passphrase for ssh private keys.  Use the MS @code{ssh-agent}.
-
 @cindex method @option{sshx} with cygwin
 @cindex @option{sshx} method with cygwin
 
@@ -2931,15 +2891,13 @@ Windows file names to Cygwin file names.
 @cindex @env{SSH_AUTH_SOCK} and emacs on ms windows
 @vindex SSH_AUTH_SOCK@r{, environment variable}
 
-When using the cygwin @command{ssh-agent} on MS Windows for
-password-less interaction, @option{ssh} methods depend on the
-environment variable @env{SSH_AUTH_SOCK}.  But this variable is not
-set when Emacs is started from a Desktop shortcut and authentication
-fails.
+When using the @command{ssh-agent} on MS Windows for password-less
+interaction, @option{ssh} methods depend on the environment variable
+@env{SSH_AUTH_SOCK}.  But this variable is not set when Emacs is
+started from a Desktop shortcut and authentication fails.
 
-One workaround is to use an MS Windows based SSH Agent, such as the
-native MS @command{ssh-agent} or @command{Pageant}.  The latter is
-part of the PuTTY Suite of tools.
+One workaround is to use an MS Windows based SSH Agent, such as
+@command{Pageant}.  It is part of the PuTTY Suite of tools.
 
 The fallback is to start Emacs from a shell.
 
@@ -3213,11 +3171,6 @@ auto-saved files to the same directory as the original file.
 Alternatively, set the user option @code{tramp-auto-save-directory}
 to direct all auto saves to that location.
 
-@c Since Emacs 30.
-@vindex remote-file-name-inhibit-auto-save
-If you want to suppress auto-saving of remote files at all, set user
-option @code{remote-file-name-inhibit-auto-save} to non-@code{nil}.
-
 @c Since Emacs 29.
 @vindex remote-file-name-inhibit-auto-save-visited
 An alternative to @code{auto-save-mode} is
@@ -4333,10 +4286,9 @@ It does not use @code{tramp-remote-path}.
 In order to gain even more performance, it is recommended to bind
 @code{tramp-verbose} to 0 when running @code{make-process} or
 @code{start-file-process}.  Furthermore, you might set
-@code{tramp-use-connection-share} to @code{nil} in order to bypass
-@value{tramp}'s handling of the @option{ControlMaster} options, and
-use your own settings in @file{~/.ssh/config}, @ref{Using ssh
-connection sharing}.
+@code{tramp-use-ssh-controlmaster-options} to @code{nil} in order to
+bypass @value{tramp}'s handling of the @option{ControlMaster} options,
+and use your own settings in @file{~/.ssh/config}.
 
 
 @node Cleanup remote connections
@@ -4377,6 +4329,7 @@ Flushes the current buffer's remote connection objects, the same as in
 Flushes all active remote connection objects, the same as in
 @code{tramp-cleanup-connection}.  This command removes also ad-hoc
 proxy definitions (@pxref{Ad-hoc multi-hops}).
+
 @end deffn
 
 @deffn Command tramp-cleanup-all-buffers
@@ -4385,20 +4338,6 @@ connections and ad-hoc proxy definition are cleaned up in addition to
 killing all buffers related to remote connections.
 @end deffn
 
-@deffn Command tramp-cleanup-some-buffers
-Similar to @code{tramp-cleanup-all-buffers}, where all remote
-connections and ad-hoc proxy definition are cleaned up.  However,
-additional buffers are killed only if one of the functions in
-@code{tramp-cleanup-some-buffers-hook} returns @code{t}.
-@end deffn
-
-@defopt tramp-cleanup-some-buffers-hook
-The functions in this hook determine, whether a remote buffer is
-killed when @code{tramp-cleanup-some-buffers} is called.  Per default,
-remote buffers which are linked to a remote file, remote @code{dired}
-buffers, and buffers related to a remote process are cleaned up.
-@end defopt
-
 
 @node Renaming remote files
 @section Renaming remote files
@@ -4947,36 +4886,6 @@ Disable file locks.  Set @code{remote-file-name-inhibit-locks} to
 @code{t} if you know that different Emacs sessions are not modifying
 the same remote file.
 
-@item
-@vindex remote-file-name-inhibit-auto-save
-Keep auto-save files local.  This is already the default configuration
-in Emacs, don't change it.  If you want to disable auto-saving for
-remote files at all, set @code{remote-file-name-inhibit-auto-save} to
-@code{t}, but think about the consequences!
-
-If you want to disable auto-saving just for selected connections, for
-example due to security considerations, use connection-local variables
-in order to set @code{buffer-auto-save-file-name}.  If you, for
-example, want to disable auto-saving for all @option{sudo}
-connections, apply the following code.
-@ifinfo
-@xref{Connection Variables, , , emacs}.
-@end ifinfo
-
-@lisp
-@group
-(connection-local-set-profile-variables
-  'my-auto-save-profile
-  '((buffer-auto-save-file-name . nil)))
-@end group
-
-@group
-(connection-local-set-profiles
- '(:application tramp :protocol "sudo")
- 'my-auto-save-profile)
-@end group
-@end lisp
-
 @item
 Disable excessive traces.  Set @code{tramp-verbose} to 3 or lower,
 default being 3.  Increase trace levels temporarily when hunting for
@@ -5291,7 +5200,6 @@ HISTFILE=/dev/null
 @item
 Where are remote files trashed to?
 
-@vindex remote-file-name-inhibit-delete-by-moving-to-trash
 Emacs can trash file instead of deleting
 @ifinfo
 them, @ref{Misc File Ops, Trashing , , emacs}.

doc/misc/transient.texi

@@ -2566,20 +2566,6 @@ currently exist.
 
 Yes, see @code{transient-display-buffer-action} in @ref{Configuration}.
 
-@anchor{How can I copy text from the popup buffer?}
-@appendixsec How can I copy text from the popup buffer?
-
-To be able to mark text in any transient popup buffer using the mouse,
-you have to add the following binding.  Note that the region won't be
-visualized, while doing so.  After you have quit the transient popup,
-you will be able to yank it another buffer.
-
-@lisp
-(keymap-set transient-predicate-map
-            "<mouse-set-region>"
-            #'transient--do-stay)
-@end lisp
-
 @anchor{Why did some of the key bindings change?}
 @appendixsec Why did some of the key bindings change?
 

etc/EGLOT-NEWS

@@ -1,602 +0,0 @@
-Eglot NEWS                                                     -*- outline -*-
-
-Copyright (C) 2018-2023 Free Software Foundation, Inc.
-See the end of the file for license conditions.
-
-Please send Eglot bug reports to 'bug-gnu-emacs@gnu.org', and Cc (or
-X-Debbugs-CC) the maintainer 'joaotavora@gmail.com' as well.  Please
-read the chapter titled "Troubleshooting" in the Eglot manual,
-available https://joaotavora.github.io/eglot/#Troubleshooting-Eglot
-
-This file is about changes in Eglot, the Emacs client for LSP
-(Language Server Protocol) distributed with GNU Emacs since Emacs
-version 29.1 and with GNU ELPA since 2018.
-
-Note: references to some Eglot issues are presented as "github#nnnn".
-This refers to https://github.com/joaotavora/eglot/issues/.  That is,
-to look up issue github#1234, go to
-https://github.com/joaotavora/eglot/issues/1234.
-
-
-* Changes in Eglot 1.15 (29/4/2023)
-
-** Fix LSP "languageId" detection
-
-Many servers today support multiple languages, meaning they can handle
-more than one file type in the same connection.  This relies on the
-client supplying a ':languageId' string.  Previously, Eglot calculated
-this string based on an imperfect heuristic and was often wrong.  See
-github#1206.
-
-** Fix problems with missing signature documentation (bug#62687)
-
-** Reworked 'eglot-imenu'
-
-Eglot's Imenu backend (used for M-x imenu among other extensions), has
-been reworked.  Most newer servers respond to
-'textDocument/documentSymbol' with a vector of 'DocumentSymbol', not
-'SymbolInformation'.  It's not worth it trying to make the two formats
-resemble each other.  This also lays groundwork supporting a
-forthcoming "breadcrumb" feature of bug#58431.
-
-** New command 'eglot-update'
-
-This allows users to easily update to the latest version of Eglot.
-
-
-* Changes in Eglot 1.14 (3/4/2023)
-
-** Faster, more responsive completion
-
-Eglot takes advantage of LSP's "isIncomplete" flag in responses to
-completion requests to drive new completion-caching mechanism for the
-duration of each completion session.  Once a full set of completions
-is obtained for a given position, the server needn't be contacted in
-many scenarios, resulting in significantly less communication
-overhead.  This works with the popular Company package and stock
-completion-at-point interfaces.
-
-A variable 'eglot-cache-session-completions', t by default, controls
-this.  The mechanism was tested with ccls, jdtls, pylsp, golsp and
-clangd.  Notably, the C/C++ language server Clangd version 15 has a
-bug in its "isIcomplete" flag (it is fixed in later versions).  If you
-run into problems, disable this mechanism like so:
-
-(add-hook 'c-common-mode-hook
-   (lambda () (setq-local eglot-cache-session-completions nil)))
-
-** At-point documentation less obtrusive in echo area
-
-Eglot takes advantage of new features of ElDoc to separate short
-documentation strings from large ones, sending the former to be shown in
-the ElDoc's echo area and the latter to be shown in other outlets,
-such as the *eldoc* buffer obtainable with 'C-h .'.
-
-** New variable 'eglot-prefer-plaintext'
-
-Customize this to t to opt-in to docstrings in plain text instead of
-Markdown.
-
-(bug#61373)
-
-** Progress indicators inhabit the mode-line by default
-
-To switch to the echo area, customize 'eglot-report-progress' to
-'messages'.  To switch off progress reporting completely, set to nil.
-
-** Snippet support is easier to enable
-
-The user needn't manually activate 'yas-minor-mode' or
-'yas-global-mode'.  If YASnippet is installed and the server supports
-snippets, it is used automatically, unless the symbol 'yasnippet' has
-been added to 'eglot-stay-out-of'.
-
-
-* Changes in Eglot 1.13 (15/03/2023)
-
-** ELPA installations on Emacs 26.3 are supported again.
-
-
-* Changes in Eglot 1.12.29 (Eglot bundled with Emacs 29.1)
-
-** Eglot can upgrade itself to the latest version.
-
-The new command 'eglot-upgrade-eglot' works around behaviour in the
-existing 'package-install' command and the new 'package-upgrade'
-command which would prevent the user from easily grabbing the latest
-version as usual.
-
-
-* Changes in Eglot 1.12 (13/03/2023)
-
-** LSP inlay hints are now supported.
-Inlay hints are small text annotations 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.
-Emacs can display these hints using overlays, helping the user
-remember those types and parameter names.
-
-** Longstanding Tramp instability issues solved.
-The solution involves a Tramp-specific workaround in Eglot.  Future
-Tramp versions will have this problem solved at the origin.  The
-workaround will then be removed.  Emacs bug#61350 has more details.
-
-(github#859, github#1020, github#883)
-
-** LSP's 'positionEncoding' capability is now supported.
-The position-encoding scheme (UTF-8, UTF-16 or UTF-32) can now
-be negotiated with the server.
-
-** More of the user's Eldoc configuration is respected.
-This change addresses the problems reported in many Eglot reports
-dating back to early 2021 at least.
-
-(github#646, github#894, github#920, github#1031, github#1171).
-
-This is unfinished work, as 'eldoc-documentation-strategy' is still
-set by Eglot during its tenure over a buffer.  The default value for
-it cannot work reasonably with Eglot's additions to
-'eldoc-documentation-functions'.
-
-** Completion labels are correctly displayed in servers like clangd.
-
-(github#1141)
-
-** Assorted bugfixes.
-
-(bug#61312, bug#61478, bug#61532, bug#61726, bug#61866, bug#61748)
-
-
-* Changes in Eglot 1.11 (27/1/2023)
-
-** New server vscode-json-languageserver added to 'eglot-server-programs'.
-
-(bug#60198)
-
-** Assorted bugfixes.
-
-(bug#60379, bug#60557, (bug#61048)
-
-
-* Changes in Eglot 1.10 (16/12/2022)
-
-** Emacs progress reporters are used for LSP progress notifications.
-(bug#59149)
-
-** LSP reported URIs other than file:// are passed on to Emacs.
-This change allows other URI handlers, such as a 'jar:' handling
-package, to cooperate with Eglot and find files inside compressed file
-systems (bug#58790).
-
-** Eglot now shows in the menu bar.
-
-** Tree-sitter modes added to 'eglot-server-programs'.
-These modes are usually handled by the same server that handles the
-"classical mode".
-
-** New servers csharp-ls and texlab added to 'eglot-server-programs'.
-
-** Assorted bugfixes.
-(bug#59824, bug#59338)
-
-
-* Changes in Eglot 1.9 (8/10/2022)
-
-This is the last release before integration into Emacs's core.
-
-** New 'M-x eglot-list-connections' command.
-Probably not very useful for now.  More keybindings and clickable
-shortcuts to connection-specific commands to be added later.
-
-** Manual temporarily lives in separate MANUAL.md file.
-The manual has been rewritten mostly from scratch.  It is structured
-hierarchically and is more complete.  After the merge into Emacs, the
-Eglot Texinfo manual bundled with Emacs used this temporary manual as
-a starting point.
-
-** Support for "single server, multiple modes".
-Previously, if an entry such as '((c++-mode c-mode) . ("clangd)")' was
-found in 'eglot-server-programs', it meant that '.cpp' files '.c'
-files would lead to two 'clangd' instances for managing them, even if
-these files were in the same project.  Now only one is created.  It is
-assumed that most, if not all, servers configured in
-'eglot-server-programs' handle this correctly.
-
-(github#681)
-
-** 'eglot-imenu' no longer uses problematic "special elements".
-Though Eglot's 'eglot-imenu' returned a fully compliant 'imenu'
-structure, that object was not understood by many other frontends
-other than 'M-x imenu' itself.  Since the special functionality it
-enabled wasn't being used anyway, it was decided to remove it to fix
-these longstanding problems.
-
-(github#758, github#536, github#535)
-
-** 'eglot-workspace-configuration' has been overhauled.
-This variable and its uses are now more thoroughly documented.  It can
-be set to a function for dynamic calculation of the configuration.
-The preferred format is a plist, though the earlier alist format is
-still supported.
-
-(github#967, github#590, github#790)
-
-** 'C-u M-.' lists and completes arbitrary workspace symbols.
-A very old request, now made possible by a relatively recent change to
-the 'workspace/symbol' RPC method.
-
-(github#131)
-
-** Reworked mode-line menus.
-New menus help discover Eglot's features and show which of them are
-supported by the current server.  Menus can be customized away via
-'eglot-menu-string', making space in mode-line.
-
-(github#792)
-
-** Easier to use LSP 'initialize.initializationOptions'.
-In 'eglot-server-programs' a plist may be appended to the usual list
-of strings passed as command line arguments.  The value of its
-':initializationOptions' key constructs the corresponding LSP JSON
-object.  This may be easier than creating a 'defclass' for a specific
-server and specializing 'eglot-initialization-options' to that class.
-
-(github#901, github#845, github#940)
-
-** LSP on-type formatting is now supported.
-This is the 'documentOnTypeFormattingProvider' LSP capability, which
-may be disabled via 'eglot-ignored-server-capabilities'
-
-(github#899)
-
-** Basic LSP "workspace folders" support added.
-Eglot now advertises 'project-root' and 'project-external-roots' as
-workspace-folders.  (Configuring 'project-vc-external-roots-function'
-via Elisp or 'tags-table-list' via Custtomize are two ways to set the
-external roots of a simple git project.)
-
-(github#893)
-
-** Eglot can now show project wide diagnosics via Flymake.
-Some LSP servers report diagnostics for all files in the current
-workspace.  Flymake has (as of version 1.2.1) the option to show
-diagnostics from buffers other than the currently visited one.  The
-command 'M-x flymake-show-project-diagnostics' will now show all the
-diagnostics relevant to a workspace.
-
-(github#810)
-
-** Support LSP completion tags.
-An LSP completion tag can be used to tell the editor how to render a
-completion.  Presently, one kind of tag exists, denoting its
-corresponding completion as obsolete.
-
-(github#797)
-
-** Support LSP optional diagnostic tags.
-A diagnostic tag can indicate either "unused or unnecessary code" or
-"deprecated or obsolete code".  Following the rendering suggestions in
-the protocol, we fade out unnecessary code and strike-through
-deprecated code.
-
-(github#794)
-
-** The Rust language server is now rust-analyzer by default.
-Eglot will now prefer starting "rust-analyzer" to "rls" when it is
-available.  The special support code for RLS has been removed.
-
-(github#803)
-
-** New servers have been added to 'eglot-server-programs'.
-- clojure-lsp (github#813)
-- racket-langserver (github#694)
-- futhark lsp (github#922)
-- purescript-language-server (github#905)
-- Perl::LanguageServer (github#952)
-- marksman (github#1013)
-- jedi-language-server ([#994](github#994))
-
-
-* Changes in Eglot 1.8 (12/1/2022)
-
-** Alternate servers supported out-of-box for the same major mode.
-In practice, this removes the need for Eglot to "officially" bless one
-server over another.
-
-Do not confuse this feature with another missing feature which
-consists of supporting multiple servers simultaneously managing a
-major mode within a project.
-
-(github#688)
-
-** TRAMP support added.
-There are no variables to customize: visit a remote file, ensure the
-server also exists in the remote, and type "M-x eglot".
-
-(github#637, github#463, github#84)
-
-** 'eglot-ignored-server-capabilities' is now correctly spelled.
-This user-visible variable used to be spelled
-'eglot-ignored-server-capabilites', which is still a valid but
-obsolete name.
-
-(github#724)
-
-** Eglot can manage cross-referenced files outside project.
-This is activated by a new customization option
-'eglot-extend-to-xref', which defaults to nil.
-
-(github#76, github#686, github#695)
-
-** Code action shortcuts can be added by the user.
-'M-x eglot-code-actions' accepts an optional 'action-kind' argument,
-specified interactively with 'C-u'.  Other shortcuts call specific
-actions directly ('eglot-code-action-inline',
-'eglot-code-action-extract', 'eglot-code-action-rewrite',
-'eglot-code-action-organize-imports' and
-'eglot-code-action-quickfix').  One can create one's own shortcuts for
-code actions with specific a kind by calling 'eglot-code-actions' from
-Lisp.
-
-(github#411)
-
-** New command 'eglot-shutdown-all added.
-This disconnects all the Eglot connections in the user's session.
-
-(github#643)
-
-** New variable 'eglot-withhold-process-id' added.
-If non-nil, Eglot will not send the Emacs process ID to the language
-server.  This can be useful when using docker to run a language
-server.
-
-(github#722)
-
-** Several new servers have been added to 'eglot-server-programs'.
-- cmake-language-server (github#787)
-- css-languageserver (github#204, github#769)
-- fortls (github#603)
-- html-languageserver (github#204, github#769)
-- json-languageserver (github#204, github#769)
-- lua-lsp (github#721)
-- mint ls (github#750)
-- pyright (github#742)
-- vim-language-server (github#787)
-- yaml-language-server (github#751)
-- zls (github#646)
-
-
-* Changes in Eglot 1.7 (16/12/2020)
-
-** Hierarchical symbols are supported in Imenu.
-(github#303).
-
-** Multiple "documentation at point" sources are supported.
-Such sources include as LSP's signature, hover and also the Flymake
-diagnostic messages.  They can all be presented in the echo area
-(space permitting), or via 'C-h .'.  For now, composition of different
-sources can be customized using 'eldoc-documentation-strategy',
-'eldoc-echo-area-use-multiline-p' and 'eldoc-prefer-doc-buffer'.
-
-The variables 'eglot-put-doc-in-help-buffer' and
-'eglot-auto-display-help-buffer' have been removed.
-
-(github#439, github#494, github#481, github#454)
-
-
-* Changes in Eglot 1.6 (16/04/2020)
-
-** Column offset calculation is now LSP-conformant.
-It seems the majority of servers now comply with the language server
-specification when it comes to handling non-ASCII texts.  Therefore
-the default values of 'eglot-move-to-column-function' and
-'eglot-current-column-function' have been changed.  Consult the
-documentation of these variables for how to restore the old behavior.
-
-(github#361)
-
-** LSP workspace/configuration requests are supported.
-Also a new section "Per-project server configuration" in the README.md
-should answer some FAQ's in this regard.
-
-(github#326)
-
-
-* Changes in Eglot 1.5 (20/10/2019)
-
-** Eglot takes over Company configuration.
-Similar to what was already the case with Flymake, Eldoc and Xref, use
-just the backend that can do something useful in Eglot,
-'company-capf'.  See 'eglot-stay-out-of' to opt out of this.
-
-(github#324)
-
-** New option 'eglot-autoshutdown' added.
-This disconnects the server after last managed buffer is killed.
-
-(github#217, github#270)
-
-** Completion support has been fixed.
-Among other things, consider LSP's "filterText" cookies, which enable
-a kind of poor-man's flex-matching for some backends.
-
-(github#235, github#313, github#311, github#279)
-
-** Supports LSP's "goto declaration/implementation/typeDefinition".
-
-(github#302)
-
-** New option 'eglot-send-changes-idle-time' added.
-
-(github#258)
-
-** Eglot's Eldoc no longer flickers when moving around.
-
-(github#198)
-
-** Large docs shown in help buffer instead of echo area by default.
-Also add two new customization variables
-'eglot-put-doc-in-help-buffer' and 'eglot-auto-display-help-buffer'.
-
-(github#198)
-
-** Built-in support for Go, Elixir and Ada added.
-
-(github#304, github#264, github#316)
-
-
-* Changes in Eglot 1.4 (5/1/2019)
-
-** Parameter highlighting in the first line of signature corrected.
-
-** Markdown documentation strings are rendered with faces.
-Eglot uses 'gfm-view-mode' for this.
-
-** Hard dependencies on Flymake have been removed.
-The user can turn Flymake off now in buffers managed by Eglot.
-
-** Connection hooks are run with proper directory local variables.
-This fixes issues with suspiciously empty 'didChangeConfiguration'
-messages that are supposed to communicate parameters from a
-directory-set 'eglot-workspace-configuration'.
-
-(github#196)
-
-** Completion sorting has been fixed.
-If the server returns completions in some sensible order, Eglot will
-keep it.
-
-(github#190)
-
-** Flymake and Eldoc taken over completely while managing buffers.
-No longer try to add Eglot's facilities to existing facilities in
-these two domains.
-
-
-* Changes in Eglot 1.3 (10/12/2018)
-
-** Provide strict checking of incoming LSP messagesp.
-
-(github#144, github#156)
-
-** Add brief context after 'xref-find-references' when available.
-
-(github#52)
-
-** Support 'completionContext' to help servers like 'ccls'.
-
-** Use Flymake from GNU ELPA.
-
-(github#178)
-
-
-* Changes in Eglot 1.2 (23/11/2018)
-
-** Support snippet completions.
-Eglot uses 'yasnippet.el' for this, if it is installed.
-
-(github#50)
-
-** 'workspace/didChangeConfiguration' implemented.
-
-(github#29)
-
-** Handle experimental/unknown server methods gracefully.
-
-(github#39)
-
-** Accept functions as entries in 'eglot-server-programs'.
-'CONTACT' in the '(MAJOR-MODE . CONTACT)' association in
-'eglot-server-programs' can now be a function of no arguments
-producing any value previously valid for a contact.  Functions can be
-interactive or non-interactive.
-
-(github#63)
-
-** Improve completion to be snappier and don't hinder typing.
-
-(github#61)
-
-** Consider ':triggerCharacters' in company completion.
-
-(github#80)
-
-** Add support for LSP 'TextEdit' objects in completion.
-
-** Prefer ccls over cquery for C/C++
-
-(github#94)
-
-** 'eglot-ignored-server-capabilites' is more user-friendly.
-
-(github#126)
-
-** Supports asynchronous connections.
-If a connection to the server is taking too long, is will continue in
-the background.  A new defcustom 'eglot-sync-connect' controls this
-feature.
-
-(github#68)
-
-** The 'eglot-shutdown' command prompts for the server to shutdown.
-
-(github#73)
-
-** Add support for the Eclipse JDT language server.
-
-(github#63)
-
-** Add out-of-the-box support for Haskell, Kotlin, Go, Ocaml, R.
-
-** Add the ability to move to LSP-precise columns.
-Some servers like 'clangd' follow the UTF-16-based spec very closely
-here.
-
-(github#124)
-
-** Fix a potential security issue fontifying LSP doc.
-
-(github#154)
-
-** Fix many, many bugs
-
-(github#44, github#48, github#54, github#58, github#64, github#74,
- github#81, github#82, github#86, github#87, github#83, github#93,
- github#100, github#115, github#120, github#121, github#126,
- github#138, github#144, github#158, github#160, github#167)
-
-
-* Changes in Eglot 1.1 (9/7/2018)
-
-** Implement TCP autostart/autoconnect (and support Ruby's Solargraph).
-The ':autoport' symbol in the server incovation is replaced
-dynamically by a local port believed to be vacant, so that the ensuing
-TCP connection finds a listening server.
-
-** Eglot now depends on Emacs library 'jsonrpc.el'.
-
-
-----------------------------------------------------------------------
-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/>.
-
-
-Local Variables:
-bug-reference-bug-regexp: "\\(\\(github\\|bug\\)#\\([0-9]+\\)\\)"
-bug-reference-url-format: eglot--debbugs-or-github-bug-uri
-paragraph-separate: "[	 ]"
-End:
-

etc/ERC-NEWS

@@ -11,210 +11,6 @@ This file is about changes in ERC, the powerful, modular, and
 extensible IRC (Internet Relay Chat) client distributed with
 GNU Emacs since Emacs version 22.1.
 
-
-* Changes in ERC 5.6
-
-** Module 'keep-place' now offers a visual indicator.
-Remember your place in ERC buffers a bit more easily while retaining
-the freedom to look around.  Optionally sync the indicator to any
-progress made when you haven't yet caught up to the live stream.  See
-options 'erc-keep-place-indicator-style' and friends and new module
-'keep-place-indicator', which for now must be added manually to
-'erc-modules'.
-
-** Module 'fill' now offers a style based on 'visual-line-mode'.
-This fill style mimics the "hanging indent" look of 'erc-fill-static'
-and provides some movement and editing commands to optionally tame the
-less familiar aspects of 'visual-line' behavior.  An interactive
-helper called 'erc-fill-wrap-nudge' allows for dynamic "refilling" of
-buffers on the fly.  Set 'erc-fill-function' to 'erc-fill-wrap' to get
-started.
-
-** A unified interactive entry point.
-New users are often dismayed to discover that M-x ERC doesn't connect
-to its default network, Libera.Chat, over TLS.  Though perhaps a
-decade overdue, this is no longer the case.  Other UX improvements in
-this area aim to make the process of connecting interactively slightly
-more streamlined and less repetitive, even for veteran users.
-
-** Revised buffer-display handling for interactive commands.
-A point of friction for new users and one only just introduced with
-ERC 5.5 has been the lack of visual feedback when first connecting via
-M-x erc or when issuing a "/JOIN" command at the prompt.  As explained
-below, in the news for 5.5, the discovery of a security issue led to
-most new ERC buffers being "buried" on creation.  On further
-reflection, this was judged to have been an overcorrection in the case
-of interactive invocations, hence the borrowing of an old option,
-'erc-query-display', and the bestowing of a new alias,
-'erc-interactive-display', which better describes its expanded role as
-a more general buffer-display knob for interactive commands ("/QUERY"
-still among them).
-
-Accompanying this addition are "display"-suffixed aliases for related
-options 'erc-join-buffer' and 'erc-auto-query', which users have
-reported as being difficult to discover and remember.  When the latter
-option (now known as 'erc-receive-query-display') is nil, ERC uses
-'erc-join-buffer' in its place, much like it does for
-'erc-interactive-display'.  The old nil behavior can still be gotten
-via the new compatibility flag 'erc-receive-query-display-defer'.
-
-** Setting a module's mode variable via Customize earns a warning.
-Trying and failing to activate a module via its minor mode's Custom
-widget has been an age-old annoyance for new users.  Previously
-ineffective, this method now actually works, but it also admonishes
-users to edit the 'erc-modules' widget instead.
-
-** The option 'erc-timestamp-use-align-to' is more versatile.
-While this option has always offered to right-align stamps via the
-'display' text property, it's now more effective at doing so when set
-to a number indicating an offset from the right edge.  And when set to
-the symbol 'margin', it displays stamps in the right margin, although,
-at the moment, this is mostly intended for use by other modules, such
-as 'fill-wrap', described above.  For both these variants, users of
-the 'log' module may want to customize 'erc-log-filter-function' to
-'erc-stamp-prefix-log-filter' to avoid ragged right-hand stamps
-appearing in their saved logs.
-
-** Smarter reconnect handling for users on the move.
-ERC now offers a new, experimental reconnect strategy in the function
-'erc-server-delayed-check-reconnect', which tests for underlying
-connectivity before attempting to reconnect in earnest.  See options
-'erc-server-reconnect-function' and 'erc-nickname-in-use-functions' to
-get started.
-
-** Easily constrain all ERC-related business to a dedicated frame.
-The option 'erc-reuse-frames' can now be set to 'displayed', which
-tells ERC to show new buffers in frames already occupied by buffers
-from the same connection.  This customization depends on the option
-'erc-buffer-display' (formerly 'erc-join-buffer') being set to
-'frame'.  If you find the name 'displayed' unhelpful, please suggest
-an alternative by writing to the mailing list.
-
-** Some keybindings are now set by modules rather than their libraries.
-To put it another way, simply loading a built-in module's library no
-longer modifies 'erc-mode-map'.  Instead, modifications occur during
-module setup.  This should not impact most user configs since ERC
-doesn't bother with keys already taken and only removes bindings it's
-previously created.  Note that while all affected bindings still
-reside in 'erc-mode-map', future built-in modules will use their own
-minor-mode maps, and new third-party modules should do the same.
-
-** The option 'erc-timestamp-format-right' has been deprecated.
-Having to account for this option prevented other ERC modules from
-easily determining what right-hand stamps would look like before
-insertion, which is knowledge needed for certain UI decisions.  The
-way ERC has chosen to address this is imperfect and boils down to
-asking users who've customized this option to switch to
-'erc-timestamp-format' instead.  If you're affected by this and feel
-that some other solution, like automatic migration, is justified,
-please make that known on the bug list.
-
-** The 'nicknames' entry in 'erc-button-alist' is officially exceptional.
-It's no secret that the 'buttons' module treats potential nicknames
-specially.  To simplify ERC's move to next-gen "rich UI" extensions,
-this special treatment is being canonized.  From now on, all values
-other than the symbol 'erc-button-buttonize-nicks' appearing in the
-"FORM" field (third element) of this entry are considered deprecated
-and will incur a warning.
-
-** Option 'erc-query-on-unjoined-chan-privmsg' restored and renamed.
-This option was accidentally removed from the default client in ERC
-5.5 and was thus prevented from influencing PRIVMSG routing.  It's now
-been restored with a slightly revised role contingent on a few
-assumptions explained in its doc string.  For clarity, it has been
-renamed 'erc-ensure-target-buffer-on-privmsg'.
-
-** Miscellaneous UX changes.
-Some minor quality-of-life niceties have finally made their way to
-ERC.  For example, the function 'erc-echo-timestamp' is now
-interactive and can be invoked on any message to view its timestamp in
-the echo area.  The command 'erc-button-previous' now moves to the
-beginning instead of the end of buttons.  And the 'irccontrols' module
-now supports additional colors and special handling for "spoilers"
-(hidden text).
-
-** Changes in the library API.
-
-*** Some top-level dependencies have been removed.
-The library 'erc-goodies' is no longer loaded by ERC's main library.
-This was done to further cement the move toward a unidirectional
-dependency flow begun in 5.5.  Additionally, a few barely used and
-newly introduced dependencies are now lazily loaded, which may upset
-some third-party code.  The first of these is 'pp' because its
-'pp-to-string' is autoloaded in all supported ERC versions.  Also gone
-are 'thingatpt', 'time-date', and 'iso8601'.  All were used ultra
-sparingly, and the latter two have only been around for one minor
-release cycle, so their removal hopefully won't cause much churn.
-
-*** Some ERC-applied text properties have changed.
-Chiefly, 'rear-sticky' has been replaced by 'erc-command', which
-records the IRC command (or numeric) associated with a message.  Less
-impactfully, the value of the 'field' property for ERC's prompt has
-changed from 't' to the more useful 'erc-prompt', although the
-property of the same name has been retained.
-
-*** ERC now manages timestamp-related properties a bit differently.
-For starters, the 'cursor-sensor-functions' property no longer
-contains unique closures and thus no longer proves effective for
-traversing messages.  To compensate, a new property, 'erc-timestamp',
-now spans message bodies but not the newlines delimiting them.
-Somewhat relatedly, the function 'erc-insert-aligned' has been
-deprecated and removed from the primary client code path.
-
-*** The role of a module's Custom group is now more clearly defined.
-Associating built-in modules with Custom groups and provided library
-features has improved.  More specifically, a module's group now enjoys
-the singular purpose of determining where the module's minor mode
-variable lives in the Customize interface.  And although ERC is now
-slightly more adept at linking these entities, third-parties are still
-encouraged to keep a module's name aligned with its group's as well as
-the provided feature of its containing library, if only for the usual
-reasons of namespace hygiene and discoverability.
-
-*** ERC now supports arbitrary CHANTYPES.
-Specifically, channels can be prefixed with any predesignated
-character, mainly to afford more flexibility to specialty services,
-like bridges to other protocols.
-
-*** 'erc-cmd-HELP' recognizes subcommands.
-Some IRC "slash" commands are hierarchical and require users to
-specify a subcommand to actually carry out anything of consequence.
-Built-in modules can now provide more detailed help for a particular
-subcommand by telling ERC to defer to a specialized handler.
-
-*** Longtime quasi modules have been made proper.
-The 'fill' module is now defined by 'define-erc-module'.  The same
-goes for ERC's imenu integration, which has 'imenu' now appearing in
-the default value of 'erc-modules'.
-
-*** Prompt input is split before 'erc-pre-send-functions' has a say.
-Hook members are now treated to input whose lines have already been
-adjusted to fall within the allowed length limit.  For convenience,
-third-party code can request that the final input be "re-filled" prior
-to being sent.  See doc string for details.
-
-*** ERC's prompt survives the insertion of user input and messages.
-Previously, ERC's prompt and its input marker disappeared while
-running hooks during message insertion, and the position of its
-"insert marker" (ERC's per-buffer process mark) was inconsistent
-during these spells.  To make insertion handling more predictable in
-preparation for incorporating various protocol extensions, the prompt
-and its bounding markers have become perennial fixtures.  In rare
-cases, these changes may mean third-party code needs tweaking, for
-example, requiring the use of 'insert-before-markers' instead of
-'insert'.  As always, users feeling unduly inconvenienced by these
-changes are encouraged to voice their concerns on the bug list.
-
-*** Miscellaneous changes
-Two helper macros from GNU ELPA's Compat library are now available to
-third-party modules as 'erc-compat-call' and 'erc-compat-function'.
-In the area of buttons, 'Info-goto-node' has been supplanted by plain
-old 'info' in 'erc-button-alist', and the bracketed "<URL:...>"
-pattern entry has been removed because it was more or less redundant.
-And the "TAB" key is now bound to a new command, 'erc-tab', that only
-calls 'completion-at-point' when point is in the input area and
-module-specific commands, like 'erc-button-next', otherwise.
-
 
 * Changes in ERC 5.5
 
@@ -248,13 +44,8 @@ The 'networks' module is now all but required for everyday interactive
 use.  A default member of 'erc-modules' since ERC 5.3, 'networks' has
 grown increasingly integral to core client operations over the years.
 From now on, only the most essential operations will be officially
-supported in its absence, and users will see a warning upon invoking
-an entry point, like 'erc-tls', when that's the case.
-
-On a related note, the function 'erc-network' now always returns
-non-nil in buffers created by a successfully established IRC
-connection, even after that connection has been closed.  This was done
-to aid the overall effort to improve buffer association.
+supported in its absence, and users will see a warning upon
+entry-point invocation when it's not present.
 
 ** Tighter auth-source integration.
 The days of hit-and-miss auth-source queries are hopefully behind us.
@@ -286,14 +77,12 @@ now avoids any hijacking of the active window as well.
 
 Beyond this, additional flexibility is now available for controlling
 the behavior of newly created target buffers during reconnection.
-See the option 'erc-reconnect-display' for more.
 
 ** Improved handling of multiline prompt input.
 This means better detection and handling of intervening and trailing
 blanks when 'erc-send-whitespace-lines' is active.  New options have
 also been added for warning when input spans multiple lines.  Although
-off by default, new users are encouraged to enable them.  See options
-'erc-inhibit-multiline-input' and 'erc-ask-about-multiline-input'.
+off by default, new users are encouraged to enable them.
 
 ** URL handling has improved.
 Clicking on 'irc://' and 'ircs://' links elsewhere in Emacs now does
@@ -302,21 +91,6 @@ users are now prompted to confirm connection parameters prior to lift
 off.  See the new '(erc) Integrations' section in the Info manual for
 details.
 
-** ERC's major-mode hook now runs slightly later.
-The function 'erc-open' now delays running 'erc-mode-hook' until ERC's
-prompt and its bounding markers and many essential local variables
-have been initialized.  Those essentials include the familiar
-'erc-default-recipients', 'erc-server-users', and 'erc-network', as
-well as the various "session" variables, like 'erc-session-connector'.
-ERC activates "local modules" immediately afterward, just before
-running 'erc-connect-pre-hook', which is still useful for gaining a
-full accounting of what's been set.
-
-In similar news, 'erc-open' no longer calls 'erc-update-modules'.
-However, it still activates modules in a similar fashion, meaning,
-among other things, global-module setup still occurs before major-mode
-activation (something that's here to stay for compatibility reasons).
-
 ** Miscellaneous behavioral changes impacting the user experience.
 A bug has been fixed that saw prompts being mangled, doubled, or
 erased in server buffers upon disconnection.  Instead, input prompts
@@ -325,61 +99,58 @@ now collapse into an alternate form designated by the option
 but can be fine-tuned via the repurposed, formerly abandoned option
 'erc-hide-prompt'.
 
-Another fix-turned-feature involves certain commands provided by the
-'erc-match' module, such as 'erc-add-keyword', 'erc-add-pal', and
-others, which now optionally offer to 'regexp-quote' the current
-input.  The old behavior, if desired, can still be had via the new
-option 'erc-match-quote-when-adding'.
+Certain commands provided by the 'erc-match' module, such as
+'erc-add-keyword', 'erc-add-pal', and others, now optionally ask
+whether to 'regexp-quote' the current input.  A new option,
+'erc-match-quote-when-adding', has been added to allow for retaining
+the old behavior, if desired.
 
-In 5.4, support for using network symbols as keys was added for
+A bug has been fixed affecting users of the Soju bouncer: outgoing
+messages during periods of heavy traffic no longer disappear.
+
+Although rare, server passwords containing white space are now handled
+correctly.
+
+** Miscellaneous behavioral changes in the library API.
+A number of core macros and other definitions have been moved to a new
+file called erc-common.el.  This was done to further lessen the
+various complications arising from the mutual dependency between 'erc'
+and 'erc-backend'.
+
+ERC now relies on the Compat library from GNU ELPA to supply forward
+compatibility shims for users running older versions of Emacs.  The
+required Compat version resides atop ERC's main library file, in the
+'Package-Requires' header.  Third-party ERC modules will benefit
+automatically from this adoption.
+
+The function 'erc-network' always returns non-nil in server and target
+buffers belonging to a successfully established IRC connection, even
+after that connection has been closed.  (Also see the note in the
+section above about the 'networks' module basically being mandatory.)
+
+In 5.4, support for network symbols as keys was added for
 'erc-autojoin-channels-alist'.  This has been extended to include
 explicit symbols passed to 'erc-tls' and 'erc' as so-called
 network-context identifiers via a new ':id' keyword.  The latter
 carries wider significance beyond autojoin and can be used for
 unequivocally identifying a connection in a human-readable way.
 
-A number of UX-centric bug fixes accompany this release.  For example,
-spaces are now possible in server passwords, and users of the Soju
-bouncer should no longer see outgoing messages pile up during periods
-of heavy traffic.  See the Emacs change log for the full complement.
+The function 'erc-auto-query' was deemed too difficult to reason
+through and has thus been deprecated with no public replacement; it
+has also been removed from the client code path.
 
-** Miscellaneous behavioral changes in the library API.
-A number of core macros and other definitions have been moved to a new
-file called erc-common.el.  This was done to help mitigate various
-complications arising from the mutual dependency between 'erc' and
-'erc-backend'.
+The function 'erc-open' now delays running 'erc-mode-hook' members
+until most local session variables have been initialized (minus those
+connection-related ones in erc-backend).  'erc-open' also no longer
+calls 'erc-update-modules', although modules are still activated
+in an identical fashion.
 
-Also on the maintainability front, ERC now relies on the Compat
-library from GNU ELPA to supply forward compatibility shims for users
-running older versions of Emacs.  The required Compat version resides
-atop ERC's main library file, in the 'Package-Requires' header.
-Third-party modules should benefit automatically from its adoption.
+Some groundwork has been laid for what may become a new breed of ERC
+module, namely, "connection-local" (or simply "local") modules.
 
-In an effort to help further tame ERC's complexity, the variable
-'erc-default-recipients' is now expected to hold but a single target.
-As a consequence, functions like 'erc-add-default-channel' that
-imagine an alternate, aspirational model of buffer-target relations
-have been deprecated.  Grep for their names in ChangeLog.4 for
-details.
-
-A number of less consequential deprecations also debut in this
-release.  For example, the function 'erc-auto-query' was deemed too
-difficult to understand, behavior wise, and has thus been stricken
-from the client code path with no public replacement.  Although likely
-uncontroversial, such changes may still spell disruption for some.  If
-you find yourself among them and in need of explanations, please see
-related entries in the change log and discussions on the bug tracker.
-
-Although this release is light on API features, some groundwork has
-been laid for what may become a new breed of ERC module, namely,
-"connection-local" (or simply "local") modules.  This marks a small
-but crucial step forward toward a more flexible and granular revamping
-of ERC's long touted extensibility.  See the Info node "(erc) Local
-Modules" for details.
-
-Lastly, a few internal variables have been introduced that could just
-as well have been made public, possibly as user options.  Likewise for
-some internal functions.  As always, users needing such functionality
+A few internal variables have been introduced that could just as well
+have been made public, possibly as user options.  Likewise for some
+internal functions.  As always, users needing such functionality
 officially exposed are encouraged to write to emacs-erc@gnu.org.
 
 

etc/HELLO

@@ -89,9 +89,7 @@ Mathematics	∀ p ∈ world • hello p  □
 Meetei Mayek (ꯃꯤꯇꯩ ꯃꯌꯦꯛ)	ꯈꯨꯔꯨꯝꯖꯔꯤ
 Mende Kikakui (𞠀𞠁𞠂)	𞠛𞠉
 Modi (𑘦𑘻𑘚𑘲)	𑘡𑘦𑘭𑘿𑘎𑘰𑘨
-Mongolian Cyrillic (монгол хэл)	Сайн байна уу?
-Mongolian Traditional (ᠮᠣᠩᠭᠣᠯ ᠪᠢᠴᠢᠭ᠋)	ᠰᠠᠶᠢᠨ ᠪᠠᠶᠢᠨ᠎ᠠ ᠤᠤ?
-
+Mongolian (монгол хэл)	Сайн байна уу?
 Northern Thai (ᨣᩣᩴᨾᩮᩬᩥᨦ / ᨽᩣᩈᩣᩃ᩶ᩣ᩠ᨶᨶᩣ)	ᩈ᩠ᩅᩢᩔ᩠ᨯᩦᨣᩕᩢ᩠ᨸ
 Norwegian (norsk)	Hei / God dag
 Odia (ଓଡ଼ିଆ)	ନମସ୍କାର

etc/NEWS

@@ -30,11 +30,6 @@ applies, and please also update docstrings as needed.
 
 * Changes in Emacs 30.1
 
----
-** New user option 'describe-bindings-outline-rules'.
-This user option controls outline visibility in the output buffer of
-'describe-bindings' when 'describe-bindings-outline' in non-nil.
-
 ** X selection requests are now handled much faster and asynchronously.
 This means it should be less necessary to disable the likes of
 'select-active-regions' when Emacs is running over a slow network
@@ -55,11 +50,6 @@ as it has in batch mode since Emacs 24.
 When non-nil, this option suppresses moving remote files to the local
 trash when deleting.  Default is nil.
 
----
-** New user option 'remote-file-name-inhibit-auto-save'.
-If this user option is non-nil, 'auto-save-mode' will not auto-save
-remote buffers.  The default is nil.
-
 +++
 ** New user option 'yes-or-no-prompt'.
 This allows the user to customize the prompt that is appended by
@@ -71,11 +61,6 @@ This allows the user to customize the prompt that is appended by
 This is used for displaying the time and date components of
 'display-time-mode'.
 
----
-** New icon images for general use.
-Several symbolic icons are added to "etc/images/symbols", including
-plus, minus, check-mark, start, etc.
-
 
 * Editing Changes in Emacs 30.1
 
@@ -91,6 +76,16 @@ mistaken compositions, this will now work as well.
 This works like 'kill-matching-buffers', but without asking for
 confirmation.
 
++++
+** Files can be visited asynchronously.
+If the new user option 'execute-file-commands-asynchronously' has a
+non-nil value, interactive file visiting commands load the file
+asynchronously into the respective buffer.  I.e., Emacs is still
+responsive while loading the files, which is useful especially for
+remote files.  If the value is a regular expression, files matching
+this expression are loaded asynchronously.  See the node "(emacs)
+Visiting" in the user manual for the supported commands.
+
 
 * Changes in Specialized Modes and Packages in Emacs 30.1
 
@@ -110,12 +105,12 @@ If you want to get back the old behavior, set the user option to the value
     (setopt gdb-locals-table-row-config
             `((type . 0) (name . 0) (value . ,gdb-locals-value-limit)))
 
-** Grep
+** Compile
 
 *** New user option 'grep-use-headings'.
 When non-nil, the output of Grep is split into sections, one for each
 file, instead of having file names prefixed to each line.  It is
-equivalent to the "--heading" option of some tools such as 'git grep'
+equivalent to the --heading option of some tools such as 'git grep'
 and 'rg'.  The headings are displayed using the new 'grep-heading'
 face.
 
@@ -131,7 +126,7 @@ switches for shortlogs, such as the one produced by 'C-x v L'.
 
 +++
 *** 'diff-ignore-whitespace-hunk' can now be applied to all hunks.
-When called with a non-nil prefix argument,
+When called with a non-nil prefix argument
 'diff-ignore-whitespace-hunk' now iterates over all the hunks in the
 current diff, regenerating them without whitespace changes.
 
@@ -176,7 +171,7 @@ this to your configuration:
 
 ---
 *** You can now properly unload Eshell.
-Calling '(unload-feature 'eshell)' no longer signals an error, and now
+Calling "(unload-feature 'eshell)" no longer signals an error, and now
 correctly unloads Eshell and all of its modules.
 
 +++
@@ -184,19 +179,6 @@ correctly unloads Eshell and all of its modules.
 After manually editing 'eshell-aliases-file', you can use this command
 to load the edited aliases.
 
-+++
-*** 'rgrep' is now a builtin command.
-Running 'rgrep' in Eshell now uses the Emacs grep facility instead of
-calling external rgrep.
-
-** Shell Mode
-
-+++
-*** New user option 'shell-get-old-input-include-continuation-lines'.
-When this user option is non-nil, 'shell-get-old-input' ('C-RET')
-includes multiple shell "\" continuation lines from command output.
-Default is nil.
-
 ** Prog Mode
 
 +++
@@ -208,24 +190,12 @@ point is not in a comment or a string.  It is by default bound to
 
 ** Tramp
 
-+++
-*** New connection methods "toolbox" and "flatpak".
-They allow accessing system containers provided by Toolbox or
-sandboxes provided by Flatpak.
+---
+*** Tramp is now thread-safe.
 
 +++
-*** Rename 'tramp-use-ssh-controlmaster-options' to 'tramp-use-connection-share'.
-The old name still exists as obsolete variable alias.  This user
-option controls now connection sharing for both ssh-based and
-plink-based methods.  It allows the values t, nil, and 'suppress'.
-The latter suppresses also "ControlMaster" settings in the user's
-"~/.ssh/config" file, or connection share configuration in PuTTY
-sessions, respectively.
-
-+++
-*** New command 'tramp-cleanup-some-buffers'.
-It allows to kill only selected remote buffers, controlled by user
-option 'tramp-cleanup-some-buffers-hook'.
+*** New connection method "toolbox".
+This allows accessing system containers provided by Toolbox.
 
 ** EWW
 
@@ -236,17 +206,6 @@ the new argument NEW-BUFFER non-nil, it will use a new buffer instead.
 Interactively, invoke 'eww-open-file' with a prefix argument to
 activate this behavior.
 
----
-*** 'eww' URL or keyword prompt now has tab completion.
-The interactive minibuffer prompt when invoking 'eww' now has support
-for tab completion.
-
-+++
-*** 'eww' URL and keyword prompt now completes suggested URIs and bookmarks.
-The interactive minibuffer prompt when invoking 'eww' now provides
-completions from 'eww-suggest-uris'.  'eww-suggest-uris' now includes
-bookmark URIs.
-
 ** go-ts-mode
 
 +++
@@ -262,85 +221,16 @@ bound to 'C-c C-d' in 'go-ts-mode'.
 When this is non-nil, call the 'man' program synchronously rather than
 asynchronously (which is the default behavior).
 
-** DocView
-
----
-*** New face 'doc-view-svg-face'.
-This replaces 'doc-view-svg-foreground' and 'doc-view-svg-background'.
-
-** Shortdoc
-
-+++
-*** New function 'shortdoc-function-examples'.
-This function returns examples of use of a given Emacs Lisp function
-from the available shortdoc information.
-
-+++
-*** New function 'shortdoc-help-fns-examples-function'.
-This function inserts into the current buffer examples of use of a
-given Emacs Lisp function, which it gleans from the shortdoc
-information.  If you want 'describe-function' ('C-h f') to insert
-examples of using the function into regular "*Help*" buffers, add the
-following to your init file:
-
-    (add-hook 'help-fns-describe-function-functions
-              #'shortdoc-help-fns-examples-function)
-
-** Package
-
----
-*** New user option 'package-vc-register-as-project'.
-When non-nil, it will automatically register every package as a
-project, that you can quickly select using 'project-switch-project'
-('C-x p p').
-
-** Flymake
-
-+++
-*** New user option 'flymake-show-diagnostics-at-end-of-line'.
-When non-nil, Flymake shows 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 the buffer or reaching for the
-mouse to consult an error message.
-
-** Python Mode
-
----
-*** New user option 'python-indent-block-paren-deeper'.
-If non-nil, increase the indentation of the lines inside parens in a
-header of a block when they are indented to the same level as the body
-of the block:
-
-    if (some_expression
-            and another_expression):
-        do_something()
-
-instead of:
-
-    if (some_expression
-        and another_expression):
-        do_something()
-
 
 * New Modes and Packages in Emacs 30.1
 
-** New major modes based on the tree-sitter library
+** New major modes based on the tree-sitter library.
 
 +++
 *** New major mode 'html-ts-mode'.
 An optional major mode based on the tree-sitter library for editing
 HTML files.
 
----
-*** New major mode 'heex-ts-mode'.
-A major mode based on the tree-sitter library for editing HEEx files.
-
----
-*** New major mode 'elixir-ts-mode'.
-A major mode based on the tree-sitter library for editing Elixir
-files.
-
 ---
 ** The highly accessible Modus themes collection has six items.
 The 'modus-operandi' and 'modus-vivendi' are the main themes that have
@@ -355,18 +245,6 @@ their customization options.
 
 * Incompatible Lisp Changes in Emacs 30.1
 
----
-** The escape sequence '\x' not followed by hex digits is now an error.
-Previously, '\x' without at least one hex digit denoted character code
-zero (NUL) but as this was neither intended nor documented or even
-known by anyone, it is now treated as an error by the Lisp reader.
-
----
-** Connection-local variables are applied in buffers visiting a remote file.
-This overrides possible directory-local or file-local variables with
-the same name.
-
----
 ** User option 'tramp-completion-reread-directory-timeout' has been removed.
 This user option has been obsoleted in Emacs 27, use
 'remote-file-name-inhibit-cache' instead.
@@ -380,7 +258,12 @@ hooks named after the feature name, like 'esh-mode-unload-hook'.
 
 * Lisp Changes in Emacs 30.1
 
-** New variable 'inhibit-auto-fill' to temporarily prevent auto-fill.
+--- (Needs better documentation)
+** There is a new command 'universal-async-argument', bound to 'C-x &'.
+If this command precedes another command, the value of variable
+'universal-async-argument' will be toggled.  This indicates, that the
+following command shall be executed asynchronously.  For example,
+file visiting commands would load files into buffers asynchronously.
 
 ** Functions and variables to transpose sexps
 
@@ -489,65 +372,26 @@ was to catch all errors, add an explicit handler for 'error', or use
 This warning can be suppressed using 'with-suppressed-warnings' with
 the warning name 'suspicious'.
 
----
-*** Warn about 'unwind-protect' without unwind forms.
-The compiler now warns when the 'unwind-protect' form is used without
-any unwind forms, as in
-
-    (unwind-protect (read buffer))
-
-because the behavior is identical to that of the argument; there is
-no protection of any kind.  Perhaps the intended unwind forms have
-been misplaced or forgotten, or the use of 'unwind-protect' could be
-simplified away.
-
-This warning can be suppressed using 'with-suppressed-warnings' with
-the warning name 'suspicious'.
-
----
-*** Warn about more ignored function return values.
-The compiler now warns when the return value from certain functions is
-implicitly ignored.  Example:
-
-    (progn (nreverse my-list) my-list)
-
-will elicit a warning because it is usually pointless to call
-'nreverse' on a list without using the returned value.
-
-To silence the warning, make use of the value in some way, such as
-assigning it to a variable.  You can also wrap the function call in
-'(ignore ...)', or use 'with-suppressed-warnings' with the warning
-name 'ignored-return-value'.
-
-The warning will only be issued for calls to functions declared
-'important-return-value' or 'side-effect-free' (but not 'error-free').
++++
+** New function 'file-user-uid'.
+This function is like 'user-uid', but is aware of file name handlers,
+so it will return the remote UID for remote files (or -1 if the
+connection has no associated user).
 
 +++
-** New function declaration and property 'important-return-value'.
-The declaration '(important-return-value t)' sets the
-'important-return-value' property which indicates that the function
-return value should probably not be thrown away implicitly.
-
-+++
-** New functions 'file-user-uid' and 'file-group-gid'.
-These functions are like 'user-uid' and 'group-gid', respectively, but
-are aware of file name handlers, so they will return the remote UID or
-GID for remote files (or -1 if the connection has no associated user).
-
-+++
-** 'fset', 'defalias' and 'defvaralias' now signal an error for cyclic aliases.
-Previously, 'fset', 'defalias' and 'defvaralias' could be made to
-build circular function and variable indirection chains as in
+** 'fset' and 'defalias' now signal an error for circular alias chains.
+Previously, 'fset' and 'defalias' could be made to build circular
+function indirection chains as in
 
     (defalias 'able 'baker)
     (defalias 'baker 'able)
 
-but trying to use them would sometimes make Emacs hang.  Now, an attempt
+but trying to call them would often make Emacs hang.  Now, an attempt
 to create such a loop results in an error.
 
-Since circular alias chains now cannot occur, 'function-alias-p',
-'indirect-function' and 'indirect-variable' will never signal an error.
-Their 'noerror' arguments have no effect and are therefore obsolete.
+Since circular alias chains now cannot occur, 'function-alias-p' and
+'indirect-function' will never signal an error.  Their second
+'noerror' arguments have no effect and are therefore obsolete.
 
 
 * Changes in Emacs 30.1 on Non-Free Operating Systems

etc/NEWS.29

@@ -218,13 +218,13 @@ of 'user-emacs-directory'.
 
 +++
 ** The image commands have changed key bindings.
-In previous Emacs versions, the '+', '-' and 'r' keys were bound when
-point was over an image.  In Emacs 29.1, additional commands have been
-added, and this made it more likely that users would trigger the image
-commands by mistake.  To avoid this, all image commands have been
-moved to the 'i' prefix keymap, so '+' is now 'i +', '-' is now 'i -',
-and 'r' is now 'i r'.  In addition, these commands are now repeating,
-so you can rotate an image twice by saying 'i r r', for instance.
+In previous Emacs versions, images have had the '+', '-' and 'r' keys
+bound when point is over an image.  In Emacs 29.1, additional commands
+were added, and this made it more likely that users would trigger the
+image commands by mistake.  To avoid this, all image commands have
+moved to the 'i' keymap, so '+' is now 'i +', '-' is now 'i -', and
+'r' is now 'i r'.  In addition, these commands are now repeating, so
+you can rotate an image twice by saying 'i r r', for instance.
 
 +++
 ** Emacs now picks the correct coding-system for X input methods.
@@ -380,7 +380,7 @@ this user option to nil to revert back to the old behavior.
 ---
 ** Support for old EIEIO functions is not autoloaded any more.
 You need an explicit '(require 'eieio-compat)' to use 'defmethod'
-and 'defgeneric' (which were made obsolete in Emacs 25.1 by
+and 'defgeneric' (which have been made obsolete in Emacs 25.1 with
 'cl-defmethod' and 'cl-defgeneric').
 Similarly you might need to '(require 'eieio-compat)' before loading
 files that were compiled with an old EIEIO (Emacs<25).
@@ -497,7 +497,7 @@ the 'nlinum' package from GNU ELPA instead.  The former has better
 performance, but the latter is closer to a drop-in replacement.
 
 1. To use 'display-line-numbers-mode', add something like this to your
-   init file:
+   Init file:
 
     (global-display-line-numbers-mode 1)
     ;; Alternatively, to use it only in programming modes:
@@ -517,7 +517,7 @@ performance, but the latter is closer to a drop-in replacement.
 
 ---
 ** The thumbs.el library is now obsolete.
-We recommend using the 'image-dired' command instead.
+We recommend using command 'image-dired' instead.
 
 ---
 ** The autoarg.el library is now marked obsolete.
@@ -577,7 +577,7 @@ encoding, only for decoding.
 ** New user option 'major-mode-remap-alist' to specify favorite major modes.
 This user option lets you remap the default modes (e.g. 'perl-mode' or
 'latex-mode') to your favorite ones (e.g. 'cperl-mode' or
-'LaTeX-mode') instead of having to use 'defalias', which can have
+'LaTeX-mode') without having to use 'defalias', which can have
 undesirable side effects.
 This applies to all modes specified via 'auto-mode-alist', file-local
 variables, etc.
@@ -587,8 +587,6 @@ variables, etc.
 
 ---
 ** New user option 'electric-quote-replace-consecutive'.
-This allows you to disable the default behavior of consecutive single
-quotes being replaced with a double quote.
 
 ---
 ** Emacs is now capable of editing files with very long lines.
@@ -797,14 +795,13 @@ part of the buffer.
 
 +++
 ** New user option 'set-message-functions'.
-It allows more flexible control of how echo-area messages are displayed
-by adding functions to this list.  The default value is a list of one
-element: 'set-minibuffer-message', which displays echo-area messages
-at the end of the minibuffer text when the minibuffer is active.
-Other useful functions include 'inhibit-message', which allows
-specifying, via 'inhibit-message-regexps', the list of messages whose
-display should be inhibited; and 'set-multi-message' that accumulates
-recent messages and displays them stacked together.
+It allows selecting more functions for 'set-message-function'
+in addition to the default function that handles messages
+in the active minibuffer.  The most useful are 'inhibit-message'
+that allows specifying a list of messages to inhibit via
+'inhibit-message-regexps', and 'set-multi-message' that
+accumulates recent messages and displays them stacked
+in the echo area.
 
 ---
 ** New user option 'find-library-include-other-files'.
@@ -857,17 +854,17 @@ This value stands for the value of the corresponding attribute of the
 inheriting from other faces.
 
 +++
-** New X resource "borderThickness".
+** New X resource: "borderThickness".
 This controls the thickness of the external borders of the menu bars
 and pop-up menus.
 
 +++
-** New X resource "inputStyle".
+** New X resource: "inputStyle".
 This controls the style of the pre-edit and status areas of X input
 methods.
 
 +++
-** New X resources "highlightForeground" and "highlightBackground".
+** New X resources: "highlightForeground" and "highlightBackground".
 Only in the Lucid build, this controls colors used for highlighted
 menu item widgets.
 
@@ -904,7 +901,7 @@ frame's contents will be hidden, leaving only the title bar on display.
 ---
 ** New user option 'x-gtk-use-native-input'.
 This controls whether or not GTK input methods are used by Emacs,
-instead of XIM input methods.  Defaults to nil.
+instead of XIM input methods.
 
 +++
 ** New user option 'use-system-tooltips'.
@@ -1001,17 +998,17 @@ combinations in a graphical menu system.
 
 +++
 *** New command 'emoji-search' (bound to 'C-x 8 e s').
-This command lets you search for and insert an Emoji based on names.
+This command lets you search for Emoji based on names.
 
 +++
 *** New command 'emoji-list' (bound to 'C-x 8 e l').
 This command lists all Emoji (categorized by themes) in a special
-buffer and lets you choose one of them to insert.
+buffer and lets you choose one of them.
 
 ---
 *** New command 'emoji-recent' (bound to 'C-x 8 e r').
 This command lets you choose among the Emoji you have recently
-inserted and insert it.
+inserted.
 
 +++
 *** New command 'emoji-describe' (bound to 'C-x 8 e d').
@@ -1023,11 +1020,6 @@ works for non-Emoji characters.)
 These are bound to 'C-x 8 e +' and 'C-x 8 e -', respectively.  They
 can be used on any character, but are mainly useful for Emoji.
 
----
-*** New command 'emoji-zoom-reset'.
-This is bound to 'C-x 8 e 0', and undoes any size changes performed by
-'emoji-zoom-increase' and 'emoji-zoom-decrease'.
-
 ---
 *** New input method 'emoji'.
 This allows you to enter Emoji using short strings, eg ':face_palm:'
@@ -1045,7 +1037,7 @@ quotes removed.
 
 ---
 *** 'M-x apropos-variable' output now includes values of variables.
-Such an apropos buffer is more easily viewed with outlining after
+Such apropos buffer is more easily viewed with outlining after
 enabling 'outline-minor-mode' in 'apropos-mode'.
 
 +++
@@ -1077,7 +1069,7 @@ This has been changed to:
 +++
 *** The 'C-h .' command now accepts a prefix argument.
 'C-u C-h .' would previously inhibit displaying a warning message if
-there was no local help at point.  This has been changed to call
+there's no local help at point.  This has been changed to call
 'button-describe'/'widget-describe' and display button/widget help
 instead.
 
@@ -1130,7 +1122,7 @@ helpful commands for various tasks.  You can toggle the display using
 'C-h C-q'.
 
 ** Emacs now comes with Org v9.6.
-See the file "etc/ORG-NEWS" for user-visible changes in Org.
+See the file "ORG-NEWS" for user-visible changes in Org.
 
 ** Outline Mode
 
@@ -1193,13 +1185,12 @@ the display of several buffers in a row more amenable.
 
 +++
 *** New buffer display action alist entry 'lru-frames'.
-This allows specifying which frames 'display-buffer' should consider
-when using a window that shows another buffer.  It is interpreted as
-per the ALL-FRAMES argument of 'get-lru-window'.
+This allows to specify which frames 'display-buffer' should consider
+when using a window that shows another buffer.
 
 +++
 *** New buffer display action alist entry 'lru-time'.
-'display-buffer' will ignore windows with a use time higher than this
+'display-buffer' will ignore windows with a use time higher than that
 when using a window that shows another buffer.
 
 +++
@@ -1209,14 +1200,12 @@ making it a less likely candidate for displaying another buffer.
 
 +++
 *** New buffer display action alist entry 'window-min-width'.
-This allows specifying a preferred minimum width of the window used to
-display a buffer.
+This allows to specify a minimum width of the window used to display a
+buffer.
 
 ---
-*** You can specify on which window 'scroll-other-window' operates.
-This is controlled by the new 'other-window-scroll-default' variable,
-which should be set to a function that returns a window.  When this
-variable is nil, 'next-window' is used.
+*** You can customize on which window 'scroll-other-window' operates.
+This is controlled by the new 'other-window-scroll-default' variable.
 
 ** Frames
 
@@ -1279,19 +1268,17 @@ respond within N seconds.  The default is to wait forever.
 +++
 *** 'server-stop-automatically' can be used to automatically stop the server.
 The Emacs server will be automatically stopped when certain conditions
-are met.  The conditions are determined by the argument to
-'server-stop-automatically', which can be 'empty', 'delete-frame' or
-'kill-terminal'.
+are met.  The conditions are given by the argument, which can be
+'empty', 'delete-frame' or 'kill-terminal'.
 
 ** Rcirc
 
 +++
 *** New command 'rcirc-when'.
-This shows the reception time of the message at point (if available).
 
 +++
 *** New user option 'rcirc-cycle-completion-flag'.
-Rcirc now uses the default 'completion-at-point' mechanism.  The
+Rcirc will use the default 'completion-at-point' mechanism.  The
 conventional IRC behavior of completing by cycling through the
 available options can be restored by enabling this option.
 
@@ -1546,10 +1533,6 @@ environments are:
 
  Coptic script and language environment
 
- Mongolian-traditional script and language environment
-
- Mongolian-cyrillic language environment
-
 ---
 *** The "Oriya" language environment was renamed to "Odia".
 This is to follow the change in the official name of the script.  The
@@ -1563,10 +1546,7 @@ Type 'C-u C-h t' to select it in case your language setup does not do
 so automatically.
 
 ---
-*** New Ukrainian translation of the Emacs tutorial.
-
----
-*** New Farsi/Persian translation of the Emacs tutorial.
+*** New Ukrainian translation of the Emacs Tutorial.
 
 ---
 *** New default phonetic input method for the Tamil language environment.
@@ -1591,12 +1571,6 @@ This input method is based on the russian-computer input method, and
 is intended for typing in the Chuvash language written in the Cyrillic
 script.
 
----
-*** New input method 'cyrillic-mongolian'.
-This input method is for typing in the Mongolian language using the
-Cyrillic script.  It is the default input method for the new
-Mongolian-cyrillic language environment, see above.
-
 
 * Changes in Specialized Modes and Packages in Emacs 29.1
 
@@ -1843,18 +1817,13 @@ this includes "binary" buffers like 'archive-mode' and 'image-mode'.
 ** Package
 
 +++
-*** New command 'package-upgrade'.
+*** New command 'package-update'.
 This command allows you to upgrade packages without using 'M-x
-list-packages'.  A package that comes with the Emacs distribution can
-only be upgraded after you install, once, a newer version from ELPA
-via the package-menu displayed by 'list-packages'.
+list-packages'.
 
 +++
-*** New command 'package-upgrade-all'.
-This command allows upgrading all packages without any queries.
-A package that comes with the Emacs distribution will only be upgraded
-by this command after you install, once, a newer version of that
-package from ELPA via the package-menu displayed by 'list-packages'.
+*** New command 'package-update-all'.
+This command allows updating all packages without any queries.
 
 +++
 *** New commands 'package-recompile' and 'package-recompile-all'.
@@ -1889,26 +1858,13 @@ packages checked out using 'package-vc-install'.
 +++
 *** New command 'package-report-bug'.
 This command helps you compose an email for sending bug reports to
-package maintainers, and is bound to 'b' in the "*Packages*" buffer.
+package maintainers.
 
 +++
 *** New user option 'package-vc-selected-packages'.
 By customizing this user option you can specify specific packages to
 install.
 
----
-*** New user option 'package-install-upgrade-built-in'.
-When enabled, 'package-install' will include in the list of
-upgradeable packages those built-in packages (like Eglot and
-use-package, for example) for which a newer version is available in
-package archives, and will allow installing those newer versions.  By
-default, this is disabled; however, if 'package-install' is invoked
-with a prefix argument, it will act as if this new option were
-enabled.
-
-If you customize this option, we recommend you place its non-default
-setting in your early-init file.
-
 ** Emacs Sessions (Desktop)
 
 +++
@@ -1966,8 +1922,8 @@ displayed in a window.
 
 +++
 *** New user option 'compilation-hidden-output'.
-This regular expression can be used to make specific parts of
-compilation output invisible.
+This can be used to make specific parts of compilation output
+invisible.
 
 +++
 *** The 'compilation-auto-jump-to-first-error' user option has been extended.
@@ -2129,18 +2085,6 @@ command accepts the Unicode name of an Emoji (for example, "smiling
 face" or "heart with arrow"), like 'C-x 8 e e', with minibuffer
 completion, and adds the Emoji into the search string.
 
-** GDB/MI
-
----
-*** New user option 'gdb-debuginfod-enable-setting'.
-On capable platforms, GDB 10.1 and later can download missing source
-and debug info files from special-purpose servers, called "debuginfod
-servers".  Use this new option to control whether 'M-x gdb' instructs
-GDB to download missing files from debuginfod servers when you debug
-the corresponding programs.  The default is to ask you at the
-beginning of each debugging session whether to download the files for
-that session.
-
 ** Glyphless Characters
 
 +++
@@ -2350,7 +2294,7 @@ EUDC inline expansion result formatting defaulted to
     ("%s %s <%s>" firstname name email)
 
 Since email address specifications need to comply with RFC 5322 in
-order to be useful in messages, there was a risk of producing syntax
+order to be useful in messages, there was a risk to produce syntax
 which was standard with RFC 822, but is marked as obsolete syntax by
 its successor RFC 5322.  Also, the first and last name part was never
 enclosed in double quotes, potentially producing invalid address
@@ -2384,8 +2328,8 @@ used to select the entry type in the ecomplete database.
 +++
 *** New back-end for mailabbrev.
 A new back-end for mailabbrev allows information from that database to
-be queried by EUDC, too.  Only the attributes 'email', 'name', and
-'firstname' are supported.
+be queried by EUDC, too.  The attributes 'email', 'name', and 'firstname'
+are supported only.
 
 ** EWW/SHR
 
@@ -2584,16 +2528,8 @@ the project by a VC project based on that VCS.
 
 +++
 *** New command 'xref-go-forward'.
-It is bound to 'C-M-,' and jumps to the location where you previously
-invoked 'xref-go-back' ('M-,', also known as 'xref-pop-marker-stack').
-
-+++
-*** The depth of the Xref marker stack is now infinite.
-The implementation of the Xref marker stack was changed in a way that
-allows as many places to be saved on the stack as needed, limited only
-by the available memory.  Therefore, the variables
-'find-tag-marker-ring-length' and 'xref-marker-ring-length' are now
-obsolete and unused; setting them has no effect.
+It is bound to 'C-M-,' and jumps to the location where 'xref-go-back'
+('M-,', also known as 'xref-pop-marker-stack') was invoked previously.
 
 +++
 *** 'xref-query-replace-in-results' prompting change.
@@ -2632,14 +2568,14 @@ as opposed to via the command-line.
 +++
 *** New command 'image-transform-fit-to-window'.
 This command fits the image to the current window by scaling down or
-up as necessary.  Unlike 'image-transform-fit-both', this can scale
-the image up as well as down.  It is bound to 's w' in Image Mode by
-default.
+up as necessary.  Unlike 'image-transform-fit-both', this does not
+only scale the image down, but up as well.  It is bound to 's w' in
+Image Mode by default.
 
 ---
 *** New command 'image-mode-wallpaper-set'.
 This command sets the desktop background to the current image.  It is
-bound to 'W' in Image Mode by default.
+bound to 'W' by default.
 
 +++
 *** 'image-transform-fit-to-{height,width}' are now obsolete.
@@ -2657,14 +2593,19 @@ much (in percent).  It is nil by default, which means no limit.
 
 ---
 *** New user option 'image-text-based-formats'.
-This controls whether or not to show a message, when opening certain
-image formats, explaining how to edit it as text.  The default is to
-show this message for SVG and XPM.
+This controls whether or not to show a message when opening certain
+image formats saying how to edit it as text.  The default is to show
+this message for SVG and XPM.
+
++++
+*** New commands: 'image-flip-horizontally' and 'image-flip-vertically'.
+These commands horizontally and vertically flip the image under point,
+and are bound to 'i h' and 'i v', respectively.
 
 +++
 *** New command 'image-transform-set-percent'.
-It allows resizing the image to a percentage of its original size, and
-is bound to 's p' in Image mode.
+It allows setting the image size to a percentage of its original size,
+and is bound to 's p' in Image mode.
 
 +++
 *** 'image-transform-original' renamed to 'image-transform-reset-to-original'.
@@ -2676,19 +2617,6 @@ The old name was confusing, and is now an obsolete function alias.
 
 ** Images
 
-+++
-*** New commands 'image-crop' and 'image-cut'.
-These commands allow interactively cropping/cutting the image at
-point.  The commands are bound to keys 'i c' and 'i x' (respectively)
-in the local keymap over images.  They rely on external programs, by
-default "convert" from ImageMagick, to do the actual cropping/eliding
-of the image file.
-
-+++
-*** New commands 'image-flip-horizontally' and 'image-flip-vertically'.
-These commands horizontally and vertically flip the image under point,
-and are bound to 'i h' and 'i v', respectively.
-
 +++
 *** Users can now add special image conversion functions.
 This is done via 'image-converter-add-handler'.
@@ -3274,12 +3202,7 @@ Imenu now lists the members directly nested in R6RS Scheme libraries
 Emacs now comes with the Eglot package, which enhances various Emacs
 features, such as completion, documentation, error detection, etc.,
 based on data provided by language servers using the Language Server
-Protocol (LSP).  See the new Info manual "(eglot) Top" for more.  Also
-see "etc/EGLOT-NEWS".
-
-If you want to be able to use 'package-install' to upgrade Eglot to
-newer versions released on GNU ELPA, customize the new option
-'package-install-upgrade-built-in' to a non-nil value.
+Protocol (LSP).  See the new Info manual "(eglot) Top" for more.
 
 +++
 ** use-package: Declarative package configuration.
@@ -3288,9 +3211,13 @@ macro, which allows you to isolate package configuration in your init
 file in a way that is declarative, tidy, and performance-oriented.
 See the new Info manual "(use-package) Top" for more.
 
-If you want to be able to use 'package-install' to upgrade use-package
-to newer versions released on GNU ELPA, customize the new option
-'package-install-upgrade-built-in' to a non-nil value.
++++
+** New commands 'image-crop' and 'image-cut'.
+These commands allow interactively cropping/cutting the image at
+point.  The commands are bound to keys 'i c' and 'i x' (respectively)
+in the local keymap over images.  They rely on external programs, by
+default "convert" from ImageMagick, to do the actual cropping/eliding
+of the image file.
 
 ---
 ** New package 'wallpaper'.
@@ -3304,11 +3231,8 @@ manually if needed, using the new user options 'wallpaper-command' and
 
 +++
 ** New package 'oclosure'.
-This allows the creation of OClosures, which are "functions with
-slots" or "function objects" that expose additional information about
-themselves.  Use the new macros 'oclosure-define' and
-'oclosure-lambda' to create OClosures.  See the "(elisp) OClosures"
-node for more information.
+This allows the creation of "functions with slots" or "function
+objects" via the macros 'oclosure-define' and 'oclosure-lambda'.
 
 +++
 *** New generic function 'oclosure-interactive-form'.
@@ -3617,13 +3541,11 @@ font spec.  In these cases, replacing ":weight 'normal" with ":weight
 'medium" should fix the issue.
 
 ---
-** Keymap descriptions by Help commands have changed.
+** Keymap descriptions have changed.
 'help--describe-command', 'C-h b' and associated functions that output
 keymap descriptions have changed.  In particular, prefix commands are
-not output at all, and instead of "??" for closures/functions, these
-functions output "[closure]"/"[lambda]".  You can get back the old
-behavior of including prefix commands by customizing the new option
-'describe-bindings-show-prefix-commands' to a non-nil value.
+not output at all, and instead of "??" for closures/functions,
+"[closure]"/"[lambda]" is output.
 
 ---
 ** 'downcase' details have changed slightly.
@@ -3956,9 +3878,9 @@ connection-local profile.
 +++
 *** New macro 'with-connection-local-application-variables'.
 This macro works like 'with-connection-local-variables', but it allows
-using another application instead of 'tramp'.  This is useful when
-running code in a buffer where Tramp has already set some
-connection-local variables.
+to use another application but 'tramp'.  This is useful when running
+code in a buffer where Tramp has already set some connection-local
+variables.
 
 +++
 *** New macro 'setq-connection-local'.
@@ -4037,8 +3959,8 @@ This returns a list of sub-sequences of the specified sequence.
 
 +++
 *** New function 'seq-remove-at-position'.
-This function returns a copy of the specified sequence with the
-element at a given (zero-based) index removed.
+This function returns a copy of the specified sequence where the
+element at a given (zero-based) index got removed.
 
 +++
 *** New function 'seq-positions'.
@@ -4106,7 +4028,7 @@ that quote character has to be escaped to avoid Emacs displaying it as
 
     (setq foo '(1 2 3))
 
-invalid.  Emacs will now warn during byte compilation if it sees
+invalid.  Emacs will now warn during byte compilation if it seems
 something like that, and also warn about when using RIGHT/LEFT SINGLE
 QUOTATION MARK directly.  In both these cases, if these characters
 should really be present in the docstring, they should be quoted with
@@ -4166,7 +4088,7 @@ example for benchmarking purposes.
 ** New function 'string-edit'.
 This is meant to be used when the user has to edit a (potentially)
 long string.  It pops up a new buffer where you can edit the string,
-and the provided callback is called when the user types 'C-c C-c'.
+and a callback is called when the user types 'C-c C-c'.
 
 +++
 ** New function 'read-string-from-buffer'.
@@ -4312,7 +4234,7 @@ them towards or away from each other.
 
 +++
 ** New hook 'x-pre-popup-menu-hook'.
-This hook is run before 'x-popup-menu' is about to display a
+This hook, run before 'x-popup-menu', is about to display a
 deck-of-cards menu on screen.
 
 ---
@@ -4374,11 +4296,9 @@ that binding is ignored by 'where-is-internal'.
 
 +++
 *** New functions for defining and manipulating keystrokes.
-These all take the syntax defined by 'key-valid-p', which is basically
-the same syntax as the one accepted by the 'kbd' macro.  None of the
-older functions have been deprecated or altered, but they are now
-de-emphasized in the documentation, and we encourage Lisp programs to
-switch to these new functions.
+These all take the syntax defined by 'key-valid-p'.  None of the older
+functions have been deprecated or altered, but they are now
+de-emphasized in the documentation.
 
 +++
 *** Use 'keymap-set' instead of 'define-key'.
@@ -4413,8 +4333,8 @@ switch to these new functions.
 +++
 *** 'define-key' now takes an optional REMOVE argument.
 If non-nil, remove the definition from the keymap.  This is subtly
-different from setting a definition to nil: when the keymap has a
-parent such a definition will shadow the parent's definition.
+different from setting a definition to nil (when the keymap has a
+parent).
 
 +++
 *** 'read-multiple-choice' now takes an optional SHOW-HELP argument.
@@ -4949,12 +4869,6 @@ two buttons: "Yes" and "No".
 ---
 *** 'process-attributes' is now implemented.
 
-** macOS
-
-+++
-*** The 'ns-popup-font-panel' command has been removed.
-Use the general command 'M-x menu-set-font' instead.
-
 
 ----------------------------------------------------------------------
 This file is part of GNU Emacs.

etc/ORG-NEWS

@@ -332,7 +332,7 @@ When the block type starts from the upper case, structure template
 will now insert =#+BEGIN_TYPE=.  Previously, lower-case =#+begin_type= was inserted unconditionally.
 *** New ox-latex tabbing support for tables.
 
-LaTeX tables can now be exported to the latex tabbing environment
+Latex tables can now be exported to the latex tabbing environment
 tabbing environment]].
 This is done by adding =#+ATTR_LATEX: :mode tabbing= at the top
 of the table.
@@ -4284,7 +4284,7 @@ parameters specific to some pre-defined translators, e.g.,
 ~:environment~ and ~:booktabs~ for ~orgtbl-to-latex~.  See translators
 docstrings (including ~orgtbl-to-generic~) for details.
 
-*** Non-floating minted listings in LaTeX export
+*** Non-floating minted listings in Latex export
 
 It is not possible to specify =#+attr_latex: :float nil= in conjunction
 with source blocks exported by the minted package.
@@ -6540,7 +6540,7 @@ that Calc formulas can operate on them.
 
 *** Hyperlinks
 
-**** Org-BibTeX -- major improvements
+**** Org-Bibtex -- major improvements
 
      Provides support for managing bibtex bibliographical references
      data in headline properties.  Each headline corresponds to a

etc/PROBLEMS

@@ -2313,33 +2313,6 @@ recommended way of turning on Font-lock is by typing "M-x
 global-font-lock-mode RET" or by customizing the variable
 'global-font-lock-mode'.
 
-** Colors are not available or messed up on TTY frames inside 'screen'.
-
-This can happen if you have COLORTERM=truecolor defined in the
-environment when Emacs starts, but your version of 'screen' doesn't
-actually support 24-bit true colors.
-
-The COLORTERM environment variable is supposed to be set to the value
-"truecolor" only if the terminal used by Emacs actually supports true
-color.  Emacs does not have any means of verifying that this support
-is available, it takes the fact that the variable is defined to this
-value as an indication that true color support is, in fact, available,
-and uses color setting commands that COLORTERM=truecolor presumes,
-bypassing the usual Terminfo capabilities related to colors.
-
-Some text-mode terminals, such as GNOME Terminal, are known to set
-this environment variable, supposedly to announce their own support
-for true color; however the setting is then inherited by any other
-terminal emulators started from such a terminal, even though those
-other terminal emulators might not themselves support true color using
-the same commands as Emacs uses when it sees COLORTERM=truecolor.
-
-The solution is to either upgrade to a newer version of 'screen'
-(version 5.x or later reportedly supports true color), or to unset the
-COLORTERM variable before starting 'screen', and let Emacs use the
-color support provided by the terminal emulator as defined in the
-Terminfo database.
-
 ** Unexpected characters inserted into the buffer when you start Emacs.
 See e.g. <URL:https://debbugs.gnu.org/11129>
 
@@ -2708,15 +2681,6 @@ Emacs so that it isn't compiled with '-O5'.
 We list bugs in current versions here.  See also the section on legacy
 systems.
 
-*** On Solaris 10, running 'configure' with "/bin/sh" produces errors.
-The "/bin/sh" shell on Solaris is an ancient and non-POSIX shell, so
-we recommend not to use it.  The Emacs 'configure' script should find
-an appropriate shell and re-exec itself with that shell, unless you
-force it to use "/bin/sh" by using "CONFIG_SHELL=/bin/sh" on the
-'configure' command line.  So either don't use CONFIG_SHELL, or, if
-you'd rather pick the shell yourself, choose "/bin/bash" or "/bin/ksh"
-or "/usr/xpg4/bin/sh" instead.
-
 *** On Solaris 10 sparc, Emacs crashes during the build while saving state.
 This was observed for Emacs 28.1 on Solaris 10 32-bit sparc, with
 Oracle Developer Studio 12.6 (Sun C 5.15).  The failure was intermittent,

etc/emacsclient-mail.desktop

@@ -1,10 +1,7 @@
 [Desktop Entry]
 Categories=Network;Email;
 Comment=GNU Emacs is an extensible, customizable text editor - and more
-# We want to pass the following commands to the shell wrapper:
-# u=$(echo "$1" | sed 's/[\"]/\\&/g'); exec emacsclient --alternate-editor= --display="$DISPLAY" --eval "(message-mailto \"$u\")"
-# Special chars '"', '$', and '\' must be escaped as '\\"', '\\$', and '\\\\'.
-Exec=sh -c "u=\\$(echo \\"\\$1\\" | sed 's/[\\\\\\"]/\\\\\\\\&/g'); exec emacsclient --alternate-editor= --display=\\"\\$DISPLAY\\" --eval \\"(message-mailto \\\\\\"\\$u\\\\\\")\\"" sh %u
+Exec=sh -c "exec emacsclient --alternate-editor= --display=\\"\\$DISPLAY\\" --eval \\"(message-mailto \\\\\\"\\$1\\\\\\")\\"" sh %u
 Icon=emacs
 Name=Emacs (Mail, Client)
 MimeType=x-scheme-handler/mailto;
@@ -16,7 +13,7 @@ Actions=new-window;new-instance;
 
 [Desktop Action new-window]
 Name=New Window
-Exec=sh -c "u=\\$(echo \\"\\$1\\" | sed 's/[\\\\\\"]/\\\\\\\\&/g'); exec emacsclient --alternate-editor= --create-frame --eval \\"(message-mailto \\\\\\"\\$u\\\\\\")\\"" sh %u
+Exec=sh -c "exec emacsclient --alternate-editor= --create-frame --eval \\"(message-mailto \\\\\\"\\$1\\\\\\")\\"" sh %u
 
 [Desktop Action new-instance]
 Name=New Instance

etc/images/symbols/README

@@ -1,43 +0,0 @@
-This directory contains icons for some inline symbols.
-
-COPYRIGHT AND LICENSE INFORMATION FOR IMAGE FILES
-
-Files: *.svg
-Author: Yuan Fu <casouri@gmail.com>
-Copyright (C) 2023 Free Software Foundation, Inc.
-License: GNU General Public License version 3 or later (see COPYING)
-
-How I made these icons: I made them with Figma, and exported them into
-SVG. I made the shapes with vectors (SVG paths) rather than strokes,
-merged all the shapes into a single shape with union operation, and
-stripped filling attributes from the SVG files. This way the icons can
-be colored like normal text! I'm not exactly sure how it works, but as
-long as the icon uses SVG path, and there is only one path in the
-file, and there is no filling attributes, the icons can be colored as
-text.
-
-FWIW, this is the command I used to strip filling attributes:
-
-sed -i 's/fill="none"//g' <file>
-sed -i 's/fill="black"//g' <file>
-
-Naming: Use underscore to separate styles, dash are considered normal
-character so you can use it for names. End with the intended optical
-size for the icon.
-
-There should also be an order for all the keywords. Right now we have
-directions (left/right), circle, fill, and optical size. Among them,
-the order should be
-
-1. direction
-2. circle
-3. fill
-4. size
-
-E.g., arrow_right_circle_fill_16.
-
-
-
-Every time you modify the SVG icons, please use the ImageMagick
-`convert' utility to convert them to PBM icons, for the sake of
-Emacsen that cannot display SVG images.

etc/images/symbols/check-mark_16.svg

@@ -1,3 +0,0 @@
-<svg width="16" height="16" viewBox="0 0 16 16"  xmlns="http://www.w3.org/2000/svg">
-<path d="M6.58449 9.82778L3.75736 6.99807L2.3425 8.41164L6.58321 12.6562L13.6575 5.58837L12.2439 4.17351L6.58449 9.82778Z" />
-</svg>

etc/images/symbols/chevron_down_16.svg

@@ -1,3 +0,0 @@
-<svg width="16" height="16" viewBox="0 0 16 16"  xmlns="http://www.w3.org/2000/svg">
-<path d="M14 4.5L14 7L8 12L2 7L2 4.5L8 9.5L14 4.5Z" />
-</svg>

etc/images/symbols/chevron_left_16.svg

@@ -1,3 +0,0 @@
-<svg width="16" height="16" viewBox="0 0 16 16"  xmlns="http://www.w3.org/2000/svg">
-<path d="M11 3.05H8.5L4 8.00001L8.5 13H11L6.5 8.00001L11 3.05Z" />
-</svg>

etc/images/symbols/chevron_right_16.svg

@@ -1,3 +0,0 @@
-<svg width="16" height="16" viewBox="0 0 16 16"  xmlns="http://www.w3.org/2000/svg">
-<path d="M4.95455 3H7.45455L12 8L7.45455 13H4.95455L9.5 8L4.95455 3Z" />
-</svg>