procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge remote-tracking branch 'origin/master' into feature/tree-sitter

Browse source
This commit is contained in:
Yuan Fu 2022-08-29 11:41:10 -07:00
commit 77d5a0cf9f
1242 changed files with 71058 additions and 43834 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.dir-locals.el
View file

@ -4,6 +4,7 @@
((nil . ((tab-width . 8)
(sentence-end-double-space . t)
(fill-column . 70)
(emacs-lisp-docstring-fill-column . 65)
(bug-reference-url-format . "https://debbugs.gnu.org/%s")))
(c-mode . ((c-file-style . "GNU")
(c-noise-macro-names . ("INLINE" "ATTRIBUTE_NO_SANITIZE_UNDEFINED" "UNINIT" "CALLBACK" "ALIGN_STACK"))

6
.gitignore vendored
View file

@ -324,3 +324,9 @@ lib-src/seccomp-filter-exec.pfc
# Ignore directory made by admin/make-manuals.
manual/
# Ignore Finder files on MacOS.
.DS_Store
# Ignore a directory used by dap-mode.
.vscode

36
CONTRIBUTE
View file

@ -314,11 +314,45 @@ them right the first time, so here are guidelines for formatting them:
with Emacs commands like 'C-x 4 a', and commit the change using the
shell command 'vc-dwim --commit'. Type 'vc-dwim --help' for more.
** 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
fail. These scripts live in the '.git/hooks/' subdirectory of the
top-level directory of the repository, and they perform the following
tests:
- commit log message must not be empty;
- the first line of the commit log message doesn't start with
whitespace characters;
- the second line of the commit log message must be empty;
- commit log message should include only valid printable ASCII and
UTF-8 characters;
- commit log message lines must be shorter than 79 characters, unless
a line consists of a single long word, in which case that word can
be up to 140 characters long;
- there shouldn't be any "Signed-off-by:" tags in the commit log
message, and "git commit" should not be invoked with the '-s' option
(which automatically adds "Signed-off-by:");
- if the commit adds new files, the file names must not begin with
'-' and must consist of ASCII letters, digits, and characters of the
set [-+./_];
- the changes don't include unresolved merge conflict markers;
- the changes don't introduce whitespace errors: trailing whitespace,
lines that include nothing but whitespace characters, and indented
lines where a SPC character is immediately followed by a TAB in the
line's initial indentation
** Committing changes by others
If committing changes written by someone else, commit in their name,
not yours. You can use 'git commit --author="AUTHOR"' to specify a
change's author.
change's author. When using Emacs VC to commit, the author can be
specified in the log-edit buffer by adding an "Author: AUTHOR" header
line (set 'log-edit-setup-add-author' non-nil to have this header line
added automatically). Note that the validity checks described in the
previous section are still applied, so you will have to correct any
problems they uncover in the changes submitted by others.
** Branches

6
ChangeLog.2
View file

@ -4040,7 +4040,7 @@
* lisp/progmodes/xref.el (xref--query-replace-1):
Say 'All results processed' at the end if the user hadn't
cancelled the process (bug#23284).
canceled the process (bug#23284).
2016-05-07 Eli Zaretskii <eliz@gnu.org>
@ -12542,7 +12542,7 @@
* lisp/erc/erc-backend.el (erc-server-setup-periodical-ping): Checks
for existing timers in the alist before adding new ones. If a
timer already exists, it is cancelled and
timer already exists, it is canceled and
overwritten. (bug#19292).
2015-12-27 Jens Lechtenboerger <jens.lechtenboerger@fsfe.org>
@ -22108,7 +22108,7 @@
* src/gfilenotify.c (dir_monitor_callback): Cancel the monitor if
the file or directory to be watched is deleted.
(Fgfile_add_watch): Make watch_object a triple.
(Fgfile_rm_watch): Check, whether watch is cancelled already.
(Fgfile_rm_watch): Check, whether watch is canceled already.
(Fgfile_valid_p): New defun.
(syms_of_gfilenotify): Declare Sgfile_valid_p.

2342
ChangeLog.3
View file

File diff suppressed because it is too large Load diff

35
Makefile.in
View file

@ -51,7 +51,15 @@
#
# make bootstrap
# Removes all the compiled files to force a new bootstrap from a
# clean slate, and then build in the normal way.
# clean slate, and then build in the normal way. If the FAST Make
# variable is set, then the config.cache file isn't removed. This
# allows you to say
#
# ./configure -C
# make FAST=true bootstrap
#
# and use the cached results from the configure run, which is much
# faster.
#
# make docs
# Make Emacs documentation files from their sources; requires makeinfo.
@ -358,10 +366,17 @@ endif
gsettings_SCHEMAS = etc/org.gnu.emacs.defaults.gschema.xml
all: ${SUBDIR} info $(gsettings_SCHEMAS:.xml=.valid)
all: ${SUBDIR} info $(gsettings_SCHEMAS:.xml=.valid) src-depending-on-lisp
.PHONY: all ${SUBDIR} blessmail epaths-force epaths-force-w32 epaths-force-ns-self-contained etc-emacsver
# Changes in lisp may require us to reconsider the build in src. For
# example, if loaddefs.{el,elc} were built in lisp, we need a new
# .pdmp containing the new autoloads.
.PHONY: src-depending-on-lisp
src-depending-on-lisp: lisp
${MAKE} -C src BIN_DESTDIR='$(BIN_DESTDIR)' ELN_DESTDIR='$(ELN_DESTDIR)'
# If configure were to just generate emacsver.tex from emacsver.tex.in
# in the normal way, the timestamp of emacsver.tex would always be
# newer than that of the pdf files, which are prebuilt in release tarfiles.
@ -455,18 +470,11 @@ lisp: src
lib lib-src lisp nt: Makefile
$(MAKE) -C $@ all
# Ideally, VCSWITNESS should be a file that is modified whenever the
# repository registers a commit from either a local checkin or a
# repository pull. In git there is no single file that guarantees
# this, but the local log for the current head should be close enough.
#
# Pass an unexpanded $srcdir to src's Makefile, which then
# expands it using its own value of srcdir (which points to the
# source directory of src/).
dirstate = .git/logs/HEAD
VCSWITNESS = $(if $(wildcard $(srcdir)/$(dirstate)),$$(srcdir)/../$(dirstate))
src: Makefile
$(MAKE) -C $@ VCSWITNESS='$(VCSWITNESS)' BIN_DESTDIR='$(BIN_DESTDIR)' \
$(MAKE) -C $@ BIN_DESTDIR='$(BIN_DESTDIR)' \
ELN_DESTDIR='$(ELN_DESTDIR)' all
blessmail: Makefile src
@ -936,7 +944,7 @@ clean: $(clean_dirs:=_clean) clean-gsettings-schemas
### 'bootclean'
### Delete all files that need to be remade for a clean bootstrap.
top_bootclean=\
rm -f config.cache config.log ${srcdir}/doc/man/emacs.1
rm -f config.log ${srcdir}/doc/man/emacs.1
### 'distclean'
### Delete all files from the current directory that are created by
@ -946,7 +954,7 @@ top_bootclean=\
### distribution.
top_distclean=\
${top_bootclean}; \
rm -f config.status config.log~ \
rm -f config.cache config.status config.log~ \
Makefile makefile lib/gnulib.mk ${SUBDIR_MAKEFILES}
distclean_dirs = $(clean_dirs) leim lisp admin/grammars
@ -966,6 +974,9 @@ bootstrap-clean: $(distclean_dirs:=_bootstrap-clean)
rm -rf ${srcdir}/info
rm -f ${srcdir}/etc/refcards/emacsver.tex
rm -rf native-lisp/ lisp/leim/ja-dic/
ifndef FAST
rm -f config.cache
endif
${top_bootclean}
### 'maintainer-clean'

1
admin/MAINTAINERS
View file

@ -137,6 +137,7 @@ Andrea Corallo
Stefan Kangas
admin/automerge
admin/update_autogen
Po Lu
The Haiku port:

9
admin/admin.el
View file

@ -488,10 +488,11 @@ the @import directive."
(delete-region opoint (point))
(search-forward "<meta http-equiv=\"Content-Style")
(setq opoint (match-beginning 0)))
(search-forward "<title>")
(delete-region opoint (match-beginning 0))
(search-forward "</title>\n")
(delete-region opoint (point))
(search-forward "<link href=")
(goto-char (match-beginning 0))
(when (search-forward "<link href=" nil t)
(goto-char (match-beginning 0)))
(insert manual-links-string)
(setq opoint (point))
(search-forward "</head>")
@ -617,7 +618,7 @@ style=\"text-align:left\">")
;; its original form.
(when (or (search-forward "<ul class=\"menu\">" nil t)
;; FIXME? The following search seems dangerously lax.
(search-forward "<ul>"))
(search-forward "<ul>" nil t))
;; Convert the list that Makeinfo made into a table.
(replace-match "<table style=\"float:left\" width=\"100%\">")
(forward-line 1)

3
admin/authors.el
View file

@ -163,6 +163,7 @@ files.")
("Michael R. Cook" "Michael Cook")
("Michael Sperber" "Mike Sperber" "Michael Sperber \\[Mr. Preprocessor\\]")
("Michalis V" "^mvar")
("Miha Rihtaršič" "Miha Rihtarsic")
("Mikio Nakajima" "Nakajima Mikio")
("Nelson Jose dos Santos Ferreira" "Nelson Ferreira")
("Noorul Islam" "Noorul Islam K M")
@ -1882,7 +1883,7 @@ list of their contributions.\n")
(insert "\n "))
(insert " " file))
(insert "\n")))))
(insert "\nLocal" " Variables:\nmode: etc-authors\ncoding: "
(insert "\nLocal" " Variables:\nmode: emacs-authors\ncoding: "
(symbol-name authors-coding-system) "\nEnd:\n")
(message "Generating buffer %s... done" buffer-name)
(unless noninteractive

2
admin/automerge
View file

@ -4,7 +4,7 @@
## Copyright (C) 2018-2022 Free Software Foundation, Inc.
## Author: Glenn Morris <rgm@gnu.org>
## Maintainer: Stefan Kangas <stefan@marxist.se>
## Maintainer: Stefan Kangas <stefankangas@gmail.com>
## This file is part of GNU Emacs.

8
admin/check-doc-strings
View file

@ -290,13 +290,7 @@ while (my $file = <FIND>) {
}
}
my @pkgs;
if (-d "../xemacs-packages") {
@pkgs = qw (libs/edebug libs/xemacs-base comm/eudc oa/edit-utils);
} else {
@pkgs = ();
}
for (@pkgs) { s@^@../xemacs-packages/@; }
my @pkgs = ();
open (FIND, "find lisp @pkgs -name '*.el' -print |") or die;
while (my $file = <FIND>) {
my $contents = FileContents $file;

6
admin/coccinelle/window.cocci
View file

@ -106,9 +106,6 @@ Lisp_Object O;
- W->column_number_displayed
+ WVAR (W, column_number_displayed)
|
- W->redisplay_end_trigger
+ WVAR (W, redisplay_end_trigger)
|
- W->combination_limit
+ WVAR (W, combination_limit)
|
@ -225,9 +222,6 @@ Lisp_Object O;
- XWINDOW (O)->column_number_displayed
+ WVAR (XWINDOW (O), column_number_displayed)
|
- XWINDOW (O)->redisplay_end_trigger
+ WVAR (XWINDOW (O), redisplay_end_trigger)
|
- XWINDOW (O)->combination_limit
+ WVAR (XWINDOW (O), combination_limit)
|

5
admin/emake
View file

@ -20,7 +20,7 @@ if [ -f /proc/cpuinfo ]; then
sed 's/^[0-9]*/+/')))
fi
make -j$cores "$@" 2>&1 | \
make FAST=true -j$cores "$@" 2>&1 | \
sed -u 's# \.\./\.\./# #
s# \.\./# #
s#^Configuring local git # Configuring local git #
@ -29,6 +29,7 @@ s#^Running # Running #
s#^Configured for # Configured for #
s#^./temacs.*# \\& #
s#^make.*Error# \\& #
s#^Dumping under the name.*# \\& #
' | \
grep -E --line-buffered -v "^make|\
^Loading|\
@ -36,13 +37,13 @@ SCRAPE|\
INFO.*Scraping.*[.] ?\$|\
INFO.*Scraping.*done\$|\
GEN.*etc/DOC|\
GEN.*autoloads|\
^Waiting for git|\
^Finding pointers|\
^Using load-path|\
^Adding name|\
^Dump mode|\
^Dumping finger|\
^Dumping under the name|\
^Byte counts|\
^Reloc counts|\
^Pure-hashed|\

8
admin/gitmerge.el
View file

@ -124,7 +124,7 @@ If nil, the function `gitmerge-default-branch' guesses.")
(let ((coding-system-for-read vc-git-log-output-coding-system))
(call-process "git" nil t nil "show" (format "%s:configure.ac" branch)))
(goto-char (point-min)))
(re-search-forward "^AC_INIT([^,]+, \\([0-9]+\\)\\.")
(re-search-forward "^AC_INIT([^,]+, \\[?\\([0-9]+\\)\\.")
(string-to-number (match-string 1))))
(defun gitmerge-default-branch ()
@ -135,7 +135,7 @@ If nil, the function `gitmerge-default-branch' guesses.")
(defun gitmerge-get-sha1 ()
"Get SHA1 from commit at point."
(save-excursion
(goto-char (point-at-bol))
(goto-char (line-beginning-position))
(when (looking-at "^[A-Z ]\\s-*\\([a-f0-9]+\\)")
(match-string 1))))
@ -187,7 +187,7 @@ If nil, the function `gitmerge-default-branch' guesses.")
skip)
(when commit
(save-excursion
(goto-char (point-at-bol))
(goto-char (line-beginning-position))
(when (looking-at "^\\([A-Z ]\\)\\s-*\\([a-f0-9]+\\)")
(setq skip (string= (match-string 1) " "))
(goto-char (match-beginning 2))
@ -195,7 +195,7 @@ If nil, the function `gitmerge-default-branch' guesses.")
(dolist (ct gitmerge--commits)
(when (string-match commit (car ct))
(setcdr ct (when skip "M"))))
(goto-char (point-at-bol))
(goto-char (line-beginning-position))
(setq buffer-read-only nil)
(delete-char 1)
(insert (if skip "M" " "))

57
admin/make-tarball.txt
View file

@ -15,8 +15,8 @@ Steps to take before starting on the first pretest in any release sequence:
2. Consider increasing the value of the variable
'customize-changed-options-previous-release' in cus-edit.el to
refer to a newer version of Emacs. (This is now done when cutting
the release branch, see admin/release-branch.txt.)
Commit cus-edit.el if changed.
the release branch, see admin/release-branch.txt, but it can't
hurt to double check its value.) Commit cus-edit.el if changed.
3. Remove any old pretests from https://alpha.gnu.org/gnu/emacs/pretest.
You can use 'gnupload --delete' (see below for more gnupload details).
@ -24,8 +24,8 @@ Steps to take before starting on the first pretest in any release sequence:
General steps (for each step, check for possible errors):
1. git pull # fetch from the repository
git status # check for locally modified files
1. git pull # fetch from the repository
git status # check for locally modified files
Ensure that you have a clean, unmodified state.
If you switched in-place from another branch to the release branch,
@ -49,6 +49,9 @@ General steps (for each step, check for possible errors):
files will end up in the tarball. Otherwise, the *.eln files
might not build correctly on the user's system.
./autogen.sh
./configure --with-native-compilation && make
For a release (as opposed to pretest), delete any left-over "---"
and "+++" markers from etc/NEWS, as well as the "Temporary note"
section at the beginning of that file, and commit etc/NEWS if it
@ -158,13 +161,15 @@ General steps (for each step, check for possible errors):
5. Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the
files changed by M-x set-version. The easiest way of doing that
is "C-x v d ROOT-DIR RET", then go to the first modified file,
press 'M' to mark all modified files, and finally 'v' to commit
them. Make sure the commit log message mentions all the changes
in all modified files, as by default 'v' doesn't necessarily do
so.
Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the files
changed by M-x set-version. Note that the set-version changes
should be committed separately, as described in step 3 above.
The easiest way of doing that is "C-x v d ROOT-DIR RET", then go
to the first modified file, press 'M' to mark all modified files,
and finally 'v' to commit them. Make sure the commit log message
mentions all the changes in all modified files, as by default 'v'
doesn't necessarily do so.
If someone else made a commit between step 1 and now,
you need to repeat from step 4 onwards. (You can commit the files
@ -178,9 +183,10 @@ General steps (for each step, check for possible errors):
yourself, find it at <https://alpha.gnu.org/gnu/emacs/pretest>.
Releases are of course at <https://ftp.gnu.org/pub/gnu/emacs/>.
./admin/diff-tar-files emacs-OLD.tar.gz emacs-NEW.tar.gz
./admin/diff-tar-files emacs-OLD.tar emacs-NEW.tar
Alternatively:
Alternatively, if you want to use the compressed tarballs (which
diff-tar-files doesn't understand):
tar tJf emacs-OLD.tar.xz | sed -e 's,^[^/]*,,' | sort > old_tmp
tar tJf emacs-NEW.tar.xz | sed -e 's,^[^/]*,,' | sort > new_tmp
@ -198,7 +204,7 @@ General steps (for each step, check for possible errors):
The output of this command might be easier to compare to the
tarball than the one you get from find.
7. tar -xf emacs-NEW.tar; cd emacs-NEW
7. tar xf emacs-NEW.tar; cd emacs-NEW
./configure --prefix=/tmp/emacs && make check && make install
Use 'script' or M-x compile to save the compilation log in
@ -282,7 +288,8 @@ General steps (for each step, check for possible errors):
https://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or
https://ftp.gnu.org/gnu/emacs/ for a release.
Download them and check the signatures. Check they build.
Download them and check the signatures and SHA1/SHA256 checksums.
Check they build (./configure --with-native-compilation).
11. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
For a pretest, also bcc: platform-testers@gnu.org.
@ -300,12 +307,20 @@ General steps (for each step, check for possible errors):
To create the included SHA1 and SHA256 checksums, run:
sha1sum emacs-NEW.tar.xz
sha256sum emacs-NEW.tar.xz
sha1sum emacs-NEW.tar.xz
sha256sum emacs-NEW.tar.xz
You can optionally sign the announcement email, preferably using
the same PGP key that you used for signing the tarball.
(Use e.g. `M-x mml-secure-message-sign' in `message-mode' to sign
an email.)
12. After a release, update the Emacs pages as described below.
13. Bump the Emacs version on the release branch.
13. After a release, bump the Emacs version on the release branch.
There is no need to bump the version after a pretest; the version
is bumped before the next pretest or release instead.
If the released version was XX.Y, use 'set-version' from
admin/admin.el to bump the version on the release branch to
XX.Y.50. Commit the changes.
@ -313,8 +328,8 @@ General steps (for each step, check for possible errors):
UPDATING THE EMACS WEB PAGES AFTER A RELEASE
As soon as possible after a release, the Emacs web pages at
https://www.gnu.org/software/emacs/ should be updated. (See
admin/notes/www for general information.)
https://www.gnu.org/software/emacs/ should be updated.
(See admin/notes/www for general information.)
The pages to update are:
@ -330,7 +345,7 @@ looks like this:
<div class="release-banner">
<div class="container">
<h2><em>Emacs 27.1 is out</em>, download it <a href="download.html">here</a>!</h2>
<h2><em>Emacs 28.1 is out</em>, download it <a href="download.html">here</a>!</h2>
</div>
</div>

2
admin/merge-gnulib
View file

@ -51,7 +51,7 @@ GNULIB_MODULES='
'
AVOIDED_MODULES='
btowc close crypto/af_alg dup fchdir fstat langinfo lock
btowc chmod close crypto/af_alg dup fchdir fstat langinfo lock
mbrtowc mbsinit memchr mkdir msvc-inval msvc-nothrow nl_langinfo
openat-die opendir pthread-h raise
save-cwd select setenv sigprocmask stat stdarg stdbool

2
admin/notes/multi-tty
View file

@ -474,7 +474,7 @@ THINGS TO DO
definition.
Exceptions found so far: x-select-text and
x-selection-value (old name: x-cut-buffer-or-selection-value).
x-selection-value.
** Have a look at fatal_error_hook.

2
admin/notes/spelling
View file

@ -6,6 +6,6 @@ Re "behavior" vs "behaviour", etc.
for new text (code, docs), choose the US variant.
- It's probably (IMHO --ttn, 2017-10-13) not a high priority to
change existing text; use your best judgement (ask if unsure).
change existing text; use your best judgment (ask if unsure).
- https://lists.gnu.org/r/emacs-devel/2005-06/msg00489.html

2
admin/nt/dist-build/README-scripts
View file

@ -131,7 +131,7 @@ The process is the same as for building from the master branch, except
that the release branch should already exist as a worktree, and the
version number must be added to the command line with `build-zips.sh
-V 27 -s`. The final zips will be named after the branch rather than
the version (e.g emacs-27-2019-12-26.zip) rather than than the Emacs
the version (e.g emacs-27-2019-12-26.zip) rather than the Emacs
version (e.g emacs-27.0.50.zip).

2
admin/nt/dist-build/build-zips.sh
View file

@ -148,7 +148,7 @@ done
if [ -z $ACTUAL_VERSION ];
then
ACTUAL_VERSION=`
sed -n 's/^AC_INIT(GNU Emacs,[ ]*\([^ ,)]*\).*/\1/p' < ../../../configure.ac
sed -n 's/^AC_INIT(\[*GNU Emacs]*,[ ]*\[*\([^] ,)]*\).*/\1/p' < ../../../configure.ac
`
fi

4
admin/quick-install-emacs
View file

@ -172,10 +172,10 @@ test x"$prefix" = x && { prefix="`get_config_var prefix`" || exit 4 ; }
test x"$ARCH" = x && { ARCH="`get_config_var host`" || exit 4 ; }
VERSION=`
sed -n 's/^AC_INIT([ ]*emacs[ ]*,[ ]*\([^ ),]*\).*/\1/p' <$SRC/configure.ac
sed -n 's/^AC_INIT([ ]*\[*emacs]*[ ]*,[ ]*\[*\([^] ),]*\).*/\1/p' <$SRC/configure.ac
` || exit 4
test -n "$VERSION" || VERSION=`
sed -n 's/^AC_INIT([ ]*GNU Emacs[ ]*,[ ]*\([^ ),]*\).*/\1/p' <$SRC/configure.ac
sed -n 's/^AC_INIT([ ]*\[*GNU Emacs]*[ ]*,[ ]*\[*\([^] ),]*\).*/\1/p' <$SRC/configure.ac
` || exit 4
test -n "$VERSION" || { printf '%s\n' >&2 "$me: no version in configure.ac"; exit 4; }

11
admin/unidata/blocks.awk
View file

@ -224,9 +224,14 @@ FILENAME ~ "emoji-data.txt" && /^[0-9A-F].*; Emoji_Presentation / {
END {
idx = 0
# ## These are here so that font_range can choose Emoji presentation
# ## for the preceding codepoint when it encounters a VS
override_start[idx] = "FE00"
## This is here so that font_range can choose Emoji presentation
## for the preceding codepoint when it encounters a VS-16
## (U+FE0F). See also font_range and the comments in composite.el
## around the setup of `composition-function-table' for
## U+FE00..U+FE0E.
## It originally covered the whole FE00-FE0F range, but that
## turned out to be a mistake.
override_start[idx] = "FE0F"
override_end[idx] = "FE0F"
for (k in override_start)

4
admin/unidata/unidata-gen.el
View file

@ -1083,8 +1083,8 @@ Property value is a symbol `o' (Open), `c' (Close), or `n' (None)."
(defun unidata--ensure-compiled (&rest funcs)
(dolist (fun funcs)
(or (byte-code-function-p (symbol-function fun))
(byte-compile fun))))
(unless (compiled-function-p (symbol-function fun))
(byte-compile fun))))
(defun unidata-gen-table-name (prop index &rest _ignore)
(let* ((table (unidata-gen-table-word-list prop index 'unidata-split-name))

14
admin/update_autogen
View file

@ -4,7 +4,7 @@
## Copyright (C) 2011-2022 Free Software Foundation, Inc.
## Author: Glenn Morris <rgm@gnu.org>
## Maintainer: emacs-devel@gnu.org
## Maintainer: Stefan Kangas <stefankangas@gmail.com>
## This file is part of GNU Emacs.
@ -81,7 +81,6 @@ ldefs_flag=1
lboot_flag=
## Parameters.
ldefs_in=lisp/loaddefs.el
ldefs_out=lisp/ldefs-boot.el
sources="configure.ac lib/Makefile.am"
## Files to copy into autogendir.
@ -177,8 +176,6 @@ modified=$(status ${autogendir:+$sources} ${ldefs_flag:+lisp}) || die
echo "Running 'make maintainer-clean'..."
make maintainer-clean #|| die "Cleaning error"
rm -f $ldefs_in
}
@ -289,18 +286,13 @@ make -C src "$@" bootstrap-emacs || die "make src error"
echo "Running lisp/ make..."
make -C lisp "$@" autoloads EMACS=../src/bootstrap-emacs || die "make src error"
make -C lisp "$@" ldefs-boot.el EMACS=../src/bootstrap-emacs || die "make src error"
## Ignore comment differences.
[ ! "$lboot_flag" ] || \
diff -q -I '^;' $ldefs_in $ldefs_out || \
cp $ldefs_in $ldefs_out || die "cp ldefs_boot error"
# Refresh the prebuilt grammar-wy.el
grammar_in=lisp/cedet/semantic/grammar-wy.el
grammar_out=lisp/cedet/semantic/grm-wy-boot.el
make -C admin/grammars/ ../../$grammar_in
make -C admin/grammars/ ../../$grammar_in EMACS=../../src/bootstrap-emacs
cp $grammar_in $grammar_out || die "cp grm_wy_boot error"

2
autogen.sh
View file

@ -35,7 +35,7 @@
progs="autoconf"
## Minimum versions we need:
autoconf_min=`sed -n 's/^ *AC_PREREQ(\([0-9\.]*\)).*/\1/p' configure.ac`
autoconf_min=`sed -n 's/^ *AC_PREREQ(\[\([0-9\.]*\)]).*/\1/p' configure.ac`
## $1 = program, eg "autoconf".

9
build-aux/config.guess vendored
View file

@ -4,7 +4,7 @@
# shellcheck disable=SC2006,SC2268 # see below for rationale
timestamp='2022-05-08'
timestamp='2022-05-25'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
@ -1378,8 +1378,11 @@ EOF
BePC:Haiku:*:*) # Haiku running on Intel PC compatible.
GUESS=i586-pc-haiku
;;
x86_64:Haiku:*:*)
GUESS=x86_64-unknown-haiku
ppc:Haiku:*:*) # Haiku running on Apple PowerPC
GUESS=powerpc-apple-haiku
;;
*:Haiku:*:*) # Haiku modern gcc (not bound by BeOS compat)
GUESS=$UNAME_MACHINE-unknown-haiku
;;
SX-4:SUPER-UX:*:*)
GUESS=sx4-nec-superux$UNAME_RELEASE

6
build-aux/config.sub vendored
View file

@ -1,10 +1,10 @@
#! /bin/sh
# Configuration validation subroutine script.
# Copyright 1992-2021 Free Software Foundation, Inc.
# Copyright 1992-2022 Free Software Foundation, Inc.
# shellcheck disable=SC2006,SC2268 # see below for rationale
timestamp='2021-12-25'
timestamp='2022-01-03'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
@ -76,7 +76,7 @@ Report bugs and patches to <config-patches@gnu.org>."
version="\
GNU config.sub ($timestamp)
Copyright 1992-2021 Free Software Foundation, Inc.
Copyright 1992-2022 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."

1
config.bat
View file

@ -301,6 +301,7 @@ If Exist sys_time.in.h update sys_time.in.h sys_time.in-h
If Exist sys_types.in.h update sys_types.in.h sys_types.in-h
If Exist time.in.h update time.in.h time.in-h
If Exist unistd.in.h update unistd.in.h unistd.in-h
If Exist stdckdint.in.h update stdckdint.in.h stdckdint.in-h
If Exist gnulib.mk.in update gnulib.mk.in gnulib.mk-in
Rem Only repository has the msdos/autogen directory
If Exist Makefile.in sed -f ../msdos/sedlibcf.inp < Makefile.in > makefile.tmp

1545
configure.ac
View file

File diff suppressed because it is too large Load diff

2
doc/emacs/ChangeLog.1
View file

@ -8529,7 +8529,7 @@
* text.texi (Cell Justification):
* trouble.texi (After a Crash):
* xresources.texi (GTK styles):
Delete duplicate duplicate words.
Delete duplicate words.
2005-07-17 Richard M. Stallman <rms@gnu.org>

6
doc/emacs/abbrevs.texi
View file

@ -106,8 +106,10 @@ taken as the expansion. For example, to define the abbrev @samp{foo} as
mentioned above, insert the text @samp{find outer otter} and then type
@kbd{C-u 3 C-x a g f o o @key{RET}}.
An argument of zero to @kbd{C-x a g} means to use the contents of the
region as the expansion of the abbrev being defined.
If you're using @code{transient-mark-mode} (which is the default),
the active region will be used as the expansion of the abbrev being
defined. If not, an argument of zero to @kbd{C-x a g} means to use
the contents of the region.
@kindex C-x a l
@findex add-mode-abbrev

13
doc/emacs/buffers.texi
View file

@ -616,10 +616,11 @@ select it in another window (@code{clone-indirect-buffer-other-window}).
The text of the indirect buffer is always identical to the text of its
base buffer; changes made by editing either one are visible immediately
in the other. But in all other respects, the indirect buffer and its
in the other. ``Text'' here includes both the characters and their text
properties. But in all other respects, the indirect buffer and its
base buffer are completely separate. They can have different names,
different values of point, different narrowing, different markers,
different major modes, and different local variables.
different overlays, different major modes, and different local variables.
An indirect buffer cannot visit a file, but its base buffer can. If
you try to save the indirect buffer, that actually works by saving the
@ -649,6 +650,14 @@ both using the minibuffer.
When this hook runs, the newly created indirect buffer is the current
buffer.
Note: When a modification is made to the text of a buffer, the
modification hooks are run only in the base buffer, because most of
the functions on those hooks are not prepared to work correctly in
indirect buffers. So if you need a modification hook function in an
indirect buffer, you need to manually add that function to the hook
@emph{in the base buffer} and then make the function operate in the
desired indirect buffer.
@node Buffer Convenience
@section Convenience Features and Customization of Buffer Handling

8
doc/emacs/custom.texi
View file

@ -511,6 +511,9 @@ Set up a customization buffer for just one user option, @var{option}.
@item M-x customize-face @key{RET} @var{face} @key{RET}
Set up a customization buffer for just one face, @var{face}.
@item M-x customize-icon @key{RET} @var{face} @key{RET}
Set up a customization buffer for just one icon, @var{icon}.
@item M-x customize-group @key{RET} @var{group} @key{RET}
Set up a customization buffer for just one group, @var{group}.
@ -2300,6 +2303,8 @@ as a function from Lisp programs.
@cindex startup (init file)
@cindex XDG_CONFIG_HOME
@c When updating this, also update ``Setting up a customization file''
@c in efaq.texi.
When Emacs is started, it normally tries to load a Lisp program from
an @dfn{initialization file}, or @dfn{init file} for short. This
file, if it exists, specifies how to initialize Emacs for you.
@ -2449,6 +2454,9 @@ keys which send non-@acronym{ASCII} characters.
Write a single-quote (@code{'}) followed by the Lisp object you want.
@end table
For more information on the Emacs Lisp syntax, @pxref{Introduction,,,
elisp, The Emacs Lisp Reference Manual}.
@node Init Examples
@subsection Init File Examples

115
doc/emacs/dired.texi
View file

@ -41,6 +41,7 @@ you to operate on the listed files. @xref{Directories}.
* Operating on Files:: How to copy, rename, print, compress, etc.
either one file or several files.
* Shell Commands in Dired:: Running a shell command on the marked files.
* Shell Command Guessing:: Guessing shell commands for files.
* Transforming File Names:: Using patterns to rename multiple files.
* Comparison in Dired:: Running @code{diff} by way of Dired.
* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
@ -844,6 +845,26 @@ This is like @samp{ln -s}. The argument @var{new} is the directory to
make the links in, or (if making just one link) the name to give the
link.
@findex dired-do-relsymlink
@kindex Y @r{(Dired)}
@item Y @var{new} @key{RET}
Make relative symbolic links to the specified files
(@code{dired-do-relsymlink}). The argument @var{new} is the directory
to make the links in, or (if making just one link) the name to give
the link. This is like @code{dired-do-symlink} but creates relative
symbolic links. For example:
@example
foo -> ../bar/foo
@end example
@noindent
It does not create absolute ones like:
@example
foo -> /path/that/may/change/any/day/bar/foo
@end example
@findex dired-do-chmod
@kindex M @r{(Dired)}
@cindex changing file permissions (in Dired)
@ -963,6 +984,18 @@ Byte compile the specified Emacs Lisp files
(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte
Compilation, elisp, The Emacs Lisp Reference Manual}.
@findex dired-do-info
@kindex I @r{(Dired)}
@cindex running info on files (in Dired)
@item I
Run Info on this file (assumed to be a file in Info format).
@findex dired-do-man
@kindex N @r{(Dired)}
@cindex running man on files (in Dired)
@item N
Run man on this file (assumed to be a file in @code{nroff} format).
@kindex A @r{(Dired)}
@findex dired-do-find-regexp
@cindex search multiple files (in Dired)
@ -1089,6 +1122,73 @@ buffer (@pxref{Dired Updating}).
@xref{Single Shell}, for information about running shell commands
outside Dired.
@node Shell Command Guessing
@section Shell Command Guessing
@cindex guessing shell commands for files (in Dired)
Based upon the name of a file, Dired tries to guess what shell command
you might want to apply to it. For example, if you have point on a
file named @file{foo.tar} and you press @kbd{!}, Dired will guess that
you want to run @samp{tar xvf}, and suggest that as the default shell
command.
You can type @kbd{M-n} to get the default into the minibuffer for
editing. If there are several commands for a given file, type
@kbd{M-n} several times to see each matching command in order.
Dired only tries to guess a command for a single file, never for a
list of marked files.
@defvar dired-guess-shell-alist-default
This variable specifies the predefined rules for guessing shell
commands suitable for certain files. Set this to @code{nil} to turn
guessing off. The elements of @code{dired-guess-shell-alist-user}
(defined by the user) will override these rules.
@end defvar
@defvar dired-guess-shell-alist-user
If non-@code{nil}, this variable specifies the user-defined alist of
file regexps and their suggested commands. These rules take
precedence over the predefined rules in the variable
@code{dired-guess-shell-alist-default} when
@code{dired-do-shell-command} is run). The default is @code{nil}.
Each element of the alist looks like
@example
(@var{regexp} @var{command}@dots{})
@end example
@noindent
where each @var{command} can either be a string or a Lisp expression
that evaluates to a string. If several commands are given, all of
them will temporarily be pushed onto the history.
A @samp{*} in the shell command stands for the file name that matched
@var{regexp}. When Emacs invokes the @var{command}, it replaces each
instance of @samp{*} with the matched file name.
To add rules for @samp{.foo} and @samp{.bar} file extensions, add this
to your Init file:
@example
(setq dired-guess-shell-alist-user
(list
(list "\\.foo$" "@var{foo-command}") ; fixed rule
;; possibly more rules...
(list "\\.bar$" ; rule with condition test
'(if @var{condition}
"@var{bar-command-1}"
"@var{bar-command-2}"))))
@end example
@noindent
This will override any predefined rules for the same extensions.
@end defvar
You can find more user options with @kbd{M-x customize-group @key{RET}
dired-guess @key{RET}}.
@node Transforming File Names
@section Transforming File Names in Dired
@ -1138,9 +1238,12 @@ Rename each of the selected files to a lower-case name
@itemx % S @var{from} @key{RET} @var{to} @key{RET}
@kindex % S @r{(Dired)}
@findex dired-do-symlink-regexp
These four commands rename, copy, make hard links and make soft links,
in each case computing the new name by regular-expression substitution
from the name of the old file.
@itemx % Y @var{from} @key{RET} @var{to} @key{RET}
@kindex % Y @r{(Dired)}
@findex dired-do-relsymlink-regexp
These five commands rename, copy, make hard links, make soft links,
and make relative soft links, in each case computing the new name by
regular-expression substitution from the name of the old file.
@end table
The four regular-expression substitution commands effectively
@ -1298,6 +1401,12 @@ parent directory.
@kindex > @r{(Dired)}
@item >
Move down to the next directory-file line (@code{dired-next-dirline}).
@findex dired-goto-subdir
@kindex M-G @r{(Dired)}
@item M-G
Prompt for a directory and move to its directory-file line
(@code{dired-goto-subdir}).
@end table
@node Hiding Subdirectories

97
doc/emacs/display.texi
View file

@ -24,6 +24,7 @@ the text is displayed.
* Faces:: How to change the display style using faces.
* Colors:: Specifying colors for faces.
* Standard Faces:: The main predefined faces.
* Icons:: How to change how icons look.
* Text Scale:: Increasing or decreasing text size in a buffer.
* Font Lock:: Minor mode for syntactic highlighting using faces.
* Highlight Interactively:: Tell Emacs what text to highlight.
@ -851,10 +852,44 @@ This face is used to display on text-mode terminals the menu item that
would be selected if you click a mouse or press @key{RET}.
@end table
@node Icons
@section Icons
@cindex icons, on clickable buttons
Emacs sometimes displays clickable buttons (or other informative
icons), and you can customize how these look on display.
@vindex icon-preference
The main customization point here is the @code{icon-preference} user
option. By using this, you can tell Emacs your overall preferences
for icons. This is a list of icon types, and the first icon type
that's supported will be used. The supported types are:
@table @code
@item image
Use an image for the icon.
@item emoji
Use a colorful emoji for the icon.
@item symbol
Use a monochrome symbol for the icon.
@item text
Use a simple text for the icon.
@end table
In addition, each individual icon can be customized with @kbd{M-x
customize-icon}, and themes can further alter the looks of the icons.
To get a quick description of an icon, use the @kbd{M-x describe-icon}
command.
@node Text Scale
@section Text Scale
@cindex adjust buffer face height
@cindex adjust buffer font size
@cindex font size of @code{default} face, increase or decrease
@findex text-scale-adjust
@kindex C-x C-+
@kindex C-x C--
@ -862,17 +897,27 @@ would be selected if you click a mouse or press @key{RET}.
@kindex C-x C-0
@kindex C-wheel-down
@kindex C-wheel-up
To increase the height of the default face in the current buffer,
type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x
C--}. To restore the default (global) face height, type @kbd{C-x
C-0}. These keys are all bound to the same command,
To increase the font size of the @code{default} face in the current
buffer, type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type
@kbd{C-x C--}. To restore the default (global) font size, type
@kbd{C-x C-0}. These keys are all bound to the same command,
@code{text-scale-adjust}, which looks at the last key typed to
determine which action to take.
determine which action to take and adjusts the font size accordingly
by changing the height of the default face.
Most faces don't have an explicit setting of the @code{:height}
attribute, and thus inherit the height from the @code{default} face.
Those faces are also scaled by the above commands.
Faces other than @code{default} that have an explicit setting of the
@code{:height} attribute are not affected by these font size changes.
The @code{header-line} face is an exception: it will be scaled even if
it has an explicit setting of the @code{:height} attribute.
Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier
pressed, when the mouse pointer is above buffer text, will increase or
decrease the height of the default face, depending on the direction of
the scrolling.
decrease the font size of the affected faces, depending on the
direction of the scrolling.
The final key of these commands may be repeated without the leading
@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face
@ -882,21 +927,37 @@ of 1.2; to change this factor, customize the variable
to the @code{text-scale-adjust} command restores the default height,
the same as typing @kbd{C-x C-0}.
@cindex increase buffer face height
@cindex adjust global font size
@findex global-text-scale-adjust
@vindex global-text-scale-adjust-resizes-frames
@kindex C-x C-M-+
@kindex C-x C-M-=
@kindex C-x C-M--
@kindex C-x C-M-0
@kindex C-M-wheel-down
@kindex C-M-wheel-up
Similarly, to change the sizes of the fonts globally, type @kbd{C-x
C-M-+}, @kbd{C-x C-M-=}, @kbd{C-x C-M--} or @kbd{C-x C-M-0}, or scroll
the mouse wheel with both the @kbd{Ctrl} and @kbd{Meta} modifiers
pressed. To enable frame resizing when the font size is changed
globally, customize the variable
@code{global-text-scale-adjust-resizes-frames} (@pxref{Easy
Customization}).
@cindex increase buffer font size
@findex text-scale-increase
@cindex decrease buffer face height
@cindex decrease buffer font size
@findex text-scale-decrease
The commands @code{text-scale-increase} and
@code{text-scale-decrease} increase or decrease the height of the
default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively.
You may find it convenient to bind to these commands, rather than
@code{text-scale-adjust}.
@code{text-scale-decrease} increase or decrease the size of the font
in the current buffer, just like @kbd{C-x C-+} and @kbd{C-x C--}
respectively. You may find it convenient to bind to these commands,
rather than @code{text-scale-adjust}.
@cindex set buffer face height
@cindex set buffer font size
@findex text-scale-set
The command @code{text-scale-set} scales the height of the default
face in the current buffer to an absolute level specified by its
prefix argument.
The command @code{text-scale-set} scales the size of the font in the
current buffer to an absolute level specified by its prefix argument.
@findex text-scale-mode
The above commands automatically enable the minor mode

3
doc/emacs/emacs.texi
View file

@ -1183,7 +1183,6 @@ The Emacs Initialization File
Dealing with Emacs Trouble
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
* Stuck Recursive:: '[...]' in mode line around the parentheses.
* Screen Garbled:: Garbage on the screen.
* Text Garbled:: Garbage in the text.
@ -1191,7 +1190,7 @@ Dealing with Emacs Trouble
* Crashing:: What Emacs does when it crashes.
* After a Crash:: Recovering editing in an Emacs session that crashed.
* Emergency Escape:: What to do if Emacs stops responding.
* Long Lines:: Mitigating slowness due to extremely long lines.
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
Reporting Bugs

61
doc/emacs/files.texi
View file

@ -420,6 +420,9 @@ With prefix argument (@kbd{C-u}), mark the current buffer as changed.
Save the current buffer with a specified file name (@code{write-file}).
@item M-x set-visited-file-name
Change the file name under which the current buffer will be saved.
@item M-x rename-visited-file
The same as @kbd{M-x set-visited-file-name}, but also rename the file
the buffer is visiting (if any).
@end table
@kindex C-x C-s
@ -652,10 +655,10 @@ Never make numbered backups; always make single backups.
The usual way to set this variable is globally, through your init file
or the customization buffer. However, you can set
@code{version-control} locally in an individual buffer to control the
making of backups for that buffer's file (@pxref{Locals}). You can
have Emacs set @code{version-control} locally whenever you visit a
given file (@pxref{File Variables}). Some modes, such as Rmail mode,
set this variable.
making of backups for that buffer's file (@pxref{Locals}). Some
modes, such as Rmail mode, set this variable. You can also have Emacs
set @code{version-control} locally whenever you visit a given file
(@pxref{File Variables}).
@cindex @env{VERSION_CONTROL} environment variable
If you set the environment variable @env{VERSION_CONTROL}, to tell
@ -2222,13 +2225,16 @@ recently-opened files, reading file names from a buffer.
@findex recentf-mode
@vindex recentf-mode
@findex recentf-open
@findex recentf-save-list
@findex recentf-edit-list
If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
@samp{File} menu includes a submenu containing a list of recently
opened files. @kbd{M-x recentf-save-list} saves the current
@code{recentf-list} to a file, and @kbd{M-x recentf-edit-list} edits
it.
If you enable Recentf mode, with @kbd{M-x recentf-mode}, Emacs
maintains a list of recently opened files. To open a file from this
list, use the @kbd{M-x recentf-open} command. When this mode is
enabled, the @samp{File} menu will include a submenu that you can use
to visit one of these files. @kbd{M-x recentf-save-list} saves the
current @code{recentf-list} to a file, and @kbd{M-x recentf-edit-list}
edits it.
@c FIXME partial-completion-mode (complete.el) is obsolete.
The @kbd{M-x ffap} command generalizes @code{find-file} with more
@ -2267,12 +2273,14 @@ behavior by using the options @code{image-auto-resize} and
@findex image-transform-set-scale
@findex image-transform-reset
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 specifying a scale factor, use the command
@code{image-transform-set-scale} bound to @kbd{s s}.
To reset all transformations to the initial state, use
@code{image-transform-reset} bound to @kbd{s 0}.
@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
percentage of its original size, use the command
@code{image-transform-set-percent} bound to @kbd{s p}. To scale
the image specifying a scale factor, use the command
@code{image-transform-set-scale} bound to @kbd{s s}. To reset all
transformations to the initial state, use @code{image-transform-reset}
bound to @kbd{s 0}.
@findex image-next-file
@findex image-previous-file
@ -2349,6 +2357,29 @@ can be used to transform the image in question to @acronym{PNG} before
displaying. GraphicsMagick, ImageMagick and @command{ffmpeg} are
currently supported for image conversions.
@findex image-converter-add-handler
In addition, you may wish to add special handlers for certain image
formats. These can be added with the
@code{image-converter-add-handler} function. For instance, to allow
viewing Krita files as simple images, you could say something like:
@lisp
(image-converter-add-handler
"kra"
(lambda (file data-p)
(if data-p
(error "Can't decode non-files")
(call-process "unzip" nil t nil
"-qq" "-c" "-x" file "mergedimage.png"))))
@end lisp
The function takes two parameters, where the first is a file name
suffix, and the second is a function to do the ``conversion''. This
function takes two parameters, where the first is the file name or a
string with the data, and the second says whether the first parameter
is data or not, and should output an image in
@code{image-convert-to-format} format in the current buffer.
@findex thumbs-mode
@cindex mode, Thumbs
The Image-Dired package can also be used to view images as

11
doc/emacs/frames.texi
View file

@ -223,8 +223,8 @@ mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and
buffers are scrolled. The variable
@code{mouse-wheel-progressive-speed} determines whether the scroll
speed is linked to how fast you move the wheel. This mode also
supports increasing or decreasing the height of the default face, by
default bound to scrolling with the @key{Ctrl} modifier.
supports increasing or decreasing the font size, by default bound to
scrolling with the @key{Ctrl} modifier.
@vindex mouse-wheel-scroll-amount-horizontal
Emacs also supports horizontal scrolling with the @key{Shift}
@ -1249,6 +1249,13 @@ To drag text from Emacs to other programs, set the option
@code{mouse-drag-and-drop-region-cross-program} to a non-@code{nil}
value.
On the X window system, some programs can drop files on Emacs,
expecting Emacs to save them. Normally, Emacs will prompt for a file
name under which the file will be saved, and then open the file, but
that behavior can be changed by changing the variable
@code{x-dnd-direct-save-function}. @xref{Drag and Drop,,, elisp, The
Emacs Lisp Reference Manual}.
@node Menu Bars
@section Menu Bars
@cindex menu bar mode

5
doc/emacs/glossary.texi
View file

@ -182,6 +182,7 @@ corresponding Control character. @xref{User Input,C-M-}.
Case conversion means changing text from upper case to lower case or
vice versa. @xref{Case}.
@cindex ignore case
@item Case Folding
Case folding means ignoring the differences between case variants of
the same letter: upper-case, lower-case, and title-case. Emacs
@ -1456,8 +1457,8 @@ level by aborting (q.v.@:) and quitting (q.v.). @xref{Quitting}.
@item Transient Mark Mode
The default behavior of the mark (q.v.@:) and region (q.v.), in which
setting the mark activates it and highlights the region, is called
Transient Mark mode. In GNU Emacs 23 and onwards, it is enabled by
default. @xref{Disabled Transient Mark}.
Transient Mark mode. It is enabled by default. @xref{Disabled
Transient Mark}.
@item Transposition
Transposing two units of text means putting each one into the place

5
doc/emacs/help.texi
View file

@ -542,6 +542,11 @@ previous hyperlink. These commands act cyclically; for instance,
typing @key{TAB} at the last hyperlink moves back to the first
hyperlink.
@vindex help-clean-buttons
By default, many links in the help buffer are displayed surrounded
by quote characters. If the @code{help-clean-buttons} user option is
non-@code{nil}, these quote characters are removed from the buffer.
@kindex n @r{(Help mode)}
@kindex p @r{(Help mode)}
@findex help-goto-next-page

23
doc/emacs/killing.texi
View file

@ -610,14 +610,14 @@ yanks the contents of the clipboard at point.
@cindex primary selection
@cindex selection, primary
Under the X Window System, there exists a @dfn{primary selection}
containing the last stretch of text selected in an X application
(usually by dragging the mouse). Typically, this text can be inserted
into other X applications by @kbd{mouse-2} clicks. The primary
selection is separate from the clipboard. Its contents are more
fragile; they are overwritten each time you select text with the
mouse, whereas the clipboard is only overwritten by explicit cut
or copy commands.
Under the X Window System, PGTK and Haiku, there exists a
@dfn{primary selection} containing the last stretch of text selected
in an X application (usually by dragging the mouse). Typically, this
text can be inserted into other X applications by @kbd{mouse-2}
clicks. The primary selection is separate from the clipboard. Its
contents are more fragile; they are overwritten each time you select
text with the mouse, whereas the clipboard is only overwritten by
explicit cut or copy commands.
Under X, whenever the region is active (@pxref{Mark}), the text in
the region is saved in the primary selection. This applies regardless
@ -639,6 +639,13 @@ regions to the primary selection entirely.
(@kbd{C-y}) to insert this text if @code{select-enable-primary} is set
(@pxref{Clipboard}).
@cindex lost-selection-mode
By default, Emacs keeps the region active even after text is
selected in another program; this is contrary to typical X behavior.
To make Emacs deactivate the region after another program places data
in the primary selection, enable the global minor mode
@code{lost-selection-mode}.
@cindex MS-Windows, and primary selection
MS-Windows provides no primary selection, but Emacs emulates it
within a single Emacs session by storing the selected text internally.

4
doc/emacs/maintaining.texi
View file

@ -2222,8 +2222,8 @@ where you were with @kbd{M-,}.
@kindex C-M-,
@findex xref-go-forward
Go forward to a place from where you previously went back using @kbd{M-,}.
This is useful if you find that you went back too far.
If you previously went back too far with @kbd{M-,}, @kbd{C-M-,}
(@code{xref-go-forward}) can be used to go forward again.
@findex xref-etags-mode
Some major modes install @code{xref} support facilities that might

11
doc/emacs/mini.texi
View file

@ -734,11 +734,14 @@ highlighting. This feature uses the special text property
@section Minibuffer History
@cindex minibuffer history
@cindex history of minibuffer input
@cindex completion, walking through candidates
Every argument that you enter with the minibuffer is saved in a
@dfn{minibuffer history list} so you can easily use it again later.
You can use the following arguments to quickly fetch an earlier
argument into the minibuffer:
Everything you type in the minibuffer is saved in a @dfn{minibuffer
history list} so you can easily use it again later. This includes
completion candidates (such as file names, buffer names, command
names, etc.@:) and any other kind of minibuffer input. You can use
the following commands to quickly fetch an earlier or alternative
response into the minibuffer:
@table @kbd
@item M-p

102
doc/emacs/misc.texi
View file

@ -1,6 +1,5 @@
@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2022 Free Software
@c Foundation, Inc.
@c Copyright (C) 1985--2022 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands
@ -1643,11 +1642,11 @@ interface is similar to the @code{more} program.
@cindex remote host
@cindex connecting to remote host
@cindex Telnet
@cindex Rlogin
@cindex SSH
You can login to a remote computer, using whatever commands you
would from a regular terminal (e.g., using the @command{ssh} or
@command{telnet} or @code{rlogin} commands), from a Term window.
would from a regular terminal (e.g., the @command{ssh} command), from
a Term window.
A program that asks you for a password will normally suppress
echoing of the password, so the password will not show up in the
@ -2870,99 +2869,6 @@ new major mode which provides a command to switch back. These
approaches give you more flexibility to go back to unfinished tasks in
the order you choose.
@ignore
@c Apart from edt and viper, this is all obsolete.
@c (Can't believe we were saying "most other editors" into 2014!)
@c There seems no point having a node just for those, which both have
@c their own manuals.
@node Emulation
@section Emulation
@cindex emulating other editors
@cindex other editors
@cindex EDT
@cindex vi
@cindex WordStar
GNU Emacs can be programmed to emulate (more or less) most other
editors. Standard facilities can emulate these:
@table @asis
@item CRiSP/Brief (PC editor)
@findex crisp-mode
@vindex crisp-override-meta-x
@findex scroll-all-mode
@cindex CRiSP mode
@cindex Brief emulation
@cindex emulation of Brief
@cindex mode, CRiSP
@kbd{M-x crisp-mode} enables key bindings to emulate the CRiSP/Brief
editor. Note that this rebinds @kbd{M-x} to exit Emacs unless you set
the variable @code{crisp-override-meta-x}. You can also use the
command @kbd{M-x scroll-all-mode} or set the variable
@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature
(scrolling all windows together).
@item EDT (DEC VMS editor)
@findex edt-emulation-on
@findex edt-emulation-off
Turn on EDT emulation with @kbd{M-x edt-emulation-on}; restore normal
command bindings with @kbd{M-x edt-emulation-off}.
Most of the EDT emulation commands are keypad keys, and most standard
Emacs key bindings are still available. The EDT emulation rebindings
are done in the global keymap, so there is no problem switching
buffers or major modes while in EDT emulation.
@item TPU (DEC VMS editor)
@findex tpu-edt-on
@cindex TPU
@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT.
@item vi (Berkeley editor)
@findex viper-mode
Viper is an emulator for vi. It implements several levels of
emulation; level 1 is closest to vi itself, while level 5 departs
somewhat from strict emulation to take advantage of the capabilities of
Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you
the rest of the way and ask for the emulation level. @inforef{Top,
Viper, viper}.
@item vi (another emulator)
@findex vi-mode
@kbd{M-x vi-mode} enters a major mode that replaces the previously
established major mode. All of the vi commands that, in real vi, enter
input mode are programmed instead to return to the previous major
mode. Thus, ordinary Emacs serves as vi's input mode.
Because vi emulation works through major modes, it does not work
to switch buffers during emulation. Return to normal Emacs first.
If you plan to use vi emulation much, you probably want to bind a key
to the @code{vi-mode} command.
@item vi (alternate emulator)
@findex vip-mode
@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi
more thoroughly than @kbd{M-x vi-mode}. Input mode in this emulator
is changed from ordinary Emacs so you can use @key{ESC} to go back to
emulated vi command mode. To get from emulated vi command mode back to
ordinary Emacs, type @kbd{C-z}.
This emulation does not work through major modes, and it is possible
to switch buffers in various ways within the emulator. It is not
so necessary to assign a key to the command @code{vip-mode} as
it is with @code{vi-mode} because terminating insert mode does
not use it.
@inforef{Top, VIP, vip}, for full information.
@item WordStar (old wordprocessor)
@findex wordstar-mode
@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
key bindings.
@end table
@end ignore
@node Hyperlinking
@section Hyperlinking and Web Navigation Features

6
doc/emacs/msdos.texi
View file

@ -986,9 +986,9 @@ printer, put this in your @file{.emacs} file:
@section Specifying Fonts on MS-Windows
@cindex font specification (MS Windows)
Starting with Emacs 23, fonts are specified by their name, size
and optional properties. The format for specifying fonts comes from the
fontconfig library used in modern Free desktops:
Fonts are specified by their name, size and optional properties.
The format for specifying fonts comes from the fontconfig library used
in modern Free desktops:
@example
[Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]]

10
doc/emacs/package.texi
View file

@ -483,6 +483,16 @@ The default value is just @code{'(all)}.
installed will be ignored. The @samp{muse} package will be listed in
the package menu with the @samp{held} status.
@findex package-recompile
@findex package-recompile-all
Emacs byte code is quite stable, but it's possible for byte code to
become outdated, or for the compiled files to rely on macros that have
changed in new versions of Emacs. You can use the command @w{@kbd{M-x
package-recompile}} to recompile a particular package, or
@w{@kbd{M-x package-recompile-all}} to recompile all the packages. (The
latter command might take quite a while to run if you have many
installed packages.)
@node Package Files
@section Package Files and Directory Layout
@cindex package directory

17
doc/emacs/search.texi
View file

@ -228,8 +228,9 @@ customizing the @code{isearch-wrap-pause} user option. If it is
@code{t} (the default), signal an error. (Repeating the search will
wrap around.) If @code{no}, issue a @code{ding} and wrap immediately
after reaching the last match. If @code{no-ding}, wrap immediately,
but don't @code{ding}. Finally, if @code{nil}, never wrap, but just
stop at the last match.
but don't @code{ding}. With the values @code{no} and @code{no-ding}
the search will try to wrap around also on typing a character.
Finally, if @code{nil}, never wrap, but just stop at the last match.
@cindex search ring
@findex isearch-ring-advance
@ -1428,16 +1429,18 @@ of its accented cousins like @code{@"a} and @code{@'a}, i.e., the
match disregards the diacritics that distinguish these
variants. In addition, @code{a} matches other characters that
resemble it, or have it as part of their graphical representation,
such as U+249C @sc{parenthesized latin small letter a} and U+2100
@sc{account of} (which looks like a small @code{a} over @code{c}).
such as U+00AA @sc{feminine ordinal indicator} and U+24D0
@sc{circled latin small letter a} (which looks like a small @code{a}
inside a circle).
Similarly, the @acronym{ASCII} double-quote character @code{"} matches
all the other variants of double quotes defined by the Unicode
standard. Finally, character folding can make a sequence of one or
more characters match another sequence of a different length: for
example, the sequence of two characters @code{ff} matches U+FB00
@sc{latin small ligature ff}. Character sequences that are not identical,
but match under character folding are known as @dfn{equivalent
character sequences}.
@sc{latin small ligature ff} and the sequence @code{(a)} matches
U+249C @sc{parenthesized latin small letter a}. Character sequences
that are not identical, but match under character folding are known as
@dfn{equivalent character sequences}.
@kindex M-s ' @r{(Incremental Search)}
@findex isearch-toggle-char-fold

142
doc/emacs/trouble.texi
View file

@ -151,7 +151,6 @@ garbled displays, running out of memory, and crashes and hangs.
Emacs.
@menu
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
* Stuck Recursive:: '[...]' in mode line around the parentheses.
* Screen Garbled:: Garbage on the screen.
* Text Garbled:: Garbage in the text.
@ -159,66 +158,9 @@ Emacs.
* Crashing:: What Emacs does when it crashes.
* After a Crash:: Recovering editing in an Emacs session that crashed.
* Emergency Escape:: What to do if Emacs stops responding.
* Long Lines:: Mitigating slowness due to extremely long lines.
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
@end menu
@node DEL Does Not Delete
@subsection If @key{DEL} Fails to Delete
@cindex @key{DEL} vs @key{BACKSPACE}
@cindex @key{BACKSPACE} vs @key{DEL}
@cindex @key{DEL} does not delete
Every keyboard has a large key, usually labeled @key{BACKSPACE},
which is ordinarily used to erase the last character that you typed.
In Emacs, this key is supposed to be equivalent to @key{DEL}.
When Emacs starts up on a graphical display, it determines
automatically which key should be @key{DEL}. In some unusual cases,
Emacs gets the wrong information from the system, and @key{BACKSPACE}
ends up deleting forwards instead of backwards.
Some keyboards also have a @key{Delete} key, which is ordinarily
used to delete forwards. If this key deletes backward in Emacs, that
too suggests Emacs got the wrong information---but in the opposite
sense.
On a text terminal, if you find that @key{BACKSPACE} prompts for a
Help command, like @kbd{Control-h}, instead of deleting a character,
it means that key is actually sending the @samp{BS} character. Emacs
ought to be treating @key{BS} as @key{DEL}, but it isn't.
@findex normal-erase-is-backspace-mode
In all of those cases, the immediate remedy is the same: use the
command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
between the two modes that Emacs supports for handling @key{DEL}, so
if Emacs starts in the wrong mode, this should switch to the right
mode. On a text terminal, if you want to ask for help when @key{BS}
is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?}
may also work, if it sends character code 127.
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
first case above, where @key{BACKSPACE} deletes forwards instead of
backwards, use this line to make @key{BACKSPACE} act as @key{DEL}:
@lisp
(normal-erase-is-backspace-mode 0)
@end lisp
@noindent
For the other two cases, use this line:
@lisp
(normal-erase-is-backspace-mode 1)
@end lisp
@vindex normal-erase-is-backspace
Another way to fix the problem for every Emacs session is to
customize the variable @code{normal-erase-is-backspace}: the value
@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy
Customization}.
@node Stuck Recursive
@subsection Recursive Editing Levels
@cindex stuck in recursive editing
@ -490,40 +432,62 @@ program.
emergency escape---but there are cases where it won't work, when a
system call hangs or when Emacs is stuck in a tight loop in C code.
@node Long Lines
@subsection Long Lines
@cindex long lines
@node DEL Does Not Delete
@subsection If @key{DEL} Fails to Delete
@cindex @key{DEL} vs @key{BACKSPACE}
@cindex @key{BACKSPACE} vs @key{DEL}
@cindex @key{DEL} does not delete
For a variety of reasons (some of which are fundamental to the Emacs
redisplay code and the complex range of possibilities it handles;
others of which are due to modes and features which do not scale well
in unusual circumstances), Emacs can perform poorly when extremely
long lines are present (where ``extremely long'' usually means at
least many thousands of characters).
Every keyboard has a large key, usually labeled @key{BACKSPACE},
which is ordinarily used to erase the last character that you typed.
In Emacs, this key is supposed to be equivalent to @key{DEL}.
@cindex @code{so-long} mode
@findex global-so-long-mode
@vindex so-long-action
A particular problem is that Emacs may ``hang'' for a long time at
the point of visiting a file with extremely long lines. This can be
mitigated by enabling the @file{so-long} library, which detects when a
visited file contains abnormally long lines, and takes steps to
disable features which are liable to cause slowness in that situation.
To enable this library, type @kbd{M-x global-so-long-mode @key{RET}},
or turn on the @code{global-so-long-mode} in your init file
(@pxref{Init File}), or customize the @code{global-so-long-mode}
option. You can tailor this mode's operation by customizing the
variable @code{so-long-action}.
When Emacs starts up on a graphical display, it determines
automatically which key should be @key{DEL}. In some unusual cases,
Emacs gets the wrong information from the system, and @key{BACKSPACE}
ends up deleting forwards instead of backwards.
The @file{so-long} library can also significantly improve
performance when moving and editing in a buffer with long lines.
Performance is still likely to degrade as you get deeper into the long
lines, but the improvements from using this library can nevertheless
be substantial.
Some keyboards also have a @key{Delete} key, which is ordinarily
used to delete forwards. If this key deletes backward in Emacs, that
too suggests Emacs got the wrong information---but in the opposite
sense.
@findex so-long-commentary
Use @kbd{M-x so-long-commentary} to view the documentation for this
library and learn more about how to enable and configure it.
On a text terminal, if you find that @key{BACKSPACE} prompts for a
Help command, like @kbd{Control-h}, instead of deleting a character,
it means that key is actually sending the @samp{BS} character. Emacs
ought to be treating @key{BS} as @key{DEL}, but it isn't.
@findex normal-erase-is-backspace-mode
In all of those cases, the immediate remedy is the same: use the
command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
between the two modes that Emacs supports for handling @key{DEL}, so
if Emacs starts in the wrong mode, this should switch to the right
mode. On a text terminal, if you want to ask for help when @key{BS}
is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?}
may also work, if it sends character code 127.
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
first case above, where @key{BACKSPACE} deletes forwards instead of
backwards, use this line to make @key{BACKSPACE} act as @key{DEL}:
@lisp
(normal-erase-is-backspace-mode 0)
@end lisp
@noindent
For the other two cases, use this line:
@lisp
(normal-erase-is-backspace-mode 1)
@end lisp
@vindex normal-erase-is-backspace
Another way to fix the problem for every Emacs session is to
customize the variable @code{normal-erase-is-backspace}: the value
@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy
Customization}.
@node Bugs
@section Reporting Bugs

10
doc/emacs/xresources.texi
View file

@ -382,7 +382,9 @@ which prevents blank areas of a frame that have not yet been painted
from being displayed. If set to @samp{extended}, it will enable use
of an alternative frame synchronization protocol, which might be
supported by some compositing window managers that don't support the
protocol Emacs uses by default.
protocol Emacs uses by default, and causes Emacs to synchronize
display with the monitor refresh rate when a compatible compositing
window manager is in use.
@item @code{verticalScrollBars} (class @code{ScrollBars})
Give frames scroll bars on the left if @samp{left}, on the right if
@ -449,6 +451,12 @@ Foreground color for a selected item.
Foreground color.
@item disabledForeground
Foreground color for a disabled menu item.
@item highlightForeground
Foreground color for a menu item highlighted by the mouse or key
navigation.
@item highlightBackground
Background color for a menu item highlighted by the mouse or key
navigation.
@ifnottex
@item horizontalSpacing
Horizontal spacing in pixels between items. Default is 3.

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

@ -2020,7 +2020,6 @@ the arguments to the function @code{concat} are the strings
@w{@code{"The "}} and @w{@code{" red foxes."}} and the list
@code{(number-to-string (+ 2 fill-column))}.
@c For GNU Emacs 22, need number-to-string
@smallexample
(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
@end smallexample
@ -10297,9 +10296,8 @@ loop with a list.
@cindex @file{*scratch*} buffer
The function requires several lines for its output. If you are
reading this in a recent instance of GNU Emacs,
@c GNU Emacs 21, GNU Emacs 22, or a later version,
you can evaluate the following expression inside of Info, as usual.
reading this in a recent instance of GNU Emacs, you can evaluate the
following expression inside of Info, as usual.
If you are using an earlier version of Emacs, you need to copy the
necessary expressions to your @file{*scratch*} buffer and evaluate
@ -15134,16 +15132,16 @@ Emacs may produce different results.)
@end group
@group
(lengths-list-file "./lisp/makesum.el")
@result{} (85 181)
(lengths-list-file "./lisp/hex-util.el")
@result{} (82 71)
@end group
@group
(recursive-lengths-list-many-files
'("./lisp/macros.el"
"./lisp/mail/mailalias.el"
"./lisp/makesum.el"))
@result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
"./lisp/hex-util.el"))
@result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 82 71)
@end group
@end smallexample
@ -15235,27 +15233,13 @@ Sorting the list returned by the
@code{recursive-lengths-list-many-files} function is straightforward;
it uses the @code{<} function:
@ignore
2006 Oct 29
In GNU Emacs 22, eval
(progn
(cd "/usr/local/share/emacs/22.0.50/")
(sort
(recursive-lengths-list-many-files
'("./lisp/macros.el"
"./lisp/mail/mailalias.el"
"./lisp/makesum.el"))
'<))
@end ignore
@smallexample
@group
(sort
(recursive-lengths-list-many-files
'("./lisp/macros.el"
"./lisp/mailalias.el"
"./lisp/makesum.el"))
"./lisp/hex-util.el"))
'<)
@end group
@end smallexample
@ -15265,7 +15249,7 @@ In GNU Emacs 22, eval
which produces:
@smallexample
(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
(29 32 38 71 82 90 95 178 180 218 263 283 321 324 480)
@end smallexample
@noindent
@ -15313,7 +15297,7 @@ as a list that looks like this (but with more elements):
@group
("./lisp/macros.el"
"./lisp/mail/rmail.el"
"./lisp/makesum.el")
"./lisp/hex-util.el")
@end group
@end smallexample
@ -17711,17 +17695,6 @@ or start GNU Emacs with the command @code{emacs -nbc}.
(setq grep-command "grep -i -nH -e ")
@end smallexample
@ignore
@c Evidently, no longer needed in GNU Emacs 22
item Automatically uncompress compressed files when visiting them
smallexample
(load "uncompress")
end smallexample
@end ignore
@item Find an existing buffer, even if it has a different name@*
This avoids problems with symbolic links.

14
doc/lispref/buffers.texi
View file

@ -981,14 +981,22 @@ of
Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with
the same buffer and @code{arg}.
@item or
Satisfied if @var{oper} is a list and @emph{any} condition if
Satisfied if @var{expr} is a list and @emph{any} condition in
@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
@code{arg}.
@item and
Satisfied if @var{oper} is a list and @emph{all} condition if
@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
Satisfied if @var{expr} is a list and @emph{all} conditions in
@var{expr} satisfy @code{buffer-match-p}, with the same buffer and
@code{arg}.
@item derived-mode
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.
@end table
@item t
Satisfied by any buffer. A convenient alternative to @code{""} (empty
string), @code{(and)} (empty conjunction) or @code{always}.
@end itemize
@end defun

37
doc/lispref/commands.texi
View file

@ -443,9 +443,9 @@ specification. If the key sequence that invoked the command has
and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
@item f
A file name of an existing file (@pxref{File Names}). The default
directory is @code{default-directory}. Existing, Completion, Default,
Prompt.
A file name of an existing file (@pxref{File Names}). @xref{Reading
File Names}, for details about default values. Existing, Completion,
Default, Prompt.
@item F
A file name. The file need not exist. Completion, Default, Prompt.
@ -897,6 +897,10 @@ keymaps. This command is the normal definition of @kbd{M-S-x}
(that's ``meta shift x'').
@end deffn
Both these commands prompt for a command name, but with different
completion rules. You can toggle between these two modes by using the
@kbd{M-S-x} command while being prompted.
@node Distinguish Interactive
@section Distinguish Interactive Calls
@cindex distinguish interactive calls
@ -2074,7 +2078,7 @@ and @var{kind} as arguments.
@item load-changed
This xwidget event indicates that the @var{xwidget} has reached a
particular point of the page-loading process. When these events are
sent, @var{arg} will contain a string that futher describes the status
sent, @var{arg} will contain a string that further describes the status
of the widget:
@table @samp
@ -2208,6 +2212,17 @@ and @code{mouse-wheel-down-alternate-event} defined in
@file{mwheel.el} to determine what event types to expect for the mouse
wheel.
@vindex mouse-wheel-left-event
@vindex mouse-wheel-right-event
Similarly, some mice can generate @code{mouse-wheel-left-event} and
@code{mouse-wheel-right-event} and can be used to scroll if
@code{mouse-wheel-tilt-scroll} is non-@code{nil}. However, some mice
also generate other events at the same time as they're generating
these scroll events which may get in the way. The way to fix this is
generally to unbind these events (for instance, @code{mouse-6} or
@code{mouse-7}, but this is very hardware and operating system
dependent).
@cindex @code{pinch} event
@item (pinch @var{position} @var{dx} @var{dy} @var{scale} @var{angle})
This kind of event is generated by the user performing a ``pinch''
@ -2686,7 +2701,10 @@ the character at that position.
@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}. This is the time at which the
event occurred, in milliseconds.
event occurred, in milliseconds. Such a timestamp is reported
relative to an arbitrary starting time that varies according to the
window system in use. On the X Window System, for example, it is the
number of milliseconds since the X server was started.
@end defun
These functions compute a position list given particular buffer
@ -2962,7 +2980,7 @@ returns the key sequence as a vector, never as a string.
If an input character is upper-case (or has the shift modifier) and
has no key binding, but its lower-case equivalent has one, then
@code{read-key-sequence} converts the character to lower case. (This
behaviour can be disabled by setting the
behavior can be disabled by setting the
@code{translate-upper-case-key-bindings} user option to @code{nil}.)
Note that @code{lookup-key} does not perform case conversion in this
way.
@ -3198,7 +3216,7 @@ causes it to evaluate @code{help-form} and display the result. It
then continues to wait for a valid input character, or keyboard-quit.
@end defun
@defun read-multiple-choice prompt choices &optional help-string show-help
@defun read-multiple-choice prompt choices &optional help-string show-help long-form
Ask user a multiple choice question. @var{prompt} should be a string
that will be displayed as the prompt.
@ -3217,6 +3235,11 @@ If optional argument @var{show-help} is non-@code{nil}, the help
buffer will be displayed immediately, before any user input. If it is
a string, use it as the name of the help buffer.
If optional argument @var{long-form} is non-@code{nil}, the user
will have to type in long-form answers (using @code{completing-read})
instead of hitting a single key. The answers must be among the second
elements of the values in the @var{choices} list.
The return value is the matching value from @var{choices}.
@lisp

6
doc/lispref/compile.texi
View file

@ -979,7 +979,11 @@ Its value should be a number between @minus{}1 and 3. Values between
0 and 3 specify the optimization levels equivalent to the
corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line
options of the compiler. The value @minus{}1 means disable
native-compilation; functions and files will be only byte-compiled.
native-compilation: functions and files will be only byte-compiled;
however, the @file{*.eln} files will still be produced, they will just
contain the compiled code in bytecode form. (This can be achieved at
function granularity by using the @w{@code{(declare (speed -1))}}
form, @pxref{Declare Form}.)
The default value is 2.
@end defopt

4
doc/lispref/customize.texi
View file

@ -672,6 +672,10 @@ The value must be a valid color name. The widget provides completion
for color names, as well as a sample and a button for selecting a
color name from a list of color names shown in a @file{*Colors*}
buffer.
@item fringe-bitmap
The value must be a valid fringe bitmap name. The widget provides
completion.
@end table
@node Composite Types

44
doc/lispref/debugging.texi
View file

@ -77,6 +77,7 @@ debugger recursively. @xref{Recursive Editing}.
@menu
* Error Debugging:: Entering the debugger when an error happens.
* Debugging Redisplay:: Getting backtraces from redisplay errors.
* Infinite Loops:: Stopping and debugging a program that doesn't exit.
* Function Debugging:: Entering it when a certain function is called.
* Variable Debugging:: Entering it when a variable is modified.
@ -105,6 +106,10 @@ debugger, set the variable @code{debug-on-error} to non-@code{nil}.
(The command @code{toggle-debug-on-error} provides an easy way to do
this.)
Note that, for technical reasons, you cannot use the facilities
defined in this subsection to debug errors in Lisp that the redisplay
code has invoked. @xref{Debugging Redisplay}, for help with these.
@defopt debug-on-error
This variable determines whether the debugger is called when an error
is signaled and not handled. If @code{debug-on-error} is @code{t},
@ -213,6 +218,45 @@ file, use the option @samp{--debug-init}. This binds
bypasses the @code{condition-case} which normally catches errors in the
init file.
@node Debugging Redisplay
@subsection Debugging Redisplay Errors
@cindex redisplay errors
@cindex debugging redisplay errors
When an error occurs in Lisp code which redisplay has invoked, Emacs's
usual debugging mechanisms are unusable, for technical reasons. This
subsection describes how to get a backtrace from such an error, which
should be helpful in debugging it.
These directions apply to Lisp forms used, for example, in
@code{:eval} mode line constructs (@pxref{Mode Line Data}), and in all
hooks invoked from redisplay, such as:
@itemize
@item
@code{fontification-functions} (@pxref{Auto Faces}).
@item
@code{window-scroll-functions} (@pxref{Window Hooks}).
@end itemize
Note that if you have had an error in a hook function called from
redisplay, the error handling might have removed this function from
the hook. You will thus need to reinitialize that hook somehow,
perhaps with @code{add-hook}, to be able to replay the bug.
To generate a backtrace in these circumstances, set the variable
@code{backtrace-on-redisplay-error} to non-@code{nil}. When the error
occurs, Emacs will dump the backtrace to the buffer
@file{*Redisplay-trace*}, but won't automatically display it in a
window. This is to avoid needlessly corrupting the redisplay you are
debugging. You will thus need to display the buffer yourself, with a
command such as @code{switch-to-buffer-other-frame} @key{C-x 5 b}.
@defvar backtrace-on-redisplay-error
Set this variable to non-@code{nil} to enable the generation of a
backtrace when an error occurs in any Lisp called from redisplay.
@end defvar
@node Infinite Loops
@subsection Debugging Infinite Loops
@cindex infinite loops

258
doc/lispref/display.texi
View file

@ -27,6 +27,7 @@ that Emacs presents to the user.
* Window Dividers:: Separating windows visually.
* Display Property:: Images, margins, text size, etc.
* Images:: Displaying images in Emacs buffers.
* Icons:: Displaying icons in Emacs buffers.
* Xwidgets:: Displaying native widgets in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
@ -2474,6 +2475,7 @@ Otherwise, it returns @code{nil}.
The following table lists all the face attributes, their possible
values, and their effects.
@cindex unspecified, face attribute value
Apart from the values given below, each face attribute can have the
value @code{unspecified}. This special value means that the face
doesn't specify that attribute directly. An @code{unspecified}
@ -2482,7 +2484,13 @@ description @code{:inherit} attribute below); or, failing that, to an
underlying face (@pxref{Displaying Faces}). (However,
@code{unspecified} is not a valid value in @code{defface}.)
The @code{default} face must specify all attributes.
@cindex reset, face attribute value
A face attribute can also have the value @code{reset}. This special
value stands for the value of the corresponding attribute of the
@code{default} face.
The @code{default} face must explicitly specify all attributes, and
cannot use the special value @code{reset}.
Some of these attributes are meaningful only on certain kinds of
displays. If your display cannot handle a certain attribute, the
@ -2615,14 +2623,17 @@ Draw a box with lines of width 1, in the foreground color.
Draw a box with lines of width 1, in color @var{color}.
@item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})}
This way you can explicitly specify all aspects of the box. The values
@var{vwidth} and @var{hwidth} specifies respectively the width of the
vertical and horizontal lines to draw; they default to (1 . 1).
A negative horizontal or vertical width @minus{}@var{n} means to draw a line
of width @var{n} that occupies the space of the underlying text, thus
avoiding any increase in the character height or width. For simplification
the width could be specified with only a single number @var{n} instead
of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}.
You can explicitly specify all aspects of the box with a plist on this
form. Any element in this plist can be omitted.
The values @var{vwidth} and @var{hwidth} specifies respectively the
width of the vertical and horizontal lines to draw; they default to (1
. 1). A negative horizontal or vertical width @minus{}@var{n} means
to draw a line of width @var{n} that occupies the space of the
underlying text, thus avoiding any increase in the character height or
width. For simplification the width could be specified with only a
single number @var{n} instead of a list, such case is equivalent to
@code{((abs @var{n}) . @var{n})}.
The value @var{style} specifies whether to draw a 3D box. If it is
@code{released-button}, the box looks like a 3D button that is not
@ -2706,6 +2717,13 @@ doesn't specify an explicit value for a face, the value from the
original face definition by @code{defface} is inherited
(@pxref{Defining Faces}).
Some modes, like @code{hl-line-mode}, use a face with an
@code{:extend} property to mark the entire current line. Note,
however, that Emacs will always allow you to move point after the
final character in a buffer, and if the buffer ends with a newline
character, point can be placed on what is seemingly a line at the end
of the buffer---but Emacs can't highlight that ``line'', because it
doesn't really exist.
@end table
@defun font-family-list &optional frame
@ -3465,6 +3483,12 @@ function finishes are the ones that really matter.
For efficiency, we recommend writing these functions so that they
usually assign faces to around 400 to 600 characters at each call.
When the buffer text includes very long lines, these functions are
called with the buffer narrowed to a relatively small region around
@var{pos}, and with narrowing locked, so the functions cannot use
@code{widen} to gain access to the rest of the buffer.
@xref{Narrowing}.
@end defvar
@node Basic Faces
@ -4605,6 +4629,7 @@ Used to indicate buffer boundaries.
Used for different types of fringe cursors.
@item @code{exclamation-mark}, @code{question-mark}
@itemx @code{large-circle}
Not used by core Emacs features.
@end table
@ -5710,6 +5735,12 @@ are supported, unless the image type is @code{imagemagick}. Positive
values rotate clockwise, negative values counter-clockwise. Rotation
is performed after scaling and cropping.
@item :flip @var{flip}
If this is @code{t}, the image will be horizontally flipped.
Currently it has no effect if the image type is @code{imagemagick}.
Vertical flipping can be achieved by rotating the image 180 degrees
and toggling this value.
@item :transform-smoothing @var{smooth}
If this is @code{t}, any image transform will have smoothing applied;
if @code{nil}, no smoothing will be applied. The exact algorithm used
@ -5858,6 +5889,14 @@ When you click the mouse when the mouse pointer is over a hot-spot, an
event is composed by combining the @var{id} of the hot-spot with the
mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
@var{id} is @code{area4}.
Note that the map's coordinates should reflect the displayed image
after all transforms have been done (rotation, scaling and so on), and
also note that Emacs (by default) performs auto-scaling of images, so
to make things match up, you should either specify @code{:scale 1.0}
when creating the image, or use the result of
@code{image-compute-scaling-factor} to compute the elements of the
map.
@end table
@defun image-mask-p spec &optional frame
@ -5923,13 +5962,10 @@ There are three formats you can use for @var{data}:
@itemize @bullet
@item
A vector of strings or bool-vectors, each specifying one line of the
image. Do specify @code{:height} and @code{:width}.
image. Do specify @code{:data-height} and @code{:data-width}.
@item
A string containing the same byte sequence as an XBM file would contain.
You must not specify @code{:height} and @code{:width} in this case,
because omitting them is what indicates the data has the format of an
XBM file. The file contents specify the height and width of the image.
@item
A string or a bool-vector containing the bits of the image (plus
@ -5937,26 +5973,11 @@ perhaps some extra bits at the end that will not be used). It should
contain at least @w{@code{@var{stride} * @var{height}}} bits, where
@var{stride} is the smallest multiple of 8 greater than or equal to
the width of the image. In this case, you should specify
@code{:height}, @code{:width} and @code{:stride}, both to indicate
that the string contains just the bits rather than a whole XBM file,
and to specify the size of the image.
@code{:data-height}, @code{:data-width} and @code{:stride}, both to
indicate that the string contains just the bits rather than a whole
XBM file, and to specify the size of the image.
@end itemize
@item :width @var{width}
The value, @var{width}, specifies the width of the image, in pixels.
@item :height @var{height}
The value, @var{height}, specifies the height of the image, in pixels.
Note that @code{:width} and @code{:height} can only be used if passing
in data that doesn't specify the width and height (e.g., a string or a
vector containing the bits of the image). @acronym{XBM} files usually
specify this themselves, and it's an error to use these two properties
on these files. Also note that @code{:width} and @code{:height} are
used by most other image formats to specify what the displayed image
is supposed to be, which usually means performing some sort of
scaling. This isn't supported for @acronym{XBM} images.
@item :stride @var{stride}
The number of bool vector entries stored for each row; the smallest
multiple of 8 greater than or equal to @var{width}.
@ -6977,6 +6998,165 @@ bytes. An image of size 200x100 with 24 bits per color will have a
cache size of 60000 bytes, for instance.
@end defun
@node Icons
@section Icons
Emacs sometimes uses buttons (for clicking on) or small graphics (to
illustrate something). Since Emacs is available on a wide variety of
systems with different capabilities, and users have different
preferences, Emacs provides a facility to handle this in a convenient
way, allowing customization, graceful degradation, accessibility, as
well as themability: @dfn{Icons}.
The central macro here is @code{define-icon}, and here's a simple
example:
@lisp
(define-icon outline-open button
'((image "right.svg" "open.xpm" "open.pbm" :height line)
(emoji "▶️")
(symbol "▶" "➤")
(text "open" :face icon-button))
"Icon used for buttons for opening a section in outline buffers."
:version "29.1"
:help-echo "Open this section")
@end lisp
Which alternative will actually be displayed depends on the value of
the user option @code{icon-preference} (@pxref{Icons,,, emacs, The GNU
Emacs Manual}) and on the results of run-time checks for what the
current frame's terminal can actually display.
The macro in the example above defines @code{outline-open} as an icon,
and inherits properties from the icon called @code{button} (so this is
meant as a clickable button to be inserted in a buffer). It is
followed by a list of @dfn{icon types} along with the actual icon
shapes themselves. In addition, there's a doc string and various
keywords that contain additional information and properties.
To instantiate an icon, you use @code{icon-string}, which will
consult the current Customize theming, and the @code{icon-preference}
user option, and finally what the Emacs is able to actually display.
If @code{icon-preference} is @code{(image emoji symbol text)} (i.e.,
allowing all of these forms of icons), in this case,
@code{icon-string} will first check that Emacs is able to display
images at all, and then whether it has support for each of those
different image formats. If that fails, Emacs will check whether
Emacs can display emojis (in the current frame). If that fails, it'll
check whether it can display the symbol in question. If that fails,
it'll use the plain text version.
For instance, if @code{icon-preference} doesn't contain @code{image}
or @code{emoji}, it'll skip those entries.
Code can confidently call @code{icon-string} in all circumstances and
be sure that something readable will appear on the screen, no
matter whether the user is on a graphical terminal or a text terminal,
and no matter which features Emacs was built with.
@defmac define-icon name parent specs doc &rest keywords
Define an icon @var{name}, a symbol, with the display alternatives in
@var{spec}, that can be later instantiated using @code{icon-string}.
The @var{name} is the name of the resulting keyword.
The resulting icon will inherit specs from @var{parent}, and from
their parent's parents, and so on, and the lowest descendent element
wins.
@var{specs} is a list of icon specifications. The first element of each
specification is the type, and the rest is something that can be used
as an icon of that type, and then optionally followed by a keyword
list. The following icon types are available:
@cindex icon types
@table @code
@item image
In this case, there may be many images listed as candidates. Emacs
will choose the first one that the current Emacs instance can show.
If an image is listed is an absolute file name, it's used as is, but it's
otherwise looked up in the list @code{image-load-path}
(@pxref{Defining Images}).
@item emoji
This should be a (possibly colorful) emoji.
@item symbol
This should be a (monochrome) symbol character.
@item text
Icons should also have a textual fallback. This can also be used for
the visually impaired: if @code{icon-preference} is just
@code{(text)}, all icons will be replaced by text.
@end table
Various keywords may follow the list of icon specifications. For
instance:
@example
(symbol "▶" "➤" :face icon-button)
@end example
Unknown keywords are ignored. The following keywords are allowed:
@cindex icon keywords
@table @code
@item :face
The face to be used for the icon.
@item :height
This is only valid for @code{image} icons, and can be either a number
(which specifies the height in pixels), or the symbol @code{line},
which will use the default line height in the currently selected
window.
@end table
@var{doc} should be a doc string.
@var{keywords} is a list of keyword/value pairs. The following
keywords are allowed:
@table @code
@item :version
The (approximate) Emacs version this button first appeared. (This
keyword is mandatory.)
@item :group
The customization group this icon belongs in. If not present, it is
inferred.
@item :help-echo
The help string shown when hovering over the icon with the mouse
pointer.
@end table
@end defmac
@defun icon-string icon
This function returns a string suitable for display in the current
buffer for @var{icon}.
@end defun
@defun icon-elements icon
Alternatively, you can get a ``deconstructed'' version of @var{icon}
with this function. It returns a plist (@pxref{Property Lists}) where
the keys are @code{string}, @code{face} and @var{image}. (The latter
is only present if the icon is represented by an image.) This can be
useful if the icon isn't to be inserted directly in the buffer, but
needs some sort of pre-processing first.
@end defun
Icons can be customized with @kbd{M-x customize-icon}. Themes can
specify changes to icons with, for instance:
@lisp
(custom-theme-set-icons
'my-theme
'(outline-open ((image :height 100)
(text " OPEN ")))
'(outline-close ((image :height 100)
(text " CLOSE " :face warning))))
@end lisp
@node Xwidgets
@section Embedded Native Widgets
@cindex xwidget
@ -7309,6 +7489,7 @@ the usual Emacs @code{highlight} face.
@item keymap
@kindex keymap @r{(button property)}
@vindex button-map
The button's keymap, defining bindings active within the button
region. By default this is the usual button region keymap, stored
in the variable @code{button-map}, which defines @key{RET} and
@ -7523,6 +7704,7 @@ Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
These are commands and functions for locating and operating on
buttons in an Emacs buffer.
@cindex buffer-button-map
@code{push-button} is the command that a user uses to actually push
a button, and is bound by default in the button itself to @key{RET}
and to @key{mouse-2} using a local keymap in the button's overlay or
@ -8360,7 +8542,11 @@ hexadecimal notation.
@item an @acronym{ASCII} string
Display a box containing that string. The string should contain at
most 6 @acronym{ASCII} characters.
most 6 @acronym{ASCII} characters. As an exception, if the string
includes just one character, on text-mode terminals that character
will be displayed without a box; this allows to handle such
``acronyms'' as a replacement character for characters that cannot be
displayed by the terminal.
@item a cons cell @code{(@var{graphical} . @var{text})}
Display with @var{graphical} on graphical displays, and with
@ -8426,9 +8612,9 @@ Characters of Unicode General Category [Cf], such as U+200E
images, such as U+00AD @sc{soft hyphen}.
@item variation-selectors
Unicode VS-1 through VS-16 (U+FE00 through U+FE0F), which are used to
select between different glyphs for the same codepoints (typically
emojis).
Unicode VS-1 through VS-256 (U+FE00 through U+FE0F and U+E0100 through
U+E01EF), which are used to select between different glyphs for the same
codepoints (typically emojis).
@item no-font
Characters for which there is no suitable font, or which cannot be
@ -8556,7 +8742,7 @@ displayed in the echo area.
@vindex use-system-tooltips
When Emacs is built with the GTK+ toolkit or Haiku windowing support,
it by default displays tooltips using toolkit functions, and the
appearance of the tooltips is then controlled by by the toolkit's
appearance of the tooltips is then controlled by the toolkit's
settings. Toolkit-provided tooltips can be disabled by changing the
value of the variable @code{use-system-tooltips} to @code{nil}. The
rest of this subsection describes how to control non-toolkit tooltips,

10
doc/lispref/edebug.texi
View file

@ -701,7 +701,11 @@ on this process.
@item e @var{exp} @key{RET}
Evaluate expression @var{exp} in the context outside of Edebug
(@code{edebug-eval-expression}). That is, Edebug tries to minimize
its interference with the evaluation. By default, this command
its interference with the evaluation. The result is shown in the echo
area, or, if this command is given a prefix, pop up a new buffer and
pretty-print the result there.
By default, this command
suppresses the debugger during evaluation, so that an error in the
evaluated expression won't add a new error on top of the existing one.
Set the @code{debug-allow-recursive-debug} user option to a
@ -715,7 +719,8 @@ Evaluate expression @var{exp} in the context of Edebug itself
Evaluate the expression before point, in the context outside of Edebug
(@code{edebug-eval-last-sexp}). With the prefix argument of zero
(@kbd{C-u 0 C-x C-e}), don't shorten long items (like strings and
lists).
lists). Any other prefix will result in the value being
pretty-printed in a separate buffer.
@end table
@cindex lexical binding (Edebug)
@ -836,7 +841,6 @@ you continue execution, and recreated next time it is needed.
@cindex printing (Edebug)
@cindex printing circular structures
@pindex cust-print
If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.

9
doc/lispref/files.texi
View file

@ -2445,6 +2445,15 @@ You can use this function for directory names and for file names,
because it recognizes abbreviations even as part of the name.
@end defun
@defun file-parent-directory filename
This function returns the directory name of the parent directory of
@var{filename}. If @var{filename} is at the root directory of the
filesystem, it returns @code{nil}. A relative @var{filename} is
assumed to be relative to @code{default-directory}, and the return
value will also be relative in that case. If the return value is
non-@code{nil}, it ends in a slash.
@end defun
@node File Name Expansion
@subsection Functions that Expand Filenames
@cindex expansion of file names

86
doc/lispref/frames.texi
View file

@ -1746,15 +1746,16 @@ fit will be clipped by the window manager.
@item fullscreen
This parameter specifies whether to maximize the frame's width, height
or both. Its value can be @code{fullwidth}, @code{fullheight},
@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as
wide as possible, a @dfn{fullheight} frame is as tall as possible, and
a @dfn{fullboth} frame is both as wide and as tall as possible. A
@dfn{maximized} frame is like a ``fullboth'' frame, except that it
usually keeps its title bar and the buttons for resizing and closing
the frame. Also, maximized frames typically avoid hiding any task bar
or panels displayed on the desktop. A ``fullboth'' frame, on the
other hand, usually omits the title bar and occupies the entire
available screen space.
@code{fullboth}, or @code{maximized}.@footnote{On PGTK frames, setting
the values @code{fullheight} and @code{fullwidth} has no effect.} A
@dfn{fullwidth} frame is as wide as possible, a @dfn{fullheight} frame
is as tall as possible, and a @dfn{fullboth} frame is both as wide and
as tall as possible. A @dfn{maximized} frame is like a ``fullboth''
frame, except that it usually keeps its title bar and the buttons for
resizing and closing the frame. Also, maximized frames typically
avoid hiding any task bar or panels displayed on the desktop. A
``fullboth'' frame, on the other hand, usually omits the title bar and
occupies the entire available screen space.
Full-height and full-width frames are more similar to maximized
frames in this regard. However, these typically display an external
@ -2179,10 +2180,20 @@ If non-@code{nil}, the frame is visible on all virtual desktops on systems
with virtual desktops.
@vindex shaded@r{, a frame parameter}
@item sticky
@item shaded
If non-@code{nil}, tell the window manager to display the frame in a
way that its contents are hidden, leaving only the title bar.
@vindex use-frame-synchronization@r{, a frame parameter}
@item use-frame-synchronization
If non-@code{nil}, synchronize the frame redisplay with the refresh
rate of the monitor to avoid graphics tearing. At present, this is
only implemented on Haiku and the X window system inside no-toolkit
and X toolkit builds, does not work correctly with toolkit scroll
bars, and requires a compositing manager supporting the relevant
display synchronization protocols. The @code{synchronizeResize} X
resource must also be set to the string @code{"extended"}.
@vindex inhibit-double-buffering@r{, a frame parameter}
@item inhibit-double-buffering
If non-@code{nil}, the frame is drawn to the screen without double
@ -4090,6 +4101,20 @@ They can either be the same data types that are typically accepted by
specific drag-n-drop protocol being used. Plain text may be
@code{"STRING"} or @code{"text/plain"}, for example.
@vindex x-dnd-direct-save-function
However, @code{x-dnd-types-alist} does not handle a special kind of
drop sent by a program which wants Emacs to save a file in a location
Emacs must determine by itself. These drops are handled via the
variable @code{x-dnd-direct-save-function}, which should be a function
that accepts two arguments. If the first argument is non-@code{nil},
then the second argument is a string describing the name (with no
leading directory) that the other program recommends the file be saved
under, and the function should return the complete file name under
which it will be saved. Otherwise, the file has already been saved,
and the second argument is the complete name of the file. The
function should then perform whatever action is appropriate (i.e.,
open the file or refresh the directory listing.)
@cindex initiating drag-and-drop
On capable window systems, Emacs also supports dragging contents
from its frames to windows of other applications.
@ -4186,6 +4211,13 @@ This function is like @code{dnd-begin-file-drag}, except that
dropping multiple files, then the first file will be used instead.
@end defun
@defun dnd-direct-save file name &optional frame allow-same-frame
This function is similar to @code{dnd-begin-file-drag} (with the
default action of copy), but instead of specifying the action you
specify the name of the copy created by the target program in
@code{name}.
@end defun
@cindex initiating drag-and-drop, low-level
The high-level interfaces described above are implemented on top of
a lower-level primitive. If you need to drag content other than files
@ -4251,6 +4283,40 @@ chosen by the target. For example, callers should delete the buffer
text that was dragged if this function returns @code{XdndActionMove}.
@end defun
@cindex drag and drop protocols, X
On X Windows, several different drag-and-drop protocols are
supported by @code{x-begin-drag}. When dragging content that is known
to not be supported by a specific drag-and-drop protocol, it might be
desirable to turn that protocol off, by changing the values of the
following variables:
@defvar x-dnd-disable-motif-protocol
When this is non-@code{nil}, the Motif drag and drop protocols are
disabled, and dropping onto programs that only understand them will
not work.
@end defvar
@defvar x-dnd-use-offix-drop
When this is @code{nil}, the OffiX (old KDE) drag and drop protocol is
disabled. When this is the symbol @code{files}, the OffiX protocol
will only be used if @code{"FILE_NAME"} is one of the targets given to
@code{x-begin-drag}. Any other value means to use the OffiX protocol
to drop all supported content.
@end defvar
@defvar x-dnd-use-unsupported-drop
When one of the @code{"STRING"}, @code{"UTF8_STRING"},
@code{"COMPOUND_TEXT"} or @code{"TEXT"} targets is present in the list
given to @code{x-begin-drag}, Emacs will try to use synthesized mouse
events and the primary selection to insert the text if the drop target
doesn't support any drag-and-drop protocol at all.
A side effect is that Emacs will become the owner of the primary
selection upon such a drop. If that is not desired, then the drop
emulation can be disabled by setting this variable to @code{nil}.
@end defvar
@node Color Names
@section Color Names

38
doc/lispref/functions.texi
View file

@ -217,6 +217,16 @@ function. For example:
@end example
@end defun
@defun compiled-function-p object
This function returns @code{t} if @var{object} is a function object
that is not in the form of ELisp source code but something like
machine code or byte code instead. More specifically it returns
@code{t} if the function is built-in (a.k.a.@: ``primitive'',
@pxref{What Is a Function}), or byte-compiled (@pxref{Byte
Compilation}), or natively-compiled (@pxref{Native Compilation}), or
a function loaded from a dynamic module (@pxref{Dynamic Modules}).
@end defun
@defun subr-arity subr
This works like @code{func-arity}, but only for built-in functions and
without symbol indirection. It signals an error for non-built-in
@ -2497,6 +2507,34 @@ the current buffer.
@item (modes @var{modes})
Specify that this command is meant to be applicable for @var{modes}
only.
@item (interactive-args @var{arg} ...)
Specify the arguments that should be stored for @code{repeat-command}.
Each @var{arg} is on the form @code{@var{argument-name} @var{form}}.
@item (pure @var{val})
If @var{val} is non-@code{nil}, this function is @dfn{pure}
(@pxref{What Is a Function}). This is the same as the @code{pure}
property of the function's symbol (@pxref{Standard Properties}).
@item (side-effect-free @var{val})
If @var{val} is non-@code{nil}, this function is free of side effects,
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 (speed @var{n})
Specify the value of @code{native-comp-speed} in effect for native
compilation of this function (@pxref{Native-Compilation Variables}).
This allows function-level control of the optimization level used for
native code emitted for the function. In particular, if @var{n} is
@minus{}1, native compilation of the function will emit bytecode
instead of native code for the function.
@item no-font-lock-keyword
This is valid for macros only. Macros with this declaration are
highlighted by font-lock (@pxref{Font Lock Mode}) as normal functions,
not specially as macros.
@end table
@end defmac

28
doc/lispref/hash.texi
View file

@ -203,7 +203,8 @@ association in @var{table}.
@defun puthash key value table
This function enters an association for @var{key} in @var{table}, with
value @var{value}. If @var{key} already has an association in
@var{table}, @var{value} replaces the old associated value.
@var{table}, @var{value} replaces the old associated value. This
function always returns @var{value}.
@end defun
@defun remhash key table
@ -219,10 +220,7 @@ otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}.
@defun clrhash table
This function removes all the associations from hash table @var{table},
so that it becomes empty. This is also called @dfn{clearing} the hash
table.
@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
@var{table}. In Emacs Lisp, it returns @code{nil}.
table. @code{clrhash} returns the empty @var{table}.
@end defun
@defun maphash function table
@ -289,9 +287,13 @@ If two objects @var{obj1} and @var{obj2} are @code{equal}, then
are the same integer.
If the two objects are not @code{equal}, the values returned by
@code{sxhash-equal} are usually different, but not always; once in a
rare while, by luck, you will encounter two distinct-looking objects
that give the same result from @code{sxhash-equal}.
@code{sxhash-equal} are usually different, but not always.
@code{sxhash-equal} is designed to be reasonably fast (since it's used
for indexing hash tables) so it won't recurse deeply into nested
structures. In addition; once in a rare while, by luck, you will
encounter two distinct-looking simple objects that give the same
result from @code{sxhash-equal}. So you can't, in general, use
@code{sxhash-equal} to check whether an object has changed.
@b{Common Lisp note:} In Common Lisp a similar function is called
@code{sxhash}. Emacs provides this name as a compatibility alias for
@ -322,15 +324,13 @@ the same integer.
compared case-insensitively.
@example
(defun case-fold-string= (a b)
(eq t (compare-strings a nil nil b nil nil t)))
(defun case-fold-string-hash (a)
(defun string-hash-ignore-case (a)
(sxhash-equal (upcase a)))
(define-hash-table-test 'case-fold
'case-fold-string= 'case-fold-string-hash)
(define-hash-table-test 'ignore-case
'string-equal-ignore-case 'string-hash-ignore-case)
(make-hash-table :test 'case-fold)
(make-hash-table :test 'ignore-case)
@end example
Here is how you could define a hash table test equivalent to the

2
doc/lispref/hooks.texi
View file

@ -280,7 +280,6 @@ kbd-macro-termination-hook
signal-hook-function
C functions:
redisplay-end-trigger-functions
x-lost-selection-functions
x-sent-selection-functions
@ -290,7 +289,6 @@ auto-fill-function
command-error-function
compose-chars-after-function
composition-function-table
deferred-action-function
input-method-function
load-read-function
load-source-file-function

35
doc/lispref/keymaps.texi
View file

@ -374,7 +374,8 @@ number of keys. Here's a very basic example:
@end lisp
This function creates a new sparse keymap, defines the keystrokes in
@var{pairs}, and returns the new keymap.
@var{pairs}, and returns the new keymap. It signals an error if there
are duplicate key bindings in @var{pairs}.
@var{pairs} is a list of alternating key bindings and key definitions,
as accepted by @code{keymap-set}. In addition, the key can be the
@ -438,7 +439,8 @@ variable. This is what virtually all modes do---a mode called
This macro defines @var{name} as a variable, passes @var{options}
and @var{pairs} to @code{define-keymap}, and uses the result as the
default value for the variable.
default value for the variable. It signals an error if there are
duplicate key bindings in @var{pairs}.
@var{options} is like the keywords in @code{define-keymap}, but
there's an additional @code{:doc} keyword that provides the doc
@ -579,11 +581,10 @@ override any non-@code{nil} binding in any other of the @var{maps}.
@code{button-buffer-map} and @code{special-mode-map}:
@example
(defvar help-mode-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map
(make-composed-keymap button-buffer-map special-mode-map))
... map) ... )
(defvar-keymap help-mode-map
:parent (make-composed-keymap button-buffer-map
special-mode-map)
...)
@end example
@ -1064,6 +1065,20 @@ The optional argument @var{on-exit}, if non-@code{nil}, specifies a
function that is called, with no arguments, after @var{keymap} is
deactivated.
The optional argument @var{message} specifies the message to display
after activating the transient map. If @var{message} is a string, it
is the format string for the message, and any @samp{%k} specifier in
that string is replaced with the list of keys from the transient map.
Any other non-@code{nil} value of @var{message} stands for the default
message format @samp{Repeat with %k}.
@vindex set-transient-map-timeout
If the optional argument @var{timeout} is non-@code{nil}, it should be
a number that specifies how many seconds of idle time to wait before
deactivating @var{keymap}. The value of the variable
@code{set-transient-map-timeout}, if non-@code{nil}, overrides the
value of this argument.
This function works by adding and removing @var{keymap} from the
variable @code{overriding-terminal-local-map}, which takes precedence
over all other active keymaps (@pxref{Searching Keymaps}).
@ -1869,6 +1884,7 @@ to make entries in @code{input-decode-map} beyond those that can be
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
@end defvar
@cindex function-key-map
@defvar local-function-key-map
This variable holds a keymap similar to @code{input-decode-map} except
that it describes key sequences which should be translated to
@ -2209,6 +2225,11 @@ If @var{no-remap} is @code{nil}, return the bindings for
non-@code{nil}, return the bindings for @var{command}, ignoring the
fact that it is remapped.
@end table
If a command maps to a key binding like @code{[some-event]}, and
@code{some-event} has a symbol plist containing a non-@code{nil}
@code{non-key-event} property, then that binding is ignored by
@code{where-is-internal}.
@end defun
@deffn Command describe-bindings &optional prefix buffer-or-name

67
doc/lispref/lists.texi
View file

@ -340,6 +340,44 @@ If @var{n} is zero, @code{nthcdr} returns all of
@end example
@end defun
@defun take n list
This function returns the @var{n} first elements of @var{list}. Essentially,
it returns the part of @var{list} that @code{nthcdr} skips.
@code{take} returns @var{list} if shorter than @var{n} elements;
it returns @code{nil} if @var{n} is zero or negative.
@example
@group
(take 3 '(a b c d))
@result{} (a b c)
@end group
@group
(take 10 '(a b c d))
@result{} (a b c d)
@end group
@group
(take 0 '(a b c d))
@result{} nil
@end group
@end example
@end defun
@defun ntake n list
This is a version of @code{take} that works by destructively modifying
the list structure of the argument. That makes it faster, but the
original value of @var{list} may be lost.
@code{ntake} returns @var{list} unmodified if shorter than @var{n}
elements; it returns @code{nil} if @var{n} is zero or negative.
Otherwise, it returns @var{list} truncated to its first @var{n}
elements.
This means that it is usually a good idea to use the return value and
not just rely on the truncation effect unless @var{n} is known to be
positive.
@end defun
@defun last list &optional n
This function returns the last link of @var{list}. The @code{car} of
this link is the list's last element. If @var{list} is null,
@ -1925,9 +1963,10 @@ and later discarded; this is not possible with a property list.
The following functions can be used to manipulate property lists.
They all compare property names using @code{eq}.
@defun plist-get plist property
@defun plist-get plist property &optional predicate
This returns the value of the @var{property} property stored in the
property list @var{plist}. It accepts a malformed @var{plist}
property list @var{plist}. Comparisons are done with @var{predicate},
and defaults to @code{eq}. It accepts a malformed @var{plist}
argument. If @var{property} is not found in the @var{plist}, it
returns @code{nil}. For example,
@ -1943,9 +1982,10 @@ returns @code{nil}. For example,
@end example
@end defun
@defun plist-put plist property value
@defun plist-put plist property value &optional predicate
This stores @var{value} as the value of the @var{property} property in
the property list @var{plist}. It may modify @var{plist} destructively,
the property list @var{plist}. Comparisons are done with @var{predicate},
and defaults to @code{eq}. It may modify @var{plist} destructively,
or it may construct a new list structure without altering the old. The
function returns the modified property list, so you can store that back
in the place where you got @var{plist}. For example,
@ -1961,19 +2001,20 @@ in the place where you got @var{plist}. For example,
@end defun
@defun lax-plist-get plist property
Like @code{plist-get} except that it compares properties
using @code{equal} instead of @code{eq}.
This obsolete function is like @code{plist-get} except that it
compares properties using @code{equal} instead of @code{eq}.
@end defun
@defun lax-plist-put plist property value
Like @code{plist-put} except that it compares properties
using @code{equal} instead of @code{eq}.
This obsolete function is like @code{plist-put} except that it
compares properties using @code{equal} instead of @code{eq}.
@end defun
@defun plist-member plist property
@defun plist-member plist property &optional predicate
This returns non-@code{nil} if @var{plist} contains the given
@var{property}. Unlike @code{plist-get}, this allows you to distinguish
between a missing property and a property with the value @code{nil}.
The value is actually the tail of @var{plist} whose @code{car} is
@var{property}.
@var{property}. Comparisons are done with @var{predicate}, and
defaults to @code{eq}. Unlike @code{plist-get}, this allows you to
distinguish between a missing property and a property with the value
@code{nil}. The value is actually the tail of @var{plist} whose
@code{car} is @var{property}.
@end defun

36
doc/lispref/loading.texi
View file

@ -149,10 +149,9 @@ up the execution of uncompiled code. Sometimes, this macro expansion
cannot be done, owing to a cyclic dependency. In the simplest
example of this, the file you are loading refers to a macro defined
in another file, and that file in turn requires the file you are
loading. This is generally harmless. Emacs prints a warning
loading. Emacs will issue an error about
(@samp{Eager macro-expansion skipped due to cycle@dots{}})
giving details of the problem, but it still loads the file, just
leaving the macro unexpanded for now. You may wish to restructure
giving details of the problem. You have to restructure
your code so that this does not happen. Loading a compiled file does
not cause macroexpansion, because this should already have happened
during compilation. @xref{Compiling Macros}.
@ -441,7 +440,7 @@ similarly-named file in a directory earlier on @code{load-path}.
For instance, suppose @code{load-path} is set to
@example
("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
("/opt/emacs/site-lisp" "/usr/share/emacs/29.1/lisp")
@end example
@noindent
@ -699,14 +698,13 @@ Switch to *doctor* buffer and start giving psychotherapy.
@noindent
@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
in the usage part of the documentation string is replaced with the
function's name when the various help functions (@pxref{Help
Functions}) display it.
While the @file{loaddefs.el} isn't for editing, we try to keep it
somewhat readable for people. For instance, control characters in
@code{defvar} values are escaped, and we insert a backslash and
newline immediately following the double-quote of the doc string to
keep the line length down. @samp{(fn)} in the usage part of the
documentation string is replaced with the function's name when the
various help functions (@pxref{Help Functions}) display it.
If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
@ -729,7 +727,7 @@ variables to control this:
The value of this constant is a regexp that matches autoload cookies.
@code{loaddefs-generate} copies the Lisp form that follows the
cookie into the autoload file it generates. This will match comments
like like @samp{;;;###autoload} and @samp{;;;###calc-autoload}.
like @samp{;;;###autoload} and @samp{;;;###calc-autoload}.
@end defvar
@defvar generated-autoload-file
@ -768,7 +766,7 @@ the corresponding list of files to load for it. Entries to this
mapping are added by calls to @code{register-definition-prefixes}
which are generated by @code{loaddefs-generate}
(@pxref{Autoload}). Files which don't contain any definitions worth
loading (test files, for examples), should set
loading (test files, for example), should set
@code{autoload-compute-prefixes} to @code{nil} as a file-local
variable.
@ -1033,7 +1031,7 @@ with a call to @code{provide}. The order of the elements in the
@cindex symbol, where defined
@cindex where was a symbol defined
@defun symbol-file symbol &optional type
@defun symbol-file symbol &optional type native-p
This function returns the name of the file that defined @var{symbol}.
If @var{type} is @code{nil}, then any kind of definition is acceptable.
If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
@ -1044,6 +1042,14 @@ The value is normally an absolute file name. It can also be @code{nil},
if the definition is not associated with any file. If @var{symbol}
specifies an autoloaded function, the value can be a relative file name
without extension.
If the optional third argument @var{native-p} is non-@code{nil}, and
Emacs was built with native compilation support (@pxref{Native
Compilation}), this function will try to find the @file{.eln} file
that defined @var{symbol}, instead of the @file{.elc} or @file{.el}
file. If such a @file{.eln} file is found and is not outdated, the
function will return its absolute file name; otherwise it will report
the name of either the source or the byte-compiled file.
@end defun
The basis for @code{symbol-file} is the data in the variable

4
doc/lispref/maps.texi
View file

@ -125,6 +125,7 @@ setup-language-environment-map, describe-language-environment-map,
menu-bar-epatch-menu, menu-bar-ediff-merge-menu, menu-bar-ediff-menu, etc.
@end ignore
@cindex minibuffer-inactive-mode-map
@item minibuffer-inactive-mode-map
A full keymap used in the minibuffer when it is not active.@*
@xref{Minibuffer Edit,, Editing in the Minibuffer, emacs, The GNU Emacs Manual}.
@ -156,6 +157,7 @@ The global keymap used for the @kbd{C-x @key{RET}} prefix key.
@vindex narrow-map
A sparse keymap for subcommands of the prefix @kbd{C-x n}.
@cindex prog-mode-map
@item prog-mode-map
The keymap used by Prog mode.@*
@xref{Basic Major Modes}.
@ -171,6 +173,7 @@ for multi-buffer replacements. @xref{Search and Replace, query-replace-map}.
@item search-map
A sparse keymap that provides global bindings for search-related commands.
@cindex special-mode-map
@item special-mode-map
The keymap used by Special mode.@*
@xref{Basic Major Modes}.
@ -179,6 +182,7 @@ The keymap used by Special mode.@*
The global keymap used for the @kbd{C-x t} prefix key for tab-bar related commands.@*
@xref{Tab Bars,,, emacs, The GNU Emacs Manual}.
@cindex tab-bar-map
@item tab-bar-map
The keymap defining the contents of the tab bar.@*
@xref{Tab Bars,,, emacs, The GNU Emacs Manual}.

27
doc/lispref/modes.texi
View file

@ -271,7 +271,7 @@ normal-mode}), but tries to force it not to choose any modes in
@defun clean-mode
Changing the major mode clears out most local variables, but it
doesn't remove all artefacts in the buffer (like text properties and
doesn't remove all artifacts in the buffer (like text properties and
overlays). It's rare to change a buffer from one major mode to
another (except from @code{fundamental-mode} to everything else), so
this is usually not a concern. It can sometimes be convenient (mostly
@ -1356,11 +1356,10 @@ the conventions listed above:
;; @r{Create the keymap for this mode.}
@group
(defvar-keymap text-mode-map
"C-M-i" #'ispell-complete-word
@dots{})
"Keymap for `text-mode'.
Many other modes, such as `mail-mode', `outline-mode' and
`indented-text-mode', inherit all the commands defined in this map.")
:doc "Keymap for `text-mode'.
Many other modes, such as `mail-mode' and `outline-mode', inherit all
the commands defined in this map."
"C-M-i" #'ispell-complete-word)
@end group
@end smallexample
@ -3476,7 +3475,8 @@ fontification functions, and gives it two arguments, @var{start} and
@var{end}, which specify the region to be fontified or refontified.
If @var{function} performs fontifications, it can return a list of the
form @w{@code{(jit-lock-bounds @var{beg} . @var{end})}}, to indicate
the bounds of the region it actually fontified; JIT font-lock will use
the bounds of the region it actually fontified; Just-In-Time (a.k.a.@:
@acronym{``JIT''}) font-lock will use
this information to optimize subsequent redisplay cycles and regions
of buffer text it will pass to future calls to @var{function}.
@ -3496,6 +3496,19 @@ If @var{function} was previously registered as a fontification
function using @code{jit-lock-register}, this function unregisters it.
@end defun
@cindex debugging font-lock
@cindex jit-lock functions, debugging
@deffn Command jit-lock-debug-mode &optional arg
This is a minor mode whose purpose is to help in debugging code that
is run by JIT font-lock. When this mode is enabled, most of the code
that JIT font-lock normally runs during redisplay cycles, where Lisp
errors are suppressed, is instead run by a timer. Thus, this mode
allows using debugging aids such as @code{debug-on-error}
(@pxref{Error Debugging}) and Edebug (@pxref{Edebug}) for finding and
fixing problems in font-lock code and any other code run by JIT
font-lock.
@end deffn
@node Levels of Font Lock
@subsection Levels of Font Lock

3
doc/lispref/objects.texi
View file

@ -2022,6 +2022,9 @@ with references to further information.
@item byte-code-function-p
@xref{Byte-Code Type, byte-code-function-p}.
@item compiled-function-p
@xref{Byte-Code Type, compiled-function-p}.
@item case-table-p
@xref{Case Tables, case-table-p}.

66
doc/lispref/os.texi
View file

@ -1541,20 +1541,20 @@ Year numbers count since the year 1 BCE, and do not skip zero
as traditional Gregorian years do; for example, the year number
@minus{}37 represents the Gregorian year 38 BCE@.
@defun time-convert time &optional form
@defun time-convert time form
This function converts a time value into a Lisp timestamp.
The optional @var{form} argument specifies the timestamp form to be
returned. If @var{form} is the symbol @code{integer}, this function
returns an integer count of seconds. If @var{form} is a positive
integer, it specifies a clock frequency and this function returns an
integer-pair timestamp @code{(@var{ticks} . @var{form})}. If @var{form} is
The @var{form} argument specifies the timestamp form to be returned.
If @var{form} is the symbol @code{integer}, this function returns an
integer count of seconds. If @var{form} is a positive integer, it
specifies a clock frequency and this function returns an integer-pair
timestamp @code{(@var{ticks} . @var{form})}. If @var{form} is
@code{t}, this function treats it as a positive integer suitable for
representing the timestamp; for example, it is treated as 1000000000
if @var{time} is @code{nil} and the platform timestamp has nanosecond
resolution. If @var{form} is @code{list}, this function returns an
integer list @code{(@var{high} @var{low} @var{micro} @var{pico})}.
Although an omitted or @code{nil} @var{form} currently acts like
Although a @code{nil} @var{form} currently acts like
@code{list}, this is planned to change in a future Emacs version, so
callers requiring list timestamps should pass @code{list} explicitly.
@ -1754,9 +1754,10 @@ at the 15th of the month when adding months. Alternatively, you can use the
@cindex time formatting
@cindex formatting time values
These functions convert time values to text in a string, and vice versa.
Time values include @code{nil}, finite numbers, and Lisp timestamps
(@pxref{Time of Day}).
These functions convert time values to text in a string, and vice
versa. Time values are either represented as a Lisp timestamp
(@pxref{Time of Day}) or a decoded time structure (@pxref{Time
Conversion}).
@defun date-to-time string
This function parses the time-string @var{string} and returns the
@ -1769,22 +1770,11 @@ The operating system limits the range of time and zone values.
@end defun
@defun parse-time-string string
This function parses the time-string @var{string} into a list of the
following form:
@example
(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz})
@end example
@noindent
The format of this list is the same as what @code{decode-time} accepts
(@pxref{Time Conversion}), and is described in more detail there. Any
@code{dst} element that cannot be determined from the input is set to
@minus{}1, and any other unknown element is set to
@code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or
ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or
``1998-09-12T12:21:54-0200'', but this function will attempt to parse
less well-formed time strings as well.
This function parses the time-string @var{string} into a decoded time
structure (@pxref{Time Conversion}). The argument @var{string} should
resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar
2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this
function will attempt to parse less well-formed time strings as well.
@end defun
@vindex ISO 8601 date/time strings
@ -1801,11 +1791,11 @@ time structures, except the final one, which returns three of them
@end defun
@defun format-time-string format-string &optional time zone
This function converts @var{time} (or the current time, if
@var{time} is omitted or @code{nil}) to a string according to
@var{format-string}. The conversion uses the time zone rule @var{zone}, which
defaults to the current time zone rule. @xref{Time Zone Rules}. The argument
This function converts @var{time} (which should be a Lisp timestamp,
and defaults to the current time if @var{time} is omitted or
@code{nil}) to a string according to @var{format-string}. The
conversion uses the time zone rule @var{zone}, which defaults to the
current time zone rule. @xref{Time Zone Rules}. The argument
@var{format-string} may contain @samp{%}-sequences which say to
substitute parts of the time. Here is a table of what the
@samp{%}-sequences mean:
@ -2077,7 +2067,12 @@ This returns @code{t} if the time value @var{t1} is less than the time value
@defun time-equal-p t1 t2
This returns @code{t} if the two time values @var{t1} and @var{t2} are
equal.
equal. The result is @code{nil} if either argument is a NaN.
For the purpose of comparison, a @code{nil} argument represents the
current time with infinite resolution, so this function returns
@code{nil} if one argument is @code{nil} and the other is not, and
callers can therefore use @code{nil} to represent an unknown time
value that does not equal any timestamp.
@end defun
@defun time-subtract t1 t2
@ -2748,6 +2743,13 @@ if it is non-@code{nil}; this can be overridden by binding
@code{coding-system-for-write} to a coding system of you choice
(@pxref{Explicit Encoding}).
In batch mode, Emacs will enlarge the value of the
@code{gc-cons-percentage} variable from the default of @samp{0.1} up to
@samp{1.0}. Batch jobs that are supposed to run for a long time
should adjust the limit back down again, because this means that less
garbage collection will be performed by default (and more memory
consumed).
@defvar noninteractive
This variable is non-@code{nil} when Emacs is running in batch mode.
@end defvar

22
doc/lispref/positions.texi
View file

@ -387,6 +387,16 @@ Return the position that @code{(end-of-line @var{count})}
would move to.
@end defun
@defun pos-bol &optional count
Like @code{line-beginning-position}, but ignores fields (and is more
efficient).
@end defun
@defun pos-eol &optional count
Like @code{line-end-position}, but ignores fields (and is more
efficient).
@end defun
@deffn Command forward-line &optional count
@cindex beginning of line
This function moves point forward @var{count} lines, to the beginning of
@ -1002,6 +1012,12 @@ positions.
In an interactive call, @var{start} and @var{end} are set to the bounds
of the current region (point and the mark, with the smallest first).
Note that, in rare circumstances, Emacs may decide to leave, for
performance reasons, the accessible portion of the buffer unchanged
after a call to @code{narrow-to-region}. This can happen when a Lisp
program is called via low-level hooks, such as
@code{jit-lock-functions}, @code{post-command-hook}, etc.
@end deffn
@deffn Command narrow-to-page &optional move-count
@ -1027,6 +1043,12 @@ It is equivalent to the following expression:
@end example
@end deffn
Note that, in rare circumstances, Emacs may decide to leave, for
performance reasons, the accessible portion of the buffer unchanged
after a call to @code{widen}. This can happen when a Lisp program is
called via low-level hooks, such as @code{jit-lock-functions},
@code{post-command-hook}, etc.
@defun buffer-narrowed-p
This function returns non-@code{nil} if the buffer is narrowed, and
@code{nil} otherwise.

152
doc/lispref/processes.texi
View file

@ -705,12 +705,13 @@ coding system will apply. @xref{Default Coding Systems}.
Initialize the type of device used to communicate with the subprocess.
Possible values are @code{pty} to use a pty, @code{pipe} to use a
pipe, or @code{nil} to use the default derived from the value of the
@code{process-connection-type} variable. This parameter and the value
of @code{process-connection-type} are ignored if a non-@code{nil}
value is specified for the @code{:stderr} parameter; in that case, the
type will always be @code{pipe}. On systems where ptys are not
available (MS-Windows), this parameter is likewise ignored, and pipes
are used unconditionally.
@code{process-connection-type} variable. If @var{type} is a cons cell
@w{@code{(@var{input} . @var{output})}}, then @var{input} will be used
for standard input and @var{output} for standard output (and standard
error if @code{:stderr} is @code{nil}).
On systems where ptys are not available (MS-Windows), this parameter
is ignored, and pipes are used unconditionally.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@ -1242,15 +1243,24 @@ that are already closed, the value is either 0 or 256, depending on
whether the connection was closed normally or abnormally.
@end defun
@defun process-tty-name process
@defun process-tty-name process &optional stream
This function returns the terminal name that @var{process} is using for
its communication with Emacs---or @code{nil} if it is using pipes
instead of a pty (see @code{process-connection-type} in
@ref{Asynchronous Processes}). If @var{process} represents a program
running on a remote host, the terminal name used by that program on
the remote host is provided as process property @code{remote-tty}. If
@var{process} represents a network, serial, or pipe connection, the
value is @code{nil}.
@ref{Asynchronous Processes}). By default, this function returns the
terminal name if any of @var{process}'s standard streams use a
terminal. If @var{stream} is one of @code{stdin}, @code{stdout}, or
@code{stderr}, this function returns the terminal name (or @code{nil},
as above) that @var{process} uses for that stream specifically. You
can use this to determine whether a particular stream uses a pipe or a
pty.
If @var{process} represents a program running on a remote host, this
function returns the @emph{local} terminal name that communicates with
@var{process}; you can get the terminal name used by that program on
the remote host with the process property @code{remote-tty}. If
@var{process} represents a network, serial, or pipe connection, this
function always returns @code{nil}.
@end defun
@defun process-coding-system process
@ -1512,7 +1522,7 @@ This variable is a list of functions to be called for
for @code{signal-process}. These functions are called in the order of
the list, until one of them returns non-@code{nil}. The default
function, which shall always be the last in this list, is
@code{signal-default-interrupt-process}.
@code{internal-default-signal-process}.
This is the mechanism, how Tramp implements @code{signal-process}.
@end defvar
@ -1530,20 +1540,11 @@ a buffer, which is called the associated buffer of the process
default filter discards the output.
If the subprocess writes to its standard error stream, by default
the error output is also passed to the process filter function. If
Emacs uses a pseudo-TTY (pty) for communication with the subprocess,
then it is impossible to separate the standard output and standard
error streams of the subprocess, because a pseudo-TTY has only one
output channel. In that case, if you want to keep the output to those
streams separate, you should redirect one of them to a file---for
example, by using an appropriate shell command via
@code{start-process-shell-command} or a similar function.
Alternatively, you could use the @code{:stderr} parameter with a
the error output is also passed to the process filter function.
Alternatively, you could use the @code{:stderr} parameter with a
non-@code{nil} value in a call to @code{make-process}
(@pxref{Asynchronous Processes, make-process}) to make the destination
of the error output separate from the standard output; in that case,
Emacs will use pipes for communicating with the subprocess.
of the error output separate from the standard output.
When a subprocess terminates, Emacs reads any pending output,
then stops reading output from that subprocess. Therefore, if the
@ -1959,7 +1960,6 @@ because @var{seconds} can be floating point to specify
waiting a fractional number of seconds. If @var{seconds} is 0, the
function accepts whatever output is pending but does not wait.
@c Emacs 22.1 feature
If @var{process} is a process, and the argument @var{just-this-one} is
non-@code{nil}, only output from that process is handled, suspending output
from other processes until some output has been received from that
@ -3204,20 +3204,39 @@ If the vector does not include the port number, @var{p}, or if
@code{:@var{p}} suffix.
@end defun
@defun network-lookup-address-info name &optional family
This function is used to perform hostname lookups on @var{name}, which
is expected to be an ASCII-only string, otherwise an error is
signaled. Call @code{puny-encode-domain} on @var{name}
first if you wish to lookup internationalized hostnames.
@defun network-lookup-address-info name &optional family hints
This function perform hostname lookups on @var{name}, which is
expected to be an ASCII-only string, otherwise it signals an error. Call
@code{puny-encode-domain} on @var{name} first if you wish to lookup
internationalized hostnames.
If successful it returns a list of Lisp representations of network
addresses, otherwise it returns @code{nil}. In the latter case, it
also displays the error message hopefully explaining what went wrong.
If successful, this function returns a list of Lisp representations of network
addresses (@pxref{Network Processes}, for a description of the
format), otherwise return @code{nil}. In the latter case, it also logs
an error message hopefully explaining what went wrong.
By default both IPv4 and IPv6 lookups are attempted. The optional
argument @var{family} controls this behavior, specifying the symbol
@code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6
By default, this function attempts both IPv4 and IPv6 lookups. The
optional argument @var{family} controls this behavior, specifying the
symbol @code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6
respectively.
If optional argument @var{hints} is @code{numeric}, the function
treats the @var{name} as a numerical IP address (and does not perform DNS
lookups). This can be used to check whether a string is a valid
numerical representation of an IP address, or to convert a numerical
string to its canonical representation. e.g.@:
@example
(network-lookup-address-info "127.1" 'ipv4 'numeric)
@result{} ([127 0 0 1 0])
(network-lookup-address-info "::1" nil 'numeric)
@result{} ([0 0 0 0 0 0 0 1 0])
@end example
Be warned that there are some surprising valid forms,
especially for IPv4, e.g @samp{0xe3010203} and @samp{0343.1.2.3} are both
valid, as are @samp{0} and @samp{1} (but they are invalid for IPv6).
@end defun
@node Serial Ports
@ -3493,43 +3512,40 @@ any null bytes in the packed input string will appear in the unpacked
output.
@item strz &optional @var{len}
If @var{len} is not provided: Variable-length null-terminated unibyte
string (@pxref{Text Representations}). When packing, the entire input
string is copied to the packed output. The following byte will be
null (zero) unless a pre-allocated string was provided to
@code{bindat-pack}, in which case that byte is left unmodified. The
length of the packed output is the length of the input string plus one
(for the null terminator). The input string must not contain any null
If @var{len} is not provided, this is a variable-length
null-terminated unibyte string (@pxref{Text Representations}). When
packing into @code{strz}, the entire input string is copied to the
packed output followed by a null (zero) byte. (If pre-allocated
string is provided for packing into @code{strz}, that pre-allocated
string should have enough space for the additional null byte appended
to the output string contents, @pxref{Bindat Functions}). The length
of the packed output is the length of the input string plus one (for
the null terminator). The input string must not contain any null
bytes. If the input string is multibyte with only ASCII and
@code{eight-bit} characters, it is converted to unibyte before it is
packed; other multibyte strings signal an error. When unpacking, the
resulting string contains all bytes up to (but excluding) the null
byte.
packed; other multibyte strings signal an error. When unpacking a
@code{strz}, the resulting output string will contain all bytes up to
(but excluding) the null byte that terminated the input string.
@quotation Caution
If a pre-allocated string is provided to @code{bindat-pack}, the
packed output will not be properly null-terminated unless the
pre-allocated string already has a null byte at the appropriate
location.
@end quotation
If @var{len} is provided, @code{strz} behaves the same as @code{str},
but with a couple of differences:
If @var{len} is provided: @code{strz} behaves the same as @code{str}
with one difference: When unpacking, the first null byte encountered
in the packed string and all subsequent bytes are excluded from the
unpacked result.
@quotation Caution
The packed output will not be null-terminated unless one of the
following is true:
@itemize
@itemize @bullet
@item
The input string is shorter than @var{len} bytes and either no pre-allocated
string was provided to @code{bindat-pack} or the appropriate byte in
the pre-allocated string was already null.
When packing, a null terminator is written after the packed input
string if the number of characters in the input string is less than
@var{len}.
@item
The input string contains a null byte within the first @var{len}
bytes.
When unpacking, the first null byte encountered in the packed string
is interpreted as the terminating byte, and it and all subsequent
bytes are excluded from the result of the unpacking.
@end itemize
@quotation Caution
The packed output will not be null-terminated unless the input string
is shorter than @var{len} bytes or it contains a null byte within the
first @var{len} bytes.
@end quotation
@item vec @var{len} [@var{type}]
@ -3550,7 +3566,7 @@ and @code{#x1c} @code{#x28} to @w{@code{(3 5 10 11 12)}}.
@item fill @var{len}
@var{len} bytes used as a mere filler. In packing, these bytes are
are left unchanged, which normally means they remain zero.
left unchanged, which normally means they remain zero.
When unpacking, this just returns nil.
@item align @var{len}

4
doc/lispref/searching.texi
View file

@ -1898,7 +1898,7 @@ attempts. Other zero-width assertions may also bring benefits by
causing a match to fail early.
@item
Avoid or-patterns in favour of character alternatives: write
Avoid or-patterns in favor of character alternatives: write
@samp{[ab]} instead of @samp{a\|b}. Recall that @samp{\s-} and @samp{\sw}
are equivalent to @samp{[[:space:]]} and @samp{[[:word:]]}, respectively.
@ -1933,7 +1933,7 @@ purposes.
@ifnottex
@item
Consider using @code{rx} (@pxref{Rx Notation}); it can optimise some
Consider using @code{rx} (@pxref{Rx Notation}); it can optimize some
or-patterns automatically and will never introduce capturing groups
unless explicitly requested.
@end ifnottex

14
doc/lispref/sequences.texi
View file

@ -577,6 +577,20 @@ starting from the first one for which @var{predicate} returns @code{nil}.
@end example
@end defun
@defun seq-split sequence length
This function returns a list consisting of sub-sequences of
@var{sequence} of (at most) length @var{length}. (The final element
may be shorter than @var{length} if the length of @var{sequence} isn't
a multiple of @var{length}.
@example
@group
(seq-split [0 1 2 3 4] 2)
@result{} ([0 1] [2 3] [4])
@end group
@end example
@end defun
@defun seq-do function sequence
This function applies @var{function} to each element of
@var{sequence} in turn (presumably for side effects), and returns

25
doc/lispref/strings.texi
View file

@ -560,6 +560,12 @@ Representations}.
@code{string-equal} is another name for @code{string=}.
@end defun
@defun string-equal-ignore-case string1 string2
@code{string-equal-ignore-case} compares strings ignoring case
differences, like @code{char-equal} when @code{case-fold-search} is
@code{t}.
@end defun
@cindex locale-dependent string equivalence
@defun string-collate-equalp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} and @var{string2} are
@ -567,11 +573,19 @@ equal with respect to collation rules. A collation rule is not only
determined by the lexicographic order of the characters contained in
@var{string1} and @var{string2}, but also further rules about
relations between these characters. Usually, it is defined by the
@var{locale} environment Emacs is running with.
@var{locale} environment Emacs is running with and by the Standard C
library against which Emacs was linked@footnote{
For more information about collation rules and their locale
dependencies, see @uref{https://unicode.org/reports/tr10/, The Unicode
Collation Algorithm}. Some Standard C libraries, such as the
@acronym{GNU} C Library (a.k.a.@: @dfn{glibc}) implement large
portions of the Unicode Collation Algorithm and use the associated
locale data, Common Locale Data Repository, or @acronym{CLDR}.
}.
For example, characters with different coding points but
the same meaning might be considered as equal, like different grave
accent Unicode characters:
For example, characters with different code points but the same
meaning, like different grave accent Unicode characters, might, in
some locales, be considered as equal:
@example
@group
@ -759,7 +773,8 @@ The strings are compared by the numeric values of their characters.
For instance, @var{str1} is considered less than @var{str2} if
its first differing character has a smaller numeric value. If
@var{ignore-case} is non-@code{nil}, characters are converted to
upper-case before comparing them. Unibyte strings are converted to
upper-case, using the current buffer's case-table (@pxref{Case
Tables}), before comparing them. Unibyte strings are converted to
multibyte for comparison (@pxref{Text Representations}), so that a
unibyte string and its conversion to multibyte are always regarded as
equal.

46
doc/lispref/text.texi
View file

@ -243,10 +243,8 @@ using a function specified by the variable
The default filter function consults the obsolete wrapper hook
@code{filter-buffer-substring-functions} (see the documentation string
of the macro @code{with-wrapper-hook} for the details about this
obsolete facility), and the obsolete variable
@code{buffer-substring-filters}. If both of these are @code{nil}, it
returns the unaltered text from the buffer, i.e., what
@code{buffer-substring} would return.
obsolete facility). If it is @code{nil}, it returns the unaltered
text from the buffer, i.e., what @code{buffer-substring} would return.
If @var{delete} is non-@code{nil}, the function deletes the text
between @var{start} and @var{end} after copying it, like
@ -282,22 +280,12 @@ the same as those of @code{filter-buffer-substring}.
The first hook function is passed a @var{fun} that is equivalent to
the default operation of @code{filter-buffer-substring}, i.e., it
returns the buffer-substring between @var{start} and @var{end}
(processed by any @code{buffer-substring-filters}) and optionally
deletes the original text from the buffer. In most cases, the hook
function will call @var{fun} once, and then do its own processing of
the result. The next hook function receives a @var{fun} equivalent to
this, and so on. The actual return value is the result of all the
hook functions acting in sequence.
@end defvar
@defvar buffer-substring-filters
The value of this obsolete variable should be a list of functions
that accept a single string argument and return another string.
The default @code{filter-buffer-substring} function passes the buffer
substring to the first function in this list, and the return value of
each function is passed to the next function. The return value of the
last function is passed to @code{filter-buffer-substring-functions}.
returns the buffer-substring between @var{start} and @var{end} and
optionally deletes the original text from the buffer. In most cases,
the hook function will call @var{fun} once, and then do its own
processing of the result. The next hook function receives a @var{fun}
equivalent to this, and so on. The actual return value is the result
of all the hook functions acting in sequence.
@end defvar
@defun current-word &optional strict really-word
@ -2378,6 +2366,9 @@ begins. @xref{Usual Display}.
amount of horizontal scrolling. Consequently, a column value can be
arbitrarily high. The first (or leftmost) column is numbered 0. They
also ignore overlays and text properties, aside from invisibility.
Invisible text is considered as having zero width, unless
@code{buffer-invisibility-spec} specifies that invisible text should
be displayed as ellipsis (@pxref{Invisible Text}).
@defun current-column
This function returns the horizontal position of point, measured in
@ -2451,6 +2442,10 @@ This function returns the indentation of the current line, which is
the horizontal position of the first nonblank character. If the
contents are entirely blank, then this is the horizontal position of the
end of the line.
This function considers invisible text as having zero width, unless
@code{buffer-invisibility-spec} specifies that invisible text should
be displayed as ellipsis. @xref{Invisible Text}.
@end defun
@deffn Command indent-to column &optional minimum
@ -3406,7 +3401,7 @@ for @var{object} is the current buffer.
Search for the next region that has text property @var{prop} set to
@var{value} according to @var{predicate}.
This function is modelled after @code{search-forward} and friends in
This function is modeled after @code{search-forward} and friends in
that it moves point, but it returns a structure that describes the
match instead of returning it in @code{match-beginning} and friends.
@ -3485,7 +3480,7 @@ This will give you a list of all those URLs.
@end defun
@defun text-property-search-backward prop &optional value predicate not-current
This is just like @code{text-property-search-backward}, but searches
This is just like @code{text-property-search-forward}, but searches
backward instead. Point is placed at the beginning of the matched
region instead of the end, though.
@end defun
@ -5478,12 +5473,15 @@ available in this Emacs session.
When libxml2 support is available, the following functions can be used
to parse HTML or XML text into Lisp object trees.
@defun libxml-parse-html-region start end &optional base-url discard-comments
@defun libxml-parse-html-region &optional start end base-url discard-comments
This function parses the text between @var{start} and @var{end} as
HTML, and returns a list representing the HTML @dfn{parse tree}. It
attempts to handle real-world HTML by robustly coping with syntax
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.
@ -5529,7 +5527,7 @@ buffer. The argument @var{dom} should be a list as generated by
@end defun
@cindex parsing xml
@defun libxml-parse-xml-region start end &optional base-url discard-comments
@defun libxml-parse-xml-region &optional start end base-url discard-comments
This function is the same as @code{libxml-parse-html-region}, except
that it parses the text as XML rather than HTML (so it is stricter
about syntax).

16
doc/lispref/tips.texi
View file

@ -689,6 +689,18 @@ line. This looks nice in the source code, but looks bizarre when users
view the documentation. Remember that the indentation before the
starting double-quote is not part of the string!
@item
When documentation should display an ASCII apostrophe or grave accent,
use @samp{\\='} or @samp{\\=`} in the documentation string literal so
that the character is displayed as-is.
@item
In documentation strings, do not quote expressions that are not Lisp symbols,
as these expressions can stand for themselves. For example, write
@samp{Return the list (NAME TYPE RANGE) ...}@: instead of
@samp{Return the list `(NAME TYPE RANGE)' ...}@: or
@samp{Return the list \\='(NAME TYPE RANGE) ...}.
@anchor{Docstring hyperlinks}
@item
@cindex curly quotes
@ -700,7 +712,7 @@ two exceptions: write @code{t} and @code{nil} without surrounding
punctuation. For example:
@example
CODE can be `lambda', nil, or t.
CODE can be `lambda', nil, or t.
@end example
Note that when Emacs displays these doc strings, Emacs will usually
@ -856,7 +868,7 @@ find an alternate phrasing that conveys the meaning.
@item
Try to avoid using abbreviations such as ``e.g.'' (for ``for
example''), ``i.e.'' (for ``that is''), ``no.'' (for ``number''),
``c.f.'' (for ``in contrast to'') and ``w.r.t.'' (for ``with respect
``cf.'' (for ``compare''/``see also'') and ``w.r.t.'' (for ``with respect
to'') as much as possible. It is almost always clearer and easier to
read the expanded version.@footnote{We do use these occasionally, but
try not to overdo it.}

65
doc/lispref/variables.texi
View file

@ -327,7 +327,7 @@ Example of a loop summing a list of numbers:
@anchor{Tail recursion}
Recursive calls to @var{name} that occur in @emph{tail
positions} in @var{body} are guaranteed to be optimised as @emph{tail
positions} in @var{body} are guaranteed to be optimized as @emph{tail
calls}, which means that they will not consume any additional stack
space no matter how deeply the recursion runs. Such recursive calls
will effectively jump to the top of the loop with new values for the
@ -1363,7 +1363,7 @@ disappear without prior notice.
The byte-compiler can also warn about lexical variables that are
special in other Emacs Lisp files, often indicating a missing
@code{defvar} declaration. This useful but somewhat specialised check
@code{defvar} declaration. This useful but somewhat specialized check
requires three steps:
@enumerate
@ -2679,17 +2679,46 @@ cdar nthcdr
A call to any of the following Emacs-specific functions:
@smallexample
alist-get process-get
frame-parameter process-sentinel
terminal-parameter window-buffer
keymap-parent window-display-table
match-data window-dedicated-p
overlay-get window-hscroll
overlay-start window-parameter
overlay-end window-point
process-buffer window-start
process-filter default-value
alist-get overlay-start
default-value overlay-get
face-background process-buffer
face-font process-filter
face-foreground process-get
face-stipple process-sentinel
face-underline-p terminal-parameter
file-modes window-buffer
frame-parameter window-dedicated-p
frame-parameters window-display-table
get-register window-hscroll
getenv window-parameter
keymap-parent window-point
match-data window-start
overlay-end
@end smallexample
@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
where @var{subplace} is itself a valid generalized variable whose
current value is a string, and where the value stored is also a
string. The new string is spliced into the specified part of the
destination string. For example:
@example
(setq a (list "hello" "world"))
@result{} ("hello" "world")
(cadr a)
@result{} "world"
(substring (cadr a) 2 4)
@result{} "rl"
(setf (substring (cadr a) 2 4) "o")
@result{} "o"
(cadr a)
@result{} "wood"
a
@result{} ("hello" "wood")
@end example
@c FIXME? Also 'eq'? (see gv.el)
@end itemize
@noindent
@ -2822,6 +2851,16 @@ expression manipulating @var{place} via @var{getter} and @var{setter}.
Consult the source file @file{gv.el} for more details.
@defun make-obsolete-generalized-variable obsolete-name current-name when
This function makes the byte compiler warn that the generalized
variable @var{obsolete-name} is obsolete. If @var{current-name} is a
symbol, then the warning message says to use @var{current-name}
instead of @var{obsolete-name}. If @var{current-name} is a string,
this is the message. @var{when} should be a string indicating when
the variable was first made obsolete (usually a version number
string).
@end defun
@cindex CL note---no @code{setf} functions
@quotation
@b{Common Lisp note:} Common Lisp defines another way to specify the
@ -2843,7 +2882,7 @@ Common Lisp, this is not an error since the function @code{(setf
it, that value won't be automatically restored. Users usually set
normal variables in their startup files, or use Customize
(@pxref{Customization}) to set user options permanently, and various
packages have various files wher they store the data (e.g., Gnus
packages have various files where they store the data (e.g., Gnus
stores this in @file{.newsrc.eld} and the URL library stores cookies
in @file{~/.emacs.d/url/cookies}).

24
doc/lispref/windows.texi
View file

@ -737,7 +737,7 @@ with any other @var{round} it returns the internal value of
@cindex window width
@cindex width of a window
@cindex total width of a window
The @dfn{total width} of a window is the number of lines comprising its
The @dfn{total width} of a window is the number of columns comprising its
body and its left and right decorations (@pxref{Basic Windows}).
@defun window-total-width &optional window round
@ -747,7 +747,7 @@ the selected window. If @var{window} is internal, the return value is
the total width occupied by its descendant windows.
If a window's pixel width is not an integral multiple of its frame's
character width, the number of lines occupied by the window is rounded
character width, the number of columns occupied by the window is rounded
internally. This is done in a way such that, if the window is a parent
window, the sum of the total widths of all its children internally
equals the total width of their parent. This means that although two
@ -1158,11 +1158,13 @@ frame to its buffer using the command @code{fit-frame-to-buffer}.
This command adjusts the size of @var{frame} to display the contents of
its buffer exactly. @var{frame} can be any live frame and defaults to
the selected one. Fitting is done only if @var{frame}'s root window is
live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
and @var{min-width} specify bounds on the new total size of
@var{frame}'s root window. @var{min-height} and @var{min-width} default
to the values of @code{window-min-height} and @code{window-min-width}
respectively.
live.
The arguments @var{max-height}, @var{min-height}, @var{max-width} and
@var{min-width}, if non-@code{nil}, specify bounds on the new body size
of @var{frame}'s root window. A non-@code{nil} value specified by any
of these arguments overrides the corresponding value specified by
the option @code{fit-frame-to-buffer-sizes} described below.
If the optional argument @var{only} is @code{vertically}, this function
may resize the frame vertically only. If @var{only} is
@ -1187,10 +1189,10 @@ here can be overridden for a specific frame by that frame's
@defopt fit-frame-to-buffer-sizes
This option specifies size boundaries for @code{fit-frame-to-buffer}.
It specifies the total maximum and minimum lines and maximum and minimum
columns of the root window of any frame that shall be fit to its buffer.
If any of these values is non-@code{nil}, it overrides the corresponding
argument of @code{fit-frame-to-buffer}.
It specifies the maximum and minimum lines and maximum and minimum
columns of the root window's body of any frame that shall be fit to its
buffer. Any value this option specifies will be overridden by the
corresponding argument of @code{fit-frame-to-buffer}, if non-@code{nil}.
@end defopt
@deffn Command shrink-window-if-larger-than-buffer &optional window

1
doc/misc/Makefile.in
View file

@ -248,6 +248,7 @@ emacs = "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefe
define org_template
$(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
--eval '(setq gc-cons-threshold 50000000)' \
-f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
endef

16
doc/misc/auth.texi
View file

@ -384,7 +384,7 @@ This function creates a new item in @var{collection} with label
@var{item} and password @var{password}. The label @var{item} does not
have to be unique in @var{collection}. @var{attributes} are key-value
pairs set for the created item. The keys are keyword symbols,
starting with a colon. Example:
starting with a colon; values are strings. Example:
@example
;;; The collection is "session", the label is "my item"
@ -466,6 +466,10 @@ then fall back to @file{~/.authinfo.gpg}.
"~/.authinfo.gpg"))
@end example
Attribute values in the auth-source spec, which are not strings (like
port numbers), are stringified prior calling the @file{secrets.el}
functions.
@node The Unix password store
@chapter The Unix password store
@ -652,14 +656,8 @@ before @file{~/.authinfo}, the auth-source library will try to
read the GnuPG encrypted @file{.gpg} file first, before
the unencrypted file.
In Emacs 23 or later there is an option @code{auto-encryption-mode} to
automatically decrypt @file{*.gpg} files. It is enabled by default.
If you are using earlier versions of Emacs, you will need:
@lisp
(require 'epa-file)
(epa-file-enable)
@end lisp
There is an option @code{auto-encryption-mode} to automatically
decrypt @file{*.gpg} files. It is enabled by default.
If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
or EasyPG Assistant

40
doc/misc/autotype.texi
View file

@ -92,7 +92,6 @@ completions and expansions of text at point.
* Copyrights:: Inserting and updating copyrights.
* Executables:: Turning interpreter scripts into executables.
* Timestamps:: Updating dates and times in modified files.
* QuickURL:: Inserting URLs based on text at point.
* Tempo:: Flexible template insertion.
* Hippie Expand:: Expansion of text trying various methods.
* Skeleton Language:: Making skeleton commands insert what you want.
@ -274,13 +273,13 @@ empty file is visited. This is accomplished by putting
@vindex auto-insert-alist
What gets inserted, if anything, is determined by the variable
@code{auto-insert-alist}. The @sc{car}s of this list are each either
a mode name, making an element applicable when a buffer is in that
mode. Or they can be a string, which is a regexp matched against the
buffer's file name. In that way different kinds of files that have
the same mode in Emacs can be distinguished. The @sc{car}s may also
be cons cells consisting of mode name or regexp as above and an
additional descriptive string.
@code{auto-insert-alist}. The @sc{car} of each element of this list
is either a mode name, making the element applicable when a buffer is
in that mode, or a string, which is a regexp matched against a
buffer's file name (the latter allows to distinguish between different
kinds of files that have the same mode in Emacs). The @sc{car} of an
element may also be a cons cell, consisting of mode name or regexp, as
above, and an additional descriptive string.
When a matching element is found, the @sc{cdr} says what to do. It may
be a string, which is a file name, whose contents are to be inserted, if
@ -478,31 +477,6 @@ The time stamp is written between the brackets or quotes:
Time-stamp: <1998-02-18 10:20:51 gildea>
@end example
@node QuickURL
@chapter QuickURL: Inserting URLs Based on Text at Point
@vindex quickurl-url-file
@findex quickurl
@cindex URLs
@kbd{M-x quickurl} can be used to insert a URL into a buffer based on
the text at point. The URLs are stored in an external file defined by
the variable @code{quickurl-url-file} as a list of either cons cells of
the form @code{(@var{key} . @var{URL})} or
lists of the form @code{(@var{key} @var{URL} @var{comment})}. These
specify that @kbd{M-x quickurl} should insert @var{URL} if the word
@var{key} is at point, for example:
@example
(("FSF" "https://www.fsf.org/" "The Free Software Foundation")
("emacs" . "https://www.gnu.org/software/emacs/"))
@end example
@findex quickurl-add-url
@findex quickurl-list
@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL}
pair. @kbd{M-x quickurl-list} provides interactive editing of the URL
list.
@node Tempo
@chapter Tempo: Flexible Template Insertion

2
doc/misc/calc.texi
View file

@ -1,7 +1,7 @@
\input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
@setfilename ../../info/calc.info
@comment %**start of header (This is for running Texinfo on a region.)
@c smallbook
@setfilename ../../info/calc.info
@c [title]
@settitle GNU Emacs Calc Manual
@include docstyle.texi

94
doc/misc/cl.texi
View file

@ -920,69 +920,6 @@ cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
of the function must itself be a valid @var{place} form.
@item
General Emacs Lisp functions:
@example
buffer-file-name getenv
buffer-modified-p global-key-binding
buffer-name local-key-binding
buffer-string mark
buffer-substring mark-marker
current-buffer marker-position
current-case-table mouse-position
current-column point
current-global-map point-marker
current-input-mode point-max
current-local-map point-min
current-window-configuration read-mouse-position
default-file-modes screen-height
documentation-property screen-width
face-background selected-window
face-background-pixmap selected-screen
face-font selected-frame
face-foreground standard-case-table
face-underline-p syntax-table
file-modes visited-file-modtime
frame-height window-height
frame-parameters window-width
frame-visible-p x-get-secondary-selection
frame-width x-get-selection
get-register
@end example
Most of these have directly corresponding ``set'' functions, like
@code{use-local-map} for @code{current-local-map}, or @code{goto-char}
for @code{point}. A few, like @code{point-min}, expand to longer
sequences of code when they are used with @code{setf}
(@code{(narrow-to-region x (point-max))} in this case).
@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
where @var{subplace} is itself a valid generalized variable whose
current value is a string, and where the value stored is also a
string. The new string is spliced into the specified part of the
destination string. For example:
@example
(setq a (list "hello" "world"))
@result{} ("hello" "world")
(cadr a)
@result{} "world"
(substring (cadr a) 2 4)
@result{} "rl"
(setf (substring (cadr a) 2 4) "o")
@result{} "o"
(cadr a)
@result{} "wood"
a
@result{} ("hello" "wood")
@end example
The generalized variable @code{buffer-substring}, listed above,
also works in this way by replacing a portion of the current buffer.
@c FIXME? Also 'eq'? (see cl-lib.el)
@c Currently commented out in cl.el.
@ignore
@item
@ -1381,19 +1318,10 @@ bar
A @code{setq} of a symbol macro is treated the same as a @code{setf}.
I.e., @code{(setq foo 4)} in the above would be equivalent to
@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
Likewise, a @code{let} or @code{let*} binding a symbol macro is
treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
Common Lisp, where the rules of lexical scoping cause a @code{let}
binding to shadow a @code{symbol-macrolet} binding. In this package,
such shadowing does not occur, even when @code{lexical-binding} is
@c See https://debbugs.gnu.org/12119
@code{t}. (This behavior predates the addition of lexical binding to
Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
At present in this package, only @code{lexical-let} and
@code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
Lexical Binding}.
@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar)
4)}. A @code{let} (or @code{let*}, @code{lambda}, ...) binding of
the same symbol will locally shadow the symbol macro as is the case in
Common Lisp.
There is no analogue of @code{defmacro} for symbol macros; all symbol
macros are local. A typical use of @code{cl-symbol-macrolet} is in the
@ -3756,7 +3684,7 @@ a merged sequence which is (stably) sorted according to
The functions described here operate on lists.
@menu
* List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
* List Functions:: @code{cl-first}, @code{cl-list*}, etc.
* Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
* Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
* Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc.
@ -3769,14 +3697,6 @@ The functions described here operate on lists.
This section describes a number of simple operations on lists,
i.e., chains of cons cells.
@defun cl-caddr x
This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
Likewise, this package aliases all 24 @code{c@var{xxx}r} functions
where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
All of these functions are @code{setf}-able, and calls to them
are expanded inline by the byte-compiler for maximum efficiency.
@end defun
@defun cl-first x
This function is a synonym for @code{(car @var{x})}. Likewise,
the functions @code{cl-second}, @code{cl-third}, @dots{}, through
@ -4553,8 +4473,8 @@ For example,
@end example
@end ignore
Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
have built-in compiler macros to optimize them in common cases.
Note that @code{cl-adjoin} and @code{cl-member} have built-in compiler
macros to optimize them in common cases.
@end defun
@appendixsec Error Checking

172
doc/misc/dired-x.texi
View file

@ -92,7 +92,6 @@ For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}.
* Introduction::
* Installation::
* Omitting Files in Dired::
* Shell Command Guessing::
* Virtual Dired::
* Advanced Mark Commands::
* Multiple Dired Directories::
@ -135,9 +134,6 @@ Some features provided by Dired Extra:
Omitting uninteresting files from Dired listing
(@pxref{Omitting Files in Dired}).
@item
Guessing shell commands in Dired buffers
(@pxref{Shell Command Guessing}).
@item
Running Dired command in non-Dired buffers
(@pxref{Virtual Dired}).
@item
@ -165,10 +161,6 @@ When @file{dired-x.el} is loaded, some standard Dired functions from
Dired}), if it is active. @code{dired-find-buffer-nocreate} and
@code{dired-initial-position} respect the value of
@code{dired-find-subdir} (@pxref{Miscellaneous Commands}).
@code{dired-clean-up-after-deletion} respects the value of
@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses
@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to
offer a smarter default command.
@node Installation
@chapter Installation
@ -186,7 +178,6 @@ In your @file{~/.emacs} file, or in the system-wide initialization file
(with-eval-after-load 'dired
(require 'dired-x)
;; Set dired-x global variables here. For example:
;; (setq dired-guess-shell-gnutar "gtar")
;; (setq dired-x-hands-off-my-keys nil)
))
(add-hook 'dired-mode-hook
@ -438,111 +429,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting
call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup}
in your @code{dired-mode-hook}.
@node Shell Command Guessing
@chapter Shell Command Guessing
@cindex guessing shell commands for files.
Based upon the name of a file, Dired tries to guess what shell
command you might want to apply to it. For example, if you have point
on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
you want to @samp{tar xvf} it and suggest that as the default shell
command.
The default is mentioned in brackets and you can type @kbd{M-n} to get
the default into the minibuffer and then edit it, e.g., to change
@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given
file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
@kbd{M-n} several times to see each of the matching commands.
Dired only tries to guess a command for a single file, never for a list
of marked files.
The following variables control guessing of shell commands:
@defvar dired-guess-shell-alist-default
This variable specifies the predefined rules for guessing shell
commands suitable for certain files. Set this to @code{nil} to turn
guessing off. The elements of @code{dired-guess-shell-alist-user}
(defined by the user) will override these rules.
@end defvar
@defvar dired-guess-shell-alist-user
If non-@code{nil}, this variables specifies the user-defined alist of
file regexps and their suggested commands. These rules take
precedence over the predefined rules in the variable
@code{dired-guess-shell-alist-default} (to which they are prepended)
when @code{dired-do-shell-command} is run). The default is
@code{nil}.
Each element of the alist looks like
@example
(@var{regexp} @var{command}@dots{})
@end example
@noindent
where each @var{command} can either be a string or a Lisp expression
that evaluates to a string. If several commands are given, all of
them will temporarily be pushed onto the history.
A @samp{*} in the shell command stands for the file name that matched
@var{regexp}. When Emacs invokes the @var{command}, it replaces each
instance of @samp{*} with the matched file name.
You can set this variable in your @file{~/.emacs}. For example,
to add rules for @samp{.foo} and @samp{.bar} file extensions, write
@example
(setq dired-guess-shell-alist-user
(list
(list "\\.foo$" "@var{foo-command}");; fixed rule
;; possibly more rules...
(list "\\.bar$";; rule with condition test
'(if @var{condition}
"@var{bar-command-1}"
"@var{bar-command-2}"))))
@end example
@noindent
This will override any predefined rules for the same extensions.
@end defvar
@defvar dired-guess-shell-case-fold-search
If this variable is non-@code{nil},
@code{dired-guess-shell-alist-default} and
@code{dired-guess-shell-alist-user} are matched case-insensitively.
The default is @code{t}.
@end defvar
@cindex passing GNU Tar its @samp{z} switch.
@defvar dired-guess-shell-gnutar
If this variable is non-@code{nil}, it specifies the name of the GNU
Tar executable (e.g., @file{tar} or @file{gnutar}). GNU Tar's
@samp{z} switch is used for compressed archives. If you don't have
GNU Tar, set this to @code{nil}: a pipe using @command{zcat} is then
used instead. The default is @code{nil}.
@end defvar
@cindex @code{gzip}
@defvar dired-guess-shell-gzip-quiet
A non-@code{nil} value of this variable means that @samp{-q} is passed
to @command{gzip}, possibly overriding a verbose option in the @env{GZIP}
environment variable. The default is @code{t}.
@end defvar
@cindex @code{znew}
@defvar dired-guess-shell-znew-switches nil
This variable specifies a string of switches passed to @command{znew}.
An example is @samp{-K} which will make @command{znew} keep a @file{.Z}
file when it is smaller than the @file{.gz} file. The default is
@code{nil}: no additional switches are passed to @command{znew}.
@end defvar
@defvar dired-shell-command-history nil
This variable holds the history list for commands that read
dired-shell commands.
@end defvar
@node Virtual Dired
@chapter Virtual Dired
@ -884,15 +770,6 @@ normal and a wildcard buffer for the same directory, @kbd{C-x d @key{RET}}
will toggle between those two.
@end table
@table @kbd
@findex dired-goto-subdir
@kindex M-G
@item M-G
(@code{dired-goto-subdir}) Go to the header line of an inserted directory.
This command reads its argument, with completion derived from the names of the
inserted subdirectories.
@end table
@table @code
@item dired-vm
@ -920,55 +797,6 @@ to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound.
@findex dired-rmail
Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this
file (assumed to be mail folder in Rmail format).
@item dired-info
@kindex I
@cindex running info.
@findex dired-info
Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info
format).
@vindex dired-bind-info
If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
not be bound to @kbd{I}.
@item dired-man
@cindex running man.
@kindex N
@findex dired-man
Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff}
format).
@vindex dired-bind-man
If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
be bound to @kbd{N}.
@item dired-do-relsymlink
@cindex relative symbolic links.
@kindex Y
@findex dired-do-relsymlink
Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a
directory, or make a relative symbolic link to the current file. This creates
relative symbolic links like
@example
foo -> ../bar/foo
@end example
@noindent
not absolute ones like
@example
foo -> /ugly/path/that/may/change/any/day/bar/foo
@end example
@item dired-do-relsymlink-regexp
@kindex %Y
@findex dired-do-relsymlink-regexp
Bound to @kbd{%Y}. Relative symlink all marked files containing
@var{regexp} to @var{newname}. See functions
@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more
info.
@end table
@node Bugs

4
doc/misc/ede.texi
View file

@ -1551,14 +1551,14 @@ This is a URL to be sent to a web site for documentation.
@item :web-site-directory @*
A directory where web pages can be found by Emacs.
For remote locations use a path compatible with ange-ftp or EFS@.
For remote locations use a path compatible with ange-ftp.
You can also use TRAMP for use with rcp & scp.
@item :web-site-file @*
A file which contains the website for this project.
This file can be relative to slot @code{web-site-directory}.
This can be a local file, use ange-ftp, EFS, or TRAMP.
This can be a local file, use ange-ftp or TRAMP.
@item :ftp-site
Type: @code{string} @*

11
doc/misc/ediff.texi
View file

@ -947,12 +947,14 @@ This function can also be invoked from the Menubar. However, in some
cases, the change will take place only after you execute one of the Ediff
commands, such as going to the next difference or redisplaying.
@c --> The below can be revisited once the toolbar has been ported to Emacs:
@ignore
@item ediff-toggle-use-toolbar
@findex ediff-toggle-use-toolbar
Available in XEmacs only. The Ediff toolbar provides quick access to some
of the common Ediff functions. This function toggles the display of the
toolbar. If invoked from the menubar, the function may take sometimes
effect only after you execute an Ediff command, such as going to the next
The Ediff toolbar provides quick access to some of the common Ediff
functions. This function toggles the display of the toolbar. If
invoked from the menubar, the function may take sometimes effect only
after you execute an Ediff command, such as going to the next
difference.
@item ediff-use-toolbar-p
@ -961,6 +963,7 @@ The use of the toolbar can also be specified via the variable
@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set
only in @file{.emacs}: do @strong{not} change it interactively. Use the
function @code{ediff-toggle-use-toolbar} instead.
@end ignore
@item ediff-revert-buffers-then-recompute-diffs
@findex ediff-revert-buffers-then-recompute-diffs

119
doc/misc/efaq-w32.texi
View file

@ -130,10 +130,8 @@ from Windows 98 onward, and all versions of the NT family starting
from NT 4.0; this includes all the modern versions from Windows XP and
on. The Windows port is built using the Win32 API and supports most
features of the X version, including variable width fonts, images and
tooltips.
Emacs on Windows can be compiled as either a 32-bit or a 64-bit
executable, using the MinGW GCC compiler and development tools.
tooltips. Emacs on Windows can be compiled as either a 64-bit or a
32-bit executable.
@node Other versions of Emacs
@section What other versions of Emacs run on Windows?
@ -177,8 +175,8 @@ best-effort basis in the @file{windows} subdirectory of the above ftp
site (as zip files digitally signed by the person who built them).
See the @file{README} file in that directory for more information.
Building Emacs from source yourself should be straightforward,
following the instructions in @file{nt/INSTALL}, so we encourage you
to give it a try. @xref{Compiling}.
following the instructions in the @file{nt} directory, so we
encourage you to give it a try. @xref{Compiling}.
@cindex latest development version of Emacs
@cindex Emacs Development
@ -190,21 +188,27 @@ development site.
@section How can I compile Emacs myself?
@cindex compiling Emacs
To compile Emacs on Windows, you will need the MinGW port of GCC and
Binutils, the MinGW runtime and development environment, and the MSYS
suite of tools. For the details, see the file @file{nt/INSTALL} in
the Emacs source distribution.
To compile Emacs on a 64-bit version of Windows 7 or newer, we
recommend to use the MinGW-w64 port of GCC and Binutils with the MSYS2
suite of tools. For the details, see the file @file{nt/INSTALL.W64}
in the Emacs source distribution.
If you need to build or run Emacs on MS Windows before Windows 7, you
have to use the MinGW port of GCC and the MSYS suite of tools. The
file @file{nt/INSTALL} in Emacs source distribution contains the
details.
Support for displaying images, as well as XML/HTML rendering and TLS
networking requires external libraries, the headers and import
libraries for which will need to be installed where your compiler can
find them. Again, the details, including URLs of sites where you can
download these libraries are in @file{nt/INSTALL}. @xref{Other useful
ports}, for auxiliary tools you may wish to install and use in
conjunction with Emacs.
download these libraries are in @file{nt/INSTALL.W64} or
@file{nt/INSTALL}. @xref{Other useful ports}, for auxiliary tools you
may wish to install and use in conjunction with Emacs.
After unpacking the source, or checking out of the repository, be sure
to read the instructions in @file{nt/README} and @file{nt/INSTALL}.
to read the instructions in @file{nt/README} and the respective
install file.
@node Debugging
@section How do I use a debugger on Emacs?
@ -222,18 +226,18 @@ specific notes about debugging Emacs.
@cindex debugging Emacs with GDB
GDB is the GNU debugger, which can be used to debug Emacs when it has
been compiled with MinGW GCC@. The best results will be obtained if
you start gdb from the @file{src} directory as @kbd{gdb ./emacs.exe}.
been compiled with GCC@. The best results will be obtained if you
start gdb from the @file{src} directory as @kbd{gdb ./emacs.exe}.
This will load the init file @file{.gdbinit}@footnote{
Latest versions of GDB might refuse to load the init file for security
reasons, unless you customize GDB; alternatively, use an explicit
@kbd{source ./gdbinit} command after entering GDB.
} in that directory, to define some extra commands for working with
lisp while debugging, and set up breakpoints to catch abnormal
aborts.
lisp while debugging, and set up breakpoints to catch abnormal aborts.
A Windows port of GDB can be found on MinGW download sites and on some
others.
A Windows port of GDB is installed with MinGW64-w64 and MSYS2
(@samp{mingw-w64-<arch>-toolchain} group) or can be found on MinGW
download sites and on some others.
@c ------------------------------------------------------------
@node Installing Emacs
@ -307,8 +311,8 @@ bsdtar -xf emacs-@value{EMACSVER}.tar.xz
Expect @command{bsdtar} to unpack the whole distribution without any
complaints.
Once you unpack the source distribution, look in @file{nt/INSTALL}
file for build instructions.
Once you unpack the source distribution, look in the @file{nt}
directory for build instructions.
@node Installing binaries
@section How do I install Emacs after unpacking the binary zip?
@ -926,9 +930,9 @@ an indication of whether the font is outline (.TTF, .ATM) or raster (.FON)
based when fonts are listed, which may let you differentiate between two
fonts with the same name and different technologies.
Starting with Emacs 23, the preferred font name format will be moving
to the simpler and more flexible fontconfig format. XLFD names will
continue to be supported for backward compatibility.
Starting with Emacs 23, the preferred font name format is the simpler
and more flexible fontconfig format. XLFD names will continue to be
supported for backward compatibility.
@example
XLFD: -*-Courier New-normal-r-*-*-13-*-*-*-c-*-iso8859-1
@ -1645,8 +1649,8 @@ obtained the packages from if you want to use them.
In your @env{HOME} directory create a file called @file{.mailcap},
with contents like the following:
@example
application/zip "C:/Program Files/7-Zip/7zFM.exe"
video/* "C:/Program Files/VideoLAN/VLC/vlc.exe"
application/zip; "C:/Program Files/7-Zip/7zFM.exe"
video/*; "C:/Program Files/VideoLAN/VLC/vlc.exe"
@end example
@strong{Warning:} Associating MIME types with @command{start} or other
@ -1754,11 +1758,13 @@ A number of implementations are listed on the
Emacs has support for spell checking on demand (@code{ispell}) and as
your type (@code{flyspell}). Both packages depend on a copy of
@command{ispell} 3.2 or a compatible spell-checking program.
GNU Aspell is a popular choice these days, Windows installers are
available from the @uref{http://aspell.net/win32/, official site}.
GNU Aspell is a popular choice these days, outdated Windows installers
are available from the @uref{http://aspell.net/win32/, official site}.
Another possibility is Hunspell, which is available from
@uref{https://sourceforge.net/projects/ezwinports/files/?source=navbar,
the ezwinports site}.
the ezwinports site}. If you're using the MSYS2 distribution, you can
install a recent version of either GNU Aspell or Hunspell through the
package manager Pacman. @xref{Other useful ports}.
Once installed, you will need to configure @code{ispell-program-name}
to tell ispell and flyspell to use @command{aspell} or
@ -2096,9 +2102,9 @@ suggestions} for improving the interaction of perldb and Emacs.
@menu
* Cygwin::
* MinGW::
* MinGW-w64::
* EZWinPorts::
* UWIN::
* MinGW::
* GnuWin32::
* GTK::
* Read man pages::
@ -2133,22 +2139,25 @@ Cygwin on your system @env{PATH} for this reason. Instead you can
make the Cygwin tools available within Emacs by setting @code{exec-path}
in your init file.
@node MinGW
@section MinGW and MSYS
@cindex mingw tools
@cindex msys environment
@cindex subprocesses, mingw and msys
@node MinGW-w64
@section MinGW-w64 and MSYS2
@cindex mingw-w64 tools
@cindex msys2 environment
@cindex subprocesses, mingw-w64 and msys2
@uref{http://www.mingw.org/}
@uref{https://www.msys2.org/}
MinGW is a set of development tools that produce native Windows
MinGW-w64 is a set of development tools that produce native Windows
executables, not dependent on Cygwin's POSIX emulation DLLs.
MinGW-w64 has forked the original MinGW in 2007 in order to provide
support for 64 bits and new APIs.
MSYS is a POSIX shell and minimal set of tools that are commonly used in
configure scripts. Like Cygwin, this environment uses a non-native
filesystem mapping to appear more POSIX like to the scripts that it
runs. This is intended to complement the MinGW tools to make it easier
to port software to Windows.
MSYS2 is software distribution and a building platform for Windows.
MSYS2 is an independent rewrite of MSYS, based on modern Cygwin and
MinGW-w64 with the aim of better interoperability with native Windows
software. It plays the same role MSYS does in MinGW. Being a
distribution, MSYS2 provides tools to build software as well as more
than 2.600 precompiled packages ready for use.
@node EZWinPorts
@section EZWinPorts
@ -2161,16 +2170,22 @@ software. This includes all the optional libraries used by Emacs
@command{man} command, Grep, xz, bzip2, bsdtar, ID Utils, Findutils,
Hunspell, Gawk, GNU Make, Groff, GDB.
@node UWIN
@section UWIN
@cindex uwin environment
@cindex subprocesses, uwin
@node MinGW
@section MinGW and MSYS
@cindex mingw tools
@cindex msys environment
@cindex subprocesses, mingw and msys
@uref{http://www.research.att.com/sw/tools/uwin/}
@uref{https://osdn.net/projects/mingw/}
UWIN is another POSIX emulation environment, like Cygwin and MSYS,
that provides a large number of ported tools. The shell used by UWIN
is @command{ksh}, the Korn shell.
MinGW is another set of development tools that produce native Windows
executables, not dependent on Cygwin's POSIX emulation DLLs.
MSYS is a POSIX shell and minimal set of tools that are commonly used in
configure scripts. Like Cygwin, this environment uses a non-native
filesystem mapping to appear more POSIX like to the scripts that it
runs. This is intended to complement the MinGW tools to make it easier
to port software to Windows.
@node GnuWin32
@section GnuWin32

272
doc/misc/efaq.texi
View file

@ -27,9 +27,6 @@ latest version of the FAQ is archived.
The FAQ may be copied and redistributed under these conditions, except that
the FAQ may not be embedded in a larger literary work unless that work
itself allows free copying and redistribution.
[This version has been heavily edited since it was included in the Emacs
distribution in 1999.]
@end quotation
@end copying
@ -545,11 +542,11 @@ printed manual}.
@cindex Reference cards, in other languages
@item
You can get a printed reference card listing commands and keys to
invoke them. You can order one from the FSF for $2 (or 10 for $18),
or you can print your own from the @file{etc/refcards/refcard.tex} or
@file{etc/refcards/refcard.pdf} files in the Emacs distribution.
The Emacs distribution comes with translations of the reference card
into several languages; look for files named
invoke them. You can order one from the FSF, or you can print your
own from the @file{etc/refcards/refcard.tex} or
@file{etc/refcards/refcard.pdf} files in the Emacs distribution. The
Emacs distribution comes with translations of the reference card into
several languages; look for files named
@file{etc/refcards/@var{lang}-refcard.*}, where @var{lang} is a
two-letter code of the language. For example, the German version of
the reference card is in the files @file{etc/refcards/de-refcard.tex}
@ -696,9 +693,10 @@ of the file in parentheses, like this:
@item
You can create your own Info directory. You can tell Emacs where that
Info directory is by adding its pathname to the value of the variable
@code{Info-default-directory-list}. For example, to use a private Info
directory which is a subdirectory of your home directory named @file{Info},
you could put this in your @file{.emacs} file:
@code{Info-default-directory-list}. For example, to use a private
Info directory which is a subdirectory of your home directory named
@file{Info}, you could put this in your init file (@pxref{Setting up a
customization file}):
@lisp
(add-to-list 'Info-default-directory-list "~/Info/")
@ -1607,36 +1605,39 @@ is better to write ``Emacs and XEmacs.''
@end menu
@node Setting up a customization file
@section How do I set up a @file{.emacs} file properly?
@section How do I set up an init file properly?
@cindex @file{.emacs} file, setting up
@cindex @file{.emacs} file, locating
@cindex @file{.emacs.d/init.el} file, setting up
@cindex Init file, setting up
@cindex Init file, locating
@cindex Customization file, setting up
When Emacs is started, it normally tries to load a Lisp program from
an @dfn{initialization file}, or @dfn{init file} for short. This
file, if it exists, specifies how to initialize Emacs for you.
Traditionally, file @file{~/.emacs} is used as the init file, although
Emacs also looks at @file{~/.emacs.el}, @file{~/.emacs.d/init.el},
@file{~/.config/emacs/init.el}, or other locations.
@xref{Init File,,, emacs, The GNU Emacs Manual}.
In general, new Emacs users should not be provided with @file{.emacs}
Emacs includes the Customize facility (@pxref{Using Customize}). This
allows users who are unfamiliar with Emacs Lisp to modify their
init files in a relatively straightforward way, using menus
rather than Lisp code.
While Customize might indeed make it easier to configure Emacs,
consider taking a bit of time to learn Emacs Lisp and modifying your
init file directly. Simple configuration options are described
rather completely in @ref{Init File,,, emacs, The GNU Emacs Manual},
for users interested in performing frequently requested, basic tasks.
In general, new Emacs users should not be provided with init
files, because this can cause confusing non-standard behavior. Then
they send questions to
@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs,
the help-gnu-emacs mailing list} asking why Emacs
isn't behaving as documented.
Emacs includes the Customize facility (@pxref{Using Customize}). This
allows users who are unfamiliar with Emacs Lisp to modify their
@file{.emacs} files in a relatively straightforward way, using menus
rather than Lisp code.
While Customize might indeed make it easier to configure Emacs,
consider taking a bit of time to learn Emacs Lisp and modifying your
@file{.emacs} directly. Simple configuration options are described
rather completely in @ref{Init File,,, emacs, The GNU Emacs Manual},
for users interested in performing frequently requested, basic tasks.
Sometimes users are unsure as to where their @file{.emacs} file should
be found. Visiting the file as @file{~/.emacs} from Emacs will find
the correct file.
@node Using Customize
@section How do I start using Customize?
@cindex Customize groups
@ -1743,21 +1744,22 @@ always use custom terminal definition with @samp{setb24} and
@samp{setf24}.
@node Debugging a customization file
@section How do I debug a @file{.emacs} file?
@cindex Debugging @file{.emacs} file
@cindex @file{.emacs} debugging
@section How do I debug an init file?
@cindex Debugging @file{.emacs.d/init.el} file
@cindex Debugging init file
@cindex @file{.emacs.d/init.el} debugging
@cindex Init file debugging
@cindex @samp{-debug-init} option
Start Emacs with the @samp{-debug-init} command-line option. This
enables the Emacs Lisp debugger before evaluating your @file{.emacs}
enables the Emacs Lisp debugger before evaluating your init
file, and places you in the debugger if something goes wrong. The top
line in the @file{trace-back} buffer will be the error message, and the
second or third line of that buffer will display the Lisp code from your
@file{.emacs} file that caused the problem.
init file that caused the problem.
You can also evaluate an individual function or argument to a function
in your @file{.emacs} file by moving the cursor to the end of the
in your init file by moving the cursor to the end of the
function or argument and typing @kbd{C-x C-e} (@kbd{M-x
eval-last-sexp}).
@ -1787,7 +1789,8 @@ You can similarly display the current column with
@end lisp
@noindent
in your @file{.emacs} file. This feature is off by default.
in your init file (@pxref{Setting up a customization file}). This
feature is off by default.
The @code{"%c"} format specifier in the variable @code{mode-line-format}
will insert the current column's value into the mode line. See the
@ -1806,9 +1809,8 @@ optional display. Alternatively, you can use the
customize @code{display-line-numbers-type} with the same value as you
would use with @code{display-line-numbers}.
There is also the @samp{linum} package (distributed with Emacs since
version 23.1) which will henceforth become obsolete. Users and
developers are encouraged to use @samp{display-line-numbers} instead.
There is also the @samp{linum} package which will henceforth become
obsolete. We recommend using @samp{display-line-numbers} instead.
@node Displaying the current file name in the titlebar
@section How can I modify the titlebar to contain the current file name?
@ -1834,7 +1836,7 @@ machine at which Emacs was invoked. This is done by setting
To modify the behavior such that frame titlebars contain the buffer's
name regardless of the number of existing frames, include the following
in your @file{.emacs}:
in your init file (@pxref{Setting up a customization file}):
@lisp
(setq frame-title-format "%b")
@ -1844,9 +1846,10 @@ in your @file{.emacs}:
@section How do I turn on abbrevs by default just in mode @var{mymode}?
@cindex Abbrevs, turning on by default
Abbrev mode expands abbreviations as you type them. To turn it on in a
specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every
buffer by default, put this in your @file{.emacs} file:
Abbrev mode expands abbreviations as you type them. To turn it on in
a specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every
buffer by default, put this in your init file (@pxref{Setting up a
customization file}):
@lisp
(setq-default abbrev-mode t)
@ -1896,7 +1899,8 @@ the script. Use @kbd{C-h v} (or @kbd{M-x describe-variable}) on
@cindex Highlighting and replacing text
Use @code{delete-selection-mode}, which you can start automatically by
placing the following Lisp form in your @file{.emacs} file:
placing the following Lisp form in your init file (@pxref{Setting up a
customization file}):
@lisp
(delete-selection-mode 1)
@ -2034,9 +2038,10 @@ The default maximum line width is 70, determined by the variable
To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
auto-fill-mode}.
To turn it on for every buffer in a certain mode, you must use the hook
for that mode. For example, to turn on @code{auto-fill} mode for all
text buffers, including the following in your @file{.emacs} file:
To turn it on for every buffer in a certain mode, you must use the
hook for that mode. For example, to turn on @code{auto-fill} mode for
all text buffers, including the following in your init file
(@pxref{Setting up a customization file}):
@lisp
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@ -2091,7 +2096,8 @@ option:
emacs -f server-start
@end example
or by invoking @code{server-start} from @file{.emacs}:
or by invoking @code{server-start} from init file (@pxref{Setting up a
customization file}):
@lisp
(if (@var{some conditions are met}) (server-start))
@ -2162,7 +2168,8 @@ f()
@}
@end example
@noindent To achieve this, add the following line to your @file{.emacs}:
@noindent To achieve this, add the following line to your init file
(@pxref{Setting up a customization file}):
@lisp
(c-set-offset 'case-label '+)
@ -2213,7 +2220,8 @@ the line or the block according to what you just specified.
@item
If you don't like the result, go back to step 1. Otherwise, add the
following line to your @file{.emacs}:
following line to your init file (@pxref{Setting up a customization
file}):
@lisp
(c-set-offset '@var{syntactic-symbol} @var{offset})
@ -2243,8 +2251,8 @@ customizations inside a C mode hook, like this:
@noindent
Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
might be unavailable when @code{cc-mode} is not loaded.
'cc-mode)}} into your init file, because @code{c-set-offset} might be
unavailable when @code{cc-mode} is not loaded.
Note that @code{c-mode-hook} runs for C source files only; use
@code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
@ -2316,8 +2324,8 @@ usage: xset [-display host:dpy] option ...
@cindex Previous line, indenting according to
@cindex Text indentation
Such behavior is automatic (in Text mode) in Emacs 20 and later. From the
@file{etc/NEWS} file for Emacs 20.2:
Such behavior is automatic (in Text mode). From the @file{etc/NEWS}
file for Emacs 20.2:
@example
** In Text mode, now only blank lines separate paragraphs. This makes
@ -2355,7 +2363,8 @@ new paragraph. There are many packages available to deal with this
@cindex Pairs of parentheses, highlighting
@cindex Matching parentheses
Call @code{show-paren-mode} in your @file{.emacs} file:
Call @code{show-paren-mode} in your init file (@pxref{Setting up a
customization file}):
@lisp
(show-paren-mode 1)
@ -2460,8 +2469,9 @@ Emacs Lisp @dfn{form}:
@item
If you want it evaluated every time you run Emacs, put it in a file
named @file{.emacs} in your home directory. This is known as ``your
@file{.emacs} file,'' and contains all of your personal customizations.
named @file{.emacs.d/init.el} in your home directory. This is known
as ``your init file,'' and contains all of your personal
customizations (@pxref{Setting up a customization file}).
@item
You can type the form in the @file{*scratch*} buffer, and then type
@ -2499,7 +2509,7 @@ about them.
Set the default value of the variable @code{tab-width}. For example, to set
@key{TAB} stops every 10 characters, insert the following in your
@file{.emacs} file:
init file (@pxref{Setting up a customization file}):
@lisp
(setq-default tab-width 10)
@ -2641,8 +2651,9 @@ Quick command-line switch descriptions are also available. For example,
You probably don't want to do this, since backups are useful, especially
when something goes wrong.
To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
load @code{dired-x} by adding the following to your @file{.emacs} file:
To avoid seeing backup files (and other ``uninteresting'' files) in
Dired, load @code{dired-x} by adding the following to your init file
(@pxref{Setting up a customization file}):
@lisp
(with-eval-after-load 'dired
@ -2651,7 +2662,7 @@ load @code{dired-x} by adding the following to your @file{.emacs} file:
With @code{dired-x} loaded, @kbd{C-x M-o} toggles omitting in each dired buffer.
You can make omitting the default for new dired buffers by putting the
following in your @file{.emacs}:
following in your init file:
@lisp
(add-hook 'dired-mode-hook 'dired-omit-mode)
@ -2891,31 +2902,32 @@ and cause an annoying delay in display, so several features exist to
work around this.
@cindex Just-In-Time syntax highlighting
In Emacs 21 and later, turning on @code{font-lock-mode} automatically
activates the new @dfn{Just-In-Time fontification} provided by
@code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
portions of buffer until you actually need to see them, and can also
fontify while Emacs is idle. This makes display of the visible portion
of a buffer almost instantaneous. For details about customizing
@code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
Turning on @code{font-lock-mode} automatically activates
@dfn{Just-In-Time fontification} provided by @code{jit-lock-mode}.
@code{jit-lock-mode} defers the fontification of portions of buffer
until you actually need to see them, and can also fontify while Emacs
is idle. This makes display of the visible portion of a buffer almost
instantaneous. For details about customizing @code{jit-lock-mode},
type @kbd{C-h f jit-lock-mode @key{RET}}.
@cindex Levels of syntax highlighting
@cindex Decoration level, in @code{font-lock-mode}
In versions of Emacs before 21, different levels of decoration are
available, from slight to gaudy. More decoration means you need to wait
more time for a buffer to be fontified (or a faster machine). To
control how decorated your buffers should become, set the value of
@code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
@code{nil} value indicating default (usually minimum) decoration, and a
@code{t} value indicating the maximum decoration. For the gaudiest
possible look, then, include the line
Different levels of decoration are available, from slight to gaudy.
More decoration means you need to wait more time for a buffer to be
fontified (or a faster machine). To control how decorated your
buffers should become, set the value of
@code{font-lock-maximum-decoration} in your init file (@pxref{Setting
up a customization file}), with a @code{nil} value indicating default
(usually minimum) decoration, and a @code{t} value indicating the
maximum decoration. For the gaudiest possible look, then, include the
line
@lisp
(setq font-lock-maximum-decoration t)
@end lisp
@noindent
in your @file{.emacs} file. You can also set this variable such that
in your init file. You can also set this variable such that
different modes are highlighted in a different ways; for more
information, see the documentation for
@code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
@ -2942,7 +2954,8 @@ customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
to a large value like, say, 10000. For an explanation of what this
means, @pxref{Auto Scrolling,,, emacs, The GNU Emacs Manual}.
Alternatively, use the following Lisp form in your @file{.emacs}:
Alternatively, use the following Lisp form in your init file
(@pxref{Setting up a customization file}):
@lisp
(setq scroll-conservatively most-positive-fixnum)
@ -2971,7 +2984,8 @@ default, a backslash (@samp{\}) will appear in the mode line.
@cindex Single space following periods
@cindex Periods, one space following
Add the following line to your @file{.emacs} file:
Add the following line to your init file (@pxref{Setting up a
customization file}):
@lisp
(setq sentence-end-double-space nil)
@ -2985,11 +2999,7 @@ Add the following line to your @file{.emacs} file:
In many systems, @code{ls} is aliased to @samp{ls --color}, which
prints using ANSI color escape sequences. Emacs includes the
@code{ansi-color} package, which lets Shell mode recognize these
escape sequences. In Emacs 23.2 and later, the package is enabled by
default; in earlier versions you can enable it by typing @kbd{M-x
ansi-color-for-comint-mode} in the Shell buffer, or by adding
@code{(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)} to
your init file.
escape sequences. It is enabled by default.
@node Fullscreen mode on MS-Windows
@section How can I start Emacs in fullscreen mode on MS-Windows?
@ -2997,15 +3007,15 @@ your init file.
@cindex Fullscreen mode
Beginning with Emacs 24.4 either run Emacs with the @samp{--maximized}
command-line option or put the following form in your @file{.emacs}
file:
command-line option or put the following form in your init file
(@pxref{Setting up a customization file}):
@lisp
(add-hook 'emacs-startup-hook 'toggle-frame-maximized)
@end lisp
With older versions use the function @code{w32-send-sys-command}. For
example, you can put the following in your @file{.emacs} file:
example, you can put the following in your init file:
@lisp
(add-hook 'emacs-startup-hook
@ -3063,10 +3073,9 @@ Emacs has an inherent fixed limitation on the size of buffers. This
limit is stricter than the maximum size of objects supported by other
programs on the same architecture.
The maximum buffer size on 32-bit machines is 512 MBytes beginning
with version 23.2. If Emacs was built using the
@code{--with-wide-int} flag, the maximum buffer size on 32-bit
machines is 2 GB.
The maximum buffer size on 32-bit machines is 512 MBytes. If Emacs
was built using the @code{--with-wide-int} flag, the maximum buffer
size on 32-bit machines is 2 GB.
Emacs compiled on a 64-bit machine can handle much larger buffers; up
to @code{most-positive-fixnum} (2.3 exabytes).
@ -3130,8 +3139,8 @@ with the following Lisp form,
The above solutions try to prevent the shell from producing the
@samp{^M} characters in the first place. If this is not possible
(e.g., if you use a Windows shell), you can get Emacs to remove these
characters from the buffer by adding this to your @file{.emacs} init
file:
characters from the buffer by adding this to your init file
(@pxref{Setting up a customization file}):
@smalllisp
(add-hook 'comint-output-filter-functions #'comint-strip-ctrl-m)
@ -3153,8 +3162,8 @@ stty -icrnl -onlcr -echo susp ^Z
@cindex @code{explicit-shell-file-name}
This might happen because Emacs tries to look for the shell in a wrong
place. If you know where your shell executable is, set the variable
@code{explicit-shell-file-name} in your @file{.emacs} file to point to
its full file name.
@code{explicit-shell-file-name} in your init file (@pxref{Setting up a
customization file}) to point to its full file name.
@cindex Antivirus programs, and Shell Mode
Some people have trouble with Shell Mode on MS-Windows because of
@ -3196,18 +3205,18 @@ if ("$term" == emacs) set term=dumb
@node Errors with init files
@section Why does Emacs say @samp{Error in init file}?
@cindex Error in @file{.emacs}
@cindex Error in @file{.emacs.d/init.el}
@cindex Error in init file
@cindex Init file, errors in
@cindex @file{.emacs} file, errors in
@cindex Debugging @file{.emacs} file
@cindex @file{.emacs.d/init.el} file, errors in
@cindex Debugging init file
An error occurred while loading either your @file{.emacs} file or the
An error occurred while loading either your init file or the
system-wide file @file{site-lisp/default.el}. Emacs pops the
@file{*Messages*} buffer, and puts there some additional information
about the error, to provide some hints for debugging.
For information on how to debug your @file{.emacs} file, see
For information on how to debug your init file, see
@ref{Debugging a customization file}.
It may be the case that you need to load some package first, or use a
@ -3493,8 +3502,8 @@ and any Emacs Info files that might be in @file{/usr/local/share/info/}.
@cindex Apple computers, Emacs for
@cindex Macintosh, Emacs for
@cindex macOS, Emacs for
Beginning with version 22.1, Emacs supports macOS natively.
See the file @file{nextstep/INSTALL} in the distribution.
Emacs supports macOS natively. See the file @file{nextstep/INSTALL}
in the distribution.
@cindex FAQ for Emacs on MS-Windows
@cindex Emacs for MS-Windows
@ -3503,8 +3512,8 @@ There is a separate FAQ for Emacs on MS-Windows,
@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}.
@cindex GNUstep, Emacs for
Beginning with version 23.1, Emacs supports GNUstep natively.
See the file @file{nextstep/INSTALL} in the distribution.
Emacs supports GNUstep natively. See the file @file{nextstep/INSTALL}
in the distribution.
@cindex MS-DOS, Emacs for
@cindex DOS, Emacs for
@ -3720,9 +3729,10 @@ information is available from
@cindex Keys, binding to commands
@cindex Commands, binding keys to
Keys can be bound to commands either interactively or in your
@file{.emacs} file. To interactively bind keys for all modes, type
@kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
Keys can be bound to commands either interactively or in your init
file (@pxref{Setting up a customization file}). To interactively bind
keys for all modes, type @kbd{M-x global-set-key @key{RET} @var{key}
@var{cmd} @key{RET}}.
To bind a key just in the current major mode, type @kbd{M-x
local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
@ -3733,7 +3743,7 @@ To make the process of binding keys interactively easier, use the
following ``trick'': First bind the key interactively, then immediately
type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
to bind the key is in the kill ring, and can be yanked into your
@file{.emacs} file. If the key binding is global, no changes to the
init file. If the key binding is global, no changes to the
command are required. For example,
@lisp
@ -3741,9 +3751,9 @@ command are required. For example,
@end lisp
@noindent
can be placed directly into the @file{.emacs} file. If the key binding is
local, the command is used in conjunction with the @samp{add-hook} function.
For example, in TeX mode, a local binding might be
can be placed directly into your init file. If the key binding is
local, the command is used in conjunction with the @samp{add-hook}
function. For example, in TeX mode, a local binding might be
@lisp
(add-hook 'tex-mode-hook
@ -3801,14 +3811,15 @@ of these forms before attempting to bind the key sequence:
@end lisp
@node Terminal setup code works after Emacs has begun
@section Why doesn't this [terminal or window-system setup] code work in my @file{.emacs} file, but it works just fine after Emacs starts up?
@cindex Terminal setup code in @file{.emacs}
@section Why doesn't this [terminal or window-system setup] code work in my init file, but it works just fine after Emacs starts up?
@cindex Terminal setup code in init file
During startup, Emacs initializes itself according to a given code/file
order. If some of the code executed in your @file{.emacs} file needs to
be postponed until the initial terminal or window-system setup code has
been executed but is not, then you will experience this problem (this
code/file execution order is not enforced after startup).
During startup, Emacs initializes itself according to a given
code/file order. If some of the code executed in your init file
(@pxref{Setting up a customization file}) needs to be postponed until
the initial terminal or window-system setup code has been executed but
is not, then you will experience this problem (this code/file
execution order is not enforced after startup).
To postpone the execution of Emacs Lisp code until after terminal or
window-system setup, treat the code as a @dfn{lambda list} and add it to
@ -4229,8 +4240,7 @@ Emacs Manual}. For more sophisticated methods,
@cindex bidirectional scripts
Emacs supports display and editing of bidirectional scripts, such as
Arabic, Farsi, and Hebrew, since version 24.1.
@xref{New in Emacs 24, bidirectional display}.
Arabic, Farsi, and Hebrew.
@node How to add fonts
@ -4258,7 +4268,8 @@ arrange for these two commands to run whenever you log in, e.g., by
adding them to your window-system startup file, such as
@file{~/.xsessionrc} or @file{~/.gnomerc}.
Now, add the following line to your @file{~/.emacs} init file:
Now, add the following line to your init file (@pxref{Setting up a
customization file}):
@lisp
(add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
@ -4268,15 +4279,15 @@ Now, add the following line to your @file{~/.emacs} init file:
(Again, modify the file name if you installed the fonts elsewhere.)
Finally, if you wish to use the installed fonts with @code{ps-print},
add the following line to your @file{~/.emacs}:
add the following line to your init file:
@lisp
(setq ps-multibyte-buffer 'bdf-font-except-latin)
@end lisp
You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
fontset, or you can select it by setting the default font in your
@file{~/.emacs}:
You can now use the Emacs font menu to select the @samp{bdf: 16-dot
medium} fontset, or you can select it by setting the default font in
your init file:
@lisp
(set-frame-font "fontset-bdf")
@ -4338,9 +4349,9 @@ yourself by putting
@end lisp
@noindent
in your @file{.emacs} file. You can automatically include an @samp{FCC}
field by putting something like the following in your @file{.emacs}
file:
in your init file (@pxref{Setting up a customization file}). You can
automatically include an @samp{FCC} field by putting something like
the following in your init file:
@lisp
(setq mail-archive-file-name (expand-file-name "~/outgoing"))
@ -4372,8 +4383,7 @@ To expand them before this, use @kbd{M-x expand-mail-aliases}.
Emacs normally only reads the @file{.mailrc} file once per session, when
you start to compose your first mail message. If you edit the file
after this, you can use @kbd{M-x build-mail-aliases} to make Emacs
reread it. Prior to Emacs 24.1, this is not an interactive command, so
you must instead type @kbd{M-: (build-mail-aliases) @key{RET}}.
reread it.
@item
If you like, you can expand mail aliases as abbrevs, as soon as you
@ -4471,7 +4481,7 @@ gnus
@end example
It is probably unwise to automatically start your mail or news reader
from your @file{.emacs} file. This would cause problems if you needed to run
from your init file. This would cause problems if you needed to run
two copies of Emacs at the same time. Also, this would make it difficult for
you to start Emacs quickly when you needed to.

6
doc/misc/emacs-mime.texi
View file

@ -403,9 +403,9 @@ This selects the function used to render @acronym{HTML}. The
predefined renderers are selected by the symbols @code{shr},
@code{gnus-w3m}, @code{w3m}@footnote{See
@uref{http://emacs-w3m.namazu.org/} for more information about
emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or
@code{html2text}. You can also specify a function, which will be
called with a @acronym{MIME} handle as the argument.
emacs-w3m}, @code{links}, @code{lynx}, or @code{w3m-standalone}. You
can also specify a function, which will be called with a
@acronym{MIME} handle as the argument.
@item mm-html-inhibit-images
@vindex mm-html-inhibit-images

211
doc/misc/erc.texi
View file

@ -545,20 +545,27 @@ Non-interactively, it takes the following keyword arguments.
@item @var{server}
@item @var{port}
@item @var{nick}
@item @var{user}
@item @var{password}
@item @var{full-name}
@item @var{id}
@end itemize
That is, if called with the following arguments, @var{server} and
@var{full-name} will be set to those values, whereas
@code{erc-compute-port} and @code{erc-compute-nick} will be invoked
for the values of the other parameters.
For example, calling the command like so
@example
@example lisp
(erc :server "irc.libera.chat" :full-name "J. Random Hacker")
@end example
@noindent
sets @var{server} and @var{full-name} directly while leaving the rest
up to functions like @code{erc-compute-port}. Note that some
arguments can't be specified interactively. @var{id}, in particular,
is rarely needed (@pxref{Network Identifier}).
@end defun
@noindent
To connect securely over an encrypted TLS connection, use @kbd{M-x
erc-tls}.
@ -570,21 +577,25 @@ Non-interactively, it takes the following keyword arguments.
@item @var{server}
@item @var{port}
@item @var{nick}
@item @var{user}
@item @var{password}
@item @var{full-name}
@item @var{id}
@item @var{client-certificate}
@end itemize
That is, if called with the following arguments, @var{server} and
@var{full-name} will be set to those values, whereas
@code{erc-compute-port} and @code{erc-compute-nick} will be invoked
for the values of the other parameters, and @code{client-certificate}
will be @code{nil}.
That is, if called in the following manner
@example
@example lisp
(erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker")
@end example
@noindent
the command will set @var{server} and @var{full-name} accordingly,
while helpers, like @code{erc-compute-nick}, will determine other
parameters, and some, like @code{client-certificate}, will just be
@code{nil}.
To use a certificate with @code{erc-tls}, specify the optional
@var{client-certificate} keyword argument, whose value should be as
described in the documentation of @code{open-network-stream}: if
@ -719,29 +730,139 @@ ERC should automatically attempt to connect with another nickname.
You can manually set another nickname with the /NICK command.
@end defopt
@subheading User
@defun erc-compute-user &optional user
Determine a suitable value to send as the first argument of the
opening @samp{USER} IRC command by consulting the following sources:
@itemize
@item
@var{user}, the argument passed to this function
@item
The option @code{erc-email-userid}, assuming @code{erc-anonymous-login}
is non-@code{nil}
@item
The result of calling the function @code{user-login-name}
@end itemize
@end defun
@defopt erc-email-userid
A permanent username value to send for all connections. It should be
a string abiding by the rules of the network.
@end defopt
@subheading Password
@cindex password
@defopt erc-prompt-for-password
If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password.
If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls}
prompt for a server password. This only affects interactive
invocations of @code{erc} and @code{erc-tls}.
@end defopt
@noindent
If you prefer, you can set this option to @code{nil} and use the
@code{auth-source} mechanism to store your password. For instance, if
you use @file{~/.authinfo} as your auth-source backend, then put
the option @code{auth-sources} contains @file{~/.authinfo}, put
something like the following in that file:
@example
machine irc.example.net login "#fsf" password sEcReT
machine irc.example.net login mynick password sEcReT
@end example
@noindent
ERC also consults @code{auth-source} to find any channel keys required
for the channels that you wish to autojoin, as specified by the
variable @code{erc-autojoin-channels-alist}.
For server passwords, that is, passwords sent for the IRC @samp{PASS}
command, the @samp{host} field (@w{@code{machine irc.example.net}} in
the above example)
corresponds to the @var{server} parameter used by @code{erc} and
@code{erc-tls}. Unfortunately, specifying a network, like
@samp{Libera.Chat}, or a specific network server, like
@samp{platinum.libera.chat}, won't normally work for looking up a server
password because such information isn't available during opening
introductions. (Actually, ERC @emph{can} find entries with arbitrary
@samp{host} values for any context, including server passwords, but
that requires customizing the more advanced options below.)
For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
If ERC can't find a suitable server password, it will just skip the IRC
@samp{PASS} command altogether, something users may want when using
CertFP or engaging NickServ via ERC's ``services'' module. If that is
what you'd like to do, you can also customize the option
@code{erc-auth-source-server-function} to @code{nil} to skip
server-password lookup for all servers. Note that some networks and
IRCds may accept account-services authentication via server password
using the nonstandard @samp{mynick:sEcReT} convention.
As just mentioned, you can also use @code{auth-source} to authenticate
to account services the traditional way, through a bot called
@samp{NickServ}. To tell ERC to do that, set
@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For
these and most other queries, entries featuring custom identifiers and
networks are matched first, followed by network-specific servers and
dialed endpoints (typically, the @var{server} argument passed to
@code{erc}). The following netrc-style entries appear in order of
precedence:
@example
machine Libera/cellphone login MyNick password sEcReT
machine Libera.Chat login MyNick password sEcReT
machine zirconium.libera.chat login MyNick password sEcReT
machine irc.libera.chat login MyNick password sEcReT
@end example
@noindent
Remember that field labels vary per backend, so @samp{machine} (in
netrc's case) maps to auth-source's generalized notion of a host,
hence the @samp{:host} keyword property. Also, be sure to mind the
syntax of your chosen backend medium. For example, always quote
channel names in a netrc file.
If this all seems overly nuanced or just plain doesn't appeal to you,
see options @code{erc-auth-source-services-function} and friends, described
below. These let you query auth-source your way. Most users can
simply ignore the passed-in arguments and get by with something like
the following:
@lisp
(defun my-fancy-auth-source-func (&rest _)
(let* ((host (read-string "host: " nil nil "default"))
(pass (auth-source-pick-first-password :host host)))
(if (and pass (string-search "libera" host))
(concat "MyNick:" pass)
pass)))
@end lisp
Lastly, ERC also consults @code{auth-source} to find ``keys'' that may
be required by certain channels you join. When modifying a
traditional @code{auth-source} entry for this purpose, put the channel
name in the @samp{user} field (for example, @samp{login "#fsf"}, in
netrc's case). The actual key goes in the @samp{password} (or
@samp{secret}) field.
@noindent
For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
@defopt erc-auth-source-server-function
@end defopt
@defopt erc-auth-source-services-function
@end defopt
@defopt erc-auth-source-join-function
ERC calls these functions with keyword arguments recognized by
@code{auth-source-search}, namely, those deemed most relevant to the
current context, if any. For example, with NickServ queries,
@code{:user} is the ``desired'' nickname rather than the current one.
Generalized names, like @code{:user} and @code{:host}, are always used
over back-end specific ones, like @code{:login} or @code{:machine}.
ERC expects a string to use as the secret or nil, if the search fails.
@findex erc-auth-source-search
The default value for all three options is the function
@code{erc-auth-source-search}. It tries to merge relevant contextual
parameters with those provided or discovered from the logical connection
or the underlying transport. Some auth-source back ends may not be
compatible; netrc, plstore, json, and secrets are currently supported.
@end defopt
@subheading Full name
@ -752,10 +873,14 @@ This tries a number of increasingly more default methods until a
non-@code{nil} value is found.
@itemize @bullet
@item @var{full-name} (the argument passed to this function)
@item The @code{erc-user-full-name} option
@item The value of the IRCNAME environment variable
@item The result from the @code{user-full-name} function
@item
@var{full-name} (the argument passed to this function)
@item
The @code{erc-user-full-name} option
@item
The value of the IRCNAME environment variable
@item
The result from the @code{user-full-name} function
@end itemize
@end defun
@ -766,6 +891,31 @@ User full name.
This can be either a string or a function to call.
@end defopt
@subheading ID
@anchor{Network Identifier}
ERC uses an abstract designation, called @dfn{network context
identifier}, for referring to a connection internally. While normally
derived from a combination of logical and physical connection
parameters, an ID can also be explicitly provided via an entry-point
command (like @code{erc-tls}). Use this in rare situations where ERC
would otherwise have trouble discerning between connections.
One such situation might arise when using multiple connections to the
same network with the same nick but different (nonstandard) @samp{device}
identifiers, which some bouncers may support. Another might be when
mimicking the experience offered by popular standalone clients, which
normally offer ``named'' persistent configurations with server buffers
reflecting those names. Yet another use case might involve
third-party code needing to identify a connection unequivocally, but in
a human-friendly way suitable for UI components.
When providing an ID as an entry-point argument, strings and symbols
make the most sense, but any reasonably printable object is
acceptable.
@node Sample Configuration
@section Sample Configuration
@cindex configuration, sample
@ -827,12 +977,6 @@ stuff, to the current ERC buffer."
(setq erc-autojoin-channels-alist
'(("Libera.Chat" "#emacs" "#erc")))
;; Rename server buffers to reflect the current network name instead
;; of SERVER:PORT (e.g., "Libera.Chat" instead of
;; "irc.libera.chat:6667"). This is useful when using a bouncer like
;; ZNC where you have multiple connections to the same server.
(setq erc-rename-buffers t)
;; Interpret mIRC-style color commands in IRC chats
(setq erc-interpret-mirc-color t)
@ -891,15 +1035,6 @@ lurkers. The function @code{erc-lurker-p} determines whether a given
nickname is considered a lurker.
@end defopt
@defopt erc-rename-buffers
If non, @code{nil}, this will rename server buffers to reflect the
current network name instead of IP:PORT
@example
(setq erc-rename-buffers t)
@end example
@end defopt
@node Getting Help and Reporting Bugs
@chapter Getting Help and Reporting Bugs
@cindex help, getting
@ -924,7 +1059,7 @@ contributors are frequently around and willing to answer your
questions.
@item
To report a bug in ERC, use @kbd{M-x report-emacs-bug}.
To report a bug in ERC, use @kbd{M-x erc-bug}.
@end itemize

4
doc/misc/ert.texi
View file

@ -321,7 +321,7 @@ Show the list of @code{should} forms executed in the test
@kindex m@r{, in ert results buffer}
@findex ert-results-pop-to-messages-for-test-at-point
Show any messages that were generated (with the Lisp function
@code{message}) in in a test or any of the code that it invoked
@code{message}) in a test or any of the code that it invoked
(@code{ert-results-pop-to-messages-for-test-at-point}).
@item L
@ -822,7 +822,7 @@ that's pretty difficult to read and write, especially when the text in
question is multi-line.
So ert provides a function called @code{ert-test-erts-file} that takes
two parameters: The name of a specially-formatted @dfn{erts} file, and
two parameters: the name of a specially-formatted @dfn{erts} file, and
(optionally) a function that performs the transform.
@findex erts-mode

161
doc/misc/eshell.texi
View file

@ -201,7 +201,7 @@ history and invoking commands in a script file.
* Aliases::
* History::
* Completion::
* for loop::
* Control Flow::
* Scripts::
@end menu
@ -219,12 +219,18 @@ same name; if there is no match, it then tries to execute it as an
external command.
The semicolon (@code{;}) can be used to separate multiple command
invocations on a single line. A command invocation followed by an
ampersand (@code{&}) will be run in the background. Eshell has no job
control, so you can not suspend or background the current process, or
bring a background process into the foreground. That said, background
processes invoked from Eshell can be controlled the same way as any
other background process in Emacs.
invocations on a single line. You can also separate commands with
@code{&&} or @code{||}. When using @code{&&}, Eshell will execute the
second command only if the first succeeds (i.e.@: has an exit
status of 0); with @code{||}, Eshell will execute the second command
only if the first fails.
A command invocation followed by an ampersand (@code{&}) will be run
in the background. Eshell has no job control, so you can not suspend
or background the current process, or bring a background process into
the foreground. That said, background processes invoked from Eshell
can be controlled the same way as any other background process in
Emacs.
@node Arguments
@section Arguments
@ -354,11 +360,11 @@ Giving the command @kbd{cd -} changes back to the previous working
directory (this is the same as @kbd{cd $-}).
@item
The command @kbd{cd =} shows the directory stack. Each line is
The command @kbd{cd =} shows the directory ring. Each line is
numbered.
@item
With @kbd{cd =foo}, Eshell searches the directory stack for a directory
With @kbd{cd =foo}, Eshell searches the directory ring for a directory
matching the regular expression @samp{foo}, and changes to that
directory.
@ -845,46 +851,77 @@ For example, you could handle a subset of the options for the
@end defmac
@node Variables
@section Variables
Since Eshell is just an Emacs @acronym{REPL}@footnote{
Short for ``Read-Eval-Print Loop''.
}
, it does not have its own scope, and simply stores variables the same
you would in an Elisp program. Eshell provides a command version of
@code{setq} for convenience.
@subsection Built-in variables
Eshell knows a few built-in variables:
@table @code
@item $+
@vindex $PWD
@vindex $+
@item $PWD
@itemx $+
This variable always contains the current working directory.
@item $-
@vindex $OLDPWD
@vindex $-
@item $OLDPWD
@itemx $-
This variable always contains the previous working directory (the
current working directory from before the last @code{cd} command).
When using @code{$-}, you can also access older directories in the
directory ring via subscripting, e.g.@: @samp{$-[1]} refers to the
working directory @emph{before} the previous one.
@item $_
@vindex $_
It refers to the last argument of the last command.
@item $_
This refers to the last argument of the last command. With a
subscript, you can access any argument of the last command. For
example, @samp{$_[1]} refers to the second argument of the last
command (excluding the command name itself).
@item $$
@vindex $$
This is the result of the last command. In case of an external
command, it is @code{t} or @code{nil}.
@item $$
This is the result of the last command. For external commands, it is
@code{t} if the exit code was 0 or @code{nil} otherwise.
@item $?
@vindex eshell-lisp-form-nil-is-failure
@vindex $?
This variable contains the exit code of the last command (0 or 1 for
Lisp functions, based on successful completion).
@item $?
This variable contains the exit code of the last command. If the last
command was a Lisp function, it is 0 for successful completion or 1
otherwise. If @code{eshell-lisp-form-nil-is-failure} is
non-@code{nil}, then a command with a Lisp form, like
@samp{(@var{command} @var{args}@dots{})}, that returns @code{nil} will
set this variable to 2.
@vindex $COLUMNS
@vindex $LINES
@item $COLUMNS
@itemx $LINES
These variables tell the number of columns and lines, respectively,
that are currently visible in the Eshell window. They are both
copied to the environment, so external commands invoked from
Eshell can consult them to do the right thing.
@item $INSIDE_EMACS
This variable indicates to external commands that they are being
invoked from within Emacs so they can adjust their behavior if
necessary. Its value is @code{@var{emacs-version},eshell}.
@end table
@xref{Aliases}, for the built-in variables @samp{$*}, @samp{$1},
@samp{$2}, @dots{}, in alias definitions.
@node Variables
@section Variables
Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it
does not have its own scope, and simply stores variables the same you
would in an Elisp program. Eshell provides a command version of
@code{setq} for convenience.
@node Aliases
@section Aliases
@ -981,19 +1018,46 @@ command for which this function provides completions; you can also name
the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions
for a specific major mode.
@node for loop
@section @code{for} loop
@node Control Flow
@section Control Flow
Because Eshell commands can not (easily) be combined with lisp forms,
Eshell provides a command-oriented @command{for}-loop for convenience.
The syntax is as follows:
Eshell provides command-oriented control flow statements for
convenience.
@example
@code{for VAR in TOKENS @{ command invocation(s) @}}
@end example
Most of Eshell's control flow statements accept a @var{conditional}.
This can take a few different forms. If @var{conditional} is a dollar
expansion, the condition is satisfied if the result is a
non-@code{nil} value. If @var{conditional} is a @samp{@{
@var{subcommand} @}} or @samp{(@var{lisp form})}, the condition is
satisfied if the command's exit status is 0.
where @samp{TOKENS} is a space-separated sequence of values of
@var{VAR} for each iteration. This can even be the output of a
command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}.
@table @code
@item if @var{conditional} @{ @var{true-commands} @}
@itemx if @var{conditional} @{ @var{true-commands} @} @{ @var{false-commands} @}
Evaluate @var{true-commands} if @var{conditional} is satisfied;
otherwise, evaluate @var{false-commands}.
@item unless @var{conditional} @{ @var{false-commands} @}
@itemx unless @var{conditional} @{ @var{false-commands} @} @{ @var{true-commands} @}
Evaluate @var{false-commands} if @var{conditional} is not satisfied;
otherwise, evaluate @var{true-commands}.
@item while @var{conditional} @{ @var{commands} @}
Repeatedly evaluate @var{commands} so long as @var{conditional} is
satisfied.
@item until @var{conditional} @{ @var{commands} @}
Repeatedly evaluate @var{commands} until @var{conditional} is
satisfied.
@item for @var{var} in @var{list}@dots{} @{ @var{commands} @}
Iterate over each element of of @var{list}, storing the element in
@var{var} and evaluating @var{commands}. If @var{list} is not a list,
treat it as a list of one element. If you specify multiple
@var{lists}, this will iterate over each of them in turn.
@end table
@node Scripts
@section Scripts
@ -1045,7 +1109,7 @@ back to a number as above). For example, @samp{$list("a" "b")c}
returns @samp{("a" "bc")}.
@item anything else
Concatenate the string represenation of each value.
Concatenate the string representation of each value.
@end table
@ -1570,7 +1634,7 @@ integration: using the remote shell's pipelining avoids copying the
data which will flow through the pipeline to local Emacs buffers and
then right back again.
Eshell recognises a special syntax to make it easier to convert
Eshell recognizes a special syntax to make it easier to convert
pipelines so as to bypass Eshell's pipelining. Prefixing at least one
@code{|}, @code{<} or @code{>} with an asterisk marks a command as
intended for the operating system shell. To make it harder to invoke
@ -1588,7 +1652,7 @@ nor the decoded data, into Emacs buffers, as would normally happen.
The command is interpreted as extending up to the next @code{|}
character which is not preceded by an unescaped asterisk following
whitespace, or the end of the input if there is no such character.
Thus, all @code{<} and @code{>} redirections occuring before the next
Thus, all @code{<} and @code{>} redirections occurring before the next
asterisk-unprefixed @code{|} are implicitly prefixed with (whitespace
and) asterisks. An exception is that Eshell-specific redirects right
at the end of the command are excluded. This allows input like this:
@ -1784,11 +1848,6 @@ scrolls back.
@item Menu support was removed, but never put back
@item Using C-p and C-n with rebind gets into a locked state
This happened a few times in Emacs 21, but has been irreproducible
since.
@item If an interactive process is currently running, @kbd{M-!} doesn't work
@item Use a timer instead of @code{sleep-for} when killing child processes
@ -1902,11 +1961,6 @@ glob match.
At the moment, this is not supported.
@item Error if a glob doesn't expand due to a predicate
An error should be generated only if @code{eshell-error-if-no-glob} is
non-@code{nil}.
@item @samp{(+ @key{RET} @key{SPC} @key{TAB}} does not cause @code{indent-according-to-mode} to occur
@item Create @code{eshell-auto-accumulate-list}
@ -2082,11 +2136,10 @@ it).
@item Make the shell spawning commands be visual
That is, make (@command{su}, @command{bash}, @command{telnet},
@command{rlogin}, @command{rsh}, etc.)@: be part of
@code{eshell-visual-commands}. The only exception is if the shell is
being used to invoke a single command. Then, the behavior should be
based on what that command is.
That is, make (@command{su}, @command{bash}, @command{ssh}, etc.)@: be
part of @code{eshell-visual-commands}. The only exception is if the
shell is being used to invoke a single command. Then, the behavior
should be based on what that command is.
@item Create a smart viewing command named @command{open}

21
doc/misc/eudc.texi
View file

@ -292,7 +292,7 @@ LDAP:
(setopt eudc-server-hotlist
'(("" . bbdb)
("ldaps://ldap.gnu.org" . ldap)))
(setopt 'ldap-host-parameters-alist
(setopt ldap-host-parameters-alist
'(("ldaps://ldap.gnu.org"
base "ou=people,dc=gnu,dc=org"
binddn "gnu\\emacsuser"
@ -346,10 +346,10 @@ configure EUDC for LDAP:
@lisp
(with-eval-after-load "message"
(define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all))
(setopt 'eudc-server-hotlist
(setopt eudc-server-hotlist
'(("" . bbdb)
("ldaps://ldap.gnu.org" . ldap)))
(setopt 'ldap-host-parameters-alist
(setopt ldap-host-parameters-alist
'(("ldaps://ldap.gnu.org"
auth-source t)))
@end lisp
@ -376,9 +376,9 @@ and the @file{.emacs} expressions become:
@lisp
(with-eval-after-load "message"
(define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all))
(setopt 'eudc-server-hotlist
(setopt eudc-server-hotlist
'(("" . bbdb) ("" . ldap)))
(setopt 'ldap-host-parameters-alist
(setopt ldap-host-parameters-alist
'(("" auth-source t)))
@end lisp
@ -423,11 +423,12 @@ all macOS versions since 10.0 (which was released 2001).
configurations.
@file{eudcb-mab.el} reverse engineers the format of the database file
used by the macOS Contacts app, and accesses its contents directly.
While this may promise some performance advantages, it comes at the
cost of using an undocumented interface. Hence, users of
@file{eudcb-mab.el} are recommended to double check the compatibility
of @file{eudcb-mab.el} before upgrading to a new version of macOS.
using the external command-line utility named contacts, which needs to
be installed separately. While this may promise some performance
advantages, it comes at the cost of using an undocumented interface.
Hence, users of @file{eudcb-mab.el} are recommended to double check
the compatibility of @file{eudcb-mab.el} and the required, external
command-line utility before upgrading to a new version of macOS.
@file{eudcb-mab.el} is retained for backwards compatibility with
existing configurations, and may be removed in a future release.

4
doc/misc/eww.texi
View file

@ -69,7 +69,7 @@ Indices
@chapter Overview
@dfn{EWW}, the Emacs Web Wowser, is a web browser for GNU Emacs. It
can load, parse, and display various web pages using @dfn{shr.el}.
However a GNU Emacs with @code{libxml2} support is required.
However, a GNU Emacs with @code{libxml2} support is required.
@node Basics
@chapter Basic Usage
@ -213,7 +213,7 @@ switch EWW buffers through a minibuffer prompt, press @kbd{s}
@cindex External Browser
Although EWW and shr.el do their best to render webpages in GNU
Emacs some websites use features which can not be properly represented
or are not implemented (E.g., JavaScript). If you have trouble
or are not implemented (e.g., JavaScript). If you have trouble
viewing a website with EWW then hit @kbd{&}
(@code{eww-browse-with-external-browser}) inside the EWW buffer to
open the website in the external browser specified by

249
doc/misc/gnus-faq.texi
View file

@ -1,7 +1,7 @@
@c \input texinfo @c -*-texinfo-*-
@c Uncomment 1st line before texing this file alone.
@c %**start of header
@c Copyright (C) 1995, 2001--2022 Free Software Foundation, Inc.
@c Copyright (C) 1995--2022 Free Software Foundation, Inc.
@c
@c @setfilename gnus-faq.info
@c @settitle Frequently Asked Questions
@ -13,7 +13,6 @@
@section Frequently Asked Questions
@menu
* FAQ - Changes::
* FAQ - Introduction:: About Gnus and this FAQ.
* FAQ 1 - Installation FAQ:: Installation of Gnus.
* FAQ 2 - Startup / Group buffer:: Start up questions and the
@ -41,21 +40,6 @@ This is the new Gnus Frequently Asked Questions list.
Please submit features and suggestions to the
@email{ding@@gnus.org, ding list}.
@node FAQ - Changes
@subsection Changes
@itemize @bullet
@item
2008-06-15: Adjust for message-fill-column. Add x-face-file.
Clarify difference between ding and gnu.emacs.gnus. Remove
reference to discontinued service.
@item
2006-04-15: Added tip on how to delete sent buffer on exit.
@end itemize
@node FAQ - Introduction
@subsection Introduction
@ -63,11 +47,11 @@ reference to discontinued service.
This is the Gnus Frequently Asked Questions list.
Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented
as a part of Emacs. It's been around in some form for almost a decade
now, and has been distributed as a standard part of Emacs for much of
that time. Gnus 5 is the latest (and greatest) incarnation. The
as a part of Emacs. It's been around in some form since the early
1990s, and has been distributed as a standard part of Emacs for much
of that time. Gnus 5 is the latest (and greatest) incarnation. The
original version was called GNUS, and was written by Masanobu UMEDA@.
When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and
When autumn crept up in 1994, Lars Magne Ingebrigtsen grew bored and
decided to rewrite Gnus.
Its biggest strength is the fact that it is extremely
@ -84,11 +68,6 @@ would like to thank Steve Baur and Per Abrahamsen for doing a wonderful
job with this FAQ before him. We would like to do the same: thanks,
Justin!
This version is much nicer than the unofficial hypertext
versions that are archived at Utrecht, Oxford, Smart Pages, Ohio
State, and other FAQ archives. See the resources question below
if you want information on obtaining it in another format.
The information contained here was compiled with the assistance
of the Gnus development mailing list, and any errors or
misprints are the Gnus team's fault, sorry.
@ -98,11 +77,9 @@ misprints are the Gnus team's fault, sorry.
@menu
* FAQ 1-1:: What is the latest version of Gnus?
* FAQ 1-2:: What's new in 5.10?
* FAQ 1-3:: Where and how to get Gnus?
* FAQ 1-4:: I sometimes read references to No Gnus and Oort Gnus,
* FAQ 1-2:: Where and how to get Gnus?
* FAQ 1-3:: I sometimes read references to No Gnus and Oort Gnus,
what are those?
* FAQ 1-5:: Which version of Emacs do I need?
@end menu
@node FAQ 1-1
@ -112,80 +89,28 @@ What is the latest version of Gnus?
@subsubheading Answer
Jingle please: Gnus 5.10 is released, get it while it's
hot! As well as the step in version number is rather
small, Gnus 5.10 has tons of new features which you
shouldn't miss. The current release (5.13) should be at
least as stable as the latest release of the 5.8 series.
The latest version of Gnus is bundled with Emacs.
@node FAQ 1-2
@subsubheading Question 1.2
What's new in 5.10?
@subsubheading Answer
First of all, you should have a look into the file
GNUS-NEWS in the toplevel directory of the Gnus tarball,
there the most important changes are listed. Here's a
short list of the changes I find especially
important/interesting:
@itemize @bullet
@item
Major rewrite of the Gnus agent, Gnus agent is now
active by default.
@item
Many new article washing functions for dealing with
ugly formatted articles.
@item
Anti Spam features.
@item
Message-utils now included in Gnus.
@item
New format specifiers for summary lines, e.g., %B for
a complex trn-style thread tree.
@end itemize
@node FAQ 1-3
@subsubheading Question 1.3
Where and how to get Gnus?
@subsubheading Answer
Gnus is bundled with Emacs.
@node FAQ 1-4
@subsubheading Question 1.4
@node FAQ 1-3
@subsubheading Question 1.3
I sometimes read references to No Gnus and Oort Gnus,
what are those?
@subsubheading Answer
Oort Gnus was the name of the development version of
Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is
the name of the current development version which will
once become Gnus 5.12 or Gnus 6. (If you're wondering why
not 5.11, the odd version numbers are normally used for
the Gnus versions bundled with Emacs)
@node FAQ 1-5
@subsubheading Question 1.5
Which version of Emacs do I need?
@subsubheading Answer
Gnus 5.13 requires an Emacs version that is greater than or equal
to Emacs 23.1, although there are some features that
only work on Emacs 24.
Oort Gnus was the name of the development version of Gnus, which
became Gnus 5.10 in autumn 2003. No Gnus was the name of the
development version that became Gnus 5.12.
@node FAQ 2 - Startup / Group buffer
@subsection Startup / Group buffer
@ -718,9 +643,8 @@ in @file{~/.gnus.el} to load enough old articles to prevent teared threads, repl
all articles (Warning: Both settings enlarge the amount of data which is
fetched when you enter a group and slow down the process of entering a group).
If you already use Gnus 5.10, you can say
@samp{/o N}
In summary buffer to load the last N messages, this feature is not available in 5.8.8
You can say @samp{/o N} in the summary buffer to load the last N
messages.
If you don't want all old messages, but the parent of the message you're just reading,
you can say @samp{^}, if you want to retrieve the whole thread
@ -820,11 +744,10 @@ Can I use some other browser than w3m to render my HTML-mails?
@subsubheading Answer
Only if you use Gnus 5.10 or younger. In this case you've got the
choice between shr, w3m, links, lynx and html2text, which
one is used can be specified in the variable
mm-text-html-renderer, so if you want links to render your
mail say
You've got the choice between @samp{shr}, @samp{w3m}, @samp{links},
and @samp{lynx}. Which one is used is specified in the variable
@code{mm-text-html-renderer}, so if you want links to render your
mail, say:
@example
(setq mm-text-html-renderer 'links)
@ -847,8 +770,7 @@ long lines'' (@samp{W w}), ``Decode ROT13''
the dumb quoting used by many users of Microsoft products
(@samp{W Y f} gives you full deuglify.
See @samp{W Y C-h} or have a look at the menus for
other deuglifications). Outlook deuglify is only available since
Gnus 5.10.
other deuglifications).
@node FAQ 4-9
@subsubheading Question 4.9
@ -1038,7 +960,7 @@ you'll find useful things like positioning the cursor and
tabulators which allow you a summary in table form, but
sadly hard tabulators are broken in 5.8.8.
Since 5.10, Gnus offers you some very nice new specifiers,
Gnus offers you some very nice new specifiers,
e.g., %B which draws a thread-tree and %&user-date which
gives you a date where the details are dependent of the
articles age. Here's an example which uses both:
@ -1245,7 +1167,7 @@ How to set stuff like From, Organization, Reply-To, signature...?
@subsubheading Answer
There are other ways, but you should use posting styles
for this. (See below why).
for this. (See below why.)
This example should make the syntax clear:
@example
@ -1329,19 +1251,14 @@ Is there a spell-checker? Perhaps even on-the-fly spell-checking?
@subsubheading Answer
You can use ispell.el to spell-check stuff in Emacs. So the
first thing to do is to make sure that you've got either
@uref{https://www.cs.hmc.edu/~geoff/ispell.html, ispell}
or @uref{http://aspell.net, aspell}
installed and in your Path. Then you need
ispell.el
and for on-the-fly spell-checking
@uref{https://www-sop.inria.fr/members/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}.
Ispell.el is shipped with Emacs,
flyspell.el is shipped with Emacs, so there should be no need to install them
manually.
You can use ispell.el to spell-check stuff in Emacs, and flyspell.el
for on-the-fly spell-checking. So the first thing to do is to make
sure that you've got either
@uref{https://hunspell.github.io/, hunspell},
@uref{https://www.cs.hmc.edu/~geoff/ispell.html, ispell} or
@uref{http://aspell.net, aspell} installed and in your Path.
Ispell.el assumes you use ispell, if you choose aspell say
Ispell.el assumes you use ispell. If you use aspell say
@example
(setq ispell-program-name "aspell")
@ -1494,14 +1411,14 @@ Now you only have to tell Gnus to include the X-face in your postings by saying
@end example
@noindent
in @file{~/.gnus.el}. If you use Gnus 5.10, you can simply add an entry
in @file{~/.gnus.el}. You can add an entry
@example
(x-face-file "~/.xface")
@end example
@noindent
to gnus-posting-styles.
to @code{gnus-posting-styles}.
@node FAQ 5-9
@subsubheading Question 5.9
@ -1519,21 +1436,6 @@ Put this in @file{~/.gnus.el}:
@end example
@noindent
if you already use Gnus 5.10, if you still use 5.8.8 or
5.9 try this instead:
@example
(with-eval-after-load "gnus-msg"
(unless (boundp 'gnus-confirm-mail-reply-to-news)
(defadvice gnus-summary-reply (around reply-in-news activate)
"Request confirmation when replying to news."
(interactive)
(when (or (not (gnus-news-group-p gnus-newsgroup-name))
(y-or-n-p "Really reply by mail to article author?"))
ad-do-it))))
@end example
@noindent
@node FAQ 5-10
@subsubheading Question 5.10
@ -1541,14 +1443,7 @@ How to tell Gnus not to generate a sender header?
@subsubheading Answer
Since 5.10 Gnus doesn't generate a sender header by
default. For older Gnus' try this in @file{~/.gnus.el}:
@example
(with-eval-after-load "message"
(add-to-list 'message-syntax-checks '(sender . disabled)))
@end example
@noindent
Gnus doesn't generate a sender header by default.
@node FAQ 5-11
@subsubheading Question 5.11
@ -1729,7 +1624,7 @@ more then one article."
You can now say @samp{M-x
my-archive-article} in summary buffer to
archive the article under the cursor in a nnml
group. (Change nnml to your preferred back end)
group. (Change nnml to your preferred back end.)
Of course you can also make sure the cache is enabled by saying
@ -1756,7 +1651,7 @@ if you found the posting there, tell Google to display
the raw message, look for the message-id, and say
@samp{M-^ the@@message.id @key{RET}} in a
summary buffer.
Since Gnus 5.10 there's also a Gnus interface for
There's a Gnus interface for
groups.google.com which you can call with
@samp{G W}) in group buffer.
@ -1770,25 +1665,6 @@ instead. Further on there are the
gnus-summary-limit-to-foo functions, which can help you,
too.
Of course you can also use grep to search through your
local mail, but this is both slow for big archives and
inconvenient since you are not displaying the found mail
in Gnus. Here nnir comes into action. Nnir is a front end
to search engines like swish-e or swish++ and
others. You index your mail with one of those search
engines and with the help of nnir you can search through
the indexed mail and generate a temporary group with all
messages which met your search criteria. If this sounds
cool to you, get nnir.el from
@c FIXME Isn't this file in Gnus?
@ignore
@c Dead link 2013/7.
@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/}
or
@end ignore
@uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}.
Instructions on how to use it are at the top of the file.
@node FAQ 6-4
@subsubheading Question 6.4
@ -1937,16 +1813,9 @@ So what was this thing about the Agent?
The Gnus agent is part of Gnus, it allows you to fetch
mail and news and store them on disk for reading them
later when you're offline. It kind of mimics offline
newsreaders like Forte Agent. If you want to use
the Agent place the following in @file{~/.gnus.el} if you are
still using 5.8.8 or 5.9 (it's the default since 5.10):
newsreaders like Forte Agent. It is enabled by default.
@example
(setq gnus-agent t)
@end example
@noindent
Now you've got to select the servers whose groups can be
You've got to select the servers whose groups can be
stored locally. To do this, open the server buffer
(that is press @samp{^} while in the
group buffer). Now select a server by moving point to
@ -2051,10 +1920,9 @@ I can't find anything in the Gnus manual about X
@subsubheading Answer
There's not only the Gnus manual but also the manuals for message,
emacs-mime, sieve, EasyPG Assistant, and pgg. Those packages are
distributed with Gnus and used by Gnus but aren't really part of core
Gnus, so they are documented in different info files, you should have
a look in those manuals, too.
emacs-mime, sieve, and EasyPG Assistant. Those packages are
distributed with Emacs and used by Gnus. They are documented in
separate info files, so you should have a look in those manuals, too.
@node FAQ 8-3
@subsubheading Question 8.3
@ -2161,42 +2029,19 @@ How to speed up the process of entering a group?
@subsubheading Answer
A speed killer is setting the variable
gnus-fetch-old-headers to anything different from @code{nil},
so don't do this if speed is an issue. To speed up
building of summary say
A speed killer is setting the variable @code{gnus-fetch-old-headers}
to anything different from @code{nil}, so don't do this if speed is an
issue.
@example
(gnus-compile)
@end example
@noindent
at the bottom of your @file{~/.gnus.el}, this will make gnus
byte-compile things like
gnus-summary-line-format.
then you could increase the value of gc-cons-threshold
by saying something like
You could increase the value of @code{gc-cons-threshold} by saying
something like:
@example
(setq gc-cons-threshold 3500000)
@end example
@noindent
in ~/.emacs. If you don't care about width of CJK
characters or use Gnus 5.10 or younger together with a
recent GNU Emacs, you should say
@example
(setq gnus-use-correct-string-widths nil)
@end example
@noindent
in @file{~/.gnus.el} (thanks to Jesper harder for the last
two suggestions). Finally if you are still using 5.8.8
or 5.9 and experience speed problems with summary
buffer generation, you definitely should update to
5.10 since there quite some work on improving it has
been done.
in ~/.emacs.
@node FAQ 9-3
@subsubheading Question 9.3
@ -2227,10 +2072,6 @@ between core Gnus and the real NNTP-, POP3-, IMAP- or
whatever-server which offers Gnus a standardized interface
to functions like "get message", "get Headers" etc.
@item Emacs
When the term Emacs is used in this FAQ, it means GNU
Emacs.
@item Message
In this FAQ message means either a mail or a posting to a
Usenet Newsgroup or to some other fancy back end, no matter

273
doc/misc/gnus.texi
View file

@ -883,10 +883,7 @@ History
* Gnus Versions:: What Gnus versions have been released.
* Why?:: What's the point of Gnus?
* Compatibility:: Just how compatible is Gnus with @sc{gnus}?
* Conformity:: Gnus tries to conform to all standards.
* Emacsen:: Gnus can be run on a few modern Emacsen.
* Gnus Development:: How Gnus is developed.
* Contributors:: Oodles of people.
* New Features:: Pointers to some of the new stuff in Gnus.
@ -1806,8 +1803,7 @@ long as Gnus is active.
@end menu
You can customize the Group Mode tool bar, see @kbd{M-x
customize-apropos @key{RET} gnus-group-tool-bar}. This feature is only
available in Emacs.
customize-apropos @key{RET} gnus-group-tool-bar}.
The tool bar icons are now (de)activated correctly depending on the
cursor position. Therefore, moving around in the Group Buffer is
@ -4839,8 +4835,7 @@ group buffer (@pxref{Selecting a Group}).
You can have as many summary buffers open as you wish.
You can customize the Summary Mode tool bar, see @kbd{M-x
customize-apropos @key{RET} gnus-summary-tool-bar}. This feature is only
available in Emacs.
customize-apropos @key{RET} gnus-summary-tool-bar}.
@kindex v @r{(Summary)}
@cindex keys, reserved for users (Summary)
@ -5070,7 +5065,7 @@ Opening bracket for adopted articles. The default is @samp{<}.
@item ]
Closing bracket, which is normally @samp{]}, but can also be @samp{>}
for adopted articles. This can be customised using following settings:
for adopted articles. This can be customized using following settings:
@table @code
@item gnus-sum-closing-bracket
@ -8621,14 +8616,6 @@ uuencoded files that have had trailing spaces deleted.
@vindex gnus-uu-pre-uudecode-hook
Hook run before sending a message to @code{uudecode}.
@item gnus-uu-view-with-metamail
@vindex gnus-uu-view-with-metamail
@cindex metamail
Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
commands defined by the rule variables and just fudge a @acronym{MIME}
content type based on the file name. The result will be fed to
@code{metamail} for viewing.
@item gnus-uu-save-in-digest
@vindex gnus-uu-save-in-digest
Non-@code{nil} means that @code{gnus-uu}, when asked to save without
@ -9359,14 +9346,11 @@ Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}.
Use @uref{http://w3m.sourceforge.net/, w3m}.
@item links
Use @uref{https://almende.github.io/chap-links-library/, CHAP Links}.
Use @uref{http://links.twibright.com/, Links}.
@item lynx
Use @uref{https://lynx.browser.org/, Lynx}.
@item html2text
Use html2text---a simple @acronym{HTML} converter included with Gnus.
@end table
@item W D F
@ -11576,8 +11560,8 @@ things to work:
To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to
install an OpenPGP implementation such as GnuPG@. The Lisp interface
to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG,
epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg,
PGG Manual}), and Mailcrypt are also supported.
epa, EasyPG Assistant user's manual}), but Mailcrypt is also
supported.
@item
To handle @acronym{S/MIME} message, you need to install OpenSSL@. OpenSSL 0.9.6
@ -11615,18 +11599,16 @@ public-key matching the @samp{From:} header as the recipient;
@item mml1991-use
@vindex mml1991-use
Symbol indicating elisp interface to OpenPGP implementation for
@acronym{PGP} messages. The default is @code{epg}, but @code{pgg},
and @code{mailcrypt} are also supported although
deprecated. By default, Gnus uses the first available interface in
this order.
@acronym{PGP} messages. The default is @code{epg}, but
@code{mailcrypt} is also supported although deprecated. By default,
Gnus uses the first available interface in this order.
@item mml2015-use
@vindex mml2015-use
Symbol indicating elisp interface to OpenPGP implementation for
@acronym{PGP/MIME} messages. The default is @code{epg}, but
@code{pgg}, and @code{mailcrypt} are also supported
although deprecated. By default, Gnus uses the first available
interface in this order.
@code{mailcrypt} is also supported although deprecated. By default,
Gnus uses the first available interface in this order.
@end table
@ -15440,8 +15422,6 @@ files. If a positive number, delete files older than number of days
(the deletion will only happen when receiving new mail). You may also
set @code{mail-source-delete-incoming} to @code{nil} and call
@code{mail-source-delete-old-incoming} from a hook or interactively.
@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae
and @code{2} in released Gnusae. @xref{Gnus Development}.
@item mail-source-delete-old-incoming-confirm
@vindex mail-source-delete-old-incoming-confirm
@ -17357,11 +17337,6 @@ changes to a wiki (e.g., @url{https://cliki.net/site/recent-changes}).
@acronym{RSS} has a quite regular and nice interface, and it's
possible to get the information Gnus needs to keep groups updated.
Note: you had better use Emacs which supports the @code{utf-8} coding
system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII}
text by default. It is also used by default for non-@acronym{ASCII}
group names.
@kindex G R @r{(Group)}
Use @kbd{G R} from the group buffer to subscribe to a feed---you will be
prompted for the location, the title and the description of the feed.
@ -17410,7 +17385,7 @@ The directory where @code{nnrss} stores its files. The default is
@vindex nnrss-file-coding-system
The coding system used when reading and writing the @code{nnrss} groups
data files. The default is the value of
@code{mm-universal-coding-system} (which defaults to @code{emacs-mule}).
@code{mm-universal-coding-system} (which defaults to @code{utf-8-emacs}).
@item nnrss-ignore-article-fields
@vindex nnrss-ignore-article-fields
@ -17518,16 +17493,16 @@ If you have a directory that has lots of articles in separate files in
it, you might treat it as a newsgroup. The files have to have numerical
names, of course.
This might be an opportune moment to mention @code{ange-ftp} (and its
successor @code{efs}), that most wonderful of all wonderful Emacs
packages. When I wrote @code{nndir}, I didn't think much about it---a
back end to read directories. Big deal.
This might be an opportune moment to mention @code{ange-ftp}, that
most wonderful of all wonderful Emacs packages. When I wrote
@code{nndir}, I didn't think much about it---a back end to read
directories. Big deal.
@code{ange-ftp} changes that picture dramatically. For instance, if you
enter the @code{ange-ftp} file name
@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
@code{ange-ftp} or @code{efs} will actually allow you to read this
directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
@code{ange-ftp} will actually allow you to read this directory over at
@samp{sina} as a newsgroup. Distributed news ahoy!
@code{nndir} will use @acronym{NOV} files if they are present.
@ -21962,7 +21937,7 @@ you can set up a local @acronym{IMAP} server, which you then access via
@code{nnimap}. This is a rather massive setup for accessing some mbox
files, so just change to MH or Maildir already... However, if you're
really, really passionate about using mbox, you might want to look into
the package @file{mairix.el}, which comes with Emacs 23.
the package @file{mairix.el}, which comes with Emacs.
@node What nnmairix does
@subsection What nnmairix does
@ -24216,8 +24191,7 @@ people have started putting nonsense addresses into their @code{From}
lines. I think this is counterproductive---it makes it difficult for
people to send you legitimate mail in response to things you write, as
well as making it difficult to see who wrote what. This rewriting may
perhaps be a bigger menace than the unsolicited commercial email itself
in the end.
perhaps be a bigger menace than the spam itself in the end.
The biggest problem I have with email spam is that it comes in under
false pretenses. I press @kbd{g} and Gnus merrily informs me that I
@ -24243,33 +24217,13 @@ This is annoying. Here's what you can do about it.
@cindex UCE
@cindex unsolicited commercial email
First, some background on spam.
If you have access to e-mail, you are familiar with spam (technically
termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it
exists because e-mail delivery is very cheap compared to paper mail,
so only a very small percentage of people need to respond to an UCE to
make it worthwhile to the advertiser. Ironically, one of the most
common spams is the one offering a database of e-mail addresses for
further spamming. Senders of spam are usually called @emph{spammers},
but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and
@emph{morons} are in common use as well.
Spam comes from a wide variety of sources. It is simply impossible to
dispose of all spam without discarding useful messages. A good
example is the TMDA system, which requires senders
unknown to you to confirm themselves as legitimate senders before
their e-mail can reach you. Without getting into the technical side
of TMDA, a downside is clearly that e-mail from legitimate sources may
be discarded if those sources can't or won't confirm themselves
through the TMDA system. Another problem with TMDA is that it
requires its users to have a basic understanding of e-mail delivery
and processing.
dispose of all spam without discarding useful messages.
The simplest approach to filtering spam is filtering, at the mail
server or when you sort through incoming mail. If you get 200 spam
messages per day from @samp{random-address@@vmadmin.com}, you block
@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you
messages per day from @samp{random-address@@example.org}, you block
@samp{example.org}. If you get 200 messages about @samp{VIAGRA}, you
discard all messages with @samp{VIAGRA} in the message. If you get
lots of spam from Bulgaria, for example, you try to filter all mail
from Bulgarian IPs.
@ -24380,7 +24334,7 @@ In my experience, this will sort virtually everything into the right
group. You still have to check the @samp{spam} group from time to time to
check for legitimate mail, though. If you feel like being a good net
citizen, you can even send off complaints to the proper authorities on
each unsolicited commercial email---at your leisure.
each spam---at your leisure.
This works for me. It allows people an easy way to contact me (they can
just press @kbd{r} in the usual way), and I'm not bothered at all with
@ -24396,8 +24350,8 @@ Be careful with this approach. Spammers are wise to it.
@cindex Vipul's Razor
@cindex DCC
The days where the hints in the previous section were sufficient in
avoiding spam are coming to an end. There are many tools out there
The days where the hints in the previous section were sufficient to
avoid spam are over. There are many tools out there
that claim to reduce the amount of spam you get. This section could
easily become outdated fast, as new products replace old, but
fortunately most of these tools seem to have similar interfaces. Even
@ -24478,7 +24432,7 @@ spam. And here is the nifty function:
@subsection Hashcash
@cindex hashcash
A novel technique to fight spam is to require senders to do something
One technique to fight spam is to require senders to do something
costly and demonstrably unique for each message they send. This has
the obvious drawback that you cannot rely on everyone in the world
using this technique, since it is not part of the Internet standards,
@ -25135,8 +25089,8 @@ The @code{gnus-article-sort-by-chars} entry simplifies detection of
false positives for me. I receive lots of worms (sweN, @dots{}), that all
have a similar size. Grouping them by size (i.e., chars) makes finding
other false positives easier. (Of course worms aren't @i{spam}
(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is
an excellent tool for filtering those unwanted mails for me.)
strictly speaking. Anyhow, bogofilter is an excellent tool for
filtering those unwanted mails for me.)
@item @b{Ham folders:}
@ -26778,7 +26732,7 @@ on finding a separator line between the head and the body. If this
variable is @code{nil}, there is no upper read bound. If it is
@code{t}, the back ends won't try to read the articles piece by piece,
but read the entire articles. This makes sense with some versions of
@code{ange-ftp} or @code{efs}.
@code{ange-ftp}.
@item nnheader-head-chop-length
@vindex nnheader-head-chop-length
@ -26917,10 +26871,7 @@ renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
@menu
* Gnus Versions:: What Gnus versions have been released.
* Why?:: What's the point of Gnus?
* Compatibility:: Just how compatible is Gnus with @sc{gnus}?
* Conformity:: Gnus tries to conform to all standards.
* Emacsen:: Gnus can be run on a few modern Emacsen.
* Gnus Development:: How Gnus is developed.
* Contributors:: Oodles of people.
* New Features:: Pointers to some of the new stuff in Gnus.
@end menu
@ -27000,71 +26951,6 @@ every one of you to explore and invent.
May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs}.
@node Compatibility
@subsection Compatibility
@cindex compatibility
Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
bindings have been kept. More key bindings have been added, of course,
but only in one or two obscure cases have old bindings been changed.
Our motto is:
@quotation
@cartouche
@center In a cloud bones of steel.
@end cartouche
@end quotation
All commands have kept their names. Some internal functions have changed
their names.
The @code{gnus-uu} package has changed drastically. @xref{Decoding
Articles}.
One major compatibility question is the presence of several summary
buffers. All variables relevant while reading a group are
buffer-local to the summary buffer they belong in. Although many
important variables have their values copied into their global
counterparts whenever a command is executed in the summary buffer, this
change might lead to incorrect values being used unless you are careful.
All code that relies on knowledge of @sc{gnus} internals will probably
fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
changing it in any way, as a matter of fact) is strictly verboten. Gnus
maintains a hash table that points to the entries in this alist (which
speeds up many functions), and changing the alist directly will lead to
peculiar results.
@cindex hilit19
@cindex highlighting
Old hilit19 code does not work at all. In fact, you should probably
remove all hilit code from all Gnus hooks
(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
Gnus provides various integrated functions for highlighting. These are
faster and more accurate. To make life easier for everybody, Gnus will
by default remove all hilit calls from all hilit hooks. Uncleanliness!
Away!
Packages like @code{expire-kill} will no longer work. As a matter of
fact, you should probably remove all old @sc{gnus} packages (and other
code) when you start using Gnus. More likely than not, Gnus already
does what you have written code to make @sc{gnus} do. (Snicker.)
Even though old methods of doing things are still supported, only the
new methods are documented in this manual. If you detect a new method of
doing something while reading this manual, that does not mean you have
to stop doing it the old way.
Gnus understands all @sc{gnus} startup files.
@findex gnus-bug
@cindex reporting bugs
@cindex bugs
Overall, a casual user who hasn't written much code that depends on
@sc{gnus} internals should suffer no problems. If problems occur,
please let me know by issuing that magic command @kbd{M-x gnus-bug}.
@node Conformity
@subsection Conformity
@ -27147,79 +27033,6 @@ mentioned above, don't hesitate to drop a note to Gnus Towers and let us
know.
@node Emacsen
@subsection Emacsen
@cindex Emacsen
@cindex Mule
@cindex Emacs
This version of Gnus should work on:
@itemize @bullet
@item
Emacs 23.1 and up.
@end itemize
This Gnus version will absolutely not work on any Emacsen older than
that. Not reliably, at least. Older versions of Gnus may work on older
Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs
20.7.
@c No-merge comment: The paragraph added in v5-10 here must not be
@c synced here!
@node Gnus Development
@subsection Gnus Development
Gnus is developed in a two-phased cycle. The first phase involves much
discussion on the development mailing list @samp{ding@@gnus.org}, where people
propose changes and new features, post patches and new back ends. This
phase is called the @dfn{alpha} phase, since the Gnusae released in this
phase are @dfn{alpha releases}, or (perhaps more commonly in other
circles) @dfn{snapshots}. During this phase, Gnus is assumed to be
unstable and should not be used by casual users. Gnus alpha releases
have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}.
After futzing around for 10--100 alpha releases, Gnus is declared
@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix,
and is called things like ``Gnus 5.10.1'' instead. Normal people are
supposed to be able to use these, and these are mostly discussed on the
@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the
mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane
as @samp{gmane.emacs.gnus.user}. These releases are finally integrated
in Emacs.
@cindex Incoming*
@vindex mail-source-delete-incoming
Some variable defaults differ between alpha Gnusae and released Gnusae,
in particular, @code{mail-source-delete-incoming}. This is to prevent
lossage of mail if an alpha release hiccups while handling the mail.
@xref{Mail Source Customization}.
The division of discussion between the ding mailing list and the Gnus
newsgroup is not purely based on publicity concerns. It's true that
having people write about the horrible things that an alpha Gnus release
can do (sometimes) in a public forum may scare people off, but more
importantly, talking about new experimental features that have been
introduced may confuse casual users. New features are frequently
introduced, fiddled with, and judged to be found wanting, and then
either discarded or totally rewritten. People reading the mailing list
usually keep up with these rapid changes, while people on the newsgroup
can't be assumed to do so.
So if you have problems with or questions about the alpha versions,
direct those to the ding mailing list @samp{ding@@gnus.org}. This list
is also available on Gmane as @samp{gmane.emacs.gnus.general}.
@cindex Incoming*
@vindex mail-source-delete-incoming
Some variable defaults differ between alpha Gnusae and released Gnusae,
in particular, @code{mail-source-delete-incoming}. This is to prevent
lossage of mail if an alpha release hiccups while handling the mail.
@xref{Mail Source Customization}.
@node Contributors
@subsection Contributors
@cindex contributors
@ -29796,19 +29609,6 @@ Ahem.
@item
Make sure your computer is switched on.
@item
Make sure that you really load the current Gnus version. If you have
been running @sc{gnus}, you need to exit Emacs and start it up again before
Gnus will work.
@item
Try doing an @kbd{M-x gnus-version}. If you get something that looks
like @c
@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line!
@c
you have the right files loaded. Otherwise you have some old @file{.el}
files lying around. Delete these.
@item
Read the help group (@kbd{G h} in the group buffer) for a
@acronym{FAQ} and a how-to.
@ -29817,7 +29617,7 @@ Read the help group (@kbd{G h} in the group buffer) for a
@vindex max-lisp-eval-depth
Gnus works on many recursive structures, and in some extreme (and very
rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at
you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or
you. If this happens to you, set @code{max-lisp-eval-depth} to 2000 or
something like that.
@end enumerate
@ -29828,10 +29628,9 @@ If all else fails, report the problem as a bug.
@findex gnus-bug
If you find a bug in Gnus, you can report it with the @kbd{M-x
gnus-bug} command. @kbd{M-x set-variable @key{RET} debug-on-error
@key{RET} t @key{RET}}, and send me the backtrace. I will fix bugs,
but I can only fix them if you send me a precise description as to how
to reproduce the bug.
gnus-bug} command. @kbd{M-x toggle-debug-on-error}, and send me the
backtrace. I will fix bugs, but I can only fix them if you send me a
precise description as to how to reproduce the bug.
You really can never be too detailed in a bug report. Always use the
@kbd{M-x gnus-bug} command when you make bug reports, even if it creates
@ -29862,7 +29661,7 @@ edebug. Debugging Lisp code is documented in the Elisp manual
(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs
Lisp Reference Manual}). To get you started with edebug, consider if
you discover some weird behavior when pressing @kbd{c}, the first
step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in
step is to do @kbd{C-h k c} and click on the hyperlink in
the documentation buffer that leads you to the function definition,
then press @kbd{M-x edebug-defun @key{RET}} with point inside that function,
return to Gnus and press @kbd{c} to invoke the code. You will be
@ -29874,7 +29673,7 @@ evaluate expressions using @kbd{M-:} or inspect variables using
@cindex elp
@cindex profile
@cindex slow
Sometimes, a problem do not directly generate an elisp error but
Sometimes, a problem do not directly generate an Emacs Lisp error but
manifests itself by causing Gnus to be very slow. In these cases, you
can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are
slow, and then try to analyze the backtrace (repeating the procedure

12
doc/misc/htmlfontify.texi
View file

@ -10,8 +10,7 @@
This manual documents Htmlfontify, a source code -> crosslinked +
formatted + syntax colorized html transformer.
Copyright @copyright{} 2002--2003, 2013--2022 Free Software Foundation,
Inc.
Copyright @copyright{} 2002--2022 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@ -34,7 +33,7 @@ modify this GNU manual.''
@titlepage
@title Htmlfontify User Manual
@sp 4
@subtitle Htmlfontify version 0.20
@subtitle Htmlfontify version 0.21
@sp 1
@subtitle Jun 2002
@sp 5
@ -1539,13 +1538,6 @@ Htmlfontify has a couple of external requirements:
@itemize @bullet
@item
GNU Emacs 20.7+ or 21.1+
Other versions may work---these have been used successfully by the
author. If you intend to use Htmlfontify in batch mode, 21.1+ is
pretty much required.
@item
A copy of etags (exuberant-ctags or GNU etags). Htmlfontify attempts
to autodetect the version you have and customize itself accordingly,

49
doc/misc/idlwave.texi
View file

@ -217,7 +217,7 @@ Integrity checks and auto-termination of logical blocks.
@item
Routine name space conflict search with likelihood-of-use ranking.
@item
Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
Support for @file{imenu}.
@item
Documentation support.
@item
@ -392,7 +392,7 @@ that IDLWAVE has many more capabilities than covered here, which can
be discovered by reading the entire manual, or hovering over the
shoulder of your nearest IDLWAVE guru for a few days.
It is assumed that you have access to Emacs or XEmacs with the full
It is assumed that you have access to Emacs with the full
IDLWAVE package including online help. We also assume that you are
familiar with Emacs and can read the nomenclature of key presses in
Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for
@ -1011,9 +1011,9 @@ Non-@code{nil} means use last match on line for
@cindex Font lock
Highlighting of keywords, comments, strings etc.@: can be accomplished
with @code{font-lock}. If you are using @code{global-font-lock-mode}
(in Emacs), or have @code{font-lock} turned on in any other buffer in
XEmacs, it should also automatically work in IDLWAVE buffers. If you'd
with @code{font-lock}. If you are using @code{global-font-lock-mode},
or have @code{font-lock-mode} turned on in any other buffer,
it should also automatically work in IDLWAVE buffers. If you'd
prefer invoking font-lock individually by mode, you can enforce it in
@code{idlwave-mode} with the following line in your @file{.emacs}:
@ -2298,12 +2298,11 @@ Regexp matching the start of a document library header.
@cindex Motion commands
@cindex Program structure, moving through
@cindex Code structure, moving through
@cindex @file{Func-menu}, XEmacs package
@cindex @file{Imenu}, Emacs package
@cindex @file{Imenu}
@cindex Function definitions, jumping to
@cindex Procedure definitions, jumping to
IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
IDLWAVE supports @file{Imenu}, a package
which make it easy to jump to the definitions of functions and
procedures in the current file with a pop-up selection. To bind
@file{Imenu} to a mouse-press, use in your @file{.emacs}:
@ -4022,7 +4021,7 @@ user is King!
IDLWAVE was developed on a UNIX system. However, thanks to the
portability of Emacs, much of IDLWAVE does also work under different
operating systems like Windows (with NTEmacs or NTXEmacs).
operating systems like Windows (with NTEmacs).
The only real problem is that there is no command-line version of IDL
for Windows with which IDLWAVE can interact. As a
@ -4117,24 +4116,6 @@ configuration files (e.g., @file{.cshrc}), but from the file
@file{~/.MacOSX/environment.plist}. Either include your path settings
there, or start Emacs and IDLWAVE from the shell.
@item @strong{I get errors like @samp{Symbol's function is void:
overlayp}}
You don't have the @samp{fsf-compat} package installed, which IDLWAVE
needs to run under XEmacs. Install it, or find an XEmacs distribution
which includes it by default.
@item @strong{I'm getting errors like @samp{Symbol's value as variable is void:
cl-builtin-gethash} on completion or routine info.}
This error arises if you upgraded Emacs from 20.x to 21.x without
re-installing IDLWAVE@. Old Emacs and new Emacs are not byte-compatible
in compiled lisp files. Presumably, you kept the original .elc files in
place, and this is the source of the error. If you recompile (or just
"make; make install") from source, it should resolve this problem.
Another option is to recompile the @file{idlw*.el} files by hand using
@kbd{M-x byte-compile-file}.
@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
windows on my desktop.}
@ -4262,20 +4243,6 @@ is updated).
Starting with IDL 6.2, the HTML help and its catalog are
distributed with IDL, and so should never be inconsistent.
@item @strong{I get errors such as @samp{void-variable
browse-url-browser-function} or similar when attempting to load IDLWAVE
under XEmacs.}
You don't have the @samp{browse-url} (or other required) XEmacs package.
Unlike Emacs, XEmacs distributes many packages separately from the
main program. IDLWAVE is actually among these, but is not always the
most up to date. When installing IDLWAVE as an XEmacs package, it
should prompt you for required additional packages. When installing it
from source, it won't and you'll get this error. The easiest solution
is to install all the packages when you install XEmacs (the so-called
@samp{sumo} bundle). The minimum set of XEmacs packages required by
IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}.
@end enumerate
@node GNU Free Documentation License

18
doc/misc/message.texi
View file

@ -1152,12 +1152,11 @@ programs are required to make things work, and some small general hints.
@uref{https://www.gnupg.org/, GNU Privacy Guard} or
@uref{https://www.openssl.org/, OpenSSL}. The default Emacs interface
to the S/MIME implementation is EasyPG (@pxref{Top,,EasyPG Assistant
User's Manual, epa, EasyPG Assistant User's Manual}), which has been
included in Emacs since version 23 and which relies on the command
line tool @command{gpgsm} provided by @acronym{GnuPG}. That tool
implements certificate management, including certificate revocation
and expiry, while such tasks need to be performed manually, if OpenSSL
is used.
User's Manual, epa, EasyPG Assistant User's Manual}), which is
included in Emacs and relies on the command line tool @command{gpgsm}
provided by @acronym{GnuPG}. That tool implements certificate
management, including certificate revocation and expiry, while such
tasks need to be performed manually, if OpenSSL is used.
The choice between EasyPG and OpenSSL is controlled by the variable
@code{mml-smime-use}, which needs to be set to the value @code{epg}
@ -1250,8 +1249,8 @@ as @uref{https://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
implementations such as PGP 2.x and PGP 5.x are also supported. The
default Emacs interface to the PGP implementation is EasyPG
(@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant
User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and
Mailcrypt are also supported. @xref{PGP Compatibility}.
User's Manual}), but Mailcrypt is also supported. @xref{PGP
Compatibility}.
As stated earlier, messages encrypted with OpenPGP can be formatted
according to two different standards, namely @acronym{PGP} or
@ -1340,8 +1339,7 @@ your PGP implementation, so we refer to it.
If you have imported your old PGP 2.x key into GnuPG, and want to send
signed and encrypted messages to your fellow PGP 2.x users, you'll
discover that the receiver cannot understand what you send. One
solution is to use PGP 2.x instead (e.g., if you use @code{pgg}, set
@code{pgg-default-scheme} to @code{pgp}). You could also convince your
solution is to use PGP 2.x instead. You could also convince your
fellow PGP 2.x users to convert to GnuPG@.
@vindex mml-signencrypt-style-alist
As a final workaround, you can make the sign and encryption work in

103
doc/misc/mh-e.texi
View file

@ -213,10 +213,8 @@ more niceties about GNU Emacs and MH@. Now I'm fully hooked on both of
them.
The MH-E package is distributed with Emacs@footnote{Version
@value{VERSION} of MH-E appeared in Emacs 24.4. It is supported in GNU
Emacs 23 and higher, as well as XEmacs 21.4.22 and 21.5.31. MH-E is
known not to work with GNU Emacs versions 20 and below, and XEmacs
version 21.5.9--21.5.16. It is compatible with MH versions 6.8.4 and
@value{VERSION} of MH-E appeared in Emacs 24.4.
It is compatible with MH versions 6.8.4 and
higher, all versions of nmh, and GNU mailutils 1.0 and higher}, so you
shouldn't have to do anything special to use it. Gnus is also
required; version 5.10 or higher is recommended. This manual covers
@ -1490,7 +1488,7 @@ Binding} of @samp{m}.
@cindex Unix commands, @command{xbuffy}
You can use @command{xbuffy} to automate the incorporation of this
mail using the Emacs 23 command @command{emacsclient} as follows:
mail using the Emacs command @command{emacsclient} as follows:
@smallexample
box ~/mail/mh-e
@ -1501,9 +1499,6 @@ box ~/mail/mh-e
command emacsclient --eval '(mh-inc-spool-mh-e)'
@end smallexample
In XEmacs, the command @command{gnuclient} is used in a similar
fashion.
@findex mh-inc-folder
@kindex i
@vindex mh-inc-folder-hook
@ -2090,8 +2085,7 @@ and @samp{X-Image-URL:} will be used. The option
This feature will be turned on by default if your system supports it.
The first header field used, if present, is the Gnus-specific
@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU
Emacs 21 and XEmacs. For more information, see
@samp{Face:} field@footnote{For more information, see
@uref{https://quimby.gnus.org/circus/face/}.}.
@cindex @command{uncompface}
@ -2104,12 +2098,9 @@ Emacs 21 and XEmacs. For more information, see
Next is the traditional @samp{X-Face:} header field@footnote{The
display of this field requires the
@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z,
@command{uncompface} program}. Recent versions of XEmacs have internal
support for @samp{X-Face:} images. If your version of XEmacs does not,
then you'll need both @command{uncompface} and the
@uref{http://www.jpl.org/ftp/pub/elisp/, @samp{x-face} package}.}. MH-E
renders the foreground and background of the image using the
associated attributes of the face @code{mh-show-xface}.
@command{uncompface} program}.} MH-E renders the foreground and
background of the image using the associated attributes of the face
@code{mh-show-xface}.
@cindex @command{convert}
@cindex @command{wget}
@ -2562,13 +2553,6 @@ produces pretty nice output, and it highlights links. It renders
@samp{&ndash;} and @samp{&reg;} okay. It sometimes fails to wrap lines
properly. It always downloads remote images.
@c -------------------------
@cindex browser, @samp{html2text}
@cindex @samp{html2text}
@item @samp{html2text}
The @samp{html2text} browser requires an external program. Some users
have reported problems with it, such as filling the entire message as
if it were one paragraph, or displaying chunks of raw HTML.
@c -------------------------
@cindex browser, @samp{links}
@cindex @samp{links}
@item @samp{links}
@ -2830,24 +2814,6 @@ The appearance of the buttons is controlled by the faces
@code{mh-show-pgg-unknown} depending on the validity of the signature.
The latter is used whether the signature is unknown or untrusted.
@cindex @samp{pgg} customization group
@cindex PGG
@cindex customization group, @samp{pgg}
The @samp{pgg} customization group may have some settings which may
interest you.
@iftex
See @cite{The PGG Manual}.
@end iftex
@ifinfo
@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
@end ifinfo
@ifhtml
See
@uref{https://www.gnu.org/software/emacs/manual/pgg.html,
@cite{The PGG Manual}}.
@end ifhtml
@node Printing
@section Printing Your Mail
@ -5594,33 +5560,6 @@ variety of mail security mechanisms. The default is @samp{PGP (MIME)}
if it is supported; otherwise, the default is @samp{None}. Other
mechanisms include vanilla @samp{PGP} and @samp{S/MIME}.
@cindex @samp{pgg} customization group
@cindex PGG
@cindex customization group, @samp{pgg}
The @samp{pgg} customization group may have some settings which may
interest you.
@iftex
See @cite{The PGG Manual}.
@end iftex
@ifinfo
@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
@end ifinfo
@ifhtml
See
@uref{https://www.gnu.org/software/emacs/manual/pgg.html,
@cite{The PGG Manual}}.
@end ifhtml
@cindex header field, @samp{Fcc}
@cindex @samp{Fcc} header field
@vindex pgg-encrypt-for-me
In particular, I turn on the option @code{pgg-encrypt-for-me} so that
all messages I encrypt are encrypted with my public key as well. If
you keep a copy of all of your outgoing mail with a @samp{Fcc:} header
field, this setting is vital so that you can read the mail you write!
@node Checking Recipients
@section Checking Recipients
@ -6448,17 +6387,9 @@ too long to list here).
@item mh-tool-bar-search-function
Function called by the tool bar search button (default:
@code{mh-search}).
@c -------------------------
@item mh-xemacs-tool-bar-position
Tool bar location (default: @samp{Same As Default Tool Bar}).
@c -------------------------
@item mh-xemacs-use-tool-bar-flag
If @samp{on}, use tool bar (default: @samp{on}, if supported).
@end vtable
In GNU Emacs, icons for some of MH-E's functions are added to the tool
bar. In XEmacs, you have the opportunity to create a separate tool bar for
the MH-E icons.
Icons for some of MH-E's functions are added to the tool bar.
@vindex mh-tool-bar-folder-buttons
@vindex mh-tool-bar-letter-buttons
@ -6480,24 +6411,6 @@ option @code{mh-tool-bar-search-function}. By default, this is set to
Function} from the @samp{Value Menu} and enter a function of your own
choosing.
@vindex mh-xemacs-use-tool-bar-flag
XEmacs provides a couple of extra options. The first,
@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E
icons at all. By default, this option is turned on if the window
system supports tool bars. If your system doesn't support tool bars,
then you won't be able to turn on this option.
@vindex mh-xemacs-tool-bar-position
The second extra option is @code{mh-xemacs-tool-bar-position} which
controls the placement of the tool bar along the four edges of the
frame. You can choose from one of @samp{Same As Default Tool Bar},
@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this
variable is set to anything other than @samp{Same As Default Tool Bar}
and the default tool bar is in a different location, then two tool
bars will be displayed: the MH-E tool bar and the default tool bar.
@node Searching
@chapter Searching Through Messages

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