Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-16 09:14:18 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into scratch/etags-regen

Browse source
This commit is contained in:
Dmitry Gutov 2022-07-11 14:17:45 +03:00
commit d4875e1235
1509 changed files with 176274 additions and 62620 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.dir-locals.el
View file

@ -10,7 +10,9 @@
((("c" "objc") .
("/[ \t]*DEFVAR_[A-Z_ \t(]+\"\\([^\"]+\\)\"/\\1/"
"/[ \t]*DEFVAR_[A-Z_ \t(]+\"[^\"]+\",[ \t]\\([A-Za-z0-9_]+\\)/\\1/"))))
(etags-regen-ignores . ("test/manual/etags/"))))
(etags-regen-ignores . ("test/manual/etags/"))
(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"))
(electric-quote-comment . nil)

1
.gitignore vendored
View file

@ -221,6 +221,7 @@ lisp/international/emoji-zwj.el
lisp/international/emoji-labels.el
lisp/international/eucjp-ms.el
lisp/international/uni-*.el
lisp/international/idna-mapping.el
lisp/language/pinyin.el
# Documentation.

49
CONTRIBUTE
View file

@ -314,11 +314,42 @@ 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. 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
@ -366,6 +397,22 @@ reasons. These should be marked by including something like "Do not
merge to master" or anything that matches gitmerge-skip-regexp (see
admin/gitmerge.el) in the commit message.
** Some packages in Emacs are maintained externally
Sometimes a package that ships as part of GNU Emacs is maintained as a
separate project, with its own upstream repository, its own maintainer
group, its own development conventions, etc. The upstream project's
code is periodically merged into Emacs (exactly when and how such
merges happen depends on the package).
So when you are making a contribution -- such as fixing a bug or
proposing an enhancement -- to one of these externally maintained
packages, you sometimes need to deal with that package at its upstream
source.
In the section "Externally maintained packages" in "admin/MAINTAINERS"
we maintain a list of such packages.
** GNU ELPA
This repository does not contain the Emacs Lisp package archive

2818
ChangeLog.3
View file

File diff suppressed because it is too large Load diff

50
INSTALL
View file

@ -4,11 +4,13 @@ Inc.
See the end of the file for license conditions.
This file contains general information on building GNU Emacs.
For more information specific to the MS-Windows, GNUstep/macOS, and
MS-DOS ports, also read the files nt/INSTALL, nextstep/INSTALL, and
msdos/INSTALL. For information about building from a repository checkout
(rather than a release), also read the file INSTALL.REPO.
This file contains general information on building GNU Emacs. For
more information specific to the MS-Windows, GNUstep/macOS, and MS-DOS
ports, also read the files nt/INSTALL, nextstep/INSTALL, and
msdos/INSTALL.
For information about building from a Git checkout (rather than an
Emacs release), read the INSTALL.REPO file first.
BASIC INSTALLATION
@ -226,6 +228,38 @@ e.g. 'emacs25'). On Red Hat-based systems, the corresponding command is
On FreeBSD, the command is 'pkg install -y `pkg rquery %dn emacs-devel`'.
* Alternative window systems
If you want to use Emacs on one of the alternative window systems
available on GNU/Linux and some Unix systems, such as Wayland or
Broadway, you can build the PGTK ("Pure GTK") port of Emacs, which
utilizes the GTK+ toolkit to support those window systems. To this
end, invoke the configure script with the '--with-pgtk' option, like
this:
./configure --with-pgtk
This build is only supported with GTK+ version 3, and it is an error
to specify any other X-specific configuration option when PGTK is
enabled.
If you use exclusively X, do not use the PGTK port. There are a
number of respects in which the regular --with-x-toolkit=gtk build
works better. The PGTK port should not be considered a simple upgrade
from --with-x-toolkit=gtk.
With the PGTK build, you will be able to switch between running Emacs
on X, Wayland and Broadway using the 'GDK_BACKEND' environment
variable. GTK+ should automatically detect and use the correct value
for your system, but you can also specify it manually. For example,
to force GTK+ to run under Broadway, start Emacs like this:
GDK_BACKEND=broadway emacs ...
(where '...' denotes any further options you may want to pass to Emacs).
The GNUstep build also supports the Wayland window system. If that is
what you want, see nextstep/INSTALL.
DETAILED BUILDING AND INSTALLATION:
@ -324,9 +358,9 @@ Use --without-toolkit-scroll-bars to disable Motif or Xaw3d scroll bars.
Use --without-xim to inhibit the default use of X Input Methods.
In this case, the X resource useXIM can be used to turn on use of XIM.
Use --with-xinput2 to enable the use of version 2 of the X Input
Extension. This enables support for touchscreens, pinch gestures, and
scroll wheels that report scroll deltas at pixel-level precision.
Use --without-xinput2 to disable the use of version 2 of the X Input
Extension. This disables support for touchscreens, pinch gestures,
and scroll wheels that report scroll deltas at pixel-level precision.
Use --disable-largefile to omit support for files larger than 2GB, and
--disable-year2038 to omit support for timestamps past the year 2038,

6
Makefile.in
View file

@ -319,6 +319,9 @@ GLIB_COMPILE_SCHEMAS = glib-compile-schemas
# Program name transformation.
TRANSFORM = @program_transform_name@
# Prevent any settings in the user environment causing problems.
unexport EMACSDATA EMACSDOC EMACSLOADPATH EMACSPATH
# What emacs should be called when installed.
EMACS_NAME = `echo emacs | sed '$(TRANSFORM)'`
EMACS = ${EMACS_NAME}${EXEEXT}
@ -691,8 +694,6 @@ install-etcdoc: src install-arch-indep
printf 'Copying %s to %s ...\n' "etc/$$docfile" \
"$(DESTDIR)${etcdocdir}"; \
${INSTALL_DATA} etc/$${docfile} "$(DESTDIR)${etcdocdir}/$${docfile}"; \
$(set_installuser); \
chown $${installuser} "$(DESTDIR)${etcdocdir}/$${docfile}" || true ; \
else true; fi
## FIXME:
@ -964,6 +965,7 @@ bootstrap-clean: $(distclean_dirs:=_bootstrap-clean)
[ ! -f config.log ] || mv -f config.log config.log~
rm -rf ${srcdir}/info
rm -f ${srcdir}/etc/refcards/emacsver.tex
rm -rf native-lisp/ lisp/leim/ja-dic/
${top_bootclean}
### 'maintainer-clean'

31
admin/CPP-DEFINES
View file

@ -24,6 +24,7 @@ DARWIN_OS Compiling on macOS or pure Darwin (and using s/darwin.h).
SOLARIS2
USG
USG5_4
HAIKU Compiling on Haiku.
** Distinguishing GUIs **
@ -32,16 +33,38 @@ HAVE_NS Use the NeXT/OpenStep/Cocoa UI under macOS or GNUstep.
NS_IMPL_GNUSTEP Compile support for GNUstep implementation of NS GUI API.
NS_IMPL_COCOA Compile support for Cocoa (Apple) implementation of NS GUI API.
HAVE_X11 Compile support for the X11 GUI.
HAVE_PGTK Compile support for using GTK itself without directly using X Windows APIs.
HAVE_HAIKU Compile support for the Haiku window system.
HAVE_X_WINDOWS Compile support for X Window system
(It looks like, nowadays, if HAVE_X11 is set, HAVE_X_WINDOWS must
be, and vice versa. At least, this is true for configure, and
msdos; not sure about nt.)
HAVE_X11R6
HAVE_X11R6_XIM
HAVE_X11XTR6
** X Windows features **
HAVE_X11R6 Whether or not the system has X11R6. (Always defined.)
HAVE_X11R6_XIM Whether or not the system supports XIM features introduced in R6.
HAVE_X11XTR6 Whether or not the Xt is from X11R6 or newer.
USE_LUCID Use the Lucid toolkit for menus&scrollbars. Requires HAVE_X11.
USE_MOTIF Use the Motif toolkit for menus&scrollbars. Requires HAVE_X11.
USE_GTK Use the Gtk toolkit for menus&scrollbars. Requires HAVE_X11.
USE_GTK Use the Gtk toolkit for menus&scrollbars. Requires HAVE_X11 or HAVE_PGTK.
HAVE_GTK3 Use GTK version 3 or later. Requires HAVE_X11.
HAVE_XCB_SHAPE Whether or not XCB supports the Nonrectangular Window Shape extension.
HAVE_XCOMPOSITE Whether or not the XCOMPOSITE extension library is present.
HAVE_XDBE Whether or not to use the Xdbe extension for double buffering.
HAVE_XFIXES Whether or not the Xfixes extension library is present.
HAVE_XINERAMA Whether or not the Xinerama extension library is present.
HAVE_XINPUT2 Whether or not to use version 2 of the X Input Extension for input.
HAVE_XINPUT2_1 Whether or not version 2.1 of the X Input Extension is supported.
HAVE_XINPUT2_2 Whether or not version 2.2 of the X Input Extension is supported.
HAVE_XINPUT2_3 Whether or not version 2.3 of the X Input Extension is supported.
HAVE_XINPUT2_4 Whether or not version 2.4 of the X Input Extension is supported.
HAVE_XKB Whether or not the XKB extension library is present.
HAVE_XRANDR Whether or not the RandR extension library is present.
HAVE_XSHAPE Whether or not the Nonrectangular Window Shape extension library is present.
HAVE_XSYNC Whether or not the X Synchronization Extension library is present.
USE_XCB Whether or not the XCB library is used to optimize some X requests.
** Frame types **

31
admin/MAINTAINERS
View file

@ -275,14 +275,6 @@ Vibhav Pant
lisp/net/browse-url.el
lisp/erc/*
Alan Third
The NS port:
nextstep/*
src/ns*
src/*.m
lisp/term/ns-win.el
doc/emacs/macos.texi
Amin Bandali
Eshell
lisp/eshell/*
@ -304,6 +296,8 @@ Tramp
Repository: git://git.savannah.gnu.org/tramp.git
Mailing List: tramp-devel@gnu.org
Bug Reports: M-x tramp-bug
Notes: For backward compatibility requirements, see
lisp/net/trampver.el.
lisp/net/tramp*.el
doc/misc/tramp*.texi
@ -311,11 +305,30 @@ Tramp
Modus themes
Maintainer: Protesilaos Stavrou
Repository and issue tracker: https://gitlab.com/protesilaos/modus-themes
Repository: https://git.sr.ht/~protesilaos
Mailing list: https://lists.sr.ht/~protesilaos/modus-themes
Bug Reports: M-x modus-themes-report-bug
doc/misc/modus-themes.org
etc/themes/modus*.el
Org Mode
Home Page: https://orgmode.org/
Maintainer: Org Mode developers
Repository: git://git.sv.gnu.org/emacs/org-mode.git
Mailing list: emacs-orgmode@gnu.org
Bug Reports: M-x org-submit-bug-report
Notes: Org Mode is maintained as a separate project that is
periodically merged into Emacs. To view or participate in
Org Mode development, please go to https://orgmode.org/ and
follow the instructions there.
lisp/org/*.el
etc/org/*
etc/refcards/orgcard.tex
doc/misc/org.org
doc/misc/org-setup.org
;;; Local Variables:
;;; coding: utf-8

156
admin/admin.el
View file

@ -351,11 +351,13 @@ Optional argument TYPE is type of output (nil means all)."
\"https://www.w3.org/TR/html4/loose.dtd\">\n\n")
(defconst manual-meta-string
"<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\">
<link rev=\"made\" href=\"mailto:bug-gnu-emacs@gnu.org\">
"<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\">\n")
(defconst manual-links-string
"<link rev=\"made\" href=\"mailto:bug-gnu-emacs@gnu.org\">
<link rel=\"icon\" type=\"image/png\" href=\"/graphics/gnu-head-mini.png\">
<meta name=\"ICBM\" content=\"42.256233,-71.006581\">
<meta name=\"DC.title\" content=\"gnu.org\">\n\n")
<meta name=\"DC.title\" content=\"gnu.org\">\n")
(defconst manual-style-string "<style type=\"text/css\">
@import url('/software/emacs/manual.css');\n</style>\n")
@ -486,6 +488,13 @@ 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")
(when (search-forward "<link href=" nil t)
(goto-char (match-beginning 0)))
(insert manual-links-string)
(setq opoint (point))
(search-forward "</head>")
(goto-char (match-beginning 0))
(delete-region opoint (point))
@ -602,76 +611,81 @@ style=\"text-align:left\">")
(forward-line 1)
(setq done t)))))
(let (done open-td tag desc)
;; Convert the list that Makeinfo made into a table.
(or (search-forward "<ul class=\"menu\">" nil t)
;; FIXME? The following search seems dangerously lax.
(search-forward "<ul>"))
(replace-match "<table style=\"float:left\" width=\"100%\">")
(forward-line 1)
(while (not done)
(cond
((or (looking-at "<li>\\(<a.+</a>\\):[ \t]+\\(.*\\)$")
(looking-at "<li>\\(<a.+</a>\\)$"))
(setq tag (match-string 1))
(setq desc (match-string 2))
(replace-match "" t t)
(when open-td
(save-excursion
(forward-char -1)
(skip-chars-backward " ")
(delete-region (point) (line-end-position))
(insert "</td>\n </tr>")))
(insert " <tr>\n ")
(if table-workaround
;; This works around a Firefox bug in the mono file.
(insert "<td bgcolor=\"white\">")
(insert "<td>"))
(insert tag "</td>\n <td>" (or desc ""))
(setq open-td t))
((eq (char-after) ?\n)
(delete-char 1)
;; Negate the following `forward-line'.
(forward-line -1))
((looking-at "<!-- ")
(search-forward "-->"))
((looking-at "<p>[- ]*The Detailed Node Listing[- \n]*")
(replace-match " </td></tr></table>\n
;; Texinfo 6.8 and later doesn't produce <ul class="menu"> lists
;; for the TOC menu, and the "description" part of each menu
;; item is not there anymore. So for HTML manuals produced by
;; those newer versions of Texinfo we punt and leave the menu in
;; its original form.
(when (or (search-forward "<ul class=\"menu\">" nil t)
;; FIXME? The following search seems dangerously lax.
(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)
(while (not done)
(cond
((or (looking-at "<li>\\(<a.+</a>\\):[ \t]+\\(.*\\)$")
(looking-at "<li>\\(<a.+</a>\\)$"))
(setq tag (match-string 1))
(setq desc (match-string 2))
(replace-match "" t t)
(when open-td
(save-excursion
(forward-char -1)
(skip-chars-backward " ")
(delete-region (point) (line-end-position))
(insert "</td>\n </tr>")))
(insert " <tr>\n ")
(if table-workaround
;; This works around a Firefox bug in the mono file.
(insert "<td bgcolor=\"white\">")
(insert "<td>"))
(insert tag "</td>\n <td>" (or desc ""))
(setq open-td t))
((eq (char-after) ?\n)
(delete-char 1)
;; Negate the following `forward-line'.
(forward-line -1))
((looking-at "<!-- ")
(search-forward "-->"))
((looking-at "<p>[- ]*The Detailed Node Listing[- \n]*")
(replace-match " </td></tr></table>\n
<h3>Detailed Node Listing</h3>\n\n" t t)
(search-forward "<p>")
;; FIXME Fragile!
;; The Emacs and Elisp manual have some text at the
;; start of the detailed menu that is not part of the menu.
;; Other manuals do not.
(if (looking-at "Here are some other nodes")
(search-forward "<p>"))
(goto-char (match-beginning 0))
(skip-chars-backward "\n ")
(setq open-td nil)
(insert "</p>\n\n<table style=\"float:left\" width=\"100%\">"))
((looking-at "</li></ul>")
(replace-match "" t t))
((looking-at "<p>")
(replace-match "" t t)
(when open-td
(insert " </td></tr>")
(setq open-td nil))
(insert " <tr>
(search-forward "<p>")
;; FIXME Fragile!
;; The Emacs and Elisp manual have some text at the
;; start of the detailed menu that is not part of the menu.
;; Other manuals do not.
(if (looking-at "Here are some other nodes")
(search-forward "<p>"))
(goto-char (match-beginning 0))
(skip-chars-backward "\n ")
(setq open-td nil)
(insert "</p>\n\n<table style=\"float:left\" width=\"100%\">"))
((looking-at "</li></ul>")
(replace-match "" t t))
((looking-at "<p>")
(replace-match "" t t)
(when open-td
(insert " </td></tr>")
(setq open-td nil))
(insert " <tr>
<th colspan=\"2\" align=\"left\" style=\"text-align:left\">")
(if (re-search-forward "</p>[ \t\n]*<ul class=\"menu\">" nil t)
(replace-match " </th></tr>")))
((looking-at "[ \t]*</ul>[ \t]*$")
(replace-match
(if open-td
" </td></tr>\n</table>"
"</table>") t t)
(setq done t))
(t
(if (eobp)
(error "Parse error in %s"
(file-name-nondirectory buffer-file-name)))
(unless open-td
(setq done t))))
(forward-line 1)))))
(if (re-search-forward "</p>[ \t\n]*<ul class=\"menu\">" nil t)
(replace-match " </th></tr>")))
((looking-at "[ \t]*</ul>[ \t]*$")
(replace-match
(if open-td
" </td></tr>\n</table>"
"</table>") t t)
(setq done t))
(t
(if (eobp)
(error "Parse error in %s"
(file-name-nondirectory buffer-file-name)))
(unless open-td
(setq done t))))
(forward-line 1))))))
(defconst make-manuals-dist-output-variables

1
admin/alloc-colors.c
View file

@ -23,6 +23,7 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
#include <stdlib.h>
#include <stdarg.h>
#include <unistd.h>
#include <string.h>
void
fatal (const char *fmt, ...)

214
admin/authors.el
View file

@ -68,6 +68,7 @@ files.")
(nil "castor@my-dejanews")
(nil "chengang31@gmail.com")
(nil "chuntaro")
("Clément Pit-Claudel" "Clément Pit--Claudel")
("David Abrahams" "Dave Abrahams")
("David J. Biesack" "David Biesack")
("David De La Harpe Golden" "David Golden")
@ -242,10 +243,14 @@ files.")
("Vinicius Jose Latorre" "viniciusjl")
("Gaby Launay" "galaunay")
("Dick R. Chiang" "dickmao")
("Lin Zhou" "georgealbert@qq.com")
(nil "yan@metatem.net")
(nil "gnu_lists@halloleo.hailmail.net")
)
"Alist of author aliases.
Each entry is of the form (REALNAME REGEXP...). If an author's name
Each entry is of the form (REALNAME REGEXP...).
If an author's full name, as in \"J.R.Hacker <foobar.com>\",
matches one of the REGEXPs, use REALNAME instead.
If REALNAME is nil, ignore that author.")
@ -498,6 +503,7 @@ Changes to files matching one of the regexps in this list are not listed.")
"nextstep/WISHLIST"
;; Removed, replaced by gitmerge.el
"admin/bzrmerge.el"
"bzrmerge.el"
;; Removed in commit f5090b91299
"lib/fdatasync.c"
;; Removed as obsolete
@ -512,8 +518,11 @@ Changes to files matching one of the regexps in this list are not listed.")
"MORE.STUFF"
"notes/font-backend"
"src/ftxfont.c"
"ftxfont.c"
"src/ptr-bounds.h"
"obsolete/options.el"
"obsolete/old-whitespace.el"
"obsolete/lucid.el"
;; ada-mode has been deleted, now in GNU ELPA
"ada-mode.texi"
"doc/misc/ada-mode.texi"
@ -874,11 +883,9 @@ Changes to files in this list are not listed.")
"gnus-compat.el" "pgg-parse.el" "pgg-pgp.el" "pgg-pgp5.el" "pgg.el"
"dns-mode.el" "run-at-time.el" "gnus-encrypt.el" "sha1-el.el"
"gnus-gl.el" "gnus.sum.el" "proto-stream.el" "color.el" "color-lab.el"
"eww.el" "shr-color.el" "shr.el" "earcon.el" "gnus-audio.el" "encrypt.el"
"format-spec.el" "gnus-move.el" "gnus-sync.el"
"auth-source.el" "ecomplete.el" "gravatar.el" "mailcap.el" "plstore.el"
"pop3.el" "qp.el" "registry.el" "rfc2231.el" "rtree.el"
"sieve.el" "sieve-mode.el" "gnus-ems.el"
"earcon.el" "gnus-audio.el" "encrypt.el"
"gnus-move.el" "gnus-sync.el"
"gnus-ems.el"
;; doc
"getopt.c" "texindex.c" "news.texi" "vc.texi" "vc2-xtra.texi"
"back.texi" "vol1.texi" "vol2.texi" "elisp-covers.texi" "two.el"
@ -959,6 +966,43 @@ in the repository.")
;; NB So only add a directory if needed to disambiguate.
;; FIXME?
;; Although perhaps we could let authors-disambiguate-file-name do that?
;;
;; WARNING: The semantics of these entries is tricky to grasp without
;; reading the code!
;; The rule is: for every file that was renamed or moved to another
;; directory, add an entry (OLD-NAME . NEW-BASENAME), where OLD-NAME
;; is the old name of the file as it appears in the ChangeLog files,
;; and NEW-BASENAME is the _basename_ of its new name. Yes, this
;; means that a file which was moved to another directory but kept its
;; basename will have a seemingly-silly entry ("foo" . "foo"). (Told
;; you: this is tricky!) If the moved/renamed file was mentioned in
;; several ChangeLog files with different leading directories, you
;; need to provide an entry for each such instance. For example, if
;; some ChangeLog mentioned a moved file as lisp/gnus/something.el and
;; another ChangeLog mentioned it as gnus/something.el, you need to
;; have two entries:
;;
;; ("gnus/something.el" . "something.el")
;; ("lisp/gnus/something.el" . "something.el")
;;
;; The important part is that the car of the entry should be identical
;; to how a file was mentioned in the respective ChangeLog. It is
;; advisable to run a Grep command such as
;;
;; fgrep -R BASENAME . --include='ChangeLog*'
;;
;; where BASENAME is the old basename of the renamed file. This will
;; show all the different reference forms of the file in the various
;; ChangeLog* files, and you can then prepare a separate entry for
;; each reference form.
;;
;; The cdr of the entry should generally be only the basename of the
;; file's current name, because that's how AUTHORS references files.
;; It _can_ have leading directories, but that is only
;; needed/advisable if there are several files in the tree that have
;; the same basename, and you want to disambiguate them, so that
;; people who actually contributed to different files aren't mentioned
;; as if they contributed to the same single file.
(defconst authors-renamed-files-alist
'(("nt.c" . "w32.c") ("nt.h" . "w32.h")
("ntheap.c" . "w32heap.c") ("ntheap.h" . "w32heap.h")
@ -966,8 +1010,9 @@ in the repository.")
("ntproc.c" . "w32proc.c")
("w32console.c" . "w32term.c")
("unexnt.c" . "unexw32.c")
("s/windowsnt.h" . "s/ms-w32.h")
("s/ms-w32.h" . "inc/ms-w32.h")
("m/windowsnt.h" . "ms-w32.h")
("s/windowsnt.h" . "ms-w32.h")
("s/ms-w32.h" . "ms-w32.h")
("src/config.h" . "config.h")
("winnt.el" . "w32-fns.el")
("linux.h" . "gnu-linux.h")
@ -990,6 +1035,10 @@ in the repository.")
("INSTALL.MSYS" . "INSTALL")
("server.c" . "emacsserver.c")
("lib-src/etags.c" . "etags.c")
;; gnulib
("lib/strftime.c" . "nstrftime.c")
("src/mini-gmp.c" . "mini-gmp.c")
("src/mini-gmp.h" . "mini-gmp.h")
;; msdos/
("is-exec.c" . "is_exec.c")
("enriched.doc" . "enriched.txt")
@ -1073,8 +1122,10 @@ in the repository.")
("nxml/test.invalid.xml" . "test-invalid.xml")
("nxml/test.valid.xml" . "test-valid.xml")
("automated/Makefile.in" . "test/Makefile.in")
("test/rmailmm.el" . "test/manual/rmailmm.el")
("rmailmm.el" . "test/manual/rmailmm.el")
;; rmailmm tests wandered from test/ to test/manual to test/lisp/mail/
("rmailmm.el" . "rmailmm-tests.el")
("test/rmailmm.el" . "rmailmm-tests.el")
("test/manual/rmailmm.el" . "rmailmm-tests.el")
;; The one in lisp is eshell/eshell.el.
("eshell.el" . "eshell-tests.el")
("automated/eshell.el" . "eshell-tests.el")
@ -1106,22 +1157,79 @@ in the repository.")
("major.texi" . "modes.texi")
("msdog-xtra.texi" . "msdos-xtra.texi")
("msdog.texi" . "msdos.texi")
;; Moved from lisp/gnus/ to lisp/
("auth-source.el" . "auth-source.el")
("lisp/gnus/auth-source.el" . "auth-source.el")
("ecomplete.el" . "ecomplete.el")
("format-spec.el" . "format-spec.el")
("gnus/format-spec.el" . "format-spec.el")
("lisp/gnus/ecomplete.el" . "ecomplete.el")
("plstore.el" . "plstore.el")
("lisp/gnus/plstore.el" . "plstore.el")
("registry.el" . "registry.el")
("lisp/gnus/registry.el" . "registry.el")
("rtree.el" . "rtree.el")
;; Moved from lisp/gnus/ to lisp/calendar/
("time-date.el" . "calendar/time-date.el")
("time-date.el" . "time-date.el")
;; Moved from lisp/gnus/ to lisp/mail/
("binhex.el" . "mail/binhex.el")
("uudecode.el" . "mail/uudecode.el")
("mail-parse.el" . "mail/mail-parse.el")
("yenc.el" . "mail/yenc.el")
("flow-fill.el" . "mail/flow-fill.el")
("ietf-drums.el" . "mail/ietf-drums.el")
("sieve-manage.el" . "mail/sieve-manage.el")
("binhex.el" . "binhex.el")
("gnus/binhex.el" . "binhex.el")
("uudecode.el" . "uudecode.el")
("gnus/uudecode.el" . "uudecode.el")
("mail-parse.el" . "mail-parse.el")
("gnus/mail-parse.el" . "mail-parse.el")
("mail-prsvr.el" . "mail-prsvr.el")
("gnus/mail-prsvr.el" . "mail-prsvr.el")
("yenc.el" . "yenc.el")
("flow-fill.el" . "flow-fill.el")
("gnus/flow-fill.el" . "flow-fill.el")
("ietf-drums.el" . "ietf-drums.el")
("gnus/ietf-drums.el" . "ietf-drums.el")
("pop3.el" . "pop3.el")
("mail/pop3.el" . "pop3.el")
("gnus/pop3.el" . "pop3.el")
("lisp/gnus/pop3.el" . "pop3.el")
("qp.el" . "qp.el")
("gnus/qp.el" . "qp.el")
("lisp/gnus/qp.el" . "qp.el")
("rfc2045.el" . "rfc2045.el")
("gnus/rfc2045.el" . "rfc2045.el")
("rfc2047.el" . "rfc2047.el")
("gnus/rfc2047.el" . "rfc2047.el")
("rfc2231.el" . "rfc2231.el")
("gnus/rfc2231.el" . "rfc2231.el")
("lisp/gnus/rfc2231.el" . "rfc2231.el")
;; Moved from lisp/gnus/ to lisp/image/
("compface.el" . "image/compface.el")
("compface.el" . "compface.el")
("gravatar.el" . "gravatar.el")
("lisp/gnus/gravatar.el" . "gravatar.el")
;; Moved from lisp/gnus/ to lisp/net/
("eww.el" . "eww.el")
("net/eww.el" . "eww.el")
("lisp/new/eww.el" . "eww.el") ; an actual typo in ChangeLog.3
("gssapi.el" . "gssapi.el")
("lisp/gnus/gssapi.el" . "gssapi.el")
("imap.el" . "net/imap.el")
("mailcap.el" . "mailcap.el")
("gnus/mailcap.el" . "mailcap.el")
("lisp/gnus/mailcap.el" . "mailcap.el")
("rfc2104.el" . "net/rfc2104.el")
("starttls.el" . "net/starttls.el")
("starttls.el" . "starttls.el")
("lisp/net/starttls.el" . "starttls.el") ; moved to obsolete/
("shr.el" . "shr.el")
("net/shr.el" . "shr.el")
("shr-color.el" . "shr-color.el")
("sieve-manage.el" . "sieve-manage.el")
("sieve-mode.el" . "sieve-mode.el")
("sieve.el" . "sieve.el")
("lisp/gnus/sieve-manage.el" . "sieve-manage.el")
("lisp/gnus/sieve-mode.el" . "sieve-mode.el")
("lisp/gnus/sieve.el" . "sieve.el")
;; Moved from lisp/gnus/ to lisp/international
("rfc1843.el" . "rfc1843.el")
("gnus/rfc1843.el" . "rfc1843.el")
("utf7.el" . "utf7.el")
("gnus/utf7.el" . "utf7.el")
;; And from emacs/ to misc/ and back again.
("ns-emacs.texi" . "macos.texi")
("overrides.texi" . "gnus-overrides.texi")
@ -1136,7 +1244,7 @@ in the repository.")
("ED.WORSHIP" . "JOKES")
("GNU.JOKES" . "JOKES")
("CHARACTERS" . "TODO")
("lisp/character-fold.el" . "lisp/char-fold.el")
("lisp/character-fold.el" . "char-fold.el")
("test/automated/character-fold-tests.el" . "char-fold-tests.el")
("test/automated/char-fold-tests.el" . "char-fold-tests.el")
("test/lisp/character-fold-tests.el" . "char-fold-tests.el")
@ -1178,7 +1286,8 @@ in the repository.")
("grammars" . "grammars")
;; Moved from lisp/emacs-lisp/ to admin/.
("emacs-lisp/authors.el" . "authors.el")
("emacs-lisp/find-gc.el" . "admin/find-gc.el")
("find-gc.el" . "find-gc.el")
("emacs-lisp/find-gc.el" . "find-gc.el")
;; From etc to lisp/cedet/semantic/.
("grammars/bovine-grammar.el" . "bovine/grammar.el")
("grammars/wisent-grammar.el" . "wisent/grammar.el")
@ -1186,28 +1295,41 @@ in the repository.")
("nt/README.W32" . "README.W32")
("notes/BRANCH" . "notes/repo")
("notes/bzr" . "notes/repo")
;; moved from lisp/ to lisp/net/
("lisp/pinentry.el" . "lisp/net/pinentry.el")
;; moved from lisp/ to lisp/net/, then removed
("pinentry.el" . "pinentry.el")
("lisp/pinentry.el" . "pinentry.el")
("lisp/net/pinentry.el" . "pinentry.el")
;; module.* moved to emacs-module.*
("src/module.h" . "src/emacs-module.h")
("src/module.c" . "src/emacs-module.c")
;; gnulib
("lib/strftime.c" . "lib/nstrftime.c")
("test/src/regex-tests.el" . "test/src/regex-emacs-tests.el")
("test/lisp/emacs-lisp/cl-tests.el" . "test/lisp/obsolete/cl-tests.el")
("lisp/net/starttls.el" . "lisp/obsolete/starttls.el")
("url-ns.el" . "lisp/obsolete/url-ns.el")
("gnus-news.texi" . "doc/misc/gnus.texi")
("lisp/multifile.el" . "lisp/fileloop.el")
("lisp/emacs-lisp/thread.el" . "lisp/thread.el")
("lisp/emacs-lisp/cl.el" . "lisp/emacs-lisp/cl-lib.el")
("lisp/progmodes/mantemp.el" . "lisp/obsolete/mantemp.el")
("src/mini-gmp.c" . "lib/mini-gmp.c")
("src/mini-gmp.h" . "lib/mini-gmp.h")
("src/module.h" . "emacs-module.h")
("src/module.c" . "emacs-module.c")
("test/src/regex-tests.el" . "regex-emacs-tests.el")
("test/lisp/emacs-lisp/cl-tests.el" . "cl-tests.el")
("url-ns.el" . "url-ns.el")
("gnus-news.texi" . "gnus.texi")
("doc/misc/gnus-news.texi" . "gnus.texi")
("lisp/multifile.el" . "fileloop.el")
("lisp/emacs-lisp/thread.el" . "thread.el")
;; cl.el was retired, replaced by cl-lib.el, and we want to
;; pretend they are the same file...
("emacs-lisp/cl.el" . "cl-lib.el")
("lisp/emacs-lisp/cl.el" . "cl-lib.el")
("lisp/obsolete/cl.el" . "cl-lib.el")
("mantemp.el" . "mantemp.el")
("lisp/progmodes/mantemp.el" . "mantemp.el")
("progmodes/mantemp.el" . "mantemp.el")
("sysdep.c" . "src/sysdep.c")
;; nnir.el started in lisp/gnus/ChangeLog.*, then was
;; lisp/gnus/nnir.el in ChangeLog.[123], and is now
;; lisp/obsolete/nnir.el.
("nnir.el" . "nnir.el")
("lisp/gnus/nnir.el" . "nnir.el")
("src/regex.c" . "emacs-regex.c")
("src/regex.h" . "emacs-regex.h")
;; regex.[ch] are mentioned as src/regex.[ch] in ChangeLog.[123],
;; but as just regex.[ch] in src/ChangeLog.*, so we need 2 entries
;; for each one of them.
("regex.c" . "regex-emacs.c")
("regex.h" . "regex-emacs.h")
("src/regex.c" . "regex-emacs.c")
("src/regex.h" . "regex-emacs.h")
("test/manual/rmailmm.el" . "rmailmm-tests.el")
("test/lisp/cedet/semantic-utest-fmt.el" . "format-tests.el")
("test/lisp/emacs-lisp/tabulated-list-test.el" . "tabulated-list-tests.el")
@ -1368,10 +1490,14 @@ Additionally, for these logs we apply the `lax' elements of
(defun authors-canonical-file-name (file log-file pos author)
"Return canonical file name for FILE found in LOG-FILE.
FILE is the file name as it appears in LOG-FILE, including any
leading directories mentioned there.
LOG-FILE is an absolute file name of the log file we are scanning.
Checks whether FILE is a valid (existing) file name, has been renamed,
or is on the list of removed files. Returns the non-directory part of
the file name. Only uses the LOG-FILE position POS and associated AUTHOR
to print a message if FILE is not found."
the file name to use for FILE in the \"AUTHORS\" file.
Only uses the LOG-FILE position POS and associated AUTHOR to print a
message if FILE is not found."
;; FILE should be re-checked in every different directory associated
;; with a LOG-FILE. Eg configure.ac from src/ChangeLog is not the
;; same as that from top-level/ChangeLog.
@ -1381,6 +1507,8 @@ to print a message if FILE is not found."
(if entry
(cdr entry)
(setq relname (file-name-nondirectory file))
;; File names in `authors-valid-file-names' are OK by
;; definition, so no need to check those.
(if (or (member file authors-valid-file-names)
(member relname authors-valid-file-names)
(file-exists-p file)

2
admin/cus-test.el
View file

@ -156,7 +156,7 @@ Names should be as they appear in loaddefs.el.")
"Set by `cus-test-apropos' to a list of options with :get property.")
(defvar cus-test-vars-with-changed-state nil
"Set by `cus-test-apropos' to a list of options with state 'changed.")
"Set by `cus-test-apropos' to a list of options with state \\='changed.")
(defvar cus-test-deps-errors nil
"List of require/load problems found by `cus-test-deps'.")

2
admin/emake
View file

@ -79,6 +79,8 @@ The GNU allocators don't work|\
^git config |\
^'\.git/|\
^\^\(\(|\
^ANCIENT=yes make|\
^touch -t|\
^'build-aux/git-hooks\
" | \
while read

2
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 ()

5
admin/grammars/Makefile.in
View file

@ -31,10 +31,11 @@ top_builddir = @top_builddir@
-include ${top_builddir}/src/verbose.mk
# Prevent any settings in the user environment causing problems.
unexport EMACSDATA EMACSDOC EMACSPATH
unexport EMACSDATA EMACSDOC EMACSLOADPATH EMACSPATH
EMACS = ${top_builddir}/src/emacs
emacs = EMACSLOADPATH= "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefer-newer t)'
emacs = "${EMACS}" -batch --no-site-file --no-site-lisp \
--eval '(setq max-specpdl-size 5000)' --eval '(setq load-prefer-newer t)'
make_bovine = ${emacs} -l semantic/bovine/grammar -f bovine-batch-make-parser
make_wisent = ${emacs} -l semantic/wisent/grammar -f wisent-batch-make-parser

170
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,
@ -43,18 +43,45 @@ General steps (for each step, check for possible errors):
because some of the commands below run Make, so they need
Makefiles to be present.
For Emacs 28, and as long as --with-native-compilation is not the
default, the tree needs to be configured with native-compilation
enabled, to ensure all the pertinent *.elc files will end up in
the tarball. Otherwise, the *.eln files might not build correctly
on the user's system.
For Emacs 28 and later, as long as --with-native-compilation is
not the default, the tree needs to be configured with
native-compilation enabled, to ensure all the pertinent *.elc
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
was modified.
2. Regenerate the versioned ChangeLog.N and etc/AUTHORS files.
The "M-x authors" command below will first update the current
versioned ChangeLog.N file. For this to work correctly, make sure
the top-level Makefile says
PREFERRED_BRANCH = emacs-NN
where NN is the version on the release branch from which you are
producing the tarball. If NN is incorrect, update Makefile.in and
re-run 'configure' to update Makefile.
If the versioned ChangeLog.N file is too large, start a new one
by bumping N, and also update the line in top-level Makefile.in
which says
CHANGELOG_HISTORY_INDEX_MAX = N
by incrementing the value of N by 1; then regenerate Makefile.
Now:
2. Regenerate the etc/AUTHORS file:
M-: (require 'authors) RET
M-x authors RET
(This first updates the current versioned ChangeLog.N)
If this says "Problem updating ChangeLog", find the reason for the
failure of the command it runs, viz.:
@ -134,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
@ -232,7 +261,9 @@ General steps (for each step, check for possible errors):
FILE.gz FILE.xz ...
You only need the --user part if you have multiple GPG keys and do
not want to use the default.
not want to use the default. Instead of "your@gpg.key.email" you
could also use the fingerprint of the key, a 40-digit hex number.
(Alternatively, define default-key in your ~/.gnupg/gpg.conf file.)
Obviously, if you do not have a fast uplink, be prepared for the
upload to take a while.
@ -256,7 +287,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.
11. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
For a pretest, also bcc: platform-testers@gnu.org.
@ -274,12 +306,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, probably 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.
@ -287,8 +327,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:
@ -304,21 +344,81 @@ 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>
Regenerate the various manuals in manual/.
The scripts admin/make-manuals and admin/upload-manuals summarize the process.
Also, make sure the copyright years at the bottom of emacs.html are
up-to-date.
If you have Texinfo installed locally, make-manuals might fail if it
cannot find epsf.tex. In that case define in the environment
The file download.html may need to be updated, for example if the
MS-Windows binaries will be signed by a different person/key than
those mentioned there.
TEXINPUTS=:/path/to/texinfo-tree/doc
Next, regenerate the various manuals in HTML, PDF, and PS formats:
where /path/to/texinfo-tree is the absolute file name of the top-level
directory where you have the Texinfo source tree. Then re-run
make-manuals.
Invoke ./admin/make-manuals from the top-level directory of the
Emacs source tree that contains the manuals for which you want to
produce HTML docs. This creates the 'manual' directory and
populates it with the necessary files.
If you have Texinfo installed locally, make-manuals might fail if it
cannot find epsf.tex. In that case define in the environment
TEXINPUTS=:/path/to/texinfo-tree/doc
where /path/to/texinfo-tree is the absolute file name of the
top-level directory where you have the Texinfo source tree. Then
re-run make-manuals.
make-manuals can also fail if the HTML manuals produced by Texinfo
violate some of the assumptions admin/admin.el makes about the
format of the produced HTML. Debug these problems and resolve them,
then re-run make-manuals. (Each time you run make-manuals, it
empties the manuals/ directory and regenerates the files there, but
if the files in manuals/ can be used without regeneration, i.e. if
the problem you solved doesn't affect the produced HTML, you can
invoke make-manuals with the -c switch, which will make the process
much faster.)
Now change to the 'manual' directory and invoke upload-manuals:
../admin/updload-manuals /path/to/webpages/cvs/checkout
where /path/to/webpages/cvs/checkout is the place where you have the
CVS checkout of the Emacs Web pages, with subdirectories 'manual'
and 'refcards'. This moves the produced manuals to directories in
the Web pages CVS checkout tree, and also invokes CVS commands to
commit changed files, add new files, and remove stale files that are
no longer part of the manuals.
If upload-manuals fails, resolve the problems and re-invoke it.
This requires running make-manuals again, since upload-manuals
destructively modifies the 'manual' directory where you invoke it.
Also, upload-manuals invokes "cvs commit -f", so if you run it
several times, some files will be committed more than once even
though they were not changed in-between. Suck it up.
All the added and removed files need to be committed, so next fire
up Emacs, type "C-x v d" to invoke vc-dir on the Web pages checkout,
and use "C-x v v" and other VC commands to commit all the files that
upload-manuals didn't automatically commit. (You can also do that
with manual CVS commands, of course, but this is not recommended.)
Next, make sure that manual/index.html file is consistent with the
info/dir file in the branch for which you are producing the manuals,
in that it mentions all the manuals. It could be outdated if
manuals were added or removed since the last release.
For each new manual, a file manual/MANUAL.html (where MANUAL is the
name of the manual) should be created from the template in
manual/eww.html, after editing the title and the Copyright years,
and the links in it changed to point to the appropriate files in the
manual/html_node/ and manual/html_mono/ subdirectories.
In addition, the file refcards/index.html should be audited to make
sure it includes the up-to-date list of refcards actually produced
and put under that subdirectory.
Browsing <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
way to check for any files that still need updating.

14
admin/merge-gnulib
View file

@ -40,7 +40,7 @@ GNULIB_MODULES='
getloadavg getopt-gnu getrandom gettime gettimeofday gitlog-to-changelog
ieee754-h ignore-value intprops largefile libgmp lstat
manywarnings memmem-simple mempcpy memrchr minmax mkostemp mktime
nproc nstrftime
nanosleep nproc nstrftime
pathmax pipe2 pselect pthread_sigmask
qcopy-acl readlink readlinkat regex
sig2str sigdescr_np socklen stat-time std-gnu11 stdalign stddef stdio
@ -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
@ -102,6 +102,12 @@ test -x "$gnulib_srcdir"/gnulib-tool || {
exit 1
}
# gnulib-tool has problems with a bare checkout (Bug#32452#65).
test -f configure || ./autogen.sh || exit
# Old caches can confuse autoconf when some Gnulib-related changes take effect.
rm -fr autom4te.cache || exit
avoided_flags=
for module in $AVOIDED_MODULES; do
avoided_flags="$avoided_flags --avoid=$module"
@ -109,7 +115,9 @@ done
"$gnulib_srcdir"/gnulib-tool --dir="$src" $GNULIB_TOOL_FLAGS \
$avoided_flags $GNULIB_MODULES &&
rm -- "$src"lib/gl_openssl.h "$src"m4/fcntl-o.m4 \
rm -- "$src"lib/gl_openssl.h \
"$src"lib/stdio-read.c "$src"lib/stdio-write.c \
"$src"m4/fcntl-o.m4 \
"$src"m4/gl-openssl.m4 \
"$src"m4/gnulib-cache.m4 "$src"m4/gnulib-tool.m4 \
"$src"m4/manywarnings-c++.m4 \

13
admin/notes/emba
View file

@ -8,7 +8,8 @@ NOTES FOR EMACS CONTINUOUS BUILD ON EMBA
A continuous build for Emacs can be found at
<https://emba.gnu.org/emacs/emacs>, a Gitlab instance. It watches the
Emacs git repository and starts a pipeline (jobset) if there are new
changes. This happens for all Emacs branches.
changes. This happens for all Emacs branches which belong to the
defined workflow (see below).
* Mail notifications
@ -32,7 +33,11 @@ The Emacs jobset is defined in the Emacs source tree, file
'test/infra'. They could be adapted for every Emacs branch, see
<https://emba.gnu.org/help/ci/yaml/README.md>.
A jobset on Gitlab is called pipeline. Emacs pipelines run through
Only branches whose name starts with 'master', 'emacs', 'feature', or
'fix' are considered. This is declared in the workflow rules of file
'test/infra/gitlab-ci.yml'.
A jobset on Gitlab is called a pipeline. Emacs pipelines run through
the stages 'build-images', 'platform-images' and 'native-comp-images'
(create an Emacs instance by 'make bootstrap' with different
configuration parameters) as well as 'normal', 'platforms' and
@ -41,11 +46,11 @@ configuration parameters) as well as 'normal', 'platforms' and
The jobs for stage 'normal' are contained in the file
'test/infra/test-jobs.yml'. This file is generated by calling 'make
-C test generate-test-jobs' in the Emacs source tree, and the
resulting file shall be pushed to the Emacs git repository afterwards.
resulting file should be pushed to the Emacs git repository afterwards.
Every job runs in a Debian docker container. It uses the local clone
of the Emacs git repository to perform a bootstrap and test of Emacs.
This could happen for several jobs with changed configuration, compile
This could happen for several jobs with changed configuration, compile,
and test parameters.
The 'build-image-*' jobs of the different '*-images' stages run only

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.

24
admin/notes/unicode
View file

@ -15,20 +15,32 @@ Emacs uses the following files from the Unicode Character Database
. BidiMirroring.txt
. IVD_Sequences.txt
. NormalizationTest.txt
. PropertyValueAliases.txt
. ScriptExtensions.txt
. Scripts.txt
. SpecialCasing.txt
. confusables.txt
. emoji-data.txt
. emoji-zwj-sequences.txt
. emoji-sequences.txt
. BidiCharacterTest.txt
Emacs also uses the file emoji-test.txt which should be imported from
the Unicode's Public/emoji/ directory.
the Unicode's Public/emoji/ directory, and IdnaMappingTable.txt from
the Public/idna/ directory.
First, the first 10 files and emoji-test.txt need to be copied into
admin/unidata/, and the file https://www.unicode.org/copyright.html
should be copied over copyright.html in admin/unidata (some of them
might need trailing whitespace removed before they can be committed to
the Emacs repository).
First, the first 14 files, emoji-test.txt and IdnaMappingTable.txt
need to be copied into admin/unidata/, and the file
https://www.unicode.org/copyright.html should be copied over
copyright.html in admin/unidata (some of them might need trailing
whitespace removed before they can be committed to the Emacs
repository).
Next, review the assignment of default values of the Bidi Class
property to blocks in the file extracted/DerivedBidiClass.txt from the
UCD (search for "unassigned" in that file). Any changes should be
reflected in the unidata-gen.el file, where it sets up the default
values around line 210.
Then Emacs should be rebuilt for them to take effect. Rebuilding
Emacs updates several derived files elsewhere in the Emacs source

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; }

8921
admin/unidata/IdnaMappingTable.txt Normal file
View file

File diff suppressed because it is too large Load diff

24
admin/unidata/Makefile.in
View file

@ -29,6 +29,9 @@ srcdir = @srcdir@
top_srcdir = @top_srcdir@
top_builddir = @top_builddir@
# Prevent any settings in the user environment causing problems.
unexport EMACSDATA EMACSDOC EMACSLOADPATH EMACSPATH
EMACS = ${top_builddir}/src/emacs
unidir = ${top_srcdir}/lisp/international
emacs = "${EMACS}" -batch --no-site-file --no-site-lisp
@ -41,7 +44,9 @@ unifiles = $(addprefix ${unidir}/,$(sort $(shell sed -n 's/^[ \t][ \t]*${lparen}
.PHONY: all
all: ${top_srcdir}/src/macuvs.h ${unifiles} ${unidir}/charscript.el \
${unidir}/charprop.el ${unidir}/emoji-zwj.el ${unidir}/emoji-labels.el
${unidir}/charprop.el ${unidir}/emoji-zwj.el ${unidir}/emoji-labels.el \
${unidir}/uni-scripts.el ${unidir}/uni-confusable.el \
${unidir}/idna-mapping.el
## Specify .elc as an order-only prereq so as to not needlessly rebuild
## target just because the .elc is missing.
@ -79,6 +84,23 @@ ${unidir}/emoji-labels.el: ${unidir}/../international/emoji.el \
${srcdir}/emoji-test.txt
$(AM_V_GEN)${emacs} -l emoji.el -f emoji--generate-file $@
${unidir}/uni-scripts.el: ${srcdir}/unidata-gen.el \
${srcdir}/Scripts.txt \
${srcdir}/ScriptExtensions.txt \
${srcdir}/PropertyValueAliases.txt
$(AM_V_GEN)${emacs} -L ${srcdir} \
-l unidata-gen.el -f unidata-gen-scripts $@
${unidir}/uni-confusable.el: ${srcdir}/unidata-gen.el \
${srcdir}/confusables.txt
$(AM_V_GEN)${emacs} -L ${srcdir} \
-l unidata-gen.el -f unidata-gen-confusable $@
${unidir}/idna-mapping.el: ${srcdir}/unidata-gen.el \
${srcdir}/IdnaMappingTable.txt
$(AM_V_GEN)${emacs} -L ${srcdir} \
-l unidata-gen.el -f unidata-gen-idna-mapping $@
.PHONY: charscript.el
charscript.el: ${unidir}/charscript.el

1615
admin/unidata/PropertyValueAliases.txt Normal file
View file

File diff suppressed because it is too large Load diff

16
admin/unidata/README
View file

@ -48,3 +48,19 @@ https://www.unicode.org/Public/emoji/14.0/emoji-sequences.txt
emoji-test.txt
https://unicode.org/Public/emoji/14.0/emoji-test.txt
2021-10-28
ScriptExtensions.txt
https://www.unicode.org/Public/UCD/latest/ucd/ScriptExtensions.txt
2022-01-17
Scripts.txt
https://www.unicode.org/Public/UCD/latest/ucd/Scripts.txt
2022-01-17
PropertyValueAliases.txt
https://www.unicode.org/Public/UCD/latest/ucd/PropertyValueAliases.txt
2022-01-17
IdnaMappingTable.txt
https://www.unicode.org/Public/idna/latest/IdnaMappingTable.txt
2022-01-18

628
admin/unidata/ScriptExtensions.txt Normal file
View file

@ -0,0 +1,628 @@
# ScriptExtensions-14.0.0.txt
# Date: 2021-06-04, 02:19:38 GMT
# © 2021 Unicode®, Inc.
# Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the U.S. and other countries.
# For terms of use, see http://www.unicode.org/terms_of_use.html
#
# Unicode Character Database
# For documentation, see http://www.unicode.org/reports/tr44/
#
# The Script_Extensions property indicates which characters are commonly used
# with more than one script, but with a limited number of scripts.
# For each code point, there is one or more property values. Each such value is a Script property value.
# For more information, see:
# UAX #24, Unicode Script Property: https://www.unicode.org/reports/tr24/
# Especially the sections:
# https://www.unicode.org/reports/tr24/#Assignment_Script_Values
# https://www.unicode.org/reports/tr24/#Assignment_ScriptX_Values
#
# Each Script_Extensions value in this file consists of a set
# of one or more abbreviated Script property values. The ordering of the
# values in that set is not material, but for stability in presentation
# it is given here as alphabetical.
#
# The Script_Extensions values are presented in sorted order in the file.
# They are sorted first by the number of Script property values in their sets,
# and then alphabetically by first differing Script property value.
#
# Following each distinct Script_Extensions value is the list of code
# points associated with that value, listed in code point order.
#
# All code points not explicitly listed for Script_Extensions
# have as their value the corresponding Script property value
#
# @missing: 0000..10FFFF; <script>
# ================================================
# Property: Script_Extensions
# ================================================
# Script_Extensions=Beng
1CF7 ; Beng # Mc VEDIC SIGN ATIKRAMA
# Total code points: 1
# ================================================
# Script_Extensions=Deva
1CD1 ; Deva # Mn VEDIC TONE SHARA
1CD4 ; Deva # Mn VEDIC SIGN YAJURVEDIC MIDLINE SVARITA
1CDB ; Deva # Mn VEDIC TONE TRIPLE SVARITA
1CDE..1CDF ; Deva # Mn [2] VEDIC TONE TWO DOTS BELOW..VEDIC TONE THREE DOTS BELOW
1CE2..1CE8 ; Deva # Mn [7] VEDIC SIGN VISARGA SVARITA..VEDIC SIGN VISARGA ANUDATTA WITH TAIL
1CEB..1CEC ; Deva # Lo [2] VEDIC SIGN ANUSVARA VAMAGOMUKHA..VEDIC SIGN ANUSVARA VAMAGOMUKHA WITH TAIL
1CEE..1CF1 ; Deva # Lo [4] VEDIC SIGN HEXIFORM LONG ANUSVARA..VEDIC SIGN ANUSVARA UBHAYATO MUKHA
# Total code points: 18
# ================================================
# Script_Extensions=Dupl
1BCA0..1BCA3 ; Dupl # Cf [4] SHORTHAND FORMAT LETTER OVERLAP..SHORTHAND FORMAT UP STEP
# Total code points: 4
# ================================================
# Script_Extensions=Grek
0342 ; Grek # Mn COMBINING GREEK PERISPOMENI
0345 ; Grek # Mn COMBINING GREEK YPOGEGRAMMENI
1DC0..1DC1 ; Grek # Mn [2] COMBINING DOTTED GRAVE ACCENT..COMBINING DOTTED ACUTE ACCENT
# Total code points: 4
# ================================================
# Script_Extensions=Hani
3006 ; Hani # Lo IDEOGRAPHIC CLOSING MARK
303E..303F ; Hani # So [2] IDEOGRAPHIC VARIATION INDICATOR..IDEOGRAPHIC HALF FILL SPACE
3190..3191 ; Hani # So [2] IDEOGRAPHIC ANNOTATION LINKING MARK..IDEOGRAPHIC ANNOTATION REVERSE MARK
3192..3195 ; Hani # No [4] IDEOGRAPHIC ANNOTATION ONE MARK..IDEOGRAPHIC ANNOTATION FOUR MARK
3196..319F ; Hani # So [10] IDEOGRAPHIC ANNOTATION TOP MARK..IDEOGRAPHIC ANNOTATION MAN MARK
31C0..31E3 ; Hani # So [36] CJK STROKE T..CJK STROKE Q
3220..3229 ; Hani # No [10] PARENTHESIZED IDEOGRAPH ONE..PARENTHESIZED IDEOGRAPH TEN
322A..3247 ; Hani # So [30] PARENTHESIZED IDEOGRAPH MOON..CIRCLED IDEOGRAPH KOTO
3280..3289 ; Hani # No [10] CIRCLED IDEOGRAPH ONE..CIRCLED IDEOGRAPH TEN
328A..32B0 ; Hani # So [39] CIRCLED IDEOGRAPH MOON..CIRCLED IDEOGRAPH NIGHT
32C0..32CB ; Hani # So [12] IDEOGRAPHIC TELEGRAPH SYMBOL FOR JANUARY..IDEOGRAPHIC TELEGRAPH SYMBOL FOR DECEMBER
32FF ; Hani # So SQUARE ERA NAME REIWA
3358..3370 ; Hani # So [25] IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR ZERO..IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY-FOUR
337B..337F ; Hani # So [5] SQUARE ERA NAME HEISEI..SQUARE CORPORATION
33E0..33FE ; Hani # So [31] IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY ONE..IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY THIRTY-ONE
1D360..1D371 ; Hani # No [18] COUNTING ROD UNIT DIGIT ONE..COUNTING ROD TENS DIGIT NINE
1F250..1F251 ; Hani # So [2] CIRCLED IDEOGRAPH ADVANTAGE..CIRCLED IDEOGRAPH ACCEPT
# Total code points: 238
# ================================================
# Script_Extensions=Latn
0363..036F ; Latn # Mn [13] COMBINING LATIN SMALL LETTER A..COMBINING LATIN SMALL LETTER X
# Total code points: 13
# ================================================
# Script_Extensions=Nand
1CFA ; Nand # Lo VEDIC SIGN DOUBLE ANUSVARA ANTARGOMUKHA
# Total code points: 1
# ================================================
# Script_Extensions=Syrc
1DFA ; Syrc # Mn COMBINING DOT BELOW LEFT
# Total code points: 1
# ================================================
# Script_Extensions=Arab Copt
102E0 ; Arab Copt # Mn COPTIC EPACT THOUSANDS MARK
102E1..102FB ; Arab Copt # No [27] COPTIC EPACT DIGIT ONE..COPTIC EPACT NUMBER NINE HUNDRED
# Total code points: 28
# ================================================
# Script_Extensions=Arab Rohg
06D4 ; Arab Rohg # Po ARABIC FULL STOP
# Total code points: 1
# ================================================
# Script_Extensions=Arab Nkoo
FD3E ; Arab Nkoo # Pe ORNATE LEFT PARENTHESIS
FD3F ; Arab Nkoo # Ps ORNATE RIGHT PARENTHESIS
# Total code points: 2
# ================================================
# Script_Extensions=Arab Syrc
064B..0655 ; Arab Syrc # Mn [11] ARABIC FATHATAN..ARABIC HAMZA BELOW
0670 ; Arab Syrc # Mn ARABIC LETTER SUPERSCRIPT ALEF
# Total code points: 12
# ================================================
# Script_Extensions=Arab Thaa
FDF2 ; Arab Thaa # Lo ARABIC LIGATURE ALLAH ISOLATED FORM
FDFD ; Arab Thaa # So ARABIC LIGATURE BISMILLAH AR-RAHMAN AR-RAHEEM
# Total code points: 2
# ================================================
# Script_Extensions=Beng Deva
1CD5..1CD6 ; Beng Deva # Mn [2] VEDIC TONE YAJURVEDIC AGGRAVATED INDEPENDENT SVARITA..VEDIC TONE YAJURVEDIC INDEPENDENT SVARITA
1CD8 ; Beng Deva # Mn VEDIC TONE CANDRA BELOW
1CE1 ; Beng Deva # Mc VEDIC TONE ATHARVAVEDIC INDEPENDENT SVARITA
1CEA ; Beng Deva # Lo VEDIC SIGN ANUSVARA BAHIRGOMUKHA
1CED ; Beng Deva # Mn VEDIC SIGN TIRYAK
1CF5..1CF6 ; Beng Deva # Lo [2] VEDIC SIGN JIHVAMULIYA..VEDIC SIGN UPADHMANIYA
A8F1 ; Beng Deva # Mn COMBINING DEVANAGARI SIGN AVAGRAHA
# Total code points: 9
# ================================================
# Script_Extensions=Bopo Hani
302A..302D ; Bopo Hani # Mn [4] IDEOGRAPHIC LEVEL TONE MARK..IDEOGRAPHIC ENTERING TONE MARK
# Total code points: 4
# ================================================
# Script_Extensions=Bugi Java
A9CF ; Bugi Java # Lm JAVANESE PANGRANGKEP
# Total code points: 1
# ================================================
# Script_Extensions=Cprt Linb
10102 ; Cprt Linb # Po AEGEAN CHECK MARK
10137..1013F ; Cprt Linb # So [9] AEGEAN WEIGHT BASE UNIT..AEGEAN MEASURE THIRD SUBUNIT
# Total code points: 10
# ================================================
# Script_Extensions=Cyrl Glag
0484 ; Cyrl Glag # Mn COMBINING CYRILLIC PALATALIZATION
0487 ; Cyrl Glag # Mn COMBINING CYRILLIC POKRYTIE
2E43 ; Cyrl Glag # Po DASH WITH LEFT UPTURN
A66F ; Cyrl Glag # Mn COMBINING CYRILLIC VZMET
# Total code points: 4
# ================================================
# Script_Extensions=Cyrl Latn
0485..0486 ; Cyrl Latn # Mn [2] COMBINING CYRILLIC DASIA PNEUMATA..COMBINING CYRILLIC PSILI PNEUMATA
# Total code points: 2
# ================================================
# Script_Extensions=Cyrl Perm
0483 ; Cyrl Perm # Mn COMBINING CYRILLIC TITLO
# Total code points: 1
# ================================================
# Script_Extensions=Cyrl Syrc
1DF8 ; Cyrl Syrc # Mn COMBINING DOT ABOVE LEFT
# Total code points: 1
# ================================================
# Script_Extensions=Deva Gran
1CD3 ; Deva Gran # Po VEDIC SIGN NIHSHVASA
1CF3 ; Deva Gran # Lo VEDIC SIGN ROTATED ARDHAVISARGA
1CF8..1CF9 ; Deva Gran # Mn [2] VEDIC TONE RING ABOVE..VEDIC TONE DOUBLE RING ABOVE
# Total code points: 4
# ================================================
# Script_Extensions=Deva Nand
1CE9 ; Deva Nand # Lo VEDIC SIGN ANUSVARA ANTARGOMUKHA
# Total code points: 1
# ================================================
# Script_Extensions=Deva Shrd
1CD7 ; Deva Shrd # Mn VEDIC TONE YAJURVEDIC KATHAKA INDEPENDENT SVARITA
1CD9 ; Deva Shrd # Mn VEDIC TONE YAJURVEDIC KATHAKA INDEPENDENT SVARITA SCHROEDER
1CDC..1CDD ; Deva Shrd # Mn [2] VEDIC TONE KATHAKA ANUDATTA..VEDIC TONE DOT BELOW
1CE0 ; Deva Shrd # Mn VEDIC TONE RIGVEDIC KASHMIRI INDEPENDENT SVARITA
# Total code points: 5
# ================================================
# Script_Extensions=Deva Taml
A8F3 ; Deva Taml # Lo DEVANAGARI SIGN CANDRABINDU VIRAMA
# Total code points: 1
# ================================================
# Script_Extensions=Geor Latn
10FB ; Geor Latn # Po GEORGIAN PARAGRAPH SEPARATOR
# Total code points: 1
# ================================================
# Script_Extensions=Gran Taml
0BE6..0BEF ; Gran Taml # Nd [10] TAMIL DIGIT ZERO..TAMIL DIGIT NINE
0BF0..0BF2 ; Gran Taml # No [3] TAMIL NUMBER TEN..TAMIL NUMBER ONE THOUSAND
0BF3 ; Gran Taml # So TAMIL DAY SIGN
11301 ; Gran Taml # Mn GRANTHA SIGN CANDRABINDU
11303 ; Gran Taml # Mc GRANTHA SIGN VISARGA
1133B..1133C ; Gran Taml # Mn [2] COMBINING BINDU BELOW..GRANTHA SIGN NUKTA
11FD0..11FD1 ; Gran Taml # No [2] TAMIL FRACTION ONE QUARTER..TAMIL FRACTION ONE HALF-1
11FD3 ; Gran Taml # No TAMIL FRACTION THREE QUARTERS
# Total code points: 21
# ================================================
# Script_Extensions=Gujr Khoj
0AE6..0AEF ; Gujr Khoj # Nd [10] GUJARATI DIGIT ZERO..GUJARATI DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Guru Mult
0A66..0A6F ; Guru Mult # Nd [10] GURMUKHI DIGIT ZERO..GURMUKHI DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Hani Latn
A700..A707 ; Hani Latn # Sk [8] MODIFIER LETTER CHINESE TONE YIN PING..MODIFIER LETTER CHINESE TONE YANG RU
# Total code points: 8
# ================================================
# Script_Extensions=Hira Kana
3031..3035 ; Hira Kana # Lm [5] VERTICAL KANA REPEAT MARK..VERTICAL KANA REPEAT MARK LOWER HALF
3099..309A ; Hira Kana # Mn [2] COMBINING KATAKANA-HIRAGANA VOICED SOUND MARK..COMBINING KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK
309B..309C ; Hira Kana # Sk [2] KATAKANA-HIRAGANA VOICED SOUND MARK..KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK
30A0 ; Hira Kana # Pd KATAKANA-HIRAGANA DOUBLE HYPHEN
30FC ; Hira Kana # Lm KATAKANA-HIRAGANA PROLONGED SOUND MARK
FF70 ; Hira Kana # Lm HALFWIDTH KATAKANA-HIRAGANA PROLONGED SOUND MARK
FF9E..FF9F ; Hira Kana # Lm [2] HALFWIDTH KATAKANA VOICED SOUND MARK..HALFWIDTH KATAKANA SEMI-VOICED SOUND MARK
# Total code points: 14
# ================================================
# Script_Extensions=Knda Nand
0CE6..0CEF ; Knda Nand # Nd [10] KANNADA DIGIT ZERO..KANNADA DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Latn Mong
202F ; Latn Mong # Zs NARROW NO-BREAK SPACE
# Total code points: 1
# ================================================
# Script_Extensions=Mani Ougr
10AF2 ; Mani Ougr # Po MANICHAEAN PUNCTUATION DOUBLE DOT WITHIN DOT
# Total code points: 1
# ================================================
# Script_Extensions=Mong Phag
1802..1803 ; Mong Phag # Po [2] MONGOLIAN COMMA..MONGOLIAN FULL STOP
1805 ; Mong Phag # Po MONGOLIAN FOUR DOTS
# Total code points: 3
# ================================================
# Script_Extensions=Arab Syrc Thaa
061C ; Arab Syrc Thaa # Cf ARABIC LETTER MARK
# Total code points: 1
# ================================================
# Script_Extensions=Arab Thaa Yezi
0660..0669 ; Arab Thaa Yezi # Nd [10] ARABIC-INDIC DIGIT ZERO..ARABIC-INDIC DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Beng Cakm Sylo
09E6..09EF ; Beng Cakm Sylo # Nd [10] BENGALI DIGIT ZERO..BENGALI DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Cakm Mymr Tale
1040..1049 ; Cakm Mymr Tale # Nd [10] MYANMAR DIGIT ZERO..MYANMAR DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Cpmn Cprt Linb
10100..10101 ; Cpmn Cprt Linb # Po [2] AEGEAN WORD SEPARATOR LINE..AEGEAN WORD SEPARATOR DOT
# Total code points: 2
# ================================================
# Script_Extensions=Cprt Lina Linb
10107..10133 ; Cprt Lina Linb # No [45] AEGEAN NUMBER ONE..AEGEAN NUMBER NINETY THOUSAND
# Total code points: 45
# ================================================
# Script_Extensions=Deva Gran Knda
1CF4 ; Deva Gran Knda # Mn VEDIC TONE CANDRA ABOVE
# Total code points: 1
# ================================================
# Script_Extensions=Deva Gran Latn
20F0 ; Deva Gran Latn # Mn COMBINING ASTERISK ABOVE
# Total code points: 1
# ================================================
# Script_Extensions=Hani Hira Kana
303C ; Hani Hira Kana # Lo MASU MARK
303D ; Hani Hira Kana # Po PART ALTERNATION MARK
# Total code points: 2
# ================================================
# Script_Extensions=Kali Latn Mymr
A92E ; Kali Latn Mymr # Po KAYAH LI SIGN CWI
# Total code points: 1
# ================================================
# Script_Extensions=Beng Deva Gran Knda
1CD0 ; Beng Deva Gran Knda # Mn VEDIC TONE KARSHANA
1CD2 ; Beng Deva Gran Knda # Mn VEDIC TONE PRENKHA
# Total code points: 2
# ================================================
# Script_Extensions=Buhd Hano Tagb Tglg
1735..1736 ; Buhd Hano Tagb Tglg # Po [2] PHILIPPINE SINGLE PUNCTUATION..PHILIPPINE DOUBLE PUNCTUATION
# Total code points: 2
# ================================================
# Script_Extensions=Deva Dogr Kthi Mahj
0966..096F ; Deva Dogr Kthi Mahj # Nd [10] DEVANAGARI DIGIT ZERO..DEVANAGARI DIGIT NINE
# Total code points: 10
# ================================================
# Script_Extensions=Bopo Hang Hani Hira Kana
3003 ; Bopo Hang Hani Hira Kana # Po DITTO MARK
3013 ; Bopo Hang Hani Hira Kana # So GETA MARK
301C ; Bopo Hang Hani Hira Kana # Pd WAVE DASH
301D ; Bopo Hang Hani Hira Kana # Ps REVERSED DOUBLE PRIME QUOTATION MARK
301E..301F ; Bopo Hang Hani Hira Kana # Pe [2] DOUBLE PRIME QUOTATION MARK..LOW DOUBLE PRIME QUOTATION MARK
3030 ; Bopo Hang Hani Hira Kana # Pd WAVY DASH
3037 ; Bopo Hang Hani Hira Kana # So IDEOGRAPHIC TELEGRAPH LINE FEED SEPARATOR SYMBOL
FE45..FE46 ; Bopo Hang Hani Hira Kana # Po [2] SESAME DOT..WHITE SESAME DOT
# Total code points: 10
# ================================================
# Script_Extensions=Arab Nkoo Rohg Syrc Thaa Yezi
060C ; Arab Nkoo Rohg Syrc Thaa Yezi # Po ARABIC COMMA
061B ; Arab Nkoo Rohg Syrc Thaa Yezi # Po ARABIC SEMICOLON
# Total code points: 2
# ================================================
# Script_Extensions=Bopo Hang Hani Hira Kana Yiii
3001..3002 ; Bopo Hang Hani Hira Kana Yiii # Po [2] IDEOGRAPHIC COMMA..IDEOGRAPHIC FULL STOP
3008 ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT ANGLE BRACKET
3009 ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT ANGLE BRACKET
300A ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT DOUBLE ANGLE BRACKET
300B ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT DOUBLE ANGLE BRACKET
300C ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT CORNER BRACKET
300D ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT CORNER BRACKET
300E ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT WHITE CORNER BRACKET
300F ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT WHITE CORNER BRACKET
3010 ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT BLACK LENTICULAR BRACKET
3011 ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT BLACK LENTICULAR BRACKET
3014 ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT TORTOISE SHELL BRACKET
3015 ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT TORTOISE SHELL BRACKET
3016 ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT WHITE LENTICULAR BRACKET
3017 ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT WHITE LENTICULAR BRACKET
3018 ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT WHITE TORTOISE SHELL BRACKET
3019 ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT WHITE TORTOISE SHELL BRACKET
301A ; Bopo Hang Hani Hira Kana Yiii # Ps LEFT WHITE SQUARE BRACKET
301B ; Bopo Hang Hani Hira Kana Yiii # Pe RIGHT WHITE SQUARE BRACKET
30FB ; Bopo Hang Hani Hira Kana Yiii # Po KATAKANA MIDDLE DOT
FF61 ; Bopo Hang Hani Hira Kana Yiii # Po HALFWIDTH IDEOGRAPHIC FULL STOP
FF62 ; Bopo Hang Hani Hira Kana Yiii # Ps HALFWIDTH LEFT CORNER BRACKET
FF63 ; Bopo Hang Hani Hira Kana Yiii # Pe HALFWIDTH RIGHT CORNER BRACKET
FF64..FF65 ; Bopo Hang Hani Hira Kana Yiii # Po [2] HALFWIDTH IDEOGRAPHIC COMMA..HALFWIDTH KATAKANA MIDDLE DOT
# Total code points: 26
# ================================================
# Script_Extensions=Deva Knda Mlym Orya Taml Telu
1CDA ; Deva Knda Mlym Orya Taml Telu # Mn VEDIC TONE DOUBLE SVARITA
# Total code points: 1
# ================================================
# Script_Extensions=Adlm Arab Nkoo Rohg Syrc Thaa Yezi
061F ; Adlm Arab Nkoo Rohg Syrc Thaa Yezi # Po ARABIC QUESTION MARK
# Total code points: 1
# ================================================
# Script_Extensions=Beng Deva Gran Knda Nand Orya Telu Tirh
1CF2 ; Beng Deva Gran Knda Nand Orya Telu Tirh # Lo VEDIC SIGN ARDHAVISARGA
# Total code points: 1
# ================================================
# Script_Extensions=Adlm Arab Mand Mani Ougr Phlp Rohg Sogd Syrc
0640 ; Adlm Arab Mand Mani Ougr Phlp Rohg Sogd Syrc # Lm ARABIC TATWEEL
# Total code points: 1
# ================================================
# Script_Extensions=Deva Dogr Gujr Guru Khoj Kthi Mahj Modi Sind Takr Tirh
A836..A837 ; Deva Dogr Gujr Guru Khoj Kthi Mahj Modi Sind Takr Tirh # So [2] NORTH INDIC QUARTER MARK..NORTH INDIC PLACEHOLDER MARK
A838 ; Deva Dogr Gujr Guru Khoj Kthi Mahj Modi Sind Takr Tirh # Sc NORTH INDIC RUPEE MARK
A839 ; Deva Dogr Gujr Guru Khoj Kthi Mahj Modi Sind Takr Tirh # So NORTH INDIC QUANTITY MARK
# Total code points: 4
# ================================================
# Script_Extensions=Beng Deva Gran Gujr Guru Knda Latn Mlym Orya Taml Telu Tirh
0952 ; Beng Deva Gran Gujr Guru Knda Latn Mlym Orya Taml Telu Tirh # Mn DEVANAGARI STRESS SIGN ANUDATTA
# Total code points: 1
# ================================================
# Script_Extensions=Beng Deva Gran Gujr Guru Knda Latn Mlym Orya Shrd Taml Telu Tirh
0951 ; Beng Deva Gran Gujr Guru Knda Latn Mlym Orya Shrd Taml Telu Tirh # Mn DEVANAGARI STRESS SIGN UDATTA
# Total code points: 1
# ================================================
# Script_Extensions=Deva Dogr Gujr Guru Khoj Knda Kthi Mahj Modi Nand Sind Takr Tirh
A833..A835 ; Deva Dogr Gujr Guru Khoj Knda Kthi Mahj Modi Nand Sind Takr Tirh # No [3] NORTH INDIC FRACTION ONE SIXTEENTH..NORTH INDIC FRACTION THREE SIXTEENTHS
# Total code points: 3
# ================================================
# Script_Extensions=Deva Dogr Gujr Guru Khoj Knda Kthi Mahj Mlym Modi Nand Sind Takr Tirh
A830..A832 ; Deva Dogr Gujr Guru Khoj Knda Kthi Mahj Mlym Modi Nand Sind Takr Tirh # No [3] NORTH INDIC FRACTION ONE QUARTER..NORTH INDIC FRACTION THREE QUARTERS
# Total code points: 3
# ================================================
# Script_Extensions=Beng Deva Dogr Gong Gonm Gran Gujr Guru Knda Mahj Mlym Nand Orya Sind Sinh Sylo Takr Taml Telu Tirh
0964 ; Beng Deva Dogr Gong Gonm Gran Gujr Guru Knda Mahj Mlym Nand Orya Sind Sinh Sylo Takr Taml Telu Tirh # Po DEVANAGARI DANDA
# Total code points: 1
# ================================================
# Script_Extensions=Beng Deva Dogr Gong Gonm Gran Gujr Guru Knda Limb Mahj Mlym Nand Orya Sind Sinh Sylo Takr Taml Telu Tirh
0965 ; Beng Deva Dogr Gong Gonm Gran Gujr Guru Knda Limb Mahj Mlym Nand Orya Sind Sinh Sylo Takr Taml Telu Tirh # Po DEVANAGARI DOUBLE DANDA
# Total code points: 1
# EOF

2991
admin/unidata/Scripts.txt Normal file
View file

File diff suppressed because it is too large Load diff

6
admin/unidata/blocks.awk
View file

@ -98,7 +98,7 @@ function name2alias(name , w, w2) {
else if (name ~ /arabic/) return "arabic"
else if (name ~ /^greek/) return "greek"
else if (name ~ /^coptic/) return "coptic"
else if (name ~ /cuneiform number/) return "cuneiform-numbers-and-punctuation"
else if (name ~ /cuneiform number/) return "cuneiform"
else if (name ~ /cuneiform/) return "cuneiform"
else if (name ~ /mathematical alphanumeric symbol/) return "mathematical"
else if (name ~ /punctuation|mathematical|arrows|currency|superscript|small form variants|geometric|dingbats|enclosed|alchemical|pictograph|emoticon|transport/) return "symbol"
@ -113,9 +113,11 @@ function name2alias(name , w, w2) {
else if (name ~/^(specials|tags)$/) return 0
else if (name ~ /linear b/) return "linear-b"
else if (name ~ /aramaic/) return "aramaic"
else if (name ~ /rumi num/) return "rumi-number"
else if (name ~ /rumi num/) return "arabic"
else if (name ~ /duployan|shorthand/) return "duployan-shorthand"
else if (name ~ /sutton signwriting/) return "sutton-sign-writing"
else if (name ~ /sinhala archaic number/) return "sinhala"
else if (name ~ /tangut components/) return "tangut"
sub(/^small /, "", name)
sub(/ (extended|extensions*|supplement).*/, "", name)

9637
admin/unidata/confusables.txt Normal file
View file

File diff suppressed because it is too large Load diff

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

@ -89,6 +89,7 @@
;; PROPn: string representing the nth property value
(eval-when-compile (require 'cl-lib))
(require 'generate-lisp-file)
(defvar unidata-list nil)
@ -209,9 +210,15 @@ Property value is one of the following symbols:
;; The assignment of default values to blocks of code points
;; follows the file DerivedBidiClass.txt from the Unicode
;; Character Database (UCD).
(L (#x0600 #x06FF AL) (#xFB50 #xFDFF AL) (#xFE70 #xFEFF AL)
(#x0590 #x05FF R) (#x07C0 #x08FF R)
(#xFB1D #xFB4F R) (#x10800 #x10FFF R) (#x1E800 #x1EFFF R))
(L (#x0600 #x07BF AL) (#x0860 #x08FF AL) (#xFB50 #xFDCF AL)
(#xFDF0 #xFDFF AL) (#xFE70 #xFEFF AL) (#x10D00 #x10D3F AL)
(#x10F30 #x10F6F AL) (#x1EC70 #x1ECBF AL) (#x1ED00 #x1ED4F AL)
(#x1EE00 #x1EEFF AL)
(#x0590 #x05FF R) (#x07C0 #x085F R) (#xFB1D #xFB4F R)
(#x10800 #x10CFF R) (#x10D40 #x10F2F R) (#x10F70 #x10FFF R)
(#x1E800 #x1EC6F R) (#x1ECC0 #x1ECFF R) (#x1ED50 #x1EDFF R)
(#x1EF00 #x1EFFF R)
(#x20A0 #x20CF ET))
;; The order of elements must be in sync with bidi_type_t in
;; src/dispextern.h.
(L R EN AN BN B AL LRE LRO RLE RLO PDF LRI RLI FSI PDI
@ -1416,13 +1423,13 @@ Property value is a symbol `o' (Open), `c' (Close), or `n' (None)."
(or elt (user-error "Unknown output file: %s" basename))
(or noninteractive (message "Generating %s..." file))
(with-temp-file file
(insert ";;; " basename " -*- lexical-binding:t -*-
;; " copyright "
;; Generated from Unicode data files by unidata-gen.el.
;; The sources for this file are found in the admin/unidata/ directory in
;; the Emacs sources. The Unicode data files are used under the
;; Unicode Terms of Use, as contained in the file copyright.html in that
;; same directory.\n")
(generate-lisp-file-heading
basename 'unidata-gen-file
:commentary (concat copyright " \
The sources for this file are found in the admin/unidata/ directory in \
the Emacs sources. The Unicode data files are used under the \
Unicode Terms of Use, as contained in the file copyright.html in that \
same directory."))
(dolist (proplist (cdr elt))
(let ((prop (unidata-prop-prop proplist))
(index (unidata-prop-index proplist))
@ -1440,38 +1447,189 @@ Property value is a symbol `o' (Open), `c' (Close), or `n' (None)."
(set-char-table-extra-slot table 3 describer))
(insert (format "(define-char-code-property '%S\n %S\n %S)\n"
prop table docstring))))
(insert ";; Local Variables:\n"
";; coding: utf-8\n"
";; version-control: never\n"
";; no-byte-compile: t\n"
";; no-update-autoloads: t\n"
";; End:\n\n"
(format ";;; %s ends here\n" basename)))))
(generate-lisp-file-trailer basename :inhibit-provide t))))
(or noninteractive (message "Generating %s...done" file)))
(defun unidata-gen-charprop (&optional charprop-file)
(defun unidata-gen-charprop (&optional charprop-file text)
(or charprop-file (setq charprop-file (pop command-line-args-left)))
(with-temp-file charprop-file
(insert ";; Automatically generated by unidata-gen.el."
" -*- lexical-binding: t -*-\n"
";; See the admin/unidata/ directory in the Emacs sources.\n")
(dolist (elt unidata-file-alist)
(dolist (proplist (cdr elt))
(insert (format "(define-char-code-property '%S %S\n %S)\n"
(unidata-prop-prop proplist) (car elt)
(unidata-prop-docstring proplist)))))
(generate-lisp-file-heading
charprop-file 'unidata-gen-charprop
:commentary "See the admin/unidata/ directory in the Emacs sources.")
(if text
(insert text)
(dolist (elt unidata-file-alist)
(dolist (proplist (cdr elt))
(insert (format "(define-char-code-property '%S %S\n %S)\n"
(unidata-prop-prop proplist) (car elt)
(unidata-prop-docstring proplist))))))
(or noninteractive (message "Writing %s..." charprop-file))
(insert "\n"
"(provide 'charprop)\n"
" \n"
";; Local Variables:\n"
";; coding: utf-8\n"
";; version-control: never\n"
";; no-byte-compile: t\n"
";; no-update-autoloads: t\n"
";; End:\n\n"
(format ";;; %s ends here\n"
(file-name-nondirectory charprop-file)))))
(generate-lisp-file-trailer charprop-file)))
(defun unidata-gen-scripts (&optional file)
;; Running from Makefile.
(unless file
(setq file (pop command-line-args-left)))
(let ((aliases (unidata-gen--read-script-aliases))
(table (make-char-table nil))
(segmented (make-hash-table :test #'equal)))
;; First parse the scripts.
(with-temp-buffer
(unidata-gen--insert-file "Scripts.txt")
(while (not (eobp))
;; 1700..1711 ; Tagalog # Lo [18] TAGALOG LETTER A..TAGALOG
(when (looking-at "\\([0-9A-F]+\\)\\(?:\\.\\.\\([0-9A-F]+\\)\\)? +; +\\([^ ]+\\) +#")
(let ((start (string-to-number (match-string 1) 16))
(end (and (match-string 2)
(string-to-number (match-string 2) 16)))
(scripts (list (intern (string-replace
"_" "-"
(downcase (match-string 3)))))))
(set-char-table-range
table (if end (cons start end) start) scripts)))
(forward-line 1)))
;; Then parse the file that lists "other scripts" that characters
;; may appear in, and add those.
(with-temp-buffer
(unidata-gen--insert-file "ScriptExtensions.txt")
(while (not (eobp))
;; 102E0 ; Arab Copt # Mn COPTIC EPACT THOUSANDS MARK
(when (looking-at "\\([0-9A-F]+\\)\\(?:\\.\\.\\([0-9A-F]+\\)\\)? +; +\\([^#]+\\)")
(let ((start (string-to-number (match-string 1) 16))
(end (and (match-string 2)
(string-to-number (match-string 2) 16)))
(scripts
(mapcar
(lambda (alias)
(intern (string-replace
"_" "-" (downcase
(gethash alias aliases)))))
(split-string (string-trim (match-string 3))))))
(dolist (script scripts)
(dotimes (i (- (1+ (or end start)) start))
(set-char-table-range
table (+ i start)
(append (elt table (+ i start)) (list script)))))))
(forward-line 1)))
;; Then go through the data and collect into buckets based on
;; identical script lists.
(map-char-table
(lambda (key value)
;; `map-char-table' is reused, so copy it.
(push (if (consp key)
(cons (car key) (cdr key))
key)
;; Keep the first element first, but sort the rest.
(gethash (cons (car value)
(sort (remq (car value) value) #'string<))
segmented)))
table)
;; Then go through the data and collect into buckets based on
(let ((scripts nil))
(maphash
(lambda (segment chars)
(push (cons segment chars) scripts))
segmented)
(setq scripts (sort scripts (lambda (s1 s2)
(string< (caar s1) (caar s2)))))
(with-temp-buffer
(insert "(textsec--create-script-table '(\n")
(dolist (script scripts)
(insert "(" (prin1-to-string (car script)) "\n")
(insert " " (prin1-to-string (cdr script)))
(insert ")\n"))
(insert "))\n")
;; Write the file.
(unidata-gen-charprop file (buffer-string))))))
(defun unidata-gen--read-script-aliases ()
(let ((aliases (make-hash-table :test #'equal)))
(with-temp-buffer
(unidata-gen--insert-file "PropertyValueAliases.txt")
(unless (re-search-forward "^# Script " nil t)
(error "Can't find the Script section"))
(forward-line 2)
(while (looking-at "sc *;")
(let ((elem (split-string (buffer-substring (point) (line-end-position))
";" nil "[ \t]+")))
(setf (gethash (nth 1 elem) aliases)
(nth 2 elem)))
(forward-line 1))
aliases)))
(defun unidata-gen--insert-file (name)
(insert-file-contents
(expand-file-name (concat "../admin/unidata/" name)
data-directory)))
(defun unidata-gen-confusable (&optional file)
;; Running from Makefile.
(unless file
(setq file (pop command-line-args-left)))
(let ((regexp
(concat "^\\([[:xdigit:]]+\\)"
"[ \t]*;[ \t]*"
"\\([[:space:][:xdigit:]]+\\)"
"[ \t]*;"))
(map (make-hash-table)))
(with-temp-buffer
(unidata-gen--insert-file "confusables.txt")
(while (re-search-forward regexp nil t)
(let ((from (match-string 1))
(to (string-trim (match-string 2))))
(setf (gethash (string-to-number from 16) map)
(apply #'string (mapcar (lambda (string)
(string-to-number string 16))
(split-string to)))))))
(with-temp-buffer
(insert "(defconst uni-confusable-table\n")
(let ((print-length nil))
(prin1 map (current-buffer)))
(insert ")")
(unidata-gen-charprop file (buffer-string)))))
(defun unidata-gen-idna-mapping (&optional file)
;; Running from Makefile.
(unless file
(setq file (pop command-line-args-left)))
(let ((map (make-char-table nil)))
(with-temp-buffer
(unidata-gen--insert-file "IdnaMappingTable.txt")
(while (re-search-forward "^\\([0-9A-F]+\\)\\(?:\\.\\.\\([0-9A-F]+\\)\\)? +; +\\([^ ]+\\) +\\(?:; +\\([ 0-9A-F]+\\)\\)?"
nil t)
(let ((start (match-string 1))
(end (match-string 2))
(status (match-string 3))
(mapped (match-string 4)))
;; Make reading the file slightly faster by using `t'
;; instead of `disallowed' all over the place.
(when (string-match-p "\\`disallowed" status)
(setq status "t"))
(unless (or (equal status "valid")
(equal status "deviation"))
(set-char-table-range
map
(if end
(cons (string-to-number start 16)
(string-to-number end 16))
(string-to-number start 16))
(cond
((equal status "mapped")
(apply #'string
(mapcar (lambda (char)
(string-to-number char 16))
(split-string (string-trim mapped)))))
(t
(intern status))))))))
(with-temp-buffer
(insert "(defconst idna-mapping-table\n")
(let ((print-length nil))
(prin1 map (current-buffer)))
(insert ")")
(unidata-gen-charprop file (buffer-string)))))

5
admin/upload-manuals
View file

@ -334,7 +334,10 @@ for d in html_node/*; do
[ -e $webdir/manual/$d ] || {
echo "New directory: $d"
mkdir $webdir/manual/$d
$cvs add $webdir/manual/$d || die "add error"
(
cd $webdir/manual
$cvs add $d || die "add error"
)
}
new=

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".

43
build-aux/config.guess vendored
View file

@ -1,14 +1,14 @@
#! /bin/sh
# Attempt to guess a canonical system name.
# Copyright 1992-2021 Free Software Foundation, Inc.
# Copyright 1992-2022 Free Software Foundation, Inc.
# shellcheck disable=SC2006,SC2268 # see below for rationale
timestamp='2021-11-30'
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
# the Free Software Foundation; either version 3 of the License, or
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
@ -60,7 +60,7 @@ version="\
GNU config.guess ($timestamp)
Originally written by Per Bothner.
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."
@ -929,6 +929,9 @@ EOF
i*:PW*:*)
GUESS=$UNAME_MACHINE-pc-pw32
;;
*:SerenityOS:*:*)
GUESS=$UNAME_MACHINE-pc-serenity
;;
*:Interix*:*)
case $UNAME_MACHINE in
x86)
@ -1148,16 +1151,27 @@ EOF
;;
x86_64:Linux:*:*)
set_cc_for_build
CPU=$UNAME_MACHINE
LIBCABI=$LIBC
if test "$CC_FOR_BUILD" != no_compiler_found; then
if (echo '#ifdef __ILP32__'; echo IS_X32; echo '#endif') | \
(CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \
grep IS_X32 >/dev/null
then
LIBCABI=${LIBC}x32
fi
ABI=64
sed 's/^ //' << EOF > "$dummy.c"
#ifdef __i386__
ABI=x86
#else
#ifdef __ILP32__
ABI=x32
#endif
#endif
EOF
cc_set_abi=`$CC_FOR_BUILD -E "$dummy.c" 2>/dev/null | grep '^ABI' | sed 's, ,,g'`
eval "$cc_set_abi"
case $ABI in
x86) CPU=i686 ;;
x32) LIBCABI=${LIBC}x32 ;;
esac
fi
GUESS=$UNAME_MACHINE-pc-linux-$LIBCABI
GUESS=$CPU-pc-linux-$LIBCABI
;;
xtensa*:Linux:*:*)
GUESS=$UNAME_MACHINE-unknown-linux-$LIBC
@ -1364,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

8
build-aux/config.sub vendored
View file

@ -1,14 +1,14 @@
#! /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
# the Free Software Foundation; either version 3 of the License, or
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
@ -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."

4
build-aux/git-hooks/pre-commit
View file

@ -45,7 +45,9 @@ git_diff='git diff --cached --name-only --diff-filter=A'
# 'git diff' will backslash escape tabs and newlines, so we don't have
# to worry about word splitting here.
$git_diff $head | sane_egrep 'ChangeLog|^-|/-|[^-+./_0-9A-Z_a-z]' | while IFS= read -r new_name; do
$git_diff $head |
LC_ALL=C grep -E 'ChangeLog|^-|/-|[^-+./_0-9A-Z_a-z]' |
while IFS= read -r new_name; do
case $new_name in
-* | */-*)
echo "$new_name: File name component begins with '-'."

2
build-aux/gitlog-to-changelog
View file

@ -35,7 +35,7 @@
eval 'exec perl -wSx "$0" "$@"'
if 0;
my $VERSION = '2021-02-24 23:42'; # UTC
my $VERSION = '2022-01-27 18:49'; # UTC
# The definition above must lie within the first 8 lines in order
# for the Emacs time-stamp write hook (at end) to update it.
# If you change this file with Emacs, please let the write hook

2
build-aux/update-copyright
View file

@ -7,7 +7,7 @@
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# the Free Software Foundation, either version 3, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,

3
config.bat
View file

@ -310,6 +310,9 @@ rm -f makefile.tmp
sed -f ../msdos/sedlibcf.inp < gnulib.mk-in > gnulib.tmp
sed -f ../msdos/sedlibmk.inp < gnulib.tmp > gnulib.mk
rm -f gnulib.tmp
Rem Create directories in lib/ that MKDIR_P is supposed to create
Rem but I have no idea how to do that on MS-DOS.
mkdir sys
Rem Create .d files for new files in lib/ and lib/malloc/
If Not Exist deps\stamp mkdir deps
for %%f in (*.c) do @call ..\msdos\depfiles.bat %%f

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

5
doc/emacs/abbrevs.texi
View file

@ -411,10 +411,13 @@ away in the buffer to search for an expansion.
@vindex dabbrev-check-all-buffers
@vindex dabbrev-check-other-buffers
@vindex dabbrev-ignored-buffer-modes
After scanning the current buffer, @kbd{M-/} normally searches other
buffers. The variables @code{dabbrev-check-all-buffers} and
@code{dabbrev-check-other-buffers} can be used to determine which
other buffers, if any, are searched.
other buffers, if any, are searched. Buffers that have major modes
derived from any of the modes in @code{dabbrev-ignored-buffer-modes}
are ignored.
@vindex dabbrev-ignored-buffer-names
@vindex dabbrev-ignored-buffer-regexps

4
doc/emacs/anti.texi
View file

@ -30,10 +30,6 @@ Fancy text shaping and display is becoming less important as you move
back in time. The @code{ftx} font backend is again part of Emacs, for
the same reasons.
@item
As Motif becomes more and more important with moving farther into the
past, we've reinstated the code which supports Motif in Emacs.
@item
Emacs once again supports versions 5.3 and older OpenBSD systems,
which will be needed as you move back in time.

24
doc/emacs/basic.texi
View file

@ -347,11 +347,11 @@ move to the column number specified by the argument's numeric value.
@kindex C-x C-n
@findex set-goal-column
Use the current column of point as the @dfn{semipermanent goal column}
for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}) in the current
buffer. When a semipermanent goal column is in effect, those commands
always try to move to this column, or as close as possible to it,
after moving vertically. The goal column remains in effect until
canceled.
(@code{set-goal-column}) in the current buffer. When a semipermanent
goal column is in effect, @kbd{C-n}, @kbd{C-p}, @kbd{<prior>} and
@kbd{<next>} always try to move to this column, or as close as
possible to it, after moving vertically. The goal column remains in
effect until canceled.
@item C-u C-x C-n
Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to
@ -653,14 +653,14 @@ Toggle automatic display of the current line number or column number.
displayed before each line, see @ref{Display Custom}.
@item M-=
Display the number of lines, words, and characters that are present in
the region (@code{count-words-region}). @xref{Mark}, for information
about the region.
Display the number of lines, sentences, words, and characters that are
present in the region (@code{count-words-region}). @xref{Mark}, for
information about the region.
@item M-x count-words
Display the number of lines, words, and characters that are present in
the buffer. If the region is active (@pxref{Mark}), display the
numbers for the region instead.
Display the number of lines, sentences, words, and characters that are
present in the buffer. If the region is active (@pxref{Mark}),
display the numbers for the region instead.
@item C-x =
Display the character code of character after point, character position of
@ -689,7 +689,7 @@ narrowed region and the line number relative to the whole buffer.
@kindex M-=
@findex count-words-region
@kbd{M-=} (@code{count-words-region}) displays a message reporting
the number of lines, words, and characters in the region
the number of lines, sentences, words, and characters in the region
(@pxref{Mark}, for an explanation of the region). With a prefix
argument, @kbd{C-u M-=}, the command displays a count for the entire
buffer.

23
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
@ -629,7 +630,6 @@ buffer, but killing an indirect buffer has no effect on its base buffer.
One way to use indirect buffers is to display multiple views of an
outline. @xref{Outline Views}.
@vindex clone-indirect-buffer-hook
A quick and handy way to make an indirect buffer is with the command
@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
buffer whose base buffer is the current buffer. With a numeric
@ -637,14 +637,27 @@ argument, it prompts for the name of the indirect buffer; otherwise it
uses the name of the current buffer, with a @samp{<@var{n}>} suffix
added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
works like @kbd{M-x clone-indirect-buffer}, but it selects the new
buffer in another window. These functions run the hook
@code{clone-indirect-buffer-hook} after creating the indirect buffer.
buffer in another window.
The more general way to make an indirect buffer is with the command
@kbd{M-x make-indirect-buffer}. It creates an indirect buffer
named @var{indirect-name} from a buffer @var{base-buffer}, prompting for
both using the minibuffer.
@vindex clone-indirect-buffer-hook
The functions that create indirect buffers run the hook
@code{clone-indirect-buffer-hook} after creating the indirect buffer.
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

29
doc/emacs/building.texi
View file

@ -138,6 +138,14 @@ of environment variable settings; each element should be a string of
the form @code{"@var{envvarname}=@var{value}"}. These environment
variable settings override the usual ones.
@vindex compilation-max-output-line-length
Displaying extremely long lines in compilation output can slow Emacs
down. Lines that are longer than
@code{compilation-max-output-line-length} will have the portion that's
exceeds that limit hidden behind a button that can be clicked on to
reveal the hidden portion. Set this variable to @code{nil} to never
hide anything.
@node Compilation Mode
@section Compilation Mode
@ -170,7 +178,9 @@ list of customization variables and faces.
If you change the variable
@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
Emacs automatically visits the locus of the first error message that
appears in the @file{*compilation*} buffer.
appears in the @file{*compilation*} buffer. (This variable can also
have the values @code{if-location-known} and @code{first-known}, which
modify the conditions for automatically visiting the error locus.)
Compilation mode provides the following additional commands. These
commands can also be used in @file{*grep*} buffers, where the
@ -279,6 +289,19 @@ window so that the current error message is @var{n} lines from the
top, whether or not there is a fringe; the default value, @code{nil},
gives the behavior described above.
@vindex compilation-hidden-output
Compilation output can sometimes be very verbose, and much of it isn't
of particular interest to a user. The
@code{compilation-hidden-output} user option should either be a regexp
or a list of regexps, and output that matches will be made invisible.
For instance, to hide the verbose output from recursive makefiles, you
can say something like:
@lisp
(setq compilation-hidden-output
'("^make[^\n]+\n"))
@end lisp
@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
To parse messages from the compiler, Compilation mode uses the
@ -1734,6 +1757,10 @@ which is provided for evaluating Emacs Lisp expressions interactively.
Its major mode is Lisp Interaction mode. You can also enable Lisp
Interaction mode by typing @kbd{M-x lisp-interaction-mode}.
@findex scratch-buffer
If you kill the @file{*scratch*} buffer, you can recreate it with
the @kbd{M-x scratch-buffer} command.
@findex eval-print-last-sexp
@kindex C-j @r{(Lisp Interaction mode)}
In the @file{*scratch*} buffer, and other Lisp Interaction mode

74
doc/emacs/cmdargs.texi
View file

@ -294,6 +294,22 @@ which will invoke Emacs with @samp{--script} and supply the name of
the script file as @var{file}. Emacs Lisp then treats the @samp{#!}
on this first line as a comment delimiter.
@item -x
@opindex -x
This option can only be used in executable script files, and should be
invoked like this:
@example
#!/usr/bin/emacs -x
@end example
This is like @samp{--script}, but suppresses loading the init files
(like @code{--quick}), and can't be used on a normal command line
(since it doesn't specify the script to load). In addition, when it
reaches the end of the script, it exits Emacs and uses the value of
the final form as the exit value from the script (if the final value
is numerical). Otherwise, it will always exit with a zero value.
@item --no-build-details
@opindex --no-build-details
@cindex build details
@ -329,6 +345,10 @@ option does this too, but other options like @samp{-q} do not.
Do not include the @file{site-lisp} directories in @code{load-path}
(@pxref{Init File}). The @samp{-Q} option does this too.
@item --init-directory
@opindex --init-directory
Specify the directory to use when looking for the Emacs init files.
@item --no-splash
@opindex --no-splash
@cindex splash screen
@ -780,29 +800,45 @@ changing any environment or registry settings.
@pindex addpm, MS-Windows installation program
@cindex registry, setting environment variables (MS-Windows)
On MS-Windows, the installation program @command{addpm.exe} adds
values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the
@file{HKEY_LOCAL_MACHINE} section of the system registry, under
@file{/Software/GNU/Emacs}. It does this because there is no standard
place to set environment variables across different versions of
Windows. Running @command{addpm.exe} is no longer strictly necessary
in recent versions of Emacs, but if you are upgrading from an older
version, running @command{addpm.exe} ensures that you do not have
older registry entries from a previous installation, which may not be
compatible with the latest version of Emacs.
When Emacs starts, as well as checking the environment, it also checks
the System Registry for those variables and for @env{HOME}, @env{LANG}
and @env{PRELOAD_WINSOCK}.
On MS-Windows, the environment variables @env{emacs_dir},
@env{EMACSLOADPATH}, @env{EMACSDATA}, @env{EMACSPATH}, @env{EMACSDOC},
@env{SHELL}, @env{TERM}, @env{HOME}, @env{LANG}, and
@env{PRELOAD_WINSOCK} can also be set in the @file{HKEY_CURRENT_USER}
or the @file{HKEY_LOCAL_MACHINE} section of the system registry, under
the @file{/Software/GNU/Emacs} key. When Emacs starts, as well as
checking the environment, it also checks the system registry for those
variables.
To determine the value of those variables, Emacs goes through the
following procedure. First, the environment is checked. If the
variable is not found there, Emacs looks for registry keys by that
name under @file{/Software/GNU/Emacs}; first in the
following procedure. First, it checks the environment. If the
variable is not found there, Emacs looks for a registry key by the
name of the variable under @file{/Software/GNU/Emacs}; first in the
@file{HKEY_CURRENT_USER} section of the registry, and if not found
there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs
still cannot determine the values, compiled-in defaults are used.
still cannot determine the values, it uses the compiled-in defaults.
Note that the registry settings have global system-wide effect: they
will affect all Emacs sessions run on the system. Thus, if you run
different Emacs versions, or use both installed and un-installed Emacs
executables, or build newer versions of Emacs, the settings in the
registry will cause all of them to use the same directories, which is
probably not what you want. For this reason, @emph{we recommend
against setting these variables in the registry}. If you have such
settings in the registry, we recommend that you remove them.
If you run the Emacs MS-Windows installation program
@command{addpm.exe}, it will update any existing registry settings of
the @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL}, and @env{TERM} variables
to have the values suitable for the installed Emacs version with which
@command{addpm.exe} came. Note that @command{addpm.exe} will
@emph{not} create any registry setting that didn't exist, it will only
update existing settings, which are most probably inherited from an
old Emacs installation, so that they are compatible with the newly
installed Emacs version. Running @command{addpm.exe} is no longer
necessary when installing recent versions of Emacs, so we only
recommend doing that if you are upgrading from an older version, and
cannot remove these settings from the registry for some reason.
In addition to the environment variables above, you can also add
settings to the @file{/Software/GNU/Emacs} registry key to specify X

59
doc/emacs/custom.texi
View file

@ -844,6 +844,21 @@ otherwise stated, affects only the current Emacs session. The only
way to alter the variable in future sessions is to put something in
your initialization file (@pxref{Init File}).
If you're setting a customizable variable in your initialization
file, and you don't want to use the Customize interface, you can use
the @code{setopt} macro. For instance:
@findex setopt
@example
(setopt fill-column 75)
@end example
This works the same as @code{setq}, but if the variable has any
special setter functions, they will be run automatically when using
@code{setopt}. You can also use @code{setopt} on other,
non-customizable variables, but this is less efficient than using
@code{setq}.
@node Hooks
@subsection Hooks
@cindex hook
@ -1217,6 +1232,28 @@ Manual}.
These four keywords are not really variables; setting them in any
other context has no special meaning.
If you're editing a file across Emacs versions, and a new mode has
been introduced to handle a file in a newer Emacs version, you can use
several @code{mode} entries to use the new mode (called
@code{my-new-mode}) in the new Emacs, and fall back to the old mode
(called @code{my-old-mode}) in older Emacs versions. If you're
enabling the modes in the first line of the file, can say:
@example
-*- mode: my-old; mode: my-new -*-
@end example
Emacs will use the final defined mode it finds, so in older Emacs
versions it will ignore @code{my-new-mode}, while in Emacs versions
where @code{my-new-mode} is defined, it'll ignore @code{my-old-mode}.
Similarly, in a local variable block at the end of the file:
@example
Local variables:
mode: my-old
mode: my-new
@end example
Do not use the @code{mode} keyword for minor modes. To enable or
disable a minor mode in a local variables list, use the @code{eval}
keyword with a Lisp expression that runs the mode command
@ -2219,6 +2256,22 @@ is included in the message displayed when the command is used:
"It's better to use `kill-region' instead.\n")
@end example
@findex command-query
As a less heavy-handed alternative to disabling commands, you may
want to be queried before executing a command. For instance, to be
queried before executing the @kbd{M->} (@code{end-of-buffer})
command, you could put something like the following in your init file:
@example
(command-query
'end-of-buffer
"Do you really want to go to the end of the buffer?")
@end example
By default, you'll be queried with a @kbd{y}/@kbd{n} question, but if
you give a non-@code{nil} value to the third, optional argument,
you'll be queried with @kbd{yes}/@kbd{no} instead.
@findex disable-command
@findex enable-command
You can make a command disabled either by editing the initialization
@ -2338,8 +2391,8 @@ mode when you set them with Customize, but ordinary @code{setq} won't
do that; to enable the mode in your init file, call the minor mode
command. Finally, a few customizable user options are initialized in
complex ways, and these have to be set either via the customize
interface (@pxref{Customization}) or by using
@code{customize-set-variable} (@pxref{Examining}).
interface (@pxref{Customization}), or by using
@code{customize-set-variable}/@code{setopt} (@pxref{Examining}).
The second argument to @code{setq} is an expression for the new
value of the variable. This can be a constant, a variable, or a
@ -2492,7 +2545,7 @@ Change the coding system used when using the clipboard
(@pxref{Communication Coding}).
@example
(customize-set-variable 'selection-coding-system 'utf-8)
(setopt selection-coding-system 'utf-8)
@end example
@item

93
doc/emacs/dired.texi
View file

@ -113,11 +113,17 @@ a directory's name.
@findex dired-jump-other-window
@kindex C-x C-j
@kindex C-x 4 C-j
Typing @kbd{C-x C-j} (@code{dired-jump}) in any buffer will open a
Dired buffer and move point to the line corresponding to the current
file. In Dired, move up a level and go to the previous directory's
line. Typing @kbd{C-x 4 C-j} (@code{dired-jump-other-window} has the
same effect but opens a new window for the Dired buffer.
You can ask Emacs to invoke Dired on the default-directory
(@pxref{File Names, default-directory}) of any buffer, by typing
@kbd{C-x C-j} (@code{dired-jump}). If the buffer visits a file, this
command will move point to that file's line in the Dired buffer it
shows; otherwise, point will end up on the first file in the directory
listing. As an exception, if you type @kbd{C-x C-j} in a Dired
buffer, Emacs displays the directory listing of the parent directory
and places point on the line that corresponds to the directory where
you invoked @code{dired-jump}. Typing @kbd{C-x 4 C-j}
(@code{dired-jump-other-window}) has the same effect, but displays the
Dired buffer in a new window.
The variable @code{dired-listing-switches} specifies the options to
give to @command{ls} for listing the directory; this string
@ -770,6 +776,11 @@ symbolic links as links or after dereferencing (like @samp{cp -L}).
The default is @code{nil}, which means that the symbolic links are
copied by creating new ones.
@vindex dired-keep-marker-copy
The @code{dired-keep-marker-copy} user option controls how this
command handles file marking. The default is to mark all new copies
of files with a @samp{C} mark.
@item D
@findex dired-do-delete
@kindex D @r{(Dired)}
@ -833,6 +844,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)
@ -952,6 +983,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)
@ -1001,6 +1044,7 @@ subdirectories whose names match @code{grep-find-ignored-directories}.
@findex dired-do-shell-command
@kindex ! @r{(Dired)}
@kindex X @r{(Dired)}
@vindex dired-confirm-shell-command
The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a
shell command string in the minibuffer, and runs that shell command on
one or more files. The files that the shell command operates on are
@ -1037,7 +1081,8 @@ list of file names, putting them into one tar file @file{foo.tar}.
If you want to use @samp{*} as a shell wildcard with whitespace around
it, write @samp{*""}. In the shell, this is equivalent to @samp{*};
but since the @samp{*} is not surrounded by whitespace, Dired does not
treat it specially.
treat it specially. Emacs will prompt for confirmation if you do
this, unless @code{dired-confirm-shell-command} is @code{nil}.
@item
Otherwise, if the command string contains @samp{?} surrounded by
@ -1125,9 +1170,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
@ -1285,6 +1333,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
@ -1689,9 +1743,18 @@ directory than in this one. It also marks files with no counterpart,
in both directories, as always.
@cindex drag and drop, Dired
On the X Window System, Emacs supports the drag and drop
protocol. You can drag a file object from another program, and drop
it onto a Dired buffer; this either moves, copies, or creates a link
to the file in that directory. Precisely which action is taken is
determined by the originating program. Dragging files out of a Dired
buffer is currently not supported.
@vindex dired-mouse-drag-files
On the X Window System, Emacs supports the drag and drop protocol.
You can drag a file object from another program, and drop it onto a
Dired buffer; this either moves, copies, or creates a link to the file
in that directory. Precisely which action is taken is determined by
the originating program. Dragging files out of a Dired buffer is also
supported, by enabling the user option @code{dired-mouse-drag-files},
the mouse can be used to drag files onto other programs. When set to
@code{link}, it will make the other program (typically a file manager)
create a symbolic link to the file; when set to @code{move}, it will
make the other program move the file to a new location, and setting it
to any other non-@code{nil} value will make the other program open or
create a copy of the file. The keyboard modifiers pressed during the
drag-and-drop operation can also control what action the other program
takes towards the file.

99
doc/emacs/display.texi
View file

@ -854,7 +854,8 @@ would be selected if you click a mouse or press @key{RET}.
@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 +863,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 +893,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 ajust 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
@ -1011,10 +1038,15 @@ in C comments, use this:
@end example
@findex font-lock-remove-keywords
@vindex font-lock-ignore
@noindent
To remove keywords from the font-lock highlighting patterns, use the
function @code{font-lock-remove-keywords}. @xref{Search-based
Fontification,,, elisp, The Emacs Lisp Reference Manual}.
Alternatively, you can selectively disable highlighting due to some
keywords by customizing the @code{font-lock-ignore} option,
@pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference
Manual}.
@cindex just-in-time (JIT) font-lock
@cindex background syntax highlighting
@ -1589,7 +1621,9 @@ charge on the mode-line, by using the command
@code{battery-mode-line-format} determines the way the battery charge
is displayed; the exact mode-line message depends on the operating
system, and it usually shows the current battery charge as a
percentage of the total charge.
percentage of the total charge. The functions in
@code{battery-update-functions} are run after updating the mode line,
and can be used to trigger actions based on the battery status.
@cindex mode line, 3D appearance
@cindex attributes of mode line, changing
@ -1894,12 +1928,22 @@ logical lines, so having a fringe indicator for each wrapped line
would be visually distracting. You can change this by customizing the
variable @code{visual-line-fringe-indicators}.
@vindex word-wrap-whitespace-mode
By default, Emacs only breaks lines after whitespace characters like
@key{SPC} and @key{TAB}, but does not break after whitespace
characters like @key{EN QUAD}. Emacs provides a minor mode called
@code{word-wrap-whitespace-mode} that switches on word wrapping in the
current mode, and sets up which characters to wrap lines on based on
the @code{word-wrap-whitespace-characters} user option. There's also
a globalized version of that mode called
@code{global-word-wrap-whitespace-mode}.
@vindex word-wrap-by-category
@findex modify-category-entry
@findex char-category-set
@findex category-set-mnemonics
By default, Emacs only breaks lines after whitespace characters.
That produces incorrect results when CJK and Latin text are mixed
Only breaking after whitespace character produces incorrect
results when CJK and Latin text are mixed
together (because CJK characters don't use whitespace to separate
words). You can customize the option @code{word-wrap-by-category} to
allow Emacs to break lines after any character with @samp{|} category
@ -1965,7 +2009,7 @@ The command @kbd{M-x display-line-numbers-mode} provides a
convenient way to turn on display of line numbers. This mode has a globalized
variant, @code{global-display-line-numbers-mode}. The user option
@code{display-line-numbers-type} controls which sub-mode of
line-number display, described above, will these modes activate.
line-number display, described above, these modes will activate.
@noindent
Note that line numbers are not displayed in the minibuffer and in the
@ -2082,3 +2126,14 @@ argument to suppress the effect of bold-face in this case.
byte with a decimal value of 128 is displayed as @code{\200}. To
change display to the hexadecimal format of @code{\x80}, set the
variable @code{display-raw-bytes-as-hex} to @code{t}.
Care may be needed when interpreting a raw byte when copying
text from a terminal containing an Emacs session, or when a terminal's
@code{escape-glyph} face looks like the default face. For example, by
default Emacs displays the four characters @samp{\}, @samp{2},
@samp{0}, @samp{0} with the same characters it displays a byte with
decimal value 128. The problem can be worse with hex displays, where
the raw byte 128 followed by the character @samp{7} is displayed as
@code{\x807}, which Emacs Lisp reads as the single character U+0807
SAMARITAN LETTER IT; this confusion does not occur with the
corresponding octal display @code{\2007} because octal escapes contain
at most three digits.

2
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.
@ -1192,6 +1191,7 @@ Dealing with Emacs Trouble
* 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

86
doc/emacs/files.texi
View file

@ -326,6 +326,48 @@ of @code{require-final-newline} (@pxref{Customize Save}). If you have
already visited the same file in the usual (non-literal) manner, this
command asks you whether to visit it literally instead.
@findex find-sibling-file
@vindex find-sibling-rules
Files are sometimes (loosely) tied to other files, and you could call
these files @dfn{sibling files}. For instance, when editing C files,
if you have a file called @samp{"foo.c"}, you often also have a file
called @samp{"foo.h"}, and that could be its sibling file. Or you may
have different versions of a file, for instance
@samp{"src/emacs/emacs-27/lisp/allout.el"} and
@samp{"src/emacs/emacs-28/lisp/allout.el"} might be considered
siblings. Emacs provides the @code{find-sibling-file} command to jump
between sibling files, but it's impossible to guess at which files a
user might want to be considered siblings, so Emacs lets you configure
this freely by altering the @code{find-sibling-rules} user option.
This is a list of match/expansion elements.
For instance, to do the @samp{".c"} to @samp{".h"} mapping, you could
say:
@lisp
(setq find-sibling-rules
'(("\\([^/]+\\)\\.c\\'" "\\1.h")))
@end lisp
(@code{ff-find-related-file} offers similar functionality especially
geared towards C files, @pxref{Other C Commands}.)
Or, if you want to consider all files under
@samp{"src/emacs/DIR/file-name"} to be siblings of other @var{dir}s,
you could say:
@lisp
(setq find-sibling-rules
'(("src/emacs/[^/]+/\\(.*\\)\\'" "src/emacs/.*/\\1")))
@end lisp
As you can see, this is a list of @var{(MATCH EXPANSION...)} elements.
The @var{match} is a regular expression that matches the visited file
name, and each @var{expansion} may refer to match groups by using
@samp{\\1} and so on. The resulting expansion string is then applied
to the file system to see if any files match this expansion
(interpreted as a regexp).
@vindex find-file-hook
@vindex find-file-not-found-functions
Two special hook variables allow extensions to modify the operation
@ -378,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
@ -610,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
@ -1467,8 +1512,8 @@ specified buffers.
The command @kbd{M-x compare-windows} compares the text in the
current window with that in the window that was the selected window
before you selected the current one. (For more information about
windows in Emacs, @ref{Windows}.) Comparison starts at point in each
window, after pushing each initial point value on the mark ring
windows in Emacs, @pxref{Windows}.) Comparison starts at point in
each window, after pushing each initial point value on the mark ring
(@pxref{Mark Ring}) in its respective buffer. Then it moves point
forward in each window, one character at a time, until it reaches
characters that don't match. Then the command exits.
@ -1828,6 +1873,22 @@ argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
them delete outright, instead of using the Trash, regardless of
@code{delete-by-moving-to-trash}.
If you have @code{delete-by-moving-to-trash} set, and you want to
delete files manually in Emacs from the Trash directory, using
commands like @kbd{D} (@code{dired-do-delete}) doesn't work well in
the Trash directory (it'll just give the file a new name, but won't
delete anything). If you want to be able to do this, you should
create a @code{.dir-locals.el} file containing something like the
following in the Trash directory:
@example
((dired-mode . ((delete-by-moving-to-trash . nil))))
@end example
Note, however, if you use the system ``empty trash'' command, it's
liable to also delete this @code{.dir-locals.el} file, so this should
only be done if you delete files from the Trash directory manually.
@ifnottex
If a file is under version control (@pxref{Version Control}), you
should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x
@ -2164,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

69
doc/emacs/frames.texi
View file

@ -128,6 +128,12 @@ In addition, the text in the region becomes the primary selection
non-@code{nil} value, dragging the mouse over a stretch of text also
adds the text to the kill ring. The default is @code{nil}.
If this variable is @code{non-empty}, only copy to the kill ring if
the region is non-empty. For instance, if you mouse drag an area that
is less than a half a character, you'd normally get the empty string
in your kill ring, but with @code{non-empty}, this short mouse drag
won't affect the kill ring.
@vindex mouse-scroll-min-lines
If you move the mouse off the top or bottom of the window while
dragging, the window scrolls at a steady rate until you move the mouse
@ -136,6 +142,12 @@ entirely on the screen. The number of lines scrolled per step depends
on how far away from the window edge the mouse has gone; the variable
@code{mouse-scroll-min-lines} specifies a minimum step size.
@vindex mouse-drag-mode-line-buffer
If you enable the option @code{mouse-drag-mode-line-buffer} and
dragging files is supported by the window system, then dragging the
mouse on the buffer name portion of the mode line will drag that
buffer's file to another program or frame.
@findex mouse-yank-primary
@findex mouse-yank-at-click
Clicking with the middle mouse button, @kbd{mouse-2}, moves point to
@ -211,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}
@ -512,6 +524,16 @@ frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}.
Delete the selected frame (@code{delete-frame}). This signals an
error if there is only one frame.
@item C-x 5 u
@kindex C-x 5 u
@findex undelete-frame
@findex undelete-frame-mode
When @code{undelete-frame-mode} is enabled, undelete one of the 16
most recently deleted frames. Without a prefix argument, undelete the
most recently deleted frame. With a numerical prefix argument between
1 and 16, where 1 is the most recently deleted frame, undelete the
corresponding deleted frame.
@item C-z
@kindex C-z @r{(X windows)}
Minimize (or iconify) the selected Emacs frame
@ -939,6 +961,7 @@ Speedbar,,speedbar, Speedbar Manual}.
@node Multiple Displays
@section Multiple Displays
@cindex multiple displays
@cindex display server
A single Emacs can talk to more than one X display. Initially, Emacs
uses just one display---the one specified with the @env{DISPLAY}
@ -1185,6 +1208,18 @@ the variable @code{dnd-open-file-other-window}.
The XDND and Motif drag and drop protocols, and the old KDE 1.x
protocol, are currently supported.
@vindex dnd-indicate-insertion-point
@vindex dnd-scroll-margin
It can be difficult to scroll a window or determine where dropped
text will be inserted while dragging text onto an Emacs window.
Setting the option @code{dnd-indicate-insertion-point} to a
non-@code{nil} value makes point move to the location any dropped text
will be inserted when the mouse moves in a window during drag, and
setting @code{dnd-scroll-margin} to an integer value causes a window
to be scrolled if the mouse moves within that many lines of the top
or bottom of the window during drag.
@vindex mouse-drag-and-drop-region
Emacs can also optionally drag the region with the mouse into
another portion of this or another buffer. To enable that, customize
@ -1209,6 +1244,17 @@ cursor during dragging. To suppress such behavior, set the options
@code{mouse-drag-and-drop-region-show-tooltip} and/or
@code{mouse-drag-and-drop-region-show-cursor} to @code{nil}.
@vindex mouse-drag-and-drop-region-cross-program
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
@ -1623,13 +1669,18 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also
For additional customization options for displaying tooltips, use
@kbd{M-x customize-group @key{RET} tooltip @key{RET}}.
@vindex x-gtk-use-system-tooltips
If Emacs is built with GTK+ support, it displays tooltips via GTK+,
using the default appearance of GTK+ tooltips. To disable this,
change the variable @code{x-gtk-use-system-tooltips} to @code{nil}.
If you do this, or if Emacs is built without GTK+ support, most
attributes of the tooltip text are specified by the @code{tooltip}
face, and by X resources (@pxref{X Resources}).
@vindex use-system-tooltips
If Emacs is built with the GTK+ toolkit, Nextstep windowing, or
Haiku windowing support, it displays tooltips via the toolkit, using
the default appearance of the toolkit's tooltips.@footnote{The
foreground and background colors of toolkit-created tooltips on
Nextstep can also be customized by setting the @code{foreground} and
@code{background} frame parameters that are part of
@code{tooltip-frame-parameters}.} To disable this, change the variable
@code{use-system-tooltips} to @code{nil}. If you do this, or if Emacs
is built without the appropriate windowing support, most attributes of
the tooltip text are specified by the @code{tooltip} face, and by X
resources (@pxref{X Resources}).
@dfn{GUD tooltips} are special tooltips that show the values of
variables when debugging a program with GUD@. @xref{Debugger

17
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
@ -229,9 +230,11 @@ from a variety of coding systems when reading or writing it.
@item Command
A command is a Lisp function specially defined to be able to serve as
a key binding in Emacs or to be invoked by its name
(@pxref{Glossary---Command Name}). When you type a key sequence
(q.v.), its binding (q.v.@:) is looked up in the relevant keymaps
(q.v.@:) to find the command to run. @xref{Commands}.
(@pxref{Glossary---Command Name}). (Another term for @dfn{command} is
@dfn{interactive function}---they are used interchangeably.) When you
type a key sequence (q.v.), its binding (q.v.@:) is looked up in the
relevant keymaps (q.v.@:) to find the command to run.
@xref{Commands}.
@item Command History
@xref{Glossary---Minibuffer History}.
@ -775,6 +778,14 @@ typing sequences of @acronym{ASCII} characters (q.v.). @xref{Input Methods}.
Insertion means adding text into the buffer, either from the keyboard
or from some other place in Emacs.
@item Interactive Function
A different term for @dfn{command} (q.v.).
@item Interactive Invocation
A function can be called from Lisp code, or called as a user level
command (via @kbd{M-x}, a key binding or a menu). In the latter case,
the function is said to be @dfn{called interactively}.
@item Interlocking
@xref{Glossary---File Locking}.

20
doc/emacs/haiku.texi
View file

@ -85,16 +85,24 @@ instead.
@cindex tooltips (haiku)
@cindex haiku tooltips
@vindex haiku-use-system-tooltips
On Haiku, Emacs defaults to using the system tooltip mechanism.
This usually leads to more responsive tooltips, but the tooltips will
not be able to display text properties or faces. If you need those
features, customize the variable @code{haiku-use-system-tooltips} to
the nil value, and Emacs will use its own implementation of tooltips.
features, customize the variable @code{use-system-tooltips} to the
@code{nil} value, and Emacs will use its own implementation of
tooltips.
Both system tooltips and Emacs's own tooltips cannot display above
the menu bar, so help text in the menu bar will display in the echo
area instead.
@cindex X resources on Haiku
Unlike the X window system, Haiku does not have a system-wide
resource database. Since many important options are specified via
X resources (@pxref{X Resources}), an emulation is provided: upon
startup, Emacs will load a file named @file{GNU Emacs} inside the user
configuration directory (normally @file{/boot/home/config/settings}),
which should be a flattened system message where keys and values are
both strings, and correspond to attributes and their values
respectively.
You can create such a file with the @command{xmlbmessage} tool.
@subsection What to do when Emacs crashes
@cindex crashes, Haiku

43
doc/emacs/help.texi
View file

@ -20,10 +20,28 @@ commands (@code{help-for-help}). You can scroll the list with
@key{SPC} and @key{DEL}, then type the help command you want. To
cancel, type @kbd{C-g}.
@cindex help buffer
Many help commands display their information in a special @dfn{help
buffer}. In this buffer, you can type @key{SPC} and @key{DEL} to
scroll and type @key{RET} to follow hyperlinks. @xref{Help Mode}.
@vindex help-window-select
By default, help commands display the help buffer in a separate
window without selecting that window. The variable
@code{help-window-select} controls this: its default value is
@code{nil}; if it's customized to the value @code{t}, the help window
is unconditionally selected by help commands, and if its value is
@code{other}, the help window is selected only if there are more than
two windows on the selected frame.
@vindex help-window-keep-selected
Conversely, many commands in the @samp{*Help*} buffer will pop up a
new window to display the results. For instance, clicking on the link
to show the source code, or using the @key{i} command to display the
manual entry, will (by default) pop up a new window. If
@code{help-window-keep-selected} is changed to non-@code{nil}, the
window displaying the @samp{*Help*} buffer will be reused instead.
@cindex searching documentation efficiently
@cindex looking for a subject in documentation
If you are looking for a certain feature, but don't know what it is
@ -182,7 +200,10 @@ programming language you are editing (@code{info-lookup-symbol}).
@item C-h .
Display the help message for a special text area, if point is in one
(@code{display-local-help}). (These include, for example, links in
@file{*Help*} buffers.) @xref{Help Echo}.
@file{*Help*} buffers.) @xref{Help Echo}. If you invoke
this command with a prefix argument, @kbd{C-u C-h .}, and point is on
a button or a widget, this command will pop a new buffer that
describes that button/widget.
@end table
@node Key Help
@ -332,9 +353,9 @@ are included varies depending on the command used.
@cindex apropos
The @dfn{apropos} commands answer questions like, ``What are the
commands for working with files?'' More precisely, you specify an
@dfn{apropos pattern}, which means either a word, a list of words, or
a regular expression.
commands for working with files?'' More precisely, you specify your
query as an @dfn{apropos pattern}, which is either a word, a list of
words, or a regular expression.
Each of the following apropos commands reads an apropos pattern in
the minibuffer, searches for items that match the pattern, and
@ -393,6 +414,12 @@ comes with a brief description and a list of keys you can currently
invoke it with. In our example, it would say that you can invoke
@code{find-file} by typing @kbd{C-x C-f}.
@vindex help-window-select@r{, and apropos commands}
By default, the window showing the apropos buffer with the results
of the query is not selected, but you can cause it to be selected by
customizing the variable @code{help-window-select} to any
non-@code{nil} value.
For more information about a function definition, variable or symbol
property listed in an apropos buffer, you can click on it with
@kbd{mouse-1} or @kbd{mouse-2}, or move there and type @key{RET}.
@ -478,6 +505,9 @@ View the source of the current help topic (if any)
(@code{help-view-source}).
@item i
Look up the current topic in the manual(s) (@code{help-goto-info}).
@item I
Look up the current topic in the Emacs Lisp manual
(@code{help-goto-lispref-info}).
@item c
Customize the variable or the face (@code{help-customize}).
@end table
@ -512,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

65
doc/emacs/killing.texi
View file

@ -111,24 +111,27 @@ active (@pxref{Using Region}).
@kindex M-\
@findex delete-horizontal-space
@kindex M-SPC
@findex just-one-space
@findex cycle-spacing
The other delete commands are those that delete only whitespace
The other delete commands are those that delete only whitespace
characters: spaces, tabs and newlines. @kbd{M-\}
(@code{delete-horizontal-space}) deletes all the spaces and tab
characters before and after point. With a prefix argument, this only
deletes spaces and tab characters before point. @kbd{M-@key{SPC}}
(@code{just-one-space}) does likewise but leaves a single space before
deletes spaces and tab characters before point.
@findex just-one-space
@code{just-one-space} does likewise but leaves a single space before
point, regardless of the number of spaces that existed previously
(even if there were none before). With a numeric argument @var{n}, it
leaves @var{n} spaces before point if @var{n} is positive; if @var{n}
is negative, it deletes newlines in addition to spaces and tabs,
leaving @minus{}@var{n} spaces before point. The command @code{cycle-spacing}
acts like a more flexible version of @code{just-one-space}. It
does different things if you call it repeatedly in succession.
The first call acts like @code{just-one-space}, the next removes
all whitespace, and a third call restores the original whitespace.
leaving @minus{}@var{n} spaces before point.
@kindex M-SPC
@findex cycle-spacing
@vindex cycle-spacing-actions
The command @code{cycle-spacing} (@kbd{M-@key{SPC}}) acts like a more
flexible version of @code{just-one-space}. It performs different
space cleanup actions defined by @code{cycle-spacing-actions}, in a
cyclic manner, if you call it repeatedly in succession.
@kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
after the current line. If the current line is blank, it deletes all
@ -540,11 +543,11 @@ clipboard.
clipboard contents are normally lost. Optionally, Emacs can save the
existing clipboard contents to the kill ring, preventing you from
losing the old clipboard data. If
@code{save-interprogram-paste-before-kill} changed to a number, then
this data is copied over if it's smaller (in characters) than this
number. If this variable is any other non-@code{nil} value, it's
always copied over---at the risk of high memory consumption if that
data turns out to be large.
@code{save-interprogram-paste-before-kill} has been set to a number,
then the data is copied over if it's smaller (in characters) than
this number. If this variable is any other non-@code{nil} value, the
data is always copied over---at the risk of high memory consumption if
that data turns out to be large.
Yank commands, such as @kbd{C-y} (@code{yank}), also use the
clipboard. If another application ``owns'' the clipboard---i.e., if
@ -567,8 +570,8 @@ change the variable @code{select-enable-clipboard} to @code{nil}.
instance, a web browser will usually let you choose ``Copy Image'' on
images, and this image will be put on the clipboard. On capable
platforms, Emacs can yank these objects with the @code{yank-media}
command---but only in modes that have support for it (@pxref{Yanking
Media,,, elisp, The Emacs Lisp Reference Manual}).
command---but only in modes that have support for it (@w{@pxref{Yanking
Media,,, elisp, The Emacs Lisp Reference Manual}}).
@cindex clipboard manager
@vindex x-select-enable-clipboard-manager
@ -607,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
@ -636,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.
@ -698,6 +708,9 @@ lines, much like @kbd{mouse-1}.
If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-mouse-2} yanks
at point. Then it does not matter precisely where you click, or even
which of the frame's windows you click on. @xref{Mouse Commands}.
This user option also effects interactive search: if it is
non-@code{nil}, yanking with the mouse anywhere in the frame will add
the text to the search string.
@node Accumulating Text
@section Accumulating Text

2
doc/emacs/kmacro.texi
View file

@ -179,7 +179,7 @@ itself counts as the first repetition, since it is executed as you
define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3
additional times.
@findex kdb-macro-redisplay
@findex kmacro-redisplay
@kindex C-x C-k d
While executing a long-running keyboard macro, it can sometimes be
useful to trigger a redisplay (to show how far we've gotten). The

42
doc/emacs/macos.texi
View file

@ -223,6 +223,7 @@ keystrokes. Here is a list of these events.
@table @key
@item ns-open-file
@cindex ns-open-file event
@vindex ns-pop-up-frames
This event occurs when another Nextstep application requests that
Emacs open a file. A typical reason for this would be a user
@ -239,52 +240,29 @@ means to always visit the file in a new frame. A value of @code{nil}
means to always visit the file in the selected frame.
@item ns-open-temp-file
@cindex ns-open-temp-file event
This event occurs when another application requests that Emacs open a
temporary file. By default, this is handled by just generating a
@code{ns-open-file} event, the results of which are described above.
@item ns-open-file-line
@cindex ns-open-file-line event
Some applications, such as ProjectBuilder and gdb, request not only a
particular file, but also a particular line or sequence of lines in
the file. Emacs handles this by visiting that file and highlighting
the requested line (@code{ns-open-file-select-line}).
@item ns-drag-n-drop
This event occurs when a user drags an object from another application
into an Emacs frame. The default behavior is to open a file in the
window under the mouse, or to insert text at point of the window under
the mouse.
The sending application has some limited ability to decide how Emacs
handles the sent object, but the user may override the default
behavior by holding one or more modifier key.
@table @kbd
@item control
Insert as text in the current buffer. If the object is a file, this
will insert the filename.
@item alt/option
Attempt to open the object as though it is a file or URL.
@item super/command
Perform the default action for the type. This can be useful when an
application is overriding the default behavior.
@end table
The modifier keys listed above are defined by macOS and are unaffected
by user changes to the modifiers in Emacs.
@item ns-change-font
This event occurs when the user selects a font in a Nextstep font
panel (which can be opened with @kbd{Cmd-t}). The default behavior is
to adjust the font of the selected frame
(@code{ns-respond-to-changefont}). The name and size of the selected
font are stored in the variables @code{ns-input-font} and
@code{ns-input-fontsize}, respectively.
@item ns-power-off
@cindex ns-power-off event
This event occurs when the user logs out and Emacs is still running, or when
``Quit Emacs'' is chosen from the application menu.
The default behavior is to save all file-visiting buffers.
@item ns-show-prefs
@cindex ns-show-prefs event
This event occurs when the user selects ``Preferences'' from the
application menu. By default, it is bound to the command
@code{customize}.
@end table
@cindex using Nextstep services (macOS)

100
doc/emacs/maintaining.texi
View file

@ -1055,15 +1055,6 @@ prefix argument is a repeat count.
Move to the next revision entry. A numeric prefix argument is a
repeat count.
@item P
Move to the log of the previous file, if showing logs for a multi-file
VC fileset. Otherwise, just move to the beginning of the log. A
numeric prefix argument is a repeat count.
@item N
Move to the log of the next file, if showing logs for a multi-file VC
fileset. A numeric prefix argument is a repeat count.
@item a
Annotate the revision on the current line (@pxref{Old Revisions}).
@ -1325,6 +1316,12 @@ point is on a directory entry, mark all files in that directory tree
(@code{vc-dir-mark-all-files}). With a prefix argument, mark all
listed files and directories.
@findex vc-dir-mark-by-regexp
@item %
You can use this command to mark files by regexp
(@code{vc-dir-mark-by-regexp}). If given a prefix, unmark files
instead.
@item G
Add the file under point to the list of files that the VC should
ignore (@code{vc-dir-ignore}). For instance, if the VC is Git, it
@ -1669,6 +1666,9 @@ support additional types of projects.
Which files do or don't belong to a project is also determined by
the project back-end. For example, the VC back-end doesn't consider
``ignored'' files (@pxref{VC Ignore}) to be part of the project.
Also, the VC Project back-end considers ``untracked'' files by default.
That behavior is controllable with the variable
@code{project-vc-include-untracked}.
@menu
* Project File Commands:: Commands for handling project files.
@ -1728,6 +1728,7 @@ doesn't seem to belong to a recognizable project, these commands
prompt you for the project directory.
@findex project-find-file
@vindex vc-directory-exclusion-list
The command @kbd{C-x p f} (@code{project-find-file}) is a convenient
way of visiting files (@pxref{Visiting}) that belong to the current
project. Unlike @kbd{C-x C-f}, this command doesn't require to type
@ -1736,7 +1737,9 @@ base name (i.e., omit the leading directories). In addition, the
completion candidates considered by the command include only the files
belonging to the current project, and nothing else. If there's a file
name at point, this command offers that file as the first element of
the ``future history''.
the ``future history''. If given a prefix, include all files under
the project root, except for @acronym{VCS} directories listed in
@code{vc-directory-exclusion-list}.
@findex project-find-regexp
The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to
@ -1831,11 +1834,14 @@ buffers as candidates for completion.
@findex project-kill-buffers
@vindex project-kill-buffer-conditions
@vindex project-kill-buffers-display-buffer-list
When you finish working on the project, you may wish to kill all the
buffers that belong to the project, to keep your Emacs session
smaller. The command @kbd{C-x p k} (@code{project-kill-buffers})
accomplishes that: it kills all the buffers that belong to the current
project that satisfy any of @code{project-kill-buffer-conditions}.
project that satisfy any of @code{project-kill-buffer-conditions}. If
@code{project-kill-buffers-display-buffer-list} is non-@code{nil}, the
buffers to be killed will be displayed first.
@node Switching Projects
@subsection Switching Projects
@ -2216,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
@ -2317,10 +2323,15 @@ them.
@item M-?
Find all the references for the identifier at point.
@item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
@item M-x xref-query-replace-in-results @key{RET} @var{replacement} @key{RET}
@itemx C-u M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Interactively replace @var{regexp} with @var{replacement} in the names
of all the identifiers shown in the @file{*xref*} buffer.
@item M-x xref-find-references-and-replace @key{RET} @var{from} @key{RET} @var{to} @key{RET}
Interactively rename all instances of the identifier @var{from} to the
new name @var{to}.
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
Search for @var{regexp} through the files in the selected tags
table.
@ -2358,13 +2369,21 @@ shown. The default value is @code{nil}, which just shows the results
in the @file{*xref*} buffer, but doesn't select any of them.
@findex xref-query-replace-in-results
@kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
names and a replacement string, just like ordinary @kbd{M-x
query-replace-regexp}. It then performs the specified replacement in
the names of the matching identifiers in all the places in all the
files where these identifiers are referenced. This is useful when you
@kbd{M-x xref-query-replace-in-results} reads a @var{replacement}
string, just like ordinary @kbd{M-x query-replace-regexp}. It then
renames the identifiers shown in the @file{*xref*} buffer in all the
places in all the files where these identifiers are referenced, such
that their new name is @var{replacement}. This is useful when you
rename your identifiers as part of refactoring. This command should
be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.
be invoked in the @file{*xref*} buffer generated by @kbd{M-?}. With a
prefix argument, the command also prompts for a regexp to match
identifier names, and renames that regexp in the names of the matching
identifiers with @var{replacement}.
@findex xref-find-references-and-replace
@kbd{M-x xref-find-references-and-replace} works similarly to
@code{xref-query-replace-in-results}, but is more convenient when you
want to rename a single identifier specified by its name @var{from}.
@findex tags-search
@kbd{M-x tags-search} reads a regexp using the minibuffer, then
@ -2807,6 +2826,13 @@ place of a file name on the command line. @command{etags} will read from
standard input and mark the produced tags as belonging to the file
@var{file}.
For C and C++, if the source files don't observe the GNU Coding
Standards' convention if having braces (@samp{@{} and @samp{@}}) in
column zero only for top-level definitions, like functions and
@code{struct} definitions, we advise that you use the
@samp{--ignore-indentation} option, to prevent @command{etags} from
incorrectly interpreting closing braces in column zero.
@samp{etags --help} outputs the list of the languages @command{etags}
knows, and the file name rules for guessing the language. It also prints
a list of all the available @command{etags} options, together with a short
@ -2979,11 +3005,12 @@ etags --language=none \
@findex visit-tags-table
Emacs has at any time at most one @dfn{selected} tags table. All
the commands for working with tags tables use the selected one. To
select a tags table, type @kbd{M-x visit-tags-table}, which reads the
tags table file name as an argument, with @file{TAGS} defaulting to
the first directory that contains a file named @file{TAGS} encountered
when recursively searching upward from the default directory.
the commands for working with tags tables use the selected one first.
To select a tags table, type @kbd{M-x visit-tags-table}, which reads
the tags table file name as an argument, with @file{TAGS} defaulting
to the first directory that contains a file named @file{TAGS}
encountered when recursively searching upward from the default
directory.
@vindex tags-file-name
Emacs does not actually read in the tags table contents until you
@ -2993,16 +3020,25 @@ variable's initial value is @code{nil}; that value tells all the
commands for working with tags tables that they must ask for a tags
table file name to use.
Using @code{visit-tags-table} when a tags table is already loaded
gives you a choice: you can add the new tags table to the current list
of tags tables, or start a new list. The tags commands use all the tags
tables in the current list. If you start a new list, the new tags table
is used @emph{instead} of others. If you add the new table to the
current list, it is used @emph{as well as} the others.
In addition to the selected tags table, Emacs maintains the list of
several tags tables that you use together. For example, if you are
working on a program that uses a library, you may wish to have the
tags tables of both the program and the library available, so that
Emacs could easily find identifiers from both. If the selected tags
table doesn't have the identifier or doesn't mention the source file a
tags command needs, the command will try using all the other tags
tables in the current list of tags tables.
Using @code{visit-tags-table} to load a new tags table when another
tags table is already loaded gives you a choice: you can add the new
tags table to the current list of tags tables, or discard the current
list and start a new list. If you start a new list, the new tags
table is used @emph{instead} of others. If you add the new table to
the current list, it is used @emph{as well as} the others.
@vindex tags-table-list
You can specify a precise list of tags tables by setting the variable
@code{tags-table-list} to a list of strings, like this:
@code{tags-table-list} to a list of directory names, like this:
@c keep this on two lines for formatting in smallbook
@example

13
doc/emacs/mark.texi
View file

@ -291,12 +291,23 @@ instead signal an error if the mark is inactive.
@cindex Delete Selection mode
@cindex mode, Delete Selection
@findex delete-selection-mode
@vindex delete-selection-temporary-region
By default, text insertion occurs normally even if the mark is
active---for example, typing @kbd{a} inserts the character @samp{a},
then deactivates the mark. Delete Selection mode, a minor mode,
modifies this behavior: if you enable that mode, then inserting text
while the mark is active causes the text in the region to be deleted
first. To toggle Delete Selection mode on or off, type @kbd{M-x
first. However, you can tune this behavior by customizing the
@code{delete-selection-temporary-region} option. Its default value is
@code{nil}, but you can set it to @code{t}, in which case only
temporarily-active regions will be replaced: those which are set by
dragging the mouse (@pxref{Setting Mark}) or by shift-selection
(@pxref{Shift Selection}), as well as by @kbd{C-u C-x C-x} when
Transient Mark Mode is disabled. You can further tune the behavior by
setting @code{delete-selection-temporary-region} to @code{selection}:
then temporary regions by @kbd{C-u C-x C-x} won't be replaced, only
the ones activated by dragging the mouse or shift-selection. To
toggle Delete Selection mode on or off, type @kbd{M-x
delete-selection-mode}.
@node Mark Ring

104
doc/emacs/mini.texi
View file

@ -195,7 +195,14 @@ use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}).
often bound to @dfn{completion commands}, which allow you to easily
fill in the desired text without typing all of it. @xref{Completion}.
As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB},
@key{SPC}, or @samp{?} character.
@key{SPC}, or @samp{?} character. If you want to make @key{SPC} and
@key{?} insert normally instead of starting completion, you can put
the following in your init file:
@lisp
(keymap-unset minibuffer-local-completion-map "SPC")
(keymap-unset minibuffer-local-completion-map "?")
@end lisp
For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a
minibuffer moves point to the beginning of the argument text, not the
@ -371,6 +378,20 @@ window. You can display the same list with @kbd{?}
used with the completion list:
@table @kbd
@vindex minibuffer-completion-auto-choose
@item M-@key{DOWN}
@itemx M-@key{UP}
While in the minibuffer, these keys navigate through the completions
displayed in the completions buffer. When
@code{minibuffer-completion-auto-choose} is non-@code{nil} (which is
the default), using these commands also inserts the current completion
candidate into the minibuffer. If
@code{minibuffer-completion-auto-choose} is @code{nil}, you can use
the @kbd{M-@key{RET}} command to insert the completion candidates into
the minibuffer. By default, that exits the minibuffer, but with a
prefix argument, @kbd{C-u M-@key{RET}} inserts the currently active
candidate without exiting the minibuffer.
@findex switch-to-completions
@item M-v
@itemx @key{PageUp}
@ -386,7 +407,10 @@ ways (@pxref{Windows}).
@itemx mouse-1
@itemx mouse-2
While in the completion list buffer, this chooses the completion at
point (@code{choose-completion}).
point (@code{choose-completion}). With a prefix argument, @kbd{C-u
@key{RET}} inserts the completion at point into the minibuffer, but
doesn't exit the minibuffer---thus, you can change your mind and
choose another candidate.
@findex next-completion
@item @key{TAB}
@ -617,11 +641,34 @@ completion alternatives in the completion list.
@vindex completion-auto-help
If @code{completion-auto-help} is set to @code{nil}, the completion
commands never display the completion list buffer; you must type
@kbd{?} to display the list. If the value is @code{lazy}, Emacs only
@kbd{?} to display the list. If the value is @code{lazy}, Emacs only
shows the completion list buffer on the second attempt to complete.
In other words, if there is nothing to complete, the first @key{TAB}
echoes @samp{Next char not unique}; the second @key{TAB} shows the
completion list buffer.
completion list buffer. If the value is @code{always}, the completion
list buffer is always shown when completion is attempted.
The display of the completion list buffer after it is shown for the
first time is also controlled by @code{completion-auto-help}. If the
value is @code{t} or @code{lazy}, the window showing the completions
pops down when Emacs is able to complete (and may pop up again if
Emacs is again unable to complete after you type some more text); if
the value is @code{always}, the window pops down only when you exit
the completion. The value @code{visible} is a hybrid: it behaves like
@code{t} when it decides whether to pop up the window showing the
completion list buffer, and like @code{always} when it decides whether
to pop it down.
@vindex completion-auto-select
Emacs can optionally select the window showing the completions when
it shows that window. To enable this behavior, customize the user
option @code{completion-auto-select} to @code{t}, which changes the
behavior of @key{TAB} when Emacs pops up the completions: pressing
@kbd{@key{TAB}} will switch to the completion list buffer, and you can
then move to a candidate by cursor motion commands and select it with
@kbd{@key{RET}}. If the value of @code{completion-auto-select} is
@code{second-tab}, then the first @kbd{@key{TAB}} will pop up the
completions list buffer, and the second one will switch to it.
@vindex completion-cycle-threshold
If @code{completion-cycle-threshold} is non-@code{nil}, completion
@ -638,11 +685,50 @@ behavior only when there are @var{n} or fewer alternatives.
@vindex completions-format
When displaying completions, Emacs will normally pop up a new buffer
to display the completions. The completions will (by default) be
sorted in columns horizontally in alphabetical order, but this can be
changed by changing the @code{completions-format} user option. If
@code{vertical}, sort the completions vertically in columns instead,
and if @code{one-column}, just use a single column.
to display the completions. The completions will by default be sorted
horizontally, using as many columns as will fit in the window-width,
but this can be changed by customizing the @code{completions-format}
user option. If its value is @code{vertical}, Emacs will sort the
completions vertically instead, and if it's @code{one-column}, Emacs
will use just one column.
@vindex completions-sort
The @code{completions-sort} user option controls the order in which
the completions are sorted in the @samp{*Completions*} buffer. The
default is @code{alphabetical}, which sorts in alphabetical order.
The value @code{nil} disables sorting. The value can also be a
function, which will be called with the list of completions, and
should return the list in the desired order.
@vindex completions-max-height
When @code{completions-max-height} is non-@code{nil}, it limits the
size of the completions window. It is specified in lines and include
mode, header line and a bottom divider, if any. For a more complex
control of the Completion window display properties, you can use
@code{display-buffer-alist} (@pxref{Buffer Display Action
Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp
Reference Manual}).
@vindex completions-header-format
The variable @code{completions-header-format} is a format spec string to
control the informative line shown before the completions list of
candidates. If it contains a @samp{%s} construct, that get replaced
by the number of completions shown in the completion list buffer. To
suppress the display of the heading line, customize this variable to
@code{nil}. The string that is the value of this variable can have
text properties to change the visual appearance of the heading line;
some useful properties @code{face} or @code{cursor-intangible}
(@pxref{Special Properties,,Properties with Special Meanings, elisp,
The Emacs Lisp Reference Manual}).
@vindex completions-highlight-face
When @code{completions-highlight-face} names a face, the current
completion candidate, the one that will be selected by typing
@kbd{@key{RET}} or clicking the mouse, will be highlighted using that
face. The default value of this variable is
@code{completions-highlight}; the value is @code{nil} disables this
highlighting. This feature uses the special text property
@code{cursor-face}.
@node Minibuffer History
@section Minibuffer History

46
doc/emacs/misc.texi
View file

@ -455,20 +455,27 @@ servers the user has connected to. If this variable is @code{t},
@cindex PostScript file
@cindex OpenDocument file
@cindex Microsoft Office file
@cindex EPUB file
@cindex CBZ file
@cindex FB2 file
@cindex XPS file
@cindex OXPS file
@cindex DocView mode
@cindex mode, DocView
@cindex document viewer (DocView)
@findex doc-view-mode
DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
OpenDocument, and Microsoft Office documents. It provides features
such as slicing, zooming, and searching inside documents. It works by
converting the document to a set of images using the @command{gs}
(GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands
and other external tools @footnote{For PostScript files, GhostScript
is a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm}
is needed. For OpenDocument and Microsoft Office documents, the
@code{unoconv} tool is needed.}, and displaying those images.
OpenDocument, Microsoft Office, EPUB, CBZ, FB2, XPS and OXPS
documents. It provides features such as slicing, zooming, and
searching inside documents. It works by converting the document to a
set of images using the @command{gs} (GhostScript) or
@command{pdfdraw}/@command{mutool draw} (MuPDF) commands and other
external tools @footnote{PostScript files require GhostScript, DVI
files require @code{dvipdf} or @code{dvipdfm}, OpenDocument and
Microsoft Office documents require the @code{unoconv} tool, and EPUB,
CBZ, FB2, XPS and OXPS files require @code{mutool} to be available.},
and displaying those images.
@findex doc-view-toggle-display
@findex doc-view-minor-mode
@ -849,6 +856,9 @@ Restores the position of point as it was before inserting the
shell-command output.
@end table
In case the output buffer is not the current buffer, shell command
output is appended at the end of this buffer.
@node Interactive Shell
@subsection Interactive Subshell
@ -886,6 +896,19 @@ also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
Subshells in different buffers run independently and in parallel.
Emacs attempts to keep track of what the current directory is by
looking at the commands you enter, looking for @samp{cd} commands and
the like. This is an error-prone solution, since there are many ways
to change the current directory, so Emacs also looks for special
@acronym{OSC} (Operating System Commands) escape codes that are
designed to convey this information in a more reliable fashion. You
should arrange for your shell to print the appropriate escape sequence
at each prompt, for instance with the following command:
@example
printf "\e]7;file://%s%s\e\\" "$HOSTNAME" "$PWD"
@end example
@vindex explicit-shell-file-name
@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@ -2760,7 +2783,12 @@ will by default ask you whether to use the locked desktop file. You
can avoid the question by customizing the variable
@code{desktop-load-locked-desktop} to either @code{nil}, which means
never load the desktop in this case, or @code{t}, which means load the
desktop without asking.
desktop without asking. Finally, the @code{check-pid} value means to
load the file if the Emacs process that has locked the desktop is not
running on the local machine. This should not be used in
circumstances where the locking Emacs might still be running on
another machine. This could be the case in multi-user environments
where your home directory is mounted remotely using NFS or similar.
@cindex desktop restore in daemon mode
When Emacs starts in daemon mode, it cannot ask you any questions,

46
doc/emacs/mule.texi
View file

@ -50,13 +50,14 @@ others.
@item
You can insert non-@acronym{ASCII} characters or search for them. To do that,
you can specify an input method (@pxref{Select Input Method}) suitable
you can specify an Emacs input method (@pxref{Select Input Method}) suitable
for your language, or use the default input method set up when you choose
your language environment. If
your keyboard can produce non-@acronym{ASCII} characters, you can select an
appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
will accept those characters. Latin-1 characters can also be input by
using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
will accept those characters. On graphical displays, modern systems
typically provide their native input methods, and Latin-1 characters
can also be input by using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
With the X Window System, your locale should be set to an appropriate
value to make sure Emacs interprets keyboard input correctly; see
@ -449,10 +450,13 @@ for that key.
@cindex input methods
An @dfn{input method} is a kind of character conversion designed
specifically for interactive input. In Emacs, typically each language
has its own input method; sometimes several languages that use the same
characters can share one input method. A few languages support several
input methods.
specifically for interactive input. This section describes input
methods that come with Emacs; for native input methods provided by the
underlying OS, @pxref{Unibyte Mode}.
In Emacs, typically each language has its own input method;
sometimes several languages that use the same characters can share one
input method. A few languages support several input methods.
The simplest kind of input method works by mapping @acronym{ASCII} letters
into another alphabet; this allows you to use one other alphabet
@ -1798,12 +1802,38 @@ as @code{xterm}, you can arrange for Meta to be converted to @key{ESC}
and still be able to type 8-bit characters present directly on the
keyboard or using @key{Compose} or @key{AltGr} keys. @xref{User Input}.
@cindex input methods, native
@cindex XIM, X Input Methods
@cindex GTK input methods
Many modern systems provide @dfn{native input methods} for many
languages whose characters don't have keyboard keys assigned to them.
If Emacs was built with support for these native input methods, you
can activate such an input method and type the characters they
support. How to activate and use these input methods depends on the
system and the input method, and will not be described here; see your
system documentation. Here we describe some Emacs facilities to
control the use of the native input methods.
@vindex x-gtk-use-native-input
In Emacs built with the GTK toolkit, the variable
@code{x-gtk-use-native-input} controls whether Emacs should receive
characters produced by GTK input methods. If the value is @code{nil},
the default, Emacs uses the X input methods (@acronym{XIM}), otherwise
it uses the GTK input methods. The @code{useXIM} X resource controls
whether to use @acronym{XIM}, and @code{inputStyle} X resource
controls the display on X of preview text generated by the native
input methods; @pxref{Table of Resources}.
On MS-Windows, Emacs supports native inputs methods provided by
@acronym{IMM}, the Input Method Manager, but that can be turned off if
needed; @pxref{Windows Keyboard}.
@cindex @code{iso-transl} library
@cindex compose character
@cindex dead character
@item
You can use the key @kbd{C-x 8} as a compose-character prefix for
entry of non-@acronym{ASCII} Latin-1 and a few other printing
entry of non-@acronym{ASCII} Latin-1 and other printing
characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
well as other buffers), for searching, and in any other context where
a key sequence is allowed.

27
doc/emacs/package.texi
View file

@ -89,6 +89,11 @@ list of available packages from package archive servers. If the
network is unavailable, it falls back on the most recently retrieved
list.
The main command to use in the package list buffer is the @key{x}
command. If the package under point isn't installed already, this
command will install it. If the package under point is already
installed, this command will delete it.
The following commands are available in the package menu:
@table @kbd
@ -162,7 +167,10 @@ installed versions (marked with status @samp{obsolete}).
@findex package-menu-execute
Download and install all packages marked with @kbd{i}, and their
dependencies; also, delete all packages marked with @kbd{d}
(@code{package-menu-execute}). This also removes the marks.
(@code{package-menu-execute}). This also removes the marks. If no
packages are marked, this command will install the package under point
(if it isn't installed already), or delete the package under point (if
it's already installed).
@item g
@item r
@ -320,10 +328,15 @@ version of the package, a newer version is also installed.
@section Package Installation
@findex package-install
@findex package-update
@findex package-update-all
Packages are most conveniently installed using the package menu
(@pxref{Package Menu}), but you can also use the command @kbd{M-x
package-install}. This prompts for the name of a package with the
@samp{available} status, then downloads and installs it.
@samp{available} status, then downloads and installs it. Similarly,
if you want to update a package, you can use the @kbd{M-x
package-update} command, and if you just want to update all the
packages, you can use the @kbd{M-x package-update-all} command.
@cindex package requirements
A package may @dfn{require} certain other packages to be installed,
@ -470,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

18
doc/emacs/programs.texi
View file

@ -250,10 +250,10 @@ where it treats each chapter, section, etc., as a definition.
together.)
@findex imenu
If you type @kbd{M-x imenu}, it reads the name of a definition using
the minibuffer, then moves point to that definition. You can use
completion to specify the name; the command always displays the whole
list of valid names.
If you type @kbd{M-g i} (@code{imenu}), it reads the name of a
definition using the minibuffer, then moves point to that definition.
You can use completion to specify the name; the command always
displays the whole list of valid names.
@findex imenu-add-menubar-index
Alternatively, you can bind the command @code{imenu} to a mouse
@ -1439,9 +1439,13 @@ performs completion using the function, variable, or property names
defined in the current Emacs session.
In all other respects, in-buffer symbol completion behaves like
minibuffer completion. For instance, if Emacs cannot complete to a
unique symbol, it displays a list of completion alternatives in
another window. @xref{Completion}.
minibuffer completion. For instance, if Emacs cannot complete to
a unique symbol, it displays a list of completion alternatives in
another window. Then you can use the keys @kbd{M-@key{DOWN}} and
@kbd{M-@key{UP}} to navigate through the completions displayed
in the completions buffer without leaving the original buffer,
and the key @kbd{M-@key{RET}} to insert the currently highlighted
completion to the buffer. @xref{Completion}.
In Text mode and related modes, @kbd{M-@key{TAB}} completes words
based on the spell-checker's dictionary. @xref{Spelling}.

139
doc/emacs/search.texi
View file

@ -422,7 +422,7 @@ characters, that disables character folding during that search.
search string.
To search for non-@acronym{ASCII} characters, use one of the
following methods:
following methods during incremental search:
@itemize @bullet
@item
@ -435,14 +435,6 @@ search string, similar to inserting into a buffer using @kbd{C-q}
incremental search adds the @samp{control-S} character to the search
string.
@item
@findex isearch-char-by-name
@kindex C-x 8 RET @r{(Incremental Search)}
Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by
a Unicode name or code-point in hex. This adds the specified
character into the search string, similar to the usual
@code{insert-char} command (@pxref{Inserting Text}).
@item
@kindex C-^ @r{(Incremental Search)}
@findex isearch-toggle-input-method
@ -471,8 +463,26 @@ transient input method (@pxref{transient input method}) with
@kbd{C-x \} (@code{isearch-transient-input-method}) to insert a single
character to the search string using an input method, and
automatically disable the input method afterwards.
@item
@findex isearch-char-by-name
@kindex C-x 8 RET @r{(Incremental Search)}
Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by
a Unicode name or code-point in hex. This adds the specified
character into the search string, similar to the usual
@code{insert-char} command (@pxref{Inserting Text}).
@end itemize
@findex isearch-emoji-by-name
@kindex C-x 8 e RET @r{(Incremental Search)}
You can also include Emoji sequences in the search string. Type
@w{@kbd{C-x 8 e @key{RET}}} (@code{isearch-emoji-by-name}), followed
by the Unicode name of an Emoji (for example, @kbd{smiling face} or
@kbd{heart with arrow}). This adds the specified Emoji to the search
string. If you don't know the name of the Emoji you want to search
for, you can use @kbd{C-x 8 e l} (@code{emoji-list}) and @kbd{C-x 8 e
d} (@code{emoji-describe}) (@pxref{Input Methods}).
@kindex M-s o @r{(Incremental Search)}
@findex isearch-occur
Typing @kbd{M-s o} in incremental search invokes
@ -889,11 +899,13 @@ character folding during incremental regexp search with @kbd{M-s '},
the search becomes a non-regexp search and the search pattern you
typed is interpreted as a literal string.)
@cindex pending, in incremental search
In some cases, adding characters to the regexp in an incremental
regexp search can make the cursor move back and start again. For
example, if you have searched for @samp{foo} and you add @samp{\|bar},
the cursor backs up in case the first @samp{bar} precedes the first
@samp{foo}. @xref{Regexps}.
@samp{foo}. (The prompt will change to say ``Pending'' to notify the
user that this recalculation has happened.) @xref{Regexps}.
Forward and backward regexp search are not symmetrical, because
regexp matching in Emacs always operates forward, starting with the
@ -1015,24 +1027,11 @@ you search for @samp{a.*?$} against the text @samp{abbab} followed by
a newline, it matches the whole string. Since it @emph{can} match
starting at the first @samp{a}, it does.
@item @kbd{\@{@var{n}\@}}
is a postfix operator specifying @var{n} repetitions---that is, the
preceding regular expression must match exactly @var{n} times in a
row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
nothing else.
@item @kbd{\@{@var{n},@var{m}\@}}
is a postfix operator specifying between @var{n} and @var{m}
repetitions---that is, the preceding regular expression must match at
least @var{n} times, but no more than @var{m} times. If @var{m} is
omitted, then there is no upper limit, but the preceding regular
expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
@cindex set of alternative characters, in regular expressions
@cindex character set, in regular expressions
@item @kbd{[ @dots{} ]}
is a @dfn{character set}, beginning with @samp{[} and terminated by
@samp{]}.
is a @dfn{set of alternative characters}, or a @dfn{character set},
beginning with @samp{[} and terminated by @samp{]}.
In the simplest case, the characters between the two brackets are what
this set can match. Thus, @samp{[ad]} matches either one @samp{a} or
@ -1049,9 +1048,10 @@ which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
period. As another example, @samp{[α-ωί]} matches all lower-case
Greek letters.
@cindex character classes, in regular expressions
You can also include certain special @dfn{character classes} in a
character set. A @samp{[:} and balancing @samp{:]} enclose a
character class inside a character alternative. For instance,
character class inside a set of alternative characters. For instance,
@samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,,
elisp, The Emacs Lisp Reference Manual}, for a list of character
classes.
@ -1119,13 +1119,13 @@ no preceding expression on which the @samp{*} can act. It is poor practice
to depend on this behavior; it is better to quote the special character anyway,
regardless of where it appears.
As a @samp{\} is not special inside a character alternative, it can
never remove the special meaning of @samp{-} or @samp{]}. So you
should not quote these characters when they have no special meaning
either. This would not clarify anything, since backslashes can
legitimately precede these characters where they @emph{have} special
meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
which matches any single character except a backslash.
As a @samp{\} is not special inside a set of alternative characters, it can
never remove the special meaning of @samp{-}, @samp{^} or @samp{]}.
You should not quote these characters when they have no special
meaning. This would not clarify anything, since backslashes
can legitimately precede these characters where they @emph{have}
special meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string
syntax), which matches any single character except a backslash.
@node Regexp Backslash
@section Backslash in Regular Expressions
@ -1190,11 +1190,11 @@ matches the same text that matched the @var{d}th occurrence of a
@samp{\( @dots{} \)} construct. This is called a @dfn{back
reference}.
After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
the beginning and end of the text matched by that construct. Then,
later on in the regular expression, you can use @samp{\} followed by the
digit @var{d} to mean ``match the same text matched the @var{d}th time
by the @samp{\( @dots{} \)} construct''.
After the end of a @samp{\( @dots{} \)} construct, the matcher
remembers the beginning and end of the text matched by that construct.
Then, later on in the regular expression, you can use @samp{\}
followed by the digit @var{d} to mean ``match the same text matched
the @var{d}th @samp{\( @dots{} \)} construct''.
The strings matching the first nine @samp{\( @dots{} \)} constructs
appearing in a regular expression are assigned numbers 1 through 9 in
@ -1211,6 +1211,21 @@ If a particular @samp{\( @dots{} \)} construct matches more than once
(which can easily happen if it is followed by @samp{*}), only the last
match is recorded.
@item @kbd{\@{@var{m}\@}}
is a postfix operator specifying @var{m} repetitions---that is, the
preceding regular expression must match exactly @var{m} times in a
row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
nothing else.
@item @kbd{\@{@var{m},@var{n}\@}}
is a postfix operator specifying between @var{m} and @var{n}
repetitions---that is, the preceding regular expression must match at
least @var{m} times, but no more than @var{n} times. If @var{n} is
omitted, then there is no upper limit, but the preceding regular
expression must match at least @var{m} times.@* @samp{\@{0,1\@}} is
equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
@item \`
matches the empty string, but only at the beginning of the string or
buffer (or its accessible portion) being matched against.
@ -1812,12 +1827,18 @@ occurrence of @var{string}. When done, exit the recursive editing level
with @kbd{C-M-c} to proceed to the next occurrence.
@item e
@itemx E
to edit the replacement string in the minibuffer. When you exit the
minibuffer by typing @key{RET}, the minibuffer contents replace the
current occurrence of the pattern. They also become the new
replacement string for any further occurrences.
@item E
is like @kbd{e}, but the next replacement will be done with exact
case. I.e., if you have a @code{query-replace} from @samp{foo} to
@samp{bar}, a text like @samp{Foo} will be normally be replaced with
@samp{Bar}. Use this command to do the current replacement with exact
case.
@item C-l
to redisplay the screen. Then you must type another character to
specify what to do with this occurrence.
@ -1864,12 +1885,12 @@ replacing regexp matches in file names.
@node Other Repeating Search
@section Other Search-and-Loop Commands
Here are some other commands that find matches for a regular
expression. They all ignore case in matching, if the pattern contains
Here are some other commands that find matches for regular
expressions. They all ignore case in matching, if the pattern contains
no upper-case letters and @code{case-fold-search} is non-@code{nil}.
Aside from @code{multi-occur} and @code{multi-occur-in-matching-buffers},
which always search the whole buffer, all operate on the text from point
to the end of the buffer, or on the region if it is active.
which always search the whole buffer, all of the commands operate on the
text from point to the end of the buffer, or on the region if it is active.
@table @kbd
@findex multi-isearch-buffers
@ -1943,19 +1964,27 @@ is not considered a match.
@kindex RET @r{(Occur mode)}
@kindex o @r{(Occur mode)}
@kindex C-o @r{(Occur mode)}
In the @file{*Occur*} buffer, you can click on each entry, or move
point there and type @key{RET}, to visit the corresponding position in
the buffer that was searched. @kbd{o} and @kbd{C-o} display the match
in another window; @kbd{C-o} does not select it. Alternatively, you
can use the @kbd{M-g M-n} (@code{next-error}) command to visit the
occurrences one by one (@pxref{Compilation Mode}).
The @file{*Occur*} buffer uses the Occur mode as its major mode. You
can use the @kbd{n} and @kbd{p} keys to move to the next or previous
match; with prefix numeric argument, these commands move that many
matches. Digit keys are bound to @code{digit-argument}, so @kbd{5 n}
moves to the fifth next match (you don't have to type @kbd{C-u}).
@key{SPC} and @key{DEL} scroll the @file{*Occur*} buffer up and down.
Clicking on a match or moving point there and typing @key{RET} visits
the corresponding position in the original buffer that was searched.
@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
does not select that window. Alternatively, you can use the @kbd{M-g
M-n} (@code{next-error}) command to visit the occurrences one by one
(@pxref{Compilation Mode}). Finally, @kbd{q} quits the window showing
the @file{*Occur*} buffer and buries the buffer.
@cindex Occur Edit mode
@cindex mode, Occur Edit
Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
mode, in which edits made to the entries are also applied to the text
in the originating buffer. Type @kbd{C-c C-c} to return to Occur
mode.
Typing @kbd{e} in the @file{*Occur*} buffer makes the buffer writable
and enters the Occur Edit mode, in which you can edit the matching
lines and have those edits reflected in the text in the originating
buffer. Type @kbd{C-c C-c} to leave the Occur Edit mode and return to
the Occur mode.
@findex list-matching-lines
The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x

6
doc/emacs/sending.texi
View file

@ -659,6 +659,7 @@ such as MIME support. Another available mode is MH-E
(@pxref{Top,,MH-E,mh-e, The Emacs Interface to MH}).
@vindex mail-user-agent
@findex define-mail-user-agent
You can choose any of these @dfn{mail user agents} as your preferred
method for editing and sending mail. The commands @kbd{C-x m},
@kbd{C-x 4 m} and @kbd{C-x 5 m} use whichever agent you have
@ -667,7 +668,10 @@ the bug reporter (@pxref{Bugs}). To specify a mail user agent,
customize the variable @code{mail-user-agent}. Currently, legitimate
values include @code{message-user-agent} (Message mode)
@code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and
@code{mh-e-user-agent}.
@code{mh-e-user-agent}. Additional options may be available; check
in the manual of your mail user agent package for details. You may
also define another mail user agent using
@code{define-mail-user-agent}.
If you select a different mail-composition method, the information
in this chapter about the mail buffer and Message mode does not apply;

23
doc/emacs/text.texi
View file

@ -1259,6 +1259,17 @@ and related functions treat hidden text, @pxref{Query Replace}.)
You can also automatically make text visible as you navigate in it by
using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode.
@vindex outline-default-state
The @code{outline-default-state} variable controls what headings
will be visible after Outline mode is turned on. If non-@code{nil},
some headings are initially outlined. If equal to a number, show only
headings up to and including the corresponding level. If equal to
@code{outline-show-all}, all text of buffer is shown. If equal to
@code{outline-show-only-headings}, show only headings, whatever their
level is. If equal to a lambda function or function name, this
function is expected to toggle headings visibility, and will be called
without arguments after the mode is enabled.
@node Outline Views
@subsection Viewing One Outline in Multiple Views
@ -1702,17 +1713,17 @@ to work with them.
@table @kbd
@item C-c C-o
Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position
point on a line between them (@code{tex-latex-block}).
point on a line between them (@code{latex-insert-block}).
@item C-c C-e
Close the innermost @LaTeX{} block not yet closed
(@code{tex-close-latex-block}).
(@code{latex-close-block}).
@end table
@findex tex-latex-block
@findex latex-insert-block
@kindex C-c C-o @r{(@LaTeX{} mode)}
In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to
group blocks of text. To insert a block, type @kbd{C-c C-o}
(@code{tex-latex-block}). This prompts for a block type, and inserts
(@code{latex-insert-block}). This prompts for a block type, and inserts
the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a
blank line between the two and moving point there.
@ -1723,11 +1734,11 @@ completion list contains the standard @LaTeX{} block types. If you
want additional block types for completion, customize the list
variable @code{latex-block-names}.
@findex tex-close-latex-block
@findex latex-close-block
@kindex C-c C-e @r{(@LaTeX{} mode)}
@findex latex-electric-env-pair-mode
In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance.
You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an
You can use @kbd{C-c C-e} (@code{latex-close-block}) to insert an
@samp{\end} tag which matches the last unmatched @samp{\begin}. It
also indents the @samp{\end} to match the corresponding @samp{\begin},
and inserts a newline after the @samp{\end} tag if point is at the

174
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.
@ -160,65 +159,9 @@ Emacs.
* 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
@ -296,6 +239,31 @@ editing in the same Emacs session.
out of memory, because the Buffer Menu needs a fair amount of memory
itself, and the reserve supply may not be enough.
@cindex out of memory killer, GNU/Linux
@cindex OOM killer
On GNU/Linux systems, Emacs does not normally get notified about
out-of-memory situations; instead, the OS can kill the Emacs process
when it runs out of memory. This feature is known as the
@dfn{out-of-memory killer}, or @dfn{@acronym{OOM} killer}. When this
behavior is in effect, Emacs is unable to detect the out-of-memory
situation in time, and won't be able to let you save your buffer as
described above. However, it is possible to turn off this behavior of
the OS, and thus allow Emacs a chance to handle the out-of-memory
situation in a more useful manner, before it is killed. To do that,
become the super user, edit the file @code{/etc/sysctl.conf} to
contain the lines shown below, and then invoke the command
@w{@kbd{sysctl -p}} from the shell prompt:
@example
vm.overcommit_memory=2
vm.overcommit_ratio=0
@end example
@noindent
Please note that the above setting affects all the processes on the
system, and in general the behavior of the system under memory
pressure, not just the Emacs process alone.
@node Crashing
@subsection When Emacs Crashes
@ -500,6 +468,86 @@ be substantial.
Use @kbd{M-x so-long-commentary} to view the documentation for this
library and learn more about how to enable and configure it.
@vindex max-redisplay-ticks
If even @code{so-long-mode} doesn't help making Emacs responsive
enough, or if you'd rather not disable the display-related features
that @code{so-long-mode} turns off, you can instead customize the
variable @code{max-redisplay-ticks} to a non-zero value. Then Emacs
will abort redisplay of a window and commands, like @kbd{C-n} and
@kbd{M-v}, which use the display code to do their job, if processing a
window needs more low-level display operations than the value of this
variable. The display of the offending window will then remain
outdated, and possibly incomplete, on the screen, but Emacs should
otherwise be responsive, and you could then switch to another buffer,
or kill the problematic buffer, or turn on @code{so-long-mode} or
@code{so-long-minor-mode} in that buffer. When the display of a
window is aborted due to this reason, the buffer shown in that window
will not have any of its windows redisplayed until the buffer is
modified or until you type @kbd{C-l} (@pxref{Recentering}) in one of
that buffer's windows.
If you decide to customize this variable to a non-zero value, we
recommend to use a value between 100,000 and 1,000,000, depending on
your patience and the speed of your system. The default value is
zero, which disables this feature.
@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 Bugs
@section Reporting Bugs
@ -782,10 +830,12 @@ Emacs, so you will have to report the bug somewhere else.
@item
The type of machine you are using, and the operating system name and
version number (again, automatically included by @kbd{M-x
report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this
information too. Copy its output from the @file{*Messages*} buffer,
so that you get it all and get it accurately.
version number (again, automatically included by @w{@kbd{M-x
report-emacs-bug}}). @w{@kbd{M-x emacs-version @key{RET}}} provides
this information too. Copy its output from the @file{*Messages*}
buffer, so that you get it all and get it accurately, or use
@w{@kbd{C-u M-x emacs-version @key{RET}}} to insert the version
information into the current buffer.
@item
The operands given to the @code{configure} command when Emacs was

2
doc/emacs/vc1-xtra.texi
View file

@ -269,7 +269,7 @@ with the file's version control type.
@vindex vc-handled-backends
The variable @code{vc-handled-backends} determines which version
control systems VC should handle. The default value is @code{(RCS CVS
SVN SCCS SRC Bzr Git Hg Mtn)}, so it contains all the version systems
SVN SCCS SRC Bzr Git Hg)}, so it contains all the version systems
that are currently supported. If you want VC to ignore one or more of
these systems, exclude its name from the list. To disable VC
entirely, set this variable to @code{nil}.

12
doc/emacs/windows.texi
View file

@ -442,8 +442,8 @@ selected window write:
@example
@group
(customize-set-variable
'display-buffer-alist
(setopt
display-buffer-alist
'(("\\*scratch\\*" (display-buffer-same-window))))
@end group
@end example
@ -468,8 +468,8 @@ Lisp Reference Manual}) as follows:
@example
@group
(customize-set-variable
'display-buffer-base-action
(setopt
display-buffer-base-action
'((display-buffer-reuse-window display-buffer-pop-up-frame)
(reusable-frames . 0)))
@end group
@ -535,8 +535,8 @@ the following form in your initialization file (@pxref{Init File}):
@example
@group
(customize-set-variable
'display-buffer-alist
(setopt
display-buffer-alist
'(("\\*Completions\\*" display-buffer-below-selected)))
@end group
@end example

28
doc/emacs/xresources.texi
View file

@ -149,6 +149,15 @@ various X toolkits (GTK+, Lucid, etc.)---we indicate below when this
is the case.
@table @asis
@item @code{alpha} (class @code{Alpha})
Sets the @samp{alpha} frame parameter, determining frame transparency
(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
@item @code{alphaBackground} (class @code{AlphaBackground})
Sets the @samp{alpha-background} frame parameter, determining background
transparency
(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
@item @code{background} (class @code{Background})
Background color (@pxref{Colors}).
@ -355,11 +364,26 @@ Let the input method decide how to display itself. This is usually
equivalent to @samp{overthespot}, but it might work with more input
methods.
@item native
Use the toolkit for handling input methods. This is currently
implemented only on GTK.
@item root
Use some location on display specific to the input method for
displaying the preview text.
@end table
@item @code{synchronizeResize} (class @code{SynchronizeResize})
If @samp{off} or @samp{false}, Emacs will not try to tell the window
manager when it has finished redrawing the display in response to a
frame being resized. Otherwise, the window manager will postpone
drawing a frame that was just resized until its contents are updated,
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.
@item @code{verticalScrollBars} (class @code{ScrollBars})
Give frames scroll bars on the left if @samp{left}, on the right if
@samp{right}; don't have scroll bars if @samp{off} (@pxref{Scroll Bars}).
@ -585,7 +609,7 @@ those are governed by normal X resources (@pxref{Resources}).
The following sections describe how to customize GTK+ resources for
Emacs. For details about GTK+ resources, see the GTK+ API document at
@uref{https://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html}.
@uref{https://developer-old.gnome.org/gtk2/stable/gtk2-Resource-Files.html}.
In GTK+ version 3, GTK+ resources have been replaced by a completely
different system. The appearance of GTK+ widgets is now determined by
@ -595,7 +619,7 @@ style settings (where @var{theme} is the name of the current GTK+
theme). Therefore, the description of GTK+ resources in this section
does not apply to GTK+ 3. For details about the GTK+ 3 styling
system, see
@uref{https://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}.
@uref{https://developer-old.gnome.org/gtk3/3.0/GtkCssProvider.html}.
@menu
* GTK Resource Basics:: Basic usage of GTK+ resources.

4
doc/lispintro/Makefile.in
View file

@ -63,7 +63,7 @@ ENVADD = \
MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)"
DVI_TARGETS = emacs-lisp-intro.dvi
HTML_TARGETS = emacs-lisp-intro.html
HTML_TARGETS = eintr.html
PDF_TARGETS = emacs-lisp-intro.pdf
PS_TARGETS = emacs-lisp-intro.ps
@ -95,7 +95,7 @@ emacs-lisp-intro.dvi: ${srcs}
emacs-lisp-intro.pdf: ${srcs}
$(ENVADD) $(TEXI2PDF) $<
emacs-lisp-intro.html: ${srcs}
eintr.html: ${srcs}
$(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $<
emacs-lisp-intro.ps: emacs-lisp-intro.dvi

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

@ -1,8 +1,6 @@
\input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
@comment %**start of header
@setfilename ../../info/eintr.info
@c setfilename emacs-lisp-intro.info
@c sethtmlfilename emacs-lisp-intro.html
@settitle Programming in Emacs Lisp
@include docstyle.texi
@syncodeindex vr cp
@ -15347,7 +15345,10 @@ nil
@group
(20615 27034 579989 697000)
(17905 55681 0 0)
(20615 26327 734791 805000)
(20615 26327 734791 805000)@footnote{If @code{current-time-list} is
@code{nil} the three timestamps are @code{(1351051674579989697
. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and
@code{(1351050967734791805 . 1000000000)}, respectively.}
13188
"-rw-r--r--"
@end group

71
doc/lispref/buffers.texi
View file

@ -541,10 +541,12 @@ file formerly visited.
@ref{Text}.
@defun buffer-modified-p &optional buffer
This function returns @code{t} if the buffer @var{buffer} has been modified
since it was last read in from a file or saved, or @code{nil}
otherwise. If @var{buffer} is not supplied, the current buffer
is tested.
This function returns non-@code{nil} if @var{buffer} has
been modified since it was last read in from a file or saved, or
@code{nil} otherwise. If @var{buffer} has been auto-saved since the
time it was last modified, this function returns the symbol
@code{autosaved}. If @var{buffer} is @code{nil} or omitted, it
defaults to the current buffer.
@end defun
@defun set-buffer-modified-p flag
@ -563,8 +565,10 @@ function @code{force-mode-line-update} works by doing this:
@end defun
@defun restore-buffer-modified-p flag
Like @code{set-buffer-modified-p}, but does not force redisplay
of mode lines.
Like @code{set-buffer-modified-p}, but does not force redisplay of
mode lines. This function also allows @var{flag}'s value to be
the symbol @code{autosaved}, which marks the buffer as modified and
auto-saved after the last modification.
@end defun
@deffn Command not-modified &optional arg
@ -953,15 +957,64 @@ with a @code{nil} @var{norecord} argument since this may lead to
infinite recursion.
@end defvar
@defun buffer-match-p condition buffer-or-name &optional arg
This function checks if a buffer designated by @code{buffer-or-name}
satisfies a @code{condition}. Optional third argument @var{arg} is
passed to the predicate function in @var{condition}. A condition can
be one of the following:
@itemize @bullet{}
@item
A string, interpreted as a regular expression. The buffer
satisfies the condition if the regular expression matches the buffer
name.
@item
A predicate function, which should return non-@code{nil} if the buffer
matches. If the function expects one argument, it is called with
@var{buffer-or-name} as the argument; if it expects 2 arguments, the
first argument is @var{buffer-or-name} and the second is @var{arg}
(or @code{nil} if @var{arg} is omitted).
@item
A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one
of
@table @code
@item not
Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with
the same buffer and @code{arg}.
@item or
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{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
@end itemize
@end defun
@defun match-buffers condition &optional buffer-list arg
This function returns a list of all buffers that satisfy a
@code{condition}, as defined for @code{buffer-match-p}. By default
all buffers are considered, but this can be restricted via the second
optional @code{buffer-list} argument. Optional third argument
@var{arg} will be used by @var{condition} in the same way as
@code{buffer-match-p} does.
@end defun
@node Creating Buffers
@section Creating Buffers
@cindex creating buffers
@cindex buffers, creating
This section describes the two primitives for creating buffers.
@code{get-buffer-create} creates a buffer if it finds no existing buffer
with the specified name; @code{generate-new-buffer} always creates a new
buffer and gives it a unique name.
@code{get-buffer-create} creates a buffer if it finds no existing
buffer with the specified name; @code{generate-new-buffer} always
creates a new buffer and gives it a unique name.
Both functions accept an optional argument @var{inhibit-buffer-hooks}.
If it is non-@code{nil}, the buffer they create does not run the hooks

186
doc/lispref/commands.texi
View file

@ -312,6 +312,25 @@ If @var{function} is an interactively callable function
specifies how to compute its arguments. Otherwise, the value is
@code{nil}. If @var{function} is a symbol, its function definition is
used.
When called on an OClosure, the work is delegated to the generic
function @code{oclosure-interactive-form}.
@end defun
@defun oclosure-interactive-form function
Just like @code{interactive-form}, this function takes a command and
returns its interactive form. The difference is that it is a generic
function and it is only called when @var{function} is an OClosure.
The purpose is to make it possible for some OClosure types to compute
their interactive forms dynamically instead of carrying it in one of
their slots.
This is used for example for @code{kmacro} functions in order to
reduce their memory size, since they all share the same interactive
form. It is also used for @code{advice} functions, where the
interactive form is computed from the interactive forms of its
components, so as to make this computation more lazily and to
correctly adjust the interactive form when one of its component's
is redefined.
@end defun
@node Interactive Codes
@ -878,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
@ -1127,6 +1150,96 @@ frame, the value is the frame to which the event was redirected.
If the last event came from a keyboard macro, the value is @code{macro}.
@end defvar
@cindex input devices
@cindex device names
Input events must come from somewhere; sometimes, that is a keyboard
macro, a signal, or `unread-command-events', but it is usually a
physical input device connected to a computer that is controlled by
the user. Those devices are referred to as @dfn{input devices}, and
Emacs associates each input event with the input device from which it
originated. They are identified by a name that is unique to each
input device.
The ability to determine the precise input device used depends on the
details of each system. When that information is unavailable, Emacs
reports keyboard events as originating from the @samp{"Virtual core
keyboard"}, and other events as originating from the @samp{"Virtual
core pointer"}. (These values are used on every platform because the
X server reports them when detailed device information is not known.)
@defvar last-event-device
This variable records the name of the input device from which the last
input event read was generated. It is @code{nil} if no such device
exists, i.e., the last input event was read from
@code{unread-command-events}, or it came from a keyboard macro.
When the X Input Extension is being used on X Windows, the device name
is a string that is unique to each physical keyboard, pointing device
and touchscreen attached to the X server. Otherwise, it is either the
string @samp{"Virtual core pointer"} or @samp{"Virtual core
keyboard"}, depending on whether the event was generated by a pointing
device (such as a mouse) or a keyboard.
@end defvar
@defun device-class frame name
There are various different types of devices, which can be determined
from their names. This function can be used to determined the correct
type of the device @var{name} for an event originating from
@var{frame}.
The return value is one of the following symbols (``device classes''):
@table @code
@item core-keyboard
The core keyboard; this is means the device is a keyboard-like device,
but no other characteristics are unknown.
@item core-pointer
The core pointer; this means the device is a pointing device, but no
other characteristics are known.
@item mouse
A computer mouse.
@item trackpoint
A trackpoint or joystick (or other similar control.)
@item eraser
The other end of a stylus on a graphics tablet, or a standalone
eraser.
@item pen
The pointed end of a pen on a graphics tablet, a stylus, or some other
similar device.
@item puck
A device that looks like a computer mouse, but reports absolute
coordinates relative to some other surface.
@item power-button
A power button or volume button (or other similar control.)
@item keyboard
A computer keyboard.
@item touchscreen
A computer touchpad.
@item pad
A collection of sensitive buttons, rings, and strips commonly found
around a drawing tablet.
@item touchpad
An indirect touch device such as a touchpad.
@item piano
A musical instrument such as an electronic keyboard.
@item test
A device used by the XTEST extension to report input.
@end table
@end defun
@node Adjusting Point
@section Adjusting Point After Commands
@cindex adjusting point
@ -2091,11 +2204,24 @@ wheel.
@vindex mouse-wheel-up-event
@vindex mouse-wheel-down-event
This kind of event is generated only on some kinds of systems. On some
systems, @code{mouse-4} and @code{mouse-5} are used instead. For
portable code, use the variables @code{mouse-wheel-up-event} and
@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
what event types to expect for the mouse wheel.
This kind of event is generated only on some kinds of systems. On
some systems, @code{mouse-4} and @code{mouse-5} are used instead. For
portable code, use the variables @code{mouse-wheel-up-event},
@code{mouse-wheel-up-alternate-event}, @code{mouse-wheel-down-event}
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})
@ -2139,19 +2265,29 @@ On X, @var{arg} is a string describing some text to place behind the
cursor. It can be @code{nil}, which means to remove any text
previously displayed.
On PGTK, @var{arg} is a list of strings with color information. Its
structure is as follows:
On PGTK frames (@pxref{Frames}), @var{arg} is a list of strings with
information about their color and underline attributes. It has the
following form:
@example
(
(TEXT (ul . COLOR) (bg . COLOR) (fg . COLOR))
; ...
@group
((@var{string1}
(ul . @var{underline-color})
(bg . @var{background-color})
(fg . @var{foreground-color}))
(@var{string2}
(ul . @var{underline-color})
(bg . @var{background-color})
(fg . @var{foreground-color}))
@dots{}
)
@end group
@end example
Color information can be omitted. @code{COLOR} of @code{ul} can be
@code{t} or a string. @var{arg} can be @code{nil}, which means to
remove any text previously displayed.
Color information can be omitted, leaving just the text of the
strings. @var{underline-color} can be @code{t}, meaning underlined
text with default underline color, or it can be a string, the name of
the color to draw the underline.
This is a special event (@pxref{Special Events}), which normally
should not be bound by the user to any command. Emacs will typically
@ -2494,7 +2630,7 @@ POSITION is assumed to lie in a window text area."
@end example
@end defun
@defun posn-col-row position
@defun posn-col-row position &optional use-window
This function returns a cons cell @w{@code{(@var{col} . @var{row})}},
containing the estimated column and row corresponding to buffer
position described by @var{position}. The return value is given in
@ -2502,7 +2638,11 @@ units of the frame's default character width and default line height
(including spacing), as computed from the @var{x} and @var{y} values
corresponding to @var{position}. (So, if the actual characters have
non-default sizes, the actual row and column may differ from these
computed values.)
computed values.) If the optional @var{window} argument is
non-@code{nil}, use the default character width in the window
indicated by @var{position} instead of the frame. (This makes a
difference if that window is showing a buffer with a non-default
zooming level, for instance.)
Note that @var{row} is counted from the top of the text area. If the
window given by @var{position} possesses a header line (@pxref{Header
@ -3073,7 +3213,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.
@ -3092,6 +3232,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
@ -3935,6 +4080,15 @@ what happens when a disabled command is invoked interactively.
Disabling a command has no effect on calling it as a function from Lisp
programs.
@findex command-query
The value of the @code{disabled} property can also be a list where
the first element is the symbol @code{query}. In that case, the user
will be queried whether to execute the command. The second element in
the list should be @code{nil} or non-@code{nil} to say whether to use
@code{y-or-n-p} or @code{yes-or-no-p}, respectively, and the third
element is the question to use. The @code{command-query} convenience
function should be used to enable querying for a command.
@deffn Command enable-command command
Allow @var{command} (a symbol) to be executed without special
confirmation from now on, and alter the user's init file (@pxref{Init

56
doc/lispref/compile.texi
View file

@ -61,7 +61,7 @@ Here is an example:
@group
(silly-loop 50000000)
@result{} 10.235304117202759
@result{} 5.200886011123657
@end group
@group
@ -71,12 +71,12 @@ Here is an example:
@group
(silly-loop 50000000)
@result{} 3.705854892730713
@result{} 0.6239290237426758
@end group
@end example
In this example, the interpreted code required 10 seconds to run,
whereas the byte-compiled code required less than 4 seconds. These
In this example, the interpreted code required more than 5 seconds to run,
whereas the byte-compiled code required less than 1 second. These
results are representative, but actual results may vary.
@node Compilation Functions
@ -135,10 +135,10 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}).
@group
(byte-compile 'factorial)
@result{}
#[(integer)
"^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
[integer 1 * factorial]
4 "Compute factorial of INTEGER."]
#[257
"\211\300U\203^H^@@\300\207\211\301^BS!_\207"
[1 factorial] 4
"Compute factorial of INTEGER.\n\n(fn INTEGER)"]
@end group
@end example
@ -688,11 +688,11 @@ Lisp source; these do not appear in the output of @code{disassemble}.
(disassemble 'factorial)
@print{} byte-code for factorial:
doc: Compute factorial of an integer.
args: (integer)
args: (arg1)
@end group
@group
0 varref integer ; @r{Get the value of @code{integer} and}
0 dup ; @r{Get the value of @code{integer} and}
; @r{push it onto the stack.}
1 constant 1 ; @r{Push 1 onto stack.}
@end group
@ -707,9 +707,9 @@ Lisp source; these do not appear in the output of @code{disassemble}.
7 return ; @r{Return the top element of the stack.}
@end group
@group
8:1 varref integer ; @r{Push value of @code{integer} onto stack.}
8:1 dup ; @r{Push value of @code{integer} onto stack.}
9 constant factorial ; @r{Push @code{factorial} onto stack.}
10 varref integer ; @r{Push value of @code{integer} onto stack.}
10 stack-ref 2 ; @r{Push value of @code{integer} onto stack.}
11 sub1 ; @r{Pop @code{integer}, decrement value,}
; @r{push new value onto stack.}
12 call 1 ; @r{Call function @code{factorial} using first}
@ -717,9 +717,9 @@ Lisp source; these do not appear in the output of @code{disassemble}.
; @r{push returned value onto stack.}
@end group
@group
13 mult ; @r{Pop top two values off stack, multiply}
13 mult ; @r{Pop top two values off stack, multiply}
; @r{them, and push result onto stack.}
14 return ; @r{Return the top element of the stack.}
14 return ; @r{Return the top element of the stack.}
@end group
@end example
@ -740,7 +740,7 @@ The @code{silly-loop} function is somewhat more complex:
(disassemble 'silly-loop)
@print{} byte-code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
args: (arg1)
@end group
@group
@ -749,24 +749,21 @@ The @code{silly-loop} function is somewhat more complex:
@end group
@group
1 call 0 ; @r{Call @code{current-time-string} with no}
; @r{argument, push result onto stack.}
; @r{argument, push result onto stack as @code{t1}.}
@end group
@group
2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.}
@end group
@group
3:1 varref n ; @r{Get value of @code{n} from the environment}
2:1 stack-ref 1 ; @r{Get value of the argument @code{n}}
; @r{and push the value on the stack.}
4 sub1 ; @r{Subtract 1 from top of stack.}
3 sub1 ; @r{Subtract 1 from top of stack.}
@end group
@group
5 dup ; @r{Duplicate top of stack; i.e., copy the top}
4 dup ; @r{Duplicate top of stack; i.e., copy the top}
; @r{of the stack and push copy onto stack.}
6 varset n ; @r{Pop the top of the stack,}
; @r{and bind @code{n} to the value.}
5 stack-set 3 ; @r{Pop the top of the stack,}
; @r{and set @code{n} to the value.}
;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack}
;; @r{into the value of @code{n} without popping it.)}
;; @r{(In effect, the sequence @code{dup stack-set} copies the top of}
;; @r{the stack into the value of @code{n} without popping it.)}
@end group
@group
@ -781,16 +778,15 @@ The @code{silly-loop} function is somewhat more complex:
; @r{else continue.}
@end group
@group
12 varref t1 ; @r{Push value of @code{t1} onto stack.}
12 dup ; @r{Push value of @code{t1} onto stack.}
13 constant current-time-string ; @r{Push @code{current-time-string}}
; @r{onto the top of the stack.}
14 call 0 ; @r{Call @code{current-time-string} again.}
@end group
@group
15 unbind 1 ; @r{Unbind @code{t1} in local environment.}
16 list2 ; @r{Pop top two elements off stack, create a}
15 list2 ; @r{Pop top two elements off stack, create a}
; @r{list of them, and push it onto stack.}
17 return ; @r{Return value of the top of stack.}
16 return ; @r{Return value of the top of stack.}
@end group
@end example

21
doc/lispref/control.texi
View file

@ -525,7 +525,7 @@ core pattern can have the following forms:
@table @code
@item _
@item _@r{ (underscore)}
Matches any @var{expval}.
This is also known as @dfn{don't care} or @dfn{wildcard}.
@ -629,7 +629,10 @@ Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order,
until one of them succeeds. In that case, @code{or} likewise matches,
and the rest of the sub-patterns are not tested.
To present a consistent environment (@pxref{Intro Eval})
To present a consistent environment
@ifnottex
(@pxref{Intro Eval})
@end ifnottex
to @var{body-forms} (thus avoiding an evaluation error on match),
the set of variables bound by the pattern is the union of the
variables bound by each sub-pattern. If a variable is not bound by
@ -1326,6 +1329,20 @@ Assign values to variables in a @code{setq} form, destructuring each
@var{value} according to its respective @var{pattern}.
@end defmac
@defmac pcase-lambda lambda-list &rest body
This is like @code{lambda}, but allows each argument to be a pattern.
For instance, here's a simple function that takes a cons cell as the
argument:
@example
(setq fun
(pcase-lambda (`(,key . ,val))
(vector key (* val 10))))
(funcall fun '(foo . 2))
@result{} [foo 20]
@end example
@end defmac
@node Iteration
@section Iteration
@cindex iteration

16
doc/lispref/customize.texi
View file

@ -376,7 +376,7 @@ name) and the new value, and should do whatever is necessary to update
the value properly for this option (which may not mean simply setting
the option as a Lisp variable); preferably, though, it should not
modify its value argument destructively. The default for
@var{setfunction} is @code{set-default}.
@var{setfunction} is @code{set-default-toplevel-value}.
If you specify this keyword, the variable's documentation string
should describe how to do the same job in hand-written Lisp code.
@ -387,7 +387,7 @@ Specify @var{getfunction} as the way to extract the value of this
option. The function @var{getfunction} should take one argument, a
symbol, and should return whatever customize should use as the
current value for that symbol (which need not be the symbol's Lisp
value). The default is @code{default-value}.
value). The default is @code{default-toplevel-value}.
You have to really understand the workings of Custom to use
@code{:get} correctly. It is meant for values that are treated in
@ -409,11 +409,11 @@ do not reinitialize it if it is already non-void.
@item custom-initialize-default
Like @code{custom-initialize-set}, but use the function
@code{set-default} to set the variable, instead of the variable's
@code{:set} function. This is the usual choice for a variable whose
@code{:set} function enables or disables a minor mode; with this choice,
defining the variable will not call the minor mode function, but
customizing the variable will do so.
@code{set-default-toplevel-value} to set the variable, instead of the
variable's @code{:set} function. This is the usual choice for a
variable whose @code{:set} function enables or disables a minor mode;
with this choice, defining the variable will not call the minor mode
function, but customizing the variable will do so.
@item custom-initialize-reset
Always use the @code{:set} function to initialize the variable. If
@ -424,7 +424,7 @@ This is the default @code{:initialize} function.
@item custom-initialize-changed
Use the @code{:set} function to initialize the variable, if it is
already set or has been customized; otherwise, just use
@code{set-default}.
@code{set-default-toplevel-value}.
@item custom-initialize-delay
This function behaves like @code{custom-initialize-set}, but it

26
doc/lispref/debugging.texi
View file

@ -194,6 +194,17 @@ If you set @code{debug-on-message} to a regular expression,
Emacs will enter the debugger if it displays a matching message in the
echo area. For example, this can be useful when trying to find the
cause of a particular message.
@end defvar
@defvar debug-allow-recursive-debug
You can evaluate forms in the current stack frame in the
@samp{*Backtrace*} buffer with the @key{e} command, and while
edebugging you can use the @key{e} and @key{C-x C-e} commands to do
something similar. By default, the debugger is inhibited by these
commands (because (re-)entering the debugger at this point will
usually take you out of the debugging context you're in). Set
@code{debug-allow-recursive-debug} to a non-@code{nil} value to allow
these commands to enter the debugger recursively.
@end defvar
To debug an error that happens during loading of the init
@ -387,11 +398,9 @@ possibilities.)
variable is temporarily set according to
@code{eval-expression-debug-on-error}. If the latter variable is
non-@code{nil}, @code{debug-on-error} will temporarily be set to
@code{t}. This means that any further errors that occur while doing a
debugging session will (by default) trigger another backtrace. If
this is not what you want, you can either set
@code{eval-expression-debug-on-error} to @code{nil}, or set
@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}.
@code{t}. However, further errors that occur while debugging won't
(by default) trigger another debugger, because @code{inhibit-debugger}
will also be bound to non-@code{nil}.
The debugger itself must be run byte-compiled, since it makes
assumptions about the state of the Lisp interpreter. These
@ -522,6 +531,7 @@ Flag the current frame like @kbd{b}. Then continue execution like
@kbd{c}, but temporarily disable break-on-entry for all functions that
are set up to do so by @code{debug-on-entry}.
@vindex debug-allow-recursive-debug
@item e
Read a Lisp expression in the minibuffer, evaluate it (with the
relevant lexical environment, if applicable), and print the
@ -530,7 +540,11 @@ variables, and the current buffer, as part of its operation; @kbd{e}
temporarily restores their values from outside the debugger, so you can
examine and change them. This makes the debugger more transparent. By
contrast, @kbd{M-:} does nothing special in the debugger; it shows you
the variable values within the debugger.
the variable values within the debugger. 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
non-@code{nil} value to override this.
@item R
Like @kbd{e}, but also save the result of evaluation in the

325
doc/lispref/display.texi
View file

@ -336,7 +336,10 @@ functions call it with no arguments when their argument message is
Usually this function is called when the next input event arrives
after displaying an echo-area message. The function is expected to
clear the message displayed by its counterpart function specified by
@code{set-message-function}.
@code{set-message-function}, but doesn't have to. If the function
wants the echo area to remain uncleared, it should return the symbol
@code{dont-clear-message}; any other value will result in the echo
area being cleared.
The default value is the function that clears the message displayed in
an active minibuffer.
@ -612,6 +615,16 @@ how to display a message and prevent it from being logged:
@end example
@end defopt
@defvar messages-buffer-name
This variable has the name of the buffer where messages should be
logged to, and defaults to @file{*Messages*}. Some packages may find
it useful to temporarily redirect the output to a different buffer
(perhaps to write the buffer out to a log file later), and they can
bind this variable to a different buffer name. (Note that this buffer
(if it doesn't exist already), will be created and put into
@code{messages-buffer-mode}.)
@end defvar
To make @file{*Messages*} more convenient for the user, the logging
facility combines successive identical messages. It also combines
successive related messages for the sake of two cases: question
@ -1997,6 +2010,11 @@ Tables}). The width of a tab character is usually @code{tab-width}
(@pxref{Usual Display}).
@end defun
@defun char-uppercase-p char
Return non-@code{nil} if @var{char} is an uppercase character
according to Unicode.
@end defun
@defun string-width string &optional from to
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
@ -2132,7 +2150,7 @@ the buffer might contain long lines that will be truncated anyway.
The optional argument @var{y-limit}, if non-@code{nil}, specifies the
maximum Y coordinate beyond which text is to be ignored; it is
therefore also the maximum pixel-height that the function can return.
If @var{y-limit} is nil or omitted, it means to considers all the
If @var{y-limit} is @code{nil} or omitted, it means to consider all the
lines of text till the buffer position specified by @var{to}. Since
calculating the pixel-height of a large buffer can take some time, it
makes sense to specify this argument; in particular, if the caller
@ -2456,6 +2474,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}
@ -2464,7 +2483,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
@ -2555,13 +2580,16 @@ Underline with the foreground color of the face.
@item @var{color}
Underline in color @var{color}, a string specifying a color.
@item @code{(:color @var{color} :style @var{style})}
@item @code{(:color @var{color} :style @var{style} :position @var{position})}
@var{color} is either a string, or the symbol @code{foreground-color},
meaning the foreground color of the face. Omitting the attribute
@code{:color} means to use the foreground color of the face.
@var{style} should be a symbol @code{line} or @code{wave}, meaning to
use a straight or wavy line. Omitting the attribute @code{:style}
means to use a straight line.
means to use a straight line. @var{position}, if non-nil, means to
display the underline at the descent of the text, instead of at the
baseline level. If it is a number, then it specifies the amount of
pixels above the descent to display the underline.
@end table
@cindex overlined text
@ -2641,9 +2669,10 @@ used automatically to handle certain shades of gray.
@item :font
The font used to display the face. Its value should be a font object
or a fontset. @xref{Low-Level Font}, for information about font
objects, font specs, and font entities. @xref{Fontsets}, for
information about fontsets.
or a fontset. If it is a font object, it specifies the font to be
used by the face for displaying ASCII characters. @xref{Low-Level
Font}, for information about font objects, font specs, and font
entities. @xref{Fontsets}, for information about fontsets.
@anchor{face-font-attribute}
When specifying this attribute using @code{set-face-attribute} or
@ -2684,6 +2713,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
@ -2802,7 +2838,7 @@ apply to. Here are the possible values of @var{characteristic}:
The kind of window system the terminal uses---either @code{graphic}
(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
console), @code{w32} (for MS Windows 9X/NT/2K/XP), @code{haiku} (for
Haiku), @code{pgtk} (for GTK), or @code{tty} (a non-graphics-capable
Haiku), @code{pgtk} (for pure GTK), or @code{tty} (a non-graphics-capable
display). @xref{Window Systems, window-system}.
@item class
@ -2910,7 +2946,8 @@ modifying the attributes of a named face.
@defun face-attribute face attribute &optional frame inherit
This function returns the value of the @var{attribute} attribute for
@var{face} on @var{frame}.
@var{face} on @var{frame}. @xref{Face Attributes}, for the supported
attributes.
If @var{frame} is omitted or @code{nil}, that means the selected frame
(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
@ -2993,7 +3030,8 @@ for all frames. This function is mostly intended for internal usage.
@defun set-face-attribute face frame &rest arguments
This function sets one or more attributes of @var{face} for
@var{frame}. The attributes specified in this way override the face
spec(s) belonging to @var{face}.
spec(s) belonging to @var{face}. @xref{Face Attributes}, for the
supported attributes.
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute
@ -3007,12 +3045,21 @@ names (such as @code{:family} or @code{:underline}) and values. Thus,
sets the attribute @code{:weight} to @code{bold} and the attribute
@code{:slant} to @code{italic}.
If @var{frame} is @code{t}, this function sets the default attributes
for newly created frames; they will effectively override the attribute
values specified by @code{defface}. If @var{frame} is @code{nil},
this function sets the attributes for all existing frames, as well as
for newly created frames.
for newly created frames. However, if you want to @emph{reset} the
value of an attribute to @code{unspecified} in a way that also affects
newly created frames, you @emph{must} explicitly call this function
with @var{frame} set to @code{t} and the value of the attribute set to
@code{unspecified} (@emph{not} @code{nil}!@:), in addition to the call
with @var{frame} set to @code{nil}. This is because the default
attributes for newly created frames are merged with the face's spec in
@code{defface} when a new frame is created, and so having
@code{unspecified} in the default attributes for new frames will be
unable to override @code{defface}; the special call to this function
as described above will arrange for @code{defface} to be overridden.
@end defun
The following commands and functions mostly provide compatibility
@ -3087,13 +3134,19 @@ return value is always specified, use a value of @code{default} for
@var{inherit}.
@defun face-font face &optional frame character
This function returns the name of the font of face @var{face}.
This function returns the name of the font used by the specified
@var{face}.
If the optional argument @var{frame} is specified, it returns the name
of the font of @var{face} for that frame. If @var{frame} is omitted or
@code{nil}, the selected frame is used. In the latter case, if the
optional third argument @var{character} is supplied, it returns the font
name used for @var{character}.
of the font of @var{face} for that frame; @var{frame} defaults to the
selected frame if it is @code{nil} or omitted. If @var{frame} is
@code{t}, the function reports on the font defaults for @var{face} to
be used for new frames.
By default, the returned font is for displaying ASCII characters, but
if @var{frame} is anything but @code{t}, and the optional third
argument @var{character} is supplied, the function returns the font
name used by @var{face} for that character.
@end defun
@defun face-foreground face &optional frame inherit
@ -3283,10 +3336,10 @@ and @code{face-remap-reset-base} functions; it is intended for major
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
This function adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
This function adds @var{specs} as relative remappings for face
@var{face} in the current buffer. @var{specs} should be a list where
each element is either a face name, or a property list of
attribute/value pairs.
The return value is a Lisp object that serves as a cookie; you can
pass this object as an argument to @code{face-remap-remove-relative}
@ -3300,6 +3353,16 @@ if you need to remove the remapping later.
;; Increase the size of the 'default' face by 50%:
(face-remap-add-relative 'default :height 1.5)
@end example
Note that buffer-local face remapping does not work reliably for
parent faces of basic faces (@pxref{Basic Faces}). (These are the
faces that are used in mode lines, header lines, and other basic
decorations of windows and frames.) For instance,
@code{mode-line-inactive} inherits from @code{mode-line}, but
remapping @code{mode-line} won't normally have the desired effect on
@code{mode-line-inactive}, especially if done locally for some
buffers. Instead you have to remap @code{mode-line-inactive}
directly.
@end defun
@defun face-remap-remove-relative cookie
@ -3425,10 +3488,10 @@ usually assign faces to around 400 to 600 characters at each call.
If your Emacs Lisp program needs to assign some faces to text, it is
often a good idea to use certain existing faces or inherit from them,
rather than defining entirely new faces. This way, if other users
have customized the basic faces to give Emacs a certain look, your
program will fit in without additional customization.
have customized those existing faces to give Emacs a certain look,
your program will fit in without additional customization.
Some of the basic faces defined in Emacs are listed below. In
Some of the @dfn{basic faces} defined in Emacs are listed below. In
addition to these, you might want to make use of the Font Lock faces
for syntactic highlighting, if highlighting is not already handled by
Font Lock mode, or if some Font Lock faces are not in use.
@ -3440,6 +3503,28 @@ The default face, whose attributes are all specified. All other faces
implicitly inherit from it: any unspecified attribute defaults to the
attribute on this face (@pxref{Face Attributes}).
@item mode-line-active
@itemx mode-line-inactive
@itemx header-line
@itemx tab-line
Basic faces used for the mode line, header line, and tab line.
@item tool-bar
@itemx tab-bar
@itemx fringe
@itemx scroll-bar
@itemx window-divider
@itemx border
@itemx child-frame-border
Basic faces used for the corresponding decorations of GUI frames.
@item cursor
The basic face used for the text cursor.
@item mouse
The basic face used for displaying mouse-sensitive text when the mouse
pointer is on that text.
@item bold
@itemx italic
@itemx bold-italic
@ -3746,57 +3831,62 @@ Then, the font specifications for all but Chinese GB2312 characters have
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
@defun set-fontset-font name character font-spec &optional frame add
This function modifies the existing fontset @var{name} to use the font
matching with @var{font-spec} for the specified @var{character}.
@defun set-fontset-font fontset characters font-spec &optional frame add
This function modifies the existing @var{fontset} to use the font
specified by @var{font-spec} for displaying the specified
@var{characters}.
If @var{name} is @code{nil}, this function modifies the fontset of the
selected frame or that of @var{frame} if @var{frame} is not
If @var{fontset} is @code{nil}, this function modifies the fontset of
the selected frame or that of @var{frame} if @var{frame} is not
@code{nil}.
If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
If @var{fontset} is @code{t}, this function modifies the default
fontset, whose short name as a string is @samp{fontset-default}.
In addition to specifying a single codepoint, @var{character} may be a
cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are
character codepoints. In that case, use @var{font-spec} for all the
characters in the range @var{from} and @var{to} (inclusive).
The @var{characters} argument can be a single character which should
be displayed using @var{font-spec}. It can also be a cons cell
@w{@code{(@var{from} . @var{to})}}, where @var{from} and @var{to} are
characters. In that case, use @var{font-spec} for all the characters
in the range @var{from} and @var{to} (inclusive).
@var{character} may be a charset (@pxref{Character Sets}). In that
case, use @var{font-spec} for all the characters in the charset.
@var{characters} may be a charset symbol (@pxref{Character Sets}). In
that case, use @var{font-spec} for all the characters in the charset.
@var{character} may be a script name (@pxref{Character Properties,
@var{characters} may be a script symbol (@pxref{Character Properties,
char-script-table}). In that case, use @var{font-spec} for all the
characters belonging to the script.
@var{character} may be @code{nil}, which means to use @var{font-spec}
for any character which no font-spec is specified.
@var{characters} may be @code{nil}, which means to use @var{font-spec}
for any character in @var{fontset} for which no font-spec is
specified.
@var{font-spec} may be a font-spec object created by the function
@code{font-spec} (@pxref{Low-Level Font}).
@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).
@var{font-spec} may be a cons cell @w{@code{(@var{family}
. @var{registry})}}, where @var{family} is a family name of a font
(possibly including a foundry name at the head), and @var{registry} is
a registry name of a font (possibly including an encoding name at the
tail).
@var{font-spec} may be a font name, a string.
@var{font-spec} may be @code{nil}, which explicitly specifies that
there's no font for the specified @var{character}. This is useful,
there's no font for the specified @var{characters}. This is useful,
for example, to avoid expensive system-wide search for fonts for
characters that have no glyphs, like those from the Unicode Private
Use Area (PUA).
The optional argument @var{add}, if non-@code{nil}, specifies how to
add @var{font-spec} to the font specifications previously set. If it
is @code{prepend}, @var{font-spec} is prepended. If it is
@code{append}, @var{font-spec} is appended. By default,
@var{font-spec} overrides the previous settings.
add @var{font-spec} to the font specifications previously set for
@var{characters}. If it is @code{prepend}, @var{font-spec} is
prepended to the existing specs. If it is @code{append},
@var{font-spec} is appended. By default, @var{font-spec} overwrites
the previously set font specs.
For instance, this changes the default fontset to use a font of which
For instance, this changes the default fontset to use a font whose
family name is @samp{Kochi Gothic} for all characters belonging to
the charset @code{japanese-jisx0208}.
the charset @code{japanese-jisx0208}:
@smallexample
(set-fontset-font t 'japanese-jisx0208
@ -3936,13 +4026,26 @@ required; and @code{gpos} is a list of OpenType GPOS feature tag
symbols, or @code{nil} if none is required. If @code{gsub} or
@code{gpos} is a list, a @code{nil} element in that list means that
the font must not match any of the remaining tag symbols. The
@code{gpos} element may be omitted.
@code{gpos} element may be omitted. For the list of OpenType script,
language, and feature tags, see
@uref{https://docs.microsoft.com/en-us/typography/opentype/spec/ttoreg,
the list of registered OTF tags}.
@item :type
@cindex font backend
The symbol that specifies the @dfn{font backend} used to draw the
characters. The possible values depend on the platform and on how
Emacs was configured at build time. Typical values include
@code{ftcrhb} and @code{xfthb} on X, @code{harfbuzz} on MS-Windows,
@code{ns} on GNUstep, etc. It can also be @code{nil} if left
unspecified, typically in a font-spec.
@end table
@end defun
@defun font-put font-spec property value
Set the font property @var{property} in the font-spec @var{font-spec}
to @var{value}.
to @var{value}. The @var{property} can any of the ones described
above.
@end defun
@cindex font entity
@ -3986,12 +4089,28 @@ object, a font entity, or a font spec.
@defun font-get font property
This function returns the value of the font property @var{property}
for @var{font}.
for @var{font}. The @var{property} can any of the ones that
@code{font-spec} supports.
If @var{font} is a font spec and the font spec does not specify
@var{property}, the return value is @code{nil}. If @var{font} is a
font object or font entity, the value for the @var{:script} property
may be a list of scripts supported by the font.
may be a list of scripts supported by the font, and the value of the
@code{:otf} property is a cons of the form @w{@code{(@var{gsub}
. @var{gpos})}}, where @var{gsub} and @var{gpos} are lists
representing OpenType features supported by the font, of the form
@smallexample
((@var{script-tag} (@var{langsys-tag} @var{feature}@dots{}) @dots{}) @dots{})
@end smallexample
@noindent where @var{script-tag}, @var{langsys-tag}, and @var{feature}
are symbols representing OpenType layout tags.
If @var{font} is a font object, the special property
@code{:combining-capability} is non-@code{nil} if the font backend of
@var{font} supports rendering of combining characters for non-OpenType
fonts.
@end defun
@defun font-face-attributes font &optional frame
@ -4581,14 +4700,15 @@ about to be executed. This feature has nothing to do with
@defvar overlay-arrow-string
This variable holds the string to display to call attention to a
particular line, or @code{nil} if the arrow feature is not in use.
On a graphical display the contents of the string are ignored; instead a
glyph is displayed in the fringe area to the left of the display area.
On a graphical display the contents of the string are ignored if the
left fringe is shown; instead a glyph is displayed in the fringe area
to the left of the display area.
@end defvar
@defvar overlay-arrow-position
This variable holds a marker that indicates where to display the overlay
arrow. It should point at the beginning of a line. On a non-graphical
display the arrow text
display, or when the left fringe is not shown, the arrow text
appears at the beginning of that line, overlaying any text that would
otherwise appear. Since the arrow is usually short, and the line
usually begins with indentation, normally nothing significant is
@ -4620,11 +4740,12 @@ this list.
Each variable on this list can have properties
@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
specify an overlay arrow string (for text terminals) or fringe bitmap
(for graphical terminals) to display at the corresponding overlay
arrow position. If either property is not set, the default
@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
is used.
specify an overlay arrow string (for text terminals or graphical
terminals without the left fringe shown) or fringe bitmap
(for graphical terminals with a left fringe) to display at the
corresponding overlay arrow position. If either property is not set,
the default @code{overlay-arrow-string} or @code{overlay-arrow} fringe
indicator is used.
@node Scroll Bars
@ -4950,7 +5071,7 @@ which are evaluated at display time. This could be unsafe in certain
situations, e.g., when the display specification was generated by some
external program/agent. Wrapping a display specification in a list
that begins with the special symbol @code{disable-eval}, as in
@w{@code{('disable-eval @var{spec})}}, will disable evaluation of any
@w{@code{(disable-eval @var{spec})}}, will disable evaluation of any
Lisp in @var{spec}, while still supporting all the other display
property features.
@ -5226,7 +5347,7 @@ is partitioned using the identity of the parameter, which is why the
parameter is a list with one element. For instance:
@lisp
(insert (propertize "foo" '(display (min-width (6.0)))))
(insert (propertize "foo" 'display '(min-width (6.0))))
@end lisp
This will add padding after @samp{foo} bringing the total width up to
@ -5444,6 +5565,12 @@ symbol}. The symbols for the above formats are, respectively,
@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg},
@code{tiff}, @code{png}, @code{svg}, and @code{webp}.
On some platforms, the built-in image support that doesn't require
any optional libraries includes BMP images.@footnote{
On MS-Windows, this requires @code{w32-use-native-image-API} to be set
non-@code{nil}.
}
Furthermore, if you build Emacs with ImageMagick
(@code{libMagickWand}) support, Emacs can display any image format
that ImageMagick can. @xref{ImageMagick Images}. All images
@ -5597,6 +5724,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
@ -5810,13 +5943,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
@ -5824,26 +5954,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}.
@ -6616,7 +6731,9 @@ buffer's text.
The argument @var{slice} specifies a slice of the image to insert. If
@var{slice} is @code{nil} or omitted the whole image is inserted.
Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
(However, note that images are chopped on display at the window's
right edge, because wrapping images is not supported.) Otherwise,
@var{slice} is a list @code{(@var{x} @var{y} @var{width}
@var{height})} which specifies the @var{x} and @var{y} positions and
@var{width} and @var{height} of the image area to insert. Integer
values are in units of pixels. A floating-point number in the range
@ -7297,7 +7414,7 @@ current buffer, and returns it.
@end defun
@defun insert-button label &rest properties
This insert a button with the label @var{label} at point,
This inserts a button with the label @var{label} at point,
and returns it.
@end defun
@ -7446,7 +7563,7 @@ end of the buffer continues from the other end. If
@var{display-message} is non-@code{nil}, the button's help-echo string
is displayed. Any button with a non-@code{nil} @code{skip} property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If @var{no-error} is non-@code{nil}, return nil
buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil}
instead of signaling the error.
@end deffn
@ -7458,7 +7575,7 @@ end of the buffer continues from the other end. If
@var{display-message} is non-@code{nil}, the button's help-echo string
is displayed. Any button with a non-@code{nil} @code{skip} property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If @var{no-error} is non-@code{nil}, return nil
buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil}
instead of signaling the error.
@end deffn
@ -8104,7 +8221,10 @@ help buffer.
The window's display table, if there is one, takes precedence over the
buffer's display table. If neither exists, Emacs tries to use the
standard display table; if that is @code{nil}, Emacs uses the usual
character display conventions (@pxref{Usual Display}).
character display conventions (@pxref{Usual Display}). (Emacs does
not ``merge'' display tables: For instance, if the window has a
display table, the buffer's display table and the standard display
table are completely ignored.)
Note that display tables affect how the mode line is displayed, so
if you want to force redisplay of the mode line using a new display
@ -8210,7 +8330,7 @@ there is no available font (on a graphical display), and characters
which cannot be encoded by the terminal's coding system (on a text
terminal).
@vindex glyphless-display-mode
@findex glyphless-display-mode
The @code{glyphless-display-mode} minor mode can be used to toggle
displaying glyphless characters in a convenient manner in the current
buffer. If this mode is enabled, all the glyphless characters are
@ -8386,6 +8506,8 @@ GNUstep and macOS).
Emacs is displaying the frame using MS-DOS direct screen writes.
@item haiku
Emacs is displaying the frame using the Application Kit on Haiku.
@item pgtk
Emacs is displaying the frame using pure GTK facilities.
@item nil
Emacs is displaying the frame on a character-based terminal.
@end table
@ -8433,13 +8555,14 @@ displayed in the echo area.
@end defun
@cindex system tooltips
@vindex x-gtk-use-system-tooltips
When Emacs is built with GTK+ support, it by default displays tooltips
using GTK+ functions, and the appearance of the tooltips is then
controlled by GTK+ settings. GTK+ tooltips can be disabled by
changing the value of the variable @code{x-gtk-use-system-tooltips} to
@code{nil}. The rest of this subsection describes how to control
non-GTK+ tooltips, which are presented by Emacs itself.
@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 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,
which are presented by Emacs itself.
@cindex tooltip frames
Tooltips are displayed in special frames called tooltip frames, which

16
doc/lispref/edebug.texi
View file

@ -700,8 +700,16 @@ on this process.
@table @kbd
@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.
(@code{edebug-eval-expression}). That is, Edebug tries to minimize
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
non-@code{nil} value to override this.
@item M-: @var{exp} @key{RET}
Evaluate expression @var{exp} in the context of Edebug itself
@ -711,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)
@ -832,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.

6
doc/lispref/elisp.texi
View file

@ -448,6 +448,9 @@ Symbols
* Creating Symbols:: How symbols are kept unique.
* Symbol Properties:: Each symbol has a property list
for recording miscellaneous information.
* Shorthands:: Properly organize your symbol names but
type less of them.
* Symbols with Position:: Symbol variants containing integer positions
Symbol Properties
@ -589,6 +592,7 @@ Advising Emacs Lisp Functions
* Advising Named Functions:: Advising named functions.
* Advice Combinators:: Ways to compose advice.
* Porting Old Advice:: Adapting code using the old defadvice.
* Advice and Byte Code:: Not all functions can be advised.
Macros
@ -735,6 +739,7 @@ Reading and Printing Lisp Objects
* Output Functions:: Functions to print Lisp objects as text.
* Output Variables:: Variables that control what the printing
functions do.
* Output Overrides:: Overriding output variables.
Minibuffers
@ -1228,6 +1233,7 @@ Text
* Decompression:: Dealing with compressed data.
* Base 64:: Conversion to or from base 64 encoding.
* Checksum/Hash:: Computing cryptographic hashes.
* Suspicious Text:: Determining whether a string is suspicious.
* GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
* Database:: Interacting with an SQL database.
* Parsing HTML/XML:: Parsing HTML and XML.

2
doc/lispref/eval.texi
View file

@ -435,7 +435,7 @@ expansion.
@cindex forms, special
@cindex evaluation of special forms
A @dfn{special form} is a primitive function specially marked so that
A @dfn{special form} is a primitive specially marked so that
its arguments are not all evaluated. Most special forms define control
structures or perform variable bindings---things which functions cannot
do.

44
doc/lispref/files.texi
View file

@ -581,9 +581,12 @@ contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
It is possible to read a special file (such as a FIFO or an I/O device)
with @code{insert-file-contents}, as long as @var{replace} and
@var{visit} are @code{nil}.
It is possible to read a special file (such as a FIFO or an I/O
device) with @code{insert-file-contents}, as long as @var{replace},
and @var{visit} and @var{beg} are @code{nil}. However, you should
normally use an @var{end} argument for these files to avoid inserting
(potentially) unlimited data into the buffer (for instance, when
inserting data from @file{/dev/urandom}).
@end defun
@defun insert-file-contents-literally filename &optional visit beg end replace
@ -1450,13 +1453,19 @@ is owned by the user with name @samp{lh}.
is in the group with name @samp{users}.
@item (20614 64019 50040 152000)
was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@.
(This timestamp is @code{(1351023123050040152 . 1000000000)}
if @code{current-time-list} is @code{nil}.)
@item (20000 23 0 0)
was last modified on July 15, 2001, at 08:53:43 UTC.
was last modified on July 15, 2001, at 08:53:43.000000000 UTC@.
(This timestamp is @code{(1310720023000000000 . 1000000000)}
if @code{current-time-list} is @code{nil}.)
@item (20614 64555 902289 872000)
last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@.
(This timestamp is @code{(1351023659902289872 . 1000000000)}
if @code{current-time-list} is @code{nil}.)
@item 122295
is 122295 bytes long. (It may not contain 122295 characters, though,
@ -2436,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
@ -3106,10 +3124,16 @@ except those two. It is useful as the @var{match-regexp} argument to
returns @code{nil}, if directory @samp{/foo} is empty.
@end defvr
@defun file-expand-wildcards pattern &optional full
@defun file-expand-wildcards pattern &optional full regexp
This function expands the wildcard pattern @var{pattern}, returning
a list of file names that match it.
@var{pattern} is, by default, a ``glob''/wildcard string, e.g.,
@samp{"/tmp/*.png"} or @samp{"/*/*/foo.png"}, but can also be a
regular expression if the optional @var{regexp} parameter is non-nil.
In any case, the matches are applied per sub-directory, so a match
can't span a parent/sub directory.
If @var{pattern} is written as an absolute file name,
the values are absolute also.
@ -3344,6 +3368,7 @@ first, before handlers for jobs such as remote file access.
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},@*
@code{list-system-processes},
@code{load}, @code{lock-file},
@code{make-auto-save-file-name},
@code{make-directory},
@ -3352,7 +3377,7 @@ first, before handlers for jobs such as remote file access.
@code{make-nearby-temp-file},
@code{make-process},
@code{make-symbolic-link},@*
@code{process-file},
@code{process-attributes}, @code{process-file},
@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@ -3405,6 +3430,7 @@ first, before handlers for jobs such as remote file access.
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
@code{list-system-processes},
@code{load}, @code{lock-file},
@code{make-auto-save-file-name},
@code{make-direc@discretionary{}{}{}tory},
@ -3413,7 +3439,7 @@ first, before handlers for jobs such as remote file access.
@code{make-nearby-temp-file},
@code{make-process},
@code{make-symbolic-link},
@code{process-file},
@code{process-attributes}, @code{process-file},
@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},

383
doc/lispref/frames.texi
View file

@ -60,6 +60,8 @@ The frame is displayed on a GNUstep or Macintosh Cocoa graphical
terminal.
@item pc
The frame is displayed on an MS-DOS terminal.
@item pgtk
The frame is displayed using pure GTK facilities.
@end table
@end defun
@ -456,6 +458,18 @@ monitor, the same string as returned by the function
@var{display} should be the name of an X display (a string).
@end deffn
@cindex monitor change functions
@defvar display-monitors-changed-functions
This variable is an abnormal hook run when the monitor configuration
changes, which can happen if a monitor is rotated, moved, added or
removed from a multiple-monitor setup, if the primary monitor changes,
or if the resolution of a monitor changes. It is called with a single
argument consisting of the terminal on which the monitor configuration
changed. Programs should call @code{display-monitor-attributes-list}
with the terminal as the argument to retrieve the new monitor
configuration on that terminal.
@end defvar
@node Frame Geometry
@section Frame Geometry
@cindex frame geometry
@ -681,9 +695,9 @@ The position of the top left corner of the native frame specifies the
indicate that position for the various builds:
@itemize @w{}
@item (1) non-toolkit and terminal frames
@item (1) non-toolkit, Haiku, and terminal frames
@item (2) Lucid, Motif, MS-Windows, and Haiku frames
@item (2) Lucid, Motif, and MS-Windows frames
@item (3) GTK+ and NS frames
@end itemize
@ -1732,17 +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}.@footnote{On Haiku, setting
@code{fullscreen} to @code{fullwidth} or @code{fullheight} 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.
@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
@ -2166,6 +2179,11 @@ prevent hanging with those window managers.
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
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 inhibit-double-buffering@r{, a frame parameter}
@item inhibit-double-buffering
If non-@code{nil}, the frame is drawn to the screen without double
@ -2431,6 +2449,16 @@ opacity when it is not selected.
Some window systems do not support the @code{alpha} parameter for child
frames (@pxref{Child Frames}).
@vindex alpha-background@r{, a frame parameter}
@item alpha-background
@cindex opacity, frame
@cindex transparency, frame
Sets the background transparency of the frame. Unlike the @code{alpha}
frame parameter, this only controls the transparency of the background
while keeping foreground elements such as text fully opaque. It
should be an integer between 0 and 100, where 0 means
completely transparent and 100 means completely opaque (default).
@end table
The following frame parameters are semi-obsolete in that they are
@ -3152,10 +3180,8 @@ raises @var{frame} above all other child frames of its parent.
@deffn Command lower-frame &optional frame
This function lowers frame @var{frame} (default, the selected frame)
below all other frames belonging to the same or a higher z-group as
@var{frame}.@footnote{Lowering frames is not supported on Haiku, due
to limitations imposed by the system.} If @var{frame} is a child
frame (@pxref{Child Frames}), this lowers @var{frame} below all other
child frames of its parent.
@var{frame}. If @var{frame} is a child frame (@pxref{Child Frames}),
this lowers @var{frame} below all other child frames of its parent.
@end deffn
@defun frame-restack frame1 frame2 &optional above
@ -3497,10 +3523,18 @@ enabled. Typically, @var{body} would use @code{read-event} to read
the motion events and modify the display accordingly. @xref{Motion
Events}, for the format of mouse motion events.
The value of @code{track-mouse} is that of the last form in @var{body}.
You should design @var{body} to return when it sees the up-event that
indicates the release of the button, or whatever kind of event means
it is time to stop tracking.
The value of @code{track-mouse} is that of the last form in
@var{body}. You should design @var{body} to return when it sees the
up-event that indicates the release of the button, or whatever kind of
event means it is time to stop tracking. Its value also controls how
mouse events are reported while a mouse button is held down: if it is
@code{dropping} or @code{drag-source}, the motion events are reported
relative to the frame underneath the pointer. If there is no such
frame, the events will be reported relative to the frame the mouse
buttons were first pressed on. In addition, the @code{posn-window} of
the mouse position list will be @code{nil} if the value is
@code{drag-source}. This is useful to determine if a frame is not
directly visible underneath the mouse pointer.
The @code{track-mouse} form causes Emacs to generate mouse motion
events by binding the variable @code{track-mouse} to a
@ -3744,6 +3778,13 @@ still use a menu keymap to implement it. To make the contents vary, add
a hook function to @code{menu-bar-update-hook} to update the contents of
the menu keymap as necessary.
@defvar x-pre-popup-menu-hook
A normal hook run immediately before a pop-up menu is displayed,
either directly by calling @code{x-popup-menu}, or through a menu
keymap. It won't be called if @code{x-popup-menu} returns for some
other reason without displaying a pop-up menu.
@end defvar
@node Dialog Boxes
@section Dialog Boxes
@cindex dialog boxes
@ -3847,8 +3888,9 @@ in the buffer. The default is to use the @code{arrow} (non-text)
pointer style.
@end defopt
When using X, you can specify what the @code{text} pointer style
really looks like by setting the variable @code{x-pointer-shape}.
When using some window systems, you can specify what the @code{text}
pointer style really looks like by setting the variable
@code{x-pointer-shape}.
@defvar x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the
@ -3896,11 +3938,18 @@ upper-case names, in accord with X Window System conventions. If
@var{type} is @code{nil}, that stands for @code{PRIMARY}.
If @var{data} is @code{nil}, it means to clear out the selection.
Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
of two integers or list of two integers), an overlay, or a cons of two
markers pointing to the same buffer. An overlay or a pair of markers
stands for text in the overlay or between the markers. The argument
@var{data} may also be a vector of valid non-vector selection values.
Otherwise, @var{data} may be a string, a symbol, an integer, an
overlay, or a cons of two markers pointing to the same buffer. An
overlay or a pair of markers stands for text in the overlay or between
the markers. The argument @var{data} may also be a vector of valid
non-vector selection values.
If @var{data} is a string, then its text properties can specify values
used for individual data types. For example, if @var{data} has a
property named @code{text/uri-list}, then a call to
@code{gui-get-selection} with the data type @code{text/uri-list} will
result in the value of that property being used instead of @var{data}
itself.
This function returns @var{data}.
@end deffn
@ -3988,16 +4037,46 @@ amount of different data types on the clipboard.
@section Drag and Drop
@cindex drag and drop
When the user drops something from another application over Emacs,
Emacs will try to insert any text and open any URL that was dropped.
If text was dropped, then it will always be inserted at the location
of the mouse pointer when the drop happened, or saved in the kill ring
if insertion failed (which can happen if the buffer is read-only). If
it was an URL, then Emacs tries to call an appropriate handler
function by first matching the URL against regexps defined in
@code{dnd-protocol-alist}, and then against @code{browse-url-handlers}
and @code{browse-url-default-handlers}, and failing that, inserting
the URL as plain text.
@defvar dnd-protocol-alist
This variable is a list of cons cells of the form
@w{@code{(@var{pattern} . @var{action})}}. @var{pattern} is a regexp
that URLs are matched against after being dropped. @var{action} is a
function that is called with two arguments should a URL being dropped
match @var{pattern}: the URL being dropped, and the action being
performed for the drop (one of the symbols @code{copy}, @code{move},
@code{link}, @code{private} or @code{ask}).
@end defvar
@cindex drag and drop, X
@cindex drag and drop, other formats
Emacs implements drag-and-drop for text and URLs individually for
each window system, and does not by default support the dropping of
anything else. Code that wishes to support the dropping of content
types not supported by Emacs can utilize the X-specific interface
described below:
@vindex x-dnd-test-function
@vindex x-dnd-known-types
When a user drags something from another application over Emacs, that other
application expects Emacs to tell it if Emacs can handle the data that is
dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
what to reply. The default value is @code{x-dnd-default-test-function}
which accepts drops if the type of the data to be dropped is present in
@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
on some other criteria.
When a user drags something from another application over Emacs on
the X Window System, that other application expects Emacs to tell it
if Emacs can handle the data that was dragged. The variable
@code{x-dnd-test-function} is used by Emacs to determine what to
reply. The default value is @code{x-dnd-default-test-function} which
accepts drops if the type of the data to be dropped is present in
@code{x-dnd-known-types}. You can customize
@code{x-dnd-test-function} and/or @code{x-dnd-known-types} if you want
Emacs to accept or reject drops based on some other criteria.
@vindex x-dnd-types-alist
If you want to change the way Emacs handles drop of different types
@ -4005,16 +4084,228 @@ or add a new type, customize @code{x-dnd-types-alist}. This requires
detailed knowledge of what types other applications use for drag and
drop.
@vindex dnd-protocol-alist
@vindex browse-url-handlers
@vindex browse-url-default-handlers
When an URL is dropped on Emacs it may be a file, but it may also be
another URL type (https, etc.). Emacs first checks
@code{dnd-protocol-alist} to determine what to do with the URL@. If
there is no match there, Emacs looks for a match in
@code{browse-url-handlers} and @code{browse-url-default-handlers}. If
still no match has been found, the text for the URL is inserted. If
you want to alter Emacs behavior, you can customize these variables.
Those data types are typically implemented as special data types an
X selection provided by the other application can be converted to.
They can either be the same data types that are typically accepted by
@code{gui-set-selection}, or they can be MIME types, depending on the
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.
@cindex drop target, in drag-and-drop operations
@defun dnd-begin-text-drag text &optional frame action allow-same-frame
This function begins dragging text from @var{frame} to another program
(known as the @dfn{drop target}), and returns the result of
drag-and-drop operation when the text is dropped or the drag-and-drop
operation is canceled. @var{text} is the text that will be inserted
by the drop target.
@var{action} must be one of the symbols @code{copy} or @code{move},
where @code{copy} means that @var{text} should be inserted by the drop
target, and @code{move} means the same as @code{copy}, but in addition
the caller may have to delete @var{text} from its source as explained
below.
@var{frame} is the frame where the mouse is currently held down, or
@code{nil}, which means to use the selected frame. This function may
return immediately if no mouse buttons are held down, so it should be
only called immediately after a @code{down-mouse-1} or similar event
(@pxref{Mouse Events}), with @var{frame} set to the frame where that
event was generated (@pxref{Click Events}).
@var{allow-same-frame} specifies whether or not drops on top of
@var{frame} itself are to be ignored.
The return value specifies the action that the drop target actually
performed, and optionally what the caller should do. It can be one of
the following symbols:
@table @code
@item copy
The drop target inserted the dropped text.
@item move
The drop target inserted the dropped text, but in addition the caller
should delete @var{text} from wherever it originated, such as its
buffer.
@item private
The drop target performed some other unspecified action.
@item nil
The drag-and-drop operation was canceled.
@end table
@end defun
@defun dnd-begin-file-drag file &optional frame action allow-same-frame
This function begins dragging @var{file} from @var{frame} to another
program, and returns the result of the drag-and-drop operation when
the file is dropped or the drag-and-drop operation is canceled.
If @var{file} is a remote file, then a temporary copy will be made.
@var{action} must be one of the symbols @code{copy}, @code{move} or
@code{link}, where @code{copy} means that @var{file} should be opened
or copied by the drop target, @code{move} means the drop target should
move the file to another location, and @code{link} means the drop
target should create a symbolic link to @var{file}. It is an error to
specify @code{link} as the action if @var{file} is a remote file.
@var{frame} and @var{allow-same-frame} have the same meaning as in
@code{dnd-begin-text-drag}.
The return value is the action that the drop target actually
performed, which can be one of the following symbols:
@table @code
@item copy
The drop target opened or copied @var{file} to a different location.
@item move
The drop target moved @var{file} to a different location.
@item link
The drop target (usually a file manager) created a symbolic link to
@var{file}.
@item private
The drop target performed some other unspecified action.
@item nil
The drag-and-drop operation was canceled.
@end table
@end defun
@defun dnd-begin-drag-files files &optional frame action allow-same-frame
This function is like @code{dnd-begin-file-drag}, except that
@var{files} is a list of files. If the drop target doesn't support
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
or text, use the low-level interface @code{x-begin-drag}
instead. However, using it will require detailed knowledge of the
data types and actions used by the programs to transfer content via
drag-and-drop on each platform you want to support.
@defun x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip
This function begins a drag from @var{frame}, and returns when the
drag-and-drop operation ends, either because the drop was successful,
or because the drop was rejected. The drop occurs when all mouse
buttons are released on top of an X window other than @var{frame} (the
@dfn{drop target}), or any X window if @var{allow-current-frame} is
non-@code{nil}. If no mouse buttons are held down when the
drag-and-drop operation begins, this function may immediately return
@code{nil}.
@var{targets} is a list of strings describing selection targets, much
like the @var{data-type} argument to @code{gui-get-selection}, that
the drop target can request from Emacs (@pxref{Window System
Selections}).
@var{action} is a symbol describing the action recommended to the
target. It can either be @code{XdndActionCopy}, which
means to copy the contents of the selection @code{XdndSelection} to
the drop target; or @code{XdndActionMove}, which means copy as with
@code{XdndActionCopy}, and in addition the caller should delete
whatever was stored in that selection after copying it.
@var{action} may also be an alist which associates between symbols
describing the available actions, and strings that the drop target is
expected to present to the user to choose between the available
actions.
If @var{return-frame} is non-@code{nil} and the mouse moves over an
Emacs frame after first moving out of @var{frame}, then the frame to
which the mouse moves will be returned immediately. If
@var{return-frame} is the symbol @code{now}, then any frame underneath
the mouse pointer will be returned without waiting for the mouse to
first move out of @var{frame}. @var{return-frame} is useful when you
want to treat dragging content from one frame to another specially,
while also being able to drag content to other programs, but it is not
guaranteed to work on all systems and with all window managers.
If @var{follow-tooltip} is non-@code{nil}, the position of any tooltip
(such as one shown by @code{tooltip-show}) will follow the location of
the mouse pointer whenever it moves during the drag-and-drop
operation. The tooltip will be hidden once all mouse buttons are
released.
If the drop was rejected or no drop target was found, this function
returns @code{nil}. Otherwise, it returns a symbol describing the
action the target chose to perform, which can differ from @var{action}
if that isn't supported by the drop target. @code{XdndActionPrivate}
is also a valid return value in addition to @code{XdndActionCopy} and
@code{XdndActionMove}; it means that the drop target chose to perform
an unspecified action, and no further processing is required by the
caller.
The caller must cooperate with the target to fully perform the action
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

171
doc/lispref/functions.texi
View file

@ -22,6 +22,7 @@ define them.
* Function Cells:: Accessing or setting the function definition
of a symbol.
* Closures:: Functions that enclose a lexical environment.
* OClosures:: Function objects
* Advising Functions:: Adding to the definition of a function.
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Functions that the compiler will expand inline.
@ -145,7 +146,12 @@ function:
This function returns @code{t} if @var{object} is any kind of
function, i.e., can be passed to @code{funcall}. Note that
@code{functionp} returns @code{t} for symbols that are function names,
and returns @code{nil} for special forms.
and returns @code{nil} for symbols that are macros or special forms.
If @var{object} is not a function, this function ordinarily returns
@code{nil}. However, the representation of function objects is
complicated, and for efficiency reasons in rare cases this function
can return @code{t} even when @var{object} is not a function.
@end defun
It is also possible to find out how many arguments an arbitrary
@ -667,6 +673,22 @@ which file defined the function, just like @code{defun}
By contrast, in programs that manipulate function definitions for other
purposes, it is better to use @code{fset}, which does not keep such
records. @xref{Function Cells}.
@end defun
@defun function-alias-p object &optional noerror
Checks whether @var{object} is a function alias. If it is, it returns
a list of symbols representing the function alias chain, else
@code{nil}. For instance, if @code{a} is an alias for @code{b}, and
@code{b} is an alias for @code{c}:
@example
(function-alias-p 'a)
@result{} (b c)
@end example
If there's a loop in the definitions, an error will be signalled. If
@var{noerror} is non-@code{nil}, the non-looping parts of the chain is
returned instead.
@end defun
You cannot create a new primitive function with @code{defun} or
@ -1493,6 +1515,116 @@ exposed to the rest of the Lisp world is considered an internal
implementation detail. For this reason, we recommend against directly
examining or altering the structure of closure objects.
@node OClosures
@section Open Closures
Traditionally, functions are opaque objects which offer no other
functionality but to call them. Emacs Lisp functions aren't fully
opaque since you can extract some info out of them such as their
docstring, their arglist, or their interactive spec, but they are
mostly opaque. This is usually what we want, but occasionally we need
functions to expose a bit more information about themselves.
OClosures are functions which carry additional type information,
and expose some information in the form of slots which you can access
via accessor functions.
They are defined in two steps: first @code{oclosure-define} is used to
define new OClosure types by specifying the slots carried by those
OClosures, and then @code{oclosure-lambda} is used to create an
OClosure object of a given type.
Say we want to define keyboard macros, i.e. interactive functions
which re-execute a sequence of key events. You could do it with
a plain function as follows:
@example
(defun kbd-macro (key-sequence)
(lambda (&optional arg)
(interactive "P")
(execute-kbd-macro key-sequence arg)))
@end example
But with such a definition there is no easy way to extract the
@var{key-sequence} from that function, for example to print it.
We can solve this problem using OClosures as follows. First we define
the type of our keyboard macros (to which we decided to add
a @code{counter} slot while at it):
@example
(oclosure-define kbd-macro
"Keyboard macro."
keys (counter :mutable t))
@end example
After which we can rewrite our @code{kbd-macro} function:
@example
(defun kbd-macro (key-sequence)
(oclosure-lambda (kbd-macro (keys key-sequence) (counter 0))
(&optional arg)
(interactive "p")
(execute-kbd-macro keys arg)
(setq counter (1+ counter))))
@end example
As you can see, the @code{keys} and @code{counter} slots of the
OClosure can be accessed as local variables from within the body
of the OClosure. But we can now also access them from outside of the
body of the OClosure, for example to describe a keyboard macro:
@example
(defun describe-kbd-macro (km)
(if (not (eq 'kbd-macro (oclosure-type km)))
(message "Not a keyboard macro")
(let ((keys (kbd-macro--keys km))
(counter (kbd-macro--counter km)))
(message "Keys=%S, called %d times" keys counter))))
@end example
Where @code{kbd-macro--keys} and @code{kbd-macro--counter} are
accessor functions generated by the @code{oclosure-define} macro.
@defmac oclosure-define name &optional docstring &rest slots
This macro defines a new OClosure type along with accessor functions
for its slots. @var{name} can be a symbol (the name of
the new type), or a list of the form @code{(@var{name} . @var{type-props})} in
which case @var{type-props} is a list of additional properties.
@var{slots} is a list of slot descriptions where each slot can be
either a symbol (the name of the slot) or it can be of the form
@code{(@var{slot-name} . @var{slot-props})} where @var{slot-props} is
a property list.
For each slot, the macro creates an accessor function named
@code{@var{name}--@var{slot-name}}. By default slots are immutable.
If you need a slot to be mutable, you need to specify it with the
@code{:mutable} slot property, after which it can be mutated for
example with @code{setf}.
Beside slot accessors, the macro can create a predicate and
functional update functions according to @var{type-props}:
a @code{(:predicate @var{pred-name})} in the @var{type-props} causes
the definition of a predicate function under the name @var{pred-name},
and @code{(:copier @var{copier-name} @var{copier-arglist})} causes the
definition of a functional update function which takes an OClosure of
type @var{name} as first argument and returns a copy of it with the
slots named in @var{copier-arglist} modified to the value passed in the
corresponding argument.
@end defmac
@defmac oclosure-lambda (type . slots) arglist &rest body
This macro creates an anonymous OClosure of type @var{type}.
@var{slots} should be a list of elements of the form @code{(@var{slot-name}
@var{exp})}.
At run time, each @var{exp} is evaluated, in order, after which
the OClosure is created with its slots initialized with the
resulting values.
When called as a function, the OClosure will accept arguments
according to @var{arglist} and will execute the code in @var{body}.
@var{body} can refer to the value of any of its slot directly as if it
were a local variable that had been captured by static scoping.
@end defmac
@defun oclosure-type object
This function returns the OClosure type (a symbol) of @var{object} if it is an
OClosure, and @code{nil} otherwise.
@end defun
@node Advising Functions
@section Advising Emacs Lisp Functions
@cindex advising functions
@ -1585,6 +1717,7 @@ ways to do it. The added function is also called a piece of @emph{advice}.
* Advising Named Functions:: Advising named functions.
* Advice Combinators:: Ways to compose advice.
* Porting Old Advice:: Adapting code using the old defadvice.
* Advice and Byte Code:: Not all functions can be advised.
@end menu
@node Core Advising Primitives
@ -2006,6 +2139,37 @@ changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so
when porting such old @code{after} advice, you'll need to turn it into new
@code{:around} or @code{:filter-return} advice instead.
@c This is its own node because we link to it from *Help* buffers.
@node Advice and Byte Code
@subsection Advice and Byte Code
@cindex compiler macros, advising
@cindex @code{byte-compile} and @code{byte-optimize}, advising
Not all functions can be reliably advised. The byte compiler may
choose to replace a call to a function with a sequence of instructions
that doesn't call the function you were interested in altering.
This usually happens due to one of the three following mechanisms:
@table @asis
@item @code{byte-compile} properties
If a function's symbol has a @code{byte-compile} property, that
property will be used instead of the symbol's function definition.
@xref{Compilation Functions}.
@item @code{byte-optimize} properties
If a function's symbol has a @code{byte-optimize} property, the byte
compiler may rewrite the function arguments, or decide to use a
different function altogether.
@item @code{compiler-macro} declare forms
A function can have a special @code{compiler-macro} @code{declare}
form in its definition (@pxref{Declare Form}) that defines an
@dfn{expander} to call when compiling the function. The expander
could then cause the produced byte-code not to call the original
function.
@end table
@node Obsolete Functions
@section Declaring Functions Obsolete
@cindex obsolete functions
@ -2137,8 +2301,8 @@ worry about how many times the body uses the arguments, as you do for
macros.
Alternatively, you can define a function by providing the code which
will inline it as a compiler macro. The following macros make this
possible.
will inline it as a compiler macro (@pxref{Declare Form}). The
following macros make this possible.
@c FIXME: Can define-inline use the interactive spec?
@defmac define-inline name args [doc] [declare] body@dots{}
@ -2294,6 +2458,7 @@ which case the warning message gives no extra details). @var{when}
should be a string indicating when the function or macro was first
made obsolete.
@cindex compiler macro
@item (compiler-macro @var{expander})
This can only be used for functions, and tells the compiler to use
@var{expander} as an optimization function. When encountering a call to the

18
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

21
doc/lispref/help.texi
View file

@ -158,6 +158,13 @@ the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
@end defun
@defun function-documentation function
Generic function used by @code{documentation} to extract the raw
docstring from a function object. You can specify how to get the
docstring of a specific function type by adding a corresponding method
to it.
@end defun
@defun face-documentation face
This function returns the documentation string of @var{face} as a
face.
@ -338,7 +345,10 @@ stands for a key sequence @var{KEYSEQ}, which will use the same face
as a command substitution. This should be used only when a key
sequence has no corresponding command, for example when it is read
directly with @code{read-key-sequence}. It must be a valid key
sequence according to @code{key-valid-p}.
sequence according to @code{key-valid-p}. It can also be used with
command names, like @samp{\`M-x foo'}, where you want this to be
fontified like a keyboard sequence, but you want to inhibit
translating it into a key sequence like @samp{\[foo]} does.
@item `
(grave accent) stands for a left quote.
@ -355,6 +365,10 @@ depending on the value of @code{text-quoting-style}.
quotes the following character and is discarded; thus, @samp{\=`} puts
@samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output,
and @samp{\=\=} puts @samp{\=} into the output.
@item \+
This indicates that the symbol directly following should not be marked
as link in the @file{*Help*} buffer.
@end table
@strong{Please note:} Each @samp{\} must be doubled when written in a
@ -379,7 +393,7 @@ quotes. You can customize it freely according to your personal
preference.
@end defopt
@defun substitute-command-keys string &optional no-face
@defun substitute-command-keys string &optional no-face include-menus
@vindex help-key-binding@r{ (face)}
This function scans @var{string} for the above special sequences and
replaces them by what they stand for, returning the result as a string.
@ -429,6 +443,9 @@ RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
The keymap description will normally exclude menu items, but if
@var{include-menus} is non-@code{nil}, include them.
@group
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type \

1
doc/lispref/hooks.texi
View file

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

10
doc/lispref/internals.texi
View file

@ -1637,7 +1637,7 @@ This function returns the value of a Lisp float specified by
@var{arg}, as a C @code{double} value.
@end deftypefn
@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{arg})
@deftypefn Function {struct timespec} extract_time (emacs_env *@var{env}, emacs_value @var{arg})
This function, which is available since Emacs 27, interprets @var{arg}
as an Emacs Lisp time value and returns the corresponding @code{struct
timespec}. @xref{Time of Day}. @code{struct timespec} represents a
@ -1942,7 +1942,7 @@ garbage-collected. Don't run any expensive code in a finalizer,
because GC must finish quickly to keep Emacs responsive.
@end deftypefn
@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value @var{arg})
@deftypefn Function {void *}get_user_ptr (emacs_env *@var{env}, emacs_value @var{arg})
This function extracts the C pointer from the Lisp object represented
by @var{arg}.
@end deftypefn
@ -2060,7 +2060,7 @@ to quit, use the following function, which is available since Emacs
27.1.
@anchor{process_input}
@deftypefn Function enum emacs_process_input_result process_input (emacs_env *@var{env})
@deftypefn Function {enum emacs_process_input_result} process_input (emacs_env *@var{env})
This function processes pending input events. It returns
@code{emacs_process_input_quit} if the user wants to quit or an error
occurred while processing signals. In that case, we recommend that
@ -2135,7 +2135,7 @@ Therefore, we recommend that your module functions check for nonlocal
exit conditions and recover from them, using the functions described
below.
@deftypefn Function enum emacs_funcall_exit non_local_exit_check (emacs_env *@var{env})
@deftypefn Function {enum emacs_funcall_exit} non_local_exit_check (emacs_env *@var{env})
This function returns the kind of nonlocal exit condition stored in
@var{env}. The possible values are:
@ -2150,7 +2150,7 @@ The last @acronym{API} function exited via @code{throw}.
@end vtable
@end deftypefn
@deftypefn Function enum emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})
@deftypefn Function {enum emacs_funcall_exit} non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data})
This function returns the kind of nonlocal exit condition stored in
@var{env}, like @code{non_local_exit_check} does, but it also returns
the full information about the nonlocal exit, if any. If the return

4
doc/lispref/intro.texi
View file

@ -503,9 +503,11 @@ if the information is not available.
@example
@group
emacs-build-time
@result{} (20614 63694 515336 438000)
@result{} (25194 55894 8547 617000)
@end group
@end example
(This timestamp is @code{(1651169878008547617 . 1000000000)}
if @code{current-time-list} was @code{nil} when Emacs was built.)
@end defvar
@defvar emacs-version

30
doc/lispref/keymaps.texi
View file

@ -579,11 +579,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 +1063,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}).
@ -1643,7 +1656,7 @@ non-@code{nil}, the definition will be removed. This is almost the
same as setting the definition to @code{nil}, but makes a difference
if the @var{keymap} has a parent, and @var{key} is shadowing the same
binding in the parent. With @var{remove}, subsequent lookups will
return the binding in the parent, and with a nil @var{def}, the
return the binding in the parent, whereas with a @code{nil} definition the
lookups will return @code{nil}.
@end defun
@ -2209,6 +2222,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

29
doc/lispref/lists.texi
View file

@ -1925,9 +1925,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 +1944,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 +1963,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

54
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}.
@ -529,7 +528,7 @@ primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs. These comments do
nothing on their own, but they serve as a guide for the command
@code{update-file-autoloads}, which constructs calls to @code{autoload}
@code{loaddefs-generate}, which constructs calls to @code{autoload}
and arranges to execute them when Emacs is built.
@defun autoload function filename &optional docstring interactive type
@ -627,22 +626,19 @@ subroutines not loaded successfully because they come later in the file.
macro, then an error is signaled with data @code{"Autoloading failed to
define function @var{function-name}"}.
@findex update-file-autoloads
@findex make-directory-autoloads
@findex loaddefs-generate
@cindex magic autoload comment
@cindex autoload cookie
@anchor{autoload cookie}
A magic autoload comment (often called an @dfn{autoload cookie})
consists of @samp{;;;###autoload}, on a line by itself,
just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
autoloadable source file. The function @code{loaddefs-generate}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
(The string that serves as the autoload cookie and the name of the
file generated by @code{update-file-autoloads} can be changed from the
file generated by @code{loaddefs-generate} can be changed from the
above defaults, see below.)
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
@kbd{M-x make-directory-autoloads} is even more powerful; it updates
autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
@file{loaddefs.el}. The form following the magic comment is copied
@ -675,7 +671,7 @@ and @code{define-global-minor-mode}.
@emph{without} executing it when the file itself is loaded. To do this,
write the form @emph{on the same line} as the magic comment. Since it
is in a comment, it does nothing when you load the source file; but
@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
@code{loaddefs-generate} copies it to @file{loaddefs.el}, where
it is executed while building Emacs.
The following example shows how @code{doctor} is prepared for
@ -728,11 +724,11 @@ corresponding autoload calls written into a file whose name is
different from the default @file{loaddefs.el}. Emacs provides two
variables to control this:
@defvar generate-autoload-cookie
The value of this variable should be a string whose syntax is a Lisp
comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
follows the cookie into the autoload file it generates. The default
value of this variable is @code{";;;###autoload"}.
@defvar lisp-mode-autoload-regexp
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 @samp{;;;###autoload} and @samp{;;;###calc-autoload}.
@end defvar
@defvar generated-autoload-file
@ -769,7 +765,7 @@ contain definitions matching the prefix being completed. The variable
@code{definition-prefixes} holds a hashtable which maps a prefix to
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{update-file-autoloads}
which are generated by @code{loaddefs-generate}
(@pxref{Autoload}). Files which don't contain any definitions worth
loading (test files, for examples), should set
@code{autoload-compute-prefixes} to @code{nil} as a file-local
@ -1067,13 +1063,8 @@ list elements have these forms:
The symbol @var{var} was defined as a variable.
@item (defun . @var{fun})
The function @var{fun} was defined.
@item (t . @var{fun})
The function @var{fun} was previously an autoload before this library
redefined it as a function. The following element is always
@code{(defun . @var{fun})}, which represents defining @var{fun} as a
function.
@item (autoload . @var{fun})
The function @var{fun} was defined as an autoload.
@item (defface . @var{face})
The face @var{face} was defined.
@item (require . @var{feature})
@ -1096,6 +1087,23 @@ The value of @code{load-history} may have one element whose @sc{car} is
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. @xref{Eval}.
@kindex function-history @r{(function symbol property)}
In addition to @code{load-history}, every function keeps track of its
own history in the symbol property @code{function-history}.
The reason why functions are treated specially in this respect is that
it is common for functions to be defined in two steps in two different
files (typically, one of them is an autoload), so in order to be
able to properly @emph{unload} a file, we need to know more precisely
what that file did to the function definition.
The symbol property @code{function-history} holds a list of the form
@w{@code{(@var{file1} @var{def2} @var{file2} @var{def3} ...)}}, where
@var{file1} is the last file that changed the definition and
@var{def2} was the definition before @var{file1}, set by @var{file2},
etc. Logically this list should end with the name of the first file
that defined this function, but to save space this last element
is usually omitted.
@node Unloading
@section Unloading
@cindex unloading packages
@ -1110,7 +1118,7 @@ It undefines all functions, macros, and variables defined in that
library with @code{defun}, @code{defalias}, @code{defsubst},
@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
It then restores any autoloads formerly associated with those symbols.
(Loading saves these in the @code{autoload} property of the symbol.)
(Loading saves these in the @code{function-history} property of the symbol.)
Before restoring the previous definitions, @code{unload-feature} runs
@code{remove-hook} to remove functions defined by the library from certain

33
doc/lispref/minibuf.texi
View file

@ -244,6 +244,13 @@ This function works by calling the
value))
@end group
@end smallexample
@findex read-string-from-buffer
If you have a long string (for instance, one that is several lines
long) that you wish to edit, using @code{read-string} may not be
ideal. In that case, popping to a new, normal buffer where the user
can edit the string may be more convenient, and you can use the
@code{read-string-from-buffer} function to do that.
@end defun
@defun read-regexp prompt &optional defaults history
@ -302,6 +309,22 @@ The optional argument @var{history}, if non-@code{nil}, is a symbol
specifying a minibuffer history list to use (@pxref{Minibuffer
History}). If it is omitted or @code{nil}, the history list defaults
to @code{regexp-history}.
@cindex @code{case-fold}, text property
@findex read-regexp-case-fold-search
The user can use the @kbd{M-c} command to indicate whether case
folding should be on or off. If the user has used this command, the
returned string will have the text property @code{case-fold} set to
either @code{fold} or @code{inhibit-fold}. It is up to the caller of
@code{read-regexp} to actually use this value, and the convenience
function @code{read-regexp-case-fold-search} is provided for that. A
typical usage pattern here might look like:
@lisp
(let* ((regexp (read-regexp "Search for: "))
(case-fold-search (read-regexp-case-fold-search regexp)))
(re-search-forward regexp))
@end lisp
@end defun
@defopt read-regexp-defaults-function
@ -1114,6 +1137,11 @@ completion command (i.e., one of the commands in
@code{minibuffer-confirm-exit-commands}) and the resulting input is
not an element of @var{collection}. @xref{Completion Commands}.
@item
If a function, it is called with the input as the only argument. The
function should return a non-@code{nil} value if the input is
acceptable.
@item
Any other value of @var{require-match} behaves like @code{t}, except
that the exit commands won't exit if it performs completion.
@ -1936,6 +1964,7 @@ completion function is trying to complete. If the symbol matches one
of the keys in @code{completion-category-overrides}, the usual
completion behavior is overridden. @xref{Completion Variables}.
@cindex @code{annotation-function}, in completion
@item annotation-function
The value should be a function for @dfn{annotating} completions. The
function should take one argument, @var{string}, which is a possible
@ -1945,6 +1974,7 @@ Unless this function puts own face on the annotation suffix string,
the @code{completions-annotations} face is added by default to
that string.
@cindex @code{affixation-function}, in completion
@item affixation-function
The value should be a function for adding prefixes and suffixes to
completions. The function should take one argument,
@ -1955,6 +1985,7 @@ the completion string in the @file{*Completions*} buffer, and
a suffix displayed after the completion string. This function
takes priority over @code{annotation-function}.
@cindex @code{group-function}, in completion
@item group-function
The value should be a function for grouping the completion candidates.
The function must take two arguments, @var{completion}, which is a
@ -1965,12 +1996,14 @@ can also be @code{nil}. Otherwise the function must return the
transformed candidate. The transformation can for example remove a
redundant prefix, which is displayed in the group title.
@cindex @code{display-sort-function}, in completion
@item display-sort-function
The value should be a function for sorting completions. The function
should take one argument, a list of completion strings, and return a
sorted list of completion strings. It is allowed to alter the input
list destructively.
@cindex @code{cycle-sort-function}, in completion
@item cycle-sort-function
The value should be a function for sorting completions, when
@code{completion-cycle-threshold} is non-@code{nil} and the user is

184
doc/lispref/modes.texi
View file

@ -762,6 +762,9 @@ uncompression packages: an entry of the form @code{("\\.gz\\'"
@var{function} t)} can uncompress the file and then put the uncompressed
file in the proper mode according to the name sans @samp{.gz}.
If @code{auto-mode-alist} has more than one element whose @var{regexp}
matches the file name, Emacs will use the first match.
Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}. (You might use this sort of expression in your
init file.)
@ -1058,12 +1061,22 @@ very end of every properly-written major mode command.
@cindex Tabulated List mode
Tabulated List mode is a major mode for displaying tabulated data,
i.e., data consisting of @dfn{entries}, each entry occupying one row of
text with its contents divided into columns. Tabulated List mode
i.e., data consisting of @dfn{entries}, each entry occupying one row
of text with its contents divided into columns. Tabulated List mode
provides facilities for pretty-printing rows and columns, and sorting
the rows according to the values in each column. It is derived from
Special mode (@pxref{Basic Major Modes}).
@findex make-vtable
@cindex variable pitch tables
Tabulated List mode is geared towards displaying text using
monospaced fonts, using a single font and text size. If you want to
display a table using variable pitch fonts or images,
@code{make-vtable} can be used instead. vtable also support having
more than a single table in a buffer, or having a buffer that contains
both a table and additional text in it. @xref{Introduction,,, vtable},
for more information.
Tabulated List mode is intended to be used as a parent mode by a more
specialized major mode. Examples include Process Menu mode
(@pxref{Process Information}) and Package Menu mode (@pxref{Package
@ -1899,6 +1912,16 @@ This means ``use in modes derived from @code{text-mode}, but nowhere
else''. (There's an implicit @code{nil} element at the end.)
@end defmac
@findex buffer-local-restore-state
@defmac buffer-local-set-state variable value...
Minor modes often set buffer-local variables that affect some features
in Emacs. When a minor mode is switched off, the mode is expected to
restore the previous state of these variables. This convenience macro
helps with doing that: It works much like @code{setq-local}, but
returns an object that can be used to restore these values back to
their previous values/states (using the companion function
@code{buffer-local-restore-state}).
@end defmac
@node Mode Line Format
@section Mode Line Format
@ -1961,8 +1984,26 @@ This function also forces an update of the menu bar and frame title.
@end defun
The selected window's mode line is usually displayed in a different
color using the face @code{mode-line}. Other windows' mode lines appear
in the face @code{mode-line-inactive} instead. @xref{Faces}.
color using the face @code{mode-line-active}. Other windows' mode
lines appear in the face @code{mode-line-inactive} instead.
@xref{Faces}.
@defun mode-line-window-selected-p
If you want to have more extensive differences between the mode lines
in selected and non-selected windows, you can use this predicate in an
@code{:eval} construct. For instance, if you want to display the
buffer name in bold in selected windows, but in italics in the other
windows, you can say something like:
@lisp
(setq-default
mode-line-buffer-identification
'(:eval (propertize "%12b"
'face (if (mode-line-window-selected-p)
'bold
'italic))))
@end lisp
@end defun
@vindex mode-line-compact
Some modes put a lot of data in the mode line, pushing elements at
@ -2534,7 +2575,23 @@ mode line feature, except that it's controlled by
This variable, local in every buffer, specifies how to display the
header line, for windows displaying the buffer. The format of the value
is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
It is normally @code{nil}, so that ordinary buffers have no header line.
It is normally @code{nil}, so that ordinary buffers have no header
line.
@findex header-line-indent-mode
If @code{display-line-numbers-mode} is used, and you want the header
line to be indented by the same amount as the buffer contents, you can
use the @code{header-line-indent-mode} minor mode. This minor mode
keeps the @code{header-line-indent} variable updated, so that you can
say something like:
@lisp
(setq header-line-format
`("" header-line-format ,my-header-line))
@end lisp
This can be useful if you're displaying columnar data, and the header
line should align with that data in the buffer.
@end defvar
@defun window-header-line-height &optional window
@ -3173,7 +3230,9 @@ Non-@code{nil} means that regular expression matching for the sake of
You can use @code{font-lock-add-keywords} to add additional
search-based fontification rules to a major mode, and
@code{font-lock-remove-keywords} to remove rules.
@code{font-lock-remove-keywords} to remove rules. You can also
customize the @code{font-lock-ignore} option to selectively disable
fontification rules for keywords that match certain criteria.
@defun font-lock-add-keywords mode keywords &optional how
This function adds highlighting @var{keywords}, for the current buffer
@ -3243,6 +3302,99 @@ mode @emph{and} all modes derived from it, do this instead:
font-lock-keyword-face)))))
@end smallexample
@defopt font-lock-ignore
@cindex selectively disabling font-lock fontifications
This option defines conditions for selectively disabling
fontifications due to certain Font Lock keywords. If non-@code{nil},
its value is a list of elements of the following form:
@example
(@var{symbol} @var{condition} @dots{})
@end example
Here, @var{symbol} is a symbol, usually a major or minor mode. The
subsequent @var{condition}s of a @var{symbol}'s list element will be in
effect if @var{symbol} is bound and its value is non-@code{nil}. For
a mode's symbol, it means that the current major mode is derived from
that mode, or that minor mode is enabled in the buffer. When a
@var{condition} is in effect, any fontifications caused by
@code{font-lock-keywords} elements that match the @var{condition} will
be disabled.
Each @var{condition} can be one of the following:
@table @asis
@item a symbol
This condition matches any element of Font Lock keywords that
references the symbol. This is usually a face, but can be any symbol
referenced by an element of the @code{font-lock-keywords} list. The
symbol can contain wildcards: @code{*} matches any string in the
symbol'ss name, @code{?} matches a single character, and
@code{[@var{char-set}]}, where @var{char-set} is a string of one or
more characters, matches a single character from the set.
@item a string
This condition matches any element of Font Lock keywords whose
@var{matcher} is a regexp which matches the string. In other words,
this condition matches a Font Lock rule which highlights the string.
Thus, the string could be a specific program keyword whose
highlighting you want to disable.
@item @code{(pred @var{function})}
This condition matches any element of Font Lock keywords for which
@var{function}, when called with the element as the argument, returns
non-@code{nil}.
@item @code{(not @var{condition})}
This matches if @var{condition} doesn’t.
@item @code{(and @var{condition} @dots{})}
This matches if each of the @var{condition}s matches.
@item @code{(or @var{condition} @dots{})}
This matches if at least one of the @var{condition}s matches.
@item @code{(except @var{condition})}
This condition can only be used at top level or inside an
@code{or} clause. It undoes the effect of a previously matching
condition on the same level.
@end table
@end defopt
As an example, consider the following setting:
@smallexample
(setq font-lock-ignore
'((prog-mode font-lock-*-face
(except help-echo))
(emacs-lisp-mode (except ";;;###autoload)")
(whitespace-mode whitespace-empty-at-bob-regexp)
(makefile-mode (except *))))
@end smallexample
Line by line, this does the following:
@enumerate
@item
In all programming modes, disable fontifications due to all font-lock
keywords that apply one of the standard font-lock faces (excluding
strings and comments, which are covered by syntactic Font Lock).
@item
However, keep any keywords that add a @code{help-echo} text property.
@item
In Emacs Lisp mode, also keep the highlighting of autoload cookies,
which would have been excluded by the first condition.
@item
When @code{whitespace-mode} (a minor mode) is enabled, also don't
highlight an empty line at beginning of buffer.
@item
Finally, in Makefile mode, don't apply any conditions.
@end enumerate
@node Other Font Lock Variables
@subsection Other Font Lock Variables
@ -3321,7 +3473,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}.
@ -3341,6 +3494,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
@ -3513,6 +3679,10 @@ the value is @code{nil}, Font Lock will call @code{jit-lock-register}
(@pxref{Other Font Lock Variables}) to set up for automatic
refontification of buffer text following a modified line to reflect
the new syntactic context due to the change.
To use only syntactic fontification, this variable should
be non-@code{nil}, while @code{font-lock-keywords} should be set to
@code{nil} (@pxref{Font Lock Basics}).
@end defvar
@defvar font-lock-syntax-table

26
doc/lispref/nonascii.texi
View file

@ -280,11 +280,12 @@ to the codepoints @code{#x3FFF80} through @code{#x3FFFFF}, inclusive
@defun string-to-unibyte string
This function returns a unibyte string containing the same sequence of
characters as @var{string}. It signals an error if @var{string}
contains a non-@acronym{ASCII} character. If @var{string} is a
unibyte string, it is returned unchanged. Use this function for
@var{string} arguments that contain only @acronym{ASCII} and eight-bit
characters.
characters as @var{string}. If @var{string} is a unibyte string, it
is returned unchanged. Otherwise, @acronym{ASCII} characters and
characters in the @code{eight-bit} charset are converted to their
corresponding byte values. Use this function for @var{string}
arguments that contain only @acronym{ASCII} and eight-bit characters;
the function signals an error if any other characters are encountered.
@end defun
@defun byte-to-string byte
@ -855,15 +856,24 @@ function to all or part of the characters in a charset:
Call @var{function} for characters in @var{charset}. @var{function}
is called with two arguments. The first one is a cons cell
@code{(@var{from} . @var{to})}, where @var{from} and @var{to}
indicate a range of characters contained in charset. The second
argument passed to @var{function} is @var{arg}.
indicate a range of characters contained in @var{charset}. The second
argument passed to @var{function} is @var{arg}, or @code{nil} if
@var{arg} is omitted.
By default, the range of codepoints passed to @var{function} includes
all the characters in @var{charset}, but optional arguments
@var{from-code} and @var{to-code} limit that to the range of
characters between these two codepoints of @var{charset}. If either
of them is @code{nil}, it defaults to the first or last codepoint of
@var{charset}, respectively.
@var{charset}, respectively. Note that @var{from-code} and
@var{to-code} are @var{charset}'s codepoints, not the Emacs codes of
characters; by contrast, the values @var{from} and @var{to} in the
cons cell passed to @var{function} @emph{are} Emacs character codes.
Those Emacs character codes are either Unicode code points, or Emacs
internal code points that extend Unicode and are beyond the Unicode
range of characters @code{0..#x10FFFF} (@pxref{Text Representations}).
The latter happens rarely, with legacy CJK charsets for codepoints of
@var{charset} which specify characters not yet unified with Unicode.
@end defun
@node Scanning Charsets

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