Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-06-14 12:31:25 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into scratch/comp-static-data

Browse source
This commit is contained in:
Vibhav Pant 2023-06-06 19:30:27 +05:30
commit 49ffcbf86a
No known key found for this signature in database
GPG key ID: E3FB28CB6AB59598
742 changed files with 147844 additions and 13845 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.dir-locals.el
View file

@ -21,6 +21,9 @@
(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)))

12
CONTRIBUTE
View file

@ -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 to read NEWS in Outline
and takes just one line -- this will allow reading 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 of some of the tests
commit for validity, and may abort the commit if 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
reasons. These should be marked by including something like "Do not
reason. 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, see admin/notes/repo.
See all the files in 'admin/notes/*'. In particular, see
'admin/notes/newfile' and '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

115679
ChangeLog.4 Normal file
View file

File diff suppressed because it is too large Load diff

6
INSTALL
View file

@ -394,6 +394,12 @@ typical 32-bit host, Emacs integers have 62 bits instead of 30.
Use --with-cairo to compile Emacs with Cairo drawing.
Use --with-cairo-xcb to also utilize the Cairo XCB backend on systems
where it is available. While such a configuration is moderately
faster when running over X connections with high latency, it is likely
to crash when a new frame is created on a display connection opened
after a display connection is closed.
Use --with-modules to build Emacs with support for dynamic modules.
This needs a C compiler that supports '__attribute__ ((cleanup (...)))',
as in GCC 3.4 and later.

13
Makefile.in
View file

@ -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=emacsclient/ s|emacsclient|${bindir}/$${client_name}|" \
sed -e "/^Exec=/ 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=emacsclient/ s|emacsclient|${bindir}/$${client_name}|" \
sed -e "/^Exec=/ 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,6 +1030,9 @@ $(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
@ -1284,7 +1287,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.

3
admin/admin.el
View file

@ -1038,8 +1038,7 @@ If optional argument OLD is non-nil, also scan for `defvar's."
(and grp
(setq grp (car (cdr-safe grp))) ; (quote foo) -> foo
(setq ver (assq grp glist))))
(setq alist (cons (cons var ver) alist))))
(if form (format-message "Malformed defcustom: `%s'" form)))))
(setq alist (cons (cons var ver) alist)))))))
(message "%sdone" m)
alist))

2
admin/authors.el
View file

@ -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") ; looks like a mistake
("Po Lu" "Po Lu Via" "Your Name") ; looks like a mistake
("Przemysław Wojnowski" "Przemyslaw Wojnowski")
("R. Bernstein" "rb@dustyfeet.com")
("Rainer Schöpf" "Rainer Schoepf")

2
admin/charsets/Makefile.in
View file

@ -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}(${mapconv} $< '/^<.*[ ]\/x[0-9]/' GLIBC-1 ${compact} && \
${AM_V_GEN}(${run_mapconv} $< '/^<.*[ ]\/x[0-9]/' GLIBC-1 ${compact} && \
echo "# Generated by hand" && \
echo "0xA1-0xDF 0xFF61" ) > $@

3
admin/charsets/mapconv
View file

@ -38,7 +38,8 @@
## 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.
export LC_ALL=C
LC_ALL=C
export LC_ALL
BASE=`expr "$1" : '.*/\(.*\)' '|' "$1"` # basename
FILE="admin/charsets/mapfiles/$BASE"

2
admin/cus-test.el
View file

@ -221,8 +221,6 @@ The detected problematic options are stored in `cus-test-errors'."
;; Check the values
(mapc (lambda (value)
;; TODO for booleans, check for values that can be
;; evaluated and are not t or nil. Usually a bug.
(unless (widget-apply conv :match value)
(let ((err (list symbol :type-error value type)))
(unless (member err cus-test-errors)

18
admin/git-bisect-start
View file

@ -82,7 +82,7 @@ done
# SKIP-BRANCH 58cc931e92ece70c3e64131ee12a799d65409100
## The list below is the exhaustive list of all commits between Dec 1
## 2016 and Jan 31 2023 on which building Emacs with the default
## 2016 and Apr 30 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,3 +1707,19 @@ $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
# SKIP-SINGLE 9686b015a0d71d08828afb0cfe6e477bbc4909ae
# SKIP-SINGLE 621e732ade0f3dc165498ebde4d55d5aacb05b56
# SKIP-SINGLE 200dbf7d302e659e618f74bde81c7b3ccd795639

33
admin/make-tarball.txt
View file

@ -68,16 +68,26 @@ 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, update Makefile.in and
re-run 'configure' to update Makefile.
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.
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
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 5 MiB, or when you make the
first pretest of a new major release, whichever happens later. If
so, start a new ChangeLog.N file 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:
@ -99,11 +109,12 @@ 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.
authors.el. If some authors are "ignored", consider adding
entries to the author-aliases variable.
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 entries to
Check the diff looks reasonable. Maybe add more entries to
authors-ambiguous-files or authors-aliases, and repeat.
Commit any fixes to authors.el.
@ -169,7 +180,13 @@ 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.
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.
Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the files
changed by M-x set-version. Note that the set-version changes

8
admin/merge-gnulib
View file

@ -44,11 +44,11 @@ GNULIB_MODULES='
nanosleep nproc nstrftime
pathmax pipe2 pselect pthread_sigmask
qcopy-acl readlink readlinkat regex
sig2str sigdescr_np socklen stat-time std-gnu11 stdbool stddef stdio
sig2str sigdescr_np socklen stat-time std-gnu11 stdbool stdckdint stddef stdio
stpcpy strnlen strtoimax symlink sys_stat sys_time
tempname time time_r time_rz timegm timer-time timespec-add timespec-sub
tempname time-h time_r time_rz timegm timer-time timespec-add timespec-sub
update-copyright unlocked-io utimensat
vla warnings
vla warnings year2038
'
AVOIDED_MODULES='
@ -132,5 +132,7 @@ cp -- "$gnulib_srcdir"/build-aux/config.guess \
cp -- "$gnulib_srcdir"/lib/af_alg.h \
"$gnulib_srcdir"/lib/save-cwd.h \
"$src"lib &&
cp -- "$gnulib_srcdir"/m4/codeset.m4 \
"$src"m4 &&
{ test -z "$src" || cd "$src"; } &&
./autogen.sh

40
admin/notes/emba
View file

@ -83,6 +83,46 @@ 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-tree-sitter, 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 --tty --env EMACS_EMBA_CI=1 --name emacs-inotify \
emacs-inotify /bin/bash -i
In this container, your working directory is "/checkout". Now you can
apply all commands known for Emacs, like
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.

17
admin/notes/tree-sitter/build-module/README
View file

@ -1,17 +0,0 @@
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.

2
admin/notes/tree-sitter/build-module/batch.sh
View file

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

6
admin/notes/tree-sitter/build-module/build.sh
View file

@ -31,11 +31,17 @@ 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"

205
admin/notes/tree-sitter/html-manual/Accessing-Node.html
View file

@ -1,205 +0,0 @@
<!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>

401
admin/notes/tree-sitter/html-manual/Language-Definitions.html
View file

@ -1,401 +0,0 @@
<!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>

327
admin/notes/tree-sitter/html-manual/Multiple-Languages.html
View file

@ -1,327 +0,0 @@
<!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>

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

@ -1,247 +0,0 @@
<!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>

280
admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html
View file

@ -1,280 +0,0 @@
<!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>

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

@ -1,125 +0,0 @@
<!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>

450
admin/notes/tree-sitter/html-manual/Pattern-Matching.html
View file

@ -1,450 +0,0 @@
<!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>

420
admin/notes/tree-sitter/html-manual/Retrieving-Node.html
View file

@ -1,420 +0,0 @@
<!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>

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

@ -1,211 +0,0 @@
<!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>

230
admin/notes/tree-sitter/html-manual/Using-Parser.html
View file

@ -1,230 +0,0 @@
<!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>

23
admin/notes/tree-sitter/html-manual/build-manual.sh
View file

@ -1,23 +0,0 @@
#!/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" .

374
admin/notes/tree-sitter/html-manual/manual.css
View file

@ -1,374 +0,0 @@
/* 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;
}

157
admin/notes/tree-sitter/starter-guide
View file

@ -17,6 +17,7 @@ TOC:
- More features?
- Common tasks (code snippets)
- Manual
- Appendix 1
* Building Emacs with tree-sitter
@ -42,11 +43,9 @@ 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,
and C#. Better yet, I pre-built these language definitions for
C#, etc. 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
@ -68,6 +67,10 @@ 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
@ -78,6 +81,10 @@ 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
@ -89,12 +96,15 @@ 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, there is python-base-mode (shared), python-mode
(native), and python-ts-mode (tree-sitter).
setup. For example, python.el defines 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
@ -180,18 +190,17 @@ 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 I paste a snippet of
it.
‘python--treesit-settings’ in python.el. Below is a snippet of it.
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.
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.
Each rule should have a :feature, like function-name,
string-interpolation, builtin, etc. Users can then enable/disable each
feature individually.
feature individually. See Appendix 1 at the bottom for a set of common
features names.
#+begin_src elisp
(defvar python--treesit-settings
@ -247,8 +256,7 @@ Concretely, something like this:
(string-interpolation decorator)))
(treesit-major-mode-setup))
(t
;; No tree-sitter
(setq-local font-lock-defaults ...)
;; No tree-sitter, do nothing or fallback to another mode.
...)))
#+end_src
@ -289,6 +297,7 @@ 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
@ -329,7 +338,8 @@ tells you which rule is applied in the echo area.
...))))
#+end_src
Then you set ‘treesit-simple-indent-rules’ to your rules, and call
To setup indentation for your major mode, set
‘treesit-simple-indent-rules’ to your rules, and call
‘treesit-major-mode-setup’:
#+begin_src elisp
@ -339,36 +349,14 @@ Then you set ‘treesit-simple-indent-rules’ to your rules, and call
* Imenu
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.
Set ‘treesit-simple-imenu-settings’ and call
‘treesit-major-mode-setup’.
* Navigation
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>
Set ‘treesit-defun-type-regexp’ and call
‘treesit-major-mode-setup’. You can additionally set
‘treesit-defun-name-function’.
* Which-func
@ -376,36 +364,7 @@ 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 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
find the current function by ‘treesit-defun-at-point’.
* More features?
@ -449,7 +408,51 @@ 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 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.
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
}

17
admin/notes/unicode
View file

@ -22,6 +22,7 @@ Emacs uses the following files from the Unicode Character Database
. confusables.txt
. emoji-data.txt
. emoji-zwj-sequences.txt
. emoji-variation-sequences.txt
. emoji-sequences.txt
. BidiCharacterTest.txt
@ -29,7 +30,7 @@ Emacs also uses the file emoji-test.txt which should be imported from
the Unicode's Public/emoji/ directory, and IdnaMappingTable.txt from
the Public/idna/ directory.
First, the first 14 files, emoji-test.txt and IdnaMappingTable.txt
First, the first 15 files, emoji-test.txt and IdnaMappingTable.txt
need to be copied into admin/unidata/, and the file
https://www.unicode.org/copyright.html should be copied over
copyright.html in admin/unidata (some of them might need trailing
@ -142,6 +143,20 @@ generated for auto-composition-emoji-eligible-codepoints by
admin/unidata/emoji-zwj.awk. Note that your emoji font might not have
glyphs for the newest codepoints yet.
Visit "emoji-variation-sequences.txt", and run the following lisp
fragment to actually insert the described codepoints, then check that
all the text in parentheses displays correctly (it can be helpful to
have `glyphless-char-display-control' customized to show hex codes for
variation selectors).
(save-excursion
(goto-char (point-min))
(while (re-search-forward "^\\([0-9A-Z]+\\) \\([0-9A-Z]+\\).*(\\([^)]+\\))" nil t)
(let ((ch (string-to-number (match-string 1) 16))
(sel (string-to-number (match-string 2) 16))
(sp (match-string 3)))
(replace-match (format "%s %c%c " sp ch sel) nil nil nil 3))))
Finally, etc/NEWS should be updated to announce the support for the
new Unicode version.

723
admin/unidata/emoji-variation-sequences.txt Normal file
View file

@ -0,0 +1,723 @@
# emoji-variation-sequences.txt
# Date: 2022-05-13, 21:54:24 GMT
# © 2022 Unicode®, Inc.
# Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the U.S. and other countries.
# For terms of use, see https://www.unicode.org/terms_of_use.html
#
# Emoji Variation Sequences for UTS #51
# Used with Emoji Version 15.0 and subsequent minor revisions (if any)
#
# For documentation and usage, see https://www.unicode.org/reports/tr51
#
0023 FE0E ; text style; # (1.1 #︎ ) NUMBER SIGN
0023 FE0F ; emoji style; # (1.1 #️ ) NUMBER SIGN
002A FE0E ; text style; # (1.1 *︎ ) ASTERISK
002A FE0F ; emoji style; # (1.1 *️ ) ASTERISK
0030 FE0E ; text style; # (1.1 0︎ ) DIGIT ZERO
0030 FE0F ; emoji style; # (1.1 0️ ) DIGIT ZERO
0031 FE0E ; text style; # (1.1 1︎ ) DIGIT ONE
0031 FE0F ; emoji style; # (1.1 1️ ) DIGIT ONE
0032 FE0E ; text style; # (1.1 2︎ ) DIGIT TWO
0032 FE0F ; emoji style; # (1.1 2️ ) DIGIT TWO
0033 FE0E ; text style; # (1.1 3︎ ) DIGIT THREE
0033 FE0F ; emoji style; # (1.1 3️ ) DIGIT THREE
0034 FE0E ; text style; # (1.1 4︎ ) DIGIT FOUR
0034 FE0F ; emoji style; # (1.1 4️ ) DIGIT FOUR
0035 FE0E ; text style; # (1.1 5︎ ) DIGIT FIVE
0035 FE0F ; emoji style; # (1.1 5️ ) DIGIT FIVE
0036 FE0E ; text style; # (1.1 6︎ ) DIGIT SIX
0036 FE0F ; emoji style; # (1.1 6️ ) DIGIT SIX
0037 FE0E ; text style; # (1.1 7︎ ) DIGIT SEVEN
0037 FE0F ; emoji style; # (1.1 7️ ) DIGIT SEVEN
0038 FE0E ; text style; # (1.1 8︎ ) DIGIT EIGHT
0038 FE0F ; emoji style; # (1.1 8️ ) DIGIT EIGHT
0039 FE0E ; text style; # (1.1 9︎ ) DIGIT NINE
0039 FE0F ; emoji style; # (1.1 9️ ) DIGIT NINE
00A9 FE0E ; text style; # (1.1 ©︎ ) COPYRIGHT SIGN
00A9 FE0F ; emoji style; # (1.1 ©️ ) COPYRIGHT SIGN
00AE FE0E ; text style; # (1.1 ®︎ ) REGISTERED SIGN
00AE FE0F ; emoji style; # (1.1 ®️ ) REGISTERED SIGN
203C FE0E ; text style; # (1.1 ‼︎ ) DOUBLE EXCLAMATION MARK
203C FE0F ; emoji style; # (1.1 ‼️ ) DOUBLE EXCLAMATION MARK
2049 FE0E ; text style; # (3.0 ⁉︎ ) EXCLAMATION QUESTION MARK
2049 FE0F ; emoji style; # (3.0 ⁉️ ) EXCLAMATION QUESTION MARK
2122 FE0E ; text style; # (1.1 ™︎ ) TRADE MARK SIGN
2122 FE0F ; emoji style; # (1.1 ™️ ) TRADE MARK SIGN
2139 FE0E ; text style; # (3.0 ℹ︎ ) INFORMATION SOURCE
2139 FE0F ; emoji style; # (3.0 ℹ️ ) INFORMATION SOURCE
2194 FE0E ; text style; # (1.1 ↔︎ ) LEFT RIGHT ARROW
2194 FE0F ; emoji style; # (1.1 ↔️ ) LEFT RIGHT ARROW
2195 FE0E ; text style; # (1.1 ↕︎ ) UP DOWN ARROW
2195 FE0F ; emoji style; # (1.1 ↕️ ) UP DOWN ARROW
2196 FE0E ; text style; # (1.1 ↖︎ ) NORTH WEST ARROW
2196 FE0F ; emoji style; # (1.1 ↖️ ) NORTH WEST ARROW
2197 FE0E ; text style; # (1.1 ↗︎ ) NORTH EAST ARROW
2197 FE0F ; emoji style; # (1.1 ↗️ ) NORTH EAST ARROW
2198 FE0E ; text style; # (1.1 ↘︎ ) SOUTH EAST ARROW
2198 FE0F ; emoji style; # (1.1 ↘️ ) SOUTH EAST ARROW
2199 FE0E ; text style; # (1.1 ↙︎ ) SOUTH WEST ARROW
2199 FE0F ; emoji style; # (1.1 ↙️ ) SOUTH WEST ARROW
21A9 FE0E ; text style; # (1.1 ↩︎ ) LEFTWARDS ARROW WITH HOOK
21A9 FE0F ; emoji style; # (1.1 ↩️ ) LEFTWARDS ARROW WITH HOOK
21AA FE0E ; text style; # (1.1 ↪︎ ) RIGHTWARDS ARROW WITH HOOK
21AA FE0F ; emoji style; # (1.1 ↪️ ) RIGHTWARDS ARROW WITH HOOK
231A FE0E ; text style; # (1.1 ⌚︎ ) WATCH
231A FE0F ; emoji style; # (1.1 ⌚️ ) WATCH
231B FE0E ; text style; # (1.1 ⌛︎ ) HOURGLASS
231B FE0F ; emoji style; # (1.1 ⌛️ ) HOURGLASS
2328 FE0E ; text style; # (1.1 ⌨︎ ) KEYBOARD
2328 FE0F ; emoji style; # (1.1 ⌨️ ) KEYBOARD
23CF FE0E ; text style; # (4.0 ⏏︎ ) EJECT SYMBOL
23CF FE0F ; emoji style; # (4.0 ⏏️ ) EJECT SYMBOL
23E9 FE0E ; text style; # (6.0 ⏩︎ ) BLACK RIGHT-POINTING DOUBLE TRIANGLE
23E9 FE0F ; emoji style; # (6.0 ⏩️ ) BLACK RIGHT-POINTING DOUBLE TRIANGLE
23EA FE0E ; text style; # (6.0 ⏪︎ ) BLACK LEFT-POINTING DOUBLE TRIANGLE
23EA FE0F ; emoji style; # (6.0 ⏪️ ) BLACK LEFT-POINTING DOUBLE TRIANGLE
23ED FE0E ; text style; # (6.0 ⏭︎ ) BLACK RIGHT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR
23ED FE0F ; emoji style; # (6.0 ⏭️ ) BLACK RIGHT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR
23EE FE0E ; text style; # (6.0 ⏮︎ ) BLACK LEFT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR
23EE FE0F ; emoji style; # (6.0 ⏮️ ) BLACK LEFT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR
23EF FE0E ; text style; # (6.0 ⏯︎ ) BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR
23EF FE0F ; emoji style; # (6.0 ⏯️ ) BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR
23F1 FE0E ; text style; # (6.0 ⏱︎ ) STOPWATCH
23F1 FE0F ; emoji style; # (6.0 ⏱️ ) STOPWATCH
23F2 FE0E ; text style; # (6.0 ⏲︎ ) TIMER CLOCK
23F2 FE0F ; emoji style; # (6.0 ⏲️ ) TIMER CLOCK
23F3 FE0E ; text style; # (6.0 ⏳︎ ) HOURGLASS WITH FLOWING SAND
23F3 FE0F ; emoji style; # (6.0 ⏳️ ) HOURGLASS WITH FLOWING SAND
23F8 FE0E ; text style; # (7.0 ⏸︎ ) DOUBLE VERTICAL BAR
23F8 FE0F ; emoji style; # (7.0 ⏸️ ) DOUBLE VERTICAL BAR
23F9 FE0E ; text style; # (7.0 ⏹︎ ) BLACK SQUARE FOR STOP
23F9 FE0F ; emoji style; # (7.0 ⏹️ ) BLACK SQUARE FOR STOP
23FA FE0E ; text style; # (7.0 ⏺︎ ) BLACK CIRCLE FOR RECORD
23FA FE0F ; emoji style; # (7.0 ⏺️ ) BLACK CIRCLE FOR RECORD
24C2 FE0E ; text style; # (1.1 Ⓜ︎ ) CIRCLED LATIN CAPITAL LETTER M
24C2 FE0F ; emoji style; # (1.1 Ⓜ️ ) CIRCLED LATIN CAPITAL LETTER M
25AA FE0E ; text style; # (1.1 ▪︎ ) BLACK SMALL SQUARE
25AA FE0F ; emoji style; # (1.1 ▪️ ) BLACK SMALL SQUARE
25AB FE0E ; text style; # (1.1 ▫︎ ) WHITE SMALL SQUARE
25AB FE0F ; emoji style; # (1.1 ▫️ ) WHITE SMALL SQUARE
25B6 FE0E ; text style; # (1.1 ▶︎ ) BLACK RIGHT-POINTING TRIANGLE
25B6 FE0F ; emoji style; # (1.1 ▶️ ) BLACK RIGHT-POINTING TRIANGLE
25C0 FE0E ; text style; # (1.1 ◀︎ ) BLACK LEFT-POINTING TRIANGLE
25C0 FE0F ; emoji style; # (1.1 ◀️ ) BLACK LEFT-POINTING TRIANGLE
25FB FE0E ; text style; # (3.2 ◻︎ ) WHITE MEDIUM SQUARE
25FB FE0F ; emoji style; # (3.2 ◻️ ) WHITE MEDIUM SQUARE
25FC FE0E ; text style; # (3.2 ◼︎ ) BLACK MEDIUM SQUARE
25FC FE0F ; emoji style; # (3.2 ◼️ ) BLACK MEDIUM SQUARE
25FD FE0E ; text style; # (3.2 ◽︎ ) WHITE MEDIUM SMALL SQUARE
25FD FE0F ; emoji style; # (3.2 ◽️ ) WHITE MEDIUM SMALL SQUARE
25FE FE0E ; text style; # (3.2 ◾︎ ) BLACK MEDIUM SMALL SQUARE
25FE FE0F ; emoji style; # (3.2 ◾️ ) BLACK MEDIUM SMALL SQUARE
2600 FE0E ; text style; # (1.1 ☀︎ ) BLACK SUN WITH RAYS
2600 FE0F ; emoji style; # (1.1 ☀️ ) BLACK SUN WITH RAYS
2601 FE0E ; text style; # (1.1 ☁︎ ) CLOUD
2601 FE0F ; emoji style; # (1.1 ☁️ ) CLOUD
2602 FE0E ; text style; # (1.1 ☂︎ ) UMBRELLA
2602 FE0F ; emoji style; # (1.1 ☂️ ) UMBRELLA
2603 FE0E ; text style; # (1.1 ☃︎ ) SNOWMAN
2603 FE0F ; emoji style; # (1.1 ☃️ ) SNOWMAN
2604 FE0E ; text style; # (1.1 ☄︎ ) COMET
2604 FE0F ; emoji style; # (1.1 ☄️ ) COMET
260E FE0E ; text style; # (1.1 ☎︎ ) BLACK TELEPHONE
260E FE0F ; emoji style; # (1.1 ☎️ ) BLACK TELEPHONE
2611 FE0E ; text style; # (1.1 ☑︎ ) BALLOT BOX WITH CHECK
2611 FE0F ; emoji style; # (1.1 ☑️ ) BALLOT BOX WITH CHECK
2614 FE0E ; text style; # (4.0 ☔︎ ) UMBRELLA WITH RAIN DROPS
2614 FE0F ; emoji style; # (4.0 ☔️ ) UMBRELLA WITH RAIN DROPS
2615 FE0E ; text style; # (4.0 ☕︎ ) HOT BEVERAGE
2615 FE0F ; emoji style; # (4.0 ☕️ ) HOT BEVERAGE
2618 FE0E ; text style; # (4.1 ☘︎ ) SHAMROCK
2618 FE0F ; emoji style; # (4.1 ☘️ ) SHAMROCK
261D FE0E ; text style; # (1.1 ☝︎ ) WHITE UP POINTING INDEX
261D FE0F ; emoji style; # (1.1 ☝️ ) WHITE UP POINTING INDEX
2620 FE0E ; text style; # (1.1 ☠︎ ) SKULL AND CROSSBONES
2620 FE0F ; emoji style; # (1.1 ☠️ ) SKULL AND CROSSBONES
2622 FE0E ; text style; # (1.1 ☢︎ ) RADIOACTIVE SIGN
2622 FE0F ; emoji style; # (1.1 ☢️ ) RADIOACTIVE SIGN
2623 FE0E ; text style; # (1.1 ☣︎ ) BIOHAZARD SIGN
2623 FE0F ; emoji style; # (1.1 ☣️ ) BIOHAZARD SIGN
2626 FE0E ; text style; # (1.1 ☦︎ ) ORTHODOX CROSS
2626 FE0F ; emoji style; # (1.1 ☦️ ) ORTHODOX CROSS
262A FE0E ; text style; # (1.1 ☪︎ ) STAR AND CRESCENT
262A FE0F ; emoji style; # (1.1 ☪️ ) STAR AND CRESCENT
262E FE0E ; text style; # (1.1 ☮︎ ) PEACE SYMBOL
262E FE0F ; emoji style; # (1.1 ☮️ ) PEACE SYMBOL
262F FE0E ; text style; # (1.1 ☯︎ ) YIN YANG
262F FE0F ; emoji style; # (1.1 ☯️ ) YIN YANG
2638 FE0E ; text style; # (1.1 ☸︎ ) WHEEL OF DHARMA
2638 FE0F ; emoji style; # (1.1 ☸️ ) WHEEL OF DHARMA
2639 FE0E ; text style; # (1.1 ☹︎ ) WHITE FROWNING FACE
2639 FE0F ; emoji style; # (1.1 ☹️ ) WHITE FROWNING FACE
263A FE0E ; text style; # (1.1 ☺︎ ) WHITE SMILING FACE
263A FE0F ; emoji style; # (1.1 ☺️ ) WHITE SMILING FACE
2640 FE0E ; text style; # (1.1 ♀︎ ) FEMALE SIGN
2640 FE0F ; emoji style; # (1.1 ♀️ ) FEMALE SIGN
2642 FE0E ; text style; # (1.1 ♂︎ ) MALE SIGN
2642 FE0F ; emoji style; # (1.1 ♂️ ) MALE SIGN
2648 FE0E ; text style; # (1.1 ♈︎ ) ARIES
2648 FE0F ; emoji style; # (1.1 ♈️ ) ARIES
2649 FE0E ; text style; # (1.1 ♉︎ ) TAURUS
2649 FE0F ; emoji style; # (1.1 ♉️ ) TAURUS
264A FE0E ; text style; # (1.1 ♊︎ ) GEMINI
264A FE0F ; emoji style; # (1.1 ♊️ ) GEMINI
264B FE0E ; text style; # (1.1 ♋︎ ) CANCER
264B FE0F ; emoji style; # (1.1 ♋️ ) CANCER
264C FE0E ; text style; # (1.1 ♌︎ ) LEO
264C FE0F ; emoji style; # (1.1 ♌️ ) LEO
264D FE0E ; text style; # (1.1 ♍︎ ) VIRGO
264D FE0F ; emoji style; # (1.1 ♍️ ) VIRGO
264E FE0E ; text style; # (1.1 ♎︎ ) LIBRA
264E FE0F ; emoji style; # (1.1 ♎️ ) LIBRA
264F FE0E ; text style; # (1.1 ♏︎ ) SCORPIUS
264F FE0F ; emoji style; # (1.1 ♏️ ) SCORPIUS
2650 FE0E ; text style; # (1.1 ♐︎ ) SAGITTARIUS
2650 FE0F ; emoji style; # (1.1 ♐️ ) SAGITTARIUS
2651 FE0E ; text style; # (1.1 ♑︎ ) CAPRICORN
2651 FE0F ; emoji style; # (1.1 ♑️ ) CAPRICORN
2652 FE0E ; text style; # (1.1 ♒︎ ) AQUARIUS
2652 FE0F ; emoji style; # (1.1 ♒️ ) AQUARIUS
2653 FE0E ; text style; # (1.1 ♓︎ ) PISCES
2653 FE0F ; emoji style; # (1.1 ♓️ ) PISCES
265F FE0E ; text style; # (1.1 ♟︎ ) BLACK CHESS PAWN
265F FE0F ; emoji style; # (1.1 ♟️ ) BLACK CHESS PAWN
2660 FE0E ; text style; # (1.1 ♠︎ ) BLACK SPADE SUIT
2660 FE0F ; emoji style; # (1.1 ♠️ ) BLACK SPADE SUIT
2663 FE0E ; text style; # (1.1 ♣︎ ) BLACK CLUB SUIT
2663 FE0F ; emoji style; # (1.1 ♣️ ) BLACK CLUB SUIT
2665 FE0E ; text style; # (1.1 ♥︎ ) BLACK HEART SUIT
2665 FE0F ; emoji style; # (1.1 ♥️ ) BLACK HEART SUIT
2666 FE0E ; text style; # (1.1 ♦︎ ) BLACK DIAMOND SUIT
2666 FE0F ; emoji style; # (1.1 ♦️ ) BLACK DIAMOND SUIT
2668 FE0E ; text style; # (1.1 ♨︎ ) HOT SPRINGS
2668 FE0F ; emoji style; # (1.1 ♨️ ) HOT SPRINGS
267B FE0E ; text style; # (3.2 ♻︎ ) BLACK UNIVERSAL RECYCLING SYMBOL
267B FE0F ; emoji style; # (3.2 ♻️ ) BLACK UNIVERSAL RECYCLING SYMBOL
267E FE0E ; text style; # (4.1 ♾︎ ) PERMANENT PAPER SIGN
267E FE0F ; emoji style; # (4.1 ♾️ ) PERMANENT PAPER SIGN
267F FE0E ; text style; # (4.1 ♿︎ ) WHEELCHAIR SYMBOL
267F FE0F ; emoji style; # (4.1 ♿️ ) WHEELCHAIR SYMBOL
2692 FE0E ; text style; # (4.1 ⚒︎ ) HAMMER AND PICK
2692 FE0F ; emoji style; # (4.1 ⚒️ ) HAMMER AND PICK
2693 FE0E ; text style; # (4.1 ⚓︎ ) ANCHOR
2693 FE0F ; emoji style; # (4.1 ⚓️ ) ANCHOR
2694 FE0E ; text style; # (4.1 ⚔︎ ) CROSSED SWORDS
2694 FE0F ; emoji style; # (4.1 ⚔️ ) CROSSED SWORDS
2695 FE0E ; text style; # (4.1 ⚕︎ ) STAFF OF AESCULAPIUS
2695 FE0F ; emoji style; # (4.1 ⚕️ ) STAFF OF AESCULAPIUS
2696 FE0E ; text style; # (4.1 ⚖︎ ) SCALES
2696 FE0F ; emoji style; # (4.1 ⚖️ ) SCALES
2697 FE0E ; text style; # (4.1 ⚗︎ ) ALEMBIC
2697 FE0F ; emoji style; # (4.1 ⚗️ ) ALEMBIC
2699 FE0E ; text style; # (4.1 ⚙︎ ) GEAR
2699 FE0F ; emoji style; # (4.1 ⚙️ ) GEAR
269B FE0E ; text style; # (4.1 ⚛︎ ) ATOM SYMBOL
269B FE0F ; emoji style; # (4.1 ⚛️ ) ATOM SYMBOL
269C FE0E ; text style; # (4.1 ⚜︎ ) FLEUR-DE-LIS
269C FE0F ; emoji style; # (4.1 ⚜️ ) FLEUR-DE-LIS
26A0 FE0E ; text style; # (4.0 ⚠︎ ) WARNING SIGN
26A0 FE0F ; emoji style; # (4.0 ⚠️ ) WARNING SIGN
26A1 FE0E ; text style; # (4.0 ⚡︎ ) HIGH VOLTAGE SIGN
26A1 FE0F ; emoji style; # (4.0 ⚡️ ) HIGH VOLTAGE SIGN
26A7 FE0E ; text style; # (4.1 ⚧︎ ) MALE WITH STROKE AND MALE AND FEMALE SIGN
26A7 FE0F ; emoji style; # (4.1 ⚧️ ) MALE WITH STROKE AND MALE AND FEMALE SIGN
26AA FE0E ; text style; # (4.1 ⚪︎ ) MEDIUM WHITE CIRCLE
26AA FE0F ; emoji style; # (4.1 ⚪️ ) MEDIUM WHITE CIRCLE
26AB FE0E ; text style; # (4.1 ⚫︎ ) MEDIUM BLACK CIRCLE
26AB FE0F ; emoji style; # (4.1 ⚫️ ) MEDIUM BLACK CIRCLE
26B0 FE0E ; text style; # (4.1 ⚰︎ ) COFFIN
26B0 FE0F ; emoji style; # (4.1 ⚰️ ) COFFIN
26B1 FE0E ; text style; # (4.1 ⚱︎ ) FUNERAL URN
26B1 FE0F ; emoji style; # (4.1 ⚱️ ) FUNERAL URN
26BD FE0E ; text style; # (5.2 ⚽︎ ) SOCCER BALL
26BD FE0F ; emoji style; # (5.2 ⚽️ ) SOCCER BALL
26BE FE0E ; text style; # (5.2 ⚾︎ ) BASEBALL
26BE FE0F ; emoji style; # (5.2 ⚾️ ) BASEBALL
26C4 FE0E ; text style; # (5.2 ⛄︎ ) SNOWMAN WITHOUT SNOW
26C4 FE0F ; emoji style; # (5.2 ⛄️ ) SNOWMAN WITHOUT SNOW
26C5 FE0E ; text style; # (5.2 ⛅︎ ) SUN BEHIND CLOUD
26C5 FE0F ; emoji style; # (5.2 ⛅️ ) SUN BEHIND CLOUD
26C8 FE0E ; text style; # (5.2 ⛈︎ ) THUNDER CLOUD AND RAIN
26C8 FE0F ; emoji style; # (5.2 ⛈️ ) THUNDER CLOUD AND RAIN
26CF FE0E ; text style; # (5.2 ⛏︎ ) PICK
26CF FE0F ; emoji style; # (5.2 ⛏️ ) PICK
26D1 FE0E ; text style; # (5.2 ⛑︎ ) HELMET WITH WHITE CROSS
26D1 FE0F ; emoji style; # (5.2 ⛑️ ) HELMET WITH WHITE CROSS
26D3 FE0E ; text style; # (5.2 ⛓︎ ) CHAINS
26D3 FE0F ; emoji style; # (5.2 ⛓️ ) CHAINS
26D4 FE0E ; text style; # (5.2 ⛔︎ ) NO ENTRY
26D4 FE0F ; emoji style; # (5.2 ⛔️ ) NO ENTRY
26E9 FE0E ; text style; # (5.2 ⛩︎ ) SHINTO SHRINE
26E9 FE0F ; emoji style; # (5.2 ⛩️ ) SHINTO SHRINE
26EA FE0E ; text style; # (5.2 ⛪︎ ) CHURCH
26EA FE0F ; emoji style; # (5.2 ⛪️ ) CHURCH
26F0 FE0E ; text style; # (5.2 ⛰︎ ) MOUNTAIN
26F0 FE0F ; emoji style; # (5.2 ⛰️ ) MOUNTAIN
26F1 FE0E ; text style; # (5.2 ⛱︎ ) UMBRELLA ON GROUND
26F1 FE0F ; emoji style; # (5.2 ⛱️ ) UMBRELLA ON GROUND
26F2 FE0E ; text style; # (5.2 ⛲︎ ) FOUNTAIN
26F2 FE0F ; emoji style; # (5.2 ⛲️ ) FOUNTAIN
26F3 FE0E ; text style; # (5.2 ⛳︎ ) FLAG IN HOLE
26F3 FE0F ; emoji style; # (5.2 ⛳️ ) FLAG IN HOLE
26F4 FE0E ; text style; # (5.2 ⛴︎ ) FERRY
26F4 FE0F ; emoji style; # (5.2 ⛴️ ) FERRY
26F5 FE0E ; text style; # (5.2 ⛵︎ ) SAILBOAT
26F5 FE0F ; emoji style; # (5.2 ⛵️ ) SAILBOAT
26F7 FE0E ; text style; # (5.2 ⛷︎ ) SKIER
26F7 FE0F ; emoji style; # (5.2 ⛷️ ) SKIER
26F8 FE0E ; text style; # (5.2 ⛸︎ ) ICE SKATE
26F8 FE0F ; emoji style; # (5.2 ⛸️ ) ICE SKATE
26F9 FE0E ; text style; # (5.2 ⛹︎ ) PERSON WITH BALL
26F9 FE0F ; emoji style; # (5.2 ⛹️ ) PERSON WITH BALL
26FA FE0E ; text style; # (5.2 ⛺︎ ) TENT
26FA FE0F ; emoji style; # (5.2 ⛺️ ) TENT
26FD FE0E ; text style; # (5.2 ⛽︎ ) FUEL PUMP
26FD FE0F ; emoji style; # (5.2 ⛽️ ) FUEL PUMP
2702 FE0E ; text style; # (1.1 ✂︎ ) BLACK SCISSORS
2702 FE0F ; emoji style; # (1.1 ✂️ ) BLACK SCISSORS
2708 FE0E ; text style; # (1.1 ✈︎ ) AIRPLANE
2708 FE0F ; emoji style; # (1.1 ✈️ ) AIRPLANE
2709 FE0E ; text style; # (1.1 ✉︎ ) ENVELOPE
2709 FE0F ; emoji style; # (1.1 ✉️ ) ENVELOPE
270C FE0E ; text style; # (1.1 ✌︎ ) VICTORY HAND
270C FE0F ; emoji style; # (1.1 ✌️ ) VICTORY HAND
270D FE0E ; text style; # (1.1 ✍︎ ) WRITING HAND
270D FE0F ; emoji style; # (1.1 ✍️ ) WRITING HAND
270F FE0E ; text style; # (1.1 ✏︎ ) PENCIL
270F FE0F ; emoji style; # (1.1 ✏️ ) PENCIL
2712 FE0E ; text style; # (1.1 ✒︎ ) BLACK NIB
2712 FE0F ; emoji style; # (1.1 ✒️ ) BLACK NIB
2714 FE0E ; text style; # (1.1 ✔︎ ) HEAVY CHECK MARK
2714 FE0F ; emoji style; # (1.1 ✔️ ) HEAVY CHECK MARK
2716 FE0E ; text style; # (1.1 ✖︎ ) HEAVY MULTIPLICATION X
2716 FE0F ; emoji style; # (1.1 ✖️ ) HEAVY MULTIPLICATION X
271D FE0E ; text style; # (1.1 ✝︎ ) LATIN CROSS
271D FE0F ; emoji style; # (1.1 ✝️ ) LATIN CROSS
2721 FE0E ; text style; # (1.1 ✡︎ ) STAR OF DAVID
2721 FE0F ; emoji style; # (1.1 ✡️ ) STAR OF DAVID
2733 FE0E ; text style; # (1.1 ✳︎ ) EIGHT SPOKED ASTERISK
2733 FE0F ; emoji style; # (1.1 ✳️ ) EIGHT SPOKED ASTERISK
2734 FE0E ; text style; # (1.1 ✴︎ ) EIGHT POINTED BLACK STAR
2734 FE0F ; emoji style; # (1.1 ✴️ ) EIGHT POINTED BLACK STAR
2744 FE0E ; text style; # (1.1 ❄︎ ) SNOWFLAKE
2744 FE0F ; emoji style; # (1.1 ❄️ ) SNOWFLAKE
2747 FE0E ; text style; # (1.1 ❇︎ ) SPARKLE
2747 FE0F ; emoji style; # (1.1 ❇️ ) SPARKLE
2753 FE0E ; text style; # (6.0 ❓︎ ) BLACK QUESTION MARK ORNAMENT
2753 FE0F ; emoji style; # (6.0 ❓️ ) BLACK QUESTION MARK ORNAMENT
2757 FE0E ; text style; # (5.2 ❗︎ ) HEAVY EXCLAMATION MARK SYMBOL
2757 FE0F ; emoji style; # (5.2 ❗️ ) HEAVY EXCLAMATION MARK SYMBOL
2763 FE0E ; text style; # (1.1 ❣︎ ) HEAVY HEART EXCLAMATION MARK ORNAMENT
2763 FE0F ; emoji style; # (1.1 ❣️ ) HEAVY HEART EXCLAMATION MARK ORNAMENT
2764 FE0E ; text style; # (1.1 ❤︎ ) HEAVY BLACK HEART
2764 FE0F ; emoji style; # (1.1 ❤️ ) HEAVY BLACK HEART
27A1 FE0E ; text style; # (1.1 ➡︎ ) BLACK RIGHTWARDS ARROW
27A1 FE0F ; emoji style; # (1.1 ➡️ ) BLACK RIGHTWARDS ARROW
2934 FE0E ; text style; # (3.2 ⤴︎ ) ARROW POINTING RIGHTWARDS THEN CURVING UPWARDS
2934 FE0F ; emoji style; # (3.2 ⤴️ ) ARROW POINTING RIGHTWARDS THEN CURVING UPWARDS
2935 FE0E ; text style; # (3.2 ⤵︎ ) ARROW POINTING RIGHTWARDS THEN CURVING DOWNWARDS
2935 FE0F ; emoji style; # (3.2 ⤵️ ) ARROW POINTING RIGHTWARDS THEN CURVING DOWNWARDS
2B05 FE0E ; text style; # (4.0 ⬅︎ ) LEFTWARDS BLACK ARROW
2B05 FE0F ; emoji style; # (4.0 ⬅️ ) LEFTWARDS BLACK ARROW
2B06 FE0E ; text style; # (4.0 ⬆︎ ) UPWARDS BLACK ARROW
2B06 FE0F ; emoji style; # (4.0 ⬆️ ) UPWARDS BLACK ARROW
2B07 FE0E ; text style; # (4.0 ⬇︎ ) DOWNWARDS BLACK ARROW
2B07 FE0F ; emoji style; # (4.0 ⬇️ ) DOWNWARDS BLACK ARROW
2B1B FE0E ; text style; # (5.1 ⬛︎ ) BLACK LARGE SQUARE
2B1B FE0F ; emoji style; # (5.1 ⬛️ ) BLACK LARGE SQUARE
2B1C FE0E ; text style; # (5.1 ⬜︎ ) WHITE LARGE SQUARE
2B1C FE0F ; emoji style; # (5.1 ⬜️ ) WHITE LARGE SQUARE
2B50 FE0E ; text style; # (5.1 ⭐︎ ) WHITE MEDIUM STAR
2B50 FE0F ; emoji style; # (5.1 ⭐️ ) WHITE MEDIUM STAR
2B55 FE0E ; text style; # (5.2 ⭕︎ ) HEAVY LARGE CIRCLE
2B55 FE0F ; emoji style; # (5.2 ⭕️ ) HEAVY LARGE CIRCLE
3030 FE0E ; text style; # (1.1 〰︎ ) WAVY DASH
3030 FE0F ; emoji style; # (1.1 〰️ ) WAVY DASH
303D FE0E ; text style; # (3.2 〽︎ ) PART ALTERNATION MARK
303D FE0F ; emoji style; # (3.2 〽️ ) PART ALTERNATION MARK
3297 FE0E ; text style; # (1.1 ㊗︎ ) CIRCLED IDEOGRAPH CONGRATULATION
3297 FE0F ; emoji style; # (1.1 ㊗️ ) CIRCLED IDEOGRAPH CONGRATULATION
3299 FE0E ; text style; # (1.1 ㊙︎ ) CIRCLED IDEOGRAPH SECRET
3299 FE0F ; emoji style; # (1.1 ㊙️ ) CIRCLED IDEOGRAPH SECRET
1F004 FE0E ; text style; # (5.1 🀄︎ ) MAHJONG TILE RED DRAGON
1F004 FE0F ; emoji style; # (5.1 🀄️ ) MAHJONG TILE RED DRAGON
1F170 FE0E ; text style; # (6.0 🅰︎ ) NEGATIVE SQUARED LATIN CAPITAL LETTER A
1F170 FE0F ; emoji style; # (6.0 🅰️ ) NEGATIVE SQUARED LATIN CAPITAL LETTER A
1F171 FE0E ; text style; # (6.0 🅱︎ ) NEGATIVE SQUARED LATIN CAPITAL LETTER B
1F171 FE0F ; emoji style; # (6.0 🅱️ ) NEGATIVE SQUARED LATIN CAPITAL LETTER B
1F17E FE0E ; text style; # (6.0 🅾︎ ) NEGATIVE SQUARED LATIN CAPITAL LETTER O
1F17E FE0F ; emoji style; # (6.0 🅾️ ) NEGATIVE SQUARED LATIN CAPITAL LETTER O
1F17F FE0E ; text style; # (5.2 🅿︎ ) NEGATIVE SQUARED LATIN CAPITAL LETTER P
1F17F FE0F ; emoji style; # (5.2 🅿️ ) NEGATIVE SQUARED LATIN CAPITAL LETTER P
1F202 FE0E ; text style; # (6.0 🈂︎ ) SQUARED KATAKANA SA
1F202 FE0F ; emoji style; # (6.0 🈂️ ) SQUARED KATAKANA SA
1F21A FE0E ; text style; # (5.2 🈚︎ ) SQUARED CJK UNIFIED IDEOGRAPH-7121
1F21A FE0F ; emoji style; # (5.2 🈚️ ) SQUARED CJK UNIFIED IDEOGRAPH-7121
1F22F FE0E ; text style; # (5.2 🈯︎ ) SQUARED CJK UNIFIED IDEOGRAPH-6307
1F22F FE0F ; emoji style; # (5.2 🈯️ ) SQUARED CJK UNIFIED IDEOGRAPH-6307
1F237 FE0E ; text style; # (6.0 🈷︎ ) SQUARED CJK UNIFIED IDEOGRAPH-6708
1F237 FE0F ; emoji style; # (6.0 🈷️ ) SQUARED CJK UNIFIED IDEOGRAPH-6708
1F30D FE0E ; text style; # (6.0 🌍︎ ) EARTH GLOBE EUROPE-AFRICA
1F30D FE0F ; emoji style; # (6.0 🌍️ ) EARTH GLOBE EUROPE-AFRICA
1F30E FE0E ; text style; # (6.0 🌎︎ ) EARTH GLOBE AMERICAS
1F30E FE0F ; emoji style; # (6.0 🌎️ ) EARTH GLOBE AMERICAS
1F30F FE0E ; text style; # (6.0 🌏︎ ) EARTH GLOBE ASIA-AUSTRALIA
1F30F FE0F ; emoji style; # (6.0 🌏️ ) EARTH GLOBE ASIA-AUSTRALIA
1F315 FE0E ; text style; # (6.0 🌕︎ ) FULL MOON SYMBOL
1F315 FE0F ; emoji style; # (6.0 🌕️ ) FULL MOON SYMBOL
1F31C FE0E ; text style; # (6.0 🌜︎ ) LAST QUARTER MOON WITH FACE
1F31C FE0F ; emoji style; # (6.0 🌜️ ) LAST QUARTER MOON WITH FACE
1F321 FE0E ; text style; # (7.0 🌡︎ ) THERMOMETER
1F321 FE0F ; emoji style; # (7.0 🌡️ ) THERMOMETER
1F324 FE0E ; text style; # (7.0 🌤︎ ) WHITE SUN WITH SMALL CLOUD
1F324 FE0F ; emoji style; # (7.0 🌤️ ) WHITE SUN WITH SMALL CLOUD
1F325 FE0E ; text style; # (7.0 🌥︎ ) WHITE SUN BEHIND CLOUD
1F325 FE0F ; emoji style; # (7.0 🌥️ ) WHITE SUN BEHIND CLOUD
1F326 FE0E ; text style; # (7.0 🌦︎ ) WHITE SUN BEHIND CLOUD WITH RAIN
1F326 FE0F ; emoji style; # (7.0 🌦️ ) WHITE SUN BEHIND CLOUD WITH RAIN
1F327 FE0E ; text style; # (7.0 🌧︎ ) CLOUD WITH RAIN
1F327 FE0F ; emoji style; # (7.0 🌧️ ) CLOUD WITH RAIN
1F328 FE0E ; text style; # (7.0 🌨︎ ) CLOUD WITH SNOW
1F328 FE0F ; emoji style; # (7.0 🌨️ ) CLOUD WITH SNOW
1F329 FE0E ; text style; # (7.0 🌩︎ ) CLOUD WITH LIGHTNING
1F329 FE0F ; emoji style; # (7.0 🌩️ ) CLOUD WITH LIGHTNING
1F32A FE0E ; text style; # (7.0 🌪︎ ) CLOUD WITH TORNADO
1F32A FE0F ; emoji style; # (7.0 🌪️ ) CLOUD WITH TORNADO
1F32B FE0E ; text style; # (7.0 🌫︎ ) FOG
1F32B FE0F ; emoji style; # (7.0 🌫️ ) FOG
1F32C FE0E ; text style; # (7.0 🌬︎ ) WIND BLOWING FACE
1F32C FE0F ; emoji style; # (7.0 🌬️ ) WIND BLOWING FACE
1F336 FE0E ; text style; # (7.0 🌶︎ ) HOT PEPPER
1F336 FE0F ; emoji style; # (7.0 🌶️ ) HOT PEPPER
1F378 FE0E ; text style; # (6.0 🍸︎ ) COCKTAIL GLASS
1F378 FE0F ; emoji style; # (6.0 🍸️ ) COCKTAIL GLASS
1F37D FE0E ; text style; # (7.0 🍽︎ ) FORK AND KNIFE WITH PLATE
1F37D FE0F ; emoji style; # (7.0 🍽️ ) FORK AND KNIFE WITH PLATE
1F393 FE0E ; text style; # (6.0 🎓︎ ) GRADUATION CAP
1F393 FE0F ; emoji style; # (6.0 🎓️ ) GRADUATION CAP
1F396 FE0E ; text style; # (7.0 🎖︎ ) MILITARY MEDAL
1F396 FE0F ; emoji style; # (7.0 🎖️ ) MILITARY MEDAL
1F397 FE0E ; text style; # (7.0 🎗︎ ) REMINDER RIBBON
1F397 FE0F ; emoji style; # (7.0 🎗️ ) REMINDER RIBBON
1F399 FE0E ; text style; # (7.0 🎙︎ ) STUDIO MICROPHONE
1F399 FE0F ; emoji style; # (7.0 🎙️ ) STUDIO MICROPHONE
1F39A FE0E ; text style; # (7.0 🎚︎ ) LEVEL SLIDER
1F39A FE0F ; emoji style; # (7.0 🎚️ ) LEVEL SLIDER
1F39B FE0E ; text style; # (7.0 🎛︎ ) CONTROL KNOBS
1F39B FE0F ; emoji style; # (7.0 🎛️ ) CONTROL KNOBS
1F39E FE0E ; text style; # (7.0 🎞︎ ) FILM FRAMES
1F39E FE0F ; emoji style; # (7.0 🎞️ ) FILM FRAMES
1F39F FE0E ; text style; # (7.0 🎟︎ ) ADMISSION TICKETS
1F39F FE0F ; emoji style; # (7.0 🎟️ ) ADMISSION TICKETS
1F3A7 FE0E ; text style; # (6.0 🎧︎ ) HEADPHONE
1F3A7 FE0F ; emoji style; # (6.0 🎧️ ) HEADPHONE
1F3AC FE0E ; text style; # (6.0 🎬︎ ) CLAPPER BOARD
1F3AC FE0F ; emoji style; # (6.0 🎬️ ) CLAPPER BOARD
1F3AD FE0E ; text style; # (6.0 🎭︎ ) PERFORMING ARTS
1F3AD FE0F ; emoji style; # (6.0 🎭️ ) PERFORMING ARTS
1F3AE FE0E ; text style; # (6.0 🎮︎ ) VIDEO GAME
1F3AE FE0F ; emoji style; # (6.0 🎮️ ) VIDEO GAME
1F3C2 FE0E ; text style; # (6.0 🏂︎ ) SNOWBOARDER
1F3C2 FE0F ; emoji style; # (6.0 🏂️ ) SNOWBOARDER
1F3C4 FE0E ; text style; # (6.0 🏄︎ ) SURFER
1F3C4 FE0F ; emoji style; # (6.0 🏄️ ) SURFER
1F3C6 FE0E ; text style; # (6.0 🏆︎ ) TROPHY
1F3C6 FE0F ; emoji style; # (6.0 🏆️ ) TROPHY
1F3CA FE0E ; text style; # (6.0 🏊︎ ) SWIMMER
1F3CA FE0F ; emoji style; # (6.0 🏊️ ) SWIMMER
1F3CB FE0E ; text style; # (7.0 🏋︎ ) WEIGHT LIFTER
1F3CB FE0F ; emoji style; # (7.0 🏋️ ) WEIGHT LIFTER
1F3CC FE0E ; text style; # (7.0 🏌︎ ) GOLFER
1F3CC FE0F ; emoji style; # (7.0 🏌️ ) GOLFER
1F3CD FE0E ; text style; # (7.0 🏍︎ ) RACING MOTORCYCLE
1F3CD FE0F ; emoji style; # (7.0 🏍️ ) RACING MOTORCYCLE
1F3CE FE0E ; text style; # (7.0 🏎︎ ) RACING CAR
1F3CE FE0F ; emoji style; # (7.0 🏎️ ) RACING CAR
1F3D4 FE0E ; text style; # (7.0 🏔︎ ) SNOW CAPPED MOUNTAIN
1F3D4 FE0F ; emoji style; # (7.0 🏔️ ) SNOW CAPPED MOUNTAIN
1F3D5 FE0E ; text style; # (7.0 🏕︎ ) CAMPING
1F3D5 FE0F ; emoji style; # (7.0 🏕️ ) CAMPING
1F3D6 FE0E ; text style; # (7.0 🏖︎ ) BEACH WITH UMBRELLA
1F3D6 FE0F ; emoji style; # (7.0 🏖️ ) BEACH WITH UMBRELLA
1F3D7 FE0E ; text style; # (7.0 🏗︎ ) BUILDING CONSTRUCTION
1F3D7 FE0F ; emoji style; # (7.0 🏗️ ) BUILDING CONSTRUCTION
1F3D8 FE0E ; text style; # (7.0 🏘︎ ) HOUSE BUILDINGS
1F3D8 FE0F ; emoji style; # (7.0 🏘️ ) HOUSE BUILDINGS
1F3D9 FE0E ; text style; # (7.0 🏙︎ ) CITYSCAPE
1F3D9 FE0F ; emoji style; # (7.0 🏙️ ) CITYSCAPE
1F3DA FE0E ; text style; # (7.0 🏚︎ ) DERELICT HOUSE BUILDING
1F3DA FE0F ; emoji style; # (7.0 🏚️ ) DERELICT HOUSE BUILDING
1F3DB FE0E ; text style; # (7.0 🏛︎ ) CLASSICAL BUILDING
1F3DB FE0F ; emoji style; # (7.0 🏛️ ) CLASSICAL BUILDING
1F3DC FE0E ; text style; # (7.0 🏜︎ ) DESERT
1F3DC FE0F ; emoji style; # (7.0 🏜️ ) DESERT
1F3DD FE0E ; text style; # (7.0 🏝︎ ) DESERT ISLAND
1F3DD FE0F ; emoji style; # (7.0 🏝️ ) DESERT ISLAND
1F3DE FE0E ; text style; # (7.0 🏞︎ ) NATIONAL PARK
1F3DE FE0F ; emoji style; # (7.0 🏞️ ) NATIONAL PARK
1F3DF FE0E ; text style; # (7.0 🏟︎ ) STADIUM
1F3DF FE0F ; emoji style; # (7.0 🏟️ ) STADIUM
1F3E0 FE0E ; text style; # (6.0 🏠︎ ) HOUSE BUILDING
1F3E0 FE0F ; emoji style; # (6.0 🏠️ ) HOUSE BUILDING
1F3ED FE0E ; text style; # (6.0 🏭︎ ) FACTORY
1F3ED FE0F ; emoji style; # (6.0 🏭️ ) FACTORY
1F3F3 FE0E ; text style; # (7.0 🏳︎ ) WAVING WHITE FLAG
1F3F3 FE0F ; emoji style; # (7.0 🏳️ ) WAVING WHITE FLAG
1F3F5 FE0E ; text style; # (7.0 🏵︎ ) ROSETTE
1F3F5 FE0F ; emoji style; # (7.0 🏵️ ) ROSETTE
1F3F7 FE0E ; text style; # (7.0 🏷︎ ) LABEL
1F3F7 FE0F ; emoji style; # (7.0 🏷️ ) LABEL
1F408 FE0E ; text style; # (6.0 🐈︎ ) CAT
1F408 FE0F ; emoji style; # (6.0 🐈️ ) CAT
1F415 FE0E ; text style; # (6.0 🐕︎ ) DOG
1F415 FE0F ; emoji style; # (6.0 🐕️ ) DOG
1F41F FE0E ; text style; # (6.0 🐟︎ ) FISH
1F41F FE0F ; emoji style; # (6.0 🐟️ ) FISH
1F426 FE0E ; text style; # (6.0 🐦︎ ) BIRD
1F426 FE0F ; emoji style; # (6.0 🐦️ ) BIRD
1F43F FE0E ; text style; # (7.0 🐿︎ ) CHIPMUNK
1F43F FE0F ; emoji style; # (7.0 🐿️ ) CHIPMUNK
1F441 FE0E ; text style; # (7.0 👁︎ ) EYE
1F441 FE0F ; emoji style; # (7.0 👁️ ) EYE
1F442 FE0E ; text style; # (6.0 👂︎ ) EAR
1F442 FE0F ; emoji style; # (6.0 👂️ ) EAR
1F446 FE0E ; text style; # (6.0 👆︎ ) WHITE UP POINTING BACKHAND INDEX
1F446 FE0F ; emoji style; # (6.0 👆️ ) WHITE UP POINTING BACKHAND INDEX
1F447 FE0E ; text style; # (6.0 👇︎ ) WHITE DOWN POINTING BACKHAND INDEX
1F447 FE0F ; emoji style; # (6.0 👇️ ) WHITE DOWN POINTING BACKHAND INDEX
1F448 FE0E ; text style; # (6.0 👈︎ ) WHITE LEFT POINTING BACKHAND INDEX
1F448 FE0F ; emoji style; # (6.0 👈️ ) WHITE LEFT POINTING BACKHAND INDEX
1F449 FE0E ; text style; # (6.0 👉︎ ) WHITE RIGHT POINTING BACKHAND INDEX
1F449 FE0F ; emoji style; # (6.0 👉️ ) WHITE RIGHT POINTING BACKHAND INDEX
1F44D FE0E ; text style; # (6.0 👍︎ ) THUMBS UP SIGN
1F44D FE0F ; emoji style; # (6.0 👍️ ) THUMBS UP SIGN
1F44E FE0E ; text style; # (6.0 👎︎ ) THUMBS DOWN SIGN
1F44E FE0F ; emoji style; # (6.0 👎️ ) THUMBS DOWN SIGN
1F453 FE0E ; text style; # (6.0 👓︎ ) EYEGLASSES
1F453 FE0F ; emoji style; # (6.0 👓️ ) EYEGLASSES
1F46A FE0E ; text style; # (6.0 👪︎ ) FAMILY
1F46A FE0F ; emoji style; # (6.0 👪️ ) FAMILY
1F47D FE0E ; text style; # (6.0 👽︎ ) EXTRATERRESTRIAL ALIEN
1F47D FE0F ; emoji style; # (6.0 👽️ ) EXTRATERRESTRIAL ALIEN
1F4A3 FE0E ; text style; # (6.0 💣︎ ) BOMB
1F4A3 FE0F ; emoji style; # (6.0 💣️ ) BOMB
1F4B0 FE0E ; text style; # (6.0 💰︎ ) MONEY BAG
1F4B0 FE0F ; emoji style; # (6.0 💰️ ) MONEY BAG
1F4B3 FE0E ; text style; # (6.0 💳︎ ) CREDIT CARD
1F4B3 FE0F ; emoji style; # (6.0 💳️ ) CREDIT CARD
1F4BB FE0E ; text style; # (6.0 💻︎ ) PERSONAL COMPUTER
1F4BB FE0F ; emoji style; # (6.0 💻️ ) PERSONAL COMPUTER
1F4BF FE0E ; text style; # (6.0 💿︎ ) OPTICAL DISC
1F4BF FE0F ; emoji style; # (6.0 💿️ ) OPTICAL DISC
1F4CB FE0E ; text style; # (6.0 📋︎ ) CLIPBOARD
1F4CB FE0F ; emoji style; # (6.0 📋️ ) CLIPBOARD
1F4DA FE0E ; text style; # (6.0 📚︎ ) BOOKS
1F4DA FE0F ; emoji style; # (6.0 📚️ ) BOOKS
1F4DF FE0E ; text style; # (6.0 📟︎ ) PAGER
1F4DF FE0F ; emoji style; # (6.0 📟️ ) PAGER
1F4E4 FE0E ; text style; # (6.0 📤︎ ) OUTBOX TRAY
1F4E4 FE0F ; emoji style; # (6.0 📤️ ) OUTBOX TRAY
1F4E5 FE0E ; text style; # (6.0 📥︎ ) INBOX TRAY
1F4E5 FE0F ; emoji style; # (6.0 📥️ ) INBOX TRAY
1F4E6 FE0E ; text style; # (6.0 📦︎ ) PACKAGE
1F4E6 FE0F ; emoji style; # (6.0 📦️ ) PACKAGE
1F4EA FE0E ; text style; # (6.0 📪︎ ) CLOSED MAILBOX WITH LOWERED FLAG
1F4EA FE0F ; emoji style; # (6.0 📪️ ) CLOSED MAILBOX WITH LOWERED FLAG
1F4EB FE0E ; text style; # (6.0 📫︎ ) CLOSED MAILBOX WITH RAISED FLAG
1F4EB FE0F ; emoji style; # (6.0 📫️ ) CLOSED MAILBOX WITH RAISED FLAG
1F4EC FE0E ; text style; # (6.0 📬︎ ) OPEN MAILBOX WITH RAISED FLAG
1F4EC FE0F ; emoji style; # (6.0 📬️ ) OPEN MAILBOX WITH RAISED FLAG
1F4ED FE0E ; text style; # (6.0 📭︎ ) OPEN MAILBOX WITH LOWERED FLAG
1F4ED FE0F ; emoji style; # (6.0 📭️ ) OPEN MAILBOX WITH LOWERED FLAG
1F4F7 FE0E ; text style; # (6.0 📷︎ ) CAMERA
1F4F7 FE0F ; emoji style; # (6.0 📷️ ) CAMERA
1F4F9 FE0E ; text style; # (6.0 📹︎ ) VIDEO CAMERA
1F4F9 FE0F ; emoji style; # (6.0 📹️ ) VIDEO CAMERA
1F4FA FE0E ; text style; # (6.0 📺︎ ) TELEVISION
1F4FA FE0F ; emoji style; # (6.0 📺️ ) TELEVISION
1F4FB FE0E ; text style; # (6.0 📻︎ ) RADIO
1F4FB FE0F ; emoji style; # (6.0 📻️ ) RADIO
1F4FD FE0E ; text style; # (7.0 📽︎ ) FILM PROJECTOR
1F4FD FE0F ; emoji style; # (7.0 📽️ ) FILM PROJECTOR
1F508 FE0E ; text style; # (6.0 🔈︎ ) SPEAKER
1F508 FE0F ; emoji style; # (6.0 🔈️ ) SPEAKER
1F50D FE0E ; text style; # (6.0 🔍︎ ) LEFT-POINTING MAGNIFYING GLASS
1F50D FE0F ; emoji style; # (6.0 🔍️ ) LEFT-POINTING MAGNIFYING GLASS
1F512 FE0E ; text style; # (6.0 🔒︎ ) LOCK
1F512 FE0F ; emoji style; # (6.0 🔒️ ) LOCK
1F513 FE0E ; text style; # (6.0 🔓︎ ) OPEN LOCK
1F513 FE0F ; emoji style; # (6.0 🔓️ ) OPEN LOCK
1F549 FE0E ; text style; # (7.0 🕉︎ ) OM SYMBOL
1F549 FE0F ; emoji style; # (7.0 🕉️ ) OM SYMBOL
1F54A FE0E ; text style; # (7.0 🕊︎ ) DOVE OF PEACE
1F54A FE0F ; emoji style; # (7.0 🕊️ ) DOVE OF PEACE
1F550 FE0E ; text style; # (6.0 🕐︎ ) CLOCK FACE ONE OCLOCK
1F550 FE0F ; emoji style; # (6.0 🕐️ ) CLOCK FACE ONE OCLOCK
1F551 FE0E ; text style; # (6.0 🕑︎ ) CLOCK FACE TWO OCLOCK
1F551 FE0F ; emoji style; # (6.0 🕑️ ) CLOCK FACE TWO OCLOCK
1F552 FE0E ; text style; # (6.0 🕒︎ ) CLOCK FACE THREE OCLOCK
1F552 FE0F ; emoji style; # (6.0 🕒️ ) CLOCK FACE THREE OCLOCK
1F553 FE0E ; text style; # (6.0 🕓︎ ) CLOCK FACE FOUR OCLOCK
1F553 FE0F ; emoji style; # (6.0 🕓️ ) CLOCK FACE FOUR OCLOCK
1F554 FE0E ; text style; # (6.0 🕔︎ ) CLOCK FACE FIVE OCLOCK
1F554 FE0F ; emoji style; # (6.0 🕔️ ) CLOCK FACE FIVE OCLOCK
1F555 FE0E ; text style; # (6.0 🕕︎ ) CLOCK FACE SIX OCLOCK
1F555 FE0F ; emoji style; # (6.0 🕕️ ) CLOCK FACE SIX OCLOCK
1F556 FE0E ; text style; # (6.0 🕖︎ ) CLOCK FACE SEVEN OCLOCK
1F556 FE0F ; emoji style; # (6.0 🕖️ ) CLOCK FACE SEVEN OCLOCK
1F557 FE0E ; text style; # (6.0 🕗︎ ) CLOCK FACE EIGHT OCLOCK
1F557 FE0F ; emoji style; # (6.0 🕗️ ) CLOCK FACE EIGHT OCLOCK
1F558 FE0E ; text style; # (6.0 🕘︎ ) CLOCK FACE NINE OCLOCK
1F558 FE0F ; emoji style; # (6.0 🕘️ ) CLOCK FACE NINE OCLOCK
1F559 FE0E ; text style; # (6.0 🕙︎ ) CLOCK FACE TEN OCLOCK
1F559 FE0F ; emoji style; # (6.0 🕙️ ) CLOCK FACE TEN OCLOCK
1F55A FE0E ; text style; # (6.0 🕚︎ ) CLOCK FACE ELEVEN OCLOCK
1F55A FE0F ; emoji style; # (6.0 🕚️ ) CLOCK FACE ELEVEN OCLOCK
1F55B FE0E ; text style; # (6.0 🕛︎ ) CLOCK FACE TWELVE OCLOCK
1F55B FE0F ; emoji style; # (6.0 🕛️ ) CLOCK FACE TWELVE OCLOCK
1F55C FE0E ; text style; # (6.0 🕜︎ ) CLOCK FACE ONE-THIRTY
1F55C FE0F ; emoji style; # (6.0 🕜️ ) CLOCK FACE ONE-THIRTY
1F55D FE0E ; text style; # (6.0 🕝︎ ) CLOCK FACE TWO-THIRTY
1F55D FE0F ; emoji style; # (6.0 🕝️ ) CLOCK FACE TWO-THIRTY
1F55E FE0E ; text style; # (6.0 🕞︎ ) CLOCK FACE THREE-THIRTY
1F55E FE0F ; emoji style; # (6.0 🕞️ ) CLOCK FACE THREE-THIRTY
1F55F FE0E ; text style; # (6.0 🕟︎ ) CLOCK FACE FOUR-THIRTY
1F55F FE0F ; emoji style; # (6.0 🕟️ ) CLOCK FACE FOUR-THIRTY
1F560 FE0E ; text style; # (6.0 🕠︎ ) CLOCK FACE FIVE-THIRTY
1F560 FE0F ; emoji style; # (6.0 🕠️ ) CLOCK FACE FIVE-THIRTY
1F561 FE0E ; text style; # (6.0 🕡︎ ) CLOCK FACE SIX-THIRTY
1F561 FE0F ; emoji style; # (6.0 🕡️ ) CLOCK FACE SIX-THIRTY
1F562 FE0E ; text style; # (6.0 🕢︎ ) CLOCK FACE SEVEN-THIRTY
1F562 FE0F ; emoji style; # (6.0 🕢️ ) CLOCK FACE SEVEN-THIRTY
1F563 FE0E ; text style; # (6.0 🕣︎ ) CLOCK FACE EIGHT-THIRTY
1F563 FE0F ; emoji style; # (6.0 🕣️ ) CLOCK FACE EIGHT-THIRTY
1F564 FE0E ; text style; # (6.0 🕤︎ ) CLOCK FACE NINE-THIRTY
1F564 FE0F ; emoji style; # (6.0 🕤️ ) CLOCK FACE NINE-THIRTY
1F565 FE0E ; text style; # (6.0 🕥︎ ) CLOCK FACE TEN-THIRTY
1F565 FE0F ; emoji style; # (6.0 🕥️ ) CLOCK FACE TEN-THIRTY
1F566 FE0E ; text style; # (6.0 🕦︎ ) CLOCK FACE ELEVEN-THIRTY
1F566 FE0F ; emoji style; # (6.0 🕦️ ) CLOCK FACE ELEVEN-THIRTY
1F567 FE0E ; text style; # (6.0 🕧︎ ) CLOCK FACE TWELVE-THIRTY
1F567 FE0F ; emoji style; # (6.0 🕧️ ) CLOCK FACE TWELVE-THIRTY
1F56F FE0E ; text style; # (7.0 🕯︎ ) CANDLE
1F56F FE0F ; emoji style; # (7.0 🕯️ ) CANDLE
1F570 FE0E ; text style; # (7.0 🕰︎ ) MANTELPIECE CLOCK
1F570 FE0F ; emoji style; # (7.0 🕰️ ) MANTELPIECE CLOCK
1F573 FE0E ; text style; # (7.0 🕳︎ ) HOLE
1F573 FE0F ; emoji style; # (7.0 🕳️ ) HOLE
1F574 FE0E ; text style; # (7.0 🕴︎ ) MAN IN BUSINESS SUIT LEVITATING
1F574 FE0F ; emoji style; # (7.0 🕴️ ) MAN IN BUSINESS SUIT LEVITATING
1F575 FE0E ; text style; # (7.0 🕵︎ ) SLEUTH OR SPY
1F575 FE0F ; emoji style; # (7.0 🕵️ ) SLEUTH OR SPY
1F576 FE0E ; text style; # (7.0 🕶︎ ) DARK SUNGLASSES
1F576 FE0F ; emoji style; # (7.0 🕶️ ) DARK SUNGLASSES
1F577 FE0E ; text style; # (7.0 🕷︎ ) SPIDER
1F577 FE0F ; emoji style; # (7.0 🕷️ ) SPIDER
1F578 FE0E ; text style; # (7.0 🕸︎ ) SPIDER WEB
1F578 FE0F ; emoji style; # (7.0 🕸️ ) SPIDER WEB
1F579 FE0E ; text style; # (7.0 🕹︎ ) JOYSTICK
1F579 FE0F ; emoji style; # (7.0 🕹️ ) JOYSTICK
1F587 FE0E ; text style; # (7.0 🖇︎ ) LINKED PAPERCLIPS
1F587 FE0F ; emoji style; # (7.0 🖇️ ) LINKED PAPERCLIPS
1F58A FE0E ; text style; # (7.0 🖊︎ ) LOWER LEFT BALLPOINT PEN
1F58A FE0F ; emoji style; # (7.0 🖊️ ) LOWER LEFT BALLPOINT PEN
1F58B FE0E ; text style; # (7.0 🖋︎ ) LOWER LEFT FOUNTAIN PEN
1F58B FE0F ; emoji style; # (7.0 🖋️ ) LOWER LEFT FOUNTAIN PEN
1F58C FE0E ; text style; # (7.0 🖌︎ ) LOWER LEFT PAINTBRUSH
1F58C FE0F ; emoji style; # (7.0 🖌️ ) LOWER LEFT PAINTBRUSH
1F58D FE0E ; text style; # (7.0 🖍︎ ) LOWER LEFT CRAYON
1F58D FE0F ; emoji style; # (7.0 🖍️ ) LOWER LEFT CRAYON
1F590 FE0E ; text style; # (7.0 🖐︎ ) RAISED HAND WITH FINGERS SPLAYED
1F590 FE0F ; emoji style; # (7.0 🖐️ ) RAISED HAND WITH FINGERS SPLAYED
1F5A5 FE0E ; text style; # (7.0 🖥︎ ) DESKTOP COMPUTER
1F5A5 FE0F ; emoji style; # (7.0 🖥️ ) DESKTOP COMPUTER
1F5A8 FE0E ; text style; # (7.0 🖨︎ ) PRINTER
1F5A8 FE0F ; emoji style; # (7.0 🖨️ ) PRINTER
1F5B1 FE0E ; text style; # (7.0 🖱︎ ) THREE BUTTON MOUSE
1F5B1 FE0F ; emoji style; # (7.0 🖱️ ) THREE BUTTON MOUSE
1F5B2 FE0E ; text style; # (7.0 🖲︎ ) TRACKBALL
1F5B2 FE0F ; emoji style; # (7.0 🖲️ ) TRACKBALL
1F5BC FE0E ; text style; # (7.0 🖼︎ ) FRAME WITH PICTURE
1F5BC FE0F ; emoji style; # (7.0 🖼️ ) FRAME WITH PICTURE
1F5C2 FE0E ; text style; # (7.0 🗂︎ ) CARD INDEX DIVIDERS
1F5C2 FE0F ; emoji style; # (7.0 🗂️ ) CARD INDEX DIVIDERS
1F5C3 FE0E ; text style; # (7.0 🗃︎ ) CARD FILE BOX
1F5C3 FE0F ; emoji style; # (7.0 🗃️ ) CARD FILE BOX
1F5C4 FE0E ; text style; # (7.0 🗄︎ ) FILE CABINET
1F5C4 FE0F ; emoji style; # (7.0 🗄️ ) FILE CABINET
1F5D1 FE0E ; text style; # (7.0 🗑︎ ) WASTEBASKET
1F5D1 FE0F ; emoji style; # (7.0 🗑️ ) WASTEBASKET
1F5D2 FE0E ; text style; # (7.0 🗒︎ ) SPIRAL NOTE PAD
1F5D2 FE0F ; emoji style; # (7.0 🗒️ ) SPIRAL NOTE PAD
1F5D3 FE0E ; text style; # (7.0 🗓︎ ) SPIRAL CALENDAR PAD
1F5D3 FE0F ; emoji style; # (7.0 🗓️ ) SPIRAL CALENDAR PAD
1F5DC FE0E ; text style; # (7.0 🗜︎ ) COMPRESSION
1F5DC FE0F ; emoji style; # (7.0 🗜️ ) COMPRESSION
1F5DD FE0E ; text style; # (7.0 🗝︎ ) OLD KEY
1F5DD FE0F ; emoji style; # (7.0 🗝️ ) OLD KEY
1F5DE FE0E ; text style; # (7.0 🗞︎ ) ROLLED-UP NEWSPAPER
1F5DE FE0F ; emoji style; # (7.0 🗞️ ) ROLLED-UP NEWSPAPER
1F5E1 FE0E ; text style; # (7.0 🗡︎ ) DAGGER KNIFE
1F5E1 FE0F ; emoji style; # (7.0 🗡️ ) DAGGER KNIFE
1F5E3 FE0E ; text style; # (7.0 🗣︎ ) SPEAKING HEAD IN SILHOUETTE
1F5E3 FE0F ; emoji style; # (7.0 🗣️ ) SPEAKING HEAD IN SILHOUETTE
1F5E8 FE0E ; text style; # (7.0 🗨︎ ) LEFT SPEECH BUBBLE
1F5E8 FE0F ; emoji style; # (7.0 🗨️ ) LEFT SPEECH BUBBLE
1F5EF FE0E ; text style; # (7.0 🗯︎ ) RIGHT ANGER BUBBLE
1F5EF FE0F ; emoji style; # (7.0 🗯️ ) RIGHT ANGER BUBBLE
1F5F3 FE0E ; text style; # (7.0 🗳︎ ) BALLOT BOX WITH BALLOT
1F5F3 FE0F ; emoji style; # (7.0 🗳️ ) BALLOT BOX WITH BALLOT
1F5FA FE0E ; text style; # (7.0 🗺︎ ) WORLD MAP
1F5FA FE0F ; emoji style; # (7.0 🗺️ ) WORLD MAP
1F610 FE0E ; text style; # (6.0 😐︎ ) NEUTRAL FACE
1F610 FE0F ; emoji style; # (6.0 😐️ ) NEUTRAL FACE
1F687 FE0E ; text style; # (6.0 🚇︎ ) METRO
1F687 FE0F ; emoji style; # (6.0 🚇️ ) METRO
1F68D FE0E ; text style; # (6.0 🚍︎ ) ONCOMING BUS
1F68D FE0F ; emoji style; # (6.0 🚍️ ) ONCOMING BUS
1F691 FE0E ; text style; # (6.0 🚑︎ ) AMBULANCE
1F691 FE0F ; emoji style; # (6.0 🚑️ ) AMBULANCE
1F694 FE0E ; text style; # (6.0 🚔︎ ) ONCOMING POLICE CAR
1F694 FE0F ; emoji style; # (6.0 🚔️ ) ONCOMING POLICE CAR
1F698 FE0E ; text style; # (6.0 🚘︎ ) ONCOMING AUTOMOBILE
1F698 FE0F ; emoji style; # (6.0 🚘️ ) ONCOMING AUTOMOBILE
1F6AD FE0E ; text style; # (6.0 🚭︎ ) NO SMOKING SYMBOL
1F6AD FE0F ; emoji style; # (6.0 🚭️ ) NO SMOKING SYMBOL
1F6B2 FE0E ; text style; # (6.0 🚲︎ ) BICYCLE
1F6B2 FE0F ; emoji style; # (6.0 🚲️ ) BICYCLE
1F6B9 FE0E ; text style; # (6.0 🚹︎ ) MENS SYMBOL
1F6B9 FE0F ; emoji style; # (6.0 🚹️ ) MENS SYMBOL
1F6BA FE0E ; text style; # (6.0 🚺︎ ) WOMENS SYMBOL
1F6BA FE0F ; emoji style; # (6.0 🚺️ ) WOMENS SYMBOL
1F6BC FE0E ; text style; # (6.0 🚼︎ ) BABY SYMBOL
1F6BC FE0F ; emoji style; # (6.0 🚼️ ) BABY SYMBOL
1F6CB FE0E ; text style; # (7.0 🛋︎ ) COUCH AND LAMP
1F6CB FE0F ; emoji style; # (7.0 🛋️ ) COUCH AND LAMP
1F6CD FE0E ; text style; # (7.0 🛍︎ ) SHOPPING BAGS
1F6CD FE0F ; emoji style; # (7.0 🛍️ ) SHOPPING BAGS
1F6CE FE0E ; text style; # (7.0 🛎︎ ) BELLHOP BELL
1F6CE FE0F ; emoji style; # (7.0 🛎️ ) BELLHOP BELL
1F6CF FE0E ; text style; # (7.0 🛏︎ ) BED
1F6CF FE0F ; emoji style; # (7.0 🛏️ ) BED
1F6E0 FE0E ; text style; # (7.0 🛠︎ ) HAMMER AND WRENCH
1F6E0 FE0F ; emoji style; # (7.0 🛠️ ) HAMMER AND WRENCH
1F6E1 FE0E ; text style; # (7.0 🛡︎ ) SHIELD
1F6E1 FE0F ; emoji style; # (7.0 🛡️ ) SHIELD
1F6E2 FE0E ; text style; # (7.0 🛢︎ ) OIL DRUM
1F6E2 FE0F ; emoji style; # (7.0 🛢️ ) OIL DRUM
1F6E3 FE0E ; text style; # (7.0 🛣︎ ) MOTORWAY
1F6E3 FE0F ; emoji style; # (7.0 🛣️ ) MOTORWAY
1F6E4 FE0E ; text style; # (7.0 🛤︎ ) RAILWAY TRACK
1F6E4 FE0F ; emoji style; # (7.0 🛤️ ) RAILWAY TRACK
1F6E5 FE0E ; text style; # (7.0 🛥︎ ) MOTOR BOAT
1F6E5 FE0F ; emoji style; # (7.0 🛥️ ) MOTOR BOAT
1F6E9 FE0E ; text style; # (7.0 🛩︎ ) SMALL AIRPLANE
1F6E9 FE0F ; emoji style; # (7.0 🛩️ ) SMALL AIRPLANE
1F6F0 FE0E ; text style; # (7.0 🛰︎ ) SATELLITE
1F6F0 FE0F ; emoji style; # (7.0 🛰️ ) SATELLITE
1F6F3 FE0E ; text style; # (7.0 🛳︎ ) PASSENGER SHIP
1F6F3 FE0F ; emoji style; # (7.0 🛳️ ) PASSENGER SHIP
#Total sequences: 354
#EOF

3
admin/unidata/emoji-zwj.awk
View file

@ -106,7 +106,8 @@ END {
for (elt in ch)
{
printf("(#x%s .\n,(eval-when-compile (regexp-opt\n'(\n%s\n))))\n", elt, vec[elt])
entries = vec[elt] sprintf("\n\"\\N{U+%s}\\N{U+FE0E}\"\n\"\\N{U+%s}\\N{U+FE0F}\"", elt, elt)
printf("(#x%s .\n,(eval-when-compile (regexp-opt\n'(\n%s\n))))\n", elt, entries)
}
print "))"
print " (set-char-table-range composition-function-table"

3
autogen.sh
View file

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

128
build-aux/git-hooks/commit-msg-files.awk Normal file
View file

@ -0,0 +1,128 @@
# 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
}

47
build-aux/git-hooks/post-commit Executable file
View file

@ -0,0 +1,47 @@
#!/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

88
build-aux/git-hooks/pre-push Executable file
View file

@ -0,0 +1,88 @@
#!/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

139
configure.ac
View file

@ -459,6 +459,7 @@ OPTION_DEFAULT_ON([sqlite3],[don't compile with sqlite3 support])
OPTION_DEFAULT_ON([lcms2],[don't compile with Little CMS support])
OPTION_DEFAULT_ON([libsystemd],[don't compile with libsystemd support])
OPTION_DEFAULT_ON([cairo],[don't compile with Cairo drawing])
OPTION_DEFAULT_OFF([cairo-xcb], [use XCB surfaces for Cairo support])
OPTION_DEFAULT_ON([xml2],[don't compile with XML parsing support])
OPTION_DEFAULT_OFF([imagemagick],[compile with ImageMagick image support])
OPTION_DEFAULT_ON([native-image-api], [don't use native image APIs (GDI+ on Windows)])
@ -1001,7 +1002,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 -e "$srcdir"/.git && test ! -f "$srcdir"/.tarball-version; then
if test -d "$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],
@ -1136,6 +1137,8 @@ AS_IF([test $gl_gcc_warnings = no],
gl_WARN_ADD([-Wno-unused-parameter]) # Too many warnings for now
gl_WARN_ADD([-Wno-format-nonliteral])
gl_WARN_ADD([-Wno-bidi-chars])
AS_IF([test $gl_gcc_warnings = yes],
[gl_WARN_ADD([-Wno-analyzer-fd-leak])]) # GCC bug 109839
# clang is unduly picky about some things.
if test "$emacs_cv_clang" = yes; then
@ -1643,7 +1646,8 @@ case "$opsys" in
## Motif needs -lgen.
unixware) LIBS_SYSTEM="-lsocket -lnsl -lelf -lgen" ;;
haiku) LIBS_SYSTEM="-lnetwork" ;;
# Haiku needs -lbsd for cfsetspeed.
haiku) LIBS_SYSTEM="-lnetwork -lbsd" ;;
esac
AC_SUBST([LIBS_SYSTEM])
@ -2033,37 +2037,29 @@ 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 -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
CFLAGS="$CFLAGS -I${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
CPPFLAGS="$CPPFLAGS -isystem ${GNUSTEP_SYSTEM_HEADERS} ${GNUSTEP_LOCAL_HEADERS}"
CFLAGS="$CFLAGS -isystem ${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.
@ -2776,6 +2772,25 @@ 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
@ -3557,14 +3572,14 @@ if test "${HAVE_X11}" = "yes"; then
CAIRO_MODULE="cairo >= $CAIRO_REQUIRED"
EMACS_CHECK_MODULES([CAIRO], [$CAIRO_MODULE])
if test $HAVE_CAIRO = yes; then
CAIRO_XCB_MODULE="cairo-xcb >= $CAIRO_REQUIRED"
EMACS_CHECK_MODULES([CAIRO_XCB], [$CAIRO_XCB_MODULE])
if test $HAVE_CAIRO_XCB = yes; then
CAIRO_CFLAGS="$CAIRO_CFLAGS $CAIRO_XCB_CFLAGS"
CAIRO_LIBS="$CAIRO_LIBS $CAIRO_XCB_LIBS"
AC_DEFINE([USE_CAIRO_XCB], [1],
[Define to 1 if cairo XCB surfaces are available.])
fi
AS_IF([test "x$with_cairo_xcb" = "xyes"], [
CAIRO_XCB_MODULE="cairo-xcb >= $CAIRO_REQUIRED"
EMACS_CHECK_MODULES([CAIRO_XCB], [$CAIRO_XCB_MODULE])
AS_IF([test "x$HAVE_CAIRO_XCB" = "xyes"], [
CAIRO_CFLAGS="$CAIRO_CFLAGS $CAIRO_XCB_CFLAGS"
CAIRO_LIBS="$CAIRO_LIBS $CAIRO_XCB_LIBS"
AC_DEFINE([USE_CAIRO_XCB], [1],
[Define to 1 if cairo XCB surfaces are available.])])])
AC_DEFINE([USE_CAIRO], [1], [Define to 1 if using cairo.])
CFLAGS="$CFLAGS $CAIRO_CFLAGS"
LIBS="$LIBS $CAIRO_LIBS"
@ -3761,7 +3776,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
if $PKG_CONFIG --atleast-version=0.9.16 libotf; then :; else
AC_DEFINE([HAVE_OTF_KANNADA_BUG], [1],
[Define to 1 if libotf is affected by https://debbugs.gnu.org/28110.])
fi
@ -3869,7 +3884,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
if $PKG_CONFIG --atleast-version=0.9.16 libotf; then :; else
AC_DEFINE([HAVE_OTF_KANNADA_BUG], [1],
[Define to 1 if libotf is affected by https://debbugs.gnu.org/28110.])
fi
@ -4187,7 +4202,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="${PACKAGE_VERSION%%.*}"
emacs_major_version=`AS_ECHO([$PACKAGE_VERSION]) | sed 's/[[.]].*//'`
AC_SUBST([emacs_major_version])
### Emacs Lisp native compiler support
@ -4270,8 +4285,8 @@ If you really want to try it anyway, use the configure option
fi
if test "${with_native_compilation}" != "no"; then
if test "${HAVE_PDUMPER}" = no; then
AC_MSG_ERROR(['--with-native-compilation' requires '--with-dumping=pdumper'])
if test "$with_unexec" = yes; then
AC_MSG_ERROR(['--with-native-compilation' is not compatible with unexec])
fi
if test "${HAVE_ZLIB}" = no; then
AC_MSG_ERROR(['--with-native-compilation' requires zlib])
@ -4297,14 +4312,16 @@ 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
MAC_CFLAGS="-I$(dirname $(port contents $PORT_PACKAGE | \
grep libgccjit.h))"
MAC_LIBS="-L$(dirname $(port contents $PORT_PACKAGE | \
grep libgccjit.dylib))"
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"
fi
fi
@ -5395,29 +5412,21 @@ if test "${emacs_cv_links_glib}" = "yes"; then
fi
AC_SUBST([XGSELOBJ])
dnl Adapted from Haible's version.
AC_CACHE_CHECK([for nl_langinfo and CODESET], [emacs_cv_langinfo_codeset],
[AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <langinfo.h>]],
[[char *cs = nl_langinfo(CODESET);]])],
[emacs_cv_langinfo_codeset=yes],
[emacs_cv_langinfo_codeset=no])
])
if test "$emacs_cv_langinfo_codeset" = yes; then
AC_DEFINE([HAVE_LANGINFO_CODESET], [1],
[Define if you have <langinfo.h> and nl_langinfo (CODESET).])
AC_CACHE_CHECK([for nl_langinfo and _NL_PAPER_WIDTH],
[emacs_cv_langinfo__nl_paper_width],
[AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <langinfo.h>]],
[[char *cs = nl_langinfo (_NL_PAPER_WIDTH);]])],
[emacs_cv_langinfo__nl_paper_width=yes],
[emacs_cv_langinfo__nl_paper_width=no])
])
if test "$emacs_cv_langinfo__nl_paper_width" = yes; then
AC_DEFINE([HAVE_LANGINFO__NL_PAPER_WIDTH], [1],
[Define if you have <langinfo.h> and nl_langinfo (_NL_PAPER_WIDTH).])
fi
fi
AC_DEFUN([EMACS_PAPER_WIDTH],
[AC_REQUIRE([AM_LANGINFO_CODESET])
AS_IF([test "$am_cv_langinfo_codeset" = yes],
[AC_CACHE_CHECK([for nl_langinfo and _NL_PAPER_WIDTH],
[emacs_cv_langinfo__nl_paper_width],
[AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <langinfo.h>]],
[[char *cs = nl_langinfo (_NL_PAPER_WIDTH);]])],
[emacs_cv_langinfo__nl_paper_width=yes],
[emacs_cv_langinfo__nl_paper_width=no])
])
AS_IF([test "$emacs_cv_langinfo__nl_paper_width" = yes],
[AC_DEFINE([HAVE_LANGINFO__NL_PAPER_WIDTH], [1],
[Define if you have <langinfo.h>
and nl_langinfo (_NL_PAPER_WIDTH).])])])])
EMACS_PAPER_WIDTH
AC_TYPE_MBSTATE_T
@ -5602,7 +5611,7 @@ case $opsys in
esac
case $opsys in
gnu-* | solaris )
gnu-* | solaris | cygwin )
dnl FIXME Can't we test if this exists (eg /proc/$$)?
AC_DEFINE([HAVE_PROCFS], [1], [Define if you have the /proc filesystem.])
;;

20
doc/emacs/custom.texi
View file

@ -1245,6 +1245,7 @@ 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
@ -1327,6 +1328,15 @@ pairs in the file, by typing @kbd{i} at the confirmation prompt --
these pairs will thereafter be ignored in this file and in all other
files.
When Emacs asks for confirmation for setting directory-local
variables (@pxref{Directory Variables}), typing @kbd{+} at the
confirmation prompt will set all the variables, and also add the
directory to the list in @code{safe-local-variable-directories}
(described below), which will cause Emacs to consider this directory
as safe for loading any directory-local variables in the future. The
@kbd{+} response should only be used for directories whose contents
you trust.
@vindex safe-local-variable-values
@vindex ignored-local-variable-values
@cindex risky variable
@ -1343,6 +1353,16 @@ record safe values for risky variables, do it directly by customizing
Similarly, if you want to record values of risky variables that should
be permanently ignored, customize @code{ignored-local-variable-values}.
@vindex safe-local-variable-directories
Sometimes it is helpful to always trust directory-variables in
certain directories, and skip the confirmation prompt when local
variables are loaded from those directories, even if the variables are
risky. The variable @code{safe-local-variable-directories} holds the
list of such directories. The names of the directories in this list
must be full absolute file names. If the variable
@code{enable-remote-dir-locals} has a non-@code{nil} value, the list
can include remote directories as well (@pxref{Remote Files}).
@vindex enable-local-variables
The variable @code{enable-local-variables} allows you to change the
way Emacs processes local variables. Its default value is @code{t},

7
doc/emacs/display.texi
View file

@ -127,7 +127,10 @@ command leaves point in the window. This variable affects all the
scroll commands documented in this section, as well as scrolling with
the mouse wheel (@pxref{Mouse Commands}); in general, it affects any
command that has a non-@code{nil} @code{scroll-command} property.
@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}.
@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. The
same property also causes Emacs not to exit incremental search when
one of these commands is invoked and @code{isearch-allow-scroll} is
non-@code{nil} (@pxref{Not Exiting Isearch}).
@vindex fast-but-imprecise-scrolling
Sometimes, particularly when you hold down keys such as @kbd{C-v}
@ -154,7 +157,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 is there's input pending.
non-@code{nil}, skip some fontifications if 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.

93
doc/emacs/files.texi
View file

@ -2289,10 +2289,15 @@ 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
@ -2353,6 +2358,94 @@ 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

10
doc/emacs/help.texi
View file

@ -317,6 +317,16 @@ 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

7
doc/emacs/macos.texi
View file

@ -201,13 +201,6 @@ 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}.

38
doc/emacs/maintaining.texi
View file

@ -999,6 +999,10 @@ Display the change history for the current fileset
Display the change history for the current repository
(@code{vc-print-root-log}).
@item C-x v b l
Display the change history for another branch
(@code{vc-print-branch-log}).
@item C-x v I
Display the changes that a ``pull'' operation will retrieve
(@code{vc-log-incoming}).
@ -1063,6 +1067,14 @@ showing only the first line of each log entry. However, you can type
@file{*vc-change-log*} buffer to reveal the entire log entry for the
revision at point. A second @key{RET} hides it again.
@kindex C-x v b l
@findex vc-print-branch-log
@kbd{C-x v b l @var{branch-name} @key{RET}} (@code{vc-print-branch-log})
displays a @file{*vc-change-log*} buffer showing the history of the
version-controlled directory tree, like @code{vc-print-root-log} does,
but it shows the history of a branch other than the current one; it
prompts for the branch whose history to display.
@kindex C-x v I
@kindex C-x v O
@findex vc-log-incoming
@ -1523,6 +1535,8 @@ switch to another branch using the @kbd{svn switch} command. With
Mercurial, command @kbd{hg update} is used to switch to another
branch.
@kindex C-x v b s
@findex vc-switch-branch
The VC command to switch to another branch in the current directory
is @kbd{C-x v b s @var{branch-name} @key{RET}} (@code{vc-switch-branch}).
@ -1673,9 +1687,12 @@ branch ID for a branch starting at the current revision. For example,
if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
and so on, depending on the number of existing branches at that point.
@kindex C-x v b c
@findex vc-create-branch
This procedure will not work for distributed version control systems
like git or Mercurial. For those systems you should use the command
@code{vc-create-branch} (@kbd{C-x v b c}) instead.
@code{vc-create-branch} (@w{@kbd{C-x v b c @var{branch-name} @key{RET}}})
instead.
To create a new branch at an older revision (one that is no longer
the head of a branch), first select that revision (@pxref{Switching
@ -2283,16 +2300,25 @@ 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-,}.
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.
@kindex C-M-,
@findex xref-go-forward
If you previously went back too far with @kbd{M-,}, @kbd{C-M-,}
(@code{xref-go-forward}) can be used to go forward again.
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.
@findex xref-etags-mode
Some major modes install @code{xref} support facilities that might

18
doc/emacs/mini.texi
View file

@ -313,19 +313,27 @@ 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 @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 @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.
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 @key{TAB}, completion fills in the rest of the
If you now type @kbd{@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

4
doc/emacs/mule.texi
View file

@ -515,9 +515,9 @@ one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
do the highlighting in the buffer showing the possible characters,
rather than in the echo area.
To enter characters according to the @dfn{pīnyīn} transliteration
To enter characters according to the @dfn{p@=iny@=in} transliteration
method instead, use the @code{chinese-sisheng} input method. This is
a composition based method, where e.g. @kbd{pi1} results in @samp{pī}.
a composition based method, where e.g. @kbd{pi1} results in @samp{p@=i}.
In Japanese input methods, first you input a whole word using
phonetic spelling; then, after the word is in the buffer, Emacs

194
doc/emacs/package.texi
View file

@ -160,7 +160,13 @@ current line by an @kbd{i} or @kbd{d} command
Mark all package with a newer available version for upgrading
(@code{package-menu-mark-upgrades}). This places an installation mark
on the new available versions, and a deletion mark on the old
installed versions (marked with status @samp{obsolete}).
installed versions (marked with status @samp{obsolete}). By default,
this won't mark built-in packages for which a newer version is
available, but customizing @code{package-install-upgrade-built-in} can
change that. @xref{Package Installation}. If you customize
@code{package-install-upgrade-built-in} to a non-@code{nil} value, be
sure to review all the built-in packages the @kbd{U} command marks, to
avoid updating built-in packages you don't want to overwrite.
@item x
@kindex x @r{(Package Menu)}
@ -201,7 +207,8 @@ from lower-priority archives (@code{package-menu-toggle-hiding}).
@findex package-menu-filter-by-archive
Filter package list by archive (@code{package-menu-filter-by-archive}).
This prompts for a package archive (e.g., @samp{gnu}), then shows only
packages from that archive.
packages from that archive. You can specify several archives by
typing their names separated by commas.
@item / d
@kindex / d @r{(Package Menu)}
@ -216,7 +223,8 @@ matching that regexp.
@findex package-menu-filter-by-keyword
Filter package list by keyword (@code{package-menu-filter-by-keyword}).
This prompts for a keyword (e.g., @samp{games}), then shows only
packages with that keyword.
packages with that keyword. You can specify several keywords by
typing them separated by commas.
@item / N
@kindex / N @r{(Package Menu)}
@ -237,16 +245,19 @@ with names matching that regexp.
@kindex / s @r{(Package Menu)}
@findex package-menu-filter-by-status
Filter package list by status (@code{package-menu-filter-by-status}).
This prompts for one or more statuses (e.g., @samp{available}), then
shows only packages with matching status.
This prompts for one or more statuses (e.g., @samp{available},
@pxref{Package Statuses}), then shows only packages with matching
status. You can specify several status values by typing them
separated by commas.
@item / v
@kindex / v @r{(Package Menu)}
@findex package-menu-filter-by-version
Filter package list by version (@code{package-menu-filter-by-version}).
This prompts first for one of the qualifiers @samp{<}, @samp{>} or
@samp{=}, and then a package version, and shows packages that has a
lower, equal or higher version than the one specified.
This prompts first for one of the comparison symbols @samp{<},
@samp{>} or @samp{=} and for a version string, and then shows packages
whose versions are correspondingly lower, equal or higher than the
version you typed.
@item / m
@kindex / m @r{(Package Menu)}
@ -258,7 +269,11 @@ This shows only the packages that have been marked to be installed or deleted.
@kindex / u @r{(Package Menu)}
@findex package-menu-filter-upgradable
Filter package list to show only packages for which there are
available upgrades (@code{package-menu-filter-upgradable}).
available upgrades (@code{package-menu-filter-upgradable}). By
default, this filter excludes the built-in packages for which a newer
version is available, but customizing
@code{package-install-upgrade-built-in} can change that.
@xref{Package Installation}.
@item / /
@kindex / / @r{(Package Menu)}
@ -286,9 +301,12 @@ the package archive.
The package is available for installation, but a newer version is also
available. Packages with this status are hidden by default.
@cindex built-in package
@item built-in
The package is included in Emacs by default. It cannot be deleted
through the package menu, and is not considered for upgrading.
through the package menu, and by default is not considered for
upgrading (but you can change that by customizing
@code{package-install-upgrade-built-in}, @pxref{Package Installation}).
@item dependency
The package was installed automatically to satisfy a dependency of
@ -329,15 +347,46 @@ version of the package, a newer version is also installed.
@section Package Installation
@findex package-install
@findex package-update
@findex package-update-all
@findex package-upgrade
@findex package-upgrade-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 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.
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.
@vindex package-install-upgrade-built-in
By default, @code{package-install} doesn't consider built-in
packages for which new versions are available from the archives. (A
package is built-in if it is included in the Emacs distribution.) In
particular, it will not show built-in packages in the list of
completion candidates when you type at its prompt. But if you invoke
@code{package-install} with a prefix argument, it will also consider
built-in packages that can be upgraded. You can make this behavior
the default by customizing the variable
@code{package-install-upgrade-built-in}: if its value is
non-@code{nil}, @code{package-install} will consider built-in packages
even when invoked without a prefix argument. Note that the
package-menu commands (@pxref{Package Menu}) are also affected by
@code{package-install-upgrade-built-in}.
By contrast, @code{package-upgrade} and @code{package-upgrade-all}
never consider built-in packages. If you want to use these commands
for upgrading some built-in packages, you need to upgrade each of
those packages, once, either via @kbd{C-u M-x package-install
@key{RET}}, or by customizing @code{package-install-upgrade-built-in}
to a non-@code{nil} value, and then upgrading the package once via the
package menu or by @code{package-install}.
If you customize @code{package-install-upgrade-built-in} to a
non-@code{nil} value, be very careful when using commands that update
many packages at once, like @code{package-upgrade-all} and @kbd{U} in
the package menu: those might overwrite built-in packages that you
didn't intent to replace with newer versions from the archives. Don't
use these bulk commands if you want to update only a small number of
built-in packages.
@cindex package requirements
A package may @dfn{require} certain other packages to be installed,
@ -551,36 +600,13 @@ 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 update them using
@code{package-update} or @code{package-update-all} and delete them
just like any other package. You can upgrade them using
@code{package-upgrade} or @code{package-upgrade-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
@ -601,3 +627,91 @@ 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 :make
A string or list of strings providing the target or targets defined in
the repository Makefile which should run before building the Info
file. Only takes effect when @code{package-vc-allow-side-effects} is
non-nil.
@item :shell-command
A string providing the shell command to run before building the Info
file. Only takes effect when @code{package-vc-allow-side-effects} is
non-@code{nil}.
@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

41
doc/emacs/search.texi
View file

@ -587,26 +587,30 @@ i.e., they don't terminate the search, even if
@item Scrolling Commands
@cindex scrolling commands, during incremental search
@vindex isearch-allow-scroll
Normally, scrolling commands exit incremental search. If you change
the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
that enables the use of the scroll-bar, as well as keyboard scrolling
commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
This applies only to calling these commands via their bound key
sequences---typing @kbd{M-x} will still exit the search. You can give
prefix arguments to these commands in the usual way. This feature
normally won't let you scroll the current match out of visibility; but
if you customize @code{isearch-allow-scroll} to the special value
@code{unlimited}, that restriction is lifted.
@cindex @code{scroll-command} property, and incremental search
Normally, scrolling commands exit incremental search. But if you
change the variable @code{isearch-allow-scroll} to a non-@code{nil}
value, that enables the use of the scroll-bar, as well as keyboard
scrolling commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l}
(@pxref{Scrolling}), which have a non-@code{nil} @code{scroll-command}
property, without exiting the search. This applies only to calling
these commands via their bound key sequences---typing @kbd{M-x} will
still exit the search. You can give prefix arguments to these
commands in the usual way. This feature normally won't let you scroll
the current match out of visibility; but if you customize
@code{isearch-allow-scroll} to the special value @code{unlimited},
that restriction is lifted.
@cindex @code{isearch-scroll} property
@cindex prevent commands from exiting incremental search
The @code{isearch-allow-scroll} feature also affects some other
commands, such as @kbd{C-x 2} (@code{split-window-below}) and
@kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do
affect where the text appears on the screen. It applies to any
command whose name has a non-@code{nil} @code{isearch-scroll}
property. So you can control which commands are affected by changing
these properties.
affect where the text appears on the screen. In fact, it affects
any command that has a non-@code{nil} @code{isearch-scroll} property.
So you can control which commands are affected by changing these
properties.
@cindex prevent commands from exiting incremental search
For example, to make @kbd{C-h l} usable within an incremental search
in all future Emacs sessions, use @kbd{C-h c} to find what command it
runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can
@ -643,6 +647,7 @@ you can extend the search string by holding down the shift key while
typing cursor motion commands. It will yank text that ends at the new
position after moving point in the current buffer.
@cindex @code{isearch-move} property
When @code{isearch-yank-on-move} is @code{t}, you can extend the
search string without using the shift key for cursor motion commands,
but it applies only for certain motion command that have the
@ -1653,9 +1658,9 @@ command's first argument. If @code{case-fold-search} is set to
@code{nil}, case is always significant in all searches.
@vindex case-replace
In addition, when the @var{newstring} argument is all or partly lower
case, replacement commands try to preserve the case pattern of each
occurrence. Thus, the command
In addition, when the second argument of a replace command is all or
partly lower case, replacement commands try to preserve the case
pattern of each occurrence. Thus, the command
@example
M-x replace-string @key{RET} foo @key{RET} bar @key{RET}

694
doc/emacs/trouble.texi
View file

@ -313,14 +313,36 @@ sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary}
@end example
@noindent
On MS-Windows, the backtrace looks somewhat differently, for example:
@example
Backtrace:
00007ff61166a12e
00007ff611538be1
00007ff611559601
00007ff6116ce84a
00007ff9b7977ff0
@dots{}
@end example
@noindent
Therefore, the filtering via @command{sed} is not required, and the
command to show the source-code line number is
@example
addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary} < @var{backtrace}
@end example
@noindent
Here, @var{backtrace} is the name of a text file containing a copy of
the backtrace, @var{bindir} is the name of the directory that
contains the Emacs executable, and @var{emacs-binary} is the name of
the Emacs executable file, normally @file{emacs} on GNU and Unix
systems and @file{emacs.exe} on MS-Windows and MS-DOS@. Omit the
@option{-p} option if your version of @command{addr2line} is too old
to have it.
the backtrace (on MS-Windows, @file{emacs_backtrace.txt} in the
directory where Emacs was started), @var{bindir} is the name of the
directory that contains the Emacs executable, and @var{emacs-binary}
is the name of the Emacs executable file, normally @file{emacs} on GNU
and Unix systems and @file{emacs.exe} on MS-Windows and MS-DOS@. Omit
the @option{-p} option if your version of @command{addr2line} is too
old to have it.
@cindex core dump
Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
@ -496,8 +518,43 @@ 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. The following sections will help you to
construct an effective bug report.
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
@menu
* Known Problems:: How to read about known problems and bugs.
@ -509,9 +566,10 @@ construct an effective bug report.
@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 it
is already known about. Indeed, it may already have been fixed in a
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
later release of Emacs, or in the development version. Here is a list
of the main places you can read about known issues:
@ -519,20 +577,26 @@ 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. Often, there
are suggestions for workarounds and solutions.
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.
@cindex bug tracker
@cindex issue tracker
@cindex search known bugs
@item
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.
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}.
@cindex debbugs package
Instead of browsing the bug tracker as a webpage, you can browse it
Instead of browsing the bug tracker as a web page, 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
@ -558,14 +622,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,
it is an alias for @samp{bug-gnu-emacs}.
email messages sent to this list are redirected to
@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
@ -628,20 +692,21 @@ to begin by reporting them to the package developers.
@node Understanding Bug Reporting
@subsection Understanding Bug Reporting
@cindex bug reporting
@cindex bug reporting, principles
@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.
command to run Emacs, until the problem happens, and the effects
produced by typing those commands.
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 will be useless; meanwhile, lacking the
Emacs is implemented, they night not be useful; 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
@ -661,19 +726,23 @@ 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}.
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'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.
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. 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 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.
Some bugs are not reproducible from @command{emacs -Q}; some are not
easily reproducible at all. In that case, you should report what you
@ -687,6 +756,7 @@ 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}).
@ -706,7 +776,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
@ -721,24 +791,26 @@ 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.
address describing the problem, including the necessary information
mentioned below.
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. This is done with the @kbd{M-x
submit-emacs-patch} command, and works much the same as when reporting
bugs.
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}.
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 appears.
your report actually appears on the tracker.
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 online
documentation to see the various features you can use.
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.
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
@ -749,55 +821,43 @@ 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.
make it available online and say where. Large attachments are best
sent compressed.
The GNU Bug Tracker will assign a bug number to your report; please
use it in the following discussions.
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.
To enable maintainers to investigate a bug, your report
should include all these things:
@itemize @bullet
@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.
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.''
@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.
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?
@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.
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 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.
Usually, description of the behavior and of the way to reproduce the
problem needs to specify one or more of the following aspects:
@itemize @minus
@item
The complete text of any files needed to reproduce the bug.
@ -818,79 +878,12 @@ 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 @kbd{M-x open-dribble-file} command.
file. To start the file, use the command @w{@kbd{M-x open-dribble-file}}.
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
@ -906,33 +899,6 @@ 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
@ -960,65 +926,89 @@ code is in your version at a given line number, and we could not be
certain.
@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
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.
@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.
However, you need to think when you collect the additional information
if you want it to show what causes the bug.
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
@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).
@example
(open-termscript "~/termscript")
@end example
@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.
@noindent
into your Emacs initialization file so that the termscript file will
be open when Emacs displays the screen for the first time.
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).
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 make Lisp errors stop Emacs and return to GDB, put a breakpoint at
@code{Fsignal}.
@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.
For a short listing of Lisp functions running, type the GDB
command @code{xbacktrace}.
@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.
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 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.
@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
The command-line arguments given to the @code{configure} command when
Emacs was built (automatically included by @kbd{M-x
report-emacs-bug}).
To find the file @file{etc/DEBUG} in your Emacs installation, use the
directory name stored in the variable @code{data-directory}.
@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.
@end itemize
Here are some things that are not necessary in a bug report:
@ -1075,17 +1065,13 @@ 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.
@ifnottex
@xref{Sending Patches}, for guidelines on how to make it easy for us to
understand and install your patches.
@end ifnottex
install it. @xref{Sending Patches}, for guidelines on how to make it
easy for us to understand and install your patches.
@item
A guess about what the bug is or what it depends on.
@ -1094,6 +1080,108 @@ 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
@ -1108,26 +1196,29 @@ 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.
can properly evaluate it. They are described below.
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.
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.
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.
Here's what we ask you to provide as part of your patch submissions:
@itemize @bullet
@item
Include an explanation with your changes of what problem they fix or what
improvement they bring about.
An explanation of what problem you are fixing or what improvement will
the patches bring about:
@itemize
@itemize @minus
@item
For a fix for an existing bug, it is
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
@ -1140,26 +1231,28 @@ implementation.
@item
For a new bug, include a proper bug report for the problem you think
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.
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.
@end itemize
@item
Include all the comments that are appropriate to help people reading the
source in the future understand why this change was needed.
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.
@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. 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 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 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
@ -1176,52 +1269,46 @@ right away. That gives us the option of installing it immediately if it
is important.
@item
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.
The patch itself. This can be produced in one of the following ways:
@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}. Or you can leave your changes
uncommitted and use @code{git diff}.
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.
@item
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.
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
@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 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.
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.
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},
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},
@ifset WWW_GNU_ORG
see
@url{https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
@ -1232,7 +1319,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 on another type of system.
will have if compiled and/or used 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
@ -1240,9 +1327,10 @@ 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 configuration files for a
particular machine. These are safe because they can't create new bugs
on other machines.
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.
Please help us keep up with the workload by designing the patch in a
form that is clearly safe to install.
@ -1259,7 +1347,7 @@ There are many ways to contribute to Emacs:
@itemize
@item
find and report bugs; @xref{Bugs}.
find and report bugs; @pxref{Bugs}.
@item
answer questions on the Emacs user mailing list
@ -1326,15 +1414,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;
@xref{Coding Standards}. In addition, non-trivial contributions
require a copyright assignment to the FSF; @xref{Copyright Assignment}.
@pxref{Coding Standards}. In addition, substantial contributions
require a copyright assignment to the FSF; @pxref{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 patch based on the current working
It is important to write your patches 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
@ -1397,7 +1485,7 @@ the Emacs Lisp Reference Manual
@node Coding Standards
@subsection Coding Standards
@cindex coding standards
@cindex coding standards for Emacs submissions
Contributed code should follow the GNU Coding Standards
@url{https://www.gnu.org/prep/standards/}. This may also be available
@ -1432,10 +1520,6 @@ 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.
@ -1455,7 +1539,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 some countries
Copyright assignment is a simple process. Residents of many 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),

9
doc/lispintro/emacs-lisp-intro.texi
View file

@ -6604,10 +6604,11 @@ 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, 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}.)
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}.)
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

24
doc/lispref/buffers.texi
View file

@ -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 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:
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:
@itemize @bullet{}
@item
A string, interpreted as a regular expression. The buffer
@ -990,21 +990,23 @@ 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), @code{(and)} (empty conjunction) or @code{always}.
string) or @code{(and)} (empty conjunction).
@end itemize
@end defun
@defun match-buffers condition &optional buffer-list arg
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.
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.
@end defun
@node Creating Buffers

42
doc/lispref/commands.texi
View file

@ -1960,8 +1960,8 @@ end-position of a drag event, this position list may represent a
location outside the boundaries of the initially selected frame, in
which case the list contains that frame in place of a window.
The special form @code{track-mouse} enables generation of motion
events within its body. Outside of @code{track-mouse} forms, Emacs
The @code{track-mouse} macro enables generation of motion
events within its body. Outside of @code{track-mouse} body, Emacs
does not generate events for mere motion of the mouse, and these
events do not appear. @xref{Mouse Tracking}.
@ -2395,6 +2395,17 @@ 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
@ -2443,7 +2454,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} special form, that produces an event like this:
the @code{track-mouse} macro, that produces an event like this:
@smallexample
(mouse-movement (#<frame *ielm* 0x102849a30> nil (563 . 205) 532301936))
@ -3215,15 +3226,24 @@ 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-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.
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.
@end defun
@defun read-multiple-choice prompt choices &optional help-string show-help long-form

3
doc/lispref/control.texi
View file

@ -1809,6 +1809,9 @@ 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}.

16
doc/lispref/customize.texi
View file

@ -264,11 +264,12 @@ have any number of prefixes.
@end table
@cindex @code{custom-group} property
The variables and subgroups of a group are stored in the
The variables, faces, 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 variable or subgroup symbol and the @code{cdr} is
either @code{custom-variable} or @code{custom-group}.
@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}.
@end defmac
@defopt custom-unlispify-remove-prefixes
@ -378,8 +379,15 @@ 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.
should describe how to do the same job in hand-written Lisp code,
either by invoking @var{setfunction} directly or by using
@code{setopt}.
@item :get @var{getfunction}
@kindex get@r{, @code{defcustom} keyword}

325
doc/lispref/display.texi
View file

@ -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. This
argument, the text of a message to display in the echo area. That
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 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.
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.
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.
The default value calls @code{set-minibuffer-message}, described
below.
@end defvar
@defvar clear-message-function
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.
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.
Usually this function is called when the next input event arrives
after displaying an echo-area message. The function is expected to
@ -358,11 +358,51 @@ 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 use the Echo Area to display messages.
will not display any messages in the Echo Area. Echo-area messages
are still logged in the @file{*Messages*} buffer, though.
@end defvar
@defmac with-temp-message message &rest body
@ -712,7 +752,8 @@ 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.
possible problem, but continue running (as opposed to signaling an
error, @pxref{Errors}).
@menu
* Warning Basics:: Warnings concepts and functions to report them.
@ -725,69 +766,74 @@ possible problem, but continue running.
@subsection Warning Basics
@cindex severity level
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:
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:
@table @code
@item :emergency
A problem that will seriously impair Emacs operation soon
if you do not attend to it promptly.
if the user does not attend to it promptly.
@item :error
A report of data or circumstances that are inherently wrong.
A report about data or circumstances that are inherently wrong.
@item :warning
A report of data or circumstances that are not inherently wrong, but
raise suspicion of a possible problem.
A report about 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 you are debugging.
A report of information that may be useful if the user is currently
debugging the Lisp program which issues the warning.
@end table
When your program encounters invalid input data, it can either
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.)
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.)
@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
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.
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.
@defun display-warning type message &optional level buffer-name
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.
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}.
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
for logging the warning. By default, it is @file{*Warnings*}.
for logging the warning message. By default, it is @file{*Warnings*}.
@end defun
@defun lwarn type level message &rest args
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}.
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}.
@end defun
@defun warn message &rest args
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.
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.
@end defun
@node Warning Variables
@ -802,15 +848,16 @@ 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 @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 @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.
The optional @var{function}, if non-@code{nil}, is a function to call
with no arguments, to get the user's attention.
with no arguments, to get the user's attention. A notable example is
@code{ding} (@pxref{Beeping}).
Normally you should not change the value of this variable.
@end defvar
@ -819,18 +866,19 @@ 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
current, and the function can insert text in it. That text becomes
the beginning of the warning message.
the current buffer, and the function can insert text into 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 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.
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.
If the variable's value is @code{nil} then there is no function
to call.
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.
@end defvar
@defvar warning-series
@ -838,17 +886,18 @@ 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 is unbound and
The series ends when the local binding of this variable 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 current. The
function can insert text which will serve as a header for the series
of warnings.
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.
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.
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.
The variable's normal value is @code{nil}, which means to handle
each warning separately.
@ -856,7 +905,7 @@ each warning separately.
@defvar warning-fill-prefix
When this variable is non-@code{nil}, it specifies a fill prefix to
use for filling each warning's text.
use for filling the text of each warning.
@end defvar
@defvar warning-fill-column
@ -865,11 +914,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 message. The result of formatting the type this way
in the warning text. 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 @code{""} then the warning type won't appear at
all.
If you bind it to the empty string @code{""} then the warning type
won't appear at all.
@end defvar
@node Warning Options
@ -881,38 +930,71 @@ 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. The default is @code{:warning}, which
means to immediately display all warnings except @code{:debug}
warnings.
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.
@end defopt
@defopt warning-minimum-log-level
This user option specifies the minimum severity level that should be
logged in the warnings buffer. The default is @code{:warning}, which
means to log all warnings except @code{:debug} warnings.
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}.
@end defopt
@defopt warning-suppress-types
This list specifies which warning types should not be displayed
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.
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.
@end defopt
@defopt warning-suppress-log-types
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.
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.
@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.
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.
@defun delay-warning type message &optional level buffer-name
This function is the delayed counterpart to @code{display-warning}
@ -933,7 +1015,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 it to @code{nil}.
then resets the variable to @code{nil}.
@end defvar
Programs which need to further customize the delayed warnings
@ -942,7 +1024,9 @@ 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.
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.
Its default value is a list of two functions:
@ -2345,10 +2429,11 @@ 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,
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 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.
@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
@ -2409,7 +2494,9 @@ 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.
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).
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
@ -6833,7 +6920,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.
as an alternative to the default @samp{x}.
The argument @var{image} must be an image descriptor, perhaps returned
by @code{create-image} or stored by @code{defimage}.
@ -6846,7 +6933,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!)
property whose value is the image. (Whew! that was a mouthful@dots{})
@end defun
@defun remove-images start end &optional buffer
@ -6893,41 +6980,47 @@ 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}). A prefix value
of @samp{4} means to increase the size by 40%. The default is 20%.
Increase the image size (@code{image-increase-size})
@findex image-decrease-size
@item i -
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%.
Decrease the image size (@code{image-decrease-size}).
@findex image-rotate
@item i r
Rotate the image by 90 degrees clockwise (@code{image-rotate}).
A prefix means to rotate by 90 degrees counter-clockwise instead.
Rotate the image (@code{image-rotate}).
@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
Crop the image interactively (@code{image-crop}).
Interactively crop the image (@code{image-crop}).
@findex image-cut
@item i x
Cut a rectangle from the image interactively (@code{image-cut}).
Interactively cut a rectangle from the image (@code{image-cut}).
@end table
The size and rotation commands are ``repeating'', which means that you
can continue adjusting the image without using the @kbd{i} prefix.
@xref{Image Mode,,, emacs, The GNU Emacs Manual}, for more details
about these image-specific key bindings.
@node Multi-Frame Images
@subsection Multi-Frame Images

4
doc/lispref/files.texi
View file

@ -3390,7 +3390,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-in-directory-p},
@code{file-group-gid}, @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 +3452,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-in-directory-p},
@code{file-group-gid}, @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},

90
doc/lispref/frames.texi
View file

@ -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} form causes Emacs to generate mouse motion
The @code{track-mouse} macro 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,29 +4141,71 @@ 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
@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.)
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
@cindex initiating drag-and-drop
On capable window systems, Emacs also supports dragging contents

34
doc/lispref/functions.texi
View file

@ -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} special
form, described in the next section.
Cells}). However, it is more common to use the @code{defun} macro,
described in the next section.
@ifnottex
@xref{Defining Functions}.
@end ifnottex
@ -1484,7 +1484,7 @@ the symbol as a function, Emacs signals a @code{void-function} error.
Note that void is not the same as @code{nil} or the symbol
@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
and can be stored into a function cell just as any other object can be
(and they can be valid functions if you define them in turn with
(and @code{void} can be a valid function if you define it with
@code{defun}). A void function cell contains no object whatsoever.
You can test the voidness of a symbol's function definition with
@ -2365,6 +2365,11 @@ this:
(set-advertised-calling-convention
'sit-for '(seconds &optional nodisp) "22.1")
@end example
@noindent
The alternative to using this function is the
@code{advertised-calling-convention} @code{declare} spec, see
@ref{Declare Form}.
@end defun
@node Inline Functions
@ -2541,6 +2546,7 @@ Each element in @var{specs} should have the form @code{(@var{property}
following effects:
@table @code
@cindex @code{advertised-calling-convention} (@code{declare} spec)
@item (advertised-calling-convention @var{signature} @var{when})
This acts like a call to @code{set-advertised-calling-convention}
(@pxref{Obsolete Functions}); @var{signature} specifies the correct
@ -2566,6 +2572,7 @@ This is typically used for macros, though it works for functions too.
Set the function's @code{interactive-only} property to @var{value}.
@xref{The interactive-only property}.
@cindex @code{obsolete} (@code{declare} spec)
@item (obsolete @var{current-name} @var{when})
Mark the function or macro as obsolete, similar to a call to
@code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name}
@ -2631,6 +2638,12 @@ 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}).
@ -2693,13 +2706,14 @@ 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}. 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} (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}.
@end defmac
@findex check-declare-file

26
doc/lispref/help.texi
View file

@ -989,3 +989,29 @@ 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

9
doc/lispref/internals.texi
View file

@ -558,12 +558,15 @@ 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, but increases total memory use. You may want to do this
when running a program that creates lots of Lisp data. However, we
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
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 system-wide memory pressure, and
necessary could potentially cause higher system-wide memory pressure,
and also make each garbage-collection cycle take much more time, and
should therefore be avoided.
You can make collections more frequent by specifying a smaller value, down

98
doc/lispref/keymaps.texi
View file

@ -451,9 +451,70 @@ 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
@ -707,8 +768,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}. The key sequence @kbd{C-p 6} is not found in any
active keymap.
like @kbd{C-x C-f}. By contrast, the key sequence @kbd{C-p 9} is not
found in any active keymap.
@example
@group
@ -717,15 +778,14 @@ active keymap.
@end group
@group
(keymap-local-set "C-p" ctl-x-map)
@result{} nil
@result{} (keymap #^[nil nil keymap @dots{}
@end group
@group
(keymap-binding "C-p C-f")
(keymap-lookup nil "C-p C-f")
@result{} find-file
@end group
@group
(keymap-binding "C-p 6")
(keymap-lookup nil "C-p 9")
@result{} nil
@end group
@end example
@ -822,7 +882,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-binding}.
@code{keymap-lookup} (@pxref{Functions for Key Lookup, keymap-lookup}).
@end defun
@node Searching Keymaps
@ -1247,7 +1307,11 @@ the second example.
@end group
@end example
The @var{keymap} argument can also be a list of keymaps.
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.
Unlike @code{read-key-sequence}, this function does not modify the
specified events in ways that discard information (@pxref{Key Sequence
@ -1440,6 +1504,24 @@ 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:

32
doc/lispref/lists.texi
View file

@ -696,29 +696,17 @@ not a list, the sequence's elements do not become elements of the
resulting list. Instead, the sequence becomes the final @sc{cdr}, like
any other non-list final argument.
@defun copy-tree tree &optional vecp
@defun copy-tree tree &optional vectors-and-records
This function returns a copy of the tree @var{tree}. If @var{tree} is a
cons cell, this makes a new cons cell with the same @sc{car} and
@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
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.
@end defun
@defun safe-copy-tree tree &optional vecp
This function returns a copy of the tree @var{tree}. If @var{tree} is
a cons cell, this make a new cons cell with the same @sc{car} and
@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
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 and records too (and operates
recursively on their elements). This function handles circular lists
and vectors, and is thus slower than @code{copy-tree} for typical cases.
@code{copy-tree} simply returns @var{tree}. However, if
@var{vectors-and-records} is non-@code{nil}, it copies vectors and records
too (and operates recursively on their elements). The @var{tree}
argument must not contain cycles.
@end defun
@defun flatten-tree tree
@ -1237,7 +1225,15 @@ x
@end example
However, the other arguments (all but the last) should be mutable
lists.
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
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

2
doc/lispref/loading.texi
View file

@ -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 use typed @kbd{C-g}
function returns an error indication, or if the user 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

38
doc/lispref/minibuf.texi
View file

@ -2174,13 +2174,14 @@ will not have serious consequences. @code{yes-or-no-p} is suitable for
more momentous questions, since it requires three or four characters to
answer.
If either of these functions is called in a command that was invoked
using the mouse---more precisely, if @code{last-nonmenu-event}
(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
uses a dialog box or pop-up menu to ask the question. Otherwise, it
uses keyboard input. You can force use either of the mouse or of keyboard
input by binding @code{last-nonmenu-event} to a suitable value around
the call.
If either of these functions is called in a command that was
invoked using the mouse or some other window-system gesture, or in a
command invoked via a menu, then they use a dialog box or pop-up menu
to ask the question if dialog boxes are supported. Otherwise, they
use keyboard input. You can force use either of the mouse or of
keyboard input by binding @code{last-nonmenu-event} to a suitable
value around the call---bind it to @code{t} to force keyboard
interaction, and to a list to force dialog boxes.
Both @code{yes-or-no-p} and @code{y-or-n-p} use the minibuffer.
@ -2200,6 +2201,9 @@ the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
@kbd{@key{DEL}}, or something that quits), the function responds
@samp{Please answer y or n.}, and repeats the request.
If @var{prompt} is a non-empty string, and it ends with a non-space
character, a @samp{SPC} character will be appended to it.
This function actually uses the minibuffer, but does not allow editing
of the answer. The cursor moves to the minibuffer while the question
is being asked.
@ -2240,6 +2244,9 @@ minibuffer, followed by the value of @code{yes-or-no-prompt} @w{(default
responses; otherwise, the function responds @w{@samp{Please answer yes or
no.}}, waits about two seconds and repeats the request.
If @var{prompt} is a non-empty string, and it ends with a non-space
character, a @samp{SPC} character will be appended to it.
@code{yes-or-no-p} requires more work from the user than
@code{y-or-n-p} and is appropriate for more crucial decisions.
@ -2247,7 +2254,7 @@ Here is an example:
@smallexample
@group
(yes-or-no-p "Do you really want to remove everything?")
(yes-or-no-p "Do you really want to remove everything? ")
;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
@ -2380,13 +2387,14 @@ Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
does not do that.
If @code{map-y-or-n-p} is called in a command that was invoked using the
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a list---then it uses a dialog box
or pop-up menu to ask the question. In this case, it does not use
keyboard input or the echo area. You can force use either of the mouse or
of keyboard input by binding @code{last-nonmenu-event} to a suitable
value around the call.
If @code{map-y-or-n-p} is called in a command that was invoked using
the mouse or some other window-system gesture, or a command invoked
via a menu, then it uses a dialog box or pop-up menu to ask the
question if dialog boxes are supported. In this case, it does not use
keyboard input or the echo area. You can force use either of the
mouse or of keyboard input by binding @code{last-nonmenu-event} to a
suitable value around the call---bind it to @code{t} to force keyboard
interaction, and to a list to force dialog boxes.
The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun

91
doc/lispref/modes.texi
View file

@ -1775,6 +1775,8 @@ 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}
@ -1860,9 +1862,10 @@ 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 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
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
@code{define-globalized-minor-mode} form is evaluated each time Emacs
starts, for example by providing a @code{:require} keyword.
@ -1875,24 +1878,27 @@ 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 can use (or
disable) it in individual buffers. This also allows them to disable a
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
globally enabled minor mode in a specific major mode, by using that
mode's hook.
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}).
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.
@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
@ -1902,13 +1908,15 @@ modes''.
((not c-mode) t)
@end example
This means ``don't use modes derived from @code{c-mode}, but use
@noindent
This means ``don't use in modes derived from @code{c-mode}, but do 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
@ -2349,18 +2357,19 @@ enabled separately in each buffer.
@defvar global-mode-string
This variable holds a mode line construct that, by default, appears in
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 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 @samp{%M} construct substitutes the value of
@code{global-mode-string}, but that is obsolete, since the variable is
included in the mode line from @code{mode-line-format}.
@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}.
@end defvar
Here is a simplified version of the default value of
@ -2389,6 +2398,7 @@ 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
@ -2440,6 +2450,10 @@ 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}).
@ -2475,6 +2489,9 @@ 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}); @*
@ -2486,9 +2503,6 @@ 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.
@ -2510,13 +2524,16 @@ The character @samp{%}---this is how to include a literal @samp{%} in a
string in which @code{%}-constructs are allowed.
@end table
The following @code{%}-construct is still supported, but it is
obsolete, since you can get the same result using the variable
@code{mode-name}.
@subsubheading Obsolete @code{%}-Constructs
The following constructs should no longer be used.
@table @code
@item %m
The value of @code{mode-name}.
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).
@end table
@node Properties in Mode
@ -4057,8 +4074,8 @@ replacing syntactic font lock, then the regexp-based font lock.
Although parser-based font lock doesn'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} is
@var{treesit-font-lock-settings}.
schemes. The tree-sitter counterpart of @code{font-lock-keywords} is
@code{treesit-font-lock-settings}.
@cindex tree-sitter fontifications, overview
@cindex fontifications with tree-sitter, overview
@ -4092,9 +4109,9 @@ To setup tree-sitter fontification, a major mode should first set
@code{treesit-major-mode-setup}.
@defun treesit-font-lock-rules &rest query-specs
This function is used to set @var{treesit-font-lock-settings}. It
This function is used to set @code{treesit-font-lock-settings}. It
takes care of compiling queries and other post-processing, and outputs
a value that @var{treesit-font-lock-settings} accepts. Here's an
a value that @code{treesit-font-lock-settings} accepts. Here's an
example:
@example
@ -4138,7 +4155,7 @@ Other keywords are optional:
@end multitable
Lisp programs mark patterns in @var{query} with capture names (names
that starts with @code{@@}), and tree-sitter will return matched nodes
that start 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
@ -4965,7 +4982,7 @@ below: then the major mode needs only to write some indentation rules
and the engine takes care of the rest.
To enable the parser-based indentation engine, either set
@var{treesit-simple-indent-rules} and call
@code{treesit-simple-indent-rules} and call
@code{treesit-major-mode-setup}, or equivalently, set the value of
@code{indent-line-function} to @code{treesit-indent}.

39
doc/lispref/numbers.texi
View file

@ -219,17 +219,25 @@ 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 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 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
``@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 obsolescent platforms, notably 32-bit x86.
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.
The read syntax for floating-point numbers requires either a decimal
point, an exponent, or both. Optional signs (@samp{+} or @samp{-})
@ -262,6 +270,10 @@ 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
@ -742,9 +754,10 @@ 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}). Floating-point division of
a nonzero number by zero yields either positive or negative infinity
(@pxref{Float Basics}).
@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.
@end defun
@defun % dividend divisor

22
doc/lispref/objects.texi
View file

@ -466,19 +466,20 @@ 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{?à}
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{?@`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.
@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{à} (@kbd{a} with grave accent).
You can use any number of hex digits, so you can represent any
character code in this way.
@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.
@item
@cindex octal character code
@ -1007,13 +1008,6 @@ 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

18
doc/lispref/os.texi
View file

@ -182,7 +182,9 @@ is over, and, together with @code{before-init-time}, provides the
measurement of how long it took.
@item
It runs the normal hook @code{after-init-hook}.
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.
@item
If the buffer @file{*scratch*} exists and is still in Fundamental mode
@ -1288,12 +1290,22 @@ 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 group-real-gid
This function returns the real @acronym{GID} of the Emacs process.
@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.
@end defun
@defun system-users

78
doc/lispref/parsing.texi
View file

@ -849,6 +849,53 @@ 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}.
@ -859,18 +906,24 @@ return non-@code{nil} to indicate that the node should be kept. If
nodes.
@end defun
@defun treesit-parent-until node predicate
@defun treesit-parent-until node predicate &optional include-node
This function repeatedly finds the parents of @var{node}, and returns
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}.
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}.
@end defun
@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
@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
takes a node as the argument. That is, this function returns the
farthest parent that still satisfies @var{predicate}.
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.
@end defun
@defun treesit-node-top-level node &optional type
@ -1305,7 +1358,8 @@ 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.
node in @var{nodes} as arguments. The function runs with the current
buffer set to the buffer of node being queried.
@end deffn
Note that a predicate can only refer to capture names that appear in
@ -1638,9 +1692,9 @@ directly translate into operations shown above.
@end example
@defun treesit-range-rules &rest query-specs
This function is used to set @var{treesit-range-settings}. It
takes care of compiling queries and other post-processing, and outputs
a value that @var{treesit-range-settings} can have.
This function is used to set @code{treesit-range-settings}. It takes
care of compiling queries and other post-processing, and outputs a
value that @code{treesit-range-settings} can have.
It takes a series of @var{query-spec}s, where each @var{query-spec} is
a @var{query} preceded by zero or more @var{keyword}/@var{value}

1
doc/lispref/positions.texi
View file

@ -1188,6 +1188,7 @@ saved bounds. In that case it is equivalent to
@end example
@cindex labeled narrowing
@cindex labeled restriction
When the optional argument @var{label}, a symbol, is present, the
narrowing is @dfn{labeled}. A labeled narrowing differs from a
non-labeled one in several ways:

8
doc/lispref/processes.texi
View file

@ -1755,7 +1755,9 @@ 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}.
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}
Many filter functions sometimes (or always) insert the output in the
process's buffer, mimicking the actions of the default filter.
@ -2159,7 +2161,9 @@ 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}.
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}
While a sentinel is running, the process sentinel is temporarily
set to @code{nil} so that the sentinel won't run recursively.

4
doc/lispref/records.texi
View file

@ -81,6 +81,10 @@ This function returns a new record with type @var{type} and
@end example
@end defun
To copy trees consisting of records, vectors and conses (lists), use
@code{copy-tree} with its optional second argument non-@code{nil}.
@xref{Building Lists, copy-tree}.
@node Backward Compatibility
@section Backward Compatibility

52
doc/lispref/sequences.texi
View file

@ -376,45 +376,43 @@ 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 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:
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:
@example
@group
(setq nums (list 1 3 2 6 5 4 0))
@result{} (1 3 2 6 5 4 0)
@end group
@group
(setq nums (list 2 1 4 3 0))
(sort nums #'<)
@result{} (0 1 2 3 4 5 6)
@end group
@group
nums
@result{} (1 2 3 4 5 6)
@result{} (0 1 2 3 4)
; nums is unpredictable at this point
@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:
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)
@end group
@group
nums
@result{} (2 1 4 3 0)
@end group
@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.

11
doc/lispref/symbols.texi
View file

@ -276,9 +276,8 @@ This function returns the string that is @var{symbol}'s name. For example:
@end group
@end example
@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!
@strong{Warning:} Never alter the string returned by that function.
Doing that might make Emacs dysfunctional, and might even crash Emacs.
@end defun
@cindex uninterned symbol, and generating Lisp code
@ -644,6 +643,12 @@ 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

33
doc/lispref/text.texi
View file

@ -3765,18 +3765,19 @@ 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 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}
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}
(@pxref{Managing Overlays}), or the position where the @code{display}
text property begins in the buffer.
@ -5509,7 +5510,7 @@ contents of an SQLite database.
@section Parsing HTML and XML
@cindex parsing html
Emacs can be compiled with built-in libxml2 support.
Emacs can be compiled with built-in @file{libxml2} support.
@defun libxml-available-p
This function returns non-@code{nil} if built-in libxml2 support is
@ -5528,8 +5529,10 @@ 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 a
string specifying the base URL for relative URLs occurring in links.
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.
If the optional argument @var{discard-comments} is non-@code{nil},
any top-level comment is discarded. (This argument is obsolete and

33
doc/lispref/variables.texi
View file

@ -1183,13 +1183,16 @@ 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 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.)
(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.)
@cindex closures, example of using
Lexical bindings have indefinite extent. Even after a binding
@ -1974,6 +1977,16 @@ this can be controlled by using this variable, which is a list of
symbols.
@end defvar
@defvar safe-local-variable-directories
This is a list of directories where local variables are always
enabled. Directory-local variables loaded from these directories,
such as the variables in @file{.dir-locals.el}, will be enabled even
if they are risky. The directories in this list must be
fully-expanded absolute file names. They may also be remote
directories if the variable @code{enable-remote-dir-locals} is set
non-@code{nil}.
@end defvar
@defun hack-local-variables &optional handle-mode
This function parses, and binds or evaluates as appropriate, any local
variables specified by the contents of the current buffer. The variable
@ -2558,6 +2571,9 @@ 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
@ -2606,9 +2622,6 @@ 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

2
doc/lispref/windows.texi
View file

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

4
doc/misc/calc.texi
View file

@ -5394,7 +5394,7 @@ a variable containing a vector of rules.
1: [merge, secsqr] 1: [a/x + b/x := (a + b)/x, ... ]
. .
' [merge,sinsqr] @key{RET} =
' [merge,secsqr] @key{RET} =
@end group
@end smallexample
@ -6217,7 +6217,7 @@ method when it is able. @xref{Programming Answer 8, 8}. (@bullet{})
@cindex Gamma constant, Euler's
@cindex Euler's gamma constant
(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function
@texline @math{\psi(z) (``psi'')}
@texline @math{\psi(z)} (``psi'')
@infoline @expr{psi(z)}
is defined as the derivative of
@texline @math{\ln \Gamma(z)}.

38
doc/misc/cc-mode.texi
View file

@ -330,6 +330,7 @@ Syntactic Symbols
* Multiline Macro Symbols::
* Objective-C Method Symbols::
* Java Symbols::
* Constraint Symbols::
* Statement Block Symbols::
* K&R Symbols::
@ -4234,6 +4235,9 @@ 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}.
@ -4397,6 +4401,7 @@ Java. @ref{Java Symbols}.
* Multiline Macro Symbols::
* Objective-C Method Symbols::
* Java Symbols::
* Constraint Symbols::
* Statement Block Symbols::
* K&R Symbols::
@end menu
@ -5070,6 +5075,39 @@ 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

20
doc/misc/efaq.texi
View file

@ -3133,13 +3133,23 @@ 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, 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 you use in the Registry settings, 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

621
doc/misc/eglot.texi
View file

@ -98,6 +98,7 @@ This manual documents how to configure, use, and customize Eglot.
* Eglot and LSP Servers:: How to work with language servers.
* Using Eglot:: Important Eglot commands and variables.
* Customizing Eglot:: Eglot customization and advanced features.
* Advanced server configuration:: Fine-tune a specific language server
* Troubleshooting Eglot:: Troubleshooting and reporting bugs.
* GNU Free Documentation License:: The license for this manual.
* Index::
@ -153,11 +154,11 @@ Use Eglot.
Most Eglot facilities are integrated into Emacs features, such as
ElDoc, Flymake, Xref, and Imenu. However, Eglot also provides
commands of its own, mainly to perform tasks by the 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.
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.
@item
That's it!
@ -226,11 +227,10 @@ 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{})
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.
@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}).
@item (@var{host} @var{port} @var{args}@dots{})
Here @var{host} is a string and @var{port} is a positive integer
@ -465,52 +465,10 @@ ElDoc look nicer on display.
@item
In addition to enabling and enhancing other features and packages,
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.
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}.
@end itemize
Not all servers support the full set of LSP capabilities, but most of
@ -713,20 +671,44 @@ 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 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-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 invoke specific code actions supported by the language
server.
@c FIXME: Need more detailed description of each action.
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.
@end ftable
The following Eglot commands are used less commonly, mostly for
@ -968,85 +950,132 @@ mechanism.
@cindex progress
@item eglot-report-progress
Set this variable to true if you'd like progress notifications coming
from the LSP server to be handled as Emacs's progress reporting
from the language 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
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.
@node Advanced server configuration
@chapter Advanced server configuration
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.
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.
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:
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:
@lisp
(:@var{server} @var{plist}@dots{})
(@var{:server1} @var{plist1} @var{:server2} @var{plist2} @dots{})
@end lisp
@noindent
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.
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.
@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
JSON value to be sent to the server. This helper command works even
before actually connecting to the server.
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.
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:
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.
@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
@subsection Examples
@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.
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.
Alternatively, the same configuration could be defined as follows:
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:
@lisp
((nil
@ -1054,61 +1083,189 @@ Alternatively, the same configuration could be defined as follows:
. (:pylsp (:plugins (:jedi_completion (:include_params t
:fuzzy t)
:pylint (:enabled :json-false)))
:gopls (:usePlaceholders t))))))
:gopls (:usePlaceholders t)))))
(python-mode . ((indent-tabs-mode . nil)))
(go-mode . ((indent-tabs-mode . t))))
@end lisp
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.
@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}.
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}.
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
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 value of the form described above.
function should return a plist suitable for use as the variable's
value.
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}).
@node User-specific configuration
@section User-specific configuration
@cindex initializationOptions
@cindex command-line arguments
Here's an example:
This kind of configuration applies to all projects the server is used
for. Here, there are a number of ways to do this inside Eglot.
A common way is to pass command-line options to the server invocation
via @code{eglot-server-programs}. Let's say we want to configure
where the @command{clangd} server reads its
@code{compile_commands.json} from. This can be done like so:
@lisp
(require 'eglot)
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs
`(c++-mode . ("clangd" "--compile-commands-dir=/tmp"))))
(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
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.
Another way is to have Eglot pass a JSON object to the server during
the LSP handshake. This is done using the
@code{:initializationOptions} syntax of @code{eglot-server-programs}:
@lisp
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs
`(c++-mode . ("clangd" :initializationOptions
(:compilationDatabasePath "/tmp")))))
@end lisp
@noindent
The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
representation in plist format of a simple JSON object
@code{@{"compilationDatabasePath": "/tmp"@}}. To learn how to
represent more deeply nested options in this format, @pxref{JSONRPC
objects in Elisp}.
In this case, the two examples achieve exactly the same, but notice
how the option's name has changed between them.
@vindex eglot-workspace-configuration
Finally there is another way to do user-specific configuration of
language servers, which may be used if the methods above are not
supported. It consists of @emph{globally} setting
@code{eglot-workspace-configuration}, a variable originally intended
for project-specific configuration. This has the same effect as
giving all your projects a certain default configuration, as described
in @ref{Project-specific configuration}. Here is an example:
@lisp
(setq-default eglot-workspace-configuration
'(:pylsp (:plugins (:jedi_completion (:include_params t
:fuzzy t)
:pylint (:enabled :json-false)))
:gopls (:usePlaceholders t)))
@end lisp
Note that the global value of @code{eglot-workspace-configuration} is
always overriden if a directory-local value is detected.
@node JSONRPC objects in Elisp
@section JSONRPC objects in Elisp
Emacs's preferred way of representing JSON is via Lisp lists. In
Eglot, the syntax of this list is the simplest possible (the one with
fewer parenthesis), a plist (@pxref{Property Lists,,, elisp, GNU Emacs
Lisp Reference Manual}).
The plist may be arbitrarily complex, and generally containing other
keyword-value property sub-plists corresponding to JSON sub-objects.
For representing the JSON leaf values @code{true}, @code{false},
@code{null} and @code{@{@}}, you can use the Lisp values @code{t},
@code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
JSON arrays are represented as Elisp vectors surrounded by square brackets
(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
For example, the plist
@lisp
(:pylsp (:plugins (:jedi_completion (:include_params t
:fuzzy t
:cache_for ["pandas" "numpy"]
:pylint (:enabled :json-false))))
:gopls (:usePlaceholders t))
@end lisp
@noindent
is serialized by Eglot to the following JSON text:
@example
@{
"pylsp": @{
"plugins": @{
"jedi_completion": @{
"include_params": true,
"fuzzy": true,
"cache_for": [ "pandas", "numpy" ],
@},
"pylint": @{
"enabled": false
@}
@}
@},
"gopls": @{
"usePlaceholders":true
@},
@}
@end example
@node Troubleshooting Eglot
@chapter Troubleshooting Eglot
@cindex troubleshooting Eglot
This section documents commands and variables that can be used to
This chapter 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.
@ -1118,53 +1275,143 @@ 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.
A common and easy-to-fix cause of performance problems is the length
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.
@menu
* Performance::
* Getting the latest version::
* Reporting bugs::
@end menu
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:
@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.
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:
@enumerate
@item
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.
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.
@item
If Emacs signaled an error (an error message was seen or heard), make
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.
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.
@item
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.
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.
@item
A description of how to setup the @emph{minimal} project (one or two
files and their contents) where the problem happens.
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.
@item
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.
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.
@item
Make sure to double check all the above elements and re-run the
recipe to see that the problem is reproducible.
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.
@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.
that used Eglot to communicate with the language server. Eglot is, in
many cases, just a frontend to that functionality.
@node GNU Free Documentation License
@appendix GNU Free Documentation License

76
doc/misc/erc.texi
View file

@ -2,7 +2,7 @@
@c %**start of header
@setfilename ../../info/erc.info
@settitle ERC Manual
@set ERCVER 5.5
@set ERCVER 5.6
@set ERCDIST as distributed with Emacs @value{EMACSVER}
@include docstyle.texi
@syncodeindex fn cp
@ -611,6 +611,7 @@ And unlike global toggles, none of these ever mutates
Integrations
* URL:: Opening IRC URLs in ERC.
* SOCKS:: Connecting to IRC with a SOCKS proxy.
* auth-source:: Retrieving auth-source entries with ERC.
@end detailmenu
@ -952,7 +953,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}. Note that @code{:user} cannot be given interactively.
@code{erc-tls}.
@item @code{external} (via Client TLS Certificate)
This works in conjunction with the @code{:client-certificate} keyword
@ -1252,6 +1253,57 @@ need a function as well:
@noindent
Users on Emacs 28 and below may need to use @code{browse-url} instead.
@anchor{SOCKS}
@subsection SOCKS
@cindex SOCKS
People wanting to connect to IRC through a @acronym{SOCKS} proxy are
most likely interested in doing so over @acronym{TOR} (The Onion
Router). If that's @emph{not} you, please adapt these instructions
accordingly. Otherwise, keep in mind that support for Tor is
experimental and thus insufficient for safeguarding a user's identity
and location, especially in the case of targeted individuals.
ERC's preferred Tor setup works by accessing a local Tor service
through the built-in @file{socks.el} library that ships with Emacs.
Other means of accessing Tor, such as via @command{torsocks}, are not
supported. Before getting started, check that your Tor service is up
and running. You can do that with the following command:
@example
curl --proxy socks5h://localhost:9050 https://check.torproject.org | \
grep 'Congratulations'
@end example
Networks and servers differ in how they expose Tor endpoints. In all
cases, you'll want to first set the option @code{socks-server} to
something appropriate, like @code{("tor" "127.0.0.1" 9050 5)}. For
some networks, setting @code{erc-server-connect-function} to
@code{socks-open-network-stream} might be enough. Others, like
@samp{Libera.Chat}, involve additional setup. At the time of writing,
connecting to @samp{Libera.Chat} requires both @acronym{TLS} and a
non-@samp{PLAIN} @acronym{SASL} mechanism (@pxref{SASL}). One way to
achieve that is by using the @samp{EXTERNAL} mechanism, as shown in
the following example:
@lisp
(require 'erc)
(require 'socks)
(let* ((socks-password "")
(socks-server '("tor" "localhost" 9050 5))
(erc-modules (cons 'sasl erc-modules))
(erc-sasl-mechanism 'external)
(erc-server-connect-function #'erc-open-socks-tls-stream))
(erc-tls
:server "libera75jm6of4wxpxt4aynol3xjmbtxgfyjpu34ss4d7r7q2v5zrpyd.onion"
:port 6697
:nick "jrh"
:user "jrandomhacker"
:full-name "J. Random Hacker"
:client-certificate (list "/home/jrh/key.pem" "/home/jrh/cert.pem")))
@end lisp
@node auth-source
@subsection auth-source
@cindex auth-source
@ -1477,10 +1529,30 @@ 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}.

2
doc/misc/eshell.texi
View file

@ -602,6 +602,8 @@ 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},

39
doc/misc/flymake.texi
View file

@ -1,8 +1,8 @@
\input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
@comment %**start of header
@setfilename ../../info/flymake.info
@set VERSION 1.2.2
@set UPDATED November 2021
@set VERSION 1.3.4
@set UPDATED April 2023
@settitle GNU Flymake @value{VERSION}
@include docstyle.texi
@syncodeindex pg cp
@ -142,6 +142,12 @@ 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
@ -314,6 +320,22 @@ 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
@ -394,7 +416,7 @@ its @code{flymake-overlay-control} property:
@item
@cindex severity of diagnostic
@code{flymake-severity} is a non-negative integer specifying the
@code{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
@ -409,6 +431,17 @@ 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

48
doc/misc/gnus.texi
View file

@ -713,7 +713,6 @@ Choosing a Mail Back End
Browsing the Web
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
* RSS:: Reading RDF site summary.
@ -10528,9 +10527,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. 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
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
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,19 +10537,22 @@ 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 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.
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.
@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 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.
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.
@vindex gnus-refer-thread-limit-to-thread
In most cases @code{gnus-refer-thread} adds any articles it finds to
@code{gnus-summary-refer-thread} tries to add 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
@ -17244,7 +17246,6 @@ Gnus has been getting a bit of a collection of back ends for providing
interfaces to these sources.
@menu
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
* RSS:: Reading RDF site summary.
@end menu
@ -17261,29 +17262,6 @@ cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus
Unplugged}) handle downloading articles, and then you can read them at
leisure from your local disk. No more World Wide Wait for you.
@node Archiving Mail
@subsection Archiving Mail
@cindex archiving mail
@cindex backup of mail
Some of the back ends, notably @code{nnml}, @code{nnfolder}, and
@code{nnmaildir}, now actually store the article marks with each group.
For these servers, archiving and restoring a group while preserving
marks is fairly simple.
(Preserving the group level and group parameters as well still
requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity
though.)
To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir}
server, take a recursive copy of the server directory. There is no need
to shut down Gnus, so archiving may be invoked by @code{cron} or
similar. You restore the data by restoring the directory tree, and
adding a server definition pointing to that directory in Gnus. The
@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things
might interfere with overwriting data, so you may want to shut down Gnus
before you restore the data.
@node Web Searches
@subsection Web Searches
@cindex nnweb

7
doc/misc/idlwave.texi
View file

@ -1372,10 +1372,9 @@ 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
@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,
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,
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

19
doc/misc/message.texi
View file

@ -1948,11 +1948,9 @@ 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. These are the
supported values:
@table @samp
@item smtpmail
can use the @samp{X-Message-SMTP-Method} header to override the
default by using the keyword @samp{smtp} followed by the server
information:
@example
X-Message-SMTP-Method: smtp smtp.fsf.org 587
@ -1968,16 +1966,19 @@ 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.
@item sendmail
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:
@example
X-Message-SMTP-Method: sendmail
@end example
This will send the message via the locally installed sendmail/exim/etc
installation.
will send the message via the locally installed sendmail program. The
recognized values of @samp{mailer} are sendmail, qmail, mh, and
mailclient.
@end table
@item message-mh-deletable-headers
@vindex message-mh-deletable-headers

400
doc/misc/modus-themes.org
View file

@ -4,9 +4,9 @@
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
#+macro: stable-version 4.1.0
#+macro: release-date 2023-02-22
#+macro: development-version 4.2.0-dev
#+macro: stable-version 4.2.0
#+macro: release-date 2023-05-30
#+macro: development-version 4.3.0-dev
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
@ -77,7 +77,7 @@ combinations of background and foreground values. For small sized
text, this corresponds to the WCAG AAA standard, which specifies a
minimum rate of distance in relative luminance of 7:1.
The Modus themes consist of six themes, divided into three subgroups.
The Modus themes consist of eight themes, divided into four subgroups.
- Main themes :: ~modus-operandi~ is the project's main light theme,
while ~modus-vivendi~ is its dark counterpart. These two themes are
@ -101,15 +101,23 @@ The Modus themes consist of six themes, divided into three subgroups.
users with deueteranopia or deuteranomaly (mostly yellow and blue
hues).
- Tritanopia themes :: ~modus-operandi-tritanopia~ and its counterpart
~modus-vivendi-tritanopia~ are optimized for users with blue-yellow
color deficiency. The idea is the same as with the deuteranopia
variants: color coding relies only on hues that are accessible to
people with tritanopia or tritanomaly, namely, shades of red and
cyan.
To ensure that users have a consistently accessible experience, the
themes strive to achieve as close to full face coverage as possible,
while still targeting a curated list of well-maintained packages
([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]).
The overarching objective of this project is to always offer accessible
color combinations. There shall never be a compromise on this
principle. If there arises an inescapable trade-off between readability
and stylistic considerations, we will always opt for the former.
The overarching objective of this project is to always offer
accessible color combinations. There shall never be a compromise on
this principle. If there arises an inescapable trade-off between
usability and stylistic considerations, we will always opt for the
former.
Starting with version 0.12.0 and onwards, the themes are built into GNU
Emacs.
@ -441,6 +449,8 @@ will lead to failures in loading the files. If either or both of those
variables need to be changed, their values should be defined before the
package declaration of the themes.
[[#h:aabcada6-810d-4eee-b34a-d2a9c301824d][Make the themes look like what the maintainer uses]]
** Differences between loading and enabling
:properties:
:custom_id: h:e68560b3-7fb0-42bc-a151-e015948f8a35
@ -1066,6 +1076,9 @@ palette variable is =THEME-NAME-palette-overrides=, thus yielding:
#+vindex: modus-operandi-tinted-palette-overrides
+ ~modus-operandi-tinted-palette-overrides~
#+vindex: modus-operandi-tritanopia-palette-overrides
+ ~modus-operandi-tritanopia-palette-overrides~
#+vindex: modus-vivendi-palette-overrides
+ ~modus-vivendi-palette-overrides~
@ -1075,6 +1088,9 @@ palette variable is =THEME-NAME-palette-overrides=, thus yielding:
#+vindex: modus-vivendi-tinted-palette-overrides
+ ~modus-vivendi-tinted-palette-overrides~
#+vindex: modus-vivendi-tritanopia-palette-overrides
+ ~modus-vivendi-tritanopia-palette-overrides~
Theme-specific overrides take precedence over the shared ones. It is
strongly advised that shared overrides do NOT alter color values, as
those will not be appropriate for both dark and light themes. Common
@ -1123,7 +1139,7 @@ For example, the ~modus-operandi-palette~ is like this:
#+end_src
The ~modus-operandi-palette-overrides~ targets the entries that need
to be changed. For example, to make the main foreground colour a dark
to be changed. For example, to make the main foreground color a dark
gray instead of pure black, use a shade of red for comments, and apply
a cyan hue to keywords:
@ -1153,15 +1169,30 @@ Named colors can be previewed, such as with the command
For a video tutorial that users of all skill levels can approach,
watch: https://protesilaos.com/codelog/2022-12-17-modus-themes-v4-demo/.
*** Palette override presets
* Advanced customization
:properties:
:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
:end:
Unlike the predefined customization options which follow a clear pattern
of allowing the user to quickly specify their preference, the themes
also provide a more flexible, albeit difficult, mechanism to control
things with precision ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
This section is of interest only to users who are prepared to maintain
their own local tweaks and who are willing to deal with any possible
incompatibilities between versioned releases of the themes. As such,
they are labeled as "do-it-yourself" or "DIY".
** Palette override presets
:PROPERTIES:
:CUSTOM_ID: h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc
:END:
This section shows how to refashion the themes by opting in to the
stylistic presets we provide. Those presets override the default
color mappings to amplify or tone down the overall coloration of the
them.
color mappings to amplify, tone down, or refashion the overall
coloration of the themes.
To make almost all aspects of the themes less intense, use this:
@ -1187,6 +1218,18 @@ The ~modus-themes-preset-overrides-intense~ makes many background
colors accented instead of gray and increases coloration in a number
of places. Colors stand out more and are made easier to spot.
#+vindex: modus-themes-preset-overrides-cooler
#+vindex: modus-themes-preset-overrides-warmer
For some stylistic variation try the "cooler" and "warmer" presets:
#+begin_src emacs-lisp
;; This:
(setq modus-themes-common-palette-overrides modus-themes-preset-overrides-cooler)
;; Or:
(setq modus-themes-common-palette-overrides modus-themes-preset-overrides-warmer)
#+end_src
Note that the user is not limited to those presets. The system of
overrides we provide makes it possible to tweak the value of each
individual named color and to change how values are assigned to
@ -1214,7 +1257,7 @@ the general idea (extra space for didactic purposes):
,@modus-themes-preset-overrides-intense))
#+end_src
*** Stylistic variants using palette overrides
** Stylistic variants using palette overrides
:PROPERTIES:
:CUSTOM_ID: h:df1199d8-eaba-47db-805d-6b568a577bf3
:END:
@ -1226,7 +1269,7 @@ to take effect. To apply overrides at startup simply define them
before the call that loads the theme. Remember that we also provide
presets that are easier to apply ([[#h:b0bc811c-227e-42ec-bf67-15e1f41eb7bc][Palette override presets]]).
**** Make the mode line borderless
*** Make the mode line borderless
:PROPERTIES:
:CUSTOM_ID: h:80ddba52-e188-411f-8cc0-480ebd75befe
:END:
@ -1263,7 +1306,7 @@ set their color to that of the underlying background.
(border-mode-line-inactive bg-mode-line-inactive)))
#+end_src
**** Make the active mode line colorful
*** Make the active mode line colorful
:PROPERTIES:
:CUSTOM_ID: h:e8d781be-eefc-4a81-ac4e-5ed156190df7
:END:
@ -1307,7 +1350,7 @@ have a blue mode line for ~modus-operandi~ and a red one for
(border-mode-line-active bg-red-subtle)))
#+end_src
**** Make the tab bar more or less colorful
*** Make the tab bar more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:096658d7-a0bd-4a99-b6dc-9b20a20cda37
:END:
@ -1359,7 +1402,7 @@ manual.
(bg-tab-other bg-cyan-subtle)))
#+end_src
**** Make the fringe invisible or another color
*** Make the fringe invisible or another color
:PROPERTIES:
:CUSTOM_ID: h:c312dcac-36b6-4a1f-b1f5-ab1c9abe27b0
:END:
@ -1393,7 +1436,7 @@ or continuation lines.
'((fringe bg-blue-nuanced)))
#+end_src
**** Make links use subtle or no underlines
*** Make links use subtle or no underlines
:PROPERTIES:
:CUSTOM_ID: h:6c1d1dea-5cbf-4d92-b7bb-570a7a23ffe9
:END:
@ -1417,7 +1460,7 @@ that underline mappings can read correctly.
(underline-link-symbolic unspecified)))
#+end_src
**** Make prompts more or less colorful
*** Make prompts more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:bd75b43a-0bf1-45e7-b8b4-20944ca8b7f8
:END:
@ -1454,7 +1497,7 @@ block we show how to add or remove color from prompts.
(bg-prompt bg-yellow-subtle))) ; try to replace "subtle" with "intense"
#+end_src
**** Make completion matches more or less colorful
*** Make completion matches more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:d959f789-0517-4636-8780-18123f936f91
:END:
@ -1541,7 +1584,7 @@ colors to two:
The user can mix and match to their liking.
**** Make comments yellow and strings green
*** Make comments yellow and strings green
:PROPERTIES:
:CUSTOM_ID: h:26f53daa-0065-48dc-88ab-6a718d16cd95
:END:
@ -1584,7 +1627,7 @@ reproduce the effect, but also how to tweak it to one's liking.
(string yellow-cooler)))
#+end_src
**** Make code syntax use the old alt-syntax style
*** Make code syntax use the old alt-syntax style
:PROPERTIES:
:CUSTOM_ID: h:c8767172-bf11-4c96-81dc-e736c464fc9c
:END:
@ -1669,7 +1712,7 @@ The user can always mix and match styles to their liking.
[[#h:943063da-7b27-4ba4-9afe-f8fe77652fd1][Make use of alternative styles for code syntax]].
**** Make use of alternative styles for code syntax
*** Make use of alternative styles for code syntax
:PROPERTIES:
:CUSTOM_ID: h:943063da-7b27-4ba4-9afe-f8fe77652fd1
:END:
@ -1760,7 +1803,7 @@ theme palette.
(variable cyan-warmer)))
#+end_src
**** Make matching parenthesis more or less intense
*** Make matching parenthesis more or less intense
:PROPERTIES:
:CUSTOM_ID: h:259cf8f5-48ec-4b13-8a69-5d6387094468
:END:
@ -1790,7 +1833,7 @@ to enable underlines for those highlights.
(underline-paren-match fg-main)))
#+end_src
**** Make box buttons more or less gray
*** Make box buttons more or less gray
:PROPERTIES:
:CUSTOM_ID: h:4f6b6ca3-f5bb-4830-8312-baa232305360
:END:
@ -1818,7 +1861,7 @@ inactive ones.
(fg-button-inactive "gray50")))
#+end_src
**** Make TODO and DONE more or less intense
*** Make TODO and DONE more or less intense
:PROPERTIES:
:CUSTOM_ID: h:b57bb50b-a863-4ea8-bb38-6de2275fa868
:END:
@ -1858,7 +1901,7 @@ to subdue them.
'((prose-done fg-dim)))
#+end_src
**** Make headings more or less colorful
*** Make headings more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:11297984-85ea-4678-abe9-a73aeab4676a
:END:
@ -1915,7 +1958,7 @@ match styles at will.
(overline-heading-1 border)))
#+end_src
**** Make Org agenda more or less colorful
*** Make Org agenda more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:a5af0452-a50f-481d-bf60-d8143f98105f
:END:
@ -1980,7 +2023,25 @@ A third example that makes the agenda more blue:
(date-weekend fg-dim)))
#+end_src
**** Make inline code in prose use alternative styles
Yet another example that also affects =DONE= and =TODO= keywords:
#+begin_src emacs-lisp
;; Change dates to a set of more subtle combinations. Deadlines are a
;; shade of magenta, scheduled dates are a shade of green that
;; complements that of the deadlines, weekday headings use the main
;; foreground color while weekends are a shade of gray. The DONE
;; keyword is a faint blue-gray while TODO is yellow.
(setq modus-themes-common-palette-overrides
'((date-deadline magenta-warmer)
(date-scheduled green-cooler)
(date-weekday fg-main)
(date-event fg-dim)
(date-now blue)
(prose-done fg-alt)
(prose-todo yellow)))
#+end_src
*** Make inline code in prose use alternative styles
:PROPERTIES:
:CUSTOM_ID: h:bb5b396f-5532-4d52-ab13-149ca24854f1
:END:
@ -2039,7 +2100,7 @@ do not show every possible permutation.
(prose-verbatim red-warmer)))
#+end_src
**** Make mail citations and headers more or less colorful
*** Make mail citations and headers more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:7da7a4ad-5d3a-4f11-9796-5a1abed0f0c4
:END:
@ -2108,7 +2169,7 @@ We thus have the following:
(mail-other green)))
#+end_src
**** Make the region preserve text colors, plus other styles
*** Make the region preserve text colors, plus other styles
:PROPERTIES:
:CUSTOM_ID: h:c8605d37-66e1-42aa-986e-d7514c3af6fe
:END:
@ -2148,7 +2209,7 @@ with an appropriate foreground value.
(fg-region fg-main)))
#+end_src
**** Make mouse highlights more or less colorful
*** Make mouse highlights more or less colorful
:PROPERTIES:
:CUSTOM_ID: h:b5cab69d-d7cb-451c-8ff9-1f545ceb6caf
:END:
@ -2177,7 +2238,7 @@ mapping that covers mouse hover effects and related highlights:
'((bg-hover bg-green-subtle)))
#+end_src
**** Make language underlines less colorful
*** Make language underlines less colorful
:PROPERTIES:
:CUSTOM_ID: h:03dbd5af-6bae-475e-85a2-cec189f69598
:END:
@ -2210,7 +2271,7 @@ by code linters and prose spell checkers.
(underline-note green-intense)))
#+end_src
**** Make line numbers use alternative styles
*** Make line numbers use alternative styles
:PROPERTIES:
:CUSTOM_ID: h:b6466f51-cb58-4007-9ebe-53a27af655c7
:END:
@ -2252,7 +2313,7 @@ this section we show how to affect the ~display-line-numbers-mode~.
(bg-line-number-active bg-cyan-intense)))
#+end_src
**** Make diffs use only a foreground
*** Make diffs use only a foreground
:PROPERTIES:
:CUSTOM_ID: h:b3761482-bcbf-4990-a41e-4866fb9dad15
:END:
@ -2268,7 +2329,7 @@ adjustments for them by overriding their palettes directly instead of
just using the "common" overrides.
#+begin_src emacs-lisp
;; Diffs with only foreground colours. Word-wise ("refined") diffs
;; Diffs with only foreground colors. Word-wise ("refined") diffs
;; have a gray background to draw attention to themselves.
(setq modus-themes-common-palette-overrides
'((bg-added unspecified)
@ -2316,7 +2377,7 @@ just using the "common" overrides.
(fg-removed-intense yellow-intense)))
#+end_src
**** Make deuteranopia diffs red and blue instead of yellow and blue
*** Make deuteranopia diffs red and blue instead of yellow and blue
:PROPERTIES:
:CUSTOM_ID: h:16389ea1-4cb6-4b18-9409-384324113541
:END:
@ -2367,20 +2428,110 @@ respectively. This is achieved by overriding the "changed" and
(fg-removed-intense "#ff9095")))
#+end_src
* Advanced customization
:properties:
:custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb
:end:
*** Make the themes look like what the maintainer uses
:PROPERTIES:
:CUSTOM_ID: h:aabcada6-810d-4eee-b34a-d2a9c301824d
:END:
Unlike the predefined customization options which follow a clear pattern
of allowing the user to quickly specify their preference, the themes
also provide a more flexible, albeit difficult, mechanism to control
things with precision ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]).
Based on what we have learnt from the previous sections of this
manual, here is what Protesilaos uses:
This section is of interest only to users who are prepared to maintain
their own local tweaks and who are willing to deal with any possible
incompatibilities between versioned releases of the themes. As such,
they are labeled as "do-it-yourself" or "DIY".
#+begin_src emacs-lisp
;; Always reload the theme for changes to take effect!
(setq modus-themes-custom-auto-reload nil
modus-themes-to-toggle '(modus-operandi modus-vivendi)
modus-themes-mixed-fonts t
modus-themes-variable-pitch-ui nil
modus-themes-italic-constructs t
modus-themes-bold-constructs nil
modus-themes-org-blocks nil
modus-themes-completions '((t . (extrabold)))
modus-themes-prompts nil
modus-themes-headings
'((agenda-structure . (variable-pitch light 2.2))
(agenda-date . (variable-pitch regular 1.3))
(t . (regular 1.15))))
(setq modus-themes-common-palette-overrides
'((cursor magenta-cooler)
;; Make the fringe invisible.
(fringe unspecified)
;; Make line numbers less intense and add a shade of cyan
;; for the current line number.
(fg-line-number-inactive "gray50")
(fg-line-number-active cyan-cooler)
(bg-line-number-inactive unspecified)
(bg-line-number-active unspecified)
;; Make the current line of `hl-line-mode' a fine shade of
;; gray (though also see my `lin' package).
(bg-hl-line bg-dim)
;; Make the region have a cyan-green background with no
;; specific foreground (use foreground of underlying text).
;; "bg-sage" refers to Salvia officinalis, else the common
;; sage.
(bg-region bg-sage)
(fg-region unspecified)
;; Make matching parentheses a shade of magenta. It
;; complements the region nicely.
(bg-paren-match bg-magenta-intense)
;; Make email citations faint and neutral, reducing the
;; default four colors to two; make mail headers cyan-blue.
(mail-cite-0 fg-dim)
(mail-cite-1 blue-faint)
(mail-cite-2 fg-dim)
(mail-cite-3 blue-faint)
(mail-part cyan-warmer)
(mail-recipient blue-warmer)
(mail-subject magenta-cooler)
(mail-other cyan-warmer)
;; Change dates to a set of more subtle combinations.
(date-deadline magenta-cooler)
(date-scheduled magenta)
(date-weekday fg-main)
(date-event fg-dim)
(date-now blue-faint)
;; Make tags (Org) less colorful and tables look the same as
;; the default foreground.
(prose-done cyan-cooler)
(prose-tag fg-dim)
(prose-table fg-main)
;; Make headings less colorful (though I never use deeply
;; nested headings).
(fg-heading-2 blue-faint)
(fg-heading-3 magenta-faint)
(fg-heading-4 blue-faint)
(fg-heading-5 magenta-faint)
(fg-heading-6 blue-faint)
(fg-heading-7 magenta-faint)
(fg-heading-8 blue-faint)
;; Make the active mode line a fine shade of lavender
;; (purple) and tone down the gray of the inactive mode
;; lines.
(bg-mode-line-active bg-lavender)
(border-mode-line-active bg-lavender)
(bg-mode-line-inactive bg-dim)
(border-mode-line-inactive bg-inactive)
;; Make the prompts a shade of magenta, to fit in nicely with
;; the overall blue-cyan-purple style of the other overrides.
;; Add a nuanced background as well.
(bg-prompt bg-magenta-nuanced)
(fg-prompt magenta-cooler)
;; Tweak some more constructs for stylistic constistency.
(name blue-warmer)
(identifier magenta-faint)
(keybind magenta-cooler)
(accent-0 magenta-cooler)
(accent-1 cyan-cooler)
(accent-2 blue-warmer)
(accent-3 red-cooler)))
;; Make the active mode line have a pseudo 3D effect (this assumes
;; you are using the default mode line and not an extra package).
(custom-set-faces
'(mode-line ((t :box (:style released-button)))))
#+end_src
** More accurate colors in terminal emulators
:PROPERTIES:
@ -2584,8 +2735,9 @@ for palette overrides. Else it reads only the default palette.
[[#h:34c7a691-19bb-4037-8d2f-67a07edab150][Option for palette overrides]].
With optional =THEME= as a symbol among ~modus-themes-items~, use the
palette of that item. Else use the current Modus theme.
With optional =THEME= as a symbol among ~modus-themes-items~ (alias
~modus-themes-collection~), use the palette of that item. Else use
the current Modus theme.
If =COLOR= is not present in the palette, this function returns the
~unspecified~ symbol, which is safe when used as a face attribute's
@ -3479,6 +3631,90 @@ In this document, we cover ~modus-themes-after-load-theme-hook~ though
the user can replace it with ~after-enable-theme-hook~ should they
need to (provided they understand the implications).
** Use more spacious margins or padding in Emacs frames
:PROPERTIES:
:CUSTOM_ID: h:43bcb5d0-e25f-470f-828c-662cee9e21f1
:END:
By default, Emacs frames try to maximize the number of characters that
fit in the current visible portion of the buffer. Users may prefer to
have some extra padding instead. This can make Emacs frames look more
pleasant, but also make it easier to identify the currently active
window.
The way to implement such padding is two-fold:
1. In the =early-init.el= file instruct Emacs to use a higher value
for the ~internal-border-width~ of all frames, as well as for the
~right-divider-width~. The former concerns the outer boundaries of
Emacs frames, while the latter pertains to dividers between Emacs
windows.
2. Make the relevant faces invisible by changing the value of their
relevant attributes to that of the current theme's main background.
The parameters of Emacs frames are specified in the variables
~initial-frame-alist~ and ~default-frame-alist~. The "initial frame"
refers to the first frame that appears on Emacs startup. The
"default" refers to the fallback values that apply to all other frames
that Emacs creates (unless those are explicitly overridden by a
bespoke ~make-frame~ call).
In detail, first we use the same values for the two frame alist variables:
#+begin_src emacs-lisp
;; This must go in the early-init.el so that it applies to the initial
;; frame.
(dolist (var '(default-frame-alist initial-frame-alist))
(add-to-list var '(right-divider-width . 20))
(add-to-list var '(internal-border-width . 20)))
#+end_src
What the ~dolist~ does is to call ~add-to-list~ for the two variables
we specify there. This economizes on typing.
Then we define a function that makes the relevant faces invisible.
The reason we do this with a function is so we can hook it to the
"post load" phase of a theme, thus applying the new background value
(otherwise you keep the old background, which likely means that the
faces will no longer be invisible).
#+begin_src emacs-lisp
(defun my-modus-themes-invisible-dividers ()
"Make window dividers invisible.
Add this to the `modus-themes-post-load-hook'."
(let ((bg (face-background 'default)))
(custom-set-faces
`(fringe ((t :background ,bg :foreground ,bg)))
`(window-divider ((t :background ,bg :foreground ,bg)))
`(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
`(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
(add-hook 'modus-themes-post-load-hook #'my-modus-themes-invisible-dividers)
#+end_src
The above will work only for themes that belong to the Modus family.
For users of Emacs version 29 or higher, there exists a theme-agnostic
hook that takes a function with one argument---that of the theme---and
calls in the the "post enable" phase of theme loading. Here is the
above snippet, with the necessary tweaks:
#+begin_src emacs-lisp
(defun my-modus-themes-invisible-dividers (_theme)
"Make window dividers for THEME invisible."
(let ((bg (face-background 'default)))
(custom-set-faces
`(fringe ((t :background ,bg :foreground ,bg)))
`(window-divider ((t :background ,bg :foreground ,bg)))
`(window-divider-first-pixel ((t :background ,bg :foreground ,bg)))
`(window-divider-last-pixel ((t :background ,bg :foreground ,bg))))))
(add-hook 'enable-theme-functions #'my-modus-themes-invisible-dividers)
#+end_src
Users of older versions of Emacs can read the entry herein about
defining their own theme-agnostic hook ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]).
** Custom hl-todo colors
:PROPERTIES:
:CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743
@ -3636,7 +3872,7 @@ have lots of extensions, so the "full support" may not be 100% true…
+ csv-mode
+ ctrlf
+ custom (what you get with {{{kbd(M-x customize)}}})
- dashboard
+ dashboard
+ deadgrep
+ deft
+ devdocs
@ -3651,6 +3887,7 @@ have lots of extensions, so the "full support" may not be 100% true…
+ dired-narrow
+ dired-subtree
+ diredfl
+ disk-usage
+ display-fill-column-indicator-mode
+ doom-modeline
+ ediff
@ -3715,6 +3952,8 @@ have lots of extensions, so the "full support" may not be 100% true…
+ ivy*
+ ivy-posframe
+ jira (org-jira)
+ jit-spell
+ jinx
+ journalctl-mode
+ js2-mode
+ julia
@ -3733,7 +3972,6 @@ have lots of extensions, so the "full support" may not be 100% true…
+ minimap
+ mode-line
+ mood-line
+ moody
+ mpdel
+ mu4e
+ multiple-cursors
@ -3780,6 +4018,7 @@ have lots of extensions, so the "full support" may not be 100% true…
+ rg (rg.el)
+ ripgrep
+ rmail
+ rst-mode
+ ruler-mode
+ sesman
+ shell-script-mode
@ -3969,9 +4208,9 @@ length elsewhere in this manual:
;; Doom should not be implementing such hacks because themes
;; cannot support them:
;; <https://protesilaos.com/codelog/2022-08-04-doom-git-gutter-modus-themes/>.
`(git-gutter-fr:added ((,c :foreground ,bg-added-intense)))
`(git-gutter-fr:deleted ((,c :foreground ,bg-removed-intense)))
`(git-gutter-fr:modified ((,c :foreground ,bg-changed-intense))))))
`(git-gutter-fr:added ((,c :foreground ,bg-added-fringe)))
`(git-gutter-fr:deleted ((,c :foreground ,bg-removed-fringe)))
`(git-gutter-fr:modified ((,c :foreground ,bg-changed-fringe))))))
(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)
#+end_src
@ -4941,9 +5180,10 @@ themes remains consistent.
The former criterion should be crystal clear as it pertains to the
scientific foundations of the themes: high legibility and taking care
of the needs of users with red-green color deficiency (deuteranopia)
by avoiding red+green color coding paradigms and/or by providing
yellow+blue variants ([[#h:f0f3dbcb-602d-40cf-b918-8f929c441baf][Overview]]).
of the needs of users with red-green/blue-yellow color deficiency
(deuteranopia and tritanopia) by avoiding red+green color coding
paradigms and/or by providing yellow+blue variants for deuteranopia
and red+cyan for tritanopia ([[#h:f0f3dbcb-602d-40cf-b918-8f929c441baf][Overview]]).
The latter criterion is the "je ne sais quoi" of the artistic aspect of
the themes, which is partially fleshed out in this manual.
@ -5099,13 +5339,14 @@ The Modus themes are a collective effort. Every bit of work matters.
+ Contributions to code or documentation :: Aleksei Gusev, Alex
Griffin, Anders Johansson, Antonio Ruiz, Basil L.{{{space()}}}
Contovounesios, Björn Lindström, Carlo Zancanaro, Christian Tietze,
Daniel Mendler, Eli Zaretskii, Fritz Grabo, Illia Ostapyshyn, Kévin
Le Gouguec, Koen van Greevenbroek, Kostadin Ninev, Madhavan
Krishnan, Manuel Giraud, Markus Beppler, Matthew Stevenson, Mauro
Aranda, Nicolas De Jaeghere, Paul David, Philip Kaludercic, Pierre
Téchoueyres, Rudolf Adamkovič, Sergey Nichiporchik, Stephen Gildea,
Shreyas Ragavan, Stefan Kangas, Utkarsh Singh, Vincent Murphy,
Xinglu Chen, Yuanchen Xie, okamsn.
Daniel Mendler, David Edmondson, Eli Zaretskii, Fritz Grabo, Gautier
Ponsinet, Illia Ostapyshyn, Kévin Le Gouguec, Koen van Greevenbroek,
Kostadin Ninev, Madhavan Krishnan, Manuel Giraud, Markus Beppler,
Matthew Stevenson, Mauro Aranda, Nacho Barrientos, Nicolas De
Jaeghere, Paul David, Philip Kaludercic, Pierre Téchoueyres, Rudolf
Adamkovič, Sergey Nichiporchik, Shreyas Ragavan, Stefan Kangas,
Stephen Gildea, Steve Downey, Tomasz Hołubowicz, Utkarsh Singh,
Vincent Murphy, Xinglu Chen, Yuanchen Xie, okamsn.
+ Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers,
Adrian Manea, Aleksei Pirogov, Alex Griffin, Alex Koen, Alex
@ -5127,19 +5368,20 @@ The Modus themes are a collective effort. Every bit of work matters.
Bestley, Mark Burton, Mark Simpson, Marko Kocic, Markus Beppler,
Matt Armstrong, Matthias Fuchs, Mattias Engdegård, Mauro Aranda,
Maxime Tréca, Michael Goldenberg, Morgan Smith, Morgan Willcock,
Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Pablo
Stafforini, Paul Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu,
Philip Kaludercic, Pierre Téchoueyres, Przemysław Kryger, Robert
Hepple, Roman Rudakov, Russell Sim, Ryan Phillips, Rytis Paškauskas,
Rudolf Adamkovič, Sam Kleinman, Samuel Culpepper, Saša Janiška,
Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thanos Apollo, Thibaut
Verron, Thomas Heartman, Togan Muftuoglu, Tony Zorman, Trey Merkley,
Tomasz Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, Vincent
Foley, Zoltan Kiraly. As well as users: Ben, CsBigDataHub1, Emacs
Contrib, Eugene, Fourchaux, Fredrik, Moesasji, Nick, Summer Emacs,
TheBlob42, TitusMu, Trey, bepolymathe, bit9tream, bangedorrunt,
derek-upham, doolio, fleimgruber, gitrj95, iSeeU, jixiuf, okamsn,
pRot0ta1p, soaringbird, tumashu, wakamenod.
Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Nicolas
Semrau, Oliver Epper, Pablo Stafforini, Paul Poloskov, Pengji Zhang,
Pete Kazmier, Peter Wu, Philip Kaludercic, Pierre Téchoueyres,
Przemysław Kryger, Robert Hepple, Roman Rudakov, Russell Sim, Ryan
Phillips, Rytis Paškauskas, Rudolf Adamkovič, Sam Kleinman, Samuel
Culpepper, Saša Janiška, Shreyas Ragavan, Simon Pugnet, Steve
Downey, Tassilo Horn, Thanos Apollo, Thibaut Verron, Thomas
Heartman, Togan Muftuoglu, Tony Zorman, Trey Merkley, Tomasz
Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley,
Zoltan Kiraly. As well as users: Ben, CsBigDataHub1, Emacs Contrib,
Eugene, Fourchaux, Fredrik, Moesasji, Nick, Summer Emacs, TheBlob42,
TitusMu, Trey, bepolymathe, bit9tream, bangedorrunt, derek-upham,
doolio, fleimgruber, gitrj95, iSeeU, jixiuf, okamsn, pRot0ta1p,
soaringbird, tumashu, wakamenod.
+ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii,
Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core

5
doc/misc/org.org
View file

@ -5958,8 +5958,9 @@ 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 Emacs Calendar
package[fn:20]. For example, with optional time:
special expression diary entries implemented in the
[[info:emacs#Special Diary Entries][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

299
doc/misc/texinfo.tex
View file

@ -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-01-02.21}
\def\texinfoversion{2023-03-27.21}
%
% Copyright 1985, 1986, 1988, 1990-2023 Free Software Foundation, Inc.
%
@ -1102,27 +1102,33 @@
% Output page labels information.
% See PDF reference v.1.7 p.594, section 8.3.1.
% Page label ranges must be increasing.
\ifpdf
\def\pagelabels{%
\def\title{0 << /P (T-) /S /D >>}%
\edef\roman{\the\romancount << /S /r >>}%
\edef\arabic{\the\arabiccount << /S /D >>}%
%
% Page label ranges must be increasing. Remove any duplicates.
% (There is a slight chance of this being wrong if e.g. there is
% a @contents but no @titlepage, etc.)
%
\ifnum\romancount=0 \def\roman{}\fi
\ifnum\arabiccount=0 \def\title{}%
% support @contents at very end of document
\ifnum\contentsendcount=\pagecount
\ifnum\arabiccount<\romancount
\pdfcatalog{/PageLabels << /Nums
[\title
\the\arabiccount << /S /D >>
\the\romancount << /S /r >>
] >> }\relax
\fi
% no contents in document
\else\ifnum\contentsendcount=0
\pdfcatalog{/PageLabels << /Nums
[\title
\the\arabiccount << /S /D >>
] >> }\relax
\else
\ifnum\romancount=\arabiccount \def\roman{}\fi
\fi
%
\ifnum\romancount<\arabiccount
\pdfcatalog{/PageLabels << /Nums [\title \roman \arabic ] >> }\relax
\else
\pdfcatalog{/PageLabels << /Nums [\title \arabic \roman ] >> }\relax
\fi
\pdfcatalog{/PageLabels << /Nums
[\title
\the\romancount << /S /r >>
\the\contentsendcount << /S /D >>
] >> }\relax
\fi\fi
}
\else
\let\pagelabels\relax
@ -1131,6 +1137,8 @@
\newcount\pagecount \pagecount=0
\newcount\romancount \romancount=0
\newcount\arabiccount \arabiccount=0
\newcount\contentsendcount \contentsendcount=0
\ifpdf
\let\ptxadvancepageno\advancepageno
\def\advancepageno{%
@ -2683,25 +2691,21 @@
}
\setregularquotes
% 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.
% output for ' in @code
% in tt font hex 0D (undirected) or 27 (curly right quote)
%
\def\codequoteright{%
\ifusingtt
{\ifflagclear{txicodequoteundirected}%
{\ifflagclear{codequoteundirected}%
{'}%
{\char'15 }}%
{\char'15 }}%
{\char"0D }}%
{\char"0D }}%
{'}%
}
% 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.
% output for ` in @code
% in tt font hex 12 (grave accent) or 60 (curly left quote)
% \relax disables Spanish ligatures ?` and !` of \tt font.
%
\def\codequoteleft{%
@ -2709,8 +2713,8 @@
{\ifflagclear{txicodequotebacktick}%
{\ifflagclear{codequotebacktick}%
{\relax`}%
{\char'22 }}%
{\char'22 }}%
{\char"12 }}%
{\char"12 }}%
{\relax`}%
}
@ -2729,7 +2733,7 @@
\errmessage{Unknown @codequoteundirected value `\temp', must be on|off}%
\fi\fi
}
%
\parseargdef\codequotebacktick{%
\def\temp{#1}%
\ifx\temp\onword
@ -2744,6 +2748,11 @@
\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}
@ -2929,10 +2938,6 @@
\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
}
%
@ -2942,21 +2947,30 @@
%
% Now, output a discretionary to allow a line break, unless
% (a) the next character is a -, or
% (b) the preceding character is a -.
% (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.
%
% 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\codedashprev\codedash
\ifx\codedashnobreak\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\codedashprev= \next
\global\let\codedashnobreak= \next
}
}
\def\normaldash{-}
%
\def\codex #1{\tclose{#1}\endgroup}
\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\codeunder{%
% this is all so @math{@code{var_name}+1} can work. In math mode, _
@ -3950,33 +3964,23 @@
\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting
% When we turn headings on, set the page number to 1.
% 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\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}
\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdouble}
\let\HEADINGSdoubleafter=\HEADINGSafter
\def\HEADINGSdoublex{%
\def\HEADINGSdouble{%
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\folio\hfil\thistitle}}
@ -3986,8 +3990,10 @@
\global\let\contentsalignmacro = \chapoddpage
}
\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
\def\HEADINGSsinglex{%
% For single-sided printing, chapter title goes across top left of page,
% page number on top right.
\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsingle}
\def\HEADINGSsingle{%
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\thischapter\hfil\folio}}
@ -3999,7 +4005,6 @@
% for @setchapternewpage off
\def\HEADINGSsinglechapoff{%
\pageone
\global\evenfootline={\hfil}
\global\oddfootline={\hfil}
\global\evenheadline={\line{\thischapter\hfil\folio}}
@ -4725,13 +4730,11 @@
% except not \outer, so it can be used within macros and \if's.
\edef\newwrite{\makecsname{ptexnewwrite}}
% \newindex {foo} defines an index named IX.
% \newindex {IX} 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
@ -4989,7 +4992,7 @@
\commondummyword\ampchar {\normalamp}%
\commondummyword\atchar {\@}%
\commondummyword\arrow {->}%
\commondummyword\backslashchar {}%
\commondummyword\backslashchar {\realbackslash}%
\commondummyword\bullet {bullet}%
\commondummyword\comma {,}%
\commondummyword\copyright {copyright}%
@ -5089,9 +5092,6 @@
%
% 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
@ -6817,12 +6817,8 @@
% Get ready to use Arabic numerals again
\def\contentsendroman{%
\lastnegativepageno = \pageno
\global\pageno = \savepageno
%
% If \romancount > \arabiccount, the contents are at the end of the
% document. Otherwise, advance where the Arabic numerals start for
% the page numbers.
\ifnum\romancount>\arabiccount\else\global\arabiccount=\pagecount\fi
\global\pageno=1
\contentsendcount = \pagecount
}
% Typeset the label for a chapter or appendix for the short contents.
@ -7387,6 +7383,7 @@
\def\setupverb{%
\tt
\def\par{\leavevmode\endgraf}%
\parindent = 0pt
\setcodequotes
\tabeightspaces
% Respect line breaks,
@ -7562,11 +7559,6 @@
\exdentamount=\defbodyindent
}
\newtoks\defidx
\newtoks\deftext
\def\useindex#1{\defidx={#1}\ignorespaces}
% Called as \printdefunline \deffooheader{text}
%
\def\printdefunline#1#2{%
@ -7574,10 +7566,6 @@
\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
@ -7592,6 +7580,24 @@
\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{%
\printdefname{#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.
@ -7643,56 +7649,51 @@
\fi\fi
}
\def\defind#1#2{
\defidx={#1}%
\deftext={#2}%
}
% Untyped functions:
% @deffn category name args
\makedefun{deffn}#1 #2 #3\endheader{%
\defind{fn}{\code{#2}}%
\defname{#1}{}{#2}\magicamp\defunargs{#3\unskip}%
\doind{fn}{\code{#2}}%
\printdefname{#1}{}{#2}\magicamp\defunargs{#3\unskip}%
}
% @defop category class name args
\makedefun{defop}#1 {\defopheaderx{#1\ \putwordon}}
\def\defopheaderx#1#2 #3 #4\endheader{%
\defind{fn}{\code{#3}\space\putwordon\ \code{#2}}%
\defname{#1\ \code{#2}}{}{#3}\magicamp\defunargs{#4\unskip}%
\doind{fn}{\code{#3}\space\putwordon\ \code{#2}}%
\printdefname{#1\ \code{#2}}{}{#3}\magicamp\defunargs{#4\unskip}%
}
% Typed functions:
% @deftypefn category type name args
\makedefun{deftypefn}#1 #2 #3 #4\endheader{%
\defind{fn}{\code{#3}}%
\doind{fn}{\code{#3}}%
\doingtypefntrue
\defname{#1}{#2}{#3}\defunargs{#4\unskip}%
\printdefname{#1}{#2}{#3}\defunargs{#4\unskip}%
}
% @deftypeop category class type name args
\makedefun{deftypeop}#1 {\deftypeopheaderx{#1\ \putwordon}}
\def\deftypeopheaderx#1#2 #3 #4 #5\endheader{%
\defind{fn}{\code{#4}\space\putwordon\ \code{#1\ \code{#2}}}%
\doind{fn}{\code{#4}\space\putwordon\ \code{#1\ \code{#2}}}%
\doingtypefntrue
\defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
\printdefname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
}
% Typed variables:
% @deftypevr category type var args
\makedefun{deftypevr}#1 #2 #3 #4\endheader{%
\defind{vr}{\code{#3}}%
\defname{#1}{#2}{#3}\defunargs{#4\unskip}%
\doind{vr}{\code{#3}}%
\printdefname{#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{%
\defind{vr}{\code{#4}\space\putwordof\ \code{#2}}%
\defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
\doind{vr}{\code{#4}\space\putwordof\ \code{#2}}%
\printdefname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}%
}
% Untyped variables:
@ -7708,8 +7709,8 @@
% @deftp category name args
\makedefun{deftp}#1 #2 #3\endheader{%
\defind{tp}{\code{#2}}%
\defname{#1}{}{#2}\defunargs{#3\unskip}%
\doind{tp}{\code{#2}}%
\printdefname{#1}{}{#2}\defunargs{#3\unskip}%
}
% Remaining @defun-like shortcuts:
@ -7725,14 +7726,14 @@
\makedefun{defivar}{\defcvheaderx\putwordInstanceVariableof}
\makedefun{deftypeivar}{\deftypecvheaderx\putwordInstanceVariableof}
% \defname, which formats the name of the @def (not the args).
% \printdefname, which formats the name of the @def (not the args).
% #1 is the category, such as "Function".
% #2 is the return type, if any.
% #3 is the function name.
%
% We are followed by (but not passed) the arguments, if any.
%
\def\defname#1#2#3{%
\def\printdefname#1#2#3{%
\par
% Get the values of \leftskip and \rightskip as they were outside the @def...
\advance\leftskip by -\defbodyindent
@ -7857,7 +7858,7 @@
% If we encounter &foo, then turn on ()-hacking afterwards
\newif\ifampseen
\def\amprm#1 {\ampseentrue{\bf\&#1 }}
\def\amprm#1 {\ampseentrue{\rm\&#1 }}
\def\parenfont{%
\ifampseen
@ -8181,12 +8182,12 @@
%
% We are in \macrobodyctxt, and the \xdef causes backslashshes in the macro
% body to be transformed.
% Set \macrobody to the body of the macro, and call \defmacro.
% Set \macrobody to the body of the macro, and call \macrodef.
%
{\catcode`\ =\other\long\gdef\parsemacbody#1@end macro{%
\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
\xdef\macrobody{\eatcr{#1}}\endgroup\macrodef}}%
{\catcode`\ =\other\long\gdef\parsermacbody#1@end rmacro{%
\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
\xdef\macrobody{\eatcr{#1}}\endgroup\macrodef}}%
% Make @ a letter, so that we can make private-to-Texinfo macro names.
\edef\texiatcatcode{\the\catcode`\@}
@ -8405,16 +8406,17 @@
% \xdef is used so that macro definitions will survive the file
% they're defined in: @include reads the file inside a group.
%
\def\defmacro{%
\def\macrodef{%
\let\hash=##% convert placeholders to macro parameter chars
\ifnum\paramno=1
\def\xeatspaces##1{##1}%
% This removes the pair of braces around the argument. We don't
% use \eatspaces, because this can cause ends of lines to be lost
% when the argument to \eatspaces is read, leading to line-based
% commands like "@itemize" not being read correctly.
\long\def\xeatspaces##1{##1}%
% We don't use \xeatspaces for single-argument macros, because we
% want to keep ends of lines. This definition removes \xeatspaces
% when \macrobody is expanded below.
\else
\let\xeatspaces\relax % suppress expansion
\def\xeatspaces{\string\xeatspaces}%
% This expands \xeatspaces as a sequence of character tokens, which
% stops \scantokens inserting an extra space after the control sequence.
\fi
\ifcase\paramno
% 0
@ -8580,6 +8582,75 @@
\fi \macnamexxx}
% @linemacro
\parseargdef\linemacro{%
\getargs{#1}% now \macname is the macname and \argl the arglist
\ifx\argl\empty
\paramno=0
\let\hash\relax
\def\paramlist{\hash 1\endlinemacro}%
\else
\expandafter\linegetparamlist\argl;%
\fi
\begingroup \macrobodyctxt \usembodybackslash
\parselinemacrobody
}
% 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
\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
{\hash\the\paramno}%
\edef\paramlist{\paramlist\hash\the\paramno\space}%
\fi\next}
\def\linegetparamlistxxxx{%
\expandafter\fixparamlist\paramlist\fixparamlist
}
% 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{%
\xdef\macrobody{#1}%
\endgroup
\linemacrodef
}}
% Make the definition
\def\linemacrodef{%
\let\hash=##%
\expandafter\xdef\csname\the\macname\endcsname{%
\bgroup
\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
}
\expandafter\expandafter
\expandafter\xdef
\expandafter\expandafter\csname\the\macname @@@\endcsname\paramlist{%
\newlinechar=13 % split \macrobody into lines
\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.
@ -9571,8 +9642,8 @@
%
\def\caption{\docaption\thiscaption}
\def\shortcaption{\docaption\thisshortcaption}
\def\docaption{\checkenv\float \bgroup\scanctxt\defcaption}
\def\defcaption#1#2{\egroup \def#1{#2}}
\def\docaption{\checkenv\float \bgroup\scanctxt\docaptionz}
\def\docaptionz#1#2{\egroup \def#1{#2}}
% The parameter is the control sequence identifying the counter we are
% going to use. Create it if it doesn't exist and assign it to \floatno.

137
doc/misc/tramp.texi
View file

@ -938,6 +938,16 @@ 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
@ -1247,6 +1257,7 @@ 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
@ -1503,8 +1514,10 @@ 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. For
Kerberos, try @option{krlogin}.
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}.
For editing local files as @option{su} or @option{sudo} methods, try
the shortened syntax of @samp{root}:
@ -2380,10 +2393,11 @@ 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, 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.
@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.
@subsection Other remote shell setup hints
@ -2758,32 +2772,32 @@ 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-ssh-controlmaster-options
@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-ssh-controlmaster-options} is set to @code{t}. If the
@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:
@lisp
(customize-set-variable 'tramp-use-ssh-controlmaster-options nil)
(customize-set-variable 'tramp-use-connection-share 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-ssh-controlmaster-options} 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{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-ssh-controlmaster-options} should also be set to
@code{nil} or @code{suppress} if you use the @option{ProxyCommand} or
@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.
In order to use the @option{ControlMaster} option, @value{tramp} must
@ -2806,12 +2820,16 @@ Host *
Check the @samp{ssh_config(5)} man page whether these options are
supported on your proxy host.
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.
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.
In PuTTY, you can achieve connection sharing in the @option{Connection/SSH}
entry, enabling the @option{Share SSH connections if possible} option.
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.
@subsection Configure direct copying between two remote servers
@ -2861,11 +2879,19 @@ When @value{tramp} uses direct remote copying, password caches are not
consulted.
@subsection Issues with Cygwin ssh
@subsection Issues with Cygwin and MS Windows 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
@ -2905,13 +2931,15 @@ 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 @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 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.
One workaround is to use an MS Windows based SSH Agent, such as
@command{Pageant}. It is part of the PuTTY Suite of tools.
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.
The fallback is to start Emacs from a shell.
@ -3185,6 +3213,11 @@ 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
@ -4300,9 +4333,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-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}, @ref{Using ssh
@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}.
@ -4344,7 +4377,6 @@ 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
@ -4353,6 +4385,20 @@ 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
@ -4901,6 +4947,36 @@ 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
@ -5215,6 +5291,7 @@ 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}.

20
doc/misc/transient.texi
View file

@ -31,7 +31,7 @@ General Public License for more details.
@finalout
@titlepage
@title Transient User and Developer Manual
@subtitle for version 0.3.7.50
@subtitle for version 0.4.1
@author Jonas Bernoulli
@page
@vskip 0pt plus 1filll
@ -74,7 +74,7 @@ that hurdle is Psionic K's interactive tutorial, available at
@end quotation
@noindent
This manual is for Transient version 0.3.7.50.
This manual is for Transient version 0.4.1.
@insertcopying
@end ifnottex
@ -2150,7 +2150,7 @@ default value of a prefix using the same format as returned by
@item
@code{always-read} For options, whether to read a value on every invocation.
If this is nil, then options that have a value are simply unset and
If this is @code{nil}, then options that have a value are simply unset and
have to be invoked a second time to set a new value.
@item
@ -2566,6 +2566,20 @@ 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?

50
doc/misc/use-package.texi
View file

@ -1554,8 +1554,11 @@ The standard Emacs package manager is documented in the Emacs manual
(@pxref{Package Installation,,, emacs, GNU Emacs Manual}). The
@code{use-package} macro provides the @code{:ensure} and @code{:pin}
keywords that interface with that package manager to automatically
install packages. This is particularly useful if you use your init
file on more than one system.
install packages. The @code{:vc} keyword may be used to control how
package sources are downloaded; e.g., from remote hosts
(@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}). This
is particularly useful if you use your init file on more than one
system.
@menu
* Install package::
@ -1607,6 +1610,49 @@ packages:
You can override the above setting for a single package by adding
@w{@code{:ensure nil}} to its declaration.
@findex :vc
The @code{:vc} keyword can be used to control how packages are
downloaded and/or installed. More specifically, it allows one to fetch
and update packages directly from a version control system. This is
especially convenient when wanting to install a package that is not on
any package archive.
The keyword accepts the same arguments as specified in
@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}, except
that a name need not explicitly be given: it is inferred from the
declaration. The accepted property list is augmented by a @code{:rev}
keyword, which has the same shape as the @code{REV} argument to
@code{package-vc-install}. Notably -- even when not specified --
@code{:rev} defaults to checking out the last release of the package.
You can use @code{:rev :newest} to check out the latest commit.
For example,
@example
@group
(use-package bbdb
:vc (:url "https://git.savannah.nongnu.org/git/bbdb.git"
:rev :newest))
@end group
@end example
would try -- by invoking @code{package-vc-install} -- to install the
latest commit of the package @code{foo} from the specified remote.
This can also be used for local packages, by combining it with the
@code{:load-path} (@pxref{Load path}) keyword:
@example
@group
;; Use a local copy of BBDB instead of the one from GNU ELPA.
(use-package bbdb
:vc t
:load-path "/path/to/bbdb/dir/")
@end group
@end example
The above dispatches to @code{package-vc-install-from-checkout}.
@node Pinning packages
@section Pinning packages using @code{:pin}
@cindex installing package from specific archive

602
etc/EGLOT-NEWS Normal file
View file

@ -0,0 +1,602 @@
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 has a new command to upgrade to the latest version.
The new command 'eglot-upgrade-eglot' allows easily grabbing the
latest version of Eglot from ELPA. This might be more convenient than
using the more general command 'package-install', which by default
will not upgrade "built-in" packages, those that come with Emacs.
* 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 Customize are two ways to set the
external roots of a simple git project.)
(github#893)
** Eglot can now show project wide diagnostics 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 messages.
(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 invocation 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:

227
etc/ERC-NEWS
View file

@ -11,6 +11,229 @@ 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.
** Module 'fill' can add a bit of space between messages.
On graphical displays, it's now possible to add some breathing room
around certain messages via the new option 'erc-fill-line-spacing'.
This is especially handy when using the option 'erc-fill-wrap-merge'
to omit repeated speaker tags, which can make message boundaries less
detectable by tired eyes.
** 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'.
** Improved interplay between buffer truncation and message logging.
While most of these improvements are subtle, some affect everyday use.
For example, users of the 'truncate' module may notice that truncation
now happens between messages rather than arbitrary lines. And those
with the default 'erc-insert-timestamp-left-and-right' for their
'erc-insert-timestamp-function' will see date stamps reprinted after
every "/CLEAR" but omitted from any logs. One notable casualty of
these changes has been the deprecation of the ancient option
'erc-truncate-buffer-on-save'. Users of the 'log' module can achieve
the same effect by issuing a "/CLEAR" at the prompt.
** 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. A new command, 'erc-news',
can now be invoked to visit this very file. 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 'erc-button-alist', 'Info-goto-node' has been supplanted by plain
old 'info', and the "<URL:...>" entry has been removed because it was
more or less redundant. In all ERC buffers, the "<TAB>" key is now
bound to a new command, 'erc-tab', that calls 'completion-at-point'
inside the input area and otherwise dispatches module-specific
commands, like 'erc-button-next'.
* Changes in ERC 5.5
@ -155,8 +378,8 @@ 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. See Emacs change-log entries from around July
of 2022 for specifics.
have been deprecated. For specifics, see entries in Emacs'
ChangeLog.4 from around June 30, 2022.
A number of less consequential deprecations also debut in this
release. For example, the function 'erc-auto-query' was deemed too

4
etc/HELLO
View file

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

323
etc/NEWS
View file

@ -30,6 +30,17 @@ applies, and please also update docstrings as needed.
* Changes in Emacs 30.1
** Help
*** 'describe-function' shows function inferred type when available.
For native compiled Lisp functions 'describe-function' prints (after
the signature) the automatically inferred function type as well.
---
** 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
@ -50,6 +61,11 @@ 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
@ -61,6 +77,11 @@ 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
@ -95,7 +116,7 @@ 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)))
** Compile
** Grep
*** New user option 'grep-use-headings'.
When non-nil, the output of Grep is split into sections, one for each
@ -169,6 +190,19 @@ 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
+++
@ -181,14 +215,23 @@ point is not in a comment or a string. It is by default bound to
** Tramp
+++
*** New connection method "toolbox".
This allows accessing system containers provided by Toolbox.
*** New connection methods "toolbox" and "flatpak".
They allow accessing system containers provided by Toolbox or
sandboxes provided by Flatpak.
+++
*** New value 'suppress' for user option 'tramp-use-ssh-controlmaster-options'.
This user option allows now the values t, nil, and 'suppress'. The
latter suppresses also "ControlMaster" settings in the user's
"~/.ssh/config" file.
*** 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'.
** EWW
@ -199,6 +242,17 @@ 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
+++
@ -214,6 +268,130 @@ 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').
---
*** New user option 'package-vc-allow-side-effects'.
When non-nil, package specifications with side-effects for building
software will be used when building a package.
** 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()
** use-package
+++
*** New ':vc' keyword.
This keyword enables the user to install packages using 'package-vc'.
** Rmail
---
*** New commands for reading mailing lists.
The new Rmail commands 'rmail-mailing-list-post',
'rmail-mailing-list-unsubscribe', 'rmail-mailing-list-help', and
'rmail-mailing-list-archive' allow to, respectively, post to,
unsubscribe from, request help about, and browse the archives, of the
mailing list from which the current email message was delivered.
** Dictionary
---
*** New user option 'dictionary-search-interface'.
Controls how the 'dictionary-search' command prompts for and displays
dictionary definitions. Customize this user option to 'help' to have
'dictionary-search' display definitions in a "*Help*" buffer and
provide dictionary-based minibuffer completion for word selection.
---
*** New user option 'dictionary-read-word-prompt'.
This allows the user to customize the prompt that is used by
'dictionary-search' when asking for a word to search in the
dictionary.
---
*** New user option 'dictionary-display-definition-function'.
This allows the user to customize the way in which 'dictionary-search'
displays word definitions. If non-nil, this user option should be set
to a function that displays a word definition obtained from a
dictionary server. The new function
'dictionary-display-definition-in-help-buffer' can be used to display
the definition in a "*Help*" buffer, instead of the default
"*Dictionary*" buffer.
---
*** New user option 'dictionary-read-word-function'.
This allows the user to customize the way in which 'dictionary-search'
prompts for a word to search in the dictionary. This user option
should be set to a function that lets the user select a word and
returns it as a string. The new function
'dictionary-completing-read-word' can be used to prompt with
completion based on dictionary matches.
---
*** New user option 'dictionary-read-dictionary-function'.
This allows the user to customize the way in which 'dictionary-search'
prompts for a dictionary to search in. This user option should be set
to a function that lets the user select a dictionary and returns its
name as a string. The new function
'dictionary-completing-read-dictionary' can be used to prompt with
completion based on dictionaries that the server supports.
* New Modes and Packages in Emacs 30.1
@ -225,19 +403,41 @@ An optional major mode based on the tree-sitter library for editing
HTML files.
---
** The highly accessible Modus themes collection has six items.
*** 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 eight items.
The 'modus-operandi' and 'modus-vivendi' are the main themes that have
been part of Emacs since version 28. The former is light, the latter
dark. In addition to these, we now have 'modus-operandi-tinted' and
'modus-vivendi-tinted' for easier legibility, as well as
'modus-operandi-deuteranopia' and 'modus-vivendi-deuteranopia' to
cover the needs of users with red-green color deficiency. The Info
manual "(modus-themes) Top" describes the details and showcases all
their customization options.
'modus-operandi-deuteranopia', 'modus-vivendi-deuteranopia',
'modus-operandi-tritanopia', and 'modus-vivendi-tritanopia' to cover
the needs of users with red-green or blue-yellow color deficiency.
The Info manual "(modus-themes) Top" describes the details and
showcases all 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.
@ -248,9 +448,19 @@ These hooks were named incorrectly, and so they never actually ran
when unloading the correspending feature. Instead, you should use
hooks named after the feature name, like 'esh-mode-unload-hook'.
+++
** 'copy-tree' now copies records when its optional 2nd argument is non-nil.
* Lisp Changes in Emacs 30.1
+++
** New user option 'safe-local-variable-directories'.
This user option names directories in which Emacs will treat all
directory-local variables as safe.
** New variable 'inhibit-auto-fill' to temporarily prevent auto-fill.
** Functions and variables to transpose sexps
+++
@ -358,31 +568,90 @@ 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'.
+++
** New function 'safe-copy-tree'
This function is a version of copy-tree which handles circular lists
and circular vectors/records.
---
*** 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 mutation of constant values.
The compiler now warns about code that modifies program constants in
some obvious cases. Examples:
(setcar '(1 2) 7)
(aset [3 4] 0 8)
(aset "abc" 1 ?d)
Such code may have unpredictable behavior because the constants are
part of the program, not data structures generated afresh during
execution, and the compiler does not expect them to change.
To avoid the warning, operate on an object created by the program
(maybe a copy of the constant), or use a non-destructive operation
instead.
This warning can be suppressed using 'with-suppressed-warnings' with
the warning name 'mutate-constant'.
---
*** 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.
+++
** '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
** 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
(defalias 'able 'baker)
(defalias 'baker 'able)
but trying to call them would often make Emacs hang. Now, an attempt
but trying to use them would sometimes 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' and
'indirect-function' will never signal an error. Their second
'noerror' arguments have no effect and are therefore obsolete.
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.
---
** New function 'eval-command-interactive-spec' in the subr-x library.
This function evaluates a command's interactive form and returns the
resultant list.
* Changes in Emacs 30.1 on Non-Free Operating Systems

335
etc/NEWS.29
View file

@ -91,24 +91,6 @@ available, and includes support for animated WebP images. To disable
WebP support, use the '--without-webp' configure flag. Image
specifiers can now use ':type webp'.
+++
** Emacs has been ported to the Haiku operating system.
The configuration process should automatically detect and build for
Haiku. There is also an optional window-system port to Haiku, which
can be enabled by configuring Emacs with the option '--with-be-app',
which will require the Haiku Application Kit development headers and a
C++ compiler to be present on your system. If Emacs is not built with
the option '--with-be-app', the resulting Emacs will only run in
text-mode terminals.
To enable Cairo support, ensure that the Cairo and FreeType
development files are present on your system, and configure Emacs with
'--with-be-cairo'.
Unlike X, there is no compile-time option to enable or disable
double-buffering; it is always enabled. To disable it, change the
frame parameter 'inhibit-double-buffering' instead.
---
** Emacs now installs the ".pdmp" file using a unique fingerprint in the name.
The file is typically installed using a file name akin to
@ -126,6 +108,16 @@ option '--without-xinput2' to disable this support.
'(featurep 'xinput2)' can be used to test for the presence of XInput 2
support from Lisp programs.
---
** Emacs can now be optionally built with the Cairo XCB backend.
Configure Emacs with the '--with-cairo-xcb' option to use the Cairo
XCB backend; the default is not to use it. This backend makes Emacs
moderately faster when running over X connections with high latency,
but is currently known to crash when Emacs repeatedly closes and opens
a display connection to the same terminal; this could happen, for
example, if you repeatedly visit files via emacsclient in a single
client frame, each time deleting the frame with 'C-x C-c'.
+++
** Emacs now supports being built with pure GTK.
To use this option, make sure the GTK 3 (version 3.22.23 or later) and
@ -139,6 +131,29 @@ known to have problems, such as undesirable frame positioning and
various issues with keyboard input of sequences such as 'C-;' and
'C-S-u'.
Note that, unlike the X build of Emacs, the PGTK build cannot
automatically switch to text-mode interface (thus emulating '-nw') if
it cannot determine the default display; it will instead complain and
ask you to invoke it with the explicit '-nw' option.
+++
** Emacs has been ported to the Haiku operating system.
The configuration process should automatically detect and build for
Haiku. There is also an optional window-system port to Haiku, which
can be enabled by configuring Emacs with the option '--with-be-app',
which will require the Haiku Application Kit development headers and a
C++ compiler to be present on your system. If Emacs is not built with
the option '--with-be-app', the resulting Emacs will only run in
text-mode terminals.
To enable Cairo support, ensure that the Cairo and FreeType
development files are present on your system, and configure Emacs with
'--with-be-cairo'.
Unlike X, there is no compile-time option to enable or disable
double-buffering; it is always enabled. To disable it, change the
frame parameter 'inhibit-double-buffering' instead.
---
** Emacs no longer reduces the size of the Japanese dictionary.
Building Emacs includes generation of a Japanese dictionary, which is
@ -218,13 +233,13 @@ of 'user-emacs-directory'.
+++
** The image commands have changed key bindings.
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.
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.
+++
** Emacs now picks the correct coding-system for X input methods.
@ -380,7 +395,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 have been made obsolete in Emacs 25.1 with
and 'defgeneric' (which were made obsolete in Emacs 25.1 by
'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 +512,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 +532,7 @@ performance, but the latter is closer to a drop-in replacement.
---
** The thumbs.el library is now obsolete.
We recommend using command 'image-dired' instead.
We recommend using the 'image-dired' command instead.
---
** The autoarg.el library is now marked obsolete.
@ -577,7 +592,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') without having to use 'defalias', which can have
'LaTeX-mode') instead of 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,6 +602,8 @@ 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.
@ -795,13 +812,14 @@ part of the buffer.
+++
** New user option 'set-message-functions'.
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.
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.
---
** New user option 'find-library-include-other-files'.
@ -854,17 +872,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.
@ -901,7 +919,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.
instead of XIM input methods. Defaults to nil.
+++
** New user option 'use-system-tooltips'.
@ -998,17 +1016,17 @@ combinations in a graphical menu system.
+++
*** New command 'emoji-search' (bound to 'C-x 8 e s').
This command lets you search for Emoji based on names.
This command lets you search for and insert an 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.
buffer and lets you choose one of them to insert.
---
*** New command 'emoji-recent' (bound to 'C-x 8 e r').
This command lets you choose among the Emoji you have recently
inserted.
inserted and insert it.
+++
*** New command 'emoji-describe' (bound to 'C-x 8 e d').
@ -1020,6 +1038,11 @@ 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:'
@ -1037,7 +1060,7 @@ quotes removed.
---
*** 'M-x apropos-variable' output now includes values of variables.
Such apropos buffer is more easily viewed with outlining after
Such an apropos buffer is more easily viewed with outlining after
enabling 'outline-minor-mode' in 'apropos-mode'.
+++
@ -1069,7 +1092,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's no local help at point. This has been changed to call
there was no local help at point. This has been changed to call
'button-describe'/'widget-describe' and display button/widget help
instead.
@ -1122,7 +1145,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 "ORG-NEWS" for user-visible changes in Org.
See the file "etc/ORG-NEWS" for user-visible changes in Org.
** Outline Mode
@ -1185,12 +1208,13 @@ the display of several buffers in a row more amenable.
+++
*** New buffer display action alist entry 'lru-frames'.
This allows to specify which frames 'display-buffer' should consider
when using a window that shows another buffer.
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'.
+++
*** New buffer display action alist entry 'lru-time'.
'display-buffer' will ignore windows with a use time higher than that
'display-buffer' will ignore windows with a use time higher than this
when using a window that shows another buffer.
+++
@ -1200,12 +1224,14 @@ making it a less likely candidate for displaying another buffer.
+++
*** New buffer display action alist entry 'window-min-width'.
This allows to specify a minimum width of the window used to display a
buffer.
This allows specifying a preferred minimum width of the window used to
display a buffer.
---
*** You can customize on which window 'scroll-other-window' operates.
This is controlled by the new 'other-window-scroll-default' variable.
*** 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.
** Frames
@ -1268,17 +1294,19 @@ 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 given by the argument, which can be
'empty', 'delete-frame' or 'kill-terminal'.
are met. The conditions are determined by the argument to
'server-stop-automatically', 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 will use the default 'completion-at-point' mechanism. The
Rcirc now uses 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.
@ -1533,6 +1561,10 @@ 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
@ -1546,7 +1578,10 @@ 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 Ukrainian translation of the Emacs tutorial.
---
*** New Farsi/Persian translation of the Emacs tutorial.
---
*** New default phonetic input method for the Tamil language environment.
@ -1571,6 +1606,12 @@ 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
@ -1651,6 +1692,13 @@ the following to your Init file:
*** New command 'dired-do-eww'.
This command visits the file on the current line with EWW.
---
*** 'browse-url-of-dired-file' can now call the secondary browser.
When invoked with a prefix arg, this will now call
'browse-url-secondary-browser-function' instead of the default
browser. 'browse-url-of-dired-file' is bound to 'W' by default in
dired mode.
---
*** New user option 'dired-omit-lines'.
This is used by 'dired-omit-mode', and now allows you to hide based on
@ -1728,7 +1776,7 @@ or can take a long time to render.
+++
*** New command 'enriched-toggle-markup'.
This allows you to see the markup in 'enriched-mode' buffers (e.g.,
the "HELLO" file).
the "HELLO" file). Bound to 'M-o m' by default.
** Shell Script Mode
@ -1817,13 +1865,18 @@ this includes "binary" buffers like 'archive-mode' and 'image-mode'.
** Package
+++
*** New command 'package-update'.
This command allows you to upgrade packages without using 'M-x
list-packages'.
*** New command 'package-upgrade'.
This command allows you to upgrade packages without using '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'.
+++
*** New command 'package-update-all'.
This command allows updating all packages without any queries.
*** 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 commands 'package-recompile' and 'package-recompile-all'.
@ -1833,7 +1886,9 @@ These commands can be useful if the ".elc" files are out of date
+++
*** New DWIM action on 'x' in "*Packages*" buffer.
If no packages are marked, 'x' will install the package under point if
it isn't already, and remove it if it is installed.
it isn't already, and remove it if it is installed. Customize the new
option 'package-menu-use-current-if-no-marks' to the nil value to get
back the old behavior of signaling an error in that case.
+++
*** New command 'package-vc-install'.
@ -1858,13 +1913,33 @@ 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.
package maintainers, and is bound to 'b' in the "*Packages*" buffer.
+++
*** 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.
In addition, when this option is non-nil, built-in packages for which
a new version is available in archives can be upgraded via the package
menu produced by 'list-packages'. If you do set this option non-nil,
we recommend not to use the 'U' command, but instead to use '/ u' to
show the packages which can be upgraded, and then decide which ones of
them you actually want to update from the archives.
If you customize this option, we recommend you place its non-default
setting in your early-init file.
** Emacs Sessions (Desktop)
+++
@ -1922,8 +1997,8 @@ displayed in a window.
+++
*** New user option 'compilation-hidden-output'.
This can be used to make specific parts of compilation output
invisible.
This regular expression can be used to make specific parts of
compilation output invisible.
+++
*** The 'compilation-auto-jump-to-first-error' user option has been extended.
@ -2306,7 +2381,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 to produce syntax
order to be useful in messages, there was a risk of producing 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
@ -2340,8 +2415,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. The attributes 'email', 'name', and 'firstname'
are supported only.
be queried by EUDC, too. Only the attributes 'email', 'name', and
'firstname' are supported.
** EWW/SHR
@ -2540,8 +2615,16 @@ 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 'xref-go-back'
('M-,', also known as 'xref-pop-marker-stack') was invoked previously.
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.
+++
*** 'xref-query-replace-in-results' prompting change.
@ -2580,14 +2663,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 does not
only scale the image down, but up as well. It is bound to 's w' in
Image Mode by default.
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.
---
*** New command 'image-mode-wallpaper-set'.
This command sets the desktop background to the current image. It is
bound to 'W' by default.
bound to 'W' in Image Mode by default.
+++
*** 'image-transform-fit-to-{height,width}' are now obsolete.
@ -2605,19 +2688,14 @@ 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 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.
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.
+++
*** New command 'image-transform-set-percent'.
It allows setting the image size to a percentage of its original size,
and is bound to 's p' in Image mode.
It allows resizing the image 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'.
@ -2629,6 +2707,19 @@ 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'.
@ -3214,7 +3305,12 @@ 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.
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.
+++
** use-package: Declarative package configuration.
@ -3223,13 +3319,9 @@ 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.
+++
** 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.
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 package 'wallpaper'.
@ -3556,11 +3648,13 @@ font spec. In these cases, replacing ":weight 'normal" with ":weight
'medium" should fix the issue.
---
** Keymap descriptions have changed.
** Keymap descriptions by Help commands 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,
"[closure]"/"[lambda]" is output.
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.
---
** 'downcase' details have changed slightly.
@ -3801,6 +3895,19 @@ The following generalized variables have been made obsolete:
'standard-case-table', 'syntax-table', 'visited-file-modtime',
'window-height', 'window-width', and 'x-get-secondary-selection'.
---
** The 'dotimes' loop variable can no longer be manipulated in the loop body.
Previously, the 'dotimes' loop counter could be modified inside the
loop body, but only in code using dynamic binding. Now the behavior
is the same as when using lexical binding: changes to the loop
variable have no effect on subsequent iterations. That is,
(dotimes (i 10)
(print i)
(setq i (+ i 6)))
now always prints the numbers 0 .. 9.
* Lisp Changes in Emacs 29.1
@ -3893,9 +4000,9 @@ connection-local profile.
+++
*** New macro 'with-connection-local-application-variables'.
This macro works like 'with-connection-local-variables', but it allows
to use another application but 'tramp'. This is useful when running
code in a buffer where Tramp has already set some connection-local
variables.
using another application instead of 'tramp'. This is useful when
running code in a buffer where Tramp has already set some
connection-local variables.
+++
*** New macro 'setq-connection-local'.
@ -3974,8 +4081,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 where the
element at a given (zero-based) index got removed.
This function returns a copy of the specified sequence with the
element at a given (zero-based) index removed.
+++
*** New function 'seq-positions'.
@ -4043,7 +4150,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 seems
invalid. Emacs will now warn during byte compilation if it sees
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
@ -4103,7 +4210,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 a callback is called when the user types 'C-c C-c'.
and the provided callback is called when the user types 'C-c C-c'.
+++
** New function 'read-string-from-buffer'.
@ -4249,7 +4356,7 @@ them towards or away from each other.
+++
** New hook 'x-pre-popup-menu-hook'.
This hook, run before 'x-popup-menu', is about to display a
This hook is run before 'x-popup-menu' is about to display a
deck-of-cards menu on screen.
---
@ -4311,9 +4418,11 @@ 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'. None of the older
functions have been deprecated or altered, but they are now
de-emphasized in the documentation.
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.
+++
*** Use 'keymap-set' instead of 'define-key'.
@ -4348,8 +4457,8 @@ de-emphasized in the documentation.
+++
*** '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).
different from setting a definition to nil: when the keymap has a
parent such a definition will shadow the parent's definition.
+++
*** 'read-multiple-choice' now takes an optional SHOW-HELP argument.
@ -4884,6 +4993,12 @@ 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.

6
etc/ORG-NEWS
View file

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

43
etc/PROBLEMS
View file

@ -516,6 +516,13 @@ directory copy is ineffective.
This is due to an arbitrary limit in certain versions of awk.
The solution is to use gawk (GNU awk).
*** Saving, via EasyPG, a file encrypted with GnuPG hangs
This is known to happen with GnuPG v2.4.1. The only known workaround
is to downgrade to a version of GnuPG older than 2.4.1 (or, in the
future, upgrade to a newer version which solves the problem, when such
a fixed version becomes available).
** Problems with hostname resolution
*** Emacs does not know your host's fully-qualified domain name.
@ -2313,6 +2320,33 @@ 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>
@ -2681,6 +2715,15 @@ 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,

Some files were not shown because too many files have changed in this diff Show more